feat(release): versioning scheme + cut-release helper (#496)

[don-petry]

What (Phase 1 · #496 · epic #495)

Establishes the version boundary the whole Release Strategy initiative depends on.

• docs/release/versioning.md — per-agent semantic versioning (<agent>/vX.Y.Z, immutable) plus
  moving per-agent channel tags (<agent>/stable, later /next, /ring*). Callers pin once
  to a channel; promotion is a central tag move — no per-caller churn (initiative §5.1).
• scripts/cut-release.sh — tested helper to cut an immutable release tag and optionally advance a
  channel to it. Refuses to overwrite immutable tags; --dry-run / --push.
• tests/test_cut_release.bats — 14 cases (agent allowlist, strict semver, tag-name formatting),
  wired into lint.yml (shellcheck + bats).

Tags already cut (the v1.0.0 baseline)

From production main (facf168) — inert until a caller references them (#497):

pr-review/v1.0.0   dev-lead/v1.0.0     (immutable release baselines)
pr-review/stable   dev-lead/stable     (channels -> v1.0.0)

v1.0.0 = "what's in production today" / the rollback floor — not a certified-perfect version.
Health-gated promotion (#501) is what makes future stable moves validated.

Per-agent channels — a small refinement

The analysis doc wrote @stable as shorthand. Because the two agents version independently, the
concrete channel is per-agent (pr-review/stable, dev-lead/stable). Documented in the scheme.

Validation

shellcheck clean · 14/14 bats green · dry-run prints the correct plan · overwrite-guard rejects
re-cutting pr-review/v1.0.0.

Closes #496. Part of epic #495; companion to #504 (analysis) and #507 (orchestration driver).

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

Warning

Review limit reached

@don-petry, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 5 minutes and 20 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4cdf3c58-8eb1-4d31-b987-8e0616f4518a

📥 Commits

Reviewing files that changed from the base of the PR and between fc4344d and 80952ce.

📒 Files selected for processing (4)

• .github/workflows/lint.yml
• docs/release/versioning.md
• scripts/cut-release.sh
• tests/test_cut_release.bats

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/issue-496-versioning

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request introduces documentation, a release script (cut-release.sh), and unit tests for managing agent versioning and release channels. The review feedback highlights two critical issues in the release script: first, a potential crash under set -euo pipefail if the --ref or --channel flags are provided without arguments; second, a risk of overwriting immutable release tags by using git push --force on all tags, which should be split to only force-push mutable channel tags.

[gemini-code-assist]

Using git push --force on the entire pushrefs array (which contains both the immutable release tag $rel and the mutable channel tag $chan) is risky. If the local repository is out of sync or the release tag was deleted locally but still exists on the remote, a force push will overwrite the remote immutable release tag. This violates the core design principle that immutable tags must never be overwritten.

To prevent this, we should push the immutable release tag $rel without --force, and only use --force when pushing the mutable channel tag $chan.

Suggested change

	if [ "$do_push" = true ]; then
	# --force needed for the (movable) channel tag; release tag is new so it is a no-op there.
	git push --force origin "${pushrefs[@]}"
	echo "pushed: ${pushrefs[*]}"
	if [ "$do_push" = true ]; then
	# Push the immutable release tag without --force to prevent accidental remote overwrites
	git push origin "$rel"
	if [ -n "$channel" ]; then
	# --force is required to move the mutable channel tag
	git push --force origin "$chan"
	fi
	echo "pushed: ${pushrefs[*]}"

[don-petry]

Applied the exact suggestion in scripts/cut-release.sh lines 116–123: replaced the [ -n "$channel" ] && git push --force ... one-liner with an explicit if [ -n "$channel" ] block and added the two comments explaining why the immutable release tag is pushed without --force and why the channel tag requires it.

[don-petry]

Verified: the fix is in place at scripts/cut-release.sh lines 116–123. The immutable release tag $rel is pushed without --force (line 118), and --force is used only for the mutable channel tag $chan inside the [ -n "$channel" ] guard (line 121), exactly matching the suggestion. ShellCheck passes cleanly on the file.

[don-petry]

Auto-rebase failed — merge conflict — this branch has conflicts with main that must be resolved.

Claude will attempt to resolve this automatically. If it cannot, a follow-up comment will explain what needs manual attention.

To resolve manually instead:

git fetch origin
git merge origin/main
# resolve conflicts, then:
git add .
git commit
git push

[don-petry]

Dev-Lead — fix-bot-comment (applied)

Changes committed and pushed.

[Copilot]

Pull request overview

Establishes the Phase 1 “version boundary” for the Release Strategy initiative by documenting a per-agent tag scheme and adding a helper script (plus CI validation) to cut immutable release tags and advance per-agent channel tags.

Changes:

• Documented per-agent immutable release tags (<agent>/vX.Y.Z) and movable per-agent channel tags (<agent>/stable, later next/rings).
• Added scripts/cut-release.sh helper (with bats unit tests) to cut release tags and optionally move a channel tag.
• Wired ShellCheck + bats coverage for the new script/tests into lint.yml.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
docs/release/versioning.md	Defines the per-agent tag scheme and how callers pin to per-agent channel tags.
scripts/cut-release.sh	Implements tag-cutting + optional channel advancement for agent releases.
tests/test_cut_release.bats	Unit tests for the pure helpers used by cut-release.sh.
.github/workflows/lint.yml	Adds ShellCheck and bats coverage for the new release-cutting script/tests.

[don-petry]

Dev-Lead — review-changes (applied)

Changes committed and pushed.

[don-petry]

Dev-Lead — review-changes (applied)

Changes committed and pushed.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[don-petry]

Note

@don-petry I reviewed this PR and no code changes were needed, but it still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews), so I cannot mark it done yet. I'll re-check automatically.
Next attempt after: 2026-06-09T04:11:28Z

[don-petry]

Dev-Lead — rate-limited (intent: review-changes)

PR: #508
The retry cron will re-attempt automatically.