ci: add an AI changelog impact review to the framework release watch #1067

Part of #1065.

Summary

Add an ai-review job to framework-release-watch.yml. For each new release it reads the upstream release notes against the adapter code that release could affect, and produces a short impact summary: which symbols, kwargs and classes we touch that the release changes, deprecates or removes, a risk rating, and a recommended action. The alert job embeds the summary in the framework-release issue.

Motivation

The isolated tests from #1066 answer "does it break us today?". They don't catch deprecations that will break us one release later, or behaviour changes our tests don't cover. Every shallow adapter is only signature-confirmed (BG §1.8, section 8 of docs/verified-apis.md), so a changelog read is the cheapest early warning available.

Depends on

• ci: detect new framework releases and test each one in isolation against the PR lock #1066 — the workflow, matrix and issue body this job plugs into

Current behavior (verified)

• No workflow calls an LLM. No workflow uses anthropics/claude-code-action or an ANTHROPIC_API_KEY secret.
• What a given adapter touches is defined by:
  • its module, python/src/donkey_kit/integrations/<fw>.py
  • its FRAMEWORKS row (verify_frameworks.py:70)
  • its rows in docs/verified-apis.md section 8 (verified-apis.md:649), §8.1 (:682) and section 8.2 (:715)

Proposal

• Job shape: a new ai-review job, one leg per release in ci: detect new framework releases and test each one in isolation against the PR lock #1066's detect matrix. It runs in parallel with evaluate, with fail-fast: false and timeout-minutes: 15.

• Action and model: anthropics/claude-code-action, pinned by full commit SHA (in line with ci(security): harden the Actions supply chain — SHA pins, Dependabot, CODEOWNERS, least-privilege Pages #757), using claude-sonnet-5-5.

• Prompt inputs:

  • the package and both versions
  • release_notes_url and the GitHub compare URL (<repo>/compare/v<locked>...v<latest> when the source is on GitHub)
  • the adapter module, its FRAMEWORKS row, and its section 8, §8.1 and 8.2 rows

• Output: a fixed markdown block:

  • Risk (none / low / high)
  • Affected symbols (each with an upstream citation)
  • Recommended action (bump / adapt adapter / record §8.1 / watch)
  • Confidence

  The block is uploaded as an artifact, and alert from ci: detect new framework releases and test each one in isolation against the PR lock #1066 embeds it under "Impact review (AI, advisory)".

• Prompt-injection hardening. Release notes are untrusted input.

  • permissions: contents: read only, and no token with write access in the job.
  • Allowed tools: Read, Grep, Glob, WebFetch. No Bash, no edit or write tools.
  • The prompt tells the model to treat fetched content as data.
  • The job never comments or writes itself; only alert writes.

• §0.3: the summary is advisory. It never flips a section 8 row and never counts as verification. The issue body says so.

• Secret scoping: a dedicated ai-review environment. The key lives as an environment secret, not a repository secret, so only the job that declares environment: ai-review can read it. This mirrors how live-sandbox scopes the proxy credentials (live-contract-check.yml).

  • Create the environment ai-review with a deployment branch policy that allows only develop, the default branch, where schedule and workflow_dispatch runs execute. This is the same rule live-sandbox uses.
  • Move the secret. Add ANTHROPIC_API_KEY as an environment secret on ai-review, then delete the repository-level ANTHROPIC_API_KEY that was set on 2026-10-10 as a stopgap, so no other workflow can read it.
  • The job declares environment: ai-review and runs only on schedule and workflow_dispatch (if: github.event_name != 'pull_request'). PR dry runs skip it instead of being rejected by the branch policy, and PR-authored workflow changes can never reach the key.
  • No reviewer gate. Leave required reviewers unset, so the daily scheduled run isn't blocked waiting for approval.

• Secret handling: if the secret is missing, or the action fails, the job emits a notice and alert writes "impact review unavailable"; the watch itself stays green.

• Cost bound: at most one review per (package, version), with results cached by artifact name, so a re-run of an unchanged release doesn't call the model again.

Cross-surface impact

• core/llm/registry/tools/integrations: not affected. It reads adapter code; it doesn't change it.
• TypeScript parity (planned): not affected. The same job can review npm releases once the TS port exists.
• CLI: not affected.
• Nextra docs site: not affected.
• docs/verified-apis.md: read only, never edited (§0.3).
• Repo settings: a new ai-review environment (develop-only branch policy) holding ANTHROPIC_API_KEY, with the stopgap repository secret removed. The repository Actions policy already allows the third-party action.

Out of scope

• Letting the model open PRs or edit code.
• Reviewing non-framework dependencies (dev tools, openai on its own). Add them later if useful.

Acceptance criteria

• The action is pinned by SHA, and the job has only contents: read and the read-only tool allowlist.
• A dispatch run on a release with a documented break produces Risk: high and names the right symbols. Use the openai 3.0.0 or anthropic 1.0.0 change recorded in §8.1.
• A dispatch run on a patch release with no API change produces Risk: none or low.
• ANTHROPIC_API_KEY exists only as an ai-review environment secret. gh secret list --repo Donkey-Development-Kit/donkey-development-kit no longer shows it at repository level, and gh secret list --env ai-review does.
• ai-review declares environment: ai-review, is skipped on pull_request, and the environment's branch policy allows only develop.
• Add a test to tests/unit/test_ci_workflows.py: ai-review is the only job in any workflow that declares environment: ai-review, and it never runs on pull_request.
• With the secret removed, the watch run is still green and the issue says "impact review unavailable".
• The docs/ci.md section from ci: detect new framework releases and test each one in isolation against the PR lock #1066 documents the job, the secret and the advisory status.