plugins/git/.apm/skills/pc-run/SKILL.md

@@ -20,6 +20,15 @@ allowed-tools: Bash Read
 
 - The `SKIP` env var takes exact hook `id` values, comma-separated with no spaces: `SKIP=check-yaml,gitleaks git commit -m "msg"`. A space after a comma silently skips nothing instead of erroring.
 - Never bypass a failing hook with `git commit --no-verify` (or `-n`). Hooks are the automated QA gate, so a bypassed commit pushes the failure downstream where it costs more — diagnose it instead.
+- `- files were modified by this hook` is not a bug. A fixer hook (`trailing-whitespace`, `end-of-file-fixer`, `pretty-format-json --autofix`) rewrote a staged file, so the staged snapshot is stale and the commit is blocked on purpose. The fix is to re-stage and re-run the same commit: `git add -u && git commit`. Do NOT reach for `pre-commit install -f` here — that flag overwrites hook files in `.git/hooks/` and has nothing to do with re-staging.
+
+## Gate — `pre-commit clean`
+
+Confirm with the user before running `pre-commit clean`, on every path that reaches it — including when it turns up as the fix for a stale or broken environment. It wipes the whole cache at `~/.cache/pre-commit`, which is machine-wide and shared by every repo on the box, forcing every hook environment to be re-downloaded.
+
+> "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?"
+
+`pre-commit gc` drops only unused environments and needs no confirmation — prefer it when the goal is just to reclaim disk.
 
 ## Route
 
@@ -36,7 +45,7 @@ Determine intent from the user's request, then execute the matching operation. W
 | "autoupdate", "update versions", "bump revs" | `pre-commit autoupdate` — read `references/autoupdate.md` |
 | "gc", "garbage collect" | `pre-commit gc` — drops unused cached environments only, safe at any time |
 | "clean", "wipe cache", "rebuild from scratch" | `pre-commit clean` — read `references/clean.md` |
-| "hooks aren't running", "hook never fires", "why did a hook fail" | Diagnose — read `references/failure-patterns.md` |
+| "hooks aren't running", "hook never fires", "why did a hook fail", a hook failure whose cause is unclear | Diagnose — read `references/failure-patterns.md` |
 
 If the intent is ambiguous, default to `pre-commit run --all-files`.
 
@@ -47,5 +56,5 @@ Default to `pre-commit run --all-files`; never silently narrow to staged files.
 When hooks fail:
 
 1. Name the hook and the specific cause. Be concrete — "gitleaks blocked `config.json` (high-entropy string on line 12)", not "gitleaks failed".
-2. Suggest one concrete next step. If the cause is not obvious from the output, read `references/failure-patterns.md`.
+2. Suggest one concrete next step. Common causes and their concrete fixes are in `references/failure-patterns.md` — read it whenever the output does not already name the fix.
 3. Do not auto-fix code files, and do not edit `.pre-commit-config.yaml` — those belong to the user or to `pc-author`.

plugins/git/.apm/skills/pc-run/references/failure-patterns.md

@@ -89,13 +89,14 @@ Fix: The user (or `pc-author`) must add `args: [--autofix]` to the hook override
 
 Cause: A hook's cached environment is corrupted or out of date.
 
-Fix:
+Fix: `pre-commit clean` is gated. It wipes the machine-wide cache at `~/.cache/pre-commit`, shared by every repo on the box, so get explicit confirmation before running it — "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?"
+
 ```bash
-pre-commit clean          # wipe all environments
+pre-commit clean          # gated — confirm with the user first
 pre-commit install-hooks  # rebuild everything
 ```
 
-Or less destructively:
+Or less destructively, needing no confirmation:
 ```bash
 pre-commit gc             # remove only unused environments
 ```

plugins/git/skills/pc-run/SKILL.md

@@ -20,6 +20,15 @@ allowed-tools: Bash Read
 
 - The `SKIP` env var takes exact hook `id` values, comma-separated with no spaces: `SKIP=check-yaml,gitleaks git commit -m "msg"`. A space after a comma silently skips nothing instead of erroring.
 - Never bypass a failing hook with `git commit --no-verify` (or `-n`). Hooks are the automated QA gate, so a bypassed commit pushes the failure downstream where it costs more — diagnose it instead.
+- `- files were modified by this hook` is not a bug. A fixer hook (`trailing-whitespace`, `end-of-file-fixer`, `pretty-format-json --autofix`) rewrote a staged file, so the staged snapshot is stale and the commit is blocked on purpose. The fix is to re-stage and re-run the same commit: `git add -u && git commit`. Do NOT reach for `pre-commit install -f` here — that flag overwrites hook files in `.git/hooks/` and has nothing to do with re-staging.
+
+## Gate — `pre-commit clean`
+
+Confirm with the user before running `pre-commit clean`, on every path that reaches it — including when it turns up as the fix for a stale or broken environment. It wipes the whole cache at `~/.cache/pre-commit`, which is machine-wide and shared by every repo on the box, forcing every hook environment to be re-downloaded.
+
+> "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?"
+
+`pre-commit gc` drops only unused environments and needs no confirmation — prefer it when the goal is just to reclaim disk.
 
 ## Route
 
@@ -36,7 +45,7 @@ Determine intent from the user's request, then execute the matching operation. W
 | "autoupdate", "update versions", "bump revs" | `pre-commit autoupdate` — read `references/autoupdate.md` |
 | "gc", "garbage collect" | `pre-commit gc` — drops unused cached environments only, safe at any time |
 | "clean", "wipe cache", "rebuild from scratch" | `pre-commit clean` — read `references/clean.md` |
-| "hooks aren't running", "hook never fires", "why did a hook fail" | Diagnose — read `references/failure-patterns.md` |
+| "hooks aren't running", "hook never fires", "why did a hook fail", a hook failure whose cause is unclear | Diagnose — read `references/failure-patterns.md` |
 
 If the intent is ambiguous, default to `pre-commit run --all-files`.
 
@@ -47,5 +56,5 @@ Default to `pre-commit run --all-files`; never silently narrow to staged files.
 When hooks fail:
 
 1. Name the hook and the specific cause. Be concrete — "gitleaks blocked `config.json` (high-entropy string on line 12)", not "gitleaks failed".
-2. Suggest one concrete next step. If the cause is not obvious from the output, read `references/failure-patterns.md`.
+2. Suggest one concrete next step. Common causes and their concrete fixes are in `references/failure-patterns.md` — read it whenever the output does not already name the fix.
 3. Do not auto-fix code files, and do not edit `.pre-commit-config.yaml` — those belong to the user or to `pc-author`.

plugins/git/skills/pc-run/references/failure-patterns.md

@@ -89,13 +89,14 @@ Fix: The user (or `pc-author`) must add `args: [--autofix]` to the hook override
 
 Cause: A hook's cached environment is corrupted or out of date.
 
-Fix:
+Fix: `pre-commit clean` is gated. It wipes the machine-wide cache at `~/.cache/pre-commit`, shared by every repo on the box, so get explicit confirmation before running it — "This will wipe the entire pre-commit cache. All hook environments will be re-downloaded on next run. Proceed?"
+
 ```bash
-pre-commit clean          # wipe all environments
+pre-commit clean          # gated — confirm with the user first
 pre-commit install-hooks  # rebuild everything
 ```
 
-Or less destructively:
+Or less destructively, needing no confirmation:
 ```bash
 pre-commit gc             # remove only unused environments
 ```