@cassiomc1/forgeloop 0.1.14 → 0.1.16

package/src/cli.js

@@ -24,14 +24,54 @@ import { formatPolicyResult, runPolicy } from "./commands/policy.js";
 import { formatBundleResult, runBundle } from "./commands/bundle.js";
 import { formatPrepareCompletionResult, runPrepareCompletion } from "./commands/prepare-completion.js";
 import { formatRecordCheckResult, runRecordCheck } from "./commands/record-check.js";
+import { formatRunCheckResult, runCheck } from "./commands/run-check.js";
 import { formatRecordTerminalResult, runRecordTerminalResult } from "./commands/record-terminal-result.js";
 import { formatNextActionResult, runNext } from "./commands/next.js";
+import { formatContinuityResult, runContinuity } from "./commands/continuity.js";
+import { formatRecordContinuityResult, runRecordContinuity } from "./commands/record-continuity.js";
+import { formatReconcileContinuityResult, runReconcileContinuity } from "./commands/reconcile-continuity.js";
+import { formatClearContinuityResult, runClearContinuity } from "./commands/clear-continuity.js";
+import { continuityOptionDefaults, consumeContinuityOption, validateContinuityOptions } from "./core/continuity-cli-options.js";
 import { resolveTarget } from "./core/filesystem.js";
 import { getPackageRoot } from "./core/templates.js";
 import { ARTIFACT_PATHS } from "./core/artifacts.js";
 
+export const COMMANDS = Object.freeze([
+  "init",
+  "doctor",
+  "update",
+  "activate",
+  "route",
+  "preflight",
+  "advance",
+  "next",
+  "continuity",
+  "record-continuity",
+  "reconcile-continuity",
+  "clear-continuity",
+  "prepare-completion",
+  "run-check",
+  "record-check",
+  "record-terminal-result",
+  "complete",
+  "audit",
+  "report",
+  "policy",
+  "bundle",
+  "inspect",
+  "status",
+  "validate-state",
+  "clear-state",
+  "validate-receipt",
+  "validate-protocol",
+]);
+
+// Commands whose usage blocks already describe --json (doctor, route) or that
+// accept no --json at all (init, update).
+const GENERIC_JSON_EXCLUDED_COMMANDS = new Set(["init", "doctor", "update", "route"]);
+
 function usage(command = null) {
-  const commands = "init|doctor|update|activate|route|preflight|advance|next|prepare-completion|record-check|record-terminal-result|complete|audit|report|policy|bundle|inspect|status|validate-state|clear-state|validate-receipt|validate-protocol";
+  const commands = COMMANDS.join("|");
   const options = ["  --path <directory>  target project directory (default: current directory)"];
   if (!command || command === "init" || command === "update") {
     options.push("  --dry-run           show planned writes without changing files");
@@ -39,6 +79,7 @@ function usage(command = null) {
   if (!command || command === "doctor") {
     options.push("  --json              emit doctor findings as JSON");
     options.push("  --strict            treat warnings as unhealthy");
+    options.push("  --fix               restore missing managed template files");
     options.push("  --adopt <path>      preserve an existing adapter in the manifest");
   }
   if (!command || command === "route") {
@@ -53,7 +94,16 @@ function usage(command = null) {
   if (!command || command === "advance") {
     options.push("  --to <phase>        destination workflow phase");
   }
-  if (!command || ["activate", "advance", "next", "prepare-completion", "record-check", "record-terminal-result", "preflight", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"].includes(command)) {
+  if (!command || command === "record-continuity") {
+    options.push("  --focus-id <id>            current implementation focus ID");
+    options.push("  --focus-summary <text>    current implementation focus summary");
+    options.push("  --remaining <id:summary>  remaining implementation item (repeatable)");
+    options.push("  --known-issue <id:summary> known implementation issue (repeatable)");
+    options.push("  --changed-area <path>     changed project area (repeatable)");
+    options.push("  --inspect-first <path>    suggested inspection path (repeatable)");
+    options.push("  --resume-note <text>      bounded operational resume note");
+  }
+  if (!command || !GENERIC_JSON_EXCLUDED_COMMANDS.has(command)) {
     options.push("  --json              emit structured output as JSON");
   }
   if (!command || ["preflight", "complete", "audit", "report"].includes(command)) {
@@ -72,22 +122,30 @@ function usage(command = null) {
     options.push("  --route-file <path>  routing-result JSON relative to target");
     options.push("  --state-file <path>  work-state JSON relative to target");
     options.push("  --receipt-file <path>  execution-receipt JSON relative to target");
+    options.push("  --continuity-file <path>  optional execution-continuity JSON relative to target");
     options.push("  --task-brief-file <path>  task brief JSON (repeatable)");
     options.push("  --delegated-result-file <path>  delegated result JSON (repeatable)");
   }
   if (!command || command === "validate-receipt") {
     options.push("  --file <path>       receipt file relative to target");
   }
-  if (!command || command === "record-check") {
+  if (!command || command === "record-check" || command === "run-check") {
     options.push("  --id <id>            stable check identifier");
-    options.push("  --kind <kind>        check kind (default: command)");
     options.push("  --requirement <id>   completion requirement covered by the check");
+    options.push("  --details <json>     additional structured check details");
+  }
+  if (!command || command === "record-check") {
+    options.push("  --kind <kind>        check kind (default: command; use manual-review for manual evidence)");
     options.push("  --status <status>    passed, failed, blocked, or not-run");
     options.push("  --evidence-kind <kind> OBSERVED, INFERRED, NOT_VERIFIED, or BLOCKED");
-    options.push("  --command <text>     command already run by the agent (recorded only)");
-    options.push("  --result <text>      observed result supplied by the agent");
+    options.push("  --command <text>     recorded only as metadata; it is never executed");
+    options.push("  --result <text>      observed result supplied by the actor");
     options.push("  --exit-code <number> observed process exit code");
-    options.push("  --details <json>     additional structured check details");
+    options.push("  --execution-ref <id> ForgeLoop execution artifact reference");
+    options.push("  --provenance <value> FORGELOOP_EXECUTED, ACTOR_REPORTED, or MANUAL_OBSERVATION");
+  }
+  if (!command || command === "run-check") {
+    options.push("  -- <argv>            exact command argv to classify, execute, and attest");
   }
   if (!command || command === "record-terminal-result") {
     options.push("  --requirement <id>   terminal requirement covered by the result");
@@ -109,6 +167,7 @@ export function parseArgs(argv) {
     dryRun: false,
     json: false,
     strict: false,
+    fix: false,
     adopt: [],
     work: null,
     surfaces: [],
@@ -122,6 +181,8 @@ export function parseArgs(argv) {
     routeFile: null,
     stateFile: null,
     receiptFile: null,
+    continuityFile: null,
+    ...continuityOptionDefaults(),
     taskBriefFiles: [],
     delegatedResultFiles: [],
     checkId: null,
@@ -133,6 +194,9 @@ export function parseArgs(argv) {
     checkResult: null,
     checkExitCode: null,
     checkDetails: null,
+    checkExecutionRef: null,
+    checkProvenance: null,
+    commandArgv: [],
     checkType: null,
     checkSource: null,
     policy: null,
@@ -144,7 +208,7 @@ export function parseArgs(argv) {
 
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];
-    if (["init", "doctor", "update", "activate", "route", "preflight", "advance", "next", "prepare-completion", "record-check", "record-terminal-result", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"].includes(argument)) {
+    if (COMMANDS.includes(argument)) {
       if (command) throw new Error(`Multiple commands are not supported: ${argument}`);
       command = argument;
     } else if (argument === "--help" || argument === "-h") {
@@ -155,6 +219,8 @@ export function parseArgs(argv) {
       options.json = true;
     } else if (argument === "--strict") {
       options.strict = true;
+    } else if (argument === "--fix") {
+      options.fix = true;
     } else if (argument === "--adopt") {
       const relativePath = argv[index + 1];
       if (!relativePath || relativePath.startsWith("-")) throw new Error("--adopt requires a path");
@@ -204,12 +270,13 @@ export function parseArgs(argv) {
       if (!contractFile || contractFile.startsWith("-")) throw new Error("--contract-file requires a path");
       options.contractFile = contractFile;
       index += 1;
-    } else if (["--route-file", "--state-file", "--receipt-file"].includes(argument)) {
+    } else if (["--route-file", "--state-file", "--receipt-file", "--continuity-file"].includes(argument)) {
       const file = argv[index + 1];
       if (!file || file.startsWith("-")) throw new Error(`${argument} requires a path`);
       if (argument === "--route-file") options.routeFile = file;
       if (argument === "--state-file") options.stateFile = file;
       if (argument === "--receipt-file") options.receiptFile = file;
+      if (argument === "--continuity-file") options.continuityFile = file;
       index += 1;
     } else if (argument === "--task-brief-file") {
       const file = argv[index + 1];
@@ -304,6 +371,30 @@ export function parseArgs(argv) {
         throw new Error("--details must be a JSON object");
       }
       index += 1;
+    } else if (argument === "--execution-ref") {
+      const executionRef = argv[index + 1];
+      if (!executionRef || executionRef.startsWith("-")) throw new Error("--execution-ref requires an execution ID");
+      options.checkExecutionRef = executionRef;
+      index += 1;
+    } else if (argument === "--provenance") {
+      const provenance = argv[index + 1];
+      if (!provenance || provenance.startsWith("-")) throw new Error("--provenance requires a provenance value");
+      options.checkProvenance = provenance;
+      index += 1;
+    } else if (argument === "--" && command === "run-check") {
+      options.commandArgv = argv.slice(index + 1);
+      break;
+    } else if ([
+      "--focus-id",
+      "--focus-summary",
+      "--remaining",
+      "--known-issue",
+      "--changed-area",
+      "--inspect-first",
+      "--resume-note",
+    ].includes(argument)) {
+      const consumed = consumeContinuityOption({ argument, argv, index, options });
+      index = consumed.index;
     } else if (argument === "--path") {
       options.path = argv[index + 1];
       if (!options.path || options.path.startsWith("-")) throw new Error("--path requires a directory");
@@ -324,7 +415,7 @@ export function parseArgs(argv) {
 
   if (!command) return { command: null, options };
 
-  const jsonCommands = ["doctor", "route", "activate", "advance", "next", "prepare-completion", "record-check", "record-terminal-result", "preflight", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"];
+  const jsonCommands = ["doctor", "route", "activate", "advance", "next", "continuity", "record-continuity", "reconcile-continuity", "clear-continuity", "prepare-completion", "run-check", "record-check", "record-terminal-result", "preflight", "complete", "audit", "report", "policy", "bundle", "inspect", "status", "validate-state", "clear-state", "validate-receipt", "validate-protocol"];
   if (!jsonCommands.includes(command) && options.json) {
     throw new Error(`Option --json is not valid for ${command}`);
   }
@@ -340,6 +431,9 @@ export function parseArgs(argv) {
   if (command !== "doctor" && options.adopt.length > 0) {
     throw new Error(`Option --adopt is not valid for ${command}`);
   }
+  if (command !== "doctor" && options.fix) {
+    throw new Error(`Option --fix is not valid for ${command}`);
+  }
   if (command !== "route" && (options.work || options.surfaces.length || options.risks.length || options.platforms.length || options.behaviorChange || options.executableChange)) {
     throw new Error(`Route options are not valid for ${command}`);
   }
@@ -364,7 +458,7 @@ export function parseArgs(argv) {
   if (!["status", "inspect", "validate-protocol"].includes(command) && options.contractFile) {
     throw new Error(`Option --contract-file is not valid for ${command}`);
   }
-  if (command !== "validate-protocol" && (options.routeFile || options.stateFile || options.receiptFile || options.taskBriefFiles.length > 0 || options.delegatedResultFiles.length > 0)) {
+  if (command !== "validate-protocol" && (options.routeFile || options.stateFile || options.receiptFile || options.continuityFile || options.taskBriefFiles.length > 0 || options.delegatedResultFiles.length > 0)) {
     throw new Error(`Protocol artifact options are not valid for ${command}`);
   }
   const checkOptions = [
@@ -377,10 +471,13 @@ export function parseArgs(argv) {
     options.checkResult,
     options.checkExitCode,
     options.checkDetails,
+    options.checkExecutionRef,
+    options.checkProvenance,
   ];
-  if (command !== "record-check" && checkOptions.some((value) => value !== null)) {
+  if (!["record-check", "run-check"].includes(command) && checkOptions.some((value) => value !== null)) {
     throw new Error(`Check recording options are not valid for ${command}`);
   }
+  validateContinuityOptions(command, options);
   if (command === "record-check" && !options.help) {
     if (!options.checkId) throw new Error("record-check requires --id");
     if (!options.checkRequirement) throw new Error("record-check requires --requirement");
@@ -388,6 +485,17 @@ export function parseArgs(argv) {
     if (!options.checkEvidenceKind) throw new Error("record-check requires --evidence-kind");
     if (!options.checkCommand && !options.checkResult) throw new Error("record-check requires --command or --result");
   }
+  if (command === "run-check" && !options.help) {
+    if (!options.checkId) throw new Error("run-check requires --id");
+    if (!options.checkRequirement) throw new Error("run-check requires --requirement");
+    if (options.checkKind || options.checkStatus || options.checkEvidenceKind || options.checkCommand
+      || options.checkResult || options.checkExitCode !== null || options.checkExecutionRef || options.checkProvenance) {
+      throw new Error("run-check accepts only --id, --requirement, --details, and -- <argv>");
+    }
+    if (!Array.isArray(options.commandArgv) || options.commandArgv.length === 0) {
+      throw new Error("run-check requires -- followed by an exact command argv");
+    }
+  }
   return { command, options };
 }
 
@@ -405,6 +513,227 @@ function printActions(actions) {
   }
 }
 
+export const COMMAND_HANDLERS = Object.freeze({
+  init: async ({ target, packageRoot, packageVersion, options }) => {
+    const result = await runInit({ target, dryRun: options.dryRun, packageRoot, packageVersion });
+    printActions(result.actions);
+    return 0;
+  },
+  doctor: async ({ target, packageRoot, options }) => {
+    const result = await runDoctor({
+      target,
+      packageRoot,
+      adoptPaths: options.adopt,
+      strict: options.strict,
+      fix: options.fix,
+    });
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      for (const item of result.findings) {
+        console.log(`${item.severity}: ${item.code}: ${item.path} - ${item.message}`);
+      }
+      console.log(result.ok ? "healthy: ForgeLoop target is ready" : "unhealthy: ForgeLoop target needs attention");
+    }
+    return result.ok ? 0 : 1;
+  },
+  route: async ({ target, packageRoot, options }) => {
+    const result = await runRoute({
+      target,
+      packageRoot,
+      workType: options.work,
+      surfaces: options.surfaces,
+      risks: options.risks,
+      platforms: options.platforms,
+      behaviorChange: options.behaviorChange,
+      executableChange: options.executableChange,
+    });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatRouteResult(result));
+    return 0;
+  },
+  activate: async ({ target, packageRoot, options }) => {
+    const result = await runActivate({ target, packageRoot });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatActivateResult(result));
+    return 0;
+  },
+  preflight: async ({ target, packageRoot, options }) => {
+    const result = await runPreflight({ target, packageRoot, strict: options.strict });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatPreflightResult(result));
+    return result.status === "READY" ? 0 : 1;
+  },
+  advance: async ({ target, packageRoot, options }) => {
+    const result = await runAdvance({ target, packageRoot, to: options.to });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatAdvanceResult(result));
+    return 0;
+  },
+  next: async ({ target, packageRoot, options }) => {
+    const result = await runNext({ target, packageRoot });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatNextActionResult(result));
+    return 0;
+  },
+  continuity: async ({ target, packageRoot, options }) => {
+    const result = await runContinuity({ target, packageRoot });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatContinuityResult(result));
+    return 0;
+  },
+  "record-continuity": async ({ target, packageRoot, options }) => {
+    const result = await runRecordContinuity({
+      target, packageRoot,
+      focusId: options.continuityFocusId,
+      focusSummary: options.continuityFocusSummary,
+      remaining: options.continuityRemaining,
+      knownIssues: options.continuityKnownIssues,
+      changedAreas: options.continuityChangedAreas,
+      inspectFirst: options.continuityInspectFirst,
+      resumeNote: options.continuityResumeNote,
+    });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatRecordContinuityResult(result));
+    return 0;
+  },
+  "reconcile-continuity": async ({ target, packageRoot, options }) => {
+    const result = await runReconcileContinuity({ target, packageRoot });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatReconcileContinuityResult(result));
+    return 0;
+  },
+  "clear-continuity": async ({ target, options }) => {
+    const result = await runClearContinuity({ target });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatClearContinuityResult(result));
+    return 0;
+  },
+  "prepare-completion": async ({ target, packageRoot, options }) => {
+    const result = await runPrepareCompletion({ target, packageRoot });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatPrepareCompletionResult(result));
+    return 0;
+  },
+  "run-check": async ({ target, packageRoot, options }) => {
+    const result = await runCheck({
+      target,
+      packageRoot,
+      id: options.checkId,
+      requirement: options.checkRequirement,
+      argv: options.commandArgv,
+      details: options.checkDetails ?? undefined,
+    });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatRunCheckResult(result));
+    return result.check.status === "passed" ? 0 : 1;
+  },
+  "record-check": async ({ target, packageRoot, options }) => {
+    const result = await runRecordCheck({
+      target,
+      packageRoot,
+      id: options.checkId,
+      kind: options.checkKind ?? "command",
+      requirement: options.checkRequirement,
+      status: options.checkStatus,
+      evidenceKind: options.checkEvidenceKind,
+      command: options.checkCommand ?? undefined,
+      result: options.checkResult ?? undefined,
+      ...(options.checkExitCode === null ? {} : { exitCode: options.checkExitCode }),
+      details: options.checkDetails ?? undefined,
+      executionRef: options.checkExecutionRef ?? undefined,
+      provenance: options.checkProvenance ?? undefined,
+    });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatRecordCheckResult(result));
+    return 0;
+  },
+  "record-terminal-result": async ({ target, packageRoot, options }) => {
+    const result = await runRecordTerminalResult({
+      target,
+      packageRoot,
+      requirement: options.checkRequirement,
+      type: options.checkType,
+      status: options.checkStatus,
+      source: options.checkSource ?? options.checkCommand,
+      result: options.checkResult,
+      details: options.checkDetails ?? undefined,
+    });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatRecordTerminalResult(result));
+    return 0;
+  },
+  complete: async ({ target, packageRoot, options }) => {
+    const result = await runComplete({ target, packageRoot, strict: options.strict });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatCompleteResult(result));
+    return result.status === "VALID" ? 0 : 1;
+  },
+  audit: async ({ target, packageRoot, options }) => {
+    const result = await runAudit({ target, packageRoot, strict: options.strict });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatAuditResult(result));
+    return result.status === "VALID" ? 0 : 1;
+  },
+  report: async ({ target, packageRoot, options }) => {
+    const result = await runReport({ target, packageRoot, strict: options.strict });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatReportResult(result));
+    return result.verdict === "VALID" ? 0 : 1;
+  },
+  policy: async ({ target, packageRoot, options }) => {
+    const result = await runPolicy({ target, packageRoot, name: options.policy });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatPolicyResult(result));
+    return 0;
+  },
+  bundle: async ({ target, packageRoot, options }) => {
+    const result = await runBundle({ target, packageRoot, taskId: options.task });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatBundleResult(result));
+    return 0;
+  },
+  inspect: async ({ target, packageRoot, options }) => {
+    const result = await inspectTarget({ target, packageRoot, contractFile: options.contractFile });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatInspectResult(result));
+    return result.ok ? 0 : 1;
+  },
+  "validate-receipt": async ({ target, packageRoot, options }) => {
+    const result = await runValidateReceipt({ target, packageRoot, file: options.file });
+    console.log(options.json ? JSON.stringify(result, null, 2) : "valid: execution receipt");
+    return 0;
+  },
+  "validate-protocol": async ({ target, packageRoot, options }) => {
+    const result = await runValidateProtocol({
+      target,
+      packageRoot,
+      stateFile: options.stateFile ?? ARTIFACT_PATHS.state,
+      receiptFile: options.receiptFile ?? ARTIFACT_PATHS.receipt,
+      routeFile: options.routeFile ?? ARTIFACT_PATHS.route,
+      contractFile: options.contractFile,
+      continuityFile: options.continuityFile,
+      taskBriefFiles: options.taskBriefFiles,
+      delegatedResultFiles: options.delegatedResultFiles,
+    });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatValidateProtocolResult(result));
+    return result.status === "VALID" ? 0 : 1;
+  },
+  status: async ({ target, packageRoot, options }) => {
+    const result = await runStatus({ target, packageRoot, contractFile: options.contractFile });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatStatusResult(result));
+    return 0;
+  },
+  "validate-state": async ({ target, packageRoot, options }) => {
+    const result = await runValidateState({ target, packageRoot });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatValidateStateResult(result));
+    return result.ok ? 0 : 1;
+  },
+  "clear-state": async ({ target, options }) => {
+    const result = await runClearState({ target });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatClearStateResult(result));
+    return 0;
+  },
+  update: async ({ target, packageRoot, packageVersion, options }) => {
+    const result = await runUpdate({ target, dryRun: options.dryRun, packageRoot, packageVersion });
+    printActions(result.actions);
+    for (const conflict of result.conflicts) {
+      const code = conflict.code ? `${conflict.code}: ` : "";
+      console.log(`conflict: ${code}${conflict.path} - ${conflict.message}`);
+    }
+    return result.conflicts.length === 0 ? 0 : 1;
+  },
+});
+
+export const COMMAND_TABLE = Object.freeze(
+  COMMANDS.map((name) => Object.freeze({
+    name,
+    handler: COMMAND_HANDLERS[name],
+    usage: usage(name),
+  })),
+);
+
 export async function main(argv = process.argv.slice(2)) {
   try {
     const { command, options } = parseArgs(argv);
@@ -421,192 +750,18 @@ export async function main(argv = process.argv.slice(2)) {
     const packageRoot = getPackageRoot();
     const version = await packageVersion(packageRoot);
 
-    if (command === "init") {
-      const result = await runInit({ target, dryRun: options.dryRun, packageRoot, packageVersion: version });
-      printActions(result.actions);
-      return 0;
-    }
-
-    if (command === "doctor") {
-      const result = await runDoctor({
-        target,
-        packageRoot,
-        adoptPaths: options.adopt,
-        strict: options.strict,
-      });
-      if (options.json) {
-        console.log(JSON.stringify(result, null, 2));
-      } else {
-        for (const item of result.findings) {
-          console.log(`${item.severity}: ${item.code}: ${item.path} - ${item.message}`);
-        }
-        console.log(result.ok ? "healthy: ForgeLoop target is ready" : "unhealthy: ForgeLoop target needs attention");
-      }
-      return result.ok ? 0 : 1;
-    }
-
-    if (command === "route") {
-      const result = await runRoute({
-        target,
-        packageRoot,
-        workType: options.work,
-        surfaces: options.surfaces,
-        risks: options.risks,
-        platforms: options.platforms,
-        behaviorChange: options.behaviorChange,
-        executableChange: options.executableChange,
-      });
-      console.log(options.json ? JSON.stringify(result, null, 2) : formatRouteResult(result));
-      return 0;
-    }
-
-    if (command === "activate") {
-      const result = await runActivate({ target, packageRoot });
-      console.log(options.json ? JSON.stringify(result, null, 2) : formatActivateResult(result));
-      return 0;
-    }
-
-    if (command === "preflight") {
-      const result = await runPreflight({ target, packageRoot, strict: options.strict });
-      console.log(options.json ? JSON.stringify(result, null, 2) : formatPreflightResult(result));
-      return result.status === "READY" ? 0 : 1;
-    }
-
-    if (command === "advance") {
-      const result = await runAdvance({ target, packageRoot, to: options.to });
-      console.log(options.json ? JSON.stringify(result, null, 2) : formatAdvanceResult(result));
-      return 0;
-    }
-
-    if (command === "next") {
-      const result = await runNext({ target, packageRoot });
-      console.log(options.json ? JSON.stringify(result, null, 2) : formatNextActionResult(result));
-      return 0;
+    const handler = COMMAND_HANDLERS[command];
+    if (typeof handler !== "function") {
+      throw new Error(`Unsupported command: ${command}`);
     }
-
-    if (command === "prepare-completion") {
-      const result = await runPrepareCompletion({ target, packageRoot });
-      console.log(options.json ? JSON.stringify(result, null, 2) : formatPrepareCompletionResult(result));
-      return 0;
-    }
-
-    if (command === "record-check") {
-      const result = await runRecordCheck({
-        target,
-        packageRoot,
-        id: options.checkId,
-        kind: options.checkKind ?? "command",
-        requirement: options.checkRequirement,
-        status: options.checkStatus,
-        evidenceKind: options.checkEvidenceKind,
-        command: options.checkCommand ?? undefined,
-        result: options.checkResult ?? undefined,
-        exitCode: options.checkExitCode,
-        details: options.checkDetails ?? undefined,
-      });
-      console.log(options.json ? JSON.stringify(result, null, 2) : formatRecordCheckResult(result));
-      return 0;
-    }
-
-    if (command === "record-terminal-result") {
-      const result = await runRecordTerminalResult({
-        target,
-        packageRoot,
-        requirement: options.checkRequirement,
-        type: options.checkType,
-        status: options.checkStatus,
-        source: options.checkSource ?? options.checkCommand,
-        result: options.checkResult,
-        details: options.checkDetails ?? undefined,
-      });
-      console.log(options.json ? JSON.stringify(result, null, 2) : formatRecordTerminalResult(result));
-      return 0;
-    }
-
-    if (command === "complete") {
-      const result = await runComplete({ target, packageRoot, strict: options.strict });
-      console.log(options.json ? JSON.stringify(result, null, 2) : formatCompleteResult(result));
-      return result.status === "VALID" ? 0 : 1;
-    }
-
-    if (command === "audit") {
-      const result = await runAudit({ target, packageRoot, strict: options.strict });
-      console.log(options.json ? JSON.stringify(result, null, 2) : formatAuditResult(result));
-      return result.status === "VALID" ? 0 : 1;
-    }
-
-    if (command === "report") {
-      const result = await runReport({ target, packageRoot, strict: options.strict });
-      console.log(options.json ? JSON.stringify(result, null, 2) : formatReportResult(result));
-      return result.verdict === "VALID" ? 0 : 1;
-    }
-
-    if (command === "policy") {
-      const result = await runPolicy({ target, packageRoot, name: options.policy });
-      console.log(options.json ? JSON.stringify(result, null, 2) : formatPolicyResult(result));
-      return 0;
-    }
-
-    if (command === "bundle") {
-      const result = await runBundle({ target, packageRoot, taskId: options.task });
-      console.log(options.json ? JSON.stringify(result, null, 2) : formatBundleResult(result));
-      return 0;
-    }
-
-    if (command === "inspect") {
-      const result = await inspectTarget({ target, packageRoot, contractFile: options.contractFile });
-      console.log(options.json ? JSON.stringify(result, null, 2) : formatInspectResult(result));
-      return result.ok ? 0 : 1;
-    }
-
-    if (command === "validate-receipt") {
-      const result = await runValidateReceipt({ target, packageRoot, file: options.file });
-      console.log(options.json ? JSON.stringify(result, null, 2) : "valid: execution receipt");
-      return 0;
-    }
-
-    if (command === "validate-protocol") {
-      const result = await runValidateProtocol({
-        target,
-        packageRoot,
-        stateFile: options.stateFile ?? ARTIFACT_PATHS.state,
-        receiptFile: options.receiptFile ?? ARTIFACT_PATHS.receipt,
-        routeFile: options.routeFile ?? ARTIFACT_PATHS.route,
-        contractFile: options.contractFile,
-        taskBriefFiles: options.taskBriefFiles,
-        delegatedResultFiles: options.delegatedResultFiles,
-      });
-      console.log(options.json ? JSON.stringify(result, null, 2) : formatValidateProtocolResult(result));
-      return result.status === "VALID" ? 0 : 1;
-    }
-
-    if (command === "status") {
-      const result = await runStatus({ target, packageRoot, contractFile: options.contractFile });
-      console.log(options.json ? JSON.stringify(result, null, 2) : formatStatusResult(result));
-      return 0;
-    }
-
-    if (command === "validate-state") {
-      const result = await runValidateState({ target, packageRoot });
-      console.log(options.json ? JSON.stringify(result, null, 2) : formatValidateStateResult(result));
-      return result.ok ? 0 : 1;
-    }
-
-    if (command === "clear-state") {
-      const result = await runClearState({ target });
-      console.log(options.json ? JSON.stringify(result, null, 2) : formatClearStateResult(result));
-      return 0;
-    }
-
-    const result = await runUpdate({ target, dryRun: options.dryRun, packageRoot, packageVersion: version });
-    printActions(result.actions);
-    for (const conflict of result.conflicts) {
-      const code = conflict.code ? `${conflict.code}: ` : "";
-      console.log(`conflict: ${code}${conflict.path} - ${conflict.message}`);
-    }
-    return result.conflicts.length === 0 ? 0 : 1;
+    return await handler({
+      target,
+      packageRoot,
+      packageVersion: version,
+      options,
+    });
   } catch (error) {
-    console.error(`error: ${error.message}`);
+    console.error(`error: ${error.code ? `${error.code}: ` : ""}${error.message}`);
     return 1;
   }
 }