CLAUDE.md is behind the code: the DeterministicPass contract and 5 shipped surfaces are undocumented

[sroussey]

CLAUDE.md is treated as this repo's contract by reviewers and agents, and is unusually good at it. After the 08-17→08-24 window it is measurably behind:

• DeterministicPass / preempts / assertsCompletePopulation appear nowhere — grep -c "DeterministicPass\|preempt\|row-completeness" CLAUDE.md = 0. This is the invariant that prevents the data-loss class PR Deterministic passes may not preempt what they cannot supply #311 fixed: covers ⊇ clears for columns, complete for rows, undeclared = decline. The code JSDoc is excellent; the spec is silent. Given that the class shipped this window — tables cleared then refilled with a strict subset, markResolved called, no dead letter, same answer on every replay — this is the single most load-bearing omission.
• sec eval management|related-party|spac-sponsors|spac-profile|spac-classification|underwriters|offering-tables|use-of-proceeds|beneficial-ownership — nine commands, ~1,800 LOC: 0 mentions.
• daily_index_cursor and the daily-index catch-up leaf, including the "EDGAR 403 means two different things" rule in dailyIndexPublication.ts: 0 mentions.
• sec spac process --force <extractor csv> / skip-successful semantics, and sync spacs --only: 0 mentions.
• The merger-proxy filterTodo is documented with 2 clauses; backfillDescriptors.ts:233-249 has 3, and the third (the resolved SECTION_NOT_FOUND trace) is what makes it converge.

Two older drifts worth folding into the same pass: the four-cycle-old self-contradicting JSDoc in ExtractorRunRepo, and the two-cycle-old one in classifySpacCandidate.

Found during the 2026-08-24 review. Snapshot: workglow-dev/prd → analysis/grades/2026-08-24/sec-detailed.md.

[sroussey]

Verified at 9a1da01: 1 of 5 bullets done, plus both older drifts, plus a structural fix this issue did not ask for. The headline bullet is unchanged.

Done

• The structural half. b2a58d3 splits CLAUDE.md 3,062 → 334 lines and moves the rest to docs/fetch-and-storage.md (422), docs/extraction.md (709), docs/identity.md (497), docs/spac.md (678), docs/eval.md (341), later joined by docs/verification.md (181). The stated reason is the right one: "loaded in full at the start of every session, and mostly not about how to work in the repo."
• Bullet 5 — the merger-proxy filterTodo. docs/extraction.md:632-640 now documents the third clause and why MODEL_EMPTY is deliberately excluded, matching backfillDescriptors.ts:236-246.
• The ExtractorRunRepo JSDoc contradiction (was 4 cycles). Gone — and better than a doc fix: the corpus-wide Set it described is replaced by successfulRunKeysForFilings, one chunked lookup per page and per extractor, with the reason recorded ("at Form D's size that is hundreds of MB resident before the first filing is fetched, and every --shard process paid it in full").
• Dead-letter vocabulary re-counted: 16 declared, 16 listed in docs/extraction.md:123-126. No drift.

Not done

• Bullet 1 — the headline. grep -rn "DeterministicPass\|preempt\|row-completeness" CLAUDE.md docs/*.md ARCHITECTURE.md SPEC.md = 0 hits, in the window that rewrote every one of those files. deterministicPass.ts itself is untouched this window. This remains the single most load-bearing omission: it is the invariant that stops a cleared table being refilled with a strict subset.
• Bullet 2 — the sec eval <section> family. docs/eval.md covers eval extract, eval s1 and eval unit-terms only; grep -rn "eval management\|eval related-party\|eval spac-sponsors\|eval beneficial-ownership" docs/ CLAUDE.md = 0, while src/cli/groups/eval.ts and src/eval/run*Eval.ts still ship them.
• Bullet 3 — daily_index_cursor and the daily-index 403 rule. SPEC.md:202 documents --from; the cursor table and dailyIndexPublication.ts's "EDGAR answers 403, not 404, for a daily index it never published — and also 403 for a client it is refusing" rule appear nowhere. (The rate-limit 403 is documented at docs/fetch-and-storage.md:86,133; that is a different 403.)
• Bullet 4 — spac process --force <csv> / sync spacs --only. 0 mentions.
• classifySpacCandidate. src/task/spac/classifySpacCandidate.ts:279 still reads "Note what is deliberately NOT decided here: whether the as-filed SGML header said 6770", above the code that decides on it. Third cycle.

Two adjacent gaps found this window are filed separately as #338 (submissionFetchKind's undocumented extractor union, and five env vars read by production code that appear in no document) rather than widening this issue's scope.

Verified during the 2026-08-31 review.

---

Generated by Claude Code