# Architecture Decision Records

One file per decision, numbered, never deleted. A superseded record has its `status:` changed
and gains a pointer to what replaced it — **its text is never edited**. The reasoning that was
rejected is the expensive half to rediscover.

The records are a **ledger**: they run in the order the decisions were taken, oldest first.

## Frontmatter

```yaml
---
status: proposed | accepted | superseded
date: YYYY-MM-DD          # when the decision was taken, not when it was written down
deciders: name
reconstructed: true|false # true when the record was written after the fact from evidence
superseded-by:            # adr/NNNN-....md, when status is superseded
extends:                  # adr/NNNN-....md, when this record widens an earlier one
---
```

## Body

```
# N. Title in plain language

## Context            what was true, with evidence
## Considered Options numbered, each with why it was rejected
## Decision           what was decided
## Consequences       what follows, including what got harder
## References         commits, pull requests, knowledge-base entries, prior art
```

State evidence, not assertion. *"Zero of 124 modules declare `brain` as a dependency"*
outranks *"the dependency rule is not followed"*.

## Reconstructed records

Records 0001–0014 were written on 2026-08-23, after the decisions they describe. Those
decisions were taken in implementation rather than in a document; the records state what was
decided and the evidence it was decided from, and each carries `reconstructed: true` and says
so in its first lines.

A reconstructed record is not a transcript. Where the deliberation is not recoverable, the
options section states what the alternatives were and why the chosen one won on the evidence
available — not a discussion that did not happen. Where a date is not establishable it says so
rather than guessing.

## Index

The index is **generated, not maintained** — run the `hal-status` skill, which reads the
frontmatter of every record. A hand-written index drifts from the folder it describes, and
this one had already done so after a single addition.