Architecture Decision Records — index

An ADR records a decision, the alternatives it beat, and what it cost — and then stops changing. This directory answers "why is it this way?", a question the design docs cannot answer because they describe the current contract, which is allowed to move.

The boundary rule

This is what keeps the corpus from becoming a fourth copy of the documentation. Each kind of fact has exactly one home:

What a map lists. A design document ends with ## Decisions governing this document — its map. It lists the ADRs whose decision that document's current contract depends on (states it, or requires it); naming another document's decision is a cross-reference, which belongs in the prose and not in the map, so a document may legitimately mention an ADR its map omits (ADR-0028).

Three kinds of page carry no map, and that is not an omission — each is a place a fact about a decision lives, not a document whose contract depends on one:

• a record page: the plan and its per-ticket history (docs/ARCHITECTURE-EXECUTION-PLAN.md), the optimization records (docs/CUDA_OPTIMIZATION.md, docs/METAL_OPTIMIZATIONS.md), and a plan's own root-cause notes (docs/QWEN3-SUPPORT-PLAN.md);
• a ledger page: docs/TEST-BASELINES.md, whose numbers are machine-checked against scripts/test-baselines.toml;
• an upstream comparison: docs/LLAMA-COMPUTE-GRAPH.md, which is not this repository's contract.

And a map may omit an ADR that names the page, in two cases — both are references about a document rather than a dependency of it:

• a correction reference: ADR-0022 names the documents whose citations it fixes (ADR-0029 records the class);
• a contrast reference: ADR-0037 names docs/CUDA-BACKEND-DESIGN.md §4.3 as a different mechanism, not as a dependency.

Three rules keep it that way. All three are about kind, not about banning a form:

• A capability is a dated consequence, never a present-tense claim. "At the Date: above, #310 enabled X" is allowed; "X is now true" is not — that is the sentence that rots. The authority for what is true today is the design doc and docs/SUPPORT-MATRIX.md, which are mutable.
• A citation is dated — a path, a symbol and a count, not only a capability. An ADR may say "the ledgers then lived under docs/"; it may not say "the ledgers live under docs/". Cite the kind of home (the machine ledger, the design doc) or date the reference. An unresolvable path citation is either pinned with a reason in scripts/adr-citations.toml or it fails check_adr.py; telling history from staleness is that ledger's whole purpose (ADR-0027).
• A number may be evidence, never a baseline. A count that is part of an argument — the rejected alternative's failures, a named boundary — is frozen with the ADR and belongs in it. A current suite baseline belongs in docs/TEST-BASELINES.md and its ledger scripts/test-baselines.toml, which are machine-checked. An ADR that quotes today's suite result is a bug.

Three consequences worth stating outright:

• Superseding is additive. Correcting a decision means writing a new ADR and setting the old one's Status to Superseded by ADR-NNNN. The old text is never edited — the record of what we believed, and why, is the useful part.
• Corrections are additive too. A defect in a frozen ADR's text is corrected by a new ADR carrying - Corrects: ADR-NNNN, and the corrected ADR's row below names the corrector — both ends, enforced by check_adr.py. The old text is never edited. See ADR-0022 (three citations at once) and ADR-0026 (a path a follow-through had moved).
• Numbers are citations. They are dense from 0001, never reused, never renumbered. A number is assigned once, in the order decisions are established when their ADR is written, and the Date: field carries the date the decision was actually taken. Because most of this corpus is backfilled from existing records, a decision discovered later keeps its true (possibly earlier) Date: and takes the next free number — so the sequence is approximately chronological, and Date: is always the authority. That is the cost of keeping numbers stable; stability is worth more here than a perfect chronology.

scripts/check_adr.py (CI job check-docs) enforces the mechanically checkable half: filename and heading agree, dense numbering, one of four Status values, a YYYY-MM-DD date, the required sections, every ADR listed below, Superseded by written from both ends, a Corrects: target that exists, is lower-numbered and is named on its own index row, and every path citation either resolving or pinned in scripts/adr-citations.toml.

Index

Ordered by Date:, because a number is a citation and a date is the chronology. Backfilled ADRs are numbered in the order they were written, so a lower number does not imply an earlier decision — see the numbering rule above. Within one date, the order is by number.

The template

# NNNN. One-line decision title

- Status: Accepted | Proposed | Rejected | Superseded by ADR-NNNN
- Date: YYYY-MM-DD
- Issues: #NN, #NN            (optional)
- Supersedes: ADR-NNNN        (required when this ADR replaces one)
- Corrects: ADR-NNNN          (when this ADR corrects an earlier one's text; see ADR-0022)

## Context

What the situation was, and what made it a decision rather than a default. Cite the record.

## Decision

What was decided, in one or two sentences, then the concrete facts (symbols, files, flags).

## Alternatives considered

Each alternative and the reason it lost — a measurement, a constraint, a cost. If the record holds
no rejected alternative, say so explicitly rather than inventing one.

## Consequences

What this makes easy, what it makes expensive, and which costs were knowingly accepted.

## References

The design doc or plan section that holds the current contract, and the issues/PRs involved.