dev-harness-cli 1.0.0

package/cli/commands/status.mjs

@@ -0,0 +1,168 @@
+/**
+ * status — Show current phase + gate state + detected stack.
+ *
+ * Reads harness-config.json via state.mjs for live project state,
+ * plus runs stack detection and gate checks for current status.
+ *
+ * Usage: harness-dev status [--json] [--target <dir>]
+ */
+import { resolve, basename } from 'node:path';
+import { detectStack } from '../lib/detect-stack.mjs';
+import { loadConfig } from '../lib/state.mjs';
+import { readLessons } from '../lib/progress.mjs';
+import { loadFeatureList, getNextFeature } from '../lib/ralph-inner.mjs';
+import { runChecks, areGatesEnabled } from '../lib/gates.mjs';
+
+export default async function statusCommand(args) {
+  const rawTarget = args.flags?.target;
+  const targetDir = (typeof rawTarget === 'string') ? resolve(rawTarget) : process.cwd();
+  const json = !!(args.json || args.flags?.json);
+
+  // Stack detection
+  const stack = detectStack(targetDir);
+
+  // Config state (graceful if missing)
+  const { config, ok: configOk, schemaErrors = [] } = loadConfig(targetDir);
+  const phase = configOk ? config.currentPhase : null;
+  const mode = configOk ? config.mode : 'copilot';
+
+  // Current feature from feature_list.json
+  let currentFeature = null;
+  if (configOk && phase) {
+    try {
+      const fl = loadFeatureList(targetDir);
+      const next = getNextFeature(fl.features);
+      if (next) {
+        currentFeature = { id: next.id, name: next.name };
+      }
+    } catch {
+      // feature_list.json missing or invalid
+    }
+  }
+
+  // Gate status — run checks for current phase
+  let gateStatus = 'disabled';
+  let checksPassing = 0;
+  let checksTotal = 0;
+  if (phase && areGatesEnabled(targetDir)) {
+    const gateResult = runChecks(targetDir, phase);
+    checksTotal = gateResult.checks.length;
+    checksPassing = gateResult.checks.filter(c => c.pass).length;
+    gateStatus = gateResult.overall ? 'pass' : 'fail';
+  }
+
+  // Lessons — last 3
+  const allLessons = readLessons(targetDir);
+  const recentLessons = allLessons.slice(-3);
+
+  if (json) {
+    process.stdout.write(JSON.stringify({
+      command: 'status',
+      status: 'ok',
+      message: configOk
+        ? `Phase: ${phase || 'not started'}, Stack: ${stack.label}`
+        : 'No harness-config.json found — run harness-dev init',
+      project: basename(targetDir),
+      stack: stack.name,
+      stackLabel: stack.label,
+      mode,
+      currentPhase: phase,
+      currentFeature: currentFeature?.name || null,
+      gateStatus,
+      checksPassing,
+      checksTotal,
+      paused: configOk ? config.paused : false,
+      features: configOk ? config.features : { remaining: 0, passing: 0, total: 0 },
+      git: configOk ? config.git : { clean: true },
+      maxRetries: configOk ? config.maxRetries : 3,
+      recentLessons: recentLessons.map(l => ({ date: l.date, author: l.author, text: l.text })),
+      schemaErrors,
+      nextAction: determineNextAction(targetDir, configOk, config, phase, gateStatus),
+    }) + '\n');
+    return;
+  }
+
+  // ── Human-readable output ─────────────────────────────────────────────
+  let out = '';
+  out += '═══ dev-harness Status ═══\n';
+  out += line('Project:', basename(targetDir)) + '\n';
+  out += line('Stack:', `${stack.label}${stack.name !== 'generic' ? '' : ' (not detected)'}`) + '\n';
+  out += line('Mode:', modeLabel(mode)) + '\n';
+  out += '\n';
+
+  if (configOk && phase) {
+    out += line('Current Phase:', phase.toUpperCase()) + '\n';
+    if (currentFeature) {
+      out += line('Current Feature:', `${currentFeature.name} (${currentFeature.id})`) + '\n';
+    }
+    out += line('Gate Status:', gateStatusLabel(gateStatus, checksPassing, checksTotal)) + '\n';
+    if (config.git?.branch) {
+      out += line('Branch:', config.git.branch) + '\n';
+    }
+    out += '\n';
+  } else if (configOk) {
+    out += '  Phase: not started.\n';
+    out += '\n';
+  } else {
+    out += '  No harness-config.json found.\n';
+    out += '\n';
+  }
+
+  // Lessons
+  if (recentLessons.length > 0) {
+    out += `Last ${recentLessons.length} lesson(s):\n`;
+    for (const l of recentLessons) {
+      out += `  ${l.date} | ${l.text}\n`;
+    }
+    out += '\n';
+  }
+
+  // Schema violations (if any) — surface so users know config is malformed
+  if (configOk && schemaErrors.length > 0) {
+    out += `Schema warnings (${schemaErrors.length}):\n`;
+    for (const e of schemaErrors) {
+      out += `  ⚠ ${e}\n`;
+    }
+    out += '\n';
+  }
+
+  // Next action
+  out += '  ' + determineNextAction(targetDir, configOk, config, phase, gateStatus) + '\n';
+
+  process.stdout.write(out);
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function line(k, v) {
+  return `${k.padEnd(18)}${v}`;
+}
+
+function modeLabel(mode) {
+  return mode === 'autopilot' ? 'Autopilot' : 'Copilot';
+}
+
+function gateStatusLabel(status, passing, total) {
+  if (status === 'disabled') {return 'disabled';}
+  if (total === 0) {return status;}
+  return `${status === 'pass' ? 'passing' : 'failing'} — ${passing}/${total} checks passing`;
+}
+
+function determineNextAction(targetDir, configOk, config, phase, gateStatus) {
+  if (!configOk) {
+    return 'Run: harness-dev init';
+  }
+  if (!phase) {
+    return 'Run: harness-dev phase define to start';
+  }
+  if (gateStatus === 'fail') {
+    return 'Run: harness-dev validate to re-check';
+  }
+  // Determine next phase
+  const order = ['define', 'plan', 'build', 'verify', 'review', 'ship'];
+  const idx = order.indexOf(phase);
+  if (idx >= 0 && idx < order.length - 1) {
+    return `Run: harness-dev phase ${order[idx + 1]}`;
+  }
+  return `Run: harness-dev validate`;
+}

package/cli/commands/validate.mjs

@@ -0,0 +1,118 @@
+/**
+ * validate — Run gate checks for current phase.
+ *
+ * If gates.enabled is false, prints "Gates disabled" and exits 0.
+ * Otherwise runs phase-specific checks and reports results.
+ *
+ * Usage:
+ *   harness-dev validate              — check current phase
+ *   harness-dev validate --json       — machine-readable output
+ *   harness-dev validate --phase X    — check specific phase
+ *
+ * Examples:
+ *   harness-dev validate
+ *   # → BUILD Gate: PASS — 3/3 checks pass
+ *
+ *   harness-dev validate --json
+ *   # → {"phase":"build","checks":[...],"overall":false,"failures":["lint"]}
+ */
+import { resolve } from 'node:path';
+import { die, CliError, EXIT } from '../lib/errors.mjs';
+import { runChecks, getPhase, areGatesEnabled } from '../lib/gates.mjs';
+import { phaseLabel } from '../lib/command-helpers.mjs';
+
+export default async function validateCommand(args) {
+  const json = !!(args.json || args.flags?.json);
+  const rawTarget = args.flags?.target;
+  const targetDir = (typeof rawTarget === 'string') ? resolve(rawTarget) : process.cwd();
+
+  // Allow explicit --phase override
+  const explicitPhase = args.flags?.phase;
+  const phase = explicitPhase || getPhase(targetDir);
+
+  // Feature/task scoping for inner-loop per-task validation
+  // NOTE: gates.mjs currently runs full phase-level checks.
+  // Per-feature/task filtering should be implemented when the
+  // gate engine grows feature-aware check functions (T8 follow-up).
+  const feature = typeof args.flags?.feature === 'string' ? args.flags.feature : null;
+  const task = typeof args.flags?.task === 'string' ? args.flags.task : null;
+
+  // Gates disabled check
+  if (!areGatesEnabled(targetDir)) {
+    if (json) {
+      const out = {
+        command: 'validate',
+        phase,
+        status: 'ok',
+        message: 'Gates disabled — enable with: config set gates.enabled true',
+        checks: [],
+        overall: true,
+        failures: [],
+      };
+      if (feature) { out.feature = feature; }
+      if (task) { out.task = task; }
+      process.stdout.write(JSON.stringify(out) + '\n');
+    } else {
+      process.stdout.write('Gates disabled. Enable with: harness-dev config set gates.enabled true\n');
+    }
+    return;
+  }
+
+  // No phase determined
+  if (!phase) {
+    die(
+      new CliError(
+        'No phase found in config. Run: harness-dev init or harness-dev phase <name>',
+        EXIT.VALIDATION_FAILURE,
+      ),
+      json,
+    );
+    return;
+  }
+
+  // Run checks
+  const result = runChecks(targetDir, phase, { feature, task });
+
+  if (json) {
+    const out = {
+      command: 'validate',
+      phase: result.phase,
+      status: result.overall ? 'ok' : 'error',
+      message: result.overall
+        ? `${phaseLabel(result.phase)} Gate: PASS — ${result.checks.length}/${result.checks.length} checks pass`
+        : `${phaseLabel(result.phase)} Gate: FAIL — ${result.checks.length - result.failures.length}/${result.checks.length} checks pass`,
+      checks: result.checks,
+      overall: result.overall,
+      failures: result.failures,
+    };
+    if (feature) { out.feature = feature; }
+    if (task) { out.task = task; }
+    process.stdout.write(JSON.stringify(out) + '\n');
+    if (!result.overall) {
+      process.exit(EXIT.VALIDATION_FAILURE);
+    }
+    return;
+  }
+
+  // Human output
+  const label = phaseLabel(result.phase);
+  if (result.overall) {
+    process.stdout.write(`${label} Gate: PASS — ${result.checks.length}/${result.checks.length} checks pass\n`);
+  } else {
+    process.stdout.write(`${label} Gate: FAIL — ${result.checks.length - result.failures.length}/${result.checks.length} checks pass\n`);
+  }
+
+  for (const check of result.checks) {
+    const icon = check.pass ? '  ✅' : '  ❌';
+    process.stdout.write(`${icon} ${check.name}: ${check.detail}\n`);
+  }
+
+  if (!result.overall) {
+    process.stdout.write(`\nFailed: ${result.failures.join(', ')}\n`);
+  }
+
+  // Exit with failure code when checks fail
+  if (!result.overall) {
+    process.exit(EXIT.VALIDATION_FAILURE);
+  }
+}

package/cli/commands/worktree.mjs

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+/**
+ * worktree — Git worktree management (create/list/prune/remove).
+ *
+ * T17 implementation:
+ *   create <name>   — git worktree add ../feat-<name> feat/<name> + scaffold
+ *   list            — list active worktrees with branch, path
+ *   prune           — git worktree prune (remove orphaned metadata)
+ *   remove <name>   — git worktree remove + optionally delete branch
+ *
+ * Usage: harness-dev worktree <subcommand> [name] [options]
+ */
+import { existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { die, CliError, EXIT } from '../lib/errors.mjs';
+import { detectStack } from '../lib/detect-stack.mjs';
+import { loadConfig, saveConfig } from '../lib/state.mjs';
+import { execGit, getGitRoot } from '../lib/git.mjs';
+import { parseCommandArgs } from '../lib/command-helpers.mjs';
+
+const SUBCOMMANDS = ['create', 'list', 'prune', 'remove'];
+
+export default async function worktreeCommand(args) {
+  const { json, targetDir } = parseCommandArgs(args);
+  const sub = args.subcommand;
+
+  if (!sub || !SUBCOMMANDS.includes(sub)) {
+    die(new CliError(`Usage: harness-dev worktree ${SUBCOMMANDS.join('|')}`, EXIT.USAGE_ERROR), json);
+    return;
+  }
+
+  const gitRoot = getGitRoot(targetDir);
+  if (!gitRoot) {
+    const msg = 'Not inside a git repository. Run: git init first or harness-dev init';
+    if (json) {
+      process.stdout.write(JSON.stringify({ command: 'worktree', subcommand: sub, status: 'error', message: msg }) + '\n');
+    } else {
+      process.stderr.write(`Error: ${msg}\n`);
+    }
+    return;
+  }
+
+  // ── create ───────────────────────────────────────────────────────────────
+  if (sub === 'create') {
+    const name = args.positionals[0];
+    if (!name) {
+      die(new CliError('Usage: harness-dev worktree create <name>', EXIT.USAGE_ERROR), json);
+      return;
+    }
+
+    const branchName = `feat/${name}`;
+    const worktreePath = resolve(dirname(gitRoot), `feat-${name}`);
+
+    // Check branch doesn't already exist
+    const branchCheck = execGit(`git show-ref --verify --quiet refs/heads/${branchName}`, gitRoot);
+    if (branchCheck.ok) {
+      const msg = `Branch "${branchName}" already exists. Choose a different name.`;
+      if (json) {
+        process.stdout.write(JSON.stringify({ command: 'worktree', subcommand: 'create', name, branch: branchName, status: 'error', message: msg }) + '\n');
+      } else {
+        process.stderr.write(`Error: ${msg}\n`);
+      }
+      return;
+    }
+
+    // Check target directory doesn't exist
+    if (existsSync(worktreePath)) {
+      const msg = `Target directory already exists: ${worktreePath}`;
+      if (json) {
+        process.stdout.write(JSON.stringify({ command: 'worktree', subcommand: 'create', name, branch: branchName, path: worktreePath, status: 'error', message: msg }) + '\n');
+      } else {
+        process.stderr.write(`Error: ${msg}\n`);
+      }
+      return;
+    }
+
+    // Create the worktree
+    const addResult = execGit(`git worktree add "${worktreePath}" -b "${branchName}"`, gitRoot);
+    if (!addResult.ok) {
+      const msg = `Failed to create worktree: ${addResult.stderr || addResult.stdout}`;
+      if (json) {
+        process.stdout.write(JSON.stringify({ command: 'worktree', subcommand: 'create', name, branch: branchName, path: worktreePath, status: 'error', message: msg }) + '\n');
+      } else {
+        process.stderr.write(`Error: ${msg}\n`);
+      }
+      return;
+    }
+
+    // Scaffold harness in the new worktree — run full init with parent's detected stack
+    const stack = detectStack(worktreePath).name;
+    const harnessDevPath = new URL('../harness-dev.mjs', import.meta.url).pathname;
+    const initResult = execGit(
+      `node "${harnessDevPath}" init --stack "${stack}" --force --no-git --json`,
+      worktreePath,
+    );
+    let filesCreated = 0;
+    let initErrors = [];
+    if (initResult.ok && initResult.stdout) {
+      try {
+        const initJson = JSON.parse(initResult.stdout);
+        filesCreated = initJson.filesCreated || 0;
+        initErrors = initJson.errors || [];
+      } catch { /* ignore parse error — fall through */ }
+    }
+
+    // Overwrite harness-config.json with worktree context (keep init settings)
+    const cfg = {
+      version: '1.0',
+      stack,
+      mode: 'copilot',
+      currentPhase: null,
+      paused: false,
+      features: { remaining: 0, passing: 0, total: 0 },
+      gates: { enabled: false, checks: ['all'] },
+      git: { autoCommit: false, autoTag: false, resetOnRetry: false, branch: branchName, clean: true, hasUpstream: false, lastCommitMessage: null },
+      phases: { enabled: ['define', 'plan', 'build', 'verify', 'review', 'ship'] },
+      agents: { tone: { planner: 'Analytical and precise. Define clear boundaries.', generator: 'Focused and practical. Build what\'s specified, nothing more.', evaluator: 'Skeptical and thorough. Accept only compelling evidence.', simplifier: 'Relentless about clarity. Delete more than you add.' } },
+      maxRetries: 3,
+      gateHistory: [],
+      worktree: { parent: gitRoot, name, branch: branchName },
+    };
+    saveConfig(worktreePath, cfg);
+
+    if (json) {
+      process.stdout.write(JSON.stringify({
+        command: 'worktree',
+        subcommand: 'create',
+        name,
+        branch: branchName,
+        path: worktreePath,
+        stacked: true,
+        status: initErrors.length > 0 ? 'partial' : 'ok',
+        message: `Worktree created at ${worktreePath} on branch ${branchName}`,
+        filesCreated,
+        errors: initErrors,
+      }) + '\n');
+    } else {
+      process.stdout.write(`✓ Worktree created at ${worktreePath}\n`);
+      process.stdout.write(`  Branch: ${branchName}\n`);
+      process.stdout.write(`  Harness scaffolded with stack "${stack}" (${filesCreated} files)\n`);
+      for (const e of initErrors) {
+        process.stderr.write(`  ⚠ ${e}\n`);
+      }
+    }
+    return;
+  }
+
+  // ── list ─────────────────────────────────────────────────────────────────
+  if (sub === 'list') {
+    const result = execGit('git worktree list', gitRoot);
+    if (!result.ok) {
+      const msg = `Failed to list worktrees: ${result.stderr || result.stdout}`;
+      if (json) {
+        process.stdout.write(JSON.stringify({ command: 'worktree', subcommand: 'list', status: 'error', message: msg }) + '\n');
+      } else {
+        process.stderr.write(`Error: ${msg}\n`);
+      }
+      return;
+    }
+
+    const lines = result.stdout.split('\n').filter(Boolean);
+    const worktrees = lines.map(line => {
+      const parts = line.split(/\s+/);
+      const path = parts[0];
+      const hash = parts[1];
+      const branch = parts.slice(2).join(' ').replace(/^\[|\]$/g, '') || '(detached HEAD)';
+      return { path, hash, branch };
+    });
+
+    // Try to enrich with harness phase info
+    for (const wt of worktrees) {
+      const cfg = loadConfig(wt.path);
+      if (cfg.ok && cfg.config) {
+        wt.phase = cfg.config.currentPhase || null;
+        wt.stack = cfg.config.stack || null;
+      } else {
+        wt.phase = null;
+        wt.stack = null;
+      }
+    }
+
+    if (json) {
+      process.stdout.write(JSON.stringify({
+        command: 'worktree',
+        subcommand: 'list',
+        status: 'ok',
+        message: `${worktrees.length} worktree(s)`,
+        worktrees,
+      }) + '\n');
+    } else {
+      if (worktrees.length === 0) {
+        process.stdout.write('No worktrees found.\n');
+      } else {
+        process.stdout.write(`${'Path'.padEnd(50)} ${'Branch'.padEnd(30)} Phase\n`);
+        process.stdout.write(`${''.padEnd(50, '-')} ${''.padEnd(30, '-')} ${''.padEnd(10, '-')}\n`);
+        for (const wt of worktrees) {
+          const phase = wt.phase || '—';
+          process.stdout.write(`${wt.path.padEnd(50)} ${wt.branch.padEnd(30)} ${phase}\n`);
+        }
+      }
+    }
+    return;
+  }
+
+  // ── prune ────────────────────────────────────────────────────────────────
+  if (sub === 'prune') {
+    const result = execGit('git worktree prune', gitRoot);
+    if (!result.ok) {
+      const msg = `Failed to prune worktrees: ${result.stderr || result.stdout}`;
+      if (json) {
+        process.stdout.write(JSON.stringify({ command: 'worktree', subcommand: 'prune', status: 'error', message: msg }) + '\n');
+      } else {
+        process.stderr.write(`Error: ${msg}\n`);
+      }
+      return;
+    }
+
+    if (json) {
+      process.stdout.write(JSON.stringify({
+        command: 'worktree',
+        subcommand: 'prune',
+        status: 'ok',
+        message: 'Orphaned worktree metadata pruned',
+      }) + '\n');
+    } else {
+      process.stdout.write('✓ Orphaned worktree metadata pruned\n');
+    }
+    return;
+  }
+
+  // ── remove ───────────────────────────────────────────────────────────────
+  if (sub === 'remove') {
+    const name = args.positionals[0];
+    if (!name) {
+      die(new CliError('Usage: harness-dev worktree remove <name>', EXIT.USAGE_ERROR), json);
+      return;
+    }
+
+    const worktreePath = resolve(dirname(gitRoot), `feat-${name}`);
+    const branchName = `feat/${name}`;
+
+    if (!existsSync(worktreePath)) {
+      const msg = `Worktree path not found: ${worktreePath}. It may have been deleted manually.`;
+      if (json) {
+        process.stdout.write(JSON.stringify({ command: 'worktree', subcommand: 'remove', name, status: 'error', message: msg }) + '\n');
+      } else {
+        process.stderr.write(`Error: ${msg}\n`);
+      }
+      return;
+    }
+
+    // Remove worktree
+    const forceRemove = args.flags?.force === true || args.flags?.force === 'true';
+    let removeResult;
+    if (forceRemove) {
+      removeResult = execGit(`git worktree remove --force "${worktreePath}"`, gitRoot);
+    } else {
+      removeResult = execGit(`git worktree remove "${worktreePath}"`, gitRoot);
+    }
+    if (!removeResult.ok) {
+      const msg = `Failed to remove worktree: ${removeResult.stderr || removeResult.stdout}`;
+      if (json) {
+        process.stdout.write(JSON.stringify({ command: 'worktree', subcommand: 'remove', name, status: 'error', message: msg }) + '\n');
+      } else {
+        process.stderr.write(`Error: ${msg}\n`);
+      }
+      return;
+    }
+
+    // Optionally delete the branch (--delete-branch flag)
+    const deleteBranch = args.flags?.['delete-branch'] === true || args.flags?.['delete-branch'] === 'true';
+    let branchDeleted = false;
+    if (deleteBranch) {
+      const branchResult = execGit(`git branch -D "${branchName}"`, gitRoot);
+      if (branchResult.ok) {
+        branchDeleted = true;
+      }
+    }
+
+    if (json) {
+      process.stdout.write(JSON.stringify({
+        command: 'worktree',
+        subcommand: 'remove',
+        name,
+        path: worktreePath,
+        branchDeleted,
+        status: 'ok',
+        message: `Worktree removed from ${worktreePath}`,
+      }) + '\n');
+    } else {
+      process.stdout.write(`✓ Worktree removed from ${worktreePath}\n`);
+      if (branchDeleted) {
+        process.stdout.write(`  Branch "${branchName}" deleted\n`);
+      }
+    }
+    return;
+  }
+}

package/cli/harness-dev.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * harness-dev — Agent-agnostic development harness CLI.
+ *
+ * Entry point. Parses args, routes to command handler,
+ * formats output (human or JSON), handles errors.
+ */
+
+import { parseArgs } from './lib/args.mjs';
+import { CliError, EXIT, die } from './lib/errors.mjs';
+import { helpText, versionText, commandHelpText } from './lib/help.mjs';
+
+/** Map of command names to their implementation modules. */
+const COMMANDS = {
+  init:      () => import('./commands/init.mjs'),
+  status:    () => import('./commands/status.mjs'),
+  phase:     () => import('./commands/phase.mjs'),
+  validate:  () => import('./commands/validate.mjs'),
+  'set-mode': () => import('./commands/set-mode.mjs'),
+  config:    () => import('./commands/config.mjs'),
+  pause:     () => import('./commands/pause.mjs'),
+  resume:    () => import('./commands/resume.mjs'),
+  learn:     () => import('./commands/learn.mjs'),
+  contract:  () => import('./commands/contract.mjs'),
+  worktree:  () => import('./commands/worktree.mjs'),
+  rollback:  () => import('./commands/rollback.mjs'),
+  checkpoint: () => import('./commands/checkpoint.mjs'),
+  'detect-tool': () => import('./commands/detect-tool.mjs'),
+  help:      null, // handled inline — prints help text, registers as valid command
+};
+
+async function main() {
+  const args = parseArgs(process.argv);
+  const json = args.json;
+
+  // --help with no command
+  if (args.help && !args.command) {
+    process.stdout.write(helpText(json) + '\n');
+    return;
+  }
+
+  // --version
+  if (args.version) {
+    process.stdout.write(versionText(json) + '\n');
+    return;
+  }
+
+  // --help with a command → per-command help (falls back to global help)
+  if (args.help && args.command) {
+    const perCmd = commandHelpText(args.command, json);
+    process.stdout.write((perCmd ?? helpText(json)) + '\n');
+    return;
+  }
+
+  // No command → help (exit 0, not an error)
+  if (!args.command) {
+    process.stdout.write(helpText(json) + '\n');
+    return;
+  }
+
+  // "help" command alias — redirects to --help
+  if (args.command === 'help') {
+    process.stdout.write(helpText(json) + '\n');
+    return;
+  }
+
+  // Resolve command module
+  const loader = COMMANDS[args.command];
+  if (!loader) {
+    throw new CliError(
+      `Unknown command "${args.command}". See harness-dev --help`,
+      EXIT.USAGE_ERROR
+    );
+  }
+
+  // Load and execute
+  const mod = await loader();
+  await mod.default(args);
+}
+
+main().catch((err) => {
+  const isCli = err instanceof CliError;
+  // Detect --json from argv since parseArgs already ran
+  const json = process.argv.includes('--json');
+  die(err, json);
+  // die() calls process.exit, but keep this as safety net
+  process.exit(isCli ? EXIT.USAGE_ERROR : EXIT.INTERNAL_ERROR);
+});