agileflow 2.79.0 → 2.81.0

package/scripts/obtain-context.js

@@ -18,12 +18,14 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
+const { c: C, box } = require('../lib/colors');
+const { isValidCommandName } = require('../lib/validate');
 
 const DISPLAY_LIMIT = 30000; // Claude Code's Bash tool display limit
 
 // Optional: Register command for PreCompact context preservation
 const commandName = process.argv[2];
-if (commandName) {
+if (commandName && isValidCommandName(commandName)) {
   const sessionStatePath = 'docs/09-agents/session-state.json';
   if (fs.existsSync(sessionStatePath)) {
     try {
@@ -44,8 +46,10 @@ if (commandName) {
         state: {},
       });
 
-      // Keep backwards compatibility - also set singular active_command to most recent
-      state.active_command = state.active_commands[state.active_commands.length - 1];
+      // Remove legacy active_command field (only use active_commands array now)
+      if (state.active_command !== undefined) {
+        delete state.active_command;
+      }
 
       fs.writeFileSync(sessionStatePath, JSON.stringify(state, null, 2) + '\n');
     } catch (e) {
@@ -54,33 +58,6 @@ if (commandName) {
   }
 }
 
-// ANSI colors
-const C = {
-  reset: '\x1b[0m',
-  dim: '\x1b[2m',
-  bold: '\x1b[1m',
-  cyan: '\x1b[36m',
-  yellow: '\x1b[33m',
-  green: '\x1b[32m',
-  red: '\x1b[31m',
-  magenta: '\x1b[35m',
-  blue: '\x1b[34m',
-  brightCyan: '\x1b[96m',
-  brightYellow: '\x1b[93m',
-  brightGreen: '\x1b[92m',
-  brand: '\x1b[38;2;232;104;58m', // AgileFlow brand orange
-
-  // Vibrant 256-color palette (modern, sleek look)
-  mintGreen: '\x1b[38;5;158m',    // Healthy/success states
-  peach: '\x1b[38;5;215m',        // Warning states
-  coral: '\x1b[38;5;203m',        // Critical/error states
-  lightGreen: '\x1b[38;5;194m',   // Session healthy
-  lightYellow: '\x1b[38;5;228m',  // Session warning
-  skyBlue: '\x1b[38;5;117m',      // Directories/paths
-  lavender: '\x1b[38;5;147m',     // Model info
-  softGold: '\x1b[38;5;222m',     // Cost/money
-};
-
 function safeRead(filePath) {
   try {
     return fs.readFileSync(filePath, 'utf8');
@@ -225,7 +202,8 @@ function generateSummary() {
 
   // Header row (full width, no column divider)
   const title = commandName ? `Context [${commandName}]` : 'Context Summary';
-  const branchColor = branch === 'main' ? C.mintGreen : branch.startsWith('fix') ? C.coral : C.skyBlue;
+  const branchColor =
+    branch === 'main' ? C.mintGreen : branch.startsWith('fix') ? C.coral : C.skyBlue;
   const maxBranchLen = 20;
   const branchDisplay =
     branch.length > maxBranchLen ? branch.substring(0, maxBranchLen - 2) + '..' : branch;
@@ -300,7 +278,12 @@ function generateSummary() {
 
   // Research
   const researchText = researchFiles.length > 0 ? `${researchFiles.length} notes` : 'none';
-  summary += row('Research', researchText, C.lavender, researchFiles.length > 0 ? C.skyBlue : C.dim);
+  summary += row(
+    'Research',
+    researchText,
+    C.lavender,
+    researchFiles.length > 0 ? C.skyBlue : C.dim
+  );
 
   // Epics
   const epicText = epicFiles.length > 0 ? `${epicFiles.length} epics` : 'none';
@@ -396,7 +379,90 @@ function generateFullContent() {
     content += `${C.dim}No session-state.json found${C.reset}\n`;
   }
 
-  // 4. DOCS STRUCTURE (using vibrant 256-color palette)
+  // 4. SESSION CONTEXT (multi-session awareness)
+  content += `\n${C.skyBlue}${C.bold}═══ Session Context ═══${C.reset}\n`;
+  const sessionManagerPath = path.join(__dirname, 'session-manager.js');
+  const altSessionManagerPath = '.agileflow/scripts/session-manager.js';
+
+  if (fs.existsSync(sessionManagerPath) || fs.existsSync(altSessionManagerPath)) {
+    const managerPath = fs.existsSync(sessionManagerPath)
+      ? sessionManagerPath
+      : altSessionManagerPath;
+    const sessionStatus = safeExec(`node "${managerPath}" status`);
+
+    if (sessionStatus) {
+      try {
+        const statusData = JSON.parse(sessionStatus);
+        if (statusData.current) {
+          const session = statusData.current;
+          const isMain = session.is_main === true;
+
+          if (isMain) {
+            content += `Session: ${C.mintGreen}Main project${C.reset} (Session ${session.id || 1})\n`;
+          } else {
+            // NON-MAIN SESSION - Show prominent banner
+            const sessionName = session.nickname
+              ? `${session.id} "${session.nickname}"`
+              : `${session.id}`;
+            content += `${C.teal}${C.bold}🔀 SESSION ${sessionName} (worktree)${C.reset}\n`;
+            content += `Branch: ${C.skyBlue}${session.branch || 'unknown'}${C.reset}\n`;
+            content += `Path: ${C.dim}${session.path || process.cwd()}${C.reset}\n`;
+
+            // Calculate relative path to main
+            const mainPath = process.cwd().replace(/-[^/]+$/, ''); // Heuristic: strip session suffix
+            content += `Main project: ${C.dim}${mainPath}${C.reset}\n`;
+
+            // Remind about merge flow
+            content += `${C.lavender}💡 When done: /agileflow:session:end → merge to main${C.reset}\n`;
+          }
+
+          // Show other active sessions
+          if (statusData.otherActive > 0) {
+            content += `${C.peach}⚠️ ${statusData.otherActive} other session(s) active${C.reset}\n`;
+          }
+        } else {
+          content += `${C.dim}No session registered${C.reset}\n`;
+        }
+      } catch (e) {
+        content += `${C.dim}Session manager available but status parse failed${C.reset}\n`;
+      }
+    } else {
+      content += `${C.dim}Session manager available${C.reset}\n`;
+    }
+  } else {
+    content += `${C.dim}Multi-session not configured${C.reset}\n`;
+  }
+
+  // 5. INTERACTION MODE (AskUserQuestion guidance)
+  const metadata = safeReadJSON('docs/00-meta/agileflow-metadata.json');
+  const askUserQuestionConfig = metadata?.features?.askUserQuestion;
+
+  if (askUserQuestionConfig?.enabled) {
+    content += `\n${C.brand}${C.bold}═══ ⚡ INTERACTION MODE: AskUserQuestion ENABLED ═══${C.reset}\n`;
+    content += `${C.dim}${'─'.repeat(60)}${C.reset}\n`;
+    content += `${C.bold}CRITICAL RULE:${C.reset} End ${C.skyBlue}EVERY${C.reset} response with the AskUserQuestion tool.\n\n`;
+    content += `${C.mintGreen}✓ CORRECT:${C.reset} Call the actual AskUserQuestion tool\n`;
+    content += `${C.coral}✗ WRONG:${C.reset} Text like "Want me to continue?" or "What's next?"\n\n`;
+    content += `${C.lavender}Required format:${C.reset}\n`;
+    content += `${C.dim}\`\`\`xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "What would you like to do next?",
+  "header": "Next step",
+  "multiSelect": false,
+  "options": [
+    {"label": "Option A (Recommended)", "description": "Why this is best"},
+    {"label": "Option B", "description": "Alternative approach"},
+    {"label": "Pause", "description": "Stop here for now"}
+  ]
+}]</parameter>
+</invoke>
+\`\`\`${C.reset}\n`;
+    content += `${C.dim}${'─'.repeat(60)}${C.reset}\n`;
+    content += `${C.dim}Mode: ${askUserQuestionConfig.mode || 'all'} | Configure: /agileflow:configure${C.reset}\n\n`;
+  }
+
+  // 5. DOCS STRUCTURE (using vibrant 256-color palette)
   content += `\n${C.skyBlue}${C.bold}═══ Documentation ═══${C.reset}\n`;
   const docsDir = 'docs';
   const docFolders = safeLs(docsDir).filter(f => {
@@ -420,7 +486,7 @@ function generateFullContent() {
     });
   }
 
-  // 5. RESEARCH NOTES - List + Full content of most recent (using vibrant 256-color palette)
+  // 6. RESEARCH NOTES - List + Full content of most recent (using vibrant 256-color palette)
   content += `\n${C.skyBlue}${C.bold}═══ Research Notes ═══${C.reset}\n`;
   const researchDir = 'docs/10-research';
   const researchFiles = safeLs(researchDir).filter(f => f.endsWith('.md') && f !== 'README.md');
@@ -443,7 +509,7 @@ function generateFullContent() {
     content += `${C.dim}No research notes${C.reset}\n`;
   }
 
-  // 6. BUS MESSAGES (using vibrant 256-color palette)
+  // 7. BUS MESSAGES (using vibrant 256-color palette)
   content += `\n${C.skyBlue}${C.bold}═══ Recent Agent Messages ═══${C.reset}\n`;
   const busPath = 'docs/09-agents/bus/log.jsonl';
   const busContent = safeRead(busPath);
@@ -467,7 +533,7 @@ function generateFullContent() {
     content += `${C.dim}No bus log found${C.reset}\n`;
   }
 
-  // 7. KEY FILES - Full content
+  // 8. KEY FILES - Full content
   content += `\n${C.cyan}${C.bold}═══ Key Context Files (Full Content) ═══${C.reset}\n`;
 
   const keyFilesToRead = [
@@ -493,7 +559,7 @@ function generateFullContent() {
   const settingsExists = fs.existsSync('.claude/settings.json');
   content += `\n  ${settingsExists ? `${C.green}✓${C.reset}` : `${C.dim}○${C.reset}`} .claude/settings.json\n`;
 
-  // 8. EPICS FOLDER
+  // 9. EPICS FOLDER
   content += `\n${C.cyan}${C.bold}═══ Epic Files ═══${C.reset}\n`;
   const epicFiles = safeLs('docs/05-epics').filter(f => f.endsWith('.md') && f !== 'README.md');
   if (epicFiles.length > 0) {

package/scripts/ralph-loop.js

@@ -36,6 +36,7 @@ const { execSync, spawnSync } = require('child_process');
 const { c } = require('../lib/colors');
 const { getProjectRoot } = require('../lib/paths');
 const { safeReadJSON, safeWriteJSON } = require('../lib/errors');
+const { isValidEpicId, parseIntBounded } = require('../lib/validate');
 
 // Read session state
 function getSessionState(rootDir) {
@@ -103,6 +104,101 @@ function runTests(rootDir, testCommand) {
   return result;
 }
 
+// Get coverage command from metadata or default
+function getCoverageCommand(rootDir) {
+  const metadataPath = path.join(rootDir, 'docs/00-meta/agileflow-metadata.json');
+  const result = safeReadJSON(metadataPath, { defaultValue: {} });
+
+  if (result.ok && result.data?.ralph_loop?.coverage_command) {
+    return result.data.ralph_loop.coverage_command;
+  }
+
+  // Default: try common coverage commands
+  return 'npm run test:coverage || npm test -- --coverage';
+}
+
+// Get coverage report path from metadata or default
+function getCoverageReportPath(rootDir) {
+  const metadataPath = path.join(rootDir, 'docs/00-meta/agileflow-metadata.json');
+  const result = safeReadJSON(metadataPath, { defaultValue: {} });
+
+  if (result.ok && result.data?.ralph_loop?.coverage_report_path) {
+    return result.data.ralph_loop.coverage_report_path;
+  }
+
+  return 'coverage/coverage-summary.json';
+}
+
+// Parse coverage report (Jest/NYC format)
+function parseCoverageReport(rootDir) {
+  const reportPath = getCoverageReportPath(rootDir);
+  const fullPath = path.join(rootDir, reportPath);
+  const report = safeReadJSON(fullPath, { defaultValue: null });
+
+  if (!report.ok || !report.data) {
+    return { passed: false, coverage: 0, error: 'Coverage report not found at ' + reportPath };
+  }
+
+  // Jest/NYC format: { total: { lines: { pct: 80 }, statements: { pct: 80 } } }
+  const total = report.data.total;
+  if (!total) {
+    return { passed: false, coverage: 0, error: 'Invalid coverage report format' };
+  }
+
+  const coverage = total.lines?.pct || total.statements?.pct || 0;
+
+  return { passed: true, coverage, raw: report.data };
+}
+
+// Verify coverage meets threshold
+function verifyCoverage(rootDir, threshold) {
+  const result = parseCoverageReport(rootDir);
+
+  if (!result.passed) {
+    return {
+      passed: false,
+      coverage: 0,
+      message: `${c.red}✗ ${result.error}${c.reset}`,
+    };
+  }
+
+  const met = result.coverage >= threshold;
+
+  return {
+    passed: met,
+    coverage: result.coverage,
+    threshold: threshold,
+    message: met
+      ? `${c.green}✓ Coverage ${result.coverage.toFixed(1)}% ≥ ${threshold}%${c.reset}`
+      : `${c.yellow}⏳ Coverage ${result.coverage.toFixed(1)}% < ${threshold}% (need ${(threshold - result.coverage).toFixed(1)}% more)${c.reset}`,
+  };
+}
+
+// Run coverage command
+function runCoverage(rootDir) {
+  const coverageCmd = getCoverageCommand(rootDir);
+  const result = { passed: false, output: '', duration: 0 };
+  const startTime = Date.now();
+
+  try {
+    const output = execSync(coverageCmd, {
+      cwd: rootDir,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 300000, // 5 minute timeout
+    });
+    result.passed = true;
+    result.output = output;
+  } catch (e) {
+    // Coverage command might fail but still generate report
+    result.passed = true; // We'll check the report
+    result.output = e.stdout || '' + '\n' + (e.stderr || '');
+  }
+
+  result.duration = Date.now() - startTime;
+  return result;
+}
+
 // Get screenshots directory from metadata or default
 function getScreenshotsDir(rootDir) {
   try {
@@ -134,7 +230,7 @@ function verifyScreenshots(rootDir) {
   const imageExtensions = ['.png', '.jpg', '.jpeg', '.webp', '.gif'];
   let files;
   try {
-    files = fs.readdirSync(fullPath).filter((file) => {
+    files = fs.readdirSync(fullPath).filter(file => {
       const ext = path.extname(file).toLowerCase();
       return imageExtensions.includes(ext);
     });
@@ -253,13 +349,18 @@ function handleLoop(rootDir) {
   const iteration = (loop.iteration || 0) + 1;
   const maxIterations = loop.max_iterations || 20;
   const visualMode = loop.visual_mode || false;
-  const minIterations = visualMode ? 2 : 1; // Visual mode requires at least 2 iterations
+  const coverageMode = loop.coverage_mode || false;
+  const coverageThreshold = loop.coverage_threshold || 80;
+  // Visual and Coverage modes require at least 2 iterations for confirmation
+  const minIterations = visualMode || coverageMode ? 2 : 1;
 
   console.log('');
   console.log(
     `${c.brand}${c.bold}══════════════════════════════════════════════════════════${c.reset}`
   );
-  const modeLabel = visualMode ? ' [VISUAL MODE]' : '';
+  let modeLabel = '';
+  if (visualMode) modeLabel += ' [VISUAL]';
+  if (coverageMode) modeLabel += ` [COVERAGE ≥${coverageThreshold}%]`;
   console.log(
     `${c.brand}${c.bold}  RALPH LOOP - Iteration ${iteration}/${maxIterations}${modeLabel}${c.reset}`
   );
@@ -320,44 +421,84 @@ function handleLoop(rootDir) {
         console.log(`${c.yellow}⚠ ${screenshotResult.output}${c.reset}`);
         if (screenshotResult.unverified.length > 0) {
           console.log(`${c.dim}Unverified screenshots:${c.reset}`);
-          screenshotResult.unverified.slice(0, 5).forEach((file) => {
+          screenshotResult.unverified.slice(0, 5).forEach(file => {
             console.log(`  ${c.yellow}- ${file}${c.reset}`);
           });
           if (screenshotResult.unverified.length > 5) {
-            console.log(`  ${c.dim}... and ${screenshotResult.unverified.length - 5} more${c.reset}`);
+            console.log(
+              `  ${c.dim}... and ${screenshotResult.unverified.length - 5} more${c.reset}`
+            );
           }
         }
         state.ralph_loop.screenshots_verified = false;
       }
     }
 
-    // Visual Mode: Enforce minimum iterations
-    if (visualMode && iteration < minIterations) {
+    // Coverage Mode: Run coverage and verify threshold
+    let coverageResult = { passed: true };
+    if (coverageMode) {
+      console.log('');
+      console.log(`${c.blue}Running coverage check...${c.reset}`);
+      runCoverage(rootDir);
+      coverageResult = verifyCoverage(rootDir, coverageThreshold);
+      console.log(coverageResult.message);
+
+      // Update state with current coverage
+      state.ralph_loop.coverage_current = coverageResult.coverage;
+
+      if (coverageResult.passed) {
+        state.ralph_loop.coverage_verified = true;
+      } else {
+        state.ralph_loop.coverage_verified = false;
+      }
+    }
+
+    // Enforce minimum iterations for Visual and Coverage modes
+    if ((visualMode || coverageMode) && iteration < minIterations) {
+      const modeNames = [];
+      if (visualMode) modeNames.push('Visual');
+      if (coverageMode) modeNames.push('Coverage');
+
       console.log('');
-      console.log(`${c.yellow}⚠ Visual Mode requires ${minIterations}+ iterations for confirmation${c.reset}`);
-      console.log(`${c.dim}Current: iteration ${iteration}. Let loop run once more to confirm.${c.reset}`);
+      console.log(
+        `${c.yellow}⚠ ${modeNames.join(' + ')} Mode requires ${minIterations}+ iterations for confirmation${c.reset}`
+      );
+      console.log(
+        `${c.dim}Current: iteration ${iteration}. Let loop run once more to confirm.${c.reset}`
+      );
 
       state.ralph_loop.iteration = iteration;
       saveSessionState(rootDir, state);
 
       console.log('');
-      console.log(`${c.brand}▶ Continue reviewing. Loop will verify again.${c.reset}`);
+      console.log(`${c.brand}▶ Continue working. Loop will verify again.${c.reset}`);
       return;
     }
 
-    // Check if both tests AND screenshots (in visual mode) passed
-    const canComplete = testResult.passed && (!visualMode || screenshotResult.passed);
+    // Check if all verification modes passed
+    const canComplete =
+      testResult.passed &&
+      (!visualMode || screenshotResult.passed) &&
+      (!coverageMode || coverageResult.passed);
 
     if (!canComplete) {
-      // Screenshots not verified yet
+      // Something not verified yet
       state.ralph_loop.iteration = iteration;
       saveSessionState(rootDir, state);
 
       console.log('');
-      console.log(`${c.cyan}▶ Review unverified screenshots:${c.reset}`);
-      console.log(`${c.dim}  1. View each screenshot in screenshots/ directory${c.reset}`);
-      console.log(`${c.dim}  2. Rename verified files with 'verified-' prefix${c.reset}`);
-      console.log(`${c.dim}  3. Loop will re-verify when you stop${c.reset}`);
+      if (visualMode && !screenshotResult.passed) {
+        console.log(`${c.cyan}▶ Review unverified screenshots:${c.reset}`);
+        console.log(`${c.dim}  1. View each screenshot in screenshots/ directory${c.reset}`);
+        console.log(`${c.dim}  2. Rename verified files with 'verified-' prefix${c.reset}`);
+        console.log(`${c.dim}  3. Loop will re-verify when you stop${c.reset}`);
+      }
+      if (coverageMode && !coverageResult.passed) {
+        console.log(`${c.cyan}▶ Increase test coverage:${c.reset}`);
+        console.log(`${c.dim}  Current: ${coverageResult.coverage?.toFixed(1) || 0}%${c.reset}`);
+        console.log(`${c.dim}  Target: ${coverageThreshold}%${c.reset}`);
+        console.log(`${c.dim}  Write more tests to cover uncovered code paths.${c.reset}`);
+      }
       return;
     }
     console.log('');
@@ -452,15 +593,29 @@ function handleCLI() {
     if (!loop || !loop.enabled) {
       console.log(`${c.dim}Ralph Loop: not active${c.reset}`);
     } else {
-      const modeLabel = loop.visual_mode ? ` ${c.cyan}[VISUAL]${c.reset}` : '';
+      let modeLabel = '';
+      if (loop.visual_mode) modeLabel += ` ${c.cyan}[VISUAL]${c.reset}`;
+      if (loop.coverage_mode)
+        modeLabel += ` ${c.magenta}[COVERAGE ≥${loop.coverage_threshold}%]${c.reset}`;
       console.log(`${c.green}Ralph Loop: active${c.reset}${modeLabel}`);
       console.log(`  Epic: ${loop.epic}`);
       console.log(`  Current Story: ${loop.current_story}`);
       console.log(`  Iteration: ${loop.iteration || 0}/${loop.max_iterations || 20}`);
       if (loop.visual_mode) {
-        const verified = loop.screenshots_verified ? `${c.green}yes${c.reset}` : `${c.yellow}no${c.reset}`;
+        const verified = loop.screenshots_verified
+          ? `${c.green}yes${c.reset}`
+          : `${c.yellow}no${c.reset}`;
         console.log(`  Screenshots Verified: ${verified}`);
       }
+      if (loop.coverage_mode) {
+        const verified = loop.coverage_verified
+          ? `${c.green}yes${c.reset}`
+          : `${c.yellow}no${c.reset}`;
+        console.log(
+          `  Coverage: ${(loop.coverage_current || 0).toFixed(1)}% / ${loop.coverage_threshold}% (Verified: ${verified})`
+        );
+        console.log(`  Baseline: ${(loop.coverage_baseline || 0).toFixed(1)}%`);
+      }
     }
     return true;
   }
@@ -491,6 +646,7 @@ function handleCLI() {
     const epicArg = args.find(a => a.startsWith('--epic='));
     const maxArg = args.find(a => a.startsWith('--max='));
     const visualArg = args.includes('--visual') || args.includes('-v');
+    const coverageArg = args.find(a => a.startsWith('--coverage='));
 
     if (!epicArg) {
       console.log(`${c.red}Error: --epic=EP-XXXX is required${c.reset}`);
@@ -498,9 +654,28 @@ function handleCLI() {
     }
 
     const epicId = epicArg.split('=')[1];
-    const maxIterations = maxArg ? parseInt(maxArg.split('=')[1]) : 20;
+
+    // Validate epic ID format
+    if (!isValidEpicId(epicId)) {
+      console.log(`${c.red}Error: Invalid epic ID "${epicId}". Expected format: EP-XXXX${c.reset}`);
+      return true;
+    }
+
+    // Validate and bound max iterations (1-100)
+    const maxIterations = parseIntBounded(maxArg ? maxArg.split('=')[1] : null, 20, 1, 100);
     const visualMode = visualArg;
 
+    // Parse coverage threshold (0-100)
+    let coverageMode = false;
+    let coverageThreshold = 80;
+    if (coverageArg) {
+      coverageMode = true;
+      const threshold = parseFloat(coverageArg.split('=')[1]);
+      if (!isNaN(threshold)) {
+        coverageThreshold = Math.max(0, Math.min(100, threshold));
+      }
+    }
+
     // Find first ready story in epic
     const status = getStatus(rootDir);
     const stories = status.stories || {};
@@ -524,6 +699,18 @@ function handleCLI() {
     // Mark first story as in_progress
     markStoryInProgress(rootDir, storyId);
 
+    // Get baseline coverage if coverage mode is enabled
+    let coverageBaseline = 0;
+    if (coverageMode) {
+      console.log(`${c.dim}Running baseline coverage check...${c.reset}`);
+      runCoverage(rootDir);
+      const baseline = parseCoverageReport(rootDir);
+      if (baseline.passed) {
+        coverageBaseline = baseline.coverage;
+        console.log(`${c.dim}Baseline coverage: ${coverageBaseline.toFixed(1)}%${c.reset}`);
+      }
+    }
+
     // Initialize loop state
     const state = getSessionState(rootDir);
     state.ralph_loop = {
@@ -534,6 +721,11 @@ function handleCLI() {
       max_iterations: maxIterations,
       visual_mode: visualMode,
       screenshots_verified: false,
+      coverage_mode: coverageMode,
+      coverage_threshold: coverageThreshold,
+      coverage_baseline: coverageBaseline,
+      coverage_current: coverageBaseline,
+      coverage_verified: false,
       started_at: new Date().toISOString(),
     };
     saveSessionState(rootDir, state);
@@ -541,7 +733,9 @@ function handleCLI() {
     const progress = getEpicProgress(status, epicId);
 
     console.log('');
-    const modeLabel = visualMode ? ` ${c.cyan}[VISUAL MODE]${c.reset}` : '';
+    let modeLabel = '';
+    if (visualMode) modeLabel += ` ${c.cyan}[VISUAL]${c.reset}`;
+    if (coverageMode) modeLabel += ` ${c.magenta}[COVERAGE ≥${coverageThreshold}%]${c.reset}`;
     console.log(`${c.green}${c.bold}Ralph Loop Initialized${c.reset}${modeLabel}`);
     console.log(`${c.dim}${'─'.repeat(40)}${c.reset}`);
     console.log(`  Epic: ${c.cyan}${epicId}${c.reset}`);
@@ -549,6 +743,14 @@ function handleCLI() {
     console.log(`  Max Iterations: ${maxIterations}`);
     if (visualMode) {
       console.log(`  Visual Mode: ${c.cyan}enabled${c.reset} (screenshot verification)`);
+    }
+    if (coverageMode) {
+      console.log(
+        `  Coverage Mode: ${c.magenta}enabled${c.reset} (threshold: ${coverageThreshold}%)`
+      );
+      console.log(`  Baseline: ${coverageBaseline.toFixed(1)}%`);
+    }
+    if (visualMode || coverageMode) {
       console.log(`  Min Iterations: 2 (for confirmation)`);
     }
     console.log(`${c.dim}${'─'.repeat(40)}${c.reset}`);
@@ -577,17 +779,19 @@ function handleCLI() {
 ${c.brand}${c.bold}ralph-loop.js${c.reset} - Autonomous Story Processing
 
 ${c.bold}Usage:${c.reset}
-  node scripts/ralph-loop.js                              Run loop check (Stop hook)
-  node scripts/ralph-loop.js --init --epic=EP-XXX         Initialize loop for epic
-  node scripts/ralph-loop.js --init --epic=EP-XXX --visual Initialize with Visual Mode
-  node scripts/ralph-loop.js --status                     Check loop status
-  node scripts/ralph-loop.js --stop                       Stop the loop
-  node scripts/ralph-loop.js --reset                      Reset loop state
+  node scripts/ralph-loop.js                                  Run loop check (Stop hook)
+  node scripts/ralph-loop.js --init --epic=EP-XXX             Initialize loop for epic
+  node scripts/ralph-loop.js --init --epic=EP-XXX --visual    Initialize with Visual Mode
+  node scripts/ralph-loop.js --init --epic=EP-XXX --coverage=80  Initialize with Coverage Mode
+  node scripts/ralph-loop.js --status                         Check loop status
+  node scripts/ralph-loop.js --stop                           Stop the loop
+  node scripts/ralph-loop.js --reset                          Reset loop state
 
 ${c.bold}Options:${c.reset}
   --epic=EP-XXXX    Epic ID to process (required for --init)
   --max=N           Max iterations (default: 20)
   --visual, -v      Enable Visual Mode (screenshot verification)
+  --coverage=N      Enable Coverage Mode (iterate until N% coverage)
 
 ${c.bold}Visual Mode:${c.reset}
   When --visual is enabled, the loop also verifies that all screenshots
@@ -596,16 +800,24 @@ ${c.bold}Visual Mode:${c.reset}
   This ensures Claude actually looks at UI screenshots before declaring
   completion. Requires minimum 2 iterations for confirmation.
 
+${c.bold}Coverage Mode:${c.reset}
+  When --coverage=N is enabled, the loop verifies test coverage meets
+  the threshold N% before completing stories.
+
+  Coverage is read from coverage/coverage-summary.json (Jest/NYC format).
+  Configure in docs/00-meta/agileflow-metadata.json:
+    { "ralph_loop": { "coverage_command": "npm run test:coverage" } }
+
   Workflow:
     1. Tests run → must pass
-    2. Screenshots verified → all must have 'verified-' prefix
-    3. Minimum 2 iterations → prevents premature completion
+    2. Coverage checked → must meet threshold
+    3. Minimum 2 iterations → confirms coverage is stable
     4. Only then → story marked complete
 
 ${c.bold}How it works:${c.reset}
-  1. Start loop with /agileflow:babysit EPIC=EP-XXX MODE=loop VISUAL=true
+  1. Start loop with /agileflow:babysit EPIC=EP-XXX MODE=loop COVERAGE=80
   2. Work on the current story
-  3. When you stop, this hook runs tests (and screenshot verification in Visual Mode)
+  3. When you stop, this hook runs tests and verifications
   4. If all pass → story marked complete, next story loaded
   5. If any fail → failures shown, you continue fixing
   6. Loop repeats until epic done or max iterations

package/scripts/screenshot-verifier.js

@@ -97,7 +97,7 @@ function getImageFiles(dir) {
 
   try {
     const files = fs.readdirSync(dir);
-    return files.filter((file) => {
+    return files.filter(file => {
       const ext = path.extname(file).toLowerCase();
       return imageExtensions.includes(ext);
     });
@@ -172,7 +172,9 @@ function formatResult(result, options) {
 
   if (result.success) {
     console.log(`${c.green}${c.bold}All screenshots verified${c.reset}`);
-    console.log(`${c.dim}${result.verified}/${result.total} screenshots have 'verified-' prefix${c.reset}`);
+    console.log(
+      `${c.dim}${result.verified}/${result.total} screenshots have 'verified-' prefix${c.reset}`
+    );
   } else {
     console.log(`${c.red}${c.bold}Unverified screenshots found${c.reset}`);
     console.log(`${c.dim}${result.verified}/${result.total} verified${c.reset}`);