docs: the review-loop entries answer a caller, and the argument has one home (#473)
#464's fourth slice. `editor_patch` 224 lines → 101, `editor_list_markers_split` 104 → 51,
`reader` / `editor` 83 → 64. API.md 5,695 → 5,502; design-notes 2,611 → 2,746.
One of the three entries needed deleting rather than moving. `## The review loop` in
design-notes already carried the whole `editor_list_markers_split` argument inside its
flattened-view bullet — the licence's scope, why `doubled` compares values rather than kinds,
the marker shape and each false positive that narrowed it — and even names API.md's own
version of the error in passing. So that entry is 51 lines pointing at the home that existed,
not a move. The same destination already held the #250 block contract and the #174 prose
floor, so `editor_patch`'s and `reader` / `editor`'s reasoning about both went the same way.
What had no home is the heading gate. #331, #375 and #376 appeared nowhere in design-notes,
though that gate is the one place in the loop that refuses part of a reply with no defect
anywhere in it. `## The review loop` gains two subsections, and the existing flattened-view
bullet gains a heading of its own, so all three cross-references land on a place rather than
on a 480-line section:
- `### What the review loop's structure counts count`
- `### A heading fall with nothing else wrong`
- `### The flattened view, and the one conversion it polices`
API.md keeps which fields are on the line and what each means, which of them refuse a block
and which are costs on the record, and the limits to know before counting a corpus off one.
`discarded`'s three values, the six conditional fields, the five marker counts and the four
heading-attribution fields are tables now.
Five real losses were caught by the move checks, which is the first slice where they have
caught any. Two before the first commit: `1.6%`, the round that dropped 5 of 7 lists and 13 of
47 list items while its length barely moved, which is the measurement that argued for a
structure count existing at all; and `xxxix`, the roman-marker cap that is what excludes `cm.`
and `ml.`, so a design-notes sentence already saying "which `cm.` and `ml.` are not" was
carrying a conclusion with its reason left in API.md. Three more after round 1, all of them
invisible to a digit sweep. Every one went into the text that already owned it.
Three review rounds, five notes, all fixed. Round 3 found nothing new, which is the merge
condition.
Round 1 (`d3a59bc` → `e6843d3`) — a figure check that cannot read a spelled-out number.
"three samples on one document" was the only measurement of a legitimate round available
before `chars_before` / `chars_after` existed, and the move dropped it while the figure check
reported 61 of 61. Extending the check to number-word phrases found two more real losses it
had passed: `(see)` as "three letters and no numeral", and the prose condition on
`navigation_lost`. Also this round: `doubled` read as a self-contradiction, "per item, not a
total" three lines above "every count is a block total", both true of the code and together
unreadable; and one sentence carrying four claims behind a colon, a `which` and two `so`
clauses, split into four.
Round 2 (`e6843d3` → `2aacc17`) — a count named "the count" in a subsection that has two.
`navigation_lost.headings` compares the joined body before against after and carries the prose
condition; `headings_dropped` is read per block inside `applyBlockEdits` and carries none of
it. The bullet names the joined count now. Its reason also arrived two bullets after the fact
was used, so the two are swapped. Sweeping that class found a third instance in prose this
slice carried across: `docs/API.md:3481` credited `navigation_lost` with the per-block
reading, and the argument it makes — no denominator to be wrong about — is true of
`headings_dropped`.
Gates on every round: `npm test` 1707 pass / 0 fail, `npm run typecheck` clean,
`./test/e2e.sh` ALL ENDPOINTS PASSED, anchor sweep 429 links / 0 bad, no `####` in API.md.
Move checks: 49 digit figures 0 absent, 22 number-word phrases with 4 rewordings and 0 losses,
79 of 79 identifiers, links 339 → 350 with no target linked fewer times than before.
Refs #464
Co-Authored-By: Blake Bertuccelli-Booth <bbertucc@users.noreply.github.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>