Design-doc audit: correct five stale status headers, and the two one-file fixes it surfaced

[JamesKane]

An audit of all 32 documents in documents/design/ against the tree. Five status headers
were wrong, three of them claiming less than the tree actually has, and the audit
surfaced two small code fixes that had been sitting in the backlog.

Four commits, split so the one behaviour change can be reviewed — or reverted —
independently of the documentation.

c0994d0 — project_report reads only the five artifact kinds it uses

The only behaviour change here.

AlignmentArtifacts::load called artifact::list_for_alignments, which selects the
payload of every artifact of every listed alignment. A tree-genotype row runs to
megabytes, so opening one project tab pulled gigabytes of JSON to read five small kinds.
list_for_alignments_of_kind already existed for exactly this and the caller was never
converted; BACKLOG.md has carried the item under "Cross-cutting" since 2026-07-26.

load now takes the (kind, algorithm version) pairs to read and runs one narrow query
for each. The five pairs live in PROJECT_REPORT_KINDS, next to the method that reads
them.

Worth a reviewer's attention: all six accessor call sites in project_report resolve
to those five pairs, and two of the six sit on a continuation line, so
grep 'artifacts\.' alone does not find them. A kind absent from the const reads as
None at all times, which is the failure mode to watch for if someone adds a column
later. The const documents that.

list_for_alignments now has no caller in the workspace. It stays — a caller that does
not know the kinds in advance still needs it — but its doc now says which form to reach
for and what this one costs.

db86061 — TrioPhaser does not exist

phasing.rs linked [`TrioPhaser`] twice, and no such type has ever been written.
The trait doc read as though trio phasing were available today: "a Mendelian trio phaser
when a parent is available (see [TrioPhaser])". Both passages now say plainly that
ReferencePhaser is the only implementation and that the beam search stands in for the
full PBWT.

Nine unresolved links remain in the crate and are untouched: resolve_chip (×4), 0,1
(×2), haplo::INDEL_DERIVED, crate::revert::collate, AnalysisError::io.

ec965c3 — five stale status headers

A header goes stale the moment a branch merges, because the merge updates code, not the
header.

Document	Said	Actually
ArchaicAncestry_Design.md	"Tier B GATED OFF"	ARCHAIC_SEGMENTS_ENABLED = true
realignment-module.md	"not yet merged"	bf576ab, v0.1.0-alpha.17
project-block-tree.md	"15 commits, not pushed"	4cb9eca (#45), v0.1.0-alpha.16
BACKLOG.md §1.1	Tier B gated off	both tiers ship
BACKLOG.md §1.7	"code signing deferred"	macOS done 2026-08-15; Windows open
BACKLOG.md §2.1	"Designed, not started"	shipped — and §2.2 is unblocked by it

The archaic doc needed more than a header. PR #42 (906b9ee) carried the Why it
failed diagnosis and a full Tier B rebuild — 909 lines of archaic_match.rs, ten
validation scripts — but touched no design document at all. The whole record has lived in
a module doc-comment since 2026-08-01. Section 11 is the pointer that was missing: what
changed, the held-out numbers (r = +0.710 against −0.018 for v1), and the cross-population
limit that is the reason the report is worded as a within-population measure. Every figure
is copied from the module doc-comment, which stays authoritative.

§2.1 is compressed rather than deleted. Each measurement it carried — the 1,157 MAPQ
deltas, the SEQ: * CRAM panic, the 4 h 44 m sort, the single-core open_seq — was
checked to survive in realignment-module.md before the text came out.

Three Scala-era documents get stale-warning headers in the style of the one already on
IBD_Matching_Implementation_Plan.md, rather than a rewrite or a delete:
Edge_Client_Implementation_Status.md (~55 %, last touched 2025-12-08, six months before
the Rust cutover), UI_Redesign_Proposal.md and UI_i18n_Guidelines.md (both December
2024). The i18n guidelines still hold as architecture; only their examples and paths are
dead.

9e0e633 — archaic_match.rs no longer ends on a verdict two commits overtook

Same drift, one layer down. The module doc-comment is chronological and also ended
chronologically, so its last word was "This is still not enough to turn the module
on" — written while the module was off. b39db0b turned it on and 9fca4c1 answered
the cohort objection; neither touched the prose. A reader who reached the end of the file
came away believing Tier B does not ship.

Two stale verdicts replaced with what happened:

• "the one reason that this module stays gated", on the population-ordering result. That
  ordering is real and unchanged — it is the reason the report is within-population and
  the reason the UI carries the caveat, not a reason the module is off.
• The closing three-reasons paragraph. Two of the three had answers already sitting
  elsewhere in the same file. Cohort was chr21+22 alone → the genome-wide run written up
  130 lines earlier (40–43 % sensitivity, ~46 % precision, both better than the
  two-chromosome figures). Precision 34.9 % without the filter → the shipped path
  applies the filter (haplogroup.rs:4061), which measures 90 %. The reference callset
  has weak support genuinely stands, and is marked as standing.

A new closing section carries the outcome and says plainly that the body above stops
before the decision — which is what made the file misleading rather than merely
incomplete.

No measured figure is edited or removed. Every table, number and caveat stands as
written; only the verdicts drawn from them changed.

Checks

• cargo fmt --all --check clean (pre-commit hook ran on each commit)
• cargo clippy --all-targets -- -D warnings clean
• cargo test --workspace — 35 result lines, 0 failures, 0 errors
• STE checker at 0 workspace-wide. Two drafts of my own prose regressed it (a 26-word
  sentence with a paired em-dash aside; later a 7-sentence paragraph and a passive clause)
  and were fixed. Note that passing file paths to ste-check.py silently ignored them —
  only the full run catches anything.
• cargo doc — the three new intra-doc links resolve, no new unresolved links.

One process note: an intermediate cargo test --workspace showed 2 failures in
navigator-app --lib. That was two overlapping runs of mine colliding on shared temp
paths, not a regression — both pass alone and the clean run is 177/177. It does expose
latent fragility though: a_present_file_resolves writes a fixed filename into
std::env::temp_dir(), so it will flake under any concurrent run. Not fixed here.

Not fixed, deliberately

• The nine pre-existing unresolved intra-doc links in navigator-analysis.
• list_for_alignments kept rather than deleted (see above).
• The temp-path test fragility.
• Four designs verified to have zero implementation and left alone:
  distributed-compute-grid (now unblocked by realignment), academic-ena-import,
  pangenome (both docs), local-LLM M6.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SequryftjcFkLnjQRMKCx3