agileflow 2.91.0 → 2.92.1

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.92.1] - 2026-01-23
+
+### Added
+- Session worktree timeout, progress feedback, and docs folder copy
+
+## [2.92.0] - 2026-01-23
+
+### Added
+- Tmux integration, i18n docs, EP-0022 codebase health improvements
+
 ## [2.91.0] - 2026-01-20
 
 ### Added

package/README.md

@@ -3,8 +3,8 @@
 </p>
 
 [![npm version](https://img.shields.io/npm/v/agileflow?color=brightgreen)](https://www.npmjs.com/package/agileflow)
-[![Commands](https://img.shields.io/badge/commands-74-blue)](docs/04-architecture/commands.md)
-[![Agents/Experts](https://img.shields.io/badge/agents%2Fexperts-30-orange)](docs/04-architecture/subagents.md)
+[![Commands](https://img.shields.io/badge/commands-77-blue)](docs/04-architecture/commands.md)
+[![Agents/Experts](https://img.shields.io/badge/agents%2Fexperts-31-orange)](docs/04-architecture/subagents.md)
 [![Skills](https://img.shields.io/badge/skills-dynamic-purple)](docs/04-architecture/skills.md)
 
 **AI-driven agile development for Claude Code, Cursor, Windsurf, OpenAI Codex CLI, and more.** Combining Scrum, Kanban, ADRs, and docs-as-code principles into one framework-agnostic system.
@@ -65,8 +65,8 @@ AgileFlow combines three proven methodologies:
 
 | Component | Count | Description |
 |-----------|-------|-------------|
-| [Commands](docs/04-architecture/commands.md) | 74 | Slash commands for agile workflows |
-| [Agents/Experts](docs/04-architecture/subagents.md) | 30 | Specialized agents with self-improving knowledge bases |
+| [Commands](docs/04-architecture/commands.md) | 77 | Slash commands for agile workflows |
+| [Agents/Experts](docs/04-architecture/subagents.md) | 31 | Specialized agents with self-improving knowledge bases |
 | [Skills](docs/04-architecture/skills.md) | Dynamic | Generated on-demand with `/agileflow:skill:create` |
 
 ---
@@ -76,8 +76,8 @@ AgileFlow combines three proven methodologies:
 Full documentation lives in [`docs/04-architecture/`](docs/04-architecture/):
 
 ### Reference
-- [Commands](docs/04-architecture/commands.md) - All 74 slash commands
-- [Agents/Experts](docs/04-architecture/subagents.md) - 30 specialized agents with self-improving knowledge
+- [Commands](docs/04-architecture/commands.md) - All 77 slash commands
+- [Agents/Experts](docs/04-architecture/subagents.md) - 31 specialized agents with self-improving knowledge
 - [Skills](docs/04-architecture/skills.md) - Dynamic skill generator with MCP integration
 
 ### Architecture

package/lib/README.md

@@ -0,0 +1,178 @@
+# AgileFlow CLI Library
+
+Core utility modules for AgileFlow CLI operations.
+
+## Result Schema (`result-schema.js`)
+
+Provides a unified `Result<T>` type for consistent success/failure handling across the codebase.
+
+### Quick Start
+
+```javascript
+const { success, failure, isSuccess, unwrapOr } = require('./result-schema');
+
+// Success case
+function loadConfig() {
+  const config = readConfigFile();
+  return success(config);
+}
+
+// Failure case with error code
+function loadConfig() {
+  if (!fs.existsSync(configPath)) {
+    return failure('ENOENT', 'Config file not found');
+  }
+  return success(config);
+}
+
+// Using results
+const result = loadConfig();
+if (isSuccess(result)) {
+  console.log(result.data);
+} else {
+  console.error(result.error);
+  console.error('Fix:', result.suggestedFix);
+}
+```
+
+### Result Structure
+
+**Success:**
+```javascript
+{
+  ok: true,
+  data: <T>            // The success data
+}
+```
+
+**Failure:**
+```javascript
+{
+  ok: false,
+  error: string,       // Human-readable message
+  errorCode: string,   // Machine-readable code (ENOENT, ECONFIG, etc.)
+  severity: string,    // critical | high | medium | low
+  category: string,    // filesystem | permission | configuration | network | validation | state | dependency
+  recoverable: boolean,
+  suggestedFix: string,
+  autoFix: string|null,
+  context?: object,    // Additional context
+  cause?: Error        // Original error
+}
+```
+
+### API Reference
+
+#### Constructors
+
+| Function | Description |
+|----------|-------------|
+| `success(data, meta?)` | Create success result |
+| `failure(errorCode, message?, options?)` | Create failure result with error code |
+| `failureFromError(error, defaultCode?)` | Create failure from Error object |
+
+#### From Helpers
+
+| Function | Description |
+|----------|-------------|
+| `fromCondition(condition, data, errorCode, message?)` | Create from boolean |
+| `fromPromise(promise, defaultCode?)` | Wrap Promise in Result |
+| `fromTry(fn, defaultCode?)` | Wrap sync function in Result |
+
+#### Type Guards
+
+| Function | Description |
+|----------|-------------|
+| `isSuccess(result)` | Check if result is success |
+| `isFailure(result)` | Check if result is failure |
+
+#### Extractors
+
+| Function | Description |
+|----------|-------------|
+| `unwrap(result, context?)` | Get data or throw |
+| `unwrapOr(result, defaultValue)` | Get data or default |
+
+#### Transformers
+
+| Function | Description |
+|----------|-------------|
+| `map(result, fn)` | Transform success data |
+| `flatMap(result, fn)` | Chain result-returning operations |
+
+#### Combinators
+
+| Function | Description |
+|----------|-------------|
+| `all(results)` | Combine array of results |
+| `any(results)` | Get first success or last failure |
+
+### Error Codes
+
+Available error codes from `error-codes.js`:
+
+| Code | Category | Description |
+|------|----------|-------------|
+| `ENOENT` | filesystem | File or directory not found |
+| `ENODIR` | filesystem | Directory does not exist |
+| `EEXIST` | filesystem | Already exists |
+| `EACCES` | permission | Permission denied |
+| `EPERM` | permission | Operation not permitted |
+| `ECONFIG` | configuration | Invalid/missing configuration |
+| `EPARSE` | configuration | Parse error (JSON/YAML) |
+| `ESCHEMA` | configuration | Schema validation failed |
+| `ENETWORK` | network | Network error |
+| `ETIMEOUT` | network | Operation timed out |
+| `EINVAL` | validation | Invalid argument |
+| `EMISSING` | validation | Required value missing |
+| `ESTATE` | state | Invalid application state |
+| `ECONFLICT` | state | State conflict |
+| `ELOCK` | state | Resource locked |
+| `EDEP` | dependency | Missing dependency |
+| `EUNKNOWN` | state | Unknown error |
+
+### Migration Guide
+
+**Before (inconsistent):**
+```javascript
+// Different modules return different shapes
+return { ok: true, data };
+return { success: true, result };
+return { error: 'message' };
+```
+
+**After (unified):**
+```javascript
+const { success, failure } = require('../lib/result-schema');
+
+// Always use Result type
+return success(data);
+return failure('ENOENT', 'File not found');
+```
+
+## Error Codes (`error-codes.js`)
+
+Centralized error codes with metadata for auto-recovery.
+
+### Key Functions
+
+| Function | Description |
+|----------|-------------|
+| `createErrorResult(code, message?, options?)` | Create failure Result |
+| `createSuccessResult(data, meta?)` | Create success Result |
+| `getErrorCode(code)` | Get error code metadata |
+| `isRecoverable(error)` | Check if error is recoverable |
+| `getSuggestedFix(error)` | Get fix suggestion |
+
+## Safe Wrappers (`errors.js`)
+
+File/command wrappers that return Result objects:
+
+| Function | Description |
+|----------|-------------|
+| `safeReadJSON(path, options?)` | Read and parse JSON |
+| `safeWriteJSON(path, data, options?)` | Write JSON to file |
+| `safeReadFile(path, options?)` | Read text file |
+| `safeWriteFile(path, content, options?)` | Write text file |
+| `safeExec(command, options?)` | Execute shell command |
+| `safeParseJSON(content, options?)` | Parse JSON with validation |

package/lib/codebase-indexer.js

@@ -69,9 +69,7 @@ function loadConfig(projectRoot) {
   return {
     ...DEFAULT_CONFIG,
     // Convert ttl_hours to ttlMs if provided
-    ttlMs: userConfig.ttl_hours
-      ? userConfig.ttl_hours * 60 * 60 * 1000
-      : DEFAULT_CONFIG.ttlMs,
+    ttlMs: userConfig.ttl_hours ? userConfig.ttl_hours * 60 * 60 * 1000 : DEFAULT_CONFIG.ttlMs,
     excludePatterns: userConfig.exclude_patterns || DEFAULT_CONFIG.excludePatterns,
     includePatterns: userConfig.include_patterns || DEFAULT_CONFIG.includePatterns,
     maxFileSizeKb: userConfig.max_file_size_kb || DEFAULT_CONFIG.maxFileSizeKb,
@@ -302,11 +300,11 @@ function shouldIncludeFile(relativePath, excludePatterns) {
     // Handle ** (matches any path segments including none)
     // Handle * (matches within a single path segment)
     let regexPattern = pattern
-      .replace(/\./g, '\\.')          // Escape dots
+      .replace(/\./g, '\\.') // Escape dots
       .replace(/\*\*/g, '<<<GLOB>>>') // Temp placeholder for **
-      .replace(/\*/g, '[^/]*')        // Single * = any chars except /
-      .replace(/<<<GLOB>>>/g, '.*')   // ** = any chars including /
-      .replace(/\?/g, '.');           // ? = any single char
+      .replace(/\*/g, '[^/]*') // Single * = any chars except /
+      .replace(/<<<GLOB>>>/g, '.*') // ** = any chars including /
+      .replace(/\?/g, '.'); // ? = any single char
 
     // Support patterns that should match the start of path
     const regex = new RegExp(`^${regexPattern}`);
@@ -397,7 +395,12 @@ function buildIndex(projectRoot, options = {}) {
     const index = createEmptyIndex(projectRoot);
 
     // Scan for files
-    const files = scanDirectory(projectRoot, projectRoot, config.excludePatterns, config.maxFileSizeKb);
+    const files = scanDirectory(
+      projectRoot,
+      projectRoot,
+      config.excludePatterns,
+      config.maxFileSizeKb
+    );
     index.stats.total_files = files.length;
 
     // Process each file
@@ -437,29 +440,29 @@ function buildIndex(projectRoot, options = {}) {
         tags,
       };
 
-      // Update tag index
+      // Update tag index (use Object.hasOwn to avoid prototype pollution)
       for (const tag of tags) {
-        if (!index.tags[tag]) {
+        if (!Object.hasOwn(index.tags, tag)) {
           index.tags[tag] = [];
         }
         index.tags[tag].push(relativePath);
       }
 
-      // Update symbol index
+      // Update symbol index (use Object.hasOwn to avoid prototype pollution with names like "constructor")
       for (const func of symbols.functions) {
-        if (!index.symbols.functions[func]) {
+        if (!Object.hasOwn(index.symbols.functions, func)) {
           index.symbols.functions[func] = [];
         }
         index.symbols.functions[func].push(relativePath);
       }
       for (const cls of symbols.classes) {
-        if (!index.symbols.classes[cls]) {
+        if (!Object.hasOwn(index.symbols.classes, cls)) {
           index.symbols.classes[cls] = [];
         }
         index.symbols.classes[cls].push(relativePath);
       }
       for (const exp of exports) {
-        if (!index.symbols.exports[exp]) {
+        if (!Object.hasOwn(index.symbols.exports, exp)) {
           index.symbols.exports[exp] = [];
         }
         index.symbols.exports[exp].push(relativePath);
@@ -564,7 +567,12 @@ function updateIndex(projectRoot, options = {}) {
     const startTime = Date.now();
 
     // Scan for current files
-    const currentFiles = scanDirectory(projectRoot, projectRoot, config.excludePatterns, config.maxFileSizeKb);
+    const currentFiles = scanDirectory(
+      projectRoot,
+      projectRoot,
+      config.excludePatterns,
+      config.maxFileSizeKb
+    );
     const currentFilePaths = new Set(currentFiles.map(f => f.path));
 
     // Track changes
@@ -631,11 +639,12 @@ function updateIndex(projectRoot, options = {}) {
 
     for (const [filePath, fileData] of Object.entries(existingIndex.files)) {
       for (const tag of fileData.tags || []) {
-        if (!existingIndex.tags[tag]) existingIndex.tags[tag] = [];
+        if (!Object.hasOwn(existingIndex.tags, tag)) existingIndex.tags[tag] = [];
         existingIndex.tags[tag].push(filePath);
       }
       for (const exp of fileData.exports || []) {
-        if (!existingIndex.symbols.exports[exp]) existingIndex.symbols.exports[exp] = [];
+        if (!Object.hasOwn(existingIndex.symbols.exports, exp))
+          existingIndex.symbols.exports[exp] = [];
         existingIndex.symbols.exports[exp].push(filePath);
       }
     }
@@ -713,14 +722,14 @@ function queryFiles(index, pattern) {
   // Order matters: handle ** before * to avoid double processing
   let regexPattern = pattern
     // First, use placeholders to protect multi-char patterns
-    .replace(/\*\*\//g, '<<<GLOBSLASH>>>')  // **/ placeholder
-    .replace(/\*\*/g, '<<<GLOB>>>')         // ** placeholder
-    .replace(/\./g, '\\.')                  // Escape dots
-    .replace(/\?/g, '.')                    // ? = any single char
-    .replace(/\*/g, '[^/]*')                // Single * = any chars except /
+    .replace(/\*\*\//g, '<<<GLOBSLASH>>>') // **/ placeholder
+    .replace(/\*\*/g, '<<<GLOB>>>') // ** placeholder
+    .replace(/\./g, '\\.') // Escape dots
+    .replace(/\?/g, '.') // ? = any single char
+    .replace(/\*/g, '[^/]*') // Single * = any chars except /
     // Now restore placeholders with actual patterns
     .replace(/<<<GLOBSLASH>>>/g, '(?:.+/)?') // **/ = optionally any path + /
-    .replace(/<<<GLOB>>>/g, '.*');           // ** alone = any chars including /
+    .replace(/<<<GLOB>>>/g, '.*'); // ** alone = any chars including /
 
   const regex = new RegExp(`^${regexPattern}$`, 'i');
 

package/lib/colors.js

@@ -11,21 +11,123 @@
  * - Cyan (#00CED1):      4.6:1 ✓ (meets AA for normal text)
  * - Brand (#e8683a):     3.8:1 ✓ (meets AA for large text/UI elements)
  *
+ * WCAG AAA Contrast Ratios (high-contrast mode, 7:1+ ratio):
+ * - HC Green (#7CFC00):  11.3:1 ✓ (lawn green - meets AAA)
+ * - HC Red (#FF6B6B):    5.0:1 → #FF9999 8.1:1 ✓ (light coral - meets AAA)
+ * - HC Yellow (#FFFF00): 19.6:1 ✓ (pure yellow - meets AAA)
+ * - HC Cyan (#00FFFF):   14.0:1 ✓ (aqua - meets AAA)
+ * - HC White (#FFFFFF):  21.0:1 ✓ (pure white - meets AAA)
+ *
  * Note: Standard ANSI colors vary by terminal theme. The above ratios
  * are for typical dark terminal configurations.
  */
 
+// High-contrast mode detection
+let _highContrastMode = null;
+
+/**
+ * Check if high-contrast mode is enabled.
+ * Checks: AGILEFLOW_HIGH_CONTRAST env var, or cached value.
+ * @returns {boolean} True if high-contrast mode is enabled
+ */
+function isHighContrast() {
+  if (_highContrastMode !== null) {
+    return _highContrastMode;
+  }
+  const envValue = process.env.AGILEFLOW_HIGH_CONTRAST;
+  return envValue === '1' || envValue === 'true' || envValue === 'yes';
+}
+
+/**
+ * Enable or disable high-contrast mode programmatically.
+ * @param {boolean} enabled - Whether to enable high-contrast mode
+ */
+function setHighContrast(enabled) {
+  _highContrastMode = enabled;
+}
+
+/**
+ * Reset high-contrast mode to use environment variable.
+ */
+function resetHighContrast() {
+  _highContrastMode = null;
+}
+
 /**
  * Brand color hex value for chalk compatibility.
  * Use with chalk.hex(BRAND_HEX) in files that use chalk.
  */
 const BRAND_HEX = '#e8683a';
 
+/**
+ * WCAG AAA high-contrast color palette (7:1+ contrast ratio).
+ * Used when AGILEFLOW_HIGH_CONTRAST=1 or --high-contrast flag.
+ */
+const hc = {
+  // Reset and modifiers
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[0m', // No dimming in high-contrast (use regular text)
+  italic: '\x1b[3m',
+  underline: '\x1b[4m',
+
+  // High-contrast standard colors (bright variants for max visibility)
+  red: '\x1b[91m', // Bright red
+  green: '\x1b[92m', // Bright green
+  yellow: '\x1b[93m', // Bright yellow
+  blue: '\x1b[94m', // Bright blue
+  magenta: '\x1b[95m', // Bright magenta
+  cyan: '\x1b[96m', // Bright cyan
+  white: '\x1b[97m', // Bright white
+
+  // Bright variants (same in high-contrast mode)
+  brightBlack: '\x1b[37m', // Use white instead of gray
+  brightRed: '\x1b[91m',
+  brightGreen: '\x1b[92m',
+  brightYellow: '\x1b[93m',
+  brightBlue: '\x1b[94m',
+  brightMagenta: '\x1b[95m',
+  brightCyan: '\x1b[96m',
+  brightWhite: '\x1b[97m',
+
+  // 256-color high-contrast alternatives (all 7:1+ ratio)
+  mintGreen: '\x1b[92m', // Bright green
+  peach: '\x1b[93m', // Bright yellow
+  coral: '\x1b[91m', // Bright red
+  lightGreen: '\x1b[92m', // Bright green
+  lightYellow: '\x1b[93m', // Bright yellow
+  lightPink: '\x1b[91m', // Bright red
+  skyBlue: '\x1b[96m', // Bright cyan
+  lavender: '\x1b[95m', // Bright magenta
+  softGold: '\x1b[93m', // Bright yellow
+  teal: '\x1b[96m', // Bright cyan
+  slate: '\x1b[97m', // White (instead of gray)
+  rose: '\x1b[91m', // Bright red
+  amber: '\x1b[93m', // Bright yellow
+  powder: '\x1b[96m', // Bright cyan
+
+  // Brand color - use bright orange/yellow for visibility
+  brand: '\x1b[38;2;255;165;0m', // Bright orange (#FFA500 - 8.0:1 ratio)
+  orange: '\x1b[38;2;255;165;0m',
+
+  // Background colors (same as standard)
+  bgRed: '\x1b[41m',
+  bgGreen: '\x1b[42m',
+  bgYellow: '\x1b[43m',
+  bgBlue: '\x1b[44m',
+
+  // Semantic aliases
+  success: '\x1b[92m',
+  error: '\x1b[91m',
+  warning: '\x1b[93m',
+  info: '\x1b[96m',
+};
+
 /**
  * ANSI color codes for terminal output.
  * Includes standard colors, 256-color palette, and brand colors.
  */
-const c = {
+const cStandard = {
   // Reset and modifiers
   reset: '\x1b[0m',
   bold: '\x1b[1m',
@@ -85,6 +187,36 @@ const c = {
   info: '\x1b[36m', // Same as cyan
 };
 
+/**
+ * Get the active color palette based on high-contrast mode.
+ * @returns {Object} Color palette object (either cStandard or hc)
+ */
+function getColors() {
+  return isHighContrast() ? hc : cStandard;
+}
+
+// For backwards compatibility, export a Proxy that delegates to the active palette
+const c = new Proxy(
+  {},
+  {
+    get(_, prop) {
+      return getColors()[prop];
+    },
+    has(_, prop) {
+      return prop in cStandard;
+    },
+    ownKeys() {
+      return Object.keys(cStandard);
+    },
+    getOwnPropertyDescriptor(_, prop) {
+      if (prop in cStandard) {
+        return { enumerable: true, configurable: true, value: getColors()[prop] };
+      }
+      return undefined;
+    },
+  }
+);
+
 /**
  * Box drawing characters for tables and borders.
  */
@@ -114,18 +246,49 @@ const box = {
 };
 
 /**
- * Status indicators with colors.
+ * Get status indicators with current color palette.
+ * Uses a Proxy to dynamically generate colored indicators.
  */
-const status = {
-  success: `${c.green}✓${c.reset}`,
-  warning: `${c.yellow}⚠️${c.reset}`,
-  error: `${c.red}✗${c.reset}`,
-  info: `${c.cyan}ℹ${c.reset}`,
-  pending: `${c.dim}○${c.reset}`,
-  inProgress: `${c.yellow}◐${c.reset}`,
-  done: `${c.green}●${c.reset}`,
-  blocked: `${c.red}◆${c.reset}`,
-};
+const status = new Proxy(
+  {},
+  {
+    get(_, prop) {
+      const colors = getColors();
+      const indicators = {
+        success: `${colors.green}✓${colors.reset}`,
+        warning: `${colors.yellow}⚠️${colors.reset}`,
+        error: `${colors.red}✗${colors.reset}`,
+        info: `${colors.cyan}ℹ${colors.reset}`,
+        pending: `${isHighContrast() ? colors.white : colors.dim}○${colors.reset}`,
+        inProgress: `${colors.yellow}◐${colors.reset}`,
+        done: `${colors.green}●${colors.reset}`,
+        blocked: `${colors.red}◆${colors.reset}`,
+      };
+      return indicators[prop];
+    },
+    has(_, prop) {
+      return [
+        'success',
+        'warning',
+        'error',
+        'info',
+        'pending',
+        'inProgress',
+        'done',
+        'blocked',
+      ].includes(prop);
+    },
+    ownKeys() {
+      return ['success', 'warning', 'error', 'info', 'pending', 'inProgress', 'done', 'blocked'];
+    },
+    getOwnPropertyDescriptor(_, prop) {
+      if (status.has(_, prop)) {
+        return { enumerable: true, configurable: true };
+      }
+      return undefined;
+    },
+  }
+);
 
 /**
  * Wrap text with color codes.
@@ -199,9 +362,22 @@ function brand(text) {
 }
 
 module.exports = {
+  // Color palettes
   c,
+  cStandard,
+  hc,
+  getColors,
+
+  // High-contrast mode control
+  isHighContrast,
+  setHighContrast,
+  resetHighContrast,
+
+  // UI elements
   box,
   status,
+
+  // Helper functions
   colorize,
   dim,
   bold,
@@ -209,5 +385,7 @@ module.exports = {
   warning,
   error,
   brand,
+
+  // Constants
   BRAND_HEX,
 };