@polymorphism-tech/morph-spec 4.22.0 → 5.0.1

package/bin/morph-spec.js

@@ -1,491 +1,224 @@
-#!/usr/bin/env node
-
-import { program } from 'commander';
-import chalk from 'chalk';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-import { readFileSync } from 'fs';
-
-// Project commands
-import { initCommand } from '../src/commands/project/init.js';
-import { setupInfraCommand } from '../src/commands/project/setup-infra-cmd.js';
-import { installPluginCommand } from '../src/commands/project/install-plugin-cmd.js';
-import { updateCommand } from '../src/commands/project/update.js';
-import { doctorCommand } from '../src/commands/project/doctor.js';
-
-import { statusCommand } from '../src/commands/project/status.js';
-import { worktreeSetupCommand } from '../src/commands/project/worktree.js';
-import { checkpointSaveCommand } from '../src/commands/project/checkpoint.js';
-
-// State commands
-import { stateCommand } from '../src/commands/state/state.js';
-import { advancePhaseCommand } from '../src/commands/state/advance-phase.js';
-import { approveCommand, approvalStatusCommand, unapproveCommand } from '../src/commands/state/approve.js';
-import { phaseRunCommand } from '../src/commands/state/phase-runner.js';
-import { phaseResetCommand } from '../src/commands/phase/phase-reset.js';
-
-// Agent commands
-import { dispatchAgentsCommand } from '../src/commands/agents/dispatch-agents.js';
-import { auditDispatchCommand } from '../src/commands/agents/audit-dispatch.js';
-import { detectAgentsCommand } from '../src/commands/agents/detect-agents.js';
-import { agentMetricsCommand } from '../src/commands/agents/agent-metrics.js';
-import {
-  agentListCommand,
-  agentShowCommand,
-  agentAddCommand,
-  agentEditCommand,
-  agentRemoveCommand,
-} from '../src/commands/agents/manage-agents.js';
-
-// Task commands
-import { taskDoneCommand, taskStartCommand, taskBulkDoneCommand, taskAnnotateCommand } from '../src/commands/tasks/task.js';
-
-// Scope escalation commands
-import { scopeEscalateCommand } from '../src/commands/scope/escalate.js';
-import { taskExpandCommand } from '../src/commands/task/expand.js';
-
-// Validation commands
-import { validateCommand } from './validate.js';
-import { validateFeatureCommand } from '../src/commands/validation/validate-feature.js';
-
-// Template commands
-import { templateRenderCommand } from '../src/commands/templates/template-render.js';
-
-// Scaffold commands
-import { scaffoldDotnetCommand, scaffoldNextjsCommand } from '../src/commands/scaffold/scaffold.js';
-// MCP commands
-import { mcpSetupCommand } from '../src/commands/mcp/mcp-setup.js';
-
-// Trust commands
-import { trustStatusCommand, trustSetCommand } from '../src/commands/trust/trust.js';
-
-// Project metrics
-import { projectMetricsCommand } from '../src/commands/agents/project-metrics.js';
-
-// Context commands
-import { contextRefreshCommand } from '../src/commands/context/context-refresh.js';
-
-// Dashboard commands
-import { dashboardCommand } from '../src/commands/dashboard/dashboard.js';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
-
-const banner = chalk.cyan(`
-  ███╗   ███╗ ██████╗ ██████╗ ██████╗ ██╗  ██╗
-  ████╗ ████║██╔═══██╗██╔══██╗██╔══██╗██║  ██║
-  ██╔████╔██║██║   ██║██████╔╝██████╔╝███████║
-  ██║╚██╔╝██║██║   ██║██╔══██╗██╔═══╝ ██╔══██║
-  ██║ ╚═╝ ██║╚██████╔╝██║  ██║██║     ██║  ██║
-  ╚═╝     ╚═╝ ╚═════╝ ╚═╝  ╚═╝╚═╝     ╚═╝  ╚═╝
-
-  Methodical Orchestration for Reliable Production-ready SPEC-driven development
-  by Polymorphism Tech | v${pkg.version}
-`);
-
-program
-  .name('morph-spec')
-  .description('MORPH-SPEC Framework CLI')
-  .version(pkg.version)
-  .addHelpText('beforeAll', banner);
-
-program
-  .command('init')
-  .description('Initialize MORPH-SPEC in current directory')
-  .option('-f, --force', 'Overwrite existing MORPH installation')
-  .option('-p, --path <path>', 'Target path (default: current directory)')
-  .option('--skip-mcp', 'Skip MCP server auto-setup')
-  .action(initCommand);
-
-program
-  .command('setup-infra')
-  .description('Install MORPH-SPEC infrastructure (headless, no prompts). Called by /morph-init skill.')
-  .option('-p, --path <path>', 'Target path (default: current directory)')
-  .option('--reinstall', 'Re-install only stack-aware assets (rules, skills, agents)')
-  .action(setupInfraCommand);
-
-program
-  .command('install-plugin <name>')
-  .description('Install a Claude Code plugin (superpowers, context7). Called by /morph-init skill.')
-  .action(installPluginCommand);
-
-program
-  .command('update')
-  .description('Update MORPH templates and standards to latest version')
-  .option('--templates', 'Update only templates')
-  .option('--standards', 'Update only standards')
-  .action(updateCommand);
-
-program
-  .command('doctor')
-  .description('Check MORPH installation health')
-  .option('--full', 'Run full health check (lib files, commands, HOPs, standards, agents, state)')
-  .option('--mcp', 'Check MCP server configuration (binary + env vars)')
-  .option('--reset', 'Remove morph-managed entries from .claude/settings.local.json')
-  .action(doctorCommand);
-
-program
-  .command('status <feature>')
-  .description('Show comprehensive feature status dashboard')
-  .option('--json', 'Output as JSON')
-  .option('-v, --verbose', 'Show detailed output')
-  .action(statusCommand);
-
-// Worktree commands
-const worktreeCommand = program
-  .command('worktree')
-  .description('Manage git worktrees for feature isolation');
-
-worktreeCommand
-  .command('setup <feature>')
-  .description('Create a worktree at .worktrees/{feature}/ on branch morph/{feature}')
-  .option('--fresh', 'Create a new dated branch even if one already exists')
-  .action((feature, options) => worktreeSetupCommand(feature, options));
-
-// State management commands
-program
-  .command('state <action> [args...]')
-  .description('Manage state.json (init | get | set | list | add-agent | remove-agent | mark-output)')
-  .option('--force', 'Force overwrite (init) or bypass phase protection gates (set phase)')
-  .option('--project <name>', 'Project name (init command)')
-  .option('--type <type>', 'Project type (init command)')
-  .option('--json', 'Output as JSON (get command)')
-  .action((action, args, options) => stateCommand(action, args, options));
-
-// Task management commands (MORPH-SPEC 3.0)
-const taskCommand = program
-  .command('task')
-  .description('Manage feature tasks (done | start | expand | annotate)');
-
-taskCommand
-  .command('done <feature> <task-ids...>')
-  .description('Mark tasks as completed (runs validation first)')
-  .option('--note <text>', 'Add a deviation note explaining why task was done differently than planned')
-  .option('--skip-validation', 'Skip code validation (budget-limited, requires --reason)')
-  .option('--reason <text>', 'Reason for skipping validation (required with --skip-validation)')
-  .option('--skip-build', 'Skip test build guard')
-  .option('--dry-run', 'Show validation results without marking tasks as complete')
-  .action((feature, taskIds, options) => taskDoneCommand(feature, taskIds, options));
-
-taskCommand
-  .command('start <feature> <task-id>')
-  .description('Start a task (mark as in_progress)')
-  .action((feature, taskId, options) => taskStartCommand(feature, taskId, options));
-
-taskCommand
-  .command('expand <feature> <task-id>')
-  .description('Expand a task into sub-tasks (low-impact scope escalation)')
-  .option('--into <subtasks...>', 'Sub-task definitions ("T017a: Title")')
-  .action((feature, taskId, options) => taskExpandCommand(feature, taskId, options));
-
-taskCommand
-  .command('bulk-done <feature> [range]')
-  .description('Complete multiple tasks with a single validation pass')
-  .option('--all', 'Complete all non-completed tasks')
-  .option('--from <id>', 'Start of task range (e.g. T007)')
-  .option('--to <id>', 'End of task range (e.g. T014)')
-  .option('--note <text>', 'Add a deviation note explaining why tasks were done differently than planned')
-  .option('--skip-validation', 'Skip code validation (budget-limited, requires --reason)')
-  .option('--reason <text>', 'Reason for skipping validation (required with --skip-validation)')
-  .option('--skip-build', 'Skip test build guard')
-  .option('--dry-run', 'Show validation results without marking tasks as complete')
-  .action((feature, range, options) => taskBulkDoneCommand(feature, range, options));
-
-taskCommand
-  .command('annotate <feature> <task-id> <text>')
-  .description('Add a note to a task (deviation, context, or blocker resolution)')
-  .option('--type <type>', 'Note type: deviation | context | blocker-resolved', 'deviation')
-  .option('--mark-done', 'Also mark the task as completed')
-  .action((feature, taskId, text, options) => taskAnnotateCommand(feature, taskId, text, options));
-
-// Generation commands
-const generateCommand = program
-  .command('generate')
-  .description('Generate code from templates');
-
-generateCommand
-  .command('recap <feature>')
-  .description('Auto-generate recap.md from project data (state, validation, contracts)')
-  .option('--quiet', 'Suppress output')
-  .action(async (feature, options) => {
-    const { generateRecap } = await import('../src/lib/generators/recap-generator.js');
-    await generateRecap('.', feature, options);
-  });
-
-// Validation commands (Sprint 4: Continuous Validation)
-program
-  .command('validate [validator]')
-  .description('Run project validations (all | packages | architecture | contrast)')
-  .option('-v, --verbose', 'Show detailed output')
-  .option('--auto-fix, --fix', 'Auto-fix issues where possible')
-  .option('--no-fail', 'Don\'t exit with error code')
-  .option('--wcag-aaa', 'Use WCAG AAA standard (stricter)')
-  .action((validator, options) => {
-    const args = validator ? [validator] : ['all'];
-    if (options.verbose) args.push('--verbose');
-    if (options.autoFix) args.push('--auto-fix');
-    if (options.noFail) args.push('--no-fail');
-    if (options.wcagAaa) args.push('--wcag-aaa');
-    validateCommand(args);
-  });
-
-// Phase management commands
-const phaseCommand = program
-  .command('phase')
-  .description('Phase management (advance | validate)');
-
-phaseCommand
-  .command('advance <feature>')
-  .description('Validate current phase and advance to next')
-  .option('--skip-optional', 'Skip optional phases (uiux, sync)')
-  .option('--skip-approval', 'Skip approval gate checks')
-  .option('--force', 'Force phase transition even if state machine rejects it')
-  .action((feature, options) => advancePhaseCommand(feature, options));
-
-phaseCommand
-  .command('run <feature>')
-  .description('Automated phase chain runner — advances phases until blocker or max reached')
-  .option('--dry-run', 'Show decision tree without executing')
-  .option('--max-phases <n>', 'Max phases to auto-advance (default: 6)', parseInt)
-  .option('--skip-approval', 'Skip approval gate checks')
-  .action((feature, options) => phaseRunCommand(feature, options));
-
-phaseCommand
-  .command('reset <feature> <phase>')
-  .description('Reset feature phase (recovery tool — bypasses approval gates)')
-  .action((feature, phase) => phaseResetCommand(feature, phase));
-
-// Feature validation command (content-aware)
-program
-  .command('validate-feature <feature>')
-  .alias('vf')
-  .description('Content-aware validation of feature outputs (sections, schema, contracts)')
-  .option('--phase <phase>', 'Validate outputs for a specific phase')
-  .option('--json', 'Output as JSON')
-  .option('-v, --verbose', 'Show detailed output')
-  .action(validateFeatureCommand);
-
-// Checkpoint save/restore commands
-program
-  .command('checkpoint-save <feature>')
-  .description('Save full context at current phase boundary')
-  .option('--label <label>', 'Custom label for checkpoint')
-  .action(checkpointSaveCommand);
-
-// Approval workflow commands
-program
-  .command('approve <feature> <gate>')
-  .description('Approve a phase gate (design, tasks, uiux, proposal)')
-  .option('--approver <name>', 'Name of approver (default: current user)')
-  .option('--notes <notes>', 'Approval notes')
-  .action((feature, gate, options) => approveCommand(feature, gate, options));
-
-program
-  .command('approval-status <feature>')
-  .description('Show approval status for all gates')
-  .option('--json', 'Output as JSON')
-  .action((feature, options) => approvalStatusCommand(feature, options));
-
-program
-  .command('unapprove <feature> <gate>')
-  .description('Revoke a phase gate approval (proposal, design, tasks, uiux)')
-  .option('--revoker <name>', 'Name of person revoking (default: current user)')
-  .option('--reason <reason>', 'Reason for revocation')
-  .action((feature, gate, options) => unapproveCommand(feature, gate, options));
-
-// Template management commands
-const templateCommand = program
-  .command('template')
-  .description('Template management (render)');
-
-templateCommand
-  .command('render <template-id> <output-path> <variables-json>')
-  .description('Render a template with variables')
-  .option('--dry-run', 'Preview without writing file')
-  .option('--project-path <path>', 'Project path (default: current directory)')
-  .option('-v, --verbose', 'Show detailed output')
-  .action(templateRenderCommand);
-
-// Scaffold commands (code generation from templates)
-const scaffoldCmd = program
-  .command('scaffold')
-  .description('Generate feature files from templates');
-
-scaffoldCmd
-  .command('dotnet <feature> <slice-name>')
-  .description('Generate VSA feature slice (.NET)')
-  .option('--dry-run', 'Preview files without writing')
-  .option('--namespace <ns>', 'Root namespace (auto-detected from .csproj)')
-  .option('--output-dir <path>', 'Output directory (default: cwd)')
-  .option('-v, --verbose', 'Show detailed output')
-  .action(scaffoldDotnetCommand);
-
-scaffoldCmd
-  .command('nextjs <feature>')
-  .description('Generate feature page + components (Next.js)')
-  .option('--dry-run', 'Preview files without writing')
-  .option('--output-dir <path>', 'Output directory (default: cwd)')
-  .option('-v, --verbose', 'Show detailed output')
-  .action(scaffoldNextjsCommand);
-
-// Trust commands
-const trustCommand = program
-  .command('trust')
-  .description('Trust level management for zero-touch execution');
-
-trustCommand
-  .command('status [feature]')
-  .description('Show trust level and auto-approval status')
-  .action(trustStatusCommand);
-
-trustCommand
-  .command('set <feature> <level> [reason]')
-  .description('Manually set trust level (manual|high|auto)')
-  .action(trustSetCommand);
-
-// ─────────────────────────────────────────────────────────────────────────────
-// MCP Setup
-// ─────────────────────────────────────────────────────────────────────────────
-const mcpCommand = program
-  .command('mcp')
-  .description('MCP server setup and configuration');
-
-mcpCommand
-  .command('setup [name]')
-  .description('Install and configure MCP servers')
-  .option('--list', 'Show MCP install status')
-  .option('--auto', 'Auto-install credential-free MCPs without prompts')
-  .action((name, options) => mcpSetupCommand(name, options));
-
-// Agent orchestration commands
-program
-  .command('dispatch-agents <feature> <phase>')
-  .description('Build dispatch config for parallel agent orchestration (design | tasks | implement)')
-  .option('--table', 'Human-readable table output instead of JSON')
-  .option('--mode <mode>', 'Dispatch mode: validate (includes Tier-4 validators as read-only)')
-  .option('--preflight', 'Exit with code 1 if any agent files are missing')
-  .option('-v, --verbose', 'Show stack trace on error')
-  .action((feature, phase, options) => dispatchAgentsCommand(feature, phase, options));
-
-program
-  .command('audit-dispatch <feature>')
-  .description('Display dispatch audit log for a feature')
-  .option('--json', 'Output as JSON instead of table')
-  .action((feature, options) => auditDispatchCommand(feature, options));
-
-program
-  .command('agent-metrics [feature]')
-  .description('Display agent performance metrics for a feature')
-  .option('--json', 'Output as JSON instead of table')
-  .option('--all', 'Aggregate metrics across all features')
-  .action((feature, options) => agentMetricsCommand(feature, options));
-
-program
-  .command('detect-agents <feature>')
-  .description('Detect relevant agents for a feature based on proposal keywords')
-  .option('--proposal <path>', 'Path to proposal file (default: .morph/features/{feature}/0-proposal/proposal.md)')
-  .option('--json', 'Output as JSON (default)')
-  .option('--table', 'Human-readable table output')
-  .option('--exclude <ids>', 'Comma-separated agent IDs to exclude')
-  .option('--refresh', 'Refresh detection using all phase outputs (additive, mutates state)')
-  .action((feature, options) => detectAgentsCommand(feature, options));
-
-// Scope escalation commands
-const scopeCommand = program
-  .command('scope')
-  .description('Scope management (escalate)');
-
-scopeCommand
-  .command('escalate <feature>')
-  .description('Escalate scope when implementation reveals unexpected complexity')
-  .option('--task <id>', 'Trigger task ID (required)')
-  .option('--reason <text>', 'Reason for escalation (required)')
-  .option('--target <phase>', 'Override target phase (tasks | design)')
-  .option('--dry-run', 'Show recommendation without executing')
-  .action((feature, options) => scopeEscalateCommand(feature, options));
-
-// Agent management commands (CRUD)
-const agentCommand = program
-  .command('agent')
-  .description('Manage agents in agents.json (list, show, add, edit, remove)');
-
-agentCommand
-  .command('list')
-  .description('List all agents with optional filters')
-  .option('--group <name>', 'Filter by group')
-  .option('--tier <n>', 'Filter by tier (1-4)')
-  .option('--json', 'Output as JSON')
-  .action((options) => agentListCommand(options));
-
-agentCommand
-  .command('show <id>')
-  .description('Show detailed info for an agent')
-  .option('--json', 'Output as JSON')
-  .option('--full', 'Show full spawn_prompt (no truncation)')
-  .action((id, options) => agentShowCommand(id, options));
-
-agentCommand
-  .command('add <id>')
-  .description('Add a new agent via interactive wizard')
-  .option('--non-interactive', 'Use flags instead of prompts')
-  .option('--tier <n>', 'Tier (1-4)')
-  .option('--title <title>', 'Agent title')
-  .option('--group <group>', 'Agent group')
-  .option('--active-phases <phases>', 'Comma-separated phases or *')
-  .option('--reports-to <id>', 'Parent agent ID or "user"')
-  .option('--domains <domains>', 'Comma-separated domains')
-  .option('--keywords <keywords>', 'Comma-separated keywords')
-  .option('--spawn-prompt <prompt>', 'Teammate spawn prompt')
-  .option('--role <role>', 'Teammate role')
-  .option('--icon <emoji>', 'Teammate icon')
-  .action((id, options) => agentAddCommand(id, options));
-
-agentCommand
-  .command('edit <id>')
-  .description('Edit agent fields via flags')
-  .option('--tier <n>', 'New tier')
-  .option('--title <title>', 'New title')
-  .option('--group <group>', 'New group')
-  .option('--active-phases <phases>', 'New phases (comma-sep)')
-  .option('--reports-to <id>', 'New reports_to')
-  .option('--keywords <keywords>', 'New keywords (comma-sep)')
-  .option('--domains <domains>', 'New domains (comma-sep)')
-  .option('--spawn-prompt <prompt>', 'New spawn prompt')
-  .action((id, options) => agentEditCommand(id, options));
-
-agentCommand
-  .command('remove <id>')
-  .description('Remove an agent from agents.json')
-  .option('--force', 'Skip confirmation prompt')
-  .action((id, options) => agentRemoveCommand(id, options));
-
-// Project-level metrics
-program
-  .command('project-metrics')
-  .description('Aggregate project-level metrics from state.json')
-  .option('--json', 'Output as JSON')
-  .option('--save', 'Save metrics to .morph/metrics.json')
-  .action((options) => projectMetricsCommand(options));
-
-// Context management commands
-const contextCommand = program
-  .command('context')
-  .description('Project context management (refresh)');
-
-contextCommand
-  .command('refresh')
-  .description('Scan project architecture and generate .morph/context/README.md')
-  .option('-p, --path <path>', 'Target path (default: current directory)')
-  .option('-v, --verbose', 'Show detailed scan output')
-  .option('--json', 'Output scan result as JSON')
-  .action((options) => contextRefreshCommand(options));
-
-// Dashboard / Inspector
-program
-  .command('dashboard')
-  .description('Open the morph-spec inspector dashboard')
-  .option('-p, --port <port>', 'Port number', '3200')
-  .option('--no-open', 'Don\'t auto-open browser')
-  .action(dashboardCommand);
-
-program.parse();
+#!/usr/bin/env node
+
+/**
+ * morph-spec CLI v5
+ *
+ * In v5 the CLI is the *installer* — Claude executes everything else
+ * autonomously based on MORPH.md and the core skills. Commands here are
+ * limited to actions that humans take or operations Claude needs help with
+ * (scaffolding, validation, context refresh).
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { readFileSync } from 'fs';
+
+// === Project / install ===
+import { initCommand } from '../src/commands/project/init.js';
+import { setupInfraCommand } from '../src/commands/project/setup-infra-cmd.js';
+import { installPluginCommand } from '../src/commands/project/install-plugin-cmd.js';
+import { updateCommand } from '../src/commands/project/update.js';
+import { doctorCommand } from '../src/commands/project/doctor.js';
+import { statusCommand } from '../src/commands/project/status.js';
+import { worktreeSetupCommand } from '../src/commands/project/worktree.js';
+
+// === Approval gates (human-only) ===
+import { approveCommand, approvalStatusCommand, unapproveCommand } from '../src/commands/state/approve.js';
+
+// === Validation ===
+import { validateCommand } from './validate.js';
+import { validateFeatureCommand } from '../src/commands/validation/validate-feature.js';
+
+// === Scaffolding ===
+import { scaffoldDotnetCommand, scaffoldNextjsCommand } from '../src/commands/scaffold/scaffold.js';
+
+// === MCP setup ===
+import { mcpSetupCommand } from '../src/commands/mcp/mcp-setup.js';
+
+// === Context refresh ===
+import { contextRefreshCommand } from '../src/commands/context/context-refresh.js';
+
+// === Dashboard ===
+import { dashboardCommand } from '../src/commands/dashboard/dashboard.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+const banner = chalk.cyan(`
+  ███╗   ███╗ ██████╗ ██████╗ ██████╗ ██╗  ██╗
+  ████╗ ████║██╔═══██╗██╔══██╗██╔══██╗██║  ██║
+  ██╔████╔██║██║   ██║██████╔╝██████╔╝███████║
+  ██║╚██╔╝██║██║   ██║██╔══██╗██╔═══╝ ██╔══██║
+  ██║ ╚═╝ ██║╚██████╔╝██║  ██║██║     ██║  ██║
+  ╚═╝     ╚═╝ ╚═════╝ ╚═╝  ╚═╝╚═╝     ╚═╝  ╚═╝
+
+  Spec-driven development harness for Claude Code
+  by Polymorphism Tech | v${pkg.version}
+`);
+
+program
+  .name('morph-spec')
+  .description('MORPH-SPEC Framework CLI')
+  .version(pkg.version)
+  .addHelpText('beforeAll', banner);
+
+// ─── Install ──────────────────────────────────────────────────────────────
+program
+  .command('init')
+  .description('Initialize MORPH-SPEC in current directory')
+  .option('-f, --force', 'Overwrite existing MORPH installation')
+  .option('-p, --path <path>', 'Target path (default: current directory)')
+  .option('--skip-mcp', 'Skip MCP server auto-setup')
+  .action(initCommand);
+
+program
+  .command('setup-infra')
+  .description('Install MORPH-SPEC infrastructure (headless, no prompts)')
+  .option('-p, --path <path>', 'Target path (default: current directory)')
+  .option('--reinstall', 'Re-install only stack-aware assets (rules, skills, agents)')
+  .action(setupInfraCommand);
+
+program
+  .command('install-plugin <name>')
+  .description('Install a Claude Code plugin (superpowers, context7)')
+  .action(installPluginCommand);
+
+program
+  .command('update')
+  .description('Update MORPH templates and standards to latest version')
+  .option('--templates', 'Update only templates')
+  .option('--standards', 'Update only standards')
+  .action(updateCommand);
+
+program
+  .command('doctor')
+  .description('Check MORPH installation health')
+  .option('--full', 'Run full health check')
+  .option('--mcp', 'Check MCP server configuration')
+  .option('--reset', 'Remove morph-managed entries from .claude/settings.local.json')
+  .action(doctorCommand);
+
+// ─── Status / inspection ──────────────────────────────────────────────────
+program
+  .command('status <feature>')
+  .description('Show feature status (phase, gate state, task counts)')
+  .option('--json', 'Output as JSON')
+  .option('-v, --verbose', 'Show detailed output')
+  .action(statusCommand);
+
+// ─── Approval gates (dev-only) ────────────────────────────────────────────
+program
+  .command('approve <feature> <gate>')
+  .description('Approve a phase gate (proposal, plan, review)')
+  .option('--approver <name>', 'Name of approver (default: current user)')
+  .option('--notes <notes>', 'Approval notes')
+  .action((feature, gate, options) => approveCommand(feature, gate, options));
+
+program
+  .command('approval-status <feature>')
+  .description('Show approval status for all gates')
+  .option('--json', 'Output as JSON')
+  .action((feature, options) => approvalStatusCommand(feature, options));
+
+program
+  .command('unapprove <feature> <gate>')
+  .description('Revoke a phase gate approval (recovery only)')
+  .option('--revoker <name>', 'Name of person revoking')
+  .option('--reason <reason>', 'Reason for revocation')
+  .action((feature, gate, options) => unapproveCommand(feature, gate, options));
+
+// ─── Validation ───────────────────────────────────────────────────────────
+program
+  .command('validate [validator]')
+  .description('Run project validations (all | packages | architecture | contrast)')
+  .option('-v, --verbose', 'Show detailed output')
+  .option('--auto-fix, --fix', 'Auto-fix issues where possible')
+  .option('--no-fail', 'Don\'t exit with error code')
+  .option('--wcag-aaa', 'Use WCAG AAA standard (stricter)')
+  .action((validator, options) => {
+    const args = validator ? [validator] : ['all'];
+    if (options.verbose) args.push('--verbose');
+    if (options.autoFix) args.push('--auto-fix');
+    if (options.noFail) args.push('--no-fail');
+    if (options.wcagAaa) args.push('--wcag-aaa');
+    validateCommand(args);
+  });
+
+program
+  .command('validate-feature <feature>')
+  .alias('vf')
+  .description('Content-aware validation of feature outputs (sections, schema, contracts)')
+  .option('--phase <phase>', 'Validate outputs for a specific phase')
+  .option('--json', 'Output as JSON')
+  .option('-v, --verbose', 'Show detailed output')
+  .action(validateFeatureCommand);
+
+// ─── Scaffolding ──────────────────────────────────────────────────────────
+const scaffoldCmd = program
+  .command('scaffold')
+  .description('Generate feature files from templates');
+
+scaffoldCmd
+  .command('dotnet <feature> <slice-name>')
+  .description('Generate VSA feature slice (.NET)')
+  .option('--dry-run', 'Preview files without writing')
+  .option('--namespace <ns>', 'Root namespace (auto-detected from .csproj)')
+  .option('--output-dir <path>', 'Output directory (default: cwd)')
+  .option('-v, --verbose', 'Show detailed output')
+  .action(scaffoldDotnetCommand);
+
+scaffoldCmd
+  .command('nextjs <feature>')
+  .description('Generate feature page + components (Next.js)')
+  .option('--dry-run', 'Preview files without writing')
+  .option('--output-dir <path>', 'Output directory (default: cwd)')
+  .option('-v, --verbose', 'Show detailed output')
+  .action(scaffoldNextjsCommand);
+
+// ─── MCP setup ────────────────────────────────────────────────────────────
+const mcpCommand = program
+  .command('mcp')
+  .description('MCP server setup and configuration');
+
+mcpCommand
+  .command('setup [name]')
+  .description('Install and configure MCP servers')
+  .option('--list', 'Show MCP install status')
+  .option('--auto', 'Auto-install credential-free MCPs without prompts')
+  .action((name, options) => mcpSetupCommand(name, options));
+
+// ─── Context refresh ──────────────────────────────────────────────────────
+const contextCommand = program
+  .command('context')
+  .description('Project context management (refresh)');
+
+contextCommand
+  .command('refresh')
+  .description('Scan project architecture and generate .morph/context/README.md')
+  .option('-p, --path <path>', 'Target path (default: current directory)')
+  .option('-v, --verbose', 'Show detailed scan output')
+  .option('--json', 'Output scan result as JSON')
+  .action((options) => contextRefreshCommand(options));
+
+// ─── Worktree (optional, isolation) ───────────────────────────────────────
+const worktreeCommand = program
+  .command('worktree')
+  .description('Manage git worktrees for feature isolation');
+
+worktreeCommand
+  .command('setup <feature>')
+  .description('Create a worktree at .worktrees/{feature}/ on branch morph/{feature}')
+  .option('--fresh', 'Create a new dated branch even if one already exists')
+  .action((feature, options) => worktreeSetupCommand(feature, options));
+
+// ─── Dashboard ────────────────────────────────────────────────────────────
+program
+  .command('dashboard')
+  .description('Open the morph-spec inspector dashboard')
+  .option('-p, --port <port>', 'Port number', '3200')
+  .option('--no-open', 'Don\'t auto-open browser')
+  .action(dashboardCommand);
+
+program.parse();