Architecture decision records

This directory holds the design history that used to live as long comment blocks inside the modules the 0.9.2 task/workflow refactor touched. Brief §9 named the problem directly: "Historical essays inside large modules | Keep invariant comments locally; move design history to ADRs | Reduce cognitive load without deleting important reasoning." These records are that move.

Format

• One file per decision: NNNN-kebab-title.md, numbered in the order the decision was extracted, not the order the underlying work happened.
• No front matter.
• Four sections, in this order:
  • Context — the problem the module was solving and the constraints in play when the decision was made.
  • Decision — what was decided, including the essay's own reasoning verbatim where it was already written as reasoning. Nothing here is deleted or "cleaned up" on the move — see the binding rule below.
  • Consequences — what the decision implies for callers, for future changes, and (where the essay named one) for alternatives that were considered and rejected.
  • Provenance — the source file(s) and, where the essay named one, the spec section or review round the reasoning came from, plus the date and phase this record was extracted.

What moves here and what stays in the code

Per the brief's own framing (§15, quoted in docs/plans/specs/p4-deletions-closeout.md §1.5): a code comment that explains why mutation is delayed, why a hash includes a field, why a transaction boundary exists, why a source is revalidated, why a child invocation is idempotent — a short, load-bearing invariant a maintainer needs sitting right next to the code — stays in the code. A comment block that is historical narrative — peer-review findings, an earlier draft, a superseded alternative, a phase-by-phase chronology of how a design arrived where it is — moves here instead, replaced in the source by a one-line invariant summary plus a relative link back to the ADR that carries the full reasoning.

Binding rule carried from the spec: no ADR may delete reasoning. An essay's text moves; it is not summarized away. Where an essay describes behavior a later phase deleted, the ADR records the behavior and its removal date, rather than being quietly rewritten as if the behavior never existed.

Index