agileflow 2.85.0 → 2.87.0

package/src/core/templates/session-state.json

@@ -1,15 +1,20 @@
 {
   "$schema": "https://json-schema.org/draft-07/schema#",
   "description": "AgileFlow session state tracking",
-  "schema_version": 2,
+  "schema_version": 3,
   "current_session": {
     "id": "sess-20251206-100000",
     "started_at": "2025-12-06T10:00:00Z",
     "baseline_verified": false,
     "initial_test_status": "not_run",
     "current_story": null,
-    "active_agent": null
+    "active_agent": null,
+    "thread_type": "base",
+    "thread_complexity": "routine",
+    "expected_duration_minutes": null
   },
+  "_thread_type_enum": ["base", "parallel", "chained", "fusion", "big", "long"],
+  "_thread_complexity_enum": ["trivial", "routine", "complex", "exploratory"],
   "active_command": {
     "_comment": "Tracks which command (babysit, etc.) is currently active for context preservation across compacts",
     "name": null,
@@ -23,5 +28,29 @@
     "final_test_status": "not_run",
     "commits": []
   },
-  "session_history": []
+  "session_history": [],
+  "batch_loop": {
+    "_comment": "State for batch pmap loop mode - iterative processing with quality gates",
+    "enabled": false,
+    "batch_id": null,
+    "pattern": null,
+    "action": null,
+    "quality_gate": "tests",
+    "current_item": null,
+    "items": {},
+    "summary": {
+      "total": 0,
+      "completed": 0,
+      "in_progress": 0,
+      "pending": 0,
+      "failed": 0
+    },
+    "iteration": 0,
+    "max_iterations": 50,
+    "started_at": null,
+    "completed_at": null,
+    "stopped_reason": null,
+    "last_failure": null
+  },
+  "_batch_item_status_enum": ["pending", "in_progress", "completed", "failed", "skipped"]
 }

package/tools/cli/commands/config.js

@@ -11,6 +11,7 @@ const yaml = require('js-yaml');
 const { Installer } = require('../installers/core/installer');
 const { IdeManager } = require('../installers/ide/manager');
 const { displayLogo, displaySection, success, warning, error, info } = require('../lib/ui');
+const { ErrorHandler } = require('../lib/error-handler');
 
 const installer = new Installer();
 const ideManager = new IdeManager();
@@ -33,9 +34,12 @@ module.exports = {
 
       if (!status.installed) {
         displayLogo();
-        warning('No AgileFlow installation found');
-        console.log(chalk.dim(`\nRun 'npx agileflow setup' to set up AgileFlow\n`));
-        process.exit(1);
+        const handler = new ErrorHandler('config');
+        handler.warning(
+          'No AgileFlow installation found',
+          'Initialize AgileFlow first',
+          'npx agileflow setup'
+        );
       }
 
       const manifestPath = path.join(status.path, '_cfg', 'manifest.yaml');
@@ -76,11 +80,13 @@ module.exports = {
 
       process.exit(0);
     } catch (err) {
-      console.error(chalk.red('Error:'), err.message);
-      if (process.env.DEBUG) {
-        console.error(err.stack);
-      }
-      process.exit(1);
+      const handler = new ErrorHandler('config');
+      handler.critical(
+        'Configuration operation failed',
+        'Check manifest file integrity',
+        'npx agileflow doctor --fix',
+        err
+      );
     }
   },
 };
@@ -121,17 +127,24 @@ async function handleList(status) {
  * Handle get subcommand
  */
 async function handleGet(status, key) {
+  const handler = new ErrorHandler('config');
+
   if (!key) {
-    error('Missing key. Usage: npx agileflow config get <key>');
-    process.exit(1);
+    handler.warning(
+      'Missing key',
+      'Provide a config key to get',
+      'npx agileflow config get <key>'
+    );
   }
 
   const validKeys = ['userName', 'ides', 'agileflowFolder', 'docsFolder', 'version'];
 
   if (!validKeys.includes(key)) {
-    error(`Invalid key: ${key}`);
-    console.log(chalk.dim(`Valid keys: ${validKeys.join(', ')}\n`));
-    process.exit(1);
+    handler.warning(
+      `Invalid key: ${key}`,
+      `Valid keys: ${validKeys.join(', ')}`,
+      'npx agileflow config list'
+    );
   }
 
   let value;
@@ -160,17 +173,24 @@ async function handleGet(status, key) {
  * Handle set subcommand
  */
 async function handleSet(directory, status, manifestPath, key, value) {
+  const handler = new ErrorHandler('config');
+
   if (!key || value === undefined) {
-    error('Missing arguments. Usage: npx agileflow config set <key> <value>');
-    process.exit(1);
+    handler.warning(
+      'Missing arguments',
+      'Provide both key and value',
+      'npx agileflow config set <key> <value>'
+    );
   }
 
   const validKeys = ['userName', 'ides', 'agileflowFolder', 'docsFolder'];
 
   if (!validKeys.includes(key)) {
-    error(`Invalid key: ${key}`);
-    console.log(chalk.dim(`Valid keys: ${validKeys.join(', ')}\n`));
-    process.exit(1);
+    handler.warning(
+      `Invalid key: ${key}`,
+      `Valid keys: ${validKeys.join(', ')}`,
+      'npx agileflow config list'
+    );
   }
 
   displayLogo();
@@ -198,9 +218,11 @@ async function handleSet(directory, status, manifestPath, key, value) {
       // Validate IDEs
       for (const ide of newIdes) {
         if (!validIdes.includes(ide)) {
-          error(`Invalid IDE: ${ide}`);
-          console.log(chalk.dim(`Valid IDEs: ${validIdes.join(', ')}\n`));
-          process.exit(1);
+          handler.warning(
+            `Invalid IDE: ${ide}`,
+            `Valid IDEs: ${validIdes.join(', ')}`,
+            'npx agileflow config set ides "claude-code,cursor"'
+          );
         }
       }
 

package/tools/cli/commands/doctor.js

@@ -20,6 +20,7 @@ const {
 } = require('../lib/ui');
 const { IdeManager } = require('../installers/ide/manager');
 const { getCurrentVersion } = require('../lib/version-checker');
+const { ErrorHandler } = require('../lib/error-handler');
 
 const installer = new Installer();
 
@@ -306,11 +307,13 @@ module.exports = {
 
       process.exit(issues > 0 ? 1 : 0);
     } catch (err) {
-      console.error(chalk.red('Error:'), err.message);
-      if (process.env.DEBUG) {
-        console.error(err.stack);
-      }
-      process.exit(1);
+      const handler = new ErrorHandler('doctor');
+      handler.critical(
+        'Diagnostics failed',
+        'Check permissions and installation',
+        'npx agileflow setup',
+        err
+      );
     }
   },
 };

package/tools/cli/commands/setup.js

@@ -22,6 +22,7 @@ const {
 } = require('../lib/ui');
 const { createDocsStructure } = require('../lib/docs-setup');
 const { getLatestVersion } = require('../lib/npm-utils');
+const { ErrorHandler } = require('../lib/error-handler');
 
 const installer = new Installer();
 const ideManager = new IdeManager();
@@ -101,8 +102,12 @@ module.exports = {
       const coreResult = await installer.install(config);
 
       if (!coreResult.success) {
-        error('Core setup failed');
-        process.exit(1);
+        const handler = new ErrorHandler('setup');
+        handler.warning(
+          'Core setup failed',
+          'Check directory permissions',
+          'npx agileflow doctor'
+        );
       }
 
       success(`Installed ${coreResult.counts.agents} agents`);
@@ -144,11 +149,13 @@ module.exports = {
 
       process.exit(0);
     } catch (err) {
-      console.error(chalk.red('\nSetup failed:'), err.message);
-      if (process.env.DEBUG) {
-        console.error(err.stack);
-      }
-      process.exit(1);
+      const handler = new ErrorHandler('setup');
+      handler.critical(
+        'Setup failed',
+        'Check directory exists and has write permissions',
+        'npx agileflow doctor',
+        err
+      );
     }
   },
 };

package/tools/cli/commands/uninstall.js

@@ -10,6 +10,7 @@ const fs = require('fs-extra');
 const { Installer } = require('../installers/core/installer');
 const { IdeManager } = require('../installers/ide/manager');
 const { displayLogo, displaySection, success, warning, error, confirm } = require('../lib/ui');
+const { ErrorHandler } = require('../lib/error-handler');
 
 const installer = new Installer();
 const ideManager = new IdeManager();
@@ -138,11 +139,13 @@ module.exports = {
 
       process.exit(0);
     } catch (err) {
-      console.error(chalk.red('Uninstall failed:'), err.message);
-      if (process.env.DEBUG) {
-        console.error(err.stack);
-      }
-      process.exit(1);
+      const handler = new ErrorHandler('uninstall');
+      handler.critical(
+        'Uninstall failed',
+        'Check file permissions',
+        'sudo npx agileflow uninstall --force',
+        err
+      );
     }
   },
 };

package/tools/cli/commands/update.js

@@ -22,6 +22,7 @@ const {
 } = require('../lib/ui');
 const { createDocsStructure, getDocsFolderName } = require('../lib/docs-setup');
 const { getLatestVersion } = require('../lib/npm-utils');
+const { ErrorHandler } = require('../lib/error-handler');
 
 const installer = new Installer();
 const ideManager = new IdeManager();
@@ -76,9 +77,12 @@ module.exports = {
       const status = await installer.getStatus(directory);
 
       if (!status.installed) {
-        warning('No AgileFlow installation found');
-        console.log(chalk.dim(`\nRun 'npx agileflow setup' to set up AgileFlow\n`));
-        process.exit(1);
+        const handler = new ErrorHandler('update');
+        handler.warning(
+          'No AgileFlow installation found',
+          'Initialize AgileFlow first',
+          'npx agileflow setup'
+        );
       }
 
       displaySection('Updating AgileFlow', `Current version: ${status.version}`);
@@ -179,8 +183,12 @@ module.exports = {
       const coreResult = await installer.install(config, { force: options.force });
 
       if (!coreResult.success) {
-        error('Update failed');
-        process.exit(1);
+        const handler = new ErrorHandler('update');
+        handler.warning(
+          'Update failed',
+          'Try running doctor to diagnose issues',
+          'npx agileflow doctor --fix'
+        );
       }
 
       success('Updated core content');
@@ -237,11 +245,13 @@ module.exports = {
 
       process.exit(0);
     } catch (err) {
-      console.error(chalk.red('Update failed:'), err.message);
-      if (process.env.DEBUG) {
-        console.error(err.stack);
-      }
-      process.exit(1);
+      const handler = new ErrorHandler('update');
+      handler.critical(
+        'Update failed',
+        'Check network connection and disk space',
+        'npx agileflow doctor',
+        err
+      );
     }
   },
 };

package/tools/cli/lib/content-injector.js

@@ -202,6 +202,80 @@ function injectContent(content, context = {}) {
   return result;
 }
 
+// =============================================================================
+// Section Processing Functions (Progressive Disclosure)
+// =============================================================================
+
+/**
+ * Extract section names from content
+ * @param {string} content - Content with section markers
+ * @returns {string[]} Array of section names
+ */
+function extractSectionNames(content) {
+  const sectionPattern = /<!-- SECTION: (\w+[-\w]*) -->/g;
+  const sections = [];
+  let match;
+  while ((match = sectionPattern.exec(content)) !== null) {
+    sections.push(match[1]);
+  }
+  return sections;
+}
+
+/**
+ * Filter content to only include specified sections
+ * Sections are marked with: <!-- SECTION: name --> ... <!-- END_SECTION -->
+ *
+ * @param {string} content - Content with section markers
+ * @param {string[]} activeSections - Sections to include (empty = include all)
+ * @returns {string} Content with only active sections
+ */
+function filterSections(content, activeSections = []) {
+  // If no active sections specified, include all content
+  if (!activeSections || activeSections.length === 0) {
+    return content;
+  }
+
+  // Pattern matches: <!-- SECTION: name --> content <!-- END_SECTION -->
+  const sectionPattern = /<!-- SECTION: (\w+[-\w]*) -->([\s\S]*?)<!-- END_SECTION -->/g;
+
+  return content.replace(sectionPattern, (match, sectionName, sectionContent) => {
+    if (activeSections.includes(sectionName)) {
+      // Keep the section content, remove the markers
+      return sectionContent;
+    }
+    // Remove the entire section
+    return '';
+  });
+}
+
+/**
+ * Remove all section markers but keep content
+ * Used when no filtering is needed but markers should be cleaned
+ *
+ * @param {string} content - Content with section markers
+ * @returns {string} Content without section markers
+ */
+function stripSectionMarkers(content) {
+  // Remove section start markers
+  let result = content.replace(/<!-- SECTION: \w+[-\w]* -->\n?/g, '');
+  // Remove section end markers
+  result = result.replace(/<!-- END_SECTION -->\n?/g, '');
+  return result;
+}
+
+/**
+ * Check if content has section markers
+ * @param {string} content - Content to check
+ * @returns {boolean} True if content has sections
+ */
+function hasSections(content) {
+  return /<!-- SECTION: \w+[-\w]* -->/.test(content);
+}
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
 /**
  * Check if content has any template variables
  * @param {string} content - Content to check
@@ -263,4 +337,10 @@ module.exports = {
   injectContent,
   hasPlaceholders,
   getPlaceholderDocs,
+
+  // Section processing (progressive disclosure)
+  extractSectionNames,
+  filterSections,
+  stripSectionMarkers,
+  hasSections,
 };

package/tools/cli/lib/error-handler.js

@@ -0,0 +1,173 @@
+/**
+ * error-handler.js - Centralized Error Handling with Actionable Guidance
+ *
+ * Provides three-tier error handling:
+ * - INFO: Non-blocking issues (does not exit)
+ * - WARNING: Issues that should be addressed (exit 1)
+ * - CRITICAL: Severe errors (exit 1 + stack trace if DEBUG=1)
+ *
+ * Error output format: "X <problem> | Action: <what to do> | Run: <command>"
+ */
+
+const { c } = require('../../../lib/colors');
+
+class ErrorHandler {
+  /**
+   * Create an ErrorHandler instance
+   * @param {string} commandName - Name of the command using this handler
+   */
+  constructor(commandName = 'agileflow') {
+    this.commandName = commandName;
+  }
+
+  /**
+   * Format error with actionable guidance
+   * Output: "X <problem> | Action: <what to do> | Run: <command>"
+   *
+   * @param {string} message - The error message describing the problem
+   * @param {string} [actionText] - What the user should do to fix it
+   * @param {string} [commandHint] - Command to run to fix it
+   * @returns {string} Formatted error string
+   */
+  formatError(message, actionText, commandHint) {
+    let output = `${c.red}\u2716${c.reset} ${message}`;
+    if (actionText) {
+      output += ` ${c.dim}|${c.reset} ${c.cyan}Action:${c.reset} ${actionText}`;
+    }
+    if (commandHint) {
+      output += ` ${c.dim}|${c.reset} ${c.green}Run:${c.reset} ${c.bold}${commandHint}${c.reset}`;
+    }
+    return output;
+  }
+
+  /**
+   * Format warning message (yellow indicator)
+   * @param {string} message - The warning message
+   * @param {string} [actionText] - What the user should do
+   * @param {string} [commandHint] - Command to run
+   * @returns {string} Formatted warning string
+   */
+  formatWarning(message, actionText, commandHint) {
+    let output = `${c.yellow}\u26A0${c.reset}  ${message}`;
+    if (actionText) {
+      output += ` ${c.dim}|${c.reset} ${c.cyan}Action:${c.reset} ${actionText}`;
+    }
+    if (commandHint) {
+      output += ` ${c.dim}|${c.reset} ${c.green}Run:${c.reset} ${c.bold}${commandHint}${c.reset}`;
+    }
+    return output;
+  }
+
+  /**
+   * INFO: Non-blocking issue, continue execution (does NOT exit)
+   * Use for informational messages about issues that don't prevent operation.
+   *
+   * @param {string} message - The info message
+   * @param {string} [actionText] - Optional action hint
+   * @param {string} [commandHint] - Optional command hint
+   */
+  info(message, actionText, commandHint) {
+    console.log(this.formatWarning(message, actionText, commandHint));
+    // Does NOT exit - allows continuation
+  }
+
+  /**
+   * WARNING: Issue that should be addressed (exit 1)
+   * Use for problems that prevent the operation from completing properly.
+   *
+   * @param {string} message - The warning message
+   * @param {string} [actionText] - What the user should do
+   * @param {string} [commandHint] - Command to run to fix it
+   */
+  warning(message, actionText, commandHint) {
+    console.error(this.formatError(message, actionText, commandHint));
+    process.exit(1);
+  }
+
+  /**
+   * CRITICAL: Severe error (exit 1 + stack trace if DEBUG=1)
+   * Use for unexpected errors, crashes, or severe failures.
+   *
+   * @param {string} message - The error message
+   * @param {string} [actionText] - What the user should do
+   * @param {string} [commandHint] - Command to run
+   * @param {Error} [error] - Original error object for stack trace
+   */
+  critical(message, actionText, commandHint, error) {
+    console.error(this.formatError(message, actionText, commandHint));
+    if (process.env.DEBUG === '1' && error?.stack) {
+      console.error(`\n${c.dim}Stack trace:${c.reset}`);
+      console.error(c.dim + error.stack + c.reset);
+    }
+    process.exit(1);
+  }
+
+  /**
+   * Convenience method: Get formatted error string without exiting
+   * Useful for collecting multiple errors before displaying.
+   *
+   * @param {string} message - The error message
+   * @param {string} [actionText] - What the user should do
+   * @param {string} [commandHint] - Command to run
+   * @returns {string} Formatted error string
+   */
+  errorWithAction(message, actionText, commandHint) {
+    return this.formatError(message, actionText, commandHint);
+  }
+
+  /**
+   * Convenience method: Get formatted warning string without exiting
+   *
+   * @param {string} message - The warning message
+   * @param {string} [actionText] - What the user should do
+   * @param {string} [commandHint] - Command to run
+   * @returns {string} Formatted warning string
+   */
+  warningWithAction(message, actionText, commandHint) {
+    return this.formatWarning(message, actionText, commandHint);
+  }
+
+  /**
+   * Display multiple issues at once, then exit with appropriate code
+   * Useful for validation that collects all errors before reporting.
+   *
+   * @param {Array<{type: 'info'|'warning'|'error', message: string, action?: string, command?: string}>} issues
+   * @returns {boolean} True if there were errors/warnings (would normally exit)
+   */
+  reportIssues(issues) {
+    let hasErrors = false;
+    let hasWarnings = false;
+
+    for (const issue of issues) {
+      if (issue.type === 'error') {
+        console.error(this.formatError(issue.message, issue.action, issue.command));
+        hasErrors = true;
+      } else if (issue.type === 'warning') {
+        console.error(this.formatWarning(issue.message, issue.action, issue.command));
+        hasWarnings = true;
+      } else {
+        console.log(this.formatWarning(issue.message, issue.action, issue.command));
+      }
+    }
+
+    if (hasErrors || hasWarnings) {
+      process.exit(1);
+    }
+
+    return hasErrors || hasWarnings;
+  }
+}
+
+/**
+ * Create a pre-configured ErrorHandler instance
+ * @param {string} commandName - Name of the command
+ * @returns {ErrorHandler} New ErrorHandler instance
+ */
+function createErrorHandler(commandName) {
+  return new ErrorHandler(commandName);
+}
+
+module.exports = {
+  ErrorHandler,
+  createErrorHandler,
+};

package/tools/cli/lib/ui.js

@@ -9,6 +9,7 @@ const inquirer = require('inquirer');
 const path = require('node:path');
 const fs = require('node:fs');
 const { IdeManager } = require('../installers/ide/manager');
+const { BRAND_HEX } = require('../../../lib/colors');
 
 // Load package.json for version
 const packageJsonPath = path.join(__dirname, '..', '..', '..', 'package.json');
@@ -25,7 +26,7 @@ function displayLogo() {
 ██╔══██║██║   ██║██║██║     ██╔══╝  ██╔══╝  ██║     ██║   ██║██║███╗██║
 ██║  ██║╚██████╔╝██║███████╗███████╗██║     ███████╗╚██████╔╝╚███╔███╔╝
 ╚═╝  ╚═╝ ╚═════╝ ╚═╝╚══════╝╚══════╝╚═╝     ╚══════╝ ╚═════╝  ╚══╝╚══╝ `;
-  console.log(chalk.hex('#e8683a')(logo));
+  console.log(chalk.hex(BRAND_HEX)(logo));
   console.log(chalk.dim(`  AgileFlow v${packageJson.version} - AI-Driven Agile Development\n`));
 }
 
@@ -35,7 +36,7 @@ function displayLogo() {
  * @param {string} subtitle - Optional subtitle
  */
 function displaySection(title, subtitle = null) {
-  console.log(chalk.bold.hex('#e8683a')(`\n${title}`));
+  console.log(chalk.bold.hex(BRAND_HEX)(`\n${title}`));
   if (subtitle) {
     console.log(chalk.dim(subtitle));
   }