Home / Projects / Orchestrata Ultimate / Decisions / ADR index / ADR-0001

ADR-0001: Enforcement boundary is committed worktree state, not tool interception

ADR-0002 →

The record

• Status: Accepted
• Date: 2026-07-23
• Spec: SPEC-033 §3
• Supersedes: —

Context

Governance must bind an autonomous agent. Two prior attempts failed or were shown unsound:

1. An MCP knowledge-graph server was built and the model simply never used it. MCP tools are offered; the model decides. Advisory capability does not govern.
2. Tool-interception hooks (tool_interceptor.py, claude_governance_gate.py) gate by tool_name against a deny-list that nothing populates, and intercept_bash.py is a five-pattern regex (rm, .claude/ redirects). Everything else — python -c "open(...)", sed -i, tee, redirects, subagents, other MCP servers — passes untouched. Enumerating write channels is a cat-and-mouse the enumerator loses.

A boundary is only real if it is evaluated over something the agent cannot choose to bypass.

Decision

The enforcement boundary is the committed worktree state. At commit, a full-filesystem tree diff (not git status) is matched content-exactly against a ledger of governed write events: every governed write records the resulting content hash, and the committed tree must equal the accumulation of registered results. Any delta with no registered producer is rejected.

Legitimate non-agent writers (formatters, codegen, pre-commit hooks) are registered governed writers — an allowlist of state producers, not a denylist of commands.

PreToolUse/PostToolUse hooks are retained as a fast advisory nudge (deny + inject the deterministic answer) and are explicitly not the security boundary.

Alternatives rejected

• Tool-name matching / command denylists — provably incomplete (above); the failure mode that motivated this ADR.
• MCP tools as the governance surface — advisory by construction; empirically ignored.
• Sandboxing every write syscall — sound but disproportionate; and it still needs a policy for what a legitimate write is, which the producer registry supplies more cheaply.

Consequences

• Closes the Bash / python -c / subagent / other-MCP escape hatches, because the predicate does not care which tool produced a delta.
• Trust moves, and is named honestly: the boundary is now the registered producer set, not "the model cannot act." Provenance is a harness-side record, not reconstructible from source.
• Requires an event ledger (what was written, by which governed action, correlated to the commit diff) — a new, load-bearing component (SPEC-033 B1c).
• Requires a bootstrap path for first commits and never-before-seen files, or new files launder through the "no prior graph state" gap (B1b).
• Security detection must use the full-tree diff; incremental extraction is a performance optimisation only and must never be the security key (a write nobody declares would otherwise never be reindexed, never diffed, never rejected).

Provenance

Round-1 adversarial review (all four reviewers, code-verified: the shipping gate is fail-open and allow-by-default). Round-2 confirmed the re-grounding as sound design; Fable: "a state-based predicate genuinely does not care which tool made the change." Round-3 refined the producer-registry attestation (see ADR-0017).

Related ADRs

• Amended by: ADR-0030
• Also mentioned: ADR-0017

Rulings cited

None.

Specs cited

• SPEC-033