agileflow 2.94.1 → 2.95.0

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.0",
   "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)

package/scripts/archive-completed-stories.sh

@@ -105,13 +105,87 @@ echo -e "${BLUE}Cutoff date: $CUTOFF_DATE${NC}"
 
 # Archive using Node.js (more reliable for JSON manipulation)
 if command -v node &> /dev/null; then
-  STATUS_FILE="$STATUS_FILE" ARCHIVE_DIR="$ARCHIVE_DIR" CUTOFF_DATE="$CUTOFF_DATE" node <<'EOF'
+  STATUS_FILE="$STATUS_FILE" ARCHIVE_DIR="$ARCHIVE_DIR" CUTOFF_DATE="$CUTOFF_DATE" PROJECT_ROOT="$PROJECT_ROOT" node <<'EOF'
 const fs = require('fs');
 const path = require('path');
 
 const statusFile = process.env.STATUS_FILE;
 const archiveDir = process.env.ARCHIVE_DIR;
 const cutoffDate = process.env.CUTOFF_DATE;
+const projectRoot = process.env.PROJECT_ROOT;
+
+// =============================================================================
+// Security: Inline validatePath equivalent (US-0188)
+// =============================================================================
+
+/**
+ * Validate a path is safe and within the base directory.
+ * Rejects direct symlinks within the path but allows symlinked parent directories
+ * (needed for git worktrees where docs/ is often symlinked).
+ * @param {string} inputPath - Path to validate
+ * @param {string} baseDir - Allowed base directory
+ * @returns {{ ok: boolean, resolvedPath?: string, realPath?: string, error?: string }}
+ */
+function validatePath(inputPath, baseDir) {
+  if (!inputPath || typeof inputPath !== 'string') {
+    return { ok: false, error: 'Path is required and must be a string' };
+  }
+  if (!baseDir || typeof baseDir !== 'string') {
+    return { ok: false, error: 'Base directory is required' };
+  }
+
+  // Resolve to absolute path
+  const resolvedPath = path.resolve(baseDir, inputPath);
+  const resolvedBase = path.resolve(baseDir);
+
+  // Check path stays within base directory (path traversal prevention)
+  if (!resolvedPath.startsWith(resolvedBase + path.sep) && resolvedPath !== resolvedBase) {
+    return { ok: false, error: `Path traversal detected: ${inputPath} escapes ${baseDir}` };
+  }
+
+  // Check if the final target path itself is a symlink (allowSymlinks: false for target)
+  // Note: We allow parent directories to be symlinks (needed for git worktrees)
+  try {
+    const stats = fs.lstatSync(resolvedPath);
+    if (stats.isSymbolicLink()) {
+      // The actual file/directory we're writing to is a symlink - reject
+      return { ok: false, error: `Target path is a symlink: ${resolvedPath}` };
+    }
+  } catch (e) {
+    // Path doesn't exist yet, that's OK for new files
+    if (e.code !== 'ENOENT') {
+      return { ok: false, error: `Cannot stat path: ${e.message}` };
+    }
+  }
+
+  // Use fs.realpathSync() to get the actual path after symlink resolution
+  let realPath = resolvedPath;
+  try {
+    realPath = fs.realpathSync(resolvedPath);
+    // We don't restrict realPath to baseDir because parent directories may be
+    // symlinked (e.g., git worktrees). The key protection is:
+    // 1. path.resolve() prevents ../../ traversal in the input
+    // 2. lstatSync() above prevents the target itself from being a symlink
+  } catch (e) {
+    // Path doesn't exist yet, use resolved path
+    if (e.code !== 'ENOENT') {
+      return { ok: false, error: `Cannot resolve real path: ${e.message}` };
+    }
+    realPath = resolvedPath;
+  }
+
+  return { ok: true, resolvedPath, realPath };
+}
+
+// =============================================================================
+// Validate archive directory (US-0188)
+// =============================================================================
+
+const archiveDirValidation = validatePath(archiveDir, projectRoot);
+if (!archiveDirValidation.ok) {
+  console.error(`\x1b[31mSecurity: ${archiveDirValidation.error}. Aborting.\x1b[0m`);
+  process.exit(1);
+}
 
 // Read status.json
 const status = JSON.parse(fs.readFileSync(statusFile, 'utf8'));
@@ -146,7 +220,7 @@ for (const [storyId, story] of Object.entries(toArchive)) {
   const date = new Date(story.completed_at);
   const monthKey = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}`;
 
-  // Security: Validate monthKey matches expected format (YYYY-MM) to prevent path traversal
+  // Security: Validate monthKey matches expected format (YYYY-MM) to prevent path traversal (US-0188 AC)
   if (!/^\d{4}-\d{2}$/.test(monthKey)) {
     console.error(`\x1b[31mSkipping story ${storyId}: invalid date format\x1b[0m`);
     continue;
@@ -165,27 +239,28 @@ for (const [storyId, story] of Object.entries(toArchive)) {
 
 // Write archive files
 for (const [monthKey, archiveData] of Object.entries(byMonth)) {
-  const archiveFile = path.join(archiveDir, `${monthKey}.json`);
+  const archiveFile = `${monthKey}.json`;
 
-  // Security: Verify resolved path stays within archive directory
-  const resolvedPath = path.resolve(archiveFile);
-  const resolvedArchiveDir = path.resolve(archiveDir);
-  if (!resolvedPath.startsWith(resolvedArchiveDir + path.sep) && resolvedPath !== resolvedArchiveDir) {
-    console.error(`\x1b[31mSecurity: Archive path ${archiveFile} escapes archive directory. Skipping.\x1b[0m`);
+  // Security: Use validatePath() with allowSymlinks: false (US-0188 AC)
+  const validation = validatePath(archiveFile, archiveDir);
+  if (!validation.ok) {
+    console.error(`\x1b[31mSecurity: ${validation.error}. Skipping ${monthKey}.\x1b[0m`);
     continue;
   }
 
+  const finalPath = validation.resolvedPath;
+
   // Merge with existing archive if it exists
-  if (fs.existsSync(archiveFile)) {
+  if (fs.existsSync(finalPath)) {
     try {
-      const existing = JSON.parse(fs.readFileSync(archiveFile, 'utf8'));
+      const existing = JSON.parse(fs.readFileSync(finalPath, 'utf8'));
       archiveData.stories = { ...existing.stories, ...archiveData.stories };
     } catch (e) {
       console.error(`\x1b[31mWarning: Could not parse existing ${monthKey}.json, will overwrite\x1b[0m`);
     }
   }
 
-  fs.writeFileSync(archiveFile, JSON.stringify(archiveData, null, 2));
+  fs.writeFileSync(finalPath, JSON.stringify(archiveData, null, 2));
   const count = Object.keys(archiveData.stories).length;
   console.log(`\x1b[32m✓ Archived ${count} stories to ${monthKey}.json\x1b[0m`);
 }

package/scripts/babysit-context-restore.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * babysit-context-restore.js - UserPromptSubmit hook
+ *
+ * Backup mechanism to restore babysit context after plan mode clears context.
+ * When user selects "Clear context and bypass permissions" after ExitPlanMode,
+ * this hook fires on the next user prompt and reminds Claude of babysit rules.
+ *
+ * The primary mechanism is embedding rules in the plan file (Rule #6).
+ * This hook is a backup for edge cases where plan file approach might miss.
+ *
+ * Usage: Called automatically as UserPromptSubmit hook
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Find session-state.json - try multiple locations
+function findSessionState() {
+  const locations = [
+    'docs/09-agents/session-state.json',
+    path.join(process.env.CLAUDE_PROJECT_DIR || '.', 'docs/09-agents/session-state.json'),
+  ];
+
+  for (const loc of locations) {
+    if (fs.existsSync(loc)) {
+      return loc;
+    }
+  }
+  return null;
+}
+
+function main() {
+  const sessionStatePath = findSessionState();
+  if (!sessionStatePath) return;
+
+  try {
+    const state = JSON.parse(fs.readFileSync(sessionStatePath, 'utf8'));
+
+    // Check if restoration is pending
+    if (!state.babysit_pending_restore) return;
+
+    // Output restoration context
+    console.log('');
+    console.log('\x1b[36m╔══════════════════════════════════════════════════════════════╗\x1b[0m');
+    console.log(
+      '\x1b[36m║\x1b[0m  \x1b[1m\x1b[33m/babysit CONTEXT RESTORED\x1b[0m                                   \x1b[36m║\x1b[0m'
+    );
+    console.log('\x1b[36m╠══════════════════════════════════════════════════════════════╣\x1b[0m');
+    console.log(
+      '\x1b[36m║\x1b[0m  /agileflow:babysit was active before context clear.         \x1b[36m║\x1b[0m'
+    );
+    console.log(
+      '\x1b[36m║\x1b[0m  These rules are MANDATORY:                                  \x1b[36m║\x1b[0m'
+    );
+    console.log(
+      '\x1b[36m║\x1b[0m                                                              \x1b[36m║\x1b[0m'
+    );
+    console.log(
+      '\x1b[36m║\x1b[0m  1. ALWAYS end responses with AskUserQuestion tool           \x1b[36m║\x1b[0m'
+    );
+    console.log(
+      '\x1b[36m║\x1b[0m  2. Use EnterPlanMode before non-trivial tasks               \x1b[36m║\x1b[0m'
+    );
+    console.log(
+      '\x1b[36m║\x1b[0m  3. Delegate complex work to domain experts                  \x1b[36m║\x1b[0m'
+    );
+    console.log(
+      '\x1b[36m║\x1b[0m  4. Track progress with TodoWrite for 3+ step tasks          \x1b[36m║\x1b[0m'
+    );
+    console.log(
+      '\x1b[36m║\x1b[0m                                                              \x1b[36m║\x1b[0m'
+    );
+    console.log(
+      '\x1b[36m║\x1b[0m  For full context: /agileflow:babysit                        \x1b[36m║\x1b[0m'
+    );
+    console.log('\x1b[36m╚══════════════════════════════════════════════════════════════╝\x1b[0m');
+    console.log('');
+
+    // Clear the flag (one-time restoration)
+    state.babysit_pending_restore = false;
+    state.babysit_restored_at = new Date().toISOString();
+    fs.writeFileSync(sessionStatePath, JSON.stringify(state, null, 2) + '\n');
+  } catch (e) {
+    // Silently fail - don't break user's workflow
+  }
+}
+
+main();