release-publish-runbook.md

Alpha Publish Readiness Runbook

Status: 0.1.0-alpha.6 is the published corrective alpha release; npm alpha and latest point at alpha.6 Last updated: 2026-07-02

This runbook records the publish and registry boundary for the alpha.6 corrective path. agent-cli-runtime@0.1.0-alpha.6 is the published corrective alpha release. npm alpha and latest dist-tags both point at 0.1.0-alpha.6. GitHub Release v0.1.0-alpha.6 exists as a prerelease with the npm registry tarball asset, and release:post-alpha:verify tarball parity passes. Future beta or stable promotion requires fresh release-candidate evidence, package-docs verification, dry-run, and explicit maintainer authorization. agent-cli-runtime@0.1.0-alpha.5 is published on npm as a stale-docs incident. GitHub Release v0.1.0-alpha.5 exists as a prerelease with the npm registry tarball asset and release:post-alpha:verify tarball parity passes. The immutable alpha.5 npm tarball contains stale package docs, so aggregate published verification (published:verify / published:verify:evidence) fails with registry_packaged_docs_failed. agent-cli-runtime@0.1.0-alpha.4 is published on npm and was previously on the alpha dist-tag. The immutable alpha.4 npm tarball contains stale release-prep package docs, so npm registry metadata is authoritative for alpha.4 version and dist-tags. GitHub Release v0.1.0-alpha.4 exists as a prerelease with the npm registry tarball asset, and release:post-alpha:verify tarball parity passes. agent-cli-runtime@0.1.0-alpha.2 is published, but its immutable npm tarball contains stale pre-publish package docs. agent-cli-runtime@0.1.0-alpha.3 is the historical corrective pre-alpha release for package consumers. agent-cli-runtime@0.1.0-alpha.1 remains earlier alpha history with GitHub pre-release v0.1.0-alpha.1, and agent-cli-runtime@0.1.0-alpha.0 is deprecated because its immutable package docs shipped stale pre-publish state. npm registry metadata and GitHub Releases are the source of truth for available versions and dist-tags.

This runbook does not create or commit npm credentials and does not configure trusted publishing. Current-head release-candidate run ids, artifact digests, tarball shasums, pack shasums, integrity values, and local temporary paths are recorded outside the npm package under .release-evidence/ or attached as GitHub Release assets; package docs keep only stable process rules, the alpha.2 stale package-docs incident, the alpha.3 corrective history, the alpha.4 npm publish state, the alpha.4 stale package-docs blocker, the alpha.4 GitHub Release asset/parity state, the alpha.5 published state and stale-docs incident, the alpha.6 published corrective release state, and the human-gated boundary for any further registry or release mutations.

Decision

Current state and future human gate:

• Package metadata is ready for an alpha package page: name, version, description, license, type, bin, main, types, exports, files, engines, repository, homepage, bugs, keywords, and publishConfig.tag are present and intentional.
• The package root value API remains createAgentRuntime only; public TypeScript types are exposed through the root declarations, not as runtime values.
• The release-candidate workflow remains artifact-only: it creates and verifies the tarball but does not publish and does not require registry credentials.
• Corrective target: agent-cli-runtime@0.1.0-alpha.6; alpha.6 is published.
• Future beta or stable promotion requires fresh release evidence and explicit maintainer authorization.
• Published alpha.5 stale-docs incident package: agent-cli-runtime@0.1.0-alpha.5.
• npm alpha dist-tag points at 0.1.0-alpha.6.
• npm latest dist-tag points at 0.1.0-alpha.6.
• GitHub Release v0.1.0-alpha.6 exists as a prerelease with the npm registry tarball asset, and release:post-alpha:verify tarball parity passes for alpha.6.
• GitHub Release v0.1.0-alpha.5 exists as a prerelease with the npm registry tarball asset, and release:post-alpha:verify tarball parity passes for alpha.5.
• Aggregate published:verify and published:verify:evidence fail for alpha.5 because registry packaged docs are stale (registry_packaged_docs_failed).
• Historical published package with stale docs: agent-cli-runtime@0.1.0-alpha.4.
• The immutable alpha.4 npm tarball contains stale release-prep package docs.
• GitHub Release v0.1.0-alpha.4 exists as a prerelease with the npm registry tarball asset, so release:post-alpha:verify tarball parity passes for alpha.4.
• P9-6 fresh main evidence exists for the alpha.4 package content; P9-7 publish/post-publish summaries and P9-9 alpha.5 post-publish summary live under .release-evidence/.
• Previous corrective release: agent-cli-runtime@0.1.0-alpha.3.
• Stale-docs incident package: agent-cli-runtime@0.1.0-alpha.2.
• Previous package: agent-cli-runtime@0.1.0-alpha.1.
• Previous GitHub pre-release: v0.1.0-alpha.1.
• agent-cli-runtime@0.1.0-alpha.0 is deprecated because its immutable package docs shipped stale pre-publish state.
• Future human-controlled publish path for beta, stable, or any later pre-release: use fresh release-candidate evidence for the package content being considered, run npm run package:docs:check, run npm publish --dry-run --ignore-scripts --tag alpha or the intentionally chosen tag for that release line, and require explicit maintainer authorization before any registry mutation.
• Future beta promotion or stable promotion requires fresh release evidence for that target, including package docs, registry state, GitHub Release parity, and published verification.
• Current-head evidence rule: trigger a fresh release-candidate workflow for the commit being considered, download all five artifacts, run npm run release:verify -- --dir <normalized-artifact-dir>, and record volatile run evidence under .release-evidence/.
• Package-content equivalence rule: use npm run release:package-content:verify -- --base-ref <release-target-sha> --head-ref <sha-or-ref> only to decide whether a later ref has the same npm package content as the recorded release target SHA. A freshReleaseCandidateRequired: true result requires fresh release-candidate evidence before publishing that later ref.
• Because this runbook and release report are included in the npm package, do not write current run ids, artifact digests, tarball shasums, integrity values, or pack shasums into package docs.
• Before any future real publish, confirm the fresh release-candidate workflow head SHA matches the commit being published.
• After any future real publish, run the manual published package verification workflow and download agent-cli-runtime-published-verification; verify it with npm run published:verify:evidence -- --dir <downloaded-artifact-dir> before accepting the new version.
• For alpha.5, GitHub Release tarball parity passes but aggregate published verification fails because immutable registry package docs are stale. Do not reuse alpha.5 evidence for alpha.6 post-publish acceptance, beta, or stable promotion.
• Do not reuse historical workflow runs as publish evidence for a later commit.

Boundaries

• Do not add npm tokens, GitHub tokens, registry credential environment variables, or private auth files.
• Do not configure real npm trusted publishing in this release line.
• Do not add daemon, database, WAL, remote worker, web UI, telemetry, scheduler expansion, or package-root value exports.
• Do not run npm publish, npm deprecate, or GitHub Release create/edit commands without explicit maintainer authorization.

Future Pre-Publish Checks

Run from the repository root on a clean checkout before any future package version is published:

git status --short
npm ci
npm run typecheck
npm run lint
npm test
npm run build
npm run package:check
npm run package:docs:check
tmp_dir="$(mktemp -d)"
npm run release:candidate -- --out-dir "$tmp_dir"
npm run release:verify -- --dir "$tmp_dir"
npm pack --dry-run
npm publish --dry-run --ignore-scripts --tag alpha
node ./dist/cli/main.js agents --json
node ./dist/cli/main.js doctor --json
git diff --check

Before a future real publish, also confirm the current branch and evidence target:

git rev-parse --abbrev-ref HEAD
git rev-parse HEAD
git rev-parse origin/main
npm run release:package-content:verify -- --base-ref <recorded-release-target-sha> --head-ref HEAD
gh workflow run release-candidate.yml --ref main
gh run view <current-release-candidate-run-id> --json headSha,status,conclusion,url,jobs
npm view agent-cli-runtime@0.1.0-alpha.6 version --json
npm dist-tag ls agent-cli-runtime

The dry-run command is the required local npm publish simulation for this stage:

npm publish --dry-run --ignore-scripts --tag alpha

The command must report a dry run and must show tag alpha. If it reports latest, fix the command or metadata before publishing.

Human Confirmation Points

Before a future real publish, a maintainer must confirm:

• The version is exactly the intended immutable npm version. A published name@version cannot be overwritten.
• The release-candidate run head SHA matches the commit being published; historical runs are insufficient for later commits.
• Package-content equivalence evidence, when used, compares the recorded release target SHA with the later ref by npm package file list and file-content hashes, not by gzip/tarball bytes alone.
• npm run package:docs:check, npm pack --dry-run, and npm publish --dry-run --ignore-scripts --tag alpha show only expected files and release-state wording.
• .reference/, .release-evidence/, tests/, fixtures, raw real CLI output, private paths, token-looking values, and repair backups are absent from the packed files.
• dist/index.js runtime value exports remain limited to createAgentRuntime.
• dist/index.d.ts exposes public types without re-exporting storage/parser/store internals as the package-root contract.
• The alpha tag is intentional. If there is still no stable version and npm also points latest at a pre-alpha, document that exact post-publish state outside packaged docs or in stable package wording that names the registry as authoritative.
• The npm account/package publishing policy is understood: 2FA or an approved token path is required by npm package settings.
• The publisher accepts the provenance choice below and has the right npm package permissions.

Real Publish Commands

Do not run these commands for a new version until the human publish gate is explicitly approved. Alpha.6 used the authorized manual local path.

Manual local publish with interactive npm authentication:

npm publish --tag alpha

If the package requires public access on first publish, the maintainer may need:

npm publish --tag alpha --access public

If npm asks for a second factor, complete the interactive 2FA prompt or use the npm CLI's supported OTP flow. Do not put an OTP, token, or session credential in committed files, shell history snippets, CI logs, docs, or issue comments.

Dist-Tag Verification

Immediately after any real publish:

npm view agent-cli-runtime@0.1.0-alpha.6 version dist-tags --json
npm dist-tag ls agent-cli-runtime
npm run published:verify -- --out-dir published-verification
npm run published:verify:evidence -- --dir published-verification

published:verify is the evidence generator. published:verify:evidence is the verifier and does not generate published-verification.json; missing default evidence is an expected guard failure with redacted JSON. For GitHub artifact review, download agent-cli-runtime-published-verification and pass --dir <downloaded-artifact-dir>.

Expected result:

• The package version being verified is the version created by the authorized publish.
• Registry dist-tags match the maintainer's intended pre-alpha policy for that authorized release.
• Published verification includes agent-cli-runtime.packagedDocsVerification.v1 for the npm registry tarball, and the registry package docs inspection must pass for the newly published version.
• The release:post-alpha:verify tarball parity gate must pass after the separately authorized GitHub Release step and registry tarball asset attachment.

If the wrong tag is attached but the package version itself is acceptable, fix the tag rather than republishing the same version:

npm dist-tag add agent-cli-runtime@0.1.0-alpha.6 alpha
npm dist-tag ls agent-cli-runtime

2FA, Token, And Provenance Strategy

Current decision:

• Preferred future automated path: npm trusted publishing from a dedicated GitHub Actions publish workflow with a human approval gate. This is not configured here.
• Preferred manual alpha path: interactive local npm publish --tag alpha by a maintainer with 2FA enabled and no committed tokens.
• Avoid long-lived npm automation tokens for this package unless trusted publishing cannot be used and a maintainer explicitly accepts the rotation, scope, and audit trade-off.
• Do not add registry credential environment variables to the existing ci.yml or release-candidate.yml workflows.

Trusted publishing boundary:

• npm trusted publishing uses OIDC from supported CI providers and is intended to avoid long-lived npm tokens.
• npm trusted publishing requires npm CLI and Node versions that satisfy npm's current trusted publishing requirements.
• A future trusted-publishing workflow would need its own publish file, package-side trusted publisher configuration on npmjs.com, id-token: write, a hosted runner, registry-url: https://registry.npmjs.org, and an explicit human approval/release trigger.
• Do not retrofit publish into .github/workflows/release-candidate.yml; keep that workflow artifact-only.

Provenance boundary:

• If publishing through trusted publishing, npm currently documents automatic provenance generation.
• If publishing with provenance through a token-based GitHub Actions workflow instead, the workflow would need the npm provenance path and OIDC permissions documented by npm. This repo has not configured that path.
• If publishing manually from a local machine, do not claim GitHub Actions provenance for that package. Manual local publish and CI trusted publishing are different evidence models.

Useful official references:

• npm trusted publishing: https://docs.npmjs.com/trusted-publishers/
• npm provenance: https://docs.npmjs.com/generating-provenance-statements/
• npm package 2FA publishing requirements: https://docs.npmjs.com/requiring-2fa-for-package-publishing-and-settings-modification/
• npm dist-tag CLI: https://docs.npmjs.com/cli/v9/commands/npm-dist-tag/
• npm unpublish policy: https://docs.npmjs.com/policies/unpublish/

Failure Handling

If dry-run fails:

• Stop before any registry mutation.
• Fix metadata, build output, package boundary, package docs, or auth state.
• Rerun the full pre-publish checks.

If real publish fails before package creation:

• Capture the redacted error class only.
• Do not commit npm debug logs if they contain local paths, auth state, or registry session details.
• Re-run npm view agent-cli-runtime@0.1.0-alpha.6 version --json before retrying to confirm the version was not created.

If real publish succeeds but post-publish checks fail:

• Do not republish the same version. npm package versions are immutable.
• If only dist-tags are wrong, fix the tags with npm dist-tag.
• If package contents are wrong, publish a new patch/pre-release version after fixing the repository state.
• If the package is unsafe and still eligible under npm policy, consider unpublish only as an emergency path:

npm unpublish agent-cli-runtime@0.1.0-alpha.6

Unpublish has strict policy limits and cannot make the same name@version reusable. If unpublish is not allowed or would break consumers, prefer deprecation:

npm deprecate agent-cli-runtime@0.1.0-alpha.6 "Do not use this alpha; upgrade to a later pre-release."

Rollback Boundary

Rollback means one of these actions:

• Move or remove an incorrect dist-tag.
• Deprecate a bad version with a clear warning.
• Unpublish only when npm policy allows it and a maintainer accepts the registry impact.
• Publish a new corrected pre-release version.

Rollback does not mean overwriting agent-cli-runtime@0.1.0-alpha.2, agent-cli-runtime@0.1.0-alpha.3, agent-cli-runtime@0.1.0-alpha.4, or agent-cli-runtime@0.1.0-alpha.5; npm does not permit replacing an already published package version.