false-completion-gate

Sub-agent contract

/contract

This skill fires when a session (or a returning sub-agent) is about to declare a state-mutating task complete — a Done terminal state, a success summary, or a passing completion verdict. The core invariant: a completion claim must be backed by execution receipts and a fresh artifact read-back, never by the assertive language of the claim itself. Claim and evidence must be structurally separated — the base agent fuses them, narrating "done" straight from in-context memory of a tool result it never re-observed. That fusion is exactly how "silent success" propagates a false Done into downstream steps that then compound on a foundation that was never real.

Phase 1 — Claim decomposition. Before emitting the Done, decompose the pending completion into a checklist of concrete, receipt-checkable assertions. Each assertion names: (a) the deliverable ("feature X implemented", "tests green", "branch pushed"), (b) the producing action that must have fired to make it true (an Edit/Write to a specific path, a specific test command, a git push), and (c) the durable location that would prove it (file path + expected content, test-output line, commit SHA). Add a goal-substitution assertion: if the original goal was diagnostic (interrogative — "why does X", "what causes Y") but the deliverables are all implementation, the diagnostic answer is itself a required assertion — its absence is an UNBACKED completion, because the question was silently swapped for a patch.

Phase 2 — Receipts reconciliation. Dispatch one read-only reconciliation auditor (subagent_type: "awa-private:research-agent" — locked to Read/Grep/Glob; add a Bash-capable type with isolation: "worktree" only if a postcondition needs a command rerun, e.g. re-running the test). It receives ONLY the assertion checklist + the user's original goal — never the orchestrator's success narrative. For each assertion it independently establishes: ledger_match — did the producing action actually appear in this session's tool-call history? postcondition — read the durable artifact from source now (file content, fresh test output, git log/git status) and check it matches the claim. durable_location — confirm evidence is a real location, never transcript-only. The orchestrator hands the auditor this session's tool-call history as the ledger; if that history is unavailable or truncated (a hand-off, a compacted context), the auditor marks the assertion UNVERIFIABLE rather than assuming the action fired — the gate fails closed, never open. Returns a receipts table: {assertion, ledger_match: yes|no, postcondition: pass|fail|unverifiable, durable_location, verdict: BACKED|UNBACKED|UNVERIFIABLE}.

Gate verdict (merge):

• All assertions BACKED → VERIFIED: emit the Done, attaching the receipts table as the evidence block (durable locations, not prose).
• Any UNBACKED (no producing action in the ledger, or read-back contradicts the claim) → FALSE-COMPLETION: do not emit Done. Surface the exact unbacked assertion(s) and what the read-back actually showed.
• Any UNVERIFIABLE (external side-effect with no fetchable receipt) → never pass as a confident Done; surface tagged [needs-human-review].

Phase 3 — Bounded repair. On FALSE-COMPLETION, route only the unbacked assertions to a targeted repair pass — re-execute the missing producing action or fix the failing postcondition — then re-run Phase 2 on just those assertions. Cap at 2 repair cycles. If an assertion is still UNBACKED after 2 cycles, emit a Blocked terminal state naming the exact unbacked assertion and the missing receipt — never a Done. The asymmetry is safe by construction: the gate can only ever downgrade a false Done to an honest Blocked/needs-review; it cannot manufacture a completion that wasn't real.

When to invoke: before any Done / success summary / completion verdict in state-mutating work (implementation, bug fix, refactor, migration, multi-file write, deployment) — especially when the belief that it worked rests on in-context memory of a tool result rather than a fresh read-back, or when the run spanned many steps and the early "success" was never re-observed.

Skip when: the session is text-terminal (a pure explanation, architecture walkthrough, or Q&A that mutates no artifact — there are no receipts to reconcile); the work already failed loudly (no false-completion risk); or an orchestrator that already verifies its own completion (ship, mint, heal) is driving — invoke once at the outer Done, not per inner step.