@polymorphism-tech/morph-spec 4.9.0 → 4.10.0

package/src/lib/installers/mcp-installer.js

@@ -12,7 +12,7 @@ import { execSync } from 'child_process';
 import { installMcpServers } from '../../utils/claude-settings-manager.js';
 
 /**
- * Load the enhanced MCP registry (v2.0.0)
+ * Load the enhanced MCP registry (v3.0.0)
  * @returns {Object} Registry with install blocks
  */
 export function loadMcpRegistry() {
@@ -96,14 +96,26 @@ export function checkPrerequisites(mcpEntry) {
   return results;
 }
 
+/**
+ * Check if an MCP config uses remote HTTP transport (no local process).
+ * @param {Object} config - MCP server config
+ * @returns {boolean}
+ */
+export function isRemoteMcp(config) {
+  return config.type === 'http' || config.url != null;
+}
+
 /**
  * Patch MCP config for the current platform.
  * On Windows, npx must be invoked via `cmd /c` to avoid ENOENT errors.
  * Registry already stores cmd/c format; this handles legacy configs that still use npx directly.
- * @param {Object} config - MCP server config { command, args, env? }
+ * Remote HTTP MCPs are returned as-is (no local process to patch).
+ * @param {Object} config - MCP server config { command, args, env? } or { type: "http", url }
  * @returns {Object} Patched config (new object, original unmodified)
  */
 export function patchConfigForPlatform(config) {
+  // Remote MCPs need no platform patching
+  if (isRemoteMcp(config)) return config;
   if (config.command !== 'npx') return config;
   return {
     ...config,
@@ -123,9 +135,12 @@ export async function installAutoMcps(targetPath, mcpsToInstall) {
 
   for (const [name, entry] of Object.entries(mcpsToInstall)) {
     let config = { ...entry.install.config };
-    // Only include env if it has actual values
-    if (config.env && Object.values(config.env).every(v => !v)) {
-      delete config.env;
+    // Remote MCPs don't have env to strip
+    if (!isRemoteMcp(config)) {
+      // Only include env if it has actual values
+      if (config.env && Object.values(config.env).every(v => !v)) {
+        delete config.env;
+      }
     }
     servers[name] = patchConfigForPlatform(config);
   }
@@ -156,6 +171,23 @@ export async function installMcpWithCredentials(targetPath, name, mcpEntry, cred
 export function generateSetupInstructions(name, mcpEntry) {
   const config = mcpEntry.install.config;
   const credentials = mcpEntry.install.credentials || [];
+  const setupGuide = mcpEntry.install.setupGuide;
+
+  // Remote HTTP MCPs — show claude mcp add command instead of config snippet
+  if (isRemoteMcp(config)) {
+    const configSnippet = JSON.stringify({ [name]: config }, null, 2);
+    const credentialUrls = credentials.map(c => ({
+      name: c.name,
+      envVar: c.envVar,
+      helpUrl: c.helpUrl
+    }));
+    return {
+      configSnippet,
+      credentialUrls,
+      cliCommand: setupGuide || `claude mcp add --transport http ${name} ${config.url}`,
+      isRemote: true
+    };
+  }
 
   // Build the config snippet with placeholder values
   const snippetConfig = { ...config };

package/src/lib/phase-chain/phase-validator.js

@@ -10,7 +10,6 @@
  */
 
 import fs from 'fs';
-import { existsSync } from 'fs';
 import path, { join } from 'path';
 import { loadState, derivePhase, getFeature } from '../../core/state/state-manager.js';
 import { getWorkflowConfig } from '../../core/workflows/workflow-detector.js';
@@ -53,22 +52,28 @@ export const PHASES = {
     requiredOutputs: ['proposal.md', 'spec.md'],
     description: 'Clarify ambiguities and edge cases'
   },
-  'tasks': {
+  'plan': {
     order: 5,
-    name: 'FASE 4: TASKS',
+    name: 'FASE 4: PLAN',
     requiredOutputs: ['proposal.md', 'spec.md'],
+    description: 'Planning phase before task breakdown'
+  },
+  'tasks': {
+    order: 6,
+    name: 'FASE 5: TASKS',
+    requiredOutputs: ['proposal.md', 'spec.md', 'plan.md'],
     description: 'Break down into executable tasks'
   },
   'implement': {
-    order: 6,
-    name: 'FASE 5: IMPLEMENT',
-    requiredOutputs: ['proposal.md', 'spec.md'],
+    order: 7,
+    name: 'FASE 6: IMPLEMENT',
+    requiredOutputs: ['proposal.md', 'spec.md', 'tasks.md'],
     description: 'Execute tasks and implement code'
   },
   'sync': {
-    order: 7,
-    name: 'FASE 6: SYNC',
-    requiredOutputs: ['proposal.md', 'spec.md', 'decisions.md'],
+    order: 8,
+    name: 'FASE 7: SYNC',
+    requiredOutputs: ['proposal.md', 'spec.md', 'decisions.md', 'recap.md'],
     description: 'Sync decisions to project standards',
     optional: true
   }
@@ -86,8 +91,9 @@ const OUTPUT_PHASE_MAP = {
   'ui-mockups.md': '2-ui',
   'ui-components.md': '2-ui',
   'ui-flows.md': '2-ui',
-  'tasks.md': '3-tasks',
-  'recap.md': '4-implement'
+  'plan.md': '3-plan',
+  'tasks.md': '4-tasks',
+  'recap.md': '5-implement'
 };
 
 function checkOutput(featurePath, outputFile) {
@@ -133,12 +139,12 @@ export function validatePhase(featureName, targetPhase) {
 
   // Special validation: implement phase requires tasks.md to have actual tasks
   if (targetPhase === 'implement') {
-    const tasksFilePath = path.join(featurePath, '3-tasks', 'tasks.md');
+    const tasksFilePath = path.join(featurePath, '4-tasks', 'tasks.md');
     if (fs.existsSync(tasksFilePath)) {
       const content = fs.readFileSync(tasksFilePath, 'utf-8');
       const taskCount = (content.match(/^###\s+T\d+/gm) || []).length;
       if (taskCount === 0) {
-        missingOutputs.push(`tasks.md exists but has no task entries — add ### T001 — Task title entries`);
+        missingOutputs.push(`tasks.md exists but has no task entries — add ### T001: Task title entries`);
       }
     }
   }
@@ -172,7 +178,7 @@ export function validatePhase(featureName, targetPhase) {
 // Phase eligibility
 // ─────────────────────────────────────────────────────────────────────────────
 
-const PHASE_ORDER = ['proposal', 'setup', 'uiux', 'design', 'clarify', 'tasks', 'implement', 'sync'];
+const PHASE_ORDER = ['proposal', 'setup', 'uiux', 'design', 'clarify', 'plan', 'tasks', 'implement', 'sync'];
 
 function getNextPhase(currentPhase) {
   const idx = PHASE_ORDER.indexOf(currentPhase);
@@ -196,7 +202,7 @@ const OUTPUT_PATH_MAP = {
   'proposal': '0-proposal/proposal.md',
   'spec': '1-design/spec.md',
   'contracts': '1-design/contracts.cs',
-  'tasks': '3-tasks/tasks.md',
+  'tasks': '4-tasks/tasks.md',
   'schemaAnalysis': '1-design/schema-analysis.md',
 };
 
@@ -209,7 +215,7 @@ function getMissingRequiredOutputs(featureName, phase, projectPath) {
 
   for (const output of phaseDef.requiredOutputs) {
     const relPath = OUTPUT_PATH_MAP[output];
-    if (relPath && !existsSync(join(featureBase, relPath))) {
+    if (relPath && !fs.existsSync(join(featureBase, relPath))) {
       missing.push(output);
     }
   }

package/src/lib/scope/impact-analyzer.js

@@ -0,0 +1,106 @@
+/**
+ * Impact Analyzer for Scope Escalation
+ *
+ * Analyzes tasks.md + spec.md to determine the impact of a discovered
+ * complexity and recommend an escalation action.
+ *
+ * Pure functions — no I/O, no state mutations.
+ */
+
+/**
+ * Classify impact based on affected task count and spec status.
+ *
+ * @param {{ affectedTasks: string[], specNeedsUpdate: boolean }} input
+ * @returns {{ impact: 'low'|'medium'|'high', recommendation: string, targetPhase?: string }}
+ */
+export function classifyImpact({ affectedTasks, specNeedsUpdate }) {
+  if (specNeedsUpdate) {
+    return { impact: 'high', recommendation: 'regress-design', targetPhase: 'design' };
+  }
+  if (affectedTasks.length <= 3) {
+    return { impact: 'low', recommendation: 'expand' };
+  }
+  return { impact: 'medium', recommendation: 'regress-tasks', targetPhase: 'tasks' };
+}
+
+/**
+ * Parse task IDs from tasks.md content.
+ * @param {string} tasksMd
+ * @returns {string[]} Ordered task IDs
+ */
+function parseTaskIds(tasksMd) {
+  const ids = [];
+  const re = /^###\s+(T\d+)\s*[—–:\-]/gm;
+  let match;
+  while ((match = re.exec(tasksMd)) !== null) {
+    ids.push(match[1]);
+  }
+  return ids;
+}
+
+/**
+ * Find consecutive task IDs starting from a trigger task.
+ * Tasks are "consecutive" if their numeric IDs have no gaps.
+ *
+ * @param {string[]} allIds - All task IDs in order
+ * @param {string} triggerId - The trigger task ID
+ * @returns {string[]} Consecutive group including trigger
+ */
+function findConsecutiveGroup(allIds, triggerId) {
+  const triggerIdx = allIds.indexOf(triggerId);
+  if (triggerIdx === -1) return [triggerId];
+
+  const numOf = id => parseInt(id.replace(/\D/g, ''), 10);
+
+  const group = [triggerId];
+
+  // Look forward
+  for (let i = triggerIdx + 1; i < allIds.length; i++) {
+    const prevNum = numOf(allIds[i - 1]);
+    const currNum = numOf(allIds[i]);
+    if (currNum - prevNum <= 1) {
+      group.push(allIds[i]);
+    } else {
+      break;
+    }
+  }
+
+  // Look backward
+  for (let i = triggerIdx - 1; i >= 0; i--) {
+    const nextNum = numOf(allIds[i + 1]);
+    const currNum = numOf(allIds[i]);
+    if (nextNum - currNum <= 1) {
+      group.unshift(allIds[i]);
+    } else {
+      break;
+    }
+  }
+
+  return group;
+}
+
+/**
+ * Analyze the impact of a scope escalation.
+ *
+ * @param {{ triggerTaskId: string, tasksMd: string, specMd: string, reason: string }} input
+ * @returns {{ triggerTask: string, affectedTasks: string[], impact: string, recommendation: string, targetPhase?: string, reason: string }}
+ */
+export function analyzeImpact({ triggerTaskId, tasksMd, specMd, reason }) {
+  const allIds = parseTaskIds(tasksMd);
+  const affectedTasks = findConsecutiveGroup(allIds, triggerTaskId);
+
+  // Heuristic: detect phrases that indicate the spec itself is wrong, not just casual mentions.
+  // Requires phrases like "spec is wrong", "architecture needs", "contract mismatch", etc.
+  // Avoids false positives on casual uses like "the design of the component" or "schema file".
+  const specPhrases = /\b(spec\s+(is|was|needs|incorrect|wrong|outdated|assumed|missed)|architecture\s+(needs|is wrong|incorrect|mismatch)|contract\s+(mismatch|wrong|incorrect|needs|outdated)|schema\s+(needs|incorrect|wrong|mismatch|change))\b/i;
+  const specNeedsUpdate = specPhrases.test(reason);
+
+  const classification = classifyImpact({ affectedTasks, specNeedsUpdate });
+
+  return {
+    triggerTask: triggerTaskId,
+    affectedTasks,
+    ...classification,
+    reason
+  };
+}

package/src/lib/tasks/task-parser.js

@@ -23,7 +23,7 @@ import { join } from 'path';
  * @returns {Promise<Array<{id, title, status, dependencies, files, checkpoint}>>}
  */
 export async function parseTasksMd(featureName, cwd = process.cwd()) {
-  const tasksPath = join(cwd, `.morph/features/${featureName}/3-tasks/tasks.md`);
+  const tasksPath = join(cwd, `.morph/features/${featureName}/4-tasks/tasks.md`);
   let content = '';
   try {
     content = await readFile(tasksPath, 'utf-8');

package/src/lib/validators/shared/emit-validator-dispatch.js

@@ -0,0 +1,64 @@
+/**
+ * Shared utility: emit a VALIDATION DISPATCH block to stdout.
+ *
+ * Both `advance-phase.js` and `task-manager.js` call this so that the
+ * PostToolUse dispatch hook can parse the JSON via strategy 1 (from
+ * tool_result) without falling back to a subprocess.
+ *
+ * @module emit-validator-dispatch
+ */
+
+import chalk from 'chalk';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Emit a VALIDATION DISPATCH block to stdout for the PostToolUse hook.
+ *
+ * Non-blocking — fails silently on any error.
+ *
+ * @param {string} featureName - Feature name
+ * @param {string} phase - Current phase
+ * @param {string} cwd - Project root
+ */
+export async function emitValidatorDispatch(featureName, phase, cwd) {
+  try {
+    const { buildDispatchConfig } = await import('../../../commands/agents/dispatch-agents.js');
+    const config = await buildDispatchConfig(cwd, featureName, phase, { mode: 'validate' });
+    const validators = config.agents?.filter(a => a.tier === 4);
+    if (!validators || validators.length === 0) return;
+
+    const agentsPath = join(__dirname, '..', '..', '..', '..', 'framework', 'agents.json');
+    const agentsData = JSON.parse(readFileSync(agentsPath, 'utf8'));
+    const allAgents = agentsData.agents || {};
+
+    const validatorEntries = validators.map(v => {
+      const agentData = allAgents[v.id];
+      return {
+        id: v.id,
+        title: v.title,
+        severity: agentData?.hook_behavior?.severity || 'error',
+        blocksOnFail: agentData?.hook_behavior?.blocks_on_fail ?? true,
+        checks: agentData?.hook_behavior?.validates || [],
+        taskPrompt: v.taskPrompt,
+      };
+    });
+
+    const dispatch = {
+      validationRequired: true,
+      phase,
+      feature: featureName,
+      validators: validatorEntries,
+      instruction: 'Dispatch these validators as READ-ONLY subagents before continuing. Each must output { "passed": boolean, "issues": [] }. Blocking validators (blocksOnFail: true) must pass before marking phase complete.',
+    };
+
+    console.log(chalk.cyan('\n--- VALIDATION DISPATCH ---'));
+    console.log(JSON.stringify(dispatch, null, 2));
+    console.log(chalk.cyan('--- END VALIDATION DISPATCH ---\n'));
+  } catch {
+    // Non-blocking — fail silently
+  }
+}

package/src/scripts/setup-infra.js

@@ -228,6 +228,21 @@ export async function setupInfra(targetPath, { _exec = execSync } = {}) {
   log('Step 18: Updating .gitignore...');
   await updateGitignore(targetPath);
 
+  // --- 19. Initialize state.json (only if not exists) ---
+  log('Step 19: Initializing state.json...');
+  const statePath = join(morphPath, 'state.json');
+  if (!(await pathExists(statePath))) {
+    const dirName = targetPath.split(/[\/\\]/).pop();
+    const now = new Date().toISOString();
+    await writeJson(statePath, {
+      version: '5.0.0',
+      project: { name: dirName, type: 'unknown', createdAt: now, updatedAt: now },
+      features: {},
+      threads: {},
+      metadata: { totalFeatures: 0, completedFeatures: 0, totalTimeSpent: 0, lastUpdated: now }
+    });
+  }
+
   log('setup-infra: complete.');
 
   return {

package/src/utils/agents-installer.js

@@ -39,7 +39,9 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
 
   const DOTNET_STACKS = ['dotnet', 'blazor', 'dotnet-api', 'fullstack'];
   const eligible = agents.filter(a => {
-    if (a.tier !== 1 && a.tier !== 2) return false;
+    if (a.tier !== 1 && a.tier !== 2 && a.tier !== 4) return false;
+    // Tier 4 validators must have a teammate with spawn_prompt
+    if (a.tier === 4 && !a.teammate?.spawn_prompt) return false;
     // Skip dotnet-senior for non-.NET projects
     if (a.id === 'dotnet-senior' && projectStack && !DOTNET_STACKS.includes(projectStack)) {
       return false;
@@ -49,9 +51,11 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
 
   let tier1 = 0;
   let tier2 = 0;
+  let tier4 = 0;
   for (const agent of eligible) {
     const slug = agent.id ?? agent.name?.toLowerCase().replace(/\s+/g, '-');
-    const filename = `morph-${slug}.md`;
+    const prefix = agent.tier === 4 ? 'morph-validator-' : 'morph-';
+    const filename = `${prefix}${slug}.md`;
     const targetPath = join(targetDir, filename);
 
     const description = buildDescription(agent);
@@ -63,8 +67,9 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
 
     if (agent.tier === 1) tier1++;
     else if (agent.tier === 2) tier2++;
+    else if (agent.tier === 4) tier4++;
   }
-  return { tier1, tier2 };
+  return { tier1, tier2, tier4 };
 }
 
 /**
@@ -88,6 +93,13 @@ const TIER_DEFAULTS = {
     skills: ['morph:checklist'],
     memory: 'local',
   },
+  4: {
+    model: 'haiku',
+    tools: 'Read, Glob, Grep',
+    maxTurns: 10,
+    skills: [],
+    memory: 'project',
+  },
 };
 
 /**
@@ -101,19 +113,27 @@ const TIER_DEFAULTS = {
 function buildFrontmatter(agent, description) {
   const defaults = TIER_DEFAULTS[agent.tier] ?? TIER_DEFAULTS[2];
   const name = agent.title ?? agent.name;
-  const skillsList = defaults.skills.map(s => `  - ${s}`).join('\n');
 
-  return [
+  // Allow per-agent tool overrides (e.g., morph-spec-validator needs Bash for npm test)
+  const tools = agent.teammate?.tools ?? defaults.tools;
+  // Allow per-agent maxTurns override
+  const maxTurns = agent.teammate?.maxTurns ?? defaults.maxTurns;
+
+  const lines = [
     `name: ${name}`,
     `description: ${description}`,
     `model: ${defaults.model}`,
-    `tools: ${defaults.tools}`,
-    `maxTurns: ${defaults.maxTurns}`,
-    `skills:`,
-    skillsList,
-    `memory: ${defaults.memory}`,
-    '',
-  ].join('\n');
+    `tools: ${tools}`,
+    `maxTurns: ${maxTurns}`,
+  ];
+
+  if (defaults.skills.length > 0) {
+    const skillsList = defaults.skills.map(s => `  - ${s}`).join('\n');
+    lines.push(`skills:`, skillsList);
+  }
+
+  lines.push(`memory: ${defaults.memory}`, '');
+  return lines.join('\n');
 }
 
 function buildDescription(agent) {

package/src/utils/file-copier.js

@@ -144,7 +144,6 @@ export async function updateGitignore(projectPath) {
     '.claude/agents/',
     '.claude/CLAUDE.md',
     '.claude/settings.local.json',
-    '.mcp.json',
     '.worktrees/',
     ''
   ];

package/src/utils/hooks-installer.js

@@ -15,7 +15,7 @@ import { homedir } from 'os';
 import { execSync } from 'child_process';
 
 /** Current hooks schema version — bump when hook definitions change */
-const HOOKS_VERSION = '2.10.0';
+const HOOKS_VERSION = '2.12.0';
 
 /** Marker for old dispatch.js (v1) */
 const OLD_DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';
@@ -63,6 +63,16 @@ const MORPH_HOOKS = [
     }]
   },
 
+  // === SessionStart: compact only — post-compact context restore ===
+  {
+    event: 'SessionStart',
+    matcher: 'compact',
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/session-start/post-compact-restore.js'
+    }]
+  },
+
   // === UserPromptSubmit ===
   {
     event: 'UserPromptSubmit',
@@ -93,6 +103,10 @@ const MORPH_HOOKS = [
       {
         type: 'command',
         command: 'node framework/hooks/claude-code/pre-tool-use/enforce-phase-writes.js'
+      },
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/pre-tool-use/task-tracking-guard.js'
       }
     ]
   },