Archaic design doc: record the shipped state and where it diverged from the plan

[JamesKane]

Post-ship audit of documents/design/ArchaicAncestry_Design.md. Documentation only — no code changes.

Staleness

The doc's header read "No code yet" for a feature that shipped in v0.1.0-alpha.14. Also fixed: M3 was headed "in progress" after M3.3 wired it end to end, §9's questions were under "Still open before Phase 1" with all three long closed, and §8's phases carried no status.

The part that actually mattered

Three things shipped differently from §10, and none was recorded at the point where the plan states the rule — so a reader following this document would have been misled about what the code does.

Plan says	Reality
Ship Tier B behind a feature gate covering read and publish paths	No such constant. Extent shipped ungated; only attribute_lineage is off
Validate at ~1.5–2% Neanderthal (§7)	Calibrated against hmmix's measured EUR mean (90.9 Mb) instead — shipped result 91.5 Mb = 1.01×
Denisovan floor "must be exercised by a test"	Test was never written

Each is annotated in place with a blockquote, so the rule and its reality sit together, plus a new Deviations from the plan section carrying the justification and the residual risk.

The honest read on each:

• The gate is defensible — the fabrication risk it existed to contain was entirely in attribution, which is gated, and extent passed the bar via an external callset. But the plan still read as though the gate were there.
• §7's figure isn't wrong, it's a different measurement. Three denominators are in play (whole genome / callable genome / hmmix's per-haplotype union) and they aren't interchangeable. §7 now says so in place, because quoting "1.5–2%" beside the shipped "5.04%" reads as a contradiction otherwise.
• The missing test is a genuine open gap, not a deviation that resolved itself. Shipped behaviour is stronger than the spec — Denisovan is never surfaced at all — but nothing currently fails if a future change starts emitting denisovan_copies as a headline.

Residual risk now stated rather than implied: extent is fitted on one individual, so its error is uncharacterised for anyone with unusual ancestry or coverage.

Open follow-ups (new section)

• Write the Denisovan-floor regression test
• Validate extent across several individuals — the 1.01× agreement is a calibration check, not a validation
• Lineage attribution needs the Skov-2020 haplotype approach; threshold tuning will not fix it
• Asset staging policy was never decided — a live defect, not a doc bug (below)

The staging defect, recorded here and fixed separately

M1 said to check Asset 1's size against ON_DEMAND_PREFIXES in packaging/stage-assets.sh "before deciding". No decision was ever made, so PATTERNS lists no archaic_* while release mode fetches everything the manifest names except ancestry_haps_ — bundling all five archaic assets (105.3 MB). The two staging modes disagree, which is precisely what the comment above PATTERNS warns against.

Measured: alpha.14's installers are ~60 MB larger than alpha.13's (.dmg 136→199 MB, .exe 105→163 MB). Fixed in a follow-up PR.

🤖 Generated with Claude Code