Keep the gate runtime tracked under a global bin/ ignore, and say when a hook target is not

[jothimani-rajendran]

What

An adopter on Windows lost every agent hook. A global gitignore bin/ rule (from the Visual Studio, .NET and Java templates) matched .chock/bin/, so git add -A skipped the gate runtime. After that, every clone, CI checkout and git clean -x had hook configs naming a file that didn't exist. Claude Code showed SessionStart hook error ... can't open file '.chock/bin/claude_code.py'. Python exits 2 when it can't open a script, so each hook either blocks the tool call or, on clients that ignore hook failures, never runs the gate. chock check said nothing about it.

• Tracked explicitly. The new chock.scaffold.gitrules.ensure_git_rules writes chock's .gitignore rules. Both init and sync (recompile) call it.
  • It keeps .chock/log/ ignored.
  • It adds !.chock/bin/, !.chock/bin/**, !.chock/compiled/ and !.chock/compiled/**. A repository's own .gitignore outranks core.excludesFile, so the negations win.
  • Rules are appended once, and a rule the adopter already has is left alone.
  • Adopters who ran init before this change get the rules on their next chock sync. chock's own .gitignore now carries the block.
• Reported. check_dangling_hook_targets moved to validation/checks_hook_targets.py to keep checks_repo.py within the 300-line budget.
  • It now also covers .chock/compiled/*.json targets.
  • It reports a target that exists here but is git-ignored, naming the rule by source:line:pattern and giving the fix.
  • It still reports a missing target.
  • Whether a path is ignored is decided with check-ignore -q. -v alone also lists the ! negations that re-include a path, and exits 0 for them.
• Changelog Unreleased entries; docs/getting-started.md and docs/adopting.md updated.

Definition of done

• chock check → 0 errors, 0 warnings, 0 infos
• chock check --only matrix passes; matrix unchanged (no emitted surface changed)
• chock sync --repo . --check clean
• chock check --only verify clean
• Registry rescanned; no stale entries
• pytest -q: 1472 passed, 2 skipped. The new tests fail on the old code (6 of 7). One test is red in this sandbox and also red on unmodified main here: test_validate_hook_interpreter::test_a_stale_baked_interpreter_falls_back_instead_of_breaking. The system python3 has no jsonschema; this is environmental, and CI is the judge.
  • New tests/test_runtime_tracked_under_global_ignore.py uses a GIT_CONFIG_GLOBAL excludes file with [Bb]in/. It checks four things:
    • the runtime is tracked despite the global ignore, and an ignored runtime is reported with the rule named;
    • sync restores the rules;
    • a missing compiled gate is reported, and a negated path is not;
    • rules are written once and the adopter's own rules are kept.
• pytest acceptance/ ...: 21 passed (init and sync write .gitignore)
• Existing artifacts migrated: chock's own .gitignore carries the new block
• Touched manifests: none; changelog Unreleased entry added
• ruff check . and ruff format --check . clean

Claims

• No surface is described as enforcing more than it installs. This PR changes no emitted hook or installed surface. It keeps the installed runtime in version control and makes chock check say when it isn't.

Context: open-coder-ai/chock-catalog#108 works around this in its agent test kit (kit.py doctor, force-adding the generated files).

🤖 Generated with Claude Code

https://claude.ai/code/session_01CzNYfzP8ymU3r4JB9Sz8Ha

---

Generated by Claude Code