Story (F): major-version boundary in the channel/ring model [#604]

[don-petry]

Part of the shim-identity epic #604 — Story F (major-version boundary). Filed from the 2026-07-10 plan review.

Gap

The version+ring model gates blast radius, not compatibility. Consumer-facing channels (<agent>/next, /ring0, /ring1, /stable) encode a repo's ring tier, not a semver major. Since #870, @vN pins are treated as drift, and immutable <agent>/vMAJOR.MINOR.PATCH tags exist only as rollback anchors that nothing pins to.

Consequence: a breaking (major) change to an agent, once promoted through the rings to stable, reaches every stable consumer with no opt-in gate. There is no @dev-lead/v1-stable vs @dev-lead/v2-stable separation, and nothing halts a major bump as it advances next → ring0 → ring1 → stable. The strategy accepts this implicitly rather than by decision.

Decision needed (pick one)

1. Major-scoped channels — introduce per-agent major-scoped channel tags (e.g. dev-lead/v2-stable) so a breaking release requires a deliberate consumer re-pin to opt in. Preserves "callers pin once" within a major; a major bump is the one sanctioned re-pin event. Cost: doubles channel count per agent; re-sync + drift tooling (ring-pins.sh, compliance-audit.sh, fleet_stub_drift.sh) must learn the vN- prefix.
2. Promotion gate at the major bump — keep single channels, but the canary-rollout engine halts a release flagged as a major (breaking) at the next → ring0 edge pending explicit human sign-off, instead of auto-advancing. Cheaper; needs a way to mark a release "major" (release note / label / tag metadata) and a gate in the promotion engine.
3. Accept and document — keep the channel-only model; add an explicit note to agentic-release-strategy.md that majors are not gated and consumers accept auto-flow to stable. No engineering.

Acceptance

• A decision is recorded in the release-strategy doc's decision log.
• If (1) or (2): the ring/drift tooling and the canary-rollout engine honor the chosen mechanism, with tests; a breaking change cannot silently reach stable consumers.
• If (3): the accepted trade-off is documented where the channel model is defined.

Notes

• Depends on nothing else in Epic: Enforce identical reusable-workflow shims across the fleet (full-file drift, not just pin) #604; can be decided independently. Sequence after Story (B): channel-ify feature-ideation + pr-auto-review [#604] #606/Story (D): full-file on:/permissions drift guard in compliance-audit [#604] #607 if it competes for attention — the identity gap (Story (D): full-file on:/permissions drift guard in compliance-audit [#604] #607) is the higher-value fix.
• Relevant surfaces: scripts/lib/ring-pins.sh, scripts/compliance-audit.sh, the canary-rollout engine (relocated to .github per Epic: relocate the canary-rollout engine + bootstrap into .github (org tooling consolidation) #613), .github-private/scripts/cut-release.sh, .github-private/docs/initiatives/agentic-release-strategy.md.

[don-petry]

Decision (2026-07-13): Option 1 — major-scoped channels.

A breaking (major) agent change must require a deliberate consumer re-pin to opt in. Recorded here + to be logged in .github-private/docs/initiatives/agentic-release-strategy.md.

Design — channel = major × tier

Channel tag naming: <agent>/v<MAJOR>-<tier> — e.g. dev-lead/v1-next, dev-lead/v1-ring0, dev-lead/v1-ring1, dev-lead/v1-stable, and independently dev-lead/v2-next … as a v2 soaks. Immutable release tags <agent>/vX.Y.Z unchanged (rollback anchors).

The key semantic shift: today ring_canonical_ref(agent, repo) = <agent>/<tier> — expected ref is a pure function of (agent, repo-tier). With major-scoping, the expected ref is <agent>/v<M>-<tier> where M is the major the consumer currently pins (its opt-in). Drift = "consumer is NOT on a valid v<M>-<tier> channel for its repo tier," NOT "consumer is on the wrong major." A consumer on v1-stable stays valid until IT re-pins to v2-stable; a v2 reaching its own v2-stable never touches a v1-stable consumer.

Per-agent current major: migration maps each agent's live <agent>/<tier> → <agent>/v<currentMajor>-<tier> (currentMajor from the agent's latest release: dev-lead=v1, pr-auto-review=v1, agent-shield=v2, etc. — read from <agent>/vX.Y.Z). The bare <agent>/<tier> channels are retired after consumers move.

Phased plan (each phase = its own PR, dev-lead + pr-review, serial where files overlap)

• F1 — Decision + design doc (.github-private/docs/initiatives/agentic-release-strategy.md): record the decision-log entry + the major×tier model + migration. (no engine change)
• F2 — cut-release.sh (.github-private): teach --channel to accept/emit v<major>-<tier>; derive <major> from the <version> arg; channel_ref gains the prefix. Add cut/promote for a fresh major line.
• F3 — ring-pins.sh (.github): ring_canonical_ref emits <agent>/v<M>-<tier>; new helper to read a consumer stub's currently-pinned major; drift becomes tier-match within the consumer's major. RING_REUSABLES unchanged (membership), the ref builder changes. Bats.
• F4 — canary-rollout engine (canary-rollout.sh + canary-rings.json): channel resolution + promote/autocut/promote-all operate on v<M>-<tier> tags; a candidate soaks within its major line; evaluate reports the major. Bats (gated by Canary-rollout Tests ci: add canary-rollout-tests.yml — enforce the engine's bats suite (CI gap from #613/#624) #685).
• F5 — audit + drift + live migration: compliance-audit.sh RING branch + fleet_stub_drift.sh/template_stub_drift.sh honor the prefix; migrate live channel tags (<agent>/<tier> → <agent>/v<M>-<tier>) via the App token; re-pin all consumer templates/stubs to @<agent>/v<M>-<tier>; retire bare-tier channels. Bats + fleet re-sync.

Acceptance (from #657)

• Decision recorded in the strategy doc's decision log ✔ (F1).
• Ring/drift tooling + the canary-rollout engine honor v<major>-<tier>, with tests; a breaking change cannot silently reach stable consumers — it lands on v<newMajor>-stable, which nothing pins to until a consumer opts in.

Sequencing

F1 → F2 → F3 → F4 → F5, serial (each builds on the prior; F5's live migration is last). F1 (.github-private doc) is independent of the in-flight #607 (.github compliance-audit). Start F1 now.