A wrong reason is corrected in place and versioned; a changed choice is superseded

ADR-019: A wrong reason is corrected in place and versioned; a changed choice is superseded

Status Active · Filed 2026-08-03

Context

ADR-018 rejected an alternative for a reason that does not hold. It claimed a bot commit maintaining a badge file would hit the hazard ADR-002 names, and it wouldn’t: that hazard depends on a file being appended to at a marker and carrying assigned numbers, so in-flight branches conflict exactly where their own content goes and a mis-resolution silently drops someone’s entry. A derived badge file has neither property.

The decision itself was still right, for a different reason that hadn’t been written down. So: the choice stands, one of the arguments for it is wrong, and the record says never rewrite a decision’s body.

Read literally, that leaves only supersession — retiring a decision that is still in force, repointing every citation at a near-identical replacement, and adding a Superseded entry that tells a reader the choice changed when it didn’t. That is the wrong shape for the actual event, and doing it a few times would make the status vocabulary stop meaning anything.

Decision

Two failure modes, two remedies.

what is wrong	remedy	what the reader sees
the choice — we’d decide differently now	supersede: new decision, old one Superseded	two decisions, and when the second replaced the first
a reason — the choice stands, an argument for it doesn’t	correct in place, bump version, add history:	one decision, v2, and what the previous version got wrong

The second is what version: is for, and it is a widening of ADR-016’s account of the field, which named only the scope-widening case.

The history: entry is the load-bearing part. It says what the previous version claimed and why that was wrong — so the correction is legible as a correction rather than as a document that was always right. That is precisely what “never rewrite a body” is protecting: the objection is to silent revision, not to being wrong out loud. A version bump plus a history note is the opposite of silent.

The rule of thumb, for the case that looks ambiguous: would a reader who acted on the old version have done something different? If yes, the choice changed — supersede. If they would have done the same thing for a worse reason, correct in place.

Alternatives considered

• Supersede for any change at all. Simple, unambiguous, and it makes Superseded mean two incompatible things — “we changed our minds” and “we fixed a paragraph”. The status vocabulary is closed and small (ADR-003) because each entry is supposed to tell a reader something specific; overloading one is how it stops doing that.
• Correct silently. Cheapest, and indistinguishable from rewriting history. A record you can quietly revise is a record that can’t be trusted about what you used to think — which is the same argument that makes supersession the rule for a changed choice.
• Leave the wrong reason standing and add a footnote. Honest, and it leaves the bad argument in the position a reader quotes from. A wrong reason is more dangerous than a wrong decision, because it gets reused on the next problem.
• Only allow this before anyone has read it. Attractive and unenforceable — nobody knows when that moment passes, and a rule that depends on it is a rule people apply to whatever they feel like correcting.

Consequences

• ADR-018 is v2, with its endpoint-badge paragraph rewritten and both versions of the reasoning recorded. Its citations did not move, because the decision did not.
• The index shows v2 beside a code, which is the first time the version render (ADR-016) has had anything to display for a decision.
• This makes the record’s own governance falsifiable in a new way: a decision whose history: says nothing about why the previous version was wrong is a correction pretending to be an improvement, and that is now a thing a reviewer can point at.