@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

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

@@ -1,10 +1,3 @@
-/**
- * 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, readdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { getAllOutputPaths, getOutputPath } from '../paths/output-schema.js';
@@ -13,45 +6,24 @@ import { derivePhaseFrom, diskArtifactProbe } from '../../../framework/hooks/sha
 const STATE_FILE_NAME = '.morph/state.json';
 const FEATURES_DIR_NAME = '.morph/features';
 const FEATURE_FILE_NAME = 'feature.json';
-/**
- * The one spelling of the committed project config's location, relative to a
- * project root. Exported because three modules used to write it out by hand
- * (`readProjectFromConfig` here, `readMorphConfig` and `morphConfigPath` in
- * src/lib/tasks/) — and `morphConfigPath`'s own JSDoc promised the reader that
- * the writer and the reader "can never disagree about which file is meant",
- * a guarantee three copies of a string cannot give. Now they can't.
- */
 export const CONFIG_FILE_NAME = '.morph/config/config.json';
 
-// The on-disk state version. NOTE: this tracks the *feature-object* schema, which
-// is unchanged by the per-feature storage split — features are now persisted to
-// `.morph/features/{name}/feature.json` (authoritative, committed) with the root
-// `.morph/state.json` acting as a thin, derivable, gitignored index. Migration to
-// the split layout is detected by `feature.json` presence, not by this number.
+// Versions the feature-object schema, not the storage layout: the per-feature
+// split is detected by the presence of `feature.json`.
 const STATE_VERSION = '5.0.0';
 
-// ============================================================================
-// Core Functions
-// ============================================================================
-
-/**
- * Get the state file path (looks in current working directory)
- */
 export function getStatePath() {
   return join(process.cwd(), STATE_FILE_NAME);
 }
 
-/** Absolute path to the per-feature folder root (.morph/features). */
 function getFeaturesDir() {
   return join(process.cwd(), FEATURES_DIR_NAME);
 }
 
-/** Absolute path to a feature's authoritative feature.json. */
 function getFeatureJsonPath(featureName) {
   return join(getFeaturesDir(), featureName, FEATURE_FILE_NAME);
 }
 
-/** List feature names that have a folder on disk under .morph/features. */
 function listFeatureNamesOnDisk() {
   const dir = getFeaturesDir();
   if (!existsSync(dir)) return [];
@@ -64,7 +36,6 @@ function listFeatureNamesOnDisk() {
   }
 }
 
-/** Read a feature's feature.json, or null if missing/corrupt. */
 function readFeatureJson(featureName) {
   const path = getFeatureJsonPath(featureName);
   if (!existsSync(path)) return null;
@@ -75,7 +46,6 @@ function readFeatureJson(featureName) {
   }
 }
 
-/** Read project identity from the committed .morph/config/config.json, if present. */
 function readProjectFromConfig() {
   const path = join(process.cwd(), CONFIG_FILE_NAME);
   if (!existsSync(path)) return null;
@@ -92,10 +62,7 @@ function readProjectFromConfig() {
   }
 }
 
-/**
- * Atomic JSON write: per-process temp file then rename, with an EPERM retry loop
- * for the brief Windows lock race. Creates the parent directory if needed.
- */
+// Per-process temp file then rename; the EPERM retry covers the brief Windows lock race.
 export function atomicWriteJson(targetPath, data) {
   const dir = dirname(targetPath);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
@@ -112,41 +79,25 @@ export function atomicWriteJson(targetPath, data) {
       if (err.code === 'EPERM' && attempt < MAX_RETRIES) {
         Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50 * (attempt + 1));
       } else {
-        try { unlinkSync(tmpPath); } catch { /* ignore cleanup errors */ }
+        try { unlinkSync(tmpPath); } catch { }
         throw err;
       }
     }
   }
 }
 
-/**
- * Write a feature's authoritative feature.json (atomic).
- *
- * Skips the write entirely when the on-disk content is already byte-identical to
- * what we'd write. `saveState` hydrates and re-persists EVERY feature, so a CLI
- * mutation on feature A would otherwise rewrite sibling B's file from A's loaded
- * copy. Skipping unchanged siblings means A never touches B's authoritative file
- * in the common case — shrinking the cross-feature clobber window to nothing
- * unless B genuinely changed under A.
- *
- * A formatting mismatch is NOT free, though: the guard compares bytes, so a
- * sibling committed with a trailing newline fails it and gets rewritten. The
- * content is equivalent, but git sees ` M` on a file this caller never meant to
- * touch — enough to fail a whole-tree clean check (see the finish teardown's clearRootWorktreeRegistration).
- * And the guard only skips IDENTICAL content: a concurrent instance's CHANGED
- * write to a sibling would still be clobbered by the sweep.
- */
+// saveState re-persists every feature; skipping byte-identical content keeps a
+// mutation on one feature from rewriting (and clobbering) its siblings' files.
 function writeFeatureJson(featureName, feature) {
   const path = getFeatureJsonPath(featureName);
   try {
     if (existsSync(path) && readFileSync(path, 'utf8') === JSON.stringify(feature, null, 2)) {
-      return; // unchanged — don't rewrite (and don't clobber a concurrent sibling write)
+      return;
     }
-  } catch { /* fall through to a normal write */ }
+  } catch { }
   atomicWriteJson(path, feature);
 }
 
-/** A fresh, empty state scaffold (used when no root index exists yet). */
 function scaffoldState() {
   return {
     version: STATE_VERSION,
@@ -156,13 +107,7 @@ function scaffoldState() {
     metadata: { totalFeatures: 0, completedFeatures: 0, totalTimeSpent: 0 },
   };
 }
-/**
- * Derive current phase from filesystem — delegates to the hook-side rule
- * (`derivePhaseFrom`) so the CLI and the hooks never disagree on a feature.
- *
- * @param {string} featurePath - Absolute path to .morph/features/{feature}/
- * @returns {string} Phase name: 'review' | 'implement' | 'uiux' | 'plan'
- */
+// Delegates to the hook-side rule so the CLI and the hooks never disagree on a phase.
 export function derivePhase(featurePath) {
   let feature = null;
   try {
@@ -172,14 +117,6 @@ export function derivePhase(featurePath) {
   return derivePhaseFrom(feature, diskArtifactProbe(featurePath));
 }
 
-/**
- * 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 = {};
@@ -190,25 +127,16 @@ export function deriveOutputs(featureName, baseDir = process.cwd()) {
   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();
   const rootExists = existsSync(statePath);
   const featureNames = listFeatureNamesOnDisk();
   const featuresExist = featureNames.some((name) => existsSync(getFeatureJsonPath(name)));
 
-  // "No state" only when neither the root index nor any per-feature file exists.
   if (!rootExists && !featuresExist) {
     if (throwOnError) {
       throw new Error(`State file not found: ${statePath}\nRun 'morph-spec init' to initialize MORPH in this project.`);
@@ -233,19 +161,12 @@ export function loadState(throwOnError = true) {
     if (fromConfig) state.project = { ...(state.project || {}), ...fromConfig };
   }
 
-  // Snapshot the on-disk version BEFORE the migration blocks below bump it. The
-  // reconciliation loop uses it to tell a legacy monolith (a pre-v5 layout that
-  // predates the split — materialize) from a current-version index entry whose
-  // folder is gone (a deleted feature — prune). A missing root index is treated
-  // as "no migration" (null): the loop is empty in that case (features hydrate
-  // from disk), so the value only matters when the root index exists.
+  // Snapshot before the migrations below bump it: the reconcile loop tells a
+  // legacy monolith (materialize) from a deleted feature (prune) by this value.
   const fileVersion = rootExists ? state.version : null;
 
-  // A missing root index means we must (re)generate it from the per-feature
-  // files we're about to hydrate — this is the self-heal path after a wipe.
   let mutated = !rootExists;
 
-  // Migrate v3.0.0 → v4.0.0 (new directory layout) — operates on root features.
   if (state.version === '3.0.0') {
     state.version = '4.0.0';
     for (const [name, feature] of Object.entries(state.features)) {
@@ -258,8 +179,6 @@ export function loadState(throwOnError = true) {
     mutated = true;
   }
 
-  // Migrate v4.x → v5.0.0: drop derived fields (now filesystem-derived) and
-  // workflow selection (v5 has fixed phases).
   if (state.version && state.version.startsWith('4.')) {
     state.version = '5.0.0';
     for (const feature of Object.values(state.features)) {
@@ -271,57 +190,35 @@ export function loadState(throwOnError = true) {
     mutated = true;
   }
 
-  // Reconcile index entries whose feature.json is missing. The discriminator is
-  // the ON-DISK VERSION (`fileVersion`, snapshotted before the migrations bumped
-  // it) — NOT whether any sibling folder survived. Sibling-existence is the wrong
-  // signal: deleting EVERY folder at once (the reported incident) would leave no
-  // survivor and resurrect them all. Version is unconditional:
-  //
-  //   • A pre-v5 root (v3/v4) or an entry rich beyond the thin {status,updatedAt}
-  //     shape = a legacy monolithic state.json that predates the split. It is the
-  //     sole copy of its feature — materialize each to its authoritative
-  //     feature.json (split-on-load migration; idempotent thereafter).
-  //
-  //   • A current-version (v5) thin entry with NO folder = the feature was
-  //     DELETED and this gitignored index entry is stale. Prune it; NEVER recreate
-  //     the folder — that turned an intentional delete into a zombie. This is safe
-  //     and exhaustive because saveState ALWAYS co-writes feature.json + a thin
-  //     index entry: a v5 thin entry with no feature.json can ONLY mean the folder
-  //     was removed. The prune sticks — saveState below derives the index from this
-  //     same in-memory map, and hydration only re-adds features whose folder exists.
+  // Index entry without feature.json: a pre-v5 or rich entry is the sole copy of a
+  // legacy monolith (materialize it); a v5 thin entry means the folder was deleted
+  // (prune it, never resurrect). Safe because saveState always co-writes both.
   const isRichEntry = (f) =>
     f && typeof f === 'object' && Object.keys(f).some((k) => k !== 'status' && k !== 'updatedAt');
   const wasVersionMigration = fileVersion !== null && fileVersion !== STATE_VERSION;
   for (const [name, feature] of Object.entries(state.features)) {
     if (existsSync(getFeatureJsonPath(name))) continue;
     if (wasVersionMigration || isRichEntry(feature)) {
-      writeFeatureJson(name, feature); // legacy monolith — materialize, don't lose it
+      writeFeatureJson(name, feature);
     } else {
-      delete state.features[name]; // v5 thin entry, no folder = deleted — never resurrect
+      delete state.features[name];
       console.error(`ℹ morph-spec: dropped stale index entry "${name}" (feature folder was deleted).`);
     }
     mutated = true;
   }
 
-  // Hydrate from per-feature files (authoritative). Also picks up features that
-  // exist on disk but are absent from a stale/deleted root index — so a wiped
-  // state.json self-heals from the committed feature.json files.
   for (const name of featureNames) {
     const fj = readFeatureJson(name);
     if (fj) state.features[name] = fj;
   }
 
   if (mutated) {
-    saveState(state); // re-persists feature.json files + a freshly thinned root index
+    saveState(state);
   }
 
   return state;
 }
 
-/**
- * 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();
@@ -329,32 +226,18 @@ export function saveState(state) {
 
   const features = state.features || {};
 
-  // Aggregate metadata is derived from the authoritative feature set so the
-  // thin root index never drifts from the per-feature files.
   state.metadata.totalFeatures = Object.keys(features).length;
   state.metadata.completedFeatures = Object.values(features)
     .filter((f) => f && f.status === 'completed').length;
 
-  // 1) Persist each feature to its authoritative, committed feature.json — what
-  //    travels with the feature's own commit.
-  //
-  //    NOTE: this IS a cross-feature sweep. Mutating one feature re-persists
-  //    every sibling; writeFeatureJson's byte-identical guard makes that a no-op
-  //    only while a sibling's committed file matches our formatting exactly. A
-  //    sibling saved with a trailing newline (any editor, prettier) is rewritten
-  //    and shows up as ` M` — dirtying the tree on behalf of a feature the
-  //    caller never touched. Callers that need to change ONE feature's field
-  //    should write that feature.json directly instead of round-tripping state
-  //    through here (see the finish teardown's clearRootWorktreeRegistration).
+  // A cross-feature sweep: a sibling saved in another format (trailing newline) is
+  // rewritten and dirties the tree. To change one feature, write its feature.json directly.
   const thinFeatures = {};
   for (const [name, feature] of Object.entries(features)) {
     writeFeatureJson(name, feature);
     thinFeatures[name] = { status: feature.status, updatedAt: feature.updatedAt };
   }
 
-  // 2) Persist the thin, derivable, gitignored root index (status + updatedAt
-  //    per feature is all that callers like getActiveFeature need from the root;
-  //    full feature data is hydrated from feature.json on load).
   atomicWriteJson(getStatePath(), {
     version: state.version,
     project: state.project,
@@ -364,20 +247,11 @@ export function saveState(state) {
   });
 }
 
-// ============================================================================
-// 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);
 
@@ -408,14 +282,6 @@ export async function withStateLock(fn) {
   }
 }
 
-/**
- * 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;
 
@@ -445,27 +311,11 @@ export function initState(options = {}) {
   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
- * (plan → [uiux] → implement → review). No workflow selection.
- * @param {string} featureName - Feature name
- * @returns {Promise<Object>} Feature object
- */
 async function ensureFeature(featureName) {
   const state = loadState();
 
@@ -492,28 +342,6 @@ async function ensureFeature(featureName) {
   return state.features[featureName];
 }
 
-/**
- * Explicitly create a feature with the canonical shape (documented in
- * framework/schemas/feature.schema.json). Idempotent: an existing feature is
- * returned untouched (including its `workType` — a later `--type` on a
- * repeat call never overwrites it; see `morph-spec retype` for that). This
- * is the server-side birth path behind `morph-spec create` — replacing the
- * implicit registration on the first Write into .morph/features/ (the
- * state-sync hook remains as fallback).
- *
- * Works even before any state exists (scaffolds the root index), so a
- * feature can be born as the very first morph action in a project.
- *
- * @param {string} featureName - Feature name (kebab-case), also the folder id
- * @param {{ status?: string, workType?: string, workTypeDetection?: object, name?: string, description?: string }} [options]
- *   `name` defaults to `featureName` (the slug) — always stamped so a feature
- *   is never nameless. `description` is written only when provided (the CLI
- *   `create` enforces it; internal callers may omit it). `workType` defaults to
- *   'feature' (v8 routing — see src/core/work-types.js). `workTypeDetection` is
- *   only written when provided (source/confidence/matched audit trail from the
- *   `--type`/`--request` resolution in `create.js`).
- * @returns {Promise<{ feature: Object, created: boolean }>}
- */
 export async function createFeature(featureName, options = {}) {
   const { status = 'in_progress', workType, workTypeDetection, name, description } = options;
   const state = loadState(false) || scaffoldState();
@@ -552,12 +380,6 @@ export async function createFeature(featureName, options = {}) {
   return { feature: state.features[featureName], created: true };
 }
 
-/**
- * Update feature property (supports nested keys like "approvalGates.plan.approved")
- * @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
@@ -579,11 +401,6 @@ export async function updateFeature(featureName, key, value) {
   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
@@ -607,33 +424,16 @@ export async function updateFeatureMultiple(featureName, updates) {
   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 = [];
 
@@ -651,9 +451,9 @@ function levenshteinDistance(a, b) {
         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
+          matrix[i - 1][j - 1] + 1,
+          matrix[i][j - 1] + 1,
+          matrix[i - 1][j] + 1
         );
       }
     }
@@ -662,12 +462,6 @@ function levenshteinDistance(a, b) {
   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;
@@ -677,14 +471,11 @@ function findClosestMatch(inputType, validTypes) {
   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) {
@@ -694,28 +485,20 @@ function findClosestMatch(inputType, validTypes) {
     }
   }
 
-  // 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 (plan, checks, verifierReport, 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);
 
@@ -723,7 +506,6 @@ export async function markOutput(featureName, outputType) {
 
     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',
@@ -745,7 +527,6 @@ export async function markOutput(featureName, outputType) {
   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)) {
@@ -762,13 +543,6 @@ export async function markOutput(featureName, outputType) {
   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();
@@ -788,13 +562,6 @@ export async function trackFileChange(featureName, filePath, action, phase) {
   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];
@@ -818,12 +585,6 @@ export function getFileChanges(featureName, options = {}) {
   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();
@@ -832,7 +593,6 @@ export async function skipPhase(featureName, phase, reason = '') {
     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({
@@ -846,11 +606,6 @@ export async function skipPhase(featureName, phase, reason = '') {
   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]) {
@@ -859,19 +614,11 @@ export function getSkippedPhases(featureName) {
   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 {
@@ -881,17 +628,6 @@ export function getSummary() {
   };
 }
 
-// ============================================================================
-// Approval Gates Operations
-// ============================================================================
-
-/**
- * Set approval gate status
- * @param {string} featureName - Feature name
- * @param {string} gate - Gate name (plan, uiux, 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);
@@ -915,12 +651,6 @@ export async function setApprovalGate(featureName, gate, approved, metadata = {}
   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];
@@ -932,11 +662,6 @@ export function getApprovalGate(featureName, gate) {
   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];
@@ -947,7 +672,6 @@ export function isPendingApproval(featureName) {
 
   const currentPhase = feature.phase || 'plan';
 
-  // Check if current phase has an approval gate
   const phaseGateMap = {
     'plan': 'plan',
     'review': 'review',
@@ -963,11 +687,6 @@ export function isPendingApproval(featureName) {
   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];
@@ -990,6 +709,5 @@ export function getApprovalHistory(featureName) {
     }
   });
 
-  // Sort by timestamp
   return history.sort((a, b) => new Date(a.timestamp) - new Date(b.timestamp));
 }