[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

---

Note

Low Risk
Changes are advisory-only, fail-open hook injections and a non-blocking install warning; no link targets or blocking behavior change.

Overview
Fixes two advisory hooks that could look healthy while they had not actually checked, plus a preventive worktree install warning.

hook-freshness now reads registered hook commands from ~/.claude/settings.json, verifies script paths exist, and injects context when paths are missing or the file cannot be read (unchecked, not silent). That advisory is combined with the existing stale-checkout message in decide / decide_json.

narrow-the-scope treats more Bash runs as verification (VERIFY_RE: shell *test*.sh, docker build / compose, node --check) and clears a file’s edit streak when a Bash command mentions that file’s basename (e.g. running the script you just edited).

install.sh prints a WARNING when run from a git worktree (symlinks target the worktree and break after removal); link targets are unchanged.

New tests cover the unresolvable-hook sweep, shell/docker fixture sequences, and worktree warning behavior.

^{Reviewed by Cursor Bugbot for commit 5a64e2e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[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]

Queued — the merge queue status continues in this comment ↓.

[EdbertChan]

Mergify repair stopped: missing required check validate

[EdbertChan]

Mergify repair stopped: required check failed: test. The retry cap was reached for current head 17a2b07.

[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_0486a1d5-1622-4928-91bc-6d05df7a2c8f)

[EdbertChan]

@Mergifyio queue

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-09-13 19:23 UTC · Rule: admin-bypass · triggered by @EdbertChan with the @mergifyio queue command
• ✅ Checks passed · on draft merge queue: checking #518 on main (0d0daba), stacked on #470 and #483 #573
• ✅ Merged — 2026-09-13 19:29 UTC · at 17d64c734b810541b51cca7dc1926d2710495efb · squash

This pull request spent 5 minutes 30 seconds in the queue, including 4 minutes 45 seconds running CI.

Required conditions to merge

• check-success = lint
• check-success = test
• check-success = validate