Skip to content

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

Closed

Description

@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

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.

Activity

  1. don-petry commented on Jun 18, 2026

    @don-petry
    Collaborator

    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

  2. don-petry commented on Jun 18, 2026

    @don-petry
    Collaborator

    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).
  3. added a commit that references this issue on Jun 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    dev-leadFor dev-lead agent pickupinitiativeEpic / initiative tracking issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions