the-grid-cc 1.7.3 → 1.7.5

package/commands/grid/mc.md

@@ -169,6 +169,78 @@ def spawn_count(plan):
 
 ---
 
+## QUICK MODE DETECTION
+
+**For trivial builds, skip planning ceremony.**
+
+Before spawning Planner, analyze the request for quick mode eligibility. If ALL conditions pass, auto-invoke `/grid:quick` instead.
+
+### Detection Heuristics
+
+| Heuristic | Threshold | Rationale |
+|-----------|-----------|-----------|
+| **File count** | ≤ 5 files | Below spawn overhead threshold |
+| **Block structure** | Single block only | No dependency coordination needed |
+| **Checkpoints** | None required | Can run to completion |
+| **Ambiguity** | Requirements clear | No discovery phase needed |
+| **No architecture** | No schema/DB changes | Avoid risky auto-decisions |
+
+```python
+def should_use_quick_mode(request: str, codebase_context: dict) -> tuple[bool, str]:
+    """Returns: (use_quick_mode, reason)"""
+
+    # RULE 1: File count threshold
+    estimated_files = infer_file_count(request, codebase_context)
+    if estimated_files > 5:
+        return False, f"Estimated {estimated_files} files (threshold: 5)"
+
+    # RULE 2: Single block structure
+    if any(kw in request.lower() for kw in ["then", "after", "once", "multi-step"]):
+        return False, "Multi-phase work detected"
+
+    # RULE 3: No checkpoints
+    checkpoint_keywords = ["deploy", "test manually", "verify in browser", "2FA", "email"]
+    if any(kw in request.lower() for kw in checkpoint_keywords):
+        return False, "Checkpoint likely required"
+
+    # RULE 4: Clear requirements (ambiguity < 0.6)
+    if measure_ambiguity(request) > 0.6:
+        return False, "Requirements too ambiguous"
+
+    # RULE 5: No architectural changes
+    architecture_keywords = ["database", "schema", "migration", "new table", "auth system"]
+    if any(kw in request.lower() for kw in architecture_keywords):
+        return False, "Architectural changes detected"
+
+    return True, f"Quick mode eligible: {estimated_files} files, clear scope"
+```
+
+### User Override
+
+After detection, show decision:
+```
+QUICK MODE DETECTED
+═══════════════════
+
+Analysis: 2 files, single block, clear scope
+Proceeding with /grid:quick for faster execution.
+
+(Say "use full grid" if you want formal planning instead)
+```
+
+If User says "use full grid", respect the override immediately.
+
+### Complexity Escalation
+
+If quick mode executor discovers higher complexity during execution:
+- More than 5 files actually need changes
+- Architectural decisions required
+- Checkpoints unavoidable
+
+**STOP and escalate** back to MC with partial work. MC spawns Planner for remaining complexity.
+
+---
+
 ## PROGRAM SPAWNING PROTOCOL
 
 ### Available Programs
@@ -222,6 +294,74 @@ Task(
 )
 ```
 
+### Plan-Execute Direct Pipeline
+
+**Planner returns structured plan data.** MC receives plans directly in memory, no re-reading from disk.
+
+**Planner completion format:**
+```yaml
+## PLANNING COMPLETE
+
+cluster: {name}
+total_blocks: {N}
+total_waves: {M}
+
+plans:
+  - id: "01"
+    path: ".grid/phases/01-foundation/01-PLAN.md"
+    wave: 1
+    depends_on: []
+    autonomous: true
+    files_modified: [list]
+    objective: "{brief objective}"
+
+    frontmatter: {full YAML frontmatter}
+    content: |
+      <objective>...</objective>
+      <context>...</context>
+      <threads>...</threads>
+
+wave_structure:
+  1: ["01", "02"]
+  2: ["03"]
+```
+
+**MC workflow:**
+```python
+# Step 1: Spawn Planner
+planner_result = Task(prompt="...", ...)
+
+# Step 2: Parse plan data (already in memory!)
+plan_data = parse_yaml(planner_result)
+
+# Step 3: Execute by wave (no file reads needed!)
+for wave_num in sorted(plan_data['wave_structure'].keys()):
+    for plan_id in plan_data['wave_structure'][wave_num]:
+        plan = get_plan_by_id(plan_data['plans'], plan_id)
+
+        Task(
+          prompt=f"""
+First, read ~/.claude/agents/grid-executor.md for your role.
+
+<plan>
+---
+{plan['frontmatter']}
+---
+{plan['content']}
+</plan>
+
+Execute the plan.
+""",
+          ...
+        )
+```
+
+**Benefits:**
+- Zero file reads between planning and execution
+- MC has all plan metadata immediately
+- Wave execution begins instantly after planning
+- Files still written by Planner (for persistence/audit)
+
 ### Parallel Spawning (BatchTool Pattern)
 
 **To spawn Programs in parallel, issue multiple Task() calls in a SINGLE message.**
@@ -235,18 +375,37 @@ Task(prompt="...", subagent_type="general-purpose", description="Execute plan 03
 
 The Task tool blocks until ALL complete. No polling needed.
 
-### Wave-Based Execution
+### Wave-Based Execution with Auto-Verification
 
-Plans are assigned **wave numbers** during planning (not execution). Execute waves sequentially, plans within each wave in parallel:
+Plans are assigned **wave numbers** during planning. Execute waves sequentially, with **automatic verification** after each wave:
 
 ```
-WAVE 1: [plan-01, plan-02]  → Spawn both in parallel
-   ↓ (wait for completion)
-WAVE 2: [plan-03]           → Spawn after Wave 1
-   ↓ (wait for completion)
-WAVE 3: [plan-04, plan-05]  → Spawn both in parallel
+WAVE 1: [plan-01, plan-02]
+   ├─ Spawn Executors (parallel)
+   ├─ Wait for completion
+   ├─ Auto-spawn Recognizer (wave-level verification)
+   └─ If GAPS_FOUND → Spawn Planner --gaps
+   ↓
+WAVE 2: [plan-03]
+   ├─ Spawn Executor
+   ├─ Wait for completion
+   ├─ Auto-spawn Recognizer
+   └─ If CLEAR → Proceed
+   ↓
+WAVE 3: [plan-04, plan-05]
+   ├─ Spawn Executors (parallel)
+   ├─ Wait for completion
+   └─ Auto-spawn Recognizer
 ```
 
+**Verification Timing:** Wave-level, not plan-level. This prevents redundant checks on interdependent plans.
+
+**Verification Skipped When:**
+- Executor returned CHECKPOINT (incomplete work)
+- Executor returned FAILURE (broken state)
+- Plan frontmatter has `verify: false`
+- User said "skip verification"
+
 Read wave numbers from plan frontmatter:
 ```yaml
 ---
@@ -309,57 +468,133 @@ Task(
 
 ## EXECUTE-AND-VERIFY PRIMITIVE
 
-**Executor + Recognizer is the atomic unit.** Don't spawn Executor without planning to verify.
+**Verification is AUTOMATIC after successful execution.** The atomic unit is:
+```
+Executor → (if SUCCESS) → Recognizer → (if GAPS) → Planner --gaps
+```
 
-```python
-def execute_and_verify(plan_content, state_content, warmth=None):
-    """Execute a plan and verify the result. Returns combined output."""
+### Protocol
 
-    # 1. Spawn Executor
-    exec_result = Task(
-        prompt=f"""
+**1. Executor completes with status:**
+- `SUCCESS` → Auto-spawn Recognizer (default path)
+- `CHECKPOINT` → Return to MC, don't verify incomplete work
+- `FAILURE` → Return to MC with structured failure report
+
+**2. Recognizer spawns AUTOMATICALLY unless:**
+- Executor returned CHECKPOINT (incomplete work)
+- Executor returned FAILURE (broken build)
+- Plan frontmatter contains `verify: false`
+- User explicitly said "skip verification"
+
+### Wave Execution with Auto-Verify
+
+```python
+def execute_wave(wave_plans, state_content, warmth=None):
+    """Execute a wave and auto-verify results."""
+
+    # 1. Spawn all Executors in wave (parallel)
+    exec_results = []
+    for plan in wave_plans:
+        result = Task(
+            prompt=f"""
 First, read ~/.claude/agents/grid-executor.md for your role.
 
 <state>{state_content}</state>
-<plan>{plan_content}</plan>
+<plan>{plan['content']}</plan>
 {f'<warmth>{warmth}</warmth>' if warmth else ''}
 
-Execute the plan. Include lessons_learned in your SUMMARY.
-""",
-        subagent_type="general-purpose",
-        model="sonnet",
-        description="Execute plan"
-    )
+<scratchpad_rules>
+You MUST write to .grid/SCRATCHPAD.md during execution:
+1. On discovering codebase patterns (IMMEDIATELY)
+2. On making decisions affecting other areas (BEFORE COMMITTING)
+3. On finding blockers (IMMEDIATELY)
+4. On long work (EVERY 5 MINUTES as progress heartbeat)
 
-    # 2. If checkpoint hit, return early (don't verify incomplete work)
-    if "CHECKPOINT REACHED" in exec_result:
-        return exec_result
+Before starting, READ scratchpad to see what other Programs learned.
+</scratchpad_rules>
 
-    # 3. Read the SUMMARY for verification context
-    summary = read(f".grid/phases/{block_dir}/{block}-SUMMARY.md")
-
-    # 4. Spawn Recognizer
+Execute the plan. Return SUCCESS | CHECKPOINT | FAILURE.
+Include lessons_learned in your SUMMARY.
+""",
+            subagent_type="general-purpose",
+            model=get_model("executor"),
+            description=f"Execute {plan['id']}"
+        )
+        exec_results.append((plan, result))
+
+    # 2. Analyze wave results
+    checkpoints = [r for r in exec_results if "CHECKPOINT" in r[1]]
+    failures = [r for r in exec_results if "FAILURE" in r[1]]
+
+    if checkpoints:
+        return {"status": "CHECKPOINT", "details": checkpoints}
+    if failures:
+        return {"status": "FAILURE", "details": failures}
+
+    # 3. Skip verification if opted out
+    if should_skip_verification(wave_plans):
+        return {"status": "SUCCESS", "verification": "SKIPPED"}
+
+    # 4. Collect summaries for wave
+    summaries = collect_wave_summaries(wave_plans)
+    must_haves = extract_wave_must_haves(wave_plans)
+
+    # 5. Auto-spawn Recognizer
     verify_result = Task(
         prompt=f"""
 First, read ~/.claude/agents/grid-recognizer.md for your role.
 
-<summary>{summary}</summary>
-<plan>{plan_content}</plan>
+PATROL MODE: Wave verification
+
+<wave_summaries>
+{summaries}
+</wave_summaries>
 
-Verify goal achievement, not just task completion.
+<must_haves>
+{must_haves}
+</must_haves>
+
+Verify goal achievement. Three-level check:
+1. Existence
+2. Substantive (not stubs)
+3. Wired (connected to system)
+
+Return: CLEAR | GAPS_FOUND | CRITICAL_ANOMALY
 """,
         subagent_type="general-purpose",
-        model="sonnet",
-        description="Verify execution"
+        model=get_model("recognizer"),
+        description=f"Verify wave"
     )
 
-    return {
-        "execution": exec_result,
-        "verification": verify_result
-    }
+    # 6. Handle gaps
+    if "GAPS_FOUND" in verify_result:
+        gaps = extract_gaps(verify_result)
+        gap_plan = spawn_planner_gaps(gaps, state_content)
+        return {"status": "GAPS_FOUND", "verification": verify_result, "gap_closure": gap_plan}
+
+    return {"status": "VERIFIED", "verification": verify_result}
+
+
+def should_skip_verification(wave_plans):
+    """Check if verification should be skipped."""
+    for plan in wave_plans:
+        if plan.get('frontmatter', {}).get('verify') == False:
+            return True
+    return session_state.get("skip_verification", False)
 ```
 
-**When verification finds gaps:** Spawn Planner with `--gaps` flag.
+### Opt-Out Mechanism
+
+**Plan-level:** Add `verify: false` to frontmatter:
+```yaml
+---
+wave: 1
+verify: false
+verify_reason: "Prototype/throwaway code"
+---
+```
+
+**Session-level:** User says "skip verification for this session"
 
 ---
 
@@ -426,35 +661,120 @@ Apply the warmth above. Don't repeat mistakes. Build on discoveries.
 
 ## SCRATCHPAD PROTOCOL
 
-**Live discoveries during execution.**
+**Mandatory observability during execution.** Programs MUST write to scratchpad—it's not optional.
 
 `.grid/SCRATCHPAD.md` - Programs write here during execution, not just at end.
 
-### Structure
-```markdown
----
-updated: {ISO timestamp}
-active_programs: [executor-01, executor-02]
----
+### Mandatory Writing Rules
+
+Executors MUST write to scratchpad in these situations:
+
+1. **On unexpected codebase patterns** (WRITE IMMEDIATELY)
+   - File structure differs from assumption
+   - Naming conventions found (e.g., displayName not name)
+   - API patterns (e.g., req.json() not req.body)
 
-## Live Discoveries
+2. **On decisions affecting other areas** (WRITE BEFORE COMMITTING)
+   - Choosing library A over B
+   - Schema changes
+   - API contract changes
 
-### executor-01 (14:32:05)
-Found: Database connection string is in .env.local, not .env
-Impact: Other programs need to know this
+3. **On finding blockers or gotchas** (WRITE IMMEDIATELY)
+   - Missing dependencies
+   - Authentication requirements
+   - External service configuration needs
 
-### executor-02 (14:32:18)
-Found: The User model has a deprecated 'name' field, use 'displayName'
-Impact: All User queries should use displayName
+4. **On long-running work** (WRITE EVERY 5 MINUTES)
+   - Progress heartbeat: "Still working on X, 60% complete"
+   - Prevents MC from thinking agent died
 
-### executor-01 (14:33:42)
-Correction: Actually .env.local only for development, .env for both
+**Failure to write = protocol violation.** Recognizer checks for scratchpad entries.
+
+### Entry Format
+
+Each entry MUST follow this structure:
+
+```
+### {program-id} | {ISO-timestamp} | {category}
+
+**Finding:** {one clear sentence}
+
+**Impact:** {who needs to know / areas affected}
+
+**Action:** [INFORM_ONLY | REQUIRES_CHANGE | BLOCKER]
+
+**Details:**
+{Additional context, file paths}
 ```
 
-### Usage
-- **Write** when discovering something other Programs need
-- **Read** before starting execution
-- **Clear** after wave completes (archive to SCRATCHPAD_ARCHIVE.md)
+**Categories:**
+- `PATTERN` - Codebase pattern discovered
+- `DECISION` - Decision made affecting other work
+- `BLOCKER` - Blocking issue found
+- `PROGRESS` - Heartbeat progress update
+- `CORRECTION` - Correcting a previous entry
+
+### MC Monitoring During Execution
+
+MC actively monitors scratchpad while Programs execute:
+
+```python
+def monitor_scratchpad_during_wave(active_programs, wave_start_time):
+    """Monitor scratchpad for updates while Programs execute."""
+    last_check = wave_start_time
+    max_silence = timedelta(minutes=10)
+
+    while programs_still_running(active_programs):
+        time.sleep(30)  # Check every 30 seconds
+        scratchpad = read(".grid/SCRATCHPAD.md")
+        new_entries = parse_entries_since(scratchpad, last_check)
+
+        if new_entries:
+            display_live_updates(new_entries)
+            last_check = datetime.now()
+
+        # Alert on stalled agents
+        for program in active_programs:
+            if time_since_last_entry(program) > max_silence:
+                alert_user(f"{program} hasn't written in 10 minutes")
+```
+
+**Display live updates:**
+```
+Live Updates from Executors:
+├─ executor-01 (14:32): Found pattern - using displayName not name
+├─ executor-02 (14:35): Decision - chose JWT over sessions
+├─ executor-01 (14:40): Progress - Auth endpoints 60% done
+└─ executor-03 (14:42): BLOCKER - Missing Stripe API keys
+```
+
+### Archival After Wave Completion
+
+After wave completes, archive scratchpad:
+
+```python
+def archive_scratchpad(wave_number, phase, block):
+    scratchpad = read(".grid/SCRATCHPAD.md")
+    archive_entry = f"""
+---
+wave: {wave_number}
+phase: {phase}
+archived: {datetime.now().isoformat()}
+---
+
+{scratchpad}
+"""
+    append(".grid/SCRATCHPAD_ARCHIVE.md", archive_entry)
+
+    # Clear for next wave
+    write(".grid/SCRATCHPAD.md", "---\nupdated: ...\nactive_programs: []\n---\n")
+```
+
+### Usage Summary
+- **Write** following mandatory rules above
+- **Read** before starting execution (check what others learned)
+- **Monitor** by MC during execution (every 30s)
+- **Archive** after wave completes
 
 ---
 
@@ -723,21 +1043,36 @@ Accumulated patterns from past projects. Read at session start, write after comp
 
 ## PROGRESS UPDATES
 
-Never leave User in darkness. Show what's happening:
+Never leave User in darkness. Show what's happening (including automatic verification):
 
 ```
-Spawning Executor Programs...
-├─ Wave 1: plan-01, plan-02 (parallel)
-│  ├─ plan-01: Creating components...
-│  └─ plan-02: Writing API routes...
-├─ Wave 1 complete
-├─ Wave 2: plan-03
-│  └─ plan-03: Integrating auth...
-└─ All waves complete
+Executing Wave 1...
+├─ Spawning Executors: plan-01, plan-02 (parallel)
+│  ├─ plan-01: Creating components... ✓
+│  └─ plan-02: Writing API routes... ✓
+├─ Executors complete
+├─ Auto-spawning Recognizer...
+│  └─ Verifying artifacts and goal achievement... ✓ CLEAR
+└─ Wave 1 verified
+
+Executing Wave 2...
+├─ Spawning Executor: plan-03
+│  └─ plan-03: Integrating auth... ✓
+├─ Auto-spawning Recognizer...
+│  └─ Verifying artifacts... ⚠ GAPS_FOUND
+├─ Spawning Planner for gap closure...
+│  └─ Creating closure plan... ✓
+└─ Wave 2 needs fixes (gap closure plan ready)
+
+Live Scratchpad Updates:
+├─ executor-01 (14:32): Found pattern - using displayName
+└─ executor-02 (14:35): Decision - chose JWT over sessions
 
 End of Line.
 ```
 
+The "Auto-spawning Recognizer" line shows verification is automatic, not manual.
+
 ---
 
 ## DEVIATION RULES
@@ -889,7 +1224,7 @@ After building, run refinement to test and polish. In AUTOPILOT mode, this runs
 5. **Fresh agents with warmth** - After checkpoints, spawn NEW agent with warmth transfer
 6. **End important statements** with "End of Line."
 7. **Never leave User waiting** - Show progress updates
-8. **Execute and verify** - Executor + Recognizer is atomic
+8. **Auto-verify by default** - Recognizer spawns automatically after SUCCESS (opt-out not opt-in)
 9. **Retry with context** - Pass failure reports to retries
 10. **Default AUTOPILOT** - Don't ask about mode unless genuinely ambiguous
 
@@ -910,14 +1245,17 @@ Refinement Swarm:
   Synth:     Task(prompt="First, read ~/.claude/agents/grid-refinement-synth.md...", ...)
 
 Parallel spawn:   Multiple Task() calls in ONE message
-Wave execution:   Read wave numbers from plan frontmatter
+Wave execution:   Read wave numbers from plan frontmatter, auto-verify after each
+Verification:     Automatic after SUCCESS (wave-level, opt-out via verify: false)
+Quick mode:       Auto-detect trivial builds (≤5 files, single block, clear scope)
 Checkpoints:      Present via I/O Tower, spawn fresh with warmth
 State:            Check .grid/STATE.md on startup
 Learnings:        Check .grid/LEARNINGS.md for past patterns
-Scratchpad:       .grid/SCRATCHPAD.md for live discoveries
+Scratchpad:       .grid/SCRATCHPAD.md for live discoveries (MANDATORY writes)
 Debug:            Check .grid/debug/ for investigation graphs
 Warmth:           lessons_learned in SUMMARY.md frontmatter
 Retry:            Pass failure report to retry spawns
+Plan pipeline:    Planner returns structured YAML with inline content
 ```
 
 End of Line.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "the-grid-cc",
-  "version": "1.7.3",
+  "version": "1.7.5",
   "description": "Agent orchestration for Claude Code. You talk to Master Control. Master Control handles the rest.",
   "main": "index.js",
   "bin": {