[Phase 1] Define the consumer manifest + validator (shared-surface -> consumers map)

[github-actions]

Story

As a pr-review maintainer,
I want a committed, validated consumer-manifest that maps each provider reusable workflow to the org repos (consumers) that pin it,
so that the downstream-impact pass has a single, machine-checkable source of truth for which changes affect which consumers.

Acceptance Criteria

1. A committed manifest file (JSON) declares: providers = [".github", ".github-private"]; consumers = a list of {repo, refs} where refs are the provider reusable-workflow paths that repo pins via uses:; and surface_sources = per reusable-workflow path, the in-provider scripts/lib/*.sh and prompts/* files it sources (exact paths).
2. A refresh/builder script populates consumers empirically: it enumerates org repos and detects uses: references to provider reusable workflows using GH_PAT (the same token .github/workflows/pr-review.yml already uses), and writes the manifest deterministically (stable key ordering) so re-runs produce a clean diff.
3. A validator script exits non-zero on: invalid JSON/schema, a surface_sources key that is not an existing reusable-workflow path in this repo, or a surface_sources value pointing at a scripts/lib/prompts path that does not exist in this repo.
4. A bats test (tests/test_consumer_manifest.bats) covers: a well-formed manifest passes; a manifest referencing a non-existent local surface fails; malformed JSON fails.
5. shellcheck passes on every new/changed shell script.

Tasks / Subtasks

• Add the manifest file (e.g. scripts/lib/consumer-manifest.json) with the providers/consumers/surface_sources shape, seeded from docs/initiatives/agentic-release-strategy.md and an initial empirical scan. (AC: test issue from agent #1)
• Add a builder/refresh script (e.g. scripts/refresh-consumer-manifest.sh) that enumerates org repos via gh + GH_PAT and detects provider-reusable uses: references, writing the manifest with stable ordering. (AC: Go-live improvements for PR review agent #2)
• Add a validator (e.g. scripts/lib/validate-consumer-manifest.sh or a --validate flag) that checks schema and that every referenced local surface exists. (AC: Add @claude delegation, auto-merge, and rebase handling #3)
• Add tests/test_consumer_manifest.bats and register it in the bats job list in .github/workflows/lint.yml (repo-specific test-list exception per AGENTS.md). (AC: Optimize review: small-PR and incremental fast paths #4, feat: add Copilot engine support via REVIEW_ENGINE toggle #5)

Dev Notes

• Manifest is data, not code — follow the repo convention of keeping tabular/lookup data in scripts/lib/ (cf. scripts/lib/model-pricing.tsv, scripts/lib/review-registry.tsv). JSON is appropriate here because the consumer->refs relation is nested.
• Providers are fixed: .github and .github-private (resolved in 💡 Cross-Repo Impact-Aware Review Annotations for Downstream Breakage Detection #653). Consumers are ALL org repos that pin a provider reusable — do NOT hand-curate; build empirically. The release-strategy doc names example consumers (bmad-bgreat-suite, google-app-scripts, markets, ContentTwin) but the discussion body also names Broodly/TalkTerm — the empirical scan is authoritative, not either list.
• Reusable workflows are the consumer-facing surface (what a consumer uses:). surface_sources captures the single documented hop from a changed lib/prompt to the reusable(s) that source it — exact path only, no recursive graph (💡 Cross-Repo Impact-Aware Review Annotations for Downstream Breakage Detection #653: exact match).
• Use GH_PAT exactly as .github/workflows/pr-review.yml does (GH_TOKEN: ${{ secrets.DON_PETRY_BOT_GH_PAT_CLASSIC || secrets.DON_PETRY_BOT_GH_PAT }}); the org-enumeration call needs read access across consumer repos, which that token already has.
• Testing: bats is the repo standard for script behavior (see tests/), shellcheck for lint. New bats files MUST be added to the lint.yml bats list (AGENTS.md documents this as a repo-specific exception).

Project Structure Notes

New manifest + scripts live under scripts//scripts/lib/; new test under tests/. No changes to the cascade behavior in this story — it only introduces the data + its validator.

References

• docs/initiatives/agentic-release-strategy.md#consumers
• .github/workflows/pr-review.yml#GH_PAT
• scripts/lib/model-pricing.tsv
• scripts/lib/review-registry.tsv
• AGENTS.md#bats-test-list-exception
• .github/workflows/lint.yml#bats

Likely target surface

• scripts/
• scripts/lib/
• tests/
• .github/workflows/lint.yml

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

[don-petry]

Dev-Lead Implementation Plan

Issue: #749 — [Phase 1] Define the consumer manifest + validator (shared-surface -> consumers map)

Scope

Add a committed, validated JSON consumer-manifest (providers/consumers/surface_sources) plus an empirical refresh/builder script, a schema+existence validator, and a bats test wired into lint.yml.

Implementation Checklist

• scripts/lib/consumer-manifest.json — seeded providers (.github, .github-private), empirically-scanned consumers ({repo, refs}), and surface_sources (per .github-private reusable-workflow path -> the exact scripts/lib/*.sh + prompts/* it sources)
• scripts/lib/validate-consumer-manifest.sh — sourced lib + CLI; exits non-zero on invalid JSON/schema, a surface_sources key that is not an existing reusable-workflow path in this repo, or a surface_sources value not pointing at an existing scripts/lib/prompts path
• scripts/refresh-consumer-manifest.sh — enumerates org repos via gh + GH_TOKEN (GH_PAT), detects provider uses: references, writes the manifest deterministically (stable key + array ordering) preserving providers/surface_sources
• .github/workflows/lint.yml — register tests/test_consumer_manifest.bats in the bats job list (repo-specific test-list exception per AGENTS.md)

Tests to Write

• tests/test_consumer_manifest.bats: the committed manifest passes the validator
• manifest referencing a non-existent local surface (bad key + bad value) fails
• malformed JSON fails
• manifest schema-shape violations fail

Test Command

scripts/run-bats.sh tests/test_consumer_manifest.bats (full suite via lint.yml bats job); lint via bash .dev-lead/scripts/dev-lead-lint.sh + shellcheck

[don-petry]

Dev-Lead: Implementation Complete

Plan Execution

• Added scripts/lib/consumer-manifest.json — providers (.github, .github-private), empirically-scanned consumers (8 repos × pinned provider reusable refs), and hand-seeded surface_sources for the two .github-private reusables that source scripts/lib/prompts (pr-review.yml, dev-lead-reusable.yml)
• Added validator scripts/lib/validate-consumer-manifest.sh — exits non-zero on invalid JSON, schema-shape violations, a surface_sources key that is not an existing reusable-workflow path in this repo, or a value not pointing at an existing scripts/lib/*.sh / prompts/* file
• Added builder scripts/refresh-consumer-manifest.sh — enumerates org repos via gh + GH_TOKEN (the same PAT pr-review.yml uses), detects provider uses: references, writes deterministically (sorted keys, sorted/deduped refs); preserves providers + surface_sources. Verified: re-run produces a clean (empty) diff
• Registered tests/test_consumer_manifest.bats in the lint.yml bats job list (repo-specific test-list exception per AGENTS.md)

Test Results

1..12
ok 1 committed manifest passes the validator
ok 2 committed manifest is valid JSON with the required top-level keys
ok 3 committed manifest declares both providers
ok 4 malformed JSON fails validation
ok 5 missing surface_sources key fails validation
ok 6 consumer entry missing repo fails validation
ok 7 consumer entry with non-array refs fails validation
ok 8 surface_sources key that is not an existing reusable workflow fails
ok 9 surface_sources value pointing at a missing scripts/lib file fails
ok 10 surface_sources value pointing at a missing prompts file fails
ok 11 surface_sources value outside scripts/lib or prompts fails
ok 12 a well-formed minimal manifest with real surfaces passes

Verification

• shellcheck --severity=warning -x clean on both new scripts
• .dev-lead/scripts/dev-lead-lint.sh — all checks passed (66 shell files + agent profiles)
• Builder determinism confirmed (re-run = clean diff)
• Validator passes on the committed manifest

Files Changed

• scripts/lib/consumer-manifest.json (new): the manifest data
• scripts/lib/validate-consumer-manifest.sh (new): schema + local-surface validator
• scripts/refresh-consumer-manifest.sh (new): empirical consumers builder
• tests/test_consumer_manifest.bats (new): 12 bats cases (AC Optimize review: small-PR and incremental fast paths #4)
• .github/workflows/lint.yml: registered the new bats file

Notes

• The empirical scan is authoritative (per the issue): consumers include .github and .github-private themselves (they pin provider reusables — .github-private self-hosts Ring 0). refs are stored provider-qualified (<provider>/.github/workflows/<name>.yml) so each ref's prefix maps to a providers entry. Stale consumer refs (e.g. TalkTerm/broodly still pinning the retired pr-review-reusable.yml) are recorded as-pinned and are intentionally NOT existence-checked — only surface_sources (local surfaces) are validated.
• surface_sources captures the single documented hop (exact paths) from a changed lib/prompt to the reusable that sources it — ci-failure-analyst-reusable.yml is omitted because it sources no scripts/lib/prompts files (fully inline).