Release runbook

Release runbook (summary)

This page is a map, not the checklist. The authority is RELEASING.md for plugin releases and ah-engine/RELEASING.md for engine releases. Follow those files step by step; if this page and those files disagree, the files win.

Note

Flow: short-lived branch → dev (no CI) → pull request to main (the gate) → tag → GitHub Release. Tags are immutable.

Two kinds of release

	Plugin release	Engine release
Tag	vX.Y.Z	ah-engine-vX.Y.Z
Version source	plugins/anti-hall/.claude-plugin/plugin.json (the Codex manifest, root package.json and package-lock.json must match)	ah-engine/Cargo.toml, pinned for the plugin in ah-engine.lock
What ships	The plugin directory, installed from main	Prebuilt binaries attached to a GitHub Release, downloaded and checksum-verified on the user's machine
Workflow	Pull request dev → main, then a manual tag	ah-engine-release.yml: a manual prepare run that opens a lock PR, then a tag push that publishes

Plugin release, in one screen

1. On dev: bump the four version fields together and add a ## <version> section at the top of CHANGELOG.md (patch for fixes and docs, minor for a new capability).
2. Update every doc the change touches (the guide, llms.txt, the READMEs). A release that changes a hook, skill or discipline is not done until the docs say so.
3. Run node --test and node plugins/anti-hall/hooks/doctor.js --check locally. Pushes to dev run no CI.
4. Optional: push an rc-v<version> tag to run the full CI matrix on that commit. Pull requests run only the lean Node 24 matrix; the full matrix runs on tags, main and weekly, and nightly runs parity and benchmark suites.
5. Open the pull request dev → main. The dev-only and tests-passed checks must be green. Merging is the release: users install from main, and a version that reached main cannot be replaced under the same number. Merge with a merge commit, never squash.
6. Tag v<version> on the merged commit and create the GitHub Release with that version's CHANGELOG section as the body. The release notes template shows the headings.

Release Drafter keeps a draft release of merged pull requests grouped by type:* label. It never publishes; CHANGELOG.md is the source of the notes.

Engine release, in one screen

1. Change the engine and bump version in ah-engine/Cargo.toml.
2. Prepare: run the ah-engine-release workflow manually. It builds every target in ah-engine/targets.json, runs the tests, and opens a PR (against dev, never main) that updates ah-engine.lock and its copy at plugins/anti-hall/ah-engine.lock.
3. Merge that PR.
4. Publish: push ah-engine-vX.Y.Z on the merged commit. The workflow checks the lock, the fingerprint and every sha256 before it creates the release with build-provenance attestation.

Users get the new binary on their next session start: the bootstrap script downloads the archive named in the lock and installs it only if its sha256 matches. Any failure leaves the Node hooks in use. Details: Architecture.

Rules that never bend

Warning

A tag ruleset blocks update, deletion and force-update of v* and ah-engine-v*. A wrong release is fixed with a new version, never by re-tagging.

• Never push to main directly, and never force-push any branch.
• Never move or delete a v* or ah-engine-v* tag. A wrong release is fixed with a new version.
• No AI credit lines in commits or in release text.
• Check the GitHub Actions result before calling a public release done: a green local run is not a green CI run.

See also: Development workflow, CONTRIBUTING.md, docs/REPO-PIPELINES.md.