golem15/msd-core
4
0
Fork 0
Code Issues 1 Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs(#4333): document the ADR Amends/Amended-by convention (#4334)

Browse Source 
* docs(#4333): document the ADR Amends/Amended-by convention

Two patterns for amending an accepted ADR are established practice —
an in-place `## Amendment (YYYY-MM-DD)` section, and a separate ADR
that declares `Amends` with a reciprocal `Amended by` back-link — but
only the first was ever written down. #4030 shows the cost: a
contributor concluded no ADR owned a contract that ADR-857 already
covers, because nothing said the second pattern (used by ADR-1244 and
ADR-2782 to extend ADR-857 itself) existed.

Document both patterns in docs/contributor-standards.md, note the
Amends/Amended-by reciprocity rule in docs/adr/README.md alongside the
existing Supersedes/Subsumes rule (and that it isn't yet gated by
scripts/gen-adr-index.cjs the way those are), and point CONTRIBUTING.md's
new-ADR process at the amendment path for revisiting an existing one.

Closes #4333

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* docs(#4333): fix imprecise Amends/Amended-by precedent citations

Orthogonal review caught two inaccuracies: PR #1643 doesn't match the
in-place dated-section pattern (it rewrites the original Decision text
rather than appending an untouched dated section), and ADR-1244's
relationship to ADR-857 is prose ("extended by"), not the structured
Amends/Amended-by header field. ADR-2782 is the verified precedent for
the structured field pair — its one Amends field names four targets
(857, 894, 1016, 1244), all four carrying the reciprocal back-link.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

---------

Co-authored-by: sim <sim@local>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-09-05 16:45:57 -04:00
committed by GitHub
parent 2f920c5af3
commit 17e163f15c
3 changed files with 29 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/adr/README.md
View File

@@ -80,6 +80,12 @@ If A declares either relation toward B, **B must record the reciprocal.** A one-
Only an `Accepted` ADR is owed the back-link. A `Proposed` ADR's claim is **prospective**: it has not taken effect, so its target is not marked. On ratification, the check begins demanding the back-links.
### 3a. Amendment is symmetric too — but not yet gated
A same-file `## Amendment (YYYY-MM-DD): <topic>` section (see `docs/contributor-standards.md`'s "Amending an accepted ADR") needs no back-link — there is only one file. A **separate** ADR that amends another is the same relation as Supersedes/Subsumes and follows the same rule: if A declares `**Amends:** [ADR-B]`, B **must** carry the reciprocal `**Amended by:** [ADR-A]` in the same PR. [ADR-2782](2782-reviewer-lane-capability-surface.md)'s single `Amends` field names four targets — [ADR-857](857-capability-system.md), [ADR-894](894-capability-declaration-format.md), [ADR-1016](1016-runtime-capability-descriptor.md), [ADR-1244](1244-capability-ecosystem.md) — and all four carry the reciprocal `Amended by` back-link.
Unlike `Supersedes`/`Subsumes`, this is not yet enforced by `scripts/gen-adr-index.cjs` — `relationSections()` only recognizes `## Supersedes` / `## Subsumes` headings, and the header-field parity check does not walk `Amends`. Get the back-link right by review until that gap closes.
### 4. The declared id matches the filename
An H1 of `# ADR-0175: …` in a file named `218-*.md` is a rename that never finished. The id in the title must match the filename's prefix.