plan-assistlisted

# plan-assist — layered planning docs Three root docs. **charter.md** = stable directives (DO/DO NOT, invariants, build-order status table, gotchas). **work-plan.md** = current plan + handoff. **log.md** = append-only journal, canonical. Goal: prevent drift. ## INVARIANTS (never break) - **I1.** If charter.md and log.md disagree → **log.md wins**. charter.md only distills it. - **I2.** log.md is **append-only**: never edit/delete old entries; newest at bottom; absolute dates only (resolve "today" to the real date). - **I3.** log.md is a **write-ahead log**: append AND commit a dated entry BEFORE any risky op, not after — so a destructive op can't lose it. (A session once lost its tree on a `mv`; the journal was the only recovery.) ## SESSION CONTRACT — do each, in order 1. **START:** read charter.md → work-plan.md → log.md (skim recent). Always, even if the prompt seems narrow. 2. **ON CHANGE:** edit work-plan.md in the SAME commit as the code change — never let it lag. 3. **BEFORE RISKY OP** (`mv` workdir · `git reset --hard` · force-push · big migration): commit a dated log.md entry FIRST (per I3). 4. **PHASE LANDS:** summarize it into log.md, prune it from work-plan.md (keep < ~250 lines). 5. **STOP MID-TASK:** write a SESSION HANDOFF block atop work-plan.md (shape below). 6. **SESSION END:** append a dated log.md entry (decided/changed · new gotchas · status changes · open questions). 7. **EACH COMMIT + BOUNDARY:** run the HEARTBEAT. Keep live status OUT of charter.md