docs: three log entries a reader can act on, and the reasoning behind them has one home (#474)
#464's fifth slice, and the last of the entry moves. `page_markers` 92 lines → 37,
`agent_call` 86 → 27, `assembly_words_joined` 78 → 32. API.md 5,502 → 5,342; design-notes
2,746 → 2,946.
All three destinations needed writing. `## Assembly` had the hyphen join and the page label as
one-line bullets with none of their conditions, and `## Learning from feedback` had nothing at
all about what a training round's log can be read back to. So design-notes gains four
subsections, and three pre-existing bullets gain a heading of their own so every
cross-reference lands on a place rather than on a section:
- `### Closing a word the printing broke at a line end`
- `### A page label naming the image's position rather than the page's number`
- `### Telling a training round's two replays apart`
- `### What recovers the text a prompt actually sent`
API.md keeps what is on the line and what each field reads, the blind spots to know before
counting a corpus off one, and which lines never leave the deployment. `agent_call` and
`page_markers` are field tables now. Two index hooks widened, because a section's hook is a
claim about its contents and both sections grew past theirs.
Two of the five move checks were wrong, and repairing them found the loss. The figure check
could not read a phrase that wrapped across a line — prose here is written to 100 columns, so
`two\n reasons` in the source read as a loss against `two reasons` in the destination, and
`40 characters` read as a loss in either direction. Collapsing whitespace runs on both sides
cleared two false positives and left one real loss standing: the two classes of comment that
reach the assembly pass, `@page-failed`'s 300 characters of provider error text, and the fact
that a delivered document's `@` markers are appended by `wrapDocument` after the pass has run.
The link check keyed on the raw link string, so a bare `#anchor` in API.md and the
`API.md#anchor` needed to write the same reference from design-notes counted as different
targets — which reports a false drop on every citation a move carries. It resolves to
`<file>#<anchor>` first now, and the fix was graded both ways against the slice that first
found the check's gap: it still catches the real
`docs/API.md#diagnostics-timing--hang-detection 12 → 11` drop there, and the second drop the
raw version reported at that commit turns out to be a citation that MOVED rather than one that
went — a false positive that had been recorded as real.
Three restatements were trimmed to pointers before the first commit, all mine: design-notes
re-listed API.md's three hyphen conditions and the page label's AND-chain, and API.md
pre-announced design-notes' conclusion.
Round 1 (`80e70ab` → `791b535`) — a pointer promising more than the destination held, which is
the failure a move check cannot see, since the missing paragraph was already gone from the
source before the check ran on it. API.md said the three hyphen conditions read the document at
"three different widths" and design-notes explained two. The third is the third condition's
own: `script` and `style` content in, attribute values out, which is `page_split_words`' width
exactly — and that identity is the condition's whole claim, since it is what makes the
condition decline precisely the words that step raises. Restored with the `alt` consequence and
the direction the widening would fail in.
Sweeping that class found one more, mine rather than a loss: my blind-spots bullet said "each
is counted rather than argued away", which is false of the third. A positional number announced
through `aria-labelledby` is never read, so nothing counts it. Two are counted — the refused
document in `systems`, the numbering restart in `departures` — and the bullet says so now, and
names the third as counted nowhere.
Also round 1: `departures` and `word_splits`, both named by the pre-edit text at the claim that
needs them and described without naming in mine; `three cases (MAX_GATE_FIXTURES)`, restoring
the 3 for a reader who arrives from API.md's cross-reference into a subsection that no longer
states it, which clears the slice's only rewording; an index hook naming the page-break join,
which is this pass's INPUT, rather than the line-end hyphen it repairs; one bullet carrying
four sentences' worth of reasoning in one, split into four; and a link on the first mention of
`eval_gate`, `agent_update_blocked` and `feedback_training_failed` in the new subsections,
since a reader is being told to tell those three lines apart in a log.
Round 2 found nothing new, which is the merge condition.
Gates on both rounds: `npm test` 1707 pass / 0 fail, `npm run typecheck` clean, `./test/e2e.sh`
ALL ENDPOINTS PASSED, anchor sweep 440 links / 0 bad, no `####` in API.md. Move checks: 44
digit figures and 24 number-word phrases with 0 absent and 0 reworded, 54 of 54 identifiers,
links 350 → 361 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>