aicodeman 0.2.8 → 0.3.0

package/dist/ralph-tracker.js

@@ -10,16 +10,23 @@
  * patterns are detected in the output stream, reducing overhead for
  * sessions not using autonomous loops.
  *
+ * Composed of four sub-modules:
+ * - RalphPlanTracker: Plan task management, checkpoints, versioning
+ * - RalphFixPlanWatcher: @fix_plan.md file watching and parsing
+ * - RalphStallDetector: Iteration stall detection
+ * - RalphStatusParser: RALPH_STATUS block parsing, circuit breaker
+ *
  * @module ralph-tracker
  */
 import { EventEmitter } from 'node:events';
-import { readFile } from 'node:fs/promises';
-import { existsSync, watch as fsWatch } from 'node:fs';
-import { join } from 'node:path';
-import { createInitialRalphTrackerState, createInitialCircuitBreakerStatus, } from './types.js';
-import { ANSI_ESCAPE_PATTERN_SIMPLE, fuzzyPhraseMatch, todoContentHash, stringSimilarity } from './utils/index.js';
+import { createInitialRalphTrackerState, } from './types.js';
+import { ANSI_ESCAPE_PATTERN_SIMPLE, fuzzyPhraseMatch, todoContentHash, stringSimilarity, Debouncer, } from './utils/index.js';
 import { MAX_LINE_BUFFER_SIZE } from './config/buffer-limits.js';
 import { MAX_TODOS_PER_SESSION } from './config/map-limits.js';
+import { RalphPlanTracker } from './ralph-plan-tracker.js';
+import { RalphFixPlanWatcher, generateFixPlanMarkdown, importFixPlanMarkdown } from './ralph-fix-plan-watcher.js';
+import { RalphStallDetector } from './ralph-stall-detector.js';
+import { RalphStatusParser } from './ralph-status-parser.js';
 // ========== Configuration Constants ==========
 // Note: MAX_TODOS_PER_SESSION and MAX_LINE_BUFFER_SIZE are imported from config modules
 /**
@@ -51,7 +58,6 @@ const EVENT_DEBOUNCE_MS = 50;
  * Prevents unbounded growth if many unique phrases are seen.
  */
 const MAX_COMPLETION_PHRASE_ENTRIES = 50;
-const MAX_PLAN_HISTORY = 10;
 /**
  * Common/generic completion phrases that may cause false positives.
  * These phrases are likely to appear in Claude's natural output,
@@ -226,66 +232,6 @@ const TASK_DONE_PATTERN = /(?:task|item|todo)\s*(?:#?\d+|"\s*[^"]+\s*")?\s*(?:is
 // ---------- Utility Patterns ----------
 /** Maximum number of task number to content mappings to track */
 const MAX_TASK_MAPPINGS = 100;
-// ---------- RALPH_STATUS Block Patterns ----------
-// Based on Ralph Claude Code structured status reporting
-/**
- * Matches the start of a RALPH_STATUS block
- * Pattern: ---RALPH_STATUS---
- */
-const RALPH_STATUS_START_PATTERN = /^---RALPH_STATUS---\s*$/;
-/**
- * Matches the end of a RALPH_STATUS block
- * Pattern: ---END_RALPH_STATUS---
- */
-const RALPH_STATUS_END_PATTERN = /^---END_RALPH_STATUS---\s*$/;
-/**
- * Matches STATUS field in RALPH_STATUS block
- * Captures: IN_PROGRESS | COMPLETE | BLOCKED
- */
-const RALPH_STATUS_FIELD_PATTERN = /^STATUS:\s*(IN_PROGRESS|COMPLETE|BLOCKED)\s*$/i;
-/**
- * Matches TASKS_COMPLETED_THIS_LOOP field
- * Captures: number
- */
-const RALPH_TASKS_COMPLETED_PATTERN = /^TASKS_COMPLETED_THIS_LOOP:\s*(\d+)\s*$/i;
-/**
- * Matches FILES_MODIFIED field
- * Captures: number
- */
-const RALPH_FILES_MODIFIED_PATTERN = /^FILES_MODIFIED:\s*(\d+)\s*$/i;
-/**
- * Matches TESTS_STATUS field
- * Captures: PASSING | FAILING | NOT_RUN
- */
-const RALPH_TESTS_STATUS_PATTERN = /^TESTS_STATUS:\s*(PASSING|FAILING|NOT_RUN)\s*$/i;
-/**
- * Matches WORK_TYPE field
- * Captures: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING
- */
-const RALPH_WORK_TYPE_PATTERN = /^WORK_TYPE:\s*(IMPLEMENTATION|TESTING|DOCUMENTATION|REFACTORING)\s*$/i;
-/**
- * Matches EXIT_SIGNAL field
- * Captures: true | false
- */
-const RALPH_EXIT_SIGNAL_PATTERN = /^EXIT_SIGNAL:\s*(true|false)\s*$/i;
-/**
- * Matches RECOMMENDATION field
- * Captures: any text
- */
-const RALPH_RECOMMENDATION_PATTERN = /^RECOMMENDATION:\s*(.+)$/i;
-// ---------- Completion Indicator Patterns (for dual-condition exit) ----------
-/**
- * Patterns that indicate potential completion (natural language)
- * Count >= 2 along with EXIT_SIGNAL: true triggers exit
- */
-const COMPLETION_INDICATOR_PATTERNS = [
-    /all\s+(?:tasks?|items?|work)\s+(?:are\s+)?(?:completed?|done|finished)/i,
-    /(?:completed?|finished)\s+all\s+(?:tasks?|items?|work)/i,
-    /nothing\s+(?:left|remaining)\s+to\s+do/i,
-    /no\s+more\s+(?:tasks?|items?|work)/i,
-    /everything\s+(?:is\s+)?(?:completed?|done)/i,
-    /project\s+(?:is\s+)?(?:completed?|done|finished)/i,
-];
 // ---------- Priority Detection Patterns ----------
 // Pre-compiled for performance; avoids repeated allocation in parsePriority()
 /** P0 (Critical) priority patterns - highest severity issues */
@@ -352,6 +298,13 @@ const P2_PRIORITY_PATTERNS = [
  * - 2nd occurrence: Emits `completionDetected` event (actual completion)
  * - If loop already active: Emits immediately on first occurrence
  *
+ * ## Sub-modules
+ *
+ * - `planTracker` - Plan task management, checkpoints, versioning
+ * - `fixPlanWatcher` - @fix_plan.md file watching and parsing
+ * - `stallDetector` - Iteration stall detection
+ * - `statusParser` - RALPH_STATUS block parsing, circuit breaker
+ *
  * ## Events
  *
  * - `loopUpdate` - Loop state changed (status, iteration, phrase)
@@ -370,6 +323,16 @@ const P2_PRIORITY_PATTERNS = [
  * ```
  */
 export class RalphTracker extends EventEmitter {
+    // ========== Sub-modules ==========
+    /** Plan task management sub-module */
+    planTracker = new RalphPlanTracker();
+    /** @fix_plan.md file watcher sub-module */
+    fixPlanWatcher;
+    /** Iteration stall detector sub-module */
+    stallDetector = new RalphStallDetector();
+    /** RALPH_STATUS block parser and circuit breaker sub-module */
+    statusParser = new RalphStatusParser();
+    // ========== Core State ==========
     /** Current state of the detected loop */
     _loopState;
     /** Map of todo items by ID for O(1) lookup */
@@ -383,14 +346,10 @@ export class RalphTracker extends EventEmitter {
     _completionPhraseCount = new Map();
     /** Timestamp of last cleanup check for throttling */
     _lastCleanupTime = 0;
-    /** Debounce timer for todoUpdate events */
-    _todoUpdateTimer = null;
-    /** Debounce timer for loopUpdate events */
-    _loopUpdateTimer = null;
-    /** Flag indicating pending todoUpdate emission */
-    _todoUpdatePending = false;
-    /** Flag indicating pending loopUpdate emission */
-    _loopUpdatePending = false;
+    /** Debouncer for todoUpdate events */
+    _todoDeb = new Debouncer(EVENT_DEBOUNCE_MS);
+    /** Debouncer for loopUpdate events */
+    _loopDeb = new Debouncer(EVENT_DEBOUNCE_MS);
     /** When true, prevents auto-enable on pattern detection */
     _autoEnableDisabled = true;
     /** Maps task numbers from "✔ Task #N" format to their content for status updates */
@@ -403,64 +362,6 @@ export class RalphTracker extends EventEmitter {
     _partialPromiseBuffer = '';
     /** Maximum size of partial promise buffer */
     static MAX_PARTIAL_PROMISE_SIZE = 256;
-    // ========== RALPH_STATUS Block State ==========
-    /** Circuit breaker state tracking */
-    _circuitBreaker;
-    /** Buffer for RALPH_STATUS block lines */
-    _statusBlockBuffer = [];
-    /** Flag indicating we're inside a RALPH_STATUS block */
-    _inStatusBlock = false;
-    /** Last parsed RALPH_STATUS block */
-    _lastStatusBlock = null;
-    /** Count of completion indicators detected (for dual-condition exit) */
-    _completionIndicators = 0;
-    /** Whether dual-condition exit gate has been met */
-    _exitGateMet = false;
-    /** Cumulative files modified across all iterations */
-    _totalFilesModified = 0;
-    /** Cumulative tasks completed across all iterations */
-    _totalTasksCompleted = 0;
-    /** Working directory for @fix_plan.md watching */
-    _workingDir = null;
-    /** File watcher for @fix_plan.md */
-    _fixPlanWatcher = null;
-    /** Error handler for FSWatcher (stored for cleanup to prevent memory leak) */
-    _fixPlanWatcherErrorHandler = null;
-    /** Debounce timer for file change events */
-    _fixPlanReloadTimer = null;
-    /** Path to the @fix_plan.md file being watched */
-    _fixPlanPath = null;
-    /**
-     * When @fix_plan.md is active, treat it as the source of truth for todo status.
-     * This prevents output-based detection from overriding file-based status.
-     */
-    get isFileAuthoritative() {
-        return this._fixPlanPath !== null;
-    }
-    // ========== Enhanced Plan Management ==========
-    /** Current version of the plan (incremented on changes) */
-    _planVersion = 1;
-    /** History of plan versions for rollback support */
-    _planHistory = [];
-    /** Enhanced plan tasks with execution tracking */
-    _planTasks = new Map();
-    /** Checkpoint intervals (iterations at which to trigger review) */
-    _checkpointIterations = [5, 10, 20, 30, 50, 75, 100];
-    /** Last checkpoint iteration */
-    _lastCheckpointIteration = 0;
-    // ========== Iteration Stall Detection ==========
-    /** Timestamp when iteration count last changed */
-    _lastIterationChangeTime = 0;
-    /** Last observed iteration count for stall detection */
-    _lastObservedIteration = 0;
-    /** Timer for iteration stall detection */
-    _iterationStallTimer = null;
-    /** Iteration stall warning threshold (ms) - default 10 minutes */
-    _iterationStallWarningMs = 10 * 60 * 1000;
-    /** Iteration stall critical threshold (ms) - default 20 minutes */
-    _iterationStallCriticalMs = 20 * 60 * 1000;
-    /** Whether stall warning has been emitted */
-    _iterationStallWarned = false;
     /** Alternate completion phrases (P1-003: multi-phrase support) - Set for O(1) lookup */
     _alternateCompletionPhrases = new Set();
     // ========== P1-009: Progress Estimation ==========
@@ -472,6 +373,10 @@ export class RalphTracker extends EventEmitter {
     _todosStartedAt = 0;
     /** Map of todo ID to timestamp when it started (for duration tracking) */
     _todoStartTimes = new Map();
+    /** Last calculated completion confidence */
+    _lastCompletionConfidence;
+    /** Confidence threshold for triggering completion (0-100) */
+    static COMPLETION_CONFIDENCE_THRESHOLD = 70;
     /**
      * Creates a new RalphTracker instance.
      * Starts in disabled state until Ralph patterns are detected.
@@ -479,13 +384,230 @@ export class RalphTracker extends EventEmitter {
     constructor() {
         super();
         this._loopState = createInitialRalphTrackerState();
-        this._circuitBreaker = createInitialCircuitBreakerStatus();
-        this._lastIterationChangeTime = Date.now();
+        // Initialize fix plan watcher with callbacks to parent methods
+        this.fixPlanWatcher = new RalphFixPlanWatcher((content) => this.parsePriority(content), (content) => this.generateTodoId(content));
+        // Wire sub-module events
+        this._wireSubModuleEvents();
+    }
+    /**
+     * Forward all sub-module events through RalphTracker
+     * so external consumers don't need to know about the split.
+     */
+    _wireSubModuleEvents() {
+        // Forward plan tracker events
+        for (const event of [
+            'planInitialized',
+            'planTaskUpdate',
+            'taskBlocked',
+            'taskUnblocked',
+            'planCheckpoint',
+            'planTaskAdded',
+            'planRollback',
+        ]) {
+            this.planTracker.on(event, (...args) => this.emit(event, ...args));
+        }
+        // Forward status parser events
+        this.statusParser.on('statusBlockDetected', (block) => {
+            // Auto-enable tracker when we see a status block
+            if (!this._loopState.enabled && !this._autoEnableDisabled) {
+                this.enable();
+            }
+            this._loopState.lastActivity = Date.now();
+            this.emit('statusBlockDetected', block);
+            this.emitLoopUpdateDebounced();
+        });
+        this.statusParser.on('circuitBreakerUpdate', (status) => {
+            this.emit('circuitBreakerUpdate', status);
+        });
+        this.statusParser.on('exitGateMet', (data) => {
+            this.emit('exitGateMet', data);
+        });
+        // Forward stall detector events
+        this.stallDetector.on('iterationStallWarning', (data) => {
+            this.emit('iterationStallWarning', data);
+        });
+        this.stallDetector.on('iterationStallCritical', (data) => {
+            this.emit('iterationStallCritical', data);
+        });
+        // Forward fix plan watcher events
+        this.fixPlanWatcher.on('todosLoaded', (items) => {
+            // Replace _todos with file-based items
+            this._todos.clear();
+            for (const item of items) {
+                this._todos.set(item.id, item);
+            }
+            // Auto-enable tracker when we have todos from @fix_plan.md
+            if (!this._loopState.enabled) {
+                this.enable();
+            }
+            this.emit('todoUpdate', this.todos);
+        });
+    }
+    // ========== Delegated Plan Tracker Methods ==========
+    /**
+     * Initialize plan tasks from generated plan items.
+     */
+    initializePlanTasks(items) {
+        this.planTracker.initializePlanTasks(items);
+    }
+    /**
+     * Update a specific plan task's status, attempts, or error.
+     */
+    updatePlanTask(taskId, update) {
+        return this.planTracker.updatePlanTask(taskId, update);
+    }
+    /**
+     * Add a new task to the plan.
+     */
+    addPlanTask(task) {
+        return this.planTracker.addPlanTask(task);
+    }
+    /**
+     * Get all plan tasks.
+     */
+    getPlanTasks() {
+        return this.planTracker.getPlanTasks();
+    }
+    /**
+     * Generate a checkpoint review.
+     */
+    generateCheckpointReview() {
+        return this.planTracker.generateCheckpointReview();
+    }
+    /**
+     * Get plan version history.
+     */
+    getPlanHistory() {
+        return this.planTracker.getPlanHistory();
+    }
+    /**
+     * Rollback to a previous plan version.
+     */
+    rollbackToVersion(version) {
+        return this.planTracker.rollbackToVersion(version);
+    }
+    /**
+     * Check if checkpoint review is due.
+     */
+    isCheckpointDue() {
+        return this.planTracker.isCheckpointDue();
+    }
+    /**
+     * Get current plan version.
+     */
+    get planVersion() {
+        return this.planTracker.planVersion;
+    }
+    // ========== Delegated Fix Plan Watcher Methods ==========
+    /**
+     * Set the working directory and start watching @fix_plan.md.
+     * @param workingDir - The session's working directory
+     */
+    setWorkingDir(workingDir) {
+        this.fixPlanWatcher.setWorkingDir(workingDir);
+    }
+    /**
+     * Load @fix_plan.md from disk if it exists.
+     */
+    async loadFixPlanFromDisk() {
+        return this.fixPlanWatcher.loadFixPlanFromDisk();
+    }
+    /**
+     * Stop watching @fix_plan.md.
+     */
+    stopWatchingFixPlan() {
+        this.fixPlanWatcher.stopWatchingFixPlan();
+    }
+    /**
+     * When @fix_plan.md is active, treat it as the source of truth for todo status.
+     */
+    get isFileAuthoritative() {
+        return this.fixPlanWatcher.isFileAuthoritative;
+    }
+    /**
+     * Generate @fix_plan.md content from current todos.
+     */
+    generateFixPlanMarkdown() {
+        return generateFixPlanMarkdown(this.todos);
+    }
+    /**
+     * Parse @fix_plan.md content and import todos.
+     * Replaces current todos with imported ones.
+     *
+     * @param content - Markdown content from @fix_plan.md
+     * @returns Number of todos imported
+     */
+    importFixPlanMarkdown(content) {
+        const newTodos = importFixPlanMarkdown(content, (c) => this.parsePriority(c), (c) => this.generateTodoId(c));
+        // Replace current todos with imported ones
+        this._todos.clear();
+        for (const todo of newTodos) {
+            this._todos.set(todo.id, todo);
+        }
+        // Emit update
+        this.emit('todoUpdate', this.todos);
+        return newTodos.length;
+    }
+    // ========== Delegated Stall Detector Methods ==========
+    /**
+     * Start iteration stall detection timer.
+     */
+    startIterationStallDetection() {
+        this.stallDetector.startIterationStallDetection();
+    }
+    /**
+     * Stop iteration stall detection timer.
+     */
+    stopIterationStallDetection() {
+        this.stallDetector.stopIterationStallDetection();
+    }
+    /**
+     * Get iteration stall metrics for monitoring.
+     */
+    getIterationStallMetrics() {
+        return this.stallDetector.getIterationStallMetrics();
+    }
+    /**
+     * Configure iteration stall thresholds.
+     */
+    configureIterationStallThresholds(warningMs, criticalMs) {
+        this.stallDetector.configureIterationStallThresholds(warningMs, criticalMs);
+    }
+    // ========== Delegated Status Parser Methods ==========
+    /**
+     * Manually reset circuit breaker to CLOSED state.
+     * @fires circuitBreakerUpdate
+     */
+    resetCircuitBreaker() {
+        this.statusParser.resetCircuitBreaker();
+    }
+    /**
+     * Get current circuit breaker status.
+     */
+    get circuitBreakerStatus() {
+        return this.statusParser.circuitBreakerStatus;
+    }
+    /**
+     * Get last parsed RALPH_STATUS block.
+     */
+    get lastStatusBlock() {
+        return this.statusParser.lastStatusBlock;
+    }
+    /**
+     * Get cumulative stats from status blocks.
+     */
+    get cumulativeStats() {
+        return this.statusParser.cumulativeStats;
+    }
+    /**
+     * Whether dual-condition exit gate has been met.
+     */
+    get exitGateMet() {
+        return this.statusParser.exitGateMet;
     }
+    // ========== Core Methods ==========
     /**
      * Add an alternate completion phrase (P1-003: multi-phrase support).
-     * Multiple phrases can trigger completion (useful for complex workflows).
-     * @param phrase - Additional phrase that can trigger completion
      */
     addAlternateCompletionPhrase(phrase) {
         if (!this._alternateCompletionPhrases.has(phrase)) {
@@ -496,7 +618,6 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Remove an alternate completion phrase.
-     * @param phrase - Phrase to remove
      */
     removeAlternateCompletionPhrase(phrase) {
         if (this._alternateCompletionPhrases.delete(phrase)) {
@@ -506,16 +627,12 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Check if a phrase matches any valid completion phrase (primary or alternate).
-     * @param phrase - Phrase to check
-     * @returns True if phrase matches any valid completion phrase
      */
     isValidCompletionPhrase(phrase) {
         return this.findMatchingCompletionPhrase(phrase) !== null;
     }
     /**
      * Find which completion phrase (primary or alternate) matches the given phrase.
-     * @param phrase - Phrase to check
-     * @returns The matched canonical phrase, or null if no match
      */
     findMatchingCompletionPhrase(phrase) {
         const primary = this._loopState.completionPhrase;
@@ -531,7 +648,6 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Prevent auto-enable from pattern detection.
-     * Use this when the user has explicitly disabled the Ralph tracker.
      */
     disableAutoEnable() {
         this._autoEnableDisabled = true;
@@ -548,129 +664,14 @@ export class RalphTracker extends EventEmitter {
     get autoEnableDisabled() {
         return this._autoEnableDisabled;
     }
-    /**
-     * Set the working directory and start watching @fix_plan.md.
-     * Automatically loads existing @fix_plan.md if present.
-     * @param workingDir - The session's working directory
-     */
-    setWorkingDir(workingDir) {
-        this._workingDir = workingDir;
-        this._fixPlanPath = join(workingDir, '@fix_plan.md');
-        // Try to load existing @fix_plan.md
-        this.loadFixPlanFromDisk();
-        // Start watching for changes
-        this.startWatchingFixPlan();
-    }
-    /**
-     * Load @fix_plan.md from disk if it exists.
-     * Called on initialization and when file changes are detected.
-     */
-    async loadFixPlanFromDisk() {
-        if (!this._fixPlanPath)
-            return 0;
-        try {
-            if (!existsSync(this._fixPlanPath)) {
-                return 0;
-            }
-            const content = await readFile(this._fixPlanPath, 'utf-8');
-            const count = this.importFixPlanMarkdown(content);
-            if (count > 0) {
-                // Auto-enable tracker when we have todos from @fix_plan.md
-                if (!this._loopState.enabled) {
-                    this.enable();
-                }
-                console.log(`[RalphTracker] Loaded ${count} todos from @fix_plan.md`);
-            }
-            return count;
-        }
-        catch (err) {
-            // File doesn't exist or can't be read - that's OK
-            console.log(`[RalphTracker] Could not load @fix_plan.md: ${err}`);
-            return 0;
-        }
-    }
-    /**
-     * Start watching @fix_plan.md for changes.
-     * Reloads todos when the file is modified.
-     */
-    startWatchingFixPlan() {
-        if (!this._fixPlanPath || !this._workingDir)
-            return;
-        // Stop existing watcher if any
-        this.stopWatchingFixPlan();
-        try {
-            // Only watch if the file exists
-            if (!existsSync(this._fixPlanPath)) {
-                // Watch the directory instead for file creation
-                this._fixPlanWatcher = fsWatch(this._workingDir, (_eventType, filename) => {
-                    if (filename === '@fix_plan.md') {
-                        this.handleFixPlanChange();
-                    }
-                });
-            }
-            else {
-                // Watch the file directly
-                this._fixPlanWatcher = fsWatch(this._fixPlanPath, () => {
-                    this.handleFixPlanChange();
-                });
-            }
-            // Add error handler to prevent unhandled errors and clean up on failure
-            // Store handler reference for proper cleanup in stopWatchingFixPlan()
-            if (this._fixPlanWatcher) {
-                this._fixPlanWatcherErrorHandler = (err) => {
-                    console.log(`[RalphTracker] FSWatcher error for @fix_plan.md: ${err.message}`);
-                    this.stopWatchingFixPlan();
-                };
-                this._fixPlanWatcher.on('error', this._fixPlanWatcherErrorHandler);
-            }
-        }
-        catch (err) {
-            console.log(`[RalphTracker] Could not watch @fix_plan.md: ${err}`);
-        }
-    }
-    /**
-     * Handle @fix_plan.md file change with debouncing.
-     */
-    handleFixPlanChange() {
-        // Debounce rapid changes (e.g., multiple writes)
-        if (this._fixPlanReloadTimer) {
-            clearTimeout(this._fixPlanReloadTimer);
-        }
-        this._fixPlanReloadTimer = setTimeout(() => {
-            this._fixPlanReloadTimer = null;
-            this.loadFixPlanFromDisk();
-        }, 500); // 500ms debounce
-    }
-    /**
-     * Stop watching @fix_plan.md.
-     */
-    stopWatchingFixPlan() {
-        if (this._fixPlanWatcher) {
-            // Remove error handler before closing to prevent memory leak
-            if (this._fixPlanWatcherErrorHandler) {
-                this._fixPlanWatcher.off('error', this._fixPlanWatcherErrorHandler);
-                this._fixPlanWatcherErrorHandler = null;
-            }
-            this._fixPlanWatcher.close();
-            this._fixPlanWatcher = null;
-        }
-        if (this._fixPlanReloadTimer) {
-            clearTimeout(this._fixPlanReloadTimer);
-            this._fixPlanReloadTimer = null;
-        }
-    }
     /**
      * Whether the tracker is enabled and actively monitoring output.
-     * Disabled by default; auto-enables when Ralph patterns detected.
-     * @returns True if tracker is processing terminal data
      */
     get enabled() {
         return this._loopState.enabled;
     }
     /**
      * Enable the tracker to start monitoring terminal output.
-     * Called automatically when Ralph patterns are detected.
-     * Emits 'enabled' event when transitioning from disabled state.
      * @fires enabled
      * @fires loopUpdate
      */
@@ -684,7 +685,6 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Disable the tracker to stop monitoring terminal output.
-     * Terminal data will be ignored until re-enabled.
      * @fires loopUpdate
      */
     disable() {
@@ -696,17 +696,6 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Soft reset - clears state but keeps enabled status.
-     * Use when a new task/loop starts within the same session.
-     *
-     * Clears:
-     * - All todo items
-     * - Completion phrase tracking
-     * - Loop state (active, iterations)
-     * - Line buffer
-     *
-     * Preserves:
-     * - Enabled status
-     *
      * @fires loopUpdate
      * @fires todoUpdate
      */
@@ -721,15 +710,10 @@ export class RalphTracker extends EventEmitter {
         this._taskNumberToContent.clear();
         this._lineBuffer = '';
         this._partialPromiseBuffer = '';
-        // Reset RALPH_STATUS block state
-        this._statusBlockBuffer = [];
-        this._inStatusBlock = false;
-        this._lastStatusBlock = null;
-        this._completionIndicators = 0;
-        this._exitGateMet = false;
-        this._totalFilesModified = 0;
-        this._totalTasksCompleted = 0;
-        // Keep circuit breaker state on soft reset (it tracks across iterations)
+        // Reset sub-modules
+        this.statusParser.reset();
+        this.planTracker.reset();
+        this.stallDetector.reset();
         // Emit on next tick to prevent listeners from modifying state during reset (non-reentrant)
         const loopState = this.loopState;
         const todos = this.todos;
@@ -740,8 +724,6 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Full reset - clears all state including enabled status.
-     * Use when session is closed or completely cleared.
-     * Returns tracker to initial disabled state.
      * @fires loopUpdate
      * @fires todoUpdate
      */
@@ -755,15 +737,11 @@ export class RalphTracker extends EventEmitter {
         this._todoStartTimes.clear();
         this._alternateCompletionPhrases.clear();
         this._lineBuffer = '';
-        // Reset all RALPH_STATUS block and circuit breaker state
-        this._statusBlockBuffer = [];
-        this._inStatusBlock = false;
-        this._lastStatusBlock = null;
-        this._completionIndicators = 0;
-        this._exitGateMet = false;
-        this._totalFilesModified = 0;
-        this._totalTasksCompleted = 0;
-        this._circuitBreaker = createInitialCircuitBreakerStatus();
+        this._partialPromiseBuffer = '';
+        // Full reset sub-modules
+        this.statusParser.fullReset();
+        this.planTracker.fullReset();
+        this.stallDetector.reset();
         // Emit on next tick to prevent listeners from modifying state during reset (non-reentrant)
         const loopState = this.loopState;
         const todos = this.todos;
@@ -774,178 +752,49 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Clear all debounce timers.
-     * Called during reset/fullReset to prevent stale emissions.
      */
     clearDebounceTimers() {
-        if (this._todoUpdateTimer) {
-            clearTimeout(this._todoUpdateTimer);
-            this._todoUpdateTimer = null;
-        }
-        if (this._loopUpdateTimer) {
-            clearTimeout(this._loopUpdateTimer);
-            this._loopUpdateTimer = null;
-        }
-        this._todoUpdatePending = false;
-        this._loopUpdatePending = false;
+        this._todoDeb.cancel();
+        this._loopDeb.cancel();
     }
     /**
      * Emit todoUpdate event with debouncing.
-     * Batches rapid consecutive calls to reduce UI jitter.
-     * The event fires after EVENT_DEBOUNCE_MS of inactivity.
      */
     emitTodoUpdateDebounced() {
-        this._todoUpdatePending = true;
-        if (this._todoUpdateTimer) {
-            clearTimeout(this._todoUpdateTimer);
-        }
-        this._todoUpdateTimer = setTimeout(() => {
-            if (this._todoUpdatePending) {
-                this._todoUpdatePending = false;
-                this._todoUpdateTimer = null;
-                this.emit('todoUpdate', this.todos);
-            }
-        }, EVENT_DEBOUNCE_MS);
+        this._todoDeb.schedule(() => this.emit('todoUpdate', this.todos));
     }
     /**
      * Emit loopUpdate event with debouncing.
-     * Batches rapid consecutive calls to reduce UI jitter.
-     * The event fires after EVENT_DEBOUNCE_MS of inactivity.
      */
     emitLoopUpdateDebounced() {
-        this._loopUpdatePending = true;
-        if (this._loopUpdateTimer) {
-            clearTimeout(this._loopUpdateTimer);
-        }
-        this._loopUpdateTimer = setTimeout(() => {
-            if (this._loopUpdatePending) {
-                this._loopUpdatePending = false;
-                this._loopUpdateTimer = null;
-                this.emit('loopUpdate', this.loopState);
-            }
-        }, EVENT_DEBOUNCE_MS);
+        this._loopDeb.schedule(() => this.emit('loopUpdate', this.loopState));
     }
     /**
      * Flush all pending debounced events immediately.
-     * Useful for testing or when immediate state sync is needed.
      */
     flushPendingEvents() {
-        if (this._todoUpdatePending) {
-            this._todoUpdatePending = false;
-            if (this._todoUpdateTimer) {
-                clearTimeout(this._todoUpdateTimer);
-                this._todoUpdateTimer = null;
-            }
+        if (this._todoDeb.isPending) {
+            this._todoDeb.cancel();
             this.emit('todoUpdate', this.todos);
         }
-        if (this._loopUpdatePending) {
-            this._loopUpdatePending = false;
-            if (this._loopUpdateTimer) {
-                clearTimeout(this._loopUpdateTimer);
-                this._loopUpdateTimer = null;
-            }
+        if (this._loopDeb.isPending) {
+            this._loopDeb.cancel();
             this.emit('loopUpdate', this.loopState);
         }
     }
     /**
      * Get a copy of the current loop state.
-     * @returns Shallow copy of loop state (safe to modify)
-     */
-    // ========== Iteration Stall Detection Methods ==========
-    /**
-     * Start iteration stall detection timer.
-     * Should be called when the loop becomes active.
-     */
-    startIterationStallDetection() {
-        this.stopIterationStallDetection();
-        this._lastIterationChangeTime = Date.now();
-        this._iterationStallWarned = false;
-        // Check every minute
-        this._iterationStallTimer = setInterval(() => {
-            this.checkIterationStall();
-        }, 60 * 1000);
-    }
-    /**
-     * Stop iteration stall detection timer.
-     */
-    stopIterationStallDetection() {
-        if (this._iterationStallTimer) {
-            clearInterval(this._iterationStallTimer);
-            this._iterationStallTimer = null;
-        }
-    }
-    /**
-     * Check for iteration stall and emit appropriate events.
      */
-    checkIterationStall() {
-        if (!this._loopState.active)
-            return;
-        const stallDurationMs = Date.now() - this._lastIterationChangeTime;
-        // Critical stall (longer duration)
-        if (stallDurationMs >= this._iterationStallCriticalMs) {
-            this.emit('iterationStallCritical', {
-                iteration: this._loopState.cycleCount,
-                stallDurationMs,
-            });
-            return;
-        }
-        // Warning stall
-        if (stallDurationMs >= this._iterationStallWarningMs && !this._iterationStallWarned) {
-            this._iterationStallWarned = true;
-            this.emit('iterationStallWarning', {
-                iteration: this._loopState.cycleCount,
-                stallDurationMs,
-            });
-        }
-    }
-    /**
-     * Get iteration stall metrics for monitoring.
-     */
-    getIterationStallMetrics() {
+    get loopState() {
         return {
-            lastIterationChangeTime: this._lastIterationChangeTime,
-            stallDurationMs: Date.now() - this._lastIterationChangeTime,
-            warningThresholdMs: this._iterationStallWarningMs,
-            criticalThresholdMs: this._iterationStallCriticalMs,
-            isWarned: this._iterationStallWarned,
-            currentIteration: this._loopState.cycleCount,
+            ...this._loopState,
+            planVersion: this.planTracker.planVersion,
+            planHistoryLength: this.planTracker.getPlanHistory().length,
+            completionConfidence: this._lastCompletionConfidence,
         };
     }
     /**
-     * Configure iteration stall thresholds.
-     * @param warningMs - Warning threshold in milliseconds
-     * @param criticalMs - Critical threshold in milliseconds
-     */
-    configureIterationStallThresholds(warningMs, criticalMs) {
-        this._iterationStallWarningMs = warningMs;
-        this._iterationStallCriticalMs = criticalMs;
-    }
-    get loopState() {
-        return {
-            ...this._loopState,
-            planVersion: this._planVersion,
-            planHistoryLength: this._planHistory.length,
-            completionConfidence: this._lastCompletionConfidence,
-        };
-    }
-    /** Last calculated completion confidence */
-    _lastCompletionConfidence;
-    /** Confidence threshold for triggering completion (0-100) */
-    static COMPLETION_CONFIDENCE_THRESHOLD = 70;
-    /**
-     * Calculate confidence score for a potential completion signal.
-     *
-     * Scoring weights:
-     * - Promise tag with proper format: +30
-     * - Matches expected phrase: +25
-     * - All todos complete: +20
-     * - EXIT_SIGNAL: true: +15
-     * - Multiple completion indicators (>=2): +10
-     * - Context appropriate (not in prompt/explanation): +10
-     * - Loop was explicitly active: +10
-     *
-     * @param phrase - The detected phrase to evaluate
-     * @param context - Optional surrounding context for the phrase
-     * @returns CompletionConfidence assessment
+     * Calculate confidence score for a potential completion signal.
      */
     calculateCompletionConfidence(phrase, context) {
         let score = 0;
@@ -978,19 +827,19 @@ export class RalphTracker extends EventEmitter {
             score += 20;
         }
         // Check for EXIT_SIGNAL from RALPH_STATUS block (adds 15 points)
-        if (this._lastStatusBlock?.exitSignal === true) {
+        const lastBlock = this.statusParser.lastStatusBlock;
+        if (lastBlock?.exitSignal === true) {
             signals.hasExitSignal = true;
             score += 15;
         }
         // Check for multiple completion indicators (adds 10 points)
-        if (this._completionIndicators >= 2) {
+        if (this.statusParser.cumulativeStats.completionIndicators >= 2) {
             signals.multipleIndicators = true;
             score += 10;
         }
         // Check context appropriateness (deduct if inappropriate)
         if (context) {
             const lowerContext = context.toLowerCase();
-            // Deduct points if phrase appears in prompt-like context
             if (lowerContext.includes('output:') ||
                 lowerContext.includes('completion phrase') ||
                 lowerContext.includes('output exactly') ||
@@ -1024,28 +873,12 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Get all tracked todo items as an array.
-     * @returns Array of todo items (copy, safe to modify)
      */
     get todos() {
         return Array.from(this._todos.values());
     }
     /**
      * Process raw terminal data to detect inner loop patterns.
-     *
-     * This is the main entry point for parsing output. Call this with each
-     * chunk of data from the PTY. The tracker will:
-     *
-     * 1. Strip ANSI escape codes
-     * 2. Auto-enable if disabled and Ralph patterns detected
-     * 3. Buffer data and process complete lines
-     * 4. Detect loop status, todos, and completion phrases
-     * 5. Periodically clean up expired todos
-     *
-     * @param data - Raw terminal data (may include ANSI codes)
-     * @fires loopUpdate - When loop state changes
-     * @fires todoUpdate - When todos are detected or updated
-     * @fires completionDetected - When completion phrase found
-     * @fires enabled - When tracker auto-enables
      */
     processTerminalData(data) {
         // Remove ANSI escape codes for cleaner parsing
@@ -1054,33 +887,29 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Process pre-stripped terminal data (ANSI codes already removed).
-     * Use this when the caller has already stripped ANSI to avoid redundant regex work.
      */
     processCleanData(cleanData) {
         // If tracker is disabled, only check for patterns that should auto-enable it
         if (!this._loopState.enabled) {
-            // Don't auto-enable if explicitly disabled by user setting
             if (this._autoEnableDisabled) {
                 return;
             }
             if (this.shouldAutoEnable(cleanData)) {
                 this.enable();
-                // Continue processing now that we're enabled
             }
             else {
-                return; // Don't process further when disabled
+                return;
             }
         }
         // Buffer data for line-based processing
         this._lineBuffer += cleanData;
         // Prevent unbounded line buffer growth from very long lines
         if (this._lineBuffer.length > MAX_LINE_BUFFER_SIZE) {
-            // Truncate to last portion to preserve recent data
             this._lineBuffer = this._lineBuffer.slice(-Math.floor(MAX_LINE_BUFFER_SIZE / 2));
         }
         // Process complete lines
         const lines = this._lineBuffer.split('\n');
-        this._lineBuffer = lines.pop() || ''; // Keep incomplete line in buffer
+        this._lineBuffer = lines.pop() || '';
         for (const line of lines) {
             this.processLine(line);
         }
@@ -1091,26 +920,11 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Check if data contains patterns that should auto-enable the tracker.
-     *
-     * The tracker auto-enables when any of these patterns are detected:
-     * - `/ralph-loop:ralph-loop` command
-     * - `<promise>PHRASE</promise>` completion tags
-     * - TodoWrite tool usage indicators
-     * - Iteration patterns (`Iteration 5/50`, `[5/50]`)
-     * - Todo checkboxes (`- [ ]`, `- [x]`)
-     * - Todo indicator icons (`☐`, `◐`, `☒`)
-     * - Loop start messages (`Loop started at`)
-     * - All tasks complete announcements
-     * - Task completion signals
-     *
-     * @param data - ANSI-cleaned terminal data
-     * @returns True if any Ralph-related pattern is detected
      */
     shouldAutoEnable(data) {
         // Cheap pre-filter: skip the full regex battery if none of the key
         // substrings that any pattern could match are present in the data.
-        // This avoids 12 regex tests on every PTY chunk (the common case).
-        if (!data.includes('<') && // <promise>, TodoWrite
+        if (!data.includes('<') &&
             !data.includes('ralph') &&
             !data.includes('Ralph') &&
             !data.includes('Todo') &&
@@ -1118,8 +932,8 @@ export class RalphTracker extends EventEmitter {
             !data.includes('Iteration') &&
             !data.includes('[') &&
             !data.includes('\u2610') &&
-            !data.includes('\u2612') && // ☐ ☒
-            !data.includes('\u2714') && // ✔
+            !data.includes('\u2612') &&
+            !data.includes('\u2714') &&
             !data.includes('Loop') &&
             !data.includes('complete') &&
             !data.includes('COMPLETE') &&
@@ -1127,74 +941,46 @@ export class RalphTracker extends EventEmitter {
             !data.includes('DONE')) {
             return false;
         }
-        // Ralph loop command: /ralph-loop:ralph-loop
-        if (RALPH_START_PATTERN.test(data)) {
+        if (RALPH_START_PATTERN.test(data))
             return true;
-        }
-        // Completion phrase: <promise>...</promise>
-        if (PROMISE_PATTERN.test(data)) {
+        if (PROMISE_PATTERN.test(data))
             return true;
-        }
-        // TodoWrite tool usage
-        if (TODOWRITE_PATTERN.test(data)) {
+        if (TODOWRITE_PATTERN.test(data))
             return true;
-        }
-        // Iteration patterns from Ralph loop: "Iteration 5/50", "[5/50]"
-        if (ITERATION_PATTERN.test(data)) {
+        if (ITERATION_PATTERN.test(data))
             return true;
-        }
-        // Todo checkboxes: "- [ ] Task" or "- [x] Task"
-        // Reset lastIndex BEFORE test to ensure consistent matching with /g flag patterns
         TODO_CHECKBOX_PATTERN.lastIndex = 0;
-        if (TODO_CHECKBOX_PATTERN.test(data)) {
+        if (TODO_CHECKBOX_PATTERN.test(data))
             return true;
-        }
-        // Todo indicator icons: "Todo: ☐", "Todo: ◐", etc.
         TODO_INDICATOR_PATTERN.lastIndex = 0;
-        if (TODO_INDICATOR_PATTERN.test(data)) {
+        if (TODO_INDICATOR_PATTERN.test(data))
             return true;
-        }
-        // Claude Code native todo format: "☐ Task", "☒ Task"
         TODO_NATIVE_PATTERN.lastIndex = 0;
-        if (TODO_NATIVE_PATTERN.test(data)) {
+        if (TODO_NATIVE_PATTERN.test(data))
             return true;
-        }
-        // Claude Code checkmark-based TodoWrite: "✔ Task #N created:", "✔ Task #N updated:"
         TODO_TASK_CREATED_PATTERN.lastIndex = 0;
-        if (TODO_TASK_CREATED_PATTERN.test(data)) {
+        if (TODO_TASK_CREATED_PATTERN.test(data))
             return true;
-        }
         TODO_TASK_STATUS_PATTERN.lastIndex = 0;
-        if (TODO_TASK_STATUS_PATTERN.test(data)) {
+        if (TODO_TASK_STATUS_PATTERN.test(data))
             return true;
-        }
-        // Loop start patterns (e.g., "Loop started at", "Starting Ralph loop")
-        if (LOOP_START_PATTERN.test(data)) {
+        if (LOOP_START_PATTERN.test(data))
             return true;
-        }
-        // All tasks complete signals
-        if (ALL_COMPLETE_PATTERN.test(data)) {
+        if (ALL_COMPLETE_PATTERN.test(data))
             return true;
-        }
-        // Task completion signals
-        if (TASK_DONE_PATTERN.test(data)) {
+        if (TASK_DONE_PATTERN.test(data))
             return true;
-        }
         return false;
     }
     /**
      * Process a single line of terminal output.
-     * Runs all detection methods in sequence.
-     * @param line - Single line of ANSI-cleaned terminal output
      */
     processLine(line) {
         const trimmed = line.trim();
         if (!trimmed)
             return;
-        // Check for RALPH_STATUS block (structured status reporting)
-        this.processStatusBlockLine(trimmed);
-        // Check for completion indicators (for dual-condition exit gate)
-        this.detectCompletionIndicators(trimmed);
+        // Delegate RALPH_STATUS block and completion indicator detection to sub-module
+        this.statusParser.processLine(trimmed);
         // Check for completion phrase
         this.detectCompletionPhrase(trimmed);
         // Check for "all tasks complete" signals
@@ -1208,52 +994,25 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Detect "all tasks complete" messages.
-     *
-     * When a valid "all complete" message is detected:
-     * 1. Marks all tracked todos as completed
-     * 2. Emits completion event if a completion phrase is set
-     *
-     * Validation criteria:
-     * - Line must match ALL_COMPLETE_PATTERN
-     * - Line must be reasonably short (<100 chars) to avoid matching commentary
-     * - Must not look like prompt text (no "output:" or `<promise>`)
-     * - Must have at least one tracked todo
-     * - If count is mentioned, should roughly match tracked todo count
-     *
-     * @param line - Single line to check
-     * @fires todoUpdate - If any todos marked complete
-     * @fires completionDetected - If completion phrase was set
-     * @fires loopUpdate - If loop state changes
      */
     detectAllTasksComplete(line) {
-        // When @fix_plan.md is active, only trust the file for todo status
-        // This prevents false positives from Claude saying "all done" in conversation
         if (this.isFileAuthoritative)
             return;
-        // Only trigger if line is a clear standalone completion message
-        // Avoid matching commentary like "once all tasks are complete..."
         if (!ALL_COMPLETE_PATTERN.test(line))
             return;
-        // Must be a reasonably short line (< 100 chars) to be a completion signal, not commentary
         if (line.length > 100)
             return;
-        // Skip if this looks like it's part of the original prompt (contains "output:")
         if (line.toLowerCase().includes('output:') || line.includes('<promise>'))
             return;
-        // Don't trigger if we haven't seen any todos yet
         if (this._todos.size === 0)
             return;
-        // Check if the count matches our todo count (e.g., "All 8 files created")
         const countMatch = line.match(ALL_COUNT_PATTERN);
         const parsedCount = countMatch ? parseInt(countMatch[1], 10) : NaN;
         const mentionedCount = Number.isNaN(parsedCount) ? null : parsedCount;
         const todoCount = this._todos.size;
-        // If a count is mentioned, it should match our todo count (within reason)
         if (mentionedCount !== null && Math.abs(mentionedCount - todoCount) > 2) {
-            // Count doesn't match our todos, might be unrelated
             return;
         }
-        // Mark all todos as complete
         let updated = false;
         for (const todo of this._todos.values()) {
             if (todo.status !== 'completed') {
@@ -1264,7 +1023,6 @@ export class RalphTracker extends EventEmitter {
         if (updated) {
             this.emit('todoUpdate', this.todos);
         }
-        // Emit completion if we have an expected phrase
         if (this._loopState.completionPhrase) {
             this._loopState.active = false;
             this._loopState.lastActivity = Date.now();
@@ -1273,25 +1031,18 @@ export class RalphTracker extends EventEmitter {
         }
     }
     /**
-     * Detect individual task completion signals
-     * e.g., "Task 8 is done", "marked as completed"
-     *
-     * NOTE: This is intentionally conservative to avoid jitter.
-     * Only marks a todo complete if we can match it by task number.
+     * Detect individual task completion signals.
      */
     detectTaskCompletion(line) {
-        // When @fix_plan.md is active, only trust the file for todo status
         if (this.isFileAuthoritative)
             return;
         if (!TASK_DONE_PATTERN.test(line))
             return;
-        // Only act on explicit task number references like "Task 8 is done"
         const taskNumMatch = line.match(/task\s*#?(\d+)/i);
         if (taskNumMatch) {
             const taskNum = parseInt(taskNumMatch[1], 10);
             if (Number.isNaN(taskNum))
                 return;
-            // Find the nth todo (by order) and mark it complete
             let count = 0;
             for (const [_id, todo] of this._todos) {
                 count++;
@@ -1302,23 +1053,11 @@ export class RalphTracker extends EventEmitter {
                 }
             }
         }
-        // Don't guess which todo to mark - let the checkbox detection handle it
     }
     /**
      * Check for multi-line patterns that might span line boundaries.
-     * Completion phrases can be split across PTY chunks.
-     *
-     * Handles cross-chunk promise tags by:
-     * 1. Checking combined buffer + new data for complete tags
-     * 2. Detecting partial tags at end of chunk and buffering
-     * 3. Clearing buffer when complete tag found or buffer gets stale
-     *
-     * @param data - The full data chunk (may contain multiple lines)
      */
     checkMultiLinePatterns(data) {
-        // Only try to complete a cross-chunk promise if we have a partial buffer.
-        // Without a partial buffer, complete tags are already handled by processLine
-        // via detectCompletionPhrase — re-detecting here would double-count.
         if (this._partialPromiseBuffer) {
             const combinedData = this._partialPromiseBuffer + data;
             const promiseMatch = combinedData.match(PROMISE_PATTERN);
@@ -1329,7 +1068,6 @@ export class RalphTracker extends EventEmitter {
                 return;
             }
         }
-        // Check for partial promise tag at end of data (for next chunk)
         const partialMatch = data.match(PROMISE_PARTIAL_PATTERN);
         if (partialMatch) {
             const partialContent = partialMatch[0];
@@ -1346,32 +1084,16 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Detect completion phrases in a line.
-     *
-     * Handles two formats:
-     * 1. Tagged: `<promise>PHRASE</promise>` - Processed via handleCompletionPhrase
-     * 2. Bare: Just `PHRASE` - Only if we already know the expected phrase
-     *
-     * Bare phrase detection avoids false positives by requiring:
-     * - The phrase was previously seen in tagged form
-     * - Line is standalone or ends with the phrase
-     * - Line doesn't look like prompt context
-     *
-     * @param line - Single line to check
      */
     detectCompletionPhrase(line) {
-        // First check for tagged phrase: <promise>PHRASE</promise>
         const match = line.match(PROMISE_PATTERN);
         if (match) {
             this.handleCompletionPhrase(match[1]);
             return;
         }
-        // If we have an expected completion phrase, also check for bare phrase
-        // This handles cases where Claude outputs "ALL_TASKS_DONE" without the tags
         const expectedPhrase = this._loopState.completionPhrase;
         if (expectedPhrase && line.toUpperCase().includes(expectedPhrase.toUpperCase())) {
-            // Avoid false positives: don't trigger on prompt context
             const isNotInPromptContext = !line.includes('<promise>') && !line.includes('output:');
-            // Also avoid triggering on "completion phrase is X" explanatory text
             const isNotExplanation = !line.toLowerCase().includes('completion phrase') && !line.toLowerCase().includes('output exactly');
             if (isNotInPromptContext && isNotExplanation) {
                 this.handleBareCompletionPhrase(expectedPhrase);
@@ -1380,37 +1102,17 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Handle a bare completion phrase (without XML tags).
-     *
-     * Only fires completion if:
-     * 1. The phrase was previously seen in tagged form (from prompt)
-     * 2. This is the first bare occurrence (prevents double-firing)
-     *
-     * When triggered:
-     * - Marks all todos as complete
-     * - Emits completionDetected event
-     * - Sets loop to inactive
-     *
-     * @param phrase - The completion phrase text
-     * @fires todoUpdate - If any todos marked complete
-     * @fires completionDetected - When completion triggered
-     * @fires loopUpdate - When loop state changes
      */
     handleBareCompletionPhrase(phrase) {
-        // Allow bare phrase detection if:
-        // 1. Loop is explicitly active (via startLoop()) - phrase was set programmatically
-        // 2. OR phrase was seen in tagged form (from terminal output)
         const taggedCount = this._completionPhraseCount.get(phrase) || 0;
         const loopExplicitlyActive = this._loopState.active;
         if (taggedCount === 0 && !loopExplicitlyActive)
             return;
-        // Track bare occurrences to avoid double-firing
         const bareKey = `bare:${phrase}`;
         const bareCount = (this._completionPhraseCount.get(bareKey) || 0) + 1;
         this._completionPhraseCount.set(bareKey, bareCount);
-        // Only fire once for bare phrase
         if (bareCount > 1)
             return;
-        // Mark all todos as complete (since we've reached the completion phrase)
         let updated = false;
         for (const todo of this._todos.values()) {
             if (todo.status !== 'completed') {
@@ -1421,36 +1123,26 @@ export class RalphTracker extends EventEmitter {
         if (updated) {
             this.emit('todoUpdate', this.todos);
         }
-        // Emit completion event
         this._loopState.active = false;
         this._loopState.lastActivity = Date.now();
         this.emit('completionDetected', phrase);
         this.emit('loopUpdate', this.loopState);
     }
     /**
-     * Handle a detected completion phrase
-     *
-     * Uses occurrence-based detection combined with confidence scoring
-     * to distinguish prompt from actual completion:
-     * - 1st occurrence: Store as expected phrase (likely in prompt)
-     * - 2nd occurrence OR high confidence: Emit completionDetected (actual completion)
-     * - If loop already active: Emit immediately (explicit loop start)
+     * Handle a detected completion phrase.
      */
     handleCompletionPhrase(phrase) {
         const count = (this._completionPhraseCount.get(phrase) || 0) + 1;
         this._completionPhraseCount.set(phrase, count);
         // Trim completion phrase map if it exceeds the limit
         if (this._completionPhraseCount.size > MAX_COMPLETION_PHRASE_ENTRIES) {
-            // Keep only the most important entries (current expected phrase and highest counts)
             const entries = Array.from(this._completionPhraseCount.entries());
-            entries.sort((a, b) => b[1] - a[1]); // Sort by count descending
+            entries.sort((a, b) => b[1] - a[1]);
             this._completionPhraseCount.clear();
-            // Keep top half of entries
             const keepCount = Math.floor(MAX_COMPLETION_PHRASE_ENTRIES / 2);
             for (let i = 0; i < Math.min(keepCount, entries.length); i++) {
                 this._completionPhraseCount.set(entries[i][0], entries[i][1]);
             }
-            // Always keep the expected phrase if set
             if (this._loopState.completionPhrase && !this._completionPhraseCount.has(this._loopState.completionPhrase)) {
                 this._completionPhraseCount.set(this._loopState.completionPhrase, 1);
             }
@@ -1459,23 +1151,16 @@ export class RalphTracker extends EventEmitter {
         if (!this._loopState.completionPhrase) {
             this._loopState.completionPhrase = phrase;
             this._loopState.lastActivity = Date.now();
-            // P1-002: Validate phrase and emit warning if risky
             this.validateCompletionPhrase(phrase);
             this.emit('loopUpdate', this.loopState);
         }
-        // Check for fuzzy match with primary phrase or any alternate phrase (P1-003)
-        // This handles minor variations like whitespace, case, underscores vs hyphens
+        // Check for fuzzy match with primary phrase or any alternate phrase
         const matchedPhrase = this.findMatchingCompletionPhrase(phrase);
         if (matchedPhrase) {
-            // Use the matched phrase (canonical) for tracking
             const canonicalCount = this._completionPhraseCount.get(matchedPhrase) || 0;
-            // Require 2nd+ occurrence of canonical phrase OR explicitly active loop.
-            // First occurrence (count=1) is the prompt echo — not actual completion.
             if (canonicalCount >= 2 || this._loopState.active) {
-                // Mark as completion
                 this._loopState.active = false;
                 this._loopState.lastActivity = Date.now();
-                // Mark all todos as complete
                 let updated = false;
                 for (const todo of this._todos.values()) {
                     if (todo.status !== 'completed') {
@@ -1491,9 +1176,7 @@ export class RalphTracker extends EventEmitter {
                 return;
             }
         }
-        // Emit completion if loop is active OR this is 2nd+ occurrence
         if (this._loopState.active || count >= 2) {
-            // Mark all todos as complete when completion phrase is detected
             let updated = false;
             for (const todo of this._todos.values()) {
                 if (todo.status !== 'completed') {
@@ -1512,39 +1195,17 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Check if two phrases match with fuzzy tolerance.
-     * Handles variations in:
-     * - Case (COMPLETE vs Complete)
-     * - Whitespace (TASK_DONE vs TASK DONE)
-     * - Separators (TASK_DONE vs TASK-DONE)
-     * - Minor typos with Levenshtein distance (COMPLET vs COMPLETE)
-     *
-     * @param phrase1 - First phrase to compare
-     * @param phrase2 - Second phrase to compare
-     * @param maxDistance - Maximum edit distance for fuzzy match (default: 2)
-     * @returns True if phrases are fuzzy-equal
      */
     isFuzzyPhraseMatch(phrase1, phrase2, maxDistance = 2) {
         return fuzzyPhraseMatch(phrase1, phrase2, maxDistance);
     }
     /**
      * Validate a completion phrase and emit warnings if it's risky.
-     *
-     * P1-002: Configurable false positive prevention
-     *
-     * Checks for:
-     * - Common/generic phrases (DONE, COMPLETE, etc.)
-     * - Short phrases (< MIN_RECOMMENDED_PHRASE_LENGTH)
-     * - Numeric-only phrases
-     *
-     * @param phrase - The completion phrase to validate
-     * @fires phraseValidationWarning - When a risky phrase is detected
      */
     validateCompletionPhrase(phrase) {
         const normalized = phrase.toUpperCase().replace(/[\s_\-.]+/g, '');
-        // Generate a suggested unique phrase
         const uniqueSuffix = Date.now().toString(36).slice(-4).toUpperCase();
         const suggestedPhrase = `${phrase}_${uniqueSuffix}`;
-        // Check for common phrases
         if (COMMON_COMPLETION_PHRASES.has(normalized)) {
             console.warn(`[RalphTracker] Warning: Completion phrase "${phrase}" is very common and may cause false positives. Consider using: "${suggestedPhrase}"`);
             this.emit('phraseValidationWarning', {
@@ -1554,7 +1215,6 @@ export class RalphTracker extends EventEmitter {
             });
             return;
         }
-        // Check for short phrases
         if (normalized.length < MIN_RECOMMENDED_PHRASE_LENGTH) {
             console.warn(`[RalphTracker] Warning: Completion phrase "${phrase}" is too short (${normalized.length} chars). Consider using: "${suggestedPhrase}"`);
             this.emit('phraseValidationWarning', {
@@ -1564,7 +1224,6 @@ export class RalphTracker extends EventEmitter {
             });
             return;
         }
-        // Check for numeric-only phrases
         if (/^\d+$/.test(normalized)) {
             console.warn(`[RalphTracker] Warning: Completion phrase "${phrase}" is numeric-only and may cause false positives. Consider using: "${suggestedPhrase}"`);
             this.emit('phraseValidationWarning', {
@@ -1576,12 +1235,6 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Activate the loop if not already active.
-     *
-     * Sets loop state to active and initializes counters.
-     * No-op if loop is already active.
-     *
-     * @returns True if loop was activated, false if already active
-     * @fires loopUpdate - When loop state changes
      */
     activateLoopIfNeeded() {
         if (this._loopState.active)
@@ -1597,131 +1250,77 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Detect loop start and status indicators.
-     *
-     * Patterns detected:
-     * - Ralph loop start commands (`/ralph-loop:ralph-loop`)
-     * - Loop start messages (`Loop started at`, `Starting Ralph loop`)
-     * - Max iterations setting (`max-iterations 50`)
-     * - Iteration progress (`Iteration 5/50`, `[5/50]`)
-     * - Elapsed time (`Elapsed: 2.5 hours`)
-     * - Cycle count (`cycle #5`, `respawn cycle #3`)
-     * - TodoWrite tool usage
-     *
-     * @param line - Single line to check
-     * @fires loopUpdate - When any loop state changes
      */
     detectLoopStatus(line) {
-        // Check for Ralph loop start command (/ralph-loop:ralph-loop)
-        // or generic loop start patterns ("Loop started at", "Starting Ralph loop")
         if (RALPH_START_PATTERN.test(line) || LOOP_START_PATTERN.test(line)) {
             this.activateLoopIfNeeded();
         }
-        // Check for max iterations setting
         const maxIterMatch = line.match(MAX_ITERATIONS_PATTERN);
         if (maxIterMatch) {
             const maxIter = parseInt(maxIterMatch[1], 10);
             if (!Number.isNaN(maxIter) && maxIter > 0) {
                 this._loopState.maxIterations = maxIter;
                 this._loopState.lastActivity = Date.now();
-                // Use debounced emit for settings changes
                 this.emitLoopUpdateDebounced();
             }
         }
-        // Check for iteration patterns: "Iteration 5/50", "[5/50]"
         const iterMatch = line.match(ITERATION_PATTERN);
         if (iterMatch) {
-            // Pattern captures: group 1&2 for "Iteration X/Y", group 3&4 for "[X/Y]"
             const currentIter = parseInt(iterMatch[1] || iterMatch[3], 10);
             const maxIterStr = iterMatch[2] || iterMatch[4];
             const maxIter = maxIterStr ? parseInt(maxIterStr, 10) : null;
             if (!Number.isNaN(currentIter)) {
                 this.activateLoopIfNeeded();
-                // Track iteration changes for stall detection
-                if (currentIter !== this._lastObservedIteration) {
-                    this._lastIterationChangeTime = Date.now();
-                    this._lastObservedIteration = currentIter;
-                    this._iterationStallWarned = false; // Reset warning on iteration change
-                    // P1-004: Reset circuit breaker on successful iteration progress
-                    // If we're making progress, the loop is healthy
-                    if (this._circuitBreaker.state === 'HALF_OPEN' ||
-                        this._circuitBreaker.consecutiveNoProgress > 0 ||
-                        this._circuitBreaker.consecutiveSameError > 0 ||
-                        this._circuitBreaker.consecutiveTestsFailure > 0) {
-                        this._circuitBreaker.consecutiveNoProgress = 0;
-                        this._circuitBreaker.consecutiveSameError = 0;
-                        this._circuitBreaker.lastProgressIteration = currentIter;
-                        if (this._circuitBreaker.state === 'HALF_OPEN') {
-                            this._circuitBreaker.state = 'CLOSED';
-                            this._circuitBreaker.reason = 'Iteration progress detected';
-                            this._circuitBreaker.reasonCode = 'progress_detected';
-                            this.emit('circuitBreakerUpdate', { ...this._circuitBreaker });
-                        }
-                    }
+                // Track iteration changes for stall detection and circuit breaker
+                if (currentIter !== this.stallDetector.getIterationStallMetrics().currentIteration) {
+                    this.stallDetector.notifyIterationChanged(currentIter);
+                    this.statusParser.notifyIterationProgress(currentIter);
                 }
                 this._loopState.cycleCount = currentIter;
+                // Notify sub-modules of cycle count
+                this.planTracker.notifyCycleCount(currentIter);
+                this.statusParser.setCycleCount(currentIter);
+                this.stallDetector.setLoopActive(true);
                 if (maxIter !== null && !Number.isNaN(maxIter)) {
                     this._loopState.maxIterations = maxIter;
                 }
                 this._loopState.lastActivity = Date.now();
-                // Use debounced emit for rapid iteration updates
                 this.emitLoopUpdateDebounced();
             }
         }
-        // Check for elapsed time
         const elapsedMatch = line.match(ELAPSED_TIME_PATTERN);
         if (elapsedMatch) {
             this._loopState.elapsedHours = parseFloat(elapsedMatch[1]);
             this._loopState.lastActivity = Date.now();
-            // Use debounced emit for elapsed time updates
             this.emitLoopUpdateDebounced();
         }
-        // Check for cycle count (legacy pattern)
         const cycleMatch = line.match(CYCLE_PATTERN);
         if (cycleMatch) {
             const cycleNum = parseInt(cycleMatch[1] || cycleMatch[2], 10);
             if (!Number.isNaN(cycleNum) && cycleNum > this._loopState.cycleCount) {
                 this._loopState.cycleCount = cycleNum;
                 this._loopState.lastActivity = Date.now();
-                // Use debounced emit for cycle updates
                 this.emitLoopUpdateDebounced();
             }
         }
-        // Check for TodoWrite tool usage - indicates active task tracking
         if (TODOWRITE_PATTERN.test(line)) {
             this._loopState.lastActivity = Date.now();
-            // Don't emit update just for activity, let todo detection handle it
         }
     }
     /**
      * Detect todo items in various formats from Claude Code output.
-     *
-     * Supported formats:
-     * - Format 1: Checkbox markdown (`- [ ] Task`, `- [x] Task`)
-     * - Format 2: Indicator icons (`Todo: ☐ Task`, `Todo: ✓ Task`)
-     * - Format 3: Status in parentheses (`- Task (pending)`)
-     * - Format 4: Native TodoWrite (`☐ Task`, `☒ Task`, `◐ Task`)
-     *
-     * Uses quick pre-check to skip lines that can't contain todos.
-     * Excludes tool invocations and Claude commentary patterns.
-     *
-     * @param line - Single line to check
-     * @fires todoUpdate - When any todos are detected or updated
      */
     detectTodoItems(line) {
-        // Pre-compute which pattern categories might match (60-75% faster)
         const hasCheckbox = line.includes('[');
         const hasTodoIndicator = line.includes('Todo:');
         const hasNativeCheckbox = line.includes('☐') || line.includes('☒') || line.includes('◐') || line.includes('✓');
         const hasStatus = line.includes('(pending)') || line.includes('(in_progress)') || line.includes('(completed)');
         const hasCheckmark = line.includes('✔');
-        // Quick check: skip lines that can't possibly contain todos
         if (!hasCheckbox && !hasTodoIndicator && !hasNativeCheckbox && !hasStatus && !hasCheckmark) {
             return;
         }
         let updated = false;
         let match;
-        // Format 1: Checkbox format "- [ ] Task" or "- [x] Task"
-        // Only scan if line contains '[' character
         if (hasCheckbox) {
             TODO_CHECKBOX_PATTERN.lastIndex = 0;
             while ((match = TODO_CHECKBOX_PATTERN.exec(line)) !== null) {
@@ -1732,8 +1331,6 @@ export class RalphTracker extends EventEmitter {
                 updated = true;
             }
         }
-        // Format 2: Todo with indicator icons
-        // Only scan if line contains 'Todo:' prefix
         if (hasTodoIndicator) {
             TODO_INDICATOR_PATTERN.lastIndex = 0;
             while ((match = TODO_INDICATOR_PATTERN.exec(line)) !== null) {
@@ -1744,8 +1341,6 @@ export class RalphTracker extends EventEmitter {
                 updated = true;
             }
         }
-        // Format 3: Status in parentheses
-        // Only scan if line contains status in parentheses
         if (hasStatus) {
             TODO_STATUS_PATTERN.lastIndex = 0;
             while ((match = TODO_STATUS_PATTERN.exec(line)) !== null) {
@@ -1755,18 +1350,14 @@ export class RalphTracker extends EventEmitter {
                 updated = true;
             }
         }
-        // Format 4: Claude Code native TodoWrite output (☐, ☒, ◐)
-        // Only scan if line contains native checkbox icons
         if (hasNativeCheckbox) {
             TODO_NATIVE_PATTERN.lastIndex = 0;
             while ((match = TODO_NATIVE_PATTERN.exec(line)) !== null) {
                 const icon = match[1];
                 const content = match[2].trim();
-                // Skip if content matches exclude patterns (tool invocations, commentary)
                 const shouldExclude = TODO_EXCLUDE_PATTERNS.some((pattern) => pattern.test(content));
                 if (shouldExclude)
                     continue;
-                // Skip if content is too short or looks like partial garbage
                 if (content.length < 5)
                     continue;
                 const status = this.iconToStatus(icon);
@@ -1774,10 +1365,7 @@ export class RalphTracker extends EventEmitter {
                 updated = true;
             }
         }
-        // Format 5: Claude Code checkmark-based TodoWrite output (✔ Task #N)
-        // Handles: "✔ Task #N created: content", "✔ #N content", "✔ Task #N updated: status → X"
         if (hasCheckmark) {
-            // Task creation: "✔ Task #1 created: Fix the bug"
             TODO_TASK_CREATED_PATTERN.lastIndex = 0;
             while ((match = TODO_TASK_CREATED_PATTERN.exec(line)) !== null) {
                 const taskNum = parseInt(match[1], 10);
@@ -1789,13 +1377,11 @@ export class RalphTracker extends EventEmitter {
                     updated = true;
                 }
             }
-            // Task summary: "✔ #1 Fix the bug"
             TODO_TASK_SUMMARY_PATTERN.lastIndex = 0;
             while ((match = TODO_TASK_SUMMARY_PATTERN.exec(line)) !== null) {
                 const taskNum = parseInt(match[1], 10);
                 const content = match[2].trim();
                 if (content.length >= 5) {
-                    // Only register if not already known from a "created" line
                     if (!this._taskNumberToContent.has(taskNum)) {
                         this._taskNumberToContent.set(taskNum, content);
                         this.enforceTaskMappingLimit();
@@ -1804,7 +1390,6 @@ export class RalphTracker extends EventEmitter {
                     updated = true;
                 }
             }
-            // Status update: "✔ Task #1 updated: status → completed"
             TODO_TASK_STATUS_PATTERN.lastIndex = 0;
             while ((match = TODO_TASK_STATUS_PATTERN.exec(line)) !== null) {
                 const taskNum = parseInt(match[1], 10);
@@ -1816,19 +1401,15 @@ export class RalphTracker extends EventEmitter {
                     updated = true;
                 }
             }
-            // Plain checkmark: "✔ Create hello.txt" (no task number)
-            // Only match if numbered patterns didn't already match on this line
             if (!updated) {
                 TODO_PLAIN_CHECKMARK_PATTERN.lastIndex = 0;
                 while ((match = TODO_PLAIN_CHECKMARK_PATTERN.exec(line)) !== null) {
                     const content = match[1].trim();
-                    // Skip if content matches exclude patterns
                     const shouldExclude = TODO_EXCLUDE_PATTERNS.some((pattern) => pattern.test(content));
                     if (shouldExclude)
                         continue;
                     if (content.length < 5)
                         continue;
-                    // Skip status/created/updated prefixed content (already handled above)
                     if (/^(Task\s*#\d+|#\d+)\s/.test(content))
                         continue;
                     this.upsertTodo(content, 'completed');
@@ -1837,68 +1418,46 @@ export class RalphTracker extends EventEmitter {
             }
         }
         if (updated) {
-            // Use debounced emit to batch rapid todo updates and reduce UI jitter
             this.emitTodoUpdateDebounced();
         }
     }
     /**
      * Convert a todo icon character to its corresponding status.
-     *
-     * Icon mappings:
-     * - Completed: `✓`, `✅`, `☒`, `◉`, `●`
-     * - In Progress: `◐`, `⏳`, `⌛`, `🔄`
-     * - Pending: `☐`, `○`, and anything else (default)
-     *
-     * @param icon - Single character icon
-     * @returns Corresponding RalphTodoStatus
      */
     iconToStatus(icon) {
         switch (icon) {
             case '✓':
             case '✅':
-            case '☒': // Claude Code checked checkbox
-            case '◉': // Filled circle (completed)
-            case '●': // Solid circle (completed)
+            case '☒':
+            case '◉':
+            case '●':
                 return 'completed';
-            case '◐': // Half-filled circle (in progress)
+            case '◐':
             case '⏳':
             case '⌛':
             case '🔄':
                 return 'in_progress';
-            case '☐': // Claude Code empty checkbox
-            case '○': // Empty circle
+            case '☐':
+            case '○':
             default:
                 return 'pending';
         }
     }
     /**
      * Parse priority from todo content.
-     * P1-008: Enhanced keyword-based priority inference.
-     *
-     * Priority levels:
-     * - P0 (Critical): Explicit P0, "critical", "blocker", "urgent", "security", "crash", "broken"
-     * - P1 (High): Explicit P1, "important", "high priority", "bug", "fix", "error", "fail"
-     * - P2 (Medium): Explicit P2, "nice to have", "low priority", "refactor", "cleanup", "improve"
-     *
-     * @param content - Todo content text
-     * @returns Parsed priority level or null
      */
     parsePriority(content) {
         const upper = content.toUpperCase();
-        // Check P0 first (highest priority wins)
-        // Uses pre-compiled module-level patterns for performance
         for (const pattern of P0_PRIORITY_PATTERNS) {
             if (pattern.test(upper)) {
                 return 'P0';
             }
         }
-        // Check P1
         for (const pattern of P1_PRIORITY_PATTERNS) {
             if (pattern.test(upper)) {
                 return 'P1';
             }
         }
-        // Check P2
         for (const pattern of P2_PRIORITY_PATTERNS) {
             if (pattern.test(upper)) {
                 return 'P2';
@@ -1908,82 +1467,51 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Add a new todo item or update an existing one.
-     *
-     * Behavior:
-     * - Content is cleaned (ANSI removed, whitespace collapsed)
-     * - Content under 5 chars is skipped
-     * - ID is generated from normalized content (stable hash)
-     * - Priority is parsed from content (P0/P1/P2, Critical, High Priority, etc.)
-     * - Existing item: Updates status and timestamp
-     * - New item: Adds to map, evicts oldest if at MAX_TODOS_PER_SESSION
-     *
-     * @param content - Raw todo content text
-     * @param status - Status to set
      */
     upsertTodo(content, status) {
-        // Skip empty or whitespace-only content
         if (!content || !content.trim())
             return;
-        // Clean content: remove ANSI codes, collapse whitespace, trim
-        const cleanContent = content
-            .replace(ANSI_ESCAPE_PATTERN_SIMPLE, '') // Remove ANSI escape codes
-            .replace(/\s+/g, ' ') // Collapse whitespace
-            .trim();
+        const cleanContent = content.replace(ANSI_ESCAPE_PATTERN_SIMPLE, '').replace(/\s+/g, ' ').trim();
         if (cleanContent.length < 5)
-            return; // Skip very short content
-        // Parse priority from content
+            return;
         const priority = this.parsePriority(cleanContent);
-        // P1-009: Estimate complexity for duration tracking
         const estimatedComplexity = this.estimateComplexity(cleanContent);
-        // Generate a stable ID from normalized content
         const id = this.generateTodoId(cleanContent);
         const existing = this._todos.get(id);
         if (existing) {
-            // P1-009: Track status transitions for progress estimation
             const wasCompleted = existing.status === 'completed';
             const isNowCompleted = status === 'completed';
             const wasInProgress = existing.status === 'in_progress';
             const isNowInProgress = status === 'in_progress';
-            // Update existing todo (exact match by ID)
             existing.status = status;
             existing.detectedAt = Date.now();
-            // Update priority if parsed (don't overwrite with null)
             if (priority)
                 existing.priority = priority;
-            // Update complexity estimate if not already set
             if (!existing.estimatedComplexity) {
                 existing.estimatedComplexity = estimatedComplexity;
             }
-            // P1-009: Track completion time
             if (!wasCompleted && isNowCompleted) {
                 this.recordTodoCompletion(id);
             }
-            // P1-009: Start tracking when status changes to in_progress
             if (!wasInProgress && isNowInProgress) {
                 this.startTrackingTodo(id);
             }
         }
         else {
-            // P1-007: Check for similar existing todo (deduplication)
             const similar = this.findSimilarTodo(cleanContent);
             if (similar) {
-                // P1-009: Track status transitions on similar todo
                 const wasCompleted = similar.status === 'completed';
                 const isNowCompleted = status === 'completed';
                 const wasInProgress = similar.status === 'in_progress';
                 const isNowInProgress = status === 'in_progress';
-                // Update similar todo instead of creating duplicate
                 similar.status = status;
                 similar.detectedAt = Date.now();
-                // Update priority if new content has priority and existing doesn't
                 if (priority && !similar.priority) {
                     similar.priority = priority;
                 }
-                // Keep the longer/more descriptive content
                 if (cleanContent.length > similar.content.length) {
                     similar.content = cleanContent;
                 }
-                // P1-009: Track completion time
                 if (!wasCompleted && isNowCompleted) {
                     this.recordTodoCompletion(similar.id);
                 }
@@ -1992,20 +1520,17 @@ export class RalphTracker extends EventEmitter {
                 }
                 return;
             }
-            // Add new todo with guaranteed eviction if at capacity
-            // Use while loop to ensure we always have room (handles edge case where findOldestTodo returns undefined)
             while (this._todos.size >= MAX_TODOS_PER_SESSION) {
                 const oldest = this.findOldestTodo();
                 if (oldest) {
                     this._todos.delete(oldest.id);
                 }
                 else {
-                    // Safety valve: if somehow no oldest found, clear a random entry
                     const firstKey = this._todos.keys().next().value;
                     if (firstKey)
                         this._todos.delete(firstKey);
                     else
-                        break; // Map is empty somehow, exit loop
+                        break;
                 }
             }
             const estimatedDurationMs = this.getEstimatedDuration(estimatedComplexity);
@@ -2018,7 +1543,6 @@ export class RalphTracker extends EventEmitter {
                 estimatedComplexity,
                 estimatedDurationMs,
             });
-            // P1-009: Start tracking if already in_progress
             if (status === 'in_progress') {
                 this.startTrackingTodo(id);
             }
@@ -2026,71 +1550,39 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Normalize todo content for consistent matching.
-     *
-     * Normalization steps:
-     * 1. Collapse multiple whitespace to single space
-     * 2. Remove special characters (keep alphanumeric + basic punctuation)
-     * 3. Trim whitespace
-     * 4. Convert to lowercase
-     *
-     * This prevents duplicate todos from terminal rendering artifacts.
-     *
-     * @param content - Raw todo content
-     * @returns Normalized lowercase string
      */
     normalizeTodoContent(content) {
         if (!content)
             return '';
         return content
-            .replace(/\s+/g, ' ') // Collapse whitespace
-            .replace(/[^a-zA-Z0-9\s.,!?'"-]/g, '') // Remove special chars (keep punctuation)
+            .replace(/\s+/g, ' ')
+            .replace(/[^a-zA-Z0-9\s.,!?'"-]/g, '')
             .trim()
             .toLowerCase();
     }
     /**
      * Calculate similarity between two strings.
-     *
-     * P1-007: Uses a hybrid approach combining:
-     * 1. Levenshtein-based similarity for edit-distance tolerance
-     * 2. Bigram (Dice coefficient) for reordering tolerance
-     * Returns the maximum of both methods.
-     *
-     * @param str1 - First string (will be normalized)
-     * @param str2 - Second string (will be normalized)
-     * @returns Similarity score from 0.0 (no similarity) to 1.0 (identical)
      */
     calculateSimilarity(str1, str2) {
         const norm1 = this.normalizeTodoContent(str1);
         const norm2 = this.normalizeTodoContent(str2);
-        // Identical after normalization
         if (norm1 === norm2)
             return 1.0;
-        // If either is empty, no similarity
         if (!norm1 || !norm2)
             return 0.0;
-        // Method 1: Levenshtein-based similarity (good for typos/minor edits)
         const levenshteinSim = stringSimilarity(norm1, norm2);
-        // Method 2: Bigram/Dice similarity (good for word reordering)
         const bigramSim = this.calculateBigramSimilarity(norm1, norm2);
-        // Return the higher of the two scores
         return Math.max(levenshteinSim, bigramSim);
     }
     /**
      * Calculate bigram (Dice coefficient) similarity.
-     * Good for detecting near-duplicates with word reordering.
-     *
-     * @param norm1 - First normalized string
-     * @param norm2 - Second normalized string
-     * @returns Similarity score from 0.0 to 1.0
      */
     calculateBigramSimilarity(norm1, norm2) {
-        // Short strings: use simple character overlap
         if (norm1.length < 3 || norm2.length < 3) {
             const shorter = norm1.length <= norm2.length ? norm1 : norm2;
             const longer = norm1.length > norm2.length ? norm1 : norm2;
             return longer.includes(shorter) ? 0.9 : 0.0;
         }
-        // Extract bigrams (pairs of consecutive characters)
         const getBigrams = (s) => {
             const bigrams = new Set();
             for (let i = 0; i < s.length - 1; i++) {
@@ -2100,14 +1592,12 @@ export class RalphTracker extends EventEmitter {
         };
         const bigrams1 = getBigrams(norm1);
         const bigrams2 = getBigrams(norm2);
-        // Count intersection
         let intersection = 0;
         for (const bigram of bigrams1) {
             if (bigrams2.has(bigram)) {
                 intersection++;
             }
         }
-        // Dice coefficient: 2 * intersection / (total bigrams)
         const totalBigrams = bigrams1.size + bigrams2.size;
         if (totalBigrams === 0)
             return 0.0;
@@ -2115,32 +1605,18 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Find an existing todo that is similar to the given content.
-     * Returns the most similar todo if similarity >= threshold.
-     *
-     * Deduplication is intentionally conservative:
-     * - Short strings (< 30 chars): require 95% similarity (nearly identical)
-     * - Medium strings (30-60 chars): require 90% similarity
-     * - Longer strings: use default 85% threshold
-     *
-     * This prevents over-aggressive deduplication of brief, numbered items
-     * like "Task 1", "Task 2" while still catching true duplicates.
-     *
-     * @param content - New todo content to check against existing todos
-     * @returns Similar todo item if found, undefined otherwise
      */
     findSimilarTodo(content) {
         const normalized = this.normalizeTodoContent(content);
-        // Determine appropriate threshold based on string length
-        // Shorter strings need higher threshold to avoid false positives
         let threshold;
         if (normalized.length < 30) {
-            threshold = 0.95; // Very strict for short strings
+            threshold = 0.95;
         }
         else if (normalized.length < 60) {
-            threshold = 0.9; // Strict for medium strings
+            threshold = 0.9;
         }
         else {
-            threshold = TODO_SIMILARITY_THRESHOLD; // 0.85 for longer strings
+            threshold = TODO_SIMILARITY_THRESHOLD;
         }
         let bestMatch;
         let bestSimilarity = 0;
@@ -2156,14 +1632,9 @@ export class RalphTracker extends EventEmitter {
     // ========== P1-009: Progress Estimation Methods ==========
     /**
      * Estimate complexity of a todo based on content keywords.
-     * Used for duration estimation.
-     *
-     * @param content - Todo content text
-     * @returns Complexity category
      */
     estimateComplexity(content) {
         const lower = content.toLowerCase();
-        // Trivial: Simple fixes, typos, documentation
         const trivialPatterns = [
             /\btypo\b/,
             /\bspelling\b/,
@@ -2172,7 +1643,6 @@ export class RalphTracker extends EventEmitter {
             /\brename\b/,
             /\bformat(?:ting)?\b/,
         ];
-        // Complex: Architecture, refactoring, security, testing
         const complexPatterns = [
             /\barchitect(?:ure)?\b/,
             /\brefactor\b/,
@@ -2185,7 +1655,6 @@ export class RalphTracker extends EventEmitter {
             /\boptimiz(?:e|ation)\b/,
             /\bmultiple\s+files?\b/,
         ];
-        // Moderate: Bugs, features, enhancements
         const moderatePatterns = [/\bbug\b/, /\bfeature\b/, /\benhance(?:ment)?\b/, /\bimplement\b/, /\badd\b/, /\bfix\b/];
         for (const pattern of complexPatterns) {
             if (pattern.test(lower))
@@ -2203,13 +1672,8 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Get estimated duration for a complexity level (ms).
-     * Based on historical patterns from similar tasks.
-     *
-     * @param complexity - Complexity category
-     * @returns Estimated duration in milliseconds
      */
     getEstimatedDuration(complexity) {
-        // If we have historical data, use average adjusted by complexity
         const avgTime = this.getAverageCompletionTime();
         if (avgTime !== null) {
             const multipliers = {
@@ -2220,18 +1684,16 @@ export class RalphTracker extends EventEmitter {
             };
             return Math.round(avgTime * multipliers[complexity]);
         }
-        // Default estimates (in ms) based on typical task durations
         const defaults = {
-            trivial: 1 * 60 * 1000, // 1 minute
-            simple: 3 * 60 * 1000, // 3 minutes
-            moderate: 10 * 60 * 1000, // 10 minutes
-            complex: 30 * 60 * 1000, // 30 minutes
+            trivial: 1 * 60 * 1000,
+            simple: 3 * 60 * 1000,
+            moderate: 10 * 60 * 1000,
+            complex: 30 * 60 * 1000,
         };
         return defaults[complexity];
     }
     /**
      * Get average completion time from historical data.
-     * @returns Average time in ms, or null if no data
      */
     getAverageCompletionTime() {
         if (this._completionTimes.length === 0)
@@ -2241,14 +1703,12 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Record a todo completion for progress tracking.
-     * @param todoId - ID of the completed todo
      */
     recordTodoCompletion(todoId) {
         const startTime = this._todoStartTimes.get(todoId);
         if (startTime) {
             const duration = Date.now() - startTime;
             this._completionTimes.push(duration);
-            // Keep only recent completion times
             while (this._completionTimes.length > RalphTracker.MAX_COMPLETION_TIMES) {
                 this._completionTimes.shift();
             }
@@ -2257,23 +1717,17 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Start tracking a todo for duration estimation.
-     * @param todoId - ID of the todo being started
      */
     startTrackingTodo(todoId) {
         if (!this._todoStartTimes.has(todoId)) {
             this._todoStartTimes.set(todoId, Date.now());
         }
-        // Initialize session tracking if needed
         if (this._todosStartedAt === 0) {
             this._todosStartedAt = Date.now();
         }
     }
     /**
      * Get progress estimation for the todo list.
-     * P1-009: Provides completion percentage, estimated remaining time,
-     * and projected completion timestamp.
-     *
-     * @returns Progress estimation object
      */
     getTodoProgress() {
         const todos = Array.from(this._todos.values());
@@ -2282,19 +1736,16 @@ export class RalphTracker extends EventEmitter {
         const inProgress = todos.filter((t) => t.status === 'in_progress').length;
         const pending = todos.filter((t) => t.status === 'pending').length;
         const percentComplete = total > 0 ? Math.round((completed / total) * 100) : 0;
-        // Calculate estimated remaining time
         let estimatedRemainingMs = null;
         let avgCompletionTimeMs = null;
         let projectedCompletionAt = null;
         avgCompletionTimeMs = this.getAverageCompletionTime();
         if (total > 0 && completed > 0) {
-            // Method 1: Use historical average if available
             if (avgCompletionTimeMs !== null) {
                 const remaining = total - completed;
                 estimatedRemainingMs = remaining * avgCompletionTimeMs;
             }
             else {
-                // Method 2: Calculate based on elapsed time and progress
                 const elapsed = Date.now() - this._todosStartedAt;
                 if (elapsed > 0 && completed > 0) {
                     const timePerTodo = elapsed / completed;
@@ -2303,13 +1754,11 @@ export class RalphTracker extends EventEmitter {
                     estimatedRemainingMs = Math.round(remaining * timePerTodo);
                 }
             }
-            // Calculate projected completion timestamp
             if (estimatedRemainingMs !== null) {
                 projectedCompletionAt = Date.now() + estimatedRemainingMs;
             }
         }
         else if (total > 0 && completed === 0) {
-            // No completions yet - use complexity-based estimates
             let totalEstimate = 0;
             for (const todo of todos) {
                 if (todo.status !== 'completed') {
@@ -2331,35 +1780,17 @@ export class RalphTracker extends EventEmitter {
             projectedCompletionAt,
         };
     }
-    /**
-     * Generate a stable ID from todo content using djb2 hash.
-     *
-     * Uses the djb2 hash algorithm for good distribution across strings.
-     * Content is normalized first to prevent duplicates from terminal artifacts.
-     *
-     * @param content - Todo content text
-     * @returns Stable ID in format `todo-{hash}` (base36 encoded)
-     */
     /**
      * Generate a stable ID from todo content using content hashing.
-     *
-     * P1-007: Uses centralized todoContentHash utility for consistency
-     * with deduplication logic.
-     *
-     * @param content - Todo content text
-     * @returns Unique ID string prefixed with "todo-"
      */
     generateTodoId(content) {
         if (!content)
             return 'todo-empty';
-        // Use centralized hashing utility
         const hash = todoContentHash(content);
         return `todo-${hash}`;
     }
     /**
      * Find the todo item with the oldest detectedAt timestamp.
-     * Used for LRU eviction when at MAX_TODOS_PER_SESSION limit.
-     * @returns Oldest todo item, or undefined if map is empty
      */
     findOldestTodo() {
         let oldest;
@@ -2372,7 +1803,6 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Conditionally run cleanup, throttled to CLEANUP_THROTTLE_MS.
-     * Prevents cleanup from running on every data chunk (performance).
      */
     maybeCleanupExpiredTodos() {
         const now = Date.now();
@@ -2384,8 +1814,6 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Remove todo items older than TODO_EXPIRY_MS.
-     * Emits todoUpdate if any items were removed.
-     * @fires todoUpdate - When expired items are removed
      */
     cleanupExpiredTodos() {
         const now = Date.now();
@@ -2404,19 +1832,9 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Programmatically start a loop (external API).
-     *
-     * Use when starting a loop from outside terminal detection,
-     * such as from a user action or API call.
-     *
-     * Automatically enables the tracker if not already enabled.
-     *
-     * @param completionPhrase - Optional phrase that signals completion
-     * @param maxIterations - Optional maximum iteration count
-     * @fires enabled - If tracker was disabled
-     * @fires loopUpdate - When loop state changes
      */
     startLoop(completionPhrase, maxIterations) {
-        this.enable(); // Ensure tracker is enabled
+        this.enable();
         this._loopState.active = true;
         this._loopState.startedAt = Date.now();
         this._loopState.cycleCount = 0;
@@ -2430,9 +1848,6 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Update the maximum iteration count (external API).
-     *
-     * @param maxIterations - New max iterations, or null to remove limit
-     * @fires loopUpdate - When loop state changes
      */
     setMaxIterations(maxIterations) {
         this._loopState.maxIterations = maxIterations;
@@ -2440,11 +1855,7 @@ export class RalphTracker extends EventEmitter {
         this.emit('loopUpdate', this.loopState);
     }
     /**
-     * Configure the tracker from external state (e.g. ralph plugin config).
-     * Only updates fields that are provided, leaving others unchanged.
-     *
-     * @param config - Partial configuration to apply
-     * @fires loopUpdate - When loop state changes
+     * Configure the tracker from external state.
      */
     configure(config) {
         if (config.enabled !== undefined) {
@@ -2461,11 +1872,6 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Programmatically stop the loop (external API).
-     *
-     * Sets loop to inactive. Does not disable the tracker
-     * or clear todos - use reset() or clear() for that.
-     *
-     * @fires loopUpdate - When loop state changes
      */
     stopLoop() {
         this._loopState.active = false;
@@ -2474,12 +1880,10 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Enforce size limit on _taskNumberToContent map.
-     * Removes lowest task numbers (oldest tasks) when limit exceeded.
      */
     enforceTaskMappingLimit() {
         if (this._taskNumberToContent.size <= MAX_TASK_MAPPINGS)
             return;
-        // Sort keys and remove lowest (oldest) task numbers
         const sortedKeys = Array.from(this._taskNumberToContent.keys()).sort((a, b) => a - b);
         const keysToRemove = sortedKeys.slice(0, this._taskNumberToContent.size - MAX_TASK_MAPPINGS);
         for (const key of keysToRemove) {
@@ -2488,21 +1892,12 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Clear all state and disable the tracker.
-     *
-     * Use when the session is cleared or closed.
-     * Resets everything to initial disabled state.
-     *
-     * @fires loopUpdate - With initial state
-     * @fires todoUpdate - With empty array
      */
     clear() {
-        // Clear debounce timers to prevent stale emissions after clear
         this.clearDebounceTimers();
-        // Stop fix plan file watcher to prevent memory leak
-        this.stopWatchingFixPlan();
-        // Stop iteration stall detection timer to prevent leak
-        this.stopIterationStallDetection();
-        this._loopState = createInitialRalphTrackerState(); // This sets enabled: false
+        this.fixPlanWatcher.stop();
+        this.stallDetector.stopIterationStallDetection();
+        this._loopState = createInitialRalphTrackerState();
         this._todos.clear();
         this._taskNumberToContent.clear();
         this._todoStartTimes.clear();
@@ -2510,26 +1905,15 @@ export class RalphTracker extends EventEmitter {
         this._lineBuffer = '';
         this._partialPromiseBuffer = '';
         this._completionPhraseCount.clear();
-        // Clear RALPH_STATUS block and circuit breaker state
-        this._statusBlockBuffer = [];
-        this._inStatusBlock = false;
-        this._lastStatusBlock = null;
-        this._completionIndicators = 0;
-        this._exitGateMet = false;
-        this._totalFilesModified = 0;
-        this._totalTasksCompleted = 0;
-        this._circuitBreaker = createInitialCircuitBreakerStatus();
+        // Clear sub-module state
+        this.statusParser.fullReset();
+        this.planTracker.fullReset();
+        this.stallDetector.reset();
         this.emit('loopUpdate', this.loopState);
         this.emit('todoUpdate', this.todos);
     }
     /**
      * Get aggregated statistics about tracked todos.
-     *
-     * @returns Object with counts by status:
-     *   - total: Total number of tracked todos
-     *   - pending: Todos not yet started
-     *   - inProgress: Todos currently in progress
-     *   - completed: Finished todos
      */
     getTodoStats() {
         let pending = 0;
@@ -2557,786 +1941,38 @@ export class RalphTracker extends EventEmitter {
     }
     /**
      * Restore tracker state from persisted data.
-     *
-     * Use after loading state from StateStore. Handles backwards
-     * compatibility by defaulting missing `enabled` flag to false.
-     *
-     * Note: Does not emit events (caller should handle if needed).
-     *
-     * @param loopState - Persisted loop state object
-     * @param todos - Persisted todo items array
      */
     restoreState(loopState, todos) {
-        // Ensure enabled flag exists (backwards compatibility)
         this._loopState = {
             ...loopState,
-            enabled: loopState.enabled ?? false, // Override after spread for backwards compat
+            enabled: loopState.enabled ?? false,
         };
         this._todos.clear();
         for (const todo of todos) {
-            // Backwards compatibility: ensure priority field exists
             this._todos.set(todo.id, {
                 ...todo,
                 priority: todo.priority ?? null,
             });
         }
     }
-    // ========== RALPH_STATUS Block Detection ==========
-    /**
-     * Process a line for RALPH_STATUS block detection.
-     * Buffers lines between ---RALPH_STATUS--- and ---END_RALPH_STATUS---
-     * then parses the complete block.
-     *
-     * @param line - Single line to process (already trimmed)
-     * @fires statusBlockDetected - When a complete block is parsed
-     */
-    processStatusBlockLine(line) {
-        // Check for block start
-        if (RALPH_STATUS_START_PATTERN.test(line)) {
-            this._inStatusBlock = true;
-            this._statusBlockBuffer = [];
-            return;
-        }
-        // Check for block end
-        if (this._inStatusBlock && RALPH_STATUS_END_PATTERN.test(line)) {
-            this._inStatusBlock = false;
-            this.parseStatusBlock(this._statusBlockBuffer);
-            this._statusBlockBuffer = [];
-            return;
-        }
-        // Buffer lines while in block
-        if (this._inStatusBlock) {
-            this._statusBlockBuffer.push(line);
-        }
-    }
-    /**
-     * Parse buffered RALPH_STATUS block lines into structured data.
-     *
-     * P1-004: Enhanced with schema validation and error recovery
-     *
-     * @param lines - Array of lines between block markers
-     * @fires statusBlockDetected - When parsing succeeds
-     */
-    parseStatusBlock(lines) {
-        const block = {
-            parsedAt: Date.now(),
-        };
-        const parseErrors = [];
-        const unknownFields = [];
-        for (const line of lines) {
-            const trimmedLine = line.trim();
-            if (!trimmedLine)
-                continue;
-            // Track whether this line matched any known field
-            let matched = false;
-            // STATUS field (required)
-            const statusMatch = trimmedLine.match(RALPH_STATUS_FIELD_PATTERN);
-            if (statusMatch) {
-                const value = statusMatch[1].toUpperCase();
-                if (['IN_PROGRESS', 'COMPLETE', 'BLOCKED'].includes(value)) {
-                    block.status = value;
-                }
-                else {
-                    parseErrors.push(`Invalid STATUS value: "${value}". Expected: IN_PROGRESS, COMPLETE, or BLOCKED`);
-                }
-                matched = true;
-            }
-            // TASKS_COMPLETED_THIS_LOOP field
-            const tasksMatch = trimmedLine.match(RALPH_TASKS_COMPLETED_PATTERN);
-            if (tasksMatch) {
-                const value = parseInt(tasksMatch[1], 10);
-                if (!Number.isNaN(value) && value >= 0) {
-                    block.tasksCompletedThisLoop = value;
-                }
-                else {
-                    parseErrors.push(`Invalid TASKS_COMPLETED_THIS_LOOP value: "${tasksMatch[1]}". Expected: non-negative integer`);
-                }
-                matched = true;
-            }
-            // FILES_MODIFIED field
-            const filesMatch = trimmedLine.match(RALPH_FILES_MODIFIED_PATTERN);
-            if (filesMatch) {
-                const value = parseInt(filesMatch[1], 10);
-                if (!Number.isNaN(value) && value >= 0) {
-                    block.filesModified = value;
-                }
-                else {
-                    parseErrors.push(`Invalid FILES_MODIFIED value: "${filesMatch[1]}". Expected: non-negative integer`);
-                }
-                matched = true;
-            }
-            // TESTS_STATUS field
-            const testsMatch = trimmedLine.match(RALPH_TESTS_STATUS_PATTERN);
-            if (testsMatch) {
-                const value = testsMatch[1].toUpperCase();
-                if (['PASSING', 'FAILING', 'NOT_RUN'].includes(value)) {
-                    block.testsStatus = value;
-                }
-                else {
-                    parseErrors.push(`Invalid TESTS_STATUS value: "${value}". Expected: PASSING, FAILING, or NOT_RUN`);
-                }
-                matched = true;
-            }
-            // WORK_TYPE field
-            const workMatch = trimmedLine.match(RALPH_WORK_TYPE_PATTERN);
-            if (workMatch) {
-                const value = workMatch[1].toUpperCase();
-                if (['IMPLEMENTATION', 'TESTING', 'DOCUMENTATION', 'REFACTORING'].includes(value)) {
-                    block.workType = value;
-                }
-                else {
-                    parseErrors.push(`Invalid WORK_TYPE value: "${value}". Expected: IMPLEMENTATION, TESTING, DOCUMENTATION, or REFACTORING`);
-                }
-                matched = true;
-            }
-            // EXIT_SIGNAL field
-            const exitMatch = trimmedLine.match(RALPH_EXIT_SIGNAL_PATTERN);
-            if (exitMatch) {
-                block.exitSignal = exitMatch[1].toLowerCase() === 'true';
-                matched = true;
-            }
-            // RECOMMENDATION field
-            const recMatch = trimmedLine.match(RALPH_RECOMMENDATION_PATTERN);
-            if (recMatch) {
-                block.recommendation = recMatch[1].trim();
-                matched = true;
-            }
-            // Track unknown fields for debugging (only if looks like a field)
-            if (!matched && trimmedLine.includes(':')) {
-                const fieldName = trimmedLine.split(':')[0].trim().toUpperCase();
-                if (fieldName && !['#', '//'].some((c) => fieldName.startsWith(c))) {
-                    unknownFields.push(fieldName);
-                }
-            }
-        }
-        // Log parse errors if any
-        if (parseErrors.length > 0) {
-            console.warn(`[RalphTracker] RALPH_STATUS parse errors:\n  - ${parseErrors.join('\n  - ')}`);
-        }
-        // Log unknown fields if any
-        if (unknownFields.length > 0) {
-            console.warn(`[RalphTracker] RALPH_STATUS unknown fields: ${unknownFields.join(', ')}`);
-        }
-        // Validate required field: STATUS
-        if (block.status === undefined) {
-            console.warn('[RalphTracker] RALPH_STATUS block missing required STATUS field, skipping');
-            return;
-        }
-        // Fill in defaults for missing optional fields
-        const fullBlock = {
-            status: block.status,
-            tasksCompletedThisLoop: block.tasksCompletedThisLoop ?? 0,
-            filesModified: block.filesModified ?? 0,
-            testsStatus: block.testsStatus ?? 'NOT_RUN',
-            workType: block.workType ?? 'IMPLEMENTATION',
-            exitSignal: block.exitSignal ?? false,
-            recommendation: block.recommendation ?? '',
-            parsedAt: block.parsedAt,
-        };
-        this._lastStatusBlock = fullBlock;
-        this.handleStatusBlock(fullBlock);
-    }
-    /**
-     * Handle a parsed RALPH_STATUS block.
-     * Updates circuit breaker, checks exit conditions.
-     *
-     * @param block - Parsed status block
-     * @fires statusBlockDetected - With the block data
-     * @fires circuitBreakerUpdate - If state changes
-     * @fires exitGateMet - If dual-condition exit triggered
-     */
-    handleStatusBlock(block) {
-        // Auto-enable tracker when we see a status block
-        if (!this._loopState.enabled && !this._autoEnableDisabled) {
-            this.enable();
-        }
-        // Update cumulative counts
-        this._totalFilesModified += block.filesModified;
-        this._totalTasksCompleted += block.tasksCompletedThisLoop;
-        // Check for progress (for circuit breaker)
-        const hasProgress = block.filesModified > 0 || block.tasksCompletedThisLoop > 0;
-        // Update circuit breaker
-        this.updateCircuitBreaker(hasProgress, block.testsStatus, block.status);
-        // Check completion indicators
-        if (block.status === 'COMPLETE') {
-            this._completionIndicators++;
-        }
-        // Check dual-condition exit gate
-        if (block.exitSignal && this._completionIndicators >= 2 && !this._exitGateMet) {
-            this._exitGateMet = true;
-            this.emit('exitGateMet', {
-                completionIndicators: this._completionIndicators,
-                exitSignal: true,
-            });
-        }
-        // Update loop state
-        this._loopState.lastActivity = Date.now();
-        // Emit the status block
-        this.emit('statusBlockDetected', block);
-        this.emitLoopUpdateDebounced();
-    }
-    // ========== Circuit Breaker ==========
-    /**
-     * Update circuit breaker state based on iteration results.
-     *
-     * @param hasProgress - Whether this iteration made progress
-     * @param testsStatus - Current test status
-     * @param status - Overall status from RALPH_STATUS
-     * @fires circuitBreakerUpdate - If state changes
-     */
-    updateCircuitBreaker(hasProgress, testsStatus, status) {
-        const prevState = this._circuitBreaker.state;
-        if (hasProgress) {
-            // Progress detected - reset counters, possibly close circuit
-            this._circuitBreaker.consecutiveNoProgress = 0;
-            this._circuitBreaker.consecutiveSameError = 0;
-            this._circuitBreaker.lastProgressIteration = this._loopState.cycleCount;
-            if (this._circuitBreaker.state === 'HALF_OPEN') {
-                this._circuitBreaker.state = 'CLOSED';
-                this._circuitBreaker.reason = 'Progress detected, circuit closed';
-                this._circuitBreaker.reasonCode = 'progress_detected';
-            }
-        }
-        else {
-            // No progress
-            this._circuitBreaker.consecutiveNoProgress++;
-            // State transitions based on consecutive no-progress
-            if (this._circuitBreaker.state === 'CLOSED') {
-                if (this._circuitBreaker.consecutiveNoProgress >= 3) {
-                    this._circuitBreaker.state = 'OPEN';
-                    this._circuitBreaker.reason = `No progress for ${this._circuitBreaker.consecutiveNoProgress} iterations`;
-                    this._circuitBreaker.reasonCode = 'no_progress_open';
-                }
-                else if (this._circuitBreaker.consecutiveNoProgress >= 2) {
-                    this._circuitBreaker.state = 'HALF_OPEN';
-                    this._circuitBreaker.reason = 'Warning: no progress detected';
-                    this._circuitBreaker.reasonCode = 'no_progress_warning';
-                }
-            }
-            else if (this._circuitBreaker.state === 'HALF_OPEN') {
-                if (this._circuitBreaker.consecutiveNoProgress >= 3) {
-                    this._circuitBreaker.state = 'OPEN';
-                    this._circuitBreaker.reason = `No progress for ${this._circuitBreaker.consecutiveNoProgress} iterations`;
-                    this._circuitBreaker.reasonCode = 'no_progress_open';
-                }
-            }
-        }
-        // Track tests failure
-        if (testsStatus === 'FAILING') {
-            this._circuitBreaker.consecutiveTestsFailure++;
-            if (this._circuitBreaker.consecutiveTestsFailure >= 5 && this._circuitBreaker.state !== 'OPEN') {
-                this._circuitBreaker.state = 'OPEN';
-                this._circuitBreaker.reason = `Tests failing for ${this._circuitBreaker.consecutiveTestsFailure} iterations`;
-                this._circuitBreaker.reasonCode = 'tests_failing_too_long';
-            }
-        }
-        else {
-            this._circuitBreaker.consecutiveTestsFailure = 0;
-        }
-        // Track blocked status
-        if (status === 'BLOCKED' && this._circuitBreaker.state !== 'OPEN') {
-            this._circuitBreaker.state = 'OPEN';
-            this._circuitBreaker.reason = 'Claude reported BLOCKED status';
-            this._circuitBreaker.reasonCode = 'same_error_repeated';
-        }
-        // Emit if state changed
-        if (prevState !== this._circuitBreaker.state) {
-            this._circuitBreaker.lastTransitionAt = Date.now();
-            this.emit('circuitBreakerUpdate', { ...this._circuitBreaker });
-        }
-    }
-    /**
-     * Manually reset circuit breaker to CLOSED state.
-     * Use when user acknowledges the issue is resolved.
-     *
-     * @fires circuitBreakerUpdate
-     */
-    resetCircuitBreaker() {
-        this._circuitBreaker = createInitialCircuitBreakerStatus();
-        this._circuitBreaker.reason = 'Manual reset';
-        this._circuitBreaker.reasonCode = 'manual_reset';
-        this.emit('circuitBreakerUpdate', { ...this._circuitBreaker });
-    }
-    /**
-     * Get current circuit breaker status.
-     */
-    get circuitBreakerStatus() {
-        return { ...this._circuitBreaker };
-    }
-    /**
-     * Get last parsed RALPH_STATUS block.
-     */
-    get lastStatusBlock() {
-        return this._lastStatusBlock ? { ...this._lastStatusBlock } : null;
-    }
-    /**
-     * Get cumulative stats from status blocks.
-     */
-    get cumulativeStats() {
-        return {
-            filesModified: this._totalFilesModified,
-            tasksCompleted: this._totalTasksCompleted,
-            completionIndicators: this._completionIndicators,
-        };
-    }
-    /**
-     * Whether dual-condition exit gate has been met.
-     */
-    get exitGateMet() {
-        return this._exitGateMet;
-    }
-    // ========== Completion Indicator Detection ==========
-    /**
-     * Check line for completion indicators (natural language patterns).
-     * Used for dual-condition exit gate.
-     *
-     * @param line - Line to check
-     */
-    detectCompletionIndicators(line) {
-        for (const pattern of COMPLETION_INDICATOR_PATTERNS) {
-            if (pattern.test(line)) {
-                this._completionIndicators++;
-                break; // Only count once per line
-            }
-        }
-    }
-    // ========== @fix_plan.md Generation & Import ==========
-    /**
-     * Generate @fix_plan.md content from current todos.
-     * Groups todos by priority and status.
-     *
-     * @returns Markdown content for @fix_plan.md
-     */
-    generateFixPlanMarkdown() {
-        const todos = this.todos;
-        const lines = ['# Fix Plan', ''];
-        // Group by priority
-        const p0 = [];
-        const p1 = [];
-        const p2 = [];
-        const noPriority = [];
-        const completed = [];
-        for (const todo of todos) {
-            if (todo.status === 'completed') {
-                completed.push(todo);
-            }
-            else if (todo.priority === 'P0') {
-                p0.push(todo);
-            }
-            else if (todo.priority === 'P1') {
-                p1.push(todo);
-            }
-            else if (todo.priority === 'P2') {
-                p2.push(todo);
-            }
-            else {
-                noPriority.push(todo);
-            }
-        }
-        // High Priority (P0)
-        if (p0.length > 0) {
-            lines.push('## High Priority (P0)');
-            for (const todo of p0) {
-                const checkbox = todo.status === 'in_progress' ? '[-]' : '[ ]';
-                lines.push(`- ${checkbox} ${todo.content}`);
-            }
-            lines.push('');
-        }
-        // Standard (P1)
-        if (p1.length > 0) {
-            lines.push('## Standard (P1)');
-            for (const todo of p1) {
-                const checkbox = todo.status === 'in_progress' ? '[-]' : '[ ]';
-                lines.push(`- ${checkbox} ${todo.content}`);
-            }
-            lines.push('');
-        }
-        // Nice to Have (P2)
-        if (p2.length > 0) {
-            lines.push('## Nice to Have (P2)');
-            for (const todo of p2) {
-                const checkbox = todo.status === 'in_progress' ? '[-]' : '[ ]';
-                lines.push(`- ${checkbox} ${todo.content}`);
-            }
-            lines.push('');
-        }
-        // Tasks (no priority)
-        if (noPriority.length > 0) {
-            lines.push('## Tasks');
-            for (const todo of noPriority) {
-                const checkbox = todo.status === 'in_progress' ? '[-]' : '[ ]';
-                lines.push(`- ${checkbox} ${todo.content}`);
-            }
-            lines.push('');
-        }
-        // Completed
-        if (completed.length > 0) {
-            lines.push('## Completed');
-            for (const todo of completed) {
-                lines.push(`- [x] ${todo.content}`);
-            }
-            lines.push('');
-        }
-        return lines.join('\n');
-    }
-    /**
-     * Parse @fix_plan.md content and import todos.
-     * Replaces current todos with imported ones.
-     *
-     * @param content - Markdown content from @fix_plan.md
-     * @returns Number of todos imported
-     */
-    importFixPlanMarkdown(content) {
-        const lines = content.split('\n');
-        const newTodos = [];
-        let currentPriority = null;
-        // Patterns for section headers
-        const p0HeaderPattern = /^##\s*(High Priority|Critical|P0)/i;
-        const p1HeaderPattern = /^##\s*(Standard|P1|Medium Priority)/i;
-        const p2HeaderPattern = /^##\s*(Nice to Have|P2|Low Priority)/i;
-        const completedHeaderPattern = /^##\s*Completed/i;
-        const tasksHeaderPattern = /^##\s*Tasks/i;
-        // Pattern for todo items
-        const todoPattern = /^-\s*\[([ x-])\]\s*(.+)$/;
-        let inCompletedSection = false;
-        for (const line of lines) {
-            const trimmed = line.trim();
-            // Check for section headers
-            if (p0HeaderPattern.test(trimmed)) {
-                currentPriority = 'P0';
-                inCompletedSection = false;
-                continue;
-            }
-            if (p1HeaderPattern.test(trimmed)) {
-                currentPriority = 'P1';
-                inCompletedSection = false;
-                continue;
-            }
-            if (p2HeaderPattern.test(trimmed)) {
-                currentPriority = 'P2';
-                inCompletedSection = false;
-                continue;
-            }
-            if (completedHeaderPattern.test(trimmed)) {
-                inCompletedSection = true;
-                continue;
-            }
-            if (tasksHeaderPattern.test(trimmed)) {
-                currentPriority = null;
-                inCompletedSection = false;
-                continue;
-            }
-            // Parse todo item
-            const match = trimmed.match(todoPattern);
-            if (match) {
-                const [, checkboxState, content] = match;
-                let status;
-                if (inCompletedSection || checkboxState === 'x' || checkboxState === 'X') {
-                    status = 'completed';
-                }
-                else if (checkboxState === '-') {
-                    status = 'in_progress';
-                }
-                else {
-                    status = 'pending';
-                }
-                // Parse priority from content if not in a priority section
-                const parsedPriority = inCompletedSection ? null : currentPriority || this.parsePriority(content);
-                const id = this.generateTodoId(content);
-                newTodos.push({
-                    id,
-                    content: content.trim(),
-                    status,
-                    detectedAt: Date.now(),
-                    priority: parsedPriority,
-                });
-            }
-        }
-        // Replace current todos with imported ones
-        this._todos.clear();
-        for (const todo of newTodos) {
-            this._todos.set(todo.id, todo);
-        }
-        // Emit update
-        this.emit('todoUpdate', this.todos);
-        return newTodos.length;
-    }
-    // ========== Enhanced Plan Management Methods ==========
-    /**
-     * Initialize plan tasks from generated plan items.
-     * Called when wizard generates a new plan.
-     */
-    initializePlanTasks(items) {
-        // Save current plan to history before replacing
-        if (this._planTasks.size > 0) {
-            this._savePlanToHistory('Plan replaced with new generation');
-        }
-        // Clear and rebuild
-        this._planTasks.clear();
-        this._planVersion++;
-        items.forEach((item, idx) => {
-            const id = item.id || `task-${idx}`;
-            const task = {
-                id,
-                content: item.content,
-                priority: item.priority || null,
-                verificationCriteria: item.verificationCriteria,
-                testCommand: item.testCommand,
-                dependencies: item.dependencies || [],
-                status: 'pending',
-                attempts: 0,
-                version: this._planVersion,
-                tddPhase: item.tddPhase,
-                pairedWith: item.pairedWith,
-                complexity: item.complexity,
-            };
-            this._planTasks.set(id, task);
-        });
-        this.emit('planInitialized', { version: this._planVersion, taskCount: this._planTasks.size });
-    }
-    /**
-     * Update a specific plan task's status, attempts, or error.
-     */
-    updatePlanTask(taskId, update) {
-        const task = this._planTasks.get(taskId);
-        if (!task) {
-            return { success: false, error: 'Task not found' };
-        }
-        if (update.status) {
-            task.status = update.status;
-            if (update.status === 'completed') {
-                task.completedAt = Date.now();
-            }
-        }
-        if (update.error) {
-            task.lastError = update.error;
-        }
-        if (update.incrementAttempts) {
-            task.attempts++;
-            // After 3 failed attempts, mark as blocked and emit warning
-            if (task.attempts >= 3 && task.status === 'failed') {
-                task.status = 'blocked';
-                this.emit('taskBlocked', {
-                    taskId,
-                    content: task.content,
-                    attempts: task.attempts,
-                    lastError: task.lastError,
-                });
-            }
-        }
-        // Update blocked tasks when a dependency completes
-        if (update.status === 'completed') {
-            this._unblockDependentTasks(taskId);
-        }
-        // Check for checkpoint
-        this._checkForCheckpoint();
-        this.emit('planTaskUpdate', { taskId, task });
-        return { success: true, task };
-    }
-    /**
-     * Unblock tasks that were waiting on a completed dependency.
-     */
-    _unblockDependentTasks(completedTaskId) {
-        for (const [_, task] of this._planTasks) {
-            if (task.dependencies.includes(completedTaskId)) {
-                // Check if all dependencies are now complete
-                const allDepsComplete = task.dependencies.every((depId) => {
-                    const dep = this._planTasks.get(depId);
-                    return dep && dep.status === 'completed';
-                });
-                if (allDepsComplete && task.status === 'blocked') {
-                    task.status = 'pending';
-                    this.emit('taskUnblocked', { taskId: task.id });
-                }
-            }
-        }
-    }
-    /**
-     * Check if current iteration is a checkpoint and emit review if so.
-     */
-    _checkForCheckpoint() {
-        const currentIteration = this._loopState.cycleCount;
-        if (this._checkpointIterations.includes(currentIteration) && currentIteration > this._lastCheckpointIteration) {
-            this._lastCheckpointIteration = currentIteration;
-            const checkpoint = this.generateCheckpointReview();
-            this.emit('planCheckpoint', checkpoint);
-        }
-    }
-    /**
-     * Generate a checkpoint review summarizing plan progress and stuck tasks.
-     */
-    generateCheckpointReview() {
-        const tasks = Array.from(this._planTasks.values());
-        const summary = {
-            total: tasks.length,
-            completed: tasks.filter((t) => t.status === 'completed').length,
-            failed: tasks.filter((t) => t.status === 'failed').length,
-            blocked: tasks.filter((t) => t.status === 'blocked').length,
-            pending: tasks.filter((t) => t.status === 'pending').length,
-            inProgress: tasks.filter((t) => t.status === 'in_progress').length,
-        };
-        // Find stuck tasks (3+ attempts or blocked)
-        const stuckTasks = tasks
-            .filter((t) => t.attempts >= 3 || t.status === 'blocked')
-            .map((t) => ({
-            id: t.id,
-            content: t.content,
-            attempts: t.attempts,
-            lastError: t.lastError,
-        }));
-        // Generate recommendations
-        const recommendations = [];
-        if (stuckTasks.length > 0) {
-            recommendations.push(`${stuckTasks.length} task(s) are stuck. Consider breaking them into smaller steps.`);
-        }
-        if (summary.failed > summary.completed && summary.total > 5) {
-            recommendations.push('More tasks have failed than completed. Review approach and consider plan adjustment.');
-        }
-        const progressPercent = summary.total > 0 ? Math.round((summary.completed / summary.total) * 100) : 0;
-        if (progressPercent < 20 && this._loopState.cycleCount > 10) {
-            recommendations.push('Progress is slow. Consider simplifying tasks or reviewing dependencies.');
-        }
-        if (summary.total > 0 && summary.blocked > summary.total / 3) {
-            recommendations.push('Many tasks are blocked. Review dependency chain for bottlenecks.');
-        }
-        return {
-            iteration: this._loopState.cycleCount,
-            timestamp: Date.now(),
-            summary,
-            stuckTasks,
-            recommendations,
-        };
-    }
-    /**
-     * Save current plan state to history.
-     */
-    _savePlanToHistory(summary) {
-        // Clone current tasks
-        const tasksCopy = new Map();
-        for (const [id, task] of this._planTasks) {
-            tasksCopy.set(id, { ...task });
-        }
-        this._planHistory.push({
-            version: this._planVersion,
-            timestamp: Date.now(),
-            tasks: tasksCopy,
-            summary,
-        });
-        // Limit history size
-        if (this._planHistory.length > MAX_PLAN_HISTORY) {
-            this._planHistory.shift();
-        }
-    }
-    /**
-     * Get plan version history.
-     */
-    getPlanHistory() {
-        return this._planHistory.map((h) => {
-            const tasks = Array.from(h.tasks.values());
-            return {
-                version: h.version,
-                timestamp: h.timestamp,
-                summary: h.summary,
-                stats: {
-                    total: tasks.length,
-                    completed: tasks.filter((t) => t.status === 'completed').length,
-                    failed: tasks.filter((t) => t.status === 'failed').length,
-                },
-            };
-        });
-    }
-    /**
-     * Rollback to a previous plan version.
-     */
-    rollbackToVersion(version) {
-        const historyEntry = this._planHistory.find((h) => h.version === version);
-        if (!historyEntry) {
-            return { success: false, error: `Version ${version} not found in history` };
-        }
-        // Save current state first
-        this._savePlanToHistory(`Rolled back from v${this._planVersion} to v${version}`);
-        // Restore the historical version
-        this._planTasks.clear();
-        for (const [id, task] of historyEntry.tasks) {
-            // Reset execution state for retry
-            this._planTasks.set(id, {
-                ...task,
-                status: task.status === 'completed' ? 'completed' : 'pending',
-                attempts: task.status === 'completed' ? task.attempts : 0,
-                lastError: undefined,
-            });
-        }
-        this._planVersion++;
-        this.emit('planRollback', { version, newVersion: this._planVersion });
-        return { success: true, plan: Array.from(this._planTasks.values()) };
-    }
-    /**
-     * Add a new task to the plan (for runtime adaptation).
-     */
-    addPlanTask(task) {
-        // Generate unique ID
-        const existingIds = Array.from(this._planTasks.keys());
-        const prefix = task.priority || 'P1';
-        let counter = existingIds.filter((id) => id.startsWith(prefix)).length + 1;
-        let id = `${prefix}-${String(counter).padStart(3, '0')}`;
-        while (this._planTasks.has(id)) {
-            counter++;
-            id = `${prefix}-${String(counter).padStart(3, '0')}`;
-        }
-        const newTask = {
-            id,
-            content: task.content,
-            priority: task.priority || null,
-            verificationCriteria: task.verificationCriteria || 'Task completed successfully',
-            dependencies: task.dependencies || [],
-            status: 'pending',
-            attempts: 0,
-            version: this._planVersion,
-        };
-        this._planTasks.set(id, newTask);
-        this.emit('planTaskAdded', { task: newTask });
-        return { task: newTask };
-    }
-    /**
-     * Get all plan tasks.
-     */
-    getPlanTasks() {
-        return Array.from(this._planTasks.values());
-    }
-    /**
-     * Get current plan version.
-     */
-    get planVersion() {
-        return this._planVersion;
-    }
-    /**
-     * Check if checkpoint review is due for current iteration.
-     */
-    isCheckpointDue() {
-        const currentIteration = this._loopState.cycleCount;
-        return this._checkpointIterations.includes(currentIteration) && currentIteration > this._lastCheckpointIteration;
-    }
     /**
      * Clean up all resources and release memory.
-     *
-     * Call this when the session is being destroyed to prevent memory leaks.
-     * Stops file watchers, clears all timers, data, and removes event listeners.
      */
     destroy() {
-        this.clearDebounceTimers();
-        this.stopWatchingFixPlan();
-        this.stopIterationStallDetection();
+        this._todoDeb.dispose();
+        this._loopDeb.dispose();
+        this.fixPlanWatcher.destroy();
+        this.stallDetector.destroy();
+        this.statusParser.destroy();
+        this.planTracker.destroy();
         this._todos.clear();
         this._taskNumberToContent.clear();
         this._todoStartTimes.clear();
         this._alternateCompletionPhrases.clear();
         this._completionPhraseCount.clear();
-        this._planTasks.clear();
         this._completionTimes.length = 0;
         this._lineBuffer = '';
         this._partialPromiseBuffer = '';
-        this._statusBlockBuffer.length = 0;
-        this._planHistory.length = 0;
         this.removeAllListeners();
     }
 }