release: SpecBridge v1.0.0

[HelloThisWorld]

Summary

Final stabilization and public-release phase for SpecBridge v1.0.0. This is
not a feature-expansion release: it makes the existing v0.1–v0.7.1 product
stable, installable, recoverable, documented, secure, and releasable. The
product promise is unchanged — start in Kiro, continue anywhere, return
whenever you want — and it is now backed by documented, machine-checked
contracts.

Every public contract is inventoried and frozen behind machine-readable
snapshots; persisted state gained an explicit migration framework, read-only
validation, and hash-bound recovery; and the release itself is now
reproducible across platforms with checksummed assets.

Stable contracts

Ten contract areas are inventoried in
docs/stability/public-contracts.md with
per-area compatibility promises, and the versioning/deprecation policy lives in
docs/stability/versioning-policy.md.
Machine-readable snapshots under contracts/ freeze the CLI
command tree and exit codes, JSON report IDs, every persisted schemaVersion,
verification rule IDs SBV001–SBV026, the runner adapter vocabulary,
template and extension contracts, MCP tool/resource/prompt names, Claude Code
Skill names, and the GitHub Action interface. CI fails on drift via
pnpm check:public-contracts, so a stable contract cannot change without an
intentional snapshot update.

No persisted schema version changed in this release.

Migrations and recovery

A single migration framework replaces ad-hoc migration code:

• specbridge migrate status | plan | apply | verify — plans are hash-bound to
  exact file bytes, applies are atomic with backups and rollback, dry-run
  writes nothing, and applying twice is a no-op. Reports land under
  .specbridge/migrations/<id>/.
• specbridge state validate — read-only diagnosis across every state family.
• specbridge state recover --plan | --apply <id> — plan-only by default;
  applying requires an acknowledgement token derived from the plan hash and
  re-validates every file hash first.
• specbridge doctor --repair-plan — read-only recovery preview.

Recovery is structurally constrained: it can only act inside .specbridge/, so
.kiro, .git, and project sources are out of reach. Corrupted files are moved
to quarantine, never destroyed, and approvals, evidence, and completed tasks are
never invented. The only real historical migration is config v1 → v2; the guide
says so honestly rather than inventing migrations that never existed.

Security

docs/security/threat-model.md consolidates
the per-subsystem models into 29 threats with mitigations verified against
source, plus explicit non-claims. A deterministic scan (pnpm check:security)
guards against credentials, private keys, .env inclusion, permission-bypass
strings, eval/Function, absolute build paths, and source maps in release
bundles.

Performance

A large-repository suite (500 specs / 10,000 tasks, large diffs, 500
templates/extensions, MCP pagination) with generous CI budgets is documented in
docs/performance.md. Two findings are recorded honestly
rather than silently "fixed" during stabilization: single-spec reads perform a
full workspace discovery, and MCP spec_list analyzes all specs per page. Both
are within budget and are not regressions.

Packaging

• npm package is specbridge-cli — the bare name specbridge is taken on
  npm by an unrelated project. The bin and command remain specbridge. The
  published bundle includes the workspace packages, proven by an isolated
  npm install smoke test.
• Standalone archives for windows-x64, linux-x64, macos-x64, macos-arm64 with a
  pinned, hash-verified Node 20.20.2 runtime, plus a portable-node archive and
  the Claude Code plugin ZIP.
• Every archive carries a release manifest (schema/contract versions, SHA-256
  file list, no absolute paths); SHA256SUMS.txt/.json verify independently.
• release.yml is tag-driven and draft-first, publishes only after asset
  verification, never clobbers an existing tag or Release, and grants
  contents: write to the publish job alone. workflow_dispatch runs it as a
  build-only dry run.

Documentation

Documentation was reorganized additively around a new hub
(docs/README.md) so no existing link breaks, with new
getting-started guides, a migrations hub, migration guide, release notes, and a
dependency inventory. The README first screen was rewritten for launch. Three
new offline examples and reproducible demo scripts are validated in CI.

Release gates (all pass locally)

Gate	Result
lint / typecheck / build	pass
full test suite	1266 pass (baseline was 1180)
check:public-contracts / check:security / check:mcp-docs	pass
plugin validation + isolated bundle verification	pass (11 skills, 1.0.0)
galleries, registries, CLI smoke (47), examples (26)	pass
npm package validation (14 checks, isolated install)	pass
standalone packaging (portable-node + windows-x64 smoke, linux archive)	pass
sha256sum -c over assembled assets	all verify

Reviewer notes

• macOS x64/arm64 archives build on native CI runners and could not be
  smoke-tested on the Windows development machine; the release matrix builds
  each platform natively.
• assemble-release.mjs --verify-remote is implemented but only exercisable
  against a real published Release.
• specbridge config migrate is retained as a deprecated alias (stderr notice,
  removal no earlier than v2.0.0); JSON stdout stays clean.
• The GitHub Action version was aligned from 0.6.0 to 1.0.0, and template and
  extension compatibility ranges widened to <2.0.0.

Known limitations (documented, not defects)

• Extension isolation is process-level, not an operating-system sandbox.
• Checksums verify integrity, not publisher identity; registry listing is
  not endorsement.
• Released binaries may be unsigned.
• Model-assisted authoring and execution remain nondeterministic.
• Antigravity integration remains experimental.

Checklist

• pnpm lint, pnpm typecheck, and pnpm test pass locally
• pnpm check:public-contracts passes — snapshots are introduced in this
  PR as the initial frozen baseline
• Documentation updated for any user-visible behavior change
• CHANGELOG entry added for any user-visible change
• Everything is in English (code, comments, docs, commit messages)
• No employer or client proprietary content — examples and fixtures are
  synthetic
• No credentials, tokens, or secret values anywhere in the diff, fixtures,
  or recorded test output

Security-relevant invariants touched: migration and recovery are hash-bound and
refuse stale plans; recovery cannot escape .specbridge/; protected paths and
archive/symlink defenses are unchanged and now documented centrally.