Skip to content

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

Closed

Description

@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

  1. 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.
  2. 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).
  3. 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.
  4. 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.
  5. 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.
  6. Enforcement flip. DEPRECATED becomes a failure as a separate, explicitly-called-out change after ACs 10–11 are complete.
  7. 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

References

Activity

  1. don-petry commented on Aug 18, 2026

    @don-petry
    CollaboratorAuthor

    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)

    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

  2. don-petry commented on Aug 18, 2026

    @don-petry
    CollaboratorAuthor

    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.

    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
    
    
  3. don-petry commented on Aug 18, 2026

    @don-petry
    CollaboratorAuthor

    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.

    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
    
    
  4. don-petry commented on Aug 18, 2026

    @don-petry
    CollaboratorAuthor

    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)

    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

  5. don-petry commented on Aug 18, 2026

    @don-petry
    CollaboratorAuthor

    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.
  6. don-petry commented on Aug 19, 2026

    @don-petry
    CollaboratorAuthor

    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

  7. don-petry commented on Aug 19, 2026

    @don-petry
    CollaboratorAuthor

    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.

    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.

  8. added
    dev-leadFor dev-lead agent pickup
    and removed
    dev-leadFor dev-lead agent pickup
    on Aug 20, 2026
  9. don-petry commented on Aug 20, 2026

    @don-petry
    CollaboratorAuthor
    Already working on this: an open PR exists for issue #1493.
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 pickupenhancementFeature requestsinitiativeEpic / initiative tracking issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions