fix(hooks): make driftcheck a nudge and close two silent-failure modes

[ulises-c]

Closes #69. Closes #67.

Both issues live in agentic-ai/Claude/hooks/driftcheck.sh, so they're fixed together.

#69 — nudge instead of block

The Stop hook exited 2 on any shebang/exec-bit inconsistency, blocking the agent from
finishing until it acted on the findings. For a style check that's heavy-handed: a false
positive (paths that drifted outside a repo's .driftcheckignore globs) pressures the
agent toward the mechanical chmod +x, which for intentionally non-executable sourced
scripts is exactly the wrong action.

Findings now go out as hook JSON with exit 0, plus human-readable lines on stderr for
direct runs:

driftcheck.sh: convention drift (not blocking):
  - has shebang but missing execute permission: path/to/settings.sh
{"systemMessage":"driftcheck: has shebang but missing execute permission: path/to/settings.sh\n"}

trap 'exit 2' ERR is gone, so internal script errors can't block a stop either.

#67 — two failure modes bypassed the exit-2 trap

• git ls-files failure was invisible. Process substitution hides the exit status
  from pipefail and the ERR trap, so a corrupt index yielded zero lines and a clean
  "no violations" pass — a guard reporting all-clear having checked nothing. The listing
  is captured before the loop and a failure exits 1.
• Unset HOME exited 1, not 2. set -u treats it as an expansion error and
  terminates before the ERR trap fires. Now an explicit, diagnosed exit 1.

Exit 1 is the new "the check could not run" signal. This hook no longer uses exit 2 at all.

Tests

validate.sh gains four driftcheck.sh regression tests, each verified to fail against
the pre-fix hook (the two silent-failure bugs are precisely the class that hides from a
run-it-and-see check):

[ OK ] driftcheck.sh: flags a shebang script missing its execute bit
[ OK ] driftcheck.sh: honors .driftcheckignore patterns
[ OK ] driftcheck.sh: fails loudly when git ls-files fails
[ OK ] driftcheck.sh: unset HOME fails deliberately

The .driftcheckignore test covers #69's note that the ignore parsing was silently
dropped by a revert once before. The existing repo-state check now distinguishes three
outcomes: fail on non-zero exit, warn on reported drift, pass on clean.

Full validate.sh passes; shellcheck --severity=warning clean on both changed scripts.

Docs

agentic-ai/Claude/README.md hook section, the TODO.md manual-check line, and a
docs/CHANGELOG.md entry.

Note

~/.claude/hooks/driftcheck.sh symlinks into the working tree, so the new behavior is
live on whatever branch is checked out — merging this makes it the default again.

🤖 Generated with Claude Code