@polymorphism-tech/morph-spec 4.8.7 → 4.8.9

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

@@ -0,0 +1,430 @@
+/**
+ * dispatch-agents — Build dispatch config for parallel agent orchestration
+ *
+ * Reads activeAgents from state.json + spawn_prompts from agents.json and
+ * outputs a JSON dispatch config that phase skills use to spawn parallel subagents.
+ *
+ * Usage:
+ *   morph-spec dispatch-agents <feature> <phase>
+ *   morph-spec dispatch-agents <feature> <phase> --table
+ *
+ * Output (JSON):
+ * {
+ *   feature, phase, shouldDispatch, reason,
+ *   agents: [{ id, title, tier, icon, role, parallelGroup, canRunParallel, taskPrompt }],
+ *   taskGroups: { [group]: { agentId, description, tasks, canRunParallel, taskPrompt } }
+ * }
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { loadState, stateExists } from '../../core/state/state-manager.js';
+import chalk from 'chalk';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Path to agents.json in the installed package */
+const AGENTS_JSON_PATH = join(__dirname, '../../../framework/agents.json');
+
+/** Phases where agent dispatch is meaningful */
+const DISPATCHABLE_PHASES = ['design', 'tasks', 'implement'];
+
+/**
+ * Domain → parallel group mapping.
+ * Agents inherit group from their first matching domain.
+ */
+const DOMAIN_TO_GROUP = {
+  'backend': 'backend',
+  'backend-data': 'backend',
+  'backend-jobs': 'backend',
+  'backend-events': 'backend',
+  'frontend': 'frontend',
+  'frontend-blazor': 'frontend',
+  'frontend-nextjs': 'frontend',
+  'frontend-css': 'frontend',
+  'frontend-design': 'frontend',
+  'infrastructure': 'infra',
+  'cloud-azure': 'infra',
+  'devops': 'infra',
+  'domain': 'domain-analysis',
+  'domain-modeling': 'domain-analysis',
+  'architecture': 'domain-analysis',
+  'ai-orchestration': 'domain-analysis',
+  'testing': 'tests',
+  'qa': 'tests',
+};
+
+/** Agent-level group overrides (higher priority than domain mapping) */
+const AGENT_GROUP_OVERRIDES = {
+  'domain-architect': 'domain-analysis',
+  'standards-architect': 'domain-analysis',
+  'ai-system-architect': 'domain-analysis',
+  'popm-advisor': 'domain-analysis',
+  'dotnet-senior': 'backend',
+  'infra-architect': 'infra',
+  'ui-designer': 'frontend',
+  'testing-specialist': 'tests',
+  'code-analyzer': 'tests',
+  'load-testing-expert': 'tests',
+  'documentation-specialist': 'docs',
+  'troubleshooting-expert': 'support',
+};
+
+/**
+ * Task category → parallel group mapping for implement-phase task splitting.
+ * Matches task categories defined in phase-tasks SKILL.md.
+ */
+const TASK_CATEGORY_TO_GROUP = {
+  'domain': 'backend',
+  'domain-bc': 'backend',
+  'infrastructure': 'backend',
+  'application': 'backend',
+  'presentation': 'frontend',
+  'tests': 'tests',
+  'infra': 'infra',
+  'docs': 'docs',
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Determine the parallel execution group for an agent.
+ * Priority: explicit override → domain mapping → tier fallback.
+ *
+ * @param {string} agentId
+ * @param {Object} agentData
+ * @returns {string} group name
+ */
+function getAgentGroup(agentId, agentData) {
+  if (AGENT_GROUP_OVERRIDES[agentId]) return AGENT_GROUP_OVERRIDES[agentId];
+
+  const domains = agentData.domains || [];
+  for (const domain of domains) {
+    if (DOMAIN_TO_GROUP[domain]) return DOMAIN_TO_GROUP[domain];
+  }
+
+  // Tier-2 domain leaders default to backend if no domain matched
+  if (agentData.tier === 2) return 'backend';
+  return 'backend';
+}
+
+/**
+ * Check whether an agent should be dispatched for the given phase.
+ *
+ * Rules (in priority order):
+ * 1. Tier-4 validators → never dispatch (no task work)
+ * 2. Agent-level `active_phases` array → use that list
+ * 3. Relationships-level `active_phases` array → use that list
+ * 4. `always_active: true` → dispatchable for all DISPATCHABLE_PHASES
+ * 5. Default: specialists without active_phases → implement only
+ *
+ * @param {string} agentId
+ * @param {Object} agentData
+ * @param {string} phase
+ * @returns {boolean}
+ */
+function isRelevantForPhase(agentId, agentData, phase) {
+  // Tier-4 validators have no implementation tasks
+  if (agentData.tier === 4) return false;
+
+  // Explicit active_phases on agent root
+  if (Array.isArray(agentData.active_phases)) {
+    return agentData.active_phases.includes(phase);
+  }
+
+  // active_phases nested in relationships
+  const relPhases = agentData.relationships?.active_phases;
+  if (Array.isArray(relPhases)) {
+    return relPhases.includes(phase);
+  }
+
+  // always_active agents: dispatch for all recognised phases
+  if (agentData.always_active && DISPATCHABLE_PHASES.includes(phase)) return true;
+
+  // Specialists without active_phases: implement phase only
+  return phase === 'implement';
+}
+
+/**
+ * Parse tasks.md and return a map of { parallelGroup → taskId[] }.
+ * Gracefully returns {} if the file doesn't exist or is unparseable.
+ *
+ * @param {string} tasksPath - Absolute path to tasks.md
+ * @returns {Object}
+ */
+export function parseAndGroupTasks(tasksPath) {
+  if (!existsSync(tasksPath)) return {};
+
+  try {
+    const content = readFileSync(tasksPath, 'utf8');
+    const groups = {};
+
+    // Match task headings: ### T001 — Title  or  ### T001: Title
+    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;
+
+    let headingMatch;
+    const taskPositions = [];
+
+    while ((headingMatch = taskHeadingRe.exec(content)) !== null) {
+      taskPositions.push({ id: headingMatch[1], pos: headingMatch.index });
+    }
+
+    for (let i = 0; i < taskPositions.length; i++) {
+      const { id, pos } = taskPositions[i];
+      const end = i + 1 < taskPositions.length ? taskPositions[i + 1].pos : content.length;
+      const block = content.slice(pos, end);
+
+      const catMatch = categoryRe.exec(block);
+      const category = (catMatch?.[1] || catMatch?.[2] || 'application').toLowerCase();
+      const group = TASK_CATEGORY_TO_GROUP[category] || 'backend';
+
+      if (!groups[group]) groups[group] = [];
+      groups[group].push(id);
+    }
+
+    return groups;
+  } catch {
+    return {};
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Core Logic
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Build dispatch config for a feature and phase.
+ *
+ * @param {string} projectPath - Absolute path to project root (cwd)
+ * @param {string} featureName - Feature name
+ * @param {string} phase - Phase: 'design' | 'tasks' | 'implement'
+ * @param {Object} [opts] - Optional overrides (for testing)
+ * @param {string} [opts.agentsJsonPath] - Override path to agents.json
+ * @returns {Object} Dispatch config
+ */
+export async function buildDispatchConfig(projectPath, featureName, phase, opts = {}) {
+  // Load state
+  const state = loadState(false);
+  if (!state) {
+    return {
+      shouldDispatch: false,
+      reason: 'state.json not found — run morph-spec state init',
+      agents: [],
+      taskGroups: {},
+    };
+  }
+
+  const feature = state.features?.[featureName];
+  if (!feature) {
+    return {
+      feature: featureName,
+      phase,
+      shouldDispatch: false,
+      reason: `Feature '${featureName}' not found in state.json`,
+      agents: [],
+      taskGroups: {},
+    };
+  }
+
+  // Load agents.json (opts.agentsJsonPath allows override for testing)
+  const agentsPath = opts.agentsJsonPath || AGENTS_JSON_PATH;
+  if (!existsSync(agentsPath)) {
+    return {
+      feature: featureName,
+      phase,
+      shouldDispatch: false,
+      reason: 'framework/agents.json not found',
+      agents: [],
+      taskGroups: {},
+    };
+  }
+
+  const agentsData = JSON.parse(readFileSync(agentsPath, 'utf8'));
+  const allAgents = agentsData.agents || {};
+
+  // Active agents from state (keyword-detected during setup phase)
+  const activeAgentIds = new Set(feature.activeAgents || []);
+
+  // Collect dispatchable agents
+  // Process all agents: active ones from state + always_active ones not yet in state
+  const processed = new Set();
+  const dispatchableAgents = [];
+
+  const candidateIds = [
+    ...activeAgentIds,
+    // Add always_active agents that might not have been explicitly detected
+    ...Object.entries(allAgents)
+      .filter(([id, data]) => !id.startsWith('_comment') && data.always_active)
+      .map(([id]) => id),
+  ];
+
+  for (const agentId of candidateIds) {
+    if (processed.has(agentId)) continue;
+    processed.add(agentId);
+
+    const agentData = allAgents[agentId];
+    if (!agentData || agentId.startsWith('_comment')) continue;
+
+    // Must have a spawn_prompt to be dispatchable
+    if (!agentData.teammate?.spawn_prompt) continue;
+
+    // Phase relevance check
+    if (!isRelevantForPhase(agentId, agentData, phase)) continue;
+
+    const group = getAgentGroup(agentId, agentData);
+
+    dispatchableAgents.push({
+      id: agentId,
+      title: agentData.title,
+      tier: agentData.tier,
+      icon: agentData.teammate.icon || '🤖',
+      role: agentData.teammate.role,
+      parallelGroup: group,
+      canRunParallel: true,
+      taskPrompt: agentData.teammate.spawn_prompt,
+    });
+  }
+
+  // Sort: domain-analysis first, then by tier (ascending), then alphabetically
+  const groupOrder = ['domain-analysis', 'backend', 'frontend', 'infra', 'tests', 'docs', 'support'];
+  dispatchableAgents.sort((a, b) => {
+    const gi = groupOrder.indexOf(a.parallelGroup);
+    const gj = groupOrder.indexOf(b.parallelGroup);
+    if (gi !== gj) return gi - gj;
+    if (a.tier !== b.tier) return a.tier - b.tier;
+    return a.id.localeCompare(b.id);
+  });
+
+  const shouldDispatch = dispatchableAgents.length >= 2;
+
+  // ── Task groups ────────────────────────────────────────────────────────────
+  const taskGroups = {};
+
+  if (phase === 'implement') {
+    // Group tasks from tasks.md by domain category
+    const tasksPath = join(projectPath, `.morph/features/${featureName}/3-tasks/tasks.md`);
+    const tasksByGroup = parseAndGroupTasks(tasksPath);
+
+    for (const [group, taskIds] of Object.entries(tasksByGroup)) {
+      const groupAgent = dispatchableAgents.find(a => a.parallelGroup === group);
+      taskGroups[group] = {
+        agentId: groupAgent?.id ?? null,
+        description: `${group} implementation tasks for feature '${featureName}'`,
+        tasks: taskIds,
+        canRunParallel: true,
+        taskPrompt: groupAgent?.taskPrompt ?? null,
+      };
+    }
+  } else {
+    // For design/tasks: one group per parallel group, no task IDs yet
+    const seenGroups = new Set();
+    for (const agent of dispatchableAgents) {
+      if (seenGroups.has(agent.parallelGroup)) continue;
+      seenGroups.add(agent.parallelGroup);
+
+      taskGroups[agent.parallelGroup] = {
+        agentId: agent.id,
+        description: agent.role,
+        tasks: [],
+        canRunParallel: true,
+        taskPrompt: agent.taskPrompt,
+      };
+    }
+  }
+
+  return {
+    feature: featureName,
+    phase,
+    shouldDispatch,
+    reason: shouldDispatch
+      ? `${dispatchableAgents.length} dispatchable agents for phase '${phase}'`
+      : dispatchableAgents.length === 1
+        ? `Only 1 dispatchable agent — sequential execution preferred`
+        : `No dispatchable agents found for phase '${phase}'`,
+    agents: dispatchableAgents,
+    taskGroups,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CLI Handler
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * CLI command: morph-spec dispatch-agents <feature> <phase>
+ */
+export async function dispatchAgentsCommand(featureName, phase, options = {}) {
+  if (!featureName || !phase) {
+    console.error(chalk.red('Usage: morph-spec dispatch-agents <feature> <phase>'));
+    console.error(chalk.gray('Phases: design | tasks | implement'));
+    process.exit(1);
+  }
+
+  const normalizedPhase = phase.toLowerCase();
+  if (!DISPATCHABLE_PHASES.includes(normalizedPhase)) {
+    console.error(chalk.red(`Invalid phase: '${phase}'. Must be one of: ${DISPATCHABLE_PHASES.join(', ')}`));
+    process.exit(1);
+  }
+
+  if (!stateExists()) {
+    console.error(chalk.red('No state.json found. Run morph-spec state init first.'));
+    process.exit(1);
+  }
+
+  try {
+    const config = await buildDispatchConfig(process.cwd(), featureName, normalizedPhase);
+
+    if (options.table) {
+      // Human-readable table format
+      console.log(chalk.bold(`\n  Dispatch Config — ${featureName} (${normalizedPhase})`));
+      console.log('  ' + '─'.repeat(62));
+
+      const dispatchLabel = config.shouldDispatch ? chalk.green('YES') : chalk.yellow('NO');
+      console.log(`  Should dispatch: ${dispatchLabel}`);
+      console.log(`  Reason:          ${config.reason}`);
+
+      if (config.agents?.length > 0) {
+        console.log(`\n  Agents (${config.agents.length}):`);
+        console.log(`  ${'ID'.padEnd(28)} ${'Group'.padEnd(16)} Tier`);
+        console.log('  ' + '─'.repeat(50));
+        for (const agent of config.agents) {
+          console.log(
+            `  ${(agent.icon + ' ' + agent.id).padEnd(28)} ` +
+            `${chalk.cyan(agent.parallelGroup.padEnd(16))} ` +
+            `${agent.tier}`
+          );
+        }
+      } else {
+        console.log(chalk.gray('\n  No dispatchable agents.'));
+      }
+
+      const groupEntries = Object.entries(config.taskGroups || {});
+      if (groupEntries.length > 0) {
+        console.log(`\n  Task Groups:`);
+        console.log(`  ${'Group'.padEnd(20)} ${'Tasks'.padEnd(8)} Agent`);
+        console.log('  ' + '─'.repeat(50));
+        for (const [group, data] of groupEntries) {
+          const taskCount = data.tasks?.length || 0;
+          console.log(
+            `  ${group.padEnd(20)} ` +
+            `${String(taskCount).padEnd(8)} ` +
+            `${data.agentId || chalk.gray('none')}`
+          );
+        }
+      }
+      console.log();
+    } else {
+      // JSON (default — consumed by phase skills / LLM)
+      console.log(JSON.stringify(config, null, 2));
+    }
+  } catch (err) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    if (options.verbose) console.error(err.stack);
+    process.exit(1);
+  }
+}

package/src/commands/agents/index.js

@@ -1,3 +1,4 @@
 /**
- * Agent Commands — no active commands after CLI simplification
+ * Agent Commands
  */
+export { dispatchAgentsCommand, buildDispatchConfig } from './dispatch-agents.js';

package/src/commands/project/doctor.js

@@ -1,4 +1,4 @@
-import { join } from 'path';
+import { join, relative } from 'path';
 import { execSync } from 'child_process';
 import { platform, homedir } from 'os';
 import fs from 'fs-extra';
@@ -97,7 +97,9 @@ const REQUIRED_COMMAND_FILES = [
   'src/commands/tasks/task.js',
   'src/commands/trust/trust.js',
   'src/commands/validation/validate-feature.js',
-  'src/commands/templates/template-render.js'
+  'src/commands/templates/template-render.js',
+  'src/commands/agents/dispatch-agents.js',
+  'src/commands/templates/generate-contracts.js'
 ];
 
 // HOP templates (meta-prompts)
@@ -134,6 +136,7 @@ const FRAMEWORK_STANDARDS = [
   'framework/standards/architecture/ddd/aggregates.md',
   'framework/standards/architecture/ddd/entities.md',
   'framework/standards/architecture/ddd/value-objects.md',
+  'framework/standards/architecture/vertical-slice/vertical-slice.md',
   'framework/standards/data/vector-search/azure-ai-search.md',
   'framework/standards/data/vector-search/rag-chunking.md',
   'framework/standards/context/priming.md',
@@ -278,6 +281,134 @@ async function doctorFullCommand(frameworkRoot) {
   }
 }
 
+/**
+ * MCP health check: reads settings.json / settings.local.json and validates
+ * each configured MCP server's command binary and env var requirements.
+ *
+ * Strategy:
+ *  - "ok"   : command binary exists (or is a known runtime like npx/node) AND
+ *             all env vars referenced in args/env are set in process.env
+ *  - "warn" : binary found but env vars missing (MCP won't auth)
+ *  - "missing": command binary not found in PATH
+ *
+ * NOTE: This does NOT test actual connectivity — that requires spawning the MCP.
+ * It's a static configuration health check that catches 80% of "MCP not working" cases.
+ */
+async function doctorMcpCommand(targetPath) {
+  logger.header('MCP Server Health Check');
+  logger.blank();
+
+  const settingsPaths = [
+    join(targetPath, '.claude', 'settings.json'),
+    join(targetPath, '.claude', 'settings.local.json'),
+  ];
+
+  const allMcpServers = {};
+  const sourcesFound = [];
+
+  for (const sp of settingsPaths) {
+    if (await pathExists(sp)) {
+      try {
+        const settings = JSON.parse(await fs.readFile(sp, 'utf8'));
+        const mcps = settings.mcpServers || {};
+        const count = Object.keys(mcps).length;
+        if (count > 0) {
+          Object.assign(allMcpServers, mcps);
+          sourcesFound.push(`${relative(targetPath, sp)} (${count})`);
+        }
+      } catch { /* invalid JSON — ignore */ }
+    }
+  }
+
+  if (Object.keys(allMcpServers).length === 0) {
+    logger.warn('No MCP servers configured');
+    logger.blank();
+    logger.dim('Configure MCPs in: .claude/settings.json → mcpServers: { ... }');
+    logger.dim('Or use: morph-spec mcp setup');
+    return;
+  }
+
+  logger.dim(`Sources: ${sourcesFound.join(', ')}`);
+  logger.blank();
+
+  const KNOWN_RUNTIMES = new Set(['npx', 'node', 'python', 'python3', 'uvx', 'bun', 'deno']);
+  const checks = [];
+
+  for (const [name, config] of Object.entries(allMcpServers)) {
+    const issues = [];
+    let status = 'ok';
+
+    // ── 1. Binary check ────────────────────────────────────────────────────
+    const cmd = config.command || '';
+    if (cmd && !KNOWN_RUNTIMES.has(cmd)) {
+      try {
+        execSync(isWindows ? `where "${cmd}"` : `which "${cmd}"`, { stdio: 'ignore' });
+      } catch {
+        status = 'missing';
+        issues.push(`command "${cmd}" not found in PATH`);
+      }
+    }
+
+    // ── 2. Env vars from config.env ────────────────────────────────────────
+    for (const [key, val] of Object.entries(config.env || {})) {
+      if (typeof val === 'string' && (val.startsWith('${') || (val.startsWith('$') && !val.includes(' ')))) {
+        const varName = val.replace(/^\$\{?/, '').replace(/\}$/, '');
+        if (!process.env[varName]) {
+          if (status === 'ok') status = 'warn';
+          issues.push(`env "${key}" → $${varName} not set`);
+        }
+      }
+    }
+
+    // ── 3. Env refs in args array ──────────────────────────────────────────
+    const argsStr = (config.args || []).join(' ');
+    const envRefsInArgs = [...argsStr.matchAll(/\$\{?([A-Z_][A-Z0-9_]*)\}?/g)].map(m => m[1]);
+    for (const varName of envRefsInArgs) {
+      if (!process.env[varName] && !(config.env || {})[varName]) {
+        if (status === 'ok') status = 'warn';
+        issues.push(`args reference $${varName} which is not set`);
+      }
+    }
+
+    checks.push({ name, status, issues, cmd });
+  }
+
+  // ── Display ────────────────────────────────────────────────────────────────
+  for (const c of checks) {
+    const typeLabel = c.cmd ? chalk.gray(` [${c.cmd}]`) : '';
+
+    if (c.status === 'ok') {
+      console.log(chalk.green(`  ✓ ${c.name}`) + typeLabel);
+    } else if (c.status === 'warn') {
+      console.log(chalk.yellow(`  ⚠ ${c.name}`) + typeLabel);
+      c.issues.forEach(issue => console.log(chalk.gray(`    → ${issue}`)));
+    } else {
+      console.log(chalk.red(`  ✗ ${c.name}`) + typeLabel);
+      c.issues.forEach(issue => console.log(chalk.gray(`    → ${issue}`)));
+    }
+  }
+
+  logger.blank();
+
+  const ok = checks.filter(c => c.status === 'ok').length;
+  const warn = checks.filter(c => c.status === 'warn').length;
+  const missing = checks.filter(c => c.status === 'missing').length;
+
+  if (missing > 0) {
+    console.log(chalk.red(`  ❌ ${ok}/${checks.length} OK — ${missing} MCP(s) have missing binaries`));
+    process.exit(1);
+  } else if (warn > 0) {
+    console.log(chalk.yellow(`  ⚠️  ${ok}/${checks.length} OK — ${warn} MCP(s) have missing env vars (won't authenticate)`));
+  } else {
+    console.log(chalk.green(`  ✅ ${ok}/${checks.length} — All MCPs configured correctly`));
+  }
+
+  logger.blank();
+  logger.dim('Note: "configured correctly" = binary exists + env vars set.');
+  logger.dim('      Does NOT test actual connectivity or authentication.');
+  logger.blank();
+}
+
 export async function doctorCommand(options = {}) {
   // Reset mode: remove morph-managed settings entries
   if (options.reset) {
@@ -310,6 +441,11 @@ export async function doctorCommand(options = {}) {
     return doctorFullCommand(frameworkRoot);
   }
 
+  // MCP health check mode
+  if (options.mcp) {
+    return doctorMcpCommand(process.cwd());
+  }
+
   const targetPath = process.cwd();
 
   logger.header('MORPH-SPEC Health Check');

package/src/commands/state/state.js

@@ -139,10 +139,19 @@ async function getCommand(featureName, options) {
       const featurePath = join(process.cwd(), '.morph/features', featureName);
       const phase = derivePhase(featurePath);
       const tasks = feature.tasks || { completed: 0, total: 0 };
-      logger.info(`Status: ${chalk.cyan(feature.status)}`);
-      logger.info(`Phase: ${chalk.cyan(phase)}`);
-      logger.info(`Tasks: ${chalk.cyan(`${tasks.completed}/${tasks.total}`)}`);
-      logger.info(`Agents: ${chalk.cyan((feature.activeAgents || []).join(', ') || 'None')}`);
+      // Prefer taskList.length as total when tasks.total is stale/zero (Problem 3 complement)
+      const total = tasks.total || (Array.isArray(feature.taskList) ? feature.taskList.length : 0);
+      const taskDisplay = total > 0
+        ? `${tasks.completed}/${total}`
+        : tasks.completed > 0 ? `${tasks.completed}/? (run task done to sync)` : '0/? (tasks not yet loaded)';
+      logger.info(`Status:  ${chalk.cyan(feature.status || 'draft')}`);
+      logger.info(`Phase:   ${chalk.cyan(phase)}`);
+      logger.info(`Tasks:   ${chalk.cyan(taskDisplay)}`);
+      logger.info(`Agents:  ${chalk.cyan((feature.activeAgents || []).join(', ') || 'None')}`);
+      const outputs = Object.keys(feature.outputs || {}).filter(k => feature.outputs[k]?.created);
+      if (outputs.length > 0) {
+        logger.info(`Outputs: ${chalk.cyan(outputs.join(', '))}`);
+      }
       logger.blank();
     }
 
@@ -165,6 +174,13 @@ async function setCommand(featureName, key, value, options) {
   }
 
   try {
+    // Warn when bypassing the validated phase advance flow
+    if (key === 'phase') {
+      logger.warn(`Direct phase override — all validation gates will be bypassed.`);
+      logger.dim(`  Recommended: morph-spec phase advance ${featureName}`);
+      logger.blank();
+    }
+
     const spinner = ora('Updating state...').start();
 
     // Parse value automatically (JSON, number, boolean)