@girardmedia/bootspring 1.2.0 → 2.0.3

package/cli/loop.js

@@ -3,8 +3,11 @@
 /**
  * Bootspring Loop CLI
  *
- * Autonomous task execution loop - spawns fresh AI instances
- * iteratively until all PRD stories are complete.
+ * Enhanced autonomous task execution loop - spawns fresh AI instances
+ * iteratively until all tasks complete with intelligent exit detection,
+ * session continuity, rate limiting, and circuit breakers.
+ *
+ * Inspired by: https://github.com/frankbria/ralph-claude-code
  *
  * @package bootspring
  * @module cli/loop
@@ -13,8 +16,11 @@
 const { spawn, execSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
+const readline = require('readline');
 const prd = require('../intelligence/prd');
 const utils = require('../core/utils');
+const config = require('../core/config');
+const telemetry = require('../core/telemetry');
 
 // Colors
 const c = {
@@ -25,9 +31,256 @@ const c = {
   blue: '\x1b[34m',
   yellow: '\x1b[33m',
   cyan: '\x1b[36m',
-  red: '\x1b[31m'
+  red: '\x1b[31m',
+  magenta: '\x1b[35m'
+};
+
+// Loop configuration
+const LOOP_CONFIG = {
+  // Rate limiting
+  maxCallsPerHour: 100,
+  minDelayBetweenCalls: 2000, // 2 seconds minimum
+
+  // Circuit breaker
+  maxConsecutiveErrors: 3,
+  errorCooldownMs: 30000, // 30 seconds cooldown after errors
+
+  // Exit detection (dual-condition)
+  requiredCompletionIndicators: 2,
+  exitSignals: ['EXIT_SIGNAL', 'ALL_COMPLETE', 'LOOP_EXIT'],
+  completionIndicators: [
+    'all tasks complete',
+    'all stories complete',
+    'nothing left to do',
+    'no more work',
+    'feature complete',
+    'implementation complete',
+    'all done',
+    'finished all',
+    'completed successfully'
+  ],
+
+  // Session
+  sessionDir: '.bootspring/loop',
+  stateFile: 'session-state.json',
+  logFile: 'session.log',
+  metricsFile: 'metrics.json'
 };
 
+/**
+ * Loop Session State
+ */
+class LoopSession {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    this.sessionDir = path.join(projectRoot, LOOP_CONFIG.sessionDir);
+    this.statePath = path.join(this.sessionDir, LOOP_CONFIG.stateFile);
+    this.logPath = path.join(this.sessionDir, LOOP_CONFIG.logFile);
+    this.metricsPath = path.join(this.sessionDir, LOOP_CONFIG.metricsFile);
+
+    this.state = this.loadState();
+    this.metrics = this.loadMetrics();
+  }
+
+  loadState() {
+    try {
+      if (fs.existsSync(this.statePath)) {
+        return JSON.parse(fs.readFileSync(this.statePath, 'utf-8'));
+      }
+    } catch {
+      // Corrupted state, start fresh
+    }
+
+    return {
+      sessionId: this.generateSessionId(),
+      startedAt: null,
+      lastUpdated: null,
+      iteration: 0,
+      maxIterations: 10,
+      tool: 'claude',
+      source: 'prd', // prd, todo, plan
+      sourcePath: null,
+      status: 'idle', // idle, running, paused, completed, failed
+      completionIndicatorCount: 0,
+      exitSignalReceived: false,
+      consecutiveErrors: 0,
+      callsThisHour: [],
+      taskHistory: [],
+      currentTask: null
+    };
+  }
+
+  loadMetrics() {
+    try {
+      if (fs.existsSync(this.metricsPath)) {
+        return JSON.parse(fs.readFileSync(this.metricsPath, 'utf-8'));
+      }
+    } catch {
+      // Start fresh
+    }
+
+    return {
+      totalIterations: 0,
+      successfulTasks: 0,
+      failedTasks: 0,
+      blockedTasks: 0,
+      totalDuration: 0,
+      averageTaskDuration: 0,
+      errorRate: 0,
+      completionRate: 0
+    };
+  }
+
+  generateSessionId() {
+    return `loop-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  save() {
+    if (!fs.existsSync(this.sessionDir)) {
+      fs.mkdirSync(this.sessionDir, { recursive: true });
+    }
+
+    this.state.lastUpdated = new Date().toISOString();
+    fs.writeFileSync(this.statePath, JSON.stringify(this.state, null, 2));
+    fs.writeFileSync(this.metricsPath, JSON.stringify(this.metrics, null, 2));
+  }
+
+  log(message, level = 'info') {
+    const timestamp = new Date().toISOString();
+    const logLine = `[${timestamp}] [${level.toUpperCase()}] ${message}\n`;
+
+    fs.appendFileSync(this.logPath, logLine);
+
+    // Also track in telemetry
+    telemetry.track('loop:log', { message, level, sessionId: this.state.sessionId });
+  }
+
+  canMakeCall() {
+    // Check rate limiting
+    const now = Date.now();
+    const oneHourAgo = now - (60 * 60 * 1000);
+
+    // Clean old calls
+    this.state.callsThisHour = this.state.callsThisHour.filter(t => t > oneHourAgo);
+
+    if (this.state.callsThisHour.length >= LOOP_CONFIG.maxCallsPerHour) {
+      return { allowed: false, reason: 'rate_limit', waitMs: this.state.callsThisHour[0] - oneHourAgo };
+    }
+
+    // Check circuit breaker
+    if (this.state.consecutiveErrors >= LOOP_CONFIG.maxConsecutiveErrors) {
+      const lastError = this.state.taskHistory
+        .filter(t => t.status === 'error')
+        .slice(-1)[0];
+
+      if (lastError) {
+        const cooldownEnd = new Date(lastError.endedAt).getTime() + LOOP_CONFIG.errorCooldownMs;
+        if (now < cooldownEnd) {
+          return { allowed: false, reason: 'circuit_breaker', waitMs: cooldownEnd - now };
+        }
+      }
+    }
+
+    return { allowed: true };
+  }
+
+  recordCall() {
+    this.state.callsThisHour.push(Date.now());
+    this.save();
+  }
+
+  recordTaskStart(task) {
+    this.state.currentTask = {
+      id: task.id || task.title,
+      title: task.title,
+      startedAt: new Date().toISOString(),
+      status: 'running'
+    };
+    this.save();
+  }
+
+  recordTaskEnd(status, details = {}) {
+    if (this.state.currentTask) {
+      const task = {
+        ...this.state.currentTask,
+        endedAt: new Date().toISOString(),
+        status,
+        ...details
+      };
+
+      this.state.taskHistory.push(task);
+
+      // Update metrics
+      this.metrics.totalIterations++;
+      if (status === 'complete') {
+        this.metrics.successfulTasks++;
+        this.state.consecutiveErrors = 0;
+      } else if (status === 'error') {
+        this.metrics.failedTasks++;
+        this.state.consecutiveErrors++;
+      } else if (status === 'blocked') {
+        this.metrics.blockedTasks++;
+      }
+
+      // Calculate durations
+      const duration = new Date(task.endedAt) - new Date(task.startedAt);
+      this.metrics.totalDuration += duration;
+      this.metrics.averageTaskDuration = this.metrics.totalDuration / this.metrics.totalIterations;
+      this.metrics.errorRate = this.metrics.failedTasks / this.metrics.totalIterations;
+      this.metrics.completionRate = this.metrics.successfulTasks / this.metrics.totalIterations;
+
+      this.state.currentTask = null;
+      this.save();
+    }
+  }
+
+  checkExitConditions(output) {
+    const lowerOutput = output.toLowerCase();
+
+    // Check for explicit exit signals
+    for (const signal of LOOP_CONFIG.exitSignals) {
+      if (output.includes(signal) || output.includes(`<loop-status>${signal}</loop-status>`)) {
+        this.state.exitSignalReceived = true;
+        this.save();
+        return { shouldExit: true, reason: 'exit_signal', signal };
+      }
+    }
+
+    // Check for completion indicators (dual-condition)
+    let indicatorCount = 0;
+    for (const indicator of LOOP_CONFIG.completionIndicators) {
+      if (lowerOutput.includes(indicator)) {
+        indicatorCount++;
+      }
+    }
+
+    if (indicatorCount > 0) {
+      this.state.completionIndicatorCount += indicatorCount;
+      this.save();
+
+      // Dual condition: need both multiple indicators AND explicit confirmation
+      if (this.state.completionIndicatorCount >= LOOP_CONFIG.requiredCompletionIndicators) {
+        return { shouldExit: true, reason: 'completion_indicators', count: this.state.completionIndicatorCount };
+      }
+    }
+
+    return { shouldExit: false };
+  }
+
+  reset() {
+    this.state = this.loadState();
+    this.state.sessionId = this.generateSessionId();
+    this.state.iteration = 0;
+    this.state.status = 'idle';
+    this.state.completionIndicatorCount = 0;
+    this.state.exitSignalReceived = false;
+    this.state.consecutiveErrors = 0;
+    this.state.taskHistory = [];
+    this.state.currentTask = null;
+    this.save();
+  }
+}
+
 /**
  * Check if a tool is available
  */
@@ -50,41 +303,604 @@ function detectTool() {
 }
 
 /**
- * Run the loop via shell script
+ * Get tasks from different sources
  */
-function runLoop(options = {}) {
-  // Require MCP for autonomous loop execution
-  if (!utils.requireMCP('Autonomous loop execution')) {
-    return;
+function getTasks(source, sourcePath, projectRoot) {
+  switch (source) {
+    case 'build': {
+      // Load tasks from build orchestrator
+      const { BuildOrchestrator } = require('../core/build-orchestrator');
+      const orchestrator = new BuildOrchestrator(projectRoot);
+
+      if (!orchestrator.hasState()) {
+        return { tasks: [], source: 'build', path: null, error: 'No build state found' };
+      }
+
+      orchestrator.loadState();
+      const tasks = orchestrator.getTasksForLoop();
+
+      return {
+        tasks,
+        source: 'build',
+        path: path.join(projectRoot, 'planning', 'BUILD_STATE.json'),
+        name: orchestrator.state?.projectName || 'Build'
+      };
+    }
+
+    case 'prd': {
+      const prdPath = sourcePath || path.join(prd.DEFAULT_PRD_DIR, prd.DEFAULT_PRD_FILE);
+      const data = prd.loadPRD(prdPath);
+      if (!data) return { tasks: [], source: 'prd', path: prdPath };
+
+      return {
+        tasks: data.stories.map(s => ({
+          id: s.id || s.title,
+          title: s.title,
+          description: s.description,
+          status: s.status,
+          acceptance: s.acceptance
+        })),
+        source: 'prd',
+        path: prdPath,
+        name: data.name
+      };
+    }
+
+    case 'todo': {
+      const todoPath = sourcePath || path.join(projectRoot, 'todo.md');
+      if (!fs.existsSync(todoPath)) return { tasks: [], source: 'todo', path: todoPath };
+
+      const content = fs.readFileSync(todoPath, 'utf-8');
+      const tasks = [];
+      const lines = content.split('\n');
+
+      for (let i = 0; i < lines.length; i++) {
+        const match = lines[i].match(/^- \[([ x])\] (.+)$/i);
+        if (match) {
+          const done = match[1].toLowerCase() === 'x';
+          tasks.push({
+            id: `todo-${i}`,
+            title: match[2],
+            status: done ? 'complete' : 'pending',
+            line: i + 1
+          });
+        }
+      }
+
+      return { tasks, source: 'todo', path: todoPath };
+    }
+
+    case 'plan': {
+      const planDir = sourcePath || path.join(projectRoot, 'planning');
+      if (!fs.existsSync(planDir)) return { tasks: [], source: 'plan', path: planDir };
+
+      // Look for IMPLEMENTATION_PLAN.md or similar
+      const planFiles = ['IMPLEMENTATION_PLAN.md', 'PLAN.md', 'ROADMAP.md'];
+      let planPath = null;
+
+      for (const file of planFiles) {
+        const fp = path.join(planDir, file);
+        if (fs.existsSync(fp)) {
+          planPath = fp;
+          break;
+        }
+      }
+
+      if (!planPath) return { tasks: [], source: 'plan', path: planDir };
+
+      const content = fs.readFileSync(planPath, 'utf-8');
+      const tasks = [];
+
+      // Parse markdown checklist items
+      const lines = content.split('\n');
+      let currentSection = '';
+
+      for (let i = 0; i < lines.length; i++) {
+        const headerMatch = lines[i].match(/^##+ (.+)$/);
+        if (headerMatch) {
+          currentSection = headerMatch[1];
+          continue;
+        }
+
+        const taskMatch = lines[i].match(/^- \[([ x])\] (.+)$/i);
+        if (taskMatch) {
+          const done = taskMatch[1].toLowerCase() === 'x';
+          tasks.push({
+            id: `plan-${i}`,
+            title: taskMatch[2],
+            section: currentSection,
+            status: done ? 'complete' : 'pending',
+            line: i + 1
+          });
+        }
+      }
+
+      return { tasks, source: 'plan', path: planPath };
+    }
+
+    default:
+      return { tasks: [], source, path: sourcePath };
+  }
+}
+
+/**
+ * Get next incomplete task
+ */
+function getNextTask(tasks) {
+  return tasks.find(t => t.status === 'pending' || t.status === 'in_progress');
+}
+
+/**
+ * Generate loop prompt
+ */
+function generatePrompt(task, taskInfo, session, options = {}) {
+  const parts = [];
+
+  parts.push(`# Bootspring Autonomous Task
+
+You are executing a single task from a ${taskInfo.source}. Follow these rules strictly:
+
+## Current Task
+**${task.title}**
+${task.description || ''}
+${task.acceptance ? `\n### Acceptance Criteria\n${task.acceptance.map(a => `- ${a}`).join('\n')}` : ''}
+
+## Rules
+1. Implement ONLY this one task - do not work on other tasks
+2. Run quality checks (tests, typecheck, lint) before committing
+3. If checks pass: commit with a descriptive message
+4. Update the task status to complete when done
+5. If you discover important patterns, update CLAUDE.md
+
+## Quality Gates
+- All tests must pass
+- No TypeScript/lint errors
+- No security vulnerabilities introduced
+
+## Exit Signals
+When you successfully complete the task, output exactly:
+<loop-status>TASK_COMPLETE</loop-status>
+
+If you cannot complete the task, output exactly:
+<loop-status>TASK_BLOCKED</loop-status>
+Reason: [explanation]
+
+If all tasks are done, output exactly:
+<loop-status>ALL_COMPLETE</loop-status>
+EXIT_SIGNAL
+
+## Session Info
+- Session: ${session.state.sessionId}
+- Iteration: ${session.state.iteration + 1} of ${session.state.maxIterations}
+- Tool: ${session.state.tool}
+- Source: ${taskInfo.source} (${taskInfo.path})
+- Timestamp: ${new Date().toISOString()}
+
+## Context
+The CLAUDE.md file contains project context. Read it first.
+Git history contains decisions and learnings from previous iterations.
+`);
+
+  // Add task history context
+  if (session.state.taskHistory.length > 0) {
+    const recentHistory = session.state.taskHistory.slice(-5);
+    parts.push('\n## Recent History');
+    for (const h of recentHistory) {
+      const icon = h.status === 'complete' ? '✓' : h.status === 'error' ? '✗' : '○';
+      parts.push(`- [${icon}] ${h.title}`);
+    }
   }
 
-  const scriptPath = path.join(__dirname, '..', 'scripts', 'loop.sh');
+  parts.push('\nNow, begin work on the task above.');
 
-  if (!fs.existsSync(scriptPath)) {
-    console.error(`${c.red}Loop script not found: ${scriptPath}${c.reset}`);
+  return parts.join('\n');
+}
+
+/**
+ * Run a single iteration
+ */
+async function runIteration(session, taskInfo, options = {}) {
+  const task = getNextTask(taskInfo.tasks);
+
+  if (!task) {
+    return { status: 'all_complete', message: 'No more tasks' };
+  }
+
+  // Check rate limiting and circuit breaker
+  const canCall = session.canMakeCall();
+  if (!canCall.allowed) {
+    if (canCall.reason === 'rate_limit') {
+      const waitSecs = Math.ceil(canCall.waitMs / 1000);
+      session.log(`Rate limited. Waiting ${waitSecs} seconds...`, 'warn');
+      await sleep(canCall.waitMs);
+    } else if (canCall.reason === 'circuit_breaker') {
+      const waitSecs = Math.ceil(canCall.waitMs / 1000);
+      session.log(`Circuit breaker active. Cooling down for ${waitSecs} seconds...`, 'warn');
+      console.log(`${c.yellow}Circuit breaker active. Waiting ${waitSecs}s...${c.reset}`);
+      await sleep(canCall.waitMs);
+      session.state.consecutiveErrors = 0;
+      session.save();
+    }
+  }
+
+  // Generate prompt
+  const prompt = generatePrompt(task, taskInfo, session, options);
+
+  // Create temp prompt file
+  const promptFile = path.join(session.sessionDir, 'current-prompt.md');
+  fs.writeFileSync(promptFile, prompt);
+
+  // Record task start
+  session.recordTaskStart(task);
+  session.recordCall();
+
+  console.log(`\n${c.cyan}[${session.state.iteration + 1}/${session.state.maxIterations}]${c.reset} ${c.bold}${task.title}${c.reset}`);
+
+  // Run AI tool
+  return new Promise((resolve) => {
+    let output = '';
+    let aiCmd, aiArgs;
+
+    if (session.state.tool === 'claude') {
+      aiCmd = 'claude';
+      aiArgs = ['--print'];
+    } else if (session.state.tool === 'amp') {
+      aiCmd = 'amp';
+      aiArgs = [];
+    } else {
+      resolve({ status: 'error', message: `Unknown tool: ${session.state.tool}` });
+      return;
+    }
+
+    const child = spawn(aiCmd, aiArgs, {
+      cwd: session.projectRoot,
+      stdio: options.live ? ['pipe', 'inherit', 'inherit'] : ['pipe', 'pipe', 'pipe']
+    });
+
+    // Send prompt via stdin
+    child.stdin.write(prompt);
+    child.stdin.end();
+
+    if (!options.live) {
+      child.stdout.on('data', (data) => {
+        output += data.toString();
+        if (options.verbose) {
+          process.stdout.write(data);
+        }
+      });
+
+      child.stderr.on('data', (data) => {
+        if (options.verbose) {
+          process.stderr.write(data);
+        }
+      });
+    }
+
+    child.on('close', (code) => {
+      // Check exit conditions
+      const exitCheck = session.checkExitConditions(output);
+
+      if (exitCheck.shouldExit) {
+        session.recordTaskEnd('complete', { exitReason: exitCheck.reason });
+        resolve({ status: 'all_complete', reason: exitCheck.reason, output });
+        return;
+      }
+
+      // Check for task status in output
+      if (output.includes('<loop-status>TASK_COMPLETE</loop-status>')) {
+        session.recordTaskEnd('complete');
+        resolve({ status: 'complete', output });
+      } else if (output.includes('<loop-status>TASK_BLOCKED</loop-status>')) {
+        const reasonMatch = output.match(/Reason:\s*(.+)/);
+        session.recordTaskEnd('blocked', { reason: reasonMatch?.[1] || 'Unknown' });
+        resolve({ status: 'blocked', reason: reasonMatch?.[1], output });
+      } else if (code !== 0) {
+        session.recordTaskEnd('error', { exitCode: code });
+        resolve({ status: 'error', exitCode: code, output });
+      } else {
+        // No explicit status - assume progress made
+        session.recordTaskEnd('complete');
+        resolve({ status: 'complete', output });
+      }
+    });
+
+    child.on('error', (err) => {
+      session.recordTaskEnd('error', { error: err.message });
+      resolve({ status: 'error', error: err.message });
+    });
+  });
+}
+
+/**
+ * Sleep helper
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Run the main loop
+ */
+async function runLoop(projectRoot, options = {}) {
+  const session = new LoopSession(projectRoot);
+
+  // Initialize or resume session
+  if (options.resume && session.state.status === 'paused') {
+    console.log(`${c.cyan}Resuming session ${session.state.sessionId}${c.reset}`);
+    session.log('Session resumed');
+  } else if (session.state.status === 'running') {
+    console.log(`${c.yellow}Session already running. Use --force to restart.${c.reset}`);
+    if (!options.force) return;
+    session.reset();
+  } else {
+    session.reset();
+  }
+
+  // Configure session
+  session.state.maxIterations = options.iterations || session.state.maxIterations || 10;
+  session.state.tool = options.tool || detectTool() || 'claude';
+  session.state.source = options.source || 'prd';
+  session.state.sourcePath = options.sourcePath || null;
+  session.state.startedAt = new Date().toISOString();
+  session.state.status = 'running';
+  session.save();
+
+  // Validate tool
+  if (!toolAvailable(session.state.tool)) {
+    console.error(`${c.red}AI tool '${session.state.tool}' not found. Install claude or amp CLI.${c.reset}`);
     process.exit(1);
   }
 
-  const args = [
-    options.iterations || '10',
-    '--tool', options.tool || 'claude'
-  ];
+  // Get tasks
+  const taskInfo = getTasks(session.state.source, session.state.sourcePath, projectRoot);
 
-  if (options.prd) {
-    args.push('--prd', options.prd);
+  if (taskInfo.tasks.length === 0) {
+    console.error(`${c.red}No tasks found from ${session.state.source}${c.reset}`);
+    console.log('Create tasks with: bootspring loop prd <name>');
+    process.exit(1);
   }
 
-  console.log(`${c.cyan}Starting autonomous loop...${c.reset}`);
-  console.log(`${c.dim}Tool: ${options.tool || 'claude'} | Iterations: ${options.iterations || 10}${c.reset}\n`);
+  const incompleteTasks = taskInfo.tasks.filter(t => t.status !== 'complete').length;
+  if (incompleteTasks === 0) {
+    console.log(`${c.green}All ${taskInfo.tasks.length} tasks already complete!${c.reset}`);
+    session.state.status = 'completed';
+    session.save();
+    return;
+  }
 
-  const child = spawn('bash', [scriptPath, ...args], {
-    stdio: 'inherit',
-    cwd: process.cwd()
+  // Display startup
+  console.log(`
+${c.cyan}${c.bold}⚡ Bootspring Autonomous Loop${c.reset}
+${c.dim}Session: ${session.state.sessionId}${c.reset}
+
+${c.bold}Configuration${c.reset}
+  Tool: ${session.state.tool}
+  Source: ${taskInfo.source} (${taskInfo.name || taskInfo.path})
+  Tasks: ${incompleteTasks} pending of ${taskInfo.tasks.length} total
+  Max iterations: ${session.state.maxIterations}
+  Rate limit: ${LOOP_CONFIG.maxCallsPerHour}/hour
+`);
+
+  session.log(`Loop started: ${incompleteTasks} tasks, max ${session.state.maxIterations} iterations`);
+  telemetry.track('loop:start', {
+    sessionId: session.state.sessionId,
+    source: session.state.source,
+    tasks: taskInfo.tasks.length,
+    incomplete: incompleteTasks
   });
 
-  child.on('close', (code) => {
-    process.exit(code);
+  // Main loop
+  while (session.state.iteration < session.state.maxIterations) {
+    // Refresh task list
+    const currentTasks = getTasks(session.state.source, session.state.sourcePath, projectRoot);
+    const remaining = currentTasks.tasks.filter(t => t.status !== 'complete').length;
+
+    if (remaining === 0) {
+      console.log(`\n${c.green}${c.bold}✓ All tasks complete!${c.reset}`);
+      session.state.status = 'completed';
+      session.save();
+      break;
+    }
+
+    // Run iteration
+    const result = await runIteration(session, currentTasks, options);
+
+    session.state.iteration++;
+    session.save();
+
+    // Handle result
+    if (result.status === 'all_complete') {
+      console.log(`\n${c.green}${c.bold}✓ Loop complete: ${result.reason || 'All tasks done'}${c.reset}`);
+      session.state.status = 'completed';
+      session.save();
+      break;
+    } else if (result.status === 'complete') {
+      console.log(`${c.green}✓${c.reset} Task completed`);
+    } else if (result.status === 'blocked') {
+      console.log(`${c.yellow}⚠${c.reset} Task blocked: ${result.reason || 'Unknown reason'}`);
+    } else if (result.status === 'error') {
+      console.log(`${c.red}✗${c.reset} Error: ${result.error || `Exit code ${result.exitCode}`}`);
+
+      if (session.state.consecutiveErrors >= LOOP_CONFIG.maxConsecutiveErrors) {
+        console.log(`\n${c.red}${c.bold}Circuit breaker triggered after ${LOOP_CONFIG.maxConsecutiveErrors} consecutive errors${c.reset}`);
+        session.state.status = 'failed';
+        session.save();
+        break;
+      }
+    }
+
+    // Delay between iterations
+    await sleep(LOOP_CONFIG.minDelayBetweenCalls);
+  }
+
+  // Final summary
+  console.log(`
+${c.cyan}${c.bold}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${c.reset}
+${c.bold}Loop Summary${c.reset}
+  Status: ${session.state.status}
+  Iterations: ${session.state.iteration}
+  Success rate: ${(session.metrics.completionRate * 100).toFixed(0)}%
+  Total time: ${formatDuration(session.metrics.totalDuration)}
+`);
+
+  telemetry.track('loop:end', {
+    sessionId: session.state.sessionId,
+    status: session.state.status,
+    iterations: session.state.iteration,
+    successRate: session.metrics.completionRate
   });
+
+  // Show recent commits if any
+  try {
+    const commits = execSync('git log --oneline -n 5', {
+      cwd: projectRoot,
+      encoding: 'utf-8'
+    });
+    if (commits.trim()) {
+      console.log(`${c.bold}Recent Commits${c.reset}`);
+      console.log(commits.split('\n').map(l => `  ${l}`).join('\n'));
+    }
+  } catch {
+    // No git or no commits
+  }
+
+  session.log(`Loop ended: ${session.state.status}, ${session.state.iteration} iterations`);
+}
+
+/**
+ * Format duration
+ */
+function formatDuration(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  if (ms < 3600000) return `${(ms / 60000).toFixed(1)}m`;
+  return `${(ms / 3600000).toFixed(1)}h`;
+}
+
+/**
+ * Show loop status/monitor
+ */
+function showStatus(projectRoot, options = {}) {
+  const session = new LoopSession(projectRoot);
+
+  if (options.watch) {
+    // Live monitor mode
+    console.clear();
+    console.log(`${c.cyan}${c.bold}⚡ Bootspring Loop Monitor${c.reset}`);
+    console.log(`${c.dim}Press Ctrl+C to exit${c.reset}\n`);
+
+    const interval = setInterval(() => {
+      const s = new LoopSession(projectRoot);
+      console.clear();
+      displayStatus(s);
+    }, 1000);
+
+    process.on('SIGINT', () => {
+      clearInterval(interval);
+      process.exit(0);
+    });
+
+    displayStatus(session);
+    return;
+  }
+
+  displayStatus(session);
+}
+
+/**
+ * Display status helper
+ */
+function displayStatus(session) {
+  const state = session.state;
+  const metrics = session.metrics;
+
+  const statusIcon = {
+    idle: `${c.dim}○${c.reset}`,
+    running: `${c.green}●${c.reset}`,
+    paused: `${c.yellow}◐${c.reset}`,
+    completed: `${c.green}✓${c.reset}`,
+    failed: `${c.red}✗${c.reset}`
+  }[state.status] || '?';
+
+  console.log(`
+${c.cyan}${c.bold}⚡ Loop Status${c.reset}
+
+${c.bold}Session${c.reset}
+  ID: ${c.dim}${state.sessionId}${c.reset}
+  Status: ${statusIcon} ${state.status}
+  Tool: ${state.tool}
+  Source: ${state.source}
+
+${c.bold}Progress${c.reset}
+  Iteration: ${state.iteration}/${state.maxIterations}
+  Completion indicators: ${state.completionIndicatorCount}
+  Exit signal: ${state.exitSignalReceived ? `${c.green}Yes${c.reset}` : `${c.dim}No${c.reset}`}
+  Consecutive errors: ${state.consecutiveErrors}
+
+${c.bold}Metrics${c.reset}
+  Total iterations: ${metrics.totalIterations}
+  Successful: ${c.green}${metrics.successfulTasks}${c.reset}
+  Failed: ${c.red}${metrics.failedTasks}${c.reset}
+  Blocked: ${c.yellow}${metrics.blockedTasks}${c.reset}
+  Success rate: ${(metrics.completionRate * 100).toFixed(0)}%
+  Avg task time: ${formatDuration(metrics.averageTaskDuration)}
+`);
+
+  // Current task
+  if (state.currentTask) {
+    console.log(`${c.bold}Current Task${c.reset}`);
+    console.log(`  ${state.currentTask.title}`);
+    console.log(`  Started: ${state.currentTask.startedAt}`);
+    console.log('');
+  }
+
+  // Recent history
+  if (state.taskHistory.length > 0) {
+    console.log(`${c.bold}Recent Tasks${c.reset}`);
+    const recent = state.taskHistory.slice(-5);
+    for (const task of recent) {
+      const icon = task.status === 'complete' ? `${c.green}✓${c.reset}` :
+        task.status === 'error' ? `${c.red}✗${c.reset}` :
+          task.status === 'blocked' ? `${c.yellow}⚠${c.reset}` : '○';
+      console.log(`  ${icon} ${task.title}`);
+    }
+    console.log('');
+  }
+
+  // Rate limit status
+  const callsThisHour = state.callsThisHour.filter(t => t > Date.now() - 3600000).length;
+  const rateColor = callsThisHour > 80 ? c.red : callsThisHour > 50 ? c.yellow : c.green;
+  console.log(`${c.bold}Rate Limit${c.reset}`);
+  console.log(`  ${rateColor}${callsThisHour}${c.reset}/${LOOP_CONFIG.maxCallsPerHour} calls this hour`);
+}
+
+/**
+ * Pause the loop
+ */
+function pauseLoop(projectRoot) {
+  const session = new LoopSession(projectRoot);
+
+  if (session.state.status !== 'running') {
+    console.log(`${c.yellow}Loop is not running${c.reset}`);
+    return;
+  }
+
+  session.state.status = 'paused';
+  session.save();
+  session.log('Loop paused by user');
+
+  console.log(`${c.green}Loop paused${c.reset}`);
+  console.log('Resume with: bootspring loop start --resume');
+}
+
+/**
+ * Reset the loop
+ */
+function resetLoop(projectRoot) {
+  const session = new LoopSession(projectRoot);
+  session.reset();
+
+  console.log(`${c.green}Loop session reset${c.reset}`);
 }
 
 /**
@@ -140,7 +956,7 @@ function createPRD(name, options = {}) {
 /**
  * Show PRD status
  */
-function showStatus(prdPath) {
+function showPRDStatus(prdPath) {
   const filePath = prdPath || path.join(prd.DEFAULT_PRD_DIR, prd.DEFAULT_PRD_FILE);
   const data = prd.loadPRD(filePath);
 
@@ -207,11 +1023,6 @@ function showStatus(prdPath) {
  * Generate PRD skill for Claude Code
  */
 function generateSkill() {
-  // Require MCP for skill generation
-  if (!utils.requireMCP('Skill generation')) {
-    return;
-  }
-
   const skillDir = path.join(__dirname, '..', '.claude-plugin', 'skills');
 
   if (!fs.existsSync(skillDir)) {
@@ -345,71 +1156,154 @@ bootspring loop prd <name>      # Create new PRD
  */
 function showHelp() {
   console.log(`
-${c.bold}Bootspring Autonomous Loop${c.reset}
+${c.cyan}${c.bold}⚡ Bootspring Autonomous Loop${c.reset}
+${c.dim}Intelligent task execution with session continuity${c.reset}
 
-${c.cyan}Usage:${c.reset}
+${c.bold}Usage:${c.reset}
   bootspring loop <command> [options]
 
-${c.cyan}Commands:${c.reset}
-  start [n] [--tool]    Start loop (n iterations, default 10)
-  status                Show PRD progress
-  prd <name>            Create new PRD template
-  prd --from <file>     Create PRD from markdown
-  skill                 Generate Claude Code plugin skills
-
-${c.cyan}Options:${c.reset}
-  --tool <claude|amp>   AI tool to use (default: claude)
-  --prd <path>          Path to prd.json
-
-${c.cyan}Examples:${c.reset}
+${c.bold}Commands:${c.reset}
+  ${c.cyan}start${c.reset}             Start the autonomous loop
+  ${c.cyan}status${c.reset}            Show loop status and metrics
+  ${c.cyan}pause${c.reset}             Pause a running loop
+  ${c.cyan}reset${c.reset}             Reset loop session state
+  ${c.cyan}prd <name>${c.reset}        Create a new PRD template
+  ${c.cyan}skill${c.reset}             Generate Claude Code plugin skills
+
+${c.bold}Options:${c.reset}
+  --iterations <n>    Max iterations (default: 10)
+  --tool <name>       AI tool: claude or amp (default: auto-detect)
+  --source <type>     Task source: prd, todo, or plan (default: prd)
+  --resume            Resume a paused session
+  --force             Force restart even if session running
+  --live              Stream AI output in real-time
+  --watch             Live monitoring mode
+  --verbose           Show detailed output
+
+${c.bold}Task Sources:${c.reset}
+  ${c.cyan}prd${c.reset}               Tasks from tasks/prd.json
+  ${c.cyan}todo${c.reset}              Tasks from todo.md
+  ${c.cyan}plan${c.reset}              Tasks from planning/*.md
+  ${c.cyan}build${c.reset}             Tasks from autonomous build system
+
+${c.bold}Features:${c.reset}
+  • Session continuity (--resume)
+  • Rate limiting (${LOOP_CONFIG.maxCallsPerHour}/hour)
+  • Circuit breaker (${LOOP_CONFIG.maxConsecutiveErrors} consecutive errors)
+  • Dual-condition exit detection
+  • Live monitoring (--watch)
+
+${c.bold}Examples:${c.reset}
   bootspring loop prd user-auth
-  bootspring loop start 20 --tool claude
-  bootspring loop status
+  bootspring loop start --iterations 20
+  bootspring loop start --source todo
+  bootspring loop start --resume
+  bootspring loop status --watch
 
-${c.cyan}Workflow:${c.reset}
+${c.bold}Workflow:${c.reset}
   1. Create PRD:    bootspring loop prd my-feature
   2. Edit stories:  Edit tasks/prd.json
   3. Start loop:    bootspring loop start
-  4. Monitor:       bootspring loop status
+  4. Monitor:       bootspring loop status --watch
 `);
 }
 
+/**
+ * Parse arguments
+ */
+function parseArgs(args) {
+  const result = {
+    _: [],
+    iterations: 10,
+    tool: null,
+    source: 'prd',
+    sourcePath: null,
+    resume: false,
+    force: false,
+    live: false,
+    watch: false,
+    verbose: false,
+    from: null
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--iterations' || arg === '-n') {
+      result.iterations = parseInt(args[++i], 10) || 10;
+    } else if (arg === '--tool') {
+      result.tool = args[++i];
+    } else if (arg === '--source') {
+      result.source = args[++i];
+    } else if (arg === '--path') {
+      result.sourcePath = args[++i];
+    } else if (arg === '--from') {
+      result.from = args[++i];
+    } else if (arg === '--resume') {
+      result.resume = true;
+    } else if (arg === '--force') {
+      result.force = true;
+    } else if (arg === '--live') {
+      result.live = true;
+    } else if (arg === '--watch') {
+      result.watch = true;
+    } else if (arg === '--verbose' || arg === '-v') {
+      result.verbose = true;
+    } else if (/^\d+$/.test(arg)) {
+      result.iterations = parseInt(arg, 10);
+    } else if (!arg.startsWith('-')) {
+      result._.push(arg);
+    }
+  }
+
+  return result;
+}
+
 /**
  * Main CLI handler
  */
-function main(args) {
-  const command = args[0] || 'help';
+async function run(args) {
+  const parsed = parseArgs(args);
+  const command = parsed._[0] || 'help';
+
+  const cfg = config.load();
+  const projectRoot = cfg._projectRoot;
 
   switch (command) {
     case 'start': {
-      const tool = detectTool();
-      if (!tool) {
-        console.error(`${c.red}No AI tool found. Install claude or amp CLI.${c.reset}`);
-        process.exit(1);
-      }
-
-      const iterations = args.find(a => /^\d+$/.test(a)) || '10';
-      const toolArg = args.includes('--tool') ?
-        args[args.indexOf('--tool') + 1] : tool;
-      const prdArg = args.includes('--prd') ?
-        args[args.indexOf('--prd') + 1] : null;
-
-      runLoop({ iterations, tool: toolArg, prd: prdArg });
+      await runLoop(projectRoot, {
+        iterations: parsed.iterations,
+        tool: parsed.tool,
+        source: parsed.source,
+        sourcePath: parsed.sourcePath,
+        resume: parsed.resume,
+        force: parsed.force,
+        live: parsed.live,
+        verbose: parsed.verbose
+      });
       break;
     }
 
     case 'status':
-      showStatus(args[1]);
+    case 'monitor':
+      showStatus(projectRoot, { watch: parsed.watch });
       break;
 
-    case 'prd': {
-      // Skip the 'prd' command itself, find the feature name
-      const prdArgs = args.slice(1);
-      const name = prdArgs.find(a => !a.startsWith('--'));
-      const fromFile = prdArgs.includes('--from') ?
-        prdArgs[prdArgs.indexOf('--from') + 1] : null;
+    case 'pause':
+    case 'stop':
+      pauseLoop(projectRoot);
+      break;
+
+    case 'reset':
+      resetLoop(projectRoot);
+      break;
 
-      createPRD(name, { from: fromFile });
+    case 'prd': {
+      const name = parsed._[1];
+      createPRD(name, { from: parsed.from });
+      if (!parsed.from) {
+        showPRDStatus();
+      }
       break;
     }
 
@@ -426,7 +1320,16 @@ function main(args) {
 
 // CLI execution
 if (require.main === module) {
-  main(process.argv.slice(2));
+  run(process.argv.slice(2));
 }
 
-module.exports = { run: main, main, runLoop, createPRD, showStatus };
+module.exports = {
+  run,
+  runLoop,
+  LoopSession,
+  createPRD,
+  showStatus,
+  showPRDStatus,
+  getTasks,
+  LOOP_CONFIG
+};