feat: governed agent orchestration (v1.1.0)

[HelloThisWorld]

Summary

SpecBridge v1.0 controlled what may be executed and whether a result counts as complete. It did not control the middle. An agent could implement an underspecified requirement, silently choose between two valid architectural interpretations, retry a deterministic failure indefinitely, broaden scope while debugging, or start a fresh run and present it as a continuation.

This PR adds a bounded, observable, resumable control loop around that middle, as a reusable domain package (@specbridge/orchestration) rather than logic smeared across the CLI, MCP handlers, and skill prose. The goal is not more agent autonomy — it is more reliable, observable, bounded, and governable agent execution. SpecBridge owns state, policy, boundaries, and the completion decision; the coding agent owns interpretation and edits; Git and the trusted verifiers own evidence.

Additive throughout: no persisted schema version moved, so v1.0 workspaces load with no migration.

What changed

New package @specbridge/orchestration (~4,500 LOC)

• A 12-phase fail-closed state machine plus a per-phase allowed-action table. EDIT is absent from the allowed set of every pre-plan phase, which is what makes "no source edits before the plan gate" a hard-enforced rule rather than a line in a Markdown file.
• Intent assessment with four strictly distinct outcomes (READY / NEEDS_CLARIFICATION / REJECTED / BLOCKED). The host agent proposes a structured assessment; SpecBridge validates it against facts it checks itself — approvals, staleness, task existence, lock ownership, hard product boundaries — and may override it. Overrides only ever move towards caution.
• Structural provenance instead of a confidence score. A number invented by a model is not a safety mechanism. A READY claim resting on inferred, unknown, or conflicting facts is downgraded automatically, with the offending facts listed.
• Bounded clarification with durable structured decisions: required justification per question, refused duplicates and re-asks, refused inference-as-answer, supersession. A decision never amends an approved .kiro document — spec-changing answers route back to re-authoring and human approval.
• Execution plans bound to task fingerprint + approved stage hashes + Git baseline + policy fingerprint, with staleness detection and a plan review gate (review by default). Reviews bind to the exact plan hash.
• Material-change replanning: a changed goal, non-goal, constraint, subsystem, or strategy re-opens review; a reorder or wording fix does not.
• 18-category failure taxonomy driving a deterministic retry/repair/replan engine. Exactly two categories are retryable; a failing verifier enters bounded repair rather than a rerun; ambiguity is clarified, never retried; authentication/permission/safety are never auto-retried; cancellation is never auto-restarted.
• Deterministic no-progress detection from normalized failure fingerprints (paths, durations, pids, hex ids masked before hashing) and diff fingerprints — never natural-language similarity.
• Explicit budgets for iterations, repairs, replans, transient retries, stagnation, clarification rounds, elapsed time, and event history. Every exhaustion names the budget, preserves evidence, and leaves the task incomplete.

Surfaces — thin adapters, no duplicated logic

• CLI: specbridge orchestrate status | show | explain | policy show|validate | events | phases. Read-only and deterministic; a test asserts no read command advances a run.
• MCP: 10 orchestration_* tools with versioned schemas, annotations, bounds, and SBMCP021–SBMCP030 mapped from the SBO### domain registry in one place.
• Plugin: /specbridge:develop added. /specbridge:implement is unchanged — the governed workflow is a new skill rather than a silent repurposing of an existing command. /specbridge:continue is now orchestration-aware.

Reviewer notes

Invariants this touches (all preserved, all asserted by tests):

• .kiro remains the source of truth — no orchestration metadata in any Kiro document; byte-identical round trips still hold.
• Stage approval remains human-only. There is no agent-accessible approval path, and a contract test asserts no registered tool name matches *_approve, *_shell, *_exec, *_git, or *_write_file.
• task_complete remains the sole completion authority. orchestration_finalize refuses completed without a verified / manually-accepted status it actually returned (SBO022).
• No arbitrary shell/filesystem/Git tool, no automatic Git mutations, no provider fallback during implementation, no nested coding agent from the plugin, no network access, no telemetry.
• No private chain-of-thought is persisted — no schema has a field for it, and tests assert its absence. The reasoning is documented in docs/orchestration/react-tao-execution.md.

Two rules are honestly documented as not hard-enforced: whether the user was genuinely asked before a plan review is recorded, and whether a clarification question is genuinely load-bearing. SpecBridge binds the review to the exact plan hash and records how it arrived, but it cannot observe the conversation. See docs/orchestration/enforcement-boundaries.md, which classifies every rule as hard-enforced, contract-enforced, or skill-guided. No Claude Code hooks are used; the rationale is documented there too.

Two defects found and fixed rather than worked around:

1. The orchestration fixtures were doing a full git init per test (7 subprocess spawns), which pushed the suite into the worker-RPC starvation this repo already documents in vitest.perf.config.ts — every test passed but pnpm test exited 1. Confirmed mine by bisecting, then fixed by making git opt-in for orchestration fixtures. Test time 1052s to 856s; git-dependent tests opt back in explicitly. No test was weakened or skipped.
2. OrchestrationError reached the CLI's fallback handler and printed a stack trace instead of a stable SBO code with remediation. Caught by smoke, fixed in packages/cli/src/cli.ts, and now asserted.

StepRelay readiness: a small synthetic fixture (two specs — one deliberately ambiguous, one committed to a mechanism — plus adversarial prompt-injection content) drives scenarios A–L: ambiguity, approved-spec conflict, planned implementation, implementation defect, transient failure, no-progress, stale plan, repository divergence, interruption, auto-approval refusal, prompt injection, budget exhaustion. It is a fixture, not a second product.

Contract snapshots changed intentionally: contracts/orchestration-contract.json is new; mcp-contract, plugin-skills, schema-versions, and cli-commands are extended additively. The pinned tests were strengthened, not relaxed — they now assert the v1.0 surface survives intact alongside the additions.

Not verified: live-model verification of /specbridge:develop is BLOCKED, not passed. No model server was running (nothing on 8080/8081/11434/8000, no .gguf found), and the harness fixture lives in a separate repository. The full case set (10 answered + 9 guard) and skill contract are committed under docs/skill-verification/cases/ and statically validate clean; docs/skill-verification/README.md records this honestly. /specbridge:continue was materially modified and also carries no v1.1 live-model result.

Validation — every command below was actually run, on Windows, at the final commit:

Command	Result
pnpm lint	pass
pnpm typecheck	pass
pnpm test	pass — 105 files / 1479 tests (from 1254), exit 0, stable over 4 consecutive runs
pnpm build	pass
pnpm check:public-contracts	pass — 12 snapshots
pnpm check:mcp-docs	pass — 47 tools
pnpm validate:plugin	pass — 12 skills
pnpm verify:plugin-bundle	pass — 11 checks
pnpm check:security	pass — 386 files, no findings
pnpm smoke	pass — 52 checks
pnpm test:perf	pass — 12 tests

Checklist

• pnpm lint, pnpm typecheck, and pnpm test pass locally
• pnpm check:public-contracts passes — stable contracts changed intentionally and additively; snapshots updated in this PR
• Documentation updated for any user-visible behavior change
• CHANGELOG entry added for any user-visible change
• Everything is in English (code, comments, docs, commit messages)
• No employer or client proprietary content — the StepRelay fixture is synthetic
• No credentials, tokens, or secret values anywhere in the diff, fixtures, or recorded test output

Security-relevant: yes. Adds T30–T32 to docs/security/threat-model.md, a "v1.1 governed orchestration safety" section to docs/security.md, and one new explicit non-claim (orchestration governs an agent; it does not make one trustworthy). No existing mitigation was weakened; every new code path can only make execution stop sooner.