aicodeman 0.2.9 → 0.3.1

package/dist/ralph-tracker.d.ts

@@ -1,75 +1,46 @@
 /**
- * @fileoverview Ralph Tracker - Detects Ralph Wiggum loops, todos, and completion phrases
+ * @fileoverview Ralph Tracker - Detects Ralph Wiggum loops, todos, and completion phrases.
  *
- * This module parses terminal output from Claude Code sessions to detect:
- * - Ralph Wiggum loop state (active, completion phrase, iteration count)
- * - Todo list items from the TodoWrite tool
+ * Parses terminal output from Claude Code sessions to detect:
+ * - Ralph loop state (active, completion phrase, iteration count)
+ * - Todo items from the TodoWrite tool (with deduplication and expiry)
  * - Completion phrases signaling loop completion
+ * - Circuit breaker state (CLOSED/HALF_OPEN/OPEN)
  *
- * The tracker is DISABLED by default and auto-enables when Ralph-related
- * patterns are detected in the output stream, reducing overhead for
- * sessions not using autonomous loops.
+ * DISABLED by default — auto-enables when Ralph-related patterns appear,
+ * reducing overhead for non-autonomous sessions.
+ *
+ * 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
+ *
+ * Key exports:
+ * - `RalphTracker` class — main tracker, extends EventEmitter
+ * - `RalphTrackerEvents` interface — typed event map
+ * - Re-exports: `EnhancedPlanTask`, `CheckpointReview` from ralph-plan-tracker
+ *
+ * Key methods: `processData(data)` — feed terminal output, `getState()`,
+ * `getTodos()`, `getCompletionHistory()`, `getPlanTasks()`, `reset()`
+ *
+ * @dependencies types (RalphTrackerState, RalphTodoItem, CircuitBreakerStatus),
+ *   ralph-plan-tracker, ralph-fix-plan-watcher, ralph-stall-detector, ralph-status-parser,
+ *   config/buffer-limits, config/map-limits
+ * @consumedby session (owns one RalphTracker per session), web/server (SSE events)
+ * @emits ralphStateChanged, todoUpdated, completionDetected, statusBlockParsed,
+ *   circuitBreakerChanged, exitGateMet, planTaskUpdated, planCheckpoint
  *
  * @module ralph-tracker
  */
 import { EventEmitter } from 'node:events';
 import { RalphTrackerState, RalphTodoItem, RalphStatusBlock, CircuitBreakerStatus, RalphTodoProgress, CompletionConfidence, PlanTaskStatus, TddPhase } from './types.js';
-/**
- * Enhanced plan task with verification criteria, dependencies, and execution tracking.
- * Supports TDD workflow, failure tracking, and plan versioning.
- */
-export interface EnhancedPlanTask {
-    /** Unique identifier (e.g., "P0-001") */
-    id: string;
-    /** Task description */
-    content: string;
-    /** Criticality level */
-    priority: 'P0' | 'P1' | 'P2' | null;
-    /** How to verify completion */
-    verificationCriteria?: string;
-    /** Command to run for verification */
-    testCommand?: string;
-    /** IDs of tasks that must complete first */
-    dependencies: string[];
-    /** Current execution status */
-    status: PlanTaskStatus;
-    /** How many times attempted */
-    attempts: number;
-    /** Most recent failure reason */
-    lastError?: string;
-    /** Timestamp of completion */
-    completedAt?: number;
-    /** Plan version this belongs to */
-    version: number;
-    /** TDD phase category */
-    tddPhase?: TddPhase;
-    /** ID of paired test/impl task */
-    pairedWith?: string;
-    /** Estimated complexity */
-    complexity?: 'low' | 'medium' | 'high';
-    /** Checklist items for review tasks (tddPhase: 'review') */
-    reviewChecklist?: string[];
-}
-/** Checkpoint review data */
-export interface CheckpointReview {
-    iteration: number;
-    timestamp: number;
-    summary: {
-        total: number;
-        completed: number;
-        failed: number;
-        blocked: number;
-        pending: number;
-        inProgress: number;
-    };
-    stuckTasks: Array<{
-        id: string;
-        content: string;
-        attempts: number;
-        lastError?: string;
-    }>;
-    recommendations: string[];
-}
+import { RalphPlanTracker } from './ralph-plan-tracker.js';
+import type { EnhancedPlanTask, CheckpointReview } from './ralph-plan-tracker.js';
+import { RalphFixPlanWatcher } from './ralph-fix-plan-watcher.js';
+import { RalphStallDetector } from './ralph-stall-detector.js';
+import { RalphStatusParser } from './ralph-status-parser.js';
+export type { EnhancedPlanTask, CheckpointReview } from './ralph-plan-tracker.js';
 /**
  * Events emitted by RalphTracker
  * @event loopUpdate - Fired when loop state changes (active, iteration, completion phrase)
@@ -136,6 +107,13 @@ export interface RalphTrackerEvents {
  * - 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)
@@ -154,6 +132,14 @@ export interface RalphTrackerEvents {
  * ```
  */
 export declare class RalphTracker extends EventEmitter {
+    /** Plan task management sub-module */
+    readonly planTracker: RalphPlanTracker;
+    /** @fix_plan.md file watcher sub-module */
+    readonly fixPlanWatcher: RalphFixPlanWatcher;
+    /** Iteration stall detector sub-module */
+    readonly stallDetector: RalphStallDetector;
+    /** RALPH_STATUS block parser and circuit breaker sub-module */
+    readonly statusParser: RalphStatusParser;
     /** Current state of the detected loop */
     private _loopState;
     /** Map of todo items by ID for O(1) lookup */
@@ -167,14 +153,10 @@ export declare class RalphTracker extends EventEmitter {
     private _completionPhraseCount;
     /** Timestamp of last cleanup check for throttling */
     private _lastCleanupTime;
-    /** Debounce timer for todoUpdate events */
-    private _todoUpdateTimer;
-    /** Debounce timer for loopUpdate events */
-    private _loopUpdateTimer;
-    /** Flag indicating pending todoUpdate emission */
-    private _todoUpdatePending;
-    /** Flag indicating pending loopUpdate emission */
-    private _loopUpdatePending;
+    /** Debouncer for todoUpdate events */
+    private _todoDeb;
+    /** Debouncer for loopUpdate events */
+    private _loopDeb;
     /** When true, prevents auto-enable on pattern detection */
     private _autoEnableDisabled;
     /** Maps task numbers from "✔ Task #N" format to their content for status updates */
@@ -187,59 +169,6 @@ export declare class RalphTracker extends EventEmitter {
     private _partialPromiseBuffer;
     /** Maximum size of partial promise buffer */
     private static readonly MAX_PARTIAL_PROMISE_SIZE;
-    /** Circuit breaker state tracking */
-    private _circuitBreaker;
-    /** Buffer for RALPH_STATUS block lines */
-    private _statusBlockBuffer;
-    /** Flag indicating we're inside a RALPH_STATUS block */
-    private _inStatusBlock;
-    /** Last parsed RALPH_STATUS block */
-    private _lastStatusBlock;
-    /** Count of completion indicators detected (for dual-condition exit) */
-    private _completionIndicators;
-    /** Whether dual-condition exit gate has been met */
-    private _exitGateMet;
-    /** Cumulative files modified across all iterations */
-    private _totalFilesModified;
-    /** Cumulative tasks completed across all iterations */
-    private _totalTasksCompleted;
-    /** Working directory for @fix_plan.md watching */
-    private _workingDir;
-    /** File watcher for @fix_plan.md */
-    private _fixPlanWatcher;
-    /** Error handler for FSWatcher (stored for cleanup to prevent memory leak) */
-    private _fixPlanWatcherErrorHandler;
-    /** Debounce timer for file change events */
-    private _fixPlanReloadTimer;
-    /** Path to the @fix_plan.md file being watched */
-    private _fixPlanPath;
-    /**
-     * 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.
-     */
-    private get isFileAuthoritative();
-    /** Current version of the plan (incremented on changes) */
-    private _planVersion;
-    /** History of plan versions for rollback support */
-    private _planHistory;
-    /** Enhanced plan tasks with execution tracking */
-    private _planTasks;
-    /** Checkpoint intervals (iterations at which to trigger review) */
-    private _checkpointIterations;
-    /** Last checkpoint iteration */
-    private _lastCheckpointIteration;
-    /** Timestamp when iteration count last changed */
-    private _lastIterationChangeTime;
-    /** Last observed iteration count for stall detection */
-    private _lastObservedIteration;
-    /** Timer for iteration stall detection */
-    private _iterationStallTimer;
-    /** Iteration stall warning threshold (ms) - default 10 minutes */
-    private _iterationStallWarningMs;
-    /** Iteration stall critical threshold (ms) - default 20 minutes */
-    private _iterationStallCriticalMs;
-    /** Whether stall warning has been emitted */
-    private _iterationStallWarned;
     /** Alternate completion phrases (P1-003: multi-phrase support) - Set for O(1) lookup */
     private _alternateCompletionPhrases;
     /** History of todo completion times (ms) for averaging */
@@ -250,595 +179,395 @@ export declare class RalphTracker extends EventEmitter {
     private _todosStartedAt;
     /** Map of todo ID to timestamp when it started (for duration tracking) */
     private _todoStartTimes;
+    /** Last calculated completion confidence */
+    private _lastCompletionConfidence;
+    /** Manages periodic cleanup timers (todo expiry) */
+    private cleanup;
+    /** Confidence threshold for triggering completion (0-100) */
+    private static readonly COMPLETION_CONFIDENCE_THRESHOLD;
     /**
      * Creates a new RalphTracker instance.
      * Starts in disabled state until Ralph patterns are detected.
      */
     constructor();
     /**
-     * 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
+     * Forward all sub-module events through RalphTracker
+     * so external consumers don't need to know about the split.
      */
-    addAlternateCompletionPhrase(phrase: string): void;
+    private _wireSubModuleEvents;
     /**
-     * Remove an alternate completion phrase.
-     * @param phrase - Phrase to remove
+     * Initialize plan tasks from generated plan items.
      */
-    removeAlternateCompletionPhrase(phrase: string): void;
+    initializePlanTasks(items: Array<{
+        id?: string;
+        content: string;
+        priority?: 'P0' | 'P1' | 'P2' | null;
+        verificationCriteria?: string;
+        testCommand?: string;
+        dependencies?: string[];
+        tddPhase?: TddPhase;
+        pairedWith?: string;
+        complexity?: 'low' | 'medium' | 'high';
+    }>): void;
     /**
-     * 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
+     * Update a specific plan task's status, attempts, or error.
      */
-    isValidCompletionPhrase(phrase: string): boolean;
+    updatePlanTask(taskId: string, update: {
+        status?: PlanTaskStatus;
+        error?: string;
+        incrementAttempts?: boolean;
+    }): {
+        success: boolean;
+        task?: EnhancedPlanTask;
+        error?: string;
+    };
     /**
-     * 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
+     * Add a new task to the plan.
      */
-    private findMatchingCompletionPhrase;
+    addPlanTask(task: {
+        content: string;
+        priority?: 'P0' | 'P1' | 'P2';
+        verificationCriteria?: string;
+        dependencies?: string[];
+        insertAfter?: string;
+    }): {
+        task: EnhancedPlanTask;
+    };
     /**
-     * Prevent auto-enable from pattern detection.
-     * Use this when the user has explicitly disabled the Ralph tracker.
+     * Get all plan tasks.
      */
-    disableAutoEnable(): void;
+    getPlanTasks(): EnhancedPlanTask[];
     /**
-     * Allow auto-enable from pattern detection.
+     * Generate a checkpoint review.
      */
-    enableAutoEnable(): void;
+    generateCheckpointReview(): CheckpointReview;
     /**
-     * Whether auto-enable is disabled.
+     * Get plan version history.
      */
-    get autoEnableDisabled(): boolean;
+    getPlanHistory(): Array<{
+        version: number;
+        timestamp: number;
+        summary: string;
+        stats: {
+            total: number;
+            completed: number;
+            failed: number;
+        };
+    }>;
+    /**
+     * Rollback to a previous plan version.
+     */
+    rollbackToVersion(version: number): {
+        success: boolean;
+        plan?: EnhancedPlanTask[];
+        error?: string;
+    };
+    /**
+     * Check if checkpoint review is due.
+     */
+    isCheckpointDue(): boolean;
+    /**
+     * Get current plan version.
+     */
+    get planVersion(): number;
     /**
      * 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: string): void;
     /**
      * Load @fix_plan.md from disk if it exists.
-     * Called on initialization and when file changes are detected.
      */
     loadFixPlanFromDisk(): Promise<number>;
     /**
-     * Start watching @fix_plan.md for changes.
-     * Reloads todos when the file is modified.
+     * Stop watching @fix_plan.md.
      */
-    private startWatchingFixPlan;
+    stopWatchingFixPlan(): void;
     /**
-     * Handle @fix_plan.md file change with debouncing.
+     * When @fix_plan.md is active, treat it as the source of truth for todo status.
      */
-    private handleFixPlanChange;
+    get isFileAuthoritative(): boolean;
     /**
-     * Stop watching @fix_plan.md.
+     * Generate @fix_plan.md content from current todos.
      */
-    stopWatchingFixPlan(): void;
+    generateFixPlanMarkdown(): string;
+    /**
+     * 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: string): number;
+    /**
+     * Start iteration stall detection timer.
+     */
+    startIterationStallDetection(): void;
+    /**
+     * Stop iteration stall detection timer.
+     */
+    stopIterationStallDetection(): void;
+    /**
+     * Get iteration stall metrics for monitoring.
+     */
+    getIterationStallMetrics(): {
+        lastIterationChangeTime: number;
+        stallDurationMs: number;
+        warningThresholdMs: number;
+        criticalThresholdMs: number;
+        isWarned: boolean;
+        currentIteration: number;
+    };
+    /**
+     * Configure iteration stall thresholds.
+     */
+    configureIterationStallThresholds(warningMs: number, criticalMs: number): void;
+    /**
+     * Manually reset circuit breaker to CLOSED state.
+     * @fires circuitBreakerUpdate
+     */
+    resetCircuitBreaker(): void;
+    /**
+     * Get current circuit breaker status.
+     */
+    get circuitBreakerStatus(): CircuitBreakerStatus;
+    /**
+     * Get last parsed RALPH_STATUS block.
+     */
+    get lastStatusBlock(): RalphStatusBlock | null;
+    /**
+     * Get cumulative stats from status blocks.
+     */
+    get cumulativeStats(): {
+        filesModified: number;
+        tasksCompleted: number;
+        completionIndicators: number;
+    };
+    /**
+     * Whether dual-condition exit gate has been met.
+     */
+    get exitGateMet(): boolean;
+    /**
+     * Add an alternate completion phrase (P1-003: multi-phrase support).
+     */
+    addAlternateCompletionPhrase(phrase: string): void;
+    /**
+     * Remove an alternate completion phrase.
+     */
+    removeAlternateCompletionPhrase(phrase: string): void;
+    /**
+     * Check if a phrase matches any valid completion phrase (primary or alternate).
+     */
+    isValidCompletionPhrase(phrase: string): boolean;
+    /**
+     * Find which completion phrase (primary or alternate) matches the given phrase.
+     */
+    private findMatchingCompletionPhrase;
+    /**
+     * Prevent auto-enable from pattern detection.
+     */
+    disableAutoEnable(): void;
+    /**
+     * Allow auto-enable from pattern detection.
+     */
+    enableAutoEnable(): void;
+    /**
+     * Whether auto-enable is disabled.
+     */
+    get autoEnableDisabled(): boolean;
     /**
      * 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(): boolean;
     /**
      * 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
      */
     enable(): void;
     /**
      * Disable the tracker to stop monitoring terminal output.
-     * Terminal data will be ignored until re-enabled.
      * @fires loopUpdate
      */
     disable(): void;
     /**
      * 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
      */
     reset(): void;
     /**
      * 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
      */
     fullReset(): void;
     /**
      * Clear all debounce timers.
-     * Called during reset/fullReset to prevent stale emissions.
      */
     private clearDebounceTimers;
     /**
      * Emit todoUpdate event with debouncing.
-     * Batches rapid consecutive calls to reduce UI jitter.
-     * The event fires after EVENT_DEBOUNCE_MS of inactivity.
      */
     private emitTodoUpdateDebounced;
     /**
      * Emit loopUpdate event with debouncing.
-     * Batches rapid consecutive calls to reduce UI jitter.
-     * The event fires after EVENT_DEBOUNCE_MS of inactivity.
      */
     private emitLoopUpdateDebounced;
     /**
      * Flush all pending debounced events immediately.
-     * Useful for testing or when immediate state sync is needed.
      */
     flushPendingEvents(): void;
     /**
      * Get a copy of the current loop state.
-     * @returns Shallow copy of loop state (safe to modify)
-     */
-    /**
-     * Start iteration stall detection timer.
-     * Should be called when the loop becomes active.
-     */
-    startIterationStallDetection(): void;
-    /**
-     * Stop iteration stall detection timer.
-     */
-    stopIterationStallDetection(): void;
-    /**
-     * Check for iteration stall and emit appropriate events.
-     */
-    private checkIterationStall;
-    /**
-     * Get iteration stall metrics for monitoring.
-     */
-    getIterationStallMetrics(): {
-        lastIterationChangeTime: number;
-        stallDurationMs: number;
-        warningThresholdMs: number;
-        criticalThresholdMs: number;
-        isWarned: boolean;
-        currentIteration: number;
-    };
-    /**
-     * Configure iteration stall thresholds.
-     * @param warningMs - Warning threshold in milliseconds
-     * @param criticalMs - Critical threshold in milliseconds
      */
-    configureIterationStallThresholds(warningMs: number, criticalMs: number): void;
     get loopState(): RalphTrackerState;
-    /** Last calculated completion confidence */
-    private _lastCompletionConfidence;
-    /** Confidence threshold for triggering completion (0-100) */
-    private static readonly COMPLETION_CONFIDENCE_THRESHOLD;
     /**
      * 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
      */
     calculateCompletionConfidence(phrase: string, context?: string): CompletionConfidence;
     /**
      * Get all tracked todo items as an array.
-     * @returns Array of todo items (copy, safe to modify)
      */
     get todos(): RalphTodoItem[];
     /**
      * 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: string): void;
     /**
      * 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: string): void;
     /**
      * 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
      */
     private shouldAutoEnable;
     /**
      * Process a single line of terminal output.
-     * Runs all detection methods in sequence.
-     * @param line - Single line of ANSI-cleaned terminal output
      */
     private processLine;
     /**
      * 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
      */
     private detectAllTasksComplete;
     /**
-     * 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.
      */
     private detectTaskCompletion;
     /**
      * 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)
      */
     private checkMultiLinePatterns;
     /**
      * 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
      */
     private detectCompletionPhrase;
     /**
      * 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
      */
     private handleBareCompletionPhrase;
     /**
-     * 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.
      */
     private handleCompletionPhrase;
     /**
      * 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
      */
     private isFuzzyPhraseMatch;
     /**
      * 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
      */
     private validateCompletionPhrase;
     /**
      * 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
      */
     private activateLoopIfNeeded;
     /**
      * 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
      */
     private detectLoopStatus;
     /**
      * 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
      */
     private detectTodoItems;
     /**
      * 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
      */
     private iconToStatus;
     /**
      * 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
      */
     private parsePriority;
     /**
      * 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
      */
     private upsertTodo;
     /**
      * 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
      */
     private normalizeTodoContent;
     /**
      * 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)
      */
     private calculateSimilarity;
     /**
      * 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
      */
     private calculateBigramSimilarity;
     /**
      * 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
      */
     private findSimilarTodo;
     /**
      * Estimate complexity of a todo based on content keywords.
-     * Used for duration estimation.
-     *
-     * @param content - Todo content text
-     * @returns Complexity category
      */
     private estimateComplexity;
     /**
      * Get estimated duration for a complexity level (ms).
-     * Based on historical patterns from similar tasks.
-     *
-     * @param complexity - Complexity category
-     * @returns Estimated duration in milliseconds
      */
     private getEstimatedDuration;
     /**
      * Get average completion time from historical data.
-     * @returns Average time in ms, or null if no data
      */
     private getAverageCompletionTime;
     /**
      * Record a todo completion for progress tracking.
-     * @param todoId - ID of the completed todo
      */
     private recordTodoCompletion;
     /**
      * Start tracking a todo for duration estimation.
-     * @param todoId - ID of the todo being started
      */
     private startTrackingTodo;
     /**
      * Get progress estimation for the todo list.
-     * P1-009: Provides completion percentage, estimated remaining time,
-     * and projected completion timestamp.
-     *
-     * @returns Progress estimation object
      */
     getTodoProgress(): RalphTodoProgress;
-    /**
-     * 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-"
      */
     private generateTodoId;
     /**
      * 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
      */
     private findOldestTodo;
     /**
      * Conditionally run cleanup, throttled to CLEANUP_THROTTLE_MS.
-     * Prevents cleanup from running on every data chunk (performance).
      */
     private maybeCleanupExpiredTodos;
     /**
      * Remove todo items older than TODO_EXPIRY_MS.
-     * Emits todoUpdate if any items were removed.
-     * @fires todoUpdate - When expired items are removed
      */
     private cleanupExpiredTodos;
     /**
      * 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?: string, maxIterations?: number): void;
     /**
      * 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: number | null): void;
     /**
-     * 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: {
         enabled?: boolean;
@@ -847,36 +576,18 @@ export declare class RalphTracker extends EventEmitter {
     }): void;
     /**
      * 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(): void;
     /**
      * Enforce size limit on _taskNumberToContent map.
-     * Removes lowest task numbers (oldest tasks) when limit exceeded.
      */
     private enforceTaskMappingLimit;
     /**
      * 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(): void;
     /**
      * 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(): {
         total: number;
@@ -886,195 +597,10 @@ export declare 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: RalphTrackerState, todos: RalphTodoItem[]): void;
-    /**
-     * 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
-     */
-    private processStatusBlockLine;
-    /**
-     * 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
-     */
-    private parseStatusBlock;
-    /**
-     * 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
-     */
-    private handleStatusBlock;
-    /**
-     * 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
-     */
-    private updateCircuitBreaker;
-    /**
-     * Manually reset circuit breaker to CLOSED state.
-     * Use when user acknowledges the issue is resolved.
-     *
-     * @fires circuitBreakerUpdate
-     */
-    resetCircuitBreaker(): void;
-    /**
-     * Get current circuit breaker status.
-     */
-    get circuitBreakerStatus(): CircuitBreakerStatus;
-    /**
-     * Get last parsed RALPH_STATUS block.
-     */
-    get lastStatusBlock(): RalphStatusBlock | null;
-    /**
-     * Get cumulative stats from status blocks.
-     */
-    get cumulativeStats(): {
-        filesModified: number;
-        tasksCompleted: number;
-        completionIndicators: number;
-    };
-    /**
-     * Whether dual-condition exit gate has been met.
-     */
-    get exitGateMet(): boolean;
-    /**
-     * Check line for completion indicators (natural language patterns).
-     * Used for dual-condition exit gate.
-     *
-     * @param line - Line to check
-     */
-    private detectCompletionIndicators;
-    /**
-     * Generate @fix_plan.md content from current todos.
-     * Groups todos by priority and status.
-     *
-     * @returns Markdown content for @fix_plan.md
-     */
-    generateFixPlanMarkdown(): string;
-    /**
-     * 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: string): number;
-    /**
-     * Initialize plan tasks from generated plan items.
-     * Called when wizard generates a new plan.
-     */
-    initializePlanTasks(items: Array<{
-        id?: string;
-        content: string;
-        priority?: 'P0' | 'P1' | 'P2' | null;
-        verificationCriteria?: string;
-        testCommand?: string;
-        dependencies?: string[];
-        tddPhase?: TddPhase;
-        pairedWith?: string;
-        complexity?: 'low' | 'medium' | 'high';
-    }>): void;
-    /**
-     * Update a specific plan task's status, attempts, or error.
-     */
-    updatePlanTask(taskId: string, update: {
-        status?: PlanTaskStatus;
-        error?: string;
-        incrementAttempts?: boolean;
-    }): {
-        success: boolean;
-        task?: EnhancedPlanTask;
-        error?: string;
-    };
-    /**
-     * Unblock tasks that were waiting on a completed dependency.
-     */
-    private _unblockDependentTasks;
-    /**
-     * Check if current iteration is a checkpoint and emit review if so.
-     */
-    private _checkForCheckpoint;
-    /**
-     * Generate a checkpoint review summarizing plan progress and stuck tasks.
-     */
-    generateCheckpointReview(): CheckpointReview;
-    /**
-     * Save current plan state to history.
-     */
-    private _savePlanToHistory;
-    /**
-     * Get plan version history.
-     */
-    getPlanHistory(): Array<{
-        version: number;
-        timestamp: number;
-        summary: string;
-        stats: {
-            total: number;
-            completed: number;
-            failed: number;
-        };
-    }>;
-    /**
-     * Rollback to a previous plan version.
-     */
-    rollbackToVersion(version: number): {
-        success: boolean;
-        plan?: EnhancedPlanTask[];
-        error?: string;
-    };
-    /**
-     * Add a new task to the plan (for runtime adaptation).
-     */
-    addPlanTask(task: {
-        content: string;
-        priority?: 'P0' | 'P1' | 'P2';
-        verificationCriteria?: string;
-        dependencies?: string[];
-        insertAfter?: string;
-    }): {
-        task: EnhancedPlanTask;
-    };
-    /**
-     * Get all plan tasks.
-     */
-    getPlanTasks(): EnhancedPlanTask[];
-    /**
-     * Get current plan version.
-     */
-    get planVersion(): number;
-    /**
-     * Check if checkpoint review is due for current iteration.
-     */
-    isCheckpointDue(): boolean;
     /**
      * 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(): void;
 }