ralph-mcp 1.0.14 → 1.1.1

package/dist/index.js

@@ -10,6 +10,8 @@ import { update, updateInputSchema } from "./tools/update.js";
 import { stop, stopInputSchema } from "./tools/stop.js";
 import { merge, mergeInputSchema, mergeQueueAction, mergeQueueInputSchema } from "./tools/merge.js";
 import { setAgentId, setAgentIdInputSchema } from "./tools/set-agent-id.js";
+import { resetStagnationTool, resetStagnationInputSchema } from "./tools/reset-stagnation.js";
+import { retry, retryInputSchema } from "./tools/retry.js";
 const server = new Server({
     name: "ralph",
     version: "1.0.0",
@@ -120,6 +122,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             type: "string",
                             description: "Implementation notes",
                         },
+                        filesChanged: {
+                            type: "number",
+                            description: "Number of files changed (for stagnation detection)",
+                        },
+                        error: {
+                            type: "string",
+                            description: "Error message if stuck (for stagnation detection)",
+                        },
                     },
                     required: ["branch", "storyId", "passes"],
                 },
@@ -258,6 +268,39 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: ["prdPaths"],
                 },
             },
+            {
+                name: "ralph_reset_stagnation",
+                description: "Reset stagnation counters for an execution. Use after manual intervention to allow the agent to continue.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        branch: {
+                            type: "string",
+                            description: "Branch name (e.g., ralph/task1-agent)",
+                        },
+                        resumeExecution: {
+                            type: "boolean",
+                            description: "Also set status back to 'running' if currently 'failed' (default: true)",
+                            default: true,
+                        },
+                    },
+                    required: ["branch"],
+                },
+            },
+            {
+                name: "ralph_retry",
+                description: "Retry a failed PRD execution. Resets stagnation counters and generates a new agent prompt to continue from where it left off.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        branch: {
+                            type: "string",
+                            description: "Branch name (e.g., ralph/task1-agent)",
+                        },
+                    },
+                    required: ["branch"],
+                },
+            },
         ],
     };
 });
@@ -294,6 +337,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "ralph_batch_start":
                 result = await batchStart(batchStartInputSchema.parse(args));
                 break;
+            case "ralph_reset_stagnation":
+                result = await resetStagnationTool(resetStagnationInputSchema.parse(args));
+                break;
+            case "ralph_retry":
+                result = await retry(retryInputSchema.parse(args));
+                break;
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }

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/reset-stagnation.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+export declare const resetStagnationInputSchema: z.ZodObject<{
+    branch: z.ZodString;
+    resumeExecution: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    branch: string;
+    resumeExecution: boolean;
+}, {
+    branch: string;
+    resumeExecution?: boolean | undefined;
+}>;
+export type ResetStagnationInput = z.infer<typeof resetStagnationInputSchema>;
+export interface ResetStagnationResult {
+    success: boolean;
+    branch: string;
+    message: string;
+    previousStatus: string;
+    newStatus: string;
+}
+/**
+ * Reset stagnation counters for an execution.
+ * Use this after manual intervention to allow the agent to continue.
+ */
+export declare function resetStagnationTool(input: ResetStagnationInput): Promise<ResetStagnationResult>;

package/dist/tools/reset-stagnation.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { findExecutionByBranch, resetStagnation, updateExecution, } from "../store/state.js";
+export const resetStagnationInputSchema = z.object({
+    branch: z.string().describe("Branch name (e.g., ralph/task1-agent)"),
+    resumeExecution: z
+        .boolean()
+        .default(true)
+        .describe("Also set status back to 'running' if currently 'failed'"),
+});
+/**
+ * Reset stagnation counters for an execution.
+ * Use this after manual intervention to allow the agent to continue.
+ */
+export async function resetStagnationTool(input) {
+    const exec = await findExecutionByBranch(input.branch);
+    if (!exec) {
+        throw new Error(`No execution found for branch: ${input.branch}`);
+    }
+    const previousStatus = exec.status;
+    // Reset stagnation counters
+    await resetStagnation(exec.id);
+    // Optionally resume execution
+    let newStatus = previousStatus;
+    if (input.resumeExecution && previousStatus === "failed") {
+        await updateExecution(exec.id, {
+            status: "running",
+            updatedAt: new Date(),
+        });
+        newStatus = "running";
+    }
+    return {
+        success: true,
+        branch: input.branch,
+        message: previousStatus === "failed" && input.resumeExecution
+            ? "Stagnation counters reset and execution resumed"
+            : "Stagnation counters reset",
+        previousStatus,
+        newStatus,
+    };
+}

package/dist/tools/retry.d.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+export declare const retryInputSchema: z.ZodObject<{
+    branch: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    branch: string;
+}, {
+    branch: string;
+}>;
+export type RetryInput = z.infer<typeof retryInputSchema>;
+export interface RetryResult {
+    success: boolean;
+    branch: string;
+    message: string;
+    previousStatus: string;
+    agentPrompt: string | null;
+    progress: {
+        completed: number;
+        total: number;
+        percentage: number;
+    };
+}
+/**
+ * Retry a failed PRD execution.
+ * Resets stagnation counters and generates a new agent prompt.
+ */
+export declare function retry(input: RetryInput): Promise<RetryResult>;

package/dist/tools/retry.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { findExecutionByBranch, listUserStoriesByExecutionId, resetStagnation, updateExecution, } from "../store/state.js";
+import { generateAgentPrompt } from "../utils/agent.js";
+export const retryInputSchema = z.object({
+    branch: z.string().describe("Branch name (e.g., ralph/task1-agent)"),
+});
+/**
+ * Retry a failed PRD execution.
+ * Resets stagnation counters and generates a new agent prompt.
+ */
+export async function retry(input) {
+    const exec = await findExecutionByBranch(input.branch);
+    if (!exec) {
+        throw new Error(`No execution found for branch: ${input.branch}`);
+    }
+    const previousStatus = exec.status;
+    // Only allow retry for failed or stopped executions
+    if (previousStatus !== "failed" && previousStatus !== "stopped") {
+        return {
+            success: false,
+            branch: input.branch,
+            message: `Cannot retry execution with status '${previousStatus}'. Only 'failed' or 'stopped' executions can be retried.`,
+            previousStatus,
+            agentPrompt: null,
+            progress: { completed: 0, total: 0, percentage: 0 },
+        };
+    }
+    // Reset stagnation counters
+    await resetStagnation(exec.id);
+    // Set status back to running
+    await updateExecution(exec.id, {
+        status: "running",
+        updatedAt: new Date(),
+    });
+    // Get stories and generate new agent prompt
+    const stories = await listUserStoriesByExecutionId(exec.id);
+    const completed = stories.filter((s) => s.passes).length;
+    const total = stories.length;
+    const agentPrompt = generateAgentPrompt(exec.branch, exec.description, exec.worktreePath || exec.projectRoot, stories.map((s) => ({
+        storyId: s.storyId,
+        title: s.title,
+        description: s.description,
+        acceptanceCriteria: s.acceptanceCriteria,
+        priority: s.priority,
+        passes: s.passes,
+    })), undefined, // contextPath - would need to re-read from PRD
+    {
+        loopCount: 0, // Reset loop context for fresh start
+        consecutiveNoProgress: 0,
+        consecutiveErrors: 0,
+        lastError: null,
+    });
+    return {
+        success: true,
+        branch: input.branch,
+        message: `Execution retried. ${total - completed} stories remaining.`,
+        previousStatus,
+        agentPrompt,
+        progress: {
+            completed,
+            total,
+            percentage: total > 0 ? Math.round((completed / total) * 100) : 0,
+        },
+    };
+}

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[];
@@ -30,6 +34,7 @@ export interface StatusResult {
         completed: number;
         failed: number;
         pending: number;
+        atRisk: number;
     };
 }
 export declare function status(input: StatusInput): Promise<StatusResult>;

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)
@@ -45,6 +50,7 @@ export async function status(input) {
         completed: executionStatuses.filter((e) => e.status === "completed").length,
         failed: executionStatuses.filter((e) => e.status === "failed").length,
         pending: executionStatuses.filter((e) => e.status === "pending").length,
+        atRisk: executionStatuses.filter((e) => e.consecutiveNoProgress >= 2 || e.consecutiveErrors >= 3).length,
     };
     return {
         executions: executionStatuses,

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` : ""}
@@ -83,8 +100,22 @@ Before implementing, verify the story is small enough to complete in ONE context
 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
@@ -107,6 +138,11 @@ Provide structured learnings in the \`notes\` field:
 - Follow existing code patterns
 - 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.14",
+  "version": "1.1.1",
   "description": "MCP server for autonomous PRD execution with Claude Code. Git worktree isolation, progress tracking, auto-merge.",
   "type": "module",
   "main": "dist/index.js",