Release Readiness

The release gate is:

npm run release:check

That command runs npm run rust:check, then chains the advanced staged readiness gate through npm run check:v10. The base readiness path runs typecheck, tests, build, docs build, audit, package dry-run checks, package manifest hygiene, and mcp_readiness_report.

Local Checks

Run these before opening a release-sensitive PR:

npm run docs:build
npm run rust:check
npm run typecheck
npm test
npm run build
npm run release:check

Package Boundary

The package includes runtime output and docs:

• dist/
• bin/architect-mcp-tui.cjs
• Rust TUI workspace sources and lockfile
• packs/
• policy-bundles/
• foundation-packs/
• selected stack-sources/ metadata
• examples/
• docs/
• llms.txt
• README.md
• LICENSE
• SECURITY.md
• .env.example

Repo-only TypeScript readiness scripts and docs development scripts are stripped from the packed package.json during prepack.

npm Publishing

Publishing is handled by .github/workflows/npm-publish.yml when a GitHub release is published from a v* tag. The workflow:

• Uses pinned GitHub Actions.
• Runs in the npm-publish GitHub environment so maintainers can add required reviewers, tag restrictions, and environment-scoped secrets.
• Serializes publishes per tag with workflow concurrency so a duplicate release event cannot race another publish for the same ref.
• Installs with Node 24, upgrades npm to ^11.5.1 for provenance-capable publishing, and runs npm ci.
• Installs the pinned Rust 1.94.0 toolchain.
• Runs npm run release:check.
• Packs the package and installs the tarball in a temporary project.
• Publishes with npm publish --access public --provenance.

Current auth mode is token-backed, OIDC-ready publishing. The workflow requests GitHub Actions OIDC and uses npm 11.5.1+, but NPM_TOKEN remains the publish credential until the npm package has a trusted publisher configured. The token must be a granular automation token scoped to @tonycdr-prog/architect-mcp with publish rights and the required 2FA automation setting. Do not bypass npm run release:check; it remains the clean-checkout release gate.

Trusted Publishing Migration

npm trusted publishing can remove the long-lived publish token once the package is configured on npmjs.com. The repository workflow already has the release-side prerequisites: GitHub-hosted runner, id-token: write, Node 24, npm ^11.5.1, provenance-capable publish, and the clean npm run release:check gate.

The remaining setup happens in npm package settings, not in this repository:

1. Open @tonycdr-prog/architect-mcp on npmjs.com.
2. In package settings, add a trusted publisher for GitHub Actions.
3. Use owner tonycdr-prog, repository architect-mcp, workflow filename npm-publish.yml, and environment name npm-publish.
4. Run the next release without changing the release gate.
5. After a successful trusted-publishing release, remove NODE_AUTH_TOKEN from the publish step and delete the NPM_TOKEN GitHub secret.
6. Restrict publishing access to require 2FA and disallow traditional tokens if that policy fits the maintainer account.
7. Revoke the old automation token.

Until that npm-side configuration is complete, keep NPM_TOKEN in GitHub secrets so releases remain publishable. Do not commit tokens, paste token values into issues, or place token material in workflow logs.

Recommended GitHub environment settings for npm-publish:

• Required reviewer: repository maintainer.
• Deployment branch/tag rule: v* release tags only.
• Secrets: keep NPM_TOKEN here instead of as a broad repository secret while token-backed publishing remains enabled.
• After trusted publishing succeeds, remove NPM_TOKEN entirely and keep the environment as the human release approval gate.

Token Rotation

If token-backed publishing is still enabled, rotate the token after any suspected exposure, maintainer handoff, or release-process change:

1. Create a new granular npm token scoped to @tonycdr-prog/architect-mcp with publish rights and the required 2FA automation setting.
2. Update the GitHub Actions NPM_TOKEN secret.
3. Run npm run release:check locally from a clean checkout.
4. Publish the next tag or rerun the publish workflow for the intended release.
5. Verify npm view @tonycdr-prog/architect-mcp version and a fresh npx -y --package @tonycdr-prog/architect-mcp architect-mcp --help install path.
6. Revoke the previous automation token.

TUI Release Binaries

.github/workflows/tui-release.yml builds architect-mcp-tui for Linux x64, Linux ARM64, macOS x64, macOS ARM64, and Windows x64 release assets. Each archive is uploaded with a .sha256 checksum. The npm shim downloads only matching release assets and verifies the checksum before execution.

The shim follows HTTPS redirects for GitHub release asset and checksum downloads. .github/workflows/tui-install-smoke.yml runs the shim and release-binary build path across Ubuntu x64, Ubuntu ARM64, macOS, and Windows on pull requests and manual dispatch. .github/workflows/tui-live-qa.yml adds cross-platform TUI workflow smoke coverage. .github/workflows/tui-published-package-smoke.yml runs on a weekly schedule and manual dispatch against the already published npm latest package on Ubuntu and Windows, with TUI state isolated under a temporary ARCHITECT_MCP_WORKSPACE. Manual OS evidence is tracked in TUI Live QA.

.github/workflows/governance-audit.yml runs the read-only governance audit on manual dispatch and a weekly schedule. It writes a public-safe GitHub step summary rather than uploading raw local audit JSON. Governance reports and redaction rules live in Governance Audit.

GitHub Pages

The docs site builds with VitePress from the existing docs/ directory and uses base: "/architect-mcp/". The Pages workflow runs on pushes to main and manual dispatch, installs with Node 22, builds with npm run docs:build, uploads docs/.vitepress/dist, and deploys via GitHub Pages Actions.

After merge, repository Pages settings should use "GitHub Actions" as the Pages source.

Compatibility Gate Names

Historical check:v3 through check:v10 scripts remain because they protect compatibility and release confidence. Public docs describe these checks as advanced maturity, governance, operating-model, and productization boundary criteria rather than public product versions.