@polymorphism-tech/morph-spec 4.8.19 → 4.10.0

package/src/commands/agents/dispatch-agents.js

@@ -28,6 +28,9 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 /** Path to agents.json in the installed package */
 const AGENTS_JSON_PATH = join(__dirname, '../../../framework/agents.json');
 
+/** Path to phases.json in the installed package */
+const PHASES_JSON_PATH = join(__dirname, '../../../framework/phases.json');
+
 /** Phases where agent dispatch is meaningful */
 const DISPATCHABLE_PHASES = ['design', 'tasks', 'implement'];
 
@@ -87,6 +90,85 @@ const TASK_CATEGORY_TO_GROUP = {
   'docs': 'docs',
 };
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Required Skills Injection
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Build a mandatory skills block for the given phase.
+ * Reads requiredSkills from phases.json data and formats them as instructions for subagents.
+ * Returns null if no required skills for this phase.
+ *
+ * @param {string} phase - Phase id (e.g. 'implement')
+ * @param {Object|null} phasesData - Parsed phases.json content
+ * @returns {string|null}
+ */
+export function buildSkillsBlock(phase, phasesData) {
+  try {
+    const skills = phasesData?.phases?.[phase]?.requiredSkills;
+    if (!skills || skills.length === 0) return null;
+
+    const triggerLabel = trigger =>
+      trigger.replace(/([A-Z])/g, ' $1').toUpperCase().trim();
+
+    const lines = skills.map(s => `- ${triggerLabel(s.trigger)}: Invoke Skill(${s.skill})`);
+
+    return [
+      'Mandatory Skills (non-negotiable — invoke at the specified trigger points):',
+      ...lines,
+      '',
+      'Do NOT skip these skills. They are required by MORPH-SPEC for this phase.',
+    ].join('\n');
+  } catch {
+    return null;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MCP Awareness Injection
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Build an MCP availability block for the given phase.
+ * Reads recommendedMCPs from phases.json and MCP usage info from mcp-registry.json.
+ * Returns null if no MCPs recommended for this phase.
+ *
+ * @param {string} phase - Phase id (e.g. 'implement')
+ * @param {Object|null} phasesData - Parsed phases.json content
+ * @param {Object} [opts] - Options
+ * @param {string} [opts.registryPath] - Override path to mcp-registry.json
+ * @returns {string|null}
+ */
+export function buildMcpBlock(phase, phasesData, opts = {}) {
+  try {
+    const mcps = phasesData?.phases?.[phase]?.recommendedMCPs;
+    if (!mcps || mcps.length === 0) return null;
+
+    // Try to load registry for usage descriptions
+    let registry = null;
+    const registryPath = opts.registryPath || join(__dirname, '../../../framework/skills/level-0-meta/mcp-registry.json');
+    try {
+      if (existsSync(registryPath)) {
+        registry = JSON.parse(readFileSync(registryPath, 'utf8'));
+      }
+    } catch { /* non-blocking */ }
+
+    const lines = mcps.map(name => {
+      const usage = registry?.mcps?.[name]?.usage || '';
+      return usage ? `- ${name}: ${usage}` : `- ${name}`;
+    });
+
+    return [
+      `Available MCPs for ${phase} phase:`,
+      ...lines,
+      '',
+      'Use MCP tools when available; fall back to native tools (Bash, Read, Grep) when not.',
+    ].join('\n');
+  } catch {
+    return null;
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Helpers
 // ─────────────────────────────────────────────────────────────────────────────
@@ -164,7 +246,7 @@ export function parseAndGroupTasks(tasksPath) {
     const groups = {};
 
     // Match task headings: ### T001 — Title  or  ### T001: Title
-    const taskHeadingRe = /^###\s+(T\d{3,})\s*[—:\-]\s*(.+)$/gm;
+    const taskHeadingRe = /^###\s+(T\d{3,})\s*[—–:\-]\s*(.+)$/gm;
     // Match category line within a task block: **category**: `domain`  or  - category: application
     const categoryRe = /(?:\*\*category\*\*\s*:\s*`?([a-z-]+)`?|category:\s*([a-z-]+))/i;
 
@@ -248,6 +330,17 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
   const agentsData = JSON.parse(readFileSync(agentsPath, 'utf8'));
   const allAgents = agentsData.agents || {};
 
+  // Load phases.json for required skills injection (opts.phasesJsonPath allows override for testing)
+  const phasesPath = opts.phasesJsonPath || PHASES_JSON_PATH;
+  let phasesData = null;
+  try {
+    if (existsSync(phasesPath)) {
+      phasesData = JSON.parse(readFileSync(phasesPath, 'utf8'));
+    }
+  } catch {
+    // Non-blocking — fail silent, skills block will be omitted
+  }
+
   // Active agents from state (keyword-detected during setup phase)
   const activeAgentIds = new Set(feature.activeAgents || []);
 
@@ -296,11 +389,16 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
       rawPrompt = agentData.teammate.spawn_prompt;
     }
 
-    // Append standards digest as Constraints block
+    // Append standards digest as Constraints block, then skills block, then MCP block
     const briefing = buildAgentBriefing(agentId, phase);
-    const fullTaskPrompt = briefing
-      ? `${rawPrompt}\n\nConstraints:\n${briefing}`
-      : rawPrompt;
+    const skillsBlock = buildSkillsBlock(phase, phasesData);
+    const mcpBlock = buildMcpBlock(phase, phasesData);
+    const fullTaskPrompt = [
+      rawPrompt,
+      briefing    ? `\n\nConstraints:\n${briefing}` : '',
+      skillsBlock ? `\n\n${skillsBlock}`            : '',
+      mcpBlock    ? `\n\n${mcpBlock}`               : '',
+    ].join('');
 
     dispatchableAgents.push({
       id: agentId,
@@ -347,7 +445,7 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
 
   if (phase === 'implement') {
     // Group tasks from tasks.md by domain category
-    const tasksPath = join(projectPath, `.morph/features/${featureName}/3-tasks/tasks.md`);
+    const tasksPath = join(projectPath, `.morph/features/${featureName}/4-tasks/tasks.md`);
     const tasksByGroup = parseAndGroupTasks(tasksPath);
 
     for (const [group, taskIds] of Object.entries(tasksByGroup)) {

package/src/commands/mcp/mcp-setup.js

@@ -19,7 +19,8 @@ import {
   installMcpWithCredentials,
   generateSetupInstructions,
   formatMcpStatusTable,
-  loadMcpRegistry
+  loadMcpRegistry,
+  isRemoteMcp
 } from '../../lib/installers/mcp-installer.js';
 import { detectClaudeConfig } from '../../lib/detectors/claude-config-detector.js';
 import { detectProject } from '../../lib/detectors/index.js';
@@ -187,7 +188,43 @@ async function setupSpecificMcp(targetPath, name, stack, existingMcps) {
     return;
   }
 
-  // Needs credentials
+  // Remote HTTP MCP — show setup command and optionally auto-configure
+  if (isRemoteMcp(mcpEntry.install.config)) {
+    console.log(chalk.cyan(`\n  Setting up ${name} MCP (remote)\n`));
+    console.log(chalk.gray(`  Usage: ${mcpEntry.usage}`));
+    console.log('');
+
+    const instructions = generateSetupInstructions(name, mcpEntry);
+    console.log(chalk.white(`  Run this command to add the MCP:`));
+    console.log(chalk.cyan(`  ${instructions.cliCommand}`));
+    console.log('');
+
+    for (const warning of mcpEntry.install.warnings || []) {
+      console.log(chalk.yellow(`  ⚠ ${warning}`));
+    }
+
+    const { installNow } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'installNow',
+      message: 'Add to .claude/settings.local.json now?',
+      default: true
+    }]);
+
+    if (installNow) {
+      const spinner = ora(`Configuring ${name}...`).start();
+      const result = await installAutoMcps(targetPath, { [name]: mcpEntry });
+      if (result.added.length > 0) {
+        spinner.succeed(`${name} MCP configured (authenticate via /mcp in Claude Code)`);
+      } else {
+        spinner.info(`${name} MCP already configured`);
+      }
+    }
+
+    console.log('');
+    return;
+  }
+
+  // Needs credentials (stdio MCPs)
   console.log(chalk.cyan(`\n  Setting up ${name} MCP\n`));
   console.log(chalk.gray(`  Usage: ${mcpEntry.usage}`));
   console.log('');

package/src/commands/phase/phase-reset.js

@@ -0,0 +1,74 @@
+/**
+ * MORPH-SPEC Phase Reset Command
+ *
+ * Recovery tool for corrupted phase state.
+ * Sets the phase directly without approval gate checks.
+ *
+ * Usage:
+ *   morph-spec phase reset <feature> <phase>
+ */
+
+import chalk from 'chalk';
+import { loadState, saveState, derivePhase } from '../../core/state/state-manager.js';
+import { join } from 'path';
+
+const VALID_PHASES = ['proposal', 'setup', 'uiux', 'design', 'clarify', 'plan', 'tasks', 'implement', 'sync'];
+
+/**
+ * Core reset logic — exported for testing.
+ * @param {string} featureName
+ * @param {string} targetPhase
+ * @returns {{ success: boolean, error?: string, derivedPhase?: string }}
+ */
+export function resetPhase(featureName, targetPhase) {
+  if (!VALID_PHASES.includes(targetPhase)) {
+    return {
+      success: false,
+      error: `Unknown phase: "${targetPhase}". Valid phases: ${VALID_PHASES.join(', ')}`
+    };
+  }
+
+  const state = loadState();
+  if (!state?.features?.[featureName]) {
+    return {
+      success: false,
+      error: `Feature "${featureName}" not found in state.json`
+    };
+  }
+
+  // Get filesystem-derived phase for comparison
+  const featureFolderPath = join(process.cwd(), '.morph', 'features', featureName);
+  const derivedPhase = derivePhase(featureFolderPath);
+
+  // Set phase directly — no approval gate checks
+  state.features[featureName].phase = targetPhase;
+  state.features[featureName].updatedAt = new Date().toISOString();
+  saveState(state);
+
+  return { success: true, derivedPhase };
+}
+
+/**
+ * CLI command handler
+ */
+export async function phaseResetCommand(feature, phase) {
+  console.log(chalk.cyan('\n╔════════════════════════════════════════════════╗'));
+  console.log(chalk.cyan('║     MORPH-SPEC PHASE RESET                     ║'));
+  console.log(chalk.cyan('╚════════════════════════════════════════════════╝\n'));
+
+  const result = resetPhase(feature, phase);
+
+  if (!result.success) {
+    console.log(chalk.red(`\n✗ ${result.error}`));
+    process.exit(1);
+  }
+
+  console.log(chalk.green(`✓ Phase reset to "${phase}" for feature "${feature}"`));
+
+  if (result.derivedPhase !== phase) {
+    console.log(chalk.yellow(`\n⚠ Filesystem-derived phase is "${result.derivedPhase}" (folders on disk differ from state)`));
+    console.log(chalk.gray(`  This is expected during recovery. The state.json value takes priority.`));
+  }
+
+  console.log('');
+}

package/src/commands/project/doctor.js

@@ -67,20 +67,6 @@ function getNpmGlobalPrefix() {
 
 // lib files
 const REQUIRED_LIB_FILES = [
-  'src/lib/analytics/analytics-engine.js',
-  'src/lib/tracking/artifact-trail.js',
-  'src/lib/context/context-bundler.js',
-  'src/lib/context/context-optimizer.js',
-  'src/lib/context/context-tracker.js',
-  'src/lib/context/core-four-tracker.js',
-  'src/lib/execution/fusion-executor.js',
-  'src/lib/hops/hop-composer.js',
-  'src/lib/context/mcp-optimizer.js',
-  'src/lib/agents/micro-agent-factory.js',
-  'src/lib/execution/parallel-executor.js',
-  'src/lib/hooks/stop-hook-executor.js',  // Legacy — retained for backward compat
-  'src/lib/threads/thread-coordinator.js',
-  'src/lib/threads/thread-manager.js',
   'src/lib/trust/trust-manager.js'
 ];
 
@@ -90,7 +76,6 @@ const REQUIRED_COMMAND_FILES = [
   'src/commands/project/update.js',
   'src/commands/project/doctor.js',
   'src/commands/project/status.js',
-  'src/commands/project/tutorial.js',
   'src/commands/state/state.js',
   'src/commands/state/advance-phase.js',
   'src/commands/state/approve.js',
@@ -99,23 +84,11 @@ const REQUIRED_COMMAND_FILES = [
   'src/commands/validation/validate-feature.js',
   'src/commands/templates/template-render.js',
   'src/commands/agents/dispatch-agents.js',
-  'src/commands/templates/generate-contracts.js'
-];
-
-// HOP templates (meta-prompts)
-const HOP_TEMPLATES = [
-  'framework/templates/meta-prompts/squad-leaders/backend-squad.md',
-  'framework/templates/meta-prompts/squad-leaders/frontend-squad.md',
-  'framework/templates/meta-prompts/parallel-workers/parallel-worker.md',
-  'framework/templates/meta-prompts/parallel-workers/parallel-coordinator.md',
-  'framework/templates/meta-prompts/hops/hop-wrapper.md',
-  'framework/templates/meta-prompts/hops/hop-retry.md',
-  'framework/templates/meta-prompts/hops/hop-validation.md',
-  'framework/templates/meta-prompts/validators/checkpoint-validator.md',
-  'framework/templates/meta-prompts/validators/pre-commit-validator.md',
-  'framework/templates/meta-prompts/fusion/fusion-agent.md',
-  'framework/templates/meta-prompts/fusion/fusion-aggregator.md',
-  'framework/templates/REGISTRY.json'
+  'src/commands/project/worktree.js',
+  'src/commands/phase/phase-reset.js',
+  'src/commands/scope/escalate.js',
+  'src/commands/task/expand.js',
+  'src/lib/scope/impact-analyzer.js'
 ];
 
 // framework standards
@@ -195,17 +168,7 @@ async function doctorFullCommand(frameworkRoot) {
     missingCmds.length === 0, false,
     missingCmds.length > 0 ? `missing: ${missingCmds.join(', ')}` : '');
 
-  // ── 3. HOP Templates ────────────────────────────────────────────────────
-  console.log(chalk.cyan(`\n  framework/templates/meta-prompts/ — HOP Templates (${HOP_TEMPLATES.length})`));
-  const missingHOPs = [];
-  for (const f of HOP_TEMPLATES) {
-    if (!(await pathExists(join(frameworkRoot, f)))) missingHOPs.push(f.split('/').pop());
-  }
-  check(`HOP Templates (${HOP_TEMPLATES.length - missingHOPs.length}/${HOP_TEMPLATES.length})`,
-    missingHOPs.length === 0, false,
-    missingHOPs.length > 0 ? `missing: ${missingHOPs.join(', ')}` : '');
-
-  // ── 4. Framework Standards ───────────────────────────────────────────────
+  // ── 3. Framework Standards ───────────────────────────────────────────────
   console.log(chalk.cyan(`\n  framework/standards/ — Framework Standards (${FRAMEWORK_STANDARDS.length} files)`));
   const missingStds = [];
   for (const f of FRAMEWORK_STANDARDS) {
@@ -233,10 +196,10 @@ async function doctorFullCommand(frameworkRoot) {
     check('agents.json', false, false, 'file not found');
   }
 
-  // ── 7. Zero-Touch Workflow Config ───────────────────────────────────────
-  console.log(chalk.cyan('\n  framework/workflows/ — Zero-Touch Config'));
-  const ztPath = join(frameworkRoot, 'framework/workflows/configs/zero-touch.json');
-  check('zero-touch.json workflow config', await pathExists(ztPath));
+  // ── 7. Workflow Configs ──────────────────────────────────────────────────
+  console.log(chalk.cyan('\n  framework/workflows/ — Workflow Configs'));
+  const stdPath = join(frameworkRoot, 'framework/workflows/configs/standard.json');
+  check('standard.json workflow config', await pathExists(stdPath));
 
   // ── 8. state.json schema version ────────────────────────────────────────
   console.log(chalk.cyan('\n  .morph/state.json — Schema Version'));
@@ -337,10 +300,18 @@ async function doctorMcpCommand(targetPath) {
   for (const [name, config] of Object.entries(allMcpServers)) {
     const issues = [];
     let status = 'ok';
+    let isRemote = false;
 
-    // ── 1. Binary check ────────────────────────────────────────────────────
+    // ── 0. Remote MCP detection ────────────────────────────────────────────
+    // Remote MCPs use HTTP transport (type: "http" or url property) — no binary to check
+    if (config.type === 'http' || (config.url && !config.command)) {
+      isRemote = true;
+      // Remote MCPs are always "ok" from a config perspective — auth happens at runtime
+    }
+
+    // ── 1. Binary check (stdio MCPs only) ──────────────────────────────────
     const cmd = config.command || '';
-    if (cmd && !KNOWN_RUNTIMES.has(cmd)) {
+    if (!isRemote && cmd && !KNOWN_RUNTIMES.has(cmd)) {
       try {
         execSync(isWindows ? `where "${cmd}"` : `which "${cmd}"`, { stdio: 'ignore' });
       } catch {
@@ -370,12 +341,14 @@ async function doctorMcpCommand(targetPath) {
       }
     }
 
-    checks.push({ name, status, issues, cmd });
+    checks.push({ name, status, issues, cmd, isRemote });
   }
 
   // ── Display ────────────────────────────────────────────────────────────────
   for (const c of checks) {
-    const typeLabel = c.cmd ? chalk.gray(` [${c.cmd}]`) : '';
+    const typeLabel = c.isRemote
+      ? chalk.gray(` [remote: ${allMcpServers[c.name]?.url || 'http'}]`)
+      : c.cmd ? chalk.gray(` [${c.cmd}]`) : '';
 
     if (c.status === 'ok') {
       console.log(chalk.green(`  ✓ ${c.name}`) + typeLabel);
@@ -454,6 +427,16 @@ export async function doctorCommand(options = {}) {
   let hasErrors = false;
   let hasWarnings = false;
 
+  const check = (name, passed, warnOnly = false, msg = '') => {
+    if (passed) {
+      checks.push({ name, status: 'ok' });
+    } else {
+      checks.push({ name, status: warnOnly ? 'warn' : 'missing', msg });
+      if (warnOnly) hasWarnings = true;
+      else hasErrors = true;
+    }
+  };
+
   // Check versions first
   const cliCheck = await checkCLIOutdated();
   const projectCheck = await checkProjectOutdated(targetPath);

package/src/commands/project/init.js

@@ -385,7 +385,7 @@ export async function initCommand(options) {
     // Suggest tutorial for first-time users
     if (integrationsCreated) {
       logger.blank();
-      logger.info('First time using morph-spec? Run `morph-spec tutorial` to get started.');
+      logger.info('First time using morph-spec? Run `/morph-proposal <feature>` to start a new feature.');
     }
 
     logger.blank();

package/src/commands/project/status.js

@@ -14,7 +14,7 @@
 
 import chalk from 'chalk';
 import { loadState, getFeature, derivePhase, deriveOutputs } from '../../core/state/state-manager.js';
-import { PHASES } from '../state/validate-phase.js';
+import { PHASES } from '../../lib/phase-chain/phase-validator.js';
 
 /**
  * Phase symbols for visual representation
@@ -243,7 +243,7 @@ export async function statusCommand(featureName, options = {}) {
     process.exit(1);
   }
 
-  // Derive phase and outputs from filesystem if not stored in state (v5.0.0+)
+  // Derive phase and outputs from filesystem if not stored in state
   const { join } = await import('path');
   const featurePath = join(process.cwd(), '.morph', 'features', featureName);
   if (!feature.phase) {