agileflow 2.77.0 → 2.79.0

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;

package/scripts/screenshot-verifier.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+
+/**
+ * screenshot-verifier.js - Verify all screenshots have been reviewed
+ *
+ * Part of Visual Mode for UI development. This script checks that all
+ * screenshots in a directory have been prefixed with "verified-" to
+ * confirm Claude has visually reviewed each one.
+ *
+ * Usage:
+ *   node scripts/screenshot-verifier.js                    # Default: ./screenshots
+ *   node scripts/screenshot-verifier.js --path ./e2e/shots # Custom path
+ *   node scripts/screenshot-verifier.js --help             # Show help
+ *
+ * Exit codes:
+ *   0 - All screenshots verified (or no screenshots found)
+ *   1 - Some screenshots missing verified- prefix
+ *   2 - Error (directory not found, etc.)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Shared utilities
+const { c } = require('../lib/colors');
+
+// Parse command line arguments
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const options = {
+    path: './screenshots',
+    help: false,
+    quiet: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else if (arg === '--quiet' || arg === '-q') {
+      options.quiet = true;
+    } else if (arg === '--path' || arg === '-p') {
+      if (args[i + 1]) {
+        options.path = args[i + 1];
+        i++;
+      }
+    } else if (!arg.startsWith('-')) {
+      // Positional argument - treat as path
+      options.path = arg;
+    }
+  }
+
+  return options;
+}
+
+// Show help message
+function showHelp() {
+  console.log(`
+${c.brand}${c.bold}screenshot-verifier${c.reset} - Verify all screenshots have been reviewed
+
+${c.bold}USAGE${c.reset}
+  node screenshot-verifier.js [OPTIONS] [PATH]
+
+${c.bold}OPTIONS${c.reset}
+  --path, -p <dir>   Directory containing screenshots (default: ./screenshots)
+  --quiet, -q        Only output on failure
+  --help, -h         Show this help message
+
+${c.bold}EXAMPLES${c.reset}
+  node screenshot-verifier.js                       # Check ./screenshots
+  node screenshot-verifier.js ./tests/e2e/shots     # Check custom path
+  node screenshot-verifier.js --path ./shots -q     # Quiet mode
+
+${c.bold}EXIT CODES${c.reset}
+  0 - All screenshots verified (or no screenshots found)
+  1 - Some screenshots missing 'verified-' prefix
+  2 - Error (directory not found, etc.)
+
+${c.bold}VISUAL MODE${c.reset}
+  This script is part of AgileFlow's Visual Mode for UI development.
+
+  Workflow:
+  1. Playwright tests create screenshots in the target directory
+  2. Claude reviews each screenshot visually
+  3. Claude renames verified screenshots with 'verified-' prefix
+  4. This script confirms all screenshots have been reviewed
+
+  The 'verified-' prefix ensures Claude actually looked at each image
+  rather than declaring completion prematurely.
+`);
+}
+
+// Get all image files in directory
+function getImageFiles(dir) {
+  const imageExtensions = ['.png', '.jpg', '.jpeg', '.webp', '.gif'];
+
+  try {
+    const files = fs.readdirSync(dir);
+    return files.filter((file) => {
+      const ext = path.extname(file).toLowerCase();
+      return imageExtensions.includes(ext);
+    });
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return null; // Directory doesn't exist
+    }
+    throw err;
+  }
+}
+
+// Main verification logic
+function verifyScreenshots(options) {
+  const dir = path.resolve(options.path);
+
+  // Check if directory exists
+  if (!fs.existsSync(dir)) {
+    if (!options.quiet) {
+      console.log(`${c.yellow}No screenshots directory found at: ${dir}${c.reset}`);
+      console.log(`${c.dim}Create the directory or run tests to generate screenshots.${c.reset}`);
+    }
+    return { success: true, total: 0, verified: 0, unverified: [] };
+  }
+
+  // Get all image files
+  const files = getImageFiles(dir);
+
+  if (files === null) {
+    console.error(`${c.red}Error: Could not read directory: ${dir}${c.reset}`);
+    process.exit(2);
+  }
+
+  if (files.length === 0) {
+    if (!options.quiet) {
+      console.log(`${c.yellow}No screenshots found in: ${dir}${c.reset}`);
+    }
+    return { success: true, total: 0, verified: 0, unverified: [] };
+  }
+
+  // Check each file for verified- prefix
+  const verified = [];
+  const unverified = [];
+
+  for (const file of files) {
+    if (file.startsWith('verified-')) {
+      verified.push(file);
+    } else {
+      unverified.push(file);
+    }
+  }
+
+  return {
+    success: unverified.length === 0,
+    total: files.length,
+    verified: verified.length,
+    unverified,
+  };
+}
+
+// Format result output
+function formatResult(result, options) {
+  if (options.quiet && result.success) {
+    return;
+  }
+
+  console.log('');
+
+  if (result.total === 0) {
+    console.log(`${c.yellow}No screenshots to verify${c.reset}`);
+    return;
+  }
+
+  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}`);
+  } else {
+    console.log(`${c.red}${c.bold}Unverified screenshots found${c.reset}`);
+    console.log(`${c.dim}${result.verified}/${result.total} verified${c.reset}`);
+    console.log('');
+    console.log(`${c.yellow}Missing 'verified-' prefix:${c.reset}`);
+    for (const file of result.unverified) {
+      console.log(`  ${c.red}- ${file}${c.reset}`);
+    }
+    console.log('');
+    console.log(`${c.cyan}To verify: Review each screenshot visually, then rename:${c.reset}`);
+    console.log(`${c.dim}  mv screenshots/example.png screenshots/verified-example.png${c.reset}`);
+  }
+
+  console.log('');
+}
+
+// Main entry point
+function main() {
+  const options = parseArgs();
+
+  if (options.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  const result = verifyScreenshots(options);
+  formatResult(result, options);
+
+  process.exit(result.success ? 0 : 1);
+}
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}
+
+// Export for testing
+module.exports = { verifyScreenshots, getImageFiles };

package/scripts/session-manager.js

@@ -13,30 +13,10 @@ 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 (has .agileflow or .git)
-function getProjectRoot() {
-  let dir = process.cwd();
-  while (dir !== '/') {
-    if (fs.existsSync(path.join(dir, '.agileflow')) || fs.existsSync(path.join(dir, '.git'))) {
-      return dir;
-    }
-    dir = path.dirname(dir);
-  }
-  return process.cwd();
-}
+// Shared utilities
+const { c } = require('../lib/colors');
+const { getProjectRoot } = require('../lib/paths');
+const { safeReadJSON } = require('../lib/errors');
 
 const ROOT = getProjectRoot();
 const SESSIONS_DIR = path.join(ROOT, '.agileflow', 'sessions');
@@ -162,17 +142,16 @@ function getCurrentBranch() {
 
 // Get current story from status.json
 function getCurrentStory() {
-  try {
-    const statusPath = path.join(ROOT, 'docs', '09-agents', 'status.json');
-    if (!fs.existsSync(statusPath)) return null;
+  const statusPath = path.join(ROOT, 'docs', '09-agents', 'status.json');
+  const result = safeReadJSON(statusPath, { defaultValue: null });
 
-    const status = JSON.parse(fs.readFileSync(statusPath, 'utf8'));
-    for (const [id, story] of Object.entries(status.stories || {})) {
-      if (story.status === 'in_progress') {
-        return { id, title: story.title };
-      }
+  if (!result.ok || !result.data) return null;
+
+  for (const [id, story] of Object.entries(result.data.stories || {})) {
+    if (story.status === 'in_progress') {
+      return { id, title: story.title };
     }
-  } catch (e) {}
+  }
   return null;
 }