# Grid Persistence - Quick Start Guide

**Version:** 1.0
**Status:** Ready for Implementation

This guide provides a quick overview of Grid's persistence system.

## What is Grid Persistence?

Grid Persistence allows missions to survive session death. When your session ends unexpectedly (context exhaustion, timeout, disconnect), all state is preserved in `.grid/` files. A fresh Master Control can resume exactly where you left off.

## Core Concepts

### State Files

| File | Purpose | When Written |
|------|---------|--------------|
| `STATE.md` | Central position tracking | Every wave |
| `WARMTH.md` | Accumulated knowledge | After each block |
| `CHECKPOINT.md` | Interrupted thread state | On checkpoint/interrupt |
| `SCRATCHPAD.md` | Live discoveries | During execution |
| `DECISIONS.md` | User decisions | When user decides |
| `BLOCKERS.md` | Issues blocking progress | When blocker encountered |

### Directory Structure

```
.grid/
├── STATE.md                    # Read this first on resume
├── WARMTH.md                   # Knowledge accumulation
├── SCRATCHPAD.md               # Live discoveries
├── DECISIONS.md                # User decisions
├── BLOCKERS.md                 # Active blockers
├── config.json                 # Grid configuration
│
├── plans/                      # Execution plans
├── phases/                     # Completed work
├── discs/                      # Program Identity Discs
├── debug/                      # Debug sessions
└── refinement/                 # Refinement outputs
```

## Commands

### Initialize State

```bash
/grid:init
```

Creates the `.grid/` directory with all state files.

### Resume Mission

```bash
/grid:resume              # Auto-detect and resume
/grid:resume --validate   # Validate state only
/grid:resume --from block-02  # Resume from specific block
```

Reconstructs context from `.grid/` files and continues execution.

### Check Status

```bash
/grid:status
```

Shows current mission state and progress.

## How It Works

### 1. During Execution

- **Master Control** updates STATE.md after each wave
- **Executors** write to SCRATCHPAD.md during work
- **Executors** write SUMMARY.md after each block
- **Master Control** aggregates WARMTH.md after each block

### 2. On Checkpoint

When execution hits a checkpoint (human verification, decision point, etc.):

1. Executor writes CHECKPOINT.md with current thread state
2. MC updates STATE.md status to "checkpoint"
3. System waits for user response

### 3. On Session Death

If session dies unexpectedly:

1. Last STATE.md update shows position
2. SCRATCHPAD.md shows last activity
3. Git history shows last commits
4. Resume reconstructs state from these

### 4. On Resume

```
/grid:resume

1. Read STATE.md
2. Validate state consistency
3. Load WARMTH.md, DECISIONS.md, CHECKPOINT.md
4. Collect all SUMMARY.md files
5. Build execution context
6. Spawn continuation with full context
```

## Resume Scenarios

### Scenario 1: Clean Checkpoint

**State:** User approved checkpoint, session ended normally

```
STATUS: checkpoint
CHECKPOINT.md: exists with user_response
```

**Action:** Continue from next thread after checkpoint

### Scenario 2: Session Death

**State:** Session died mid-execution

```
STATUS: active (stale timestamp)
CHECKPOINT.md: may not exist
SCRATCHPAD.md: recent entries
```

**Action:** Reconstruct from scratchpad + git, resume from last known point

### Scenario 3: Failure

**State:** Executor failed with error

```
STATUS: failed
CHECKPOINT.md: type: failure with details
```

**Action:** Present failure report, offer rollback/retry/manual options

## Warmth Accumulation

Warmth is institutional knowledge that survives across sessions:

```yaml
# WARMTH.md
codebase_patterns:
  - "This project uses Astro content collections"
  - "Dark mode uses class strategy with localStorage"

gotchas:
  - "Astro config must use .mjs extension for ESM"
  - "Shiki syntax highlighting is build-time only"

user_preferences:
  - "User prefers minimal dependencies"
  - "User wants dark mode as default"

decisions_made:
  - "Chose serverless adapter for future flexibility"

almost_did:
  - "Considered MDX but stuck with plain MD"
```

When resuming, this warmth is injected into the continuation executor so it:
- Doesn't repeat mistakes
- Applies learned patterns
- Respects user preferences

## State Validation

Before resuming, Grid validates:

1. **Commits exist** - All claimed commit hashes are in git
2. **Files exist** - All claimed artifacts exist on disk
3. **Plans available** - Plans exist for pending blocks
4. **Single checkpoint** - No conflicting checkpoint files
5. **State parseable** - All YAML frontmatter is valid

If validation fails, Grid enters recovery mode and attempts to reconstruct state from git + artifacts.

## Templates

All templates are in: `templates/grid-state/`

- `STATE.md` - Central state template
- `WARMTH.md` - Warmth template
- `SCRATCHPAD.md` - Scratchpad template
- `DECISIONS.md` - Decisions template
- `BLOCKERS.md` - Blockers template
- `CHECKPOINT.md` - Checkpoint template
- `config.json` - Configuration template
- `BLOCK-SUMMARY.md` - Block summary template

## Example Flow

```
1. User: /grid
   MC: Initializes .grid/, starts mission

2. MC spawns Executor for block 01
   Executor: Works on threads, commits, writes SCRATCHPAD.md

3. Executor completes block 01
   Executor: Writes SUMMARY.md with commits and lessons_learned
   MC: Aggregates WARMTH.md from lessons_learned
   MC: Updates STATE.md (block: 2, wave: 1, progress: 16%)

4. Executor hits checkpoint for human verification
   Executor: Writes CHECKPOINT.md (type: human_verify)
   MC: Updates STATE.md (status: checkpoint)
   MC: Waits for user

5. Session dies (context exhaustion)
   STATE.md: status: checkpoint (last write)
   CHECKPOINT.md: awaiting user response

6. New session
   User: /grid:resume
   MC: Reads STATE.md (status: checkpoint)
   MC: Reads CHECKPOINT.md (type: human_verify)
   MC: Loads WARMTH.md (accumulated knowledge)
   MC: Presents checkpoint to user

7. User approves checkpoint
   MC: Updates CHECKPOINT.md (user_response: approved)
   MC: Spawns continuation executor with:
      - Warmth injected
      - Completed threads table
      - Resume point (next thread after checkpoint)

8. Execution continues
   Executor: Picks up from thread after checkpoint
   Executor: Has full context from warmth
   Executor: Doesn't repeat mistakes from prior attempts
```

## Implementation Status

### Completed

- [x] Template files created
- [x] `/grid:resume` added to help
- [x] resume.md spec complete
- [x] init.md enhanced with templates
- [x] PERSISTENCE.md design document
- [x] Documentation complete

### Next Steps

1. **Implement state updates in mc.md**
   - Wave complete handler
   - Block complete handler
   - Checkpoint handler

2. **Implement summary writes in grid-executor.md**
   - Block complete handler
   - lessons_learned section

3. **Complete /grid:resume implementation**
   - State validation logic
   - Context reconstruction logic
   - Continuation spawning logic

4. **Test end-to-end**
   - Full mission with interruption
   - Verify resume works correctly

## Related Documentation

- `/docs/PERSISTENCE.md` - Full technical design
- `/docs/PERSISTENCE_IMPLEMENTATION.md` - Implementation guide
- `/templates/grid-state/README.md` - Template documentation
- `/commands/grid/resume.md` - Resume command spec
- `/commands/grid/init.md` - Init command spec

End of Line.