dino-spec 16.2.0 → 17.2.0

package/dist/mcp/tools/ralph.js

@@ -21,18 +21,20 @@
  * - Optional context restore on rollback (restoreContext parameter)
  * - Hash verification for integrity
  */
-import { defineTool, registry, } from '../registry.js';
-import { initProgress, loadProgress, saveProgress, startIteration, completeIteration, failIteration, markStoryComplete, markStoryFailed, getNextStory, getStory, getProgressSummary, buildSubAgentContext, formatContextForHandoff, buildCheckpointCommand, DEFAULT_RALPH_CONFIG, 
-// Git integration (v11.6.0)
-createCheckpoint, createCheckpointTag, listRalphCheckpoints, getCheckpointCommit, rollbackToCheckpoint, cleanupRalphCheckpoints, detectExistingRalphLoop, 
-// PRD Generation (v11.7.0)
-planToPRD, formatPRDMarkdown, 
+// Context checkpoint restore (v12.5.0)
+import { createContextCheckpoint, getContextCheckpointByIteration, removeCheckpointsAfterIteration, restoreContextFromCheckpoint, } from '../../core/checkpoints/checkpoint-store.js';
+import { areStoriesIndependent, buildCheckpointCommand, buildParallelTaskSpawnParams, buildSubAgentContext, buildTaskSpawnParams, cleanupRalphCheckpoints, completeIteration, 
 // Learning Consolidation (v11.7.0)
-consolidateLearnings, exportToResearchFormat, 
+consolidateLearnings, 
+// Git integration (v11.6.0)
+createCheckpoint, createCheckpointTag, createEmptyStore, 
+// Branch strategy (v14.1.0)
+createStoryBranch, DEFAULT_RALPH_CONFIG, detectExistingRalphLoop, exportToResearchFormat, failIteration, formatContextForHandoff, formatMetricsMarkdown, formatPRDMarkdown, getCheckpointCommit, getMetricsSummary, getNextStory, getProgressSummary, getStory, groupStoriesForParallelExecution, initProgress, listRalphCheckpoints, 
 // Metrics (v11.7.0)
-loadMetrics, createEmptyStore, recordRunCompletion, formatMetricsMarkdown, getMetricsSummary, storiesToTasks, groupStoriesForParallelExecution, areStoriesIndependent, buildTaskSpawnParams, buildParallelTaskSpawnParams, } from '../../core/ralph/index.js';
-// Context checkpoint restore (v12.5.0)
-import { createContextCheckpoint, restoreContextFromCheckpoint, getContextCheckpointByIteration, removeCheckpointsAfterIteration, } from '../../core/checkpoints/checkpoint-store.js';
+loadMetrics, loadProgress, markStoryComplete, markStoryFailed, 
+// PRD Generation (v11.7.0)
+planToPRD, recordRunCompletion, rollbackToCheckpoint, saveProgress, startIteration, storiesToTasks, } from '../../core/ralph/index.js';
+import { defineTool, registry } from '../registry.js';
 // =============================================================================
 // PRD Parser Helper
 // =============================================================================
@@ -76,7 +78,7 @@ export function parsePRD(content, overrideTitle) {
         const storyMatch = line.match(storyPattern);
         if (storyMatch) {
             // Save previous story
-            if (currentStory && currentStory.id) {
+            if (currentStory?.id) {
                 stories.push(finalizeStory(currentStory));
             }
             currentStory = {
@@ -103,8 +105,8 @@ export function parsePRD(content, overrideTitle) {
         if (filesMatch) {
             currentStory.files = filesMatch[1]
                 .split(',')
-                .map(f => f.trim())
-                .filter(f => f.length > 0);
+                .map((f) => f.trim())
+                .filter((f) => f.length > 0);
             continue;
         }
         // Parse Test Command
@@ -132,7 +134,7 @@ export function parsePRD(content, overrideTitle) {
         }
     }
     // Don't forget the last story
-    if (currentStory && currentStory.id) {
+    if (currentStory?.id) {
         stories.push(finalizeStory(currentStory));
     }
     // Estimate iterations (1-2 per story)
@@ -199,10 +201,10 @@ async function handleRalphInit(params, projectDir) {
     const config = {
         ...DEFAULT_RALPH_CONFIG,
         maxIterations: params.maxIterations
-            ? parseInt(params.maxIterations, 10)
+            ? Number.parseInt(params.maxIterations, 10)
             : DEFAULT_RALPH_CONFIG.maxIterations,
         maxIterationsPerStory: params.maxPerStory
-            ? parseInt(params.maxPerStory, 10)
+            ? Number.parseInt(params.maxPerStory, 10)
             : DEFAULT_RALPH_CONFIG.maxIterationsPerStory,
         createCheckpoints: params.createCheckpoint !== 'false',
     };
@@ -394,9 +396,13 @@ async function handleRalphStatus(params, projectDir) {
     lines.push('| Story | Status | Iterations | Files |');
     lines.push('|-------|--------|------------|-------|');
     for (const story of progress.stories) {
-        const statusIcon = story.status === 'completed' ? '`done`' :
-            story.status === 'in_progress' ? '`work`' :
-                story.status === 'failed' ? '`fail`' : '`wait`';
+        const statusIcon = story.status === 'completed'
+            ? '`done`'
+            : story.status === 'in_progress'
+                ? '`work`'
+                : story.status === 'failed'
+                    ? '`fail`'
+                    : '`wait`';
         lines.push(`| ${story.title} | ${statusIcon} | ${story.iterations} | ${story.files.length} |`);
     }
     lines.push('');
@@ -415,8 +421,7 @@ async function handleRalphStatus(params, projectDir) {
         lines.push('| # | Story | Status | Tests | Checkpoint |');
         lines.push('|---|-------|--------|-------|------------|');
         for (const iter of progress.iterations) {
-            const statusIcon = iter.status === 'completed' ? '`done`' :
-                iter.status === 'running' ? '`run`' : '`fail`';
+            const statusIcon = iter.status === 'completed' ? '`done`' : iter.status === 'running' ? '`run`' : '`fail`';
             const testsIcon = iter.testsPassed ? '`pass`' : '`fail`';
             lines.push(`| ${iter.number} | ${iter.storyId} | ${statusIcon} | ${testsIcon} | ${iter.checkpointCommit.substring(0, 7)} |`);
         }
@@ -445,9 +450,7 @@ async function handleRalphStatus(params, projectDir) {
     if (progress.learnings.length > 0) {
         lines.push('## Learnings');
         lines.push('');
-        const displayLearnings = verbose
-            ? progress.learnings
-            : progress.learnings.slice(-5);
+        const displayLearnings = verbose ? progress.learnings : progress.learnings.slice(-5);
         for (const learning of displayLearnings) {
             lines.push(`- ${learning}`);
         }
@@ -468,7 +471,7 @@ async function handleRalphLearn(params, projectDir) {
         return `**Error:** No active Ralph Loop.`;
     }
     // Validate active iteration
-    const currentIteration = progress.iterations.find(i => i.number === progress.currentIteration && i.status === 'running');
+    const currentIteration = progress.iterations.find((i) => i.number === progress.currentIteration && i.status === 'running');
     if (!currentIteration) {
         return `**Error:** No active iteration. Call \`dino_ralph_iterate\` first.`;
     }
@@ -537,7 +540,9 @@ async function handleRalphLearn(params, projectDir) {
             lines.push('No more stories available.');
         }
     }
-    else if (!testsPassed && story && story.iterations < DEFAULT_RALPH_CONFIG.maxIterationsPerStory) {
+    else if (!testsPassed &&
+        story &&
+        story.iterations < DEFAULT_RALPH_CONFIG.maxIterationsPerStory) {
         lines.push(`Tests failed. Can retry this story (${story.iterations}/${DEFAULT_RALPH_CONFIG.maxIterationsPerStory} attempts).`);
         lines.push('Call `dino_ralph_iterate` to retry with learnings applied.');
     }
@@ -552,8 +557,8 @@ async function handleRalphLearn(params, projectDir) {
  * Enhanced with optional context state restoration.
  */
 async function handleRalphRestore(params, projectDir) {
-    const iteration = parseInt(params.iteration, 10);
-    if (isNaN(iteration) || iteration < 1) {
+    const iteration = Number.parseInt(params.iteration, 10);
+    if (Number.isNaN(iteration) || iteration < 1) {
         return '**Error:** Invalid iteration number. Must be a positive integer.';
     }
     const restoreContext = params.restoreContext === 'true';
@@ -609,7 +614,7 @@ async function handleRalphRestore(params, projectDir) {
         const progress = await loadProgress(projectDir);
         if (progress) {
             // Reset iterations after this point
-            progress.iterations = progress.iterations.filter(i => i.number < iteration);
+            progress.iterations = progress.iterations.filter((i) => i.number < iteration);
             progress.currentIteration = iteration - 1;
             progress.status = 'iterating';
             await saveProgress(projectDir, progress);
@@ -645,8 +650,8 @@ async function handleRalphRestore(params, projectDir) {
  * Cleanup old Ralph checkpoints (v11.6.0)
  */
 async function handleRalphCleanup(params, projectDir) {
-    const keepLast = parseInt(params.keepLast || '3', 10);
-    if (isNaN(keepLast) || keepLast < 0) {
+    const keepLast = Number.parseInt(params.keepLast || '3', 10);
+    if (Number.isNaN(keepLast) || keepLast < 0) {
         return '**Error:** keepLast must be a non-negative integer.';
     }
     try {
@@ -658,10 +663,10 @@ async function handleRalphCleanup(params, projectDir) {
             '# ✓ Checkpoints Cleaned',
             '',
             `**Removed:** ${result.removed.length} checkpoint(s)`,
-            result.removed.map(t => `- ${t}`).join('\n'),
+            result.removed.map((t) => `- ${t}`).join('\n'),
             '',
             `**Kept:** ${result.kept.length} checkpoint(s)`,
-            result.kept.map(t => `- ${t}`).join('\n'),
+            result.kept.map((t) => `- ${t}`).join('\n'),
         ].join('\n');
     }
     catch (error) {
@@ -1058,16 +1063,16 @@ async function handleRalphIterateParallel(params, projectDir) {
     if (progress.status === 'completed') {
         return `**Ralph Loop Complete**\n\n${getProgressSummary(progress)}\n\nAll stories have been completed.`;
     }
-    const maxParallel = parseInt(params.maxParallel || '3', 10);
-    if (isNaN(maxParallel) || maxParallel < 1) {
+    const maxParallel = Number.parseInt(params.maxParallel || '3', 10);
+    if (Number.isNaN(maxParallel) || maxParallel < 1) {
         return `**Error:** maxParallel must be a positive integer.`;
     }
     // Get stories to execute
     let storiesToExecute;
     if (params.storyIds) {
         // Use specified stories
-        const ids = params.storyIds.split(',').map(id => id.trim());
-        storiesToExecute = progress.stories.filter(s => ids.includes(s.id));
+        const ids = params.storyIds.split(',').map((id) => id.trim());
+        storiesToExecute = progress.stories.filter((s) => ids.includes(s.id));
         if (storiesToExecute.length === 0) {
             return `**Error:** No stories found matching IDs: ${params.storyIds}`;
         }
@@ -1093,24 +1098,44 @@ async function handleRalphIterateParallel(params, projectDir) {
     if (storiesToExecute.length === 1) {
         return `**Only one story available for parallel execution.**\n\nUse \`dino_ralph_iterate\` for single story execution, or check if other stories have dependencies.`;
     }
+    const useBranches = params.useBranches === 'true';
     const lines = [];
+    const storyBranches = new Map();
     lines.push(`# Parallel Iteration Ready`);
     lines.push('');
     lines.push(`**Stories:** ${storiesToExecute.length}`);
     lines.push(`**Max Parallel:** ${maxParallel}`);
+    lines.push(`**Isolation:** ${useBranches ? 'Git branches' : 'Checkpoints'}`);
     lines.push('');
     // Create batch checkpoint
-    lines.push('## Git Checkpoint');
+    lines.push('## Git Setup');
     lines.push('');
+    const batchNum = progress.currentIteration + 1;
     try {
-        const batchNum = progress.currentIteration + 1;
         const commitHash = await createCheckpoint(batchNum, projectDir);
         await createCheckpointTag(batchNum, projectDir);
         lines.push(`Created checkpoint: \`${commitHash.substring(0, 7)}\` (ralph-cp-${batchNum})`);
+        // Create story branches if using branch strategy
+        if (useBranches) {
+            lines.push('');
+            lines.push('**Story Branches:**');
+            for (const story of storiesToExecute) {
+                try {
+                    await createStoryBranch(story.id, projectDir);
+                    const branchName = `ralph-story-${story.id}`;
+                    storyBranches.set(story.id, branchName);
+                    lines.push(`- \`${branchName}\` created`);
+                }
+                catch (branchError) {
+                    lines.push(`- ⚠️ ${story.id}: Branch creation failed - ${branchError instanceof Error ? branchError.message : 'Unknown'}`);
+                }
+            }
+        }
         lines.push('');
     }
     catch (error) {
-        lines.push(`Warning: Checkpoint creation failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        lines.push(`Warning: Git setup failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        lines.push('Falling back to checkpoint-only strategy.');
         lines.push('');
     }
     // Generate Task tool spawn parameters for each story
@@ -1121,22 +1146,45 @@ async function handleRalphIterateParallel(params, projectDir) {
     const spawnParams = buildParallelTaskSpawnParams(storiesToExecute, progress);
     for (let i = 0; i < storiesToExecute.length; i++) {
         const story = storiesToExecute[i];
-        const params = spawnParams[i];
+        const taskParams = spawnParams[i];
+        const branchName = storyBranches.get(story.id);
         lines.push(`### ${i + 1}. ${story.title} (${story.id})`);
+        if (branchName) {
+            lines.push(`**Branch:** \`${branchName}\``);
+        }
         lines.push('');
         lines.push('```json');
+        // Build prompt with branch info if applicable
+        let promptText = `Implement story: ${story.title}\n\nFiles: ${story.files.join(', ')}\n\nAcceptance Criteria:\n${story.acceptanceCriteria.map((c) => `- ${c}`).join('\n')}\n\nTest: ${story.testCommand}`;
+        if (branchName) {
+            promptText = `[Branch: ${branchName}]\n\n${promptText}`;
+        }
         lines.push(JSON.stringify({
-            description: params.description,
-            subagent_type: params.subagent_type,
-            run_in_background: params.run_in_background,
-            model: params.model,
-            prompt: `Implement story: ${story.title}\n\nFiles: ${story.files.join(', ')}\n\nAcceptance Criteria:\n${story.acceptanceCriteria.map(c => `- ${c}`).join('\n')}\n\nTest: ${story.testCommand}`,
+            description: taskParams.description,
+            subagent_type: taskParams.subagent_type,
+            run_in_background: taskParams.run_in_background,
+            model: taskParams.model,
+            prompt: promptText,
         }, null, 2));
         lines.push('```');
         lines.push('');
     }
-    lines.push('## After Completion');
-    lines.push('');
+    // Merge instructions if using branches
+    if (useBranches && storyBranches.size > 0) {
+        lines.push('## After Completion (Branch Merge)');
+        lines.push('');
+        lines.push('After all stories complete, merge branches in sequence:');
+        lines.push('');
+        lines.push('1. Check for conflicts: `dino_parallel_status`');
+        lines.push('2. Merge each branch: `git checkout main && git merge --no-ff ralph-story-{id}`');
+        lines.push('3. Delete merged branches: `git branch -d ralph-story-{id}`');
+        lines.push('');
+        lines.push('Or use `dino_ralph_merge_branches` (coming soon) for automatic merge.');
+    }
+    else {
+        lines.push('## After Completion');
+        lines.push('');
+    }
     lines.push('For each story, call `dino_ralph_learn` with the story results.');
     lines.push('Learnings from parallel stories will be consolidated automatically.');
     // Update progress to track parallel execution
@@ -1151,7 +1199,7 @@ async function handleRalphIterateParallel(params, projectDir) {
  */
 export const ralphIterateParallelTool = defineTool({
     name: 'dino_ralph_iterate_parallel',
-    description: 'Execute multiple independent stories in parallel for faster completion',
+    description: 'Execute multiple independent stories in parallel for faster completion (v14.1.0: branch isolation)',
     category: 'agent',
     inputSchema: {
         type: 'object',
@@ -1164,20 +1212,178 @@ export const ralphIterateParallelTool = defineTool({
                 type: 'string',
                 description: 'Comma-separated list of specific story IDs to execute (optional)',
             },
+            useBranches: {
+                type: 'string',
+                description: 'Use git branches for isolation instead of checkpoints (default: "false")',
+            },
         },
     },
     handler: handleRalphIterateParallel,
-    whenToUse: 'Use when multiple stories have no shared files and can be executed concurrently. Provides ~2x speedup for independent stories.',
+    whenToUse: 'Use when multiple stories have no shared files and can be executed concurrently. Set useBranches="true" for git branch isolation with conflict detection.',
     relatedTools: ['dino_ralph_iterate', 'dino_ralph_init', 'dino_ralph_learn'],
     version: '12.1.0',
 });
-// =============================================================================
-// Exports
-// =============================================================================
 /**
- * All Ralph tools (v12.1.0)
+ * Detect Ralph Loop state and return appropriate action
+ */
+async function handleRalphDetect(input, projectDir) {
+    const { existsSync, readFileSync } = await import('node:fs');
+    const { join } = await import('node:path');
+    const stateJsonPath = join(projectDir, '.dino', 'ralph-state.json');
+    const progressMdPath = join(projectDir, '.dino', 'ralph-progress.md');
+    const prdPath = join(projectDir, '.dino', 'prd.md');
+    const lines = [];
+    lines.push('# Ralph Loop State Detection');
+    lines.push('');
+    // Case 1: Check for new state format (ralph-state.json)
+    if (existsSync(stateJsonPath)) {
+        try {
+            const stateContent = readFileSync(stateJsonPath, 'utf-8');
+            const state = JSON.parse(stateContent);
+            if (state.phase === 'completed') {
+                lines.push('## Status: COMPLETED');
+                lines.push('');
+                lines.push(`**PRD:** ${state.prdTitle}`);
+                lines.push(`**Stories:** ${state.metrics?.storiesCompleted || 0}/${state.stories?.length || 0} completed`);
+                lines.push(`**Completed:** ${state.completedAt || 'unknown'}`);
+                lines.push('');
+                lines.push('### Action Required');
+                lines.push('');
+                lines.push('The previous Ralph Loop is **complete**. To start a new loop:');
+                lines.push('1. Provide a new PRD with stories');
+                lines.push('2. Or call `dino_ralph_init` with PRD content');
+                return lines.join('\n');
+            }
+            if (state.phase === 'executing') {
+                const nextStory = state.stories?.find((s) => s.status === 'pending' || s.status === 'in_progress');
+                lines.push('## Status: IN PROGRESS');
+                lines.push('');
+                lines.push(`**PRD:** ${state.prdTitle}`);
+                lines.push(`**Iteration:** ${state.iteration}/${state.maxIterations}`);
+                lines.push(`**Progress:** ${state.metrics?.storiesCompleted || 0}/${state.stories?.length || 0} stories`);
+                lines.push('');
+                if (nextStory) {
+                    lines.push('### Current Story');
+                    lines.push('');
+                    lines.push(`**Title:** ${nextStory.title}`);
+                    lines.push(`**ID:** ${nextStory.id}`);
+                    lines.push(`**Files:** ${nextStory.files?.join(', ') || 'none'}`);
+                    lines.push('');
+                    lines.push('**Acceptance Criteria:**');
+                    for (const criterion of nextStory.acceptanceCriteria || []) {
+                        lines.push(`- [ ] ${criterion}`);
+                    }
+                    lines.push('');
+                    lines.push(`**Test Command:** \`${nextStory.testCommand || 'bun run vitest run'}\``);
+                    lines.push('');
+                    lines.push('### Action Required');
+                    lines.push('');
+                    lines.push('1. Read the files listed above');
+                    lines.push('2. Implement changes to satisfy acceptance criteria');
+                    lines.push('3. Run the test command');
+                    lines.push('4. Update state with `dino_ralph_learn`');
+                }
+                return lines.join('\n');
+            }
+        }
+        catch (e) {
+            lines.push(`Warning: Could not parse ralph-state.json: ${e}`);
+        }
+    }
+    // Case 2: Check for legacy format (ralph-progress.md)
+    if (existsSync(progressMdPath)) {
+        const progressContent = readFileSync(progressMdPath, 'utf-8');
+        if (progressContent.includes('COMPLETE')) {
+            lines.push('## Status: COMPLETED (Legacy Format)');
+            lines.push('');
+            lines.push('The previous Ralph Loop is **complete** (detected from ralph-progress.md).');
+            lines.push('');
+            lines.push('### Action Required');
+            lines.push('');
+            lines.push('To start a new loop:');
+            lines.push('1. Provide a new PRD with stories');
+            lines.push('2. Or call `dino_ralph_init` with PRD content');
+            return lines.join('\n');
+        }
+        // Incomplete legacy format - suggest migration
+        lines.push('## Status: LEGACY FORMAT DETECTED');
+        lines.push('');
+        lines.push('Found incomplete ralph-progress.md. Consider:');
+        lines.push('1. Migrating to new format with `dino_ralph_init`');
+        lines.push('2. Or continuing manually');
+        return lines.join('\n');
+    }
+    // Case 3: Check if PRD provided in input
+    if (input.prd && input.prd.trim().length > 0) {
+        lines.push('## Status: NEW PRD PROVIDED');
+        lines.push('');
+        lines.push('PRD content detected in input. Ready to initialize.');
+        lines.push('');
+        lines.push('### Action Required');
+        lines.push('');
+        lines.push('Call `dino_ralph_init` with the PRD content to start a new Ralph Loop.');
+        return lines.join('\n');
+    }
+    // Case 4: Check if there's a PRD file
+    if (existsSync(prdPath)) {
+        lines.push('## Status: PRD FILE EXISTS');
+        lines.push('');
+        lines.push(`Found PRD file at: .dino/prd.md`);
+        lines.push('');
+        lines.push('### Action Required');
+        lines.push('');
+        lines.push('To start a new Ralph Loop with this PRD:');
+        lines.push('1. Review the PRD content');
+        lines.push('2. Call `dino_ralph_init` with the PRD content');
+        return lines.join('\n');
+    }
+    // Case 5: No state, no PRD
+    lines.push('## Status: NO ACTIVE LOOP');
+    lines.push('');
+    lines.push('No Ralph Loop state found. No PRD provided.');
+    lines.push('');
+    lines.push('### Action Required');
+    lines.push('');
+    lines.push('To start a Ralph Loop, provide a PRD with stories in this format:');
+    lines.push('');
+    lines.push('```markdown');
+    lines.push('# Feature Title');
+    lines.push('');
+    lines.push('### Story: Story Title');
+    lines.push('**ID:** S1');
+    lines.push('**Files:** src/file.ts');
+    lines.push('**Acceptance Criteria:**');
+    lines.push('- [ ] Criterion 1');
+    lines.push('**Test Command:** bun run vitest run');
+    lines.push('```');
+    return lines.join('\n');
+}
+/**
+ * Ralph detect tool definition (v17.0.0)
+ */
+export const ralphDetectTool = defineTool({
+    name: 'dino_ralph_detect',
+    description: 'Automatically detect Ralph Loop state and return next action. Call this FIRST when /dino.ralph is invoked.',
+    category: 'agent',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            prd: {
+                type: 'string',
+                description: 'Optional PRD content to initialize a new loop',
+            },
+        },
+    },
+    handler: handleRalphDetect,
+    whenToUse: 'Call this at the start of /dino.ralph to detect current state and get instructions for next action.',
+    relatedTools: ['dino_ralph_init', 'dino_ralph_iterate', 'dino_ralph_learn'],
+    version: '17.0.0',
+});
+/**
+ * All Ralph tools (v17.0.0)
  */
 export const ralphTools = [
+    ralphDetectTool,
     ralphInitTool,
     ralphIterateTool,
     ralphIterateParallelTool,