# ADR-0000: Record architecture decisions

## Status

accepted

## Context

Scrum4Me makes several non-obvious architectural choices that aren't visible
from the code alone — for example, why we use `@base-ui/react` rather than
Radix, why drag-and-drop ordering uses float `sort_order` instead of integer
positions, why authentication runs on iron-session rather than NextAuth,
and why the demo-user policy is enforced in three layers. These decisions
are scattered across `CLAUDE.md`, individual pattern docs, plan files, and
commit messages. New contributors and AI agents working on the codebase
have no fast path to the *why*, which leads to one of two failure modes:
they either re-litigate decisions that were already settled, or they make
changes that violate constraints they didn't know about.

We want a single, predictable place to record significant architectural
choices, with enough context that a reader six months from now can decide
whether the decision still holds.

## Decision

We adopt Architecture Decision Records (ADRs) as the canonical format for
documenting significant architectural choices in this codebase. ADRs live
in `docs/adr/`, are numbered sequentially with a four-digit prefix
(`0001-...md`, `0002-...md`, …), and follow one of two templates:

- **Nygard** ([`templates/nygard.md`](./templates/nygard.md)) — default,
  for one-way-door decisions with a clear motivating context.
- **MADR v4** ([`templates/madr.md`](./templates/madr.md)) — for
  decisions where weighing multiple alternatives is part of the value
  the record provides (auth, queue mechanics, agent integration).

The full conventions — file naming, status lifecycle, template selection
guidance — are documented in [`README.md`](./README.md).

ADRs are immutable once accepted: course corrections create a new ADR
that supersedes the old one rather than editing the original.

## Consequences

### Positive

- Architectural choices have a single, predictable home that an AI agent
  or new contributor can find with one `ls docs/adr/`.
- The "why" of each decision is captured at the moment it's made, when
  the context is fresh, rather than reconstructed later from commits.
- Superseded decisions remain readable, so future contributors can see the
  history of a choice without git archaeology.
- The format scales: writing an ADR is a 15-minute activity for the
  default Nygard template, low enough overhead to be worth doing every
  time.

### Negative

- Adds a small ritual to every significant architectural decision — easy
  to skip when moving fast, leading to a stale or incomplete record if
  not enforced through review.
- Backfilling existing decisions requires writing 5–8 retrospective ADRs
  for choices that were never recorded (planned in fase 6 of
  [`../old/plans/docs-restructure-ai-lookup.md`](../old/plans/docs-restructure-ai-lookup.md)).
- Two templates means a per-decision choice about which to use. Mitigated
  by making Nygard the explicit default in `README.md`.