@polymorphism-tech/morph-spec 7.3.0 → 7.5.0

package/framework/hooks/shared/state-reader.js

@@ -1,221 +1,302 @@
-/**
- * Shared read-only state accessor for Claude Code hooks.
- *
- * Wraps state.json reads with fail-open semantics:
- * - Returns null instead of throwing on missing/corrupt state
- * - Never writes to state.json (read-only)
- * - Uses synchronous reads for <100ms performance
- */
-
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
-
-const STATE_FILE = '.morph/state.json';
-
-/**
- * Load state.json from the project root.
- * Fail-open: returns null if file missing or corrupt.
- * @param {string} [projectPath] - Project root (defaults to cwd)
- * @returns {Object|null} State object or null
- */
-export function loadState(projectPath) {
-  try {
-    const statePath = join(projectPath || process.cwd(), STATE_FILE);
-    if (!existsSync(statePath)) return null;
-    return JSON.parse(readFileSync(statePath, 'utf-8'));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Check if state.json exists.
- * @param {string} [projectPath]
- * @returns {boolean}
- */
-export function stateExists(projectPath) {
-  return existsSync(join(projectPath || process.cwd(), STATE_FILE));
-}
-
-/**
- * Get the active feature (most recently updated in_progress feature).
- * @param {string} [projectPath]
- * @returns {{ name: string, feature: Object }|null}
- */
-export function getActiveFeature(projectPath) {
-  const state = loadState(projectPath);
-  if (!state?.features) return null;
-
-  let active = null;
-  let latestUpdate = '';
-
-  for (const [name, feature] of Object.entries(state.features)) {
-    if (feature.status === 'in_progress' || feature.status === 'draft') {
-      const updated = feature.updatedAt || feature.createdAt || '';
-      if (updated >= latestUpdate) {
-        latestUpdate = updated;
-        active = { name, feature };
-      }
-    }
-  }
-
-  return active;
-}
-
-/**
- * Get the most recently updated feature (any status).
- * Useful as a fallback when getActiveFeature returns null (all features done).
- * @param {string} [projectPath]
- * @returns {{ name: string, feature: Object }|null}
- */
-export function getMostRecentFeature(projectPath) {
-  const state = loadState(projectPath);
-  if (!state?.features) return null;
-
-  let result = null;
-  let latestUpdate = '';
-
-  for (const [name, feature] of Object.entries(state.features)) {
-    const updated = feature.updatedAt || feature.createdAt || '';
-    if (updated >= latestUpdate) {
-      latestUpdate = updated;
-      result = { name, feature };
-    }
-  }
-
-  return result;
-}
-
-/**
- * Get a specific feature by name.
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {Object|null}
- */
-export function getFeature(featureName, projectPath) {
-  const state = loadState(projectPath);
-  return state?.features?.[featureName] || null;
-}
-
-/**
- * Derive phase from filesystem (phase deleted from state).
- * Checks for phase folders in descending order, returns highest present.
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {string} Phase name
- */
-export function derivePhaseForFeature(featureName, projectPath) {
-  const basePath = join(projectPath || process.cwd(), '.morph/features', featureName);
-  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(basePath, folder))) return phase;
-  }
-  return 'proposal';
-}
-
-/**
- * Get the current phase of a feature.
- * Falls back to filesystem derivation when phase is not in state.
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {string|null}
- */
-export function getFeaturePhase(featureName, projectPath) {
-  const feature = getFeature(featureName, projectPath);
-  if (!feature) return null;
-  return feature.phase || derivePhaseForFeature(featureName, projectPath);
-}
-
-/**
- * Get approval status for a gate.
- * @param {string} featureName
- * @param {string} gate - 'proposal'|'uiux'|'plan'|'review'
- * @param {string} [projectPath]
- * @returns {boolean}
- */
-export function isGateApproved(featureName, gate, projectPath) {
-  const feature = getFeature(featureName, projectPath);
-  // Support both field names: 'approvals' (v5 state) and 'approvalGates' (legacy)
-  const gates = feature?.approvals || feature?.approvalGates;
-  return gates?.[gate]?.approved === true;
-}
-
-/**
- * Get all pending approval gates for a feature.
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {string[]} List of gate names that are not yet approved
- */
-export function getPendingGates(featureName, projectPath) {
-  const feature = getFeature(featureName, projectPath);
-  // Support both field names: 'approvals' (v5 state) and 'approvalGates' (legacy)
-  const gates = feature?.approvals || feature?.approvalGates;
-  if (!gates) return [];
-
-  return Object.entries(gates)
-    .filter(([, gate]) => !gate.approved)
-    .map(([name]) => name);
-}
-
-/**
- * Get feature outputs status.
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {Object|null} outputs map or null
- */
-export function getOutputs(featureName, projectPath) {
-  const feature = getFeature(featureName, projectPath);
-  return feature?.outputs || null;
-}
-
-/**
- * Get uncompleted required outputs for current phase.
- * @param {string} featureName
- * @param {string} [projectPath]
- * @returns {Array<{type: string, path: string}>}
- */
-/**
- * Get task statistics directly from taskList (preferred over feature.tasks counters).
- * Excludes expanded tasks from counts, matching calculateProgress() behavior.
- *
- * @param {Object} feature - Feature state object
- * @returns {{ total: number, completed: number, inProgress: number, pending: number }}
- */
-export function getTaskStats(feature) {
-  const list = feature?.taskList || [];
-  if (list.length > 0) {
-    const active = list.filter(t => t.status !== 'expanded');
-    return {
-      total: active.length,
-      completed: active.filter(t => t.status === 'completed').length,
-      inProgress: active.filter(t => t.status === 'in_progress').length,
-      pending: active.filter(t => t.status === 'pending').length,
-    };
-  }
-  // Fallback: read from legacy counter object
-  const tasks = feature?.tasks;
-  if (tasks && typeof tasks === 'object' && !Array.isArray(tasks)) {
-    return {
-      total: tasks.total || 0,
-      completed: tasks.completed || 0,
-      inProgress: tasks.inProgress || 0,
-      pending: tasks.pending || 0,
-    };
-  }
-  return { total: 0, completed: 0, inProgress: 0, pending: 0 };
-}
-
-export function getMissingOutputs(featureName, projectPath) {
-  const feature = getFeature(featureName, projectPath);
-  if (!feature?.outputs) return [];
-
-  return Object.entries(feature.outputs)
-    .filter(([, output]) => !output.created)
-    .map(([type, output]) => ({ type, path: output.path }));
-}
+/**
+ * Shared read-only state accessor for Claude Code hooks.
+ *
+ * Wraps state.json reads with fail-open semantics:
+ * - Returns null instead of throwing on missing/corrupt state
+ * - Never writes to state.json (read-only)
+ * - Uses synchronous reads for <100ms performance
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+const STATE_FILE = '.morph/state.json';
+const FEATURES_DIR = '.morph/features';
+
+/**
+ * Load state from the project root, hydrating each feature from its
+ * authoritative per-feature `feature.json`.
+ *
+ * The root `.morph/state.json` is a thin, gitignored index (status + updatedAt
+ * per feature); the heavy feature data lives in `.morph/features/{name}/feature.json`
+ * (committed). This reader merges them: it reads the thin index for project /
+ * metadata and overlays each feature.json so callers see the full feature object.
+ * A single corrupt feature.json is skipped, not fatal.
+ *
+ * Fail-open: returns null on any unexpected error or when there is no state at
+ * all (no index and no feature files).
+ * @param {string} [projectPath] - Project root (defaults to cwd)
+ * @returns {Object|null} State object or null
+ */
+export function loadState(projectPath) {
+  try {
+    const base = projectPath || process.cwd();
+    const statePath = join(base, STATE_FILE);
+
+    let state = null;
+    if (existsSync(statePath)) {
+      state = JSON.parse(readFileSync(statePath, 'utf-8'));
+    }
+
+    const featuresDir = join(base, FEATURES_DIR);
+    if (existsSync(featuresDir)) {
+      let names = [];
+      try {
+        names = readdirSync(featuresDir, { withFileTypes: true })
+          .filter((e) => e.isDirectory())
+          .map((e) => e.name);
+      } catch {
+        names = [];
+      }
+      for (const name of names) {
+        const fjPath = join(featuresDir, name, 'feature.json');
+        if (!existsSync(fjPath)) continue;
+        try {
+          const fj = JSON.parse(readFileSync(fjPath, 'utf-8'));
+          state = state || { features: {} };
+          state.features = state.features || {};
+          state.features[name] = fj; // feature.json is authoritative
+        } catch {
+          // skip a single corrupt feature.json — don't blind every hook
+        }
+      }
+    }
+
+    return state;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check if state.json exists.
+ * @param {string} [projectPath]
+ * @returns {boolean}
+ */
+export function stateExists(projectPath) {
+  return existsSync(join(projectPath || process.cwd(), STATE_FILE));
+}
+
+/**
+ * Get the active feature (most recently updated in_progress feature).
+ * @param {string} [projectPath]
+ * @returns {{ name: string, feature: Object }|null}
+ */
+export function getActiveFeature(projectPath) {
+  const state = loadState(projectPath);
+  if (!state?.features) return null;
+
+  let active = null;
+  let latestUpdate = '';
+
+  for (const [name, feature] of Object.entries(state.features)) {
+    if (feature.status === 'in_progress' || feature.status === 'draft') {
+      const updated = feature.updatedAt || feature.createdAt || '';
+      if (updated >= latestUpdate) {
+        latestUpdate = updated;
+        active = { name, feature };
+      }
+    }
+  }
+
+  return active;
+}
+
+/**
+ * Get the most recently updated feature (any status).
+ * Useful as a fallback when getActiveFeature returns null (all features done).
+ * @param {string} [projectPath]
+ * @returns {{ name: string, feature: Object }|null}
+ */
+export function getMostRecentFeature(projectPath) {
+  const state = loadState(projectPath);
+  if (!state?.features) return null;
+
+  let result = null;
+  let latestUpdate = '';
+
+  for (const [name, feature] of Object.entries(state.features)) {
+    const updated = feature.updatedAt || feature.createdAt || '';
+    if (updated >= latestUpdate) {
+      latestUpdate = updated;
+      result = { name, feature };
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Get a specific feature by name.
+ * @param {string} featureName
+ * @param {string} [projectPath]
+ * @returns {Object|null}
+ */
+export function getFeature(featureName, projectPath) {
+  const state = loadState(projectPath);
+  return state?.features?.[featureName] || null;
+}
+
+/**
+ * Derive phase from filesystem (phase deleted from state).
+ *
+ * Walks the phase map in descending order and returns the first phase whose
+ * CANONICAL ARTIFACT exists. An empty folder is not enough — this avoids the
+ * chicken-and-egg problem where `mkdir 2-plan/` (or any pre-created sibling)
+ * advances the phase before plan content is written, then
+ * `enforce-phase-writes` blocks writes back to `0-proposal/`.
+ *
+ * Canonical artifacts (one per phase) match MORPH.md §3:
+ *   - 4-review  → review-report.md
+ *   - 3-implement → recap.md
+ *   - 2-plan    → spec.md  (the first plan-phase output produced)
+ *   - 1-design  → design-system.md
+ *   - 0-proposal → proposal.md
+ *
+ * If no canonical file is found, returns `'proposal'` (the starting phase).
+ *
+ * @param {string} featureName
+ * @param {string} [projectPath]
+ * @returns {string} Phase name
+ */
+export const PHASE_INDEX = { proposal: 0, uiux: 1, plan: 2, implement: 3, review: 4 };
+
+/**
+ * The phase implied purely by approved gates, independent of which artifacts
+ * exist on disk. An approved gate authorizes the NEXT phase, so:
+ *   review approved  → review   (terminal)
+ *   plan approved    → implement
+ *   uiux approved    → plan
+ *   otherwise        → proposal  (proposal-approval's fork between uiux/plan is
+ *                                 resolved by enforce-phase-writes, not here)
+ * @returns {string} phase name
+ */
+export function gateImpliedPhase(featureName, projectPath) {
+  if (isGateApproved(featureName, 'review', projectPath)) return 'review';
+  if (isGateApproved(featureName, 'plan', projectPath)) return 'implement';
+  if (isGateApproved(featureName, 'uiux', projectPath)) return 'plan';
+  return 'proposal';
+}
+
+export function derivePhaseForFeature(featureName, projectPath) {
+  const basePath = join(projectPath || process.cwd(), '.morph/features', featureName);
+  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'],
+  ];
+  let artifactPhase = 'proposal';
+  for (const [folder, phase, canonical] of phaseMap) {
+    if (existsSync(join(basePath, folder, canonical))) { artifactPhase = phase; break; }
+  }
+
+  // Gate-aware: an approved gate advances the phase even before the next
+  // phase's first canonical artifact exists. This breaks the chicken-and-egg
+  // where that first artifact could never be written because the phase never
+  // advanced to permit it. Take whichever of (artifact, gate-implied) is later.
+  const implied = gateImpliedPhase(featureName, projectPath);
+  return PHASE_INDEX[implied] > PHASE_INDEX[artifactPhase] ? implied : artifactPhase;
+}
+
+/**
+ * Get the current phase of a feature.
+ * Falls back to filesystem derivation when phase is not in state.
+ * @param {string} featureName
+ * @param {string} [projectPath]
+ * @returns {string|null}
+ */
+export function getFeaturePhase(featureName, projectPath) {
+  const feature = getFeature(featureName, projectPath);
+  if (!feature) return null;
+  return feature.phase || derivePhaseForFeature(featureName, projectPath);
+}
+
+/**
+ * Get approval status for a gate.
+ * @param {string} featureName
+ * @param {string} gate - 'proposal'|'uiux'|'plan'|'review'
+ * @param {string} [projectPath]
+ * @returns {boolean}
+ */
+export function isGateApproved(featureName, gate, projectPath) {
+  const feature = getFeature(featureName, projectPath);
+  // Support both field names: 'approvals' (v5 state) and 'approvalGates' (legacy)
+  const gates = feature?.approvals || feature?.approvalGates;
+  return gates?.[gate]?.approved === true;
+}
+
+/**
+ * Get all pending approval gates for a feature.
+ * @param {string} featureName
+ * @param {string} [projectPath]
+ * @returns {string[]} List of gate names that are not yet approved
+ */
+export function getPendingGates(featureName, projectPath) {
+  const feature = getFeature(featureName, projectPath);
+  // Support both field names: 'approvals' (v5 state) and 'approvalGates' (legacy)
+  const gates = feature?.approvals || feature?.approvalGates;
+  if (!gates) return [];
+
+  return Object.entries(gates)
+    .filter(([, gate]) => !gate.approved)
+    .map(([name]) => name);
+}
+
+/**
+ * Get feature outputs status.
+ * @param {string} featureName
+ * @param {string} [projectPath]
+ * @returns {Object|null} outputs map or null
+ */
+export function getOutputs(featureName, projectPath) {
+  const feature = getFeature(featureName, projectPath);
+  return feature?.outputs || null;
+}
+
+/**
+ * Get uncompleted required outputs for current phase.
+ * @param {string} featureName
+ * @param {string} [projectPath]
+ * @returns {Array<{type: string, path: string}>}
+ */
+/**
+ * Get task statistics directly from taskList (preferred over feature.tasks counters).
+ * Excludes expanded tasks from counts, matching calculateProgress() behavior.
+ *
+ * @param {Object} feature - Feature state object
+ * @returns {{ total: number, completed: number, inProgress: number, pending: number }}
+ */
+export function getTaskStats(feature) {
+  const list = feature?.taskList || [];
+  if (list.length > 0) {
+    const active = list.filter(t => t.status !== 'expanded');
+    return {
+      total: active.length,
+      completed: active.filter(t => t.status === 'completed').length,
+      inProgress: active.filter(t => t.status === 'in_progress').length,
+      pending: active.filter(t => t.status === 'pending').length,
+    };
+  }
+  // Fallback: read from legacy counter object
+  const tasks = feature?.tasks;
+  if (tasks && typeof tasks === 'object' && !Array.isArray(tasks)) {
+    return {
+      total: tasks.total || 0,
+      completed: tasks.completed || 0,
+      inProgress: tasks.inProgress || 0,
+      pending: tasks.pending || 0,
+    };
+  }
+  return { total: 0, completed: 0, inProgress: 0, pending: 0 };
+}
+
+export function getMissingOutputs(featureName, projectPath) {
+  const feature = getFeature(featureName, projectPath);
+  if (!feature?.outputs) return [];
+
+  return Object.entries(feature.outputs)
+    .filter(([, output]) => !output.created)
+    .map(([type, output]) => ({ type, path: output.path }));
+}

package/framework/hooks/shared/state-writer.js

@@ -0,0 +1,124 @@
+/**
+ * Shared per-feature state writer for Claude Code hooks.
+ *
+ * Hooks run inside the user's project and cannot import the CLI's
+ * src/core/state-manager.js. This module is the hook-side mirror of the core
+ * writers: it persists a feature to its authoritative `feature.json` (committed)
+ * and refreshes the thin, gitignored root index (`.morph/state.json`).
+ *
+ * Fail-open by contract: every function swallows errors and returns a boolean —
+ * a hook must never break the agent over a state write.
+ */
+
+import { readFileSync, writeFileSync, renameSync, unlinkSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+
+const STATE_FILE = '.morph/state.json';
+const STATE_VERSION = '5.0.0';
+
+/** Absolute path to a feature's authoritative feature.json. */
+export function featureJsonPath(featureName, projectPath) {
+  return join(projectPath || process.cwd(), '.morph', 'features', featureName, 'feature.json');
+}
+
+/** Read a feature's feature.json, or null if missing/corrupt. */
+export function readFeatureFile(featureName, projectPath) {
+  const p = featureJsonPath(featureName, projectPath);
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Atomic JSON write: per-pid temp then rename, with an EPERM retry for Windows. */
+function atomicWriteJson(targetPath, data) {
+  const dir = dirname(targetPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const tmp = `${targetPath}.tmp.${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf-8');
+  for (let attempt = 0; attempt <= 5; attempt++) {
+    try {
+      renameSync(tmp, targetPath);
+      return;
+    } catch (err) {
+      if (err.code === 'EPERM' && attempt < 5) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50 * (attempt + 1));
+      } else {
+        try { unlinkSync(tmp); } catch { /* ignore */ }
+        throw err;
+      }
+    }
+  }
+}
+
+/**
+ * Persist a feature to its authoritative feature.json and refresh the thin root
+ * index entry (status + updatedAt) + aggregate metadata. Returns true on
+ * success, false fail-open.
+ */
+export function persistFeature(featureName, feature, projectPath) {
+  try {
+    atomicWriteJson(featureJsonPath(featureName, projectPath), feature);
+
+    const statePath = join(projectPath || process.cwd(), STATE_FILE);
+    let root = {};
+    if (existsSync(statePath)) {
+      try { root = JSON.parse(readFileSync(statePath, 'utf-8')); } catch { root = {}; }
+    }
+    root.version = root.version || STATE_VERSION;
+    root.features = root.features || {};
+    root.features[featureName] = { status: feature.status, updatedAt: feature.updatedAt };
+    root.metadata = root.metadata || {};
+    root.metadata.totalFeatures = Object.keys(root.features).length;
+    atomicWriteJson(statePath, root);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Canonical gate-approval writer (hook-side mirror of CLI setApprovalGate).
+ * Stamps approvalGates[gate] = { approved, timestamp, approvedBy } — the single
+ * canonical shape — onto the feature and persists it. Returns true on success.
+ *
+ * @param {string} featureName
+ * @param {string} gate - 'proposal'|'uiux'|'plan'|'review'
+ * @param {{ approvedBy?: string, timestamp?: string }} [meta]
+ * @param {string} [projectPath]
+ */
+export function setGateApproved(featureName, gate, meta = {}, projectPath) {
+  try {
+    const feature = readFeatureFile(featureName, projectPath) || createDefaultFeature();
+    const now = new Date().toISOString();
+    feature.approvalGates = feature.approvalGates || {};
+    feature.approvalGates[gate] = {
+      approved: true,
+      timestamp: meta.timestamp || now,
+      approvedBy: meta.approvedBy || 'manual',
+    };
+    feature.updatedAt = now;
+    return persistFeature(featureName, feature, projectPath);
+  } catch {
+    return false;
+  }
+}
+
+/** Default feature shape (canonical object-form gates, incl. optional uiux). */
+export function createDefaultFeature() {
+  const now = new Date().toISOString();
+  return {
+    status: 'in_progress',
+    createdAt: now,
+    updatedAt: now,
+    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 },
+    },
+    outputs: {},
+  };
+}