Repository navigation
Closed
Labels
dev-leadFor dev-lead agent pickupFor dev-lead agent pickupinitiativeEpic / initiative tracking issueEpic / initiative tracking issue
Description
Story
As a pr-review maintainer,
I want a pure, network-free helper that takes a PR's changed file list plus the manifest and returns the impacted shared surfaces and the exact-matched consumers,
so that the impact computation is deterministic and unit-testable in isolation from any GitHub I/O.
Acceptance Criteria
- A pure function (bash + jq, NO network/
ghcalls) accepts a newline-delimited list of changed paths and the manifest path, and emits a JSON object:{impacted_surfaces: [...], impacted_consumers: [{repo, via:[surface,...]}], ...}. - Matching is exact-path: a changed reusable-workflow path matches consumers whose
refscontain exactly that path; a changedscripts/lib/*.shorprompts/*path matches viasurface_sources(the reusables that list it), then to those reusables' consumers. No prefix/glob/transitive expansion beyond the single documented hop. - Changed paths that are not in any shared surface produce an empty impact result (no false positives).
- A bats test (
tests/test_downstream_impact_map.bats) drives fixtures covering: a direct reusable-workflow change, ascripts/libchange mapped viasurface_sources, aprompts/change, a no-impact change, and a change touching multiple surfaces. shellcheckpasses on the new helper.
Tasks / Subtasks
- Add the pure mapping helper (e.g.
scripts/lib/downstream-impact.shexposing acompute_downstream_impact <changed_files> <manifest>function), implemented with jq over the manifest — nogh/network. (AC: test issue from agent #1, Go-live improvements for PR review agent #2, Add @claude delegation, auto-merge, and rebase handling #3) - Add fixture manifests + changed-file lists under
tests/fixtures/and the bats test exercising every match/no-match case; register the new bats file inlint.yml. (AC: Optimize review: small-PR and incremental fast paths #4, feat: add Copilot engine support via REVIEW_ENGINE toggle #5)
Dev Notes
- Keep this helper PURE (no
gh, no env-dependent state) so it is trivially unit-testable — mirror the structure ofscripts/lib/review-cycle.sh(jq-program helpers, defensive degradation to empty on malformed input). - Exact-path matching only (💡 Cross-Repo Impact-Aware Review Annotations for Downstream Breakage Detection #653). The two match kinds: (a) changed path is itself a reusable-workflow
ref-> direct consumer match; (b) changed path is a lib/prompt listed in some reusable'ssurface_sources-> map to those reusables, then to their consumers. Do not implement recursive source-graph resolution. - Degrade defensively: malformed manifest or empty changed-file list yields an empty, well-formed impact object (never an error that breaks the cascade) — same philosophy as
compute_review_cyclereturning 0 on bad input. - Reuse the repo's fixture convention under
tests/fixtures/; consume the manifest produced by Story 1 (do not redefine its shape).
Project Structure Notes
Adds scripts/lib/downstream-impact.sh + fixtures + a bats test. Pure logic only — no wiring into review-one-pr.sh yet (that is Story 4).
References
- scripts/lib/review-cycle.sh#compute_review_cycle
- tests/test_review_cycle.bats
- docs/initiatives/agentic-release-strategy.md#consumers
- .github/workflows/lint.yml#bats
Likely target surface
scripts/lib/tests/tests/fixtures/
Story prepared by the BMAD Scrum Master (Bob) for epic #748. Status: ready-for-dev.
Metadata
Metadata
Assignees
Labels
dev-leadFor dev-lead agent pickupFor dev-lead agent pickupinitiativeEpic / initiative tracking issueEpic / initiative tracking issue
Activity
don-petry commentedon Jun 18, 2026
Dev-Lead Implementation Plan
Issue: #750 — [Phase 2] Pure mapping helper: changed files -> impacted shared surfaces + consumers
Scope
Add a pure, network-free bash+jq helper (
compute_downstream_impact <changed_files> <manifest>) that maps a PR's changed-file list, over the Story-1 consumer manifest, to the impacted shared surfaces and exact-matched consumers — nogh/network, defensively degrading to an empty well-formed object on bad input.Implementation Checklist
scripts/lib/downstream-impact.sh— sourced lib exposingcompute_downstream_impact, jq-program style mirroringscripts/lib/review-cycle.sh. Two match kinds: (a) changed reusable-workflow path that a consumer ref pins exactly (provider-prefix normalized) → direct surface; (b) changedscripts/lib/*.sh/prompts/*path listed in asurface_sourcesvalue → its reusable key(s) → those reusables' consumers. Single hop, no transitive/glob expansion. Degrades to{impacted_surfaces:[],impacted_consumers:[],unmatched:[]}on malformed manifest / empty input.tests/fixtures/downstream-impact/manifest.json— controlled fixture manifest (providers/consumers/surface_sources) decoupled from the live committed manifest.tests/test_downstream_impact_map.batsin.github/workflows/lint.ymlbats list.Tests to Write (
tests/test_downstream_impact_map.bats)scripts/lib/*.shchange mapped viasurface_sources→ reusable(s) → consumersprompts/*change mapped viasurface_sourcesunmatchedTest Command
bats tests/test_downstream_impact_map.bats(full suite viascripts/run-bats.sh ...); lint viabash .dev-lead/scripts/dev-lead-lint.sh+shellcheck.don-petry commentedon Jun 18, 2026
Dev-Lead: Implementation Complete
Plan Execution
scripts/lib/downstream-impact.shexposingcompute_downstream_impact <changed_files> <manifest>(bash + jq, nogh/network), styled afterscripts/lib/review-cycle.sh.scripts/lib/*.sh/prompts/*path listed in a reusable'ssurface_sources→ that reusable → its consumers. Provider prefix on consumer refs is normalised (longest-match) so the helper is provider-agnostic — no transitive/glob expansion.{"impacted_surfaces":[],"impacted_consumers":[],"unmatched":[]}(never a non-zero exit).tests/fixtures/downstream-impact/manifest.json(decoupled from the live committed manifest).tests/test_downstream_impact_map.bats(15 tests) covering all AC Optimize review: small-PR and incremental fast paths #4 cases..github/workflows/lint.yml.Output shape
{ "impacted_surfaces": ["<repo-relative reusable path>", ...], "impacted_consumers": [{"repo": "...", "via": ["<surface>", ...]}, ...], "unmatched": ["<changed path with no shared surface>", ...] }Test Results
Smoke test against the real committed manifest
scripts/lib/review-cycle.sh→ surface.github/workflows/pr-review.yml→ 5 consumers (.github-private,ContentTwin,bmad-bgreat-suite,google-app-scripts,markets). Correctly excludesTalkTerm/broodly(they pinpr-review-reusable.yml, a different name)..github/workflows/dev-lead-reusable.yml→ 8 consumers.README.md→ empty impact, listed underunmatched.Files Changed
scripts/lib/downstream-impact.sh(new): the pure helper + jq program.tests/test_downstream_impact_map.bats(new): 15-case bats suite.tests/fixtures/downstream-impact/manifest.json(new): controlled fixture manifest..github/workflows/lint.yml: registered the new bats file in thebatsjob list (per the AGENTS.md repo-specific test-list exception).Notes
unmatchedfield (sanctioned by the...in the AC test issue from agent #1 shape) so the consuming story can report changed paths with no known downstream surface; the AC Add @claude delegation, auto-merge, and rebase handling #3 "empty impact result" guarantee is upheld (impacted_surfaces/impacted_consumersare[]).review-cycle.sh, this is a sourced library (noset -euo pipefail, no top-level execution) so it never mutates the caller's shell options. Pure logic only — no wiring intoreview-one-pr.sh(that is Story 4).feat: implement issue #750 — [Phase 2] Pure mapping helper: changed f…