Release

Prepare and ship a GitHub + npm + sandbox release with a mandatory preview step. A confirmed execute run is not complete until npm publish succeeds from the published package root and sandbox.neotoma.io is deployed and verified, unless the user explicitly scoped the request to GitHub-only / no registry / no sandbox.

When to Use

When you want to ship what is on dev (or the current integration branch) to main, tag it, publish to npm, create a GitHub Release with curated notes, and update the public sandbox deployment.

Trigger with /release, or naturally ("prepare a release", "let's ship v0.5.0").

Reference Documents

Document	Role
docs/developer/github_release_process.md	GitHub Release template layout, release-notes:render usage, gh release create
docs/developer/github_release_supplement.example.md	Section pattern for the human-readable supplement
docs/infrastructure/deployment.md	Sandbox Fly deployment command and verification
docs/subsystems/sandbox_deployment.md	Sandbox runtime behavior and operator runbook
.github/release_notes_wrap.md	Fixed wrap template (install commands, npm/compare table, commit list)

Workflow

Step 1: Preflight

Run before anything else:

1. Fetch: git fetch origin (and other configured remotes).
2. Determine branches: Default integration = dev, target = main. Override if the user specifies.
3. Commits not on main: git log origin/main..origin/dev --oneline (or origin/main..HEAD on integration branch). This is the default scope of "what ships."
4. Uncommitted changes: git status --short. If dirty, describe the actual pending work grouped by area/impact using git diff --stat and targeted file inspection. Do not use a generic placeholder.
5. Submodules: git submodule status — surface any that are ahead/behind recorded SHAs.
6. Previous tag: git tag --sort=-v:refname | head -1 — this is the compare base unless the user specifies --compare-base.
7. Current package.json version: Read and display.
8. Existing GitHub Release check: Run gh release view "vX.Y.Z" --json isDraft,tagName 2>/dev/null for the target version. If a release exists and is a draft, surface this to the user ("Draft release vX.Y.Z already exists on GitHub — execute will update it rather than create a new one."). If a release exists and is not a draft (already published), STOP and ask the user explicitly before proceeding — updating a published release's notes is a hold point.
9. Sandbox deploy readiness: Confirm fly.sandbox.toml exists, flyctl is available, and the active Fly account can deploy neotoma-sandbox. If Fly auth is missing, report that execute will block at sandbox deployment unless the user explicitly scopes the release to no sandbox.

Step 2: Resolve Version

1. If the user provided a version (e.g. "v0.5.0"), use it.
2. Otherwise, propose next patch from the latest tag: if latest is v0.4.2, propose v0.4.3. If the user wants a minor or major bump, ask once.
3. Confirm: "Release as vX.Y.Z?"

Step 3: Preview

Draft the supplement following the section pattern from docs/developer/github_release_supplement.example.md:

• Summary: One plain-English sentence of what this release ships.
• What changed for npm package users: CLI, runtime/data layer, shipped artifacts.
• API surface & contracts: OpenAPI / MCP tool changes.
• Behavior changes: What users notice after upgrading.
• Docs site & CI / tooling: If applicable.
• Internal changes: Refactors, architecture, dependency, test-only work.
• Fixes: Bug fixes with user/operator impact.
• Tests and validation: What validates confidence. (Optional: for a committed Markdown test evidence file, run npm run test:remote:critical:report or npm run test:integration:report, then copy a redacted .vitest/reports/*.md into docs/releases/in_progress/vX.Y.Z/ per docs/testing/integration_run_reports.md.)
• Breaking changes: None, or list with migration notes.

Integrated supplement (mandatory for /release): The narrative is always a single release story across committed history and the working tree. Walk the default compare range (commits not yet on main, plus any user override) and fold all material uncommitted and untracked work into the same sections above, written as if that work were already committed — same grouping and reader-facing tone as shipped commits. Do not isolate dirty work in a separate appendix (for example, do not use a standalone Uncommitted changes pending inclusion block as the primary description). If paths cannot ship under repo security or submodule policy, state that in Breaking changes or a one-line Ship constraints item inside the same structure.

Exact GitHub Release preview (mandatory): After drafting the supplement, render the exact Markdown body that gh release create --notes-file will use. Preview the rendered wrap + supplement, not just the supplement summary.

• If the tag already exists, render it normally:

  npm run -s release-notes:render -- --tag vX.Y.Z > /tmp/gh-release-vX.Y.Z.md
  

• If the tag does not exist yet, render a pre-tag exact preview against the intended release ref:

  npm run -s release-notes:render -- --tag vX.Y.Z --head-ref <release-ref> --supplement docs/releases/in_progress/vX.Y.Z/github_release_supplement.md > /tmp/gh-release-vX.Y.Z.md
  

  Use <release-ref> as the ref that will receive the tag (for example HEAD, origin/dev, or the chosen integration branch after any confirmed pre-release commit).

Preflight honesty: If the tree is dirty, append a short Execute note: the tag matches this preview only after the described local work is committed on the branch you will release (never stage paths forbidden by security / pre-commit rules). In that case the rendered Markdown is exact for the manual body and wrap, while the commit list becomes exact only after the pending commit set exists and you re-render in Step 4.

Write for a human reader deciding whether to upgrade. Do not dump raw commit lists into the supplement. Walk the commit range and group by theme together with local changes.

Present the rendered /tmp/gh-release-vX.Y.Z.md body to the user verbatim. STOP and ask:

"Confirm release vX.Y.Z with these notes? (yes / modify / cancel)"

If the working tree was dirty when drafting, state that execute matches the preview only after that local work is committed (excluding forbidden paths); confirm whether the user intends that full scope or needs to narrow it before Step 4.

Step 3.5: Security review lane

Run after preview is approved by the user, before Step 4. Sources: docs/security/threat_model.md, SECURITY.md.

1. Classify the release diff:

   npm run security:classify-diff -- --base <last-tag> --head HEAD --json
   

   If sensitive=false, this lane is informational; still write the gate artifact (Step 3.5.4) so the trail is consistent.

2. Run the static rules (G2):

   npm run security:lint
   

   Errors are gating; warnings annotate. Resolve any error finding before continuing.

3. Run the topology auth matrix (G3) and confirm the protected-routes manifest is in sync:

   npm run security:manifest:check
   npm run test:security:auth-matrix
   

   If the manifest is out of date, run npm run security:manifest:write (this is allowed inside the release commit) and re-render the supplement.

4. Generate the AI review scaffold (G4):

   npm run security:ai-review -- --tag vX.Y.Z --base <last-tag> --head HEAD
   

   Provider defaults to cursor. Set NEOTOMA_AI_REVIEW_PROVIDER=claude|gpt|none to override; none keeps the review fully manual.

5. Fill docs/releases/in_progress/vX.Y.Z/security_review.md: Walk the adversarial prompt sections (alternate-path auth, proxy trust, local-dev widening, unauth public route, guest-access widening, AAuth downgrade). Record findings, suggested negative tests, residual risks, and a sign-off verdict (yes | with-caveats | block). block keeps the release on the lane.

6. Add a Security hardening section to the supplement at docs/releases/in_progress/vX.Y.Z/github_release_supplement.md that links the security review file and any advisory under docs/security/advisories/ opened or referenced by this release. When classify-diff was sensitive this section is mandatory; when not sensitive, write No security-sensitive surfaces touched. so the trail is explicit.

Hard gate before Step 4: Do not merge, tag, push, create a GitHub Release, publish to npm, or deploy sandbox until Step 3.5 has run against the exact commit that will be released. Before advancing, explicitly verify and report:

• G1 security:classify-diff completed and whether sensitive is true or false.
• G2 security:lint completed with zero errors; warnings are summarized in security_review.md.
• G3 security:manifest:check and test:security:auth-matrix completed successfully.
• G4 security:ai-review created docs/releases/in_progress/vX.Y.Z/security_review.md, and the file is filled with findings, suggested negative tests, residual risks, and a non-placeholder sign-off verdict (yes or with-caveats; never block).
• The supplement has a Security hardening section that links the review artifact.

If any pre-release commit is added after Step 3.5 runs, rerun Step 3.5 before any merge/tag/push action. If a required branch-protection check is missing or bypassed, the local Step 3.5 evidence must already exist and be called out; never use bypass as a substitute for the lane.

Re-render the GitHub Release preview (npm run -s release-notes:render) so the supplement diff is reflected; STOP and re-confirm if the supplement changed materially.

Step 3.6: Test coverage review lane

Run after Step 3.5 passes, before Step 4. Symmetric in role to the security review lane: a structured audit of whether new user-facing surfaces actually have tests that would catch the failure modes a user would hit. Sources: docs/testing/testing_standard.md, the supplement's "What changed for npm package users" section.

Why this lane exists: Tests-exist is not the same as tests-cover-the-thing-users-will-do. A surface can ship with a named test file that exercises only the happy path of an internal helper, leaving destructive operations, external-file-shape parsing, or new CLI commands effectively unverified. The v0.13.0 audit found 5 such gaps after the supplement was confirmed; this lane catches them before execute.

0. Run /review <last-tag>..HEAD before writing the coverage file. The /review skill (.claude/skills/review/SKILL.md) walks the full pre-PR checklist against the diff and emits structured findings (BLOCKING / ADVISORY / NIT) covering architecture, schema-agnostic design, determinism, immutability, auth, contract seams, and user-facing-surface coverage in a single pass. Append its verdict and blocking findings to docs/releases/in_progress/vX.Y.Z/test_coverage_review.md under a ## Code review section. A NEEDS-CHANGES verdict from /review is a hard gate on Step 4 — resolve all BLOCKING findings before proceeding, even if they were introduced by commits that bypassed PR review.

1. Walk the supplement's user-facing surfaces (from "New CLI commands", "New CLI flags on existing commands", "Behavior changes in existing commands", "API surface & contracts"). For each, locate the test file(s) and read what they assert. Note specifically:

   Surfaces that need a regression test before shipping:

   • Destructive or data-mutating operations (encryption migrations, schema migrations, repair commands, anything that writes to the user's database or filesystem at rest). Required: a real round-trip test against a real file, not in-memory stubs. Encrypt→decrypt identity, dry-run non-mutation, idempotency on re-run, NULL preservation.
   • External file-shape parsers (harness transcripts, exports, third-party config files). Required: at least one fixture per supported format that exercises the actual parsing code path (not just detectSource). For SQLite-backed formats, build the SQLite file in the test and parse it.
   • New CLI commands or flags (neotoma <new-command>, new flag on existing command). Required: a test that spawns or invokes the command with the flag and asserts the user-observable effect (file written, output emitted, exit code).
   • Discovery / detection / parser pairs that must agree on file layout. Required: a roundtrip test that asserts paths emitted by discovery are parseable by the parser.
   • HTTP server runtime configuration (timeouts, headers, connection behavior) that fails silently. Required: a test that asserts the runtime behavior, not just the source string. For timeouts, read the response header or socket behavior.

2. For each surface, classify the existing test coverage as one of:

   • Covers user-observable behavior end-to-end → no action needed.
   • Covers a helper function only → flag as a gap. The helper test does not prove the command/parser/migration works for users.
   • No test → flag as BLOCKING.

3. Write docs/releases/in_progress/vX.Y.Z/test_coverage_review.md with one section per surface, the classification above, and either a link to the satisfying test or a description of the test that needs to be added before execute.

Hard gate before Step 4: Any surface classified BLOCKING must be either tested before execute or explicitly deferred to a follow-up patch release with the user's approval recorded in the review file. Trust-but-verify: read the actual test bodies; do not accept "the test file exists" as evidence of coverage.

If new commits are added to satisfy this lane, rerun Step 3.5 (Security review lane) against the final HEAD before Step 4.

Step 3.7: Release candidate PR

Run after Step 3.6 passes. Push an RC branch and open a PR so the release can be reviewed publicly — with inline comments on the notes, CI, and a clear merge point — before anything is tagged or published.

1. Create and push the RC branch from the current integration branch (e.g. dev):

   git checkout -b release/vX.Y.Z
   git push origin release/vX.Y.Z
   

2. Open the PR targeting main, using the confirmed supplement as the PR body:

   gh pr create \
     --base main \
     --head release/vX.Y.Z \
     --title "Release vX.Y.Z" \
     --body "$(cat docs/releases/in_progress/vX.Y.Z/github_release_supplement.md)"
   

   The PR body gives reviewers the exact same narrative they will see in the GitHub Release notes.

2b. Post @claude review on the release PR immediately after opening it:

gh pr comment <PR_NUMBER> --body "@claude review"

The automated Opus review (claude_pr_review.yml) will run the full /review skill against the release diff and post findings as a github-actions[bot] comment. Wait for the review to complete, then check for Blocking findings:

gh api repos/{owner}/{repo}/issues/<PR_NUMBER>/comments \
  --jq '[.[] | select(.user.login == "github-actions[bot]" and (.body | length > 300))] | last | .body' \
  | grep -E "Blocker|MUST|request changes|NEEDS-CHANGES" || echo "No blockers found"

Hard gate: If the review verdict is NEEDS-CHANGES or any finding is labeled Blocker / MUST, resolve those findings before proceeding to Step 4. A review that returns only ADVISORY / NIT findings is not blocking.

3. Surface the PR URL to the user and STOP:

   "Release candidate PR for vX.Y.Z is open at <PR_URL>. Review, comment, and approve — then reply execute (or confirm merge) to continue with tagging, npm publish, and sandbox deployment."

   Do not proceed to Step 4 until the user explicitly confirms they are ready to execute. This is the public review window.

4. When the user confirms execute (either by replying execute, confirming they merged the PR, or explicitly approving):

   • If the PR is not yet merged, merge it now:

     gh pr merge release/vX.Y.Z --merge --delete-branch
     

   • Verify the merge landed on main before proceeding.

Note: If uncommitted changes were staged in Step 4.1 and not yet committed, commit them onto release/vX.Y.Z before pushing the branch. The PR must reflect the exact state that will be released.

Step 4: Execute

After the RC PR is merged and the user confirms execute, run every step below in order through npm publish and sandbox deployment. Stopping after gh release create or npm publish is a failed full /release unless the user confirmed a GitHub-only / no-registry / no-sandbox scope.

1. Commit uncommitted changes (when the preview assumed them and the user confirms execute):

   • Stage only paths that should ship; never stage paths forbidden by repository security / pre-commit rules (for example configured protected_paths, .env*, data/ when disallowed).
   • Prefer explicit git add <paths>; avoid blind git add -A when forbidden or local-only paths are present.

   git commit -m "Pre-release: include pending changes for vX.Y.Z"
   

   Skip this step if the working tree was clean at confirm time. If this step creates or changes any commit included in the release, rerun Step 3.5 before continuing to version bump, merge, tag, or push.

2. Bump version in package.json (and workspaces if monorepo):

   npm version X.Y.Z --no-git-tag-version
   git add package.json package-lock.json
   git commit -m "Bump version to vX.Y.Z"
   

3. Update SECURITY.md Supported Versions table if this release introduces a new minor (e.g. 0.12.x → 0.13.x):

   • Add the new minor series as supported.
   • Demote the oldest supported series to the unsupported row.
   • Stage and amend into the version bump commit, or create a separate commit.

4. Confirm main is up to date (the RC PR merge already landed the release commits on main):

   git checkout main
   git pull origin main
   

   Verify git log --oneline -5 shows the RC PR merge commit at HEAD. If the branch was merged via the PR in Step 3.7, no separate git merge dev is needed. If for any reason main does not reflect the RC commits, STOP and reconcile before tagging.

5. Tag:

   git tag -a "vX.Y.Z" -m "Release vX.Y.Z"
   

6. Push:

   git push origin main
   git push origin "vX.Y.Z"
   

7. Write supplement file: Save the confirmed changelog to docs/releases/in_progress/vX.Y.Z/github_release_supplement.md.

8. Render release notes:

   npm run -s release-notes:render -- --tag vX.Y.Z > /tmp/gh-release-vX.Y.Z.md
   

   If the last npm publish does not match the previous git tag, use --compare-base <last_published_tag>. This must reproduce the same body style shown in Step 3, now with the final tag/commit set.

9. Create or update GitHub Release draft:

   if gh release view "vX.Y.Z" --json isDraft --jq '.isDraft' 2>/dev/null | grep -q true; then
     gh release edit "vX.Y.Z" --title "vX.Y.Z" --notes-file /tmp/gh-release-vX.Y.Z.md
   else
     gh release create "vX.Y.Z" --title "vX.Y.Z" --notes-file /tmp/gh-release-vX.Y.Z.md --draft
   fi
   

   If a draft already exists it is updated in place; otherwise a new draft is created. In either case the release remains invisible to users and does not trigger the "latest release" pointer until published in step 11b. If gh release view returns a release that is not a draft, STOP — do not overwrite a published release without explicit user approval.

10. Publish to npm (mandatory for a full release): From the directory that owns the published package.json (repo or workspace root per your monorepo layout):

• Registry auth: If npm publish fails for auth or the session is stale, run npm login in an interactive terminal when needed.
• Web login URL (agent-assisted): When npm login prints Login at: https://www.npmjs.com/login?..., an agent with shell access may parse that URL from the CLI or terminal transcript and run open '<url>' on macOS or xdg-open '<url>' on Linux so the default browser loads the same page pressing Enter would open. Only use URLs that clearly come from official npm output for registry.npmjs.org / npmjs.com; prefer explicit user confirmation before opening browser or running open/xdg-open.

npm web-login checkpoint (mandatory — do not skip): Browser sign-in does not prove the same shell that will run npm publish has a valid token. After any web-login assist or when the user says they finished signing in:

1. Immediately run npm whoami in the same environment you use for npm publish (same repo root, same HOME / ~/.npmrc).
2. If npm whoami succeeds: State clearly that the session is authenticated, then run npm publish (and npm publish --otp=<code> when 2FA applies). Do not advance to sandbox until publish and registry verification succeed.
3. If npm whoami still fails (E401 / unauthorized) or npm login exited before completing (for example npm printed Exit handler never called): You must end the user-visible turn with an explicit handoff that includes all of the following — do not assume the user knows the next step:
   • Explain that the browser login authorized the browser, not necessarily the agent shell (or that the CLI session aborted before writing a token).
   • Give copy-paste commands for the operator to finish auth where npm publish will run (their own Terminal with the repo as cwd, or fixing ~/.npmrc / NPM_TOKEN for CI-style shells).
   • Ask them to reply ready (or confirm they ran npm publish locally and the registry shows X.Y.Z) so the next turn retries npm whoami then npm publish immediately without waiting for another vague ping.
4. If the user message is only “I signed in” / “done” in the browser: Treat that as a signal to run the checkpoint (step 1), not as permission to end the release thread without step 2 or step 3 text above.

npm publish

Do not treat the release as finished until this succeeds (capture or report the registry URL / version). Skip only if the user explicitly confirmed a scope that excludes npm (for example tag-only or internal).

After npm publish returns, confirm the registry actually reflects the new version before moving on:

npm view neotoma version

The output must equal X.Y.Z. If it still reports the previous version, the registry has not propagated yet — wait 30s and retry rather than advancing.