@polymorphism-tech/morph-spec 4.8.19 → 4.10.0

package/framework/hooks/claude-code/post-tool-use/dispatch.js

@@ -1,25 +1,33 @@
 #!/usr/bin/env node
 
 /**
- * PostToolUse Hook: Improved Dispatch
+ * PostToolUse Hook: Dispatch + Validator Injection
  *
  * Event: PostToolUse | Matcher: Bash
  *
- * Replaces the old agent-teams/dispatch.js with:
- *   - Reads state BEFORE dispatching to pass correct from/to phases
- *   - Handles more CLI commands: approve, state init, checkpoint commands
- *   - Triggers checkpoint validation on task completion when count % 3 === 0
+ * Handles:
+ *   - morph-spec task done: auto-checkpoint every 3 tasks + validator dispatch injection
+ *   - morph-spec phase advance: phase chain evaluation + validator dispatch injection
+ *   - morph-spec approve: pass-through
+ *
+ * Validator dispatch: extracts VALIDATION DISPATCH JSON from tool output
+ * and injects it as additionalContext so Claude reliably dispatches validators
+ * as subagents via the Agent tool.
  *
  * Fail-open: exits 0 on any error.
  */
 
 import { execSync } from 'child_process';
 import { readFileSync, existsSync } from 'fs';
-import { resolve } from 'path';
+import { resolve, join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
 import { readStdin } from '../../shared/stdin-reader.js';
-import { stateExists, getFeature } from '../../shared/state-reader.js';
+import { stateExists, getFeature, getFeaturePhase } from '../../shared/state-reader.js';
 import { pass, injectContext } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
+import { extractValidationDispatch, formatValidatorInstruction, getToolOutput, parseTaskDoneCommand, parsePhaseAdvanceCommand } from '../../shared/dispatch-helpers.js';
 
 try {
   if (!stateExists()) pass();
@@ -30,24 +38,27 @@ try {
   const command = payload?.tool_input?.command || '';
   if (!command) pass();
 
-  dispatch(command);
+  await dispatch(command, payload);
 } catch {
   // Fail-open
   process.exit(0);
 }
 
-function dispatch(command) {
+async function dispatch(command, payload) {
   // morph-spec task done <feature> <taskId> [--skip-validation]
-  const taskDoneMatch = command.match(/morph-spec\s+task\s+done\s+(\S+)\s+(\S+)/);
-  if (taskDoneMatch) {
-    const [, featureName, taskId] = taskDoneMatch;
+  const taskDoneParsed = parseTaskDoneCommand(command);
+  if (taskDoneParsed) {
+    const { featureName } = taskDoneParsed;
+    const skipValidation = command.includes('--skip-validation');
+
+    const contextParts = [];
 
     // Check if checkpoint should run (every 3 tasks)
     let dispatchResult = 'task_done';
     try {
       const feature = getFeature(featureName);
       if (feature?.tasks) {
-        const completed = (feature.tasks.completed || 0) + 1; // +1 because task-done hasn't executed yet
+        const completed = (feature.tasks.completed || 0) + 1;
         if (completed > 0 && completed % 3 === 0) {
           const checkpointNum = Math.floor(completed / 3);
           run(`morph-spec checkpoint-save ${featureName} --note "Auto-checkpoint #${checkpointNum} at task ${completed}"`);
@@ -58,16 +69,45 @@ function dispatch(command) {
       // Non-blocking
     }
 
-    logHookActivity('dispatch.js', 'PostToolUse', dispatchResult);
+    // Inject validator dispatch for task completion.
+    // Skip when --skip-validation: no validators needed, avoids subprocess fallback.
+    if (!skipValidation) {
+      const validatorText = await buildValidatorDispatchContext(featureName, payload);
+      if (validatorText) {
+        contextParts.push(validatorText);
+        dispatchResult = 'task_done_with_validators';
+      }
+    }
+
+    logHookActivity('phase-dispatch', 'PostToolUse', dispatchResult);
+
+    if (contextParts.length > 0) {
+      injectContext(contextParts.join('\n\n'));
+    }
     pass();
   }
 
   // morph-spec phase advance <feature>
-  const phaseAdvanceMatch = command.match(/morph-spec\s+phase\s+advance\s+(\S+)/);
-  if (phaseAdvanceMatch) {
-    const [, featureName] = phaseAdvanceMatch;
-    evaluatePhaseChain(featureName);
-    logHookActivity('dispatch.js', 'PostToolUse', 'phase_chain');
+  const phaseAdvanceParsed = parsePhaseAdvanceCommand(command);
+  if (phaseAdvanceParsed) {
+    const { featureName } = phaseAdvanceParsed;
+
+    const contextParts = [];
+
+    // Phase chain evaluation
+    const chainText = buildPhaseChainContext(featureName);
+    if (chainText) contextParts.push(chainText);
+
+    // Validator dispatch injection
+    const validatorText = await buildValidatorDispatchContext(featureName, payload);
+    if (validatorText) contextParts.push(validatorText);
+
+    logHookActivity('phase-dispatch', 'PostToolUse',
+      validatorText ? 'phase_advance_with_validators' : 'phase_chain');
+
+    if (contextParts.length > 0) {
+      injectContext(contextParts.join('\n\n'));
+    }
     pass();
   }
 
@@ -83,45 +123,128 @@ function dispatch(command) {
 }
 
 /**
- * Evaluate whether the phase chain should auto-continue after a phase advance.
- * Injects a `morph-spec phase run` instruction when the workflow has phaseChain.enabled.
- * Silently passes when workflow doesn't support chaining or feature is not found.
+ * Build phase chain context text (returns null if not applicable).
+ * Replaces the old evaluatePhaseChain that called injectContext directly.
  *
  * @param {string} featureName
+ * @returns {string|null}
  */
-function evaluatePhaseChain(featureName) {
+function buildPhaseChainContext(featureName) {
   try {
     const feature = getFeature(featureName);
-    if (!feature) return;
+    if (!feature) return null;
 
     const workflowId = feature.workflow;
-    if (!workflowId || workflowId === 'auto') return;
+    if (!workflowId || workflowId === 'auto') return null;
 
-    // Load workflow config to check phaseChain.enabled
     const configPath = resolve(
       process.cwd(),
       `.morph/framework/workflows/configs/${workflowId}.json`
     );
-    if (!existsSync(configPath)) return;
+    if (!existsSync(configPath)) return null;
 
     let workflowConfig;
     try {
       workflowConfig = JSON.parse(readFileSync(configPath, 'utf8'));
     } catch {
-      return;
+      return null;
     }
 
-    if (!workflowConfig?.phaseChain?.enabled) return;
+    if (!workflowConfig?.phaseChain?.enabled) return null;
 
-    // Inject instruction to continue the phase chain
-    injectContext(
+    return (
       `Phase advance complete. Continue the phase chain:\n` +
       `  morph-spec phase run ${featureName}\n\n` +
       `The phase runner will check eligibility and auto-advance if all gates pass. ` +
       `It will pause automatically on blocked tasks, low pass rate, or trust gates.`
     );
   } catch {
-    // Non-blocking — fail silently
+    return null;
+  }
+}
+
+/**
+ * Extract validator dispatch from tool output and build injection context.
+ *
+ * Strategy:
+ * 1. Try to parse VALIDATION DISPATCH JSON from the tool_result (stdout of phase advance)
+ * 2. If not found, fallback to running dispatch-agents CLI in validate mode
+ *
+ * @param {string} featureName
+ * @param {object} payload - PostToolUse hook payload
+ * @returns {string|null} - Formatted injection text or null
+ */
+async function buildValidatorDispatchContext(featureName, payload) {
+  try {
+    // Strategy 1: Extract from tool output
+    const toolOutput = getToolOutput(payload);
+    const dispatch = extractValidationDispatch(toolOutput);
+    if (dispatch) return formatValidatorInstruction(dispatch);
+
+    // Strategy 2: Direct import of buildDispatchConfig (no subprocess)
+    return await buildDispatchDirect(featureName);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fallback: build validator dispatch config via direct import (no subprocess).
+ *
+ * Attempts to import buildDispatchConfig from the installed package or local
+ * framework. Falls back to null on any error (fail-open).
+ *
+ * @param {string} featureName
+ * @returns {Promise<string|null>}
+ */
+async function buildDispatchDirect(featureName) {
+  try {
+    const phase = getFeaturePhase(featureName);
+    if (!phase) return null;
+
+    // Try local project path first, then package path
+    let buildDispatchConfig;
+    const localPath = resolve(process.cwd(), 'src/commands/agents/dispatch-agents.js');
+    const pkgPath = resolve(process.cwd(), 'node_modules/@polymorphism-tech/morph-spec/src/commands/agents/dispatch-agents.js');
+
+    if (existsSync(localPath)) {
+      ({ buildDispatchConfig } = await import(`file://${localPath.replace(/\\/g, '/')}`));
+    } else if (existsSync(pkgPath)) {
+      ({ buildDispatchConfig } = await import(`file://${pkgPath.replace(/\\/g, '/')}`));
+    } else {
+      return null;
+    }
+
+    const config = await buildDispatchConfig(process.cwd(), featureName, phase, { mode: 'validate' });
+    const validators = config.agents?.filter(a => a.tier === 4);
+    if (!validators || validators.length === 0) return null;
+
+    const agentsJsonPath = resolve(process.cwd(), 'framework/agents.json');
+    const pkgAgentsPath = resolve(process.cwd(), 'node_modules/@polymorphism-tech/morph-spec/framework/agents.json');
+    const agentsPath = existsSync(agentsJsonPath) ? agentsJsonPath : pkgAgentsPath;
+
+    let allAgents = {};
+    if (existsSync(agentsPath)) {
+      allAgents = JSON.parse(readFileSync(agentsPath, 'utf8')).agents || {};
+    }
+
+    const dispatch = {
+      validators: validators.map(v => {
+        const agentData = allAgents[v.id];
+        return {
+          id: v.id,
+          title: v.title,
+          taskPrompt: v.taskPrompt,
+          severity: agentData?.hook_behavior?.severity || 'error',
+          blocksOnFail: agentData?.hook_behavior?.blocks_on_fail ?? true,
+          checks: agentData?.hook_behavior?.validates || [],
+        };
+      }),
+    };
+
+    return formatValidatorInstruction(dispatch);
+  } catch {
+    return null;
   }
 }
 

package/framework/hooks/claude-code/post-tool-use/skill-reminder.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse Hook: Skill Reminder on Task Start
+ *
+ * Event: PostToolUse | Matcher: Bash
+ *
+ * Fires after `morph-spec task start <feature> <task>` completes.
+ * Reads requiredSkills from phases.json for the current phase and injects
+ * mandatory skill invocation instructions as additionalContext.
+ *
+ * The additionalContext appears directly in Claude's view of the Bash tool
+ * result — more prominent than any pre-loaded prompt text.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists, loadState, derivePhaseForFeature } from '../../shared/state-reader.js';
+import { injectContext, pass } from '../../shared/hook-response.js';
+import { logHookActivity } from '../../shared/activity-logger.js';
+import { parseTaskStartCommand, buildSkillReminderMessage } from '../../shared/skill-reminder-helpers.js';
+
+// Re-export for backwards compatibility (tests may import from this file)
+export { parseTaskStartCommand, buildSkillReminderMessage };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook entry point
+// ─────────────────────────────────────────────────────────────────────────────
+
+try {
+  if (!stateExists()) pass();
+
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const command = payload?.tool_input?.command || '';
+  const parsed = parseTaskStartCommand(command);
+  if (!parsed) pass();
+
+  const { featureName, taskId } = parsed;
+
+  // Load state to get current phase
+  const state = loadState();
+  if (!state) pass();
+
+  const feature = state?.features?.[featureName];
+  if (!feature) pass();
+
+  const phase = feature.phase || derivePhaseForFeature(featureName);
+  if (!phase) pass();
+
+  // Load phases.json (project-local first, fall back to package-level)
+  const localPhasesPath = join(process.cwd(), 'framework', 'phases.json');
+  const pkgPhasesPath = join(
+    process.cwd(), 'node_modules', '@polymorphism-tech', 'morph-spec', 'framework', 'phases.json'
+  );
+  const phasesPath = existsSync(localPhasesPath) ? localPhasesPath : pkgPhasesPath;
+  if (!existsSync(phasesPath)) pass();
+
+  let phasesData;
+  try {
+    phasesData = JSON.parse(readFileSync(phasesPath, 'utf8'));
+  } catch {
+    pass();
+  }
+
+  const message = buildSkillReminderMessage(featureName, taskId, phase, phasesData);
+  if (!message) pass();
+
+  logHookActivity('skill-reminder', 'PostToolUse', `injected(${featureName}/${taskId}/${phase})`);
+  injectContext(message);
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/claude-code/post-tool-use/validator-feedback.js

@@ -16,12 +16,11 @@
  * Fail-open: exits 0 on any error.
  */
 
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
 import { readStdin } from '../../shared/stdin-reader.js';
-import { stateExists } from '../../shared/state-reader.js';
+import { stateExists, loadState } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
+import { parseTaskDoneCommand } from '../../shared/dispatch-helpers.js';
 
 // Standard IDs referenced in remediation messages
 const STANDARD_REFS = {
@@ -42,22 +41,14 @@ try {
   const command = payload?.tool_input?.command || '';
   if (!command) pass();
 
-  // Match: morph-spec task done <feature> <taskId>
-  const taskDoneMatch = command.match(/morph-spec\s+task\s+done\s+(\S+)\s+(\S+)/);
-  if (!taskDoneMatch) pass();
+  const parsed = parseTaskDoneCommand(command);
+  if (!parsed) pass();
 
-  const [, featureName, taskId] = taskDoneMatch;
+  const { featureName, taskId } = parsed;
 
   // Load state and find validationHistory for this task
-  const statePath = join(process.cwd(), '.morph', 'state.json');
-  if (!existsSync(statePath)) pass();
-
-  let state;
-  try {
-    state = JSON.parse(readFileSync(statePath, 'utf8'));
-  } catch {
-    pass();
-  }
+  const state = loadState();
+  if (!state) pass();
 
   const feature = state?.features?.[featureName];
   if (!feature) pass();
@@ -100,7 +91,7 @@ function buildRemediationContext(featureName, taskId, taskHistory) {
     }
   }
 
-  if (allIssues.length === 0 && taskHistory.status !== 'blocked') pass();
+  if (allIssues.length === 0 && taskHistory.status !== 'blocked') return;
 
   const lines = [];
 

package/framework/hooks/claude-code/pre-compact/save-morph-context.js

@@ -23,9 +23,7 @@ import {
 } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
-
-const DECISIONS_MAX_CHARS = 1500;
-const MAX_PENDING_TASKS   = 8;
+import { buildRichContext, DECISIONS_MAX_CHARS, MAX_PENDING_TASKS } from '../../shared/compact-restore.js';
 
 const PHASE_POSITIONS = {
   proposal: 1, setup: 1,
@@ -73,6 +71,21 @@ try {
     };
   }
 
+  // ── Enrich snapshot with richContext (decisions + taskList) ───────────────
+  if (active) {
+    try {
+      const { name: activeName, feature: activeFeature } = active;
+      const activePhase = derivePhaseForFeature(activeName);
+      let decisionsContent = '';
+      const decisionsPath = join(cwd, `.morph/features/${activeName}/1-design/decisions.md`);
+      if (existsSync(decisionsPath)) {
+        try { decisionsContent = readFileSync(decisionsPath, 'utf-8'); } catch { /* ignore */ }
+      }
+      snapshot.richContext = buildRichContext(activeFeature, activePhase, decisionsContent);
+    } catch { /* fail-open: richContext is optional */ }
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+
   const memoryDir = join(cwd, '.morph', 'memory');
   if (!existsSync(memoryDir)) mkdirSync(memoryDir, { recursive: true });
   const ts = new Date().toISOString().replace(/[:.]/g, '-');

package/framework/hooks/claude-code/pre-tool-use/enforce-phase-writes.js

@@ -9,8 +9,8 @@
  *   proposal → only 0-proposal/
  *   design, clarify → only 1-design/
  *   uiux → only 2-ui/
- *   tasks → only 3-tasks/
- *   implement → 4-implement/ + any source code (unrestricted)
+ *   tasks → only 4-tasks/
+ *   implement → 5-implement/ + any source code (unrestricted)
  *
  * Files outside .morph/features/ are always allowed.
  *
@@ -29,6 +29,7 @@ import {
 } from '../../shared/phase-utils.js';
 import { block, pass } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
+import { getFilePath } from '../../shared/payload-utils.js';
 
 try {
   // Amend mode: bypass phase write enforcement for legitimate corrections
@@ -42,7 +43,7 @@ try {
   const payload = await readStdin();
   if (!payload) pass();
 
-  const filePath = payload?.tool_input?.file_path || payload?.tool_input?.path || '';
+  const filePath = getFilePath(payload);
   if (!filePath) pass();
 
   // Only check files inside .morph/features/

package/framework/hooks/claude-code/pre-tool-use/protect-spec-files.js

@@ -7,7 +7,7 @@
  *
  * Blocks Write/Edit to spec artifacts after their approval gate has passed:
  *   - 1-design/spec.md, contracts.cs, etc. → blocked if 'design' gate approved
- *   - 3-tasks/tasks.md → blocked if 'tasks' gate approved
+ *   - 4-tasks/tasks.md → blocked if 'tasks' gate approved
  *   - 2-ui/design-system.md, etc. → blocked if 'uiux' gate approved
  *
  * Fail-open: exits 0 on any error.
@@ -23,6 +23,7 @@ import {
 } from '../../shared/phase-utils.js';
 import { block, pass } from '../../shared/hook-response.js';
 import { logHookActivity } from '../../shared/activity-logger.js';
+import { getFilePath } from '../../shared/payload-utils.js';
 
 try {
   // Amend mode: bypass spec protection for legitimate in-implementation corrections
@@ -36,7 +37,7 @@ try {
   const payload = await readStdin();
   if (!payload) pass();
 
-  const filePath = payload?.tool_input?.file_path || payload?.tool_input?.path || '';
+  const filePath = getFilePath(payload);
   if (!filePath) pass();
 
   // Only check files inside .morph/features/
@@ -58,7 +59,7 @@ try {
       `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:\n` +
-      `  1. Revoke approval: morph-spec approve ${featureName} ${requiredGate} --revoke\n` +
+      `  1. Revoke approval: morph-spec unapprove ${featureName} ${requiredGate}\n` +
       `  2. Make your edits\n` +
       `  3. Re-approve: morph-spec approve ${featureName} ${requiredGate}`
     );

package/framework/hooks/claude-code/pre-tool-use/task-tracking-guard.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse Hook: Advisory Task Tracking Guard
+ *
+ * Event: PreToolUse | Matcher: Write|Edit
+ *
+ * During implement phase, injects a warning if no task is currently in_progress.
+ * Advisory only (type: approve with context) — never blocks.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists, loadState, getActiveFeature, derivePhaseForFeature } from '../../shared/state-reader.js';
+import { approve, pass } from '../../shared/hook-response.js';
+import { getFilePath } from '../../shared/payload-utils.js';
+
+try {
+  if (!stateExists()) pass();
+
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const filePath = getFilePath(payload);
+  if (!filePath) pass();
+
+  // Skip files inside .morph/ — internal framework writes don't need task tracking
+  if (filePath.includes('.morph/') || filePath.includes('.morph\\')) pass();
+
+  // Only check during implement phase
+  const active = getActiveFeature();
+  if (!active) pass();
+
+  const { name, feature } = active;
+  const phase = feature.phase || derivePhaseForFeature(name);
+  if (phase !== 'implement') pass();
+
+  // Check if any task is in_progress
+  // Method 1: tasks.inProgress counter (v3 state format)
+  if (feature.tasks?.inProgress > 0) pass();
+
+  // Method 2: taskList array (v2 state format)
+  if (feature.taskList) {
+    const hasActive = feature.taskList.some(t => t.status === 'in_progress');
+    if (hasActive) pass();
+  }
+
+  // No task in_progress — inject advisory warning
+  approve(
+    `[morph-spec] WARNING: No active task tracking detected during implement phase.\n` +
+    `Before writing code, start a task:\n` +
+    `  npx morph-spec task next ${name}        # see what's next\n` +
+    `  npx morph-spec task start ${name} <id>   # mark it in progress\n` +
+    `Task tracking ensures validators run, checkpoints fire, and progress is recorded.`
+  );
+} catch {
+  // Fail-open
+  process.exit(0);
+}