[Hooks Cannot See] (1) Teach two hooks the checks they could not see

[EdbertChan]

Summary

Small helper scripts watch Claude while it works and nudge it when something looks off. Two of them were blind to things they should notice.

The first nudges Claude after many edits with no testing. It missed shell test scripts and container builds, so it nagged wrongly four times.

The second checks that the helpers are current. It never checked that each one still exists. One pointed at a deleted folder and did nothing all session.

Now the first knows those test commands. The second reports missing helpers, and says "unchecked" when it cannot look. The installer warns when linking from a temporary copy.

Review Claim

Approve two detector fixes and one installer warning, each with a test that fails before the change and passes after.

Review Lane

behavior

Review Unit

engine-runtime

Safety Invariant

Both hooks stay inject-only and fail-open; neither gains the ability to block. The hook-freshness sweep is read-only over settings.json and reports three outcomes, not two: an unreadable or unparseable file says "unchecked", never "clean". install.sh changes no link target at all — it only prints a warning, which is why tests/test_install.py still passes unmodified.

Slice Rationale

The two detector fixes and the installer warning ship together because they are the same defect class: a gate that reported clean when it had not actually looked. Splitting them would separate the finding from its evidence.

install.sh is in scope because it is the cause of the dead link that hook-freshness now detects; the detector alone would leave the source unaddressed.

Non-goals

Does not make either hook able to block. Both stay advisory.

Does not change where install.sh puts its symlinks. An earlier draft redirected a worktree install to the main checkout, and tests/test_install.py:290 correctly rejected it — installing from a worktree is how a branch gets tested.

Does not change corpus/. The prose rule from the same reflect pass is slice (2), split out because docs/ecosystem.md forbids engine runtime and corpus lessons in one PR.

Does not add the remaining findings from that pass: the gate-blame-needs-evidence detector defects, the pipeline-exit-status detector, and the $PIPESTATUS-is-a-no-op-in-zsh correction. Those are a separate branch.

Test Plan

Test Plan

Fail-before, with the detector reverted to origin/main and the new tests in place:

AttributeError: module 'detect' has no attribute 'unresolvable_hooks'
Ran 18 tests in 0.028s
FAILED (errors=5)

AssertionError: Lists differ: [4] != []
Ran 13 tests in 0.032s
FAILED (failures=3)

Pass-after, on the rebased branch, exit code read off each command directly rather than off a pipeline:

=== narrow-the-scope ===
Ran 13 tests in 0.140s
OK
exit=0
=== hook-freshness ===
Ran 18 tests in 0.073s
OK
exit=0
=== install worktree ===
Ran 3 tests in 2.933s
OK
exit=0
=== gates ===
check_hook_test_coverage exit=0
check_ecosystem_boundaries exit=0
check_skills_three_harnesses exit=0
check_skill_file_refs exit=0

Whole repo suite:

Ran 463 tests in 1146.986s
OK
EXIT=0

• python3 -m unittest discover -s engine/hooks/narrow-the-scope/tests
• python3 -m unittest discover -s engine/hooks/hook-freshness/tests
• python3 -m unittest tests.test_install_worktree_repo_dir
• python3 scripts/check_hook_test_coverage.py engine/hooks/narrow-the-scope
• bash scripts/run_all_tests.sh — 49 directories, 0 failures

Revert Plan

Revert Plan

• Safe to revert? Yes
• Revert command: git revert <sha>
• Post-revert steps: None. Both hooks return to their previous behaviour; install.sh stops printing the worktree warning. No installed link changes either way.
• Data migration? No

[EdbertChan]

This pull request is part of a Mergify stack:

#	Pull Request	Link
1	[Hooks Cannot See] (1) Teach two hooks the checks they could not see	#518	👈
2	[Hooks Cannot See] (2) Require the output to entail the claim, not merely agree	#519

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_b1a3ce57-72e1-4f61-a498-820a1697df4b)

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request

[EdbertChan]

Mergify repair stopped: missing required check validate