# Changelog guide (docs/history/CHANGELOG.md)

Truth document. Baseline scaffold, created if missing by the `maintenance` agent's baseline. It explains the changelog folder beside it and is never appended to: an entry is found by listing `docs/history/changelog/`, and each entry's first line is its one-line summary, so a row per entry here would be a second copy of that line that someone has to keep in step. The guide is rewritten only when the changelog's rules change.

```markdown
---
type: changelog-guide
description: "How {Project Name}'s changelog works: one entry per unit of work under changelog/, what each entry records, when one is owed, and how to read the folder."
---

# Changelog

**Goal:** what changed in {Project Name}, and how it was refined, one entry per unit of work.

## Entries

- **Location:** `changelog/YYYY-MM-DD-{three-words}.md`, one file per unit of work; the three words name the work, not the commit.
- **Summary line:** each entry opens `# {date} · {surface} — {one-line outcome}`, the line a reader scans.
- **Content:** the ask in the user's words, what was rejected, which skills held, what changed and what running it taught (the `documentation` skill's `templates/changelog-entry.md`).
- **Lifecycle:** a draft until its commit; frozen from then on. A correction is a new entry that links back.

## Owed entries

- **Plan completion:** a draft entry, written when the plan reaches `Status: Complete`.
- **Commit:** every non-exempt commit carries its entry inside it (the closed exemption list is the `documentation` skill's `templates/changelog-entry.md`).

## Reading the changelog

- **Newest first:** `ls -r changelog/`
- **One line per entry:** `grep -m1 -H '^# ' changelog/*.md`
- **One surface:** `grep -l '· {surface} —' changelog/*.md`
- **Distilled lessons:** the `retro` agent turns accumulated entries into a punch list on demand.
```