the-grid-cc 1.7.3 → 1.7.4

package/.grid-drafts/02-auto-verify-default.md

@@ -0,0 +1,867 @@
+# Feature: Auto-Verify Default
+
+## Research Summary
+
+### Industry Patterns from CI/CD and Production Systems
+
+From my research on verification patterns in modern CI/CD pipelines and production deployment systems, I identified several critical patterns:
+
+**1. Verification as Default, Not Optional (Harness CV, 2025)**
+- Modern CD platforms like Harness implement "Continuous Verification" as an automatic step that validates deployments using APM integration and ML-based anomaly detection
+- Verification triggers automatic rollbacks if anomalies are found
+- The pattern: verification is the default behavior after any deployment, not something teams must remember to add
+
+**2. Smoke Tests as Immediate Post-Deployment Gates**
+- Industry standard: smoke tests execute IMMEDIATELY after deployment completes
+- Purpose: rapid validation that core functionality works before proceeding
+- LaunchDarkly (2024): "Smoke testing confirms build stability before full testing begins"
+- New Relic (2024): Synthetic monitors continuously verify production deployments automatically
+- These are NOT opt-in; they're built into the deployment pipeline
+
+**3. Fast Feedback Loops Over Manual Verification**
+- Dev.to (2026): CI/CD pipelines prioritize "automated builds and tests" immediately after code commits
+- The faster the feedback, the cheaper the fix
+- Manual verification creates bottlenecks and is reserved for truly non-automatable scenarios
+
+**4. Blocking vs Non-Blocking Verification**
+- Production systems use both patterns depending on risk:
+  - **Blocking:** Verification completes BEFORE next wave proceeds (deployment gates)
+  - **Non-blocking:** Verification runs in parallel with next steps (canary deployments with monitoring)
+- Grid's wave-based execution aligns with blocking pattern: verify Wave 1 before spawning Wave 2
+
+**5. Verification Scope: Structural vs Runtime**
+- CI/CD distinguishes between:
+  - **Verification:** "Did we build the right thing?" (structural checks, unit tests)
+  - **Validation:** "Does it work for users?" (integration tests, E2E)
+- Recognizer's three-level artifact verification (Exist → Substantive → Wired) mirrors this structural verification pattern
+
+**6. Opt-Out Not Opt-In**
+- Modern frameworks make verification the default path
+- Teams must explicitly skip verification (e.g., `--skip-tests`, `verify: false` flags)
+- This creates psychological friction to skip safety checks, reducing incidents
+
+**Key Takeaway:** The industry has converged on **automatic verification as the default behavior** after any code execution. Manual opt-in verification is a legacy pattern that creates risk.
+
+---
+
+## Current Protocol
+
+### How It Works Now
+
+From `mc.md` lines 310-363, the current protocol documents the "execute-and-verify primitive":
+
+```python
+## EXECUTE-AND-VERIFY PRIMITIVE
+
+**Executor + Recognizer is the atomic unit.** Don't spawn Executor without planning to verify.
+
+def execute_and_verify(plan_content, state_content, warmth=None):
+    """Execute a plan and verify the result. Returns combined output."""
+
+    # 1. Spawn Executor
+    exec_result = Task(...)
+
+    # 2. If checkpoint hit, return early (don't verify incomplete work)
+    if "CHECKPOINT REACHED" in exec_result:
+        return exec_result
+
+    # 3. Read the SUMMARY for verification context
+    summary = read(f".grid/phases/{block_dir}/{block}-SUMMARY.md")
+
+    # 4. Spawn Recognizer
+    verify_result = Task(...)
+
+    return {
+        "execution": exec_result,
+        "verification": verify_result
+    }
+```
+
+**Problem:** This is documented but NOT enforced. MC must manually remember to:
+1. Check if Executor returned CHECKPOINT
+2. Decide whether to verify
+3. Spawn Recognizer if appropriate
+
+This creates gaps:
+- Verification can be forgotten under cognitive load
+- Manual decision adds friction and delay
+- The atomic "execute-and-verify" primitive isn't actually atomic in practice
+
+### Current Spawning Pattern (lines 229-236)
+
+```python
+# Parallel execution - all three spawn simultaneously
+Task(prompt="...", subagent_type="general-purpose", description="Execute plan 01")
+Task(prompt="...", subagent_type="general-purpose", description="Execute plan 02")
+Task(prompt="...", subagent_type="general-purpose", description="Execute plan 03")
+```
+
+Programs spawn in parallel, MC waits for all to complete, then manually decides next steps.
+
+### Current Recognizer Usage (lines 757-774)
+
+```markdown
+## VERIFICATION (RECOGNIZER)
+
+After execution completes, spawn Recognizer for goal-backward verification:
+
+**Three-Level Artifact Check:**
+1. **Existence** - Does the file exist?
+2. **Substantive** - Is it real code (not stub)? Min lines, no TODO/FIXME
+3. **Wired** - Is it connected to the system?
+
+If Recognizer finds gaps, spawn Planner with `--gaps` flag to create closure plans.
+```
+
+Again, documented but not automatic. "After execution completes" is vague—WHEN exactly? Who remembers?
+
+---
+
+## Proposed Changes
+
+### 1. Make Verification Automatic by Default
+
+**BEFORE (mc.md lines 310-363):**
+```markdown
+## EXECUTE-AND-VERIFY PRIMITIVE
+
+**Executor + Recognizer is the atomic unit.** Don't spawn Executor without planning to verify.
+
+def execute_and_verify(plan_content, state_content, warmth=None):
+    """Execute a plan and verify the result. Returns combined output."""
+    [current implementation]
+```
+
+**AFTER:**
+```markdown
+## EXECUTE-AND-VERIFY PRIMITIVE
+
+**Verification is AUTOMATIC after successful execution.** The atomic unit is:
+```
+Executor → (if SUCCESS) → Recognizer → (if GAPS) → Planner --gaps
+```
+
+### Protocol
+
+**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, nothing to verify yet)
+- Executor returned FAILURE (broken build, fix first)
+- Plan frontmatter contains `verify: false` (rare override)
+- User explicitly said "skip verification" in this session
+
+**3. Verification timing:**
+- **Wave-level verification:** After entire wave completes, verify all plans in that wave
+- Recognizer receives ALL wave execution summaries for holistic goal verification
+- This prevents redundant verification of interdependent plans
+
+### Implementation Pattern
+
+```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>
+{f'<warmth>{warmth}</warmth>' if warmth else ''}
+
+Execute the plan. Include lessons_learned in your SUMMARY.
+Return one of: SUCCESS | CHECKPOINT | FAILURE
+""",
+            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 "EXECUTION FAILED" in r[1]]
+    successes = [r for r in exec_results if "SUCCESS" in r[1]]
+
+    # 3. Handle non-success states
+    if checkpoints:
+        return {"status": "CHECKPOINT", "details": checkpoints}
+    if failures:
+        return {"status": "FAILURE", "details": failures}
+
+    # 4. Auto-verify successes (unless explicitly skipped)
+    if should_skip_verification(wave_plans):
+        return {"status": "SUCCESS", "verification": "SKIPPED"}
+
+    # 5. Collect all summaries for wave
+    summaries = []
+    must_haves = []
+    for plan, result in successes:
+        summary = read(f".grid/phases/{plan.phase_dir}/{plan.block}-SUMMARY.md")
+        summaries.append(summary)
+
+        # Extract must-haves from plan frontmatter
+        plan_must_haves = extract_must_haves(plan.content)
+        must_haves.extend(plan_must_haves)
+
+    # 6. Spawn Recognizer (AUTOMATIC)
+    verify_result = Task(
+        prompt=f"""
+First, read ~/.claude/agents/grid-recognizer.md for your role.
+
+PATROL MODE: Wave {wave_plans[0].wave} verification
+
+<wave_summaries>
+{''.join(summaries)}
+</wave_summaries>
+
+<must_haves>
+{yaml.dump(must_haves)}
+</must_haves>
+
+Verify goal achievement for this wave. Check all artifacts against three levels:
+1. Existence
+2. Substantive (not stubs)
+3. Wired (connected to system)
+
+Return status: CLEAR | GAPS_FOUND | CRITICAL_ANOMALY
+""",
+        subagent_type="general-purpose",
+        model=get_model("recognizer"),
+        description=f"Verify wave {wave_plans[0].wave}"
+    )
+
+    # 7. Handle verification results
+    if "GAPS_FOUND" in verify_result:
+        # Auto-spawn Planner with --gaps flag
+        gaps = extract_gaps_from_verification(verify_result)
+        gap_closure_plan = spawn_planner_gaps(gaps, state_content)
+        return {
+            "status": "GAPS_FOUND",
+            "verification": verify_result,
+            "gap_closure": gap_closure_plan
+        }
+
+    return {
+        "status": "VERIFIED",
+        "verification": verify_result
+    }
+
+
+def should_skip_verification(wave_plans):
+    """Check if verification should be skipped for this wave."""
+
+    # Check each plan's frontmatter for verify: false
+    for plan in wave_plans:
+        frontmatter = extract_frontmatter(plan.content)
+        if frontmatter.get("verify") == False:
+            return True
+
+    # Check session state for global skip flag
+    if session_state.get("skip_verification"):
+        return True
+
+    return False  # Default: always verify
+```
+
+### Opt-Out Mechanism
+
+Users can skip verification via:
+
+**A. Plan-level override (in PLAN.md frontmatter):**
+```yaml
+---
+phase: 01-foundation
+plan: 02
+wave: 1
+verify: false  # Skip verification for this plan
+verify_reason: "Prototype/throwaway code"
+---
+```
+
+**B. Session-level override:**
+```
+User: "Skip verification for the rest of this session"
+MC: "Verification disabled for this session. Will re-enable on next /grid invocation. End of Line."
+```
+
+**C. Wave-level override (rare):**
+```python
+# In MC during wave execution
+if user_said_skip_verification:
+    session_state["skip_verification"] = True
+```
+```
+
+### 2. Update Wave Execution Documentation
+
+**BEFORE (mc.md lines 238-248):**
+```markdown
+### Wave-Based Execution
+
+Plans are assigned **wave numbers** during planning (not execution). Execute waves sequentially, plans within each wave in parallel:
+
+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
+```
+
+**AFTER:**
+```markdown
+### Wave-Based Execution with Auto-Verification
+
+Plans are assigned **wave numbers** during planning. Execute waves sequentially, with automatic verification after each wave:
+
+```
+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"
+```
+
+### 3. Update Rules Section
+
+**BEFORE (mc.md line 892):**
+```markdown
+8. **Execute and verify** - Executor + Recognizer is atomic
+```
+
+**AFTER:**
+```markdown
+8. **Auto-verify by default** - Recognizer spawns automatically after successful execution (opt-out not opt-in)
+```
+
+### 4. Update Progress Updates Format
+
+**BEFORE (mc.md lines 724-740):**
+```markdown
+## PROGRESS UPDATES
+
+Never leave User in darkness. Show what's happening:
+
+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
+```
+
+**AFTER:**
+```markdown
+## PROGRESS UPDATES
+
+Never leave User in darkness. Show what's happening (including automatic verification):
+
+```
+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)
+```
+
+The "Auto-spawning Recognizer" line shows it's automatic, not manual.
+```
+
+### 5. Update Quick Reference
+
+**BEFORE (mc.md line 914):**
+```markdown
+Checkpoints:      Present via I/O Tower, spawn fresh with warmth
+```
+
+**AFTER:**
+```markdown
+Checkpoints:      Present via I/O Tower, spawn fresh with warmth
+Verification:     Automatic after SUCCESS (wave-level, opt-out via verify: false)
+```
+
+---
+
+## Rationale
+
+### Why This Is Better
+
+**1. Reduced Cognitive Load**
+- MC no longer needs to remember to verify
+- The decision tree collapses: SUCCESS → verify (always)
+- Mental overhead shifts from "should I verify?" to "is this a rare case where I skip?"
+
+**2. Aligns with Industry Standards**
+- Modern CI/CD pipelines don't ask "should we run tests?" — they just do
+- Verification gates are the default in production deployment systems
+- Grid moves from legacy "manual QA" pattern to modern "continuous verification"
+
+**3. Prevents Silent Gaps**
+- Current risk: MC forgets to verify under time pressure or complexity
+- New behavior: Gaps are caught automatically before User sees "BUILD COMPLETE"
+- Shift-left principle: catch issues immediately after creation
+
+**4. Psychological Forcing Function**
+- Opt-out (not opt-in) creates friction to skip verification
+- Teams must explicitly justify skipping with `verify: false` in frontmatter
+- This mirrors production safety patterns (e.g., required PR reviews)
+
+**5. Better User Experience**
+- User sees verification happening in progress updates
+- Trust increases: "Grid verified this automatically"
+- Reduced surprises: fewer "wait, this doesn't work" moments post-delivery
+
+**6. Wave-Level Verification Reduces Redundancy**
+- Verifying plan-01 then plan-02 separately is wasteful when they're interdependent
+- Wave-level verification checks the COMBINED result of parallel work
+- Recognizer sees the full picture, not partial snapshots
+
+**7. Enables Automatic Gap Closure**
+- Current: MC sees verification results, manually decides to spawn Planner
+- New: Verification → GAPS_FOUND → auto-spawn Planner --gaps
+- Complete automation of the "build → verify → fix gaps" cycle
+
+**8. Preserves Escape Hatches**
+- Not draconian: three ways to opt out (plan, session, wave)
+- Checkpoints and failures naturally skip verification (smart defaults)
+- Power users can disable for rapid prototyping
+
+---
+
+## Edge Cases Considered
+
+### Edge Case 1: Executor Returns CHECKPOINT
+
+**Scenario:** Executor hits a checkpoint mid-wave (e.g., "verify login flow manually").
+
+**Handling:**
+```python
+if "CHECKPOINT REACHED" in exec_result:
+    return {"status": "CHECKPOINT", "details": checkpoint_data}
+    # DON'T verify — work is incomplete
+```
+
+**Why:** Checkpoints indicate incomplete work. Verifying incomplete work produces false negatives (gaps that aren't real because work isn't done). Wait for User to resolve checkpoint, then verify on continuation.
+
+**User Experience:**
+```
+Wave 1 Execution...
+├─ plan-01: ✓ SUCCESS
+├─ plan-02: ⏸ CHECKPOINT (needs User action)
+└─ Verification skipped (checkpoint pending)
+
+[MC presents checkpoint to User]
+```
+
+### Edge Case 2: Executor Returns FAILURE
+
+**Scenario:** Executor can't complete due to error (broken build, missing dependency).
+
+**Handling:**
+```python
+if "EXECUTION FAILED" in exec_result:
+    return {"status": "FAILURE", "details": failure_report}
+    # DON'T verify — nothing meaningful to verify
+```
+
+**Why:** Verification assumes there's work to verify. A failed execution produces no artifacts to check. Spawn retry with failure context instead.
+
+**User Experience:**
+```
+Wave 1 Execution...
+├─ plan-01: ✓ SUCCESS
+├─ plan-02: ✗ FAILURE (missing prisma client)
+└─ Verification skipped (fix failures first)
+
+Spawning retry for plan-02 with failure context...
+```
+
+### Edge Case 3: Multiple Plans, Mixed Results
+
+**Scenario:** Wave has 3 plans. Two succeed, one checkpoints.
+
+**Handling:**
+```python
+# Prioritize most blocking state
+if any_checkpoints:
+    return CHECKPOINT  # Block on checkpoint first
+elif any_failures:
+    return FAILURE     # Fix failures next
+else:
+    verify(successes)  # Only verify if all succeeded
+```
+
+**Why:** Verification should see COMPLETE wave results. If wave is partial, wait until checkpoint resolves.
+
+**User Experience:**
+```
+Wave 1: 3 plans
+├─ plan-01: ✓ SUCCESS
+├─ plan-02: ✓ SUCCESS
+├─ plan-03: ⏸ CHECKPOINT
+└─ Verification deferred until checkpoint resolves
+
+[User resolves checkpoint]
+
+Resuming Wave 1...
+├─ plan-03: ✓ SUCCESS
+├─ Auto-spawning Recognizer...
+│  └─ Verifying all 3 plans... ✓ CLEAR
+└─ Wave 1 verified
+```
+
+### Edge Case 4: Verification Itself Fails
+
+**Scenario:** Recognizer crashes or times out.
+
+**Handling:**
+```python
+try:
+    verify_result = Task(...)
+except Exception as e:
+    log_error(f"Recognizer failed: {e}")
+    return {
+        "status": "VERIFICATION_FAILED",
+        "error": str(e),
+        "recommendation": "Manual verification needed"
+    }
+```
+
+**Why:** Don't block progress on verification tooling failure. Surface to User as anomaly.
+
+**User Experience:**
+```
+Wave 1: Execution complete
+├─ Auto-spawning Recognizer... ✗ FAILED (timeout)
+└─ Verification tool error (manual check recommended)
+
+MC: Recognizer encountered an error. Execution completed but verification failed.
+Manual inspection recommended before proceeding. End of Line.
+```
+
+### Edge Case 5: Verification Finds Gaps, Planner Fails
+
+**Scenario:** Recognizer finds gaps → spawns Planner --gaps → Planner fails.
+
+**Handling:**
+```python
+if "GAPS_FOUND" in verify_result:
+    try:
+        gap_closure = spawn_planner_gaps(...)
+        return {"status": "GAPS_FOUND", "closure_plan": gap_closure}
+    except Exception as e:
+        return {
+            "status": "GAPS_FOUND",
+            "closure_plan": None,
+            "error": "Planner failed, manual gap closure needed"
+        }
+```
+
+**Why:** Gaps are still real even if automated closure planning fails. Surface gaps to User.
+
+**User Experience:**
+```
+Wave 1: Verification complete
+├─ Status: GAPS_FOUND
+│  └─ Missing: Auth token validation
+├─ Spawning Planner for gap closure... ✗ FAILED
+└─ Gaps identified but automated closure failed
+
+MC: Recognizer found gaps. Automatic closure planning failed.
+See VERIFICATION.md for details. Manual fix needed. End of Line.
+```
+
+### Edge Case 6: Parallel Waves Completing Out of Order
+
+**Scenario:** Due to Task() batching, Wave 2 might complete before Wave 1 verification.
+
+**Handling:**
+```python
+# Waves execute SEQUENTIALLY (per current protocol)
+# Wave 2 doesn't spawn until Wave 1 is fully verified
+
+def execute_all_waves(waves):
+    for wave in waves:
+        result = execute_wave(wave)  # Includes auto-verification
+
+        if result["status"] == "CHECKPOINT":
+            return result  # Block and return to User
+        elif result["status"] == "FAILURE":
+            retry_or_escalate()
+        elif result["status"] == "GAPS_FOUND":
+            execute_gap_closure(result["closure_plan"])
+        # Only proceed to next wave if verified
+```
+
+**Why:** Wave-based execution is ALREADY sequential (mc.md line 245). Verification is just the last step of each wave.
+
+**User Experience:**
+```
+Wave 1: Execute → Verify ✓
+   ↓
+Wave 2: Execute → Verify ✓
+   ↓
+Wave 3: Execute → Verify ✓
+```
+
+No change from current behavior — verification just becomes automatic final step.
+
+### Edge Case 7: User Requests Mid-Session Verification Skip
+
+**Scenario:** User says "just skip verification for now, I'll check later."
+
+**Handling:**
+```python
+# Set session flag
+session_state["skip_verification"] = True
+
+# Inform User
+print("Verification disabled for this session.")
+print("Will re-enable automatically on next /grid invocation.")
+print("End of Line.")
+```
+
+**Why:** Respect User agency. Power users prototyping may want speed over safety temporarily.
+
+**User Experience:**
+```
+User: "Skip verification for now, I'm just prototyping"
+
+MC: Verification disabled for this session.
+    Will re-enable automatically on next /grid invocation.
+    End of Line.
+
+[All subsequent waves skip verification]
+
+User: /clear
+User: /grid
+User: "Build X"
+
+MC: [Verification automatically re-enabled — fresh session]
+```
+
+### Edge Case 8: Verification Takes Too Long
+
+**Scenario:** Large codebase, Recognizer takes 5+ minutes to verify.
+
+**Handling:**
+```python
+# Add timeout to verification Task
+verify_result = Task(
+    prompt="...",
+    timeout=300000,  # 5 minutes
+    ...
+)
+
+if verify_result == TIMEOUT:
+    return {
+        "status": "VERIFICATION_TIMEOUT",
+        "recommendation": "Manual verification or increase timeout"
+    }
+```
+
+**Why:** Don't block progress indefinitely. Surface timeout and let User decide.
+
+**User Experience:**
+```
+Wave 1: Execution complete
+├─ Auto-spawning Recognizer...
+│  └─ Verifying... (large codebase, this may take a few minutes)
+│  └─ Timeout after 5 minutes
+└─ Verification incomplete (manual check recommended)
+
+MC: Verification timed out. Execution completed successfully.
+Recommend manual inspection of key artifacts. End of Line.
+```
+
+### Edge Case 9: Verification Finds CRITICAL_ANOMALY
+
+**Scenario:** Recognizer can't determine goal achievement programmatically (needs human verification).
+
+**Handling:**
+```python
+if verify_result["status"] == "CRITICAL_ANOMALY":
+    return {
+        "status": "HUMAN_VERIFICATION_NEEDED",
+        "details": verify_result["human_verification_items"]
+    }
+    # Present to User via I/O Tower
+```
+
+**Why:** Some things (visual, UX, external integrations) need human eyes. Don't block, surface.
+
+**User Experience:**
+```
+Wave 1: Execution complete
+├─ Auto-spawning Recognizer... ✓
+└─ Status: HUMAN_VERIFICATION_NEEDED
+
+Human Verification Required:
+1. Check login UI renders correctly (screenshot at .grid/refinement/screenshots/login.png)
+2. Test email delivery works (external service)
+
+MC: Automated checks passed. Manual verification needed for items above.
+Confirm when ready to proceed. End of Line.
+
+User: "Looks good"
+MC: Proceeding to Wave 2. End of Line.
+```
+
+### Edge Case 10: Opt-Out via Frontmatter But Verification Needed Anyway
+
+**Scenario:** User sets `verify: false` but User later says "wait, verify that."
+
+**Handling:**
+```python
+# Respect explicit User command over frontmatter
+if user_says_verify_now:
+    spawn_recognizer(...)  # Override frontmatter setting
+    print("Verification override: Spawning Recognizer despite verify: false in plan.")
+```
+
+**Why:** User intent in conversation overrides static config. Be flexible.
+
+**User Experience:**
+```
+[Wave completes with verify: false in plan]
+
+MC: Wave 1 complete. Verification skipped (verify: false in plan). End of Line.
+
+User: "Actually, verify that wave"
+
+MC: Verification override: Spawning Recognizer despite verify: false in plan.
+    [Recognizer runs...]
+    End of Line.
+```
+
+---
+
+## Implementation Checklist
+
+Before merging this feature into production mc.md:
+
+- [ ] Update EXECUTE-AND-VERIFY PRIMITIVE section with new protocol
+- [ ] Update Wave-Based Execution section with auto-verification flow
+- [ ] Add `should_skip_verification()` helper function to Quick Reference
+- [ ] Update RULES section (rule #8)
+- [ ] Update PROGRESS UPDATES with verification output
+- [ ] Add verification opt-out patterns to documentation
+- [ ] Update Quick Reference with verification timing note
+- [ ] Test edge cases:
+  - [ ] Executor returns CHECKPOINT → verify skipped
+  - [ ] Executor returns FAILURE → verify skipped
+  - [ ] Mixed wave results → correct prioritization
+  - [ ] Verification finds gaps → Planner spawns
+  - [ ] User says "skip verification" → session flag set
+  - [ ] Plan has `verify: false` → skipped
+  - [ ] Verification timeout → graceful degradation
+- [ ] Update grid-executor.md to return explicit SUCCESS status
+- [ ] Update grid-recognizer.md to handle wave-level summaries
+- [ ] Add verification metrics to STATE.md (optional):
+  ```yaml
+  verification_stats:
+    waves_verified: 3
+    gaps_found: 1
+    gaps_closed: 1
+    verification_skipped: 0
+  ```
+
+---
+
+## Migration Path
+
+This feature is **backward compatible**:
+
+1. **Existing behavior still works:** MC can still manually spawn Recognizer if needed
+2. **New projects get automatic verification:** Fresh `/grid` sessions use auto-verify
+3. **Old projects unaffected:** No changes to existing .grid/ state
+4. **Gradual rollout:** Ship to npm, users adopt on next `npm update`
+
+No breaking changes. Pure enhancement.
+
+---
+
+## Success Metrics
+
+After shipping, measure:
+
+1. **Gap detection rate:** % of waves where Recognizer finds gaps
+   - Hypothesis: Will increase initially (catching silent gaps), then decrease (quality improves)
+
+2. **Verification skip rate:** % of waves with `verify: false`
+   - Target: <5% (verification should be rare to skip)
+
+3. **User-initiated verification skips:** % of sessions where User says "skip verification"
+   - Target: <10% (should be exceptional, not common)
+
+4. **Time-to-verification:** Median time from Executor SUCCESS to Recognizer spawn
+   - Target: <2 seconds (nearly instant)
+
+5. **Gap closure success rate:** % of GAPS_FOUND that lead to successful closure plan execution
+   - Target: >80% (most gaps should be auto-fixable)
+
+---
+
+## Future Enhancements (Out of Scope)
+
+These are NOT part of this feature but could build on it later:
+
+1. **Predictive Verification:** Recognizer prioritizes checks based on past gap patterns
+2. **Partial Wave Verification:** Verify successes even if checkpoint pending (if independent)
+3. **Verification Metrics Dashboard:** `.grid/metrics.json` tracking verification health
+4. **Smart Verification Skipping:** Auto-skip verification for trivial changes (doc updates)
+5. **Verification Confidence Scores:** Recognizer returns 0-100% confidence in each check
+6. **Parallel Verification:** Spawn multiple Recognizers to verify different aspects simultaneously
+
+---
+
+## Conclusion
+
+This feature transforms verification from a **manual afterthought** to an **automatic safety gate**. By making verification opt-out (not opt-in), we align with industry best practices and dramatically reduce the risk of silent gaps reaching Users.
+
+The execute-and-verify primitive becomes truly atomic: Executor → Recognizer happens automatically unless there's a specific reason not to (checkpoint, failure, explicit skip).
+
+User experience improves: they see verification happening automatically, trust increases, and surprises decrease.
+
+End of Line.