feat: implement issue #1297 — Synced stubs in ring repos carry a header naming v1-stable above a uses: line pinned to their ring — bots flag it and agents edit the stub to match

scripts/deploy-standard-workflows.sh

@@ -433,6 +433,12 @@ template_requires_s7635_marker() {
   grep -qE '^[[:space:]]*secrets:[[:space:]]+inherit([[:space:]]|$)' "$1"
 }
 
+# stub_has_inherited_secrets — 0 if the stub content on stdin carries a real
+# `secrets: inherit` YAML line.
+stub_has_inherited_secrets() {
+  grep -qE '^[[:space:]]*secrets:[[:space:]]+inherit([[:space:]]|$)'
+}
+
 # stub_has_s7635_marker — 0 if the stub content on stdin carries the
 # `# NOSONAR(githubactions:S7635)` marker on a real `secrets: inherit` line.
 stub_has_s7635_marker() {
@@ -601,6 +607,70 @@ merge_guarded_surfaces() {
   return 0
 }
 
+# stub_has_stale_stable_header <existing_content> <template> <repo> -> 0 if the stub carries a
+# comment naming its agent's stable channel (`<base>/stable`, `<base>/v<M>-stable`,
+# `<base> stable channel`) that the template no longer carries (#1297). Such a header
+# contradicts a ring pin; the pin alone is compliant, so without this check the sweep
+# would never ship the comment-only header fix to existing ring repos. In ring repos,
+# even a currently stable-pinned stub must migrate its header because the in-place
+# repin will change the pin to ring, leaving the header contradictory.
+stub_has_stale_stable_header() {
+  local existing="$1" template="$2" repo="$3" base re tier
+  base="$(reusable_base_of "$template")"
+  [[ -n "$base" ]] || return 1
+  re="^[[:space:]]*#.*(${base}/(v[0-9]+-)?stable|${base} stable channel)"
+  grep -qE "$re" <<< "$existing" || return 1
+  # A stable-pinned stub's header agrees with its pin, BUT only when the repo is
+  # stable-tier. In ring-managed repos, a stable-pinned stub is itself an anomaly
+  # that the repin will fix; the header must migrate too, so don't exempt in ring.
+  if ring_is_ring_reusable "$base" && [[ -n "$repo" ]]; then
+    tier="$(ring_tier_for_repo "$base" "$repo" 2>/dev/null)" || tier=""
+    # Ring-managed repo with a tier: the stub should be ring-pinned, so the header
+    # is stale regardless of the current pin.
+    if [[ -n "$tier" ]] && [[ "$tier" != "stable" ]]; then
+      # The template may still carry the stable wording; ring renders (ring_repin_uses)
+      # and the header cleanup neutralize it, so the template never exempts a ring repo.
+      return 0  # Flag as stale
+    fi
+  fi
+  ! grep -qE "$re" "$template" || return 1
+  # Non-ring reusable or stable-tier repo: apply the exemption (don't flag if
+  # the stub is stable-pinned, since the header agrees with the pin).
+  ! grep -qE "^[[:space:]]*uses:.*@${base}/(v[0-9]+-)?stable([[:space:]]|\$)" <<< "$existing"
+}
+
+# strip_stale_stable_header <base> [<template>] -> stdin minus the stale stable-channel
+# header. With <template>, the stub's whole leading comment block (everything above the
+# first top-level YAML key) is replaced by the template's canonical, tier-neutral header,
+# so a multiline legacy bullet is never left half-deleted. The body is kept verbatim, so
+# per-repo edits (e.g. workflow_run.workflows) survive and the next sweep sees no stale
+# header (#1297). Without <template>, only the lines naming the stable channel are dropped.
+strip_stale_stable_header() {
+  local base="$1" template="${2:-}"
+  if [[ -n "$template" && -r "$template" ]]; then
+    # Body comment blocks (consecutive comment lines) that name the stable channel are
+    # dropped whole too, so a legacy `# Pinned to the moving ... stable channel` block under
+    # `jobs:` does not survive and keep the detector true forever.
+    awk -v tpl="$template" -v base="$base" -v re="^[[:space:]]*#.*(${base}/(v[0-9]+-)?stable|${base} stable channel)" '
+      BEGIN {
+        while ((getline l < tpl) > 0) { if (l ~ /^[^#[:space:]]/) break; hdr = hdr l "\n" }
+        # The template header may still name the stable channel; render it tier-neutral
+        # (same wording as ring_repin_uses) so cleanup never reinstalls it.
+        gsub(base "/(v[0-9]+-)?stable", base "/<tier>", hdr)
+        gsub(base " stable channel", base "/<tier> channel", hdr)
+      }
+      function flush() { if (!stale) printf "%s", blk; blk = ""; stale = 0 }
+      !body && /^[^#[:space:]]/ { body = 1; printf "%s", hdr }
+      body && /^[[:space:]]*#/ { blk = blk $0 "\n"; if ($0 ~ re) stale = 1; next }
+      body { flush(); print; next }
+      END { if (body) flush() }
+    '
+    return 0
+  fi
+  grep -vE "^[[:space:]]*#.*(${base}/(v[0-9]+-)?stable|${base} stable channel)" || true
+}
+
+
 # is_already_compliant <existing_content> <template> <repo> -> 0 if the deployed
 # stub needs no re-deploy. A stub is compliant only when it is BOTH pin-compliant
 # (is_pin_compliant, below) AND — when its template carries a real `secrets: inherit`
@@ -615,7 +685,8 @@ merge_guarded_surfaces() {
 # rendered at the repo's tier channel (stub_body_matches_template): its callers
 # predate the template and carry per-repo edits, which are drift. So must every stub
 # in a FULL_BODY_COMPARE_REPOS repo (repo-template, #1285) other than a
-# BODY_PRESERVING_WORKFLOWS one, whose per-repo body is never re-synced.
+# BODY_PRESERVING_WORKFLOWS or PRESENT_ONLY_WORKFLOWS one, whose per-repo body is
+# re-pinned in place and never re-synced from the template.
 #
 # A pin-correct stub whose guarded `on:` / `permissions:` / `concurrency:` surface
 # differs from the template is ALSO drift (#1236): the audit flags it
@@ -634,6 +705,7 @@ is_already_compliant() {
      && ! stub_has_s7635_marker <<< "$existing_content"; then
     return 1
   fi
+  stub_has_stale_stable_header "$existing_content" "$template" "$repo" && return 1
   if is_replace_if_present_workflow "$workflow" \
      || { is_full_body_compare_repo "$repo" && ! is_body_preserving_workflow "$workflow"; }; then
     stub_body_matches_template "$existing_content" "$template" "$repo" || return 1
@@ -928,6 +1000,31 @@ deploy_repo() {
       fi
     fi
 
+    # Stale stable-channel header (#1297): migrate by editing the stub's OWN body, never
+    # by redeploying the template (that would reset per-repo edits such as
+    # pr-auto-review's workflow_run.workflows). Full-body-compared stubs are exempt —
+    # their drift is already resolved by a template redeploy.
+    if [[ "$DRY_RUN" != "true" && -n "$existing_sha" ]] \
+       && stub_has_stale_stable_header "$existing_content" "$template" "$repo"; then
+      base="$(reusable_base_of "$template")"
+      if [[ "$repin_source" == "$template" ]] && ! is_replace_if_present_workflow "$workflow" \
+         && ! { is_full_body_compare_repo "$repo" && ! is_body_preserving_workflow "$workflow"; } \
+         && is_pin_compliant "$existing_content" "$template" "$repo" \
+         && ! stub_any_surface_drift "$workflow" "$(< "$template")" "$existing_content" \
+         && { ! template_requires_s7635_marker "$template" || stub_has_inherited_secrets < <(printf '%s\n' "$existing_content"); }; then
+        # Keep the existing body only when its guarded surfaces are compliant and it
+        # still forwards `secrets: inherit` where the template does (the marker
+        # injection below cannot add a missing line); a stub with trigger/permission/
+        # secrets drift falls back to the canonical template.
+        repin_source="$(mktemp)"; _TMPFILES+=("$repin_source")
+        printf '%s\n' "$existing_content" > "$repin_source"
+      fi
+      if [[ "$repin_source" != "$template" ]]; then
+        strip_stale_stable_header "$base" "$template" < "$repin_source" > "$repin_source.stripped"
+        mv "$repin_source.stripped" "$repin_source"
+      fi
+    fi
+
     # When repin_source is a copy of existing_content (meta-repo consumer or body-
     # preserving repin-in-place) and the template requires the S7635 marker but the
     # copy lacks it, inject the marker now. Without this, the deployed stub would

scripts/lib/ring-pins.sh

@@ -455,11 +455,22 @@ ring_tag_exists() {
 # is re-pinned alongside `uses:` here. This only re-pins the VALUE of an input the
 # stub already forwards (never adds/forwards a new one), so it never introduces the
 # undeclared-input channel-skew defect (#1052).
+# When <newref> is not a stable channel, comment lines naming this agent's stable
+# channel (`<base>/v<M>-stable`, `<base> stable channel`) are rendered tier-neutral
+# (`<base>/<tier>`), so a header never contradicts the ring pin even while the
+# template still carries the stable wording (#1297).
 ring_repin_uses() {
-  local base="$1" newref="$2" file
+  local base="$1" newref="$2" file neutral=()
   file="$(ring_reusable_file "$base")"
   file="${file//./\\.}"
+  if [[ ! "$newref" =~ stable$ ]]; then
+    neutral=(
+      -e "/^[[:space:]]*#/s#${base}/(v[0-9]+-)?stable#${base}/<tier>#g"
+      -e "/^[[:space:]]*#/s#${base} stable channel#${base}/<tier> channel#g"
+    )
+  fi
   sed -E \
+    ${neutral[@]+"${neutral[@]}"} \
     -e "s#^([[:space:]]*uses:[[:space:]]*combsmith/[^@[:space:]]*/${file})@[^[:space:]]+#\1@${newref}#" \
     -e "s#^([[:space:]]*agent_ref:[[:space:]]*[\"']?)${base}/[^\"'[:space:]]+#\1${newref}#" \
     -e "s#^([[:space:]]*checkout_ref:[[:space:]]*[\"']?)${base}/[^\"'[:space:]]+#\1${newref}#"

standards/workflows/add-to-project.yml

@@ -7,7 +7,7 @@
 #   • This file is a THIN CALLER STUB. All noise-gate / reconcile logic lives
 #     in the reusable workflow above.
 #   • You MAY change: nothing in normal use. The `uses:` ref and `agent_ref`
-#     are pinned to the `add-to-project/v1-stable` channel and move with it — do
+#     are pinned to the `add-to-project/<tier>` channel and move with it — do
 #     not change them to `@main` or a SHA (see ci-standards.md → Reusable
 #     workflow versioning).
 #   • You MUST NOT change: trigger events, the concurrency group, or the

standards/workflows/idea-enhancer.yml

@@ -7,7 +7,7 @@
 #   • This file is a THIN CALLER STUB. All enhancement-dispatch logic (including
 #     the Ideas-category / non-bot guard) lives in the reusable above.
 #   • You MUST NOT change: the `uses:` ref — it is pinned to the
-#     `idea-enhancer/v1-stable` channel, a moving tag advanced centrally. Never
+#     `idea-enhancer/<tier>` channel, a moving tag advanced centrally. Never
 #     repoint it to `@main`, a SHA, or a frozen `@vX`. Do not change the trigger
 #     events or the `secrets:` block.
 #   • You MAY change: the cron schedule if the weekly cadence doesn't suit.

standards/workflows/idea-triage.yml

@@ -7,7 +7,7 @@
 #   • This file is a THIN CALLER STUB. All triage-dispatch logic lives in the
 #     reusable above.
 #   • You MUST NOT change: the `uses:` ref — it is pinned to the
-#     `idea-triage/v1-stable` channel, a moving tag advanced centrally. Never
+#     `idea-triage/<tier>` channel, a moving tag advanced centrally. Never
 #     repoint it to `@main`, a SHA, or a frozen `@vX`. Do not change the
 #     `secrets:` block.
 #   • You MAY change: the cron schedule if the weekly cadence doesn't suit.

standards/workflows/initiative-planner.yml

@@ -8,7 +8,7 @@
 #     `idea:approved` gate, the trusted-actor check, and the cross-repo dispatch
 #     to the central BMAD Scrum Master planner) lives in the reusable above.
 #   • You MUST NOT change: the `uses:` ref — it is pinned to the
-#     `initiative-planner/v1-stable` channel, a moving tag advanced centrally.
+#     `initiative-planner/<tier>` channel, a moving tag advanced centrally.
 #     Never repoint it to `@main`, a SHA, or a frozen `@vX` (see
 #     ci-standards.md → Reusable workflow versioning). Also do not change the
 #     trigger events or the `secrets:` block.

standards/workflows/persona-mention.yml

@@ -8,7 +8,7 @@
 #     workflow above, and every per-persona decision lives in that persona's
 #     manifest — not here and not in the reusable.
 #   • You MUST NOT change: the `uses:` ref — it is pinned to the
-#     `persona-mention/v1-stable` channel, a moving tag advanced centrally.
+#     `persona-mention/<tier>` channel, a moving tag advanced centrally.
 #     Never repoint it to `@main`, a SHA, or a frozen `@vX.Y.Z` (see
 #     ci-standards.md → Reusable workflow versioning). Also do not change the
 #     trigger events or the job-level `permissions:` block — reusable workflows
@@ -74,7 +74,7 @@
   persona-mention:
     permissions:
       contents: read        # the reusable checks out its tooling repo — required,
                             # or the call fails at startup (a reusable is granted
                             # no more than the caller; persona-standards.md §5)
       issues: read
       pull-requests: read

standards/workflows/pr-auto-review.yml

@@ -8,7 +8,7 @@
 #     reusable workflow above.
 #   • You MAY change: the workflow name(s) in `workflow_run.workflows` to match
 #     your repository's CI workflow name(s).
-#   • You MUST NOT change: the `@pr-auto-review/v1-stable` channel in the `uses:`
+#   • You MUST NOT change: the `@pr-auto-review/<tier>` channel in the `uses:`
 #     line — this reusable is on the org-wide moving-channel model (rollout and
 #     rollback are a single central tag move; a frozen `@vN`/`@<sha>` pin is
 #     rejected by the compliance audit). Nor the trigger event types or the

standards/workflows/pr-review.yml

@@ -9,7 +9,7 @@
 #     above, including concurrency (per PR + head SHA, never cancelling an
 #     in-flight review), the check_suite-without-a-PR skip, and reading
 #     `client_payload.pr_url` from repository_dispatch.
-#   • You MUST NOT change: the `@pr-review/v1-stable` channel in the `uses:`
+#   • You MUST NOT change: the `@pr-review/<tier>` channel in the `uses:`
 #     line or the matching `agent_ref` — both are re-pinned in lockstep to this
 #     repo's canary-ring tier by the standards sweep. Nor the workflow `name:`,
 #     the job id `review` (check names depend on both), the trigger event types,

test/scripts/deploy-standard-workflows/dry-run.bats

@@ -75,7 +75,8 @@ stub_pinning() {  # <ref> → base64 of the auto-rebase template re-pinned to <r
   # and the surface-drift check (#1236) stays clean.
   local body
   body="$(sed -E "s|(auto-rebase-reusable\.yml)@[^[:space:]]+|\1@$1|" \
-    "${REPO_ROOT}/standards/workflows/auto-rebase.yml")"
+    "${REPO_ROOT}/standards/workflows/auto-rebase.yml" \
+    | bash -c 'source "$1"; ring_repin_uses "$2" "$3"' _ "$SCRIPT" auto-rebase "${1%% *}")"
   base64 -w 0 <<<"$body" 2>/dev/null || base64 -b 0 <<<"$body"
 }
 

test/scripts/deploy-standard-workflows/emit-vform.bats

@@ -84,7 +84,8 @@ stub_pinning() {  # <ref> → base64 of the auto-rebase template re-pinned to <r
   # concurrency: surfaces match and the surface-drift check (#1236) stays clean.
   local body
   body="$(sed -E "s|(auto-rebase-reusable\.yml)@[^[:space:]]+|\1@$1|" \
-    "${REPO_ROOT}/standards/workflows/auto-rebase.yml")"
+    "${REPO_ROOT}/standards/workflows/auto-rebase.yml" \
+    | bash -c 'source "$1"; ring_repin_uses "$2" "$3"' _ "$SCRIPT" auto-rebase "$1")"
   base64 -w 0 <<<"$body" 2>/dev/null || base64 -b 0 <<<"$body"
 }
 
@@ -112,7 +113,8 @@ devlead_stub_pinning_with_marker() {  # <ref> → base64 of the dev-lead templat
   local body
   body="$(sed -E -e "s|(dev-lead-reusable\.yml)@[^[:space:]]+|\1@$1|" \
     -e "s|^([[:space:]]*agent_ref:[[:space:]]*).*|\1$1|" \
-    "${REPO_ROOT}/standards/workflows/dev-lead.yml")"
+    "${REPO_ROOT}/standards/workflows/dev-lead.yml" \
+    | bash -c 'source "$1"; ring_repin_uses "$2" "$3"' _ "$SCRIPT" dev-lead "$1")"
   base64 -w 0 <<<"$body" 2>/dev/null || base64 -b 0 <<<"$body"
 }
 

test/scripts/deploy-standard-workflows/pr-review-replace-if-present.bats

@@ -63,7 +63,8 @@ STUB
 # The template rendered at <channel> — what a correctly deployed caller looks like:
 # only the two pin lines move; the header prose keeps the template's channel.
 rendered_at() {  # <channel>
-  sed -E "/^[[:space:]]*(uses|agent_ref):/s#pr-review/v1-stable#$1#" "$TEMPLATE"
+  sed -E "/^[[:space:]]*(uses|agent_ref):/s#pr-review/v1-stable#$1#" "$TEMPLATE" \
+    | bash -c 'source "$1"; ring_repin_uses pr-review "$2"' _ "$SCRIPT" "$1"
 }
 
 # The legacy fleet caller shape (TalkTerm-like): bare pr-review/stable pin, an

test/scripts/deploy-standard-workflows/repo-template-full-body.bats

@@ -67,7 +67,8 @@ STUB
 
 # The template rendered at <channel> — only the reusable pin moves.
 rendered_at() {  # <channel>
-  sed -E "/^[[:space:]]*uses:/s#dependabot-rebase/v2-stable#$1#" "$TEMPLATE"
+  sed -E "/^[[:space:]]*uses:/s#dependabot-rebase/v2-stable#$1#" "$TEMPLATE" \
+    | bash -c 'source "$1"; ring_repin_uses dependabot-rebase "$2"' _ "$SCRIPT" "$1"
 }
 
 # The template at <channel> with a stale header comment — the #1075 shape: the