Release Publish

Release Publish

Use this skill when releasing senpi with the canonical CalVer flow, pushing a release tag, publishing the GitHub Release, or publishing packages to npm.

Canonical release flow

Run scripts/release.mjs from a clean main checkout.

• Confirm you are on main.
• Confirm the worktree is clean.
• Confirm the release version is a valid CalVer.
• Run the changelog audit before release.
• Make only product-facing release notes from packages/coding-agent/CHANGELOG.md via scripts/release-notes.mjs.
• Skip housekeeping, upstream-sync, and generated-catalog-only entries.
• Duplicate user-facing ai/agent/tui changes into the coding-agent changelog.
• Run npm run check.
• Run npm run build.
• Run CI=1 npm test.
• Create the release commit.
• Create the release tag.
• Create the next-cycle changelog commit.
• Push main and the tag.

Pre-flight checklist

• Read the current release rules in AGENTS.md and scripts/AGENTS.md.
• Use a clean dedicated clone if the main checkout has foreign state.
• Never clean, stash, or otherwise disturb other people's work.
• Use the protected-main path when needed; UPSTREAM_AUTOMATION_TOKEN exists for authenticated protected-main pushes.
• npm publish is delegated: the tag pipeline's publish-npm job no longer publishes — it dispatches publish-npm.yml in publish-only mode (the proven route from the v2026.7.28-x and v2026.8.4 recoveries) and gates the public GitHub Release on that run's success. npm's trusted publisher matches the publish-npm.yml workflow identity only; never reintroduce a direct publish or an environment: on the publish path (the environment subject is what npm rejects).
• Do not rerun scripts/release.mjs after the tag has been pushed.
• If checks fail before the tag push, fix first, then re-release from the beginning.
• Treat E404 noise for @code-yeongyu/senpi-orchestrator as non-fatal.
• Use node scripts/release-notes.mjs / the cl.md audit before publishing notes.
• Keep release notes product-facing only.

Publish watch

After tag push, watch the build-binaries workflow run (find the run id via gh run list --workflow=build-binaries.yml --branch main --limit 1 --json databaseId -q '.[0].databaseId').

The publish-npm job dispatches publish-npm.yml in publish-only mode, prints the dispatched run URL, waits up to 60 minutes, and fails if the publish run fails. There is no environment approval gate on the publish path — the old npm-publish environment subject is exactly what npm's trusted-publisher registration rejects.

Never consider the release done before publish-npm and publish-github-release complete and the GitHub Release is non-draft. If the publish job fails, recover with gh workflow run publish-npm.yml -f version=<v> -f publish-only=true, never by rerunning release.mjs.

Gate disambiguation

These are separate controls and must not be conflated:

• GitHub Environment approval: removed from the publish path (the npm-publish environment subject is what npm rejects); the unused environment may remain in repo settings harmlessly.
• npm OIDC trusted publishing: the npm-side trusted publishing path used by the job.
• npm lifecycle-script review: the npm approve-scripts --allow-scripts-pending trust review, which is not publish approval.
• Protected-main authorization: the authenticated push path for protected main, which is distinct from publish approval.

Hazards and hard rules

• Protected-main push failures are expected if the token path is wrong; use UPSTREAM_AUTOMATION_TOKEN for the authenticated release push path.
• The tag pipeline publishes only through the dispatched publish-npm.yml identity (see Pre-flight checklist). If npm-side config changes, re-verify with a dry_run dispatch before the next release.
• Never rerun scripts/release.mjs after the tag is pushed. If publishing fails, recover from the existing tag workflow.
• If a check or test fails before the tag push, stop and fix the issue, then re-release. Do not try to salvage a bad release by continuing past the failure.
• E404 noise for @code-yeongyu/senpi-orchestrator is not a release failure.
• An npm PUT 404 during npm publish can be a false negative: the publish may have landed anyway (observed live on 2026-07-28 with @code-yeongyu/senpi@2026.7.28-2 — the job failed but the version exists). ALWAYS verify with npm view <pkg> versions --json before treating a publish error as real, before rerunning anything, and before declaring a release failed.
• A failed publish-npm job skips publish-github-release and triggers the draft-cleanup path; check gh release view v<version> before recovering — the release may already be live. Recover only through the existing tag workflow, never by rerunning release.mjs.
• If the main checkout has foreign state, use a clean dedicated clone/worktree. Never clean or stash someone else's work.

Release notes provenance

• Extract notes only from packages/coding-agent/CHANGELOG.md via scripts/release-notes.mjs.
• Keep changelog entries product-facing.
• Run the cl.md audit before release.
• Skip housekeeping, upstream-sync, and generated-catalog-only changes.
• Duplicate user-facing ai, agent, and tui changes into the coding-agent changelog so the release notes stay complete.

Post-release verification checklist

• build-binaries is complete.
• stage-github-release is complete.
• publish-npm is complete.
• publish-github-release is complete.
• The npm registry resolves the published version.
• The GitHub Release is published and non-draft.

Notes

• The canonical release path is scripts/release.mjs from clean main.
• The approval checkpoint is mandatory for the normal tag-driven release.
• Publishing today goes through the publish-npm.yml publish-only dispatch (see the known-broken note above), NOT the tag pipeline's environment-gated job.
• If the tag pipeline's publish-npm fails after stage-github-release succeeded, the cleanup path deletes the draft release; the build assets survive as the run's release-assets-v<tag> artifact — re-create the release with gh release create <tag> --verify-tag --draft --title <tag> --notes-file RELEASE_NOTES.md <assets> and publish with gh release edit <tag> --draft=false after verifying npm view shows every package.