403 lines
9.1 KiB
Markdown
403 lines
9.1 KiB
Markdown
# 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"
|
|
```
|