release

name	release
description	Cut a tagged release of ai-dev-baseline. Verifies release readiness and branch health live, stamps CHANGELOG.md, ships it as a PR, tags the exact merge commit it watched go green, publishes the GitHub Release from that tag's own message, and rolls the release milestone. This is the project-owned release role that decision
argument-hint	[--version vX.Y.Z] [--dry-run]
user-invocable	true
effort	high

/release — cut a tagged release of this repo

This is a hand-written, project-owned skill. It is NOT generated by scripts/build.sh; there is no base/workflows/release.md and there must never be one. Decision #3 / D7 resolved that release execution stays project-owned because cutting has four incompatible shapes across projects while the baseline can only ship one. The release-role section of scripts/check-fact-drift.sh enforces that negative invariant against base/workflows/release.md and agents/*/skills/release — this file lives at .claude/skills/release/SKILL.md, which is the prescribed home for a project-scoped skill (docs/per-project-overrides.md → Override 2a) and is deliberately outside the paths that lint guards. Editing this file must never move it under base/ or agents/.

Why this skill exists

Before it, /roadmap would compute met and print Next: /release — a command that did not exist here. The procedure lived as three prose sentences in CONTRIBUTING.md → Releases and had to be hand-executed every time. A nonexistent slash command does not fail loudly in Claude Code; it fuzzy-matches the nearest built-in (release-notes), so the miss was silent. See issue #188.

Every decision below is delegated to a tested predicate that already exists in this repo. This skill is the glue plus the two genuinely project-specific parts: the CHANGELOG format and the tag convention.

What this skill does NOT do

• It never decides readiness itself. roadmap-lib.sh release-ready and branch-health own that; this skill refuses to proceed when they say no.
• It never force-pushes, never --no-verify, never pushes to main directly. The CHANGELOG stamp ships as an ordinary PR through the same gates as any other change.
• It never publishes a package or a deploy. It does publish a GitHub Release — step 11, since #284 / D62, which reversed the tag-only decision this bullet used to state. What it still does not do is push an artifact anywhere but that Release: no registry, no image, no deployment.
• It never creates or moves a tag while publishing. publish refuses unless the tag is already on origin, and passes --verify-tag so that gh cannot mint one from the default branch's head.
• It never edits the roadmap artifact. /roadmap owns that. This skill's last act is baseline release roll, which mutates milestones only.

How this skill runs

The procedure is a script, not prose. ./release.sh holds every step; this file explains what each one means and what you must decide. That split is deliberate and was earned: the procedure lived in fenced shell here for three review rounds and produced 27 defects — 10, then 7, then 10, and the third round's were mostly regressions introduced while fixing the second.

The reason is structural, not carelessness. A Markdown code block is a program nothing can run: shellcheck never sees it, the tests never execute it, and the shell-session contract is invisible (this repo has two opposite ones — base/workflows/roadmap.md's blocks share nothing, base/workflows/cleanup.md's share everything). Every class of defect round 3 found is impossible in a script: positional arguments are real arguments, cross-step values are real state, and a GNU-only sort -V fails the moment a test runs it on macOS.

scripts/check-release-skill.sh covers both halves and runs in selfcheck + CI.

Steps

Run these in order. Each is a separate command; state carries in .claude/state/release-run.env, so an interrupted release is resumable and a failed tag push can simply be retried.

#	Command	What it does / what you decide
1	bash .claude/skills/release/release.sh preflight	tools, [roles].release guard, fetch --tags, clean tree, and default branch equal to origin (not merely fast-forwardable)
2	… release.sh readiness	resolves the roadmap artifact + release milestone, pins their identities, and refuses anything but met
3	… release.sh inventory	prints every version already used and the previous release, plus the ### sections in [Unreleased] — you choose the version from this
4	… release.sh version-guard vX.Y.Z	refuses an empty release, a malformed/reused/non-increasing version; records it. Exit 3 = RESUME (a local-only tag from a failed push — skip to step 10)
5	… release.sh roll-preflight	dry-runs the milestone rollover before anything irreversible
6	(you) branch + edit CHANGELOG.md, then … release.sh stamp-verify	see The stamp below
7	(you) bash scripts/selfcheck.sh, commit, push, open the PR, then … release.sh record-pr <n>	commit chore(release): stamp CHANGELOG for <VERSION>; PR body names the post-merge steps; Refs #<roadmap> — never a closing keyword
8	… release.sh await-review	waits for the declared reviewer, then settles the reviewed head's check set and records it
9	… release.sh merge → … release.sh verify-merge	re-verifies readiness against the pin, merges pinned to the reviewed head, then settles + health-checks the merge commit
10	write the tag message to a file, then

The version

You pick it from step 3's output, by this repo's rule: a ### Removed or any breaking change to the install contract → major; any ### Added → minor; only non-breaking ### Fixed / ### Changed → patch. Confirm with the operator before step 4 — a pushed tag is permanent.

The stamp

On a release-<VERSION> branch, edit CHANGELOG.md:

1. Insert ## [X.Y.Z] - YYYY-MM-DD immediately below ## [Unreleased], leaving ## [Unreleased] in place and empty. Use today's date, resolved live.
2. Add a 3–6 line paragraph under the new heading saying what the release is — the only prose a reader of the tag will see.
3. Repoint the link refs, descending: [Unreleased] → compare/vX.Y.Z...HEAD, plus a new [X.Y.Z] → compare/<previous>...vX.Y.Z. Only the first tag ever uses releases/tag/.

stamp-verify then asserts all of it whole-line and fixed-string.

The tag message

Write it to a file with the Write tool — version on line 1, blank line, the same paragraph used in CHANGELOG.md, then the provenance line. Pass that path to release.sh tag --message-file.

It is a file, never an inline -m: the paragraph is Markdown and routinely contains backticks, and inside a double-quoted -m the shell would run each backticked fragment as command substitution — executing changelog text and corrupting the message.

The tag is created with --cleanup=verbatim, and that is not cosmetic. Git's default cleanup treats a #-leading line as commentary and deletes it — in Markdown that is a heading, i.e. ordinary content. Measured: an 80-byte message containing one # A markdown heading line was stored as 54 bytes, with that line simply gone and nothing said. Verbatim also makes the stored annotation byte-identical to your file, which is what lets step 11 read the notes back out of the tag instead of depending on a file that may not exist by then.

The release

release.sh publish creates the GitHub Release for the tag step 10 just pushed. You run it, the same way you run the tag step — it is the second irreversible, outward-facing act in this procedure, and it gets the same confirmation the first one does. --dry-run prints exactly what it would do (state, commit, notes size, asset digests) and makes no GitHub write and no run-state write. It is not inert: like every other subcommand it runs git fetch --prune --tags origin first, so local remote-tracking refs and tags are updated. Say that rather than "mutates nothing", which is the kind of claim that is false in exactly one place nobody checks.

• The notes are the tag's own message, byte for byte. Not the changelog, not a regenerated summary: publish reads the annotation off the tag object itself — by byte offset, so a message stored without a final newline does not silently gain one, and a CRLF message is preserved as it is. The tag is the one place that prose durably lives, so a backfill years later still has it. Three things make "byte for byte" hold rather than merely be asserted: --cleanup=verbatim when the tag is written, an identity check when a pre-existing tag is resumed (its annotation must equal the message file, and a lightweight one is refused), and a raw comparison of the published body — carriage returns are not normalized away, they are diagnosed separately.

• It publishes the commit the tag points at, re-verified against the MERGE_SHA this run pinned in step 9, and re-checked to be an ancestor of the default branch.

• Two assets: ai-dev-baseline-<X.Y.Z>.tar.gz — git archive of the tagged tree — and SHA256SUMS. Regenerate and check either of them with:

  git -c tar.umask=0022 archive --format=tar --prefix=ai-dev-baseline-X.Y.Z/ vX.Y.Z^{} > a.tar
  gzip -n -9 -c a.tar > ai-dev-baseline-X.Y.Z.tar.gz
  

  -c tar.umask=0022 is part of the command, not an optimisation. git archive takes mode bits from that setting, it is configurable per-repo and per-user, and the driver pins it — so a maintainer whose config differs would regenerate a different archive and conclude a perfectly good release was corrupt. A verification procedure that can report a false mismatch is worse than none.

  git archive fixes every entry's mtime, uid, gid and mode from the commit, and gzip -n drops the name and timestamp — so the bytes are the same on every run of the same gzip. Across other gzip implementations they may not be, which is exactly why the digest is published rather than the property merely asserted. What goes in the artifact is #285's decision; this step owns only that a checksummed, regenerable one is published at all.

  The operational consequence, so it is not a surprise: verification re-builds the artifact and compares digests, so re-running publish against an already-published release from a machine with a different gzip can refuse a release that is perfectly fine. That is the fail-closed direction on purpose — the alternative is blessing a digest nobody checked — but if you hit it, re-run from the machine that cut the release rather than clobbering the asset.

Backfilling an older tag — … release.sh publish --version vX.Y.Z — publishes a release for a tag pushed long ago. It pins on the peeled remote tag rather than run state (a historical tag has no VERSION/MERGE_SHA; roll deleted them), defaults to not Latest, and writes nothing back to the run state, so it is safe to run while another release is in flight. A lightweight tag is refused: it carries no message, and the message is the notes. v1.0.0 is lightweight, which is why it has no release.

What this skill does NOT do

• It never decides readiness or health itself — roadmap-lib.sh owns both, and the driver refuses when they say no.
• It never force-pushes, never --no-verify, never pushes to the default branch. The stamp ships as an ordinary PR through the same gates as any other change.
• It never publishes a package or a deploy, and it publishes a GitHub Release only from a tag that is already on origin. This bullet used to say the opposite — that the repo versions by git tag only and that adding a publish step would be a decision change. #284 / D62 is that decision change: four tags existed with zero Releases, so there were no release notes a human could read and no artifact this project vouched for — the two things a bare tag does not carry.
• It never consults pr-review.sh gate. That guard reads one surface of three, so the Codex connector's clean pass — a +1 with no review object — wedges it at 16 forever (#167, reproduced live on PR #187). It uses pr-watch.sh, which reads all three.
• It never moves or deletes a pushed tag. If the wrong SHA got tagged, cut a new patch version.

Failure recovery

Interrupted after	Resume by
step 4	re-run from step 6
step 6	re-run from step 7
step 8	re-run from step 9
step 9 (merged, untagged)	re-run verify-merge, then step 10
step 10 (tag created, push failed)	re-run release.sh tag --message-file <path> — it is idempotent, and version-guard exits 3 to route you here
step 10 (tag pushed, no release)	run release.sh publish — the tag is the input, so nothing is lost
step 11 (upload interrupted → a draft exists)	re-run release.sh publish — it uploads only what is missing, then publishes the draft
step 11 (release published)	run step 12 — the easy one to forget; without it /roadmap re-emits the cut forever
step 11 skipped, step 12 already run	the run state is gone, so use the backfill path: release.sh publish --version vX.Y.Z