@polymorphism-tech/morph-spec 4.9.0 → 4.10.1

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
     }
 
+    // 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('phase-dispatch', '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

@@ -18,83 +18,13 @@
 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, 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';
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Pure helpers (exported for testing)
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * Parse `morph-spec task start <feature> <taskId>` from a bash command string.
- * Returns { featureName, taskId } or null if the command doesn't match.
- *
- * @param {string} command
- * @returns {{ featureName: string, taskId: string } | null}
- */
-export function parseTaskStartCommand(command) {
-  if (!command || typeof command !== 'string') return null;
-  const match = command.match(/morph-spec\s+task\s+start\s+(\S+)\s+(\S+)/);
-  if (!match) return null;
-  return { featureName: match[1], taskId: match[2] };
-}
-
-/**
- * Build the mandatory skill reminder message for a task start event.
- * Returns null if no relevant skills exist for this phase.
- *
- * @param {string} featureName
- * @param {string} taskId
- * @param {string} phase
- * @param {Object|null} phasesData - Parsed phases.json content
- * @returns {string|null}
- */
-export function buildSkillReminderMessage(featureName, taskId, phase, phasesData) {
-  try {
-    const allSkills = phasesData?.phases?.[phase]?.requiredSkills;
-    if (!allSkills || allSkills.length === 0) return null;
-
-    const nowSkills   = allSkills.filter(s => s.trigger === 'beforeEachTask');
-    const laterSkills = allSkills.filter(s => s.trigger === 'beforeTaskDone');
-    const bugSkills   = allSkills.filter(s => s.trigger === 'onBugOrUnexpected');
-
-    if (nowSkills.length === 0 && laterSkills.length === 0) return null;
-
-    const lines = [];
-    lines.push(`⚠️  MORPH-SPEC SKILL REMINDER — Task ${taskId} started (phase: ${phase})`);
-    lines.push('');
-
-    if (nowSkills.length > 0) {
-      lines.push('INVOKE NOW before writing any code:');
-      for (const s of nowSkills) {
-        lines.push(`  → Skill(${s.skill})`);
-      }
-      lines.push('');
-    }
-
-    if (laterSkills.length > 0) {
-      lines.push('INVOKE BEFORE marking task done:');
-      for (const s of laterSkills) {
-        lines.push(`  → Skill(${s.skill})`);
-      }
-      lines.push('');
-    }
-
-    if (bugSkills.length > 0) {
-      lines.push('IF you encounter a bug or unexpected behavior:');
-      for (const s of bugSkills) {
-        lines.push(`  → Skill(${s.skill})`);
-      }
-      lines.push('');
-    }
-
-    lines.push('These are MANDATORY. Use the Skill() tool. Do NOT skip.');
-    return lines.join('\n');
-  } catch {
-    return null;
-  }
-}
+// Re-export for backwards compatibility (tests may import from this file)
+export { parseTaskStartCommand, buildSkillReminderMessage };
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Hook entry point
@@ -113,20 +43,13 @@ try {
   const { featureName, taskId } = parsed;
 
   // Load state to get current phase
-  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();
 
-  const phase = feature.phase;
+  const phase = feature.phase || derivePhaseForFeature(featureName);
   if (!phase) pass();
 
   // Load phases.json (project-local first, fall back to package-level)

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/

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);
+}

package/framework/hooks/claude-code/session-start/inject-morph-context.js

@@ -54,11 +54,11 @@ const SPEC_MAX_CHARS = getSpecMaxChars();
  * @param {string} cwd - Project root path
  */
 function saveStateSync(state, cwd) {
+  const statePath = join(cwd, '.morph/state.json');
+  const tmpPath = `${statePath}.tmp.hook.${process.pid}`;
   try {
     state.metadata = state.metadata || {};
     state.metadata.lastUpdated = new Date().toISOString();
-    const statePath = join(cwd, '.morph/state.json');
-    const tmpPath = `${statePath}.tmp.hook.${process.pid}`;
     writeFileSync(tmpPath, JSON.stringify(state, null, 2), 'utf8');
     renameSync(tmpPath, statePath);
   } catch {
@@ -209,6 +209,59 @@ try {
     }
   }
 
+  // ── MCP status injection ────────────────────────────────────────────────────
+  // Cross-reference configured MCPs with phase recommendations from mcp-registry.json.
+  // Fail-open: all inside try/catch, no crash on missing files.
+  try {
+    const currentPhase = active ? derivePhaseForFeature(active.name) : '';
+    if (currentPhase) {
+      // Read configured MCPs from settings
+      const configuredMcps = new Set();
+      const settingsFiles = [
+        join(process.cwd(), '.claude', 'settings.local.json'),
+        join(process.cwd(), '.claude', 'settings.json'),
+      ];
+      for (const sf of settingsFiles) {
+        if (existsSync(sf)) {
+          try {
+            const s = JSON.parse(readFileSync(sf, 'utf8'));
+            for (const name of Object.keys(s.mcpServers || {})) {
+              configuredMcps.add(name.toLowerCase());
+            }
+          } catch { /* ignore */ }
+        }
+      }
+
+      // Read recommended MCPs from phases.json or mcp-registry.json
+      let recommended = [];
+      const registryPaths = [
+        join(process.cwd(), 'framework', 'skills', 'level-0-meta', 'mcp-registry.json'),
+        join(process.cwd(), '.morph', 'framework', 'skills', 'level-0-meta', 'mcp-registry.json'),
+      ];
+      for (const rp of registryPaths) {
+        if (existsSync(rp)) {
+          try {
+            const registry = JSON.parse(readFileSync(rp, 'utf8'));
+            recommended = registry.phaseMatrix?.[currentPhase] || [];
+            break;
+          } catch { /* ignore */ }
+        }
+      }
+
+      if (recommended.length > 0) {
+        const mcpStatus = recommended.map(name => {
+          const isConfigured = configuredMcps.has(name.toLowerCase());
+          return `${name} ${isConfigured ? '✓' : '✗ (recommended)'}`;
+        });
+        lines.push('');
+        lines.push(`MCPs: ${mcpStatus.join(', ')}`);
+      }
+    }
+  } catch {
+    // Fail-open — MCP status must never block the session
+  }
+  // ────────────────────────────────────────────────────────────────────────────
+
   // Remind about key commands
   lines.push('');
   lines.push('Key commands: morph-spec status <feature> | morph-spec phase advance <feature> | morph-spec approve <feature> <gate>');