# Grid State Templates

This directory contains templates for the `.grid/` state persistence system.

## Template Files

### Core State Files

| File | Purpose | Updated By | Update Frequency |
|------|---------|------------|------------------|
| `STATE.md` | Central state tracking | MC | Every wave |
| `WARMTH.md` | Institutional knowledge | MC | After each block |
| `SCRATCHPAD.md` | Live discoveries | Executors | During execution |
| `DECISIONS.md` | User decision log | MC | On user decision |
| `BLOCKERS.md` | Blocker tracking | MC/Executors | On blocker encountered |
| `CHECKPOINT.md` | Interrupted thread state | Executor | On checkpoint/interrupt |
| `config.json` | Grid configuration | User/MC | On config change |
| `BLOCK-SUMMARY.md` | Completed block record | Executor | On block complete |

## Directory Structure

When `/grid:init` runs, it creates this structure:

```
.grid/
├── STATE.md                    # Central state (read first on resume)
├── WARMTH.md                   # Accumulated institutional knowledge
├── SCRATCHPAD.md               # Live discoveries
├── DECISIONS.md                # User decisions log
├── BLOCKERS.md                 # Active and resolved blockers
├── config.json                 # Grid configuration
│
├── plans/                      # Execution plans
│   ├── {cluster}-PLAN-SUMMARY.md
│   ├── {cluster}-block-01.md
│   └── ...
│
├── phases/                     # Execution artifacts
│   ├── 01-{phase-name}/
│   │   ├── 01-PLAN.md
│   │   └── 01-SUMMARY.md
│   └── ...
│
├── discs/                      # Identity Discs for Programs
│   └── {program-id}.md
│
├── debug/                      # Debug session state
│   └── {timestamp}-{slug}/
│
└── refinement/                 # Refinement swarm outputs
    ├── screenshots/
    ├── e2e/
    └── personas/
```

## Usage

### Initialize New Project

```bash
/grid:init
```

Creates `.grid/` with all templates initialized.

### Resume Interrupted Mission

```bash
/grid:resume
```

Reads STATE.md, validates consistency, reconstructs context, and continues execution.

## State Lifecycle

### 1. Initialize
- STATUS: `initialized`
- FILES: STATE.md, WARMTH.md, SCRATCHPAD.md, config.json

### 2. Mission Start
- STATUS: `active`
- FILES: Plans written to `.grid/plans/`

### 3. Block Execution
- STATUS: `active`
- FILES: SCRATCHPAD.md updated during work

### 4. Block Complete
- STATUS: `active`
- FILES: SUMMARY.md written to `.grid/phases/`
- WARMTH.md aggregated

### 5. Checkpoint Hit
- STATUS: `checkpoint`
- FILES: CHECKPOINT.md written with thread state

### 6. Session Death
- STATUS: `interrupted` (if checkpoint written) or `active` (stale)
- FILES: CHECKPOINT.md may or may not exist

### 7. Resume
- STATUS: `active`
- FILES: CHECKPOINT.md archived or deleted
- Context reconstructed from all state files

### 8. Mission Complete
- STATUS: `completed`
- FILES: Final SUMMARY.md written
- WARMTH.md finalized

## State Validation

Before resume, the system validates:

1. **Commits exist** - All claimed commit hashes exist 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

## Persistence Guarantees

After initialization, The Grid guarantees:

1. **State survives session death** - All progress recorded in files
2. **Warmth accumulates** - Knowledge transfers across Programs
3. **Decisions persist** - User choices never need repeating
4. **Commits are verified** - Git hashes enable state validation
5. **Plans are preserved** - Full execution plans available for resume

## Related Commands

- `/grid` - Begin a mission (auto-initializes if needed)
- `/grid:init` - Initialize .grid/ structure
- `/grid:resume` - Resume interrupted mission
- `/grid:status` - Display current state

End of Line.