Summary

• New PreToolUse hook (.claude/hooks/preflight-claude-md.sh) gates git commit / git push on a verdict from a fresh-context auditor subagent (.claude/agents/claude-md-auditor.md).
• Auditor reads CLAUDE.md and the staged diff cold, judges every applicable Workflow bullet, writes a structured verdict to .claude/.last-audit.json (gitignored). Hook validates branch + HEAD + command-kind + freshness, consumes the verdict on PASS (one-shot, so re-staged content always re-audits).
• 19-case test suite (.claude/hooks/preflight-claude-md.test.sh) covers the chain-segment matcher (direct, &&, ||, ;, env-var prefix, $(), literal-mention passthrough) and the gate logic (PASS/FAIL/stale/mismatch/consumed paths).

How the loop terminates

1. Agent runs git commit -> hook denies with "invoke claude-md-auditor".
2. Agent invokes the subagent via Task -> fresh context, reads CLAUDE.md + diff, writes verdict file.
3. Agent retries -> hook reads the file, validates state, allows on PASS and consumes the verdict.
4. FAIL path echoes findings back so the agent can fix and re-audit.

Test plan

• bash .claude/hooks/preflight-claude-md.test.sh — 19/19 passing locally
• End-to-end exercised on this branch: first commit attempt denied (no audit), auditor returned FAIL with 4 findings (Test/Verify/Implement/Design), addressed each (added test suite, documented matcher + one-shot trade-offs, fixed chain-segment matcher), re-audited PASS, commit allowed; push also audited PASS before this PR opened
• After merge, each contributor sees a one-time Claude Code trust prompt for the new hook on first launch in this repo
• Recommended: restart Claude Code session after pulling to pick up claude-md-auditor as a hot-loaded subagent (otherwise it must be invoked via general-purpose with inlined instructions)

Cost / caveats

• Adds one extra Claude API call (subagent audit) + 20-60s latency per git commit / git push attempt the agent makes.
• Only gates Claude-issued git calls. Humans committing from their own terminal are not affected.