One file per significant decision, numbered in the order it was taken. An ADR records why a boundary sits where it does, so the reasoning survives the people who had it and the decision is not silently reversed by whoever touches the code next.
An accepted ADR is immutable. It is never edited to reflect a change of mind; it is superseded or amended by a later record that links back to it. A record still marked Proposed is live — the decision is argued but not closed, and the mechanism it describes usually ships off by default until it is.
Copy the shape of
0001-record-architecture-decisions.md.
The filename is NNNN-a-sentence-in-the-imperative.md, zero-padded to four
digits, and the heading repeats that sentence. Every record opens with a
Status (Proposed, Accepted, or Accepted-and-superseded) and a Date, and
carries Context, Decision, and Consequences sections. Link the
specification in ../specs/ that the decision serves, and
link any earlier ADR it amends.
| # | decision | status |
|---|---|---|
| 0001 | Record architecture decisions | Accepted |
| 0002 | Hive episodes are sequential, and visibility is the fan-out knob | Accepted |
| 0003 | Refutation links evidence to a topic, and caps rather than debits | Accepted, ships off by default |
| 0004 | Grounds are weighed by evidential depth, not counted | Accepted, ships off by default |
| 0005 | A blind round may be concurrent | Proposed — amends 0002 |
| 0006 | A referral crosses one channel at a time, and carries information rather than a vote | Accepted |
| 0007 | The directory is folded from citations, and the host's affinity is a prior rather than an authority | Accepted |
| 0008 | An approval decision is total: it denies rather than fails | Accepted |
| 0009 | A refusal renders only what the caller already holds | Accepted |
| 0010 | An aside carries information rather than support, and a redaction is a row rather than an absence | Proposed |
| 0011 | An aside rides alongside the turn that authored it rather than spending one | Proposed — amends 0010 |
| 0012 | An exchange round spends model calls rather than turns | Proposed — follows 0011 |
| 0013 | A vendored crate may back an example and never a library crate | Accepted |
| 0014 | A round authorizes concurrent turns | Accepted |
| 0015 | The division of labour is the default shape | Accepted |
| 0016 | Distance is measured in the rows a fold reads | Accepted |
| 0017 | Validate semantic routing at the port | Accepted |
| 0018 | Require host-supplied conversation kinds | Accepted |
| 0019 | Complete episodes with explicit agent events | Accepted |
| 0020 | openhuman-embed is a git dependency, patched locally |
Accepted — amends 0013 |
| 0021 | An assignment is appended rather than overwritten, and a participant holds at most one open | Proposed — amends 0019 |
| 0022 | The episode MCP server is the one socket this repository opens | Proposed |
| 0023 | An ask opens a child conversation, a thread of the desk | Proposed — amends review decision D22 |
| 0024 | A broadcast completes its author unless it is waiting | Proposed — amends review decision D13 |
| 0025 | The driver names no harness; one crate links it | Proposed |
0002 is the one to read first: it fixes
one message, one turn as a type invariant, and every later record about the
hive either lives inside that constraint or says explicitly how it amends it.
0010 →
0011 →
0012 form one
argument about what a private row is and what it costs, and should be read as a
sequence. The measurements that pushed 0011 and 0012 are in
../experiments/.