@polymorphism-tech/morph-spec 8.15.1 → 8.17.0

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

@@ -24,7 +24,6 @@
  */
 
 import { readFileSync } from 'fs';
-import { readStdin } from '../../shared/stdin-reader.js';
 import { stateExists, isGateApproved } from '../../shared/state-reader.js';
 import {
   isFeaturePath,
@@ -33,7 +32,7 @@ import {
   PROTECTED_SPEC_FILES,
   MUTABLE_SPEC_FIELDS
 } from '../../shared/phase-utils.js';
-import { block, pass } from '../../shared/hook-response.js';
+import { blockResult, runStandalone } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
 import { getFilePath, getToolName, resolveMorphRoot, resolveTargetPath } from '../../shared/payload-utils.js';
 import { validateTasksDoc, outputsDivergenceViolations } from '../../shared/tasks-validator.js';
@@ -42,6 +41,15 @@ import { validateTasksDoc, outputsDivergenceViolations } from '../../shared/task
  * Compare two tasks.json structures and return the list of plan-contract
  * violations — changes that touch anything other than the mutable fields.
  *
+ * Frozen-by-default, not an enumerated frozen list: the loop below walks the
+ * UNION of old/new task keys and flags any key not in `mutableFields`. A new
+ * plan-contract field (e.g. `agent`/`standards`, stamped by morph-plan — R2
+ * token-cut) needs NO entry added here to become protected; it is frozen the
+ * moment it exists on a task, simply by never being added to
+ * MUTABLE_SPEC_FIELDS (output-schema.js → `npm run generate` →
+ * framework/hooks/shared/phase-utils.js). Only fields that must stay
+ * EDITABLE post-Gate-2 (today: status, outputs, notes) belong in that list.
+ *
  * @param {object} oldDoc - parsed previous file content
  * @param {object} newDoc - parsed proposed file content
  * @param {string[]} mutableFields - field names allowed to change
@@ -98,124 +106,132 @@ function diffPlanContract(oldDoc, newDoc, mutableFields) {
   return violations;
 }
 
-try {
-  // Amend mode: bypass spec protection for legitimate in-implementation corrections
-  if (process.env.MORPH_AMEND_PHASE) {
-    console.error(`[morph-spec] AMEND MODE: bypassing spec protection for phase '${process.env.MORPH_AMEND_PHASE}'`);
-    pass();
-  }
-
-  const payload = await readStdin();
-  if (!payload) pass();
+/**
+ * @param {object} payload - parsed PreToolUse stdin payload
+ * @returns {Promise<object|null>} `{decision:'block',reason}` or null (pass).
+ *   Never prints, never exits — see runStandalone()/chain.js at the bottom.
+ */
+export async function run(payload) {
+  try {
+    // Amend mode: bypass spec protection for legitimate in-implementation corrections
+    if (process.env.MORPH_AMEND_PHASE) {
+      console.error(`[morph-spec] AMEND MODE: bypassing spec protection for phase '${process.env.MORPH_AMEND_PHASE}'`);
+      return null;
+    }
 
-  const filePath = getFilePath(payload);
-  if (!filePath) pass();
+    if (!payload) return null;
 
-  // Only check files inside .morph/features/
-  if (!isFeaturePath(filePath)) pass();
+    const filePath = getFilePath(payload);
+    if (!filePath) return null;
 
-  // The gate that locks this file is recorded in the feature.json of the tree
-  // that OWNS it. Asking the session's tree instead made this guard go DARK in
-  // a secondary worktree: the root had no approved gate, so a post-Gate-2
-  // spec.md rewrite sailed through. Same defect as enforce-phase-writes,
-  // opposite direction — there it over-blocked, here it under-protected.
-  const root = resolveMorphRoot(filePath, process.cwd());
-  if (!stateExists(root)) pass();
+    // Only check files inside .morph/features/
+    if (!isFeaturePath(filePath)) return null;
 
-  const featureName = extractFeatureName(filePath);
-  if (!featureName) pass();
+    // The gate that locks this file is recorded in the feature.json of the tree
+    // that OWNS it. Asking the session's tree instead made this guard go DARK in
+    // a secondary worktree: the root had no approved gate, so a post-Gate-2
+    // spec.md rewrite sailed through. Same defect as enforce-phase-writes,
+    // opposite direction — there it over-blocked, here it under-protected.
+    const root = resolveMorphRoot(filePath, process.cwd());
+    if (!stateExists(root)) return null;
 
-  const filename = getBasename(filePath);
-  const requiredGate = PROTECTED_SPEC_FILES[filename];
+    const featureName = extractFeatureName(filePath);
+    if (!featureName) return null;
 
-  // Not a protected file
-  if (!requiredGate) pass();
+    const filename = getBasename(filePath);
+    const requiredGate = PROTECTED_SPEC_FILES[filename];
 
-  // Gate not yet approved — allow editing
-  if (!isGateApproved(featureName, requiredGate, root)) {
-    logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
-    pass();
-  }
+    // Not a protected file
+    if (!requiredGate) return null;
 
-  // ── Gate approved — file is locked ──────────────────────────────────────
-  const mutableFields = MUTABLE_SPEC_FIELDS[filename];
-
-  // Files with mutable progress fields (e.g. tasks.json): allow a full Write
-  // that touches only those fields. Anything else stays blocked.
-  if (mutableFields) {
-    const toolName = getToolName(payload);
-
-    // 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 = resolveTargetPath(filePath, root);
-    let oldDoc, newDoc;
-    try {
-      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 {
+    // Gate not yet approved — allow editing
+    if (!isGateApproved(featureName, requiredGate, root)) {
       logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
-      pass();
+      return null;
     }
 
-    const violations = diffPlanContract(oldDoc, newDoc, mutableFields);
+    // ── Gate approved — file is locked ──────────────────────────────────────
+    const mutableFields = MUTABLE_SPEC_FIELDS[filename];
+
+    // Files with mutable progress fields (e.g. tasks.json): allow a full Write
+    // that touches only those fields. Anything else stays blocked.
+    if (mutableFields) {
+      const toolName = getToolName(payload);
+
+      // 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 = resolveTargetPath(filePath, root);
+      let oldDoc, newDoc;
+      try {
+        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 {
+        logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
+        return null;
+      }
 
-    // Schema check on the proposed doc: even mutable-field writes must keep a
-    // valid status enum (a leaf agent writing status:"completed" was the
-    // production failure this closes). Only NEWLY introduced schema errors
-    // block — a pre-existing violation must not deadlock progress writes.
-    const preExisting = new Set(validateTasksDoc(oldDoc).errors);
-    violations.push(...validateTasksDoc(newDoc).errors.filter(e => !preExisting.has(e)));
+      const violations = diffPlanContract(oldDoc, newDoc, mutableFields);
 
-    // Planned-vs-real outputs diff: changing `outputs` is allowed, but the
-    // divergence must be explained in `notes` in the same edit.
-    violations.push(...outputsDivergenceViolations(oldDoc, newDoc));
+      // Schema check on the proposed doc: even mutable-field writes must keep a
+      // valid status enum (a leaf agent writing status:"completed" was the
+      // production failure this closes). Only NEWLY introduced schema errors
+      // block — a pre-existing violation must not deadlock progress writes.
+      const preExisting = new Set(validateTasksDoc(oldDoc).errors);
+      violations.push(...validateTasksDoc(newDoc).errors.filter(e => !preExisting.has(e)));
 
-    if (violations.length === 0) {
-      // Only mutable progress fields changed — a legitimate implement-phase
-      // update via Write OR Edit.
-      logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
-      pass();
+      // Planned-vs-real outputs diff: changing `outputs` is allowed, but the
+      // divergence must be explained in `notes` in the same edit.
+      violations.push(...outputsDivergenceViolations(oldDoc, newDoc));
+
+      if (violations.length === 0) {
+        // Only mutable progress fields changed — a legitimate implement-phase
+        // update via Write OR Edit.
+        logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
+        return null;
+      }
+
+      logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
+      return blockResult(
+        `MORPH-SPEC: '${filename}' write rejected — the '${requiredGate}' gate has been approved.\n` +
+        `This ${toolName} violates the plan contract or the tasks schema:\n` +
+        violations.map(v => `  • ${v}`).join('\n') + '\n\n' +
+        `During the implement phase only these fields may change: ${mutableFields.join(', ')}\n` +
+        `(status must stay in the schema enum, and outputs that diverge from the plan\n` +
+        `require an explanatory 'notes' in the same edit).\n` +
+        `To change the plan itself, ask the user to revoke the '${requiredGate}' gate,\n` +
+        `then re-present it for approval.`
+      );
     }
 
+    // Fully-locked file (spec.md, mandate.md, design files): blanket block.
     logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
-    block(
-      `MORPH-SPEC: '${filename}' write rejected — the '${requiredGate}' gate has been approved.\n` +
-      `This ${toolName} violates the plan contract or the tasks schema:\n` +
-      violations.map(v => `  • ${v}`).join('\n') + '\n\n' +
-      `During the implement phase only these fields may change: ${mutableFields.join(', ')}\n` +
-      `(status must stay in the schema enum, and outputs that diverge from the plan\n` +
-      `require an explanatory 'notes' in the same edit).\n` +
-      `To change the plan itself, ask the user to revoke the '${requiredGate}' gate,\n` +
-      `then re-present it for approval.`
+    return blockResult(
+      `MORPH-SPEC: '${filename}' is locked — the '${requiredGate}' gate has been approved.\n` +
+      `Editing approved specs breaks the spec contract.\n\n` +
+      `If changes are truly needed, ask the user to revoke the gate approval\n` +
+      `in .morph/state.json (set approvals.${requiredGate} to false), make\n` +
+      `your edits, then re-present the gate for approval.`
     );
+  } catch {
+    // Fail-open
+    return null;
   }
-
-  // Fully-locked file (spec.md, mandate.md, design files): blanket block.
-  logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
-  block(
-    `MORPH-SPEC: '${filename}' is locked — the '${requiredGate}' gate has been approved.\n` +
-    `Editing approved specs breaks the spec contract.\n\n` +
-    `If changes are truly needed, ask the user to revoke the gate approval\n` +
-    `in .morph/state.json (set approvals.${requiredGate} to false), make\n` +
-    `your edits, then re-present the gate for approval.`
-  );
-} catch {
-  // Fail-open
-  process.exit(0);
 }
+
+await runStandalone(run);

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

@@ -11,10 +11,10 @@
  *  - AskUserQuestion answered with option starting "aprovado"        → advance gate
  */
 
-import { readFileSync } from 'fs';
 import { loadState, stateExists } from '../../shared/state-reader.js';
 import { persistFeature, setGateApproved, createDefaultFeature, readFeatureFile } from '../../shared/state-writer.js';
 import { resolveMorphRoot } from '../../shared/payload-utils.js';
+import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import {
   locateFeatureForQuestion,
   allWorkTrees,
@@ -32,19 +32,6 @@ const PHASE_FOLDERS = {
   '5-implement': 'implement', // legacy alias
 };
 
-function exit(output = {}) {
-  process.stdout.write(JSON.stringify(output));
-  process.exit(0);
-}
-
-function readStdin() {
-  try {
-    return JSON.parse(readFileSync(0, 'utf8') || '{}');
-  } catch {
-    return {};
-  }
-}
-
 function projectDir() {
   return process.env.CLAUDE_PROJECT_DIR || process.cwd();
 }
@@ -229,36 +216,41 @@ function handleAskUserQuestion(input, sessionRoot) {
   return warnings.length ? warnings.join('\n') : null;
 }
 
-async function main() {
-  // The SESSION's root. It is only a starting point: which `.morph/` actually
-  // gets read and written is decided per event — by the target path for
-  // Write/Edit, by the feature the question names for AskUserQuestion. The
-  // `stateExists` gate therefore moved into each handler, against the tree that
-  // handler resolved; gating on the session's tree up here would skip work that
-  // belongs to a worktree (and, worse, silently pass it to the wrong one).
-  const sessionRoot = projectDir();
+/**
+ * @param {object} payload - parsed PostToolUse stdin payload (Write|Edit|AskUserQuestion)
+ * @returns {Promise<object|null>} a hookSpecificOutput warning on a gate
+ *   order/attribution violation, or null (pass/silent).
+ */
+export async function run(payload) {
+  try {
+    // The SESSION's root. It is only a starting point: which `.morph/` actually
+    // gets read and written is decided per event — by the target path for
+    // Write/Edit, by the feature the question names for AskUserQuestion. The
+    // `stateExists` gate therefore moved into each handler, against the tree that
+    // handler resolved; gating on the session's tree up here would skip work that
+    // belongs to a worktree (and, worse, silently pass it to the wrong one).
+    const sessionRoot = projectDir();
 
-  const input = readStdin();
-  const toolName = input.tool_name;
+    const input = payload || {};
+    const toolName = input.tool_name;
 
-  let warning = null;
-  try {
-    if (toolName === 'Write' || toolName === 'Edit') {
-      handleWriteEdit(input, sessionRoot);
-    } else if (toolName === 'AskUserQuestion') {
-      warning = handleAskUserQuestion(input, sessionRoot);
+    let warning = null;
+    try {
+      if (toolName === 'Write' || toolName === 'Edit') {
+        handleWriteEdit(input, sessionRoot);
+      } else if (toolName === 'AskUserQuestion') {
+        warning = handleAskUserQuestion(input, sessionRoot);
+      }
+    } catch {
+      // fail-open
     }
-  } catch {
-    // fail-open
-  }
 
-  // A non-blocking order-violation warning is surfaced as injected context
-  // (hookSpecificOutput.additionalContext); everything else exits silently.
-  if (warning) {
-    exit({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: warning } });
-  } else {
-    exit();
+    // A non-blocking order-violation warning is surfaced as injected context
+    // (hookSpecificOutput.additionalContext); everything else stays silent.
+    return warning ? contextResult(warning, 'PostToolUse') : null;
+  } catch {
+    return null;
   }
 }
 
-main().catch(() => exit());
+await runStandalone(run);

package/framework/hooks/claude-code/core/tasks-json-guard.js

@@ -22,62 +22,62 @@
 import { readFileSync } from 'fs';
 import { isAbsolute, join } from 'path';
 import { stateExists } from '../../shared/state-reader.js';
-import { injectContext, pass } from '../../shared/hook-response.js';
+import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
 import { getFilePath } from '../../shared/payload-utils.js';
 import { isFeaturePath, getBasename } from '../../shared/phase-utils.js';
 import { VALID_TASK_STATUS, validateTasksDoc } from '../../shared/tasks-validator.js';
 
-function readStdin() {
-  try {
-    return JSON.parse(readFileSync(0, 'utf8') || '{}');
-  } catch {
-    return {};
-  }
-}
-
 function projectDir() {
   return process.env.CLAUDE_PROJECT_DIR || process.cwd();
 }
 
-try {
-  const cwd = projectDir();
-  if (!stateExists(cwd)) pass();
+/**
+ * @param {object} payload - parsed PostToolUse stdin payload (Write|Edit)
+ * @returns {Promise<object|null>} a hookSpecificOutput warning when tasks.json
+ *   is unparseable or schema-invalid, or null (pass/silent).
+ */
+export async function run(payload) {
+  try {
+    const cwd = projectDir();
+    if (!stateExists(cwd)) return null;
 
-  const payload = readStdin();
-  const filePath = getFilePath(payload);
-  if (!filePath) pass();
-  if (!isFeaturePath(filePath)) pass();
-  if (getBasename(filePath) !== 'tasks.json') pass();
+    const filePath = getFilePath(payload);
+    if (!filePath) return null;
+    if (!isFeaturePath(filePath)) return null;
+    if (getBasename(filePath) !== 'tasks.json') return null;
 
-  const absPath = isAbsolute(filePath) ? filePath : join(cwd, filePath);
+    const absPath = isAbsolute(filePath) ? filePath : join(cwd, filePath);
 
-  let doc;
-  try {
-    doc = JSON.parse(readFileSync(absPath, 'utf-8'));
-  } catch {
-    logHookActivity('tasks-json-guard', 'PostToolUse', 'invalid', cwd);
-    injectContext(
-      '⚠️ [morph-spec] tasks.json INVÁLIDO — o arquivo gravado não parseia como JSON. ' +
-      'Corrija o arquivo antes de continuar.',
-      'PostToolUse'
-    );
-  }
+    let doc;
+    try {
+      doc = JSON.parse(readFileSync(absPath, 'utf-8'));
+    } catch {
+      logHookActivity('tasks-json-guard', 'PostToolUse', 'invalid', cwd);
+      return contextResult(
+        '⚠️ [morph-spec] tasks.json INVÁLIDO — o arquivo gravado não parseia como JSON. ' +
+        'Corrija o arquivo antes de continuar.',
+        'PostToolUse'
+      );
+    }
 
-  const { valid, errors } = validateTasksDoc(doc);
-  if (!valid) {
-    logHookActivity('tasks-json-guard', 'PostToolUse', 'invalid', cwd);
-    injectContext(
-      '⚠️ [morph-spec] tasks.json com schema inválido após o write:\n' +
-      errors.map(e => `  • ${e}`).join('\n') +
-      `\nStatus válidos: ${VALID_TASK_STATUS.join(', ')}. Corrija antes de marcar a task como done.`,
-      'PostToolUse'
-    );
-  }
+    const { valid, errors } = validateTasksDoc(doc);
+    if (!valid) {
+      logHookActivity('tasks-json-guard', 'PostToolUse', 'invalid', cwd);
+      return contextResult(
+        '⚠️ [morph-spec] tasks.json com schema inválido após o write:\n' +
+        errors.map(e => `  • ${e}`).join('\n') +
+        `\nStatus válidos: ${VALID_TASK_STATUS.join(', ')}. Corrija antes de marcar a task como done.`,
+        'PostToolUse'
+      );
+    }
 
-  logHookActivity('tasks-json-guard', 'PostToolUse', 'ok', cwd);
-  pass();
-} catch {
-  // Fail-open
-  process.exit(0);
+    logHookActivity('tasks-json-guard', 'PostToolUse', 'ok', cwd);
+    return null;
+  } catch {
+    // Fail-open
+    return null;
+  }
 }
+
+await runStandalone(run);