Release Checklist

Purpose #

The end-to-end checklist for cutting an aidokit release. Combines how-to-guides/how-to-cut-a-release.md and ADR-0004 into a single signoff list.

Choose the release type #

Stream	Dist-tag	When
Pre-1.0	`alpha`	Every pre-v1.0 release. `latest` stays unset.
v0.5 beta	`beta`	Optional wider beta after v0.5.
v1.0+	`latest`	GA and every subsequent stable release. Provenance required.
v1.x+ pre	`next`	Optional opt-in for in-progress v1.x or v2.0 work.

Pre-release: code health #

[ ] Branch is up to date with main.
[ ] pnpm install --frozen-lockfile succeeds without warnings.
[ ] pnpm lint clean.
[ ] pnpm typecheck clean.
[ ] pnpm build clean.
[ ] pnpm test green for every package.
[ ] Every adapter and stack-pack test:conformance green.
[ ] Dogfood byte-compare clean (see how-to-guides/how-to-run-tests-and-byte-compare.md).
[ ] Latest matrix.yml PR run green (14 {adapter, stack, tier} combinations).
[ ] Latest matrix-snapshot.yml nightly green — health/matrix-status.json shows failed: 0.
[ ] No open issues tagged health-regression.
[ ] No open snapshot-acceptance PR untouched for > 1 week (review or close).
[ ] Open quarterly-bump issue (if any): boxes ticked or rationale comment added.

Pre-release: v1.0+ integrity checks #

For v1.0 and later releases, also run on a Strict-tier dogfood project (aidokit init --tier strict --adapter claude-code --stack node-ts):

[ ] aidokit verify exits 0 (install matches templates — G5).
[ ] aidokit verify --capabilities exits 0 (D4 declared-vs-actual).
[ ] aidokit manifest --verify-capabilities exits 0.
[ ] .aidokit/capabilities.json is present and matches declared adapter manifests (ADR-0017).
[ ] aidokit audit export --format soc2 --output /tmp/soc2.md produces a non-empty packet.
[ ] aidokit audit export --format eu-ai-act --output /tmp/eu.md produces a non-empty packet.
[ ] aidokit doctor --drift reports no stale ADRs or task backlog.

Pre-release: versioning #

[ ] All pending .changeset/*.md files reviewed and merged into main.
[ ] Changeset bump levels reflect actual changes: patch / minor (pre-1.0 may include breaking) / major (v1.0+).
[ ] Run pnpm changeset version and review the produced diffs:
Per-package package.json version bumped.
Per-package CHANGELOG.md updated.
Workspace deps where applicable (workspace:* → semver) — verify Changesets rewrite is correct.

Pre-release: package hygiene #

For every package being published:

[ ] "license": "Apache-2.0" in package.json.
[ ] "type": "module".
[ ] "engines": { "node": ">=20.0.0" }.
[ ] "files" allowlist: ["dist/**", "README.md", "LICENSE", "NOTICE", "CHANGELOG.md"].
[ ] "repository": { "type": "git", "url": "..." }.
[ ] publishConfig: { "access": "public" }.
[ ] LICENSE and NOTICE present in each package directory (copied at publish per build step).

Pre-release: docs #

[ ] Root CHANGELOG.md [Unreleased] entries promoted to a versioned heading.
[ ] README and wiki updated for any user-visible surface changes.
[ ] If v1.0: README install instructions no longer reference @alpha.

Publish: pre-1.0 #

pnpm install --frozen-lockfile=false
pnpm build
pnpm test
pnpm changeset publish --tag alpha

[ ] Publish output lists every changed package.
[ ] npm view aidokit dist-tags shows alpha: <new-version>; latest still unset.

Publish: v1.0+ #

pnpm install --frozen-lockfile=false
pnpm build
pnpm test
NPM_CONFIG_PROVENANCE=true pnpm changeset publish

[ ] Publish output lists every changed package with provenance attestation.
[ ] npm view aidokit dist-tags shows latest: <new-version>.
[ ] npm audit signatures verifies provenance on the new release.

Post-publish #

[ ] Tag the release in git: git tag -a v<version> -m "v<version>" && git push --tags.
[ ] Open GitHub Release with per-package CHANGELOG excerpts.
[ ] Smoke test in a fresh temp dir:

mkdir /tmp/smoke && cd /tmp/smoke && git init
npx aidokit@<version> init --adapter claude-code --stack node-ts --yes    # (v1.0+)
# or
npx aidokit@alpha init ...                                                  # (pre-1.0)

[ ] Inspect the emitted tree; counts match expectations from tutorials/scaffold-your-first-project.md.
[ ] Announce on the channels you use (release notes, social post, blog if GA).

Rollback (if needed) #

[ ] npm dist-tag rm aidokit alpha (or latest) to unpoint the tag.
[ ] If the bad version contains a vulnerability: yank or deprecate (npm deprecate <pkg>@<version> "...").
[ ] Publish a corrected version; bump dist-tag forward.
[ ] Issue a security advisory if applicable (SECURITY.md).

Common pitfalls #

Forgetting --provenance at v1.0+. Required per ADR-0004 §5.
Promoting latest pre-1.0. Surprises users; breaks the stated dist-tag policy.
Publishing from a dirty working tree. Build outputs may include local cruft.
Skipping the dogfood compare before publish. The whole class of "looks fine in tests, breaks for users" regressions is what it catches.
Editing the published tarball after-the-fact. Use a new version; npm tarballs are immutable.