docs: Pattern 4 stub clarification (Phase 195 deferred)

Phase 33-11 Quick Wins - Task 2

Clarified that Pattern 4 (continue statements) is intentionally
not implemented, with explicit error message and migration guide.

Changes:
1. Added clear STUB IMPLEMENTATION header to module docs
2. Updated lower() to return explicit error (not silent stub)
3. Added #[doc(hidden)] and #[allow(dead_code)] annotations
4. Created comprehensive migration guide (phase-195-pattern4.md)

Status:
- Not implemented: Pattern 4 (continue)
- Use instead: Pattern 1-3 (simple/break/if+phi)
- Reason: Continue requires complex PHI analysis, lower priority
- Build: ✅ Success (no errors, no new warnings)

Migration path:
- Pattern 1: Simple while loops (no break/continue)
- Pattern 2: Loops with break
- Pattern 3: Loops with if + PHI (workaround for continue)
- Pattern 4: (FUTURE) Loops with continue statements

docs/development/proposals/phase-195-pattern4.md

@@ -0,0 +1,106 @@
+# Phase 195: Pattern 4 (Loop with Continue) Implementation Plan
+
+**Status**: Deferred (not yet implemented)
+
+## Overview
+
+Pattern 4 handles loops with `continue` statements that skip to the next iteration. This is the most complex loop pattern due to additional control flow requirements.
+
+## Why Deferred?
+
+1. **Continue semantics require additional PHI and control flow analysis**
+   - Continue creates an additional edge to the loop header
+   - Requires phi nodes for both continue and normal paths
+   - More complex than break (which exits the loop)
+
+2. **Pattern 3 covers most practical cases**
+   - Pattern 1: Simple while loops
+   - Pattern 2: Loops with break
+   - Pattern 3: Loops with if + PHI (most common complex pattern)
+   - Pattern 4: Loops with continue (less common in practice)
+
+3. **Lower priority than break/if patterns**
+   - Break patterns (Pattern 2) are more common
+   - If + PHI patterns (Pattern 3) handle complex control flow
+   - Continue can often be refactored using if statements
+
+## Example Use Case
+
+```nyash
+local i = 0
+local sum = 0
+loop(i < 10) {
+  i = i + 1
+  if (i % 2 == 0) {
+    continue  // Skip even numbers
+  }
+  sum = sum + i
+}
+// sum = 25 (1+3+5+7+9)
+```
+
+## Implementation Requirements
+
+When implemented, Pattern 4 lowering will need to:
+
+1. **Detect continue statements** in the loop body
+2. **Generate PHI nodes** for continue target (loop header)
+3. **Handle carrier variables** (i, sum) across continue boundaries
+4. **Generate exit PHI nodes** for final values after loop
+
+## Control Flow Diagram
+
+```
+       header
+         |
+         v
+       body
+         |
+    /----+----\
+   /           \
+  v             v
+continue      normal
+  |             |
+  \-----+-------/
+        |
+        v
+      latch
+        |
+    /---+---\
+   /         \
+  v           v
+loop        exit
+```
+
+## Workaround
+
+Until Pattern 4 is implemented, use Pattern 3 (if + PHI) instead:
+
+```nyash
+local i = 0
+local sum = 0
+loop(i < 10) {
+  i = i + 1
+  if (not (i % 2 == 0)) {  // Invert condition
+    sum = sum + i
+  }
+}
+```
+
+## Migration Path
+
+1. **Pattern 1**: Simple while loops (no break/continue)
+2. **Pattern 2**: Loops with break
+3. **Pattern 3**: Loops with if + PHI
+4. **Pattern 4**: (FUTURE) Loops with continue statements
+
+## Related Files
+
+- `src/mir/builder/control_flow/joinir/patterns/pattern4_with_continue.rs` - Stub implementation
+- `src/mir/join_ir/lowering/loop_with_continue_minimal.rs` - Lowering logic (TODO)
+
+## Timeline
+
+- Phase 195+: Implementation planned but deferred
+- Priority: Lower than Pattern 1-3
+- Complexity: High (additional control flow edges)

src/mir/builder/control_flow/joinir/patterns/pattern4_with_continue.rs

@@ -1,6 +1,21 @@
-//! Pattern 4: Loop with Continue minimal lowerer
+//! Phase 195: Pattern 4 (Loop with Continue) - STUB IMPLEMENTATION
 //!
-//! Phase 194+: Structure-based detection for loops with continue statements.
+//! **Status**: Not yet implemented. Use Pattern 1-3 for production.
+//!
+//! **Migration Path**:
+//! - Pattern 1: Simple while loops (no break/continue)
+//! - Pattern 2: Loops with break
+//! - Pattern 3: Loops with if + PHI
+//! - Pattern 4: (FUTURE) Loops with continue statements
+//!
+//! **Why Deferred**:
+//! - Continue semantics require additional phi and control flow analysis
+//! - Pattern 3 covers most practical cases
+//! - Planned for Phase 195+ (lower priority than Break/If patterns)
+//!
+//! **Feature Gate**: None (returns explicit error, safe fallback)
+//!
+//! See: docs/development/proposals/phase-195-pattern4.md
 
 use crate::ast::ASTNode;
 use crate::mir::builder::MirBuilder;
@@ -35,11 +50,13 @@ pub fn can_lower(_builder: &MirBuilder, ctx: &super::router::LoopPatternContext)
 
 /// Phase 194+: Lowering function for Pattern 4
 ///
+/// **STUB IMPLEMENTATION**: Returns explicit error. Pattern 4 is not yet implemented.
+///
 /// Wrapper around cf_loop_pattern4_with_continue to match router signature.
 ///
-/// # TODO
+/// # Future Implementation Plan
 ///
-/// Implement Pattern 4 lowering logic:
+/// When implemented, this will:
 /// 1. Extract loop variables from condition
 /// 2. Generate JoinIR with continue support
 /// 3. Convert JoinModule → MirModule
@@ -47,15 +64,22 @@ pub fn can_lower(_builder: &MirBuilder, ctx: &super::router::LoopPatternContext)
 /// 5. Merge MIR blocks into current_function
 /// 6. Return Void (loop doesn't produce values)
 pub fn lower(
-    builder: &mut MirBuilder,
+    _builder: &mut MirBuilder,
     ctx: &super::router::LoopPatternContext,
 ) -> Result<Option<ValueId>, String> {
-    builder.cf_loop_pattern4_with_continue(ctx.condition, ctx.body, ctx.func_name, ctx.debug)
+    Err(format!(
+        "[cf_loop/pattern4] Pattern 4 (continue) not yet implemented for '{}' loop.\n\
+         Use Pattern 1-3 instead (simple while, break, or if+phi patterns).\n\
+         See: docs/development/proposals/phase-195-pattern4.md",
+        ctx.func_name
+    ))
 }
 
 impl MirBuilder {
     /// Phase 194+: Pattern 4 (Loop with Continue) minimal lowerer
     ///
+    /// **STUB IMPLEMENTATION**: This function is a placeholder for future implementation.
+    ///
     /// Handles loops with continue statements that skip to next iteration.
     ///
     /// # Example
@@ -75,7 +99,7 @@ impl MirBuilder {
     ///
     /// # Implementation Status
     ///
-    /// **TODO**: This is a stub implementation. Pattern 4 lowering logic needs to be implemented.
+    /// **NOT IMPLEMENTED**: This is a stub. Pattern 4 lowering logic needs to be implemented.
     ///
     /// The lowerer should:
     /// 1. Detect continue statements in the loop body
@@ -91,6 +115,8 @@ impl MirBuilder {
     /// 4. Create JoinInlineBoundary for input/output mapping
     /// 5. Merge MIR blocks into current_function
     /// 6. Return Void (loop doesn't produce values)
+    #[doc(hidden)]  // Not ready for public use
+    #[allow(dead_code)]  // Will be implemented in Phase 195+
     pub(in crate::mir::builder) fn cf_loop_pattern4_with_continue(
         &mut self,
         condition: &ASTNode,