Codewalkers/docs/archive/session-state.md

# Session State

Session state tracks position, decisions, and blockers across agent restarts. Unlike the Domain Layer (which tracks codebase state), session state tracks **execution state**.

## STATE.md

Every active initiative maintains a STATE.md file tracking execution progress:

```yaml
# STATE.md
initiative: init-abc123
title: User Authentication

# Current Position
position:
  phase: 2
  phase_name: "JWT Implementation"
  plan: 3
  plan_name: "Refresh Token Rotation"
  task: "Implement token rotation endpoint"
  wave: 1
  status: in_progress

# Progress Tracking
progress:
  phases_total: 4
  phases_completed: 1
  current_phase_tasks: 8
  current_phase_completed: 5
  bar: "████████░░░░░░░░ 50%"

# Decisions Made
decisions:
  - date: 2024-01-14
    context: "Token storage strategy"
    decision: "httpOnly cookie, not localStorage"
    reason: "XSS protection, automatic inclusion in requests"

  - date: 2024-01-14
    context: "JWT library"
    decision: "jose over jsonwebtoken"
    reason: "Better TypeScript support, Web Crypto API"

  - date: 2024-01-15
    context: "Refresh token lifetime"
    decision: "7 days"
    reason: "Balance between security and UX"

# Active Blockers
blockers:
  - id: block-001
    description: "Waiting for OAuth credentials from client"
    blocked_since: 2024-01-15
    affects: ["Phase 3: OAuth Integration"]
    workaround: "Proceeding with email/password auth first"

# Session History
sessions:
  - id: session-001
    started: 2024-01-14T09:00:00Z
    ended: 2024-01-14T17:00:00Z
    completed: ["Phase 1: Database Schema", "Phase 2 Tasks 1-3"]

  - id: session-002
    started: 2024-01-15T09:00:00Z
    status: active
    working_on: "Phase 2, Task 4: Refresh token rotation"

# Next Action
next_action: |
  Continue implementing refresh token rotation endpoint.
  After completion, run verification for Phase 2.
  If Phase 2 passes, move to Phase 3 (blocked pending OAuth creds).

# Context for Resume
resume_context:
  files_modified_this_session:
    - src/api/auth/refresh.ts
    - src/middleware/auth.ts
    - db/migrations/002_refresh_tokens.sql

  key_implementations:
    - "Refresh tokens stored in SQLite with expiry"
    - "Rotation creates new token, invalidates old"
    - "Token family tracking for reuse detection"

  open_questions: []
```

---

## State Updates

### When to Update STATE.md

| Event | Update |
|-------|--------|
| Task started | `position.task`, `position.status` |
| Task completed | `progress.*`, `position` to next task |
| Decision made | Add to `decisions` |
| Blocker encountered | Add to `blockers` |
| Blocker resolved | Remove from `blockers` |
| Session start | Add to `sessions` |
| Session end | Update session `ended`, `completed` |
| Phase completed | `progress.phases_completed`, reset task counters |

### Atomic Updates

```typescript
// Update position atomically
await updateState({
  position: {
    phase: 2,
    plan: 3,
    task: "Implement token rotation",
    wave: 1,
    status: "in_progress"
  }
});

// Add decision
await addDecision({
  context: "Token storage",
  decision: "httpOnly cookie",
  reason: "XSS protection"
});

// Record blocker
await addBlocker({
  description: "Waiting for OAuth creds",
  affects: ["Phase 3"]
});
```

---

## Resume Protocol

When resuming work:

### 1. Load STATE.md
```
Read STATE.md for initiative
Extract: position, decisions, blockers, resume_context
```

### 2. Load Relevant Context
```
If position.plan exists:
  Load {phase}-{plan}-PLAN.md
  Load prior SUMMARY.md files for this phase

If position.task exists:
  Find task in current plan
  Resume from that task
```

### 3. Verify State
```
Check files_modified_this_session still exist
Check implementations match key_implementations
If mismatch: flag for review before proceeding
```

### 4. Continue Execution
```
Display: "Resuming from Phase {N}, Plan {M}, Task: {name}"
Display: decisions made (for context)
Display: active blockers (for awareness)
Continue with task execution
```

---

## Decision Tracking

Decisions are first-class citizens, not comments.

### What to Track

| Type | Example | Why Track |
|------|---------|-----------|
| Technology choice | "Using jose for JWT" | Prevents second-guessing |
| Architecture decision | "Separate auth service" | Documents reasoning |
| Trade-off resolution | "Speed over features" | Explains constraints |
| User preference | "Dark mode default" | Preserves intent |
| Constraint discovered | "API rate limited to 100/min" | Prevents repeated discovery |

### Decision Format

```yaml
decisions:
  - date: 2024-01-15
    context: "Where the decision was needed"
    decision: "What was decided"
    reason: "Why this choice"
    alternatives_considered:
      - "Alternative A: rejected because..."
      - "Alternative B: rejected because..."
    reversible: true|false
```

---

## Blocker Management

### Blocker States

```
[new] ──identify──▶ [active] ──resolve──▶ [resolved]
                       │
                       │ workaround
                       ▼
                   [bypassed]
```

### Blocker Format

```yaml
blockers:
  - id: block-001
    status: active
    description: "Need production API keys"
    identified_at: 2024-01-15T10:00:00Z
    affects:
      - "Phase 4: Production deployment"
      - "Phase 5: Monitoring setup"
    blocked_tasks:
      - task-xyz: "Configure production environment"
    workaround: null
    resolution: null

  - id: block-002
    status: bypassed
    description: "Design mockups not ready"
    identified_at: 2024-01-14T09:00:00Z
    affects: ["UI implementation"]
    workaround: "Using placeholder styles, will refine later"
    workaround_tasks:
      - task-abc: "Apply final styles when mockups ready"
```

### Blocker Impact on Execution

1. **Task Blocking:** Task marked `blocked` in tasks table
2. **Phase Blocking:** If all remaining tasks blocked, phase paused
3. **Initiative Blocking:** If all phases blocked, escalate to user

---

## Session History

Track work sessions for debugging and handoffs:

```yaml
sessions:
  - id: session-001
    agent: worker-abc
    started: 2024-01-14T09:00:00Z
    ended: 2024-01-14T12:30:00Z
    context_usage: "45%"
    completed:
      - "Phase 1, Plan 1: Database setup"
      - "Phase 1, Plan 2: User model"
    notes: "Clean execution, no issues"

  - id: session-002
    agent: worker-def
    started: 2024-01-14T13:00:00Z
    ended: 2024-01-14T17:00:00Z
    context_usage: "62%"
    completed:
      - "Phase 1, Plan 3: Auth endpoints"
    issues:
      - "Context exceeded 50%, quality may have degraded"
      - "Encountered blocker: missing env vars"
    handoff_reason: "Context limit reached"
```

---

## Storage Options

### SQLite (Recommended for Codewalk)

```sql
CREATE TABLE initiative_state (
  initiative_id TEXT PRIMARY KEY REFERENCES initiatives(id),
  current_phase INTEGER,
  current_plan INTEGER,
  current_task TEXT,
  current_wave INTEGER,
  status TEXT,
  progress_json TEXT,
  updated_at INTEGER
);

CREATE TABLE initiative_decisions (
  id TEXT PRIMARY KEY,
  initiative_id TEXT REFERENCES initiatives(id),
  date INTEGER,
  context TEXT,
  decision TEXT,
  reason TEXT,
  alternatives_json TEXT,
  reversible BOOLEAN
);

CREATE TABLE initiative_blockers (
  id TEXT PRIMARY KEY,
  initiative_id TEXT REFERENCES initiatives(id),
  status TEXT CHECK (status IN ('active', 'bypassed', 'resolved')),
  description TEXT,
  identified_at INTEGER,
  affects_json TEXT,
  workaround TEXT,
  resolution TEXT,
  resolved_at INTEGER
);

CREATE TABLE session_history (
  id TEXT PRIMARY KEY,
  initiative_id TEXT REFERENCES initiatives(id),
  agent_id TEXT,
  started_at INTEGER,
  ended_at INTEGER,
  context_usage REAL,
  completed_json TEXT,
  issues_json TEXT,
  handoff_reason TEXT
);
```

### File-Based (Alternative)

```
.planning/
├── STATE.md                    # Current state
├── decisions/
│   └── 2024-01-15-jwt-library.md
├── blockers/
│   └── block-001-oauth-creds.md
└── sessions/
    ├── session-001.md
    └── session-002.md
```

---

## Integration with Agents

### Worker
- Reads STATE.md at start
- Updates position on task transitions
- Adds deviations to session notes
- Updates progress counters

### Architect
- Creates initial STATE.md when planning
- Sets up phase/plan structure
- Documents initial decisions

### Orchestrator
- Monitors blocker status
- Triggers resume when blockers resolve
- Coordinates session handoffs

### Verifier
- Reads decisions for verification context
- Updates state with verification results
- Flags issues for resolution

---

## Example: Resume After Crash

```
1. Agent crashes mid-task

2. Supervisor detects stale assignment
   - Task assigned_at > 30min ago
   - No progress updates

3. Supervisor resets task
   - Status back to 'open'
   - Clear assigned_to

4. New agent picks up task
   - Reads STATE.md
   - Sees: "Last working on: Refresh token rotation"
   - Loads relevant PLAN.md
   - Resumes execution

5. STATE.md shows continuity
   sessions:
     - id: session-003
       status: crashed
       notes: "Agent unresponsive, task reset"
     - id: session-004
       status: active
       notes: "Resuming from session-003 crash"
```