session-statelisted

# Session State > **HARD GATE** — **HARD GATE** — Session state must be synchronized with git state. If state.yaml conflicts with the working tree, halt and ask for clarification. Do NOT assume state is correct. Track the current state of implementation, including decisions made, pending tasks, and open questions, to ensure continuity across session boundaries and prevent "context rot." ## Goal Maintain a single source of truth for the *current* session in `specs/state.yaml`. This complements long-term docs in `specs/tech-architecture/` and delivery detail in `specs/epics/` + `specs/release-plan.yaml`. Legacy markdown (`specs/archive/STATE.md`, `RELEASE-PLAN.md`) is **not** SoT when YAML exists — use `specs/state.yaml` only. ## Handoff block (cold start) When ending a session or before a context-heavy spawn, update `handoff` in `state.yaml`: ```yaml handoff: last_step_completed: "e02s01 verify-work passed" open_decisions: - "Use folder mode for e07 (>5 stories)" required_reading: - CONVENTIONS.md - specs/epics/e02-verification/epic.yaml next_skill: develop-tdd ``` ## Strategic compaction | Trigger | Action | |---------|--------| | Phase transition (Plan → Build → Verify) | Compact handoff; archive verbose decisions to ADR | | Context > 70% estimated | Run terse-mode for status only; move detail to specs/ | | Before `dispatch-agents` wave | `state.yaml` only channel between spawns | ## Workflow ### 1. Initialize (Session Start) If `specs/state.