feat(hooks): pre-bash-guard protects resources shared across the machine

[Arasz]

Stacked on #29. The diff to review is the second commit, feat(hooks): guard resources shared across the machine — the first is #29 and will disappear from this PR once that merges. Happy to rebase whenever.

The guard's rules all protect the working tree: force push, git reset --hard, git clean -f, git checkout ., rm -rf. That is the right scope for one agent on one checkout, and the wrong scope for how the kit gets used. A developer box often runs several agents at once, and pkill -f dotnet does not know which dotnet was yours.

Four rules

Rule	Reaches past the project because
pkill, killall	they match by name or pattern, so they reap every match on the machine
kill with a non-PID target	kill $(pgrep -f MyApp) kills whatever else matched
dotnet build-server shutdown	it stops the MSBuild, Razor and C#/VB compiler servers machine-wide, not just this build
recursive rm on ~/.nuget, ~/.dotnet, ~/.templateengine, ~/.local/share/NuGet	every project on the machine restores from them

kill against a numeric PID, a %job spec, or a $VAR holding one stays allowed — the agent already resolved a specific process, which is the distinction that matters. pgrep only reads, so it is untouched.

The cache rule fires with or without -f, and runs before the build-output allowlist. rm -rf ~/.dotnet/bin ends in bin and was being waved through as build output.

What I left out

Node and Python caches (~/.npm, ~/.cache/pip). This is a .NET kit; node_modules is on the allowlist only because .NET web projects vendor a front-end, and a guard for another ecosystem's caches belongs in that ecosystem's kit. One line to add if you disagree.

dotnet nuget locals all --clear. Same blast radius as deleting ~/.nuget/packages, but it is also the documented fix for a wedged restore, and blocking the documented fix is how a guard earns a reputation. Left allowed on purpose — say the word if you'd rather it warned.

Verification

18 cases, both directions of every rule: the kill blocked, and a command that merely mentions it allowed. Against the parser alone (#29 without these rules), 8 go red and every allow case stays green — so the new rules do the blocking, and they are not over-firing:

FAIL: blocks pkill by pattern (exit 0, expected 2)
FAIL: blocks killall by process name (exit 0, expected 2)
FAIL: blocks killall reached by absolute path (exit 0, expected 2)
FAIL: blocks kill against a pgrep substitution (exit 0, expected 2)
FAIL: blocks kill against a process name (exit 0, expected 2)
FAIL: blocks dotnet build-server shutdown (exit 0, expected 2)
FAIL: blocks recursive delete of ~/.dotnet without -f (exit 0, expected 2)
FAIL: blocks a cache path whose leaf looks like build output (exit 0, expected 2)
PASS: allows kill against a numeric PID
PASS: allows kill -s with a numeric PID
PASS: allows kill against a PID held in a variable
PASS: allows pgrep, which only reads
PASS: allows a command that merely mentions pkill
PASS: allows dotnet build
PASS: allows rm -rf on project build output
PASS: allows a command that merely mentions the cache path
8 hook test(s) failed

All 18 pass after the change; 48 assertions green across the suite. Run on bash 3.2 (macOS) and bash 5.2 (Debian). shellcheck --severity=warning clean, docs-count and version checks pass.

These rules need #29 underneath them. Without the parser, echo "run pkill -f dotnet if it hangs" would block on the text alone — which is the defect #29 exists to fix, and I'd rather not reintroduce it one rule at a time.

🤖 Generated with Claude Code