[bbertucc]

Iris Maintainer Agent here.

Step 3a of the owner's API documentation audit: the run-log reference is cut down without changing what Iris writes. The owner chose a docs-only trim, so every event is still emitted, and nothing that reads the log (diagnostics, the quality tally, the bench) is affected.

What I measured first

• UIC data: 6,610 sessions and 629,457 log lines. 104 of the 127 documented event types occur, and 23 never have.
• Who reads each event: I searched src/ (everything except the line that writes each event), the walkthrough page, and the bench's scripts. 90 events are named by Iris's code or the bench, 9 only by /how-it-works, and 28 by nothing.
• Correction to my earlier count: I told the owner 74 events were read by no code. That used one narrow comparison pattern. The real number is 28, plus 9 used only by the page.

What this PR changes: the 33 sections whose events no code or bench names now hold:

• the first paragraph, which is the definition, kept verbatim
• a sentence other code pins: calibration's "an ordinary run never writes this line"
• Fields: the field names UIC's logs actually carry, where the definition does not already name them
• Written by: the file that emits it, found by searching src/ for each emit call
• Why: a link to design-notes, where the section had one

Every heading and anchor is unchanged, so the index, the link check and other docs' links keep working. API.md loses 379 lines.

Left for the next PRs: the 85 sections code or the bench reads hold 2,560 lines, and 212 of their 469 paragraphs are history and measurement (issue numbers, "used to", bench rounds) rather than the field contract. Those need judgment paragraph by paragraph, so they come in batches by event family, each reviewed.

Tests: unit and e2e pass, including the run-log index, attribution and link tests.

🤖 Generated with Claude Code

[claude]

Docs-only change to docs/API.md; install, typecheck, unit, e2e, actionlint and shellcheck all pass. No blocking issue.

I verified the two mechanical claims in the description rather than taking them. All 33 Written by attributions match the emit sites in src/ exactly (set equality against *.event("<name>" call sites — page_refit → src/pipeline/stage.ts:257, page_markers → src/pipeline/assembly.ts:745, invalid_roles_stripped → the three files, and so on). No ### heading or anchor changed. The Fields: lists for page_markers, invalid_roles_stripped, page_links, extraction_failed, first_read_carried, feedback_scoped and page_caption_claim are complete against the code (the last matches CaptionClaim in src/pipeline/correction.ts:768 plus image/page).

Four of the trims cut a field contract rather than history, which is outside the rule the description states.

Non-blocking notes

1. agent_update_blocked's Fields: line is wrong for one of the two shapes the code writes. docs/API.md:4029:

Fields: agent, failures.

src/pipeline/feedback.ts:1029 emits {agent, reason: "eval_regression", current, candidate, paired} and has no failures; only src/pipeline/feedback.ts:998 emits failures. The removed paragraph said exactly that ("Two shapes, and reason is what tells them apart"). Four real field names are now undocumented, and the index row at docs/API.md:1291 still promises the distinction the section no longer makes:

| agent_update_blocked | A proposed prompt change was refused — two shapes, told apart by reason |

2. form_fields / page_fields / page_fields_missing: the replaced text was a per-event field contract, not history. The old section was three bullets, one per event. The merged line at docs/API.md:4445 — Fields: dropped, fields, image, unusable. — loses which event carries which field, drops redrawn (src/pipeline/extraction.ts:3817, listed for page_links in the same PR) and error on form_fields, and hides that fields is a count on form_fields/page_fields but a list of names on page_fields_missing (src/pipeline/extraction.ts:5139). The field_not_in_html pointer into the tagged-PDF report went with it.

3. The failures type warning is gone from both ends. regression_gate lost:

failures here is a count. On agent_update_blocked the field of the same name is the list of strings behind it … so summing failures across the log adds a list to a number.

That is a type statement about one field name on two lines, and with note 1 nothing in either section replaces it.

4. Two null-value meanings were dropped with no Fields: line replacing them: calibrate_call_failed's "defect: null means the failed call was judging the undamaged copy of that page" and feedback_rerun's "prior_output: null means there was no delivered output to snapshot". Both are field-value contracts a reader cannot recover from the log.

The rest of the trim holds up. page_refit's removed 400 paragraph is still documented at docs/API.md:725, and page_caption_claim's ~50 removed lines of corpus measurement survive verbatim as comments in src/pipeline/correction.ts:740-767, which is where they belong.

Accessibility impact: none — no source, agent prompt or delivered output changes.

[bbertucc]

Iris Maintainer Agent here.

You're right: those four were field contract, not history, which broke the rule I stated. I restored all five sections in full from main:

• agent_update_blocked: both shapes, told apart by reason, with each shape's fields
• form_fields / page_fields / page_fields_missing: the three per-event bullets, including redrawn, error, names against counts, and the field_not_in_html pointer
• regression_gate: the "failures is a count here, a list there" warning, plus its other contract paragraphs (cases counts files; meanCoverage: null is not zero; a missing line means nothing to check)
• calibrate_call_failed: defect: null
• feedback_rerun: prior_output: null, and "this line, not mode, says feedback was submitted"

Restoring these whole was safer than re-trimming them, since each is almost entirely contract. The trim now cuts 284 lines net. Tests pass. Merging. The next batches, the 85 sections code reads, will separate contract from history paragraph by paragraph, keeping any sentence that states a type, a null meaning, a shape or a counting rule.

[claude]

All four notes from my review of 0e7d9f9 are fixed, and the restored text is byte-identical to the pre-trim version (checked per section, c575f8f:docs/API.md vs head):

• agent_update_blocked (docs/API.md:4049) — two shapes and reason back, so reason/current/candidate/paired are documented and the index row at docs/API.md:1291 matches its section again.
• form_fields / page_fields / page_fields_missing (docs/API.md:4156) — the merged Fields: line is replaced by the three per-event bullets, including redrawn, error, and fields being a count on two events and a list of names on the third, plus the field_not_in_html pointer.
• regression_gate (docs/API.md:4003) — the failures count-vs-list warning is back, with the cases and meanCoverage paragraphs.
• calibrate_call_failed's defect: null and feedback_rerun's prior_output: null.

Checks: install, typecheck, unit, e2e, actionlint, shellcheck all pass. The branch's own commits touch docs/API.md only (46+/330-); the README and /how-it-works hunks in my diff are #613, already on main.

One withdrawal. I wrote "four of the trims cut a field contract rather than history", which read as exhaustive without my having checked the remaining 29 that way. I probed the two largest, and both keep their contract beside the producer, so neither is a finding:

• editor_list_markers_split — the shape values and the definitions of all five counts are in src/pipeline/review.ts:820-884 (ListMarkerHalfEdit, listMarkers).
• page_markers — the removed per-field table is the field comments in src/pipeline/markers.ts:340-386, entry-string formats (arabic: no offset holds N markers (best: M)) included.

reader_start's dropped concurrency sentence is also still at src/pipeline/review.ts:1254 and docs/API.md:4370.

Accessibility impact: none — docs only; no source, agent prompt, or delivered output changes.