docs: formalize Continuum release contract

[flyingrobots]

Summary

• formalizes the post-release retrospective and next-release planning gate
• extracts repo-specific release facts into .continuum/release.yml
• reshapes .github/RELEASE.md around a Continuum release contract, release state machine, release types, version policy, dist-tags, idempotency, failure handling, and release evidence
• hardens release dispatch so maintainer-triggered publishing runs from the tag ref and verifies checkout/tag alignment
• updates release/doc topology gates to require the release profile and allows type:release tracking issues to remain open in a target milestone

Validation

• npx markdownlint .github/RELEASE.md AGENTS.md .github/CONTRIBUTING.md
• bash -n scripts/release-guard.sh
• bash -n scripts/check-docs-topology.sh
• git diff --check
• npm run lint:docs-topology
• npm run lint:md:code
• npm run lint:md
• npm run release:guard -- --stage prep-pr
• commit hook IRONCLAD TypeScript policy check

Closes #688

Summary by CodeRabbit

• New Features

  • Added repo-specific release configuration to standardize versioning rules, publishing targets, and release workflows.
  • Added checkout-vs-tag verification during release workflow runs.
  • Strengthened milestone/issue gating to block releases with open non-release issues.

• Bug Fixes

  • Updated release automation and preflight messaging so manual publish/dispatch aligns to the release tag, not the main branch.

• Documentation

  • Reworked the release runbook into a contract + state machine, and updated contributor/agent release hygiene guidance and topology checks.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 88e65a14-c824-4b1c-821c-69e759ea3407

📥 Commits

Reviewing files that changed from the base of the PR and between 96db255 and 3785582.

📒 Files selected for processing (2)

• .github/workflows/release.yml
• scripts/release-preflight.sh

---

📝 Walkthrough

Walkthrough

The PR adds a release profile, rewrites the release runbook, and updates release workflows, guard scripts, and contributor guidance to enforce tag/commit alignment, milestone checks, and post-release planning.

Changes

Release process contract

Layer / File(s)	Summary
Release profile and guidance .continuum/release.yml, .github/CONTRIBUTING.md	.continuum/release.yml adds the release profile, and contributor guidance now points release-process references at it.
Runbook contract and prep checklist .github/RELEASE.md	The release runbook now defines the contract, state machine, release types, version policy, thesis/scope reconciliation, and prep checklist with required metadata and signposts.
Tagging and publication flow .github/RELEASE.md, .github/workflows/release-autotag.yml, .github/workflows/release.yml	The release automation sections and workflows now dispatch release.yml from the release tag and verify the checked-out commit matches that tag.
Release gates and milestone checks .github/RELEASE.md, scripts/check-docs-topology.sh, scripts/release-guard.sh	The gate guidance and scripts now add idempotency, failure handling, and evidence rules, require the release profile docs, add the type:release label gate, and check for open non-release issues in the target milestone.
Retrospective and next-release planning .github/RELEASE.md, AGENTS.md	The runbook and release hygiene guidance now define post-release retrospective requirements and next-release planning steps, including milestone thesis and bucket rules.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related issues

• Make release guards consume the Continuum release profile #689 — Adds the Continuum release profile to release guards and docs topology checks, matching the new repo-specific release source-of-truth wiring.

Possibly related PRs

• git-stunts/git-warp#675 — Updates the same release runbook, guard scripts, and workflow paths that this PR further tightens.
• git-stunts/git-warp#678 — Adjusts the manual registry publication flow and tag-based dispatch semantics in the same release workflow.
• git-stunts/git-warp#649 — Changes milestone and release-label gating in scripts/release-guard.sh, which this PR extends with the new non-release issue check.

Poem

I thump through milestones, bright and neat,
with tag-true steps and guards complete.
The docs now hum, the workflows glow,
and carrots know the release flow. 🐇🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main change: formalizing the Continuum release contract.
Description check	✅ Passed	The description includes a summary, linked issue reference, and validation steps, with only the ADR checklist left out.
Linked Issues check	✅ Passed	The changes match #688 by adding the release profile, rewriting release docs, and hardening tag-based publication and topology gates.
Out of Scope Changes check	✅ Passed	The added docs, workflow, and guard changes stay focused on the release-contract goals and do not introduce unrelated scope.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/release-retro-thesis

---

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

[github-actions]

Release Preflight

• package version: 18.1.2
• prerelease: false
• npm dist-tag on release: latest
• npm pack dry-run: passed
• jsr publish dry-run: passed

If this PR is from a release/* branch and merges to main, Release Autotag will run final preflight and create v18.1.2. A maintainer who is a JSR @git-stunts scope member must then dispatch the Release workflow manually.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/release.yml:
- Around line 80-90: The “Verify checkout matches release tag” check only
compares the checked-out commit to steps.meta.outputs.tag, so a workflow
dispatched from a different ref can still pass. Update the release workflow’s
verification step to also validate the dispatch ref/source used by
workflow_dispatch (for example against github.ref or the dispatched tag input)
in addition to HEAD_COMMIT vs TAG_COMMIT, so release.yml cannot run from main
while claiming a tag. Also align the release-preflight.sh example so it reflects
the enforced dispatch-ref requirement.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: aea25410-561a-4002-929f-c4dc8194cf7c

📥 Commits

Reviewing files that changed from the base of the PR and between 529210e and 96db255.

📒 Files selected for processing (8)

• .continuum/release.yml
• .github/CONTRIBUTING.md
• .github/RELEASE.md
• .github/workflows/release-autotag.yml
• .github/workflows/release.yml
• AGENTS.md
• scripts/check-docs-topology.sh
• scripts/release-guard.sh

[github-actions]

Release Preflight

• package version: 18.1.2
• prerelease: false
• npm dist-tag on release: latest
• npm pack dry-run: passed
• jsr publish dry-run: passed

If this PR is from a release/* branch and merges to main, Release Autotag will run final preflight and create v18.1.2. A maintainer who is a JSR @git-stunts scope member must then dispatch the Release workflow manually.

[flyingrobots]

Code Lawyer Activity Summary

Source	Severity	File(s)	Issue	Commit	Outcome
CodeRabbit	Major	.github/workflows/release.yml, scripts/release-preflight.sh	Release workflow could still be dispatched from main while claiming a tag, and the preflight example still printed the old --ref main command.	3785582f	Dispatch ref is now required to be the release tag, the printed command uses --ref vX.Y.Z, and the review thread is resolved.
Self-audit	None	PR diff	No additional correctness, release-contract, topology, Markdown, or shell issues found.	n/a	No follow-up patch required.

Validation:

• git status --porcelain: clean
• git diff --check origin/main...HEAD: passed
• npm run release:guard -- --stage prep-pr: passed
• npm run lint:docs-topology: passed
• PR checks: all green, including preflight, test-node (22), CodeRabbit, link check, coverage threshold, and type-firewall gates
• GraphQL review thread state: zero unresolved threads

@codex please confirm there are no remaining release-dispatch or release-contract blockers.