Skip to content

Epic: Enforce identical reusable-workflow shims across the fleet (full-file drift, not just pin) #604

Open

Description

@don-petry

Problem

Fleet Monitor issue combsmith/broodminder-data#7 proposed trimming dev-lead.yml's
on: block, justified by: "the stub header explicitly permits adjusting dev-lead triggers
for repo-specific needs, and drift detection guards only the initiative-planner stub, so this
is not flagged drift."
That statement is currently true — and that is the bug. We want
dev-lead, pr-review-*, and every other reusable-workflow shim to be full-file identical
across repos
(modulo the per-repo ring/channel pin), so a trigger/permission/concurrency
edit to a shim is flagged drift, never sanctioned.

Why it slips through today (enforcement inventory)

Shim Check What it validates on: / full-file?
dev-lead.yml check_dev_lead_stub() channel pin (stable/next/ring<N>), agent_ref, no per-stub concurrency:, statuses: read ❌ on: never checked
auto-rebase, dependency-audit, dependabot-automerge, dependabot-rebase, agent-shield, pr-review-mention check_centralized_workflow_stubs() (RING) pin only ❌
feature-ideation same, fixed v1 pin only; template is a frozen @SHA (off channel model) ❌
pr-auto-review none not in centralized[]; template pins @v2 (off channel) ❌
initiative-planner, initiative-driver fleet_stub_drift.sh (byte-identity) full-file blob-SHA vs canonical ✅ (only these two)

Both compliance functions are field-allowlist checks, not full-file identity. The only
byte-identity mechanism (fleet_stub_drift.sh via fleet_monitor.sh STUB_REGISTRY) is
enrolled for just the two initiative stubs. Net: a trimmed trigger surface on any shim passes.

Fleet is already fragmented (survey, 2026-07-04)

Deployed reusable pins across 7 consumer repos are a mix of @vN, @SHA, @main, and channel
tags on nearly every shim. Only broodminder-export is fully converged onto the
@<name>/stable channel model.
This drift is invisible because ring-pins.sh's legacy
@v1/@v2/@SHA grace is still active (declared "migration complete" in-comment, but the fleet
is not converged).

Sanctioning language to remove (A)

  • standards/workflows/dev-lead.yml header line ~19: "…may be freely modified on PR branches
    to adjust triggers for repo-specific needs."
    (contradicts line 7 "Copy this file verbatim").
  • .github-private/AGENTS.md: "Repo-specific trigger adjustments may be made to dev-lead.yml…"
  • .github-private/docs/dev-lead/implementation-plan.md (~line 543): same header text.

Target state

Every centralized shim is byte-identical across repos after normalizing the ring/channel pin
to the repo's tier
(ring_canonical_ref, deploy-standard-workflows.sh repin). Allowed pins:
@<name>/{stable,next,ring0,ring1,…} — never @SHA, @main, or @vN. Any other diff = drift.

Approach: B + A → D (D proves E)

Do B (standards) and A (strip sanctions) first; then D (build tier-normalized
byte-identity fleet drift and enroll every shim). Running D surfaces the existing fragmentation,
and that report drives and proves E (consumer re-syncs) — monitor goes green as repos converge.

Stories

B — Standards (petry-projects/.github)

  • standards/ci-standards.md: state centralized shims are full-file identical modulo the
    tier channel pin
    ; triggers/permissions/concurrency are not repo-adjustable. Cross-link
    the channel model (#reusable-workflow-versioning--the-stable-channel).
  • Decide & document the two off-channel exceptions: bring feature-ideation and
    pr-auto-review onto the channel model, or record them as explicit fixed-pin exceptions
    (and add pr-auto-review to centralized[] either way — it is currently unenforced).

A — Remove sanctioning language

D — Tier-normalized full-file drift + enrollment

  • Extend the byte-identity model so "expected" content is the canonical template repinned to
    the target repo's ring tier
    (reuse deploy-standard-workflows.sh repin / ring_canonical_ref,
    mirroring template_stub_drift.sh's emit-and-compare). This is what makes full-file identity
    compatible with per-tier channel pins.
  • Add a full-file on:/permissions/concurrency guard to check_dev_lead_stub() and the
    RING branch of check_centralized_workflow_stubs() (or fold both into the drift check), so a
    trimmed trigger surface is flagged in the weekly compliance audit too.
  • Register dev-lead.yml, pr-review-mention.yml, and the RING shims in
    fleet_monitor.sh STUB_REGISTRY (.github-private) so drift is alerted, not just audited.
  • Tests: fleet_stub_drift.bats / compliance-audit test suite for the tier-normalized cases.

E — Converge the fleet (driven & proven by D)

  • Re-sync each drifted consumer to its tier channel (per the D drift report): TalkTerm,
    broodly, ContentTwin, markets, google-app-scripts, bmad-bgreat-suite — one PR per
    repo, admin-merge where rulesets block direct push.
  • Once converged, remove the @v1/@v2/@SHA legacy grace from ring-pins.sh so off-channel
    pins are hard-failed (the grace's own comment already claims the migration is complete).
  • Acceptance: fleet drift monitor reports 0 drifted across all enrolled shims.

Out of scope / follow-ups

  • CodeQL / ci.yml / sonarcloud.yml (per-repo by design — not centralized shims).
  • SonarCloud S7637/S7635 markers already handled by existing standards.

Survey performed against fresh branches: .github@docs/enrollment-gate-labels,
.github-private@fix/code-quality-add-secret-scan-coverage-966.

Decision log

Story tracking

Execution model

Work is triggered by applying the dev-lead label to the story issues above; progress is monitored via the fleet monitor and steered as needed. Order: #605 / #606 / #1079 (independent) → #607 and #1079-D (drift) → E.

Activity

  1. don-petry commented on Jul 10, 2026

    @don-petry
    ContributorAuthor

    Plan review — 2026-07-10

    The world moved under this epic since it was filed (2026-07-04). The motivation section is largely overtaken by events; the enforcement thesis is still valid and unaddressed. Summary and revised scope below.

    Overtaken by events

    Still valid and unaddressed (the actual core of this epic)

    • The identity gap is untouched. check_dev_lead_stub() still never validates on:; check_centralized_workflow_stubs() RING branch validates pin only; and fleet_stub_drift.sh STUB_REGISTRY still contains only initiative-planner. A trimmed trigger surface on any shim still passes silently — the exact broodminder-export#7 hole.
    • Sanctioning language still present verbatim: standards/workflows/dev-lead.yml:19, .github-private/AGENTS.md:26, .github-private/docs/dev-lead/implementation-plan.md:543.
    • feature-ideation (@v1/@v2/@sha) and pr-auto-review (@v2/@sha) are still off-channel — now the only consumer-facing off-channel pins left in the fleet (RING_REUSABLES still excludes both).

    Revised scope

    Body edits recommended

    1. "Fleet is already fragmented (survey, 2026-07-04)" → RING shims converged fleet-wide on tier channels ([#850] standards-deploy driver deploys BROKEN dev-lead pins (@dev-lead/v14-* has no tag — uses release major, not channel major) #870 + canary-rollout cutover); only feature-ideation/pr-auto-review remain off-channel pending Story (B): channel-ify feature-ideation + pr-auto-review [#604] #606.
    2. Strike "invisible because ring-pins.sh's legacy @v1/@v2/@SHA grace is still active" — grace removed in [#850] standards-deploy driver deploys BROKEN dev-lead pins (@dev-lead/v14-* has no tag — uses release major, not channel major) #870.
    3. Story E checklist: mark "remove the @v1/@v2/@SHA legacy grace" done ([#850] standards-deploy driver deploys BROKEN dev-lead pins (@dev-lead/v14-* has no tag — uses release major, not channel major) #870); scope remaining re-sync to the two Story (B): channel-ify feature-ideation + pr-auto-review [#604] #606 shims only.

    New: major-version gap (Story F, filed separately)

    The version+ring model has no major-version boundary — channels (next/ring0/ring1/stable) encode blast-radius tier, not semver major, and @vN is now drift. A breaking change promoted to stable reaches every stable consumer with no opt-in gate. Filed as Story F to decide: major-scoped channels vs. a promotion gate at the major bump vs. accept-and-document.

    Reviewed 2026-07-10 against live ring-pins.sh, compliance-audit.sh, fleet_stub_drift.sh, and the deployed pins across all 7 consumer repos.


    Generated by Claude Code

  2. added 3 commits that reference this issue on Jul 13, 2026
  3. added 2 commits that reference this issue on Aug 7, 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

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions