Pre-release check

This is the last thing that runs before a release is cut. Nothing downstream catches what you miss here.

Releases are cut by release-please: a bot PR titled chore(main): release <version> sits open against main, and the release happens the moment it merges — tagging, publishing images, and cutting a GitHub release. There is no undo.

Three mechanics shape the whole check:

• The changelog is built only from Conventional Commit subjects on main.
• main squash-merges with the PR title as the commit subject. A PR titled without a feat/fix/chore prefix lands a commit that contributes nothing to the changelog and nothing to the version bump — a feature ships silently inside a patch release.
• main is protected against force-pushes, so a subject that landed wrong cannot be rewritten. It can only be corrected by a follow-up commit.

You end on a verdict: ship or hold. A hedge is a hold. Everything below feeds that one call, so run every step — a skipped step is an unknown, and an unknown holds.

Step 1 — Go green

Confirm the ground first: on main, synced with origin/main, working tree clean.

git fetch --tags && git fetch origin main
git status --short && git log --oneline origin/main..HEAD

Lint, typecheck and tests are not re-run here. CI runs them on every push to main, so the tip has already been through them — but "CI runs on main" is only a guarantee if you look at the result. Read it:

git rev-parse origin/main
gh run list --branch main --workflow ci.yml --limit 1 \
  --json headSha,status,conclusion,url --jq '.[0]'

The run's headSha must equal origin/main and its conclusion must be success. Three ways that goes wrong, all holds:

• The newest run is for an older commit. The tip is unverified — most likely it arrived by a push that bypassed the pull request, which is how a security fix lands off a private advisory. Wait for its run, or trigger one.
• No run at all, or one still in progress. Wait for it. An absent result is not a passing one.
• A failing run. Stop here.

Do not accept the release PR's own green check as evidence. CI skips lint, typecheck and tests on any branch starting release-please--, and the gate job passes on skipped jobs — so the release PR is green whatever state the code is in. The run that means something is the one on main.

Then run what CI does not cover, from the repo root:

pnpm build

Then pnpm format followed by git status --short. format writes, so a dirty tree afterwards means formatting has drifted on main and needs its own commit. Neither the build nor formatting drift is checked anywhere upstream of here.

Neither is the image build. build-and-push.yml runs only once the release exists, and its pnpm install sees only what each Dockerfile copies in — not the working tree pnpm build ran against. That is how 3.19.0's release build failed: a patches/ directory the root package.json had started to require was never copied into the frontend image. If the range touches any of package.json (root), pnpm-lock.yaml, pnpm-workspace.yaml, .npmrc, patches/, or a Dockerfile, build the install stages before calling green:

docker build --target deps -f apps/frontend/Dockerfile .
docker build --target prod-deps -f apps/backend/Dockerfile .

Each takes a minute or two. A failure here is a hold, and it is one no CI run will show you.

Report the CI run and each local check as pass or fail, with the failing output. Green is a CI success on this exact commit plus every local check passing on an unmodified tree. Anything red is a hold — say so and stop; do not carry a failure forward into the later steps hoping it looks smaller in a summary.

Step 2 — Reconcile the release

Establish the range: previous release tag to the tip of main.

git tag --sort=-v:refname | head -1        # previous release
gh release view <prev-tag>                 # what it told self-hosters
gh pr list --state open --head release-please--branches--main--components--platypus --json number,title,body
git log <prev-tag>..origin/main --oneline
git diff <prev-tag>..origin/main --stat

Read the previous release's notes first. A changelog lists what changed; the notes are where a breaking change gets its commentary — the migration step, the deprecation naming the release that removes it, the caveat a self-hoster acted on. That commentary is the state this upgrade starts from, so the pending range can complete it, contradict it, or strand someone who followed it.

Then read the release PR body (its changelog), then the range itself — open every file the stat flags as substantial. Never reconcile from commit subjects alone; the subject is the thing under suspicion.

Every commit in the range must be accounted for: it either appears in the changelog, or you name it and say what it actually changed. Hunt specifically for a subject that isn't feat/fix/chore — that commit is invisible to release-please.

Report:

• Commits in the range but absent from the changelog, with what each actually changed.
• Whether the proposed bump matches the largest change in the range — a feat in the range and a patch bump on the PR is a hold.
• Anything breaking: a removed or renamed env var, a changed default, an API or schema shift a self-hoster upgrades into. Breaking work in a non-major release is a hold.
• The next major's milestone (v<N>.0.0, e.g. gh issue list --milestone v4.0.0 --state all). It holds one issue per planned breaking change, each deprecated during the current major. If this release is a major, list every issue that is still open. Each one is a break this major was meant to carry, and whether to hold the release or move the issue to the following major's milestone is the user's call. If it isn't a major, an issue from the milestone that closed in the range is breaking work shipping early, which is a hold. A deprecation this range introduces with no removal issue on the milestone will be forgotten, so name it.
• Commentary in the previous notes that this range settles, contradicts, or strands — a deprecation this range removes, a migration step it invalidates, a "lands next release" it either delivers or silently skips.
• User-facing changes the changelog technically lists but doesn't convey.

The remedy for a mismatched bump is the user's call, not yours. Surface it and stop.

Step 3 — Sweep what CI can't see

The gate Step 1 confirmed is a floor. These four hold the release and none of them go red:

• Focused or disabled tests. grep -rn "\.only(\|\.skip(\|todo(" --include="*.test.ts" --include="*.test.tsx" apps packages — a .only left in the range silently disables the rest of its file, so CI went green over tests that never ran. Any hit introduced in this range is a hold until it's removed or justified.
• Docs that ship with the code. CLAUDE.md maps changed paths to the docs page that must change with them — .example.env, packages/schemas limits, apps/backend/src/plugins/**, and visible frontend labels. Apply that table to the range's paths: if a mapped path changed and apps/docs/content didn't, the release ships a docs lie. docs-contract.test.ts already passed in CI and cannot see UI labels; for those, ask the user to run /docs-audit — it is user-invoked and you cannot start it yourself.
• The plugin SDK version. If the range touches packages/plugin-sdk, its package.json version must already be bumped by hand. publish-sdk.yml fires on release publish and publishes only when that version isn't on npm — an unbumped SDK means the release goes out with SDK changes that never reach consumers.
• Migrations. If the range adds a migration, confirm it's a real .sql file that drizzle-kit migrate will run in production, not a dev-only push that exists nowhere but a developer's database. Then check the journal: every new entry's when in apps/backend/drizzle/meta/_journal.json must be later than every entry before it. Drizzle applies only entries newer than the database's newest recorded migration, so a migration generated on a branch before its lower-numbered neighbour merged is skipped by every database that already ran that neighbour — and fresh installs, including dev, apply it fine, so nothing local notices. That is how 3.7.0 shipped without the skill columns 3.6.0 upgraders needed. An out-of-order entry is a hold; migration-journal.test.ts now pins this, but check the range by hand as well.

Step 4 — Check the roadmap

ROADMAP.md groups work by horizon: Now, Shipped, Later / Exploring, and Non-goals. Its own promise is that a returning reader is never told something is unbuilt when it's running in production — and a release is exactly when that goes stale.

Against the range you just read, check each:

• Does this release complete a Now item, so it moves to Shipped with this version appended (### Item — 2.11.0)?
• Does it deliver part of a Later / Exploring item, or settle a design that section calls unsettled?
• Does it contradict a Non-goal, or make a Vision claim newly true or newly wrong?
• Do any "Contributions welcome" notes now point at work that's already done?

A stale roadmap is not a hold — it's an edit. If nothing shifted, say so plainly. If something did, propose the edit as a concrete diff for the user to accept or reject; leave ROADMAP.md unwritten until they do.

Step 5 — Check ADR statuses

docs/adr/ records decisions, and each ADR's frontmatter status claims where that decision stands relative to the code. A release is when that claim goes stale: a shipped range implements a decision, or contradicts one, and nothing mechanical notices.

Read the statuses, then the range against them:

grep -H "^status:\|^implemented-by:" docs/adr/*.md

• Every accepted-pending-implementation ADR. Its implemented-by key names the issue or PR that builds it. If that number appears in the range — or the range's code otherwise makes the ADR true — the flip to accepted was meant to land with the implementing PR and didn't. The release would ship an ADR telling readers its own decision is unbuilt while the code does it. Propose: status: accepted, drop implemented-by, and remove the "In the code today" admonition under the title, which is now false.
• The reverse. An ADR already at accepted whose implementation is not actually in the range or in main is the same lie pointing the other way — flag it, but confirm against the code before proposing a downgrade.
• Decisions this range overturns. If the range changes something an accepted ADR decided, that ADR needs superseded-by-NNNN (the later ADR replacing it) or deprecated (nothing replaced it). If no ADR records the new decision and the change is architectural, say so — the missing ADR is the finding, not the status.
• Never rewrite an accepted ADR's text to match the new state. The repo's rule is that the old ADR keeps its history and gains a pointer: append an ## Amended by ADR-NNNN section naming which claims are narrowed or withdrawn, and let the newer ADR carry the reasoning. docs/adr/README.md is the authority on the status vocabulary and this rule.

Like the roadmap, a stale ADR status is not a hold — it's an edit. If nothing shifted, say so plainly. If something did, propose each change as a concrete diff for the user to accept or reject; leave the ADRs unwritten until they do.

Step 6 — Offer the deep review

Ask the user whether they want a deep review of the release range. Recommend it when Step 2 or Step 3 turned anything up, and say why.

If they accept, run the code-review skill with the previous release tag as its fixed point. That skill owns the review criteria; don't restate them here.

Then work the findings with the user rather than reporting and leaving. Take them in severity order, and for each, propose the fix and let the user decide whether it lands before the release or after it. Some findings are worth blocking a release; most aren't, and that call is theirs.

Step 7 — Return the verdict

Close with the call, in this shape:

• SHIP — every check in Steps 1–3 passed, the bump matches the range, and any roadmap or ADR-status edit is agreed. Name the version being cut and the PR number to merge.
• HOLD — list every blocker, each with the step that found it and what would clear it.

State the verdict plainly and let it stand. Do not soften a hold into a list of observations, and do not upgrade a hold to a ship because the blockers look small — the user decides to override, and they can only do that if you called it.