One decision, followed all the way
Take one architecture decision record (ADR): ADR-118: Outbound HTTP from the payments services goes through the internal client. The internal client handles retries, authentication and audit logging. A team wrote the ADR two years ago. It sits in docs/adr/, it is well argued, and every senior engineer knows it.
A coding agent reads the same file as text. It can quote the decision. What it cannot tell from the text alone is whether the decision still holds, which code it covers, who agreed to it, or what to do when another decision points the other way.
This article follows ADR-118 through the stages that turn a record into a governed decision. At each stage it asks one question: what does an agent get wrong if you stop here? The definition and the full anatomy live on the engineering decision governance concept page. This is the stage-by-stage version.
Stage 0: the record
The ADR states the decision, the context and the consequences. For a human reader that is often enough, because the reader also knows the history.
If you stop here: the agent retrieves ADR-118 alongside an older design note that lets each service pick its own HTTP library. Both are text. Both look authoritative. The agent picks one, and you find out which in review.
Stage 1: lifecycle
The decision gets a status (proposed, accepted, superseded, deprecated) and an explicit link to what it replaced. ADR-118 supersedes ADR-074, which let each service choose its own library.
If you stop here: with a status recorded, the agent can tell ADR-074 is no longer in force. It still applies ADR-118 everywhere. Lifecycle tells you whether a decision holds, not where.
Stage 2: scope and applicability
The decision says which code it governs. ADR-118 covers services/payments/**. It deliberately excludes the sandbox tooling that calls a card network's test API directly by design.
If you stop here: the agent applies the right decision to the right code, but cannot tell an accepted decision from a draft someone pasted into the wiki. Every document with the right shape carries the same weight.
Stage 3: authority and provenance
The decision records its provenance, meaning where it came from, and that someone with the right to adopt it did so. A proposal from an agent, or from a single engineer, is not the same as an accepted decision.
If you stop here: each decision is trustworthy on its own. When two accepted decisions disagree about the same file, something still picks one silently.
Stage 4: relationships and precedence
Decisions relate to each other: one supersedes, one refines, one is an exception to another. When two accepted decisions both apply, a precedence rule decides which wins, and the losing decision is visibly set aside rather than quietly dropped. The precedence semantics article covers why this is harder than it looks.
If you stop here: the decision model is sound, but the agent may never meet the decision at the moment it matters.
Stage 5: retrieval for the task
When an agent is about to change services/payments/refunds.py, the decisions that apply to that file reach it, and the ones that do not stay out of its way. This is selection, not search: the question is which decisions govern this change, not which documents mention HTTP.
If you stop here: the agent is well informed and still free to ignore what it was told. Guidance is a request.
Stage 6: enforcement
A decision is not a rule. One decision can produce several machine-checkable rules, and some decisions produce none. ADR-118 can yield a rule that fails any change importing a third-party HTTP library in services/payments/**. Its line about setting timeouts deliberately yields no rule at all; it stays guidance for people and agents.
If you stop here: violations are caught, but afterwards nobody can show which decision, in which version, produced a given verdict.
Stage 7: evidence
Each verdict points back to the rule that fired and the decision version that rule came from. When ADR-118 changes, you can tell which verdicts were made under the old version and which under the new one.
At this point the record has become a governed decision: current, scoped, authorised, ranked against its neighbours, delivered to the right change, checked where it can be, and traceable afterwards.
| Stage | Question it answers | What breaks without it |
|---|---|---|
| Record | What did we decide? | Nothing tells old text from current text |
| Lifecycle | Does it still hold? | Superseded decisions keep steering agents |
| Scope | Where does it apply? | Decisions land on code they were never meant for |
| Authority | Who adopted it? | Drafts and proposals carry the weight of decisions |
| Precedence | What wins in a conflict? | Conflicts resolve silently and differently each time |
| Retrieval | Which decisions govern this change? | The right decision exists and never reaches the agent |
| Enforcement | Is it checked? | Agents may ignore what they were told |
| Evidence | Can we show it held? | Nobody can trace a verdict to a decision |
You do not need every stage on day one
If your ADRs stop at stage 0 or 1, that is where agent mistakes start. The stages build on each other, so the order matters. Lifecycle and scope fix the two failures that are easiest to hit: following a replaced decision, and applying a decision to the wrong code. Precedence matters once decisions start to overlap. Enforcement only pays off for the decisions that are both expensive to break and possible to check mechanically.
A practical sequence: give every ADR a status and an explicit supersedes link, give each one a path scope, decide who may accept a decision, then pick the five decisions you most need agents to respect and write rules for those. For a hands-on version of the last step, see turn an ADR into an enforceable decision.
Where Mneme fits
Mneme, an open-source decision and control layer for agentic software development, implements part of this today for architectural decisions in a repository:
- Lifecycle and versions. Its Decision Index, the versioned record of a repository's decisions shipped in mneme-hq 0.10.0, keeps each decision's immutable versions and lifecycle status. Supersession comes from the ADR's own frontmatter, and only active decisions are enforced.
- Scope. A typed rule can carry path selectors, so it fires only in the paths it names.
- Authority. Agents can propose decisions through Mneme's local Model Context Protocol (MCP) server, and a person accepts them on the command line. For proposals, authority comes from that acceptance step; for imported ADRs, from the ADR's own status. The index does not store the approver's name.
- Precedence. When two accepted ADRs share a scope, the higher priority wins, then the newer date. The other is stored as inactive rather than deleted. The import does not report this;
mneme checkwith an ADR directory warns about it. - Enforcement and evidence. The enforceable parts of a decision compile into typed rules, which are machine-checkable rules with exact meaning. They are checked by hooks inside supported coding agents, which intercept supported file writes before they land (each integration page lists the covered paths), and in continuous integration (CI). Each violation names the decision and rule that triggered it.
Mneme's design direction goes further: resolving which decisions govern a change and why, reporting how the set of governing decisions changed between two points in time, and tying every outcome to an exact decision version. That design is accepted but not yet released.