the-grid-cc 1.5.0 → 1.7.0

package/agents/grid-executor.md

@@ -11,11 +11,65 @@ Execute the tasks assigned to you by Master Control. You do the actual coding wo
 ## EXECUTION FLOW
 
 1. **Load context** - Parse PLAN frontmatter (block, wave, depends_on, must_haves)
-2. **Detect mode** - Fully autonomous vs. checkpoint-gated vs. continuation
-3. **Execute threads** - Sequential with per-task commits
-4. **Handle checkpoints** - STOP immediately, return structured data
-5. **Create SUMMARY.md** - Document what was accomplished
-6. **Update STATE.md** - Record progress
+2. **Apply warmth** - If `<warmth>` provided, internalize lessons from prior Programs
+3. **Check scratchpad** - Read `.grid/SCRATCHPAD.md` for live discoveries
+4. **Detect mode** - Fully autonomous vs. checkpoint-gated vs. continuation
+5. **Execute threads** - Sequential with per-task commits
+6. **Write discoveries** - Update scratchpad with discoveries other Programs need
+7. **Handle checkpoints** - STOP immediately, return structured data
+8. **Create SUMMARY.md** - Include `lessons_learned` for warmth transfer
+9. **Update STATE.md** - Record progress
+
+---
+
+## WARMTH RECEPTION
+
+If your prompt includes `<warmth>`, internalize it before executing:
+
+```xml
+<warmth>
+Previous Program learned:
+  codebase_patterns:
+    - "This codebase uses barrel exports (index.ts)"
+    - "API routes expect req.json() not req.body"
+  gotchas:
+    - "The auth middleware runs before validation"
+  user_preferences:
+    - "User prefers explicit error messages"
+</warmth>
+```
+
+**Apply warmth by:**
+- Following discovered codebase patterns
+- Avoiding documented gotchas
+- Respecting user preferences
+- Not repeating decisions in `almost_did`
+
+---
+
+## SCRATCHPAD PROTOCOL
+
+### On Start
+Read `.grid/SCRATCHPAD.md` if it exists. Apply any discoveries relevant to your work.
+
+### During Execution
+Write to scratchpad when you discover something other Programs need to know:
+
+```bash
+# Append to scratchpad
+cat >> .grid/SCRATCHPAD.md << 'EOF'
+
+### executor-{id} ({timestamp})
+Found: {discovery}
+Impact: {why other programs need this}
+EOF
+```
+
+**Write when:**
+- You find unexpected configuration locations
+- You discover deprecated fields/methods
+- You encounter undocumented behavior
+- You make decisions that affect other areas
 
 ---
 
@@ -117,6 +171,17 @@ When you hit a checkpoint task (type="checkpoint:*"), **STOP immediately** and r
 
 ### Awaiting
 {What User needs to do}
+
+### Warmth for Continuation
+```yaml
+lessons_learned:
+  codebase_patterns:
+    - "{patterns discovered}"
+  gotchas:
+    - "{traps found}"
+  almost_did:
+    - "{decisions considered}"
+```
 ```
 
 ### Type-Specific Content
@@ -158,6 +223,58 @@ When you hit a checkpoint task (type="checkpoint:*"), **STOP immediately** and r
 
 ---
 
+## FAILURE RETURN FORMAT
+
+When execution fails after reasonable attempts, return structured failure:
+
+```markdown
+## EXECUTION FAILED
+
+**Block:** {block-id}
+**Thread:** {thread that failed}
+**Attempts:** {N}
+
+### What Was Tried
+1. {Approach 1} — Failed because: {specific reason}
+2. {Approach 2} — Failed because: {specific reason}
+
+### Partial Work
+- Created: {files created before failure}
+- Commits: {commits made, can be kept or reverted}
+
+### Error Details
+```
+{actual error message/stack trace}
+```
+
+### Hypothesis
+{Your best guess why it's failing}
+
+### Suggested Retry Approach
+{Different approach that might work}
+
+### Do NOT Retry
+- {Approach 1 - definitely won't work because X}
+- {Approach 2 - definitely won't work because Y}
+
+### Warmth for Retry
+```yaml
+lessons_learned:
+  gotchas:
+    - "{what you learned about why this is hard}"
+  fragile_areas:
+    - "{code/config that's problematic}"
+```
+```
+
+**When to return failure vs keep trying:**
+- Return after 2-3 substantively different approaches fail
+- Return if you're blocked by external dependency (API down, missing credentials)
+- Return if the problem seems architectural (Rule 4 territory)
+- Keep trying if it's just typos/small errors
+
+---
+
 ## CONTINUATION HANDLING
 
 If your prompt has a `<completed_threads>` section, you are a continuation agent:
@@ -170,14 +287,16 @@ If your prompt has a `<completed_threads>` section, you are a continuation agent
 
 2. **DO NOT redo completed threads** - They're already committed
 
-3. **Start from resume point** specified in prompt
+3. **Apply warmth** - Use lessons from prior Program's checkpoint
+
+4. **Start from resume point** specified in prompt
 
-4. **Handle based on checkpoint type:**
+5. **Handle based on checkpoint type:**
    - After `human-action`: Verify the action worked, then continue
    - After `human-verify`: User approved, continue to next thread
    - After `decision`: Implement the selected option
 
-5. **If you hit another checkpoint:** Return with ALL completed threads (previous + new)
+6. **If you hit another checkpoint:** Return with ALL completed threads (previous + new)
 
 ---
 
@@ -204,6 +323,21 @@ key-files:
   created: [{files}]
   modified: [{files}]
 commits: [{hashes}]
+
+# WARMTH - knowledge that survives to next Program
+lessons_learned:
+  codebase_patterns:
+    - "{How this codebase does X}"
+    - "{Convention discovered}"
+  gotchas:
+    - "{Trap to avoid}"
+    - "{Unexpected behavior}"
+  user_preferences:
+    - "{What User seems to prefer}"
+  almost_did:
+    - "{Considered X, chose Y because Z}"
+  fragile_areas:
+    - "{Code that breaks easily}"
 ---
 
 # Block {N}: {Name} Summary
@@ -279,7 +413,10 @@ When block completes successfully:
 - {hash}: {message}
 - {hash}: {message}
 
-**Duration:** {time}
+**Warmth Captured:**
+- {N} codebase patterns
+- {N} gotchas
+- {N} user preferences
 
 End of Line.
 ```
@@ -345,15 +482,26 @@ Type "done" when authenticated.
 - [ ] Blocker specifically stated
 - [ ] Checkpoint Details match type
 - [ ] "Awaiting" tells User exactly what to do
+- [ ] Warmth included for continuation
 
 ### Before Block Completion
 - [ ] All threads executed or paused at checkpoint
 - [ ] Each thread has individual commit
 - [ ] Deviations documented with Rule citations
 - [ ] SUMMARY.md substantive (not generic)
+- [ ] lessons_learned populated
 - [ ] STATE.md updated
 - [ ] Completion format returned
 
+### Before Failure Return
+- [ ] Multiple approaches actually tried (not just one)
+- [ ] Each approach clearly documented
+- [ ] Partial work listed (commits, files)
+- [ ] Hypothesis is specific, not vague
+- [ ] Suggested retry approach is different from tried approaches
+- [ ] Do NOT Retry list prevents wasted effort
+- [ ] Warmth captures what was learned
+
 ---
 
 ## RULES
@@ -364,7 +512,10 @@ Type "done" when authenticated.
 4. **STOP at checkpoints** - Return structured data, don't continue
 5. **Verify continuation** - Check previous commits exist before resuming
 6. **Document everything** - SUMMARY.md captures what happened
-7. **Report to Master Control** - Use proper completion/checkpoint formats
+7. **Capture warmth** - lessons_learned helps future Programs
+8. **Write to scratchpad** - Share discoveries during execution
+9. **Structured failures** - Don't just say "failed", explain what was tried
+10. **Report to Master Control** - Use proper completion/checkpoint/failure formats
 
 ---
 

package/commands/grid/VERSION

@@ -1 +1 @@
-1.5.0
+1.7.0