codeply-cli 0.5.1 → 0.5.2

package/skills/gateguard/SKILL.md

@@ -1,133 +1,133 @@
----
-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.
-metadata:
-  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 (search the tree — Glob/Grep, or find/grep via Bash)
-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 (search the tree — Glob/Grep, or find/grep via Bash)
-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)
-
-```
-1. The current user request in one sentence
-2. What this specific command verifies or produces
-```
-
-## 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.
-
-If GateGuard blocks setup or repair work, start the session with
-`ECC_GATEGUARD=off`. For hook-level control, keep using
-`ECC_DISABLED_HOOKS` with the GateGuard hook ID.
-
-In long sessions, only the first `GATEGUARD_FACT_FORCE_FULL_DENIALS`
-fact-force denials (default 3) emit the full four-fact block; later
-denials are condensed to a single line carrying the denial ordinal, so
-near-identical blocks cannot accumulate in the context window and
-amplify model repetition loops (#2142). Retrying the same file or
-command after presenting facts never re-triggers the gate.
-
-### 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)
+---
+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.
+metadata:
+  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 (search the tree — Glob/Grep, or find/grep via Bash)
+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 (search the tree — Glob/Grep, or find/grep via Bash)
+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)
+
+```
+1. The current user request in one sentence
+2. What this specific command verifies or produces
+```
+
+## 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.
+
+If GateGuard blocks setup or repair work, start the session with
+`ECC_GATEGUARD=off`. For hook-level control, keep using
+`ECC_DISABLED_HOOKS` with the GateGuard hook ID.
+
+In long sessions, only the first `GATEGUARD_FACT_FORCE_FULL_DENIALS`
+fact-force denials (default 3) emit the full four-fact block; later
+denials are condensed to a single line carrying the denial ordinal, so
+near-identical blocks cannot accumulate in the context window and
+amplify model repetition loops (#2142). Retrying the same file or
+command after presenting facts never re-triggers the gate.
+
+### 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)