Skip to main content

ADR-0021: Amending Accepted ADRs (Amends vs Supersede)

  • Status: Accepted
  • Date: 2026-07-17
  • Deciders: Michel Gillet

Context​

A2C treats Accepted ADRs as immutable in substance (rules/08-adr-editing-evolution.md). Meaning changes require a new ADR. Today that almost always means Supersede: the new ADR replaces the old one, and authors often copy most of the prior Decision to keep a readable standalone record.

That pattern is correct when the core decision is no longer valid. It is heavy-handed when the intent is only to extend or clarify an Accepted ADR without invalidating it (for example, adding one constraint or naming a new exception). Teams then face a false choice: silent in-place edits (forbidden) or a near-duplicate superseding ADR.

This ADR introduces amendment as a first-class evolution path alongside supersession. It extends — does not replace — the existing status lifecycle (Proposed / Accepted / Rejected / Superseded / Deprecated). The informal label Active from some intake drafts maps to Accepted in A2C.

ASR files (ADR-0019) follow the same Amends vs Supersede distinction when ASRs are used.

Decision​

1. When to amend vs supersede​

IntentUseEffect
Extend or clarify; core decision still holdsAmendOriginal remains governing; must be read with its amendments
Replace; core decision no longer validSupersedeOnly the superseding ADR governs new work; old ADR is history

Prefer amend when a small additive ADR would otherwise force copying ~all of an Accepted ADR. Prefer supersede when continuing to treat the old Decision as normative would mislead readers.

2. Status values (ADRs and ASRs)​

Keep existing A2C values and add Amended:

StatusMeaning
ProposedUnder discussion — may be edited freely
AcceptedGoverning and not amended or superseded
AmendedStill governing as a base; must be read with linked amending ADRs/ASRs
RejectedNot adopted — immutable in substance
SupersededNo longer valid for new work; replaced by another ADR/ASR
DeprecatedHistorically valid; do not use for new work (even if not superseded)

Do not introduce a parallel Active status in A2C method docs.

3. Amends / Amended by (additive)​

When amending an Accepted ADR (or ASR):

  1. Create a new ADR/ASR whose Decision contains only the additive or clarifying change (and any context needed to understand that change).
  2. New artifact: Status: Proposed then Accepted; set ## Amends to the base ID(s).
  3. Base artifact (same commit as accepting the amendment, or immediately with the amending adr(...) commit): set Status: Amended; set ## Amended by to the new ID(s). Do not rewrite the base Decision/Context/Consequences for new intent.
  4. Effective architecture for readers and agents: base (Amended) plus all Accepted amendments in the Amended by chain.

Multiple amendments to one base are allowed; list all amending IDs under Amended by.

4. Supersedes / Superseded by (replacement)​

Unchanged in spirit from existing A2C rules:

  • New ADR/ASR: ## Supersedes + Accepted when adopted
  • Old ADR/ASR: Status: Superseded + ## Superseded by
  • Base body stays frozen except allowed non-semantic maintenance (rules/08 § B)

An Amended ADR may later be Superseded if the base+amendments set is replaced as a whole; the superseding ADR should state what it replaces (including whether amendments remain historically relevant).

5. Allowed in-place updates for linkage​

On Accepted ADRs/ASRs, in addition to § B maintenance in rules/08, the following status/link updates are allowed only as part of an amend or supersede commit:

  • Status: Accepted → Amended, plus ## Amended by
  • Status: Accepted or Amended → Superseded, plus ## Superseded by

These are linkage updates, not semantic rewrites of Decision text.

6. Templates and rules​

ADR and ASR templates include ## Amends / ## Amended by sections. rules/02-adr-conventions.md, rules/08-adr-editing-evolution.md, and docs/adr/README.md document amendment alongside supersession.

Consequences​

Positive​

  • Small architectural extensions without duplicate superseding ADRs
  • Clearer history: base decision stays readable; deltas live in amending ADRs
  • Same pattern usable for ASRs when adopted
  • Compatible with existing Proposed/Accepted/Superseded vocabulary

Negative​

  • Readers must follow amendment chains (INDEX and Amended by links help)
  • Risk of over-using Amends when Supersede was appropriate — authors must choose deliberately

References​

Amends​

  • (none)

Amended by​

  • (none)

Supersedes​

  • (none)

Superseded by​

  • (none)