@polymorphism-tech/morph-spec 7.4.0 → 7.5.0

package/framework/hooks/claude-code/core/state-sync.js

@@ -11,11 +11,9 @@
  *  - AskUserQuestion answered with option starting "aprovado"        → advance gate
  */
 
-import { readFileSync, existsSync, renameSync, writeFileSync } from 'fs';
-import { join } from 'path';
+import { readFileSync } from 'fs';
 import { loadState, stateExists } from '../../shared/state-reader.js';
-
-const STATE_FILE = '.morph/state.json';
+import { persistFeature, setGateApproved, createDefaultFeature } from '../../shared/state-writer.js';
 
 const PHASE_FOLDERS = {
   '0-proposal': 'proposal',
@@ -64,31 +62,12 @@ function extractFilename(filePath) {
   return normalized.split('/').pop();
 }
 
-/**
- * Atomic write — temp file then rename. Mirrors state-manager.js semantics.
- */
-function writeStateAtomic(cwd, state) {
-  const path = join(cwd, STATE_FILE);
-  const tmpPath = `${path}.tmp.${process.pid}`;
-  writeFileSync(tmpPath, JSON.stringify(state, null, 2), 'utf8');
-  renameSync(tmpPath, path);
-}
-
 function registerFeatureIfMissing(state, featureName) {
   if (!state.features) state.features = {};
   if (state.features[featureName]) return false;
 
-  const now = new Date().toISOString();
-  state.features[featureName] = {
-    status: 'in_progress',
-    createdAt: now,
-    updatedAt: now,
-    approvalGates: { proposal: false, plan: false, review: false },
-    outputs: {},
-  };
-
-  if (!state.metadata) state.metadata = {};
-  state.metadata.totalFeatures = Object.keys(state.features).length;
+  // Canonical object-form gates (incl. optional uiux) — no boolean drift.
+  state.features[featureName] = createDefaultFeature();
   return true;
 }
 
@@ -151,7 +130,9 @@ function handleWriteEdit(input, cwd) {
   }
 
   if (changed) {
-    writeStateAtomic(cwd, state);
+    // Persist the touched feature to its authoritative feature.json and refresh
+    // the thin root index. The feature's state thus travels in its own folder.
+    persistFeature(featureName, state.features[featureName], cwd);
   }
   return true;
 }
@@ -166,34 +147,21 @@ function handleAskUserQuestion(input, cwd) {
   const featureName = findActiveFeature(state);
   if (!featureName) return false;
 
-  let changed = false;
   for (const [question, answer] of Object.entries(answers)) {
     if (!isApprovalAnswer(answer)) continue;
     const gate = gateFromQuestion(question);
     if (!gate) continue;
 
-    state.features[featureName].approvalGates ??= {};
-    const existing = state.features[featureName].approvalGates[gate];
+    const existing = state.features[featureName].approvalGates?.[gate];
     const alreadyApproved = existing === true || existing?.approved === true;
-    if (!alreadyApproved) {
-      // An "aprovado" answer to AskUserQuestion is a human approving in the
-      // loop — record it as such. Write the canonical gate shape
-      // ({ approved, timestamp, approvedBy }) used by setApprovalGate so the
-      // audit trail is consistent and a manual approval is distinguishable
-      // from a policy auto-approval (approvedBy: "auto").
-      const now = new Date().toISOString();
-      state.features[featureName].approvalGates[gate] = {
-        approved: true,
-        timestamp: now,
-        approvedBy: 'manual'
-      };
-      state.features[featureName].updatedAt = now;
-      changed = true;
-    }
-  }
-
-  if (changed) {
-    writeStateAtomic(cwd, state);
+    if (alreadyApproved) continue;
+
+    // An "aprovado" answer to AskUserQuestion is a human approving in the loop.
+    // Route through the shared canonical gate writer so the hook and the CLI
+    // (`morph-spec approve`) produce one consistent shape
+    // ({ approved, timestamp, approvedBy }) in the authoritative feature.json —
+    // and a manual approval stays distinguishable from a policy auto-approval.
+    setGateApproved(featureName, gate, { approvedBy: 'manual' }, cwd);
   }
   return true;
 }

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

@@ -7,22 +7,62 @@
  * - Uses synchronous reads for <100ms performance
  */
 
-import { readFileSync, existsSync } from 'fs';
+import { readFileSync, existsSync, readdirSync } from 'fs';
 import { join } from 'path';
 
 const STATE_FILE = '.morph/state.json';
+const FEATURES_DIR = '.morph/features';
 
 /**
- * Load state.json from the project root.
- * Fail-open: returns null if file missing or corrupt.
+ * 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 statePath = join(projectPath || process.cwd(), STATE_FILE);
-    if (!existsSync(statePath)) return null;
-    return JSON.parse(readFileSync(statePath, 'utf-8'));
+    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;
   }
@@ -119,6 +159,25 @@ export function getFeature(featureName, projectPath) {
  * @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 = [
@@ -128,10 +187,17 @@ export function derivePhaseForFeature(featureName, projectPath) {
     ['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))) return phase;
+    if (existsSync(join(basePath, folder, canonical))) { artifactPhase = phase; break; }
   }
-  return 'proposal';
+
+  // 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;
 }
 
 /**

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: {},
+  };
+}

package/framework/rules/morph-task-tracking.md

@@ -1,49 +1,69 @@
----
-stacks:
-  - "*"
----
-
-# MORPH-SPEC Task Tracking
-
-> Session tasks are MANDATORY in every MORPH-SPEC phase. They track real progress and must be
-> created BEFORE any phase work begins.
-
-## Rules
-
-1. **Every phase skill MUST create session tasks** using `TaskCreate` before reading files or generating outputs
-2. **Tasks are dynamic** — analyze the phase workflow and create tasks that reflect YOUR actual planned actions for this session
-3. **Every task MUST be updated**: `in_progress` before starting, `completed` after finishing
-4. **Pipeline orchestrators** (`/morph-proposal`, `/morph-apply`) MUST create master tasks for each phase
-5. **Never skip task creation** — even if resuming mid-phase, create tasks for remaining steps
-6. **Granularity**: minimum 2, typically 3-7 tasks per phase — adjust to complexity
-7. **For iterative work** (clarification rounds, quality loops): update task `subject` with round/score progress
-
-## Task Update Pattern
-
-```
-TaskUpdate(taskId, status="in_progress")   // before starting the step
-// ... do the work ...
-TaskUpdate(taskId, status="completed")     // after step finishes
-```
-
-For iterative tasks:
-```
-TaskUpdate(taskId, subject="Round 3 — score 82/100")
-```
-
-## Deviation Tracking
-
-When completing a task differently than originally planned, record the reason:
-
-```
-morph-spec task done <feature> <taskId> --note "Reason for deviation"
-```
-
-For after-the-fact annotation (supports multiple types):
-```
-morph-spec task annotate <feature> <taskId> "Reason" --type deviation
-morph-spec task annotate <feature> <taskId> "Context info" --type context
-morph-spec task annotate <feature> <taskId> "Resolved" --type blocker-resolved
-```
-
-Note types: `deviation` (default), `context`, `blocker-resolved`
+---
+stacks:
+  - "*"
+---
+
+# MORPH-SPEC Task Tracking
+
+> Session tasks are MANDATORY in every MORPH-SPEC phase. They track real progress and must be
+> created BEFORE any phase work begins.
+
+## Rules
+
+1. **Every phase skill MUST create session tasks** using `TaskCreate` before reading files or generating outputs
+2. **Tasks are dynamic** — analyze the phase workflow and create tasks that reflect YOUR actual planned actions for this session
+3. **Every task MUST be updated**: `in_progress` before starting, `completed` after finishing
+4. **Pipeline orchestrators** (`/morph-proposal`, `/morph-apply`) MUST create master tasks for each phase
+5. **Never skip task creation** — even if resuming mid-phase, create tasks for remaining steps
+6. **Granularity**: minimum 2, typically 3-7 tasks per phase — adjust to complexity
+7. **For iterative work** (clarification rounds, quality loops): update task `subject` with round/score progress
+
+## Task Update Pattern
+
+```
+TaskUpdate(taskId, status="in_progress")   // before starting the step
+// ... do the work ...
+TaskUpdate(taskId, status="completed")     // after step finishes
+```
+
+For iterative tasks:
+```
+TaskUpdate(taskId, subject="Round 3 — score 82/100")
+```
+
+## Persisting Progress to `tasks.json`
+
+Native session tasks (`TaskCreate`/`TaskUpdate`) track your live work. To persist
+task progress for the feature, write `.morph/features/{feature}/2-plan/tasks.json`,
+touching ONLY the mutable fields:
+
+- `status` — `pending` → `in_progress` → `completed`
+- `outputs` — the files the task produced
+- `notes` — free-text record (deviations, context, resolved blockers)
+
+The plan contract — `title`, `description`, `dependencies`, `effort`, `doneCriteria`,
+`group` — is frozen after Gate 2. Any attempt to change it is blocked by the
+`protect-spec-files` hook.
+
+Use the `Write` tool (whole-file rewrite) OR the `Edit` tool — `Edit` is allowed
+as long as it touches only `status`, `outputs`, and `notes`. State is then synced
+automatically by the `state-sync` PostToolUse hook; you do not call a CLI to mark
+output.
+
+## Deviation Tracking
+
+When completing a task differently than originally planned, record the reason in the
+task's `notes` field. Use the `notes` array to capture deviations, added context, or
+resolved blockers — for example:
+
+```json
+{
+  "id": "T3",
+  "status": "completed",
+  "outputs": ["Features/User/Update/Handler.cs"],
+  "notes": [
+    "deviation: split validation into a separate validator for testability",
+    "blocker-resolved: EF migration conflict fixed by regenerating the snapshot"
+  ]
+}
+```