SpecBridge v0.6.0: capability-driven runner platform, Codex CLI and Ollama runners (#6)

Add the capability-driven runner platform with a frozen adapter contract:
versioned capability/operation/event/result/error/usage schemas (17
capability keys, 6 operations, 24 error codes, snapshot-tested), runner
categories and support levels, and a profile-based registry with
deterministic capability-checked selection that refuses incompatible
operations before any process spawn, HTTP request, run record, or file
change.

Configuration gains a v2 multi-runner schema (runnerProfiles,
operationDefaults, runnerPolicy, fallbacks) with URL/command/credential
safety rules. v1 files stay fully readable through a version-transparent
reader; migration is explicit only ("config doctor",
"config migrate --dry-run|--apply") — atomic, backed up, validated, Claude
behavior preserved, new providers left disabled, trusted verification
commands untouched.

New production adapters:
- codex-cli: read-only probes (never a model request, never credential
  files), JSONL event normalization with reasoning redaction, JSON Schema
  structured output, read-only sandbox for authoring, workspace-write for
  task execution (unrestricted modes rejected at three layers),
  explicit-session resume, full failure classification.
- ollama: authoring-only model API (loopback default, HTTPS-by-default for
  remote, redirects refused), model listing without inference,
  schema-validated structured output with ONE bounded correction retry,
  input/output limits, thinking-content redaction; task execution refused
  by capability.

The existing Claude Code runner implements the shared contract unchanged
(same process safety, permission modes, resume, prompts, configuration
semantics). Authoring supports explicitly configured bounded fallback
chains with append-only per-invocation attempt records
(.specbridge/runs/<id>/attempts/); task execution never retries or
switches providers. A reusable conformance framework
(detection/structured-output/process-control/authoring/task/resume, chosen
by declared capabilities) backs every production claim; mock, claude-code
(fake), and codex-cli (fake) pass all applicable groups, ollama passes the
authoring groups only.

CLI: runner list/matrix/show/doctor/test/conformance/models,
config doctor/migrate, --show-runner-plan, runner plans in dry runs.
Provider claims remain informational; Git snapshots and trusted
verification stay the only completion authority.

Tests: 772 total (60 files) including a process-level fake Codex CLI and a
real loopback fake Ollama HTTP server; no real providers, network, models,
or credentials in CI. All v0.1-v0.5 suites pass unchanged; lint,
typecheck, build, plugin build/validate, and isolated plugin verification
pass; versions consistently 0.6.0. Gemini CLI, OpenAI-compatible,
Antigravity, MCP runner tools, and the runner Skill are deferred to v0.6.1
(documented, not stubbed).

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

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

CHANGELOG.md

@@ -1,5 +1,140 @@
 # Changelog
 
+## 0.6.0
+
+Added:
+
+- Capability-driven runner platform: core orchestration selects and gates
+  runners by DECLARED CAPABILITIES (17 stable keys), never by provider
+  names. Runner categories (`agent-cli`, `model-api`, `mock`,
+  `experimental`) and support levels (`production`, `preview`,
+  `experimental`, `unavailable`, `incompatible`) are explicit everywhere.
+- Versioned, FROZEN runner adapter contract for v0.6.1
+  (docs/runner-adapter-contract.md) with snapshot tests guarding categories,
+  support levels, operation names, capability keys, normalized outcomes,
+  normalized error codes, event types, and required adapter methods — plus a
+  minimal-adapter test proving new providers register without core changes.
+- Operation-specific capability validation: `stage-generation`,
+  `stage-refinement`, `task-execution`, `task-resume`, `model-list`,
+  `runner-test`, each with required capabilities and (for execution) a
+  required safe boundary (`sandbox` OR the documented `toolRestriction`
+  equivalent). Incompatible selections stop BEFORE any process spawn, HTTP
+  request, run record, or file change, and list the missing capabilities and
+  compatible configured profiles.
+- Normalized provider events (17 types, size-limited flat payloads, no
+  reasoning content), normalized execution results (13 outcomes), normalized
+  runner errors (24 stable codes with safe messages, remediation, and
+  retryability), and normalized usage/cost metadata (cost is
+  provider-reported, configured-estimate, or unavailable — never computed
+  from hardcoded pricing; local Ollama reports `unavailable`, not zero).
+- Versioned runner profiles (configuration schema 2.0.0): named
+  configurations of implementations (`codex-default`, `codex-fast`,
+  `ollama-qwen`, …) with per-profile executable/endpoint, model, timeout,
+  sandbox, and output limits; unique names; unknown implementations
+  rejected.
+- Configuration migration tools: `specbridge config doctor` (read-only) and
+  `specbridge config migrate --dry-run|--apply` (atomic write, recoverable
+  `config.v1.backup.json`, validated result). The v1 schema remains fully
+  readable before explicit migration; migration preserves the Claude Code
+  default behavior and trusted verification commands, adds Codex/Ollama
+  profiles DISABLED, and creates no credentials.
+- Deterministic runner selection with precedence explicit `--runner` →
+  operation default → global default, a capability-checked selection plan
+  (`--show-runner-plan`, dry-run output), and network-policy enforcement
+  (network-backed profiles are never selected implicitly).
+- Explicit authoring fallback policy: per-operation chains
+  (`fallbacks.stageGeneration/.stageRefinement`), bounded correction and
+  transport retries, and hard stop conditions (auth/permission/config
+  failures, cancellation, quota, repository modification, real results).
+  Disabled by default; never during task execution or resume.
+- Generated runner capability matrix: `specbridge runner matrix`
+  (`--json`, `--markdown`) from registered runner metadata; plus
+  `runner show <profile>`, `runner test <profile> [--network]`,
+  `runner conformance <profile> [--network]`, and
+  `runner models <profile>`.
+- Reusable runner conformance framework (detection, structured-output,
+  process-control, stage-generation, stage-refinement, task-execution,
+  resume) with capability-derived applicability; a runner is production only
+  when every applicable group passes. Conformance uses throwaway fixture
+  workspaces, requires `--network` for real-provider invocations, and runs
+  fully against fake providers in CI.
+- Production Codex CLI runner (`codex-cli`): read-only probes for
+  version/help/`exec --help`/`login status` (never a model request, never
+  credential files), JSONL event capture and normalization, JSON Schema
+  structured output with strict validation, read-only sandbox for authoring,
+  workspace-write sandbox for task execution, explicit-session resume
+  (`codex exec resume <id>`, never "latest"), and full failure
+  classification (auth, permission, sandbox, quota, rate limit, timeout,
+  cancellation, output limits).
+- Production Ollama authoring runner (`ollama`): loopback-default native
+  HTTP API with strict URL safety (no credentials in URLs, no file/ftp
+  schemes, HTTPS-by-default for remote endpoints with a labeled insecure
+  development override, redirects never followed), model listing without
+  inference, schema-validated non-streaming structured output at
+  temperature 0, ONE bounded correction retry, input/output size limits,
+  thinking-content redaction, and task execution refused by capability
+  before any request.
+- Append-only per-invocation attempt records under
+  `.specbridge/runs/<run-id>/attempts/<attempt-id>/`: capability snapshot,
+  operation, local/network boundary, model, normalized events and result,
+  process observation, error classification, and fallback lineage. Failed
+  attempts (including invalid structured-output candidates) are retained.
+- Fake-provider test infrastructure: a process-level fake Codex CLI
+  (26 scenarios) and a real loopback fake Ollama HTTP server (20 scenarios);
+  CI needs no real providers, no network, no models, no credentials.
+
+Changed:
+
+- The existing Claude Code runner now implements the shared capability
+  contract (category `agent-cli`, declared capability set, detection-derived
+  support level) with its v0.3–v0.5 behavior, process safety, permission
+  modes, resume, structured-output validation, and configuration semantics
+  preserved unchanged.
+- Runner selection validates operation capabilities before execution; task
+  execution is restricted to compatible agent CLI runners and model API
+  runners are authoring-only.
+- Provider output is normalized (events, results, errors, usage) before it
+  enters shared orchestration; run records now reference per-attempt
+  capability snapshots and attempt metadata.
+- The shared prompt contract (v1.1.0) parameterizes repository access:
+  agent CLIs receive read-only repository tools for authoring; model APIs
+  receive an explicit no-repository-access variant. The same core safety
+  sections appear for every provider (tested for semantic equivalence).
+- `runner list`/`doctor`/`show` are profile-based; the v0.3 `unsupported`
+  stub registrations (codex/ollama/openai-compatible) were replaced by real
+  disabled-by-default profiles, and deferred providers are no longer
+  registered at all.
+
+Security:
+
+- No provider credentials stored; credential-looking configuration keys are
+  rejected; no credential-file parsing anywhere.
+- No automatic paid or network-provider selection; no automatic
+  task-execution fallback or provider switching.
+- No unrestricted Codex execution mode (`danger-full-access`, bypass flags,
+  and repo-check skips rejected at three layers).
+- No source editing by Ollama (no repository access by construction).
+- No provider claims treated as task evidence; Git snapshots and trusted
+  verification remain the only completion authority.
+- No shell interpolation for runner commands (argv arrays only, both
+  schemas).
+- Explicit local and network data boundaries in every plan and attempt
+  record; provider reasoning content never exposed; provider event payloads
+  size-limited.
+
+Deferred to v0.6.1:
+
+- Gemini CLI runner.
+- OpenAI-compatible authoring runner.
+- Antigravity capability adapter.
+- MCP runner diagnostics.
+- Claude Code runner-management Skill (`/specbridge:runners`).
+
+Deferred to v0.7:
+
+- Templates, plugin SDK, runner extension SDK distribution, analyzer and
+  verifier SDKs, extension registry, community ecosystem.
+
 ## 0.5.0
 
 Added:

README.md

@@ -14,7 +14,46 @@ Codex, local models, or any supported coding agent.
 
 > Your `.kiro` specs remain the source of truth.
 
-New in v0.5 — a self-contained **Claude Code plugin** with a local MCP
+New in v0.6 — keep your existing `.kiro` specs and **choose a compatible
+coding agent or authoring model per operation**:
+
+```text
+                  Spec authoring     Task execution
+Claude Code             ✓                  ✓
+Codex CLI               ✓                  ✓
+Ollama                  ✓                  —
+```
+
+```bash
+specbridge runner matrix
+
+specbridge spec generate notification-preferences \
+  --stage requirements \
+  --runner ollama-local
+
+specbridge spec generate notification-preferences \
+  --stage design \
+  --runner codex-default
+
+specbridge spec run notification-preferences \
+  --task 2.3 \
+  --runner codex-default
+```
+
+Runner behavior is capability-driven: authoring-only model APIs (Ollama)
+can never execute tasks, task execution needs a safe sandbox or tool
+restriction, network-backed endpoints are never selected implicitly, and
+whatever runs, task completion still requires actual Git evidence plus
+trusted verification — never a provider claim. The live matrix above is
+generated from registered runner metadata (`specbridge runner matrix`); not
+every installed Codex version is compatible (`specbridge runner doctor
+codex-default` reports the exact capabilities).
+
+SpecBridge does not include provider subscriptions, hosted models, API
+usage, or authentication — you install and authenticate Claude Code, the
+Codex CLI, or Ollama yourself. See [docs/runners.md](docs/runners.md).
+
+From v0.5 — a self-contained **Claude Code plugin** with a local MCP
 server and verified interactive task execution:
 
 ```text
@@ -214,6 +253,9 @@ Working today (fully offline, no model, no API key):
 | `specbridge verify rules / explain <id>` | **v0.4** — inspect the stable rule registry SBV001–SBV025 |
 | `specbridge mcp serve / doctor / manifest / tools` | **v0.5** — local stdio MCP server (21 tools, 7 resources, 4 prompts) |
 | `specbridge run recover-lock` | **v0.5** — diagnose and explicitly recover the interactive execution lock |
+| `specbridge runner list / matrix / show / doctor` | **v0.6** — profile-based runner diagnostics and the generated capability matrix (read-only) |
+| `specbridge runner test / conformance / models <profile>` | **v0.6** — bounded structured-output probe (`--network`), conformance suite, provider-supported model listing |
+| `specbridge config doctor / migrate` | **v0.6** — configuration validation and the explicit v1 → v2 migration (dry-run by default, atomic apply with backup) |
 
 Planned commands (`spec sync/export`) are registered, marked "(planned)" in
 `--help`, and exit with an honest error — see the [roadmap](docs/roadmap.md).
@@ -317,25 +359,27 @@ by `spec approve` — see [docs/approval-workflow.md](docs/approval-workflow.md)
 Runner-assisted generation (since v0.3) is always explicit opt-in; offline
 templates remain the default.
 
-## Model-assisted authoring and task execution (v0.3)
+## Model-assisted authoring and task execution (v0.3, multi-runner since v0.6)
 
-With a locally installed, locally authenticated Claude Code CLI (or the
-offline mock runner), SpecBridge can draft spec stages and execute approved
-tasks — with the safety model doing the real work:
+With a locally installed, locally authenticated agent CLI (Claude Code or
+Codex), a local Ollama endpoint for authoring, or the offline mock runner,
+SpecBridge can draft spec stages and execute approved tasks — with the
+safety model doing the real work:
 
 ```sh
 specbridge runner doctor claude-code
+specbridge runner matrix
 
-specbridge spec generate notification-preferences --stage requirements
+specbridge spec generate notification-preferences --stage requirements --runner ollama-local
 specbridge spec analyze  notification-preferences --stage requirements
 specbridge spec approve  notification-preferences --stage requirements
 
-specbridge spec generate notification-preferences --stage design
+specbridge spec generate notification-preferences --stage design --runner codex-default
 specbridge spec approve  notification-preferences --stage design
 specbridge spec generate notification-preferences --stage tasks
 specbridge spec approve  notification-preferences --stage tasks
 
-specbridge spec run notification-preferences --task 2.3
+specbridge spec run notification-preferences --task 2.3 --runner codex-default
 specbridge run show <run-id>
 ```
 
@@ -451,19 +495,26 @@ CI for this repository runs on Linux, macOS, and Windows with Node 20/22.
 ## Supported runners
 
 Runners make SpecBridge model- and agent-agnostic. Default commands never
-require one.
-
-| Runner | Status |
-| --- | --- |
-| `mock` | ✅ Implemented — offline, deterministic, scenario-driven, used by CI |
-| `claude-code` | ✅ **v0.3** — local CLI runner: generation, refinement, task execution, resume |
-| `codex` | ❌ Stub — honestly not implemented (roadmap) |
-| `ollama` | ❌ Stub — honestly not implemented |
-| `openai-compatible` | ❌ Stub — honestly not implemented |
-
-Configuration lives in `.specbridge/config.json`
-([docs/agent-runners.md](docs/agent-runners.md)). Never commit API keys;
-SpecBridge stores no credentials of any kind.
+require one. Since v0.6, runners are configured as capability-checked
+PROFILES; the live matrix comes from `specbridge runner matrix`:
+
+| Profile | Support | Author | Refine | Execute | Resume | Local |
+|---------|---------|--------|--------|---------|--------|-------|
+| claude-code | production | yes | yes | yes | yes | no |
+| codex-default | production | yes | yes | yes | yes | no |
+| ollama-local | production | yes | yes | no | no | yes |
+| mock | production | yes | yes | yes | yes | yes |
+
+`codex-default` and `ollama-local` ship DISABLED until you enable them
+explicitly. Ollama is authoring-only by capability — it can never execute
+tasks or modify files. Gemini CLI, an OpenAI-compatible authoring runner,
+and Antigravity are planned for v0.6.1 (no placeholders are registered).
+
+Configuration lives in `.specbridge/config.json` (schema 2.0.0; v1 files
+stay readable, migration is explicit — see
+[docs/configuration-migration.md](docs/configuration-migration.md) and
+[docs/runners.md](docs/runners.md)). Never commit API keys; SpecBridge
+stores no credentials of any kind.
 
 ## Security and privacy
 
@@ -479,7 +530,7 @@ SpecBridge stores no credentials of any kind.
   secrets or environment variables.
 - Full model: [docs/security.md](docs/security.md).
 
-## Limitations (v0.5)
+## Limitations (v0.6)
 
 - The MCP server is stdio-only and local-only: no HTTP/SSE/WebSocket
   transport, no OAuth, no cloud hosting. One server process serves one
@@ -500,8 +551,18 @@ SpecBridge stores no credentials of any kind.
   references, chore-task exclusion) are labelled and never default to error.
 - `spec sync` and `spec export` are not implemented yet (they fail
   honestly). SARIF output is deferred.
-- Claude Code is the only production runner; codex/ollama/openai-compatible
-  remain stubs. Claude usage happens under your own account and plan.
+- Production runners are claude-code, codex-cli, ollama (authoring-only),
+  and mock. Gemini CLI, OpenAI-compatible, and Antigravity are deferred to
+  v0.6.1 and are not registered as placeholders. Provider usage happens
+  under your own accounts and plans; not every installed Codex version is
+  compatible (the doctor reports the exact missing capabilities).
+- Ollama cannot execute tasks or modify files — by capability, not by
+  configuration. Models are never pulled or selected automatically.
+- Codex resume needs an installed version with explicit session resume;
+  without it, resume is reported unsupported instead of guessed.
+- Authoring fallback exists only for explicitly configured chains, only for
+  stage generation/refinement, with bounded retries; there is no automatic
+  provider switching anywhere else.
 - Task execution requires a git repository, sidecar workflow state, and
   fully approved stages — by design; there is no force flag.
 - Tasks can only auto-verify when verification commands are configured;
@@ -535,10 +596,15 @@ git snapshots, trusted verification, append-only evidence, verified-only
 checkbox completion, manual acceptance, resumable sessions. v0.4:
 deterministic drift verification (rule engine SBV001–SBV025, policies,
 affected-spec resolution, evidence freshness, four report formats) and the
-production GitHub Action. v0.5 (this release): the local stdio MCP server,
-direct interactive task execution, and the self-contained Claude Code
-plugin with its repository-local marketplace. Next — v0.6: production
-multi-runner support. v0.7: templates, plugin SDK, extension registry,
+production GitHub Action. v0.5: the local stdio MCP server, direct
+interactive task execution, and the self-contained Claude Code plugin with
+its repository-local marketplace. v0.6.0 (this release): the
+capability-driven runner platform with a frozen adapter contract, runner
+profiles and explicit configuration migration, deterministic selection and
+bounded authoring fallback, the conformance framework, and the production
+Codex CLI and Ollama (authoring-only) runners. Next — v0.6.1: Gemini CLI,
+OpenAI-compatible authoring, Antigravity, MCP runner diagnostics, and the
+runner-management Skill. v0.7: templates, plugin SDK, extension registry,
 community ecosystem. Full detail: [docs/roadmap.md](docs/roadmap.md).
 
 ## Documentation
@@ -549,6 +615,19 @@ community ecosystem. Full detail: [docs/roadmap.md](docs/roadmap.md).
 [Spec analysis](docs/spec-analysis.md) ·
 [Approval workflow](docs/approval-workflow.md) ·
 [Sidecar state](docs/sidecar-state.md) ·
+[Runners (v0.6)](docs/runners.md) ·
+[Runner capabilities](docs/runner-capabilities.md) ·
+[Runner profiles](docs/runner-profiles.md) ·
+[Runner selection](docs/runner-selection.md) ·
+[Runner fallback](docs/runner-fallback.md) ·
+[Runner conformance](docs/runner-conformance.md) ·
+[Runner adapter contract](docs/runner-adapter-contract.md) ·
+[Codex CLI runner](docs/codex-cli-runner.md) ·
+[Ollama runner](docs/ollama-runner.md) ·
+[Network & data boundaries](docs/network-data-boundaries.md) ·
+[Runner security](docs/runner-security.md) ·
+[Runner troubleshooting](docs/runner-troubleshooting.md) ·
+[Configuration migration](docs/configuration-migration.md) ·
 [Agent runners](docs/agent-runners.md) ·
 [Claude Code runner](docs/claude-code-runner.md) ·
 [Model-assisted authoring](docs/model-assisted-authoring.md) ·

docs/agent-runners.md

@@ -4,7 +4,12 @@ Runners make SpecBridge model- and agent-agnostic: a runner wraps one way of
 invoking an AI coding agent. Default SpecBridge commands never require one;
 runner execution is always explicit.
 
-## The contract (v0.3)
+> **v0.6:** runners are now selected through capability-checked PROFILES
+> (`claude-code`, `codex-default`, `ollama-local`, `mock`) with a frozen
+> adapter contract. Start at **[runners.md](runners.md)**; this page keeps
+> the v0.3 execution-contract fundamentals, which are unchanged.
+
+## The contract (v0.3 core, extended by v0.6 capabilities)
 
 Every runner implements the same model-agnostic contract
 (`@specbridge/runners`):
@@ -25,8 +30,10 @@ orchestration lives in `@specbridge/execution` and evidence evaluation in
 ### Runner kinds and statuses
 
 Kinds: `mock` (offline, deterministic), `claude-code` (local Claude Code
-CLI), `unsupported` (honest stubs: `codex`, `ollama`, `openai-compatible` —
-documented on the [roadmap](roadmap.md), not implemented, never faked).
+CLI), `codex-cli` (local Codex CLI, v0.6), and `ollama` (local model API,
+authoring-only, v0.6). The v0.3-era `unsupported` stubs are gone — deferred
+providers (Gemini CLI, OpenAI-compatible, Antigravity) exist only on the
+[roadmap](roadmap.md) and are not registered as placeholders.
 
 Detection statuses: `available`, `unavailable`, `unauthenticated`,
 `incompatible`, `misconfigured`, `error`. Only `available` permits