Architectural Decision Records

This page indexes every Architectural Decision Record (ADR) shipped with the Technology Selection Guide. ADRs capture the "why" behind prescriptive guidance: the context, the considered alternatives, the decision drivers, and the consequences. The evergreen chapters tell you what the guide recommends today; the ADRs tell you why that recommendation was selected over its alternatives, and when that selection was last reviewed.

The hybrid structure (evergreen chapters plus a dated ADR archive) follows the ADR-0001 — Hybrid Evergreen plus ADR Subdirectory decision. Adopting organizations MAY retire any upstream ADR by superseding it with a follow-up record; readers MUST treat superseded records as historical context only.

Status legend

The status field of each ADR uses one of the following values. The MADR project defines the canonical semantics; this section restates them so readers SHOULD NOT need to leave the page to interpret the index.

Status	Meaning
proposed	Authored but not yet adopted. MAY be revised or rejected.
accepted	Adopted as binding guidance. Immutable in content; only status MAY change downstream.
rejected	Considered and explicitly not adopted. Retained for historical context.
deprecated	Previously accepted, now retired without replacement. The behaviour is no longer recommended.
superseded	Previously accepted, replaced by a newer ADR. The successor ADR MUST be linked from the Links section.

A reader MUST treat the most recent accepted ADR on a topic as the binding record. A deprecated or superseded ADR MUST NOT be cited as current guidance.

ADR index

The seed ADRs shipped with this guide are listed below in numerical order. Each row gives the canonical title, the current status, the date the status was set, and a link to the full record.

ADR	Title	Status	Date
ADR-0001	Hybrid Evergreen plus ADR Subdirectory	accepted	2026-05-11
ADR-0002	MkDocs Material as Site Generator	accepted	2026-05-11
ADR-0003	RFC 2119 Keywords for Prescriptive Tone	accepted	2026-05-11
ADR-0004	Version Pins as Snapshot, No In-Repo Automation	accepted	2026-05-11
ADR-0005	Exclude .claude Subdirectory Content	accepted	2026-05-11
ADR-0006	react-router v7 Data Mode as Canonical Routing	accepted	2026-05-11
ADR-0007	Include llms.txt and llms-full.txt for LLM Discovery	accepted	2026-05-11

Authoring new ADRs

Adopting organizations and upstream contributors SHOULD author a new ADR whenever a prescriptive recommendation changes, a previously considered alternative is reopened, or a new technology domain is brought under the guide. The process is:

1. Copy 0000-template.md to NNNN-<short-slug>.md, where NNNN is the next free four-digit number.
2. Fill in every section of the template. Authors MUST cite the decision drivers explicitly and MUST include at least two considered options.
3. Set status: "proposed" while the ADR is in review. Change to accepted only when the decision is binding.
4. Append a row to the table above. The row MUST link to the new file with a relative Markdown link.
5. Update mkdocs.yml's nav block under the Decisions: section so the new ADR appears in the site sidebar.
6. Re-run python scripts/generate-llms-full.py so the bundled llms-full.txt mirrors the new sidebar order.

When an ADR is superseded, the superseding ADR MUST link the predecessor under its Links section, and the predecessor's status MUST be flipped to superseded. The predecessor's body content MUST NOT be edited — readers depend on its immutability for historical accuracy.

See also

• ADR template — the MADR-format scaffold authors copy.
• MADR project — upstream format definition.
• RFC 2119 — keyword semantics used in every prescription.