Merge pull request #1966 from fullsend-ai/docs/adr-minor-updates-policy

docs: allow minor annotations on accepted ADRs

Author: ralphbean

AGENTS.md

@@ -30,8 +30,8 @@ All git forge operations (GitHub API calls, PR comments, issue creation, workflo
 
 These rules apply whenever you touch `docs/ADRs/` or review a PR that does. Full authoring guidance is in [`skills/writing-adrs/SKILL.md`](skills/writing-adrs/SKILL.md); invoke that skill when writing a new ADR.
 
-**Immutability:** Once an ADR on `main` has status **Accepted**, its Context, Decision, and Consequences sections are frozen. Do not add post-decision notes, rewrite rationale, or edit consequences in place. When circumstances change, write a **new** ADR that supersedes the old one. The only acceptable edits to an Accepted ADR on `main` are status changes (e.g., to Deprecated or Superseded) and links to the superseding ADR. Typos and broken links are narrow exceptions — call them out in the PR description.
+**Immutability:** Once an ADR on `main` has status **Accepted**, it is a point-in-time record. Do not substantially rewrite its Context, Decision, or Consequences sections. When circumstances change, write a **new** ADR that supersedes the old one. Minor annotations are welcome: cross-references to related ADRs, short notes linking to newer decisions, typo and broken-link fixes, and status changes (e.g., to Deprecated or Superseded). Call out any edits to accepted ADRs in the PR description.
 
 **New ADRs in pull requests:** Approval happens at **merge**, not when the branch is created. If the decision is made, set status to **Accepted** in the ADR you are proposing (not **Proposed** merely because the PR is open). Use **Proposed** or **Undecided** only when the decision itself is still unsettled. When status is Accepted, update `docs/architecture.md` and related problem docs in the same PR per the writing-adrs skill.
 
-**When reviewing PRs:** Flag in-place edits to Context, Decision, or Consequences on Accepted ADRs already on `main` as a policy violation. Allow status-only updates and supersession links. For brand-new ADR files on the PR branch, evaluate whether the recorded decision matches the diff — do not treat **Accepted** on a new file as a mistake if the ADR is ready for human review at merge.
+**When reviewing PRs:** Flag substantial rewrites to Context, Decision, or Consequences on Accepted ADRs already on `main` as a policy violation. Allow minor annotations (cross-references, short notes, typo fixes), status updates, and supersession links. For brand-new ADR files on the PR branch, evaluate whether the recorded decision matches the diff — do not treat **Accepted** on a new file as a mistake if the ADR is ready for human review at merge.

CONTRIBUTING.md

@@ -81,7 +81,7 @@ This project uses the [Probot DCO app](https://github.com/apps/dco) to enforce s
 - PRs require approval from a [CODEOWNERS](CODEOWNERS) member before merging.
 ## Working with ADRs
 
-ADRs (Architecture Decision Records) are **point-in-time records**. Once accepted, their content is frozen — do not edit the Context, Decision, or Consequences sections. If a decision needs to change, write a new ADR that supersedes the old one. See the [ADR template](docs/ADRs/0000-adr-template.md) and [ADR 0001](docs/ADRs/0001-use-adrs-for-decision-making.md) for full details.
+ADRs (Architecture Decision Records) are **point-in-time records**. Once accepted, do not substantially rewrite their Context, Decision, or Consequences sections — if a decision needs to change, write a new ADR that supersedes the old one. Minor annotations are welcome: cross-references to related ADRs, short notes linking to newer decisions, and typo fixes. See the [ADR template](docs/ADRs/0000-adr-template.md) and [ADR 0001](docs/ADRs/0001-use-adrs-for-decision-making.md) for full details.
 
 ### ADR numbering
 

docs/ADRs/0000-adr-template.md

@@ -15,10 +15,12 @@ Date: YYYY-MM-DD
 
 {Accepted | Deprecated | Superseded}
 
-<!-- Once this ADR is Accepted, its content is frozen. Do not edit the Context,
-     Decision, or Consequences sections. If circumstances change, write a new
-     ADR that supersedes this one. Only status changes and links to superseding
-     ADRs should be added after acceptance. -->
+<!-- ADRs are point-in-time records, but not fully frozen after acceptance.
+     Minor annotations are welcome: cross-references to related ADRs, short
+     notes linking to newer decisions, or clarifying remarks. However, do not
+     substantially rewrite the Context, Decision, or Consequences sections. If
+     the decision itself needs to change, write a new ADR that supersedes this
+     one. For evolving design narrative, use docs/architecture.md. -->
 
 ## Context
 

docs/architecture.md

@@ -4,8 +4,8 @@ What are the components of the agent execution stack?
 
 > **This is a living document.** It must always reflect the current state of
 > architectural decisions. When an ADR is accepted (or superseded), this
-> document is updated to match. ADRs are point-in-time records and are not
-> modified after acceptance; this document is where the *current* truth lives.
+> document is updated to match. ADRs are point-in-time records that may receive minor annotations
+> but are not substantially rewritten; this document is where the *current* truth lives.
 > A reader should be able to understand the system's architecture from this
 > document alone, without tracing a chain of ADRs.
 

skills/renumber-adr/SKILL.md

@@ -128,4 +128,4 @@ After all renames and reference updates:
   collides, renumber all of them before updating references (so cross-references
   among the new ADRs are correct).
 - **Do not modify ADR content** beyond the number in the title and heading.
-  ADR content is immutable once accepted; this skill only fixes numbering.
+  Substantial ADR content is not rewritten once accepted; this skill only fixes numbering.

skills/writing-adrs/SKILL.md

@@ -12,29 +12,38 @@ description: >-
 
 An ADR records exactly **one** decision. Problem docs explore; ADRs decide.
 `docs/architecture.md` and problem docs are the current state (mutable). ADRs
-are point-in-time records (immutable once accepted).
+are point-in-time records that can receive minor annotations but should not be
+substantially rewritten.
 
-### ADRs are immutable records
+### ADRs are point-in-time records, not evolving documents
 
-Once an ADR is accepted, its content is frozen. It captures the decision, the
-context that existed at that time, and the consequences as understood then. When
-new information arrives or circumstances change, write a **new** ADR that
-supersedes the old one -- do not edit the original's Context, Decision, or
-Consequences sections.
+An ADR captures a decision and the context that existed when it was made. It is
+not a living design document -- that role belongs to `docs/architecture.md`.
+
+That said, accepted ADRs are **not 100% frozen**. Minor annotations after the
+fact are welcome and encouraged:
 
 **Acceptable modifications to an accepted ADR:**
 
 - Changing its `status` (e.g., from Accepted to Deprecated or Superseded)
-- Adding a link or note pointing to a newer ADR that supersedes it
+- Adding cross-reference links to related or superseding ADRs
+- Adding short notes that connect the ADR to newer decisions or clarifications
+- Fixing typos, broken links, or formatting
+
+These annotations keep ADRs useful as navigational aids rather than dead-end
+documents. When a reader lands on an older ADR, links to subsequent decisions
+help them find the current state of thinking.
 
-**Not acceptable:**
+**Not acceptable -- write a new ADR instead:**
 
-- Rewriting the Context to reflect updated understanding
+- Substantially rewriting Context to reflect updated understanding
 - Editing the Decision to match a revised approach
 - Modifying Consequences based on what actually happened
+- Turning the ADR into a running log of how the decision evolved
 
-If a decision turned out to be wrong, that is exactly what supersession is for.
-The original ADR remains as a historical record of what was decided and why.
+If a decision turned out to be wrong, that is what supersession is for. The
+original ADR remains as a historical record of what was decided and why. For
+ongoing design narrative, use `docs/architecture.md`.
 
 ### docs/architecture.md is always current
 
@@ -191,8 +200,10 @@ If the ADR partially answers a question, add a parenthetical:
 - You're rewriting a section of architecture.md -- make a surgical edit instead
 - `relates_to` lists more than 3 problem docs -- the decision may be too broad
 - You didn't run `make lint` -- stop and run it
-- You're editing the Context, Decision, or Consequences of an accepted ADR --
-  write a new superseding ADR instead
+- You're substantially rewriting the Context, Decision, or Consequences of an
+  accepted ADR -- write a new superseding ADR instead
+- You're turning an old ADR into a running changelog -- use
+  `docs/architecture.md` for evolving design narrative
 
 ## Common Mistakes
 
@@ -205,6 +216,8 @@ If the ADR partially answers a question, add a parenthetical:
 | Rewriting existing doc sections | Make surgical additions only |
 | Skipping linters | Run `make lint` before committing |
 | Wrong ADR number | Check existing files in `docs/ADRs/` first |
-| Editing an accepted ADR's content | Write a new ADR that supersedes it |
+| Substantially rewriting an accepted ADR | Write a new ADR that supersedes it |
+| Omitting cross-references to related ADRs | Link older ADRs to newer related decisions |
+| Treating old ADRs as evolving design docs | Use `docs/architecture.md` for living narrative |
 | Forgetting to update architecture.md | It must always reflect current decisions |
 | Leading zeros in title number | Use `"1. Title"` not `"0001. Title"` — zero-padded numbers are only for filenames |