epic(ci): watch supported-framework releases, assess their impact, and publish supported versions #1065

Summary

We support 8 frameworks (ADAPTERS), but nothing tells us when one ships a release. We find out only if the nightly fresh resolve goes red, and even then not which release did it. Users have no single place that says which versions we support. This epic adds three pieces: a daily release watch that tests each new release in isolation against the PR lock, an AI changelog review that flags deprecations and removals before they break us, and a generated version-compatibility page in the docs.

Motivation

On 2026-10-10, 6 of the 11 framework packages we watch had a release newer than the PR lock, all published in the last 2 days, and no signal fired for any of them:

Today's process has three gaps:

• The nightly can't attribute a failure. framework-legs (nightly-matrix.yml:175) resolves fresh, so every dependency moves at once. When it goes red, alert (nightly-matrix.yml:261) opens one generic nightly-failure issue that doesn't say which release caused it.
• Nothing triggers a lock refresh. ADR 0007 rule 3 keeps it a manual PR "on whatever cadence a maintainer judges useful" (0007-dependency-policy.md:69), so the locks fall behind without anyone noticing.
• Supported versions are scattered. The floors are in pyproject.toml (pyproject.toml:57-84), the tested versions are prose in the docs/verified-apis.md section 8 rows, and the known-bad versions are in §8.1. The README "Framework support" table (README.md:104) shows only tiers, and two framework pages hard-code versions that go stale (agent-framework.mdx:19,178,186 say 1.19.0, while the lock is 1.20.0).

BG §1.8 (adapters) and BG §1.10 (docs) govern this work. Policy stays as §8.4 and ADR 0007 define it: floors, never ceilings. A red result leads to an adapter fix or a §8.1 record, never a pin.

Children

• ci: detect new framework releases and test each one in isolation against the PR lock #1066 — ci: detect new framework releases and test each one in isolation against the PR lock
• ci: add an AI changelog impact review to the framework release watch #1067 — ci: add an AI changelog impact review to the framework release watch (depends on ci: detect new framework releases and test each one in isolation against the PR lock #1066)
• docs: publish a generated framework version-compatibility page #1068 — docs: publish a generated framework version-compatibility page

Out of scope (tracked elsewhere)

• Opening lock-bump PRs automatically (Dependabot or Renovate). That's ci(deps): pin the dev and release toolchain with a lock, and make mypy independent of installed extras #763 and ci(security): harden the Actions supply chain — SHA pins, Dependabot, CODEOWNERS, least-privilege Pages #757. Until those land, the framework-release issue from ci: detect new framework releases and test each one in isolation against the PR lock #1066 is the documented trigger for the manual refresh.
• The lowest-direct floor job and the pairwise co-installability table. That's ci: test the declared support matrix — lowest-direct per extra, openai<2, Python 3.13/3.14, co-installability #769. docs: publish a generated framework version-compatibility page #1068 links the table once it exists.

Related

• epic(ci): code review — CI/CD & developer experience #711 — CI/CD epic
• epic(docs): code review — documentation, examples & website #712 — docs epic
• test(ci): run framework-dependent tests against real framework installs #748 — the framework-legs nightly
• ci: run CI on pushes to develop and alert on nightly failures #755 — the nightly alert pattern this reuses

Done when

• A new release of any watched package produces exactly one framework-release issue within a day. The issue carries isolated test results and an impact summary.
• The issue closes itself once the lock reaches that version.
• docs/framework-support.md and /frameworks/compatibility on the docs site list the minimum version, the tested version and the known-bad versions for every adapter, and CI fails if either is stale.