@polymorphism-tech/morph-spec 7.3.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,22 +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 ??= {};
-    if (state.features[featureName].approvalGates[gate] !== true) {
-      state.features[featureName].approvalGates[gate] = true;
-      state.features[featureName].updatedAt = new Date().toISOString();
-      changed = true;
-    }
-  }
+    const existing = state.features[featureName].approvalGates?.[gate];
+    const alreadyApproved = existing === true || existing?.approved === true;
+    if (alreadyApproved) continue;
 
-  if (changed) {
-    writeStateAtomic(cwd, state);
+    // 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/claude-code/core/validate-completion.js

@@ -25,6 +25,96 @@ import {
 import { injectContext, pass } from '../../shared/hook-response.js';
 import { logHookActivity, logEvent } from '../../shared/activity-logger.js';
 
+/**
+ * Audit recap.md against tasks.json + standard-citation rule.
+ *
+ * Returns an array of human-readable warnings. Empty array = audit clean.
+ *
+ * Two checks:
+ *   1. Task IDs that appear as a "## T<n>" heading in recap.md but still
+ *      carry status != 'done' in tasks.json — claim/state divergence.
+ *   2. Task headings without a "**Standard:**" line nearby (within 10 lines
+ *      after the heading) — no standard citation = unauditable decision.
+ */
+function auditRecapAndTasks(featurePath) {
+  const warnings = [];
+  const recapPath = join(featurePath, '3-implement', 'recap.md');
+  const tasksJsonPath = join(featurePath, '2-plan', 'tasks.json');
+  if (!existsSync(recapPath) || !existsSync(tasksJsonPath)) return warnings;
+
+  let recap, tasksJson;
+  try {
+    recap = readFileSync(recapPath, 'utf-8');
+    tasksJson = JSON.parse(readFileSync(tasksJsonPath, 'utf-8'));
+  } catch {
+    return warnings;
+  }
+
+  const tasks = Array.isArray(tasksJson.tasks) ? tasksJson.tasks : [];
+  if (tasks.length === 0) return warnings;
+
+  // Index recap by task ID — collect line numbers where each task is mentioned
+  // as completed. Supports two formats agents commonly use:
+  //   (a) "## T<n>"           — heading style (per the SKILL.md template)
+  //   (b) "| T<n> | ... done" — markdown table row with done in same row
+  const lines = recap.split('\n');
+  const recapMentions = new Map(); // id → starting line index
+  const headingRe = /^##\s+(T\d+)\b/;
+  const tableRowRe = /^\|\s*(T\d+)\s*\|.*\bdone\b/i;
+  lines.forEach((ln, i) => {
+    const heading = ln.match(headingRe);
+    if (heading && !recapMentions.has(heading[1])) {
+      recapMentions.set(heading[1], i);
+      return;
+    }
+    const tableRow = ln.match(tableRowRe);
+    if (tableRow && !recapMentions.has(tableRow[1])) {
+      recapMentions.set(tableRow[1], i);
+    }
+  });
+
+  // Check 1: status drift — task mentioned as done in recap but tasks.json
+  // still shows it as pending/in_progress.
+  for (const t of tasks) {
+    if (recapMentions.has(t.id) && t.status !== 'done') {
+      warnings.push(
+        `tasks.json drift: ${t.id} appears as done in recap.md but tasks.json shows status="${t.status}". Run writeTasksJson to sync.`
+      );
+    }
+  }
+
+  // Check 2: missing Standard citation per task mention. Skip pure
+  // table-row mentions (they're a summary, the heading-style block
+  // is where the standard belongs) — only flag when the agent did
+  // not produce a heading block at all for a task that is also marked
+  // done in tasks.json.
+  const standardRe = /\*\*Standard:\*\*|\bStandard\s*consulted\b|\bstandards?\s+used\b/i;
+  const headingMentions = new Map();
+  lines.forEach((ln, i) => {
+    const m = ln.match(headingRe);
+    if (m && !headingMentions.has(m[1])) headingMentions.set(m[1], i);
+  });
+  for (const t of tasks) {
+    if (t.status !== 'done') continue;
+    const lineIdx = headingMentions.get(t.id);
+    if (lineIdx === undefined) {
+      // Task is done but has no heading block at all — recap is summary-only.
+      warnings.push(
+        `recap.md task ${t.id} (status=done in tasks.json) has no detailed "## ${t.id}" block. Per morph-implement SKILL.md, each done task needs a heading block with a "**Standard:** ..." citation so the reviewer can audit the decision.`
+      );
+      continue;
+    }
+    const window = lines.slice(lineIdx, lineIdx + 12).join('\n');
+    if (!standardRe.test(window)) {
+      warnings.push(
+        `recap.md task ${t.id} is missing a "**Standard:** ..." citation within 12 lines of its heading. Cite which standard from STANDARDS.json justified the implementation (or "ad-hoc (see decisions.md ADR-N)" if intentional).`
+      );
+    }
+  }
+
+  return warnings;
+}
+
 // Phases where compaction is strongly recommended before starting
 const COMPACT_TRIGGER_PHASES = new Set(['implement']);
 
@@ -104,6 +194,21 @@ try {
   }
   // ────────────────────────────────────────────────────────────────────────
 
+  // ── Recap + tasks.json audit ──────────────────────────────────────────────
+  // Surface drift between recap.md and tasks.json, plus missing standard
+  // citations. Advisory warnings only — Stop hook never blocks.
+  try {
+    const featurePath = join(cwd, '.morph', 'features', name);
+    const recapWarnings = auditRecapAndTasks(featurePath);
+    if (recapWarnings.length > 0) {
+      warnings.push('📋 Recap audit:');
+      for (const w of recapWarnings) warnings.push(`  • ${w}`);
+    }
+  } catch {
+    // Fail-open — audit must never block Stop
+  }
+  // ────────────────────────────────────────────────────────────────────────
+
   // ── Session snapshot ──────────────────────────────────────────────────────
   // Save session state for next session's "getting up to speed" routine.
   try {