adr

Architecture Decision Records

This directory records the significant architectural decisions made on Atlas, using the MADR-influenced format described in template.md.

An ADR captures a decision, the context that forced it, the options considered, and the consequences accepted. ADRs are immutable once accepted: if a decision changes, a new ADR supersedes the old one rather than editing it.

A number belongs to exactly one decision, and it is assigned when the record lands on main — never on a branch. go test ./docs/adr enforces unique, gapless numbers, keeps the index below in step with the directory, and checks that every ADR-NNNN citation anywhere in the repository still resolves. The index is a table of contents: one row per record, carrying that record's own # ADR-NNNN: heading, so what the decision says belongs in the record, not in the cell.

Writing a record

Do not pick a number. A record in flight carries none:

1. Copy template.md to docs/adr/draft-<slug>.md — a kebab-case slug, no number.
2. Keep the heading as # ADR-DRAFT: Your title, and fill in the record.
3. Add no row to the index below.
4. Cite it as ADR-draft-<slug> from code comments and docs, or link draft-<slug>.md.

When the PR merges, a workflow on main runs make adr-number. That renames the file to NNNN-<slug>.md, rewrites the heading, appends the index row, and rewrites every citation of the draft to the number it just got. Nothing for you to remember; you can also run make adr-number by hand on main.

Why the ceremony: the number used to be taken when the record was written, which is the earliest possible moment and the one with the least information. Two open branches both saw the same "next free" number and both took it — that is how 0090, 0103 and 0105 came to be shared by unrelated ADRs (the later record of each pair now lives at 0139, 0140 and 0141). Once a test caught the collision, the cost became a renumber on every merge instead: one record walked 0164 → 0169 across six of them without a word of its content changing. Assigning the number where the question has one answer removes both. The full argument is in the record on merge-time numbering.

A number, once assigned, is never reassigned — that is what makes (ADR-0168) in a comment safe to write.

When the record rests on a question you could not answer

Some decisions are right while something we do not know stays unknown. ADR-0292 is the case that prompted this rule: it renders a MIMWAL table's cells by position because the meaning of the columns is established by no reference anyone could find, and it would be re-argued the day one turns up. Written like any other record, that reads a year later as settled — nothing in it separates "we decided this" from "we decided this for now, on a gap in what we know".

So say both, in the front matter:

- **Open question:** MIMWAL's grid column semantics are not established from its own
  source. The positional cells rest on that gap.
- **Question checked:** 2026-09

The two come as a pair, and go test ./docs/adr insists on it: a question with no date cannot go stale, and a date with no question says a thing was checked without saying what. The question may wrap onto indented lines. The date is the month somebody last looked at the question, not the month the record was written, and the guard fails once it has stood for a year — the same interval, for the same reason, as the Worker Type setup steps of ADR-0289.

The reasoning behind the pair — including why it states a month somebody looked rather than a deadline somebody set — is in ADR-0293.

When the check fires, the fix is never to bump the date. Go and look: if the question now has an answer, delete both lines and check whether the decision that rested on the gap still holds — that is the case this exists for. If it is still open, write down what you learned and date the month you looked.

Reading the older records: "connector"

Records written before ADR-0203 say connector where the rest of the documentation now says Worker Type (an execution capability), Worker (one configured target and identity of that type) or Worker Instance (a process leasing its jobs) — the word meant all three depending on where it stood, which is why it was replaced.

Those records are not rewritten: an ADR is immutable once accepted, and ADR-0203 says so explicitly — older connector wording is reconciled through links, not by editing history. So read ADR-0036, ADR-0041, ADR-0067, ADR-0154/0166/0172/0173/0201 and their neighbours in their own vocabulary; ADR-0203 carries the mapping. The persisted contracts kept the old spelling too, on purpose: the connector/ package paths, the connector="…" BPMN attribute, atlas worker --connector, the ATLAS_*_CONNECTORS variables and the /api/v1/connectors routes.

Index

The two states of a record

A record answers two questions, and they are not the same question. Status says whether the decision holds. Implementation says whether it is built. go test ./docs/adr checks both against their word lists and against each other, and the index above carries both.

Status

• Proposed — under discussion
• Accepted — decided and in effect
• Superseded by ADR-XXXX — replaced by a later decision
• Deprecated — no longer relevant

A parenthetical after the word is fine and common: Accepted (amended 2026-08-17: the marker runs on every activity kind). A different word is not — the guard rejects it.

Implementation

• Not started — none of the chosen option is in the tree
• Partial — part of what the record decided is built and part is not
• Landed — the chosen option is in production code, with tests
• Superseded — a later record replaced the decision; nothing here left to measure

This field carries no parenthetical, because the index is rendered from it. What is built and what is not belongs in the record, where a reader is.

Partial is the word that needs care. An extension the record itself defers is not what makes a record partial — ADR-0154 decided an LDAP connector and listed a delta cookie as a follow-up, and that record is Landed. A piece of the decision that is missing is what makes it partial — ADR-0027 decided that an author selects and applies an element template, and only the store behind it exists.

Why they are two fields

They were one until 2026-09. Status was asked to carry both, readers used it for the more useful question, and the two meanings drifted apart the only way they could: 115 records whose code had shipped, with tests, still read Proposed, because nothing in the process ever went back to change the line. An audit said so in August and named 28 of them; two weeks later not one had moved. That is a missing mechanism, not a missing afternoon.

So there is a rule with a test behind it: Implementation: Landed requires Status: Accepted. Nobody merges code against a decision that has not been made, so a record with landed code is a record whose decision was taken — whatever the front matter still says. The reconciliation that applied this to all 295 records, and the evidence behind each classification, is in the status reconciliation.