fix: report a git index query that could not run, at four sites

[randomparity]

Closes #69.

tracked_in_index in .github/scripts/check-records.sh ran git ls-files --error-unmatch with its status discarded, so an untracked path and an index that could not be read were one answer. Every caller then reported an ordinary negative verdict off a query that never ran — the defect class ADR 0005 records. The sibling site named in the issue's follow-up comment, is_shell_source in scripts/list-shell-sources.sh, had the same collapse through a failed read.

Measured on git 2.50.1: git ls-files --error-unmatch exits 1 for an untracked or absent path and 128 for a real fault, so unlike git cat-file it separates the two on its own and needs no second witness.

The record gate

tracked_in_index is three-valued — 0 tracked, 1 not tracked, 2 the query could not run — and still_a_record, which delegates to it, is three-valued with it. Each caller cases on the result:

• check_no_disappearances reported E-GONE for a record sitting untouched in the tree, and skipped the append-only rules on the way. It now emits E-TRACKED-SCAN and runs neither branch. The two branches that spelled the predicate out separately — present_as_real_file && tracked_in_index against ! still_a_record — are one case, because neither shape can express a third answer.
• renumbered_elsewhere dropped a faulted candidate out of the renumber search with || continue, so a damaged index removed the real destination and the record read as erased. The fault is remembered and returned only once the loop exhausts, so a genuine match on another candidate still wins.
• check_gate_files accused the change of deleting a gate file that is present and tracked (E-GATE-TRACKED-SCAN), and exempted a declared rename whose successor it could not verify (E-GATE-SUCCESSOR-SCAN).

E-RENUMBER-SCAN now names what could not be read. Three origins reach that one code through three different git commands, and the record named as its subject is the one file the search did read.

The shell-source inventory

is_shell_source decided from read's status, which reports a clean EOF on an empty file, a clean EOF on a last line with no trailing newline, and a file that could not be opened — three unrelated things, one of them a fault. The open now decides, and read's status decides nothing. The [[ -f ]] guard above it went too: it answered "not a regular file" and dropped a tracked path missing from the worktree, one behind an unsearchable directory, and a broken symlink as silently as the case below it.

Four causes get four diagnostics, because "stage the deletion", "fix the symlink", "replace the FIFO" and "fix the permissions" are not one instruction. Two shapes never reach the open: a directory, which is a submodule's gitlink and the ordinary negative, and anything else that exists but is not a regular file — opening a FIFO left at a tracked path blocks until a writer appears and would hang every gate that consumes the list.

Sparse-checkout and assume-unchanged entries are absent from the worktree by design and are listed by git ls-files all the same, so git ls-files -v is asked which case it is, for a path that already faulted.

The lister's own git ls-files -z walk is captured rather than read through a process substitution, as are the lint and format-check recipes that consume it: while ... done < <(cmd) reports the loop's status and never the command's, so a discovery that stopped partway produced a short inventory at exit 0.

Consequence for a working tree

Deleting a tracked file without staging the deletion now reds just lint, just format-check and the commit-check hook until it is staged or the file is restored. That is the intended reading of an inventory that cannot be trusted, and the diagnostic says which case it is. A .sh name is classified without opening anything, so an unopenable one fails at shellcheck instead.

Tests

Seven assertions on the record gate, each red against the unconverted checker. Their git stubs key on the path as well as the subcommand, because tracked_in_index is that script's only git ls-files caller and its call sites are reached through different fixtures.

scripts/list-shell-sources-test.sh is new and covers thirteen cases: a shebang with no trailing newline, an empty file, a binary whose first byte is NUL, a sparse-checkout entry, a walk that stops partway, a FIFO, a dangling symlink, a submodule gitlink, an unreadable file, an unreadable empty file, an unsearchable parent, a symlink to an unreadable target, and both real recipes run against a producer that emits a partial list and fails. Each was confirmed red against the code it guards. The permission cases are skipped under uid 0 and the skip reaches the summary line, so a run that tested none of them cannot read as one that did.

.github/scripts/check-records.sh and check-records-test.sh are mirrored byte for byte under skills/tome-of-lore/assets/; just records compares them.

Verification

just verify green (exit 0) on macOS arm64, bash 3.2.57.

Review status — read before merging

The $trial-loop adversarial review ran one cycle of five iterations and ended at its iteration cap with the verdict needs-attention, not approve. Every finding across the five passes is dispositioned and the accepted ones are fixed, but the fixes made in iteration 5 — the sparse-checkout guard, the walk capture, and the symlink-target diagnostic — did not receive a confirming adversarial pass. Iteration 5 found a genuine regression this branch had introduced (sparse checkouts), so the loop was still finding real defects when the budget ran out rather than churning on its own output.

$dispel was not run, for the same reason: the cap says do not advance to the next step without a human decision.

Deferred with owners:

• just test reads its suite list through a process substitution that hides a failed discovery #83 — the test recipe keeps the status-blind process substitution the lint and format-check recipes lost here. Also the sole finding of the $detect-evil pass.
• An outranked scan fault is discarded with no trace, at two sites #87 — an outranked scan fault is discarded with no trace, at renumbered_elsewhere and gate_existed_at. A W-RENUMBER-SCAN trace was added and reverted on this branch: ADR 0005 puts reporting in the caller and specifies the error channel, so a warning-severity scan code emitted from inside a predicate is a change to that record rather than an application of it, and this branch may not amend an append-only record.

🤖 Generated with Claude Code

[randomparity]

WORK:REVIEW — token quest-69-a4c7b2

$trial-loop — 1 cycle, 5 iterations, no charter change. Final verdict needs-attention at the iteration cap, not approve.

pass	verdict	findings	suppressed
1	needs-attention	3	2
2	needs-attention	5	0
3	needs-attention	3	2
4	needs-attention	4	2
5	needs-attention	4	0

19 findings, all dispositioned: 16 accepted-fixed, 1 accepted-fixed by reverting the fix a previous pass had accepted (the W-RENUMBER-SCAN trace), 2 deferred-tracked. No finding was rejected and none is unresolved.

Not confirmed. The iteration-5 fixes — the sparse-checkout guard, the walk capture, the symlink-target diagnostic — had no adversarial pass over them. Iteration 5 found a real regression this branch had introduced rather than churning on its own output, so the budget ran out while the loop was still productive. $dispel was not run for the same reason.

Suppressions (governing-ADR re-litigations, all correctly suppressed against docs/adr/0005-scan-faults-are-reported-not-collapsed.md):

1. that tracked_in_index should emit its own diagnostic rather than returning a sentinel — decision 3 puts reporting in the caller;
2. that one generic E-INDEX-SCAN should replace the per-rule codes — decision 1 requires per-rule codes so a test can assert which site faulted;
3. that err_full is discarded in the base-ref collect pass — the Consequences section accepts that explicitly rather than fixing it;
4. that an E-TRACKED-SCAN leaves the append-only rules unrun for that record — decision 3 requires the fault to replace the ordinary verdict, not accompany it.

$detect-evil — needs-attention, 1 finding, 0 suppressed, run_id detect-evil-69-20260812-4f1a9c2e. The single finding is the just test recipe's status-blind process substitution, already deferred to #83 before the scan ran; re-affirmed against that owner, no second record.

Deferred with owners: #83 (the test recipe's walk), #87 (an outranked scan fault discarded with no trace, at renumbered_elsewhere and gate_existed_at).

Guardrails: just verify green, exit 0, macOS arm64, bash 3.2.57.

[randomparity]

Merge-result verification. CI runs on the branch head, not on the merge result, and main has advanced by 45 commits since this branch's fork point — including changes to scripts/test-fixture-helpers.sh, which the new scripts/list-shell-sources-test.sh sources.

Merged origin/main into this branch head in a throwaway worktree and ran the full suite there: just verify green, exit 0 at merge commit cd241c4 (branch 650ed49 + origin/main 044bdc9). The worktree has been removed; this branch is untouched.

No file in this change set was touched by any of those 45 commits, and the helper's public interface (clear_git_env, fixture_init, fixture_scratch, fail, SCRATCH) is unchanged there.