# ADR-018: History lives in the changelog, never inside living documents

| | |
| --- | --- |
| **Status** | Accepted; the `changes/` fragments mechanism it mentioned was removed on 2026-08-02 - one path at every profile, `## Unreleased` in `CHANGELOG.md`. The decision (one accumulating history; living documents carry no change-log section) stands unchanged |
| **Date** | 2026-07-29 |
| **Author** | Łukasz Bodurka |
| **Tags** | documentation, changelog, specs |

## Context

The standard already has a changelog process with two outputs - the complete
technical `CHANGELOG.md` and the curated stakeholder `RELEASE-NOTES.md` - fed
from one source. In the field a second, unplanned history channel appeared:
capability specs growing their own `## Change log` sections, one dated entry per
change, partly to satisfy the coupling guard's "touch the spec" demand on changes
with no behavioral delta (dependency bumps matched by broad capability globs).
The result reads badly and is structurally wrong: the spec - a living document
whose whole contract is "the current version is the truth, git is the history"
(R4) - starts duplicating git and the changelog, grows without bound, and buries
the actual behavior under bookkeeping.

## Options considered

- **Per-document change-log sections** - history next to the content it touched.
  Rejected: duplicates git and the changelog, drifts from both, bloats every
  living document, and gives a reader three competing histories.
- **Git only** - no curated history at all. Rejected: the changelog process
  exists precisely because two audiences (engineer, stakeholder) need curated
  views git does not give them.
- **One history home: the changelog process** - living documents describe the
  present only; every change event is recorded once, in the changelog source
  (Unreleased section, or `changes/` fragments at scale), assembled into the two
  outputs at release.

## Decision

We will keep exactly one accumulating history: the changelog process. A living
document - a spec, ARCHITECTURE, a runbook - describes the present and MUST NOT
carry a `## Change log` / `## History` section; git holds every past state, and
the changelog holds the curated record (technical and stakeholder). R4 in
`standard/SPEC.md` now states this. Two supporting rules keep the guard honest:
capability-map globs bind behavior-bearing source and SHOULD NOT match dependency
manifests or lockfiles (a version bump is not a behavior change), and when the
coupling guard fires on a genuinely behavior-free change the answer is to
reconcile the spec's content or narrow the map - never to append a history note
to the spec.

## Consequences

- Positive: specs stay readable and stay specs; one history, two audiences, no
  drift between three channels; routine dependency updates stop forcing
  ceremonial spec edits.
- Negative / cost we accept: a reader of a spec who wants "what changed lately"
  must look at git or the changelog - one hop away.
- Follow-ups: repos that accumulated in-spec change-log sections migrate them
  into the changelog and strip the sections; capability maps get narrowed so
  manifests and lockfiles no longer trip the guard.

## Confirmation

Review, plus the structure lint direction: a spec containing a change-log
section fails the spec shape. Until that check ships, `pre-pr-review` and align
flag it.

## Revisit when

A regulated context requires an in-document audit trail that git and the
changelog provably cannot serve, or the changelog process is retired.

## Related

R4, R11, R18 in `standard/SPEC.md`; `standard/docs/changelog-process.md`;
`standard/specs/enforcement.md` (coupling guard, map hygiene); ADR-001
(records policy).