Cross-repo impact-aware review annotations: proactive downstream-breakage detection in the pr-review pipeline

[github-actions]

Summary

Extend the self-hosted pr-review cascade so a reviewer sees, during review, when a PR changes a reusable workflow that downstream consumer repos pin. The ring-staged release strategy (docs/initiatives/agentic-release-strategy.md) mitigates blast radius after a change lands; this initiative adds the missing proactive signal at review time — a DOWNSTREAM_IMPACT annotation listing which consumer repos reference the changed shared surface.

Source: Discussion #653. Motivating operational evidence: #463 (review never runs at green CI) and #619 (self-host deadlock — ring-0 validation can fail when the broken agent gates its own fix). #606 (oversized-PR handling) shows the cascade already absorbs cross-cutting context.

Scope (resolved in discussion #653)

The three open questions from the prior plan are now answered by the maintainer and are baked into this plan — no longer open:

• Providers / consumers: .github and .github-private are the providers; all org repos are consumers. The consumer set is built empirically by enumerating org repos and detecting which pin a provider reusable workflow (no hand-curated list, no unverified parking).
• Cross-repo read access: existing .github-private workflows already carry cross-repo read via GH_PAT (see .github/workflows/pr-review.yml); the feature reuses it and degrades to (none) by default when a repo is unreadable.
• Match granularity: exact-path matching for v1. A changed reusable-workflow file maps to consumers whose uses: references exactly that path; a changed scripts/lib/*.sh or prompts/* maps via a single documented manifest hop (the reusables that source it) — no recursive/transitive dependency graph.

Shared surfaces in scope

Reusable workflow files under .github/workflows/*-reusable.yml (both provider repos) are the primary consumer-facing surface (what consumers uses:). The manifest also records, per reusable, the in-provider shell libs (scripts/lib/) and prompts (prompts/) it sources, so a lib/prompt change maps to its reusables, then to consumers — exact-path lookups only.

Architecture entry points

• Triage context is assembled in scripts/review-one-pr.sh (the TRIAGE_PROMPT_FILE block, ~line 539) and runs at the triage tier (haiku 4.5) via scripts/engine.sh run_triage. The deep tier reads enrichment from env-passed file paths (the ADVISORY_BOT_FEEDBACK_FILE pattern). The DOWNSTREAM_IMPACT block follows that exact pattern.

Success metrics (initiative-level)

• When enabled, a DOWNSTREAM_IMPACT annotation is present on 100% of PRs that change a reusable workflow pinned by >=1 consumer (and explicitly (none) otherwise).
• The annotation correctly lists impacted consumers on a fixed regression fixture set (golden manifest + golden mapping) with zero false negatives for a directly-pinned reusable change.
• Over a defined soak window after enablement on ring-0, >=1 cross-repo breaking change is surfaced at review time before it reaches ring-0 (the Self-host deadlock: force_review bypasses the advisory gate but not the CI gate, so CI-gate fixes can't merge through ring-0 #619 class of failure), or a documented note that none occurred.

Cost cap

• Ships default-off behind a feature flag (zero added tokens / zero behavior change until an operator enables it).
• The impact pass runs only at the triage tier (haiku 4.5) — no extra deep/audit invocations.
• Consumer-reference fetching is bounded: only consumers that exact-match an impacted surface are fetched, capped at a configurable max repo count per PR, and the assembled DOWNSTREAM_IMPACT block is size-capped (mirroring the 8 KB cap on ADVISORY_BOT_FEEDBACK).

This epic is created inert (initiative, not initiative:auto); activation is a human decision.

---

Planned from idea discussion #653 by the BMAD Scrum Master initiative-planner. Inert until a maintainer adds initiative:auto.