@polymorphism-tech/morph-spec 4.3.6 → 4.5.0

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

@@ -1,592 +1,831 @@
-/**
- * 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, existsSync, mkdirSync } from 'fs';
-import { join, dirname } from 'path';
-import { detectWorkflow } from '../workflows/workflow-detector.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);
-}
-
-/**
- * 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 state init' first.`);
-    }
-    return null;
-  }
-
-  try {
-    const content = readFileSync(statePath, 'utf8');
-    return JSON.parse(content);
-  } 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 });
-  }
-
-  writeFileSync(statePath, JSON.stringify(state, null, 2), 'utf8');
-}
-
-/**
- * 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., 'blazor-server')
- * @returns {Object} Initial state
- */
-export function initState(options = {}) {
-  const { force = false, projectName = '{PROJECT_NAME}', projectType = 'blazor-server' } = options;
-
-  if (stateExists() && !force) {
-    throw new Error('State file already exists. Use force=true to overwrite.');
-  }
-
-  const initialState = {
-    version: "3.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;
-      } catch (err) {
-        // If detection fails, fall back to auto
-        console.warn('Workflow detection failed:', err.message);
-      }
-    }
-
-    state.features[featureName] = {
-      status: "draft",
-      phase: "proposal",
-      workflow: workflowId, // auto | fast-track | standard | full-morph | design-impl | ui-refresh
-      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 },
-        design: { approved: false, timestamp: null, approvedBy: null },
-        tasks: { approved: false, timestamp: null, approvedBy: null }
-      },
-      outputs: {
-        proposal: { created: false, path: `.morph/project/outputs/${featureName}/proposal.md` },
-        spec: { created: false, path: `.morph/project/outputs/${featureName}/spec.md` },
-        contracts: { created: false, path: `.morph/project/outputs/${featureName}/contracts.cs` },
-        tasks: { created: false, path: `.morph/project/outputs/${featureName}/tasks.md` },
-        uiDesignSystem: { created: false, path: `.morph/project/outputs/${featureName}/ui-design-system.md` },
-        uiMockups: { created: false, path: `.morph/project/outputs/${featureName}/ui-mockups.md` },
-        uiComponents: { created: false, path: `.morph/project/outputs/${featureName}/ui-components.md` },
-        uiFlows: { created: false, path: `.morph/project/outputs/${featureName}/ui-flows.md` },
-        decisions: { created: false, path: `.morph/project/outputs/${featureName}/decisions.md` },
-        recap: { created: false, path: `.morph/project/outputs/${featureName}/recap.md` }
-      },
-      tasks: {
-        total: 0,
-        completed: 0,
-        inProgress: 0,
-        pending: 0
-      },
-      checkpoints: [],
-      threadMetrics: {
-        totalThreads: 0,
-        parallelPeak: 0,
-        avgDuration: 0,
-        checkpointPassRate: 100
-      },
-      trustConfig: {
-        level: 'low',
-        history: [],
-        autoApprove: {
-          design: false,
-          tasks: false
-        }
-      },
-      contextBundles: []
-    };
-
-    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,
-    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;
-}
-
-/**
- * Normalize output type from kebab-case to camelCase for UI types (BUG #12 fix)
- * @param {string} type - Output type (e.g., 'ui-design-system' or 'uiDesignSystem')
- * @returns {string} Normalized type in camelCase
- */
-function normalizeOutputType(type) {
-  const kebabMap = {
-    'ui-design-system': 'uiDesignSystem',
-    'ui-mockups': 'uiMockups',
-    'ui-components': 'uiComponents',
-    'ui-flows': 'uiFlows'
-  };
-  return kebabMap[type] || type;
-}
-
-/**
- * Mark output as created
- * @param {string} featureName - Feature name
- * @param {string} outputType - Output type (proposal, spec, contracts, etc.)
- */
-export async function markOutput(featureName, outputType) {
-  await ensureFeature(featureName);
-  const state = loadState();
-
-  const normalized = normalizeOutputType(outputType);
-
-  if (!state.features[featureName].outputs[normalized]) {
-    throw new Error(`Output type '${outputType}' not valid. Valid types: proposal, spec, contracts, tasks, uiDesignSystem (or ui-design-system), uiMockups (or ui-mockups), uiComponents (or ui-components), uiFlows (or ui-flows), decisions, recap`);
-  }
-
-  state.features[featureName].outputs[normalized].created = true;
-  state.features[featureName].updatedAt = new Date().toISOString();
-
-  // If marking tasks output, try to sync task count from state tasks array
-  if (normalized === 'tasks') {
-    syncTasksCount(state.features[featureName]);
-  }
-
-  saveState(state);
-}
-
-/**
- * Sync progress counters from taskList array into feature.progress
- * @param {Object} feature - Feature object
- */
-function syncTasksCount(feature) {
-  const list = feature.taskList;
-  if (!Array.isArray(list) || list.length === 0) return;
-  const completed = list.filter(t => t.status === 'completed').length;
-  feature.progress = {
-    total: list.length,
-    completed,
-    inProgress: list.filter(t => t.status === 'in_progress').length,
-    pending: list.filter(t => t.status === 'pending').length,
-    percentage: Math.round((completed / list.length) * 100)
-  };
-}
-
-/**
- * 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, design, tasks)
- * @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 },
-      design: { approved: false, timestamp: null, approvedBy: null },
-      tasks: { 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;
-
-  // Check if current phase has an approval gate
-  const phaseGateMap = {
-    'design': 'design',
-    'tasks': 'tasks',
-    '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));
-}
+/**
+ * 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, existsSync, mkdirSync } 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: 'implement' | 'tasks' | 'uiux' | 'design' | 'proposal' | 'setup'
+ */
+export function derivePhase(featurePath) {
+  const phaseMap = [
+    ['4-implement', 'implement'],
+    ['3-tasks', 'tasks'],
+    ['2-ui', 'uiux'],
+    ['1-design', 'design'],
+    ['0-proposal', 'proposal'],
+  ];
+  for (const [folder, phase] of phaseMap) {
+    if (existsSync(join(featurePath, folder))) return phase;
+  }
+  return 'setup';
+}
+
+/**
+ * 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 state init' first.`);
+    }
+    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 });
+  }
+
+  writeFileSync(statePath, JSON.stringify(state, null, 2), 'utf8');
+}
+
+/**
+ * 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., 'blazor-server')
+ * @returns {Object} Initial state
+ */
+export function initState(options = {}) {
+  const { force = false, projectName = '{PROJECT_NAME}', projectType = 'blazor-server' } = 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;
+      } catch (err) {
+        // If detection fails, fall back to auto
+        console.warn('Workflow detection failed:', err.message);
+      }
+    }
+
+    state.features[featureName] = {
+      status: "draft",
+      workflow: workflowId, // auto | fast-track | standard | full-morph | design-impl | ui-refresh
+      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 },
+        design: { approved: false, timestamp: null, approvedBy: null },
+        tasks: { approved: false, timestamp: null, approvedBy: null }
+      },
+      tasks: {
+        total: 0,
+        completed: 0,
+        inProgress: 0,
+        pending: 0
+      },
+      checkpoints: [],
+      threadMetrics: {
+        totalThreads: 0,
+        parallelPeak: 0,
+        avgDuration: 0,
+        checkpointPassRate: 100
+      },
+      trustConfig: {
+        level: 'low',
+        history: [],
+        autoApprove: {
+          design: false,
+          tasks: false
+        }
+      },
+      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 || 'setup',
+    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;
+}
+
+/**
+ * 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', 'schema-analysis', 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: 'schema-analysis' → 'schemaAnalysis'
+  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, contracts, etc.)
+ */
+export async function markOutput(featureName, outputType) {
+  await ensureFeature(featureName);
+  const state = loadState();
+
+  const normalized = normalizeOutputType(outputType);
+
+  // Initialize outputs on demand (not pre-stored since v5.0.0)
+  if (!state.features[featureName].outputs) {
+    state.features[featureName].outputs = getAllOutputPaths(featureName);
+  }
+
+  // Define all valid output types (both camelCase and kebab-case alternatives)
+  const validTypes = [
+    'proposal', 'spec', 'contracts', 'tasks', 'decisions', 'recap',
+    'uiDesignSystem', 'ui-design-system',
+    'uiMockups', 'ui-mockups',
+    'uiComponents', 'ui-components',
+    'uiFlows', 'ui-flows'
+  ];
+
+  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 += `  - Standard: proposal, spec, contracts, tasks, decisions, recap\n`;
+    errorMsg += `  - UI/UX: uiDesignSystem, uiMockups, uiComponents, uiFlows\n`;
+    errorMsg += `\nNote: UI types also accept kebab-case (e.g., 'ui-design-system')`;
+
+    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()
+    });
+  }
+
+  // If marking tasks output, try to sync task count from state tasks array
+  if (normalized === 'tasks') {
+    syncTasksCount(state.features[featureName]);
+  }
+
+  saveState(state);
+}
+
+/**
+ * Sync progress counters from taskList array into feature.progress
+ * @param {Object} feature - Feature object
+ */
+function syncTasksCount(feature) {
+  const list = feature.taskList;
+  if (!Array.isArray(list) || list.length === 0) return;
+  const completed = list.filter(t => t.status === 'completed').length;
+  feature.progress = {
+    total: list.length,
+    completed,
+    inProgress: list.filter(t => t.status === 'in_progress').length,
+    pending: list.filter(t => t.status === 'pending').length,
+    percentage: Math.round((completed / list.length) * 100)
+  };
+}
+
+/**
+ * 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 || 'setup',
+    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, design, tasks)
+ * @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 },
+      design: { approved: false, timestamp: null, approvedBy: null },
+      tasks: { 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 || 'setup';
+
+  // Check if current phase has an approval gate
+  const phaseGateMap = {
+    'design': 'design',
+    'tasks': 'tasks',
+    '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));
+}