fix(pc-run): rebind the clean gate and fixer-hook rule to every branch

SKILL.md tells a dispatching agent to read the matching reference file
"and no other". The retrofit moved the `pre-commit clean` confirmation
gate out of the always-loaded body into references/clean.md, but
references/failure-patterns.md — loaded by the diagnosis route, not the
clean route — prescribes `pre-commit clean` with no gate at all. So "why
is this hook failing" could wipe the machine-wide cache at
~/.cache/pre-commit for every repo without asking.

The gate returns to the body, where every branch loads it, and is
restated at the point of use in failure-patterns.md. It is its own
section rather than a Gotchas bullet because folding it in pushed the
Gotchas ratio to 41%, whose only suggested remedy is moving it back to
references/ — the move that caused this.

The fixer-hook rule had the same shape: reachable only behind "if the
cause is not obvious from the output", which is false precisely when
pre-commit prints `- files were modified by this hook`. The fix
(`git add -u && git commit`) and the prohibition on `pre-commit install -f`
are now unconditional, and the two weakened pointers that stranded them
are restored.

Found by an independent review of this branch.

Refs #99

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
 ```