Reconcile the documentation with the tree, and unbreak CI

[Ethan-Arrowood]

We pushed to the public repo at a decent point in the implementation, so I did a pass over every document in it to check what still matched reality. Four things, in order of how much they cost us.

CI has been red since the repo went public

The conformance job asserted Harper's pinned version by reading /usr/local/lib/node_modules/harper/package.json. That is npm's default prefix, not a guarantee — the runner resolves elsewhere, so every run failed at the version check with MODULE_NOT_FOUND, which reads as "Harper is missing" rather than "we looked in the wrong place". It now asks npm root -g.

No document knew this. docs/plan.md still listed the GitHub repo as a blocker and CI as "written, never executed".

The harness README claimed a guard the harness does not have

It listed Correctness guards under what it implements, on the grounds that the quote is deterministic. Determinism is necessary and is checked, but it is not a ground-truth check, and docs/plan.md has had this right all along: a consistently wrong answer is deterministic too. For a repo whose whole discipline is not claiming what it cannot support, this was the one that mattered. Moved to the not-implemented list with what closing it takes.

Three other bullets listed gaps that have since been built — the containerized path, trial restore, and the cold/warm/hot split all exist in the orchestrator. Replaced with the gap actually left: one target means "containerized identically for every target" is vacuous rather than satisfied.

Also dropped its ladder table, which described a dataset an order of magnitude smaller than the current one and a capacity an order of magnitude higher. It was a second copy of numbers whose first copy moved.

The plan was four days and five commits behind

AGENTS.md says to keep it current. It reported the conformance suite as mostly stubs after the stubs were gone, listed filling it as the next task, called FRESH_MS "deliberately TBD" after SPEC.md set it provisionally, and carried loyaltyBalance as unapplied after QUOTE-004 was rewritten around it.

One item was backwards rather than merely stale, and the corrected version is a real finding: the product endpoint omits the compute phase OBS-001 requires of both endpoints, and the coverage gate passes anyway because the quote's test also names OBS-001. That is the gate satisfied by the letter rather than the requirement, which is the failure mode the gate exists to prevent.

Related, and also now recorded: scripts/verify-run-record.mjs declares coverage of the run-shaped requirements and nothing executes it — not npm run check, not CI, not run-benchmark.sh. The gate scans its COVERS: line statically, so those requirements currently pass on a comment. The split is right; the wiring is missing.

Remaining drift

• README told every newcomer to regenerate the committed dataset in place as step one of the quickstart — two sections above the line explaining that implementations do not re-derive it, in a repo whose CONTRIBUTING calls regenerating it a heavy change.
• docs/data-model.md explained at length why promotions carry ['*'] sentinel key arrays, then listed a Promotion type without them, with @indexed still on the authoritative arrays that are deliberately not indexed. It also omitted @sealed throughout and omitted ProductView entirely — the cache is the one piece of the Harper design SPEC.md does not describe, so this document was the only place it was going to be described, and it wasn't. The block now matches schemas/store.graphql field for field.
• docs/structure.md called the repo root the Next.js app root, and asserted measurement scaffolding "does not live here at all" with bench/ and containers/ sitting beside it.
• docs/future-work.md said the Next.js wiring was retained but inert; structure.md said it was removed. Removed is right.

On counts

I took tallies out of the docs — requirements, tests, stubs, checks, row totals — and pointed each at a source that cannot drift: SPEC.md and the registry, npm run check, each dataset's MANIFEST.json. Every one of those numbers was wrong within days of being written, and the dev row count had drifted silently when the generator was fixed.

Measurements keep their numbers: the ladder latencies, the 2.5% → 77.7% cache-hit finding, the scrypt memory table. Those are dated experimental records, not status.

Two things I did not decide

• SPEC.md §8 has Self-review unticked but Cross-model ticked, which is backwards in sequence. The plan used to claim self-review had passed; the two disagreed in both directions. Gate status now lives only in SPEC.md §8, and I left the boxes exactly as they were rather than adjudicate.
• The CI fix is unverifiable until it runs, so the plan says "not yet confirmed green by a run" rather than claiming green. This PR is what tests that.

npm run check passes.

🤖 Generated with Claude Code