@polymorphism-tech/morph-spec 8.15.1 → 8.17.0

package/framework/hooks/claude-code/core/gate-guard.js

@@ -24,21 +24,12 @@
  * No persisted decision, non-gate action, or any error → silence.
  */
 
-import { readFileSync } from 'fs';
 import { loadState, stateExists, getActiveFeature } 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 { resolveMorphRoot, resolveTargetPath } from '../../shared/payload-utils.js';
 import { locateFeatureForQuestion } from '../../shared/feature-locator.js';
 
-function readStdin() {
-  try {
-    return JSON.parse(readFileSync(0, 'utf8') || '{}');
-  } catch {
-    return {};
-  }
-}
-
 function projectDir() {
   return process.env.CLAUDE_PROJECT_DIR || process.cwd();
 }
@@ -118,7 +109,7 @@ function checkAskUserQuestion(input, sessionRoot) {
     if (!decision) continue; // no persisted decision → nothing to verify
     if (decision.pause === false) {
       logHookActivity('gate-guard', 'PostToolUse', 'divergent', cwd);
-      return injectContext(
+      return contextResult(
         `⚠️ [morph-spec] GATE OVER-PAUSE — você apresentou o Gate "${gate}" via AskUserQuestion, ` +
         `mas a decisão registrada em state.json (gateDecisions.${gate}) era pause:false ` +
         `(trust:${decision.trust ?? 'auto'}, nenhum sinal de risco). ` +
@@ -130,9 +121,9 @@ function checkAskUserQuestion(input, sessionRoot) {
     }
     // The decision said pause:true and the LLM did pause — coherent.
     logHookActivity('gate-guard', 'PostToolUse', 'coherent', cwd);
-    return pass();
+    return null;
   }
-  return pass();
+  return null;
 }
 
 /** True for edits to .morph/state.json (legacy) or a per-feature feature.json (v5). */
@@ -149,17 +140,17 @@ function isGateStateFile(filePath) {
  */
 function checkStateEdit(input, sessionRoot) {
   const filePath = input.tool_input?.file_path;
-  if (!isGateStateFile(filePath)) return pass();
+  if (!isGateStateFile(filePath)) return null;
 
   // The edited file names its own tree — and, for the v5 per-feature
   // feature.json, its own feature. Only the legacy `.morph/state.json` shape
   // still needs a most-recently-updated fallback within that tree.
   const cwd = rootOfGateStateFile(filePath, sessionRoot);
-  if (!stateExists(cwd)) return pass(); // fail-open
+  if (!stateExists(cwd)) return null; // fail-open
   const state = loadState(cwd);
-  if (!state) return pass();
+  if (!state) return null;
   const feature = featureFromStatePath(filePath) || getActiveFeature(cwd)?.name;
-  if (!feature) return pass();
+  if (!feature) return null;
 
   let checked = false;
   const gates = state.features?.[feature]?.approvalGates ?? {};
@@ -171,7 +162,7 @@ function checkStateEdit(input, sessionRoot) {
     if (!decision) continue;
     if (decision.pause === true) {
       logHookActivity('gate-guard', 'PostToolUse', 'divergent', cwd);
-      return injectContext(
+      return contextResult(
         `⚠️ [morph-spec] GATE SKIPPED PAUSE — o Gate "${gate}" foi marcado approvedBy:"auto", ` +
         `mas a decisão registrada (gateDecisions.${gate}) era pause:true ` +
         `(sinal: ${decision.reason || 'risco detectado'}). ` +
@@ -183,24 +174,29 @@ function checkStateEdit(input, sessionRoot) {
     checked = true;
   }
   if (checked) logHookActivity('gate-guard', 'PostToolUse', 'coherent', cwd);
-  return pass();
+  return null;
 }
 
-function main() {
+/**
+ * @param {object} payload - parsed PostToolUse stdin payload (Write|Edit|AskUserQuestion)
+ * @returns {Promise<object|null>} a hookSpecificOutput warning on a
+ *   trust-mode divergence, or null (pass/silent).
+ */
+export async function run(payload) {
   // Starting point only — each branch resolves the tree it actually inspects
   // (from the edited path, or from the feature the question names).
   const sessionRoot = projectDir();
 
-  const input = readStdin();
+  const input = payload || {};
   const toolName = input.tool_name;
 
   // Short-circuit before loading state: a Write/Edit only matters if it
   // touched gate state (state.json legacy, or the v5 per-feature
   // feature.json). Skip the disk read for unrelated edits.
   if (toolName === 'Edit' || toolName === 'Write') {
-    if (!isGateStateFile(input.tool_input?.file_path)) return pass();
+    if (!isGateStateFile(input.tool_input?.file_path)) return null;
   } else if (toolName !== 'AskUserQuestion') {
-    return pass();
+    return null;
   }
 
   try {
@@ -209,7 +205,7 @@ function main() {
   } catch {
     // fail-open
   }
-  return pass();
+  return null;
 }
 
-main();
+await runStandalone(run);

package/framework/hooks/claude-code/core/loop-detect.js

@@ -16,9 +16,8 @@
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { join } from 'path';
-import { readStdin } from '../../shared/stdin-reader.js';
 import { stateExists } from '../../shared/state-reader.js';
-import { injectContext, pass } from '../../shared/hook-response.js';
+import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import { getCommandSignature } from '../../shared/payload-utils.js';
 import { logEvent } from '../../shared/activity-logger.js';
 
@@ -27,78 +26,85 @@ const LOOP_WINDOW = 8;
 const MAX_UNIQUE_SIGS = 2;
 const COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes
 
-try {
-  if (!stateExists()) pass();
-
-  const payload = await readStdin();
-  if (!payload) pass();
-
-  const cwd = process.cwd();
-  const memoryDir = join(cwd, '.morph', 'memory');
-  const bufferPath = join(memoryDir, 'action-buffer.json');
-  const cooldownPath = join(memoryDir, 'loop-cooldown.json');
-
-  mkdirSync(memoryDir, { recursive: true });
-
-  // Read existing buffer
-  let buffer = [];
+/**
+ * @param {object} payload - parsed PostToolUse stdin payload (any tool)
+ * @returns {Promise<object|null>} a hookSpecificOutput loop warning, or null
+ *   (pass/silent).
+ */
+export async function run(payload) {
   try {
-    if (existsSync(bufferPath)) {
-      buffer = JSON.parse(readFileSync(bufferPath, 'utf-8'));
-      if (!Array.isArray(buffer)) buffer = [];
+    if (!stateExists()) return null;
+    if (!payload) return null;
+
+    const cwd = process.cwd();
+    const memoryDir = join(cwd, '.morph', 'memory');
+    const bufferPath = join(memoryDir, 'action-buffer.json');
+    const cooldownPath = join(memoryDir, 'loop-cooldown.json');
+
+    mkdirSync(memoryDir, { recursive: true });
+
+    // Read existing buffer
+    let buffer = [];
+    try {
+      if (existsSync(bufferPath)) {
+        buffer = JSON.parse(readFileSync(bufferPath, 'utf-8'));
+        if (!Array.isArray(buffer)) buffer = [];
+      }
+    } catch {
+      buffer = [];
     }
-  } catch {
-    buffer = [];
-  }
 
-  // Append current action
-  const sig = getCommandSignature(payload);
-  buffer.push({ sig, ts: new Date().toISOString() });
+    // Append current action
+    const sig = getCommandSignature(payload);
+    buffer.push({ sig, ts: new Date().toISOString() });
 
-  // Trim to max size (FIFO)
-  if (buffer.length > MAX_BUFFER) {
-    buffer = buffer.slice(-MAX_BUFFER);
-  }
+    // Trim to max size (FIFO)
+    if (buffer.length > MAX_BUFFER) {
+      buffer = buffer.slice(-MAX_BUFFER);
+    }
 
-  // Save updated buffer
-  writeFileSync(bufferPath, JSON.stringify(buffer), 'utf-8');
+    // Save updated buffer
+    writeFileSync(bufferPath, JSON.stringify(buffer), 'utf-8');
 
-  // Check for loop (need at least LOOP_WINDOW actions)
-  if (buffer.length < LOOP_WINDOW) pass();
+    // Check for loop (need at least LOOP_WINDOW actions)
+    if (buffer.length < LOOP_WINDOW) return null;
 
-  const recent = buffer.slice(-LOOP_WINDOW);
-  const uniqueSigs = new Set(recent.map(a => a.sig));
+    const recent = buffer.slice(-LOOP_WINDOW);
+    const uniqueSigs = new Set(recent.map(a => a.sig));
 
-  if (uniqueSigs.size > MAX_UNIQUE_SIGS) pass();
+    if (uniqueSigs.size > MAX_UNIQUE_SIGS) return null;
 
-  // Check cooldown
-  try {
-    if (existsSync(cooldownPath)) {
-      const cooldown = JSON.parse(readFileSync(cooldownPath, 'utf-8'));
-      const elapsed = Date.now() - new Date(cooldown.lastDetected).getTime();
-      if (elapsed < COOLDOWN_MS) pass();
+    // Check cooldown
+    try {
+      if (existsSync(cooldownPath)) {
+        const cooldown = JSON.parse(readFileSync(cooldownPath, 'utf-8'));
+        const elapsed = Date.now() - new Date(cooldown.lastDetected).getTime();
+        if (elapsed < COOLDOWN_MS) return null;
+      }
+    } catch {
+      // Ignore corrupt cooldown — proceed with detection
     }
+
+    // Loop detected — set cooldown and warn
+    writeFileSync(cooldownPath, JSON.stringify({ lastDetected: new Date().toISOString() }), 'utf-8');
+
+    logEvent('loop_detected', { signatures: uniqueSigs.size }, process.cwd());
+
+    const sigList = [...uniqueSigs].join(', ');
+    return contextResult(
+      `⚠️ [morph-spec] LOOP DETECTED — the last ${LOOP_WINDOW} actions repeat only ${uniqueSigs.size} pattern(s): ${sigList}\n\n` +
+      `This usually means you're stuck. Stop and try a different approach:\n` +
+      `  1. Re-read the error message carefully — what is it actually saying?\n` +
+      `  2. Try a completely different fix strategy\n` +
+      `  3. If the test keeps failing, check if the test itself is wrong\n` +
+      `  4. If blocked, ask the user for guidance\n\n` +
+      `Do NOT continue the same pattern.`,
+      'PostToolUse'
+    );
   } catch {
-    // Ignore corrupt cooldown — proceed with detection
+    // Fail-open
+    return null;
   }
-
-  // Loop detected — set cooldown and warn
-  writeFileSync(cooldownPath, JSON.stringify({ lastDetected: new Date().toISOString() }), 'utf-8');
-
-  logEvent('loop_detected', { signatures: uniqueSigs.size }, process.cwd());
-
-  const sigList = [...uniqueSigs].join(', ');
-  injectContext(
-    `⚠️ [morph-spec] LOOP DETECTED — the last ${LOOP_WINDOW} actions repeat only ${uniqueSigs.size} pattern(s): ${sigList}\n\n` +
-    `This usually means you're stuck. Stop and try a different approach:\n` +
-    `  1. Re-read the error message carefully — what is it actually saying?\n` +
-    `  2. Try a completely different fix strategy\n` +
-    `  3. If the test keeps failing, check if the test itself is wrong\n` +
-    `  4. If blocked, ask the user for guidance\n\n` +
-    `Do NOT continue the same pattern.`,
-    'PostToolUse'
-  );
-} catch {
-  // Fail-open
-  process.exit(0);
 }
+
+await runStandalone(run);

package/framework/hooks/claude-code/core/post-edit-typecheck.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * PostToolUse Hook: TypeScript typecheck with debounce
+ * PostToolUse Hook: TypeScript typecheck with debounce + build-dirty flag
  *
  * Event: PostToolUse | Matcher: Write|Edit
  *
@@ -9,6 +9,13 @@
  * so rapid sequential edits (e.g. multiple files in one task) don't each
  * trigger a full typecheck. Silent on success — only injects on error.
  *
+ * Also touches `.morph/memory/build-dirty.json` on EVERY Write/Edit of a
+ * source file (any extension build-check.js knows how to verify — dotnet .cs
+ * included, not just TS), even when the tsc check below is skipped/debounced.
+ * validate-completion.js (Stop hook) only runs its full build/typecheck when
+ * this flag is present — this is the write side of that dirty-flag gate
+ * (R1.2 of the performance plan).
+ *
  * Debounce state: .morph/memory/typecheck-debounce.json
  *
  * Fail-open: exits 0 on any error.
@@ -17,62 +24,104 @@
 import { execSync } from 'child_process';
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { join } from 'path';
-import { readStdin } from '../../shared/stdin-reader.js';
-import { pass, injectContext } from '../../shared/hook-response.js';
+import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import { stateExists } from '../../shared/state-reader.js';
 import { resolveRootForFile } from '../../shared/payload-utils.js';
 
 const DEBOUNCE_MS = 3000;
+const TSC_TIMEOUT_MS = 30000;
 
-try {
-  if (!stateExists()) pass();
+// Extensions build-check.js knows how to verify (dotnet .cs + the frontend
+// TS/JS family) — broader than the `/\.tsx?$/` gate below on purpose: editing
+// a .cs file never runs tsc here, but it DOES need the next Stop's
+// `dotnet build` to run.
+const SOURCE_FILE_RE = /\.(cs|ts|tsx|js|jsx|mjs|cjs|vue|razor|cshtml)$/i;
 
-  const payload = await readStdin();
-  const toolName = payload?.tool_name || '';
-  const filePath = payload?.tool_input?.file_path || payload?.tool_input?.path || '';
+/**
+ * Mark the build dirty for validate-completion.js's Stop-hook gate.
+ * Cheap, best-effort — never blocks, never throws.
+ *
+ * @param {string} morphRoot - the root whose `.morph/` the Stop hook itself
+ *   reads (resolved by the `.morph` marker, NOT the tsc/package.json root —
+ *   they can differ in a monorepo, e.g. editing `frontend/src/Foo.tsx` walks
+ *   up to `frontend/` for tsc but `.morph/` still lives at the repo root).
+ */
+function markBuildDirty(morphRoot) {
+  try {
+    const memDir = join(morphRoot, '.morph', 'memory');
+    mkdirSync(memDir, { recursive: true });
+    writeFileSync(join(memDir, 'build-dirty.json'), JSON.stringify({ ts: new Date().toISOString() }), 'utf-8');
+  } catch { /* non-blocking */ }
+}
 
-  if (!['Write', 'Edit'].includes(toolName)) pass();
-  if (!filePath.match(/\.tsx?$/)) pass();
+/**
+ * @param {object} payload - parsed PostToolUse stdin payload (Write|Edit)
+ * @returns {Promise<object|null>} a hookSpecificOutput context object on a
+ *   typecheck failure, or null (pass/silent). Never prints, never exits —
+ *   see runStandalone()/chain.js at the bottom.
+ */
+export async function run(payload) {
+  try {
+    if (!stateExists()) return null;
 
-  // Resolve the root that OWNS the edited file — when a subagent edits inside
-  // its own git worktree (isolation: "worktree", §3b-w), tsc must run there,
-  // not in the main working tree. Falls back to cwd for the normal case.
-  const root = resolveRootForFile(filePath, process.cwd());
+    const toolName = payload?.tool_name || '';
+    const filePath = payload?.tool_input?.file_path || payload?.tool_input?.path || '';
 
-  // No node_modules under the resolved root → tsc can't run; pass silently
-  // (a fresh worktree before `morph-spec worktree link` has no node_modules).
-  if (!existsSync(join(root, 'node_modules'))) pass();
+    if (!['Write', 'Edit'].includes(toolName)) return null;
 
-  // Debounce (keyed by root): skip if a typecheck ran within the last 3s.
-  const memDir = join(root, '.morph', 'memory');
-  const debouncePath = join(memDir, 'typecheck-debounce.json');
+    // Dirty-flag: resolved against the nearest ancestor that HAS a `.morph/`
+    // dir — the same root validate-completion.js reads from `process.cwd()`.
+    // This is deliberately independent of the tsc root below: a monorepo's
+    // `frontend/package.json` would otherwise make the flag land under
+    // `frontend/.morph/`, where the Stop hook (running from the repo root)
+    // never looks — a silently-dark guardrail.
+    const morphRoot = resolveRootForFile(filePath, process.cwd(), ['.morph']);
+    if (SOURCE_FILE_RE.test(filePath)) markBuildDirty(morphRoot);
 
-  try {
-    if (existsSync(debouncePath)) {
-      const { lastRun } = JSON.parse(readFileSync(debouncePath, 'utf-8'));
-      if (Date.now() - new Date(lastRun).getTime() < DEBOUNCE_MS) pass();
-    }
-  } catch { /* corrupt file — proceed */ }
+    if (!filePath.match(/\.tsx?$/)) return null;
 
-  try {
-    mkdirSync(memDir, { recursive: true });
-    writeFileSync(debouncePath, JSON.stringify({ lastRun: new Date().toISOString() }), 'utf-8');
-  } catch { /* non-blocking */ }
+    // Resolve the root that OWNS the edited file — when a subagent edits inside
+    // its own git worktree (isolation: "worktree", §3b-w), tsc must run there,
+    // not in the main working tree. Falls back to cwd for the normal case.
+    const root = resolveRootForFile(filePath, process.cwd());
 
-  try {
-    execSync('npx tsc --noEmit', { cwd: root, stdio: 'pipe', timeout: 30000 });
-    pass();
-  } catch (err) {
-    const stderr = err.stderr?.toString() || '';
-    const stdout = err.stdout?.toString() || '';
-    const output = (stderr + stdout).trim();
-    const fileName = filePath.split(/[\\/]/).pop();
-    const relevant = output.split('\n')
-      .filter(l => l.includes(fileName) || l.includes('error TS'))
-      .slice(0, 10)
-      .join('\n');
-    injectContext(`TypeScript errors after editing ${fileName}:\n${relevant || output.split('\n').slice(0, 10).join('\n')}`, 'PostToolUse');
+    // No node_modules under the resolved root → tsc can't run; pass silently
+    // (a fresh worktree before `morph-spec worktree link` has no node_modules).
+    if (!existsSync(join(root, 'node_modules'))) return null;
+
+    // Debounce (keyed by root): skip if a typecheck ran within the last 3s.
+    const memDir = join(root, '.morph', 'memory');
+    const debouncePath = join(memDir, 'typecheck-debounce.json');
+
+    try {
+      if (existsSync(debouncePath)) {
+        const { lastRun } = JSON.parse(readFileSync(debouncePath, 'utf-8'));
+        if (Date.now() - new Date(lastRun).getTime() < DEBOUNCE_MS) return null;
+      }
+    } catch { /* corrupt file — proceed */ }
+
+    try {
+      mkdirSync(memDir, { recursive: true });
+      writeFileSync(debouncePath, JSON.stringify({ lastRun: new Date().toISOString() }), 'utf-8');
+    } catch { /* non-blocking */ }
+
+    try {
+      execSync('npx tsc --noEmit', { cwd: root, stdio: 'pipe', timeout: TSC_TIMEOUT_MS });
+      return null;
+    } catch (err) {
+      const stderr = err.stderr?.toString() || '';
+      const stdout = err.stdout?.toString() || '';
+      const output = (stderr + stdout).trim();
+      const fileName = filePath.split(/[\\/]/).pop();
+      const relevant = output.split('\n')
+        .filter(l => l.includes(fileName) || l.includes('error TS'))
+        .slice(0, 10)
+        .join('\n');
+      return contextResult(`TypeScript errors after editing ${fileName}:\n${relevant || output.split('\n').slice(0, 10).join('\n')}`, 'PostToolUse');
+    }
+  } catch {
+    return null;
   }
-} catch {
-  pass();
 }
+
+await runStandalone(run);

package/framework/hooks/claude-code/core/pre-bash-denylist.js

@@ -2,28 +2,34 @@
 import { readFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { readStdin } from '../../shared/stdin-reader.js';
-import { pass, block } from '../../shared/hook-response.js';
+import { blockResult, runStandalone } from '../../shared/hook-response.js';
 import { stateExists } from '../../shared/state-reader.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-try {
-  if (!stateExists()) pass();
+/**
+ * @param {object} payload - parsed PreToolUse stdin payload (Bash matcher)
+ * @returns {Promise<object|null>} `{decision:'block',reason}` or null (pass).
+ */
+export async function run(payload) {
+  try {
+    if (!stateExists()) return null;
 
-  const payload = await readStdin();
-  const command = payload?.tool_input?.command || '';
-  if (!command) pass();
+    const command = payload?.tool_input?.command || '';
+    if (!command) return null;
 
-  const denylist = JSON.parse(readFileSync(join(__dirname, 'denylist.json'), 'utf-8'));
+    const denylist = JSON.parse(readFileSync(join(__dirname, 'denylist.json'), 'utf-8'));
 
-  for (const pattern of denylist.patterns) {
-    if (command.includes(pattern)) {
-      block(`Comando bloqueado pela denylist: padrão '${pattern}' detectado.`);
+    for (const pattern of denylist.patterns) {
+      if (command.includes(pattern)) {
+        return blockResult(`Comando bloqueado pela denylist: padrão '${pattern}' detectado.`);
+      }
     }
-  }
 
-  pass();
-} catch {
-  pass();
+    return null;
+  } catch {
+    return null;
+  }
 }
+
+await runStandalone(run);