Decisions as case-law

Every design system eventually contradicts itself: a ruling made in May quietly survives in one document while a June ruling overturns it in another, and both look equally authoritative. Supernova’s answer is to treat decisions like case-law rather than like a folder of ADRs — one living ledger where every ruling carries the human’s verbatim words, every reversal formally cites what it overrules, and nothing is ever silently deleted. The ledger is the backward half of the traceability chain that requirement percolation carries forward: code → annotation → spec → Origin → decision → Matt’s actual sentence.

The ledger [live in automatt]

The decision ledger is a single living document in the project wiki — roughly 2,900 lines and ~150 dated entries by heading count (the ledger’s own index, written in June, still says ~110) — organized as dated ruling batches from the 2026-06-04 baseline forward. Conflict resolution between batches is explicit: read newer-over-older, with a marked CURRENT-TRUTH section that supersedes conflicting entries in earlier batches. An entry carries a title, Matt’s verbatim quote where one exists, the decision and its rationale, a pointer to the spec R# where the ruling is applied, and a Supersedes: line when it overturns a prior call. Quotes are cited like court records, down to transcript ID and minute (f70f827b @ 04:03); one contested fold ruling — delete-folded-dirs-no-tombstone, reversed ten minutes later — was adjudicated from the gap between two utterances.

The recording convention is strict (Matt, 2026-06-22: “I would prefer if you could backport the decisions to the decisions log and make clear in the project that’s how it goes”): every decision is recorded in the ledger in the same session it is made. Folding a ruling into a spec annotation is necessary but not sufficient — the spec is where a decision is applied; the ledger is where it is recorded. A ruling that lives only in an R# annotation, a synthesis doc, or a commit message is not yet recorded. Backfill is a sanctioned move: rulings discovered folded-but-never-recorded get backported as a grouped batch.

Supersession: strike through, never delete

The supersession convention (2026-06-10) was born from a concrete failure, not from tidiness. A 2026-05-16 ruling about task storage survived in an issue-system requirement despite a 2026-06-04 database ruling that superseded it — and adversarial review missed it, because both claims carried valid Matt provenance from different dates. Temporal drift, not doc-vs-doc inconsistency. Two true quotes, no way to adjudicate without formal supersession. Hence two rules:

1. Every entry that changes a prior call carries an explicit Supersedes: line naming what it replaces, with ID and date.
2. Superseded claims get a struck-through SUPERSEDED marker citing the superseding ruling — history preserved, authority removed.

The ledger’s own justification: “Provenance is exactly what makes stale claims look authoritative; mechanical validation only catches what is declared.”

stateDiagram-v2
    [*] --> OPEN : escalated, not yet canon
    [*] --> Canon : Matt rules, recorded same session
    OPEN --> Canon : Matt ratifies
    Canon --> SUPERSEDED : newer entry cites ID and date
    Canon --> CONTESTED : conflicting utterances, docketed
    CONTESTED --> Canon : re-ratified by Matt
    SUPERSEDED --> [*] : kept in place, struck through

Authority grades

Not every ruling is equally grounded, and the ledger says so out loud. A 2026-06-22 provenance dig — a full pass of the ledger against raw session transcripts — produced a strength taxonomy that now appears inline on entries:

There is deliberately no limbo: “a ruling is either canon … or it is OPEN (escalated to Matt, not yet canon).” A verbatim quote is mandatory — not merely preferred — when a ruling supersedes a prior Matt ruling, adds or kills a system, touches the permission/approval/security/traceability apparatus, or narrows a founding property. For mechanical applications of existing rulings, “the precedent IS the provenance.” Even embarrassments are labeled rather than disguised: a load-bearing outbox rule sat in the ledger for weeks marked “Provenance: NONE — no Matt quote backs this as stated” until a later ruling ratified its substance.

The formalized version of this — standard S21, “provenance as case-law” — grades every record authoritative (chain terminates at a Matt-verbatim anchor), derived (cites a graded-authoritative parent via synthesis), or ungrounded-or-drifted (no anchor, or contradicted by newer authority), with a corpus-level provenance-coverage metric. Today those grades are assigned by humans and agents reading transcripts [live in automatt]; the mechanical grading engine, chain resolver, and coverage audit are [supernova design].

Eight rulings, spanning the range

Honorable mention: choosing Next.js over Rust for the cockpit UI (D70) on the grounds that “building a website in rust just seems weird and I suspect random agents will be really bad at it” — training-distribution density treated as an engineering constraint.

Why case-law beats ADRs-in-a-folder

An ADR folder records decisions; it does not notice when the corpus contradicts them. The ledger’s machinery is aimed at exactly that gap. The temporal-drift incident above is one instance; the standards doc cites another, where a system index page marked a ratified ruling DONE while still narrating the superseded model on the same page — “a spec author reading the superseded model implements decided-against architecture.” Formal supersession plus a per-round sweep of foundational quotes is what catches two individually-true claims that disagree.

The ledger also indicts itself, which is the property that makes it trustworthy. A 2026-07-01 entry records that ~773 of 1,328 done requirements were found inflated, naming the exact mass-promotion commits that did it. D82 (2026-07-03) records, about the project’s own E2E harness, “~12%, disjoint stubs … a fake/always-green harness lets everything FAKE-CLOSE.” Case-law even outranks fresh literal words when the words conflict with standing precedent: one entry overrides Matt’s own “kill -9 a session thread” instruction by invoking the standing anti-watchdog rule — and flags the override for confirmation rather than hiding it.

Enforcement is layered. Canon, the decision-ledger judge, is a persistent agent definition [live in automatt]: on ambiguity it searches the ledger and verbatim archives for controlling precedent, rules and records when the case is mechanically analogous, and escalates to Matt when it is load-bearing or precedent-free. “Canon never invents Matt provenance; a NONE entry stays NONE until Matt speaks.” A first mechanical slice — a decision_ledger_conflict check that parses the ledger’s headings and blocks when two entries take opposite build/no-build positions on the same topic without a declared supersession — is real, tested code that runs today inside the wiki validator as a development gate [built in-repo]. Canon’s precedent search, escalation workflow, and autonomous adjudication remain [supernova design].

What this costs

• It is a 2,900-line hand-maintained monolith. Conflict resolution is “read newer-over-older” — a human protocol, not a data structure — and resolving a D# means grepping the ledger and two archive logs. There is no mechanical D# registry.
• Mechanical enforcement is thin against the standard’s ambition. The live check catches only opposite-polarity headings on a normalized topic; conflicts phrased differently slip through. Authority grading, coverage metrics, and supersession-propagation scans are design-stage. Today’s real guarantee is editorial discipline plus one validator slice.
• Quote-mining is expensive and fragile. The provenance dig required full transcript excavation from session logs stored outside the repo, with genuine retention risk for future re-audits.
• The human is the bottleneck, by design. Mandatory-provenance items queue on Matt; a ten-item docket of NONE/PARTIAL rulings sat OPEN or CONTESTED for weeks. Case-law that cannot be ratified stalls.
• PARTIAL is a fuzzy grade. “Matt set the property; the architecture is agent-crystallized” covers everything from a schema detail to an entire taxonomy, with very different amounts of agent invention behind the same label.
• The ledger records; it does not prevent. The 773-requirement inflation happened under this regime and was caught by a deliberate deep-dive, not by the standing apparatus. The fixes it prescribed are themselves partly aspirational.
• Churn is preserved, faithfully. Same-day supersession means the ledger keeps its thrash on display; readers must trust the banners to navigate it. That is the price of never deleting anything.