agileflow 2.94.1 → 2.95.1

package/lib/smart-json-file.js

@@ -31,6 +31,7 @@
 const fs = require('fs');
 const path = require('path');
 const { createTypedError, getErrorCodeFromError, ErrorCodes } = require('./error-codes');
+const { success, failure, failureFromError } = require('./result-schema');
 
 // Debug logging
 const DEBUG = process.env.AGILEFLOW_DEBUG === '1';
@@ -54,7 +55,7 @@ const SECURE_FILE_MODE = 0o600;
 function checkFilePermissions(mode) {
   // Skip permission checks on Windows (different permission model)
   if (process.platform === 'win32') {
-    return { ok: true };
+    return success(undefined);
   }
 
   // Extract permission bits (last 9 bits)
@@ -106,7 +107,7 @@ function checkFilePermissions(mode) {
     };
   }
 
-  return { ok: true };
+  return success(undefined);
 }
 
 /**
@@ -117,13 +118,13 @@ function checkFilePermissions(mode) {
 function setSecurePermissions(filePath) {
   // Skip on Windows
   if (process.platform === 'win32') {
-    return { ok: true };
+    return success(undefined);
   }
 
   try {
     fs.chmodSync(filePath, SECURE_FILE_MODE);
     debugLog('setSecurePermissions', { filePath, mode: SECURE_FILE_MODE.toString(8) });
-    return { ok: true };
+    return success(undefined);
   } catch (err) {
     const error = createTypedError(
       `Failed to set secure permissions on ${filePath}: ${err.message}`,
@@ -133,7 +134,7 @@ function setSecurePermissions(filePath) {
         context: { filePath, mode: SECURE_FILE_MODE },
       }
     );
-    return { ok: false, error };
+    return failureFromError(error);
   }
 }
 
@@ -221,12 +222,12 @@ class SmartJsonFile {
         if (!fs.existsSync(this.filePath)) {
           if (this.defaultValue !== undefined) {
             debugLog('read', { status: 'using default value' });
-            return { ok: true, data: this.defaultValue };
+            return success(this.defaultValue);
           }
           const error = createTypedError(`File not found: ${this.filePath}`, 'ENOENT', {
             context: { filePath: this.filePath },
           });
-          return { ok: false, error };
+          return failureFromError(error);
         }
 
         // Read file
@@ -257,7 +258,7 @@ class SmartJsonFile {
             'EPARSE',
             { cause: parseError, context: { filePath: this.filePath } }
           );
-          return { ok: false, error };
+          return failureFromError(error);
         }
 
         // Validate schema if provided
@@ -270,12 +271,12 @@ class SmartJsonFile {
               'ESCHEMA',
               { cause: schemaError, context: { filePath: this.filePath } }
             );
-            return { ok: false, error };
+            return failureFromError(error);
           }
         }
 
         debugLog('read', { status: 'success' });
-        return { ok: true, data };
+        return success(data);
       } catch (err) {
         lastError = err;
         debugLog('read', { status: 'error', error: err.message, attempt });
@@ -288,7 +289,7 @@ class SmartJsonFile {
             cause: err,
             context: { filePath: this.filePath },
           });
-          return { ok: false, error };
+          return failureFromError(error);
         }
 
         // Wait before retrying
@@ -308,7 +309,7 @@ class SmartJsonFile {
       'EUNKNOWN',
       { cause: lastError, context: { filePath: this.filePath, attempts: this.retries + 1 } }
     );
-    return { ok: false, error };
+    return failureFromError(error);
   }
 
   /**
@@ -330,7 +331,7 @@ class SmartJsonFile {
           'ESCHEMA',
           { cause: schemaError, context: { filePath: this.filePath } }
         );
-        return { ok: false, error };
+        return failureFromError(error);
       }
     }
 
@@ -368,7 +369,7 @@ class SmartJsonFile {
 
         debugLog('write', { status: 'success' });
 
-        return { ok: true };
+        return success(undefined);
       } catch (err) {
         lastError = err;
         debugLog('write', { status: 'error', error: err.message, attempt });
@@ -394,7 +395,7 @@ class SmartJsonFile {
             errorCode.code,
             { cause: err, context: { filePath: this.filePath } }
           );
-          return { ok: false, error };
+          return failureFromError(error);
         }
 
         // Wait before retrying
@@ -414,7 +415,7 @@ class SmartJsonFile {
       'EUNKNOWN',
       { cause: lastError, context: { filePath: this.filePath, attempts: this.retries + 1 } }
     );
-    return { ok: false, error };
+    return failureFromError(error);
   }
 
   /**
@@ -447,7 +448,7 @@ class SmartJsonFile {
         cause: modifyError,
         context: { filePath: this.filePath },
       });
-      return { ok: false, error };
+      return failureFromError(error);
     }
 
     // Write modified data
@@ -456,7 +457,7 @@ class SmartJsonFile {
       return writeResult;
     }
 
-    return { ok: true, data: newData };
+    return success(newData);
   }
 
   /**
@@ -474,12 +475,12 @@ class SmartJsonFile {
   async delete() {
     try {
       if (!fs.existsSync(this.filePath)) {
-        return { ok: true }; // Already doesn't exist
+        return success(undefined); // Already doesn't exist
       }
 
       fs.unlinkSync(this.filePath);
       debugLog('delete', { filePath: this.filePath, status: 'success' });
-      return { ok: true };
+      return success(undefined);
     } catch (err) {
       const errorCode = getErrorCodeFromError(err);
       const error = createTypedError(
@@ -487,7 +488,7 @@ class SmartJsonFile {
         errorCode.code,
         { cause: err, context: { filePath: this.filePath } }
       );
-      return { ok: false, error };
+      return failureFromError(error);
     }
   }
 
@@ -499,12 +500,12 @@ class SmartJsonFile {
     try {
       if (!fs.existsSync(this.filePath)) {
         if (this.defaultValue !== undefined) {
-          return { ok: true, data: this.defaultValue };
+          return success(this.defaultValue);
         }
         const error = createTypedError(`File not found: ${this.filePath}`, 'ENOENT', {
           context: { filePath: this.filePath },
         });
-        return { ok: false, error };
+        return failureFromError(error);
       }
 
       const content = fs.readFileSync(this.filePath, 'utf8');
@@ -514,7 +515,7 @@ class SmartJsonFile {
         this.schema(data);
       }
 
-      return { ok: true, data };
+      return success(data);
     } catch (err) {
       const errorCode = getErrorCodeFromError(err);
       const error = createTypedError(
@@ -522,7 +523,7 @@ class SmartJsonFile {
         errorCode.code,
         { cause: err, context: { filePath: this.filePath } }
       );
-      return { ok: false, error };
+      return failureFromError(error);
     }
   }
 
@@ -559,7 +560,7 @@ class SmartJsonFile {
         }
       }
 
-      return { ok: true };
+      return success(undefined);
     } catch (err) {
       // Clean up temp file
       try {
@@ -576,7 +577,7 @@ class SmartJsonFile {
         errorCode.code,
         { cause: err, context: { filePath: this.filePath } }
       );
-      return { ok: false, error };
+      return failureFromError(error);
     }
   }
 }
@@ -594,7 +595,7 @@ const DEFAULT_TEMP_MAX_AGE_MS = 24 * 60 * 60 * 1000;
  * @param {Object} [options={}] - Cleanup options
  * @param {number} [options.maxAgeMs=86400000] - Max age in ms (default: 24 hours)
  * @param {boolean} [options.dryRun=false] - Don't delete, just report
- * @returns {{ok: boolean, cleaned: string[], errors: string[]}}
+ * @returns {Result<{cleaned: string[], errors: string[]}>}
  */
 function cleanupTempFiles(directory, options = {}) {
   const { maxAgeMs = DEFAULT_TEMP_MAX_AGE_MS, dryRun = false } = options;
@@ -604,7 +605,7 @@ function cleanupTempFiles(directory, options = {}) {
 
   try {
     if (!fs.existsSync(directory)) {
-      return { ok: true, cleaned, errors };
+      return success({ cleaned, errors });
     }
 
     const now = Date.now();
@@ -646,10 +647,17 @@ function cleanupTempFiles(directory, options = {}) {
       }
     }
 
-    return { ok: errors.length === 0, cleaned, errors };
+    if (errors.length > 0) {
+      return failure('EUNKNOWN', 'Some temp files could not be cleaned', {
+        context: { cleaned, errors },
+      });
+    }
+    return success({ cleaned, errors });
   } catch (err) {
     errors.push(`Directory read error: ${err.message}`);
-    return { ok: false, cleaned, errors };
+    return failure('EUNKNOWN', `Directory read error: ${err.message}`, {
+      context: { cleaned, errors },
+    });
   }
 }
 
@@ -658,7 +666,7 @@ function cleanupTempFiles(directory, options = {}) {
  *
  * @param {string} filePath - Path to the JSON file
  * @param {Object} [options={}] - Cleanup options
- * @returns {{ok: boolean, cleaned: string[], errors: string[]}}
+ * @returns {Result<{cleaned: string[], errors: string[]}>}
  */
 function cleanupTempFilesFor(filePath, options = {}) {
   const directory = path.dirname(filePath);

package/lib/state-machine.js

@@ -0,0 +1,286 @@
+/**
+ * state-machine.js - Generic State Machine Base Class
+ *
+ * Provides a reusable state machine pattern for:
+ * - Story status transitions (ready → in_progress → completed)
+ * - Session thread type transitions (base → parallel → fusion)
+ *
+ * Features:
+ * - Configurable states and transitions
+ * - Transition validation with clear error messages
+ * - Audit trail support
+ * - Force mode for admin overrides
+ *
+ * Usage:
+ *   const { StateMachine } = require('./state-machine');
+ *
+ *   const storyMachine = new StateMachine({
+ *     states: ['ready', 'in_progress', 'completed'],
+ *     transitions: {
+ *       ready: ['in_progress'],
+ *       in_progress: ['completed', 'ready'],
+ *       completed: [],
+ *     },
+ *     initial: 'ready',
+ *   });
+ *
+ *   const result = storyMachine.transition('ready', 'in_progress');
+ *   // { success: true, from: 'ready', to: 'in_progress' }
+ */
+
+/**
+ * Generic State Machine
+ */
+class StateMachine {
+  /**
+   * @param {Object} config - State machine configuration
+   * @param {string[]} config.states - Valid state values
+   * @param {Object<string, string[]>} config.transitions - Map of state -> allowed next states
+   * @param {string} [config.initial] - Initial state (first in states array if not specified)
+   * @param {string} [config.name='state'] - Name for error messages (e.g., 'status', 'thread_type')
+   */
+  constructor(config) {
+    if (!config.states || !Array.isArray(config.states) || config.states.length === 0) {
+      throw new Error('StateMachine requires non-empty states array');
+    }
+    if (!config.transitions || typeof config.transitions !== 'object') {
+      throw new Error('StateMachine requires transitions object');
+    }
+
+    this.states = config.states;
+    this.transitions = config.transitions;
+    this.initial = config.initial || config.states[0];
+    this.name = config.name || 'state';
+
+    // Validate that all transition targets are valid states
+    for (const [from, targets] of Object.entries(this.transitions)) {
+      if (!this.states.includes(from)) {
+        throw new Error(`Invalid transition source state: ${from}`);
+      }
+      for (const to of targets) {
+        if (!this.states.includes(to)) {
+          throw new Error(`Invalid transition target state: ${to} (from ${from})`);
+        }
+      }
+    }
+  }
+
+  /**
+   * Check if a state is valid
+   * @param {string} state - State to check
+   * @returns {boolean}
+   */
+  isValidState(state) {
+    return this.states.includes(state);
+  }
+
+  /**
+   * Check if a transition is valid
+   * @param {string} from - Current state
+   * @param {string} to - Target state
+   * @returns {boolean}
+   */
+  isValidTransition(from, to) {
+    // Same state is always valid (no-op)
+    if (from === to) {
+      return true;
+    }
+
+    // Check if from state has defined transitions
+    const allowed = this.transitions[from];
+    if (!allowed) {
+      return false;
+    }
+
+    return allowed.includes(to);
+  }
+
+  /**
+   * Get valid transitions from a state
+   * @param {string} from - Current state
+   * @returns {string[]}
+   */
+  getValidTransitions(from) {
+    return this.transitions[from] || [];
+  }
+
+  /**
+   * Validate and perform a transition
+   * @param {string} from - Current state
+   * @param {string} to - Target state
+   * @param {Object} [options={}] - Transition options
+   * @param {boolean} [options.force=false] - Force transition even if invalid
+   * @returns {{success: boolean, from: string, to: string, error?: string, forced?: boolean}}
+   */
+  transition(from, to, options = {}) {
+    const { force = false } = options;
+
+    // Validate target state
+    if (!this.isValidState(to)) {
+      return {
+        success: false,
+        from,
+        to,
+        error: `Invalid ${this.name}: "${to}". Valid values: ${this.states.join(', ')}`,
+      };
+    }
+
+    // Validate source state
+    if (!this.isValidState(from)) {
+      return {
+        success: false,
+        from,
+        to,
+        error: `Invalid source ${this.name}: "${from}". Valid values: ${this.states.join(', ')}`,
+      };
+    }
+
+    // Same state is a no-op
+    if (from === to) {
+      return {
+        success: true,
+        from,
+        to,
+        noop: true,
+      };
+    }
+
+    // Check transition validity
+    if (!force && !this.isValidTransition(from, to)) {
+      const validTargets = this.getValidTransitions(from);
+      return {
+        success: false,
+        from,
+        to,
+        error: `Invalid transition: ${from} → ${to}. Valid transitions from "${from}": ${validTargets.join(', ') || 'none'}`,
+      };
+    }
+
+    return {
+      success: true,
+      from,
+      to,
+      forced: force && !this.isValidTransition(from, to),
+    };
+  }
+
+  /**
+   * Get the initial state
+   * @returns {string}
+   */
+  getInitialState() {
+    return this.initial;
+  }
+
+  /**
+   * Get all valid states
+   * @returns {string[]}
+   */
+  getStates() {
+    return [...this.states];
+  }
+
+  /**
+   * Get all transitions as a map
+   * @returns {Object<string, string[]>}
+   */
+  getTransitionsMap() {
+    return { ...this.transitions };
+  }
+
+  /**
+   * Generate a Mermaid state diagram
+   * @returns {string}
+   */
+  toMermaidDiagram() {
+    const lines = ['stateDiagram-v2'];
+
+    // Add initial state arrow
+    lines.push(`    [*] --> ${this.initial}`);
+
+    // Add transitions
+    for (const [from, targets] of Object.entries(this.transitions)) {
+      for (const to of targets) {
+        lines.push(`    ${from} --> ${to}`);
+      }
+      // Mark terminal states
+      if (targets.length === 0) {
+        lines.push(`    ${from} --> [*]`);
+      }
+    }
+
+    return lines.join('\n');
+  }
+}
+
+// ============================================================================
+// Pre-configured State Machines
+// ============================================================================
+
+/**
+ * Story status state machine
+ *
+ * States: ready, in_progress, in_review, blocked, completed, archived
+ *
+ * Transitions:
+ * - ready → in_progress, blocked
+ * - in_progress → in_review, blocked, ready
+ * - in_review → completed, in_progress, blocked
+ * - blocked → ready, in_progress, in_review
+ * - completed → archived, in_progress (reopened)
+ * - archived → (terminal)
+ */
+const storyStatusMachine = new StateMachine({
+  name: 'status',
+  states: ['ready', 'in_progress', 'in_review', 'blocked', 'completed', 'archived'],
+  transitions: {
+    ready: ['in_progress', 'blocked'],
+    in_progress: ['in_review', 'blocked', 'ready'],
+    in_review: ['completed', 'in_progress', 'blocked'],
+    blocked: ['ready', 'in_progress', 'in_review'],
+    completed: ['archived', 'in_progress'],
+    archived: [], // Terminal state
+  },
+  initial: 'ready',
+});
+
+/**
+ * Session thread type state machine
+ *
+ * States: base, parallel, chained, fusion, big, long
+ *
+ * Thread Type Semantics:
+ * - base: Main session in project root (default)
+ * - parallel: Independent worktree session
+ * - chained: Sequential dependency on another session
+ * - fusion: Merged work from multiple sessions
+ * - big: Large task spanning multiple sessions
+ * - long: Extended session with context preservation
+ *
+ * Transitions:
+ * - base → parallel (spawn worktree)
+ * - parallel → base (merge to main), fusion (merge multiple), chained (add dependency)
+ * - chained → parallel (remove dependency), fusion (complete chain)
+ * - fusion → base (merge to main)
+ * - big → parallel (split), fusion (consolidate)
+ * - long → base (complete), parallel (split)
+ */
+const sessionThreadMachine = new StateMachine({
+  name: 'thread_type',
+  states: ['base', 'parallel', 'chained', 'fusion', 'big', 'long'],
+  transitions: {
+    base: ['parallel', 'big', 'long'],
+    parallel: ['base', 'fusion', 'chained'],
+    chained: ['parallel', 'fusion'],
+    fusion: ['base'],
+    big: ['parallel', 'fusion'],
+    long: ['base', 'parallel'],
+  },
+  initial: 'base',
+});
+
+module.exports = {
+  StateMachine,
+  storyStatusMachine,
+  sessionThreadMachine,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agileflow",
-  "version": "2.94.1",
+  "version": "2.95.1",
   "description": "AI-driven agile development system for Claude Code, Cursor, Windsurf, and more",
   "keywords": [
     "agile",

package/scripts/agileflow-configure.js

@@ -23,7 +23,7 @@
  *   --detect                            Show current status
  *   --help                              Show help
  *
- * Features: sessionstart, precompact, ralphloop, selfimprove, archival, statusline, autoupdate, damagecontrol, askuserquestion, tmuxautospawn
+ * Features: sessionstart, precompact, ralphloop, selfimprove, archival, statusline, autoupdate, damagecontrol, askuserquestion, tmuxautospawn, shellaliases, claudemdreinforcement
  */
 
 const fs = require('fs');
@@ -121,16 +121,17 @@ ${c.cyan}Usage:${c.reset}
   node .agileflow/scripts/agileflow-configure.js [options]
 
 ${c.cyan}Profiles:${c.reset}
-  --profile=full      All features (hooks, Stop hooks, archival, statusline)
-  --profile=basic     SessionStart + PreCompact + archival (no Stop hooks)
-  --profile=minimal   SessionStart + archival only
-  --profile=none      Disable all AgileFlow features
+  --profile=full         All features (hooks, Stop hooks, archival, statusline)
+  --profile=basic        SessionStart + PreCompact + archival (no Stop hooks)
+  --profile=minimal      SessionStart + archival only
+  --profile=experimental ⚠️ All features + FULL FILE injection during compact (CONTEXT HEAVY)
+  --profile=none         Disable all AgileFlow features
 
 ${c.cyan}Feature Control:${c.reset}
   --enable=<list>     Enable features (comma-separated)
   --disable=<list>    Disable features (comma-separated)
 
-  Features: sessionstart, precompact, ralphloop, selfimprove, archival, statusline, damagecontrol, askuserquestion, tmuxautospawn
+  Features: sessionstart, precompact, ralphloop, selfimprove, archival, statusline, damagecontrol, askuserquestion, tmuxautospawn, shellaliases, claudemdreinforcement
 
 ${c.cyan}Statusline Components:${c.reset}
   --show=<list>       Show statusline components (comma-separated)