release: SpecBridge v1.0.0 (#12)

* feat(core): add unified state-migration framework and hash-bound recovery engine

Generic, schema-agnostic plan/apply/report/verify migration engine plus a
recovery engine restricted to safe action kinds inside .specbridge/. Plans
are hash-bound to exact file bytes; applies are atomic with backups and
rollback; recovery preserves originals in quarantine and appends to an
append-only log. Nothing runs automatically; CLI wiring follows.

* chore(release): bump every package and manifest to 1.0.0

Root, all workspace packages, CLI/MCP/extension-SDK/Action version
constants, plugin and marketplace manifests. Template and extension
compatibility ranges widen from <1.0.0 to <2.0.0 (scaffolds now emit
>=1.0.0 <2.0.0); built-in packs, registry index/entries, and galleries
regenerated; version-sensitive tests updated. Plugin and Action dist
rebuilds follow once the new CLI commands land.

* docs: add v1.0.0 stability contracts, threat model, and community files

docs/stability/{public-contracts,versioning-policy}.md inventory every
public contract with per-area stability promises. docs/security/
threat-model.md consolidates the per-subsystem threat models (29 threats
with mitigations verified against source) and states explicit non-claims.
Adds SECURITY/SUPPORT/CONTRIBUTING/CODE_OF_CONDUCT, issue forms, PR
template, release checklist, and the temporary v1.0.0 resume document.

* feat(release): add public-contract snapshots, MCP doc generation, and security scan

Machine-readable contract snapshots under contracts/ (CLI tree, exit codes,
report IDs, schema versions, verification rules, runner/template/extension
contracts, MCP names, Skill names, Action interface) enforced by
pnpm check:public-contracts. Adds pnpm generate/check:mcp-docs (tool-reference
generated from the authoritative registry) and pnpm check:security
(deterministic scan for credentials, bypass strings, and bundle paths).
Wires the new checks plus example validation into CI and adds a tag-driven,
draft-first release workflow with a workflow_dispatch dry-run mode.

* feat(cli): add migrate, state validate/recover, and setup commands

Wires the migration framework and recovery engine into the CLI:
  specbridge migrate status|plan|apply|verify  (--dry-run/--json/--backup-directory/--target)
  specbridge state validate                    (read-only; per-family diagnosis)
  specbridge state recover --plan|--apply <id> (acknowledgement-token gated)
  specbridge doctor --repair-plan              (read-only recovery preview)
  specbridge setup                             (preview-first initialization)
config migrate becomes a deprecated alias (stderr notice; removal >= v2.0.0).
Adds the state-family registry, corruption fixtures, and 66 tests covering
migration idempotency/atomicity/rollback, read-only validation, hash-bound
recovery, quarantine preservation, and the never-invent-approvals guarantees.

* test(perf): add large-repository performance suite and budgets

500-spec / 10,000-task deterministic fixtures plus 12 gated measurements
(workspace detection, spec discovery, drift verification, template/extension/
registry search, affected-spec detection, MCP pagination, report generation,
peak memory) with generous CI budgets and stable 'perf:' benchmark logs.
docs/performance.md records methodology, indicative numbers, and two honest
findings (single-spec read does full discovery; MCP spec_list analyzes all
specs per page). Also pins the MCP stdio version assertions to the constant.

* docs(examples): add maintained example projects and offline demo scripts

Three new offline, deterministic examples validated in CI: claude-code-workflow
(plugin flow + committed approvals), ci-drift-gate (verification policy +
GitHub Action + trusted commands), and template-and-extension (template
search/preview + safe analyzer flow). Adds scripts/validate-examples.mjs
(26 checks over temp copies), scripts/demo.{sh,ps1} (offline drift demo,
both run green), and docs/launch/demo-recording.md.

* docs: reorganize documentation around a hub, rewrite README, add 1.0.0 CHANGELOG

Additive documentation architecture: docs/README.md hub over the existing
flat pages plus new getting-started/ (installation, quickstart, existing-kiro
-project, claude-code-plugin), migrations hub, and dependency inventory.
README first screen follows the launch layout (positioning, workflow,
30-second quickstart, honest maturity/security note). CHANGELOG gains the
1.0.0 entry; roadmap marks v0.7.1 and v1.0.0 shipped; verification-rules
documents SBV026.

* chore(release): publish CLI as specbridge-cli and rebuild bundled artifacts

The bare npm name 'specbridge' is taken by an unrelated project, so the
package is named specbridge-cli; the bin and command stay 'specbridge'. tsup
bundles the @specbridge/* workspace packages into the published dist so the
package installs standalone, with an explicit files allowlist (no source
maps, tests, or fixtures) and committed LICENSE/NOTICE/README. Rebuilds the
plugin and GitHub Action bundles at 1.0.0 and adds the release QUICKSTART.

* feat(release): add cross-platform packaging, checksums, and release notes

scripts/package-standalone.mjs builds portable-node and per-platform archives
(windows-x64/linux-x64/macos-x64/macos-arm64) with a pinned, hash-verified
Node 20.20.2 runtime, a per-archive release manifest (schema/contract
versions, SHA-256 file list, no absolute paths), and on-platform smoke tests.
scripts/validate-npm-package.mjs enforces the files allowlist and proves the
packed specbridge-cli tarball installs and runs in isolation.
scripts/assemble-release.mjs emits SHA256SUMS.txt/json and a combined release
manifest, failing on any missing expected asset. Adds the v1.0.0 migration
guide and release notes, fixes the plugin-ZIP path in release.yml, ignores
dist-release/, and widens the doc example compatibility ranges to <2.0.0.

* release: prepare SpecBridge v1.0.0

Removes the temporary release working document. All local release gates pass:
lint, typecheck, 1266 tests, build, public-contract snapshots, security scan,
MCP-doc drift, plugin validation + isolated bundle, template/extension
galleries and registries, CLI smoke (47), example validation (26), npm
package validation (14, isolated install), and standalone packaging
(portable-node + windows-x64 smoke, linux archive, checksummed release
manifest). Versions are consistently 1.0.0.

No remote operation performed; publication awaits explicit authorization.

* fix(ci): rebuild plugin bundle and isolate the performance suite

Two CI failures on the v1.0.0 PR:

The committed Claude Code plugin bundle predated the `setup` command, so
CI's reproducibility check (git diff over the bundled dist) failed on Linux.
Rebuilt from current source; a second build is now byte-identical.

The large-repository performance suite builds ~9,000-file fixtures and real
git history inside the main worker pool, which starved vitest's worker RPC on
loaded runners: every test passed but the run still failed with an unhandled
"Timeout calling onTaskUpdate" error (seen on windows/node-20). The suite now
runs separately via `pnpm test:perf` (vitest.perf.config.ts, serial, generous
timeouts) and CI runs it as its own step on one matrix combination, matching
the policy of treating performance numbers as informational benchmarks.

Main suite: 92 files / 1254 tests. Perf suite: 12 tests. Both green, with no
unhandled errors.

* ci: pin the skill-verification template to v0.2.0

SpecBridge 1.0.0 widens built-in template and reference-extension
compatibility ranges to '<2.0.0' (the old '<1.0.0' bound excluded 1.0.0
itself, failing every built-in template with SBT006). That is a real change
in grounded CLI output, so the pinned fixture in
agent-skill-verification-template was regenerated and tagged v0.2.0; this
pins the new ref. The verifier release pin (ASV_VERSION/ASV_SHA256) is
unchanged.

Author: HelloThisWorld

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "specbridge",
       "source": "./integrations/claude-code-plugin/specbridge",
       "description": "Kiro-compatible spec workflows, verified interactive task execution, and deterministic drift checks.",
-      "version": "0.7.1",
+      "version": "1.0.0",
       "license": "MIT",
       "keywords": [
         "spec-driven-development",

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,84 @@
+name: Bug report
+description: Report a reproducible problem in SpecBridge
+title: "[bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report. Reproducible bugs in documented behavior — especially anything
+        touching the security model or `.kiro` file integrity — get priority.
+
+        **Security issues do not belong here.** Report them privately per
+        [SECURITY.md](https://github.com/HelloThisWorld/specbridge/blob/main/SECURITY.md).
+  - type: input
+    id: version
+    attributes:
+      label: SpecBridge version
+      description: Output of `specbridge --version`, plus how you installed it (npm, plugin, source).
+      placeholder: "1.0.0 (npm)"
+    validations:
+      required: true
+  - type: input
+    id: platform
+    attributes:
+      label: Platform
+      description: Operating system and version.
+      placeholder: "Windows 11 Pro 26100 / macOS 15.3 / Ubuntu 24.04"
+    validations:
+      required: true
+  - type: input
+    id: node-version
+    attributes:
+      label: Node.js version
+      description: Output of `node --version` (Node >= 20 is required).
+      placeholder: "v20.17.0"
+    validations:
+      required: true
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: The exact command you ran and what SpecBridge did, including error output.
+      placeholder: |
+        Command:
+        Output:
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+      description: What documented behavior you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: doctor-output
+    attributes:
+      label: "`specbridge doctor` output"
+      description: >
+        Paste the output of `specbridge doctor --json` with sensitive paths redacted.
+        It prints no secret values by design, but paths can reveal machine or project names.
+      render: json
+    validations:
+      required: false
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction steps
+      description: >
+        The smallest sequence that reproduces the issue — ideally against a tiny synthetic
+        `.kiro` workspace. Numbered steps beat prose.
+      placeholder: |
+        1. Create a workspace with ...
+        2. Run `specbridge ...`
+        3. Observe ...
+    validations:
+      required: true
+  - type: checkboxes
+    id: hygiene
+    attributes:
+      label: Report hygiene
+      options:
+        - label: I removed all credentials, API keys, and proprietary company content from this report.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Documentation
+    url: https://github.com/HelloThisWorld/specbridge/tree/main/docs
+    about: Guides for every area — start here for usage questions before opening an issue.
+  - name: Security reports (private)
+    url: https://github.com/HelloThisWorld/specbridge/blob/main/SECURITY.md
+    about: Never report vulnerabilities in a public issue — see the reporting instructions.

.github/ISSUE_TEMPLATE/extension_contribution.yml

@@ -0,0 +1,83 @@
+name: Extension contribution
+description: Propose an extension for the community registry index
+title: "[extension] "
+labels: ["extension", "registry"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        The registry lists **metadata only** — your code stays in your repository and your
+        archive stays on your HTTPS host. Read
+        [registry/CONTRIBUTING.md](https://github.com/HelloThisWorld/specbridge/blob/main/registry/CONTRIBUTING.md)
+        first: the actual contribution is a pull request adding
+        `registry/entries/<your-extension-id>.json`; this issue is for proposing and
+        discussing it.
+
+        Before filing, your extension should pass:
+        ```
+        specbridge extension validate ./my-extension
+        specbridge extension conformance ./my-extension --yes
+        specbridge extension package ./my-extension
+        ```
+  - type: input
+    id: extension-id
+    attributes:
+      label: Extension ID
+      description: "Must match the extension ID grammar: lowercase letters and digits in hyphen-separated segments, starting with a letter, max 64 characters."
+      placeholder: "security-analyzer"
+    validations:
+      required: true
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Kind
+      options:
+        - template-provider
+        - analyzer
+        - verifier
+        - exporter
+        - runner
+    validations:
+      required: true
+  - type: input
+    id: repo-url
+    attributes:
+      label: Source repository URL
+      description: Public HTTPS URL of the extension's source repository.
+      placeholder: "https://github.com/you/security-analyzer"
+    validations:
+      required: true
+  - type: textarea
+    id: checksum
+    attributes:
+      label: Archive hosting and checksum
+      description: >
+        The stable, credential-free HTTPS URL of your packaged
+        `.specbridge-extension.zip` and the exact archive SHA-256 printed by
+        `specbridge extension package`. The registry entry must carry both for every version.
+      placeholder: |
+        archiveUrl: https://github.com/you/security-analyzer/releases/download/v1.0.0/security-analyzer-1.0.0.specbridge-extension.zip
+        sha256: <64 hex characters>
+    validations:
+      required: true
+  - type: textarea
+    id: permissions
+    attributes:
+      label: Permissions requested
+      description: >
+        The exact `permissions` block from your manifest (specRead, repositoryRead,
+        repositoryWrite, network, childProcess, environmentVariables). It must match the
+        manifest inside the archive byte-for-byte — understating permissions is grounds
+        for removal.
+      render: json
+    validations:
+      required: true
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Registry terms
+      options:
+        - label: I understand that registry listing is not endorsement, review, or a security guarantee, and that checksums prove integrity, not publisher identity.
+          required: true
+        - label: My entry declares every permission the manifest declares, my archive is hosted at a stable credential-free HTTPS URL, and I will publish new versions as new entries rather than changing published archives in place.
+          required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,44 @@
+name: Feature request
+description: Propose an improvement or new capability for SpecBridge
+title: "[feature] "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Feature discussions work best when grounded in a concrete problem. Note that some
+        requests are bounded by the project's invariants — SpecBridge will not add features
+        that execute untrusted content, bypass permission systems, treat model claims as
+        evidence, or mutate `.kiro`/Git state automatically.
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What are you trying to do that SpecBridge currently makes hard or impossible? Describe the workflow, not just the missing flag.
+    validations:
+      required: true
+  - type: textarea
+    id: proposed-solution
+    attributes:
+      label: Proposed solution
+      description: How you imagine it working — CLI commands, configuration, MCP tools, output. Sketches welcome.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you tried or considered (including workarounds, templates, or extensions) and why they fall short.
+    validations:
+      required: false
+  - type: dropdown
+    id: contribution
+    attributes:
+      label: Willingness to contribute
+      description: Would you implement this yourself if the design is agreed?
+      options:
+        - I would open a PR for this
+        - I could help test or review
+        - I am only proposing the idea
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/template_contribution.yml

@@ -0,0 +1,56 @@
+name: Template contribution
+description: Propose a built-in spec template pack
+title: "[template] "
+labels: ["template"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Built-in templates are data, not code: a JSON manifest plus Markdown files with
+        one-pass `{{variable}}` substitution — no scripts, no network, no model. Read
+        [docs/template-contribution-guide.md](https://github.com/HelloThisWorld/specbridge/blob/main/docs/template-contribution-guide.md)
+        for the pack layout, the generated artifacts, and the automatic test gate.
+  - type: input
+    id: template-id
+    attributes:
+      label: Template ID
+      description: The manifest `id`, which must equal the pack directory name under `packages/templates/builtins/`.
+      placeholder: "graphql-api"
+    validations:
+      required: true
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Kind
+      description: Which spec kind the template generates.
+      options:
+        - feature
+        - bugfix
+    validations:
+      required: true
+  - type: textarea
+    id: modes
+    attributes:
+      label: Modes and variables
+      description: Which stages the pack provides (requirements/bugfix, design, tasks) and the variables it declares, with their constraints.
+      placeholder: |
+        Stages: requirements, design, tasks
+        Variables: serviceName (required), storageBackend (optional, default "postgres")
+    validations:
+      required: true
+  - type: textarea
+    id: scaffolds
+    attributes:
+      label: What it scaffolds
+      description: What the rendered spec covers and why it is broadly reusable rather than project-specific. Which existing built-in is it closest to, and why is it not a variant of that one?
+    validations:
+      required: true
+  - type: checkboxes
+    id: guarantees
+    attributes:
+      label: Template guarantees
+      options:
+        - label: Rendering is fully offline and deterministic — the pack is plain UTF-8 Markdown plus a JSON manifest, uses only `{{variable}}` substitution, and contains no scripts, no symlinks, no network references, and no environment-dependent content.
+          required: true
+        - label: I removed all credentials and proprietary company content; examples are synthetic.
+          required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+# Summary
+
+<!-- What this PR changes and why. One or two paragraphs; link the design
+     discussion if there was one. -->
+
+Closes #<!-- issue number, or remove this line -->
+
+## Checklist
+
+- [ ] `pnpm lint`, `pnpm typecheck`, and `pnpm test` pass locally
+- [ ] `pnpm check:public-contracts` passes — or a stable contract changed
+      **intentionally** and the snapshot under `contracts/` is updated in
+      this PR
+- [ ] Documentation updated for any user-visible behavior change
+- [ ] CHANGELOG entry added for any user-visible change (required whenever
+      a contract snapshot changed)
+- [ ] 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 change? Read SECURITY.md and
+     docs/security/threat-model.md first, and say here which invariants
+     the change touches. Never describe an unfixed vulnerability in a
+     public PR. -->

.github/workflows/ci.yml

@@ -45,6 +45,12 @@ jobs:
       - name: Test (compatibility fixtures, round-trip byte identity, CLI, drift, action)
         run: pnpm test
 
+      - name: Large-repository performance suite (informational budgets)
+        # Heavy ~9,000-file fixtures: one representative combination is enough,
+        # and isolating it keeps the main test run's workers responsive.
+        if: matrix.os == 'ubuntu-latest' && matrix.node == 20
+        run: pnpm test:perf
+
       - name: CLI smoke test against the example Kiro workspace
         run: node scripts/smoke.mjs
 
@@ -54,6 +60,25 @@ jobs:
       - name: Template gallery matches the built-in manifests
         run: pnpm check:template-gallery
 
+      - name: Public contract snapshots match the built surface
+        run: pnpm check:public-contracts
+
+      - name: Deterministic security scan (credentials, bypass strings, bundle paths)
+        run: pnpm check:security
+
+      - name: Extension registry validates and matches the reference extensions
+        run: |
+          pnpm validate:extension-registry
+          pnpm check:extension-registry
+          pnpm check:builtin-registry
+          pnpm check:extension-gallery
+
+      - name: Generated MCP tool reference matches the registry
+        run: pnpm check:mcp-docs
+
+      - name: Example projects run offline with expected output
+        run: node scripts/validate-examples.mjs
+
       - name: GitHub Action bundle is reproducible
         if: matrix.os == 'ubuntu-latest'
         run: git diff --exit-code integrations/github-action/dist