@polymorphism-tech/morph-spec 7.2.0 → 7.3.0

package/src/commands/project/doctor.js

@@ -1,946 +1,941 @@
-import { join, relative } from 'path';
-import { execSync } from 'child_process';
-import { platform, homedir } from 'os';
-import fs from 'fs-extra';
-import chalk from 'chalk';
-import { logger } from '../../utils/logger.js';
-import { pathExists, readJson } from '../../utils/file-copier.js';
-import { checkClaudeMdImport } from '../../utils/claude-md-injector.js';
-import {
-  checkCLIOutdated,
-  checkProjectOutdated,
-  getInstalledCLIVersion
-} from '../../utils/version-checker.js';
-import { resetMorphSettings } from '../../utils/claude-settings-manager.js';
-import { checkMissingAgents } from '../../utils/agents-installer.js';
-import { getProjectTags } from '../../lib/stack-filter.js';
-
-const isWindows = platform() === 'win32';
-/**
- * Check which required Claude Code plugins are installed.
- * @param {Object} pluginsData - The `plugins` object from installed_plugins.json
- * @returns {{ superpowers: boolean, context7: boolean }}
- */
-export function checkInstalledPlugins(pluginsData) {
-  const REQUIRED = ['superpowers', 'context7'];
-  return Object.fromEntries(
-    REQUIRED.map(name => [name, `${name}@claude-plugins-official` in (pluginsData || {})])
-  );
-}
-
-
-/**
- * Check if morph-spec command is in PATH
- */
-function isMorphSpecInPath() {
-  try {
-    const command = isWindows ? 'where morph-spec' : 'which morph-spec';
-    execSync(command, { stdio: 'ignore' });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Detect if nvm-windows is installed
- */
-function isUsingNvmWindows() {
-  if (!isWindows) return false;
-
-  try {
-    const path = process.env.PATH || '';
-    return path.includes('nvm4w') || path.includes('\\nvm\\');
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Get npm global prefix
- */
-function getNpmGlobalPrefix() {
-  try {
-    const prefix = execSync('npm config get prefix', { encoding: 'utf8' }).trim();
-    return prefix;
-  } catch {
-    return null;
-  }
-}
-
-// lib files (v5 — minimal surface)
-const REQUIRED_LIB_FILES = [
-  'src/lib/stack-filter.js'
-];
-
-// command files (v5 CLI surface — installer-only)
-const REQUIRED_COMMAND_FILES = [
-  'src/commands/project/init.js',
-  'src/commands/project/update.js',
-  'src/commands/project/doctor.js',
-  'src/commands/project/status.js',
-  'src/commands/project/worktree.js',
-  'src/commands/state/approve.js',
-  'src/commands/validation/validate-feature.js',
-  'src/commands/scaffold/scaffold.js',
-  'src/commands/mcp/mcp-setup.js',
-  'src/commands/context/context-refresh.js',
-];
-
-// framework standards (stack-relevant only)
-const FRAMEWORK_STANDARDS = [
-  'framework/standards/architecture/vertical-slice/vertical-slice.md',
-  'framework/standards/data/nosql/cosmos-db.md',
-  'framework/standards/data/nosql/cache/redis.md',
-  'framework/standards/data/vector-search/rag-chunking.md',
-  'framework/standards/integration/mcp/mcp-tools.md',
-  'framework/standards/workflows/thread-management.md',
-  'framework/standards/workflows/parallel-execution.md'
-];
-
-// required personas expected in agents.json (v5 — at least the universal evaluator)
-const REQUIRED_AGENTS = [
-  'evaluator'
-];
-
-/**
- * Run full health checks
- */
-async function doctorFullCommand(frameworkRoot) {
-  console.log(chalk.bold('\n🔬 MORPH-SPEC Full Health Check\n'));
-  console.log('─'.repeat(60));
-
-  const checks = [];
-  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;
-    }
-  };
-
-  // ── 1. Core Libraries ───────────────────────────────────────────────────
-  console.log(chalk.cyan(`\n  src/lib/ — Core Libraries (${REQUIRED_LIB_FILES.length} files)`));
-  const missingLibs = [];
-  for (const f of REQUIRED_LIB_FILES) {
-    if (!(await pathExists(join(frameworkRoot, f)))) missingLibs.push(f.split('/').pop());
-  }
-  check(`Core Libraries (${REQUIRED_LIB_FILES.length - missingLibs.length}/${REQUIRED_LIB_FILES.length})`,
-    missingLibs.length === 0, false,
-    missingLibs.length > 0 ? `missing: ${missingLibs.join(', ')}` : '');
-
-  // ── 2. Command Files ─────────────────────────────────────────────────────
-  console.log(chalk.cyan(`\n  src/commands/ — Command Files (${REQUIRED_COMMAND_FILES.length} files)`));
-  const missingCmds = [];
-  for (const f of REQUIRED_COMMAND_FILES) {
-    if (!(await pathExists(join(frameworkRoot, f)))) missingCmds.push(f.split('/').pop());
-  }
-  check(`Command Files (${REQUIRED_COMMAND_FILES.length - missingCmds.length}/${REQUIRED_COMMAND_FILES.length})`,
-    missingCmds.length === 0, false,
-    missingCmds.length > 0 ? `missing: ${missingCmds.join(', ')}` : '');
-
-  // ── 3. Framework Standards ───────────────────────────────────────────────
-  console.log(chalk.cyan(`\n  framework/standards/ — Framework Standards (${FRAMEWORK_STANDARDS.length} files)`));
-  const missingStds = [];
-  for (const f of FRAMEWORK_STANDARDS) {
-    if (!(await pathExists(join(frameworkRoot, f)))) missingStds.push(f.replace('framework/standards/', ''));
-  }
-  check(`Framework Standards (${FRAMEWORK_STANDARDS.length - missingStds.length}/${FRAMEWORK_STANDARDS.length})`,
-    missingStds.length === 0, false,
-    missingStds.length > 0 ? `missing: ${missingStds.join(', ')}` : '');
-
-  // ── 5. Required Agents in agents.json ───────────────────────────────────
-  console.log(chalk.cyan(`\n  .morph/framework/agents.json — Required Agents (${REQUIRED_AGENTS.length})`));
-  const agentsPath = join(frameworkRoot, '.morph/framework/agents.json');
-  if (await pathExists(agentsPath)) {
-    try {
-      const agentsConfig = JSON.parse(await fs.readFile(agentsPath, 'utf8'));
-      const agents = agentsConfig.agents || {};
-      const missingAgents = REQUIRED_AGENTS.filter(id => !agents[id]);
-      check(`Required Agents (${REQUIRED_AGENTS.length - missingAgents.length}/${REQUIRED_AGENTS.length})`,
-        missingAgents.length === 0, false,
-        missingAgents.length > 0 ? `missing: ${missingAgents.join(', ')}` : '');
-    } catch {
-      check('agents.json parse', false, false, 'invalid JSON');
-    }
-  } else {
-    check('agents.json', false, false, 'file not found');
-  }
-
-  // ── 6. agents.json version freshness ──────────────────────────────────
-  const canonicalAgentsPath = join(frameworkRoot, 'framework/agents.json');
-  if (await pathExists(agentsPath) && await pathExists(canonicalAgentsPath)) {
-    try {
-      const installed = JSON.parse(await fs.readFile(agentsPath, 'utf8'));
-      const canonical = JSON.parse(await fs.readFile(canonicalAgentsPath, 'utf8'));
-      const installedVer = installed.version || 'unknown';
-      const canonicalVer = canonical.version || 'unknown';
-      const isFresh = installedVer === canonicalVer;
-      check(`agents.json version (${installedVer})`, isFresh, true,
-        isFresh ? '' : `stale — canonical is v${canonicalVer}, run 'morph-spec update' to sync`);
-    } catch { /* ignore parse errors — already caught above */ }
-  }
-
-  // ── 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'));
-  const statePath = join(frameworkRoot, '.morph/state.json');
-  if (await pathExists(statePath)) {
-    try {
-      const state = JSON.parse(await fs.readFile(statePath, 'utf8'));
-      const isCurrent = state.version === '5.0.0';
-      check(`state.json schema (${state.version})`, isCurrent, true,
-        isCurrent ? '' : `expected 5.0.0, found ${state.version} — run any CLI command to auto-migrate`);
-    } catch {
-      check('state.json parse', false, false, 'invalid JSON');
-    }
-  } else {
-    check('state.json', false, true, 'not found (run: morph-spec init)');
-  }
-
-  // ── Display ──────────────────────────────────────────────────────────────
-  console.log('\n' + '─'.repeat(60));
-  console.log(chalk.bold('\nResults:\n'));
-  for (const c of checks) {
-    if (c.status === 'ok') {
-      console.log(chalk.green(`  ✓ ${c.name}`));
-    } else if (c.status === 'warn') {
-      console.log(chalk.yellow(`  ⚠ ${c.name}`) + chalk.gray(c.msg ? ` (${c.msg})` : ''));
-    } else {
-      console.log(chalk.red(`  ✗ ${c.name}`) + chalk.gray(c.msg ? ` — ${c.msg}` : ''));
-    }
-  }
-
-  console.log('');
-  const passed = checks.filter(c => c.status === 'ok').length;
-  const total = checks.length;
-
-  if (hasErrors) {
-    console.log(chalk.red(`\n❌ ${passed}/${total} checks passed — see errors above\n`));
-    process.exit(1);
-  } else if (hasWarnings) {
-    console.log(chalk.yellow(`\n⚠️  ${passed}/${total} checks passed (warnings only)\n`));
-  } else {
-    console.log(chalk.green(`\n✅ ${passed}/${total} — All checks passed!\n`));
-  }
-}
-
-/**
- * MCP health check: reads .mcp.json, settings.json, and 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 allMcpServers = {};
-  const sourcesFound = [];
-
-  // Primary: .mcp.json (Claude Code reads MCPs from here)
-  const mcpJsonPath = join(targetPath, '.mcp.json');
-  if (await pathExists(mcpJsonPath)) {
-    try {
-      const mcpJson = JSON.parse(await fs.readFile(mcpJsonPath, 'utf8'));
-      const mcps = mcpJson.mcpServers || {};
-      const count = Object.keys(mcps).length;
-      if (count > 0) {
-        Object.assign(allMcpServers, mcps);
-        sourcesFound.push(`.mcp.json (${count})`);
-      }
-    } catch { /* invalid JSON — ignore */ }
-  }
-
-  // Legacy: settings files (for backward compat)
-  const settingsPaths = [
-    join(targetPath, '.claude', 'settings.json'),
-    join(targetPath, '.claude', 'settings.local.json'),
-  ];
-
-  for (const sp of settingsPaths) {
-    if (await pathExists(sp)) {
-      try {
-        const settings = JSON.parse(await fs.readFile(sp, 'utf8'));
-        const mcps = settings.mcpServers || {};
-        let addedCount = 0;
-        for (const [name, config] of Object.entries(mcps)) {
-          if (!allMcpServers[name]) {
-            allMcpServers[name] = config;
-            addedCount++;
-          }
-        }
-        if (addedCount > 0) {
-          sourcesFound.push(`${relative(targetPath, sp)} (${addedCount})`);
-        }
-      } catch { /* invalid JSON — ignore */ }
-    }
-  }
-
-  if (Object.keys(allMcpServers).length === 0) {
-    logger.warn('No MCP servers configured');
-    logger.blank();
-    logger.dim('Configure MCPs in: .mcp.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';
-    let isRemote = false;
-
-    // ── 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 (!isRemote && 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, isRemote });
-  }
-
-  // ── Display ────────────────────────────────────────────────────────────────
-  for (const c of checks) {
-    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);
-    } 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) {
-    const targetPath = process.cwd();
-    logger.header('MORPH-SPEC Settings Reset');
-
-    const result = await resetMorphSettings(targetPath);
-
-    if (!result.removed) {
-      logger.warn(`Nothing to reset: ${result.reason}`);
-      return;
-    }
-
-    logger.success('Morph-managed settings removed.');
-    if (result.permissionsRemoved?.length > 0) {
-      logger.dim(`  Permissions removed: ${result.permissionsRemoved.join(', ')}`);
-    }
-    if (result.envRemoved?.length > 0) {
-      logger.dim(`  Env vars removed: ${result.envRemoved.join(', ')}`);
-    }
-    if (result.backupPath) {
-      logger.dim(`  Backup saved: ${result.backupPath}`);
-    }
-    return;
-  }
-
-  // full health check mode
-  if (options.full) {
-    const frameworkRoot = process.cwd();
-    return doctorFullCommand(frameworkRoot);
-  }
-
-  // MCP health check mode
-  if (options.mcp) {
-    return doctorMcpCommand(process.cwd());
-  }
-
-  const targetPath = process.cwd();
-
-  logger.header('MORPH-SPEC Health Check');
-
-  const checks = [];
-  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);
-
-  // CLI Version
-  if (cliCheck.latest) {
-    if (cliCheck.isOutdated) {
-      checks.push({
-        name: `CLI version (${cliCheck.current})`,
-        status: 'warn',
-        msg: `outdated, ${cliCheck.latest} available`
-      });
-      hasWarnings = true;
-    } else {
-      checks.push({
-        name: `CLI version (${cliCheck.current})`,
-        status: 'ok',
-        msg: 'latest'
-      });
-    }
-  } else {
-    checks.push({
-      name: `CLI version (${cliCheck.current})`,
-      status: 'ok'
-    });
-  }
-
-  // Project MORPH version
-  if (projectCheck.current) {
-    if (projectCheck.isOutdated) {
-      checks.push({
-        name: `Project MORPH version (${projectCheck.current})`,
-        status: 'warn',
-        msg: `outdated, ${projectCheck.cliVersion} available`
-      });
-      hasWarnings = true;
-    } else {
-      checks.push({
-        name: `Project MORPH version (${projectCheck.current})`,
-        status: 'ok'
-      });
-    }
-  } else {
-    checks.push({
-      name: 'Project MORPH version',
-      status: 'warn',
-      msg: 'not found (legacy installation)'
-    });
-    hasWarnings = true;
-  }
-
-  // Check if morph-spec is in PATH
-  const inPath = isMorphSpecInPath();
-  if (inPath) {
-    checks.push({
-      name: 'morph-spec in PATH',
-      status: 'ok'
-    });
-  } else {
-    checks.push({
-      name: 'morph-spec in PATH',
-      status: 'warn',
-      msg: 'command not found'
-    });
-    hasWarnings = true;
-  }
-
-  // Check CLAUDE.md has morph-spec @import
-  const claudeMd = join(targetPath, 'CLAUDE.md');
-  const claudeMdStatus = await checkClaudeMdImport(claudeMd);
-  if (claudeMdStatus === 'ok') {
-    checks.push({ name: 'CLAUDE.md', status: 'ok' });
-  } else if (claudeMdStatus === 'missing-import') {
-    checks.push({ name: 'CLAUDE.md', status: 'warn', msg: 'missing @.claude/CLAUDE.md import — run morph-spec update' });
-    hasWarnings = true;
-  } else {
-    checks.push({ name: 'CLAUDE.md', status: 'missing' });
-    hasErrors = true;
-  }
-
-  // Check .morph folder
-  const morphPath = join(targetPath, '.morph');
-  if (await pathExists(morphPath)) {
-    checks.push({ name: '.morph/', status: 'ok' });
-  } else {
-    checks.push({ name: '.morph/', status: 'missing' });
-    hasErrors = true;
-  }
-
-  // Check config.json
-  const configPath = join(morphPath, 'config', 'config.json');
-  if (await pathExists(configPath)) {
-    try {
-      const config = await readJson(configPath);
-      if (config.project?.name) {
-        checks.push({ name: 'config.json', status: 'ok' });
-      } else {
-        checks.push({ name: 'config.json', status: 'warn', msg: 'project.name not set' });
-      }
-    } catch {
-      checks.push({ name: 'config.json', status: 'error', msg: 'invalid JSON' });
-      hasErrors = true;
-    }
-  } else {
-    checks.push({ name: 'config.json', status: 'missing' });
-    hasErrors = true;
-  }
-
-  // Check agents.json
-  const agentsPath = join(morphPath, 'framework', 'agents.json');
-  if (await pathExists(agentsPath)) {
-    try {
-      const agentsData = JSON.parse(await fs.readFile(agentsPath, 'utf8'));
-      const agentEntries = Object.entries(agentsData.agents || {})
-        .filter(([k]) => !k.startsWith('_comment'));
-      const actualCount = agentEntries.length;
-      const declaredCount = agentsData.total_agents;
-
-      // Check 1: total_agents matches actual count
-      if (actualCount !== declaredCount) {
-        checks.push({
-          name: 'agents.json count',
-          status: 'warn',
-          msg: `total_agents declares ${declaredCount} but found ${actualCount} agents`
-        });
-        hasWarnings = true;
-      } else {
-        checks.push({ name: 'agents.json count', status: 'ok', msg: `${actualCount} agents` });
-      }
-
-      // Check 2: required v5 personas present
-      const requiredPersonas = REQUIRED_AGENTS;
-      const missingPersonas = requiredPersonas.filter(id => !agentsData.agents[id]);
-      if (missingPersonas.length > 0) {
-        checks.push({
-          name: 'agents.json required personas',
-          status: 'error',
-          msg: `Missing required personas: ${missingPersonas.join(', ')}`
-        });
-        hasErrors = true;
-      } else {
-        checks.push({ name: 'agents.json required personas', status: 'ok' });
-      }
-
-      // Check 3: v5 schema validation (flat personas, no tiers)
-      const version = agentsData.version || 'unknown';
-      const isV5 = version.startsWith('5.');
-      const v4Fields = [];
-      const missingV5Fields = [];
-
-      for (const [id, data] of agentEntries) {
-        if (data.tier !== undefined) v4Fields.push(`${id}.tier`);
-        if (data.active_phases !== undefined) v4Fields.push(`${id}.active_phases`);
-        if (data.reports_to !== undefined) v4Fields.push(`${id}.reports_to`);
-        if (data.teammate !== undefined) v4Fields.push(`${id}.teammate`);
-        if (!data.title) missingV5Fields.push(`${id}.title`);
-        if (!Array.isArray(data.domains)) missingV5Fields.push(`${id}.domains`);
-        if (typeof data.persona !== 'string' || !data.persona) missingV5Fields.push(`${id}.persona`);
-      }
-
-      if (isV5) {
-        checks.push({ name: `agents.json schema (v${version})`, status: 'ok' });
-      } else {
-        checks.push({
-          name: `agents.json schema (v${version})`,
-          status: 'warn',
-          msg: 'expected v5.x — run agents migration'
-        });
-        hasWarnings = true;
-      }
-
-      if (v4Fields.length > 0) {
-        const sample = v4Fields.slice(0, 3).join(', ');
-        checks.push({
-          name: 'agents.json deprecated v4 fields',
-          status: 'warn',
-          msg: `${v4Fields.length} v4 field(s) found: ${sample}${v4Fields.length > 3 ? '...' : ''}`
-        });
-        hasWarnings = true;
-      }
-
-      if (missingV5Fields.length > 0 && isV5) {
-        const sample = missingV5Fields.slice(0, 3).join(', ');
-        checks.push({
-          name: 'agents.json v5 required fields',
-          status: 'warn',
-          msg: `${missingV5Fields.length} missing: ${sample}${missingV5Fields.length > 3 ? '...' : ''}`
-        });
-        hasWarnings = true;
-      }
-    } catch {
-      checks.push({ name: 'agents.json', status: 'error', msg: 'invalid JSON' });
-      hasErrors = true;
-    }
-  } else {
-    checks.push({ name: 'agents.json', status: 'missing' });
-    hasErrors = true;
-  }
-
-  // Check standards (either in project .morph/framework/standards/ or in framework package)
-  const standardsPath = join(morphPath, 'framework', 'standards');
-  const frameworkStdsRoot = join(import.meta.dirname, '..', '..', '..', 'framework', 'standards');
-  if (await pathExists(standardsPath)) {
-    // Check for VSA standard (core to the framework)
-    const vsaStd = await pathExists(join(standardsPath, 'architecture', 'vertical-slice', 'vertical-slice.md')) ||
-                   await pathExists(join(standardsPath, 'vertical-slice.md'));
-    if (vsaStd) {
-      checks.push({ name: 'standards/', status: 'ok' });
-    } else {
-      checks.push({ name: 'standards/', status: 'warn', msg: 'VSA standard missing — run morph-spec init' });
-      hasWarnings = true;
-    }
-  } else if (await pathExists(frameworkStdsRoot)) {
-    // Framework package has standards (dev/global install mode)
-    checks.push({ name: 'standards/', status: 'warn', msg: 'not installed in project (run morph-spec init)' });
-    hasWarnings = true;
-  } else {
-    checks.push({ name: 'standards/', status: 'missing' });
-    hasErrors = true;
-  }
-
-  // Check templates
-  const templatesPath = join(morphPath, 'framework', 'templates');
-  if (await pathExists(templatesPath)) {
-    checks.push({ name: 'templates/', status: 'ok' });
-  } else {
-    checks.push({ name: 'templates/', status: 'missing' });
-    hasErrors = true;
-  }
-
-  // Check .claude folder
-  const claudePath = join(targetPath, '.claude');
-  if (await pathExists(claudePath)) {
-    const commandsPath = join(claudePath, 'commands');
-    const skillsPath = join(claudePath, 'skills');
-
-    const hasCommands = await pathExists(commandsPath);
-    const hasSkills = await pathExists(skillsPath);
-
-    if (hasCommands && hasSkills) {
-      checks.push({ name: '.claude/', status: 'ok' });
-
-      // Check skills link status
-      const skillEntries = await fs.readdir(skillsPath, { withFileTypes: true });
-      const skillDirs = skillEntries.filter(e => e.isDirectory() || e.isSymbolicLink());
-      let linkedCount = 0;
-
-      for (const dir of skillDirs) {
-        try {
-          const stat = await fs.lstat(join(skillsPath, dir.name));
-          if (stat.isSymbolicLink()) linkedCount++;
-        } catch { /* ignore */ }
-      }
-
-      if (skillDirs.length > 0) {
-        if (linkedCount === skillDirs.length) {
-          checks.push({ name: '.claude/skills/ links', status: 'ok', msg: `${linkedCount} categories linked` });
-        } else if (linkedCount > 0) {
-          checks.push({ name: '.claude/skills/ links', status: 'warn', msg: `${linkedCount}/${skillDirs.length} linked, rest copied` });
-          hasWarnings = true;
-        } else {
-          checks.push({ name: '.claude/skills/ links', status: 'warn', msg: 'all categories copied (no auto-update)' });
-          hasWarnings = true;
-        }
-      }
-
-      // Check .claude/rules/
-      const rulesPath = join(claudePath, 'rules');
-      if (await pathExists(rulesPath)) {
-        const ruleFiles = await fs.readdir(rulesPath);
-        const mdRules = ruleFiles.filter(f => f.endsWith('.md'));
-        checks.push({ name: '.claude/rules/', status: 'ok', msg: `${mdRules.length} rules` });
-      } else {
-        checks.push({ name: '.claude/rules/', status: 'warn', msg: 'missing — run morph-spec update' });
-        hasWarnings = true;
-      }
-
-      // Check .claude/agents/
-      const agentsPathClaude = join(claudePath, 'agents');
-      if (await pathExists(agentsPathClaude)) {
-        const agentFiles = await fs.readdir(agentsPathClaude);
-        const morphAgents = agentFiles.filter(f => f.startsWith('morph-') && f.endsWith('.md'));
-        checks.push({ name: '.claude/agents/', status: 'ok', msg: `${morphAgents.length} agents` });
-
-        // Check for missing agents based on stack tags
-        try {
-          const config = await readJson(configPath);
-          const projectTags = getProjectTags(config);
-          if (projectTags.length > 0) {
-            const frameworkDir = join(import.meta.dirname, '..', '..', '..', 'framework');
-            const { missing } = checkMissingAgents(targetPath, frameworkDir, projectTags);
-            if (missing.length > 0) {
-              const names = missing.map(m => m.name).join(', ');
-              checks.push({
-                name: 'agents completeness',
-                status: 'warn',
-                msg: `${missing.length} agent(s) missing for [${projectTags.join(', ')}]: ${names} — run morph-spec setup-infra`
-              });
-              hasWarnings = true;
-            } else {
-              checks.push({ name: 'agents completeness', status: 'ok', msg: `all agents for [${projectTags.join(', ')}]` });
-            }
-          }
-        } catch { /* config not readable — skip completeness check */ }
-      } else {
-        checks.push({ name: '.claude/agents/', status: 'warn', msg: 'missing — run morph-spec update' });
-        hasWarnings = true;
-      }
-      // ── Hook health: verify hook scripts exist ───────────────────────────────
-      const settingsLocalPath = join(claudePath, 'settings.local.json');
-      if (await pathExists(settingsLocalPath)) {
-        try {
-          const settings = JSON.parse(await fs.readFile(settingsLocalPath, 'utf8'));
-          const hookCommands = [];
-          for (const eventHooks of Object.values(settings.hooks || {})) {
-            for (const group of (Array.isArray(eventHooks) ? eventHooks : [])) {
-              for (const h of (group.hooks || [])) {
-                if (h.type === 'command' && h.command) hookCommands.push(h.command);
-              }
-            }
-          }
-          const hookPathRe = /\$CLAUDE_PROJECT_DIR\/([^\s"]+\.js)/;
-          const missingHooks = [];
-          for (const cmd of hookCommands) {
-            const m = cmd.match(hookPathRe);
-            if (m && !(await pathExists(join(targetPath, m[1])))) {
-              missingHooks.push(m[1].split('/').pop());
-            }
-          }
-          if (missingHooks.length === 0) {
-            checks.push({ name: 'hook scripts', status: 'ok', msg: `${hookCommands.length} hooks configured` });
-          } else {
-            checks.push({ name: 'hook scripts', status: 'warn', msg: `missing: ${missingHooks.join(', ')} — run morph-spec update` });
-            hasWarnings = true;
-          }
-        } catch {
-          checks.push({ name: 'hook scripts', status: 'warn', msg: 'could not parse settings.local.json' });
-          hasWarnings = true;
-        }
-      } else {
-        checks.push({ name: 'hook scripts', status: 'warn', msg: 'settings.local.json missing — run morph-spec init' });
-        hasWarnings = true;
-      }
-
-      // ── Skills cliVersion: warn if installed skills reference older CLI ──────
-      try {
-        const cliVersion = getInstalledCLIVersion();
-        if (cliVersion) {
-          const skillDirsForVersion = await fs.readdir(skillsPath);
-          const staleSkills = [];
-          for (const skillDir of skillDirsForVersion) {
-            const skillMdPath = join(skillsPath, skillDir, 'SKILL.md');
-            if (!(await pathExists(skillMdPath))) continue;
-            const content = await fs.readFile(skillMdPath, 'utf8');
-            const m = content.match(/^cliVersion:\s*"?([^"\n]+)"?/m);
-            if (m && m[1].trim() !== cliVersion) {
-              staleSkills.push(skillDir);
-            }
-          }
-          if (staleSkills.length === 0) {
-            checks.push({ name: 'skill cliVersion', status: 'ok' });
-          } else {
-            checks.push({ name: 'skill cliVersion', status: 'warn', msg: `${staleSkills.length} skill(s) behind CLI v${cliVersion} — run morph-spec update` });
-            hasWarnings = true;
-          }
-        }
-      } catch { /* non-fatal */ }
-
-      // ── Claude Code Plugins ──────────────────────────────────────────────────
-      console.log(chalk.cyan('\n  Claude Code Plugins (required for /morph-init)'));
-      const pluginsFile = join(homedir(), '.claude', 'plugins', 'installed_plugins.json');
-      let pluginData = { plugins: {} };
-      try {
-        pluginData = JSON.parse(await fs.readFile(pluginsFile, 'utf8'));
-      } catch { /* file may not exist */ }
-      const pluginStatus = checkInstalledPlugins(pluginData.plugins || {});
-      check('superpowers plugin', pluginStatus.superpowers, false,
-        'Run: morph-spec install-plugin superpowers');
-      check('context7 plugin', pluginStatus.context7, false,
-        'Run: morph-spec install-plugin context7');
-    } else {
-      checks.push({ name: '.claude/', status: 'warn', msg: 'incomplete structure' });
-    }
-  } else {
-    checks.push({ name: '.claude/', status: 'missing' });
-    hasErrors = true;
-  }
-
-  // Check state.json
-  const statePath = join(targetPath, '.morph', 'state.json');
-  if (await pathExists(statePath)) {
-    try {
-      const stateContent = await readJson(statePath);
-      if (stateContent.version && stateContent.features) {
-        const featureCount = Object.keys(stateContent.features).length;
-        checks.push({ name: 'state.json', status: 'ok', msg: `${featureCount} feature(s)` });
-      } else {
-        checks.push({ name: 'state.json', status: 'warn', msg: 'invalid schema' });
-        hasWarnings = true;
-      }
-    } catch {
-      checks.push({ name: 'state.json', status: 'error', msg: 'invalid JSON' });
-      hasErrors = true;
-    }
-  } else {
-    checks.push({ name: 'state.json', status: 'warn', msg: 'not initialized (run: morph-spec init)' });
-    hasWarnings = true;
-  }
-
-  // Check key templates exist (in framework package, not project copy)
-  const frameworkTemplatesRoot = join(import.meta.dirname, '..', '..', '..', 'framework', 'templates');
-  const keyTemplates = [
-    { name: 'proposal.md', path: join(frameworkTemplatesRoot, 'docs', 'proposal.md') },
-    { name: 'spec.md', path: join(frameworkTemplatesRoot, 'docs', 'spec.md') },
-    { name: 'tasks.md', path: join(frameworkTemplatesRoot, 'feature', 'tasks.md') },
-    { name: 'decisions.md', path: join(frameworkTemplatesRoot, 'feature', 'decisions.md') }
-  ];
-  const missingTemplates = [];
-  for (const template of keyTemplates) {
-    if (!(await pathExists(template.path))) {
-      missingTemplates.push(template.name);
-    }
-  }
-
-  if (missingTemplates.length === 0) {
-    checks.push({ name: 'key templates', status: 'ok' });
-  } else if (missingTemplates.length < keyTemplates.length) {
-    checks.push({ name: 'key templates', status: 'warn', msg: `missing: ${missingTemplates.join(', ')}` });
-    hasWarnings = true;
-  } else {
-    checks.push({ name: 'key templates', status: 'missing' });
-    hasErrors = true;
-  }
-
-  // Check Node.js version
-  const nodeVersion = process.version;
-  const majorVersion = parseInt(nodeVersion.slice(1).split('.')[0], 10);
-  if (majorVersion >= 18) {
-    checks.push({ name: `Node.js ${nodeVersion}`, status: 'ok' });
-  } else {
-    checks.push({ name: `Node.js ${nodeVersion}`, status: 'warn', msg: 'v18+ recommended' });
-    hasWarnings = true;
-  }
-
-  // Display results
-  for (const check of checks) {
-    if (check.status === 'ok') {
-      console.log(chalk.green(`  ✓ ${check.name}`));
-    } else if (check.status === 'warn') {
-      console.log(chalk.yellow(`  ⚠ ${check.name}`) + chalk.gray(` (${check.msg})`));
-    } else if (check.status === 'missing') {
-      console.log(chalk.red(`  ✗ ${check.name}`) + chalk.gray(' (missing)'));
-    } else if (check.status === 'error') {
-      console.log(chalk.red(`  ✗ ${check.name}`) + chalk.gray(` (${check.msg})`));
-    }
-  }
-
-  logger.blank();
-
-  if (hasErrors) {
-    logger.error('Some checks failed. Run "morph-spec setup-infra" to fix.');
-    process.exit(1);
-  } else if (hasWarnings) {
-    logger.warn('Some checks need attention.');
-    logger.blank();
-
-    if (!inPath) {
-      const usingNvm = isUsingNvmWindows();
-      const prefix = getNpmGlobalPrefix();
-
-      if (usingNvm && prefix) {
-        logger.info('PATH Issue Detected (nvm-windows):');
-        logger.dim(`  Add to PATH: ${prefix}`);
-        logger.blank();
-        logger.dim('  PowerShell (as Administrator):');
-        console.log(chalk.gray(`    [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";${prefix}", "User")`));
-        logger.blank();
-        logger.dim('  Then open a new terminal.');
-        logger.blank();
-      } else if (!inPath) {
-        logger.info('morph-spec not in PATH:');
-        logger.dim('  Open a new terminal — the installer adds npm global to $PROFILE automatically.');
-        logger.dim('  If it persists, add manually: npm config get prefix → add to PATH');
-        logger.blank();
-      }
-    }
-
-    if (cliCheck.isOutdated || projectCheck.isOutdated) {
-      logger.info('To update:');
-      logger.dim('  1. Update the CLI: npm install -g @polymorphism-tech/morph-spec@latest');
-      logger.dim('  2. Update the project: morph-spec update');
-      logger.blank();
-    }
-  } else {
-    logger.success('All checks passed!');
-  }
-}
+import { join, relative } from 'path';
+import { execSync } from 'child_process';
+import { platform, homedir } from 'os';
+import fs from 'fs-extra';
+import chalk from 'chalk';
+import { logger } from '../../utils/logger.js';
+import { pathExists, readJson } from '../../utils/file-copier.js';
+import { checkClaudeMdImport } from '../../utils/claude-md-injector.js';
+import {
+  checkCLIOutdated,
+  checkProjectOutdated,
+  getInstalledCLIVersion
+} from '../../utils/version-checker.js';
+import { resetMorphSettings } from '../../utils/claude-settings-manager.js';
+import { checkMissingAgents } from '../../utils/agents-installer.js';
+import { getProjectTags } from '../../lib/stack-filter.js';
+
+const isWindows = platform() === 'win32';
+/**
+ * Check which required Claude Code plugins are installed.
+ * @param {Object} pluginsData - The `plugins` object from installed_plugins.json
+ * @returns {{ superpowers: boolean, context7: boolean }}
+ */
+export function checkInstalledPlugins(pluginsData) {
+  const REQUIRED = ['superpowers', 'context7'];
+  return Object.fromEntries(
+    REQUIRED.map(name => [name, `${name}@claude-plugins-official` in (pluginsData || {})])
+  );
+}
+
+
+/**
+ * Check if morph-spec command is in PATH
+ */
+function isMorphSpecInPath() {
+  try {
+    const command = isWindows ? 'where morph-spec' : 'which morph-spec';
+    execSync(command, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detect if nvm-windows is installed
+ */
+function isUsingNvmWindows() {
+  if (!isWindows) return false;
+
+  try {
+    const path = process.env.PATH || '';
+    return path.includes('nvm4w') || path.includes('\\nvm\\');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get npm global prefix
+ */
+function getNpmGlobalPrefix() {
+  try {
+    const prefix = execSync('npm config get prefix', { encoding: 'utf8' }).trim();
+    return prefix;
+  } catch {
+    return null;
+  }
+}
+
+// lib files (v5 — minimal surface)
+const REQUIRED_LIB_FILES = [
+  'src/lib/stack-filter.js'
+];
+
+// command files (v5 CLI surface — installer-only)
+const REQUIRED_COMMAND_FILES = [
+  'src/commands/project/init.js',
+  'src/commands/project/update.js',
+  'src/commands/project/doctor.js',
+  'src/commands/project/status.js',
+  'src/commands/project/worktree.js',
+  'src/commands/state/approve.js',
+  'src/commands/validation/validate-feature.js',
+  'src/commands/scaffold/scaffold.js',
+  'src/commands/mcp/mcp-setup.js',
+  'src/commands/context/context-refresh.js',
+];
+
+// framework standards (stack-relevant only)
+const FRAMEWORK_STANDARDS = [
+  'framework/standards/architecture/vertical-slice/vertical-slice.md',
+  'framework/standards/data/nosql/cosmos-db.md',
+  'framework/standards/data/nosql/cache/redis.md',
+  'framework/standards/data/vector-search/rag-chunking.md',
+  'framework/standards/integration/mcp/mcp-tools.md',
+  'framework/standards/workflows/thread-management.md',
+  'framework/standards/workflows/parallel-execution.md'
+];
+
+// required personas expected in agents.json (v5 — at least the universal evaluator)
+const REQUIRED_AGENTS = [
+  'evaluator'
+];
+
+/**
+ * Run full health checks
+ */
+async function doctorFullCommand(frameworkRoot) {
+  console.log(chalk.bold('\n🔬 MORPH-SPEC Full Health Check\n'));
+  console.log('─'.repeat(60));
+
+  const checks = [];
+  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;
+    }
+  };
+
+  // ── 1. Core Libraries ───────────────────────────────────────────────────
+  console.log(chalk.cyan(`\n  src/lib/ — Core Libraries (${REQUIRED_LIB_FILES.length} files)`));
+  const missingLibs = [];
+  for (const f of REQUIRED_LIB_FILES) {
+    if (!(await pathExists(join(frameworkRoot, f)))) missingLibs.push(f.split('/').pop());
+  }
+  check(`Core Libraries (${REQUIRED_LIB_FILES.length - missingLibs.length}/${REQUIRED_LIB_FILES.length})`,
+    missingLibs.length === 0, false,
+    missingLibs.length > 0 ? `missing: ${missingLibs.join(', ')}` : '');
+
+  // ── 2. Command Files ─────────────────────────────────────────────────────
+  console.log(chalk.cyan(`\n  src/commands/ — Command Files (${REQUIRED_COMMAND_FILES.length} files)`));
+  const missingCmds = [];
+  for (const f of REQUIRED_COMMAND_FILES) {
+    if (!(await pathExists(join(frameworkRoot, f)))) missingCmds.push(f.split('/').pop());
+  }
+  check(`Command Files (${REQUIRED_COMMAND_FILES.length - missingCmds.length}/${REQUIRED_COMMAND_FILES.length})`,
+    missingCmds.length === 0, false,
+    missingCmds.length > 0 ? `missing: ${missingCmds.join(', ')}` : '');
+
+  // ── 3. Framework Standards ───────────────────────────────────────────────
+  console.log(chalk.cyan(`\n  framework/standards/ — Framework Standards (${FRAMEWORK_STANDARDS.length} files)`));
+  const missingStds = [];
+  for (const f of FRAMEWORK_STANDARDS) {
+    if (!(await pathExists(join(frameworkRoot, f)))) missingStds.push(f.replace('framework/standards/', ''));
+  }
+  check(`Framework Standards (${FRAMEWORK_STANDARDS.length - missingStds.length}/${FRAMEWORK_STANDARDS.length})`,
+    missingStds.length === 0, false,
+    missingStds.length > 0 ? `missing: ${missingStds.join(', ')}` : '');
+
+  // ── 5. Required Agents in agents.json ───────────────────────────────────
+  console.log(chalk.cyan(`\n  .morph/framework/agents.json — Required Agents (${REQUIRED_AGENTS.length})`));
+  const agentsPath = join(frameworkRoot, '.morph/framework/agents.json');
+  if (await pathExists(agentsPath)) {
+    try {
+      const agentsConfig = JSON.parse(await fs.readFile(agentsPath, 'utf8'));
+      const agents = agentsConfig.agents || {};
+      const missingAgents = REQUIRED_AGENTS.filter(id => !agents[id]);
+      check(`Required Agents (${REQUIRED_AGENTS.length - missingAgents.length}/${REQUIRED_AGENTS.length})`,
+        missingAgents.length === 0, false,
+        missingAgents.length > 0 ? `missing: ${missingAgents.join(', ')}` : '');
+    } catch {
+      check('agents.json parse', false, false, 'invalid JSON');
+    }
+  } else {
+    check('agents.json', false, false, 'file not found');
+  }
+
+  // ── 6. agents.json version freshness ──────────────────────────────────
+  const canonicalAgentsPath = join(frameworkRoot, 'framework/agents.json');
+  if (await pathExists(agentsPath) && await pathExists(canonicalAgentsPath)) {
+    try {
+      const installed = JSON.parse(await fs.readFile(agentsPath, 'utf8'));
+      const canonical = JSON.parse(await fs.readFile(canonicalAgentsPath, 'utf8'));
+      const installedVer = installed.version || 'unknown';
+      const canonicalVer = canonical.version || 'unknown';
+      const isFresh = installedVer === canonicalVer;
+      check(`agents.json version (${installedVer})`, isFresh, true,
+        isFresh ? '' : `stale — canonical is v${canonicalVer}, run 'morph-spec update' to sync`);
+    } catch { /* ignore parse errors — already caught above */ }
+  }
+
+  // ── 7. state.json schema version ────────────────────────────────────────
+  console.log(chalk.cyan('\n  .morph/state.json — Schema Version'));
+  const statePath = join(frameworkRoot, '.morph/state.json');
+  if (await pathExists(statePath)) {
+    try {
+      const state = JSON.parse(await fs.readFile(statePath, 'utf8'));
+      const isCurrent = state.version === '5.0.0';
+      check(`state.json schema (${state.version})`, isCurrent, true,
+        isCurrent ? '' : `expected 5.0.0, found ${state.version} — run any CLI command to auto-migrate`);
+    } catch {
+      check('state.json parse', false, false, 'invalid JSON');
+    }
+  } else {
+    check('state.json', false, true, 'not found (run: morph-spec init)');
+  }
+
+  // ── Display ──────────────────────────────────────────────────────────────
+  console.log('\n' + '─'.repeat(60));
+  console.log(chalk.bold('\nResults:\n'));
+  for (const c of checks) {
+    if (c.status === 'ok') {
+      console.log(chalk.green(`  ✓ ${c.name}`));
+    } else if (c.status === 'warn') {
+      console.log(chalk.yellow(`  ⚠ ${c.name}`) + chalk.gray(c.msg ? ` (${c.msg})` : ''));
+    } else {
+      console.log(chalk.red(`  ✗ ${c.name}`) + chalk.gray(c.msg ? ` — ${c.msg}` : ''));
+    }
+  }
+
+  console.log('');
+  const passed = checks.filter(c => c.status === 'ok').length;
+  const total = checks.length;
+
+  if (hasErrors) {
+    console.log(chalk.red(`\n❌ ${passed}/${total} checks passed — see errors above\n`));
+    process.exit(1);
+  } else if (hasWarnings) {
+    console.log(chalk.yellow(`\n⚠️  ${passed}/${total} checks passed (warnings only)\n`));
+  } else {
+    console.log(chalk.green(`\n✅ ${passed}/${total} — All checks passed!\n`));
+  }
+}
+
+/**
+ * MCP health check: reads .mcp.json, settings.json, and 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 allMcpServers = {};
+  const sourcesFound = [];
+
+  // Primary: .mcp.json (Claude Code reads MCPs from here)
+  const mcpJsonPath = join(targetPath, '.mcp.json');
+  if (await pathExists(mcpJsonPath)) {
+    try {
+      const mcpJson = JSON.parse(await fs.readFile(mcpJsonPath, 'utf8'));
+      const mcps = mcpJson.mcpServers || {};
+      const count = Object.keys(mcps).length;
+      if (count > 0) {
+        Object.assign(allMcpServers, mcps);
+        sourcesFound.push(`.mcp.json (${count})`);
+      }
+    } catch { /* invalid JSON — ignore */ }
+  }
+
+  // Legacy: settings files (for backward compat)
+  const settingsPaths = [
+    join(targetPath, '.claude', 'settings.json'),
+    join(targetPath, '.claude', 'settings.local.json'),
+  ];
+
+  for (const sp of settingsPaths) {
+    if (await pathExists(sp)) {
+      try {
+        const settings = JSON.parse(await fs.readFile(sp, 'utf8'));
+        const mcps = settings.mcpServers || {};
+        let addedCount = 0;
+        for (const [name, config] of Object.entries(mcps)) {
+          if (!allMcpServers[name]) {
+            allMcpServers[name] = config;
+            addedCount++;
+          }
+        }
+        if (addedCount > 0) {
+          sourcesFound.push(`${relative(targetPath, sp)} (${addedCount})`);
+        }
+      } catch { /* invalid JSON — ignore */ }
+    }
+  }
+
+  if (Object.keys(allMcpServers).length === 0) {
+    logger.warn('No MCP servers configured');
+    logger.blank();
+    logger.dim('Configure MCPs in: .mcp.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';
+    let isRemote = false;
+
+    // ── 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 (!isRemote && 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, isRemote });
+  }
+
+  // ── Display ────────────────────────────────────────────────────────────────
+  for (const c of checks) {
+    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);
+    } 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) {
+    const targetPath = process.cwd();
+    logger.header('MORPH-SPEC Settings Reset');
+
+    const result = await resetMorphSettings(targetPath);
+
+    if (!result.removed) {
+      logger.warn(`Nothing to reset: ${result.reason}`);
+      return;
+    }
+
+    logger.success('Morph-managed settings removed.');
+    if (result.permissionsRemoved?.length > 0) {
+      logger.dim(`  Permissions removed: ${result.permissionsRemoved.join(', ')}`);
+    }
+    if (result.envRemoved?.length > 0) {
+      logger.dim(`  Env vars removed: ${result.envRemoved.join(', ')}`);
+    }
+    if (result.backupPath) {
+      logger.dim(`  Backup saved: ${result.backupPath}`);
+    }
+    return;
+  }
+
+  // full health check mode
+  if (options.full) {
+    const frameworkRoot = process.cwd();
+    return doctorFullCommand(frameworkRoot);
+  }
+
+  // MCP health check mode
+  if (options.mcp) {
+    return doctorMcpCommand(process.cwd());
+  }
+
+  const targetPath = process.cwd();
+
+  logger.header('MORPH-SPEC Health Check');
+
+  const checks = [];
+  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);
+
+  // CLI Version
+  if (cliCheck.latest) {
+    if (cliCheck.isOutdated) {
+      checks.push({
+        name: `CLI version (${cliCheck.current})`,
+        status: 'warn',
+        msg: `outdated, ${cliCheck.latest} available`
+      });
+      hasWarnings = true;
+    } else {
+      checks.push({
+        name: `CLI version (${cliCheck.current})`,
+        status: 'ok',
+        msg: 'latest'
+      });
+    }
+  } else {
+    checks.push({
+      name: `CLI version (${cliCheck.current})`,
+      status: 'ok'
+    });
+  }
+
+  // Project MORPH version
+  if (projectCheck.current) {
+    if (projectCheck.isOutdated) {
+      checks.push({
+        name: `Project MORPH version (${projectCheck.current})`,
+        status: 'warn',
+        msg: `outdated, ${projectCheck.cliVersion} available`
+      });
+      hasWarnings = true;
+    } else {
+      checks.push({
+        name: `Project MORPH version (${projectCheck.current})`,
+        status: 'ok'
+      });
+    }
+  } else {
+    checks.push({
+      name: 'Project MORPH version',
+      status: 'warn',
+      msg: 'not found (legacy installation)'
+    });
+    hasWarnings = true;
+  }
+
+  // Check if morph-spec is in PATH
+  const inPath = isMorphSpecInPath();
+  if (inPath) {
+    checks.push({
+      name: 'morph-spec in PATH',
+      status: 'ok'
+    });
+  } else {
+    checks.push({
+      name: 'morph-spec in PATH',
+      status: 'warn',
+      msg: 'command not found'
+    });
+    hasWarnings = true;
+  }
+
+  // Check CLAUDE.md has morph-spec @import
+  const claudeMd = join(targetPath, 'CLAUDE.md');
+  const claudeMdStatus = await checkClaudeMdImport(claudeMd);
+  if (claudeMdStatus === 'ok') {
+    checks.push({ name: 'CLAUDE.md', status: 'ok' });
+  } else if (claudeMdStatus === 'missing-import') {
+    checks.push({ name: 'CLAUDE.md', status: 'warn', msg: 'missing @.claude/CLAUDE.md import — run morph-spec update' });
+    hasWarnings = true;
+  } else {
+    checks.push({ name: 'CLAUDE.md', status: 'missing' });
+    hasErrors = true;
+  }
+
+  // Check .morph folder
+  const morphPath = join(targetPath, '.morph');
+  if (await pathExists(morphPath)) {
+    checks.push({ name: '.morph/', status: 'ok' });
+  } else {
+    checks.push({ name: '.morph/', status: 'missing' });
+    hasErrors = true;
+  }
+
+  // Check config.json
+  const configPath = join(morphPath, 'config', 'config.json');
+  if (await pathExists(configPath)) {
+    try {
+      const config = await readJson(configPath);
+      if (config.project?.name) {
+        checks.push({ name: 'config.json', status: 'ok' });
+      } else {
+        checks.push({ name: 'config.json', status: 'warn', msg: 'project.name not set' });
+      }
+    } catch {
+      checks.push({ name: 'config.json', status: 'error', msg: 'invalid JSON' });
+      hasErrors = true;
+    }
+  } else {
+    checks.push({ name: 'config.json', status: 'missing' });
+    hasErrors = true;
+  }
+
+  // Check agents.json
+  const agentsPath = join(morphPath, 'framework', 'agents.json');
+  if (await pathExists(agentsPath)) {
+    try {
+      const agentsData = JSON.parse(await fs.readFile(agentsPath, 'utf8'));
+      const agentEntries = Object.entries(agentsData.agents || {})
+        .filter(([k]) => !k.startsWith('_comment'));
+      const actualCount = agentEntries.length;
+      const declaredCount = agentsData.total_agents;
+
+      // Check 1: total_agents matches actual count
+      if (actualCount !== declaredCount) {
+        checks.push({
+          name: 'agents.json count',
+          status: 'warn',
+          msg: `total_agents declares ${declaredCount} but found ${actualCount} agents`
+        });
+        hasWarnings = true;
+      } else {
+        checks.push({ name: 'agents.json count', status: 'ok', msg: `${actualCount} agents` });
+      }
+
+      // Check 2: required v5 personas present
+      const requiredPersonas = REQUIRED_AGENTS;
+      const missingPersonas = requiredPersonas.filter(id => !agentsData.agents[id]);
+      if (missingPersonas.length > 0) {
+        checks.push({
+          name: 'agents.json required personas',
+          status: 'error',
+          msg: `Missing required personas: ${missingPersonas.join(', ')}`
+        });
+        hasErrors = true;
+      } else {
+        checks.push({ name: 'agents.json required personas', status: 'ok' });
+      }
+
+      // Check 3: v5 schema validation (flat personas, no tiers)
+      const version = agentsData.version || 'unknown';
+      const isV5 = version.startsWith('5.');
+      const v4Fields = [];
+      const missingV5Fields = [];
+
+      for (const [id, data] of agentEntries) {
+        if (data.tier !== undefined) v4Fields.push(`${id}.tier`);
+        if (data.active_phases !== undefined) v4Fields.push(`${id}.active_phases`);
+        if (data.reports_to !== undefined) v4Fields.push(`${id}.reports_to`);
+        if (data.teammate !== undefined) v4Fields.push(`${id}.teammate`);
+        if (!data.title) missingV5Fields.push(`${id}.title`);
+        if (!Array.isArray(data.domains)) missingV5Fields.push(`${id}.domains`);
+        if (typeof data.persona !== 'string' || !data.persona) missingV5Fields.push(`${id}.persona`);
+      }
+
+      if (isV5) {
+        checks.push({ name: `agents.json schema (v${version})`, status: 'ok' });
+      } else {
+        checks.push({
+          name: `agents.json schema (v${version})`,
+          status: 'warn',
+          msg: 'expected v5.x — run agents migration'
+        });
+        hasWarnings = true;
+      }
+
+      if (v4Fields.length > 0) {
+        const sample = v4Fields.slice(0, 3).join(', ');
+        checks.push({
+          name: 'agents.json deprecated v4 fields',
+          status: 'warn',
+          msg: `${v4Fields.length} v4 field(s) found: ${sample}${v4Fields.length > 3 ? '...' : ''}`
+        });
+        hasWarnings = true;
+      }
+
+      if (missingV5Fields.length > 0 && isV5) {
+        const sample = missingV5Fields.slice(0, 3).join(', ');
+        checks.push({
+          name: 'agents.json v5 required fields',
+          status: 'warn',
+          msg: `${missingV5Fields.length} missing: ${sample}${missingV5Fields.length > 3 ? '...' : ''}`
+        });
+        hasWarnings = true;
+      }
+    } catch {
+      checks.push({ name: 'agents.json', status: 'error', msg: 'invalid JSON' });
+      hasErrors = true;
+    }
+  } else {
+    checks.push({ name: 'agents.json', status: 'missing' });
+    hasErrors = true;
+  }
+
+  // Check standards (either in project .morph/framework/standards/ or in framework package)
+  const standardsPath = join(morphPath, 'framework', 'standards');
+  const frameworkStdsRoot = join(import.meta.dirname, '..', '..', '..', 'framework', 'standards');
+  if (await pathExists(standardsPath)) {
+    // Check for VSA standard (core to the framework)
+    const vsaStd = await pathExists(join(standardsPath, 'architecture', 'vertical-slice', 'vertical-slice.md')) ||
+                   await pathExists(join(standardsPath, 'vertical-slice.md'));
+    if (vsaStd) {
+      checks.push({ name: 'standards/', status: 'ok' });
+    } else {
+      checks.push({ name: 'standards/', status: 'warn', msg: 'VSA standard missing — run morph-spec init' });
+      hasWarnings = true;
+    }
+  } else if (await pathExists(frameworkStdsRoot)) {
+    // Framework package has standards (dev/global install mode)
+    checks.push({ name: 'standards/', status: 'warn', msg: 'not installed in project (run morph-spec init)' });
+    hasWarnings = true;
+  } else {
+    checks.push({ name: 'standards/', status: 'missing' });
+    hasErrors = true;
+  }
+
+  // Check templates
+  const templatesPath = join(morphPath, 'framework', 'templates');
+  if (await pathExists(templatesPath)) {
+    checks.push({ name: 'templates/', status: 'ok' });
+  } else {
+    checks.push({ name: 'templates/', status: 'missing' });
+    hasErrors = true;
+  }
+
+  // Check .claude folder
+  const claudePath = join(targetPath, '.claude');
+  if (await pathExists(claudePath)) {
+    const commandsPath = join(claudePath, 'commands');
+    const skillsPath = join(claudePath, 'skills');
+
+    const hasCommands = await pathExists(commandsPath);
+    const hasSkills = await pathExists(skillsPath);
+
+    if (hasCommands && hasSkills) {
+      checks.push({ name: '.claude/', status: 'ok' });
+
+      // Check skills link status
+      const skillEntries = await fs.readdir(skillsPath, { withFileTypes: true });
+      const skillDirs = skillEntries.filter(e => e.isDirectory() || e.isSymbolicLink());
+      let linkedCount = 0;
+
+      for (const dir of skillDirs) {
+        try {
+          const stat = await fs.lstat(join(skillsPath, dir.name));
+          if (stat.isSymbolicLink()) linkedCount++;
+        } catch { /* ignore */ }
+      }
+
+      if (skillDirs.length > 0) {
+        if (linkedCount === skillDirs.length) {
+          checks.push({ name: '.claude/skills/ links', status: 'ok', msg: `${linkedCount} categories linked` });
+        } else if (linkedCount > 0) {
+          checks.push({ name: '.claude/skills/ links', status: 'warn', msg: `${linkedCount}/${skillDirs.length} linked, rest copied` });
+          hasWarnings = true;
+        } else {
+          checks.push({ name: '.claude/skills/ links', status: 'warn', msg: 'all categories copied (no auto-update)' });
+          hasWarnings = true;
+        }
+      }
+
+      // Check .claude/rules/
+      const rulesPath = join(claudePath, 'rules');
+      if (await pathExists(rulesPath)) {
+        const ruleFiles = await fs.readdir(rulesPath);
+        const mdRules = ruleFiles.filter(f => f.endsWith('.md'));
+        checks.push({ name: '.claude/rules/', status: 'ok', msg: `${mdRules.length} rules` });
+      } else {
+        checks.push({ name: '.claude/rules/', status: 'warn', msg: 'missing — run morph-spec update' });
+        hasWarnings = true;
+      }
+
+      // Check .claude/agents/
+      const agentsPathClaude = join(claudePath, 'agents');
+      if (await pathExists(agentsPathClaude)) {
+        const agentFiles = await fs.readdir(agentsPathClaude);
+        const morphAgents = agentFiles.filter(f => f.startsWith('morph-') && f.endsWith('.md'));
+        checks.push({ name: '.claude/agents/', status: 'ok', msg: `${morphAgents.length} agents` });
+
+        // Check for missing agents based on stack tags
+        try {
+          const config = await readJson(configPath);
+          const projectTags = getProjectTags(config);
+          if (projectTags.length > 0) {
+            const frameworkDir = join(import.meta.dirname, '..', '..', '..', 'framework');
+            const { missing } = checkMissingAgents(targetPath, frameworkDir, projectTags);
+            if (missing.length > 0) {
+              const names = missing.map(m => m.name).join(', ');
+              checks.push({
+                name: 'agents completeness',
+                status: 'warn',
+                msg: `${missing.length} agent(s) missing for [${projectTags.join(', ')}]: ${names} — run morph-spec setup-infra`
+              });
+              hasWarnings = true;
+            } else {
+              checks.push({ name: 'agents completeness', status: 'ok', msg: `all agents for [${projectTags.join(', ')}]` });
+            }
+          }
+        } catch { /* config not readable — skip completeness check */ }
+      } else {
+        checks.push({ name: '.claude/agents/', status: 'warn', msg: 'missing — run morph-spec update' });
+        hasWarnings = true;
+      }
+      // ── Hook health: verify hook scripts exist ───────────────────────────────
+      const settingsLocalPath = join(claudePath, 'settings.local.json');
+      if (await pathExists(settingsLocalPath)) {
+        try {
+          const settings = JSON.parse(await fs.readFile(settingsLocalPath, 'utf8'));
+          const hookCommands = [];
+          for (const eventHooks of Object.values(settings.hooks || {})) {
+            for (const group of (Array.isArray(eventHooks) ? eventHooks : [])) {
+              for (const h of (group.hooks || [])) {
+                if (h.type === 'command' && h.command) hookCommands.push(h.command);
+              }
+            }
+          }
+          const hookPathRe = /\$CLAUDE_PROJECT_DIR\/([^\s"]+\.js)/;
+          const missingHooks = [];
+          for (const cmd of hookCommands) {
+            const m = cmd.match(hookPathRe);
+            if (m && !(await pathExists(join(targetPath, m[1])))) {
+              missingHooks.push(m[1].split('/').pop());
+            }
+          }
+          if (missingHooks.length === 0) {
+            checks.push({ name: 'hook scripts', status: 'ok', msg: `${hookCommands.length} hooks configured` });
+          } else {
+            checks.push({ name: 'hook scripts', status: 'warn', msg: `missing: ${missingHooks.join(', ')} — run morph-spec update` });
+            hasWarnings = true;
+          }
+        } catch {
+          checks.push({ name: 'hook scripts', status: 'warn', msg: 'could not parse settings.local.json' });
+          hasWarnings = true;
+        }
+      } else {
+        checks.push({ name: 'hook scripts', status: 'warn', msg: 'settings.local.json missing — run morph-spec init' });
+        hasWarnings = true;
+      }
+
+      // ── Skills cliVersion: warn if installed skills reference older CLI ──────
+      try {
+        const cliVersion = getInstalledCLIVersion();
+        if (cliVersion) {
+          const skillDirsForVersion = await fs.readdir(skillsPath);
+          const staleSkills = [];
+          for (const skillDir of skillDirsForVersion) {
+            const skillMdPath = join(skillsPath, skillDir, 'SKILL.md');
+            if (!(await pathExists(skillMdPath))) continue;
+            const content = await fs.readFile(skillMdPath, 'utf8');
+            const m = content.match(/^cliVersion:\s*"?([^"\n]+)"?/m);
+            if (m && m[1].trim() !== cliVersion) {
+              staleSkills.push(skillDir);
+            }
+          }
+          if (staleSkills.length === 0) {
+            checks.push({ name: 'skill cliVersion', status: 'ok' });
+          } else {
+            checks.push({ name: 'skill cliVersion', status: 'warn', msg: `${staleSkills.length} skill(s) behind CLI v${cliVersion} — run morph-spec update` });
+            hasWarnings = true;
+          }
+        }
+      } catch { /* non-fatal */ }
+
+      // ── Claude Code Plugins ──────────────────────────────────────────────────
+      console.log(chalk.cyan('\n  Claude Code Plugins (required for /morph-init)'));
+      const pluginsFile = join(homedir(), '.claude', 'plugins', 'installed_plugins.json');
+      let pluginData = { plugins: {} };
+      try {
+        pluginData = JSON.parse(await fs.readFile(pluginsFile, 'utf8'));
+      } catch { /* file may not exist */ }
+      const pluginStatus = checkInstalledPlugins(pluginData.plugins || {});
+      check('superpowers plugin', pluginStatus.superpowers, false,
+        'Run: morph-spec install-plugin superpowers');
+      check('context7 plugin', pluginStatus.context7, false,
+        'Run: morph-spec install-plugin context7');
+    } else {
+      checks.push({ name: '.claude/', status: 'warn', msg: 'incomplete structure' });
+    }
+  } else {
+    checks.push({ name: '.claude/', status: 'missing' });
+    hasErrors = true;
+  }
+
+  // Check state.json
+  const statePath = join(targetPath, '.morph', 'state.json');
+  if (await pathExists(statePath)) {
+    try {
+      const stateContent = await readJson(statePath);
+      if (stateContent.version && stateContent.features) {
+        const featureCount = Object.keys(stateContent.features).length;
+        checks.push({ name: 'state.json', status: 'ok', msg: `${featureCount} feature(s)` });
+      } else {
+        checks.push({ name: 'state.json', status: 'warn', msg: 'invalid schema' });
+        hasWarnings = true;
+      }
+    } catch {
+      checks.push({ name: 'state.json', status: 'error', msg: 'invalid JSON' });
+      hasErrors = true;
+    }
+  } else {
+    checks.push({ name: 'state.json', status: 'warn', msg: 'not initialized (run: morph-spec init)' });
+    hasWarnings = true;
+  }
+
+  // Check key templates exist (in framework package, not project copy)
+  const frameworkTemplatesRoot = join(import.meta.dirname, '..', '..', '..', 'framework', 'templates');
+  const keyTemplates = [
+    { name: 'proposal.md', path: join(frameworkTemplatesRoot, 'docs', 'proposal.md') },
+    { name: 'spec.md', path: join(frameworkTemplatesRoot, 'docs', 'spec.md') },
+    { name: 'tasks.template.json', path: join(frameworkTemplatesRoot, 'tasks.template.json') },
+    { name: 'decisions.md', path: join(frameworkTemplatesRoot, 'feature', 'decisions.md') }
+  ];
+  const missingTemplates = [];
+  for (const template of keyTemplates) {
+    if (!(await pathExists(template.path))) {
+      missingTemplates.push(template.name);
+    }
+  }
+
+  if (missingTemplates.length === 0) {
+    checks.push({ name: 'key templates', status: 'ok' });
+  } else if (missingTemplates.length < keyTemplates.length) {
+    checks.push({ name: 'key templates', status: 'warn', msg: `missing: ${missingTemplates.join(', ')}` });
+    hasWarnings = true;
+  } else {
+    checks.push({ name: 'key templates', status: 'missing' });
+    hasErrors = true;
+  }
+
+  // Check Node.js version
+  const nodeVersion = process.version;
+  const majorVersion = parseInt(nodeVersion.slice(1).split('.')[0], 10);
+  if (majorVersion >= 18) {
+    checks.push({ name: `Node.js ${nodeVersion}`, status: 'ok' });
+  } else {
+    checks.push({ name: `Node.js ${nodeVersion}`, status: 'warn', msg: 'v18+ recommended' });
+    hasWarnings = true;
+  }
+
+  // Display results
+  for (const check of checks) {
+    if (check.status === 'ok') {
+      console.log(chalk.green(`  ✓ ${check.name}`));
+    } else if (check.status === 'warn') {
+      console.log(chalk.yellow(`  ⚠ ${check.name}`) + chalk.gray(` (${check.msg})`));
+    } else if (check.status === 'missing') {
+      console.log(chalk.red(`  ✗ ${check.name}`) + chalk.gray(' (missing)'));
+    } else if (check.status === 'error') {
+      console.log(chalk.red(`  ✗ ${check.name}`) + chalk.gray(` (${check.msg})`));
+    }
+  }
+
+  logger.blank();
+
+  if (hasErrors) {
+    logger.error('Some checks failed. Run "morph-spec setup-infra" to fix.');
+    process.exit(1);
+  } else if (hasWarnings) {
+    logger.warn('Some checks need attention.');
+    logger.blank();
+
+    if (!inPath) {
+      const usingNvm = isUsingNvmWindows();
+      const prefix = getNpmGlobalPrefix();
+
+      if (usingNvm && prefix) {
+        logger.info('PATH Issue Detected (nvm-windows):');
+        logger.dim(`  Add to PATH: ${prefix}`);
+        logger.blank();
+        logger.dim('  PowerShell (as Administrator):');
+        console.log(chalk.gray(`    [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";${prefix}", "User")`));
+        logger.blank();
+        logger.dim('  Then open a new terminal.');
+        logger.blank();
+      } else if (!inPath) {
+        logger.info('morph-spec not in PATH:');
+        logger.dim('  Open a new terminal — the installer adds npm global to $PROFILE automatically.');
+        logger.dim('  If it persists, add manually: npm config get prefix → add to PATH');
+        logger.blank();
+      }
+    }
+
+    if (cliCheck.isOutdated || projectCheck.isOutdated) {
+      logger.info('To update:');
+      logger.dim('  1. Update the CLI: npm install -g @polymorphism-tech/morph-spec@latest');
+      logger.dim('  2. Update the project: morph-spec update');
+      logger.blank();
+    }
+  } else {
+    logger.success('All checks passed!');
+  }
+}