mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-04-14 22:13:41 +08:00
dd2962ee92
Bugs fixed: - B1: JS gate messages still said "cat one real record" -> redacted/synthetic - B2: Destructive bash key used 200-char truncation (collision bypass) -> SHA256 hash - B3: sanitizePath only stripped \n\r -> now strips null bytes, bidi overrides, all control chars - B4: Tool name matching was case-sensitive (latent bypass) -> lookup map normalization - B5: SKILL.md Gate Types missing MultiEdit -> added with explanation Tests added: - T1: MultiEdit gate denies first unchecked file (CRITICAL - was untested) - T2: MultiEdit allows after all files gated 11/11 tests pass. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
121 lines
4.4 KiB
Markdown
121 lines
4.4 KiB
Markdown
---
|
|
name: gateguard
|
|
description: Fact-forcing gate that blocks Edit/Write/Bash (including MultiEdit) and demands concrete investigation (importers, data schemas, user instruction) before allowing the action. Measurably improves output quality by +2.25 points vs ungated agents.
|
|
origin: community
|
|
---
|
|
|
|
# GateGuard — Fact-Forcing Pre-Action Gate
|
|
|
|
A PreToolUse hook that forces Claude 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.
|
|
|
|
## 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 Claude 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.
|
|
|
|
## Gate Types
|
|
|
|
### Edit / MultiEdit Gate (first edit per file)
|
|
|
|
MultiEdit is handled identically — each file in the batch is gated individually.
|
|
|
|
```
|
|
Before editing {file_path}, present these facts:
|
|
|
|
1. List ALL files that import/require this file (use Grep)
|
|
2. List the public functions/classes affected by this change
|
|
3. If this file reads/writes data files, show field names, structure,
|
|
and date format (use redacted or synthetic values, not raw production data)
|
|
4. Quote the user's current instruction verbatim
|
|
```
|
|
|
|
### Write Gate (first new file creation)
|
|
|
|
```
|
|
Before creating {file_path}, present these facts:
|
|
|
|
1. Name the file(s) and line(s) that will call this new file
|
|
2. Confirm no existing file serves the same purpose (use Glob)
|
|
3. If this file reads/writes data files, show field names, structure,
|
|
and date format (use redacted or synthetic values, not raw production data)
|
|
4. Quote the user's current instruction verbatim
|
|
```
|
|
|
|
### Destructive Bash Gate (every destructive command)
|
|
|
|
Triggers on: `rm -rf`, `git reset --hard`, `git push --force`, `drop table`, etc.
|
|
|
|
```
|
|
1. List all files/data this command will modify or delete
|
|
2. Write a one-line rollback procedure
|
|
3. Quote the user's current instruction verbatim
|
|
```
|
|
|
|
### Routine Bash Gate (once per session)
|
|
|
|
```
|
|
Quote the user's current instruction verbatim.
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### Option A: Use the ECC hook (zero install)
|
|
|
|
The hook at `scripts/hooks/gateguard-fact-force.js` is included in this plugin. Enable it via hooks.json.
|
|
|
|
### Option B: Full package with config
|
|
|
|
```bash
|
|
pip install gateguard-ai
|
|
gateguard init
|
|
```
|
|
|
|
This adds `.gateguard.yml` for per-project configuration (custom messages, ignore paths, gate toggles).
|
|
|
|
## Anti-Patterns
|
|
|
|
- **Don't use self-evaluation instead.** "Are you sure?" always gets "yes." This is experimentally verified.
|
|
- **Don't skip the data schema check.** Both A/B test agents assumed ISO-8601 dates when real data used `%Y/%m/%d %H:%M`. Checking data structure (with redacted values) prevents this entire class of bugs.
|
|
- **Don't gate every single Bash command.** Routine bash gates once per session. Destructive bash gates every time. This balance avoids slowdown while catching real risks.
|
|
|
|
## Best Practices
|
|
|
|
- Let the gate fire naturally. Don't try to pre-answer the gate questions — the investigation itself is what improves quality.
|
|
- Customize gate messages for your domain. If your project has specific conventions, add them to the gate prompts.
|
|
- Use `.gateguard.yml` to ignore paths like `.venv/`, `node_modules/`, `.git/`.
|
|
|
|
## Related Skills
|
|
|
|
- `safety-guard` — Runtime safety checks (complementary, not overlapping)
|
|
- `code-reviewer` — Post-edit review (GateGuard is pre-edit investigation)
|