# ADR-001 — One file per change, distributed IDs, generated CHANGELOG

**Status:** accepted · **Date:** 2026-10-13 · **Deciders:** RG

*Ported from YoutubeManager (same decision, proven there since 2026-09-24).*

## Context

A changelog as one Markdown file with entries appended at the bottom and IDs assigned by
"read the last ID and add one" collides the moment two people (or two AI sessions) work in
parallel: both pick the same next ID, both edit the same last lines, every merge conflicts.
Renumbering after merge breaks the commit messages that already reference the ID. An Excel file
was considered: it is binary, cannot be diffed, merged or blamed, and an AI agent cannot safely
edit it.

## Decision

1. **One file per change** in `RULEFOLDER/changes/`. Two people never touch the same file.
   This is the pattern used by towncrier, GitLab (`changelogs/unreleased/`), Kubernetes and the
   `changesets` tool in the JavaScript world.
2. **The ID is derived, not counted**: `CHG-YYYYMMDD-DEV-NN`, where `DEV` is the developer code
   from `TEAM.md` and `NN` is that developer's sequence for that day. Uniqueness needs no
   coordination and no network. The ID also tells you when and by whom.
3. **Front matter** (YAML subset) makes each file machine-readable: type, scope, files, routes,
   API endpoints, security impact, tests. Free text follows in fixed sections.
4. **`CHANGELOG.md` is generated** by `tools/build_changelog.py` from the fragments. It is
   committed so that reviewers and non-developers can read one file, but it is never hand-edited;
   a merge conflict in it is resolved by re-running the generator.
5. **Excel/CSV is an export** (`build_changelog.py --csv`), never a source.

## Consequences

- Positive: zero ID collisions; zero changelog merge conflicts; the log is queryable; tooling can
  enforce presence of a fragment per commit; the format is portable to any project (this port is
  the proof).
- Negative: two steps instead of one (create fragment, then build).
- Ordering: fragments sort by date then ID; if exact order matters, the commit history has it.