the-grid-cc 1.7.14 → 1.7.15

package/docs/PERSISTENCE_QUICKSTART.md

@@ -0,0 +1,283 @@
+# 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.