# `plans/` — how this work remembers itself

The local-AI derived-corpus work spans many phases and months, and **context is cleared
between phases** to keep token cost down. That only works if a cold agent can resume without
re-deriving anything. Seven kinds of artifact, with deliberately different lifetimes:

| File | Lifetime | Contents |
| --- | --- | --- |
| [`../PLAN.md`](../PLAN.md) | Rarely changes | The durable roadmap: why, architecture, all phases, sequencing. |
| [`FACTS.md`](FACTS.md) | Append-only | Verified codebase facts with `file:line` anchors. |
| [`STATE.md`](STATE.md) | Rewritten each session | Phase status, decisions log, open questions, commands known to pass. |
| `phase-N-<slug>.md` | Written at phase start, archived at merge | File-level detail for the phase in flight. |
| `<topic>.md` design docs | Live until the design is fully shipped | A model that spans phases and outlives any one of them: [`unified-operations-model.md`](unified-operations-model.md) (how media-derived work is dispatched — the backend half) and [`editor-operations-ia.md`](editor-operations-ia.md) (what the editor's screens are about — the UI half, nine slices, complete). Read the matching one before touching a dispatcher or a page. |
| `release-N.md` | Written at a release's start; its record grows per slice | One release: rulings, slices, the "as shipped" records, the rollout. Indexed at the end of `../PLAN.md`. |
| `landed-<yyyy-mm>.md` | Written once | Work that reached `main` without a plan of its own: merges and what they landed. |

`FACTS.md` is the most valuable file here. It holds exactly the material that is expensive to
establish and cheap to get wrong — the original draft of this plan contained several
confident, wrong claims about how the build pipeline works, and each one would have cost real
implementation time. The roadmap is stable prose; the ledger grows every time something is
checked against the tree.

## Context-clear protocol

**Before clearing context:**

1. Update `STATE.md` — phase status, decisions made and *why*, anything surprising.
2. Append newly verified facts to `FACTS.md`, each with a `file:line` anchor.
3. **Commit.** An uncommitted memory file does not survive a container reclaim.

**After clearing context:**

`AGENTS.md` arrives automatically (`CLAUDE.md` is just `@AGENTS.md`), and it points here.
Read `STATE.md`, then `FACTS.md`, then the current `phase-N-*.md`. That is the whole warm-up
and it should cost a few thousand tokens rather than a re-exploration.

**Never re-verify something already in `FACTS.md`** unless the surrounding code changed. If a
fact turns out to be stale, correct it in place and note the correction in `STATE.md`.

## Writing a phase plan

Start it when the phase starts, not before — a plan written three phases early is written
against a tree that no longer exists. Keep it to what `PLAN.md` deliberately omits: exact
files, exact edits, the order to make them in, and how to verify. Everything general belongs
in `PLAN.md`; everything verified belongs in `FACTS.md`.

Archive rather than delete on merge — `git mv plans/phase-N-*.md plans/done/` — so the
reasoning behind a shipped phase stays findable.