SpecBridge v0.7.1: extension SDK, registry, and community ecosystem (#9)

* feat(extension-sdk): add extension manifest, protocol, and stdio server SDK

* feat(extensions): add extension host with checksums, install, grants, and process isolation

* feat(extensions): add conformance framework and analyzer CLI integration

* feat(extensions): integrate verifier, exporter, runner proxy, and template providers

* feat(extensions): add scaffold, deterministic packaging, extension and registry CLI

* feat(registry): add reference extensions, repository registry index, and gallery

* feat(mcp): add read-only extension and registry tools plus the extensions plugin skill

* docs: add v0.7.1 ecosystem section, changelog, and extension smoke coverage

* test: update assertions for implemented spec export and SBV026

* fix(examples): commit reference extension entrypoints excluded by the dist ignore rule

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.0",
+      "version": "0.7.1",
       "license": "MIT",
       "keywords": [
         "spec-driven-development",

.gitignore

@@ -11,6 +11,10 @@ dist/
 # The Claude Code plugin ships its reproducible bundle in-repo too, so
 # installing the plugin straight from the GitHub marketplace source works.
 !integrations/claude-code-plugin/specbridge/dist/
+# Reference extensions ship their committed self-contained entrypoints;
+# locally built archives stay ignored.
+!examples/extensions/*/dist/
+examples/extensions/*/dist/*.zip
 
 # Test output
 coverage/

CHANGELOG.md

@@ -1,5 +1,111 @@
 # Changelog
 
+## 0.7.1
+
+Added:
+
+- Versioned extension manifest (`specbridge-extension.json`, schema 1.0.0)
+  covering five stable extension kinds: template-provider, analyzer,
+  verifier, exporter, and runner.
+- Publishable extension SDK (`@specbridge/extension-sdk`): manifest,
+  protocol, permission, and diagnostic schemas; a stdio extension server
+  with input/output validation, cancellation, and clean shutdown; typed
+  helpers per kind; in-process testing utilities.
+- Out-of-process extension protocol (JSON-RPC 2.0 over JSON Lines, protocol
+  1.0.0): initialize handshake with identity and capability validation,
+  invocation, cancellation, shutdown, structured errors, bounded messages.
+- Explicit extension permission model (specRead, repositoryRead,
+  repositoryWrite, network, childProcess, explicit environment-variable
+  names) with permission-aware input boundaries per kind.
+- Permission-hash acceptance: enabling requires
+  `--accept-permissions <hash>`, deterministically bound to the extension
+  ID, version, manifest hash, and normalized permissions; any manifest
+  change invalidates prior grants (SBE018).
+- Analyzer extensions (`spec analyze --extension <id>`, repeatable) with
+  namespaced rule IDs (`<extension-id>/<RULE>`) that never overwrite
+  built-in diagnostics.
+- Verifier extensions via explicit per-spec policy (`extensionVerifiers`);
+  results land in the verification report and reach the gate only through
+  the new built-in rollup rule SBV026 (required failure fails, optional
+  warns).
+- Exporter extensions (`spec export --extension <id> --output <dir>`):
+  candidate files only, previewed by default, written atomically after
+  explicit `--yes`, never overwriting, recorded append-only.
+- Runner extensions behind an extension-runner proxy implementing the
+  frozen v0.6.0 `AgentRunner` contract, wired through a new
+  backward-compatible `"runner": "extension"` profile variant (disabled by
+  default, preview support level, never auto-selected).
+- Template-provider extensions: data-only v0.7.0-format template packs
+  contributed to the catalog as `extension:<extension-id>/<template-id>`,
+  with ambiguity errors instead of shadowing.
+- Local extension installation from directories and archives (atomic,
+  versioned side-by-side, disabled after install, zero code execution),
+  plus explicit enablement/disablement and recoverable uninstall.
+- Extension conformance framework (`extension conformance --yes`) with
+  common protocol checks and kind-specific checks, recorded per install.
+- Deterministic extension packaging
+  (`<id>-<version>.specbridge-extension.zip`, store-method, fixed
+  timestamps, sorted entries, regenerated checksums, printed SHA-256).
+- Local (built-in + `--file`) and HTTPS registry indexes with a validated
+  atomic cache under `.specbridge/registry-cache/` and explicit
+  `registry update <name> --network`.
+- Extension and registry CLI command groups (`specbridge extension …`,
+  `specbridge registry …`) including scaffold for every kind.
+- Seven read-only MCP discovery tools: extension_list, extension_search,
+  extension_show, extension_doctor, registry_list, registry_search,
+  registry_show (37 MCP tools total).
+- Claude Code `/specbridge:extensions` Skill (discovery only).
+- Generated extension gallery (`docs/extensions.md`) with CI drift check,
+  repository registry index (`registry/`), and five maintained reference
+  extensions under `examples/extensions/`.
+- Stable error code registries: SBE001–SBE030 (extensions) and
+  SBR001–SBR015 (registry), every error with remediation.
+
+Security:
+
+- No in-process third-party code execution: no dynamic import of installed
+  extensions, no `eval`, no `Function`; the only executable surface is the
+  declared entrypoint launched as `node <entrypoint>` (argv array, no
+  shell) in a child process.
+- No package-manager lifecycle scripts: install/postinstall/prepare
+  declarations in a bundled package.json are validation errors and are
+  never executed.
+- No automatic enablement, no automatic updates, no automatic registry
+  network access; remote installs and updates require an explicit
+  `--network`.
+- Manifest-bound permission grants with stale-grant detection.
+- SHA-256 archive and per-file integrity checks; installed files are
+  revalidated after extraction.
+- Symlink and path-traversal rejection everywhere packages are read,
+  extracted, installed, or exported.
+- Bounded archive extraction (50 MB archive, 100 MB extracted, 1,000
+  files) with CRC verification and declared-size enforcement.
+- Protocol stdout isolation: stdout is protocol-only, logs go to stderr,
+  corruption terminates the process without crashing SpecBridge.
+- Startup (10 s) and operation (default 5 min) timeouts, cooperative
+  cancellation, SIGTERM→SIGKILL cleanup, bounded stdout/stderr capture.
+- Sanitized child environment with an explicit variable allowlist; granted
+  secret values are redacted from retained logs.
+- Extensions cannot approve stages, complete tasks, change evidence, or
+  disable built-in protected-path rules.
+
+Limitations:
+
+- Process isolation and permission declarations are safety boundaries and
+  audit mechanisms, not an OS sandbox; enabled executable extensions run
+  as local code with the user's operating-system permissions.
+- Checksums prove integrity, not publisher identity.
+- Registry listing is not endorsement.
+- Registry archive URLs in the repository index use a documented
+  placeholder host until a real hosted registry exists.
+
+Deferred to v1.0:
+
+- Stable publishing workflow and release automation.
+- Cross-platform installation verification.
+- Final security audit and performance hardening.
+- Schema migration guarantees and public launch assets.
+
 ## 0.7.0
 
 Added:

README.md

@@ -565,6 +565,34 @@ stay readable, migration is explicit — see
 [docs/runners.md](docs/runners.md)). Never commit API keys; SpecBridge
 stores no credentials of any kind.
 
+## Extension ecosystem (v0.7.1)
+
+Extend SpecBridge without modifying the core. Five stable extension kinds —
+template-provider, analyzer, verifier, exporter, and runner — run out of
+process behind a versioned stdio protocol, install disabled, and run only
+after you accept their declared permissions (bound to the manifest hash):
+
+```bash
+specbridge extension scaffold security-analyzer \
+  --kind analyzer \
+  --output ./security-analyzer
+
+specbridge extension conformance ./security-analyzer --yes
+
+specbridge extension package ./security-analyzer
+```
+
+Discover cached registry extensions (offline; updates are explicit):
+
+```bash
+specbridge registry search security
+```
+
+Extensions can never approve stages, mark tasks complete, alter evidence, or
+disable protected-path rules; process isolation is a safety boundary, not an
+OS sandbox, and checksums prove integrity, not publisher identity. See
+[docs/extensions.md](docs/extensions.md).
+
 ## Security and privacy
 
 - Default commands are read-only and fully offline; no telemetry, no network.
@@ -579,7 +607,7 @@ stores no credentials of any kind.
   secrets or environment variables.
 - Full model: [docs/security.md](docs/security.md).
 
-## Limitations (v0.7.0)
+## Limitations (v0.7.1)
 
 - The MCP server is stdio-only and local-only: no HTTP/SSE/WebSocket
   transport, no OAuth, no cloud hosting. One server process serves one

docs/extensions.md

@@ -0,0 +1,82 @@
+# SpecBridge extensions
+
+SpecBridge v0.7.1 adds a secure extension ecosystem: third parties extend
+SpecBridge **without modifying the core**. Executable extensions always run
+out of process behind a versioned stdio protocol, install disabled, and can
+run only after the user explicitly accepts their declared permissions.
+
+Five stable extension kinds exist:
+
+| Kind | What it does | Executable |
+| --- | --- | --- |
+| `template-provider` | Contributes v0.7.0-format spec template packs | No — data-only |
+| `analyzer` | Returns diagnostics for bounded spec content | Yes |
+| `verifier` | Returns diagnostics for a bounded verification context | Yes |
+| `exporter` | Returns candidate output files; SpecBridge writes them | Yes |
+| `runner` | An out-of-process adapter behind the frozen v0.6.0 runner contract | Yes |
+
+Extensions can never approve stages, mark tasks complete, change evidence, or
+disable built-in protected-path rules. Their output is never task-completion
+evidence. See [extensions/overview.md](extensions/overview.md) for the
+architecture and [extensions/security.md](extensions/security.md) for the
+threat model and the honest limitations: **process isolation and permission
+declarations are safety boundaries and audit mechanisms, not an OS sandbox**,
+and **checksums prove integrity, not publisher identity**.
+
+## Gallery
+
+<!-- BEGIN GENERATED EXTENSION GALLERY (pnpm generate:extension-gallery) -->
+
+Registry: **specbridge-examples** (5 extensions). Listing is not endorsement; review permissions before enabling.
+
+| Extension | Kind | Version | Description | Permissions | SpecBridge | Source |
+| --- | --- | --- | --- | --- | --- | --- |
+| `example-analyzer` | analyzer | 1.0.0 | Deterministic spec diagnostics contributed by the example-analyzer analyzer extension. | specRead | `>=0.7.1 <1.0.0` | [source](https://github.com/HelloThisWorld/specbridge) |
+| `example-exporter` | exporter | 1.0.0 | Candidate export files produced by the example-exporter exporter extension. | specRead | `>=0.7.1 <1.0.0` | [source](https://github.com/HelloThisWorld/specbridge) |
+| `example-runner` | runner | 1.0.0 | An out-of-process runner adapter provided by the example-runner extension. | specRead, repositoryRead, repositoryWrite | `>=0.7.1 <1.0.0` | [source](https://github.com/HelloThisWorld/specbridge) |
+| `example-template-provider` | template-provider | 1.0.0 | Spec template packs contributed by the example-template-provider template-provider extension. | none | `>=0.7.1 <1.0.0` | [source](https://github.com/HelloThisWorld/specbridge) |
+| `example-verifier` | verifier | 1.0.0 | Verification diagnostics contributed by the example-verifier verifier extension. | specRead | `>=0.7.1 <1.0.0` | [source](https://github.com/HelloThisWorld/specbridge) |
+
+<!-- END GENERATED EXTENSION GALLERY -->
+
+The reference extensions above live in [`examples/extensions/`](../examples/extensions)
+and are maintained with SpecBridge itself — reference implementations, not
+production recommendations.
+
+## Try it
+
+```bash
+# Discover (offline; searches the built-in and cached registry indexes)
+specbridge registry search analyzer
+
+# Install from a local archive or directory — installs disabled, runs no code
+specbridge extension install ./example-analyzer-1.0.0.specbridge-extension.zip
+specbridge extension show example-analyzer
+
+# Enable by accepting the exact permission hash shown by `show`
+specbridge extension enable example-analyzer --accept-permissions <hash>
+
+# Use it
+specbridge spec analyze my-spec --extension example-analyzer
+```
+
+## Build your own
+
+```bash
+specbridge extension scaffold my-analyzer --kind analyzer --output ./my-analyzer
+specbridge extension validate ./my-analyzer
+specbridge extension conformance ./my-analyzer --yes
+specbridge extension package ./my-analyzer
+```
+
+Guides: [creating analyzers](extensions/creating-analyzers.md) ·
+[verifiers](extensions/creating-verifiers.md) ·
+[exporters](extensions/creating-exporters.md) ·
+[runners](extensions/creating-runners.md) ·
+[template providers](extensions/creating-template-providers.md) ·
+[packaging](extensions/packaging.md) ·
+[publishing](extensions/publishing.md) ·
+[registry contribution](extensions/registry-contribution.md)
+
+Contributions enter the community index via
+[`registry/CONTRIBUTING.md`](../registry/CONTRIBUTING.md).

docs/extensions/manifest.md

@@ -0,0 +1,118 @@
+# Extension manifest reference
+
+Every extension package carries a `specbridge-extension.json` at its root.
+The manifest is parsed with a strict schema — unknown fields are rejected,
+every string is length-bounded, and documents above **256 KB** fail before
+parsing (`SBE008`). Validation never executes anything; all findings are
+reported at once as `SBE` issues.
+
+## Full example
+
+The maintained reference analyzer
+(`examples/extensions/example-analyzer/specbridge-extension.json`):
+
+```json
+{
+  "schemaVersion": "1.0.0",
+  "protocolVersion": "1.0.0",
+  "id": "example-analyzer",
+  "version": "1.0.0",
+  "displayName": "example-analyzer",
+  "description": "Deterministic spec diagnostics contributed by the example-analyzer analyzer extension.",
+  "kind": "analyzer",
+  "entrypoint": "dist/extension.cjs",
+  "compatibility": {
+    "specbridge": ">=0.7.1 <1.0.0",
+    "extensionSdk": ">=0.7.1 <1.0.0"
+  },
+  "capabilities": {
+    "operations": ["analyzer.analyze"]
+  },
+  "permissions": {
+    "specRead": true,
+    "repositoryRead": false,
+    "repositoryWrite": false,
+    "network": false,
+    "childProcess": false,
+    "environmentVariables": []
+  },
+  "license": "MIT",
+  "keywords": ["analyzer", "specbridge-extension"]
+}
+```
+
+## Required fields
+
+| Field | Rules |
+| --- | --- |
+| `schemaVersion` | Strict `X.Y.Z`; supported major is `1` (`SBE005` otherwise) |
+| `protocolVersion` | Strict `X.Y.Z`; major must match the supported protocol `1.0.0` (`SBE007`) |
+| `id` | Extension ID grammar below; max 64 characters (`SBE003`) |
+| `version` | Strict `X.Y.Z` — no ranges, no prerelease tags |
+| `displayName` | 1–100 characters |
+| `description` | 1–500 characters |
+| `kind` | One of `template-provider`, `analyzer`, `verifier`, `exporter`, `runner` |
+| `compatibility.specbridge` | A validated semver range the running SpecBridge must satisfy (`SBE006` at load time) |
+| `capabilities.operations` | Operations declared for this kind (table below); max 16, no duplicates |
+| `permissions` | All six permission fields, explicitly (see [permissions.md](permissions.md)) |
+| `license` | 1–100 characters (SPDX identifier recommended) |
+
+## Optional fields
+
+`entrypoint` (rules below), `compatibility.extensionSdk` (semver range),
+`author` (`{name, email?, url?}`), `homepage` and `repository` (must be
+`https://` URLs), `keywords` (max 12, each max 30 characters), `deprecated`
+(boolean), `replacement` (a valid extension ID; warns unless `deprecated` is
+true), `examples` (max 5), `configurationSchema` (a JSON object describing
+the extension's `configuration` input), and `minimumNodeVersion` (`X.Y.Z`).
+
+## Entrypoint rules
+
+- **Required** for executable kinds (`analyzer`, `verifier`, `exporter`,
+  `runner`) — missing is `SBE012`.
+- **Forbidden** for `template-provider` — data-only packages must not declare
+  one (`SBE004`).
+- Must be a relative, forward-slash path to a `.cjs`, `.mjs`, or `.js` file
+  inside the package: no `..`, no leading `/`, no drive letters, no
+  backslashes, no null bytes. The declared file must exist in the package,
+  and symlinks anywhere on the entrypoint path are rejected at run time
+  (`SBE011`).
+
+The host always runs the entrypoint as `node <entrypoint>` in a fresh child
+process — an entrypoint is never imported into the SpecBridge process.
+
+## Extension ID grammar
+
+`^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$`, at most 64 characters: lowercase letters
+and digits in hyphen-separated segments, starting with a letter. IDs double
+as store directory names, registry keys, and the namespace prefix for
+diagnostic rule IDs, so the grammar is deliberately restrictive.
+
+| Example | Verdict |
+| --- | --- |
+| `security-analyzer`, `jira-exporter`, `runner2` | Valid |
+| `Security-Analyzer` | Invalid — uppercase |
+| `security_analyzer` | Invalid — underscore |
+| `-analyzer`, `analyzer-` | Invalid — leading/trailing hyphen |
+| `security--analyzer` | Invalid — consecutive hyphens |
+| `2fast` | Invalid — starts with a digit |
+| `sec/analyzer` | Invalid — path separator |
+
+## Operations per kind
+
+| Kind | Required | Optional |
+| --- | --- | --- |
+| `template-provider` | none — must declare **no** operations | none |
+| `analyzer` | `analyzer.analyze` | — |
+| `verifier` | `verifier.verify` | — |
+| `exporter` | `exporter.export` | — |
+| `runner` | `runner.detect` | `runner.generateStage`, `runner.refineStage`, `runner.executeTask`, `runner.resumeTask`, `runner.listModels` |
+
+Declaring an operation outside the kind's list is `SBE021`. Declared
+operations are a ceiling, not a suggestion: the host only ever invokes
+declared operations, and an extension reporting undeclared operations at
+runtime fails the handshake.
+
+`template-provider` manifests are additionally rejected when they request
+`repositoryRead`, `repositoryWrite`, `network`, `childProcess`, or any
+environment variable — data-only packages get no permissions.