tracked_in_index collapses a git ls-files fault into 'not tracked'

[randomparity]

Found during the spec review on #55's branch. Deferred from #55 with an owner
rather than swept there: converting it ripples through three callers, each
needing its own post-fault decision, and #55 already converts nine sites.

Problem

tracked_in_index (.github/scripts/check-records.sh:371) is a two-valued
predicate over a git query:

tracked_in_index() {
  local path=$1
  git ls-files --error-unmatch -- "$path" >/dev/null 2>&1
}

git ls-files --error-unmatch exits 1 when the path is not tracked — the
ordinary negative — and non-zero for a real fault, with stdout and stderr both
discarded so the status is the only signal. The two collapse, which is the defect
class ADR 0005 (landing with #55) records: a scan that could not run is reported
as one that ran and found nothing.

Three callers treat the collapsed result as authoritative:

• renumbered_elsewhere:415 — tracked_in_index "$candidate" || continue, a
  literal in-charter cmd || continue. A fault silently drops a candidate from
  the renumber search, so a genuinely renumbered record reports E-GONE.
• check_no_disappearances:581 — decides whether a record is present as a real
  tracked file, and so whether the anti-erasure rules run against it at all.
• check_gate_files:739 — decides whether a renamed gate file's successor is
  really tracked, which is what separates an exempted rename from E-GATE-GONE.

Expected

Per ADR 0005: tracked_in_index becomes three-valued — 0 tracked, 1 not
tracked, 2 fault — capturing git ls-files' status rather than discarding it,
and each of the three callers cases on the result and reports the fault instead
of its ordinary negative verdict.

Each caller needs its own decision about what the fault means, which is the work
here and the reason it is not folded into #55:

• renumbered_elsewhere — a fault on one candidate must not outrank a positive
  match on another; it is remembered and returned only if the loop exhausts.
• check_no_disappearances — a fault must not let a record skip the
  append-only rules silently.
• check_gate_files — a fault must not exempt a rename it could not verify.

A regression test per caller, using the PATH-stubbed git shape #55 introduces.
Note the callers are reached through different fixtures, and a stub keyed only on
ls-files will fire for whichever caller runs first — the stub needs to key on
the path argument as well.

Notes

.github/scripts/check-records.sh has a byte-identical mirror under
skills/tome-of-lore/assets/; the fix lands twice. just records compares them.

Best done after #55 lands, which introduces the three-valued predicate
convention and the git stub harness this would reuse.

Related: #25 (PR #54), #55, #63, #64, #66. ADR 0005 states the rule.

[randomparity]

Sibling site found during the branch review on #55, same predicate-collapse shape and worth folding into this issue rather than filing again.

scripts/list-shell-sources.sh:44, is_shell_source:

IFS= read -r first_line <"$path" || return 1

A read that fails because the file is unreadable is indistinguishable from one that failed because the file is empty, and both return 1 — "not a shell source". The file then drops silently out of the inventory that just lint, just format-check and just format consume, so it is never linted and never format-checked, with nothing reported.

The existing ((found)) || exit 1 guard catches total discovery failure but not a single file going missing, which is the reachable case.

Different mechanism from tracked_in_index (a read rather than a git query) but the same defect and the same fix shape: capture the status, distinguish an empty file from an unreadable one, and fail loudly on the latter rather than dropping the file.

Recorded in #55's spec disposition table as owned here.

[randomparity]

WORK:SCOPE — token quest-69-a4c7b2

• scope identity: tracked_in_index collapses a git ls-files fault into 'not tracked' #69 · token quest-69-a4c7b2
• outcome: tracked_in_index in .github/scripts/check-records.sh (and its byte-identical mirror) becomes three-valued, so a git ls-files fault stops reading as "not tracked", and each of its three callers reports the fault instead of its ordinary negative verdict. The sibling site named in the issue's follow-up comment — is_shell_source in scripts/list-shell-sources.sh, where a failed read reads as "not a shell source" — gets the same treatment.
• completion criteria:
  1. tracked_in_index returns 0 tracked, 1 not tracked, 2 the query could not run, capturing git ls-files' status rather than discarding it (source: issue body, Expected; ADR 0005 decision 3).
  2. renumbered_elsewhere remembers a candidate fault and returns it only if the loop exhausts, so it cannot outrank a positive match on another candidate (source: issue body, Expected).
  3. check_no_disappearances reports a fault instead of letting the record skip the append-only rules silently (source: issue body, Expected).
  4. check_gate_files reports a fault instead of exempting a rename it could not verify (source: issue body, Expected).
  5. A fault replaces the caller's ordinary negative verdict rather than accompanying it, through a per-rule coded ::error:: naming the path and git's exit status, emitted via err_full (source: ADR 0005 decisions 1 and 3, and its Consequences bullet on err_full).
  6. is_shell_source distinguishes an empty file from one it could not read, and fails loudly on the second rather than dropping it from the inventory just lint, just format-check and just format consume (source: issue comment of 2026-08-12).
  7. A regression test per converted caller, using the suite's existing PATH-stubbed git shape, keyed on the path argument as well as the subcommand (source: issue body, Expected).
  8. Both mirrors stay byte-identical; just verify green (source: repository CLAUDE.md).
• provenance: issue tracked_in_index collapses a git ls-files fault into 'not tracked' #69 body (outcome, criteria 1–4, 7); issue tracked_in_index collapses a git ls-files fault into 'not tracked' #69 follow-up comment by randomparity (criterion 6); docs/adr/0005-scan-faults-are-reported-not-collapsed.md, Accepted 2026-08-12, decisions 1 and 3 plus the err_full Consequences bullet (criterion 5, and the shape of 1); repository CLAUDE.md (criterion 8); campaign dispatch brief (worktree isolation, no-merge instruction). No user decisions taken in this run.
• exclusions: merging the PR — owner: the campaign orchestrator. Pipeline-status sites (records_in_ref's extraction) — owner: issue Sweep the pipeline-into-grep verdict idiom, which needs PIPESTATUS not a captured $? #63. A CI guard for the idiom — owner: issue Decide whether a guard should enforce ADR 0005's scan-fault rule #66. resolve_tracker's absence probes — owner: ADR 0005, accepted exception. Amending ADR 0005 — the record is append-only and this change applies it rather than changing it.
• surface: .github/scripts/check-records.sh, .github/scripts/check-records-test.sh and their byte-identical mirrors under skills/tome-of-lore/assets/; scripts/list-shell-sources.sh and a new suite beside it; the lint and format-check recipes in Justfile. Direct dependencies: the existing err_full channel and E-*-SCAN code convention, the path_exists_at three-valued shape this follows, and still_a_record, which delegates to tracked_in_index and so becomes three-valued with it.
• ambiguities: none unresolved. Two resolved by the governing decision or by measurement rather than by a user, both recorded below.
• interaction: unattended (dispatched by a $campaign orchestrator; no human reachable in this turn).

Resolved without a user decision. (a) ADR 0005 decision 2 requires a second witness where a command's status cannot separate absent from faulted, as with git cat-file. 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 its own status separates them and no ls-tree witness is added here. (b) Criterion 6 is not met by a diagnostic alone: just lint and just format-check read the lister through while ... done < <(lister), which reports the loop's status and not the lister's — the shape scripts/check-ripgrep-config.sh:70-73 already names as wrong and avoids. Both recipes capture the list to a file first, so a loud failure is one the gate can hear.

Tracking: classification governed-small-change; governing decision ADR 0005 docs/adr/0005-scan-faults-are-reported-not-collapsed.md, kind architecture decision record, status Accepted (2026-08-12), not superseded (no supersession banner in its ## Status, no later ADR references it), governing every scan whose result feeds a verdict in the record-gate scripts, and by decision 3 every predicate that can fault together with its callers. Blast radius: two mirrored shell files plus two mirrored suites, one discovery script, and the two Justfile recipes that consume it; no runtime consumers outside CI. Risk flags: gate self-protection (check_gate_files defends the gate's own files) and inventory coverage (a wrong change to the lister silently ungates scripts). Complexity: M. Decompose: no — one independently testable slice; the lister site shares the defect class, the fix shape, and the issue's own ownership.