An agent's STATUS: COMPLETE is a claim — only disk state, git diffs, and ledger entries are proof.

Principle

Trust But Verify

The canonical failure

The phantom-edit pattern has a specific shape.

Four steps. Two happy lies. One production regression.

STEP 1

Builder

"deleted X,

modified Y"

STATUS: COMPLETE

→

STEP 2

Validator

grep -r "oldsym"

→ 0 matches

PASS ✓

→

STEP 3

Finalizer

git diff HEAD

→ empty

files never touched

→

STEP 4

User

finds regression

in production

Two self-reports agreed. Neither was evidence. The phase finalizer was the first thing in the chain that looked at disk — and that's why the bug reached prod.

Every part of the task system exists to make this specific shape impossible by default.

The asymmetry

What the agent produces vs. what the system needs.

Claim

"I'm done."

Optimized output that looks like completion. The agent has no mechanism to penalize itself for lying.

• STATUS: COMPLETE
• well-formatted summary
• plausible-sounding notes
• confident prose

Proof

"The disk agrees."

Observable state the agent cannot fake. Questions answered by the filesystem, not by the agent's output.

• file exists on disk
• symbol in AST
• build exits 0
• git diff non-empty

A claim without evidence is a guess dressed as a report.

The evidence layer

Four kinds of proof. Each kills a specific lie.

Every evidence kind exists because the matching failure was observed in production.

Evidence

Proves

Failure mode it kills

Commit hash

Work was committed

"Agent reports done; never ran."

Screenshot

UI behavior was observed

"Feature works; selector never resolved."

Ledger entry

File was written this session

"Edit claimed; file existed from prior run."

filesExpected

Declared contract met

"Agent optimized the edit path away."

The enforcement stack is archaeology of past bugs.

The design shift

Stop asking the agent. Ask the disk.

Trusting design

"Did the agent say it completed?"

You're asking the optimizer to grade its own output. The answer is always yes — that's what it was optimized for.

→

Verifying design

"What would need to be true on disk for this to be done?"

Then you build the machinery to check exactly that. The question stops being about the agent and starts being about observable state.

This is not skepticism about agents — it's alignment. Verification is how you point the optimizer at the target you care about.

The enforcement stack

A claim enters — four independent checks — proof exits.

Each layer checks disk, not self-report. None depend on any other believing the agent.

agent: STATUS: COMPLETE

↓

1filesExpected contract — declares what must be on diskdeclaration

2PostToolUse Hook — appends every Write/Edit to task-{id}.ledger.jsonlrecording

3Stop Hook — checks declared contract against ledger + diskenforcement

4Validator — checks spec independently against real statecross-check

↓

proof: disk matches declared contract

No layer trusts the agent. No layer trusts another layer's trust of the agent.

The discipline

Self-reported completion is a claim. Disk state is proof.

Agents optimize for what looks like success. Verification is how you align that optimization with yours — by asking questions only the filesystem can answer.