Record a milestone

A git log says what changed. It rarely says why the change was worth making, and never says which areas moved together. Six months later that is what somebody needs — usually while deciding whether they are allowed to undo it.

When to write one

For a change big enough that a newcomer would ask "why is this part like that?"

• a migration — a database, an auth model, a framework
• a rewrite of a module, or a service split in two
• a design reversal: something was done one way, then deliberately undone

Roughly a handful a year on an active repository. If you are writing one a week, they are commits, not milestones, and the file stops being readable.

When not to

• A task, or something in progress. That is STATE.md, or a session record.
• A single decision with no structural change. That is /chamnan:remember → .chamnan/memory/decisions/.
• A repeated procedure. That is /chamnan:capture.
• Anything with a status, an owner, or a due date. This is not project management, and adding those fields would quietly turn it into a worse version of a tool you already have.

Where it goes

.chamnan/milestones.md

One file, and entries are appended at the end. Newest last is deliberate: appending keeps every diff to added lines, where prepending would rewrite the context of the whole file each time.

The format

## 2026-08-20 — Authentication migration

**Why:** sessions dropped under load; the old design held state per node.
**Affected:** auth module, API layer
**Decisions:** short-lived tokens; the old endpoint stays for one release

Four parts, and the middle two carry the value:

Leave out a field rather than filling it with a dash.

Write the why as the problem, not the activity. "Migrated to short-lived tokens" is the diff restated; "sessions dropped under load because the old design held state per node" is the reason, and it is the half that stops somebody re-treading it.

What reaches a session

Only the two most recent titles, with their dates. The bodies stay in the file, and the agent reads it when a title looks relevant. So a repository with forty milestones costs the same per session as one with two.

What not to put in it

• No credentials, hostnames or connection strings. This file is committed. The session-start hook redacts what it injects; that does not clean the file on disk.
• No incident write-ups. Name the failure in one clause; a post-mortem belongs in docs/.

Housekeeping

Not pruned by age, on purpose — the oldest entry is usually the one nobody can reconstruct. Because only titles are injected, length costs nothing per session. Edit an entry if it turns out to be wrong; a false milestone is worse than a missing one.

Set "milestones": false in .chamnan/config.json to switch it off.