# IO-PARSER-22 DOCS LANE — JIT plan (todlando, 2026-08-27)

Branch `build/io-parser-docs` @ base `9c3a129a` (W5) in `.worktrees/io-parser-w1`; pool claimed
`io-parser-docs`. Binding record: `IO-PARSER-22-JIT.md`. Doyle's scope: SWEEP for gaps and
coherence — do NOT rewrite what W1-W5 shipped.

## Measured state at base (2026-08-27)

W1-W5 touched **exactly two** docs files: `docs-site/src/shells/frames.md` (the whole IO / shortform
/ `;;` / now-signal contract, doc-tagged) and `docs-site/src/cli/reference.md` (**GENERATED** — do
not hand-edit; regenerated by `xtask gen`, drift-gated by `xtask check`). Token census over
`docs-site/src`: `now-signal`, `shortform`, `DISPATCH_RESULTS`, `COMMUNE_FAIL`, `[io]`, `SPT-NOW`
appear in those two files and nowhere else.

`crates/spt-runtime/manifest.schema.json` already carries `io` (W3/W5 regen). All milestone REQ
`doc` stages are already satisfied by frames.md tags. `REQ-IO-SEND-VERDICT` has no `doc` stage.

## The gaps (all are ABSENCE, not drift)

1. `docs-site/src/harness-contract/manifest.md` — no `[io]`, no `[io.now_signal]`. The manifest
   reference is what a harness author reads to declare compliance; the surface is undiscoverable
   from it today.
2. `docs-site/src/harness-contract/api.md` — `api state` documented without the payload flags; no
   `api now-signal`, no `api hint`.
3. `docs-site/src/harness-contract/integration-checklist.md` — no IO item in any group, none in the
   "Am I done?" floor.
4. `docs/MANIFEST.md` (repo-side authoritative schema doc) — no `[io]` section.
5. `docs-site/llms.txt` — `shells/frames.md` is listed NOWHERE (pre-existing; now load-bearing,
   since the whole IO contract lives there).
6. `docs-site/src/messaging/overview.md` — shortform `@<…@>` is a new author-side send path; the
   canonical messaging page never names it.
7. `docs-site/src/messaging/wax-seal.md` — `;;` is a new path into the ceremony; not named.
8. `docs-site/src/shells/overview.md` — "alongside the four channels, spt-core pushes one thing"
   (activity) is now falsified by the `io` frame class.
9. `docs-site/src/harness-contract/overview.md` — "Where to go" has no IO pointer.

Rule for every fix: frames.md stays the ONE canonical home. Everything else POINTS at it and
carries only its own surface's specifics (manifest fields, verb flags, checklist rows).

## Non-drift confirmed (do not "fix")

- `reference/json-shapes.md` send-outcome vocabulary + `messaging/overview.md#send-outcomes`: W5
  changed the INTERNAL `SendVerdict`; operator-facing outcome lines and exit codes are unchanged to
  the byte. Nothing to correct.

## Acceptance

- `cargo run -p xtask -- check` (docs drift + llms links).
- `traceable-reqs check` = 0.
- Blind consumer read.
- **IR-52 rider:** this lane does NOT touch the CLI reference generator (no CLI surface change, no
  `xtask` edit) — say so explicitly to doyle so IR-52 stays open in the register.

## Commit trailer

`Co-authored by: todlando` (space spelling).

## OUTCOME (2026-08-27) — DELIVERED, awaiting doyle's gate

Commit `b7135d66` on `build/io-parser-docs`, **PR #167** (base `main`, stacked on W5). 13 files,
+237/-18. All nine gaps above filled; nothing W1-W5 shipped was rewritten.

**Extra, beyond the plan:** `Io::shortform`'s Rust doc comment (and therefore the published
`manifest.schema.json` description generated from it) claimed the field opts out of `@<…@>` parsing
only — the one bool gates the `;;` seal mint too (`api/delivery.rs:332/353`). Comment corrected,
schema reblessed. Flagged to doyle rather than asked; revert is one commit.

**Gates at `b7135d66`** (each read from its own `.exit` / captured line): `xtask check` OK exit 0 ·
`traceable-reqs check` exit 0 · schema drift test 1 passed exit 0 · clippy `--workspace
--all-targets` exit 0 / 0 warnings Windows · same on kitsubito, `CLIPPY_EXIT=0` with
`SHA=b7135d66…` echoed in the same command.

**IR-52: reported OPEN.** The CLI reference generator was not touched; `reference.md` is
byte-identical.

**Pool `io-parser-docs` still claimed** — hold it until the gate closes, in case of a respin.