docs(claude-code-hooks): three gaps found by actually building a guard with this skill

[daymade]

Built a real PreToolUse guard using this skill, and hit three things it doesn't cover — each of which every hook author will hit. 63 lines added, 0 removed.

⚠️ Merge-order note — read before merging

perf/history-search-date-prefilter (pushed at e9c8235, no PR yet) carries two rounds of independent-review work on this same file, and one of its hunks edits the exact bullet this PR attaches to — "If the guard needs a release valve, make it a human gate, not an env var" — appending its own nested ⚠️ /dev/tty sub-bullet there.

This PR will conflict with that branch at that anchor. The resolution is trivial and non-semantic: both sub-bullets belong under the same parent and neither contradicts the other. Keep both, ⚠️ /dev/tty first, then Below Tier-0. Merging that branch first and rebasing this one is the cleaner order, since it is the more mature work on this file.

1. Check ShellCheck first — and record the answer (build order, step 3)

It is the de-facto standard for shell anti-patterns, so "why didn't you just use shellcheck" is the first thing a reviewer asks. Without the answer written down, every author re-derives it.

Measured on 0.11.0 against find . -name x | head -5 || echo "no" — a fallback that provably cannot fire, since || binds to the pipeline's last stage and head exits 0 on empty input:

	Result
default config	nothing reported, exit 0
--enable=all	SC2312 (check-extra-masked-returns) fires
same rule on cmd | jq . || echo bad (a live fallback)	fires identically

Three reasons that disqualifies it as the gate, each generalizing beyond this case: it is off by default (protecting nobody today), it cannot distinguish a dead fallback from a live one (blanket firing is the rule-1 false-block spiral), and its own suggested remedy is "use || true to ignore" — the opposite of the intent. It also lints files, not tool-call events.

General shape: the standard linter is the right thing to check and usually the wrong thing to delegate a blocking gate to — linters are tuned for advisory breadth, a gate needs precision.

2. Give the hook a --selftest, sized by mutants killed (build order, step 4)

The pattern existed informally in hook_pitfalls.md but was never in the build-order checklist. It is the only automatic check for the one failure bash -n and registration both structurally miss: a hook degraded into a permanent no-op — invisible by construction, because a guard that never fires produces output identical to a session with nothing to report.

The sizing rule is the part worth having, and it came from being wrong first. An earlier draft of this PR said "keep it to two probes". That is refuted by the shipped compounding-edit-review, whose own header records: its first version's two fixtures killed only 4 of 14 mutants — every behavior its comments declared load-bearing had zero coverage, including a mutation short-circuiting the anti-loop check while the selftest still printed OK. It now runs 58 cases.

So: two fixtures is the floor (one must-block + one must-pass; either kind alone is blind in one direction), and you size up by mutants killed. The real constraint is session-start wall-clock — measured ~5.3 s for those 58 cases vs ~140 ms for a two-probe liveness check. When killing the mutants exceeds that budget, split rather than shrink: cheap liveness probe on --selftest, full battery in test_hook.sh at build time.

3. Below Tier-0, make the escape hatch the correct usage (nested under rule 4)

Rule 4 is absolute for Tier-0 and this does not bend it — it addresses the correctness guards that fall short of Tier-0, which still need a way out for the legitimate case the detector cannot distinguish.

A SKIP=1 / --force escape trains exactly the reflex rule 1 warns about. Prefer an escape that is the thing you wanted them to do anyway, so taking it improves the command instead of disarming the guard. The test: if someone takes my escape hatch, is the resulting command better, or merely unblocked? Cross-referenced to the sibling Tier-0 principle already in hook_patterns.md ("the escape hatch may only make the gate stricter"), which points the other way mechanically and reads as tension until you work it out.

Placed as a nested bullet under rule 4's human-gate rule specifically so the Tier-0 scoping is structural rather than a qualifier someone can read past.

Verification

• quick_validate → valid
• Existing-skill migration gate (audit_skill_regression compare) → 0 candidates, 716 exact preservations. It earned its keep: it caught a real defect this PR introduced — a sub-bullet insertion had pushed the back half of step 4 to the end of the new text, where it read as part of the selftest advice. Fixed, re-run clean.
• One fresh-context independent review, which re-ran shellcheck itself and reproduced every measured claim; all three of its substantive findings were verified and applied (they are what produced §2's refutation and §3's placement).
• No step renumbering: step 4 is cross-referenced elsewhere in the file, so both additions extend existing steps in place.

🤖 Generated with Claude Code