# Milestones

Break projects into numbered milestones (M1, M2, ...). Every milestone completion MUST include:

1. **Verification script** (`scripts/verify-m<N>.sh`) — automated checks confirming all milestone outcomes. Idempotent, non-destructive, returns non-zero on failure. Colour output (green/red) for pass/fail.

2. **Milestone reflection** in `memory/m<N>-reflection.md` — review the **entire conversation** from the start of the milestone (not just the final state) and capture:
   - **Process improvements:** what slowed us down, wrong assumptions, backtracking, what could be automated. What would make this milestone faster if we redid it from scratch?
   - **Key knowledge for reproduction:** critical facts, gotchas, non-obvious config details that someone (or a future Claude session) would need to recreate this milestone reliably. Include version-specific quirks, network/subnet constraints, debugging detours.
   - **Scripts and automation:** existing scripts that proved valuable, new scripts that would condense multi-step manual processes, patterns that could be extracted. Look at the conversation history for command sequences run repeatedly — these are scripting candidates.
   - **Future improvement ideas:** things that surfaced but don't belong in current scope. Add to `FUTURE.md` with the standard Problem/Idea/Open questions/Depends on format.

3. **Updated README.md** — scripts section, milestone table, any new setup steps.

4. **Updated CLAUDE.md** — repo structure, conventions, new patterns discovered. (After the split: this may mean updating a `claude/<topic>.md` detail file rather than the root CLAUDE.md.)

5. **Update affected topic files in `memory/`** (new gotchas, updated status) and the MEMORY.md index.