# Rule: ADR editing and evolution

Accepted, Amended, and Rejected ADRs are **immutable in substance**. The ADR log is append-only history — not a silently rewritten design document.

Full narrative: `docs/adr/README.md` § ADR editing and evolution.

## A. Immutability principle

| State | Rule |
|-------|------|
| **Accepted** | Immutable in substance — decision, context, rationale, consequences |
| **Amended** | Base still governing; immutable in substance; must be read with Accepted amendments listed under `## Amended by` |
| **Rejected** | Immutable in substance — historical record of what was not adopted |
| **Proposed** | May be edited freely until Accepted or Rejected |
| **Superseded** | Body frozen except allowed maintenance (below); only `Status` and `Superseded by` may be updated when superseded |
| **Deprecated** | Historically valid; do not use for new work |

Do not reinterpret an Accepted ADR to match new reality. Record a **new** ADR:
prefer **amend** when the core decision still holds; **supersede** when it does
not ([ADR-0021](../docs/adr/0021-amending-accepted-adrs.md)).

## B. Allowed in-place edits (non-semantic maintenance)

On **Accepted**, **Amended**, **Rejected**, or **Superseded** ADRs, these edits are **ALLOWED** only when they do **not** change decision, context, rationale, or consequences:

- Typos, spelling, grammar
- Broken URLs or incorrect links (wrong path or protocol)
- Incorrect file references when intent is unchanged (e.g. `docs/architecture.md` → `docs/architecture/overview.md`)
- Markdown formatting (headings, lists, fences) without meaning change
- Clarifying non-normative text where decision, context, and consequences stay **exactly** the same

**Commit:** `docs(adr):` or `fix(adr):` — not `adr(...)` unless creating, amending, or superseding a decision.

**Forbidden in maintenance commits:** `Status` changes (except amend/supersede link updates in the corresponding `adr(...)` commit), edits to `## Decision`, `## Context`, or `## Consequences` that alter meaning.

## C. Changes that REQUIRE a new ADR (amend or supersede)

Do **not** edit these in-place on Accepted/Amended/Rejected ADRs. Create a **new** ADR instead:

- The decision itself (any change)
- Scope of what the decision applies to
- Context or rationale that would change reader interpretation
- Governing specs, workflow versions, or dependencies that change the basis of the decision
- Broadening or narrowing obligations, constraints, or consequences
- Reinterpreting the ADR to fit new reality without recording a new decision

Choose path:

| Intent | Path |
|--------|------|
| Core decision still holds; additive or clarifying only | **Amend** (§ D) |
| Core decision no longer valid | **Supersede** (§ E) |

## D. Amending pattern

**New ADR must:**

- Contain **only** the additive or clarifying Decision (plus needed context)
- List base ADR(s) under `## Amends`
- Reach **Accepted** when adopted

**Base ADR must (same commit as accepting the amendment, or with the amending `adr(...)` commit):**

- Keep original Decision/Context/Consequences intact (maintenance-only edits afterward)
- Set `Status` to `Amended`
- Set `## Amended by` to the new ADR ID(s)

**Effective architecture:** Amended base **plus** all Accepted amendments in the
`Amended by` chain. Update `docs/adr/INDEX.md` in the amending commit.

## E. Superseding pattern

**New ADR must:**

- State the new decision
- List ADR(s) it supersedes under `## Supersedes`
- Explain why the older ADR is insufficient or incorrect

**Old ADR must (same commit as new ADR, or immediately following `adr(...)` commit):**

- Keep original decision/context/consequences intact (maintenance-only edits afterward)
- Set `Status` to `Superseded`
- Set `Superseded by` to the new ADR

**Active decision:** latest **Accepted** ADR in the supersession chain (or Amended
base + amendments when not superseded). Update `docs/adr/INDEX.md` in the
superseding commit.

## F. Versioning examples

### Downstream project (consumer)

1. ADR-0000: `Adopt A2C workflow v0.1.0` — **Accepted**
2. Project moves to v0.2.0 → new ADR-00NN:
   - decides adoption of v0.2.0
   - `Supersedes: ADR-0000`
   - ADR-0000 → `Status: Superseded`, `Superseded by: ADR-00NN`

### `a2c-workflow` (definition repo)

- ADR-0000 records a **foundational workflow-repo decision** (e.g. establish canonical repository) — **not** `this project uses A2C vX.Y`
- Same immutability and supersession rules apply
- Bumping `VERSION` alone does not require editing ADR-0000; a new ADR is required only when the **foundational decision** changes

## G. AI behavior (mandatory)

- Treat Accepted/Amended/Rejected ADRs as **immutable in substance**
- Perform only **B** maintenance edits when explicitly asked and when edits clearly match B
- If a request would change meaning (**C**): **stop** — propose an **amending** or **superseding** ADR (choose via § C table) or ask for human confirmation; **never** silently rewrite Decision/Context/Consequences
- Preserve amend and supersession chains; never delete or reorder ADR files to "fix" history
- When fixing a broken link in an Accepted/Amended ADR (allowed under B): change the link only; do not revise surrounding rationale