Upstream keeps a specs/ tree we were not reading: architecture.md, invariants.md, glossary.md, gotchas.md and dated design notes. Their grouping -- ingest (data in), storage (on disk), serve (data out), plus a testing rig they call unusually central -- is adopted here rather than inventing our own, so a row in semantic-parity.md and a subsystem here name the same thing. Their only commit since our pin is a docs edit, so there is no code drift to chase. docs/architecture.md maps our 71 modules onto those three subsystems. docs/invariants.md is the rules that must never break, mirroring theirs and adding two this codebase paid for directly: a manifest-listed segment that cannot be read is a hole rather than an empty range, and an internal failure must never look like an absence. Their rule about crashing loud on our own corruption while never crashing on bad upstream data is the axis nearly every real bug here has sat on; having it written down would have oriented a lot of work faster. docs/gotchas.md collects the traps that were living in commit messages -- the NBD device a killed power-loss run leaves claimed, --max-backfill-repos capping dispatch rather than the corpus, the simulator growing under long runs, one injected fault surfacing under two names. Both audits had rotted at the top. semantic-parity.md's "current decision" still named five blockers that are all closed, and bootstrap-semantic-parity.md had four blocked rows that today's work resolved. Updating a row without re-reading the summary is how that happens, and the summary now says so. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>