@polymorphism-tech/morph-spec 4.8.19 → 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

@@ -0,0 +1,336 @@
+/**
+ * Phase Validator — centralized phase validation and eligibility checking.
+ *
+ * Exports: PHASES, validatePhase, computePassRate, checkPhaseEligibility
+ *
+ * Callers:
+ *   - src/commands/state/advance-phase.js
+ *   - src/commands/state/phase-runner.js
+ *   - src/commands/project/status.js
+ */
+
+import fs 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';
+import { shouldAutoApprove } from '../trust/trust-manager.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Phase definitions (from validate-phase.js)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const PHASES = {
+  'proposal': {
+    order: 0,
+    name: 'FASE 0: PROPOSAL',
+    requiredOutputs: [],
+    description: 'Initial proposal and agent detection'
+  },
+  'setup': {
+    order: 1,
+    name: 'FASE 1: SETUP',
+    requiredOutputs: ['proposal.md'],
+    description: 'Load context and standards'
+  },
+  'uiux': {
+    order: 2,
+    name: 'FASE 1.5: UI/UX DESIGN',
+    requiredOutputs: ['proposal.md'],
+    optionalOutputs: ['ui-design-system.md', 'ui-mockups.md', 'ui-components.md', 'ui-flows.md'],
+    description: 'UI/UX design (conditional - only if frontend)',
+    optional: true
+  },
+  'design': {
+    order: 3,
+    name: 'FASE 2: DESIGN',
+    requiredOutputs: ['proposal.md'],
+    description: 'Technical specification and contracts'
+  },
+  'clarify': {
+    order: 4,
+    name: 'FASE 3: CLARIFY',
+    requiredOutputs: ['proposal.md', 'spec.md'],
+    description: 'Clarify ambiguities and edge cases'
+  },
+  'plan': {
+    order: 5,
+    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: 7,
+    name: 'FASE 6: IMPLEMENT',
+    requiredOutputs: ['proposal.md', 'spec.md', 'tasks.md'],
+    description: 'Execute tasks and implement code'
+  },
+  'sync': {
+    order: 8,
+    name: 'FASE 7: SYNC',
+    requiredOutputs: ['proposal.md', 'spec.md', 'decisions.md', 'recap.md'],
+    description: 'Sync decisions to project standards',
+    optional: true
+  }
+};
+
+// Map output filenames to their phase subfolders
+const OUTPUT_PHASE_MAP = {
+  'proposal.md': '0-proposal',
+  'schema-analysis.md': '1-design',
+  'spec.md': '1-design',
+  'clarifications.md': '1-design',
+  'contracts.cs': '1-design',
+  'decisions.md': '1-design',
+  'ui-design-system.md': '2-ui',
+  'ui-mockups.md': '2-ui',
+  'ui-components.md': '2-ui',
+  'ui-flows.md': '2-ui',
+  'plan.md': '3-plan',
+  'tasks.md': '4-tasks',
+  'recap.md': '5-implement'
+};
+
+function checkOutput(featurePath, outputFile) {
+  const phaseDir = OUTPUT_PHASE_MAP[outputFile] || '';
+  const filePath = path.join(featurePath, phaseDir, outputFile);
+  return fs.existsSync(filePath);
+}
+
+/**
+ * Validate phase prerequisites for a feature.
+ * Used by advance-phase.js before advancing.
+ */
+export function validatePhase(featureName, targetPhase) {
+  const featurePath = path.join(process.cwd(), '.morph/features', featureName);
+
+  if (!fs.existsSync(featurePath)) {
+    return {
+      valid: false,
+      error: `Feature directory not found: ${featurePath}`,
+      suggestion: `Run 'morph-spec state init ${featureName}' to start`,
+      missingOutputs: [],
+      phase: null
+    };
+  }
+
+  const phaseDefinition = PHASES[targetPhase];
+  if (!phaseDefinition) {
+    return {
+      valid: false,
+      error: `Unknown phase: ${targetPhase}`,
+      validPhases: Object.keys(PHASES),
+      missingOutputs: [],
+      phase: null
+    };
+  }
+
+  const missingOutputs = [];
+  for (const output of phaseDefinition.requiredOutputs) {
+    if (!checkOutput(featurePath, output)) {
+      missingOutputs.push(output);
+    }
+  }
+
+  // Special validation: implement phase requires tasks.md to have actual tasks
+  if (targetPhase === 'implement') {
+    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`);
+      }
+    }
+  }
+
+  // Warn if skipping phases
+  let stateWarning = null;
+  try {
+    const feature = getFeature(featureName);
+    if (feature) {
+      const currentPhaseOrder = PHASES[feature.phase]?.order ?? -1;
+      const targetPhaseOrder = phaseDefinition.order;
+      if (targetPhaseOrder > currentPhaseOrder + 1) {
+        stateWarning = `Skipping phases: current is '${feature.phase}' (order ${currentPhaseOrder}), target is '${targetPhase}' (order ${targetPhaseOrder})`;
+      }
+    }
+  } catch {
+    // State file may not exist
+  }
+
+  return {
+    valid: missingOutputs.length === 0,
+    error: null,
+    missingOutputs,
+    phase: phaseDefinition,
+    featurePath,
+    stateWarning
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Phase eligibility
+// ─────────────────────────────────────────────────────────────────────────────
+
+const PHASE_ORDER = ['proposal', 'setup', 'uiux', 'design', 'clarify', 'plan', 'tasks', 'implement', 'sync'];
+
+function getNextPhase(currentPhase) {
+  const idx = PHASE_ORDER.indexOf(currentPhase);
+  if (idx === -1 || idx >= PHASE_ORDER.length - 1) return null;
+  return PHASE_ORDER[idx + 1];
+}
+
+/**
+ * Compute overall validation pass rate from validationHistory.
+ * Returns null when no history exists.
+ */
+export function computePassRate(validationHistory) {
+  if (!validationHistory || Object.keys(validationHistory).length === 0) return null;
+  const entries = Object.values(validationHistory);
+  const passed = entries.filter(e => e.status === 'passed').length;
+  return entries.length > 0 ? passed / entries.length : null;
+}
+
+// Map output type names to file paths for eligibility checks
+const OUTPUT_PATH_MAP = {
+  'proposal': '0-proposal/proposal.md',
+  'spec': '1-design/spec.md',
+  'contracts': '1-design/contracts.cs',
+  'tasks': '4-tasks/tasks.md',
+  'schemaAnalysis': '1-design/schema-analysis.md',
+};
+
+function getMissingRequiredOutputs(featureName, phase, projectPath) {
+  const phaseDef = PHASES[phase];
+  if (!phaseDef?.requiredOutputs) return [];
+
+  const missing = [];
+  const featureBase = join(projectPath, '.morph', 'features', featureName);
+
+  for (const output of phaseDef.requiredOutputs) {
+    const relPath = OUTPUT_PATH_MAP[output];
+    if (relPath && !fs.existsSync(join(featureBase, relPath))) {
+      missing.push(output);
+    }
+  }
+
+  return missing;
+}
+
+function getBlockedTasks(feature) {
+  const history = feature.validationHistory || {};
+  return Object.entries(history)
+    .filter(([, entry]) => entry.status === 'blocked')
+    .map(([taskId]) => taskId);
+}
+
+/**
+ * Check whether a feature is eligible to auto-advance to the next phase.
+ * Used by phase-runner.js.
+ */
+export function checkPhaseEligibility(featureName, opts = {}) {
+  const projectPath = opts.projectPath || process.cwd();
+
+  const state = loadState(false);
+  if (!state) {
+    return {
+      eligible: false,
+      blockers: [{ type: 'state_error', items: ['state.json not found'] }],
+      currentPhase: 'unknown',
+      nextPhase: null,
+      passRate: null,
+    };
+  }
+
+  const feature = state.features?.[featureName];
+  if (!feature) {
+    return {
+      eligible: false,
+      blockers: [{ type: 'state_error', items: [`Feature '${featureName}' not found in state.json`] }],
+      currentPhase: 'unknown',
+      nextPhase: null,
+      passRate: null,
+    };
+  }
+
+  const featureFolderPath = join(projectPath, '.morph', 'features', featureName);
+  const currentPhase = feature.phase || derivePhase(featureFolderPath);
+  const nextPhase = getNextPhase(currentPhase);
+
+  if (!nextPhase) {
+    return {
+      eligible: false,
+      blockers: [{ type: 'state_error', items: ['Feature is at the final phase'] }],
+      currentPhase,
+      nextPhase: null,
+      passRate: null,
+    };
+  }
+
+  let workflowConfig = null;
+  if (feature.workflow && feature.workflow !== 'auto') {
+    try {
+      workflowConfig = getWorkflowConfig(feature.workflow);
+    } catch {
+      // Non-blocking: fall through to defaults
+    }
+  }
+
+  const minPassRate = workflowConfig?.phaseChain?.pauseOn
+    ? 0.80
+    : workflowConfig?.eligibility?.minPassRate ?? 0.80;
+
+  const blockers = [];
+
+  const missingOutputs = getMissingRequiredOutputs(featureName, currentPhase, projectPath);
+  if (missingOutputs.length > 0) {
+    blockers.push({ type: 'missing_outputs', items: missingOutputs });
+  }
+
+  const blockedTasks = getBlockedTasks(feature);
+  if (blockedTasks.length > 0) {
+    blockers.push({ type: 'blocked_tasks', items: blockedTasks });
+  }
+
+  const passRate = computePassRate(feature.validationHistory);
+  if (passRate !== null && passRate < minPassRate) {
+    blockers.push({
+      type: 'low_pass_rate',
+      current: passRate,
+      required: minPassRate,
+    });
+  }
+
+  try {
+    const requiredGateMap = { design: 'design', tasks: 'tasks', uiux: 'uiux' };
+    const gate = requiredGateMap[currentPhase];
+    if (gate) {
+      const trustResult = shouldAutoApprove(featureName, gate);
+      if (!trustResult.autoApprove) {
+        const gateStatus = feature.approvalGates?.[gate];
+        if (!gateStatus?.approved) {
+          blockers.push({
+            type: 'trust_too_low',
+            items: [`Gate '${gate}' requires trust level ${trustResult.level || 'medium+'}`],
+          });
+        }
+      }
+    }
+  } catch {
+    // Trust manager unavailable — non-blocking
+  }
+
+  return {
+    eligible: blockers.length === 0,
+    blockers,
+    currentPhase,
+    nextPhase,
+    passRate,
+  };
+}

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

@@ -0,0 +1,88 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+/** @typedef {'nextjs'|'blazor'|'dotnet'|'nodejs-cli'|'unknown'} StackName */
+
+/**
+ * @typedef {Object} StackProfile
+ * @property {StackName} stack
+ * @property {boolean} isDotnet
+ * @property {boolean} isNextjs
+ * @property {string[]} defaultValidators
+ * @property {string[]} checkpointValidators
+ * @property {'contracts'|'contractsTs'} contractsOutputType
+ * @property {'contracts.cs'|'contracts.ts'} contractsFilename
+ * @property {'csharp'|'typescript'} contractsLanguage
+ */
+
+const DOTNET_STACKS = new Set(['dotnet', 'blazor', 'aspnet', 'dotnet-blazor']);
+const NEXTJS_STACKS = new Set(['nextjs', 'next', 'next.js']);
+const NO_VALIDATOR_STACKS = new Set(['nodejs-cli', 'node-cli', 'cli']);
+
+const PROFILES = {
+  dotnet: {
+    isDotnet: true, isNextjs: false,
+    defaultValidators: ['architecture', 'packages'],
+    checkpointValidators: ['architecture', 'packages', 'design-system', 'security'],
+    contractsOutputType: 'contracts',
+    contractsFilename: 'contracts.cs',
+    contractsLanguage: 'csharp',
+  },
+  nextjs: {
+    isDotnet: false, isNextjs: true,
+    defaultValidators: ['nextjs-component'],
+    checkpointValidators: ['nextjs-component', 'css'],
+    contractsOutputType: 'contractsTs',
+    contractsFilename: 'contracts.ts',
+    contractsLanguage: 'typescript',
+  },
+  empty: {
+    isDotnet: false, isNextjs: false,
+    defaultValidators: [],
+    checkpointValidators: [],
+    contractsOutputType: 'contracts',
+    contractsFilename: 'contracts.cs',
+    contractsLanguage: 'csharp',
+  },
+};
+
+/**
+ * Read project stack from .morph/config/config.json.
+ * @param {string} cwd - Project root
+ * @returns {string|null}
+ */
+function readStack(cwd) {
+  const configPath = join(cwd, '.morph', 'config', 'config.json');
+  if (!existsSync(configPath)) return null;
+  try {
+    return JSON.parse(readFileSync(configPath, 'utf8')).project?.stack ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get the StackProfile for the current project.
+ * @param {string} [cwd] - Project root. Defaults to process.cwd().
+ * @param {string} [stackOverride] - Skip config read and use this stack directly.
+ * @returns {StackProfile}
+ */
+export function getStackProfile(cwd, stackOverride) {
+  const root = cwd ?? process.cwd();
+  const raw = stackOverride ?? readStack(root);
+  const stack = raw?.toLowerCase() ?? 'unknown';
+
+  let profile;
+  if (NEXTJS_STACKS.has(stack)) {
+    profile = PROFILES.nextjs;
+  } else if (NO_VALIDATOR_STACKS.has(stack)) {
+    profile = PROFILES.empty;
+  } else if (DOTNET_STACKS.has(stack) || stack === 'unknown') {
+    profile = PROFILES.dotnet;
+  } else {
+    // Unknown non-.NET stack → empty validators, dotnet contracts (backward compat)
+    profile = PROFILES.empty;
+  }
+
+  return { stack, ...profile };
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Task classifier — identifies test/validation tasks by title.
+ */
+
+const TEST_TASK_PATTERN = /\b(tests?|testing|specs?|coverage|e2e|unit|integration|integra[cç][aã]o|valida[cç][aã]o|cobertura|testes?)\b/i;
+
+/**
+ * Returns true if the task title indicates a testing or validation task.
+ *
+ * @param {string} taskTitle
+ * @returns {boolean}
+ */
+export function isTestTask(taskTitle) {
+  if (!taskTitle) return false;
+  return TEST_TASK_PATTERN.test(taskTitle);
+}

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');