awesome-slash 2.4.4 → 2.5.0

package/lib/state/workflow-state.js

@@ -1,130 +1,64 @@
 /**
- * Workflow State Management
+ * Simplified workflow state management
  *
- * Persistent state management for next-task workflow orchestration.
- * Enables resume capability, multi-agent coordination, and progress tracking.
+ * Two files:
+ * - Main project: .claude/tasks.json (tracks active worktree/task)
+ * - Worktree: .claude/flow.json (tracks workflow progress)
  */
 
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 
-const SCHEMA_VERSION = '2.0.0';
-const STATE_DIR = '.claude';
-const STATE_FILE = 'workflow-state.json';
+// File paths
+const CLAUDE_DIR = '.claude';
+const TASKS_FILE = 'tasks.json';
+const FLOW_FILE = 'flow.json';
 
 /**
- * State cache configuration
- */
-const STATE_CACHE_TTL_MS = 200; // Cache TTL for rapid successive reads
-const _stateCache = new Map(); // Cache keyed by resolved base directory
-
-/**
- * Get cached state if valid
- * @param {string} cacheKey - Cache key (resolved base path)
- * @returns {Object|null} Cached state or null if expired/missing
- */
-function getCachedState(cacheKey) {
-  const cached = _stateCache.get(cacheKey);
-  if (cached && Date.now() < cached.expiry) {
-    return cached.state;
-  }
-  return null;
-}
-
-/**
- * Set state cache
- * @param {string} cacheKey - Cache key (resolved base path)
- * @param {Object} state - State to cache
- */
-function setCachedState(cacheKey, state) {
-  _stateCache.set(cacheKey, {
-    state,
-    expiry: Date.now() + STATE_CACHE_TTL_MS
-  });
-}
-
-/**
- * Invalidate state cache for a directory
- * @param {string} cacheKey - Cache key (resolved base path)
- */
-function invalidateStateCache(cacheKey) {
-  _stateCache.delete(cacheKey);
-}
-
-/**
- * Clear all state caches (useful for testing)
- */
-function clearAllStateCaches() {
-  _stateCache.clear();
-}
-
-/**
- * Validate and normalize base directory path to prevent path traversal
- * @param {string} baseDir - Base directory path
+ * Validate and resolve path to prevent path traversal attacks
+ * @param {string} basePath - Base directory path
  * @returns {string} Validated absolute path
- * @throws {Error} If path is invalid or potentially dangerous
+ * @throws {Error} If path is invalid
  */
-function validateBasePath(baseDir) {
-  if (typeof baseDir !== 'string' || baseDir.length === 0) {
-    throw new Error('Base directory must be a non-empty string');
+function validatePath(basePath) {
+  if (typeof basePath !== 'string' || basePath.length === 0) {
+    throw new Error('Path must be a non-empty string');
   }
-
-  // Resolve to absolute path
-  const resolvedPath = path.resolve(baseDir);
-
-  // Check for null bytes (path traversal via null byte injection)
-  if (resolvedPath.includes('\0')) {
+  const resolved = path.resolve(basePath);
+  if (resolved.includes('\0')) {
     throw new Error('Path contains invalid null byte');
   }
+  return resolved;
+}
 
-  // Ensure the path exists and is a directory
-  try {
-    const stats = fs.statSync(resolvedPath);
-    if (!stats.isDirectory()) {
-      throw new Error('Path is not a directory');
-    }
-  } catch (error) {
-    if (error.code === 'ENOENT') {
-      // Directory doesn't exist yet - that's OK, it will be created
-      // But the parent must exist and be a directory
-      const parentDir = path.dirname(resolvedPath);
-      try {
-        const parentStats = fs.statSync(parentDir);
-        if (!parentStats.isDirectory()) {
-          throw new Error('Parent path is not a directory');
-        }
-      } catch (parentError) {
-        if (parentError.code === 'ENOENT') {
-          throw new Error('Parent directory does not exist');
-        }
-        throw parentError;
-      }
-    } else if (error.message) {
-      throw error;
-    }
+/**
+ * Validate that target path is within base directory
+ * @param {string} targetPath - Target file path
+ * @param {string} basePath - Base directory
+ * @throws {Error} If path traversal detected
+ */
+function validatePathWithinBase(targetPath, basePath) {
+  const resolvedTarget = path.resolve(targetPath);
+  const resolvedBase = path.resolve(basePath);
+  if (!resolvedTarget.startsWith(resolvedBase + path.sep) && resolvedTarget !== resolvedBase) {
+    throw new Error('Path traversal detected');
   }
-
-  return resolvedPath;
 }
 
 /**
- * Validate that the final state path is within the base directory
- * @param {string} statePath - The full state file path
- * @param {string} baseDir - The validated base directory
- * @throws {Error} If path traversal is detected
+ * Generate a unique workflow ID
+ * @returns {string} Workflow ID
  */
-function validateStatePathWithinBase(statePath, baseDir) {
-  const resolvedStatePath = path.resolve(statePath);
-  const resolvedBaseDir = path.resolve(baseDir);
-
-  // Ensure state path is within base directory
-  if (!resolvedStatePath.startsWith(resolvedBaseDir + path.sep) &&
-      resolvedStatePath !== resolvedBaseDir) {
-    throw new Error('Path traversal detected: state path is outside base directory');
-  }
+function generateWorkflowId() {
+  const now = new Date();
+  const date = now.toISOString().slice(0, 10).replace(/-/g, '');
+  const time = now.toISOString().slice(11, 19).replace(/:/g, '');
+  const random = crypto.randomBytes(4).toString('hex');
+  return `workflow-${date}-${time}-${random}`;
 }
 
+// Valid phases for the workflow
 const PHASES = [
   'policy-selection',
   'task-discovery',
@@ -134,702 +68,466 @@ const PHASES = [
   'user-approval',
   'implementation',
   'review-loop',
-  'delivery-approval',
-  'ship-prep',
-  'create-pr',
-  'ci-wait',
-  'comment-fix',
-  'merge',
-  'production-ci',
-  'deploy',
-  'production-release',
+  'delivery-validation',
+  'shipping',
   'complete'
 ];
 
-// Pre-computed phase index map for O(1) lookup (vs O(n) array indexOf)
-const PHASE_INDEX = new Map(PHASES.map((phase, index) => [phase, index]));
-
 /**
- * Check if a phase name is valid (O(1) lookup)
- * @param {string} phaseName - Phase to check
- * @returns {boolean} True if valid phase
+ * Ensure .claude directory exists
  */
-function isValidPhase(phaseName) {
-  return PHASE_INDEX.has(phaseName);
-}
-
-/**
- * Get the index of a phase (O(1) lookup)
- * @param {string} phaseName - Phase name
- * @returns {number} Phase index or -1 if invalid
- */
-function getPhaseIndex(phaseName) {
-  return PHASE_INDEX.has(phaseName) ? PHASE_INDEX.get(phaseName) : -1;
+function ensureClaudeDir(basePath) {
+  const claudeDir = path.join(basePath, CLAUDE_DIR);
+  if (!fs.existsSync(claudeDir)) {
+    fs.mkdirSync(claudeDir, { recursive: true });
+  }
+  return claudeDir;
 }
 
-const DEFAULT_POLICY = {
-  taskSource: 'gh-issues',
-  priorityFilter: 'continue',
-  platform: 'detected',
-  stoppingPoint: 'merged',
-  mergeStrategy: 'squash',
-  autoFix: true,
-  maxReviewIterations: 3
-};
+// =============================================================================
+// TASKS.JSON - Main project directory
+// =============================================================================
 
 /**
- * Generate a unique workflow ID
- * @returns {string} Workflow ID in format: workflow-YYYYMMDD-HHMMSS-random
+ * Get path to tasks.json with validation
  */
-function generateWorkflowId() {
-  const now = new Date();
-  const date = now.toISOString().slice(0, 10).replace(/-/g, '');
-  const time = now.toISOString().slice(11, 19).replace(/:/g, '');
-  const random = crypto.randomBytes(4).toString('hex');
-  return `workflow-${date}-${time}-${random}`;
+function getTasksPath(projectPath = process.cwd()) {
+  const validatedBase = validatePath(projectPath);
+  const tasksPath = path.join(validatedBase, CLAUDE_DIR, TASKS_FILE);
+  validatePathWithinBase(tasksPath, validatedBase);
+  return tasksPath;
 }
 
 /**
- * Get the state file path with validation
- * @param {string} [baseDir=process.cwd()] - Base directory
- * @returns {string} Full path to state file
- * @throws {Error} If path validation fails
+ * Read tasks.json from main project
+ * Returns { active: null } if file doesn't exist or is corrupted
+ * Logs critical error on corruption to prevent silent data loss
  */
-function getStatePath(baseDir = process.cwd()) {
-  const validatedBase = validateBasePath(baseDir);
-  const statePath = path.join(validatedBase, STATE_DIR, STATE_FILE);
-
-  // Verify the state path is still within the base directory
-  validateStatePathWithinBase(statePath, validatedBase);
-
-  return statePath;
+function readTasks(projectPath = process.cwd()) {
+  const tasksPath = getTasksPath(projectPath);
+  if (!fs.existsSync(tasksPath)) {
+    return { active: null };
+  }
+  try {
+    const data = JSON.parse(fs.readFileSync(tasksPath, 'utf8'));
+    // Normalize legacy format that may not have 'active' field
+    if (!Object.prototype.hasOwnProperty.call(data, 'active')) {
+      return { active: null };
+    }
+    return data;
+  } catch (e) {
+    console.error(`[CRITICAL] Corrupted tasks.json at ${tasksPath}: ${e.message}`);
+    return { active: null };
+  }
 }
 
 /**
- * Ensure state directory exists with validation
- * @param {string} [baseDir=process.cwd()] - Base directory
- * @throws {Error} If path validation fails
+ * Write tasks.json to main project
  */
-function ensureStateDir(baseDir = process.cwd()) {
-  const validatedBase = validateBasePath(baseDir);
-  const stateDir = path.join(validatedBase, STATE_DIR);
-
-  // Verify the state dir path is still within the base directory
-  validateStatePathWithinBase(stateDir, validatedBase);
-
-  if (!fs.existsSync(stateDir)) {
-    fs.mkdirSync(stateDir, { recursive: true });
-  }
+function writeTasks(tasks, projectPath = process.cwd()) {
+  ensureClaudeDir(projectPath);
+  const tasksPath = getTasksPath(projectPath);
+  fs.writeFileSync(tasksPath, JSON.stringify(tasks, null, 2), 'utf8');
+  return true;
 }
 
 /**
- * Create a new workflow state
- * @param {string} [type='next-task'] - Workflow type
- * @param {Object} [policy={}] - Policy overrides
- * @returns {Object} New workflow state
+ * Set active task in main project
  */
-function createState(type = 'next-task', policy = {}) {
-  const now = new Date().toISOString();
-
-  return {
-    version: SCHEMA_VERSION,
-    workflow: {
-      id: generateWorkflowId(),
-      type,
-      status: 'pending',
-      startedAt: now,
-      lastUpdatedAt: now,
-      completedAt: null
-    },
-    policy: { ...DEFAULT_POLICY, ...policy },
-    task: null,
-    git: null,
-    pr: null,
-    phases: {
-      current: 'policy-selection',
-      currentIteration: 0,
-      history: []
-    },
-    agents: null,
-    checkpoints: {
-      canResume: true,
-      resumeFrom: null,
-      resumeContext: null
-    },
-    metrics: {
-      totalDuration: 0,
-      tokensUsed: 0,
-      toolCalls: 0,
-      filesModified: 0,
-      linesAdded: 0,
-      linesRemoved: 0
-    }
+function setActiveTask(task, projectPath = process.cwd()) {
+  const tasks = readTasks(projectPath);
+  tasks.active = {
+    ...task,
+    startedAt: new Date().toISOString()
   };
+  return writeTasks(tasks, projectPath);
 }
 
 /**
- * Read workflow state from file (with caching for rapid successive reads)
- * @param {string} [baseDir=process.cwd()] - Base directory
- * @param {Object} [options={}] - Options
- * @param {boolean} [options.skipCache=false] - Skip cache and read from file
- * @returns {Object|Error|null} Workflow state, Error if corrupted, or null if not found
+ * Clear active task
  */
-function readState(baseDir = process.cwd(), options = {}) {
-  const statePath = getStatePath(baseDir);
-  const cacheKey = path.resolve(baseDir);
-
-  // Check cache first (unless skipCache is true)
-  if (!options.skipCache) {
-    const cached = getCachedState(cacheKey);
-    if (cached !== null) {
-      // Return a deep copy to prevent mutations affecting cache
-      return JSON.parse(JSON.stringify(cached));
-    }
-  }
-
-  if (!fs.existsSync(statePath)) {
-    return null;
-  }
-
-  try {
-    const content = fs.readFileSync(statePath, 'utf8');
-    const state = JSON.parse(content);
-
-    // Version check
-    if (state.version !== SCHEMA_VERSION) {
-      console.warn(`State version mismatch: ${state.version} vs ${SCHEMA_VERSION}`);
-      // Future: Add migration logic here
-    }
-
-    // Cache the state
-    setCachedState(cacheKey, state);
-
-    return state;
-  } catch (error) {
-    const corrupted = new Error(`Corrupted workflow state: ${error.message}`);
-    corrupted.code = 'ERR_STATE_CORRUPTED';
-    corrupted.cause = error;
-    console.error(corrupted.message);
-    return corrupted;
-  }
+function clearActiveTask(projectPath = process.cwd()) {
+  const tasks = readTasks(projectPath);
+  tasks.active = null;
+  return writeTasks(tasks, projectPath);
 }
 
 /**
- * Write workflow state to file (invalidates cache)
- * @param {Object} state - Workflow state
- * @param {string} [baseDir=process.cwd()] - Base directory
- * @returns {boolean} Success status
+ * Check if there's an active task
+ * Uses != null to catch both null and undefined (legacy format safety)
  */
-function writeState(state, baseDir = process.cwd()) {
-  ensureStateDir(baseDir);
-  const statePath = getStatePath(baseDir);
-  const cacheKey = path.resolve(baseDir);
-
-  try {
-    // Update timestamp
-    state.workflow.lastUpdatedAt = new Date().toISOString();
-
-    const content = JSON.stringify(state, null, 2);
-    fs.writeFileSync(statePath, content, 'utf8');
+function hasActiveTask(projectPath = process.cwd()) {
+  const tasks = readTasks(projectPath);
+  return tasks.active != null;
+}
 
-    // Update cache with new state
-    setCachedState(cacheKey, state);
+// =============================================================================
+// FLOW.JSON - Worktree directory
+// =============================================================================
 
-    return true;
-  } catch (error) {
-    // Invalidate cache on write error
-    invalidateStateCache(cacheKey);
-    console.error(`Error writing state: ${error.message}`);
-    return false;
-  }
+/**
+ * Get path to flow.json with validation
+ */
+function getFlowPath(worktreePath = process.cwd()) {
+  const validatedBase = validatePath(worktreePath);
+  const flowPath = path.join(validatedBase, CLAUDE_DIR, FLOW_FILE);
+  validatePathWithinBase(flowPath, validatedBase);
+  return flowPath;
 }
 
 /**
- * Update specific fields in workflow state
- * @param {Object} updates - Fields to update (deep merge)
- * @param {string} [baseDir=process.cwd()] - Base directory
- * @returns {Object|null} Updated state or null on error
+ * Read flow.json from worktree
+ * Returns null if file doesn't exist or is corrupted
+ * Logs critical error on corruption to prevent silent data loss
  */
-function updateState(updates, baseDir = process.cwd()) {
-  let state = readState(baseDir);
-
-  if (state instanceof Error) {
-    console.error(`Cannot update state: ${state.message}`);
+function readFlow(worktreePath = process.cwd()) {
+  const flowPath = getFlowPath(worktreePath);
+  if (!fs.existsSync(flowPath)) {
     return null;
   }
-  if (!state) {
-    console.error('No existing state to update');
+  try {
+    return JSON.parse(fs.readFileSync(flowPath, 'utf8'));
+  } catch (e) {
+    console.error(`[CRITICAL] Corrupted flow.json at ${flowPath}: ${e.message}`);
     return null;
   }
-
-  // Deep merge updates
-  state = deepMerge(state, updates);
-
-  if (writeState(state, baseDir)) {
-    return state;
-  }
-
-  return null;
 }
 
 /**
- * Maximum recursion depth for deepMerge to prevent stack overflow attacks
+ * Write flow.json to worktree
+ * Creates a copy to avoid mutating the original object
  */
-const MAX_MERGE_DEPTH = 50;
+function writeFlow(flow, worktreePath = process.cwd()) {
+  ensureClaudeDir(worktreePath);
+  // Clone to avoid mutating the original object
+  const flowCopy = JSON.parse(JSON.stringify(flow));
+  flowCopy.lastUpdate = new Date().toISOString();
+  const flowPath = getFlowPath(worktreePath);
+  fs.writeFileSync(flowPath, JSON.stringify(flowCopy, null, 2), 'utf8');
+  return true;
+}
 
 /**
- * Deep merge two objects (with prototype pollution and stack overflow protection)
- * @param {Object} target - Target object
- * @param {Object} source - Source object
- * @param {number} [depth=0] - Current recursion depth (internal)
- * @returns {Object} Merged object
- * @throws {Error} If recursion depth exceeds MAX_MERGE_DEPTH
+ * Update flow.json with partial updates
+ * Handles null values correctly (null overwrites existing values)
+ * Deep merges nested objects when both exist
  */
-function deepMerge(target, source, depth = 0) {
-  // Protect against stack overflow from deeply nested objects
-  if (depth > MAX_MERGE_DEPTH) {
-    throw new Error(`Maximum merge depth (${MAX_MERGE_DEPTH}) exceeded - possible circular reference or attack`);
-  }
-
-  // Handle null/undefined cases
-  if (!source || typeof source !== 'object') return target;
-  if (!target || typeof target !== 'object') return source;
+function updateFlow(updates, worktreePath = process.cwd()) {
+  const flow = readFlow(worktreePath) || {};
 
-  const result = { ...target };
-
-  for (const key of Object.keys(source)) {
-    // Protect against prototype pollution
-    if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
-      continue;
+  for (const [key, value] of Object.entries(updates)) {
+    // Null explicitly overwrites
+    if (value === null) {
+      flow[key] = null;
     }
-
-    const sourceVal = source[key];
-    const targetVal = result[key];
-
-    // Handle Date objects - preserve as-is
-    if (sourceVal instanceof Date) {
-      result[key] = new Date(sourceVal.getTime());
+    // Deep merge if both source and target are non-null objects
+    else if (
+      value && typeof value === 'object' && !Array.isArray(value) &&
+      flow[key] && typeof flow[key] === 'object' && !Array.isArray(flow[key])
+    ) {
+      flow[key] = { ...flow[key], ...value };
     }
-    // Handle null explicitly - allow overwriting with null
-    else if (sourceVal === null) {
-      result[key] = null;
-    }
-    // Recursively merge plain objects (with depth tracking)
-    else if (sourceVal && typeof sourceVal === 'object' && !Array.isArray(sourceVal)) {
-      result[key] = deepMerge(targetVal || {}, sourceVal, depth + 1);
-    }
-    // Replace arrays and primitives
+    // Otherwise direct assignment
     else {
-      result[key] = sourceVal;
+      flow[key] = value;
     }
   }
 
-  return result;
+  return writeFlow(flow, worktreePath);
 }
 
 /**
- * Start a new phase
- * @param {string} phaseName - Phase name
- * @param {string} [baseDir=process.cwd()] - Base directory
- * @returns {Object|null} Updated state or null on error
+ * Create initial flow for a new task
+ * Also registers the task as active in the main project's tasks.json
+ * @param {Object} task - Task object with id, title, source, url
+ * @param {Object} policy - Policy object with stoppingPoint
+ * @param {string} worktreePath - Path to worktree
+ * @param {string} projectPath - Path to main project (for tasks.json registration)
  */
-function startPhase(phaseName, baseDir = process.cwd()) {
-  if (!isValidPhase(phaseName)) {
-    console.error(`Invalid phase: ${phaseName}`);
-    return null;
-  }
+function createFlow(task, policy, worktreePath = process.cwd(), projectPath = null) {
+  const flow = {
+    task: {
+      id: task.id,
+      title: task.title,
+      source: task.source,
+      url: task.url || null
+    },
+    policy: {
+      stoppingPoint: policy.stoppingPoint || 'merged'
+    },
+    phase: 'policy-selection',
+    status: 'in_progress',
+    lastUpdate: new Date().toISOString(),
+    userNotes: '',
+    git: {
+      branch: null,
+      baseBranch: 'main'
+    },
+    pr: null,
+    exploration: null,
+    plan: null,
+    // Store projectPath so completeWorkflow knows where to clear the task
+    projectPath: projectPath
+  };
 
-  const state = readState(baseDir);
-  if (state instanceof Error) {
-    console.error(`Cannot start phase: ${state.message}`);
-    return null;
-  }
-  if (!state) {
-    console.error('No workflow state exists. Create a workflow first.');
-    return null;
-  }
+  writeFlow(flow, worktreePath);
 
-  const history = state.phases?.history || [];
+  // Register task as active in main project
+  if (projectPath) {
+    setActiveTask({
+      taskId: task.id,
+      title: task.title,
+      worktree: worktreePath,
+      branch: flow.git.branch
+    }, projectPath);
+  }
 
-  history.push({
-    phase: phaseName,
-    status: 'in_progress',
-    startedAt: new Date().toISOString(),
-    completedAt: null,
-    duration: null,
-    result: null
-  });
-
-  return updateState({
-    workflow: { status: 'in_progress' },
-    phases: { current: phaseName, history },
-    checkpoints: { canResume: true, resumeFrom: phaseName, resumeContext: null }
-  }, baseDir);
+  return flow;
 }
 
 /**
- * Update the current phase entry with completion data
- * @param {Object} state - Current state
- * @param {string} status - New status (completed/failed)
- * @param {Object} result - Result data
- * @returns {Object} Updated history
+ * Delete flow.json
  */
-function finalizePhaseEntry(state, status, result) {
-  const history = state.phases.history || [];
-  const entry = history[history.length - 1];
-
-  if (entry) {
-    const now = new Date().toISOString();
-    entry.status = status;
-    entry.completedAt = now;
-    entry.duration = new Date(now).getTime() - new Date(entry.startedAt).getTime();
-    entry.result = result;
+function deleteFlow(worktreePath = process.cwd()) {
+  const flowPath = getFlowPath(worktreePath);
+  if (fs.existsSync(flowPath)) {
+    fs.unlinkSync(flowPath);
+    return true;
   }
+  return false;
+}
+
+// =============================================================================
+// PHASE MANAGEMENT
+// =============================================================================
 
-  return history;
+/**
+ * Check if phase is valid
+ */
+function isValidPhase(phase) {
+  return PHASES.includes(phase);
 }
 
 /**
- * Complete the current phase
- * @param {Object} [result={}] - Phase result data
- * @param {string} [baseDir=process.cwd()] - Base directory
- * @returns {Object|null} Updated state or null on error
+ * Set current phase
  */
-function completePhase(result = {}, baseDir = process.cwd()) {
-  const state = readState(baseDir);
-  if (state instanceof Error) {
-    console.error(`Cannot complete phase: ${state.message}`);
-    return null;
+function setPhase(phase, worktreePath = process.cwd()) {
+  if (!isValidPhase(phase)) {
+    throw new Error(`Invalid phase: ${phase}`);
   }
-  if (!state) return null;
-
-  const history = finalizePhaseEntry(state, 'completed', result);
-  const currentIndex = getPhaseIndex(state.phases.current);
-  const nextPhase = currentIndex < PHASES.length - 1 ? PHASES[currentIndex + 1] : 'complete';
+  return updateFlow({ phase, status: 'in_progress' }, worktreePath);
+}
 
-  return updateState({
-    phases: { current: nextPhase, history },
-    checkpoints: { resumeFrom: nextPhase, resumeContext: null }
-  }, baseDir);
+/**
+ * Start a phase (alias for setPhase, for backwards compatibility)
+ */
+function startPhase(phase, worktreePath = process.cwd()) {
+  return setPhase(phase, worktreePath);
 }
 
 /**
  * Fail the current phase
- * @param {string} reason - Failure reason
- * @param {Object} [context={}] - Context for resume
- * @param {string} [baseDir=process.cwd()] - Base directory
- * @returns {Object|null} Updated state or null on error
  */
-function failPhase(reason, context = {}, baseDir = process.cwd()) {
-  const state = readState(baseDir);
-  if (state instanceof Error) {
-    console.error(`Cannot fail phase: ${state.message}`);
-    return null;
-  }
-  if (!state) return null;
-
-  const history = finalizePhaseEntry(state, 'failed', { error: reason });
-
-  return updateState({
-    workflow: { status: 'failed' },
-    phases: { history },
-    checkpoints: {
-      canResume: true,
-      resumeFrom: state.phases.current,
-      resumeContext: { reason, ...context }
-    }
-  }, baseDir);
+function failPhase(reason, context = {}, worktreePath = process.cwd()) {
+  const flow = readFlow(worktreePath);
+  if (!flow) return null;
+
+  return updateFlow({
+    status: 'failed',
+    error: reason,
+    failContext: context
+  }, worktreePath);
 }
 
 /**
  * Skip to a specific phase
- * @param {string} phaseName - Phase to skip to
- * @param {string} [reason='manual skip'] - Skip reason
- * @param {string} [baseDir=process.cwd()] - Base directory
- * @returns {Object|null} Updated state or null on error
  */
-function skipToPhase(phaseName, reason = 'manual skip', baseDir = process.cwd()) {
-  if (!isValidPhase(phaseName)) {
-    console.error(`Invalid phase: ${phaseName}`);
-    return null;
-  }
-
-  const state = readState(baseDir);
-  if (state instanceof Error) {
-    console.error(`Cannot skip to phase: ${state.message}`);
-    return null;
-  }
-  if (!state) return null;
-
-  const currentIndex = getPhaseIndex(state.phases.current);
-  const targetIndex = getPhaseIndex(phaseName);
-
-  // Add skipped entries for phases we're jumping over
-  const history = [...(state.phases.history || [])];
-  const now = new Date().toISOString();
-
-  for (let i = currentIndex; i < targetIndex; i++) {
-    history.push({
-      phase: PHASES[i],
-      status: 'skipped',
-      startedAt: now,
-      completedAt: now,
-      duration: 0,
-      result: { skippedReason: reason }
-    });
+function skipToPhase(phase, reason = 'manual skip', worktreePath = process.cwd()) {
+  if (!isValidPhase(phase)) {
+    throw new Error(`Invalid phase: ${phase}`);
   }
-
-  return updateState({
-    phases: {
-      current: phaseName,
-      history
-    },
-    checkpoints: {
-      resumeFrom: phaseName
-    }
-  }, baseDir);
+  return updateFlow({
+    phase,
+    status: 'in_progress',
+    skipReason: reason
+  }, worktreePath);
 }
 
 /**
- * Complete the entire workflow
- * @param {Object} [result={}] - Final result data
- * @param {string} [baseDir=process.cwd()] - Base directory
- * @returns {Object|null} Updated state or null on error
+ * Complete current phase and move to next
+ * Uses updateFlow pattern to avoid direct mutation issues
  */
-function completeWorkflow(result = {}, baseDir = process.cwd()) {
-  const state = readState(baseDir);
-  if (state instanceof Error) {
-    console.error(`Cannot complete workflow: ${state.message}`);
-    return null;
-  }
-  if (!state) return null;
+function completePhase(result = null, worktreePath = process.cwd()) {
+  const flow = readFlow(worktreePath);
+  if (!flow) return null;
 
-  const now = new Date().toISOString();
-  const startTime = new Date(state.workflow.startedAt).getTime();
-  const endTime = new Date(now).getTime();
+  const currentIndex = PHASES.indexOf(flow.phase);
+  const nextPhase = PHASES[currentIndex + 1] || 'complete';
 
-  return updateState({
-    workflow: {
-      status: 'completed',
-      completedAt: now
-    },
-    phases: {
-      current: 'complete'
-    },
-    checkpoints: {
-      canResume: false,
-      resumeFrom: null
-    },
-    metrics: {
-      totalDuration: endTime - startTime,
-      ...result.metrics
+  // Build updates object
+  const updates = {
+    phase: nextPhase,
+    status: nextPhase === 'complete' ? 'completed' : 'in_progress'
+  };
+
+  // Store result in appropriate field
+  if (result) {
+    const resultField = getResultField(flow.phase);
+    if (resultField) {
+      updates[resultField] = result;
     }
-  }, baseDir);
+  }
+
+  updateFlow(updates, worktreePath);
+  return readFlow(worktreePath);
 }
 
 /**
- * Abort the workflow
- * @param {string} [reason='user aborted'] - Abort reason
- * @param {string} [baseDir=process.cwd()] - Base directory
- * @returns {Object|null} Updated state or null on error
+ * Map phase to result field
  */
-function abortWorkflow(reason = 'user aborted', baseDir = process.cwd()) {
-  return updateState({
-    workflow: {
-      status: 'aborted',
-      completedAt: new Date().toISOString()
-    },
-    checkpoints: {
-      canResume: false,
-      resumeFrom: null,
-      resumeContext: { abortReason: reason }
-    }
-  }, baseDir);
+function getResultField(phase) {
+  const mapping = {
+    'exploration': 'exploration',
+    'planning': 'plan',
+    'review-loop': 'reviewResult'
+  };
+  return mapping[phase] || null;
 }
 
 /**
- * Delete workflow state (cleanup)
- * @param {string} [baseDir=process.cwd()] - Base directory
- * @returns {boolean} Success status
+ * Mark workflow as failed
  */
-function deleteState(baseDir = process.cwd()) {
-  const statePath = getStatePath(baseDir);
-
-  try {
-    if (fs.existsSync(statePath)) {
-      fs.unlinkSync(statePath);
-    }
-    return true;
-  } catch (error) {
-    console.error(`Error deleting state: ${error.message}`);
-    return false;
-  }
+function failWorkflow(error, worktreePath = process.cwd()) {
+  return updateFlow({
+    status: 'failed',
+    error: error?.message || String(error)
+  }, worktreePath);
 }
 
 /**
- * Check if a workflow is in progress
- * @param {string} [baseDir=process.cwd()] - Base directory
- * @returns {boolean} True if workflow is active
+ * Mark workflow as complete
+ * Automatically clears the active task from tasks.json using stored projectPath
+ * @param {string} worktreePath - Path to worktree
  */
-function hasActiveWorkflow(baseDir = process.cwd()) {
-  const state = readState(baseDir);
-  if (state instanceof Error) return false;
-  if (!state) return false;
+function completeWorkflow(worktreePath = process.cwd()) {
+  const flow = readFlow(worktreePath);
+
+  // Clear active task from main project if projectPath is stored
+  if (flow && flow.projectPath) {
+    clearActiveTask(flow.projectPath);
+  }
 
-  return ['pending', 'in_progress', 'paused'].includes(state.workflow.status);
+  return updateFlow({
+    phase: 'complete',
+    status: 'completed',
+    completedAt: new Date().toISOString()
+  }, worktreePath);
 }
 
 /**
- * Get workflow summary for display
- * @param {string} [baseDir=process.cwd()] - Base directory
- * @returns {Object|null} Summary object or null
+ * Abort workflow
+ * Also clears the active task from tasks.json using stored projectPath
  */
-function getWorkflowSummary(baseDir = process.cwd()) {
-  const state = readState(baseDir);
-  if (state instanceof Error) {
-    return { error: state.message, code: state.code };
-  }
-  if (!state) return null;
+function abortWorkflow(reason, worktreePath = process.cwd()) {
+  const flow = readFlow(worktreePath);
 
-  const completedPhases = state.phases.history?.filter(p => p.status === 'completed').length || 0;
-  const totalPhases = PHASES.length - 1; // Exclude 'complete'
+  // Clear active task from main project if projectPath is stored
+  if (flow && flow.projectPath) {
+    clearActiveTask(flow.projectPath);
+  }
 
-  return {
-    id: state.workflow.id,
-    type: state.workflow.type,
-    status: state.workflow.status,
-    currentPhase: state.phases.current,
-    progress: `${completedPhases}/${totalPhases}`,
-    progressPercent: Math.round((completedPhases / totalPhases) * 100),
-    task: state.task ? {
-      id: state.task.id,
-      title: state.task.title,
-      source: state.task.source
-    } : null,
-    pr: state.pr ? {
-      number: state.pr.number,
-      url: state.pr.url,
-      ciStatus: state.pr.ciStatus
-    } : null,
-    canResume: state.checkpoints.canResume,
-    resumeFrom: state.checkpoints.resumeFrom,
-    startedAt: state.workflow.startedAt,
-    duration: state.metrics?.totalDuration || 0
-  };
+  return updateFlow({
+    status: 'aborted',
+    abortReason: reason,
+    abortedAt: new Date().toISOString()
+  }, worktreePath);
 }
 
+// =============================================================================
+// CONVENIENCE FUNCTIONS
+// =============================================================================
+
 /**
- * Update agent results
- * @param {string} agentName - Agent identifier
- * @param {Object} result - Agent result
- * @param {string} [baseDir=process.cwd()] - Base directory
- * @returns {Object|null} Updated state or null on error
+ * Get workflow summary for display
  */
-function updateAgentResult(agentName, result, baseDir = process.cwd()) {
-  const state = readState(baseDir);
-  if (state instanceof Error) {
-    console.error(`Cannot update agent result: ${state.message}`);
-    return null;
-  }
-  if (!state) return null;
+function getFlowSummary(worktreePath = process.cwd()) {
+  const flow = readFlow(worktreePath);
+  if (!flow) return null;
 
-  const agents = state.agents || {
-    lastRun: {},
-    totalIterations: 0,
-    totalIssuesFound: 0,
-    totalIssuesFixed: 0
+  return {
+    task: flow.task?.title || 'Unknown',
+    taskId: flow.task?.id,
+    phase: flow.phase,
+    status: flow.status,
+    lastUpdate: flow.lastUpdate,
+    pr: flow.pr?.number ? `#${flow.pr.number}` : null
   };
-
-  agents.lastRun[agentName] = result;
-  agents.totalIssuesFound += result.issues || 0;
-
-  return updateState({ agents }, baseDir);
 }
 
 /**
- * Increment review iteration
- * @param {Object} [result={}] - Iteration result
- * @param {string} [baseDir=process.cwd()] - Base directory
- * @returns {Object|null} Updated state or null on error
+ * Check if workflow can be resumed
  */
-function incrementIteration(result = {}, baseDir = process.cwd()) {
-  const state = readState(baseDir);
-  if (state instanceof Error) {
-    console.error(`Cannot increment iteration: ${state.message}`);
-    return null;
-  }
-  if (!state) return null;
-
-  const agents = state.agents || {
-    lastRun: {},
-    totalIterations: 0,
-    totalIssuesFound: 0,
-    totalIssuesFixed: 0
-  };
+function canResume(worktreePath = process.cwd()) {
+  const flow = readFlow(worktreePath);
+  if (!flow) return false;
+  return flow.status === 'in_progress' && flow.phase !== 'complete';
+}
 
-  agents.totalIterations += 1;
-  agents.totalIssuesFixed += result.fixed || 0;
+// =============================================================================
+// BACKWARDS COMPATIBILITY ALIASES
+// =============================================================================
 
-  return updateState({
-    phases: {
-      currentIteration: state.phases.currentIteration + 1
-    },
-    agents
-  }, baseDir);
-}
+// These maintain compatibility with existing agent code
+const readState = readFlow;
+const writeState = writeFlow;
+const updateState = updateFlow;
+const createState = (type, policy) => createFlow({ id: 'manual', title: 'Manual task', source: 'manual' }, policy);
+const deleteState = deleteFlow;
+const hasActiveWorkflow = hasActiveTask;
+const getWorkflowSummary = getFlowSummary;
 
-// Export all functions
 module.exports = {
   // Constants
-  SCHEMA_VERSION,
   PHASES,
-  PHASE_INDEX,
-  DEFAULT_POLICY,
-  MAX_MERGE_DEPTH,
-
-  // Phase helpers (O(1) lookup)
-  isValidPhase,
-  getPhaseIndex,
 
-  // Core functions
-  generateWorkflowId,
-  getStatePath,
-  ensureStateDir,
-
-  // CRUD operations
-  createState,
-  readState,
-  writeState,
-  updateState,
-  deleteState,
+  // Tasks (main project)
+  getTasksPath,
+  readTasks,
+  writeTasks,
+  setActiveTask,
+  clearActiveTask,
+  hasActiveTask,
+
+  // Flow (worktree)
+  getFlowPath,
+  readFlow,
+  writeFlow,
+  updateFlow,
+  createFlow,
+  deleteFlow,
 
   // Phase management
+  isValidPhase,
+  setPhase,
   startPhase,
   completePhase,
   failPhase,
   skipToPhase,
-
-  // Workflow lifecycle
+  failWorkflow,
   completeWorkflow,
   abortWorkflow,
+
+  // Convenience
+  getFlowSummary,
+  canResume,
+  generateWorkflowId,
+
+  // Backwards compatibility
+  readState,
+  writeState,
+  updateState,
+  createState,
+  deleteState,
   hasActiveWorkflow,
-  getWorkflowSummary,
-
-  // Agent management
-  updateAgentResult,
-  incrementIteration,
-
-  // Cache management
-  clearAllStateCaches,
-
-  // Internal functions for testing
-  _internal: {
-    validateBasePath,
-    validateStatePathWithinBase,
-    deepMerge,
-    getCachedState,
-    setCachedState,
-    invalidateStateCache,
-    STATE_CACHE_TTL_MS
-  }
+  getWorkflowSummary
 };