ralph-mcp 1.0.13 → 1.1.0

package/dist/store/state.d.ts

@@ -15,6 +15,11 @@ export interface ExecutionRecord {
     autoMerge: boolean;
     notifyOnComplete: boolean;
     dependencies: string[];
+    loopCount: number;
+    consecutiveNoProgress: number;
+    consecutiveErrors: number;
+    lastError: string | null;
+    lastFilesChanged: number;
     createdAt: Date;
     updatedAt: Date;
 }
@@ -66,3 +71,35 @@ export declare function areDependenciesSatisfied(execution: ExecutionRecord): Pr
     pending: string[];
     completed: string[];
 }>;
+/**
+ * Stagnation detection thresholds (matching original ralph-claude-code)
+ */
+export declare const STAGNATION_THRESHOLDS: {
+    NO_PROGRESS_THRESHOLD: number;
+    SAME_ERROR_THRESHOLD: number;
+    MAX_LOOPS_PER_STORY: number;
+};
+export type StagnationType = "no_progress" | "repeated_error" | "max_loops" | null;
+export interface StagnationCheckResult {
+    isStagnant: boolean;
+    type: StagnationType;
+    message: string;
+    metrics: {
+        loopCount: number;
+        consecutiveNoProgress: number;
+        consecutiveErrors: number;
+        lastError: string | null;
+    };
+}
+/**
+ * Check if an execution is stagnant (stuck in a loop).
+ */
+export declare function checkStagnation(executionId: string): Promise<StagnationCheckResult>;
+/**
+ * Record a loop result for stagnation tracking.
+ */
+export declare function recordLoopResult(executionId: string, filesChanged: number, error: string | null): Promise<StagnationCheckResult>;
+/**
+ * Reset stagnation counters (e.g., after manual intervention).
+ */
+export declare function resetStagnation(executionId: string): Promise<void>;

package/dist/store/state.js

@@ -46,6 +46,12 @@ function deserializeState(file) {
         executions: file.executions.map((e) => ({
             ...e,
             dependencies: Array.isArray(e.dependencies) ? e.dependencies : [],
+            // Stagnation detection defaults for backward compatibility
+            loopCount: typeof e.loopCount === "number" ? e.loopCount : 0,
+            consecutiveNoProgress: typeof e.consecutiveNoProgress === "number" ? e.consecutiveNoProgress : 0,
+            consecutiveErrors: typeof e.consecutiveErrors === "number" ? e.consecutiveErrors : 0,
+            lastError: typeof e.lastError === "string" ? e.lastError : null,
+            lastFilesChanged: typeof e.lastFilesChanged === "number" ? e.lastFilesChanged : 0,
             createdAt: parseDate(e.createdAt, "executions.createdAt"),
             updatedAt: parseDate(e.updatedAt, "executions.updatedAt"),
         })),
@@ -236,3 +242,152 @@ export async function areDependenciesSatisfied(execution) {
         };
     });
 }
+// =============================================================================
+// STAGNATION DETECTION
+// =============================================================================
+/**
+ * Stagnation detection thresholds (matching original ralph-claude-code)
+ */
+export const STAGNATION_THRESHOLDS = {
+    NO_PROGRESS_THRESHOLD: 3, // Open circuit after 3 loops with no file changes
+    SAME_ERROR_THRESHOLD: 5, // Open circuit after 5 loops with repeated errors
+    MAX_LOOPS_PER_STORY: 10, // Safety limit per story
+};
+/**
+ * Check if an execution is stagnant (stuck in a loop).
+ */
+export async function checkStagnation(executionId) {
+    return readState((s) => {
+        const exec = s.executions.find((e) => e.id === executionId);
+        if (!exec) {
+            return {
+                isStagnant: false,
+                type: null,
+                message: "Execution not found",
+                metrics: { loopCount: 0, consecutiveNoProgress: 0, consecutiveErrors: 0, lastError: null },
+            };
+        }
+        const metrics = {
+            loopCount: exec.loopCount,
+            consecutiveNoProgress: exec.consecutiveNoProgress,
+            consecutiveErrors: exec.consecutiveErrors,
+            lastError: exec.lastError,
+        };
+        // Check no progress threshold
+        if (exec.consecutiveNoProgress >= STAGNATION_THRESHOLDS.NO_PROGRESS_THRESHOLD) {
+            return {
+                isStagnant: true,
+                type: "no_progress",
+                message: `No file changes for ${exec.consecutiveNoProgress} consecutive loops (threshold: ${STAGNATION_THRESHOLDS.NO_PROGRESS_THRESHOLD})`,
+                metrics,
+            };
+        }
+        // Check repeated error threshold
+        if (exec.consecutiveErrors >= STAGNATION_THRESHOLDS.SAME_ERROR_THRESHOLD) {
+            return {
+                isStagnant: true,
+                type: "repeated_error",
+                message: `Same error repeated ${exec.consecutiveErrors} times (threshold: ${STAGNATION_THRESHOLDS.SAME_ERROR_THRESHOLD}): ${exec.lastError?.slice(0, 100)}`,
+                metrics,
+            };
+        }
+        // Check max loops per story
+        const stories = s.userStories.filter((st) => st.executionId === executionId);
+        const pendingStories = stories.filter((st) => !st.passes);
+        if (pendingStories.length > 0 && exec.loopCount >= STAGNATION_THRESHOLDS.MAX_LOOPS_PER_STORY * pendingStories.length) {
+            return {
+                isStagnant: true,
+                type: "max_loops",
+                message: `Exceeded max loops (${exec.loopCount}) for ${pendingStories.length} pending stories`,
+                metrics,
+            };
+        }
+        return {
+            isStagnant: false,
+            type: null,
+            message: "OK",
+            metrics,
+        };
+    });
+}
+/**
+ * Record a loop result for stagnation tracking.
+ */
+export async function recordLoopResult(executionId, filesChanged, error) {
+    return mutateState(async (s) => {
+        const exec = s.executions.find((e) => e.id === executionId);
+        if (!exec) {
+            throw new Error(`No execution found with id: ${executionId}`);
+        }
+        // Increment loop count
+        exec.loopCount++;
+        exec.lastFilesChanged = filesChanged;
+        exec.updatedAt = new Date();
+        // Track no progress
+        if (filesChanged === 0) {
+            exec.consecutiveNoProgress++;
+        }
+        else {
+            exec.consecutiveNoProgress = 0;
+        }
+        // Track repeated errors
+        if (error) {
+            if (exec.lastError === error) {
+                exec.consecutiveErrors++;
+            }
+            else {
+                exec.consecutiveErrors = 1;
+                exec.lastError = error;
+            }
+        }
+        else {
+            exec.consecutiveErrors = 0;
+            exec.lastError = null;
+        }
+        // Check stagnation after recording
+        const metrics = {
+            loopCount: exec.loopCount,
+            consecutiveNoProgress: exec.consecutiveNoProgress,
+            consecutiveErrors: exec.consecutiveErrors,
+            lastError: exec.lastError,
+        };
+        if (exec.consecutiveNoProgress >= STAGNATION_THRESHOLDS.NO_PROGRESS_THRESHOLD) {
+            exec.status = "failed";
+            return {
+                isStagnant: true,
+                type: "no_progress",
+                message: `Stagnation detected: No file changes for ${exec.consecutiveNoProgress} consecutive loops`,
+                metrics,
+            };
+        }
+        if (exec.consecutiveErrors >= STAGNATION_THRESHOLDS.SAME_ERROR_THRESHOLD) {
+            exec.status = "failed";
+            return {
+                isStagnant: true,
+                type: "repeated_error",
+                message: `Stagnation detected: Same error repeated ${exec.consecutiveErrors} times`,
+                metrics,
+            };
+        }
+        return {
+            isStagnant: false,
+            type: null,
+            message: "OK",
+            metrics,
+        };
+    });
+}
+/**
+ * Reset stagnation counters (e.g., after manual intervention).
+ */
+export async function resetStagnation(executionId) {
+    return mutateState((s) => {
+        const exec = s.executions.find((e) => e.id === executionId);
+        if (!exec)
+            throw new Error(`No execution found with id: ${executionId}`);
+        exec.consecutiveNoProgress = 0;
+        exec.consecutiveErrors = 0;
+        exec.lastError = null;
+        exec.updatedAt = new Date();
+    });
+}

package/dist/tools/batch-start.js

@@ -127,6 +127,12 @@ export async function batchStart(input) {
                 autoMerge: input.autoMerge,
                 notifyOnComplete: input.notifyOnComplete,
                 dependencies: prd.dependencies,
+                // Stagnation detection fields
+                loopCount: 0,
+                consecutiveNoProgress: 0,
+                consecutiveErrors: 0,
+                lastError: null,
+                lastFilesChanged: 0,
                 createdAt: now,
                 updatedAt: now,
             });

package/dist/tools/get.d.ts

@@ -36,5 +36,13 @@ export interface GetResult {
         total: number;
         percentage: number;
     };
+    stagnation: {
+        loopCount: number;
+        consecutiveNoProgress: number;
+        consecutiveErrors: number;
+        lastError: string | null;
+        isAtRisk: boolean;
+        riskReason: string | null;
+    };
 }
 export declare function get(input: GetInput): Promise<GetResult>;

package/dist/tools/get.js

@@ -15,6 +15,21 @@ export async function get(input) {
     stories.sort((a, b) => a.priority - b.priority);
     const completed = stories.filter((s) => s.passes).length;
     const total = stories.length;
+    // Calculate stagnation risk
+    const loopCount = exec.loopCount ?? 0;
+    const consecutiveNoProgress = exec.consecutiveNoProgress ?? 0;
+    const consecutiveErrors = exec.consecutiveErrors ?? 0;
+    const lastError = exec.lastError ?? null;
+    let isAtRisk = false;
+    let riskReason = null;
+    if (consecutiveNoProgress >= 2) {
+        isAtRisk = true;
+        riskReason = `No file changes for ${consecutiveNoProgress} consecutive updates (threshold: 3)`;
+    }
+    else if (consecutiveErrors >= 3) {
+        isAtRisk = true;
+        riskReason = `Same error repeated ${consecutiveErrors} times (threshold: 5)`;
+    }
     return {
         execution: {
             id: exec.id,
@@ -44,5 +59,13 @@ export async function get(input) {
             total,
             percentage: total > 0 ? Math.round((completed / total) * 100) : 0,
         },
+        stagnation: {
+            loopCount,
+            consecutiveNoProgress,
+            consecutiveErrors,
+            lastError,
+            isAtRisk,
+            riskReason,
+        },
     };
 }

package/dist/tools/start.js

@@ -54,6 +54,12 @@ export async function start(input) {
         autoMerge: input.autoMerge,
         notifyOnComplete: input.notifyOnComplete,
         dependencies: prd.dependencies,
+        // Stagnation detection fields
+        loopCount: 0,
+        consecutiveNoProgress: 0,
+        consecutiveErrors: 0,
+        lastError: null,
+        lastFilesChanged: 0,
         createdAt: now,
         updatedAt: now,
     });

package/dist/tools/status.d.ts

@@ -21,6 +21,10 @@ export interface ExecutionStatus {
     agentTaskId: string | null;
     lastActivity: string;
     createdAt: string;
+    loopCount: number;
+    consecutiveNoProgress: number;
+    consecutiveErrors: number;
+    lastError: string | null;
 }
 export interface StatusResult {
     executions: ExecutionStatus[];

package/dist/tools/status.js

@@ -34,6 +34,11 @@ export async function status(input) {
             agentTaskId: exec.agentTaskId,
             lastActivity: exec.updatedAt.toISOString(),
             createdAt: exec.createdAt.toISOString(),
+            // Stagnation metrics
+            loopCount: exec.loopCount ?? 0,
+            consecutiveNoProgress: exec.consecutiveNoProgress ?? 0,
+            consecutiveErrors: exec.consecutiveErrors ?? 0,
+            lastError: exec.lastError ?? null,
         });
     }
     // Sort by last activity (most recent first)

package/dist/tools/update.d.ts

@@ -4,16 +4,22 @@ export declare const updateInputSchema: z.ZodObject<{
     storyId: z.ZodString;
     passes: z.ZodBoolean;
     notes: z.ZodOptional<z.ZodString>;
+    filesChanged: z.ZodOptional<z.ZodNumber>;
+    error: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     branch: string;
     storyId: string;
     passes: boolean;
     notes?: string | undefined;
+    filesChanged?: number | undefined;
+    error?: string | undefined;
 }, {
     branch: string;
     storyId: string;
     passes: boolean;
     notes?: string | undefined;
+    filesChanged?: number | undefined;
+    error?: string | undefined;
 }>;
 export type UpdateInput = z.infer<typeof updateInputSchema>;
 export interface UpdateResult {
@@ -28,5 +34,10 @@ export interface UpdateResult {
         branch: string;
         agentPrompt: string | null;
     }>;
+    stagnation?: {
+        isStagnant: boolean;
+        type: string | null;
+        message: string;
+    };
 }
 export declare function update(input: UpdateInput): Promise<UpdateResult>;

package/dist/tools/update.js

@@ -3,7 +3,7 @@ import notifier from "node-notifier";
 import { appendFile, mkdir, readFile, writeFile } from "fs/promises";
 import { existsSync } from "fs";
 import { join, dirname } from "path";
-import { areDependenciesSatisfied, findExecutionByBranch, findExecutionsDependingOn, findMergeQueueItemByExecutionId, findUserStoryById, insertMergeQueueItem, listMergeQueue, listUserStoriesByExecutionId, updateExecution, updateUserStory, } from "../store/state.js";
+import { areDependenciesSatisfied, findExecutionByBranch, findExecutionsDependingOn, findMergeQueueItemByExecutionId, findUserStoryById, insertMergeQueueItem, listMergeQueue, listUserStoriesByExecutionId, recordLoopResult, updateExecution, updateUserStory, } from "../store/state.js";
 import { mergeQueueAction } from "./merge.js";
 import { generateAgentPrompt } from "../utils/agent.js";
 export const updateInputSchema = z.object({
@@ -11,6 +11,8 @@ export const updateInputSchema = z.object({
     storyId: z.string().describe("Story ID (e.g., US-001)"),
     passes: z.boolean().describe("Whether the story passes"),
     notes: z.string().optional().describe("Implementation notes"),
+    filesChanged: z.number().optional().describe("Number of files changed (for stagnation detection)"),
+    error: z.string().optional().describe("Error message if stuck (for stagnation detection)"),
 });
 function formatDate(date) {
     const pad = (n) => n.toString().padStart(2, '0');
@@ -81,6 +83,28 @@ export async function update(input) {
     if (!story) {
         throw new Error(`No story found with ID ${input.storyId} for branch ${input.branch}`);
     }
+    // Record loop result for stagnation detection
+    const filesChanged = input.filesChanged ?? 0;
+    const error = input.error ?? null;
+    const stagnationResult = await recordLoopResult(exec.id, filesChanged, error);
+    // If stagnant, mark execution as failed and return early
+    if (stagnationResult.isStagnant) {
+        return {
+            success: false,
+            branch: input.branch,
+            storyId: input.storyId,
+            passes: false,
+            allComplete: false,
+            progress: `Stagnation detected`,
+            addedToMergeQueue: false,
+            triggeredDependents: [],
+            stagnation: {
+                isStagnant: true,
+                type: stagnationResult.type,
+                message: stagnationResult.message,
+            },
+        };
+    }
     // Update story
     await updateUserStory(storyKey, {
         passes: input.passes,

package/dist/utils/agent.d.ts

@@ -8,7 +8,12 @@ export declare function generateAgentPrompt(branch: string, description: string,
     acceptanceCriteria: string[];
     priority: number;
     passes: boolean;
-}>, contextInjectionPath?: string): string;
+}>, contextInjectionPath?: string, loopContext?: {
+    loopCount: number;
+    consecutiveNoProgress: number;
+    consecutiveErrors: number;
+    lastError: string | null;
+}): string;
 /**
  * Generate merge agent prompt for conflict resolution
  */

package/dist/utils/agent.js

@@ -6,13 +6,15 @@ const execAsync = promisify(exec);
 /**
  * Generate agent prompt for PRD execution
  */
-export function generateAgentPrompt(branch, description, worktreePath, stories, contextInjectionPath) {
+export function generateAgentPrompt(branch, description, worktreePath, stories, contextInjectionPath, loopContext) {
     const pendingStories = stories
         .filter((s) => !s.passes)
         .sort((a, b) => a.priority - b.priority);
     if (pendingStories.length === 0) {
         return "All user stories are complete. No action needed.";
     }
+    const completedCount = stories.filter((s) => s.passes).length;
+    const totalCount = stories.length;
     const storiesText = pendingStories
         .map((s) => `
 ### ${s.storyId}: ${s.title}
@@ -43,6 +45,16 @@ ${s.acceptanceCriteria.map((ac) => `- ${ac}`).join("\n")}
             // Ignore read errors
         }
     }
+    // Build loop context warning if stagnation is approaching
+    let loopWarning = "";
+    if (loopContext) {
+        if (loopContext.consecutiveNoProgress >= 2) {
+            loopWarning = `\n⚠️ **WARNING**: No file changes detected for ${loopContext.consecutiveNoProgress} consecutive updates. If stuck, try a different approach or mark the story as blocked.\n`;
+        }
+        if (loopContext.consecutiveErrors >= 3) {
+            loopWarning += `\n⚠️ **WARNING**: Same error repeated ${loopContext.consecutiveErrors} times. Consider a different approach.\nLast error: ${loopContext.lastError?.slice(0, 200)}\n`;
+        }
+    }
     return `You are an autonomous coding agent working on the "${branch}" branch.
 
 ## Working Directory
@@ -50,6 +62,11 @@ ${worktreePath}
 
 ## PRD: ${description}
 
+## Progress
+- Completed: ${completedCount}/${totalCount} stories
+- Current story: ${pendingStories[0].storyId}
+${loopContext ? `- Loop iteration: ${loopContext.loopCount}` : ""}
+${loopWarning}
 ${injectedContext ? `## Project Context\n${injectedContext}\n` : ""}
 
 ${progressLog ? `## Progress & Learnings\n${progressLog}\n` : ""}
@@ -80,11 +97,25 @@ Before implementing, verify the story is small enough to complete in ONE context
 2. ${progressLog ? "Review the 'Progress & Learnings' section above - especially the 'Codebase Patterns' section at the top." : "Check if 'ralph-progress.md' exists and review it for context."}
 3. Implement the feature to satisfy all acceptance criteria.
 4. Run quality checks: \`pnpm check-types\` and \`pnpm --filter api build\` (adjust for repo structure).
-5. **Browser Testing (UI stories)**: If the story changes UI, verify in browser using Chrome DevTools MCP or similar tools. A frontend story is NOT complete until visually verified.
+5. **Testing**: Run relevant tests. For UI changes, run component tests if available. If no browser tools are available, note "Manual UI verification needed" in your update notes.
 6. Commit changes with message: \`feat: [${pendingStories[0].storyId}] - ${pendingStories[0].title}\`
 7. **Update Directory CLAUDE.md**: If you discovered reusable patterns, add them to the CLAUDE.md in the directory you modified (create if needed). Only add genuinely reusable knowledge, not story-specific details.
-8. Call \`ralph_update\` to mark the story as passed. Include detailed notes:
-   \`ralph_update({ branch: "${branch}", storyId: "${pendingStories[0].storyId}", passes: true, notes: "..." })\`
+8. Call \`ralph_update\` with structured status. Include:
+   - \`passes: true\` if story is complete, \`passes: false\` if blocked/incomplete
+   - \`filesChanged\`: number of files modified (for stagnation detection)
+   - \`error\`: error message if stuck (for stagnation detection)
+   - \`notes\`: detailed implementation notes
+
+   Example:
+   \`\`\`
+   ralph_update({
+     branch: "${branch}",
+     storyId: "${pendingStories[0].storyId}",
+     passes: true,
+     filesChanged: 5,
+     notes: "**Implemented:** ... **Files changed:** ... **Learnings:** ..."
+   })
+   \`\`\`
 9. Continue to the next story until all are complete.
 
 ## Notes Format for ralph_update
@@ -102,11 +133,16 @@ Provide structured learnings in the \`notes\` field:
 
 ## Quality Requirements (Feedback Loops)
 - ALL commits must pass typecheck and build - broken code compounds across iterations
+- Run relevant tests before committing
 - Keep changes focused and minimal
 - Follow existing code patterns
-- UI changes must be browser-verified
 - Do NOT commit broken code - if checks fail, fix before committing
 
+## Stagnation Prevention
+- If you're stuck on the same error 3+ times, try a different approach
+- If no files are changing, you may be in a loop - step back and reassess
+- It's OK to mark a story as \`passes: false\` with notes explaining the blocker
+
 ## Stop Condition
 When all stories are complete, report completion.
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-mcp",
-  "version": "1.0.13",
+  "version": "1.1.0",
   "description": "MCP server for autonomous PRD execution with Claude Code. Git worktree isolation, progress tracking, auto-merge.",
   "type": "module",
   "main": "dist/index.js",