Skip to content

[bug] seed-repo-template.sh repins caller stubs to pre-#1184 legacy channels — template-drift enforces a baseline that contradicts standards #1436

Closed

Description

@don-petry

Story

As a maintainer relying on template-drift to keep repo-template faithful to standards/,
I want the guard's expected baseline to use the current major-scoped channel convention,
so that it stops reporting the correct state as DRIFTED and stops silently halting review across the repo.

Problem — the drift guard enforces a pre-#1184 baseline

scripts/seed-repo-template.sh repins every caller stub using a hardcoded table (:66-74):

"agent-shield|caller|petry-projects/.github|agent-shield/stable"
"auto-rebase|caller|petry-projects/.github|auto-rebase/stable"
"dependabot-automerge|caller|petry-projects/.github|dependabot-automerge/stable"
"dependency-audit|caller|petry-projects/.github|dependency-audit/stable"
"dev-lead|caller|petry-projects/.github-private|dev-lead/stable"
…

Those are the pre-#1184 legacy channel names. AGENTS.md (:385) states the convention is major-scoped: "Moving channel tags <name>/v<MAJOR>-<tier> (major-scoped, #1184…)", and canonical standards/ already uses it:

stub canonical standards/ seed-script repin
agent-shield @agent-shield/v2-stable @agent-shield/stable
auto-rebase @auto-rebase/v2-stable @auto-rebase/stable
dependabot-automerge @dependabot-automerge/v2-stable @dependabot-automerge/stable
dependency-audit @dependency-audit/v2-stable @dependency-audit/stable
dev-lead @dev-lead/v1-stable @dev-lead/stable

So seed-repo-template.sh takes a correct canonical stub and rewrites its pin to a legacy channel. template-drift then compares the template against that rewritten output — meaning the guard's "expected" content contradicts standards/ for every caller stub.

The correct change was reported as drift

repo-template commit d5a79417 (dev-lead, 10:51Z) repinned dev-lead.yml:

-    uses: …/dev-lead-reusable.yml@dev-lead/stable
+    uses: …/dev-lead-reusable.yml@dev-lead/v1-stable
-      agent_ref: dev-lead/stable
+      agent_ref: dev-lead/v1-stable

That moved the template toward canonical standards and the #1184 convention — it is right. template-drift immediately reported dev-lead.yml, agent-shield.yml and dependabot-automerge.yml as DRIFTED, because the guard expects the legacy form.

Why it matters beyond a red check

template-drift is not a required check, but a red non-required check makes compute_ci_status return failing, and review-one-pr.sh:141 then silently skips the review (run log only, nothing posted). Zero PRs merged in this repo between 09:55Z and 15:14Z — an epic halted by a guard enforcing an obsolete convention. The reviewer-side half is #1427 AC #7; this issue is one of the causes.

Do not "fix" this by re-seeding the affected files. Re-seeding would revert d5a79417 and pin the template back to legacy channels — regressing it away from standards to satisfy a stale guard. The repin table is what must change.

Acceptance Criteria

  1. seed-repo-template.sh's repin table produces the same channel refs as canonical standards/ for every caller stub — major-scoped <name>/v<MAJOR>-<tier>, matching AGENTS.md and F2: cut-release.sh learns v<major>-<tier> channels [#657] #1184.
  2. The channel is derived from the canonical stub rather than hardcoded, so a future channel promotion (e.g. v2-stable → v3-stable) cannot re-introduce this skew. If a hardcoded table is retained for a stated reason, a test asserts each entry equals the canonical stub's pin.
  3. template-drift is green on main with the corrected table, without reverting repo-template@d5a79417.
  4. A test covers the exact regression: a canonical stub pinned @<name>/v<MAJOR>-stable must emit that same pin, not @<name>/stable.
  5. Any consumer repo already seeded with a legacy <name>/stable pin is identified and reported (whether to repin them is a separate decision — record the list).
  6. The relationship to the mutable-ref exception in AGENTS.md is checked: the sanctioned-exception guidance lists channel-tag namespaces, and both forms currently exist as live tags (dev-lead/stable and dev-lead/v1-stable). Record whether the legacy tags are still promoted or are now dead, since a stub pinned to an unpromoted channel silently stops receiving updates.

Tasks / Subtasks

Dev Notes

Project Structure Notes

scripts/seed-repo-template.sh (the TEMPLATE_STUBS repin table), scripts/template_stub_drift.sh (consumer of the emission), tests under tests/ (template_stub_drift.bats exists) registered in lint.yml's bats list.

References

Likely target surface

  • scripts/seed-repo-template.sh

Found while repairing the template-drift failure that halted all PR review in this repo from 09:55Z. Re-seeding the reported files would have regressed the template to legacy channel pins — the guard, not the template, is wrong.

Activity

  1. don-petry commented on Aug 2, 2026

    @don-petry
    CollaboratorAuthor

    Fix verified locally — 3 of 5 stubs resolve immediately

    I applied the corrected repin table to a clean origin/main worktree and ran the real guard (bash scripts/template_stub_drift.sh) against live repo-template.

    The exact change (scripts/seed-repo-template.sh:66-74):

    agent-shield/stable          → agent-shield/v2-stable
    auto-rebase/stable           → auto-rebase/v2-stable
    dependabot-automerge/stable  → dependabot-automerge/v2-stable
    dependency-audit/stable      → dependency-audit/v2-stable
    dev-lead/stable              → dev-lead/v1-stable
    

    Note dependabot-rebase and pr-review-mention were already on v2-stable — so this is a half-finished #1184 migration, not an oversight of the whole table. That is worth stating in the fix's commit message.

    Result — three flip straight to ALIGNED:

    agent-shield.yml          DRIFTED → ALIGNED
    dependabot-automerge.yml  DRIFTED → ALIGNED
    dev-lead.yml              DRIFTED → ALIGNED     ← confirms repo-template@d5a79417 was correct
    

    That last line is the proof the guard was wrong, not the template: dev-lead's repin to @dev-lead/v1-stable becomes ALIGNED the moment the table is corrected.

    Two remain genuinely drifted, and each differs by exactly one line — the same legacy pin, plus a missing trailing newline:

      auto-rebase.yml
    - …/auto-rebase-reusable.yml@auto-rebase/stable
    + …/auto-rebase-reusable.yml@auto-rebase/v2-stable
    
      dependency-audit.yml
    - …/dependency-audit-reusable.yml@dependency-audit/stable
    + …/dependency-audit-reusable.yml@dependency-audit/v2-stable

    Those need a re-seed in repo-template, tracked separately (see below) because it is a different repo.

    This PR self-validates — no chicken-and-egg

    template-drift runs bash scripts/template_stub_drift.sh from the PR's own checkout (lint.yml:225-239, plain actions/checkout with no ref:). So the fix PR exercises its own corrected script and its template-drift job passes, even though main is currently red. It can merge normally.

    Sequencing

    1. This issue — correct the table + regression test (in this repo).
    2. Then re-seed auto-rebase.yml + dependency-audit.yml in repo-template, generating with the fixed script. Doing that first would write the legacy pins straight back in.

    Only after both is template-drift green on main here — which is what stops pr-review silently skipping every PR (#1427 AC #7) and unblocks the epic.

    AC #4 — the regression test, concretely

    Assert that a canonical stub pinned @<name>/v<MAJOR>-stable emits that same pin, not @<name>/stable. Today's table would fail that test for the five entries above and pass for the two already migrated, which makes it a genuine guard against the migration being left half-done again.

  2. don-petry commented on Aug 2, 2026

    @don-petry
    CollaboratorAuthor

    Dev-Lead Implementation Plan

    Issue: #1436 — [bug] seed-repo-template.sh repins caller stubs to pre-#1184 legacy channels

    Scope

    Make seed-repo-template.sh derive each caller stub's repin channel from the canonical standards/ stub's own uses: ref (major-scoped <name>/v<MAJOR>-stable, #1184) instead of the hardcoded pre-#1184 <name>/stable table, so template-drift's baseline stops contradicting standards — without reverting repo-template@d5a79417.

    Root cause confirmed

    • Canonical standards/workflows/*.yml all pin @<name>/v<MAJOR>-stable (verified live: agent-shield/v2, auto-rebase/v2, dependabot-automerge/v2, dependency-audit/v2, dev-lead/v1, dependabot-rebase/v2, pr-review-mention/v2).
    • The script's WORKFLOW_MANIFEST hardcodes legacy <name>/stable for 5 of them, so the emitted "expected" baseline rewrites the correct pin to a legacy channel → every caller stub reported DRIFTED.

    Implementation Checklist

    • scripts/seed-repo-template.sh: drop the hardcoded channel field from WORKFLOW_MANIFEST rows (name|kind|host).
    • Add _derive_stable_channel <name> (reads stub on stdin): extract <name>/v<MAJOR> from the <name>-reusable.yml@<ref> pin, emit <name>/v<MAJOR>-stable; fail loud if no major-scoped ref is found.
    • Rewire _repin_stub_content to derive the channel from the fetched canonical content (drops the channel arg); update _emit_workflow and the --repin CLI accordingly.

    Tests to Write / Update (tests/test_seed_repo_template.bats)

    • AC Optimize review: small-PR and incremental fast paths #4 regression: a canonical stub pinned @<name>/v<MAJOR>-stable emits that same pin, not @<name>/stable.
    • _derive_stable_channel unit: v2-next→v2-stable, v1-stable→v1-stable; preserves the major.
    • Update the existing repin tests to major-scoped inputs/expectations (they asserted the buggy legacy <name>/stable output).
    • Replace the _manifest_channel helper (4-field manifest) now that the channel is derived.

    AC #5 / #6 (investigation — reported, no code)

    • Enumerate consumer repos still carrying legacy <name>/stable pins.
    • Record whether legacy <name>/stable tags are still promoted. Preliminary finding: legacy tags are FROZEN — agent-shield/stable, auto-rebase/stable, dependency-audit/stable point to OLDER commits than their v<MAJOR>-stable counterparts, so consumers on legacy pins are silently not receiving promotions.

    Test Command

    bats tests/test_seed_repo_template.bats tests/template_stub_drift.bats + bash .dev-lead/scripts/dev-lead-lint.sh

  3. don-petry commented on Aug 2, 2026

    @don-petry
    CollaboratorAuthor

    Follow-on filed — the re-seed half

    The two genuinely-drifted stubs (auto-rebase.yml, dependency-audit.yml) are tracked in the template repo as petry-projects/repo-template#125, since the change must be made there.

    It is deliberately not yet assigned to dev-lead: re-seeding with today's generator would write the legacy <name>/stable pins straight back in. It should be picked up only once this issue has merged and the generator emits the major-scoped refs. I will label it dev-lead at that point.

    Sequence: #1436 (here) → repo-template#125 → template-drift green → pr-review stops silently skipping → #1434 and the epic queue drain.

  4. don-petry commented on Aug 2, 2026

    @don-petry
    CollaboratorAuthor

    Dev-Lead: Implementation Complete

    Plan Execution

    Test Results

    $ bats tests/test_seed_repo_template.bats tests/template_stub_drift.bats \
           tests/caller_stub_freeze.bats tests/fleet_stub_drift.bats
    1..77
    ... (77 ok, 0 failures)
    
    $ shellcheck scripts/seed-repo-template.sh   → clean
    $ bash .dev-lead/scripts/dev-lead-lint.sh    → all checks passed
    

    Files Changed

    AC #3 — template-drift result (live run)

    The three files the issue flagged are now ALIGNED, without reverting repo-template@d5a79417:

    stub committed (repo-template) expected (new emission) status
    dev-lead.yml @dev-lead/v1-stable @dev-lead/v1-stable ALIGNED ✓
    agent-shield.yml @agent-shield/v2-stable @agent-shield/v2-stable ALIGNED ✓
    dependabot-automerge.yml @dependabot-automerge/v2-stable @dependabot-automerge/v2-stable ALIGNED ✓
    dependabot-rebase.yml / pr-review-mention.yml v2-stable v2-stable ALIGNED ✓

    The corrected guard now surfaces two genuinely-stale pins that the old (equally-wrong) baseline was masking:

    stub committed (repo-template) expected status
    auto-rebase.yml @auto-rebase/stable (legacy) @auto-rebase/v2-stable DRIFTED
    dependency-audit.yml @dependency-audit/stable (legacy) @dependency-audit/v2-stable DRIFTED

    This is real drift, not a guard error: repo-template still pins these two to the frozen legacy channel. Turning the guard fully green requires a forward repin of those two files in repo-template to v2-stable — the same standards-ward move as d5a79417 for dev-lead — not a re-seed back to legacy. That is a separate cross-repo change (this task does not push to other repos); recommend a follow-up PR on petry-projects/repo-template.

    AC #5 — consumer repos carrying legacy <name>/stable pins

    Seeded consumer artifact (petry-projects/repo-template) — live pin audit:

    • auto-rebase.yml → @auto-rebase/stable (legacy)
    • dependency-audit.yml → @dependency-audit/stable (legacy)
    • all other caller stubs already major-scoped.

    Live workflow files elsewhere still on a legacy pin (dogfood stubs in this repo, distinct from the seeded artifact — repin decision separate):

    • petry-projects/.github-private/.github/workflows/agent-shield.yml → @agent-shield/stable
    • petry-projects/.github-private/.github/workflows/dev-lead.yml → @dev-lead/stable

    (Remaining code-search hits are tests/docs/fixtures, not live caller stubs.)

    AC #6 — are the legacy <name>/stable tags still promoted?

    No — they are effectively dead. scripts/cut-release.sh only cuts immutable <agent>/vX.Y.Z tags and moves the major-scoped <agent>/v<MAJOR>-<tier> channel (cut-release.sh header :5-6,26); the non-major-scoped <name>/stable tag is not in its channel-move model. Live tag SHAs confirm the legacy channels are frozen behind their major-scoped counterparts:

    namespace <name>/stable <name>/v<MAJOR>-stable
    agent-shield b7e6b67 837cee9 DIFFERENT (legacy frozen)
    auto-rebase 1a186e9 837cee9 DIFFERENT (legacy frozen)
    dependency-audit 1a186e9 837cee9 DIFFERENT (legacy frozen)
    dependabot-automerge b7e6b67 b7e6b67 same (coincidental; not re-promoted since split)
    dev-lead 6d36231 6d36231 same (coincidental)

    Blast radius (per the Dev Note): any consumer seeded from the old table onto <name>/stable is pinned to a frozen channel and silently stops receiving promotions. Both dev-lead/stable and dev-lead/v1-stable still exist as live tags (currently the same commit), so the sanctioned mutable-ref exception namespaces in AGENTS.md cover both forms — but only the v<MAJOR>- forms are advanced going forward.

    Notes

  5. added a commit that references this issue on Aug 2, 2026
  6. don-petry commented on Aug 3, 2026

    @don-petry
    CollaboratorAuthor

    Scope extension (maintainer decision) — pin the standards fetch, and let compliance accept N-1

    Folding the template-drift non-determinism into this issue, per the maintainer.

    Decision:

    1. seed-repo-template.sh fetches standards at the latest published stable version, not the live default branch.
    2. The compliance/drift check accepts N-1 — the current published version or the one before it — so a standards promotion does not instantly fail every consumer during propagation.

    The defect being fixed

    scripts/seed-repo-template.sh:116 fetches unpinned:

    gh api "repos/${STANDARDS_REPO}/contents/${path}" --jq '.content'   # no ?ref=

    So the "expected" baseline is whatever petry-projects/.github has on its default branch at the moment of execution. The same commit therefore passes or fails depending purely on when the check runs. Demonstrated today: PR #1446's template-drift expected blob 3e2daee1f7f8 at 01:58Z; regenerating the identical SHA locally after standards moved at 02:10Z (cff381f6) produced 569270be4153. Neither is wrong — the target moved.

    ⚠️ Blocking prerequisite — do not pin to any existing tag

    I checked every candidate ref, and none currently carries the corrected content:

    candidate ref standards/workflows/dev-lead.yml
    v2 (repo-level, 2026-05-19) file absent — predates the standards/workflows/ layout entirely
    v1 (repo-level, 2026-05-13) file absent
    pr-review-mention/v2-stable @dev-lead/stable ← legacy
    feature-ideation/v1-stable @dev-lead/stable ← legacy
    initiative-planner/v1-stable @dev-lead/stable ← legacy
    pr-auto-review/v1-stable file absent
    default HEAD @dev-lead/v1-stable ✅ (the only correct one)

    Pinning to any published tag today would reintroduce the exact pre-#1184 legacy pins this issue just fixed. The repo-level v1/v2 tags are stale and predate the layout; the per-reusable channel tags version reusables, not the standards/ corpus, and happen to point at commits from before the July channel migration.

    So there is currently no published version of standards/ as a corpus — that has to be created before the pin can be adopted. Implementing "pin to latest published stable" without it would silently regress the fix.

    Required sequencing

    1. Establish a publication scheme for standards/ in petry-projects/.github — a corpus-level moving channel (e.g. standards/v<MAJOR>-stable) distinct from the per-reusable channels, cut from a commit that contains the corrected major-scoped pins.
    2. Then teach seed-repo-template.sh to fetch at that ref (STANDARDS_REF, defaulting to the published stable channel; STANDARDS_DIR local override retained for tests).
    3. Then teach the drift check to accept N or N-1.

    Steps 2 and 3 are in this repo; step 1 is a cross-repo prerequisite in petry-projects/.github — the same standards-first ordering as #1435's original constraint and #1425's persona-schema dependency.

    Updated acceptance criteria

    1. seed-repo-template.sh resolves standards content at an explicit ref (STANDARDS_REF), defaulting to the published stable channel — never an unpinned default-branch read. The resolved ref is logged, and recorded in the drift report so a mismatch is explainable rather than mysterious.
    2. The drift check treats a stub as ALIGNED if it matches the emission at either the current published version or the immediately preceding one (N-1), and says which one it matched. Matching N-1 is reported as a visible notice (propagation pending), not silently.
    3. Neither N nor N-1 may resolve to a ref carrying pre-F2: cut-release.sh learns v<major>-<tier> channels [#657] #1184 legacy channel pins — a guard or test asserts the resolved standards content uses major-scoped <name>/v<MAJOR>-<tier> refs, so this issue's fix cannot be undone by a pin.
    4. The prerequisite in step 1 is either completed or explicitly tracked before ACs 7–8 are implemented; if it is not yet available, the fetch stays on HEAD and logs the resolved commit SHA so runs remain explainable in the meantime.

    AC #10 matters: it means this work delivers value (explainability) even if the cross-repo publication scheme lands later.

  7. don-petry commented on Aug 3, 2026

    @don-petry
    CollaboratorAuthor

    The scope extension above (pin the standards fetch to a published stable version; compliance accepts N-1) is carried in #1448, since this issue had already shipped as #1441. ACs there are numbered 7–10 to continue this issue's sequence.

    Flagging the key constraint again because it inverts the obvious implementation: no currently-published ref carries the corrected pins. v1/v2 predate the standards/workflows/ layout (files absent), and every per-reusable channel tag points at a pre-#1184 commit carrying @dev-lead/stable. Pinning to any of them today would undo exactly what this issue fixed. A corpus-level published version of standards/ has to exist first.

  8. added 14 commits that reference this issue on Aug 3, 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

    bugBug reportsdev-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