feat: [release] harden /release — preflight script, fail-closed tags, publish gates

Merged
AN
4mo ago
+1103-79

PINEAPPLE

Summary

Hardens the /release process based on a full-trace retro of the last three releases (v0.8.10, v0.9.1, v0.9.2). Each release hit at least one live failure that process should have caught:

  • v0.9.1 nearly published the wrong artifact: a stale local v0.9.1 tag made git tag silently no-op and the push sent a tag pointing at a 2641-commit-divergent commit. Caught by vigilance, not process.
  • v0.9.2 hit a fork-inherited tag collision, smoke-tested a stale globally-installed 0.7.3 binary while releasing 0.9.2, and burned 7 serial marker-guard fix rounds.
  • publish-npm was never gated on the test job — npm could publish with typecheck/tests red.

Changes:

  1. script/release-preflight.ts (+34 unit tests) — deterministic, fail-closed preflight gate: clean tree; HEAD == fresh origin/main (stage pre) or ancestor (stage tag); local+remote tag-collision check that never auto-deletes; version sanity vs npm (SemVer, monotonic, unpublished); prerelease-line ancestry (the missing check that turned v0.9.1 into a 17-hour merge side-quest); open release-blocker PRs; PREV_TAG dry-run (replicates release.yml selection); marker guard with full output in one pass.
  2. .github/workflows/release.yml — publish-npm now needs: [test, build, sanity-verdaccio]; new Validate release tag step (format, tag-SHA == checked-out SHA, CHANGELOG.md entry for stable releases) runs BEFORE any publish; pre-publish smoke test asserts the exact tag version instead of just "binary starts".
  3. .claude/commands/release.md — preflight as the Step 2 gate; stop-never-improvise on structural failures; three-step verified commit/tag + git push --atomic origin HEAD:main v{V}; fail-closed tag rules; exit-status integrity rule (no trailing status echoes on gates); smoke-test the dist binary by path; deferred findings require durable issue links; P0-candidates verified or explicitly downgraded with rationale; every step visible (✅/⏭️/❌) in the final summary; persona reviewers deliver via SendMessage before idling.
  4. docs/RELEASING.md — targeted staging instead of git add -A; atomic push with pre-push tag verification; honest wording: AUR publishing is disabled, Docker publish is best-effort.

Test Plan

  • bun test script/release-preflight.test.ts — 34/34 pass (semver precedence incl. stable > prerelease, the exact v0.9.1 PREV_TAG bug, malformed-tag rejection)
  • E2E: bun script/release-preflight.ts --version 99.0.0 --stage pre correctly FAILs (branch ahead of origin/main, exit 1); --stage tag PASSes 9/9
  • Negative E2E: --version 0.9.2 correctly FAILs on tag collision (shows local+remote SHA) and already-published npm version
  • bun test test/branding/ test/install/ (the CI test job's exact scope, which asserts release.yml contents) — 442 pass / 0 fail
  • Marker guard --strict clean; release.yml YAML validated

Checklist

  • Tests added/updated
  • Documentation updated
  • CHANGELOG updated (release-process change only; no user-facing behavior — will land in the next release's changelog if desired)

Closes #1031

🤖 Generated with Claude Code


Summary by cubic

Tightens the release flow with a deterministic preflight gate, fail‑closed tag rules, strict SemVer, and stronger CI publish gates. Adds authoritative tag validation, exact‑version smoke checks, and blocks beta downgrades.

  • New Features

    • script/release-preflight.ts: clean worktree; HEAD == fresh origin/main (pre) or origin/main is ancestor (tag); fail‑closed local/remote tag collision check; strict SemVer (no leading zeros, no empty prerelease ids); npm reachability/unpublished enforced (fail‑closed); prerelease ancestry checked against HEAD; beta targets must be > current beta dist‑tag; release-blocker PRs gate; PREV_TAG dry‑run; marker guard with full output; unit tests added.
    • /release-beta: runs preflight with --allow-prerelease; fail‑closed local/remote tag collision and “tag-at-HEAD” checks before pushing.
  • Bug Fixes

    • CI: publish-npm now needs test; release.yml validates tag format and SHA via git ls-remote origin (incl. ^{} peel) and requires a stable changelog entry before publish; pre‑publish smoke asserts the exact tag version; PREV_TAG picks the highest merged stable strictly lower than the target; preflight tests run in CI.
    • Marker guard: fails if analyze.ts degrades to pattern‑only due to a missing upstream remote. Docs (RELEASING.md, .claude/commands/release(-beta).md): preflight is the gate; verify tags before push; push HEAD:main atomically; targeted staging (no -A); run stage‑tag preflight after the release commit; smoke‑test the built binary with an injected version; Docker is best‑effort and AUR is disabled.

Summary by CodeRabbit

  • New Features

    • Added deterministic release preflight validation for versioning, tags, changelog entries, repository state, and publishing readiness.
    • Strengthened release workflows with tag collision checks, atomic pushes, commit verification, and expanded CI validation.
    • Improved generated release notes by selecting the correct previous stable release.
  • Documentation

    • Updated release guides with the new preflight process, verification steps, and release requirements.
  • Tests

    • Added comprehensive preflight validation tests and integrated them into CI.