Architecture Decision Records

Why we record decisions here:

The repo grows; the why behind a constraint stops being obvious.
AI agents and new contributors need durable, searchable context for rules they will otherwise question or accidentally undo.
git log carries the what. ADRs carry the why + the trade-offs considered + the consequences if you break the rule.

Convention

Filename: NNNN-kebab-title.md — zero-padded sequence, never reused.
One decision per file. Short. ≤1 page when possible.
Every ADR uses the same structure: see TEMPLATE.md.
Status: proposed → accepted → optionally superseded by NNNN / deprecated. Never delete an ADR; supersede it.
Date: the date status changed (ISO YYYY-MM-DD).
Cite source files (path:line) and tests so the rule is verifiable.

ADR vs `features/` / `technical/`

docs/adr/ — historical decisions that shape today's code. Read to understand why a rule exists.
docs/features/ — forward-looking product / UX briefs. What and why of a feature being shaped.
docs/technical/ — implementation plans and cross-cutting tech reference. How a feature is being built.

A design brief or tech plan may graduate to an ADR once the decision is locked in and worth defending against future drift.

When to write a new ADR

Triggers (any one):

A rule has been broken once and we want to make sure it isn't again.
A reviewer asked "why is it this way?" and the answer isn't in code.
We chose between two reasonable approaches and the loser will keep resurfacing.
A constraint is imposed by an external system (regulator, vendor, licensor) and we need to capture it once.

Index

#	Title	Status	Date
0001	Modular plugin architecture	accepted	2026-04-27
0002	Per-module Alembic branches	accepted	2026-04-27
0003	Event bus over direct cross-module imports	accepted	2026-04-27
0004	BSL 1.1 license, Apache 2.0 after 4 years	accepted	2026-04-27
0005	Relative permissions, registry-prefixed namespacing	accepted	2026-04-27
0006	Budget public link two-factor authentication	accepted	2026-04-28