tools: absence-scan — the fixture hygiene classes as an importable scanner + CLI (git-range mode for the push guard)

The five absence classes lived inside harvest-scrub-relations.test.mjs §6 and
fired at test time. The cost they guard against is paid at push time: a
harvested fixture carrying capture identifiers reached a public PR, and a
published history cannot be scrubbed. This extracts them — predicates, walker
and LEDGER allowlist unchanged — so the dotfiles pre-push hook can run the same
check at that boundary. §6 now imports them; its assertions are untouched.

Findings never echo the matched bytes: class, file, JSON path and length only.
A reporter that prints the leak has moved it, not found it.

Classes carry a scope. The three that describe a SANITIZED HARVEST keep §6's
own scope (test/fixtures/harvested); the two byte-level ones apply anywhere.
Measured basis: all five at repo width produced 219 findings, ~205 of them
hand-authored synthetic test data — a guard that fires on those trains the
override reflex that kills it.

Verified: 20/20 harvest-scrub-relations, 14/14 absence-scan, 60/60 harvest
family. Mutant matrix over all five classes — each goes red on its own seeded
defect and green when exactly that predicate is neutered; an absence check over
a clean corpus cannot bite itself without the seed.

Two leaks surfaced, both already published and neither fixed here (see
docs/code-reviews/absence-guard-report.md findings 1 and 2).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: Gunther-Schulz

docs/code-reviews/absence-guard-report.md

@@ -0,0 +1,387 @@
+# Absence guard — fixture hygiene classes as a tool, and a push-boundary guard
+
+Built 2026-08-01. Two deliverables, sequential: `tools/absence-scan.mjs` in
+this repo (the classes, importable + runnable), and `git/hooks/pre-push` in
+the dotfiles repo (the same classes in front of every push of this repo
+family). Both unpushed at the time of writing.
+
+---
+
+## 1. What was built
+
+### `tools/absence-scan.mjs` (fork, new)
+
+An **extraction** of `test/harvest-scrub-relations.test.mjs` §6 — the five
+absence classes, the string walker, and the LEDGER allowlist. Nothing was
+tightened and nothing loosened; every predicate is the one §6 encoded on
+2026-07-31, restated from
+`docs/directives/fixture-sanitization-directive.md` rather than read back out
+of `tools/harvest.mjs` (same-parentage expectations pin the bug they should
+catch).
+
+Exports: `CLASSES` (each with `name`, `scope`, `why`, `applies`, `violates`),
+`strings` (walker), `scanDocument`, `scanContent`, `scanFile`, `scanName`,
+`scanGitRange`, `isAllowlisted`, plus the individual regexes.
+
+Class names, mapped to §6's letters:
+
+| §6 | class name | what it is |
+|---|---|---|
+| a | `b64-run` | base64-alphabet run > 200 chars |
+| b | `nested-payload` | a `source.data` that is not a `data_<sha10>` token |
+| c | `live-timestamp` | a whole-string ISO instant outside the fixed epoch |
+| d | `capture-uuid` | an 8-4-4-4-12 UUID in any string |
+| d | `capture-uuid-filename` | a UUID or an 8-hex `s-` prefix in a filename |
+| e | `raw-content` | a `text`/`thinking`/`content` string that is not a token |
+
+**Findings never echo the match.** A finding carries `{class, file, path,
+length}` and, for `b64-run`, the run length. Nothing else. A leak reporter
+that prints the leak into a terminal, a hook transcript or a CI log has moved
+the leak, not found it. This is asserted mechanically
+(`test/absence-scan.test.mjs`: "a finding never carries the matched bytes",
+and the CLI-level `assert.ok(!bad.stdout.includes(FAKE_UUID))`).
+
+**The third answer** (`docs/dev-loop.md`, "A checker has THREE answers"): a
+file that does not parse is neither skipped nor passed — it is scanned as raw
+bytes (fail closed, so the byte-level classes still apply) and named on a
+`degraded:` line. Same for a base ref git cannot resolve: the scan degrades to
+"everything at the new ref" and says so, rather than erroring.
+
+**CLI contract** (pinned; the hook depends on it):
+
+```
+node tools/absence-scan.mjs <file...>
+node tools/absence-scan.mjs --git-range <old>..<new>    # <old> may be EMPTY
+# exit 0 = clean, 2 = findings, 1 = internal error
+```
+
+### `test/harvest-scrub-relations.test.mjs` §6 (fork, rewired)
+
+§6's local `B64_RUN` / `UUID` / `ISO_INSTANT` / `EPOCH_*` / `CONTENT_KEYS` /
+`WRAP` / `strings()` are gone; the section now imports `scanDocument`,
+`scanName`, `isAllowlisted`, `CLASS_NAMES` from the tool and asserts on the
+returned findings. Assertions are unchanged (`deepEqual(hits, [])` plus the
+same vacuity floors, now read off each class's per-class `seen` counter).
+§§1–5 are untouched — their local `TOKEN` / `wellFormed` / `DATA_TOKEN` are
+the *sanitizer's* spec, stated from the documented token contract, and moving
+them would have changed their parentage.
+
+The LEDGER exclusion is no longer a `startsWith("LEDGER-")` in the test: both
+the test and the hook now ask `isAllowlisted()`, so they cannot drift into
+disagreeing about what is accepted.
+
+### `test/absence-scan.test.mjs` (fork, new)
+
+14 tests: per-class seeded-defect bites, the no-echo property, the filename
+class, scope behaviour, the degraded path, the allowlist, CLI red/green, CLI
+exit-1 on no arguments, and four git-range tests against real scratch
+repositories (red in range / green before it, `EMPTY` = new-branch push,
+deleted files skipped, unresolvable base ref degrades).
+
+### `git/hooks/pre-push` (dotfiles, new)
+
+Global dispatcher in the pre-commit neighbour's shape: German docstring
+stating WHY, silent `exit 0` in foreign repos, repo-local hook chaining with
+the local exit code winning, `--test` bite battery, `git push --no-verify`
+named as the audited escape.
+
+- **Activation:** any configured remote URL of the pushing repo contains
+  `claude-code-cache-fix`, unioned with the URL git passes as `argv[2]` (a
+  `git push <url> <ref>` need not be in the config — the union is the
+  fail-closed direction).
+- **Ranges:** stdin lines `<local ref> <local sha> <remote ref> <remote sha>`.
+  All-zero remote sha → `EMPTY..<local>`; all-zero **local** sha is a ref
+  *deletion*, nothing is transferred, so it is skipped.
+- **Scanner resolution:** the pushing repo's own `tools/absence-scan.mjs`,
+  else `~/dev/vendor/claude-code-cache-fix/tools/absence-scan.mjs` (machine
+  binding, precedent `CACHE_FIX_PROXY_TREE_PIN`).
+- **Fail-closed deviation, deliberate:** an *active* repo with neither
+  scanner resolvable is **blocked**, naming both paths and the escape. A leak
+  guard that fails open on its own misconfiguration protects nothing and does
+  not say so. Genuine unclarity (no git, unreadable stdin) stays fail-open per
+  the house pattern. Stated in the docstring.
+- **Chaining deviation, deliberate:** the chained repo-local `pre-push` gets
+  the consumed ref lines back on stdin, not `/dev/null` as in `pre-commit`. A
+  `pre-push` without its ref lines is broken by construction. The hang
+  protection is kept (closed pipe + 120 s timeout).
+
+---
+
+## 2. Checks run, with real output
+
+### The rewired suite
+
+```
+$ node --test test/harvest-scrub-relations.test.mjs
+ℹ tests 20 / pass 20 / fail 0
+```
+
+### The new CLI suite
+
+```
+$ node --test test/absence-scan.test.mjs
+ℹ tests 14 / pass 14 / fail 0
+```
+
+One real red on the way there, kept as evidence that the seeded bites
+discriminate: the first `b64-run` seed put the long run in a `text` field and
+tripped two classes —
+
+```
+✖ every class goes RED on its own seeded defect, and only that class
+  AssertionError: b64-run's seeded defect must not trip a second class
+  actual: [ 'b64-run', 'raw-content' ]   expected: [ 'b64-run' ]
+```
+
+A base64 run inside a content field genuinely *is* both an unsanitized payload
+and untokenized content; the seed moved to a `signature` field.
+
+### Harvest family, after the rewire
+
+```
+$ node --test test/harvest.test.mjs test/harvest-pin.test.mjs \
+      test/harvest-scrub-relations.test.mjs test/absence-scan.test.mjs
+ℹ tests 60 / pass 60 / fail 0
+```
+
+### MUTANT run — all five classes
+
+An absence assertion over a *clean* corpus cannot bite itself: neuter its
+predicate and it still passes, because there was nothing to find. So each
+class was bitten in two steps in an isolated tree (`cp -r tools`, the rewired
+test, the real fixtures, a symlink to `proxy/`; the repo was never touched):
+seed the corpus with that class's defect, then neuter exactly that class's
+`violates` (`CLASSES.find(c => c.name === "<cls>").violates = () => null;`).
+
+```
+CLASS: b64-run
+--- 1. seeded defect, real predicates (expect RED) ---
+✖ absence (a): no committed fixture carries a base64 run longer than 200 characters
+ℹ pass 19  ℹ fail 1   exit=1
+--- 2. same seeded defect, b64-run predicate neutered (expect GREEN) ---
+ℹ pass 20  ℹ fail 0   exit=0
+
+CLASS: nested-payload
+✖ absence (b): every source.data in the corpus is a data_ token
+ℹ pass 19  ℹ fail 1   exit=1
+neutered: ℹ pass 20  ℹ fail 0   exit=0
+
+CLASS: live-timestamp
+✖ absence (c): every whole-string ISO instant lies in the fixed-epoch family
+ℹ pass 19  ℹ fail 1   exit=1
+neutered: ℹ pass 20  ℹ fail 0   exit=0
+
+CLASS: capture-uuid
+✖ absence (d): no 8-4-4-4-12 UUID appears anywhere in the corpus
+ℹ pass 19  ℹ fail 1   exit=1
+neutered: ℹ pass 20  ℹ fail 0   exit=0
+
+CLASS: raw-content
+✖ absence (e): every content string in the corpus is a token, not capture prose
+ℹ pass 19  ℹ fail 1   exit=1
+neutered: ℹ pass 20  ℹ fail 0   exit=0
+```
+
+Each red names exactly its own §6 test, and each mutation turns exactly that
+red green. The extraction orphaned no class.
+
+A first run of this matrix printed `pass 0 / fail 1` in **both** arms — the
+isolated tree was missing `proxy/extensions/message-hash.mjs`, which
+`tools/replay.mjs` imports, so the file failed to load and the "red" said
+nothing about any predicate. Recorded because it is the shape the discipline
+warns about: a red that was not attributed is not evidence.
+
+### The hook's bite battery
+
+```
+$ python3 git/hooks/pre-push --test
+pre-push: all tests passed
+```
+
+Eight bites: the three pure-logic ones (activation predicate, zero-sha
+handling, range derivation incl. deletion and malformed lines), then, against
+real scratch repositories with a bare remote and `core.hooksPath` aimed at a
+temp dir containing only this hook —
+
+1. active repo + fixture with a synthetic UUID → **`git push` fails**, stderr
+   names `capture-uuid` and `--no-verify` and does **not** contain the UUID;
+2. active repo + clean fixture → **`git push` succeeds**, ref present on the
+   remote;
+3. foreign remote (no marker) + the same dirty fixture → **push succeeds**,
+   hook invisible;
+4. active repo, neither scanner resolvable (`FALLBACK_SCANNER` patched, same
+   technique as `pre-commit`'s `installed_version` bite) → `main()` returns 1
+   and names both paths;
+5. chaining: the repo-local `pre-push` runs, its exit code (42) wins, and the
+   ref lines arrive on its stdin verbatim.
+
+### Doctor registration
+
+No `bootstrap/doctor.py` hunk was needed or written. `check_hook_bite_tests`
+already enumerates `DOTFILES/git/hooks` by *content* (`'"--test"' in
+p.read_text()`) rather than by suffix — doctor.py:766-780, whose comment says
+the content filter exists precisely so extensionless git hooks are not missed.
+Verified by executing the check:
+
+```
+$ python3 -c "import doctor; r=doctor.Report(); doctor.check_hook_bite_tests(r)"
+OK   hook bite-test: pre-commit
+OK   hook bite-test: pre-push
+```
+
+---
+
+## 3. The scope decision, and its measurement
+
+The brief pinned range mode to "blobs whose path matches `*.json`/`*.jsonl`".
+Applying all five classes at that width was **measured first**:
+
+```
+$ node tools/absence-scan.mjs $(git ls-files '*.json' '*.jsonl')   # 31 files
+absence-scan: 219 finding(s)
+```
+
+Roughly 205 of those are hand-authored synthetic test data — English prose in
+`text` fields of `test/fixtures/insertion-1405.json`, `read-dedupe/*.json`,
+`replay-classes/corpus-*.jsonl`, `toolgc-1536.json`; `ts` fields written by
+hand; a 4-character `source.data` placeholder in
+`read-dedupe/mixed-array-shape.json`. None is a defect. A guard that fires on
+those fires on every push and trains the `--no-verify` reflex that kills it
+(`docs/dev-loop.md`: "a check that fires on a non-defect is also broken").
+
+So each class carries a `scope`:
+
+- **`corpus`** — `nested-payload`, `live-timestamp`, `raw-content`. These say
+  what a *sanitized harvest* looks like, and §6 states that scope in the same
+  breath as the classes ("every committed fixture under
+  `test/fixtures/harvested`"). Carrying the scope over is part of the
+  extraction, not a loosening of it.
+- **`any`** — `b64-run`, `capture-uuid`, `capture-uuid-filename`. These need
+  no corpus to be true: a 200-char base64 run is a payload and an 8-4-4-4-12
+  UUID is a live capture identifier wherever they sit. **Measured false-fire
+  rate outside the corpus: zero.**
+
+Re-measured with the scoping in place:
+
+```
+$ node tools/absence-scan.mjs $(git ls-files '*.json' '*.jsonl')
+scope: 21 file(s) outside test/fixtures/harvested/ — byte-level classes only
+absence-scan: 10 finding(s)
+```
+
+All 10 are in one file, and they are real — see finding 1 below. Files scanned
+under the reduced class set are counted on a `scope:` line, never silently
+passed.
+
+Wider audit (all five classes over any path) remains available by naming the
+files explicitly; the scope filter only applies where a path decides it.
+
+---
+
+## 4. Findings surfaced (not fixed — outside the write boundary)
+
+### Finding 1 — `test/fixtures/cc-transcript-shape-snapshot.json` carries live capture data, already public
+
+Introduced by `16ad235` ("feat: JSONL session-content mirror (P1 …) (#221)").
+Ten findings:
+
+- 8 × `capture-uuid` — six *distinct* session/prompt/parent UUIDs at
+  `$.assistant_sample.{uuid,parentUuid,sessionId}`,
+  `$.user_sample.{uuid,parentUuid,promptId,sessionId,sourceToolAssistantUUID}`;
+- 1 × `capture-uuid` at `$.source`, a 130-char string that is a filesystem
+  path naming a home directory *and* a session UUID;
+- 1 × `b64-run`, 448 chars, at
+  `$.assistant_sample.message.content[0].signature` — an unscrubbed thinking
+  signature.
+
+The same file also carries raw thinking prose and live wall-clock timestamps
+(caught when the corpus classes are applied to it explicitly). It is *not* a
+harvested fixture, so `harvest.mjs`'s sanitizer never touched it; it was
+hand-committed as a shape snapshot.
+
+**This is already in public history and cannot be scrubbed by editing.** It is
+an operator decision, and it is above this tier: (a) accept and allowlist with
+a written ruling, (b) re-author the snapshot with synthetic identifiers going
+forward, (c) treat it as a rotation-class incident. Nothing was changed here.
+
+Operational consequence to be aware of: because it is already committed, a
+*new-branch* push (`EMPTY..<sha>`, which scans everything reachable) from a
+repo containing it will be blocked by the new hook until one of the above is
+decided. An incremental push is unaffected — the file is not in the range.
+
+### Finding 2 — the `pr/insertion-normalization` branch carries pre-scrub-upgrade fixtures, already pushed
+
+Measured on the worktree `/home/g/dev/vendor/cache-fix-pr1` (branch
+`pr/insertion-normalization`, HEAD `b713b2f`), scanner exit 2:
+
+```
+$ node tools/absence-scan.mjs --git-range origin/main..HEAD
+     55 live-timestamp        test/fixtures/harvested/pinned-s-633915a8-26-28.json
+     21 raw-content           test/fixtures/harvested/oscillation-s-633915a8-863.json
+     13 live-timestamp        test/fixtures/harvested/oscillation-s-633915a8-863.json
+      4 b64-run               test/fixtures/harvested/oscillation-s-633915a8-863.json
+      1 capture-uuid          test/fixtures/harvested/pinned-s-633915a8-26-28.json
+      1 capture-uuid-filename test/fixtures/harvested/pinned-s-633915a8-26-28.json
+      1 capture-uuid-filename test/fixtures/harvested/oscillation-s-633915a8-863.json
+```
+
+Both files predate the 2026-07-31 sanitizer work and were harvested under the
+old scrub:
+
+- **Unscrubbed thinking signatures**: 1170 and 531 base64 characters at
+  `$.requests_864[0].msg864.content[0].signature` and `[1].signature`, twice
+  over.
+- **Raw capture prose**: 21 content strings of 289–387 characters at
+  `$.requests[*].msg863.content[*].text`.
+- **A raw session key** at `$.header.key` of the pinned fixture (38 chars,
+  matching the UUID shape — `sidToken` was not applied).
+- **68 live wall-clock instants** — `rebaseTimestamps` was not applied.
+- **Both filenames carry `s-633915a8`, an 8-hex session prefix** — exactly the
+  name shape `tools/harvest.mjs` names in its own comment as the reason the
+  filename convention moved to `s-<sha12>`.
+
+`git ls-tree origin/pr/insertion-normalization` confirms both files are
+**already on the remote**. Introduced by `1ca82f0`
+("test(insertion-suppression): real-pair check falls back to pinned fixture").
+
+This is the dispatch's own incident class, live and current, on the branch
+another session is working on right now. Two consequences:
+
+1. **The new pre-push hook will block that session's next push of this
+   branch.** That is the guard working, not a false fire — but it will arrive
+   as a surprise, and the escape is `git push --no-verify`.
+2. **Remediation is an operator decision above this tier**: the bytes are
+   already public, so the choice is between re-harvesting the fixtures under
+   the current sanitizer (fixes the branch going forward, does not un-publish),
+   accepting with a ruling, or treating the exposure as an incident. Nothing
+   was changed here — the files are outside the write boundary and belong to
+   another agent's branch.
+
+### Finding 3 — the `_sanitization` header claim is still unverified per fixture
+
+The classes verify the *content*; nothing verifies that a fixture's own
+`_sanitization` header describes what was actually applied. Both files in
+finding 2 would presumably carry a header that is now false, which is the
+2026-07-31 gap-1 shape repeating. Not built (out of scope); named.
+
+---
+
+## 5. Residuals and what was NOT verified
+
+- **§§1–5 keep local copies of `TOKEN` / `wellFormed` / `DATA_TOKEN`**, now
+  duplicated with the tool's. Deliberate: those are the sanitizer's spec at
+  the site that tests the sanitizer, and both are stated from the documented
+  token contract rather than from each other. A future tightening must touch
+  both — noted rather than silently unified.
+- **The hook is live the moment the file exists** (`core.hooksPath` points
+  into the dotfiles working tree). It was exercised only through its own
+  scratch repositories; no real push through it has happened.
+- **No push was performed** from either working copy, and both commits are
+  unpushed.
+- **Not verified:** behaviour under `git push --all` / multiple refs in one
+  push beyond the unit-level range derivation; sha256 repositories beyond the
+  `is_zero` unit bite; a repo whose `origin` URL acquires the marker only via
+  `argv[2]` was covered by unit test, not by a live push; performance of
+  `EMPTY..<sha>` on a very large tree (this repo: sub-second).
+- **`npm test` was not run** — `CLAUDE.local.md` warns the full suite can hang
+  on the production port. Targeted files only, as briefed.