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 retroactive restructure of ADRs 001–018 to full conformance (all four mandatory sections + a parseable Status line), reorganizing existing content under canonical headings.
• Out (for now): changing the substance of any existing decision (the restructure is presentational — relabel/regroup/demote existing content, add a dated Status, never alter what was decided); 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); grandfathering pre-convention ADRs from the check (rejected — the whole corpus is brought to conformance instead).

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 restructure (001–018)

A separate step after the ADR and template land: bring every pre-convention ADR to full conformance — all four mandatory sections present and a parseable Status line. This is a presentational restructure, governed by a strict faithfulness rule:

• Add a ## Status section valued Accepted (YYYY-MM-DD), the date reconstructed from the file's first git-commit date. For 016–018, whose existing trailing build-state note is unparseable, prepend the dated Accepted (...) clause so the note becomes a parseable Status line's tail.
• Reorganize existing content under the canonical headings: relabel a synonym (## Decisions → ## Decision), or introduce a ## Decision umbrella and demote the existing topical ## headings to ### beneath it. No sentence of existing prose is altered.
• Add a ## Consequences section built only from implications the ADR already states (trade-offs, "what was ruled out", "open questions", follow-on work already named). If an ADR genuinely states nothing that can be faithfully cast as a consequence, that file is escalated for a human decision rather than inventing one.
• Never change the substance of a decision. A git diff of the restructure should show heading-level changes, a new Status section, and a Consequences section assembled from existing material — not edits to existing argument.

ADRs already conformant (019–022) are left alone. End state: the adr-structure check reports zero findings across the whole corpus, with no grandfathering.

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 restructure touching ~18 files (heading reorganization + a Status section + a Consequences section per file). Larger and more judgment-heavy than a Status-only backfill, hence the faithfulness rule and per-file review.
• The whole corpus conforms — the check needs no grandfathering or number threshold, and stays simple (presence + parseable Status, applied uniformly).
• /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 full retroactive restructure of 001–018 (no grandfathering) were all confirmed during brainstorming.