gateguard

GateGuard — Fact-Forcing Pre-Action Gate

A runtime PreToolUse hook + skill pair that forces the agent to investigate before editing. Instead of self-evaluation ("are you sure?"), it demands concrete facts. The act of investigation creates awareness that self-evaluation never did.

Implementation status: GateGuard ships as a runtime PreToolUse hook at hooks/gateguard.mjs, wired as the first PreToolUse entry in the plugin bundle. The hook physically blocks Edit / Write / MultiEdit and every destructive Bash on stdin/stdout JSON, returning {decision: "block", reason: "..."} until the agent presents facts and retries with the per-session clearance signal. This skill file is the human-readable spec the hook implements. Originally tracked in issue #106 (closed; landed as PR #108).

When to Activate

• Working on any codebase where file edits affect multiple modules
• Projects with data files that have specific schemas or date formats
• Teams where AI-generated code must match existing patterns
• Any workflow where the agent tends to guess instead of investigating

Core Concept

LLM self-evaluation doesn't work. Ask "did you violate any policies?" and the answer is always "no." This is verified experimentally.

But asking "list every file that imports this module" forces the LLM to run Grep and Read. The investigation itself creates context that changes the output.

Three-stage gate:

1. DENY  — block the first Edit/Write/Bash attempt
2. FORCE — tell the model exactly which facts to gather
3. ALLOW — permit retry after facts are presented

No competitor does all three. Most stop at deny.

Evidence

Two independent A/B tests, identical agents, same task:

Task	Gated	Ungated	Gap
Analytics module	8.0/10	6.5/10	+1.5
Webhook validator	10.0/10	7.0/10	+3.0
Average	9.0	6.75	+2.25

Both agents produce code that runs and passes tests. The difference is design depth.