@polymorphism-tech/morph-spec 4.9.0 → 4.10.1

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/stack-filter.js

@@ -0,0 +1,58 @@
+/**
+ * Parse `stacks:` from YAML frontmatter content.
+ * Returns ['*'] if no stacks field found (backwards compatible — always install).
+ *
+ * Supports:
+ *   stacks:\n  - dotnet\n  - blazor   (YAML list)
+ *   stacks: [dotnet, blazor]           (inline array)
+ *
+ * @param {string} content - Raw file content with YAML frontmatter
+ * @returns {string[]}
+ */
+export function parseStacks(content) {
+  const normalized = content.replace(/\r\n/g, '\n');
+  const fmMatch = normalized.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) return ['*'];
+
+  const fm = fmMatch[1];
+
+  // Try inline format: stacks: [dotnet, blazor]
+  const inlineMatch = fm.match(/^stacks:\s*\[([^\]]*)\]/m);
+  if (inlineMatch) {
+    const items = inlineMatch[1].split(',').map(s => s.trim()).filter(Boolean);
+    return items.length > 0 ? items : ['*'];
+  }
+
+  // Try YAML list format: stacks:\n  - dotnet\n  - blazor
+  const listMatch = fm.match(/^stacks:\s*\n((?:\s+-\s+.+\n?)*)/m);
+  if (listMatch) {
+    const items = listMatch[1]
+      .split('\n')
+      .map(line => line.replace(/^\s+-\s+/, '').replace(/["']/g, '').trim())
+      .filter(Boolean);
+    return items.length > 0 ? items : ['*'];
+  }
+
+  return ['*'];
+}
+
+/**
+ * Extract project stack tags from config object.
+ * Splits `project.stack` by '-' to produce tag array.
+ */
+export function getProjectTags(config) {
+  const stack = config?.project?.stack;
+  if (!stack || typeof stack !== 'string') return [];
+  return stack.split('-').filter(Boolean);
+}
+
+/**
+ * Determine if an asset should be installed for the given project tags.
+ * - stacks includes '*' → always install
+ * - stacks is empty → treat as '*' (backwards compatible)
+ * - Otherwise → install if intersection with projectTags is non-empty
+ */
+export function shouldInstall(assetStacks, projectTags) {
+  if (assetStacks.length === 0 || assetStacks.includes('*')) return true;
+  return assetStacks.some(s => projectTags.includes(s));
+}

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

@@ -14,6 +14,7 @@
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
+import { readFileSync, readdirSync, copyFileSync, unlinkSync } from 'fs';
 import {
   copyDirectory,
   copyFile,
@@ -23,6 +24,8 @@ import {
   writeFile,
   updateGitignore
 } from '../utils/file-copier.js';
+import { parseStacks, getProjectTags, shouldInstall } from '../lib/stack-filter.js';
+import { injectMorphImport } from '../utils/claude-md-injector.js';
 import { saveProjectMorphVersion, getInstalledCLIVersion } from '../utils/version-checker.js';
 import { installClaudeHooks, installGlobalStatusline, installVSCodeTerminalSettings, installShellIntegration } from '../utils/claude-settings-manager.js';
 import { installSkills } from '../utils/skills-installer.js';
@@ -47,6 +50,35 @@ async function installRequiredPlugins(log, exec) {
   }
 }
 
+/**
+ * Install only stack-matching rules from rulesSrc to rulesDest.
+ * Also removes orphan rules in rulesDest that are no longer in the install set.
+ *
+ * @param {string} rulesSrc - Source rules directory (framework/rules/)
+ * @param {string} rulesDest - Destination rules directory (.claude/rules/)
+ * @param {string[]} projectTags - Stack tags from config (e.g., ['dotnet', 'blazor'])
+ */
+export function installRulesForStack(rulesSrc, rulesDest, projectTags) {
+  const sourceFiles = readdirSync(rulesSrc).filter(f => f.endsWith('.md'));
+  const installed = new Set();
+
+  for (const file of sourceFiles) {
+    const content = readFileSync(join(rulesSrc, file), 'utf-8');
+    const stacks = parseStacks(content);
+    if (shouldInstall(stacks, projectTags)) {
+      copyFileSync(join(rulesSrc, file), join(rulesDest, file));
+      installed.add(file);
+    }
+  }
+
+  // Cleanup orphans
+  for (const file of readdirSync(rulesDest).filter(f => f.endsWith('.md'))) {
+    if (!installed.has(file)) {
+      unlinkSync(join(rulesDest, file));
+    }
+  }
+}
+
 /**
  * Installs MORPH-SPEC infrastructure into the target project directory.
  * Headless — no prompts, no spinner (suppressed when MORPH_QUIET=1), no stack detection.
@@ -63,19 +95,12 @@ export async function setupInfra(targetPath, { _exec = execSync } = {}) {
   // --- 0. Install required Claude Code plugins ---
   await installRequiredPlugins(log, _exec);
 
-  // --- 1. Copy CLAUDE.md (backup existing non-MORPH CLAUDE.md) ---
-  log('Step 1: Copying CLAUDE.md...');
+  // --- 1. Inject @import into root CLAUDE.md (preserves user content) ---
+  log('Step 1: Setting up CLAUDE.md...');
   const claudeMdSrc = join(FRAMEWORK_DIR, 'CLAUDE.md');
   const claudeMdDest = join(targetPath, 'CLAUDE.md');
-
-  if (await pathExists(claudeMdDest)) {
-    const { readFile } = await import('../utils/file-copier.js');
-    const existingContent = await readFile(claudeMdDest);
-    if (!existingContent.includes('MORPH-SPEC')) {
-      await copyFile(claudeMdDest, `${claudeMdDest}.backup`);
-    }
-  }
-  await copyFile(claudeMdSrc, claudeMdDest);
+  const importResult = await injectMorphImport(claudeMdDest);
+  log(`  ✓ Root CLAUDE.md: ${importResult}`);
 
   // --- 2. Create .morph directory structure ---
   log('Step 2: Creating .morph structure...');
@@ -163,27 +188,37 @@ export async function setupInfra(targetPath, { _exec = execSync } = {}) {
     await copyDirectory(commandsSrc, commandsDest);
   }
 
-  // --- 10. Copy framework/rules → .claude/rules ---
+  // --- Compute project tags for stack-aware installation ---
+  let projectTags = [];
+  if (await pathExists(configPath)) {
+    try {
+      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+      projectTags = getProjectTags(config);
+    } catch { /* ignore malformed config */ }
+  }
+
+  // --- 10. Copy framework/rules → .claude/rules (filtered by stack) ---
   log('Step 10: Installing path-scoped rules...');
   const rulesSrc = join(FRAMEWORK_DIR, 'rules');
   const rulesDest = join(claudeDest, 'rules');
   if (await pathExists(rulesSrc)) {
-    await copyDirectory(rulesSrc, rulesDest);
+    await ensureDir(rulesDest);
+    installRulesForStack(rulesSrc, rulesDest, projectTags);
   }
 
-  // --- 11. installSkills ---
+  // --- 11. installSkills (filtered by stack) ---
   log('Step 11: Installing skills...');
-  await installSkills(targetPath);
+  await installSkills(targetPath, { projectTags });
 
   // --- 12. installAgents ---
   log('Step 12: Installing agents...');
   const agentCounts = await installAgents(targetPath, FRAMEWORK_DIR, { projectStack: null });
 
-  // --- 13. installDomainAgents ---
+  // --- 13. installDomainAgents (filtered by stack) ---
   log('Step 13: Installing domain agents...');
-  const domainCounts = await installDomainAgents(targetPath, FRAMEWORK_DIR);
+  const domainCounts = await installDomainAgents(targetPath, FRAMEWORK_DIR, { projectTags });
 
-  // --- 14. Copy framework/CLAUDE.md → .claude/CLAUDE.md ---
+  // --- 14. Copy framework/CLAUDE.md → .claude/CLAUDE.md (morph-owned, gitignored) ---
   log('Step 14: Installing .claude/CLAUDE.md...');
   const runtimeClaudeMdDest = join(claudeDest, 'CLAUDE.md');
   if (await pathExists(claudeMdSrc)) {
@@ -228,6 +263,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 {