@polymorphism-tech/morph-spec 7.4.0 → 7.5.0

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

@@ -5,11 +5,21 @@
  * Used both by CLI commands and internal automation.
  */
 
-import { readFileSync, writeFileSync, renameSync, unlinkSync, existsSync, mkdirSync, rmdirSync, statSync } from 'fs';
+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';
 
 const STATE_FILE_NAME = '.morph/state.json';
+const FEATURES_DIR_NAME = '.morph/features';
+const FEATURE_FILE_NAME = 'feature.json';
+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.
+const STATE_VERSION = '5.0.0';
 
 // ============================================================================
 // Core Functions
@@ -21,6 +31,116 @@ const STATE_FILE_NAME = '.morph/state.json';
 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 [];
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
+/** Read a feature's feature.json, or null if missing/corrupt. */
+function readFeatureJson(featureName) {
+  const path = getFeatureJsonPath(featureName);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** 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;
+  try {
+    const cfg = JSON.parse(readFileSync(path, 'utf8'));
+    const p = cfg.project || cfg;
+    if (!p) return null;
+    const project = {};
+    if (p.name) project.name = p.name;
+    if (p.type) project.type = p.type;
+    return Object.keys(project).length ? project : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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.
+ */
+function atomicWriteJson(targetPath, data) {
+  const dir = dirname(targetPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  const tmpPath = `${targetPath}.tmp.${process.pid}`;
+  writeFileSync(tmpPath, JSON.stringify(data, null, 2), 'utf8');
+
+  const MAX_RETRIES = 5;
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      renameSync(tmpPath, targetPath);
+      return;
+    } catch (err) {
+      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 */ }
+        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 only costs a
+ * redundant (idempotent) write, never correctness.
+ */
+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)
+    }
+  } catch { /* fall through to a normal write */ }
+  atomicWriteJson(path, feature);
+}
+
+/** A fresh, empty state scaffold (used when no root index exists yet). */
+function scaffoldState() {
+  return {
+    version: STATE_VERSION,
+    project: readProjectFromConfig() || { name: '{PROJECT_NAME}', type: 'dotnet-nextjs' },
+    features: {},
+    threads: {},
+    metadata: { totalFeatures: 0, completedFeatures: 0, totalTimeSpent: 0 },
+  };
+}
 /**
  * Derive current phase from filesystem.
  *
@@ -38,6 +158,17 @@ export function getStatePath() {
  * @param {string} featurePath - Absolute path to .morph/features/{feature}/
  * @returns {string} Phase name: 'review' | 'implement' | 'plan' | 'uiux' | 'proposal'
  */
+const PHASE_INDEX = { proposal: 0, uiux: 1, plan: 2, implement: 3, review: 4 };
+
+/** Phase implied purely by approved gates (mirrors hook-side gateImpliedPhase). */
+function gateImpliedPhaseFromGates(gates) {
+  const ok = (g) => gates?.[g]?.approved === true;
+  if (ok('review')) return 'review';
+  if (ok('plan')) return 'implement';
+  if (ok('uiux')) return 'plan';
+  return 'proposal';
+}
+
 export function derivePhase(featurePath) {
   const phaseMap = [
     ['4-review',    'review',    'review-report.md'],
@@ -46,10 +177,21 @@ export function derivePhase(featurePath) {
     ['1-design',    'uiux',      'design-system.md'],
     ['0-proposal',  'proposal',  'proposal.md'],
   ];
+  let artifactPhase = 'proposal';
   for (const [folder, phase, canonical] of phaseMap) {
-    if (existsSync(join(featurePath, folder, canonical))) return phase;
+    if (existsSync(join(featurePath, folder, canonical))) { artifactPhase = phase; break; }
   }
-  return 'proposal';
+
+  // Gate-aware (same rule as the hook-side derivePhaseForFeature): an approved
+  // gate advances the phase before the next phase's canonical artifact exists,
+  // so the agent can actually write that first artifact.
+  let gates = null;
+  try {
+    const fjPath = join(featurePath, 'feature.json');
+    if (existsSync(fjPath)) gates = JSON.parse(readFileSync(fjPath, 'utf8'))?.approvalGates;
+  } catch { gates = null; }
+  const implied = gateImpliedPhaseFromGates(gates);
+  return PHASE_INDEX[implied] > PHASE_INDEX[artifactPhase] ? implied : artifactPhase;
 }
 
 /**
@@ -84,54 +226,88 @@ export function stateExists() {
  */
 export function loadState(throwOnError = true) {
   const statePath = getStatePath();
+  const rootExists = existsSync(statePath);
+  const featureNames = listFeatureNamesOnDisk();
+  const featuresExist = featureNames.some((name) => existsSync(getFeatureJsonPath(name)));
 
-  if (!existsSync(statePath)) {
+  // "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.`);
     }
     return null;
   }
 
+  let state;
   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');
+    state = rootExists ? JSON.parse(readFileSync(statePath, 'utf8')) : scaffoldState();
+  } catch (err) {
+    if (throwOnError) {
+      throw new Error(`Failed to parse state.json: ${err.message}`);
     }
+    return null;
+  }
+
+  state.features = state.features || {};
+  state.metadata = state.metadata || {};
+  if (!state.project || !state.project.name || state.project.name === '{PROJECT_NAME}') {
+    const fromConfig = readProjectFromConfig();
+    if (fromConfig) state.project = { ...(state.project || {}), ...fromConfig };
+  }
 
-    // Migrate v4.x -> v5.0.0: remove outputs and phase (now derived from
-    // filesystem) and workflow/workflowDetection (v5 has fixed phases, no
-    // workflow selection).
-    if (state.version && state.version.startsWith('4.')) {
-      state.version = '5.0.0';
-      for (const feature of Object.values(state.features || {})) {
-        delete feature.outputs;
-        delete feature.phase;
-        delete feature.workflow;
-        delete feature.workflowDetection;
+  // 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)) {
+      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');
     }
+    mutated = true;
+  }
 
-    return state;
-  } catch (err) {
-    if (throwOnError) {
-      throw new Error(`Failed to parse state.json: ${err.message}`);
+  // 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)) {
+      delete feature.outputs;
+      delete feature.phase;
+      delete feature.workflow;
+      delete feature.workflowDetection;
+    }
+    mutated = true;
+  }
+
+  // Split-on-load: any feature still living only in the root index (no
+  // feature.json yet) is written out to its authoritative per-feature file.
+  // This migrates pre-split monolithic state and is idempotent thereafter.
+  for (const [name, feature] of Object.entries(state.features)) {
+    if (!existsSync(getFeatureJsonPath(name))) {
+      writeFeatureJson(name, feature);
+      mutated = true;
     }
-    return null;
   }
+
+  // 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
+  }
+
+  return state;
 }
 
 /**
@@ -141,38 +317,34 @@ export function loadState(throwOnError = true) {
 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 });
+  state.version = state.version || STATE_VERSION;
+
+  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. This
+  //    is what travels with the feature's own commit — no cross-feature sweep.
+  const thinFeatures = {};
+  for (const [name, feature] of Object.entries(features)) {
+    writeFeatureJson(name, feature);
+    thinFeatures[name] = { status: feature.status, updatedAt: feature.updatedAt };
   }
 
-  // Atomic write: write to a per-process temp file then rename.
-  // Per-process name prevents two concurrent CLI invocations (e.g. `task done && task start`)
-  // from clobbering each other's temp file on Windows.
-  const tmpPath = `${statePath}.tmp.${process.pid}`;
-  writeFileSync(tmpPath, JSON.stringify(state, null, 2), 'utf8');
-
-  // Retry rename on EPERM — Windows holds a brief exclusive lock on the target
-  // when another process is reading it; a short backoff resolves the contention.
-  const MAX_RETRIES = 5;
-  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    try {
-      renameSync(tmpPath, statePath);
-      return;
-    } catch (err) {
-      if (err.code === 'EPERM' && attempt < MAX_RETRIES) {
-        // Synchronous sleep: CPU-friendly, works on Node.js main thread (v9.4+)
-        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50 * (attempt + 1));
-      } else {
-        try { unlinkSync(tmpPath); } catch { /* ignore cleanup errors */ }
-        throw err;
-      }
-    }
-  }
+  // 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,
+    threads: state.threads || {},
+    metadata: state.metadata,
+    features: thinFeatures,
+  });
 }
 
 // ============================================================================

package/src/dashboard/scanner/state-scanner.js

@@ -1,8 +1,35 @@
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
-
-export function scanState(projectDir) {
-  const statePath = join(projectDir, '.morph', 'state.json');
-  if (!existsSync(statePath)) return null;
-  try { return JSON.parse(readFileSync(statePath, 'utf8')); } catch { return null; }
-}
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+export function scanState(projectDir) {
+  const statePath = join(projectDir, '.morph', 'state.json');
+  let state = null;
+  if (existsSync(statePath)) {
+    try { state = JSON.parse(readFileSync(statePath, 'utf8')); } catch { state = null; }
+  }
+
+  // Hydrate full feature objects from the authoritative per-feature files. The
+  // root state.json is now a thin, derivable index (status + updatedAt only), so
+  // the dashboard must read .morph/features/{name}/feature.json for full data.
+  const featuresDir = join(projectDir, '.morph', 'features');
+  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, 'utf8'));
+        state = state || { features: {} };
+        state.features = state.features || {};
+        state.features[name] = fj;
+      } catch { /* skip a corrupt feature.json */ }
+    }
+  }
+
+  return state;
+}

package/src/lib/generators/context-generator.js

@@ -309,19 +309,23 @@ export async function generateFeatureContext(projectPath, featureName) {
     loadAgents(projectPath)
   ]);
 
-  // Find feature in state (handle both array and object format)
+  // Find the feature. The authoritative per-feature state lives in
+  // .morph/features/{name}/feature.json (the root state.json is now a thin
+  // index); read it directly, falling back to the index for back-compat.
   let feature;
-  if (Array.isArray(state?.features)) {
-    feature = state.features.find(f => f.name === featureName);
-  } else if (state?.features && typeof state.features === 'object') {
-    feature = state.features[featureName];
-    if (feature) {
-      feature = { name: featureName, ...feature };
+  try {
+    const fjPath = path.join(projectPath, '.morph/features', featureName, 'feature.json');
+    feature = { name: featureName, ...JSON.parse(await fs.readFile(fjPath, 'utf8')) };
+  } catch {
+    if (Array.isArray(state?.features)) {
+      feature = state.features.find(f => f.name === featureName);
+    } else if (state?.features && typeof state.features === 'object' && state.features[featureName]) {
+      feature = { name: featureName, ...state.features[featureName] };
     }
   }
 
   if (!feature) {
-    throw new Error(`Feature "${featureName}" not found in state.json`);
+    throw new Error(`Feature "${featureName}" not found in .morph/features/ or state.json`);
   }
 
   // Load feature outputs

package/src/utils/file-copier.js

@@ -138,6 +138,13 @@ export async function updateGitignore(projectPath) {
   const morphRules = [
     '',
     '# MORPH-SPEC',
+    // Derivable, per-machine state index — rebuilt from the committed
+    // .morph/features/{feature}/feature.json files. Never commit it: doing so
+    // sweeps every feature's accumulated diffs into one commit. The feature
+    // state that matters travels inside each feature folder (which IS committed).
+    '.morph/state.json',
+    '.morph/state.json.tmp.*',
+    '.morph/state.json.lock/',
     '.morph/framework/',
     '.morph/memory/',
     '.morph/plans/',