/release

name: release
description: Cut a release — the order the steps must run in, and the criteria that abort a release
user-invocable: true
disable-model-invocation: true
argument-hint: "[X.Y.Z]"
model: inherit

Release

The user wants to cut a release of this package. Optional argument — the target version: **$ARGUMENTS**.

**The mechanism is `scripts/release.mjs`.** It exists, it is executable, and its pure half is unit-tested (`tests/scripts/release.test.mjs`). This skill carries only the two things the script cannot carry: the **order**, and the **criteria that stop a release**. Do not restate the script's internals here — `node scripts/release.mjs --help` and the file header are the reference.

Invocation

`$ARGUMENTS` is optional and holds the target version `X.Y.Z`. When it is empty, resolve the target from `package.json` and the CHANGELOG before step 2.

The flags this repo's release path uses — the operator-facing entry points, in the order they run:

• `node scripts/release.mjs --set-version X.Y.Z` — rewrite every version surface and sync `package-lock.json`.
• `node scripts/snapshot-probe.mjs --local --json` — under `mirror: curated`, run what GitHub runs on the tree GitHub gets (the release commit's export) before anything is pushed; `--check` requires its receipt.
• `node scripts/release.mjs --check --json` — the preflight gate; every row must be green.
• `node scripts/release.mjs --publish` — stages the release (ADR-0018 route C): `npm stage publish`, proof, stop; the owner approves on npmjs.com with 2FA, then `--resume-tail --target X.Y.Z` runs the tail. `--publish --direct` is the pre-2027 one-run route; start that one in the background, never under a `timeout` wrapper (step 9). Route detail: `skills/npm-publish/SKILL.md` § Route C.
• `node scripts/release.mjs --publish --trusted` — opt-in route B (ADR-0018): no local `npm publish`; the tag push on the GitHub mirror starts the trusted-publishing workflow, the owner approves the run in the GitHub environment `npm-publish`, and the script verifies the receipt on the registry. Refused with `--direct`. If it ends `awaiting-workflow` (exit 1), approve the run, then `--resume-tail --target X.Y.Z`. Route detail: `skills/npm-publish/SKILL.md` § Route B.

`--skip-ci` marks the CI row green without checking anything and is **refused by the script** when combined with `--publish`; it is an inspection aid for `--check`, never a release path.

Why the order is written down

`3.18.0` has a git tag, a GitHub release and a CHANGELOG entry — and the npm registry never saw it; a checklist line is not a mechanism.

Verify it yourself before trusting the paragraph above:

npm view session-orchestrator versions --json          # read 2026-08-19: 3.16.0, 3.17.0, 3.19.0, 3.20.0 — no 3.18.0
git for-each-ref --format='%(refname:short) %(creatordate:short)' refs/tags
gh release list --repo Kanevry/session-orchestrator --limit 12

The same reading shows the other half: the GitHub releases for 3.15/3.18/3.19/3.20 were all created on 2026-08-19 within a three-second window — 5 to 31 days after their tags. Every step that lives only in prose gets skipped and backfilled later.

The order

1. **Preconditions.** Working tree clean, on `main`, `origin/main` level with `HEAD`, and the GitHub mirror current. The mirror is checked because the site deploy hangs off `github`, not `origin`. What "current" means follows Session Config `mirror` (`--check` row `github-mirror-mode` names it): under `mirror: github` (or unset), `github/main` equals `HEAD`; under `mirror: curated` (#1645), GitHub never receives `HEAD` — `github/main` is a squash snapshot whose `Source-Commit:` trailer must name `HEAD` (publish it with `/close` on `main`, session-end § 4.4). `docs/github-mirror-protection.md` § Releases under `mirror: curated`. 2. **Set the version.** `node scripts/release.mjs --set-version X.Y.Z` — rewrites every version surface, syncs `package-lock.json`, re-stamps the measured census on the site. 3. **Write the editorial half.** The dated `## [X.Y.Z] - YYYY-MM-DD` CHANGELOG entry, `[Unreleased]` folded, README highlights. The script does not write these; `--check` enforces them. 4. **Gate, commit.** Full quality gate, then commit. Do not push yet. 5. **Probe the export (under `mirror: curated`), before the push.** `node scripts/snapshot-probe.mjs --local --json` — builds the curated tree of `HEAD` (the release commit) and runs on it what GitHub's `test` job runs. The question it answers: does what GitHub runs pass on what GitHub gets? Since the slim mirror (#1594) the policy carries an `include` list, GitHub gets no `tests/`, vitest or eslint config, and its `test` job runs `npm run test:mirror` (`scripts/ci/plugin-smoke.mjs`: manifests, syntax, runtime dependencies, SessionStart). The probe's `test` step runs the same smoke, in about a minute; validate-plugin is not a default step there, because it reads files the mirror does not carry. The full suite runs on GitLab (step 7). The probe needs no remote and no pushed commit. Run it here, not after the push: 5.13.0 found three blockers only after its first curated push (#1712), when the release commit was already on `main`, and the fixes took two more MRs (!223, !224). A red probe here is fixed before anything leaves this machine.

• **Host:** the smoke is light, so `node scripts/snapshot-probe.mjs --local` is the route. `node scripts/snapshot-probe.mjs --host <alias>` runs the pre-push router's full gate on that host and exits 2 under an `include` list, since that gate cannot pass on a tree without tests; it applies only to a policy without one (the pre-#1594 mirror). A host that is unknown, not ready or falls back exits 2 and writes no receipt.
• **Exporter version:** an allow-list policy (version 2) needs export code at or after commit 482cd32a. An older plugin root refuses it with a policy-version error and publishes nothing; run the export (and `/close`) with `PLUGIN_ROOT` set to a