Skip to content

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

Closed

Description

@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.

Activity

  1. don-petry commented on Jul 22, 2026

    @don-petry
    ContributorAuthor

    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

  2. don-petry commented on Jul 22, 2026

    @don-petry
    ContributorAuthor

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

    @don-petry
    ContributorAuthor

    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.

    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.

  4. added
    dev-leadFor dev-lead agent pickup
    and removed
    dev-leadFor dev-lead agent pickup
    on Jul 22, 2026
  5. don-petry commented on Jul 22, 2026

    @don-petry
    ContributorAuthor

    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

  6. don-petry commented on Jul 22, 2026

    @don-petry
    ContributorAuthor

    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.

  7. don-petry commented on Jul 22, 2026

    @don-petry
    ContributorAuthor

    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.

    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.

  8. don-petry commented on Sep 1, 2026

    @don-petry
    ContributorAuthor

    Closing — cosmetic, and the functional state it describes is now verified correct

    This issue (self-labelled cosmetic in its own title) reported that a deployed stub's comment reads "pinned to the moving <agent>/v1-stable channel" while the actual pin is the repo's ring tier — e.g. .github → v1-ring0, .github-private → v1-next.

    The issue itself states the pin is functionally correct; only generic template boilerplate in the comment is stale. That assessment now has live confirmation: the pinned-version-report run 33409266607 (2026-08-31) resolved 92 fleet pins and found 90 compliant, with the only two exceptions being .github-private's deliberate stable pin for self-review duty (the SC2 property, now test-guarded by .github-private#1624).

    So the thing that could actually break — the pin — is verified right across the fleet, and what remains is a comment string. Closing rather than leaving it on needs-human-review, where it competes for attention with live defects. If stub comments are worth templating per ring tier, that belongs in the stub-generation path as an enhancement, not as a human-gated bug.

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 pickupdev-lead:needs-humandev-lead could not complete this issue; needs human attention

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions