boma/docs/superpowers/specs/2026-06-10-adr-structure-design.md

# Design — ADR structure & lifecycle

- **Date:** 2026-06-10
- **Status:** Approved design — implementation plan to follow
- **Resolves:** the absence of a written standard for how ADRs in
  `docs/decisions/` are structured. The newest ADRs (019–022) have converged on a
  clean pattern (`Status` → `Context` → `Decision` → `Consequences` → `Related`),
  but it lives only as imitation; ADRs 001–018 predate it and most lack a `Status`
  section.
- **Becomes:** ADR-023 (this design is the basis for that ADR).
- **Reuses:** boma's existing `*-template.md` convention (`service-security-template.md`,
  `service-verify-template.md`, `service-access-template.md`, `service-backup-template.md`);
  ADR-014 (knowledge-sourcing → the optional `Verified facts` section); ADR-019/020/021/022
  (the emergent structure being codified); the `/review-repo` command (enforcement home).

---

## Problem

boma documents architectural decisions as numbered ADRs in `docs/decisions/`, and
CLAUDE.md treats them as load-bearing ("Before assuming a role, provider, or pipeline
exists, check STATUS.md"; the entire "Further reading" table points into them). Yet
there is no ADR that says how an ADR is written. The result:

- **Structural drift.** ADRs 001–018 are freeform; 019–022 converged on a consistent
  shape but only by imitation. A new ADR's structure depends on which existing one the
  author happened to copy.
- **No status discipline.** Most early ADRs have no `## Status` section, so there is no
  uniform way to tell an active decision from a superseded or deprecated one — and no
  written rule for how a decision gets reversed without silently rewriting history.
- **No scaffold.** Every other recurring document type in boma has a template
  (`service-security-template.md`, etc.). ADRs do not.

This design codifies the structure 019–022 already demonstrate, pins a status
lifecycle, ships a template, and reconciles the back-catalogue.

## Scope

- **In:** the canonical section set (mandatory + optional); title and filename
  convention; the `Accepted / Superseded / Deprecated` status lifecycle and the
  no-silent-rewrite rule; cross-reference convention; an ADR template file; a
  lightweight `/review-repo` structure check; a one-time backfill of `## Status` into
  the ADRs that lack one.
- **Out (for now):** rewriting the *decisions* in any existing ADR; normalizing the
  body section names of 001–018 beyond adding `Status`; a `make lint` / CI gate for
  ADR structure (explicitly rejected in favour of the `/review-repo` check —
  consistent with boma's other doctrine ADRs, which add no CI gate); a "Proposed"
  draft stage (rejected — boma is single-contributor and trunk-based with no review
  gate, so ADRs are born Accepted).

## Decision

### 1. Title & filename
- Title line: `# ADR-NNN — <Title>: <optional clarifying subtitle>` (em-dash `—`,
  matching every existing ADR).
- 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. Canonical sections

**Mandatory — every ADR, in this order:**

| Section | Holds |
|---|---|
| `## Status` | `Accepted (YYYY-MM-DD)`, plus an optional one-line note (what it resolves/supersedes, or a doctrine-not-yet-built caveat as ADR-022 uses) |
| `## Context` | the forces, the problem, what exists today, why now |
| `## Decision` | what we are doing — numbered sub-decisions for multi-part ADRs, as 020/021/022 do |
| `## Consequences` | results, trade-offs *explicitly accepted*, follow-on work |

**Optional — use only where genuinely applicable, never as padding:**

- `## Related` — links to other ADRs by number.
- `## Scope` — explicit in/out-of-scope boundaries.
- `## Guardrails` / `## Enforcement` — how the decision is mechanically enforced
  (lint, CI, hooks).
- `## What was ruled out` — rejected alternatives, each with its reason.
- `## Verified facts (ADR-014)` — version-stamped facts per the knowledge-sourcing rule.

### 3. Status lifecycle

Three states; no "Proposed" stage.

- Born **`Accepted (YYYY-MM-DD)`** — the sole author commits to it on writing.
- Replaced by a later decision → the old ADR's Status becomes
  **`Superseded by ADR-NNN (YYYY-MM-DD)`**; the superseding ADR records
  `Supersedes ADR-MMM` in its own `## Status` and `## Related`. The link is
  **bidirectional** — both files must point at each other.
- Retired with no replacement → **`Deprecated (YYYY-MM-DD)`** plus a one-line reason.

**Load-bearing rule — 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. The history of decisions stays legible.

### 4. Cross-references
Reference other ADRs by number inline (`ADR-019`), and collect the relationships in a
`## Related` section.

### 5. Template file
Ship `docs/decisions/adr-template.md` — consistent with boma's existing
`*-template.md` convention. It contains the mandatory section headers pre-filled with
short HTML-comment hints, and the optional sections listed as commented stubs to
uncomment when relevant. It is a skeleton, not a numbered decision, so it does not take
an ADR number.

### 6. Retroactive backfill (001–018)
A **separate follow-up step** after the ADR and template land: add a `## Status`
section to every ADR that lacks one. Status value is `Accepted (YYYY-MM-DD)` where the
date is reconstructed from each file's **first git-commit date**. **Only the Status
header is added — no decision content is touched.** ADRs already carrying a `## Status`
(019–022) are left alone.

### 7. Enforcement
Lightweight, no CI gate. The `/review-repo` command gains an ADR-structure check:
every file in `docs/decisions/` matching `NNN-*.md` has the four mandatory sections and
a parseable `## Status` line. The template carries the convention forward for new ADRs.

## Consequences

- New ADRs have one obvious shape and a scaffold to start from; structural drift stops.
- Every ADR declares its lifecycle state uniformly, and reversals are traceable rather
  than silent — the back-catalogue becomes a legible decision history.
- One-time churn: a backfill commit touching ~18 files (Status header only).
- `/review-repo` grows a new check; no new CI machinery, matching boma's habit of not
  gating doctrine in CI.
- This ADR is itself the first conformant example — it must follow its own structure.

## Open questions

None outstanding — title/filename, the 3-state lifecycle, template name
(`adr-template.md`), enforcement (`/review-repo`, no CI gate), and the
Status-only backfill were all confirmed during brainstorming.