notarius/docs/adr/0001-record-architecture-decisions.md

ADR-0001: Record architecture decisions as ADRs

Status: Accepted Date: 2026-07-13

Context

Architectural reasoning made during design (pattern choices, rejected alternatives, trigger conditions for revisiting) is lost if only the final state is documented.

Decision

We keep a living overview in docs/policy/architecture.md describing current intended state, and immutable, numbered ADRs (Nygard format) in docs/adr/ recording each significant decision, its alternatives, and its consequences. Changed decisions get a new ADR that marks the old one Superseded.

Alternatives considered

• Overview doc only: loses the "why" and the rejected options.
• arc42 / RFC-style design docs: heavier than warranted for a solo repo.

Consequences

Small ongoing writing cost; durable reasoning trail; cheap onboarding for future contributors (including future-us).