false-completion-gate

Files (1)

• SKILL.md

SKILL.md (first lines)

## 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.

From griffinwork40/agent-framework, Apache-2.0.

More from griffinwork40/agent-framework