alkblobs/tasks/docs-consistency-review.md

id, name, status, depends_on, scope, risk, impact, level

id	name	status	depends_on	scope	risk	impact	level
docs-consistency-review	Whole-docs drift pass and the N-8..N-14 disposition	completed	unicode-hygiene	moderate	low	phase	implementation

Description

The operator-requested docs consistency round: a whole-tree read of docs/ (architecture specs, ADRs, plans, reviews, research headers) plus AGENTS.md, catching drift and inconsistencies — with the known-stale spots found at decomposition (2026-10-16) as the first read:

• docs/architecture/README.md Current State — says "wave 8 (the structural split — decomposed), wave 9 (correctness), wave 10 (security; fuzzing/release follow as waves 11/12)". Reality: waves 8-11 completed at their gates (2026-10-15/16); wave 12 decomposed. last_updated: 2026-10-15 predates the wave-11 close.
• AGENTS.md status line — "Phase 1 (Architecture) … specs draft, ADRs 001-006 accepted". Reality: ADRs 001-017 accepted, implementation complete through wave 11, release readiness in flight.
• review-001's N-8..N-14 — wave 11's target inventory named them "hygiene/doc items remaining recorded for wave-12 candidacy". Disposition each: absorbed by waves 8-10 (name where), fixed now if doc-trivial, or recorded post-release with a named home. Note the review's file:line references predate the wave-8 split (its frontmatter says so) — resolve against the current tree, not the stale paths.

Then the general sweep the round exists for:

• Spec frontmatter (status/last_updated) accurate against each doc's last substantive edit.
• Cross-references resolve: post-split module paths (the split moved store.rs/ops.rs/postgres.rs/pg_lo.rs into directories — any doc naming the flat files as current code is stale), ADR↔spec↔plan links, task-file links in the plan's decomposition records.
• docs/plans/implementation.md internal consistency (wave table vs section records vs decided points).
• docs/architecture/open-questions.md — statuses match the ADR record; the parked index claim still true.
• Doc-vs-code claims spot-checked where cheap (the N-10 class: a doc sentence contradicted by the implemented behavior). Code-doc mismatches get fixed or explicitly filed — never silently skipped.

No behavior changes. Code edits, if any fall out, are doc-comment-only or trivially mechanical; anything larger becomes a named follow-up instead of scope creep.

Acceptance Criteria

• docs/architecture/README.md Current State + last_updated reflect waves 1-11 completed and wave 12 in flight
• AGENTS.md status line accurate (ADRs through 017; implementation-complete posture)
• N-8..N-14 each dispositioned (fixed / absorbed-with-pointer / recorded-with-home) — the disposition visible in review-001 or the open-questions tracker
• Every docs/architecture/ spec's frontmatter matches its content; no stale wave/status references anywhere in docs/
• No doc reference names a pre-split flat file as current code (store.rs/ops.rs/postgres.rs/pg_lo.rs as living paths)
• Cross-reference sweep clean (links resolve; plan decomposition records' task links exist)
• cargo doc --no-deps still clean (doc-comment edits compile)

References

• docs/reviews/001-storage-surface-general-review.md (N-8..N-14 at lines 784-790; the closure record at 833-837)
• docs/architecture/README.md (Current State, Lifecycle)
• docs/plans/implementation.md (wave table, decided points)
• AGENTS.md (status line, conventions)

Notes

The disposition was made against the post-split tree; every N-8..N-14 item's current code state was checked directly (file:line in the disposition record). Doc-trivial closes landed in this round: N-9's list-duplicate semantics documented (src/store/read.rs), N-13's audit wording scoped to its two halves (src/ops/tests.rs), N-14's stale #[allow(too_many_arguments)] removed (src/store/sweep.rs) and the walk's by-name exclusion documented (src/local.rs). The recorded items (N-11, N-12, the N-14 remainders) have tasks/n-cleanup-residue.md as their named home. Stale docs fixed: the architecture README's Current State + frontmatter, AGENTS.md's status line, ADR-014's src/ops.rs living-path reference. The open-questions tracker verified current without edits (statuses match the ADR record; the parked-index claim holds); the remaining pre-split flat-file mentions are the review's stamped historical references and the plan's split history — not living-path claims.

Summary

Completed 2026-10-16. docs/architecture/README.md's Current State now reads waves 1-11 completed at their gates with wave 12 (release readiness) decomposed and in flight, frontmatter current; AGENTS.md's status line matches (Phase 1 release readiness, ADRs 001-017, implementation complete through wave 11); review-001 carries a wave-12 disposition section (N-8..N-14 each fixed / absorbed-with-pointer / recorded-with-home, with the recorded remainder gathered into tasks/n-cleanup-residue.md as the named follow-up). No behavior changes; the four code edits are doc-comment-only plus one stale allow removed. Verification: cargo fmt --check, clippy (default + all-features, -D warnings), cargo doc --no-deps, cargo test (default + --all-features against the live pg harness), and the fuzz corpus-replay gate — all green.