@polymorphism-tech/morph-spec 7.4.0 → 7.6.0

package/framework/hooks/claude-code/core/protect-spec-files.js

@@ -11,11 +11,14 @@
  *
  * Semantic exception for files in MUTABLE_SPEC_FIELDS (e.g. tasks.json):
  * the plan contract is frozen, but per-task progress fields (status, outputs,
- * notes) may still change during the implement phase. For those files a Write
- * is allowed only when the semantic diff touches solely the mutable fields;
- * Edit is always blocked because the legitimate progress path is a full Write
- * via writeTasksJson(). This lets the implement phase record task status
- * without unfreezing the plan.
+ * notes) may still change during the implement phase. For those files BOTH a
+ * full Write and a targeted Edit are allowed — but only when the semantic diff
+ * touches solely the mutable fields. The Edit is simulated (old_string →
+ * new_string applied to the current file) and diffed exactly like a Write, so a
+ * one-field status flip via Edit is permitted while any change to the frozen
+ * plan contract (titles, dependencies, doneCriteria, the task set) is blocked.
+ * This is the sanctioned progress path — the agent never has to rewrite the
+ * whole file nor reach for a Node script to record task status.
  *
  * Fail-open: exits 0 on any error.
  */
@@ -129,40 +132,39 @@ try {
   // that touches only those fields. Anything else stays blocked.
   if (mutableFields) {
     const toolName = getToolName(payload);
-    const newContent = payload?.tool_input?.content;
-
-    // Edit is never the legitimate progress path — progress is written as a
-    // full file via writeTasksJson(). Block Edit; fall through to the message.
-    if (toolName !== 'Write' || typeof newContent !== 'string') {
-      logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
-      block(
-        `MORPH-SPEC: '${filename}' is locked — the '${requiredGate}' gate has been approved.\n` +
-        `Progress updates (${mutableFields.join(', ')}) must be written as a full-file\n` +
-        `Write, not an Edit. The plan contract (titles, dependencies, doneCriteria…)\n` +
-        `is frozen. To change the plan itself, ask the user to revoke the\n` +
-        `'${requiredGate}' gate in .morph/state.json, then re-present it for approval.`
-      );
-    }
 
-    // Semantic diff: old = current file on disk, new = proposed content.
-    // Any failure to read/parse → fail-open (pass), never a false block.
+    // Build the proposed document from either a full Write or a targeted Edit,
+    // then semantic-diff it against the current file on disk. Any failure to
+    // read / parse / apply → fail-open (pass), never a false block.
+    const absPath = isAbsolute(filePath) ? filePath : join(process.cwd(), filePath);
     let oldDoc, newDoc;
     try {
-      // filePath may already be absolute (Claude Code usually sends absolute
-      // paths); only join against cwd when it is relative.
-      const absPath = isAbsolute(filePath) ? filePath : join(process.cwd(), filePath);
-      oldDoc = JSON.parse(readFileSync(absPath, 'utf-8'));
-      newDoc = JSON.parse(newContent);
+      const original = readFileSync(absPath, 'utf-8');
+      oldDoc = JSON.parse(original);
+
+      if (toolName === 'Edit') {
+        // Simulate the edit: apply old_string → new_string to the current file.
+        const oldStr = payload?.tool_input?.old_string;
+        const newStr = payload?.tool_input?.new_string;
+        if (typeof oldStr !== 'string' || typeof newStr !== 'string') throw new Error('no edit strings');
+        const edited = payload?.tool_input?.replace_all
+          ? original.split(oldStr).join(newStr)
+          : original.replace(oldStr, newStr);
+        newDoc = JSON.parse(edited);
+      } else {
+        const newContent = payload?.tool_input?.content;
+        if (typeof newContent !== 'string') throw new Error('no content');
+        newDoc = JSON.parse(newContent);
+      }
     } catch {
-      // Cannot compare — fail-open rather than block a possibly-valid write.
       logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
       pass();
     }
 
     const violations = diffPlanContract(oldDoc, newDoc, mutableFields);
     if (violations.length === 0) {
-      // Only mutable progress fields changed — this is a legitimate
-      // implement-phase update.
+      // Only mutable progress fields changed — a legitimate implement-phase
+      // update via Write OR Edit.
       logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
       pass();
     }
@@ -170,7 +172,7 @@ try {
     logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
     block(
       `MORPH-SPEC: '${filename}' is locked — the '${requiredGate}' gate has been approved.\n` +
-      `This Write changes the frozen plan contract:\n` +
+      `This ${toolName} changes the frozen plan contract:\n` +
       violations.map(v => `  • ${v}`).join('\n') + '\n\n' +
       `During the implement phase only these fields may change: ${mutableFields.join(', ')}.\n` +
       `To change the plan itself, ask the user to revoke the '${requiredGate}' gate\n` +

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/infrastructure-standards.md

@@ -3,14 +3,14 @@ paths:
   - "**/Dockerfile*"
   - "**/docker-compose*"
   - "**/.github/**"
-  - "**/easypanel*"
+  - "**/coolify*"
 stacks:
   - docker
 ---
 
 # Infrastructure Standards
 
-@.morph/framework/standards/infrastructure/docker/easypanel-deploy.md
+@.morph/framework/standards/infrastructure/docker/coolify-deploy.md
 
 ## Infrastructure Templates
 
@@ -19,9 +19,9 @@ stacks:
 | .NET API Dockerfile | `.morph/framework/templates/infrastructure/docker/dockerfile-api.dockerfile` | Multi-stage .NET |
 | Next.js Dockerfile | `.morph/framework/templates/infrastructure/docker/dockerfile-web.dockerfile` | Multi-stage Next.js |
 | Docker Compose | `.morph/framework/templates/infrastructure/docker/docker-compose.template.yml` | Local dev env |
-| EasyPanel Config | `.morph/framework/templates/infrastructure/docker/easypanel.template.json` | Deployment config |
+| Coolify Config | `.morph/framework/templates/infrastructure/docker/coolify.template.json` | Deployment config |
 | .NET Build CI | `.morph/framework/templates/infrastructure/github/workflows/dotnet-build.yml.hbs` | CI workflow |
 | Docker Push CI | `.morph/framework/templates/infrastructure/github/workflows/docker-build-push.yml.hbs` | Build & push |
-| Deploy EasyPanel | `.morph/framework/templates/infrastructure/github/workflows/deploy-easypanel.yml.hbs` | CD webhook |
+| Deploy Coolify | `.morph/framework/templates/infrastructure/github/workflows/deploy-coolify.yml.hbs` | CD via SSH |
 
 Read the template and adapt to your project structure.

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"
+  ]
+}
+```