docs-of-record-and-arbitrationlisted

# Docs of record and arbitration Mature projects accumulate overlapping documentation: several versions of the same spec, a "why we built it this way" doc that's now describing a stack nobody uses anymore, a README that was accurate on the day it was written and hasn't been touched since. The failure mode is building from whichever doc you happened to open first. The fix is an explicit arbitration order, applied consistently. ## Classify every doc as authoritative or historical, explicitly Keep one short table: which documents currently govern which decisions, and which are retained only as history and should never be built from. A doc that's superseded should say so in its own header if possible ("superseded by vN, kept for history"), but don't rely on that alone. Maintain the classification independent of whether the old doc admits it's stale. ## Arbitration order when documents disagree A reasonable default order; adapt it to your own project's actual sources of truth: 1. **A settled-decisions ledger**, if you keep one (a running log of "we decided X, here's why, here's where it's implemented"). This beats every other document, because it records an actual decision made with full context, not a snapshot of intent. 2. **The contract/invariants document** (see architecture-contracts-as-law), for anything about schema, API shape, or system invariants. 3. **The current product/behavior spec**, for what the system is supposed to do, as of now. 4. **Everything else**: olde