[Phase 3] Default-off feature flag + regression guard + operator docs for the downstream-impact pass #753

Activity

1. github-actions

   added

   initiativeEpic / initiative tracking issueEpic / initiative tracking issue

   on Jun 15, 2026
2. github-actions

   added a parent issue on Jun 15, 2026

   • Cross-repo impact-aware review annotations: proactive downstream-breakage detection in the pr-review pipeline #748
3. github-actions

   marked this as blocked by 3 issues on Jun 15, 2026

   • [Phase 2] Pure mapping helper: changed files -> impacted shared surfaces + consumers #750
   • [Phase 2] Fetch consumer references + assemble the DOWNSTREAM_IMPACT context block #751
   • [Phase 3] Wire the DOWNSTREAM_IMPACT block into the triage + deep prompts and surface it in the verdict #752
4. don-petry

   added

   dev-leadFor dev-lead agent pickupFor dev-lead agent pickup

   on Jun 19, 2026
5. don-petry commented on Jun 19, 2026

   

   don-petry

   on Jun 19, 2026

   Collaborator

   More actions

   Dev-Lead Implementation Plan

   Issue: #753 — [Phase 3] Default-off feature flag + regression guard + operator docs for the downstream-impact pass

   Scope

   Ship the downstream-impact pass default-off behind DOWNSTREAM_IMPACT_ENABLED (gate already wired in #752), add a golden-fixture regression guard pinning the pure mapper, and write operator docs.

   Implementation Checklist

   • Confirm the DOWNSTREAM_IMPACT_ENABLED default-off gate already wraps the whole pass (assembly + triage inline + verdict note) in scripts/review-one-pr.sh; no behavior when off.
   • Add committed golden fixtures tests/fixtures/downstream-impact/golden/ (frozen manifest + per-case changed.txt/expected.json).
   • Add tests/test_downstream_impact_regression.bats pinning compute_downstream_impact output against the golden fixtures + an off-path no-op assertion.
   • Register the new bats file in .github/workflows/lint.yml bats list.
   • Write docs/pr-review-agent/downstream-impact.md and link it from docs/pr-review-agent/documentation-index.md.
   • Update AGENTS.md bats-list exception to document the regression guard; run shellcheck.

   Tests to Write

   • tests/test_downstream_impact_regression.bats — golden-fixture diff per case (direct workflow, indirect lib, indirect prompt, shared-source union, mixed, no-impact, empty) + flag-off no-op.

   Test Command

   bats tests/test_downstream_impact_regression.bats (full suite via scripts/run-bats.sh); lint via bash .dev-lead/scripts/dev-lead-lint.sh
6. don-petry commented on Jun 19, 2026

   

   don-petry

   on Jun 19, 2026

   Collaborator

   More actions

   Dev-Lead: Implementation Complete

   Plan Execution

   • Confirmed the DOWNSTREAM_IMPACT_ENABLED default-off gate already wraps the whole pass (assembly + triage inline + verdict note) — the gate was wired in [Phase 3] Wire the DOWNSTREAM_IMPACT block into the triage + deep prompts and surface it in the verdict #752; this story adds the regression guard, docs, and AGENTS.md record. (AC test issue from agent #1)
   • Added committed golden fixtures under tests/fixtures/downstream-impact/golden/ (frozen manifest + 7 per-case changed.txt/expected.json). (AC Go-live improvements for PR review agent #2)
   • Added tests/test_downstream_impact_regression.bats pinning compute_downstream_impact against the golden fixtures, plus flag-off no-op assertions. (AC test issue from agent #1, Go-live improvements for PR review agent #2)
   • Registered the new bats file in .github/workflows/lint.yml. (AC Go-live improvements for PR review agent #2)
   • Wrote docs/pr-review-agent/downstream-impact.md (what the pass does, the DOWNSTREAM_IMPACT_ENABLED flag, GH_PAT scope, per-PR fetch + size caps, manifest refresh) and linked it from documentation-index.md. (AC Add @claude delegation, auto-merge, and rebase handling #3)
   • Documented the regression guard in the AGENTS.md bats-list exception; shellcheck/dev-lead-lint pass. (AC Optimize review: small-PR and incremental fast paths #4)

   Test Results

   # Full lint.yml bats list (33 files): 572 tests, 0 failures
   1..572
   ...
   ok 561 golden manifest fixture exists and is valid JSON
   ok 562 at least one golden case is present
   ok 563 golden: direct reusable-workflow change
   ok 564 golden: indirect scripts/lib change via surface_sources
   ok 565 golden: indirect prompts change via surface_sources
   ok 566 golden: source shared by two reusables (union of surfaces + consumers)
   ok 567 golden: mixed impacting + non-impacting paths
   ok 568 golden: no-impact change
   ok 569 golden: empty changed-file list
   ok 570 every golden case directory matches its expected output
   ok 571 flag off: triage section emits nothing (off-path no-op)
   ok 572 flag explicitly false: triage section emits nothing (off-path no-op)
   
   # dev-lead-lint (shellcheck on 67 files + agent-profile validation)
     [lint] all checks passed
   
   # Mutation test: perturbing one expected.json made the guard fail (cases 3 + catch-all),
   # restoring it returned all 12 to green — the guard is not vacuous.
   

   Files Changed

   • tests/test_downstream_impact_regression.bats: new golden-fixture regression guard for the pure mapper + flag-off no-op checks.
   • tests/fixtures/downstream-impact/golden/manifest.json: frozen golden manifest (independent of the live consumer-manifest.json).
   • tests/fixtures/downstream-impact/golden/cases/*/{changed.txt,expected.json}: 7 golden cases (direct, indirect-lib, indirect-prompt, shared-source union, mixed, no-impact, empty).
   • .github/workflows/lint.yml: registered the new bats file in the bats job list.
   • docs/pr-review-agent/downstream-impact.md: new operator guide.
   • docs/pr-review-agent/documentation-index.md: linked the new guide.
   • AGENTS.md: documented the regression guard under the bats-list exception.

   Notes

   • The AC test issue from agent #1 gate (DOWNSTREAM_IMPACT_ENABLED, default-off) was already implemented in [Phase 3] Wire the DOWNSTREAM_IMPACT block into the triage + deep prompts and surface it in the verdict #752; the off-path is a no-op (the assembly/fetch step in review-one-pr.sh is skipped when the flag is off, and the triage-section helper emits nothing), and this story adds the explicit flag-off no-op assertions to the new guard.
   • No new always-run workflow was introduced — the guard runs in the existing always-run bats job, so no new workflow exception was added to AGENTS.md (only the bats-list exception was extended).
   • The golden manifest is deliberately decoupled from the live consumer-manifest.json so Story 1's builder refreshing the manifest does not break the guard; only a mapper-output change does, requiring an explicit, reviewable fixture update.
7. don-petry

   added a commit that references this issue on Jun 19, 2026

   feat: implement issue #753 — [Phase 3] Default-off feature flag + reg…

   ...

   9cb66bb
8. don-petry

   closed this as completedin #787on Jun 19, 2026