awesome-slash 2.4.4 → 2.5.1

package/plugins/deslop-around/lib/state/workflow-state.js

@@ -1,18 +1,69 @@
 /**
- * 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: {stateDir}/tasks.json (tracks active worktree/task)
+ * - Worktree: {stateDir}/flow.json (tracks workflow progress)
+ *
+ * State directory is platform-aware:
+ * - Claude Code: .claude/
+ * - OpenCode: .opencode/
+ * - Codex CLI: .codex/
  */
 
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const { getStateDir } = require('../platform/state-dir');
+
+// File paths
+const TASKS_FILE = 'tasks.json';
+const FLOW_FILE = 'flow.json';
 
-const SCHEMA_VERSION = '2.0.0';
-const STATE_DIR = '.claude';
-const STATE_FILE = 'workflow-state.json';
+/**
+ * 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
+ */
+function validatePath(basePath) {
+  if (typeof basePath !== 'string' || basePath.length === 0) {
+    throw new Error('Path must be a non-empty string');
+  }
+  const resolved = path.resolve(basePath);
+  if (resolved.includes('\0')) {
+    throw new Error('Path contains invalid null byte');
+  }
+  return resolved;
+}
+
+/**
+ * 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');
+  }
+}
 
+/**
+ * Generate a unique workflow ID
+ * @returns {string} Workflow ID
+ */
+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',
@@ -22,614 +73,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'
 ];
 
-const DEFAULT_POLICY = {
-  taskSource: 'gh-issues',
-  priorityFilter: 'continue',
-  platform: 'detected',
-  stoppingPoint: 'merged',
-  mergeStrategy: 'squash',
-  autoFix: true,
-  maxReviewIterations: 3
-};
-
 /**
- * Generate a unique workflow ID
- * @returns {string} Workflow ID in format: workflow-YYYYMMDD-HHMMSS-random
+ * Ensure state directory exists (platform-aware)
  */
-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 ensureStateDir(basePath) {
+  const stateDir = path.join(basePath, getStateDir(basePath));
+  if (!fs.existsSync(stateDir)) {
+    fs.mkdirSync(stateDir, { recursive: true });
+  }
+  return stateDir;
 }
 
+// =============================================================================
+// TASKS.JSON - Main project directory
+// =============================================================================
+
 /**
- * Get the state file path
- * @param {string} [baseDir=process.cwd()] - Base directory
- * @returns {string} Full path to state file
+ * Get path to tasks.json with validation
  */
-function getStatePath(baseDir = process.cwd()) {
-  return path.join(baseDir, STATE_DIR, STATE_FILE);
+function getTasksPath(projectPath = process.cwd()) {
+  const validatedBase = validatePath(projectPath);
+  const tasksPath = path.join(validatedBase, getStateDir(projectPath), TASKS_FILE);
+  validatePathWithinBase(tasksPath, validatedBase);
+  return tasksPath;
 }
 
 /**
- * Ensure state directory exists
- * @param {string} [baseDir=process.cwd()] - Base directory
+ * 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 ensureStateDir(baseDir = process.cwd()) {
-  const stateDir = path.join(baseDir, STATE_DIR);
-  if (!fs.existsSync(stateDir)) {
-    fs.mkdirSync(stateDir, { recursive: true });
+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 };
   }
 }
 
 /**
- * Create a new workflow state
- * @param {string} [type='next-task'] - Workflow type
- * @param {Object} [policy={}] - Policy overrides
- * @returns {Object} New workflow state
+ * Write tasks.json to main project
  */
-function createState(type = 'next-task', policy = {}) {
-  const now = new Date().toISOString();
+function writeTasks(tasks, projectPath = process.cwd()) {
+  ensureStateDir(projectPath);
+  const tasksPath = getTasksPath(projectPath);
+  fs.writeFileSync(tasksPath, JSON.stringify(tasks, null, 2), 'utf8');
+  return true;
+}
 
-  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
-    }
+/**
+ * Set active task in main project
+ */
+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
- * @param {string} [baseDir=process.cwd()] - Base directory
- * @returns {Object|Error|null} Workflow state, Error if corrupted, or null if not found
+ * Clear active task
  */
-function readState(baseDir = process.cwd()) {
-  const statePath = getStatePath(baseDir);
-
-  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
-    }
-
-    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
- * @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);
+function hasActiveTask(projectPath = process.cwd()) {
+  const tasks = readTasks(projectPath);
+  return tasks.active != null;
+}
 
-  try {
-    // Update timestamp
-    state.workflow.lastUpdatedAt = new Date().toISOString();
+// =============================================================================
+// FLOW.JSON - Worktree directory
+// =============================================================================
 
-    const content = JSON.stringify(state, null, 2);
-    fs.writeFileSync(statePath, content, 'utf8');
-    return true;
-  } catch (error) {
-    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, getStateDir(worktreePath), 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;
 }
 
 /**
- * Deep merge two objects (with prototype pollution protection)
- * @param {Object} target - Target object
- * @param {Object} source - Source object
- * @returns {Object} Merged object
+ * Write flow.json to worktree
+ * Creates a copy to avoid mutating the original object
  */
-function deepMerge(target, source) {
-  // Handle null/undefined cases
-  if (!source || typeof source !== 'object') return target;
-  if (!target || typeof target !== 'object') return source;
-
-  const result = { ...target };
-
-  for (const key of Object.keys(source)) {
-    // Protect against prototype pollution
-    if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
-      continue;
-    }
+function writeFlow(flow, worktreePath = process.cwd()) {
+  ensureStateDir(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;
+}
 
-    const sourceVal = source[key];
-    const targetVal = result[key];
+/**
+ * Update flow.json with partial updates
+ * Handles null values correctly (null overwrites existing values)
+ * Deep merges nested objects when both exist
+ */
+function updateFlow(updates, worktreePath = process.cwd()) {
+  const flow = readFlow(worktreePath) || {};
 
-    // Handle Date objects - preserve as-is
-    if (sourceVal instanceof Date) {
-      result[key] = new Date(sourceVal.getTime());
-    }
-    // Handle null explicitly - allow overwriting with null
-    else if (sourceVal === null) {
-      result[key] = null;
+  for (const [key, value] of Object.entries(updates)) {
+    // Null explicitly overwrites
+    if (value === null) {
+      flow[key] = null;
     }
-    // Recursively merge plain objects
-    else if (sourceVal && typeof sourceVal === 'object' && !Array.isArray(sourceVal)) {
-      result[key] = deepMerge(targetVal || {}, sourceVal);
+    // 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 };
     }
-    // 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 (!PHASES.includes(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 = PHASES.indexOf(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 (!PHASES.includes(phaseName)) {
-    console.error(`Invalid phase: ${phaseName}`);
-    return null;
+function skipToPhase(phase, reason = 'manual skip', worktreePath = process.cwd()) {
+  if (!isValidPhase(phase)) {
+    throw new Error(`Invalid phase: ${phase}`);
   }
-
-  const state = readState(baseDir);
-  if (state instanceof Error) {
-    console.error(`Cannot skip to phase: ${state.message}`);
-    return null;
-  }
-  if (!state) return null;
-
-  const currentIndex = PHASES.indexOf(state.phases.current);
-  const targetIndex = PHASES.indexOf(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 }
-    });
-  }
-
-  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,
-  DEFAULT_POLICY,
-
-  // 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,
-  hasActiveWorkflow,
-  getWorkflowSummary,
 
-  // Agent management
-  updateAgentResult,
-  incrementIteration
+  // Convenience
+  getFlowSummary,
+  canResume,
+  generateWorkflowId,
+
+  // Backwards compatibility
+  readState,
+  writeState,
+  updateState,
+  createState,
+  deleteState,
+  hasActiveWorkflow,
+  getWorkflowSummary
 };