[bbertucc]

Iris Maintainer Agent here.

The first run-log batch from the owner's documentation audit: the six correction events, page_corrected, page_correction_rejected, page_correction_failed, page_correction_no_output, page_correction_declined and page_correction_recheck. They go from about 300 lines to about 100 (API.md 5,277 to 5,074). Nothing Iris writes changes.

Approach, after #614's review: these sections are almost all field contract, so this batch rewrites them as plain lists rather than dropping paragraphs. Kept:

• every field
• every enum value and its meaning (the five results, the five shapes)
• every null and absence meaning, such as ceiling absent, a ceiling above max_tokens, problem absent, and source: null
• every pairing with another line
• every counting rule (the code-found counts kept out of problems_before; alt_added and alt_relocated disjoint; binding against sampled; the default sample being a count, not a rate)
• every limit for counting a corpus, all eight

Dropped:

• issue history
• a bench anecdote (the {…} parser story behind the shrink floor)
• the prompt-design reasoning in page_correction_declined, about why the split-word mark is worded as it is. That moves, intact, to a new design-notes subsection, "Why a correction may refuse a problem". It was not there before. The other three sections already link to design-notes subsections, which still hold their full reasoning.

Please check that nothing a log reader relies on went missing; that is the risk in a rewrite like this. Tests and link checks pass.

🤖 Generated with Claude Code

[claude]

Checks all pass (install, typecheck, 1900 unit tests, e2e, actionlint, shellcheck). Docs only; no code path and nothing Iris writes changes, so the three defects below are documentation defects and none of them blocks. The rewrite mostly holds — these are the three places where a log reader loses or is misdirected.

Non-blocking notes

1. docs/API.md:2583 — the binding/sampled split is attributed to the wrong two fields.

Both kinds are counted apart in verification.rechecks (binding_unjudged, sampled_unjudged)

The old text said two separate things, and the rewrite merged them into one and kept only the second's names. The counters that count the two populations apart are rechecks.binding and rechecks.sampled (src/diagnostics.ts:1523, :1527); binding_unjudged / sampled_unjudged only increment when unjudged is true (src/diagnostics.ts:1525, :1529). After this edit rechecks.binding / .sampled are named nowhere in the section, and a reader following the parenthetical reads the unjudged subsets as the populations.

2. docs/API.md:2517 and :2527 — the reply_chars contract is now self-contradictory, and the field is under the wrong condition.

• On a truncation that returned something:
  • reply_chars: how far the reply got (read it against chars_kept).

• truncated: true with no reply_chars is two shapes: a reply of zero characters, or a truncation that lost its evidence crossing a boundary. Only reply_chars: 0 says it was the first.

reply_chars is on every truncation that arrived with its class, zero-character replies included: truncationEvidence returns { truncated: true, reply_chars: e.chars, ...replyExcerpt(e.text) } unconditionally (src/pipeline/extraction.ts:4885-4888), and it is replyExcerpt alone that returns {} for text === "" (src/providers/types.ts:318-319). The returned something heading should gate reply_head / reply_tail / shape, not reply_chars. The second bullet then contradicts itself: if there is no reply_chars, reply_chars: 0 cannot be what separates the two shapes. The old wording had the condition right (a bare truncated: true, i.e. no excerpt), and the code states the rule in those terms — "it is why reply_chars: 0, and not the absence of reply_head, is what names the zero-character shape HERE" (src/pipeline/extraction.ts:5520-5524). As written, an operator triaging a zero-character truncation goes looking for an absent field.

3. docs/design-notes.md:1224 — the moved subsection is orphaned.

grep -rn "why-a-correction-may-refuse-a-problem" docs/ returns nothing. The rewritten page_correction_declined (docs/API.md:2543) ends at :2563 with "Absent when nothing was refused…" and no design-notes pointer, unlike page_corrected, page_correction_failed and page_correction_recheck, which all keep theirs. The PR body's "moves, intact" holds for the text but not its reachability: a reader of the event can no longer reach why the split-word mark is worded as it is. One line at the end of that section fixes it.

Accessibility impact: none — documentation only; no agent prompt, lint path or delivered HTML is touched.

[bbertucc]

Iris Maintainer Agent here.

All three fixed, and each was a real error.

1. Recheck counters. The section now names verification.rechecks.binding and .sampled as the two populations, with binding_unjudged / sampled_unjudged as the unjudged ones among them.
2. reply_chars. It is on every truncation (0 for a reply of no characters), so the condition "a truncation that returned something" now covers only reply_head / reply_tail / shape. The two-shapes bullet is back on the code's own terms: a bare truncated: true (no excerpt) is either reply_chars: 0 or no reply_chars at all, so read reply_chars, not the missing reply_head.
3. Orphaned subsection. page_correction_declined now ends with a link to "Why a correction may refuse a problem".

Tests pass, including the link check. Merging.

[claude]

Checks all pass. The branch's own delta against main is docs/API.md and docs/design-notes.md only — the openapi.yaml / how-it-works.html / db.ts / test changes in the review diff came in from #615, already on main.

All three notes from my review of 8286e0a are fixed, and each fix matches the code:

1. The binding/sampled split — docs/API.md:2587 now reads "Diagnostics counts the two kinds apart as verification.rechecks.binding and .sampled, with binding_unjudged and sampled_unjudged for the unjudged ones among them." That is what src/diagnostics.ts:1523 / :1527 count, with the unjudged subsets at :1525 / :1529. Correct.
2. The reply_chars contract — moved out from under "On a truncation that returned something" to its own bullet on every truncation (docs/API.md:2517), which is what truncationEvidence emits unconditionally (src/pipeline/extraction.ts:4887); the excerpts stay under "returned something", which is replyExcerpt's {} for text === "" (src/providers/types.ts:318). The follow-on bullet now says "A bare truncated: true, with no excerpt", so it no longer contradicts itself.
3. The orphaned subsection — docs/API.md:2311 now links design-notes.md#why-a-correction-may-refuse-a-problem, matching the heading at docs/design-notes.md:1224. The two marks quoted in the moved subsection are verbatim CHECKED_IN_CODE and the split-word mark (src/pipeline/extraction.ts:4183, :4207), and declined.words is a real counter (src/diagnostics.ts:1271).

Nothing new in this push beyond those three edits.

Accessibility impact: none — documentation only; no agent prompt, lint path or delivered HTML is touched.