[#850] driver should match the stub comment tier to the pinned ring tier (cosmetic)

[don-petry]

On ring/canary consumers the deployed stub comment reads the generic 'pinned to the moving /v1-stable channel' while the actual pin is the repo's ring tier (e.g. bmad → @dev-lead/v1-ring1, .github → v1-ring0, .github-private → v1-next). The PIN is functionally correct; only the comment tier is stale (generic template boilerplate). Fix: when the driver re-pins to a ring tier, update the comment's tier token to match (or make the template comment tier-agnostic). Cosmetic/doc-consistency, non-blocking. Surfaced on bmad#411/qodo during #857.

[don-petry]

Dev-Lead Implementation Plan

Issue: #883 — [#850] driver should match the stub comment tier to the pinned ring tier (cosmetic)

Scope

When the deploy driver re-pins a ring-managed stub to the repo's ring tier, it currently rewrites only the uses:/agent_ref: refs — leaving comment references to the generic <agent>/v1-stable channel stale. Extend ring_repin_uses to also rewrite the agent's channel token wherever it appears in comment lines, so the comment tier matches the actual pin.

Implementation Checklist

• scripts/lib/ring-pins.sh — extend ring_repin_uses to rewrite ${base}/(v<M>-)?<tier> tokens on comment lines to the new ref (scoped to this agent's base; English words like "next"/"stable" not preceded by <base>/ are untouched)

Tests to Write

• test/scripts/lib/ring-pins.bats — re-pin rewrites a channel token inside a comment line to the new tier
• test/scripts/lib/ring-pins.bats — re-pin leaves non-channel comment text (URL anchors, the bare English word "next", other agents' tokens) untouched
• test/scripts/lib/ring-pins.bats — a full dev-lead stub comment block (dev-lead/v1-stable → dev-lead/v1-ring1) is updated in both the comment and the uses:/agent_ref: lines

Test Command

bats test/scripts/lib/ring-pins.bats (full lib suite); repo lint: bash .dev-lead/scripts/dev-lead-lint.sh

[don-petry]

Dev-Lead: Implementation Complete

Plan Execution

• Extended ring_repin_uses in scripts/lib/ring-pins.sh to sync the comment tier token to the pinned ring tier
• Added 3 TDD unit tests to test/scripts/lib/ring-pins.bats (red → green)
• Verified against the real standards/workflows/dev-lead.yml template (integration sanity)

Root Cause

The deploy driver re-pins ring-managed stubs via ring_repin_uses, which rewrote only the uses: and agent_ref: refs. The stub's boilerplate comment block (e.g. dev-lead.yml lines 59/61: "Pinned to the moving dev-lead/v1-stable channel tag") kept the generic stable token, so on a ring/canary consumer the comment tier disagreed with the actual pin (functionally correct, cosmetically stale).

Fix

Added a third sed expression, scoped to comment lines only (/^[[:space:]]*#/), that rewrites THIS agent's channel token <base>/(v<M>-)?<tier> to the new ref. Scoping to ${base}/ guarantees the English words next/stable, URL anchors like …--the-stable-channel, and other agents' tokens are never touched. Idempotent for stable-tier repos (token replaced with itself).

Real-template verification (dev-lead/v1-ring1)

    # Pinned to the moving dev-lead/v1-ring1 channel tag, not @main, so a broken
    ...
    # dependency). Promotion is done by moving the dev-lead/v1-ring1 tag centrally; this
    uses: ...dev-lead-reusable.yml@dev-lead/v1-ring1  # NOSONAR(githubactions:S7637) ...
      agent_ref: dev-lead/v1-ring1
Remaining stale 'dev-lead/v1-stable' tokens: 0

Test Results (bats test/scripts/lib/ring-pins.bats)

1..24
ok 1 ring_tier_for_repo maps each tier
ok 2 ring_is_ring_reusable recognises the ring set (incl. dev-lead)
ok 3 ring_canonical_ref: feature-ideation and pr-auto-review resolve to tier channels (#606)
ok 4 ring_canonical_ref is the repo's tier channel
ok 5 ring_canonical_ref: major-aware form yields <agent>/v<major>-<tier> (#657 F3)
ok 6 ring_pinned_major: extracts M from v<M>-<tier>, empty for bare tier (#657 F3)
ok 7 ring_accepted_refs: canonical first, then the ring-channel grace
ok 8 ring_legacy_csv excludes the canonical and comma-joins the ring channels
ok 9 ring_highest_major: picks the MAJOR of the highest strict semver
ok 10 ring_highest_major: ignores non-semver tokens; empty when none valid
ok 11 ring_highest_channel_major: picks the highest v<M>-<tier> channel token
ok 12 ring_highest_channel_major: ignores RELEASE semver; empty when no channel token (#870)
ok 13 ring_repin_uses: rewrites the reusable uses: ref, preserving the trailing comment
ok 14 ring_repin_uses: also rewrites a matching agent_ref (dev-lead stub)
ok 15 ring_repin_uses: rewrites a stale channel token inside a comment line to the new tier (#883)
ok 16 ring_repin_uses: leaves non-channel comment text (English words, URLs, other agents) untouched (#883)
ok 17 ring_repin_uses: full dev-lead comment block re-pins comment + uses + agent_ref (#883)
ok 18 ring_vform_tier_aligned: true only for the repo's tier v-form (any major)
ok 19 ring_stub_selfhosts: true for a local ./ self-host ref
ok 20 ring_stub_selfhosts: false for a channel-pinned consumer ref
ok 21 ring_stub_selfhosts: false when the stub does not reference the reusable at all
ok 22 ring_host_current_channel_major: picks v1 for dev-lead despite a v14 release tag (#870)
ok 23 ring_host_current_channel_major: empty when only release tags exist (#870)
ok 24 ring_tag_exists: true only for a ref present on the host (#870)

Files Changed

• scripts/lib/ring-pins.sh: ring_repin_uses now also re-pins the agent's channel token on comment lines.
• test/scripts/lib/ring-pins.bats: +3 tests (comment re-pin, no-over-match negative case, full dev-lead block).

Notes

• Repo lint (bash .dev-lead/scripts/dev-lead-lint.sh) passes.
• Full ring-pins.bats + deploy-standard-workflows/ + compliance-audit/ suites pass.
• Pre-existing, unrelated: test/scripts/lib/gitignore-baseline.bats tests 223–225 fail only in a single combined 73-file bats process (cross-file state pollution); they pass in isolation and fail identically on a clean tree without this change. Not touched by this fix.
• TDD Phase 2 followed: the 3 new tests failed before the implementation and pass after.

[don-petry]

Dev-Lead: cannot implement issue #883 — needs human attention

A stage timed out (exit 124) while implementing this issue. A timeout is treated as a first-class, non-retryable condition — retrying with the same budget would just time out again — so this escalates for human review on the first occurrence instead of wasting a same-budget retry.

• Cause: timeout
• Tier: action
• Elapsed: 2100s
• Budget: 2100s
• Run: https://github.com/petry-projects/.github/actions/runs/29945694264

This hit the max action budget. Split this issue into smaller, independently-implementable pieces, or raise vars.ACTION_TIMEOUT_SEC, then re-apply the dev-lead label.

Note: the engine had produced changes before the timeout. They were on branch dev-lead/issue-883-20260722-1813 on the runner and were not pushed, so they are not recoverable from this run (the runner is ephemeral). The redacted session snippet below shows what it attempted — treat it as context, not restorable output. Re-apply dev-lead after splitting the issue or raising the budget to regenerate the work.

[don-petry]

Dev-Lead Implementation Plan

Issue: #883 — [#850] driver should match the stub comment tier to the pinned ring tier (cosmetic)

Scope

When the driver re-pins a caller stub to a ring/canary tier, sync the stub's descriptive comment tier token (e.g. dev-lead/v1-stable) to match the new pinned ref, so the comment no longer reads a stale generic tier.

Root Cause

ring_repin_uses (scripts/lib/ring-pins.sh) is the single chokepoint for all re-pinning (deploy-standard-workflows.sh:537). It rewrites only the uses: and agent_ref: lines, leaving comment prose like # Pinned to the moving dev-lead/v1-stable channel tag untouched — so on a ring1 repo the pin is v1-ring1 but the comment still says v1-stable. The compliance audit and surface-drift guard never inspect comments, so this is purely cosmetic and safe to change.

Implementation Checklist

• scripts/lib/ring-pins.sh — extend ring_repin_uses to also rewrite channel tier tokens (<base>/[v<M>-]<tier>) on comment lines to the new ref

Tests to Write

• test/scripts/lib/ring-pins.bats — comment tier token is synced to the new ref on re-pin
• test/scripts/lib/ring-pins.bats — multiple comment occurrences all synced; non-comment behavior (uses/agent_ref) unchanged; unrelated comment prose (URL fragments) untouched

Test Command

./node_modules/.bin/bats test/scripts/lib/ring-pins.bats

[don-petry]

Dev-Lead: Implementation Complete

Plan Execution

• Root-caused the stale comment tier to ring_repin_uses (scripts/lib/ring-pins.sh) — the single re-pin chokepoint (deploy-standard-workflows.sh:537) that rewrote only uses:/agent_ref: and left descriptive comment tier tokens untouched
• Wrote failing tests first (TDD), then implemented
• Extended ring_repin_uses to sync <base>/[v<M>-]<tier> tokens on comment lines to the new ref
• Full bats suite + required dev-lead-lint.sh (shellcheck + frontmatter) pass
• Rubber-duck review of the diff

Approach

ring_repin_uses now applies a third sed expression, scoped to comment lines only (/^[[:space:]]*#/), that rewrites any <base>/(v<M>-)?<tier> channel token to <newref>. Because it fires from the one function every re-pin path routes through, both verbatim-template deploys and in-place re-pins get a comment that matches the actual pin (e.g. a ring1 repo's # Pinned to the moving dev-lead/v1-stable channel tag becomes .../v1-ring1). Comment-line scoping leaves doc-link fragments like --the-stable-channel (no <base>/ prefix) intact. The compliance surface-drift and agent_ref/uses channel-sync audits never inspect comments, so this is purely cosmetic and introduces no drift.

Test Results

# ./node_modules/.bin/bats test/scripts/lib/ring-pins.bats  → 25/25 ok
# ./node_modules/.bin/bats test/scripts/lib/ test/scripts/compliance-audit/ test/scripts/deploy-standard-workflows/  → 286/286 ok
# bash .dev-lead/scripts/dev-lead-lint.sh  → all checks passed (exit 0)

New/updated ring-pins tests:
ok ring_repin_uses: syncs a comment's channel tier token to the new ref (#883)
ok ring_repin_uses: syncs every comment occurrence of the tier token (#883)
ok ring_repin_uses: syncs a bare-tier comment token (no v-major) (#883)
ok ring_repin_uses: leaves unrelated comment prose (URL tier fragments) untouched (#883)

Full recursive suite: 1094 ok. The only 3 failures are in test/scripts/compliance-remediate/gitignore-baseline.bats, which are pre-existing and unrelated — they fail identically with my changes stashed (environment/git-setup dependent, not touched by this change).

Files Changed

• scripts/lib/ring-pins.sh: added a comment-line-scoped sed expression to ring_repin_uses so re-pins sync the descriptive comment tier token to the pinned ref
• test/scripts/lib/ring-pins.bats: 4 new tests covering v-form sync, multi-occurrence sync, bare-tier sync, and the no-false-positive guard on doc-link fragments

Notes

Scoped to comments only; the uses:/agent_ref: rewrite behavior is unchanged. No template edits were needed — syncing at the driver covers both fresh copies and existing deployed stubs on the next sweep. Purely cosmetic/doc-consistency per the issue; no audit or behavior surface is affected.

[don-petry]

Dev-Lead: cannot implement issue #883 — needs human attention

A stage timed out (exit 124) while implementing this issue. A timeout is treated as a first-class, non-retryable condition — retrying with the same budget would just time out again — so this escalates for human review on the first occurrence instead of wasting a same-budget retry.

• Cause: timeout
• Tier: action
• Elapsed: 2101s
• Budget: 2100s
• Run: https://github.com/petry-projects/.github/actions/runs/29957330475

This hit the max action budget. Split this issue into smaller, independently-implementable pieces, or raise vars.ACTION_TIMEOUT_SEC, then re-apply the dev-lead label.

Note: the engine had produced changes before the timeout. They were on branch dev-lead/issue-883-20260722-2058 on the runner and were not pushed, so they are not recoverable from this run (the runner is ephemeral). The redacted session snippet below shows what it attempted — treat it as context, not restorable output. Re-apply dev-lead after splitting the issue or raising the budget to regenerate the work.