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

[HelloThisWorld]

What changed

v0.6.0 turns the single-runner v0.3 architecture into a capability-driven multi-runner platform while preserving every v0.1–v0.5 guarantee, and ships two new production adapters.

Runner platform (frozen contract)

• Versioned contracts in @specbridge/runners: 17 capability keys, 4 categories, 5 support levels, 6 operations with per-operation capability requirements (task execution additionally requires a safe boundary: sandbox OR the documented toolRestriction equivalent), 17 normalized event types, 13 normalized outcomes, 24 normalized error codes, normalized usage/cost (cost is never computed from hardcoded pricing; local Ollama reports unavailable, not zero).
• The contract is frozen for v0.6.1 (docs/runner-adapter-contract.md) and guarded by snapshot tests, including a minimal-adapter test proving a new provider registers without touching core orchestration. Core never branches on provider names.
• Profile-based registry (claude-code, codex-default, ollama-local, mock) with deterministic selection (explicit --runner → operation default → global default). Incompatible selections are refused before any process spawn, HTTP request, run record, or file change, listing missing capabilities and compatible configured profiles. Network-backed endpoints are never selected implicitly. The v0.3 unsupported stubs are gone; deferred providers are documentation-only.

Configuration v2 + explicit migration

• Schema 2.0.0: runnerProfiles, operationDefaults, runnerPolicy, fallbacks; argv-array commands only, credential-looking keys rejected, base-URL safety (loopback default, HTTPS-by-default remote, no embedded credentials, no file/ftp), unrestricted Codex modes rejected anywhere in the file.
• v1 files remain fully readable through a version-transparent reader. specbridge config doctor (read-only) and config migrate --dry-run|--apply (atomic, config.v1.backup.json, validated, rollback on failure). Migration preserves Claude behavior and trusted verification commands, adds Codex/Ollama disabled, and never creates credentials.

Codex CLI runner (production)

• Read-only detection probes (--version, --help, exec --help, login status) — never a model request, never credential files; capability tokens, not one help layout; honest downgrades (e.g. no workspace-write → authoring preserved, execution incompatible).
• Authoring under --sandbox read-only; task execution under --sandbox workspace-write (config can narrow, never broaden). danger-full-access, --dangerously-bypass-approvals-and-sandbox, --yolo, --skip-git-repo-check are rejected at three layers (config schema, argv builder, pre-spawn assertion). Prompts travel via stdin; JSONL events are normalized with reasoning content redacted; resume uses the explicit recorded session id only.
• Codex claims (file changes, commands, tests) are recorded as claims; the shared evidence pipeline (Git snapshots + trusted verification) remains the only completion authority — .kiro/protected-path writes keep the task unverified and are never rolled back.

Ollama runner (production, authoring-only)

• Native loopback HTTP API: model listing without inference, non-streaming schema-validated structured output (temperature 0), one bounded correction retry, input/output size limits enforced mid-stream, redirects refused, thinking content redacted from all artifacts. No repository access exists; spec run --runner ollama-local is refused before any request. Models are never pulled or auto-selected.

Shared orchestration

• Claude Code runner adapted onto the contract unchanged (same probes, invocation, permission safeguards, resume, prompts, config semantics).
• Shared semantic prompt contract v1.1.0 with a repository-access parameter (agent CLIs: read-only tools; model APIs: no access) — semantic-equivalence tests prove the same safety sections reach every provider.
• Append-only per-invocation attempt records (.specbridge/runs/<id>/attempts/) with capability snapshots, boundaries, normalized results, and fallback lineage; explicitly configured authoring fallback chains with bounded retries and hard stop conditions (auth/permission/config/cancellation/quota/repository-modified).
• Reusable conformance framework; specbridge runner conformance <profile> [--network] runs it against throwaway fixture workspaces.

Verification

Check	Baseline (v0.5)	Final (v0.6.0)
pnpm lint	pass	pass
pnpm typecheck	pass	pass
pnpm test	631/631 (51 files)	772/772 (60 files)
pnpm build	pass	pass
pnpm build:plugin / validate:plugin / verify:plugin-bundle	pass (0.5.0)	pass (0.6.0, all 8 isolated checks)
pnpm smoke (built CLI)	pass	pass (34 checks)

• Conformance (fake providers, full invocation): mock, claude-code, codex-cli — all applicable groups pass (production confirmed); ollama — authoring groups pass, task/resume correctly not applicable.
• New coverage includes: contract snapshots, config v2 safety (URL/command/credential rules), migration (dry-run writes nothing, apply atomic+backup, invalid input leaves the file intact), selection precedence and refusals, fallback boundaries (never after auth failure/cancellation/repo modification, never without an explicit chain, never during execution), 30+ process-level fake-Codex scenarios (timeout/cancel kill the process, output limits never parse truncated output, extra prose rejected, secrets never echoed), 20+ fake-Ollama HTTP scenarios (real loopback server), and end-to-end Codex task execution through the shared evidence pipeline (verified checkbox flip, failing verifier, .kiro write, claims-not-evidence, explicit-session resume).
• All v0.1–v0.5 suites pass unchanged; the only pre-existing tests edited were version literals (0.5.0→0.6.0), the v0.3 stub-listing assertions in runner list/doctor output tests, and two matching lines in scripts/smoke.mjs.

Reviewer notes

• Fully offline CI: the fake Codex CLI is a real child process (tests/fixtures/fake-codex/fake-codex.mjs) and the fake Ollama server is a real loopback HTTP server (tests/helpers-fake-ollama.ts) — adapters are never mocked internally.
• packages/runners/src/contracts/ + docs/runner-adapter-contract.md are the frozen surface for v0.6.1; changing discriminator values there should fail tests/runners/contracts.test.ts by design.
• The committed plugin dist/ artifacts (cli.cjs, mcp-server.cjs, checksums) are rebuilt at 0.6.0, as this repo intentionally commits the self-contained bundle.
• MCP server and plugin behavior are unchanged besides version bumps (verified by the untouched v0.5 suites and isolated bundle verification).
• Deferred to v0.6.1 (documented, not stubbed): Gemini CLI, OpenAI-compatible authoring, Antigravity, MCP runner diagnostics, /specbridge:runners Skill. Deferred to v0.7: templates, plugin/runner/analyzer/verifier SDKs, extension registry.

🤖 Generated with Claude Code