# ADR-0000: Record architecture decisions ## Status Accepted ## Context The RDBMS Playground project will accumulate design decisions as it grows. We want those decisions to be traceable, reviewable, and easy to challenge later when context has changed. ## Decision Record significant architecture and product decisions as Architecture Decision Records (ADRs) in `docs/adr/`, using the Michael Nygard format (Status, Context, Decision, Consequences). Files are numbered sequentially with a four-digit prefix and a kebab-case slug, e.g. `0001-language-and-tui-framework.md`. Each ADR captures one decision. Superseding a decision means adding a new ADR that references the old one and marking the old one as "Superseded by ADR-NNNN". ADRs document decisions, not speculation. An idea under discussion belongs in conversation, an issue, or a design note — not an ADR. An ADR is written once a decision has actually been made. ## Index discipline `docs/adr/README.md` contains the canonical index of all ADRs. Whenever an ADR is added, renamed, or has its status changed (e.g. "Superseded by ADR-NNNN"), the index MUST be updated in the same change. An ADR change without a corresponding index update is incomplete. The index lists ADRs in numerical order. Each entry shows the number, title, and — where relevant — status annotations such as "Superseded by ADR-NNNN" or "Deprecated". ## Numbering discipline ADR numbers are a single global sequence, so two branches can each grab "the next number" independently and collide on merge. (This happened when the `website` branch's ADR-0042 met `main`'s ADR-0042, resolved by renumbering the former to ADR-0044.) To prevent it: **Reserve the number up front, via `scripts/adr-reserve.sh`** (ADR-0059, which superseded the earlier placeholder-until-merge default). The moment you know an ADR is needed — at branch start or mid-branch — run `scripts/adr-reserve.sh ""`. It atomically claims the next free number against `main` (the remote ref is the registry; a `git push` is the compare-and-swap, retried on contention) and records it in the append-only ledger `docs/adr/RESERVATIONS.log`. The number is then **stable from creation**, so it is safe to cite in commit messages (immutable under the no-rewrite rule), in other ADRs, and in the PR from the first commit. Create the ADR as `docs/adr/<NNNN>-<slug>.md` and add its README index row as part of the branch's normal work. A number is "taken" once its ledger line (or `NNNN-*.md` file) is on `main`; the script reads both to compute the next free number — never compute "next" by hand from a feature branch. The full rationale (why reserve-first beats number-on-merge, issue-number ids, or an allocator bot) is in **ADR-0059**. ### Subproject ADR namespaces A long-lived subproject developed on its own branch can escape the shared integer pool entirely by keeping its decision records in a **separate namespace**, rather than fighting collisions on every merge. The **website** (`docs/website/adr/`) is the first: its ADRs use a dated sequence — `<date>-adr-website-<NNN>.md`, referenced in prose as `ADR-website-NNN` — and are indexed by their own `docs/website/adr/README.md`. Because the date-plus-subproject prefix is disjoint from `main`'s integer sequence, a website ADR and a `main` ADR can never claim "the same number" again. (This namespace was created on 2026-06-10 after the website's ADR collided with `main`'s on consecutive numbers — drafted 0042, bumped to 0044, both times landing on a number `main` had taken; the move retired it from the pool as **ADR-website-001**.) The main `docs/adr/` index carries a pointer to each such namespace. Use this for a new subproject only when it is genuinely self-contained and branch-isolated; one-off cross-cutting decisions stay in the global sequence. ## Out-of-scope discipline ADRs (and the plans they spawn) lean heavily on "out of scope" language. The phrase carries two very different meanings, and conflating them misleads a later reader: - **Deferred** — out of scope *for this plan / phase / step*, but a reasonable thing to do later. A sequencing decision, effectively a tracked TODO. Where possible, point at where it will be picked up. - **Rejected** — considered and deliberately *not* done, on principle. Durable. State the reason. When writing an out-of-scope item, **say which kind it is** — e.g. `OOS (deferred)` / `OOS (rejected: <reason>)`, or the equivalent in prose — so a future reader can tell a standing decision from a not-yet. A bare "out of scope" is ambiguous and tends to read, wrongly, as permanent. (Motivating example: ADR-0030 §13 OOS-2 was a deferred scope exclusion that read as a permanent rejection until ADR-0039 lifted it.) ## Consequences - New significant decisions require an ADR before or alongside the implementation that depends on them. - Old decisions remain visible even after they are superseded. - Reviewers can audit the rationale chain by reading `docs/adr/` in order. - The index in `README.md` stays trustworthy because keeping it current is part of every ADR change, not an afterthought.