[Phase 2] Fetch consumer references + assemble the DOWNSTREAM_IMPACT context block

[github-actions]

Story

As a pr-review maintainer,
I want a step that takes the mapped impacted consumers, fetches their referencing workflow files via GH_PAT, and assembles a size-capped DOWNSTREAM_IMPACT block to a file,
so that the triage/deep tiers can consume a ready-made, bounded downstream-impact context the same way they consume advisory-bot feedback.

Acceptance Criteria

1. Given the impact object from Story 2, the step fetches, for each impacted consumer, the workflow file(s) that reference the impacted surface using gh + GH_PAT, and writes a human-readable DOWNSTREAM_IMPACT block to a file path exported as DOWNSTREAM_IMPACT_FILE.
2. When no surfaces are impacted, the block is the literal (none) (no fetches performed).
3. Degrades gracefully: a consumer repo that is private/unreadable or a missing token scope yields (none) for that entry (or an explicit unreadable note) and never fails the cascade — exit status stays 0.
4. Fetch volume is bounded: only exact-matched consumers are fetched, capped at a configurable max repo count per PR, and the assembled block is truncated to a size cap (mirroring the 8 KB ADVISORY_BOT_FEEDBACK cap).
5. A bats test stubs gh to cover: impacted-with-readable-consumer, impacted-with-unreadable-consumer (-> graceful), and no-impact (-> (none), zero fetches). shellcheck passes.

Tasks / Subtasks

• Add an assembler (e.g. assemble_downstream_impact in scripts/lib/downstream-impact.sh) that calls the pure mapper, then fetches consumer workflow files via gh api/gh with GH_PAT, honoring the per-PR repo cap and size cap. (AC: test issue from agent #1, Optimize review: small-PR and incremental fast paths #4)
• Implement graceful degradation for unreadable/private repos and missing scope — catch fetch errors, emit (none)/unreadable, keep exit 0. (AC: Go-live improvements for PR review agent #2, Add @claude delegation, auto-merge, and rebase handling #3)
• Write the block to DOWNSTREAM_IMPACT_FILE (default under /tmp/cascade/), export it, and add the gh-stubbed bats test; register it in lint.yml. (AC: test issue from agent #1, feat: add Copilot engine support via REVIEW_ENGINE toggle #5)

Dev Notes

• Mirror the ADVISORY_BOT_FEEDBACK_FILE lifecycle in scripts/review-one-pr.sh (~lines 570–575): write a capped block to a file under /tmp/cascade/, export the path for downstream tiers, rm -f stale copies first.
• Cap discipline matches the existing advisory cap (~8 KB) so huge consumer sets cannot blow up the prompt — see the 'Cap total size' note around scripts/review-one-pr.sh:534.
• Use GH_PAT via gh exactly as the rest of pr-review does; do not add a new secret. Read-only gh api GET calls on consumer .github/workflows/* paths; no enumeration beyond the exact-matched consumer set.
• Graceful degradation is a hard requirement: the cascade must never fail because a consumer repo is private or the token lacks a scope — follow the rate-limit/error-handling philosophy already in review-one-pr.sh (degrade, log ::warning::, continue).
• Stub gh in bats the way existing tests do (PATH shim / function override) — see tests/test_ci_status.bats for the pattern.

Project Structure Notes

Extends scripts/lib/downstream-impact.sh with the I/O assembler; adds a bats test. Still no prompt wiring (Story 4).

References

• scripts/review-one-pr.sh#ADVISORY_BOT_FEEDBACK_FILE
• scripts/review-one-pr.sh#cap-total-size
• .github/workflows/pr-review.yml#GH_PAT
• tests/test_ci_status.bats#gh-stub

Likely target surface

• scripts/lib/
• tests/

Story prepared by the BMAD Scrum Master (Bob) for epic #748. Status: ready-for-dev.

[don-petry]

Dev-Lead Implementation Plan

Issue: #751 — [Phase 2] Fetch consumer references + assemble the DOWNSTREAM_IMPACT context block

Scope

Add an I/O assembler assemble_downstream_impact to scripts/lib/downstream-impact.sh that calls the pure mapper, fetches each impacted consumer's referencing workflow file(s) via gh+GH_PAT (bounded by a per-PR repo cap and an 8 KB size cap), degrades gracefully on unreadable/private repos, and writes a human-readable DOWNSTREAM_IMPACT block to DOWNSTREAM_IMPACT_FILE.

Implementation Checklist

• scripts/lib/downstream-impact.sh: add assemble_downstream_impact <changed_files> <manifest> [out_file] (calls compute_downstream_impact, fetches consumer workflow files, builds + caps the block, writes the file, exports DOWNSTREAM_IMPACT_FILE)
• Honor DOWNSTREAM_IMPACT_MAX_REPOS (default 10) and DOWNSTREAM_IMPACT_MAX_BYTES (default 8000, mirrors ADVISORY_BOT_FEEDBACK cap)
• Graceful degradation: unreadable/private/missing-scope consumer → unreadable note, never non-zero exit; no surfaces → literal (none) with zero fetches
• .github/workflows/lint.yml: register the new bats test file in the run-bats.sh list

Tests to Write

• tests/test_downstream_impact_assemble.bats with a PATH-shimmed gh stub
• impacted + readable consumer → block lists surfaces, consumers, and referencing workflow file(s)
• impacted + unreadable consumer → graceful unreadable note, exit 0
• no-impact change → block is literal (none), zero gh calls
• repo cap + size cap enforced

Test Command

scripts/run-bats.sh tests/test_downstream_impact_assemble.bats (full suite via lint.yml), then bash .dev-lead/scripts/dev-lead-lint.sh

[don-petry]

Dev-Lead: Implementation Complete

Plan Execution

• Added assemble_downstream_impact <changed_files> <manifest> [out_file] to scripts/lib/downstream-impact.sh (calls the pure compute_downstream_impact mapper, fetches consumer workflow files, builds + caps the block, writes the file, exports DOWNSTREAM_IMPACT_FILE)
• Honors DOWNSTREAM_IMPACT_MAX_REPOS (default 10) and DOWNSTREAM_IMPACT_MAX_BYTES (default 8000, mirrors the ADVISORY_BOT_FEEDBACK 8 KB cap)
• Graceful degradation: unreadable/private/missing-scope consumer → unreadable note + ::warning::, never non-zero exit; no impacted surfaces → literal (none) with zero fetches
• Uses GH_PAT via gh (preferred, falls back to ambient GH_TOKEN); no new secret
• Added gh-stubbed bats test tests/test_downstream_impact_assemble.bats and registered it in .github/workflows/lint.yml

Test Results

$ bats tests/test_downstream_impact_assemble.bats
1..6
ok 1 impacted change with a readable consumer writes the surfaces, consumers, and referencing files
ok 2 impacted change with an unreadable consumer degrades to 'unreadable' and exits 0
ok 3 a no-impact change writes literal (none) and performs zero fetches
ok 4 the per-PR repo cap bounds the number of consumers fetched
ok 5 the assembled block is truncated to the configured size cap
ok 6 DOWNSTREAM_IMPACT_FILE is exported and points at the written file

$ scripts/run-bats.sh <downstream/manifest/consumer/ci-status/auth-scopes suites>
1..95   (no failures)

$ shellcheck -S warning scripts/lib/downstream-impact.sh
=== shellcheck (warning) OK ===

$ bash .dev-lead/scripts/dev-lead-lint.sh
  [lint] shellcheck on 67 file(s)...
  [lint] validating 4 agent profile(s)...
  [lint] all checks passed

Files Changed

• scripts/lib/downstream-impact.sh: added the I/O assembler assemble_downstream_impact plus two private helpers (_downstream_gh for GH_PAT-preferring auth, _downstream_referencing_files for listing+fetching+matching a consumer's workflow files). The pure mapper is unchanged.
• tests/test_downstream_impact_assemble.bats: new gh-stubbed bats test (6 cases) covering readable/unreadable/no-impact plus the repo cap, size cap, and path export.
• .github/workflows/lint.yml: registered the new test file in the run-bats.sh list.

Notes

• Matching locates which file references a surface by substring-matching the repo-relative surface path (e.g. .github/workflows/pr-review.yml) against the consumer's uses: line — the consumer was already confirmed to pin that surface by the pure mapper, so this only resolves the filename. Best-effort context.
• Verified the function returns 0 on every path under set -euo pipefail (the caller review-one-pr.sh runs with it), so a fetch failure can never break the cascade.
• Per the issue, no prompt wiring is included — that is Story 4. Default output path is /tmp/cascade/downstream-impact.txt, mirroring the ADVISORY_BOT_FEEDBACK_FILE lifecycle.
• Followed the repo constraint: did not commit, push, or open a PR — CI handles git operations.