`check-step-collectors` cannot see `.claude/hooks/*.selftest.sh` collectors — a second self-test family it is structurally blind to

[os-steve]

Found while wiring #11514 (PR #11799). Filing rather than widening the gate in that PR: its declared surface is .github/workflows/lint.yml alone, and this is a scripts/ change.

Measured

check-step-collectors.mjs decides what to judge from two regexes:

/** A repo script path carrying `--self-test` somewhere after it on the same command. */
const SELF_TEST_TARGET = /(?:^|\s)((?:\.\/)?(?:scripts|packages)\/[\w./-]+\.(?:mjs|mts|cjs|js|sh|ts))(?=\s)[^\n]*?\s--self-test\b/;

A step is only considered once selfTestTargets(step.run).length >= 2, so its population is scripts/|packages/ paths carrying a --self-test flag. The matrices in .claude/hooks/ are neither: they live under .claude/, and they are invoked as bare executables (.claude/hooks/guard-shared-stash.selftest.sh), with no flag.

Confirmed on the PR #11799 tree, which adds a real third collector to lint.yml:

✓ check-step-collectors: 329 `run:` steps across 26 workflow(s); 2 step(s) run 2+ independent self-tests, all of them through a collector.

Still 2, with three collectors in the file.

Why this is the gate's own defect class

#10814 exists because a run: block is bash -e, so a bare sequence of independent self-tests aborts at the first failure and leaves the rest unrun — neither green nor red. The new step runs two independent hermetic matrices and is written as a tolerate-and-collect block for exactly that reason; the measurement is in PR #11799 (with the first matrix mutated red, the second still runs). But nothing enforces it. Someone "simplifying" that block into

for t in "${selftests[@]}"; do "$t"; done

restores the #10814 defect verbatim, and every gate in the repo stays green. The step therefore carries a ⛔ comment asking reviewers not to do that — prose enforcement, which is the state #10814 was filed to leave behind.

That the gate's own header says its sweep found "exactly two" matches is not a defence: it was true when written and it is what makes the blind spot invisible now — a count that stays right while its subject grows.

Options

1. Widen SELF_TEST_TARGET's path alternation to include .claude/ and make the --self-test flag optional for a path matching *.selftest.sh (self-testing is in the filename there). Note driveBlock's SCRIPT_TOKEN stubbing needs the same widening, or a .claude/ collector reaches it and throws no repo script path in command.
2. Key the population on "≥2 independent self-tests" in a spelling-independent way — a path ending .selftest.sh, or a --self-test flag, either counting.
3. Accept the blind spot and record it. Not recommended: this is the gate whose whole argument is that a static shape cannot vouch for itself.

Option 1 or 2 should keep the gate's --self-test harness driving the real block, since a collector that swallows its exit code is worse than the masking it replaces.

Note on --self-test reach

The .claude/hooks/ matrices are not the only family outside this gate's population — scripts/bump-objectui.selftest.sh uses the same *.selftest.sh naming and is likewise unmatched by the --self-test flag requirement. Whether that one is run anywhere is a separate question and is not asserted here.

[os-steve]

Claim: devx lane PM seat, session e2eac1a7-8000-5c95-9749-38aec2ace6fc, branch claude/issue-11801-step-collectors-hooks-blind.

⚠️ Sequencing flagged, not blocking: PR #11799 (#11514) is open and adds the .claude/hooks/*.selftest.sh collector block to .github/workflows/lint.yml. This card touches scripts/check-step-collectors.mjs — different file, no collision — but the block it must learn to see lives in that PR. Base off a main that includes #11799 if it has landed; if not, read the block from the PR and say which state you measured against.

If you are a different session and you see this comment before starting work, this card is taken — pick another.

---

Generated by Claude Code

[os-steve]

{
 "issue": 11801,
 "status": "done",
 "branch": "claude/issue-11801-step-collectors-hooks-blind",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/11815",
 "premise_still_valid": true,
 "summary": "The card's premise held and is re-derived, but its two proposed remedies were both falsified and the blindness had a second cause the filing had not measured. Confirmed first: with the OLD gate on a main+#11799 tree the hook step reads targets=0, collector=true, judged=false, so the count really is 2-vs-3. But the reason is not only that .claude/ is outside the path alternation: that block names NO self-test at all -- it runs `find .claude/hooks -name '*.selftest.sh'` and loops, so its only literals are a directory and a glob. Measured: with the markers widened and nothing else, the step still reports 0 targets, so options 1 and 2 as written would have left it invisible while reading as fixed. Implemented instead: recognition keyed on two self-declaring markers (a --self-test flag after ANY repo script path; a basename ending .selftest.sh) plus a separate notion of an ENUMERATED set, judged plural by construction because an enumeration is chosen precisely because the set is open. No .claude/ special case anywhere. The recognised enumeration spellings are published in the header and the failure text and each is pinned. SEQUENCING: #11799 is OPEN, not merged -- measured against main at 7e8393262 WITHOUT it, with the block read from the PR and swapped into a scratch tree.",
 "tests": "Union re-run AFTER the final commit at 563923901, worktree clean. 7 families from `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` + check:nul-bytes, all exit 0 (redirect-then-capture, never `| tail` then $?): check:agent-test-spelling; check:cross-package-test-inputs `OK: 16 package(s) read outside themselves`; check:entry-guard `145 scripts/ file(s)`; check:parse-guard `144 scripts/ file(s)`; check:pnpm-filter-targets `134/167`; check-step-collectors `329 run: steps across 26 workflow(s); 2 step(s)`; --self-test `98 assertions, 2 live block(s)`; check-nul-bytes `OK (scanned 6589 text file(s))`. NO NARROWING DECLARED -- full `pnpm lint` (eslint . --no-inline-config) run complete under the shared verify lock, exit 0 in 53s. POPULATION DELTA, before/after x two trees: main before 329 steps/26 wf/31 with 1+ target/2 with 2+/2 collectors; main after IDENTICAL (31/2/2); main+#11799 before 32 signalled/2 collectors; main+#11799 after 32 signalled/3 collectors. Exactly one entry moves and it is the intended addition -- `lint.yml::lint::Claude hook guard self-tests` from targets=[] judged=false to a judged collector carrying discovery `.claude/hooks/*.selftest.sh` bound to `selftests`. Nothing else moved on either tree. Generalising M1's path was probed SEPARATELY before adoption: adds 0, loses 0, both trees. RED/GREEN on the REAL block, mutated on disk under `trap ... EXIT INT TERM`, anchors AND sha256 both directions: unmutated routed=1/bare=0/helper=3 sha 888ca2ff287c8503 -> 0 problems, 3 collectors; collector call debarred routed=0/bare=1/helper=3 sha c0beb40ab4b83ef4 -> 1 problem 'does not route .claude/hooks/*.selftest.sh (discovered at run time, bound to selftests)'; helper deleted AND loop debarred routed=0/bare=1/helper=2 sha 2827a03291a5dfff -> 1 problem 'runs a DISCOVERED set ... as a bare sequence'; restored sha 888ca2ff287c8503 byte-identical, 0 problems / 3 collectors. HONEST NOTE: the first helper-deletion attempt matched the WRONG `run_self_test() {` (the helper body is byte-identical across all three collector steps) and mutated a different step; the anchor assert refused and the leg was re-anchored on the hook step's own loop -- the numbers above are from the re-anchored run. POST-MERGE SIMULATION (the two PRs land independently): with #11799's lint.yml swapped in, gate = 3 collectors, --self-test = 120 assertions / 3 live blocks driven under real `bash -e` (up from 98/2 = exactly one full discovery drive); restored byte-identical, git status clean. NON-VACUITY OF MY OWN ADDITIONS: blinding selfTestDiscoveries to return [] turns --self-test red with 8 NAMED failures (first attempt crashed with a TypeError -- red but unspecific, so the fixture reach is now guarded); restored byte-identical, exit 0. EVERY ZERO WITH ITS POSITIVE CONTROL: M2's literal form matches 0 live steps (no workflow invokes a *.selftest.sh by name), so its control is a committed fixture, never the population -- stated in the header and the PR. The empty-discovery #4690 case is pinned red and doubles as proof the harness feeds the block the fixture rather than the repo.",
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code