release-process

Context

This is the definitive release runbook for Squad. Born from the v0.8.22 release disaster (4-part semver mangled by npm, draft release never triggered publish, wrong NPM_TOKEN type, 6+ hours of broken latest dist-tag).

Rule: No agent releases Squad without following this checklist. No exceptions. No improvisation.

---

Pre-Release Validation

Before starting ANY release work, validate the following:

1. Version Number Validation

Rule: Only 3-part semver (major.minor.patch) or prerelease (major.minor.patch-tag.N) are valid. 4-part versions (0.8.21.4) are NOT valid semver and npm will mangle them.

# Check version is valid semver
node -p "require('semver').valid('0.8.22')"
# Output: '0.8.22' = valid
# Output: null = INVALID, STOP

# For prerelease versions
node -p "require('semver').valid('0.8.23-preview.1')"
# Output: '0.8.23-preview.1' = valid

If semver.valid() returns null: STOP. Fix the version. Do NOT proceed.

2. NPM_TOKEN Verification

Rule: NPM_TOKEN must be an Automation token (no 2FA required). User tokens with 2FA will fail in CI with EOTP errors.

# Check token type (requires npm CLI authenticated)
npm token list

Look for:

• ✅ read-write tokens with NO 2FA requirement = Automation token (correct)
• ❌ Tokens requiring OTP = User token (WRONG, will fail in CI)

How to create an Automation token:

1. Go to npmjs.com → Settings → Access Tokens
2. Click "Generate New Token"
3. Select "Automation" (NOT "Publish")
4. Copy token and save as GitHub secret: NPM_TOKEN

If using a User token: STOP. Create an Automation token first.

3. Branch and Tag State

Rule: Release from main branch. Ensure clean state, no uncommitted changes, latest from origin.

# Ensure on main and clean
git checkout main
git pull origin main
git status  # Should show: "nothing to commit, working tree clean"

# Check tag doesn't already exist
git tag -l "v0.8.22"
# Output should be EMPTY. If tag exists, release already done or collision.