Reference for building verification gates with fail-closed design - when verification tools fail, mark results as UNVERIFIED and report clearly, never silent pass-through
SKILL.md
Verification Gate: Fail-Closed Design
"A gate that breaks silently is worse than no gate."
Overview
A verification gate that silently passes when the verification tool breaks is not a gate—it's a security vulnerability.
Core principle: Verification tools can fail. When they do, you must mark results as UNVERIFIED and report the failure clearly. Silent pass-through creates false confidence.
Violating the letter of fail-closed design is violating the spirit of safety.
When to Use
Building orchestrators, pipelines, or gates that check work before marking it complete
Any place where "tool passed" becomes a claim in a manifest, report, or downstream decision
When tool failure (network error, timeout, API limit, parsing failure) is possible
Marking batches or manifests as "verified" based on tool output
When NOT to use:
Simple linear validation (if [check], then [proceed]) - use error handling instead
Verification where tool failure causes immediate hard stop (use try/catch + propagate error)
Cases where unverified results cannot flow downstream
The Gate Function (5 Steps)
BEFORE marking any output as "verified" or "passed":
1. INVOKE: Call verification tool with full context
2. WAIT: Let tool finish completely (no timeouts before completion)
3. PARSE: Extract result AND error codes/messages (not just final status)
4. DECIDE:
- If tool succeeded: Mark as VERIFIED + record evidence
- If tool failed: Mark as UNVERIFIED + record failure reason
5. REPORT: Always distinguish verified/unverified/skipped/failed in output
Skip or hide any step = hidden vulnerability, not efficiency
Subagent ≠ verification tool. If tool actually failed, agent's report is fiction.
earthPGS mining: agent said "all verified" → tool logs showed 40% failed
"Tool was flaky, so this might pass next time"
"Might" ≠ "is verified". Mark UNVERIFIED.
Vid proof1 fail-closed: must mark false-positive as UNVERIFIED not "probably works"
"Partial screenshot covered the key part"
You didn't verify the whole output. You verified what you SAW. Mark that scope.
Evidence before claims: only mark what you actually checked
"Manifest says verified, so assume rest are too"
Manifest is a claim. Check the tool logs.
CSO lesson: description of tool ≠ tool actually running
"Different gate tool, different standard"
All gates must fail-closed. Standard is: tool failure = UNVERIFIED.
Pagis fact-check gate, Ink OCR gate, Vid proof gate: same law applies
Oracle-Specific Implementation
UNVERIFIED Marking
When verification tool fails (error, timeout, crash, API blocked, parse failure):
Record result as:
{
status: "UNVERIFIED",
reason: "[specific failure: 'agy timeout 60s' | 'network 429' | 'parse error row 42' | 'tool crashed']",
attempted: true,
tool_exit_code: [actual code or error],
evidence: [what we were able to check before failure]
}
Never:
# BAD: silently passes
return success if tool_error_code exists
# BAD: assumes tool would pass
if network_error then continue
Why: A manifest reporting "94% verified" but skipping 40% creates false confidence. The actual passed rate is 42%.
Linked to Cross-Model Verification
Fail-closed gates pair with cross-model-verify pattern: if one tool flags UNVERIFIED, dispatch second tool to decide. But both tools failing = UNVERIFIED (not "stalemate means pass").
Spirit vs Letter
Violating the letter = violating the spirit.
Tool crashes but "data looks right" → still UNVERIFIED
Tool timeout but "data was 99% checked" → still UNVERIFIED
Skipping whole category but "important items were checked" → still UNVERIFIED
If you didn't complete verification, don't claim you did.
Common Implementation Failures
Failure
Fix
Tool error silently ignored
Catch errors, set status to UNVERIFIED
Timeout continues anyway
Wait for timeout, set UNVERIFIED
Manifest counts skipped as verified
Separate verified / skipped / unverified categories
Report hides failure reason
Include failure_reason field in output
No evidence when tool fails
Record what we learned before tool broke
Mixed verification methods
All methods follow same fail-closed rule
"Probably correct" assumptions
Confidence ≠ verification. Mark UNVERIFIED.
Real-World Examples
Ink OCR Verification Gate (from memory):
agy (Gemini) crashes during recheck
Gate caught this: set status → UNVERIFIED
Did NOT: skip verification, keep raw file, continue silently
Result: blocked bad OCR, forced retry with diagnostics
Vid Proof1 Gate (from memory):
Verification returned false-positive (marked pass, was actually fail)