agileflow 2.78.0 → 2.79.0

package/scripts/damage-control/write-tool-damage-control.js

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+
+/**
+ * write-tool-damage-control.js - Enforce path protection for Write tool
+ *
+ * This PreToolUse hook runs before every Write tool execution.
+ * It checks the file path against patterns.yaml to block writes
+ * to protected paths.
+ *
+ * Path protection levels:
+ *   zeroAccessPaths: Cannot read, write, edit, or delete
+ *   readOnlyPaths: Can read, cannot write or delete
+ *   noDeletePaths: Can read and write, cannot delete (Write is allowed)
+ *
+ * Exit codes:
+ *   0 = Allow write to proceed
+ *   2 = Block write
+ *
+ * Usage (as PreToolUse hook):
+ *   node .claude/hooks/damage-control/write-tool-damage-control.js
+ *
+ * Environment:
+ *   CLAUDE_TOOL_INPUT - JSON string with tool input (contains "file_path")
+ *   CLAUDE_PROJECT_DIR - Project root directory
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ANSI colors for output
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
+};
+
+// Exit codes
+const EXIT_ALLOW = 0;
+const EXIT_BLOCK = 2;
+
+/**
+ * Load path protection rules from patterns.yaml
+ */
+function loadPathRules(projectDir) {
+  const locations = [
+    path.join(projectDir, '.claude/hooks/damage-control/patterns.yaml'),
+    path.join(projectDir, '.agileflow/hooks/damage-control/patterns.yaml'),
+    path.join(projectDir, 'patterns.yaml'),
+  ];
+
+  for (const loc of locations) {
+    if (fs.existsSync(loc)) {
+      try {
+        const content = fs.readFileSync(loc, 'utf8');
+        return parsePathRules(content);
+      } catch (e) {
+        console.error(`Warning: Could not parse ${loc}: ${e.message}`);
+      }
+    }
+  }
+
+  return getDefaultPathRules();
+}
+
+/**
+ * Parse path rules from YAML content
+ */
+function parsePathRules(content) {
+  const rules = {
+    zeroAccessPaths: [],
+    readOnlyPaths: [],
+    noDeletePaths: [],
+  };
+
+  let currentSection = null;
+
+  const lines = content.split('\n');
+
+  for (const line of lines) {
+    if (line.trim().startsWith('#') || line.trim() === '') continue;
+
+    if (line.match(/^zeroAccessPaths:/)) {
+      currentSection = 'zeroAccessPaths';
+      continue;
+    }
+    if (line.match(/^readOnlyPaths:/)) {
+      currentSection = 'readOnlyPaths';
+      continue;
+    }
+    if (line.match(/^noDeletePaths:/)) {
+      currentSection = 'noDeletePaths';
+      continue;
+    }
+    if (line.match(/^(bashToolPatterns|askPatterns|agileflowPatterns|config):/)) {
+      currentSection = null;
+      continue;
+    }
+
+    if (currentSection && rules[currentSection]) {
+      const pathMatch = line.match(/^\s+-\s*['"]?(.+?)['"]?\s*$/);
+      if (pathMatch) {
+        rules[currentSection].push(pathMatch[1]);
+      }
+    }
+  }
+
+  return rules;
+}
+
+/**
+ * Default path rules if patterns.yaml not found
+ */
+function getDefaultPathRules() {
+  return {
+    zeroAccessPaths: [
+      '~/.ssh/',
+      '~/.aws/credentials',
+      '.env',
+      '.env.local',
+      '.env.production',
+    ],
+    readOnlyPaths: [
+      '/etc/',
+      '~/.bashrc',
+      '~/.zshrc',
+      'package-lock.json',
+      'yarn.lock',
+      '.git/',
+    ],
+    noDeletePaths: [
+      '.agileflow/',
+      '.claude/',
+      'docs/09-agents/status.json',
+      'CLAUDE.md',
+    ],
+  };
+}
+
+/**
+ * Expand home directory in path
+ */
+function expandHome(filePath) {
+  if (filePath.startsWith('~/')) {
+    return path.join(process.env.HOME || '', filePath.slice(2));
+  }
+  return filePath;
+}
+
+/**
+ * Check if a file path matches a pattern
+ */
+function pathMatches(filePath, pattern) {
+  const expandedPattern = expandHome(pattern);
+  const normalizedFile = path.normalize(filePath);
+  const normalizedPattern = path.normalize(expandedPattern);
+
+  // Exact match
+  if (normalizedFile === normalizedPattern) return true;
+
+  // Directory prefix match
+  if (pattern.endsWith('/')) {
+    if (normalizedFile.startsWith(normalizedPattern)) return true;
+  }
+
+  // Glob pattern (**)
+  if (pattern.includes('**/')) {
+    const globPart = pattern.split('**/')[1];
+    if (normalizedFile.includes(globPart)) return true;
+  }
+
+  // Wildcard at end
+  if (pattern.endsWith('*')) {
+    const prefix = normalizedPattern.slice(0, -1);
+    if (normalizedFile.startsWith(prefix)) return true;
+  }
+
+  // Basename match
+  if (!pattern.includes('/') && !pattern.includes(path.sep)) {
+    const basename = path.basename(normalizedFile);
+    if (basename === pattern) return true;
+    if (pattern.endsWith('*')) {
+      const patternBase = pattern.slice(0, -1);
+      if (basename.startsWith(patternBase)) return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Check if file path is protected for writing
+ * Returns: { blocked: boolean, reason: string, level: string }
+ */
+function checkPath(filePath, rules) {
+  // Check zero access paths (blocked completely)
+  for (const pattern of rules.zeroAccessPaths) {
+    if (pathMatches(filePath, pattern)) {
+      return {
+        blocked: true,
+        reason: `Path is in zero-access protected list: ${pattern}`,
+        level: 'zero-access',
+      };
+    }
+  }
+
+  // Check read-only paths (cannot write)
+  for (const pattern of rules.readOnlyPaths) {
+    if (pathMatches(filePath, pattern)) {
+      return {
+        blocked: true,
+        reason: `Path is read-only: ${pattern}`,
+        level: 'read-only',
+      };
+    }
+  }
+
+  // noDeletePaths allows writing, only blocks deletion
+  // so we don't block writes here
+
+  return { blocked: false, reason: null, level: null };
+}
+
+/**
+ * Main entry point
+ */
+function main() {
+  const toolInput = process.env.CLAUDE_TOOL_INPUT;
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+  if (!toolInput) {
+    process.exit(EXIT_ALLOW);
+  }
+
+  let input;
+  try {
+    input = JSON.parse(toolInput);
+  } catch (e) {
+    console.error('Error parsing CLAUDE_TOOL_INPUT:', e.message);
+    process.exit(EXIT_ALLOW);
+  }
+
+  const filePath = input.file_path;
+  if (!filePath) {
+    process.exit(EXIT_ALLOW);
+  }
+
+  // Resolve to absolute path
+  const absolutePath = path.isAbsolute(filePath)
+    ? filePath
+    : path.join(projectDir, filePath);
+
+  // Load rules
+  const rules = loadPathRules(projectDir);
+
+  // Check path
+  const result = checkPath(absolutePath, rules);
+
+  if (result.blocked) {
+    console.error(`${c.red}${c.bold}BLOCKED${c.reset}: ${result.reason}`);
+    console.error(`${c.yellow}File: ${filePath}${c.reset}`);
+    console.error(`${c.cyan}This file is protected by damage control (${result.level}).${c.reset}`);
+    process.exit(EXIT_BLOCK);
+  }
+
+  process.exit(EXIT_ALLOW);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { checkPath, loadPathRules, pathMatches };

package/scripts/obtain-context.js

@@ -28,11 +28,25 @@ if (commandName) {
   if (fs.existsSync(sessionStatePath)) {
     try {
       const state = JSON.parse(fs.readFileSync(sessionStatePath, 'utf8'));
-      state.active_command = {
+
+      // Initialize active_commands array if not present
+      if (!Array.isArray(state.active_commands)) {
+        state.active_commands = [];
+      }
+
+      // Remove any existing entry for this command (avoid duplicates)
+      state.active_commands = state.active_commands.filter(c => c.name !== commandName);
+
+      // Add the new command
+      state.active_commands.push({
         name: commandName,
         activated_at: new Date().toISOString(),
         state: {},
-      };
+      });
+
+      // Keep backwards compatibility - also set singular active_command to most recent
+      state.active_command = state.active_commands[state.active_commands.length - 1];
+
       fs.writeFileSync(sessionStatePath, JSON.stringify(state, null, 2) + '\n');
     } catch (e) {
       // Silently continue if session state can't be updated
@@ -370,7 +384,12 @@ function generateFullContent() {
     } else {
       content += `${C.dim}No active session${C.reset}\n`;
     }
-    if (sessionState.active_command) {
+    // Show all active commands (array)
+    if (Array.isArray(sessionState.active_commands) && sessionState.active_commands.length > 0) {
+      const cmdNames = sessionState.active_commands.map(c => c.name).join(', ');
+      content += `Active commands: ${C.skyBlue}${cmdNames}${C.reset}\n`;
+    } else if (sessionState.active_command) {
+      // Backwards compatibility for old format
       content += `Active command: ${C.skyBlue}${sessionState.active_command.name}${C.reset}\n`;
     }
   } else {

package/scripts/ralph-loop.js

@@ -7,12 +7,18 @@
  * It runs as a Stop hook and handles:
  *   1. Checking if loop mode is enabled
  *   2. Running test validation
- *   3. Updating story status on success
- *   4. Feeding context back for next iteration
- *   5. Tracking iterations and enforcing limits
+ *   3. Running screenshot verification (Visual Mode)
+ *   4. Updating story status on success
+ *   5. Feeding context back for next iteration
+ *   6. Tracking iterations and enforcing limits
  *
  * Named after the "Ralph Wiggum" pattern from Anthropic.
  *
+ * Visual Mode:
+ *   When visual_mode is enabled, the loop also verifies that all
+ *   screenshots have been reviewed (verified- prefix). This ensures
+ *   Claude actually looks at UI screenshots before declaring completion.
+ *
  * Usage (as Stop hook):
  *   node scripts/ralph-loop.js
  *
@@ -26,78 +32,46 @@ const fs = require('fs');
 const path = require('path');
 const { execSync, spawnSync } = require('child_process');
 
-// ANSI colors
-const c = {
-  reset: '\x1b[0m',
-  bold: '\x1b[1m',
-  dim: '\x1b[2m',
-  red: '\x1b[31m',
-  green: '\x1b[32m',
-  yellow: '\x1b[33m',
-  blue: '\x1b[34m',
-  cyan: '\x1b[36m',
-  brand: '\x1b[38;2;232;104;58m',
-};
-
-// Find project root
-function getProjectRoot() {
-  let dir = process.cwd();
-  while (!fs.existsSync(path.join(dir, '.agileflow')) && dir !== '/') {
-    dir = path.dirname(dir);
-  }
-  return dir !== '/' ? dir : process.cwd();
-}
+// Shared utilities
+const { c } = require('../lib/colors');
+const { getProjectRoot } = require('../lib/paths');
+const { safeReadJSON, safeWriteJSON } = require('../lib/errors');
 
 // Read session state
 function getSessionState(rootDir) {
   const statePath = path.join(rootDir, 'docs/09-agents/session-state.json');
-  try {
-    if (fs.existsSync(statePath)) {
-      return JSON.parse(fs.readFileSync(statePath, 'utf8'));
-    }
-  } catch (e) {}
-  return {};
+  const result = safeReadJSON(statePath, { defaultValue: {} });
+  return result.ok ? result.data : {};
 }
 
 // Write session state
 function saveSessionState(rootDir, state) {
   const statePath = path.join(rootDir, 'docs/09-agents/session-state.json');
-  const dir = path.dirname(statePath);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-  fs.writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n');
+  safeWriteJSON(statePath, state, { createDir: true });
 }
 
 // Read status.json for stories
 function getStatus(rootDir) {
   const statusPath = path.join(rootDir, 'docs/09-agents/status.json');
-  try {
-    if (fs.existsSync(statusPath)) {
-      return JSON.parse(fs.readFileSync(statusPath, 'utf8'));
-    }
-  } catch (e) {}
-  return { stories: {}, epics: {} };
+  const result = safeReadJSON(statusPath, { defaultValue: { stories: {}, epics: {} } });
+  return result.ok ? result.data : { stories: {}, epics: {} };
 }
 
 // Save status.json
 function saveStatus(rootDir, status) {
   const statusPath = path.join(rootDir, 'docs/09-agents/status.json');
-  fs.writeFileSync(statusPath, JSON.stringify(status, null, 2) + '\n');
+  safeWriteJSON(statusPath, status);
 }
 
 // Get test command from package.json or metadata
 function getTestCommand(rootDir) {
   // Check agileflow metadata first
-  try {
-    const metadataPath = path.join(rootDir, 'docs/00-meta/agileflow-metadata.json');
-    if (fs.existsSync(metadataPath)) {
-      const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
-      if (metadata.ralph_loop?.test_command) {
-        return metadata.ralph_loop.test_command;
-      }
-    }
-  } catch (e) {}
+  const metadataPath = path.join(rootDir, 'docs/00-meta/agileflow-metadata.json');
+  const result = safeReadJSON(metadataPath, { defaultValue: {} });
+
+  if (result.ok && result.data?.ralph_loop?.test_command) {
+    return result.data.ralph_loop.test_command;
+  }
 
   // Default to npm test
   return 'npm test';
@@ -129,6 +103,73 @@ function runTests(rootDir, testCommand) {
   return result;
 }
 
+// Get screenshots directory from metadata or default
+function getScreenshotsDir(rootDir) {
+  try {
+    const metadataPath = path.join(rootDir, 'docs/00-meta/agileflow-metadata.json');
+    if (fs.existsSync(metadataPath)) {
+      const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+      if (metadata.ralph_loop?.screenshots_dir) {
+        return metadata.ralph_loop.screenshots_dir;
+      }
+    }
+  } catch (e) {}
+  return './screenshots';
+}
+
+// Run screenshot verification (Visual Mode)
+function verifyScreenshots(rootDir) {
+  const result = { passed: false, output: '', total: 0, verified: 0, unverified: [] };
+  const screenshotsDir = getScreenshotsDir(rootDir);
+  const fullPath = path.resolve(rootDir, screenshotsDir);
+
+  // Check if directory exists
+  if (!fs.existsSync(fullPath)) {
+    result.passed = true; // No screenshots = nothing to verify
+    result.output = 'No screenshots directory found';
+    return result;
+  }
+
+  // Get all image files
+  const imageExtensions = ['.png', '.jpg', '.jpeg', '.webp', '.gif'];
+  let files;
+  try {
+    files = fs.readdirSync(fullPath).filter((file) => {
+      const ext = path.extname(file).toLowerCase();
+      return imageExtensions.includes(ext);
+    });
+  } catch (e) {
+    result.output = `Error reading screenshots directory: ${e.message}`;
+    return result;
+  }
+
+  if (files.length === 0) {
+    result.passed = true;
+    result.output = 'No screenshots found in directory';
+    return result;
+  }
+
+  // Check each file for verified- prefix
+  for (const file of files) {
+    if (file.startsWith('verified-')) {
+      result.verified++;
+    } else {
+      result.unverified.push(file);
+    }
+  }
+
+  result.total = files.length;
+  result.passed = result.unverified.length === 0;
+
+  if (result.passed) {
+    result.output = `All ${result.total} screenshots verified`;
+  } else {
+    result.output = `${result.unverified.length} screenshots missing 'verified-' prefix`;
+  }
+
+  return result;
+}
+
 // Get next ready story in epic
 function getNextStory(status, epicId, currentStoryId) {
   const stories = status.stories || {};
@@ -211,13 +252,16 @@ function handleLoop(rootDir) {
   const status = getStatus(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
 
   console.log('');
   console.log(
     `${c.brand}${c.bold}══════════════════════════════════════════════════════════${c.reset}`
   );
+  const modeLabel = visualMode ? ' [VISUAL MODE]' : '';
   console.log(
-    `${c.brand}${c.bold}  RALPH LOOP - Iteration ${iteration}/${maxIterations}${c.reset}`
+    `${c.brand}${c.bold}  RALPH LOOP - Iteration ${iteration}/${maxIterations}${modeLabel}${c.reset}`
   );
   console.log(
     `${c.brand}${c.bold}══════════════════════════════════════════════════════════${c.reset}`
@@ -261,6 +305,61 @@ function handleLoop(rootDir) {
 
   if (testResult.passed) {
     console.log(`${c.green}✓ Tests passed${c.reset} (${(testResult.duration / 1000).toFixed(1)}s)`);
+
+    // Visual Mode: Also verify screenshots
+    let screenshotResult = { passed: true };
+    if (visualMode) {
+      console.log('');
+      console.log(`${c.blue}Verifying screenshots...${c.reset}`);
+      screenshotResult = verifyScreenshots(rootDir);
+
+      if (screenshotResult.passed) {
+        console.log(`${c.green}✓ ${screenshotResult.output}${c.reset}`);
+        state.ralph_loop.screenshots_verified = true;
+      } else {
+        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) => {
+            console.log(`  ${c.yellow}- ${file}${c.reset}`);
+          });
+          if (screenshotResult.unverified.length > 5) {
+            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) {
+      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}`);
+
+      state.ralph_loop.iteration = iteration;
+      saveSessionState(rootDir, state);
+
+      console.log('');
+      console.log(`${c.brand}▶ Continue reviewing. Loop will verify again.${c.reset}`);
+      return;
+    }
+
+    // Check if both tests AND screenshots (in visual mode) passed
+    const canComplete = testResult.passed && (!visualMode || screenshotResult.passed);
+
+    if (!canComplete) {
+      // Screenshots 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}`);
+      return;
+    }
     console.log('');
 
     // Mark story complete
@@ -353,10 +452,15 @@ function handleCLI() {
     if (!loop || !loop.enabled) {
       console.log(`${c.dim}Ralph Loop: not active${c.reset}`);
     } else {
-      console.log(`${c.green}Ralph Loop: active${c.reset}`);
+      const modeLabel = loop.visual_mode ? ` ${c.cyan}[VISUAL]${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}`;
+        console.log(`  Screenshots Verified: ${verified}`);
+      }
     }
     return true;
   }
@@ -386,6 +490,7 @@ function handleCLI() {
   if (args.some(a => a.startsWith('--init'))) {
     const epicArg = args.find(a => a.startsWith('--epic='));
     const maxArg = args.find(a => a.startsWith('--max='));
+    const visualArg = args.includes('--visual') || args.includes('-v');
 
     if (!epicArg) {
       console.log(`${c.red}Error: --epic=EP-XXXX is required${c.reset}`);
@@ -394,6 +499,7 @@ function handleCLI() {
 
     const epicId = epicArg.split('=')[1];
     const maxIterations = maxArg ? parseInt(maxArg.split('=')[1]) : 20;
+    const visualMode = visualArg;
 
     // Find first ready story in epic
     const status = getStatus(rootDir);
@@ -426,6 +532,8 @@ function handleCLI() {
       current_story: storyId,
       iteration: 0,
       max_iterations: maxIterations,
+      visual_mode: visualMode,
+      screenshots_verified: false,
       started_at: new Date().toISOString(),
     };
     saveSessionState(rootDir, state);
@@ -433,11 +541,16 @@ function handleCLI() {
     const progress = getEpicProgress(status, epicId);
 
     console.log('');
-    console.log(`${c.green}${c.bold}Ralph Loop Initialized${c.reset}`);
+    const modeLabel = visualMode ? ` ${c.cyan}[VISUAL MODE]${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}`);
     console.log(`  Stories: ${progress.ready} ready, ${progress.total} total`);
     console.log(`  Max Iterations: ${maxIterations}`);
+    if (visualMode) {
+      console.log(`  Visual Mode: ${c.cyan}enabled${c.reset} (screenshot verification)`);
+      console.log(`  Min Iterations: 2 (for confirmation)`);
+    }
     console.log(`${c.dim}${'─'.repeat(40)}${c.reset}`);
     console.log('');
     console.log(`${c.brand}▶ Starting Story:${c.reset} ${storyId}`);
@@ -464,22 +577,37 @@ 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 --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 --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)
+
+${c.bold}Visual Mode:${c.reset}
+  When --visual is enabled, the loop also verifies that all screenshots
+  in the screenshots/ directory have been reviewed (verified- prefix).
+
+  This ensures Claude actually looks at UI screenshots before declaring
+  completion. Requires minimum 2 iterations for confirmation.
+
+  Workflow:
+    1. Tests run → must pass
+    2. Screenshots verified → all must have 'verified-' prefix
+    3. Minimum 2 iterations → prevents premature completion
+    4. Only then → story marked complete
 
 ${c.bold}How it works:${c.reset}
-  1. Start loop with /agileflow:babysit EPIC=EP-XXX MODE=loop
+  1. Start loop with /agileflow:babysit EPIC=EP-XXX MODE=loop VISUAL=true
   2. Work on the current story
-  3. When you stop, this hook runs tests
-  4. If tests pass → story marked complete, next story loaded
-  5. If tests fail → failures shown, you continue fixing
+  3. When you stop, this hook runs tests (and screenshot verification in Visual Mode)
+  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
 `);
     return true;