Windsurf rules

1---
2name: session-state
3model: haiku
4description: "Track implementation decisions and progress in specs/state.yaml to prevent context rot. Use at the start of a session to load context, and whenever a significant decision is made or a milestone is reached."
5---
6 
7# story: e45s23
8 
9# Session State
10> **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.
11 
12 
13Track the current state of implementation, including decisions made, pending tasks, and open questions, to ensure continuity across session boundaries and prevent "context rot."
14 
15Session-state implements the **isolate** strategy from the context-engineering framework (docs/references/context-engineering.md): each agent gets exactly the context it needs — no more — by recording decisions so the next agent can cold-start without replaying history. The four strategies (write, select, compress, isolate) work together: session-state handles isolation, terse-mode handles compression, survey-context handles selection, and CONVENTIONS.md ensures token-efficient writing.
16 
17## Goal
18 
19Maintain 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`.
20 
21Legacy markdown (`specs/archive/STATE.md`, `RELEASE-PLAN.md`) is **not** SoT when YAML exists — use `specs/state.yaml` only.
22 
23When a story modifies existing behavior, patch only between matching marker pairs in `CLAUDE.md` / `AGENTS.md` `learned-preferences` fence — see e45s21.
24 
25## Handoff block (cold start)
26 
27When ending a session or before a context-heavy spawn, update `handoff` in `state.yaml`:
28 
29```yaml
30handoff:
31  last_step_completed: "e02s01 verify-work passed"
32  open_decisions:
33    - "Use folder mode for e07 (>5 stories)"
34  required_reading:
35    - CONVENTIONS.md
36    - specs/epics/e02-verification/epic.yaml
37  next_skill: develop-tdd
38```
39 
40## Strategic compaction
41 
42| Trigger | Action |
43|---------|--------|
44| Phase transition (Plan → Build → Verify) | Compact handoff; archive verbose decisions to ADR |
45| Context > 70% estimated | Run terse-mode for status only; move detail to specs/ |
46| Before `dispatch-agents` wave | `state.yaml` only channel between spawns |
47 
48## Workflow
49 
50### 1. Initialize (Session Start)
51 
52If `specs/state.yaml` does not exist, or if starting a new major phase:
53 
54- [ ] Read `specs/release-plan.yaml` and `specs/product/SCOPE_LATEST.yaml`.
55- [ ] Get git metadata: `git branch --show-current` and `git rev-parse --short HEAD`.
56- [ ] Create `specs/state.yaml` with active flow, git, handoff, and epic cycle if in build.
57 
58### 2. Load (Context Refresh)
59 
60When starting a new session or after a significant context flush:
61 
62- [ ] Read `specs/state.yaml` to understand where the previous agent left off.
63- [ ] Read `specs/execution-status.yaml` for story progress (do not infer from release-plan).
64- [ ] Verify git matches `state.yaml` `git.branch` / `git.hash`.
65 
66### 3. Update (Decision Point/Milestone)
67 
68Whenever a significant decision is made or a milestone is reached:
69 
70- [ ] Patch via `bash scripts/bp-yaml-set.sh specs/state.yaml git.hash <hash>` (or edit directly).
71- [ ] Patch `handoff` and `learned_preferences` / `workspace_facts` in `CLAUDE.md` fenced block when durable user preferences or repo facts crystallize (e45s23).
72- [ ] Update `handoff.open_decisions` with rationale.
73- [ ] Update `epic_cycle` when advancing `ship-epic` steps.
74- [ ] Record open questions under `handoff.open_decisions` or an ADR.
75 
76→ verify: `bash scripts/validate-specs-yaml.sh`
77 
78## Universal checkpoint pattern
79 
80Every multi-step flow (>3 steps) in bigpowers uses a cycle counter in `state.yaml`:
81 
82| Flow | Cycle key | Step field | Phases/Steps |
83|------|-----------|------------|-------------|
84| build-epic | `epic_cycle` | `current_step` | 8 (survey → release) |
85| fix-bug | `bug_cycle` | `current_step` | 5 (investigate → release) |
86| orchestrate-project | `project_cycle` | `current_phase` | 6 (discover → release) |
87 
88**Checkpoint:** After each step/phase completes, increment the counter in `state.yaml` and update `handoff.next_skill`.
89 
90**Resume:** On session start, read the current step/phase from the cycle key — continue from there, not from step 1.
91 
92**Completed steps:** Track completed steps in `completed_steps` (comma-separated string) for audit trail.
93 
94## Strategic compaction
95 
96Print the current session state: `cat specs/state.yaml`, then display `active_flow` and `handoff.next_skill` for quick reference.
97 
98### reset-state (absorbed)
99 
100Clear ephemeral session state. Set `active_epic_id`, `active_story_id`, and `epic_cycle.current_step` to `null` in `specs/state.yaml`. Use when ending a phase or starting a new project context.
101 
102### compact-state (absorbed)
103 
104Archive verbose decisions before a context transition. Move all entries from `handoff.open_decisions` to their appropriate location:
105 
106- **System-wide decisions** → `specs/adr/NNNN-slug.md` (global Architectural Decision Records)
107- **Epic-scoped decisions** → `specs/epics/<active_epic_id>-<slug>/adr/NNNN-slug.md` (epic-local ADRs, archived with epic)
108 
109After archiving, reset `handoff.open_decisions` to an empty list.
110 
111## File Format: specs/state.yaml
112 
113```yaml
114active_flow: build_epic       # planning | build_epic | fix_bug
115active_epic_id: e02
116active_story_id: e02s01       # required when epic mode: folder
117active_bug_id: null           # BUG-2026-06-01T143022 when fix_bug
118release:
119  target_version: null         # NOT tracked manually — semantic-release decides at merge
120  last_tag: v2.28.0            # mirror of `gh release view`, reference only
121  last_publish: null
122epic_cycle:
123  current_step: develop-tdd
124  next_skill: develop-tdd
125  completed_steps: [kickoff-branch]
126bug_cycle:
127  current_step: null
128  completed_steps: []
129git:
130  branch: feat/e02-verify
131  hash: abc1234
132handoff:
133  last_step_completed: null
134  open_decisions: []
135  next_skill: survey-context
136```
137 
138## Anti-Patterns
139 
140- **Duplicate Plan**: Don't copy `release-plan.yaml` or epic shards into `state.yaml`.
141- **Stale State**: Forgetting to update `state.yaml` after a major refactor or decision.
142- **Status in release-plan**: Story/epic status lives only in `execution-status.yaml`.
143 
144 
145<!-- story: e03s03 -->
146<!-- story: e04s01 -->
147