release: harden and prepare 0.3.1 publication

[chtnnh]

Summary

Prepare the 0.3.1 release across the CLI, GitHub Action, package metadata, changelog, and generated versioned documentation.

• Align every current 0.3.1 pin: root and workspace package manifests/lockfile, Action defaults and examples, CLI-generated workflow references, and documentation.
• Add the 0.3.1 frozen documentation snapshot and sidebar, then register it in the version manifest.
• Harden the release workflow: require an exact tag/package-version match, require and re-check main ancestry before publication, safely distinguish an existing matching npm publish from a conflicting one, and verify npm gitHead, SLSA provenance, and signatures.
• Harden documentation deployment: validate the published package provenance before release docs are deployed, serialize Pages deployments, and verify the release/version manifest and current main immediately before deployment.
• Prevent release-history drift with an immutable versioned-docs provenance check. It rejects removed, reordered, rewritten, or side-branch/failed-release snapshots while preserving the pre-versioned legacy baseline.
• Add release-contract fixtures for mismatched tags, transactional and idempotent pin updates, invalid versions, deleted or rewritten snapshots, and unrelated tags.

Validation

• npm run lint -- --max-diagnostics=100
• npm run build
• npm test — 219/219 passing
• npm run smoke
• npm run smoke:verify
• npm run build:docs
• npm pack -w @chtnnh/know-code --dry-run --json
• git diff --check
• Two independent GPT-5.6 Sol xhigh correctness reviews — clean

Release prerequisite

Before pushing v0.3.1, protect v* tags in the repository rulesets against updates and deletion. The workflow checks fetched refs defensively, but server-side tag protection is needed to close the final remote tag-mutation race.

[cursor]

PR Summary

Medium Risk
Changes critical release and GitHub Pages pipelines and npm publish behavior; mistakes could block releases or deploy wrong docs, though checks are largely fail-closed with new regression tests.

Overview
Prepares 0.3.1 by aligning version pins (monorepo, CLI, GitHub Action defaults, init --workflow references, CI docs) and adding a frozen version-0.3.1 Docusaurus snapshot plus website/versions.json entry. Docs policy text now says every npm release gets a versioned cut and Pages deploys on every main push (not only website/** changes).

Release and Pages CI gain a coordinated safety layer: new check-release-tag.mjs and check-release-docs-provenance.mjs enforce tag/package parity, main ancestry, immutable version manifests, and byte-stable frozen docs (blocking dropped, reordered, or rewritten snapshots). release.yml runs those checks twice around publish, verifies the remote tag has not moved, publishes with --provenance (SLSA + signature audit, idempotent skip when gitHead already matches), upserts GitHub Releases, and adds a deploy-docs job. docs.yml only deploys after the latest declared version exists on npm with matching gitHead and provenance; Pages uses queued concurrency and confirms main has not advanced before deploy.

Tooling/tests: bump-release-pins.mjs is transactional and covers more pin sites; release-contract.test.ts locks workflow shape and provenance edge cases; CLI tests assert version from package.json instead of hard-coded semver.

^{Reviewed by Cursor Bugbot for commit 15e0f44. Bugbot is set up for automated code reviews on this repo. Configure here.}