Architecture Decision Records

An Architecture Decision Record (ADR) captures a single architecturally consequential decision — the context that forced it, the decision itself, and the consequences that follow — as a short, immutable, numbered document. The format here is Michael Nygard's: Title / Status / Context / Decision / Consequences. See the template.

ADRs are how we make the why behind the architecture durable. Code shows what we did; an ADR explains why we did it, what we considered, and what we gave up — so future contributors don't relitigate settled questions or accidentally violate an invariant without knowing it was deliberate.

The index

The process

1. When. Any decision that constrains the architecture — a crate boundary, a dependency with reach (parser, binding, incremental engine), a portability rule, the public API contract, the versioning model — lands as an ADR. Reversible, local choices do not need one.
2. How. Copy template.md to the next number (NNNN-short-kebab-title.md), fill in Context / Decision / Consequences, add it to the index above and to SUMMARY.md, and submit it in the same PR as the change it justifies.
3. Status lifecycle. Proposed → Accepted (merged) → later possibly Deprecated or Superseded by ADR-NNNN. ADRs are append-only: you don't rewrite history, you supersede it with a new record that links back.
4. Source. The three seeded ADRs distill decisions already settled in plans/00-VISION-AND-SCOPE.md and plans/01-ARCHITECTURE.md.