fix(gate): accept a FILE target in run-tests.sh — unbreaks main, 913 tests were not running

[ZacxDev]

main's pytest gate is RED, and 913 tests have not been running. This unbreaks it and pins the failure mode so it cannot recur silently.

The bug

#276 (e21985a) added a file to the runner's target list:

scripts/claude-hooks/tests/test_guard_core.py

run_pytest() guarded with if [ ! -d "$d" ], which rejects a regular file:

FAIL  scripts/claude-hooks/tests/test_guard_core.py (missing directory)
RESULT: FAIL

Three consequences, all measured:

1. the gate has been red on main ever since;
2. the 913 tests in that file never ran (913 passed in 1.38s when invoked directly);
3. the wording made it worse — "missing directory" reads as an environment fault, so the natural conclusion was "the new test(gate): count skips in the pytest gate — tool precondition, pinned skip set, collected-test floors #284 gate is noisy", not "a real target is being dropped". It landed after test(gate): count skips in the pytest gate — tool precondition, pinned skip set, collected-test floors #284 made this gate loud, which is exactly the reading that trains people to click through.

The fix

• run_pytest() checks existence with -e and branches on -d/-f only to choose the message — python -m pytest accepts either. The per-target parse and attribution are untouched, so test(gate): count skips in the pytest gate — tool precondition, pinned skip set, collected-test floors #284's guarantee (a per-suite collapse stays attributable and cannot hide in the total) is preserved: a file target is reported under its own name exactly like a directory.
• HERMETIC_DIRS → HERMETIC_TARGETS (and DEVHOST_DIRS/DIRS likewise). The name asserted something false about its own contents, which is how the guard and the list drifted apart in the first place.
• The header comment now states that entries may be files, and documents the new guard. (Nothing else in the repo referenced the old names — checked.)

New GUARD 5 — validate the whole list up front, naming every bad entry

The failure mode was "an entry was added, the runner silently rejected it, and the gate failed for a reason that looked environmental." A typo, a moved suite, an unexpanded glob and a legitimate file all failed the same indistinguishable way, and only once the runner reached that suite — minutes into the output.

GUARD 5 validates every entry before anything runs and reports each bad one with a reason. --check-targets runs just that guard (no pytest, no tool precondition), which is what makes it testable in milliseconds instead of minutes.

$ bash scripts/run-tests.sh --check-targets .
run-tests: all 15 hermetic target(s) resolve.
  dir   scripts/tests
  …
  file  scripts/claude-hooks/tests/test_guard_core.py

A claim I got wrong and corrected mid-PR: I first wrote that bash does not expand globs inside an array literal. My own reachability test disproved it — injecting scripts/tests/test_*.py took the list from 15 to 32 entries. So a matching glob expands harmlessly; only an unmatched one survives as a literal *. The comment and the test case now say that instead of the opposite. (claude/RULES.md: "a comment is a claim too".)

Measurements

Controlled A/B — same tree, only the runner differs (old runner extracted from origin/main and pointed at this worktree), so the delta is attributable to the fix alone:

	collected	test_guard_core.py
before (pre-fix runner)	3385	FAIL … (missing directory)
after (this branch)	4306	PASS … (collected=913 passed=913 skipped=0)

Δ = +921 = 913 recovered + 8 from the new test file. The count is the proof, not the exit status: accepting the target without executing it would look identical from outside the gate.

Red → green matrix

New file scripts/tests/test_run_tests_targets.py (8 tests):

runner under test	result
origin/main's run-tests.sh (pre-fix, base 8b0931a)	8 failed in 0.06s
this branch (ef5306a)	8 passed in 0.06s

A capability check (_require_check_targets) makes the pre-fix state fail fast and by name. Without it the pre-fix behaviour is red for the wrong reason: the old arg parser has no --check-targets case, so the flag falls through to *) ROOT="$1", the trailing ROOT overwrites it, cd succeeds and the runner executes the entire suite — measured, each invocation blew the 120s subprocess timeout, turning 8 tests into 8 full suite runs.

Reachability, against the REAL list

Injected a bogus entry into the actual HERMETIC_TARGETS:

run-tests: FATAL — 1 unusable entr(ies) in the hermetic target list:
    scripts/bogus/reachability-probe/tests  — does not exist (typo, or the suite moved?)

exit 2, and the regression test went red as 2 failed, 6 passed — the two list-acceptance tests specifically, not a blanket collapse, so the guard fails for its own reason. Reverted and re-confirmed 8 passed; the revert was verified byte-identical against the staged blob, not assumed.

The test file labels which of its tests are regression coverage and which is an invariant guard (test_hermetic_list_still_names_the_guard_core_file pins that nobody "fixes" a future failure by deleting the entry — the runner's own error message warns against exactly that).

🔴 A second #276 regression — NOT fixed here

#276 also moved SECRET_PATTERNS out of bash-guard.py into guard_core.py. session_insight's test_patterns_cover_bash_guard still ast.parses ~/.claude/hooks/bash-guard.py, gets [], and fails:

AssertionError: could not parse SECRET_PATTERNS from bash-guard.py

It fails on any host where the hook is deployed (so it breaks the pre-push tier) and skips in the nix sandbox (synthetic $HOME → file absent → pinned skip), so the flake gate never sees it. It passed at 16:45 today and failed at 17:03 on the same tree — the host's deployed hook changed under a home-manager switch mid-session.

Different file, different failure mode, and it needs a judgement call about what the test should assert now — so I deliberately did not bundle it. The fix is a one-line repoint of _BASH_GUARD to guard_core.py. Happy to take it as the next PR.

Process note

My own … ; echo "EXIT=$?" wrapper reported exit 0 for a run whose summary said RESULT: FAIL — $? read the echo, not the pipeline. Same shape as the rc=$? case documented in #287. It is why every number above is a counted total rather than an exit status.

I also discarded one contaminated baseline: I removed a worktree while a measurement was still running against it, which produced a plausible-looking collected=1133 with a cascade of "missing directory" lines that were my own doing. Caught by reading the log rather than quoting the total.

Verification

• node: # tests 468 / # pass 468 / # fail 0 (glob form)
• nix flake check — result reported in a follow-up comment.
• shellcheck on run-tests.sh: clean apart from a pre-existing SC2155 on a line this PR does not touch.

Do not merge without the gate confirmation comment.

🤖 Generated with Claude Code