SpecBridge v0.3: agent runners and evidence-gated task execution

[HelloThisWorld]

What

v0.3 implements roadmap Phases F (runner adapters) and G (task execution with evidence): a safe, auditable, model-assisted development workflow on top of approved Kiro-compatible specs. .kiro remains the source of truth for spec content; .specbridge now also owns runner configuration, run records, execution evidence, verification results, and resumable run metadata.

Runners (@specbridge/runners, rebuilt)

• Model-agnostic contract: detect / generateStage / executeTask / resumeTask?, with discriminated statuses (available, unavailable, unauthenticated, incompatible, misconfigured, error) and structured outcomes. Runners return observations only — they never touch checkboxes and never judge evidence.
• Claude Code local-CLI runner: executable + authentication detection, help-token capability probing (graceful degradation instead of parsing one help layout), argv-array invocation with the prompt over stdin, session ids, configurable timeout, AbortSignal cancellation, graceful-then-forced termination, stdout/stderr size limits.
• Deterministic mock runner with 14 scenarios (including rogue behaviors: protected-path writes, direct tasks.md edits, malformed JSON, claimed-but-never-run tests) so every safety layer is testable offline.
• codex / ollama / openai-compatible remain honest unsupported stubs.
• CLI: runner list, runner doctor [name], runner show <name> — read-only, --json, never echo credentials.

Model-assisted authoring (spec generate / spec refine)

• Versioned prompt contracts with explicit trust boundaries (control instructions vs. steering vs. spec documents vs. untrusted file content).
• Workflow-mode prerequisites enforced (requirements-first / design-first / quick / bugfix); an approved stage is never overwritten (revoke first); nothing is ever auto-approved.
• The runner returns Markdown in structured output; SpecBridge writes the .kiro file after deterministic v0.2 analysis. Invalid candidates are retained under the run directory and never applied. Refinement shows a unified diff. Dependent approvals are invalidated on content change.
• Generation runs with read-only tools (Read, Glob, Grep).

Task execution (spec run) — new packages @specbridge/evidence + @specbridge/execution

• One approved task per run; pre-run validation covers approvals (byte-exact hashes), task identity (leaf tasks only, stable ids), runner availability/auth/capabilities, and the clean-working-tree policy (--allow-dirty captures a hash-exact baseline; pre-existing changes are never attributed to the task).
• Git snapshots before/after every run, hash-exact changed-file attribution, protected-path hashing (.kiro/**, sidecar config/state), patch capture with size limits, moved-HEAD detection (runners must never commit).
• Trusted verification commands come only from .specbridge/config.json (argv arrays; shell strings rejected; never derived from spec content or model output).
• Deterministic evidence evaluation: a model claim is never sufficient. Only verified (or explicit manually-accepted) evidence flips a checkbox — via the v0.1 surgical writer (one character, one line; the tasks approval hash is re-recorded for SpecBridge's own sanctioned edit).
• Append-only run records (.specbridge/runs/<run-id>/: prompt, raw output, snapshots, verification, evidence, report) and evidence (.specbridge/evidence/<spec>/<task>/); run list / run show / run resume with repository-divergence detection and parentRunId lineage; sequential --all stops at the first unverified task; spec accept-task --reason for audited manual acceptance.
• Exit codes extended: 0/1/2 unchanged, plus 3 (runner unavailable), 4 (runner failure), 5 (timeout/cancel), 6 (safety violation).

Security (each control tested)

• No embedded auth: the user installs and authenticates Claude Code independently; SpecBridge never collects, stores, proxies, or prints credentials (auth probe output is summarized, never echoed).
• bypassPermissions / dangerously-skip-permissions rejected at three layers (config schema, argv assembly, pre-spawn assertion) with no override.
• Spec files, source files, and model output are treated as data; nothing from them is ever executed.
• No automatic git commit, push, reset, stash, or rollback. Protected-path modifications block verification and are reported with evidence preserved.

Why

The v0.2 workflow ends at approved specs. v0.3 closes the loop — approved spec → bounded task context → one agent-executed task → actual git evidence → trusted verification → checkbox — without ever trusting a model's claim of success, and while keeping the zero-migration promise intact (byte-identical round trips are regression-tested throughout).

Testing

• 362/362 tests (117 new) across 30 files; lint, typecheck, and build clean; scripts/smoke.mjs 22/22 against the built CLI.
• New process-level integration tests run against a fake Claude CLI fixture (tests/fixtures/fake-claude/) covering detection, auth redaction, capability degradation, argv purity, timeouts, cancellation, output limits, malformed output, and resume flags — CI needs no Claude installation and no network.
• Full §-style acceptance scenarios were run against the built CLI: verified run (exactly one line changed, [ ]→[x], unrelated bytes identical), failed verification (evidence retained, checkbox unchanged), protected-path violation (flagged, no rollback), resume (lineage preserved, divergence refused), manual acceptance (reason required, recorded distinctly).
• Bonus real-world check: runner doctor claude-code validated against the actual Claude Code 2.1.141 installed on the dev machine.

Reviewer notes

• packages/runners was rebuilt around the new contract (the v0.1 layer was detection-only by design); the old interface had no CLI consumers.
• Three deliberate policy decisions worth a look: the clean-tree gate exempts .specbridge/ and .kiro files whose bytes hash-match recorded approvals (docs/task-execution.md); --all implicitly baselines earlier tasks' uncommitted work (runs never commit); resume attributes against the original run's baseline but judges protected paths/HEAD against the resume session start (docs/session-resume.md).
• Deferred (documented on the roadmap): drift-verification CLI, GitHub Action gates, MCP server, additional production runners, parallel execution.

🤖 Generated with Claude Code