evidence-before-done

name

evidence-before-done

description

Blocks the agent from claiming a task is done, fixed, verified, ready, or complete unless that claim is backed by concrete evidence (a real command actually run, with its real output) or an explicit list of what was NOT verified. Best used reactively before presenting any completion claim to the user. Use when the user says "is it done?", "are you sure?", "did you test it?", "ship it", "mark this complete", or whenever the agent is about to claim a task is finished/fixed/working/verified. Also runs LAST as the aggregator when other proofguard guards fired, confirming their fix-required items were resolved before the done-claim is allowed. DO NOT USE for pure Q&A with no code change, and not for judging test quality (out of scope), doc sync (use docs-drift-guard), diff scope (use clean-diff-guard), secret leaks (use no-secret-leak-guard), or dependency hallucination (use dep-verify-guard).

evidence-before-done

Never say "done" without proof. If you cannot produce proof, say exactly what is unproven.

When to use

Three modes, pick the one matching what's happening:

• Guard-pass (default). Right before presenting a completion claim ("done", "fixed", "works", "verified", "ready", "shipped") to the user: gather evidence for that claim first. If you don't already have it, go get it (run the real check). If you cannot get it, state the gap explicitly instead of claiming done.
• Live. While actively implementing: verify each meaningful step as you go (run the test, read the real output) rather than batching one unverified claim for the end.
• Review. When the user explicitly asks "is this really done?" / "are you sure?" / "did you actually test it?": audit the existing claim as a critic. Produce a findings report — what's backed by evidence, what isn't. Do not silently start editing code unless asked to fix what you find.

What this guard blocks

1. No unverified completion words. Never output "done", "fixed", "works", "verified", "ready", "complete", or "should work now" as the final claim without pasting the EXACT command you ran and its REAL output next to it. Never paraphrase a result ("tests pass", "it builds fine") in place of the actual output.
2. No invented commands. Detect the real check command from the repo itself: manifest scripts (package.json → scripts), Makefile targets, CI workflow files (.github/workflows/*), or an existing test runner config. Do not guess a plausible-looking command (npm test, pytest, go test ./...) if the repo doesn't actually wire that up. If detection fails, say so — do not invent one.
3. No infra, no claim. If the real check cannot be run (missing dependencies, no test harness, sandboxed/no-network environment, no automatable check exists at all for this task), say that EXPLICITLY, and give the user a concrete manual verification step they can run themselves. Do not claim "done" or "verified" as a substitute for the missing check.
4. "Ran" vs "should work" — never conflate them. "I ran X, here is the output: Y" is a fundamentally different claim from "this should work" or "this looks correct." The second is a prediction, not evidence. Label predictions as predictions.
5. Bug fixes need a regression check. A bug fix is not evidenced by "I changed the code and it looks right." It requires a check (test, repro script, or manual repro steps) that FAILS on the old behavior and PASSES after the fix. If you can't write or run that check, say explicitly that the fix is unverified against regression.
6. Always report the residual gap. Every completion claim ends with two lists, even if one is empty: what was verified (with evidence), and what remains unverified/untested. "Nothing is unverified" is itself a claim that must be earned — don't default to it.
7. Aggregator role. If this session already triggered other proofguard guards (their footer line is visible above in the transcript: proofguard:<guard-name> — <STATUS> · ...), this guard runs LAST, right before the final done-claim. Read each guard's footer. If any says FIX-REQUIRED, the done-claim is blocked until you either resolve that guard's listed obligation or explicitly downgrade to "partially done, blocked on: ". Do not let an earlier FIX-REQUIRED get buried under a later "all done" message.

Procedure (guard-pass mode)

1. Notice the trigger. You are about to say (or the user asked) something like "done / fixed / works / verified / ready / complete / should work now."
2. Identify the claim's scope. What exactly is being claimed as done — the whole task, or one step of it?
3. Find the real check for that scope.
   • Look for a manifest script, Makefile target, or CI job that runs the relevant check. If one exists, run it. Capture the exact command and its full real output (or the relevant excerpt if long, noted as such).
   • If none exists, check whether a manual/adhoc check is reasonable (e.g. running the script directly, calling the function in a REPL, curling an endpoint). Run it and capture the real output.
   • If bug-fix scope: confirm the check fails on the pre-fix code path (or explain why that specific repro isn't practical), then confirm it passes after the fix.
4. If no check is runnable at all (no infra/environment/access): stop trying to fake it. Write the manual verification steps the user should run, and do not claim "done" — claim "implemented, unverified" or an equally honest status.
5. Check for other guards' obligations (aggregator step, see above). Resolve or explicitly flag any outstanding FIX-REQUIRED.
6. Compose the completion message with three parts: (a) exact command(s) run + real output, or explicit "could not run: <reason>" + manual steps, (b) what was verified, (c) what remains unverified.
7. Emit the guard footer (see Output) as the last line of the response.

Output

Emit this verbatim as the last line of any response where a completion claim is made:

proofguard:evidence-before-done — <PASS | FIX-REQUIRED | WAIVED(reason)> · Triggered: <what fired it> · Fixed: <n> · Verified: <exact command + result> · Remaining gap: <what's unchecked>

• PASS — a real command was run and its real output backs the claim. Never a bare PASS with no command shown.
• FIX-REQUIRED — a completion claim was about to be made (or was made) without evidence that could be produced here; state what's missing.
• WAIVED(reason) — evidence genuinely cannot be produced in this environment (e.g. no test infra). This has been disclosed to the user as an explicit gap with a manual verification step, and no false completion claim was made.

References

• references/evidence-standard.md — what counts as evidence, how to detect the repo's real check command, the "ran vs should-work" distinction, the regression-check-for-bugfix rule.
• references/aggregator-role.md — how this guard runs last, reads other guards' footers, and blocks the done-claim until their FIX-REQUIRED items are resolved.

What this guard does NOT do

It does not judge whether a test is a good test (out of proofguard's scope today; a test-quality-guard is parked in deferred/), whether docs stayed in sync with the change (docs-drift-guard), whether the diff is scoped tightly (clean-diff-guard), whether secrets leaked (no-secret-leak-guard), or whether a dependency is real and safe (dep-verify-guard). This guard only verifies the DONE CLAIM itself — that whatever is being asserted as finished has real evidence behind it, or an honest statement that it doesn't.