@polymorphism-tech/morph-spec 7.2.0 → 7.4.0

package/src/core/state/state-manager.js

@@ -1,934 +1,910 @@
-/**
- * MORPH-SPEC State Manager Library
- *
- * Manages state.json for tracking features, progress, agents, and checkpoints.
- * Used both by CLI commands and internal automation.
- */
-
-import { readFileSync, writeFileSync, renameSync, unlinkSync, existsSync, mkdirSync, rmdirSync, statSync } from 'fs';
-import { join, dirname } from 'path';
-import { detectWorkflow } from '../workflows/workflow-detector.js';
-import { getAllOutputPaths, getOutputPath } from '../paths/output-schema.js';
-
-const STATE_FILE_NAME = '.morph/state.json';
-
-// ============================================================================
-// Core Functions
-// ============================================================================
-
-/**
- * Get the state file path (looks in current working directory)
- */
-export function getStatePath() {
-  return join(process.cwd(), STATE_FILE_NAME);
-}
-/**
- * Derive current phase from filesystem — checks for phase folders in descending order.
- * Returns the phase corresponding to the highest-numbered folder present.
- *
- * @param {string} featurePath - Absolute path to .morph/features/{feature}/
- * @returns {string} Phase name: 'review' | 'implement' | 'plan' | 'uiux' | 'proposal'
- */
-export function derivePhase(featurePath) {
-  const phaseMap = [
-    ['4-review', 'review'],
-    ['3-implement', 'implement'],
-    ['2-plan', 'plan'],
-    ['1-design', 'uiux'],
-    ['0-proposal', 'proposal'],
-  ];
-  for (const [folder, phase] of phaseMap) {
-    if (existsSync(join(featurePath, folder))) return phase;
-  }
-  return 'proposal';
-}
-
-/**
- * Derive output existence from filesystem — checks if each output file exists at its expected path.
- * Returns an object matching the old outputs shape for backwards-compatible display.
- *
- * @param {string} featureName - Feature name
- * @param {string} [baseDir] - Project base dir (defaults to cwd)
- * @returns {Object} Map of outputType -> { created: boolean, path: string }
- */
-export function deriveOutputs(featureName, baseDir = process.cwd()) {
-  const outputPaths = getAllOutputPaths(featureName);
-  const result = {};
-  for (const [type, { path: relPath }] of Object.entries(outputPaths)) {
-    const absPath = join(baseDir, relPath);
-    result[type] = { created: existsSync(absPath), path: relPath };
-  }
-  return result;
-}
-
-/**
- * Check if state file exists
- */
-export function stateExists() {
-  return existsSync(getStatePath());
-}
-
-/**
- * Load state from disk
- * @param {boolean} throwOnError - If false, returns null instead of throwing
- * @returns {Object|null} State object or null
- */
-export function loadState(throwOnError = true) {
-  const statePath = getStatePath();
-
-  if (!existsSync(statePath)) {
-    if (throwOnError) {
-      throw new Error(`State file not found: ${statePath}\nRun 'morph-spec init' to initialize MORPH in this project.`);
-    }
-    return null;
-  }
-
-  try {
-    const content = readFileSync(statePath, 'utf8');
-    const state = JSON.parse(content);
-
-    // Migrate v3.0.0 → v4.0.0 (new directory layout)
-    if (state.version === '3.0.0') {
-      state.version = '4.0.0';
-      for (const [name, feature] of Object.entries(state.features || {})) {
-        if (!feature.outputs) continue;
-        const outputPathMap = getAllOutputPaths(name);
-        for (const [key, { path: newPath }] of Object.entries(outputPathMap)) {
-          if (feature.outputs[key]) {
-            feature.outputs[key].path = newPath;
-          }
-        }
-      }
-      writeFileSync(statePath, JSON.stringify(state, null, 2), 'utf8');
-    }
-
-    // Migrate v4.x -> v5.0.0: remove outputs and phase (now derived from filesystem)
-    if (state.version && state.version.startsWith('4.')) {
-      state.version = '5.0.0';
-      for (const feature of Object.values(state.features || {})) {
-        delete feature.outputs;
-        delete feature.phase;
-      }
-      writeFileSync(statePath, JSON.stringify(state, null, 2), 'utf8');
-    }
-
-    return state;
-  } catch (err) {
-    if (throwOnError) {
-      throw new Error(`Failed to parse state.json: ${err.message}`);
-    }
-    return null;
-  }
-}
-
-/**
- * Save state to disk
- * @param {Object} state - State object to save
- */
-export function saveState(state) {
-  state.metadata = state.metadata || {};
-  state.metadata.lastUpdated = new Date().toISOString();
-
-  const statePath = getStatePath();
-  const stateDir = dirname(statePath);
-
-  // Ensure .morph directory exists
-  if (!existsSync(stateDir)) {
-    mkdirSync(stateDir, { recursive: true });
-  }
-
-  // Atomic write: write to a per-process temp file then rename.
-  // Per-process name prevents two concurrent CLI invocations (e.g. `task done && task start`)
-  // from clobbering each other's temp file on Windows.
-  const tmpPath = `${statePath}.tmp.${process.pid}`;
-  writeFileSync(tmpPath, JSON.stringify(state, null, 2), 'utf8');
-
-  // Retry rename on EPERM — Windows holds a brief exclusive lock on the target
-  // when another process is reading it; a short backoff resolves the contention.
-  const MAX_RETRIES = 5;
-  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    try {
-      renameSync(tmpPath, statePath);
-      return;
-    } catch (err) {
-      if (err.code === 'EPERM' && attempt < MAX_RETRIES) {
-        // Synchronous sleep: CPU-friendly, works on Node.js main thread (v9.4+)
-        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50 * (attempt + 1));
-      } else {
-        try { unlinkSync(tmpPath); } catch { /* ignore cleanup errors */ }
-        throw err;
-      }
-    }
-  }
-}
-
-// ============================================================================
-// File Locking (BUG-002)
-// ============================================================================
-
-const LOCK_DIR_NAME = '.morph/state.json.lock';
-const LOCK_MAX_RETRIES = 5;
-const LOCK_BASE_MS = 100;
-const LOCK_STALE_MS = 30_000;
-
-/**
- * Wrap a read-modify-write cycle on state.json with a mkdir-based mutex.
- * @param {Function} fn - Async function to execute while holding the lock
- * @returns {Promise<*>} Return value of fn
- */
-export async function withStateLock(fn) {
-  const lockPath = join(process.cwd(), LOCK_DIR_NAME);
-
-  for (let attempt = 0; attempt <= LOCK_MAX_RETRIES; attempt++) {
-    try {
-      mkdirSync(lockPath);
-      break;
-    } catch (err) {
-      if (err.code !== 'EEXIST') throw err;
-      try {
-        const lockStat = statSync(lockPath);
-        if (Date.now() - lockStat.mtimeMs > LOCK_STALE_MS) {
-          try { rmdirSync(lockPath); } catch { }
-          continue;
-        }
-      } catch { }
-      if (attempt === LOCK_MAX_RETRIES) {
-        throw new Error('Could not acquire state lock after retries');
-      }
-      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_BASE_MS * (2 ** attempt));
-    }
-  }
-
-  try {
-    return await fn();
-  } finally {
-    try { rmdirSync(lockPath); } catch { }
-  }
-}
-
-/**
- * Initialize new state file
- * @param {Object} options - Options
- * @param {boolean} options.force - Overwrite existing file
- * @param {string} options.projectName - Project name
- * @param {string} options.projectType - Project type (e.g., 'dotnet-nextjs')
- * @returns {Object} Initial state
- */
-export function initState(options = {}) {
-  const { force = false, projectName = '{PROJECT_NAME}', projectType = 'dotnet-nextjs' } = options;
-
-  if (stateExists() && !force) {
-    throw new Error('State file already exists. Use force=true to overwrite.');
-  }
-
-  const initialState = {
-    version: "5.0.0",
-    project: {
-      name: projectName,
-      type: projectType,
-      createdAt: new Date().toISOString(),
-      updatedAt: new Date().toISOString()
-    },
-    features: {},
-    threads: {},
-    metadata: {
-      totalFeatures: 0,
-      completedFeatures: 0,
-      totalTimeSpent: 0,
-      lastUpdated: new Date().toISOString()
-    }
-  };
-
-  saveState(initialState);
-  return initialState;
-}
-
-// ============================================================================
-// Feature Operations
-// ============================================================================
-
-/**
- * Get feature from state
- * @param {string} featureName - Feature name
- * @returns {Object|null} Feature object or null
- */
-export function getFeature(featureName) {
-  const state = loadState();
-  return state.features[featureName] || null;
-}
-
-/**
- * Create or get feature with default structure
- * @param {string} featureName - Feature name
- * @param {Object} options - Options
- * @param {string} options.userRequest - User's feature request for workflow detection
- * @param {string} options.workflow - Manual workflow override
- * @param {string} options.projectPath - Project path
- * @returns {Promise<Object>} Feature object
- */
-async function ensureFeature(featureName, options = {}) {
-  const state = loadState();
-
-  if (!state.features[featureName]) {
-    // Detect workflow if userRequest provided
-    let workflowId = 'auto';
-    let workflowDetection = {
-      auto: false,
-      confidence: 0,
-      userOverride: false
-    };
-
-    if (options.workflow) {
-      // Manual override
-      workflowId = options.workflow;
-      workflowDetection.userOverride = true;
-    } else if (options.userRequest) {
-      // Auto-detect
-      try {
-        const detection = await detectWorkflow({
-          userRequest: options.userRequest,
-          projectPath: options.projectPath || '.',
-          featureName
-        });
-        workflowId = detection.workflowId;
-        workflowDetection.auto = true;
-        workflowDetection.confidence = detection.confidence;
-        workflowDetection.matchedKeywords = detection.matchedKeywords;
-        workflowDetection.estimatedComplexity = detection.estimatedComplexity;
-        workflowDetection.reasoning = detection.reasoning;
-        workflowDetection.warnings = detection.warnings || [];
-      } catch (err) {
-        // If detection fails, fall back to auto
-        console.warn('Workflow detection failed:', err.message);
-      }
-    }
-
-    state.features[featureName] = {
-      status: "draft",
-      workflow: workflowId, // auto | standard | nodejs-cli
-      workflowDetection,
-      createdAt: new Date().toISOString(),
-      updatedAt: new Date().toISOString(),
-      activeAgents: [],
-      approvalGates: {
-        proposal: { approved: false, timestamp: null, approvedBy: null },
-        uiux: { approved: false, timestamp: null, approvedBy: null },
-        plan: { approved: false, timestamp: null, approvedBy: null },
-        review: { approved: false, timestamp: null, approvedBy: null }
-      },
-      tasks: {
-        total: 0,
-        completed: 0,
-        inProgress: 0,
-        pending: 0
-      },
-      checkpoints: [],
-      dispatchLog: [],
-      trustConfig: {},
-      contextBundles: [],
-      fileChanges: []
-    };
-
-    state.metadata.totalFeatures++;
-    saveState(state);
-  }
-
-  return state.features[featureName];
-}
-
-/**
- * Update feature property (supports nested keys like "tasks.completed")
- * @param {string} featureName - Feature name
- * @param {string} key - Property key (supports dot notation)
- * @param {any} value - Value to set
- */
-export async function updateFeature(featureName, key, value) {
-  await ensureFeature(featureName);
-  const state = loadState(); // Load AFTER ensuring feature exists
-
-  const keys = key.split('.');
-  let target = state.features[featureName];
-
-  for (let i = 0; i < keys.length - 1; i++) {
-    if (!target[keys[i]]) {
-      target[keys[i]] = {};
-    }
-    target = target[keys[i]];
-  }
-
-  const finalKey = keys[keys.length - 1];
-  target[finalKey] = value;
-  state.features[featureName].updatedAt = new Date().toISOString();
-
-  saveState(state);
-}
-
-/**
- * Update multiple feature properties at once
- * @param {string} featureName - Feature name
- * @param {Object} updates - Object with key-value pairs to update
- */
-export async function updateFeatureMultiple(featureName, updates) {
-  await ensureFeature(featureName);
-  const state = loadState(); // Load AFTER ensuring feature exists
-
-  for (const [key, value] of Object.entries(updates)) {
-    const keys = key.split('.');
-    let target = state.features[featureName];
-
-    for (let i = 0; i < keys.length - 1; i++) {
-      if (!target[keys[i]]) {
-        target[keys[i]] = {};
-      }
-      target = target[keys[i]];
-    }
-
-    const finalKey = keys[keys.length - 1];
-    target[finalKey] = value;
-  }
-
-  state.features[featureName].updatedAt = new Date().toISOString();
-  saveState(state);
-}
-
-/**
- * Add checkpoint to feature
- * @param {string} featureName - Feature name
- * @param {string} note - Checkpoint note
- * @returns {Object} Checkpoint object
- */
-export async function addCheckpoint(featureName, note) {
-  await ensureFeature(featureName);
-  const state = loadState();
-  const feature = state.features[featureName];
-
-  const checkpoint = {
-    passed: true,
-    checkpointNum: feature.checkpoints.length + 1,
-    timestamp: new Date().toISOString(),
-    phase: feature.phase || 'proposal',
-    results: [],
-    summary: {
-      note: note,
-      completedTasks: feature.tasks.completed
-    }
-  };
-
-  feature.checkpoints.push(checkpoint);
-  feature.updatedAt = new Date().toISOString();
-
-  saveState(state);
-  return checkpoint;
-}
-
-/**
- * Add agent to feature
- * @param {string} featureName - Feature name
- * @param {string} agentId - Agent ID
- * @returns {boolean} True if added, false if already exists
- */
-export async function addAgent(featureName, agentId) {
-  await ensureFeature(featureName);
-  const state = loadState(); // Load AFTER ensuring feature exists
-
-  if (!state.features[featureName].activeAgents.includes(agentId)) {
-    state.features[featureName].activeAgents.push(agentId);
-    state.features[featureName].updatedAt = new Date().toISOString();
-    saveState(state);
-    return true;
-  }
-
-  return false;
-}
-
-/**
- * Remove agent from feature
- * @param {string} featureName - Feature name
- * @param {string} agentId - Agent ID
- * @returns {boolean} True if removed, false if not found
- */
-export function removeAgent(featureName, agentId) {
-  const state = loadState();
-
-  if (!state.features[featureName]) {
-    throw new Error(`Feature '${featureName}' not found.`);
-  }
-
-  const index = state.features[featureName].activeAgents.indexOf(agentId);
-  if (index > -1) {
-    state.features[featureName].activeAgents.splice(index, 1);
-    state.features[featureName].updatedAt = new Date().toISOString();
-    saveState(state);
-    return true;
-  }
-
-  return false;
-}
-
-/**
- * Log a dispatch event to state.json.
- * Appends entry to feature.dispatchLog, capped at 50 entries (oldest trimmed).
- *
- * @param {string} featureName - Feature name
- * @param {{ timestamp: string, phase: string, mode: string, agents: Array<{ id: string, subagentType: string, group: string, tasks: string[] }> }} entry - Dispatch event to log
- */
-export function logDispatch(featureName, entry) {
-  const state = loadState();
-  const feature = state.features?.[featureName];
-  if (!feature) return;
-
-  if (!Array.isArray(feature.dispatchLog)) feature.dispatchLog = [];
-  feature.dispatchLog.push(entry);
-
-  // Cap at 50 entries
-  if (feature.dispatchLog.length > 50) {
-    feature.dispatchLog = feature.dispatchLog.slice(-50);
-  }
-
-  saveState(state);
-}
-
-/**
- * Normalize output type from kebab-case to camelCase (BUG-002 fix - Enhanced)
- * Supports both kebab-case and camelCase input formats for all output types
- * @param {string} type - Output type (e.g., 'ui-design-system', 'stack-scan', or 'uiDesignSystem')
- * @returns {string} Normalized type in camelCase
- */
-function normalizeOutputType(type) {
-  // If string doesn't contain hyphens, assume it's already camelCase
-  if (!type.includes('-')) {
-    return type;
-  }
-
-  // Convert kebab-case to camelCase automatically
-  // Example: 'ui-design-system' → 'uiDesignSystem'
-  // Example: 'stack-scan' → 'stackScan'
-  const camelCase = type.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
-
-  return camelCase;
-}
-
-/**
- * Calculate Levenshtein distance between two strings
- * Used for fuzzy matching and typo detection
- * @param {string} a - First string
- * @param {string} b - Second string
- * @returns {number} Edit distance
- */
-function levenshteinDistance(a, b) {
-  const matrix = [];
-
-  for (let i = 0; i <= b.length; i++) {
-    matrix[i] = [i];
-  }
-
-  for (let j = 0; j <= a.length; j++) {
-    matrix[0][j] = j;
-  }
-
-  for (let i = 1; i <= b.length; i++) {
-    for (let j = 1; j <= a.length; j++) {
-      if (b.charAt(i - 1) === a.charAt(j - 1)) {
-        matrix[i][j] = matrix[i - 1][j - 1];
-      } else {
-        matrix[i][j] = Math.min(
-          matrix[i - 1][j - 1] + 1, // substitution
-          matrix[i][j - 1] + 1,     // insertion
-          matrix[i - 1][j] + 1      // deletion
-        );
-      }
-    }
-  }
-
-  return matrix[b.length][a.length];
-}
-
-/**
- * Find closest matching output type for error suggestions
- * @param {string} inputType - The invalid input type
- * @param {Array<string>} validTypes - List of valid output types
- * @returns {string|null} Closest match or null
- */
-function findClosestMatch(inputType, validTypes) {
-  let closestMatch = null;
-  let minDistance = Infinity;
-
-  const normalizedInput = inputType.toLowerCase();
-
-  for (const validType of validTypes) {
-    const distance = levenshteinDistance(normalizedInput, validType.toLowerCase());
-
-    // Consider it a match if distance is less than 3 (likely typo)
-    // or if one string contains the other (partial match)
-    if (distance < minDistance && distance <= 3) {
-      minDistance = distance;
-      closestMatch = validType;
-    }
-
-    // Also check for partial matches
-    if (validType.toLowerCase().includes(normalizedInput) ||
-        normalizedInput.includes(validType.toLowerCase())) {
-      if (distance < minDistance) {
-        minDistance = distance;
-        closestMatch = validType;
-      }
-    }
-  }
-
-  // Only suggest if similarity is reasonable
-  return minDistance <= 3 ? closestMatch : null;
-}
-
-/**
- * Mark output as created
- * @param {string} featureName - Feature name
- * @param {string} outputType - Output type (proposal, spec, mandate, etc.)
- */
-export async function markOutput(featureName, outputType) {
-  await ensureFeature(featureName);
-  const state = loadState();
-
-  const normalized = normalizeOutputType(outputType);
-
-  // Initialize outputs on demand (not pre-stored)
-  if (!state.features[featureName].outputs) {
-    state.features[featureName].outputs = getAllOutputPaths(featureName);
-  }
-
-  if (!state.features[featureName].outputs[normalized]) {
-    // Try to find closest match for better error message
-    const validCamelCaseTypes = Object.keys(state.features[featureName].outputs);
-    const suggestion = findClosestMatch(outputType, validCamelCaseTypes);
-
-    let errorMsg = `Output type '${outputType}' not valid.`;
-
-    if (suggestion) {
-      errorMsg += `\n\nDid you mean '${suggestion}'?`;
-      // If the suggestion has a kebab-case alternative, show it too
-      const kebabAlternative = {
-        'uiDesignSystem': 'ui-design-system',
-        'uiMockups': 'ui-mockups',
-        'uiComponents': 'ui-components',
-        'uiFlows': 'ui-flows'
-      }[suggestion];
-      if (kebabAlternative) {
-        errorMsg += ` (also accepts '${kebabAlternative}')`;
-      }
-    }
-
-    errorMsg += `\n\nValid types:\n`;
-    errorMsg += `  ${validCamelCaseTypes.join(', ')}\n`;
-    errorMsg += `\nNote: kebab-case is also accepted (e.g., 'ui-design-system', 'stack-scan')`;
-
-    throw new Error(errorMsg);
-  }
-
-  state.features[featureName].outputs[normalized].created = true;
-  state.features[featureName].updatedAt = new Date().toISOString();
-
-  // Track the file change automatically
-  const outputPath = state.features[featureName].outputs[normalized].path;
-  if (outputPath) {
-    if (!Array.isArray(state.features[featureName].fileChanges)) {
-      state.features[featureName].fileChanges = [];
-    }
-    state.features[featureName].fileChanges.push({
-      path: outputPath,
-      action: 'created',
-      phase: state.features[featureName].phase,
-      timestamp: new Date().toISOString()
-    });
-  }
-
-  saveState(state);
-}
-
-/**
- * Track a file change for a feature
- * @param {string} featureName - Feature name
- * @param {string} filePath - Path of the changed file
- * @param {string} action - 'created' | 'modified' | 'deleted'
- * @param {string} phase - Phase during which the change occurred
- */
-export async function trackFileChange(featureName, filePath, action, phase) {
-  await ensureFeature(featureName);
-  const state = loadState();
-
-  if (!Array.isArray(state.features[featureName].fileChanges)) {
-    state.features[featureName].fileChanges = [];
-  }
-
-  state.features[featureName].fileChanges.push({
-    path: filePath,
-    action,
-    phase: phase || state.features[featureName].phase || 'proposal',
-    timestamp: new Date().toISOString()
-  });
-
-  state.features[featureName].updatedAt = new Date().toISOString();
-  saveState(state);
-}
-
-/**
- * Get file changes for a feature, optionally grouped by phase
- * @param {string} featureName - Feature name
- * @param {Object} options - Options
- * @param {boolean} options.groupByPhase - Group changes by phase
- * @returns {Array|Object} File changes
- */
-export function getFileChanges(featureName, options = {}) {
-  const state = loadState();
-  const feature = state.features[featureName];
-
-  if (!feature) {
-    throw new Error(`Feature '${featureName}' not found.`);
-  }
-
-  const changes = feature.fileChanges || [];
-
-  if (options.groupByPhase) {
-    const grouped = {};
-    for (const change of changes) {
-      const phase = change.phase || 'unknown';
-      if (!grouped[phase]) grouped[phase] = [];
-      grouped[phase].push(change);
-    }
-    return grouped;
-  }
-
-  return changes;
-}
-
-/**
- * Skip a phase and record it
- * @param {string} featureName - Feature name
- * @param {string} phase - Phase to skip
- * @param {string} reason - Reason for skipping
- */
-export async function skipPhase(featureName, phase, reason = '') {
-  await ensureFeature(featureName);
-  const state = loadState();
-
-  if (!state.features[featureName].skippedPhases) {
-    state.features[featureName].skippedPhases = [];
-  }
-
-  // Don't add duplicates
-  const existing = state.features[featureName].skippedPhases.find(s => s.phase === phase);
-  if (!existing) {
-    state.features[featureName].skippedPhases.push({
-      phase,
-      reason,
-      timestamp: new Date().toISOString()
-    });
-  }
-
-  state.features[featureName].updatedAt = new Date().toISOString();
-  saveState(state);
-}
-
-/**
- * Get skipped phases for a feature
- * @param {string} featureName - Feature name
- * @returns {Array} Array of skipped phases
- */
-export function getSkippedPhases(featureName) {
-  const state = loadState();
-  if (!state.features[featureName]) {
-    return [];
-  }
-  return state.features[featureName].skippedPhases || [];
-}
-
-/**
- * List all features
- * @returns {Array} Array of [featureName, featureObject] tuples
- */
-export function listFeatures() {
-  const state = loadState();
-  return Object.entries(state.features);
-}
-
-/**
- * Get project summary
- * @returns {Object} Summary with metadata
- */
-export function getSummary() {
-  const state = loadState();
-  return {
-    project: state.project,
-    metadata: state.metadata,
-    featuresCount: Object.keys(state.features).length
-  };
-}
-
-// ============================================================================
-// Approval Gates Operations
-// ============================================================================
-
-/**
- * Set approval gate status
- * @param {string} featureName - Feature name
- * @param {string} gate - Gate name (proposal, uiux, plan, review)
- * @param {boolean} approved - Approval status
- * @param {Object} metadata - Additional metadata (approvedBy, reason, etc.)
- */
-export async function setApprovalGate(featureName, gate, approved, metadata = {}) {
-  const state = loadState();
-  const feature = await ensureFeature(featureName);
-
-  if (!feature.approvalGates) {
-    feature.approvalGates = {
-      proposal: { approved: false, timestamp: null, approvedBy: null },
-      uiux: { approved: false, timestamp: null, approvedBy: null },
-      plan: { approved: false, timestamp: null, approvedBy: null },
-      review: { approved: false, timestamp: null, approvedBy: null }
-    };
-  }
-
-  feature.approvalGates[gate] = {
-    approved,
-    timestamp: metadata.approvedAt || metadata.rejectedAt || new Date().toISOString(),
-    approvedBy: metadata.approvedBy || metadata.rejectedBy || null,
-    ...metadata
-  };
-
-  state.features[featureName] = feature;
-  saveState(state);
-}
-
-/**
- * Get approval gate status
- * @param {string} featureName - Feature name
- * @param {string} gate - Gate name
- * @returns {Object|null} Gate object or null
- */
-export function getApprovalGate(featureName, gate) {
-  const state = loadState();
-  const feature = state.features[featureName];
-
-  if (!feature || !feature.approvalGates) {
-    return null;
-  }
-
-  return feature.approvalGates[gate] || null;
-}
-
-/**
- * Check if feature is pending approval
- * @param {string} featureName - Feature name
- * @returns {boolean} True if any gate is pending approval
- */
-export function isPendingApproval(featureName) {
-  const state = loadState();
-  const feature = state.features[featureName];
-
-  if (!feature || !feature.approvalGates) {
-    return false;
-  }
-
-  const currentPhase = feature.phase || 'proposal';
-
-  // Check if current phase has an approval gate
-  const phaseGateMap = {
-    'plan': 'plan',
-    'review': 'review',
-    'uiux': 'uiux'
-  };
-
-  const relevantGate = phaseGateMap[currentPhase];
-  if (!relevantGate) {
-    return false;
-  }
-
-  const gate = feature.approvalGates[relevantGate];
-  return gate && !gate.approved;
-}
-
-/**
- * Get approval history for a feature
- * @param {string} featureName - Feature name
- * @returns {Array} Array of approval events
- */
-export function getApprovalHistory(featureName) {
-  const state = loadState();
-  const feature = state.features[featureName];
-
-  if (!feature || !feature.approvalGates) {
-    return [];
-  }
-
-  const history = [];
-
-  Object.entries(feature.approvalGates).forEach(([gate, data]) => {
-    if (data.timestamp) {
-      history.push({
-        gate,
-        approved: data.approved,
-        timestamp: data.timestamp,
-        approvedBy: data.approvedBy || data.rejectedBy,
-        reason: data.reason
-      });
-    }
-  });
-
-  // Sort by timestamp
-  return history.sort((a, b) => new Date(a.timestamp) - new Date(b.timestamp));
-}
-
-/**
- * Find which agent was assigned a specific task in the latest dispatch.
- * Searches only the last dispatchLog entry.
- *
- * @param {string} featureName
- * @param {string} taskId
- * @returns {string|null} Agent ID or null if not found
- */
-export function resolveAgentForTask(featureName, taskId) {
-  const state = loadState();
-  const feature = state.features?.[featureName];
-  if (!feature) return null;
-
-  const log = feature.dispatchLog;
-  if (!Array.isArray(log) || log.length === 0) return null;
-
-  const latest = log[log.length - 1];
-  for (const agent of latest.agents || []) {
-    if (Array.isArray(agent.tasks) && agent.tasks.includes(taskId)) {
-      return agent.id;
-    }
-  }
-  return null;
-}
-
-/**
- * Update timing fields on a specific agent in the latest dispatch entry.
- * Fail-open: returns silently if feature/dispatch/agent not found.
- *
- * @param {string} featureName
- * @param {string} agentId - Agent ID to update
- * @param {Object} updates - Fields to merge (startedAt, completedAt, tasksCompleted)
- */
-export function updateDispatchAgentTiming(featureName, agentId, updates) {
-  const state = loadState();
-  const feature = state.features?.[featureName];
-  if (!feature) return;
-
-  const log = feature.dispatchLog;
-  if (!Array.isArray(log) || log.length === 0) return;
-
-  const latest = log[log.length - 1];
-  const agent = (latest.agents || []).find(a => a.id === agentId);
-  if (!agent) return;
-
-  Object.assign(agent, updates);
-
-  // If all agents now have completedAt, set entry.completedAt to the latest
-  const allComplete = (latest.agents || []).every(a => a.completedAt);
-  if (allComplete && latest.agents.length > 0) {
-    const timestamps = latest.agents.map(a => new Date(a.completedAt).getTime());
-    latest.completedAt = new Date(Math.max(...timestamps)).toISOString();
-  }
-
-  saveState(state);
-}
+/**
+ * MORPH-SPEC State Manager Library
+ *
+ * Manages state.json for tracking features, progress, agents, and checkpoints.
+ * Used both by CLI commands and internal automation.
+ */
+
+import { readFileSync, writeFileSync, renameSync, unlinkSync, existsSync, mkdirSync, rmdirSync, statSync } from 'fs';
+import { join, dirname } from 'path';
+import { getAllOutputPaths, getOutputPath } from '../paths/output-schema.js';
+
+const STATE_FILE_NAME = '.morph/state.json';
+
+// ============================================================================
+// Core Functions
+// ============================================================================
+
+/**
+ * Get the state file path (looks in current working directory)
+ */
+export function getStatePath() {
+  return join(process.cwd(), STATE_FILE_NAME);
+}
+/**
+ * Derive current phase from filesystem.
+ *
+ * Walks the phase map in descending order and returns the first phase whose
+ * CANONICAL ARTIFACT exists. An empty folder is not enough — `mkdir 2-plan/`
+ * does not count as "in plan phase" until `spec.md` (the first canonical
+ * plan-phase output) lands. If no canonical artifact is found anywhere,
+ * returns `'proposal'` (the starting phase).
+ *
+ * This avoids the chicken-and-egg problem where the agent pre-creates all
+ * phase folders, the derived phase jumps to the highest one, and
+ * `enforce-phase-writes` then blocks the agent from writing back to the
+ * prior phase folder.
+ *
+ * @param {string} featurePath - Absolute path to .morph/features/{feature}/
+ * @returns {string} Phase name: 'review' | 'implement' | 'plan' | 'uiux' | 'proposal'
+ */
+export function derivePhase(featurePath) {
+  const phaseMap = [
+    ['4-review',    'review',    'review-report.md'],
+    ['3-implement', 'implement', 'recap.md'],
+    ['2-plan',      'plan',      'spec.md'],
+    ['1-design',    'uiux',      'design-system.md'],
+    ['0-proposal',  'proposal',  'proposal.md'],
+  ];
+  for (const [folder, phase, canonical] of phaseMap) {
+    if (existsSync(join(featurePath, folder, canonical))) return phase;
+  }
+  return 'proposal';
+}
+
+/**
+ * Derive output existence from filesystem — checks if each output file exists at its expected path.
+ * Returns an object matching the old outputs shape for backwards-compatible display.
+ *
+ * @param {string} featureName - Feature name
+ * @param {string} [baseDir] - Project base dir (defaults to cwd)
+ * @returns {Object} Map of outputType -> { created: boolean, path: string }
+ */
+export function deriveOutputs(featureName, baseDir = process.cwd()) {
+  const outputPaths = getAllOutputPaths(featureName);
+  const result = {};
+  for (const [type, { path: relPath }] of Object.entries(outputPaths)) {
+    const absPath = join(baseDir, relPath);
+    result[type] = { created: existsSync(absPath), path: relPath };
+  }
+  return result;
+}
+
+/**
+ * Check if state file exists
+ */
+export function stateExists() {
+  return existsSync(getStatePath());
+}
+
+/**
+ * Load state from disk
+ * @param {boolean} throwOnError - If false, returns null instead of throwing
+ * @returns {Object|null} State object or null
+ */
+export function loadState(throwOnError = true) {
+  const statePath = getStatePath();
+
+  if (!existsSync(statePath)) {
+    if (throwOnError) {
+      throw new Error(`State file not found: ${statePath}\nRun 'morph-spec init' to initialize MORPH in this project.`);
+    }
+    return null;
+  }
+
+  try {
+    const content = readFileSync(statePath, 'utf8');
+    const state = JSON.parse(content);
+
+    // Migrate v3.0.0 → v4.0.0 (new directory layout)
+    if (state.version === '3.0.0') {
+      state.version = '4.0.0';
+      for (const [name, feature] of Object.entries(state.features || {})) {
+        if (!feature.outputs) continue;
+        const outputPathMap = getAllOutputPaths(name);
+        for (const [key, { path: newPath }] of Object.entries(outputPathMap)) {
+          if (feature.outputs[key]) {
+            feature.outputs[key].path = newPath;
+          }
+        }
+      }
+      writeFileSync(statePath, JSON.stringify(state, null, 2), 'utf8');
+    }
+
+    // Migrate v4.x -> v5.0.0: remove outputs and phase (now derived from
+    // filesystem) and workflow/workflowDetection (v5 has fixed phases, no
+    // workflow selection).
+    if (state.version && state.version.startsWith('4.')) {
+      state.version = '5.0.0';
+      for (const feature of Object.values(state.features || {})) {
+        delete feature.outputs;
+        delete feature.phase;
+        delete feature.workflow;
+        delete feature.workflowDetection;
+      }
+      writeFileSync(statePath, JSON.stringify(state, null, 2), 'utf8');
+    }
+
+    return state;
+  } catch (err) {
+    if (throwOnError) {
+      throw new Error(`Failed to parse state.json: ${err.message}`);
+    }
+    return null;
+  }
+}
+
+/**
+ * Save state to disk
+ * @param {Object} state - State object to save
+ */
+export function saveState(state) {
+  state.metadata = state.metadata || {};
+  state.metadata.lastUpdated = new Date().toISOString();
+
+  const statePath = getStatePath();
+  const stateDir = dirname(statePath);
+
+  // Ensure .morph directory exists
+  if (!existsSync(stateDir)) {
+    mkdirSync(stateDir, { recursive: true });
+  }
+
+  // Atomic write: write to a per-process temp file then rename.
+  // Per-process name prevents two concurrent CLI invocations (e.g. `task done && task start`)
+  // from clobbering each other's temp file on Windows.
+  const tmpPath = `${statePath}.tmp.${process.pid}`;
+  writeFileSync(tmpPath, JSON.stringify(state, null, 2), 'utf8');
+
+  // Retry rename on EPERM — Windows holds a brief exclusive lock on the target
+  // when another process is reading it; a short backoff resolves the contention.
+  const MAX_RETRIES = 5;
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      renameSync(tmpPath, statePath);
+      return;
+    } catch (err) {
+      if (err.code === 'EPERM' && attempt < MAX_RETRIES) {
+        // Synchronous sleep: CPU-friendly, works on Node.js main thread (v9.4+)
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50 * (attempt + 1));
+      } else {
+        try { unlinkSync(tmpPath); } catch { /* ignore cleanup errors */ }
+        throw err;
+      }
+    }
+  }
+}
+
+// ============================================================================
+// File Locking (BUG-002)
+// ============================================================================
+
+const LOCK_DIR_NAME = '.morph/state.json.lock';
+const LOCK_MAX_RETRIES = 5;
+const LOCK_BASE_MS = 100;
+const LOCK_STALE_MS = 30_000;
+
+/**
+ * Wrap a read-modify-write cycle on state.json with a mkdir-based mutex.
+ * @param {Function} fn - Async function to execute while holding the lock
+ * @returns {Promise<*>} Return value of fn
+ */
+export async function withStateLock(fn) {
+  const lockPath = join(process.cwd(), LOCK_DIR_NAME);
+
+  for (let attempt = 0; attempt <= LOCK_MAX_RETRIES; attempt++) {
+    try {
+      mkdirSync(lockPath);
+      break;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      try {
+        const lockStat = statSync(lockPath);
+        if (Date.now() - lockStat.mtimeMs > LOCK_STALE_MS) {
+          try { rmdirSync(lockPath); } catch { }
+          continue;
+        }
+      } catch { }
+      if (attempt === LOCK_MAX_RETRIES) {
+        throw new Error('Could not acquire state lock after retries');
+      }
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_BASE_MS * (2 ** attempt));
+    }
+  }
+
+  try {
+    return await fn();
+  } finally {
+    try { rmdirSync(lockPath); } catch { }
+  }
+}
+
+/**
+ * Initialize new state file
+ * @param {Object} options - Options
+ * @param {boolean} options.force - Overwrite existing file
+ * @param {string} options.projectName - Project name
+ * @param {string} options.projectType - Project type (e.g., 'dotnet-nextjs')
+ * @returns {Object} Initial state
+ */
+export function initState(options = {}) {
+  const { force = false, projectName = '{PROJECT_NAME}', projectType = 'dotnet-nextjs' } = options;
+
+  if (stateExists() && !force) {
+    throw new Error('State file already exists. Use force=true to overwrite.');
+  }
+
+  const initialState = {
+    version: "5.0.0",
+    project: {
+      name: projectName,
+      type: projectType,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString()
+    },
+    features: {},
+    threads: {},
+    metadata: {
+      totalFeatures: 0,
+      completedFeatures: 0,
+      totalTimeSpent: 0,
+      lastUpdated: new Date().toISOString()
+    }
+  };
+
+  saveState(initialState);
+  return initialState;
+}
+
+// ============================================================================
+// Feature Operations
+// ============================================================================
+
+/**
+ * Get feature from state
+ * @param {string} featureName - Feature name
+ * @returns {Object|null} Feature object or null
+ */
+export function getFeature(featureName) {
+  const state = loadState();
+  return state.features[featureName] || null;
+}
+
+/**
+ * Create or get feature with default structure.
+ * v5: every feature follows the fixed phase sequence
+ * (proposal → uiux → plan → implement → review). No workflow selection.
+ * @param {string} featureName - Feature name
+ * @returns {Promise<Object>} Feature object
+ */
+async function ensureFeature(featureName) {
+  const state = loadState();
+
+  if (!state.features[featureName]) {
+    state.features[featureName] = {
+      status: "draft",
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      activeAgents: [],
+      approvalGates: {
+        proposal: { approved: false, timestamp: null, approvedBy: null },
+        uiux: { approved: false, timestamp: null, approvedBy: null },
+        plan: { approved: false, timestamp: null, approvedBy: null },
+        review: { approved: false, timestamp: null, approvedBy: null }
+      },
+      tasks: {
+        total: 0,
+        completed: 0,
+        inProgress: 0,
+        pending: 0
+      },
+      checkpoints: [],
+      dispatchLog: [],
+      trustConfig: {},
+      contextBundles: [],
+      fileChanges: []
+    };
+
+    state.metadata.totalFeatures++;
+    saveState(state);
+  }
+
+  return state.features[featureName];
+}
+
+/**
+ * Update feature property (supports nested keys like "tasks.completed")
+ * @param {string} featureName - Feature name
+ * @param {string} key - Property key (supports dot notation)
+ * @param {any} value - Value to set
+ */
+export async function updateFeature(featureName, key, value) {
+  await ensureFeature(featureName);
+  const state = loadState(); // Load AFTER ensuring feature exists
+
+  const keys = key.split('.');
+  let target = state.features[featureName];
+
+  for (let i = 0; i < keys.length - 1; i++) {
+    if (!target[keys[i]]) {
+      target[keys[i]] = {};
+    }
+    target = target[keys[i]];
+  }
+
+  const finalKey = keys[keys.length - 1];
+  target[finalKey] = value;
+  state.features[featureName].updatedAt = new Date().toISOString();
+
+  saveState(state);
+}
+
+/**
+ * Update multiple feature properties at once
+ * @param {string} featureName - Feature name
+ * @param {Object} updates - Object with key-value pairs to update
+ */
+export async function updateFeatureMultiple(featureName, updates) {
+  await ensureFeature(featureName);
+  const state = loadState(); // Load AFTER ensuring feature exists
+
+  for (const [key, value] of Object.entries(updates)) {
+    const keys = key.split('.');
+    let target = state.features[featureName];
+
+    for (let i = 0; i < keys.length - 1; i++) {
+      if (!target[keys[i]]) {
+        target[keys[i]] = {};
+      }
+      target = target[keys[i]];
+    }
+
+    const finalKey = keys[keys.length - 1];
+    target[finalKey] = value;
+  }
+
+  state.features[featureName].updatedAt = new Date().toISOString();
+  saveState(state);
+}
+
+/**
+ * Add checkpoint to feature
+ * @param {string} featureName - Feature name
+ * @param {string} note - Checkpoint note
+ * @returns {Object} Checkpoint object
+ */
+export async function addCheckpoint(featureName, note) {
+  await ensureFeature(featureName);
+  const state = loadState();
+  const feature = state.features[featureName];
+
+  const checkpoint = {
+    passed: true,
+    checkpointNum: feature.checkpoints.length + 1,
+    timestamp: new Date().toISOString(),
+    phase: feature.phase || 'proposal',
+    results: [],
+    summary: {
+      note: note,
+      completedTasks: feature.tasks.completed
+    }
+  };
+
+  feature.checkpoints.push(checkpoint);
+  feature.updatedAt = new Date().toISOString();
+
+  saveState(state);
+  return checkpoint;
+}
+
+/**
+ * Add agent to feature
+ * @param {string} featureName - Feature name
+ * @param {string} agentId - Agent ID
+ * @returns {boolean} True if added, false if already exists
+ */
+export async function addAgent(featureName, agentId) {
+  await ensureFeature(featureName);
+  const state = loadState(); // Load AFTER ensuring feature exists
+
+  if (!state.features[featureName].activeAgents.includes(agentId)) {
+    state.features[featureName].activeAgents.push(agentId);
+    state.features[featureName].updatedAt = new Date().toISOString();
+    saveState(state);
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Remove agent from feature
+ * @param {string} featureName - Feature name
+ * @param {string} agentId - Agent ID
+ * @returns {boolean} True if removed, false if not found
+ */
+export function removeAgent(featureName, agentId) {
+  const state = loadState();
+
+  if (!state.features[featureName]) {
+    throw new Error(`Feature '${featureName}' not found.`);
+  }
+
+  const index = state.features[featureName].activeAgents.indexOf(agentId);
+  if (index > -1) {
+    state.features[featureName].activeAgents.splice(index, 1);
+    state.features[featureName].updatedAt = new Date().toISOString();
+    saveState(state);
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Log a dispatch event to state.json.
+ * Appends entry to feature.dispatchLog, capped at 50 entries (oldest trimmed).
+ *
+ * @param {string} featureName - Feature name
+ * @param {{ timestamp: string, phase: string, mode: string, agents: Array<{ id: string, subagentType: string, group: string, tasks: string[] }> }} entry - Dispatch event to log
+ */
+export function logDispatch(featureName, entry) {
+  const state = loadState();
+  const feature = state.features?.[featureName];
+  if (!feature) return;
+
+  if (!Array.isArray(feature.dispatchLog)) feature.dispatchLog = [];
+  feature.dispatchLog.push(entry);
+
+  // Cap at 50 entries
+  if (feature.dispatchLog.length > 50) {
+    feature.dispatchLog = feature.dispatchLog.slice(-50);
+  }
+
+  saveState(state);
+}
+
+/**
+ * Normalize output type from kebab-case to camelCase (BUG-002 fix - Enhanced)
+ * Supports both kebab-case and camelCase input formats for all output types
+ * @param {string} type - Output type (e.g., 'ui-design-system', 'stack-scan', or 'uiDesignSystem')
+ * @returns {string} Normalized type in camelCase
+ */
+function normalizeOutputType(type) {
+  // If string doesn't contain hyphens, assume it's already camelCase
+  if (!type.includes('-')) {
+    return type;
+  }
+
+  // Convert kebab-case to camelCase automatically
+  // Example: 'ui-design-system' → 'uiDesignSystem'
+  // Example: 'stack-scan' → 'stackScan'
+  const camelCase = type.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+
+  return camelCase;
+}
+
+/**
+ * Calculate Levenshtein distance between two strings
+ * Used for fuzzy matching and typo detection
+ * @param {string} a - First string
+ * @param {string} b - Second string
+ * @returns {number} Edit distance
+ */
+function levenshteinDistance(a, b) {
+  const matrix = [];
+
+  for (let i = 0; i <= b.length; i++) {
+    matrix[i] = [i];
+  }
+
+  for (let j = 0; j <= a.length; j++) {
+    matrix[0][j] = j;
+  }
+
+  for (let i = 1; i <= b.length; i++) {
+    for (let j = 1; j <= a.length; j++) {
+      if (b.charAt(i - 1) === a.charAt(j - 1)) {
+        matrix[i][j] = matrix[i - 1][j - 1];
+      } else {
+        matrix[i][j] = Math.min(
+          matrix[i - 1][j - 1] + 1, // substitution
+          matrix[i][j - 1] + 1,     // insertion
+          matrix[i - 1][j] + 1      // deletion
+        );
+      }
+    }
+  }
+
+  return matrix[b.length][a.length];
+}
+
+/**
+ * Find closest matching output type for error suggestions
+ * @param {string} inputType - The invalid input type
+ * @param {Array<string>} validTypes - List of valid output types
+ * @returns {string|null} Closest match or null
+ */
+function findClosestMatch(inputType, validTypes) {
+  let closestMatch = null;
+  let minDistance = Infinity;
+
+  const normalizedInput = inputType.toLowerCase();
+
+  for (const validType of validTypes) {
+    const distance = levenshteinDistance(normalizedInput, validType.toLowerCase());
+
+    // Consider it a match if distance is less than 3 (likely typo)
+    // or if one string contains the other (partial match)
+    if (distance < minDistance && distance <= 3) {
+      minDistance = distance;
+      closestMatch = validType;
+    }
+
+    // Also check for partial matches
+    if (validType.toLowerCase().includes(normalizedInput) ||
+        normalizedInput.includes(validType.toLowerCase())) {
+      if (distance < minDistance) {
+        minDistance = distance;
+        closestMatch = validType;
+      }
+    }
+  }
+
+  // Only suggest if similarity is reasonable
+  return minDistance <= 3 ? closestMatch : null;
+}
+
+/**
+ * Mark output as created
+ * @param {string} featureName - Feature name
+ * @param {string} outputType - Output type (proposal, spec, mandate, etc.)
+ */
+export async function markOutput(featureName, outputType) {
+  await ensureFeature(featureName);
+  const state = loadState();
+
+  const normalized = normalizeOutputType(outputType);
+
+  // Initialize outputs on demand (not pre-stored)
+  if (!state.features[featureName].outputs) {
+    state.features[featureName].outputs = getAllOutputPaths(featureName);
+  }
+
+  if (!state.features[featureName].outputs[normalized]) {
+    // Try to find closest match for better error message
+    const validCamelCaseTypes = Object.keys(state.features[featureName].outputs);
+    const suggestion = findClosestMatch(outputType, validCamelCaseTypes);
+
+    let errorMsg = `Output type '${outputType}' not valid.`;
+
+    if (suggestion) {
+      errorMsg += `\n\nDid you mean '${suggestion}'?`;
+      // If the suggestion has a kebab-case alternative, show it too
+      const kebabAlternative = {
+        'uiDesignSystem': 'ui-design-system',
+        'uiMockups': 'ui-mockups',
+        'uiComponents': 'ui-components',
+        'uiFlows': 'ui-flows'
+      }[suggestion];
+      if (kebabAlternative) {
+        errorMsg += ` (also accepts '${kebabAlternative}')`;
+      }
+    }
+
+    errorMsg += `\n\nValid types:\n`;
+    errorMsg += `  ${validCamelCaseTypes.join(', ')}\n`;
+    errorMsg += `\nNote: kebab-case is also accepted (e.g., 'ui-design-system', 'stack-scan')`;
+
+    throw new Error(errorMsg);
+  }
+
+  state.features[featureName].outputs[normalized].created = true;
+  state.features[featureName].updatedAt = new Date().toISOString();
+
+  // Track the file change automatically
+  const outputPath = state.features[featureName].outputs[normalized].path;
+  if (outputPath) {
+    if (!Array.isArray(state.features[featureName].fileChanges)) {
+      state.features[featureName].fileChanges = [];
+    }
+    state.features[featureName].fileChanges.push({
+      path: outputPath,
+      action: 'created',
+      phase: state.features[featureName].phase,
+      timestamp: new Date().toISOString()
+    });
+  }
+
+  saveState(state);
+}
+
+/**
+ * Track a file change for a feature
+ * @param {string} featureName - Feature name
+ * @param {string} filePath - Path of the changed file
+ * @param {string} action - 'created' | 'modified' | 'deleted'
+ * @param {string} phase - Phase during which the change occurred
+ */
+export async function trackFileChange(featureName, filePath, action, phase) {
+  await ensureFeature(featureName);
+  const state = loadState();
+
+  if (!Array.isArray(state.features[featureName].fileChanges)) {
+    state.features[featureName].fileChanges = [];
+  }
+
+  state.features[featureName].fileChanges.push({
+    path: filePath,
+    action,
+    phase: phase || state.features[featureName].phase || 'proposal',
+    timestamp: new Date().toISOString()
+  });
+
+  state.features[featureName].updatedAt = new Date().toISOString();
+  saveState(state);
+}
+
+/**
+ * Get file changes for a feature, optionally grouped by phase
+ * @param {string} featureName - Feature name
+ * @param {Object} options - Options
+ * @param {boolean} options.groupByPhase - Group changes by phase
+ * @returns {Array|Object} File changes
+ */
+export function getFileChanges(featureName, options = {}) {
+  const state = loadState();
+  const feature = state.features[featureName];
+
+  if (!feature) {
+    throw new Error(`Feature '${featureName}' not found.`);
+  }
+
+  const changes = feature.fileChanges || [];
+
+  if (options.groupByPhase) {
+    const grouped = {};
+    for (const change of changes) {
+      const phase = change.phase || 'unknown';
+      if (!grouped[phase]) grouped[phase] = [];
+      grouped[phase].push(change);
+    }
+    return grouped;
+  }
+
+  return changes;
+}
+
+/**
+ * Skip a phase and record it
+ * @param {string} featureName - Feature name
+ * @param {string} phase - Phase to skip
+ * @param {string} reason - Reason for skipping
+ */
+export async function skipPhase(featureName, phase, reason = '') {
+  await ensureFeature(featureName);
+  const state = loadState();
+
+  if (!state.features[featureName].skippedPhases) {
+    state.features[featureName].skippedPhases = [];
+  }
+
+  // Don't add duplicates
+  const existing = state.features[featureName].skippedPhases.find(s => s.phase === phase);
+  if (!existing) {
+    state.features[featureName].skippedPhases.push({
+      phase,
+      reason,
+      timestamp: new Date().toISOString()
+    });
+  }
+
+  state.features[featureName].updatedAt = new Date().toISOString();
+  saveState(state);
+}
+
+/**
+ * Get skipped phases for a feature
+ * @param {string} featureName - Feature name
+ * @returns {Array} Array of skipped phases
+ */
+export function getSkippedPhases(featureName) {
+  const state = loadState();
+  if (!state.features[featureName]) {
+    return [];
+  }
+  return state.features[featureName].skippedPhases || [];
+}
+
+/**
+ * List all features
+ * @returns {Array} Array of [featureName, featureObject] tuples
+ */
+export function listFeatures() {
+  const state = loadState();
+  return Object.entries(state.features);
+}
+
+/**
+ * Get project summary
+ * @returns {Object} Summary with metadata
+ */
+export function getSummary() {
+  const state = loadState();
+  return {
+    project: state.project,
+    metadata: state.metadata,
+    featuresCount: Object.keys(state.features).length
+  };
+}
+
+// ============================================================================
+// Approval Gates Operations
+// ============================================================================
+
+/**
+ * Set approval gate status
+ * @param {string} featureName - Feature name
+ * @param {string} gate - Gate name (proposal, uiux, plan, review)
+ * @param {boolean} approved - Approval status
+ * @param {Object} metadata - Additional metadata (approvedBy, reason, etc.)
+ */
+export async function setApprovalGate(featureName, gate, approved, metadata = {}) {
+  const state = loadState();
+  const feature = await ensureFeature(featureName);
+
+  if (!feature.approvalGates) {
+    feature.approvalGates = {
+      proposal: { approved: false, timestamp: null, approvedBy: null },
+      uiux: { approved: false, timestamp: null, approvedBy: null },
+      plan: { approved: false, timestamp: null, approvedBy: null },
+      review: { approved: false, timestamp: null, approvedBy: null }
+    };
+  }
+
+  feature.approvalGates[gate] = {
+    approved,
+    timestamp: metadata.approvedAt || metadata.rejectedAt || new Date().toISOString(),
+    approvedBy: metadata.approvedBy || metadata.rejectedBy || null,
+    ...metadata
+  };
+
+  state.features[featureName] = feature;
+  saveState(state);
+}
+
+/**
+ * Get approval gate status
+ * @param {string} featureName - Feature name
+ * @param {string} gate - Gate name
+ * @returns {Object|null} Gate object or null
+ */
+export function getApprovalGate(featureName, gate) {
+  const state = loadState();
+  const feature = state.features[featureName];
+
+  if (!feature || !feature.approvalGates) {
+    return null;
+  }
+
+  return feature.approvalGates[gate] || null;
+}
+
+/**
+ * Check if feature is pending approval
+ * @param {string} featureName - Feature name
+ * @returns {boolean} True if any gate is pending approval
+ */
+export function isPendingApproval(featureName) {
+  const state = loadState();
+  const feature = state.features[featureName];
+
+  if (!feature || !feature.approvalGates) {
+    return false;
+  }
+
+  const currentPhase = feature.phase || 'proposal';
+
+  // Check if current phase has an approval gate
+  const phaseGateMap = {
+    'plan': 'plan',
+    'review': 'review',
+    'uiux': 'uiux'
+  };
+
+  const relevantGate = phaseGateMap[currentPhase];
+  if (!relevantGate) {
+    return false;
+  }
+
+  const gate = feature.approvalGates[relevantGate];
+  return gate && !gate.approved;
+}
+
+/**
+ * Get approval history for a feature
+ * @param {string} featureName - Feature name
+ * @returns {Array} Array of approval events
+ */
+export function getApprovalHistory(featureName) {
+  const state = loadState();
+  const feature = state.features[featureName];
+
+  if (!feature || !feature.approvalGates) {
+    return [];
+  }
+
+  const history = [];
+
+  Object.entries(feature.approvalGates).forEach(([gate, data]) => {
+    if (data.timestamp) {
+      history.push({
+        gate,
+        approved: data.approved,
+        timestamp: data.timestamp,
+        approvedBy: data.approvedBy || data.rejectedBy,
+        reason: data.reason
+      });
+    }
+  });
+
+  // Sort by timestamp
+  return history.sort((a, b) => new Date(a.timestamp) - new Date(b.timestamp));
+}
+
+/**
+ * Find which agent was assigned a specific task in the latest dispatch.
+ * Searches only the last dispatchLog entry.
+ *
+ * @param {string} featureName
+ * @param {string} taskId
+ * @returns {string|null} Agent ID or null if not found
+ */
+export function resolveAgentForTask(featureName, taskId) {
+  const state = loadState();
+  const feature = state.features?.[featureName];
+  if (!feature) return null;
+
+  const log = feature.dispatchLog;
+  if (!Array.isArray(log) || log.length === 0) return null;
+
+  const latest = log[log.length - 1];
+  for (const agent of latest.agents || []) {
+    if (Array.isArray(agent.tasks) && agent.tasks.includes(taskId)) {
+      return agent.id;
+    }
+  }
+  return null;
+}
+
+/**
+ * Update timing fields on a specific agent in the latest dispatch entry.
+ * Fail-open: returns silently if feature/dispatch/agent not found.
+ *
+ * @param {string} featureName
+ * @param {string} agentId - Agent ID to update
+ * @param {Object} updates - Fields to merge (startedAt, completedAt, tasksCompleted)
+ */
+export function updateDispatchAgentTiming(featureName, agentId, updates) {
+  const state = loadState();
+  const feature = state.features?.[featureName];
+  if (!feature) return;
+
+  const log = feature.dispatchLog;
+  if (!Array.isArray(log) || log.length === 0) return;
+
+  const latest = log[log.length - 1];
+  const agent = (latest.agents || []).find(a => a.id === agentId);
+  if (!agent) return;
+
+  Object.assign(agent, updates);
+
+  // If all agents now have completedAt, set entry.completedAt to the latest
+  const allComplete = (latest.agents || []).every(a => a.completedAt);
+  if (allComplete && latest.agents.length > 0) {
+    const timestamps = latest.agents.map(a => new Date(a.completedAt).getTime());
+    latest.completedAt = new Date(Math.max(...timestamps)).toISOString();
+  }
+
+  saveState(state);
+}