101 lines
4.9 KiB
Markdown
101 lines
4.9 KiB
Markdown
# ADR-023 — ADR structure & lifecycle
|
||
|
||
## Status
|
||
|
||
Accepted (2026-06-10). Meta/doctrine ADR — pins how ADRs are written; the
|
||
`adr-structure` check (`scripts/repo-scan.py`) and `docs/decisions/adr-template.md`
|
||
ship with it, and ADRs 001–018 were retroactively restructured to conform. Resolves
|
||
the FRICTION signal (2026-05-31) about ADR-writing policy being unsettled.
|
||
|
||
## Context
|
||
|
||
boma records architectural decisions as numbered ADRs in `docs/decisions/`, and
|
||
CLAUDE.md treats them as load-bearing. Yet no ADR said how an ADR is written. The
|
||
newest ADRs (019–022) converged on a clean shape — Status → Context → Decision →
|
||
Consequences → Related — but only by imitation. ADRs 001–018 predate it and drifted
|
||
widely: most lacked a `## Status` section entirely (016–018 carried only a trailing
|
||
build-state note), and many lacked an explicit `## Decision` or `## Consequences`
|
||
heading, their decisions spread across ad-hoc topical sections. The result was
|
||
structural drift and no uniform way to tell an active decision from a superseded or
|
||
deprecated one.
|
||
|
||
## Decision
|
||
|
||
### 1. Title & filename
|
||
|
||
Title line: `# ADR-NNN — <Title>: <optional clarifying subtitle>` (em-dash). Filename:
|
||
`NNN-kebab-title.md`, zero-padded 3-digit, monotonic, never reused — a superseded ADR
|
||
keeps its number and file. A new ADR is registered as a row in the CLAUDE.md
|
||
"Further reading" table.
|
||
|
||
### 2. Mandatory sections, in this order
|
||
|
||
- `## Status` — `Accepted (YYYY-MM-DD)`, plus an optional one-line note.
|
||
- `## Context` — the forces, the problem, what exists today, why now.
|
||
- `## Decision` — what we are doing; numbered sub-decisions for multi-part ADRs.
|
||
- `## Consequences` — results, trade-offs explicitly accepted, follow-on work.
|
||
|
||
### 3. Optional sections (use only where they genuinely apply)
|
||
|
||
`## Related`, `## Scope`, `## Guardrails` / `## Enforcement`, `## What was ruled out`,
|
||
`## Verified facts (ADR-014)`.
|
||
|
||
### 4. Status lifecycle
|
||
|
||
Three states; no "Proposed" stage (boma is single-contributor and trunk-based with no
|
||
review gate, so an ADR is born committed-to).
|
||
|
||
- Born **`Accepted (YYYY-MM-DD)`**.
|
||
- Replaced → old ADR's Status becomes **`Superseded by ADR-NNN (YYYY-MM-DD)`**; the new
|
||
ADR records `Supersedes ADR-MMM` in its Status and `## Related`. The link is
|
||
**bidirectional**.
|
||
- Retired with no replacement → **`Deprecated (YYYY-MM-DD)`** + a one-line reason.
|
||
|
||
**No silent rewrites.** An Accepted ADR is not edited to reverse its decision. Typo and
|
||
clarity fixes are fine; a material reversal requires a new ADR and a `Superseded by`
|
||
marker on the old one.
|
||
|
||
### 5. Template & enforcement
|
||
|
||
`docs/decisions/adr-template.md` is the scaffold for new ADRs. The `/review-repo`
|
||
command's pre-scan (`scripts/repo-scan.py`) emits an `adr-structure` finding for any
|
||
numbered ADR missing a mandatory section or with an unparseable Status line. It checks
|
||
**presence and Status, not section order** — order is a convention the template carries,
|
||
deliberately not gated, to keep enforcement lightweight (consistent with boma's other
|
||
doctrine ADRs adding no CI gate).
|
||
|
||
### 6. Retroactive conformance of the back-catalogue
|
||
|
||
ADRs 001–018 are restructured to satisfy this standard rather than grandfathered. The
|
||
restructure is **presentational** — existing headings are relabelled, regrouped, or
|
||
demoted under a `## Decision` umbrella; a dated `## Status` is added; a `## Consequences`
|
||
section is assembled from implications the ADR already states. **The substance of no
|
||
decision is changed.** This keeps the check uniform (no number threshold) and the corpus
|
||
a consistent, legible decision history.
|
||
|
||
## Consequences
|
||
|
||
- New ADRs have one obvious shape and a scaffold; structural drift stops.
|
||
- Every ADR declares its lifecycle state uniformly, and reversals are traceable.
|
||
- The whole corpus conforms; the check needs no grandfathering and stays simple.
|
||
- One-time restructure churn across ADRs 001–018 (heading reorganization + a Status and
|
||
a Consequences section per file; no decision substance changed).
|
||
- `/review-repo` grows one deterministic check; no new CI machinery.
|
||
- This ADR is the first conformant example and is held to its own check.
|
||
|
||
## What was ruled out
|
||
|
||
- **A "Proposed" draft stage** — no review gate exists for it to serve.
|
||
- **A `make lint` / CI gate for ADR structure** — heavier than the risk warrants;
|
||
the `/review-repo` check and the template suffice.
|
||
- **Machine-enforcing section order** — brittle for marginal value; left as a
|
||
template-demonstrated convention.
|
||
- **Grandfathering 001–018 from the check** — rejected in favour of restructuring the
|
||
whole corpus to conform, so the standard applies uniformly with no exceptions.
|
||
|
||
## Related
|
||
|
||
- ADR-014 — knowledge sourcing (the `Verified facts` optional section).
|
||
- ADR-019/020/021/022 — the emergent structure this ADR codifies.
|
||
- `docs/decisions/adr-template.md` — the scaffold.
|
||
- `scripts/repo-scan.py` — the `adr-structure` enforcement check.
|