@cassiomc1/forgeloop 1.0.0 → 1.1.0

package/src/cli.js

@@ -31,137 +31,158 @@ 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 { formatTaskCreateResult, runTaskCreate } from "./commands/task-create.js";
+import { formatTaskListResult, runTaskList } from "./commands/task-list.js";
+import { formatTaskShowResult, runTaskShow } from "./commands/task-show.js";
+import { formatTaskScopeResult, runTaskScope } from "./commands/task-scope.js";
+import { formatTaskMigrateResult, runTaskMigrate } from "./commands/task-migrate.js";
+import { formatTaskUnlockResult, runTaskUnlock } from "./commands/task-unlock.js";
+import { continuityOptionDefaults, 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 = 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");
-  }
-  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") {
-    options.push("  --work <type>       declared work type");
-    options.push("  --surface <value>   affected surface (repeatable)");
-    options.push("  --risk <value>      task risk (repeatable)");
-    options.push("  --platform <value>  affected platform (repeatable)");
-    options.push("  --behavior-change   declare behavior change");
-    options.push("  --executable-change declare executable/configuration change");
-    options.push("  --json              emit route result as JSON");
-  }
-  if (!command || command === "advance") {
-    options.push("  --to <phase>        destination workflow phase");
-  }
-  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)) {
-    options.push("  --strict            require strict protocol compliance");
-  }
-  if (!command || command === "policy") {
-    options.push("  <name>              policy pack name");
-  }
-  if (!command || command === "bundle") {
-    options.push("  --task <id>         task ID to export as a portable bundle");
+import { CLI_COMMAND_DEFINITIONS, buildOptionLookup, getPositionalDefinitions } from "./core/cli-command-definitions.js";
+
+export const COMMANDS = Object.freeze(Object.keys(CLI_COMMAND_DEFINITIONS));
+
+function formatOptionUsage(optKey, optDef) {
+  let label = optKey;
+  if (optDef.valueName) {
+    label = optKey === "--" ? `-- <${optDef.valueName}>` : `${optKey} <${optDef.valueName}>`;
   }
-  if (!command || ["status", "inspect", "validate-protocol"].includes(command)) {
-    options.push("  --contract-file <path>  current JSON contract used for freshness comparison");
+  return `  ${label.padEnd(20)} ${optDef.description}`;
+}
+
+export function usage(command = null) {
+  if (command && CLI_COMMAND_DEFINITIONS[command]) {
+    const def = CLI_COMMAND_DEFINITIONS[command];
+    const lines = Object.entries(def.options).map(([optKey, optDef]) => formatOptionUsage(optKey, optDef));
+    return `Usage: forgeloop <${command}> [options]\n\nOptions:\n${lines.join("\n")}\n`;
   }
-  if (!command || command === "validate-protocol") {
-    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)");
+
+  const allOptions = new Map();
+  for (const def of Object.values(CLI_COMMAND_DEFINITIONS)) {
+    for (const [optKey, optDef] of Object.entries(def.options)) {
+      if (!allOptions.has(optKey)) {
+        allOptions.set(optKey, optDef);
+      }
+    }
   }
-  if (!command || command === "validate-receipt") {
-    options.push("  --file <path>       receipt file relative to target");
+
+  const lines = [...allOptions.entries()].map(([optKey, optDef]) => formatOptionUsage(optKey, optDef));
+  const commands = COMMANDS.join("|");
+  return `Usage: forgeloop <${commands}> [options]\n\nOptions:\n${lines.join("\n")}\n`;
+}
+
+export function splitLongOption(argument) {
+  if (!argument.startsWith("--")) {
+    return { name: argument, inlineValue: undefined };
   }
-  if (!command || command === "record-check" || command === "run-check") {
-    options.push("  --id <id>            stable check identifier");
-    options.push("  --requirement <id>   completion requirement covered by the check");
-    options.push("  --details <json>     additional structured check details");
+  const index = argument.indexOf("=");
+  if (index === -1) {
+    return { name: argument, inlineValue: undefined };
   }
-  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>     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("  --execution-ref <id> ForgeLoop execution artifact reference");
-    options.push("  --provenance <value> FORGELOOP_EXECUTED, ACTOR_REPORTED, or MANUAL_OBSERVATION");
+  return {
+    name: argument.slice(0, index),
+    inlineValue: argument.slice(index + 1),
+  };
+}
+
+function applyOption({ canonicalName, optionDef, inlineValue, argv, index, options, suppliedFlags }) {
+  const key = optionDef.targetKey;
+  suppliedFlags.add(canonicalName);
+
+  if (inlineValue !== undefined && !optionDef.takesValue) {
+    throw new Error(`${canonicalName} does not accept a value`);
   }
-  if (!command || command === "run-check") {
-    options.push("  -- <argv>            exact command argv to classify, execute, and attest");
+
+  switch (optionDef.parseType) {
+    case "boolean": {
+      options[key] = true;
+      return { index };
+    }
+    case "string": {
+      const value = inlineValue ?? argv[index + 1];
+      if (
+        value === undefined ||
+        (value.length === 0 && !optionDef.allowEmpty) ||
+        (value.startsWith("-") && inlineValue === undefined && !optionDef.allowLeadingHyphen)
+      ) {
+        throw new Error(optionDef.missingValueMessage ?? `${canonicalName} requires a value`);
+      }
+      if (optionDef.repeatable) {
+        if (!Array.isArray(options[key])) options[key] = [];
+        options[key].push(value);
+      } else {
+        options[key] = value;
+      }
+      return { index: inlineValue === undefined ? index + 1 : index };
+    }
+    case "non-negative-integer": {
+      const value = inlineValue ?? argv[index + 1];
+      if (value === undefined || !/^\d+$/.test(value)) {
+        throw new Error(optionDef.missingValueMessage ?? `${canonicalName} requires a non-negative integer`);
+      }
+      options[key] = Number(value);
+      return { index: inlineValue === undefined ? index + 1 : index };
+    }
+    case "json-object": {
+      const raw = inlineValue ?? argv[index + 1];
+      if (!raw || (raw.startsWith("-") && inlineValue === undefined)) {
+        throw new Error(optionDef.missingValueMessage ?? `${canonicalName} requires a JSON object`);
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        throw new Error(`${canonicalName} must be valid JSON`);
+      }
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`${canonicalName} must be a JSON object`);
+      }
+      options[key] = parsed;
+      return { index: inlineValue === undefined ? index + 1 : index };
+    }
+    case "argv": {
+      const remaining = argv.slice(index + 1);
+      options[key] = remaining;
+      return { index: argv.length, stop: true };
+    }
+    default:
+      throw new Error(`Unsupported option type: ${optionDef.parseType}`);
   }
-  if (!command || command === "record-terminal-result") {
-    options.push("  --requirement <id>   terminal requirement covered by the result");
-    options.push("  --type <type>        PUBLICATION or PRODUCTION_READINESS");
-    options.push("  --status <status>    observed terminal status");
-    options.push("  --source <text>      external action source (e.g. npm publish, git push)");
-    options.push("  --result <text>      observed external result description");
-    options.push("  --details <json>     additional structured result details");
+}
+
+const ALL_VALUE_TAKING_FLAGS = new Set();
+for (const def of Object.values(CLI_COMMAND_DEFINITIONS)) {
+  for (const [optName, optDef] of Object.entries(def.options)) {
+    if (optDef.takesValue && optName.startsWith("-")) {
+      ALL_VALUE_TAKING_FLAGS.add(optName);
+    }
   }
-  options.push("  --version           show the installed package version");
-  options.push("  --help              show this help");
+}
 
-  return `Usage: forgeloop <${command ?? commands}> [options]\n\nOptions:\n${options.join("\n")}\n`;
+export function discoverCommand(argv) {
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--") break;
+
+    if (arg.startsWith("-")) {
+      const eqIdx = arg.indexOf("=");
+      const optName = eqIdx === -1 ? arg : arg.slice(0, eqIdx);
+      if (eqIdx === -1 && ALL_VALUE_TAKING_FLAGS.has(optName)) {
+        i += 1; // Skip the option's value so it is never scanned as a candidate command
+      }
+      continue;
+    }
+
+    if (COMMANDS.includes(arg)) {
+      return arg;
+    }
+  }
+  return null;
 }
 
-export function parseArgs(argv) {
+export function parseCliSyntax(argv) {
   const options = {
     path: ".",
     dryRun: false,
@@ -204,242 +225,84 @@ export function parseArgs(argv) {
     help: false,
     version: false,
   };
-  let command = null;
+
+  const command = discoverCommand(argv);
+  const bootstrapLookup = buildOptionLookup(null);
+  const commandLookup = buildOptionLookup(command);
+  const positionalDefs = getPositionalDefinitions(command);
+  let positionalCursor = 0;
+  const suppliedFlags = new Set();
+  let commandSeen = false;
 
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];
-    if (COMMANDS.includes(argument)) {
-      if (command) throw new Error(`Multiple commands are not supported: ${argument}`);
-      command = argument;
-    } else if (argument === "--help" || argument === "-h") {
-      options.help = true;
-    } else if (argument === "--dry-run") {
-      options.dryRun = true;
-    } else if (argument === "--json") {
-      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");
-      options.adopt.push(relativePath);
-      index += 1;
-    } else if (argument === "--work") {
-      const workType = argv[index + 1];
-      if (!workType || workType.startsWith("-")) throw new Error("--work requires a type");
-      options.work = workType;
-      index += 1;
-    } else if (argument === "--surface") {
-      const surface = argv[index + 1];
-      if (!surface || surface.startsWith("-")) throw new Error("--surface requires a value");
-      options.surfaces.push(surface);
-      index += 1;
-    } else if (argument === "--risk") {
-      const risk = argv[index + 1];
-      if (!risk || risk.startsWith("-")) throw new Error("--risk requires a value");
-      options.risks.push(risk);
-      index += 1;
-    } else if (argument === "--platform") {
-      const platform = argv[index + 1];
-      if (!platform || platform.startsWith("-")) throw new Error("--platform requires a value");
-      options.platforms.push(platform);
-      index += 1;
-    } else if (argument === "--behavior-change") {
-      options.behaviorChange = true;
-    } else if (argument === "--executable-change") {
-      options.executableChange = true;
-    } else if (argument === "--to") {
-      const phase = argv[index + 1];
-      if (!phase || phase.startsWith("-")) throw new Error("--to requires a phase");
-      options.to = phase;
-      index += 1;
-    } else if (argument === "--task") {
-      const task = argv[index + 1];
-      if (!task || task.startsWith("-")) throw new Error("--task requires an ID");
-      options.task = task;
-      index += 1;
-    } else if (argument === "--file") {
-      const file = argv[index + 1];
-      if (!file || file.startsWith("-")) throw new Error("--file requires a path");
-      options.file = file;
-      index += 1;
-    } else if (argument === "--contract-file") {
-      const contractFile = argv[index + 1];
-      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", "--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];
-      if (!file || file.startsWith("-")) throw new Error("--task-brief-file requires a path");
-      options.taskBriefFiles.push(file);
-      index += 1;
-    } else if (argument === "--delegated-result-file") {
-      const file = argv[index + 1];
-      if (!file || file.startsWith("-")) throw new Error("--delegated-result-file requires a path");
-      options.delegatedResultFiles.push(file);
-      index += 1;
-    } else if (argument === "--id") {
-      const id = argv[index + 1];
-      if (!id || id.startsWith("-")) throw new Error("--id requires a check ID");
-      options.checkId = id;
-      index += 1;
-    } else if (argument.startsWith("--id=")) {
-      const id = argument.slice("--id=".length);
-      if (!id || id.startsWith("-")) throw new Error("--id requires a check ID");
-      options.checkId = id;
-    } else if (argument === "--kind") {
-      const kind = argv[index + 1];
-      if (!kind || kind.startsWith("-")) throw new Error("--kind requires a check kind");
-      options.checkKind = kind;
-      index += 1;
-    } else if (argument === "--requirement") {
-      const requirement = argv[index + 1];
-      if (!requirement || requirement.startsWith("-")) throw new Error("--requirement requires an evidence target");
-      options.checkRequirement = requirement;
-      index += 1;
-    } else if (argument.startsWith("--requirement=")) {
-      const requirement = argument.slice("--requirement=".length);
-      if (!requirement) throw new Error("--requirement requires an evidence target");
-      options.checkRequirement = requirement;
-    } else if (argument === "--status") {
-      const status = argv[index + 1];
-      if (!status || status.startsWith("-")) throw new Error("--status requires a check status");
-      options.checkStatus = status;
-      index += 1;
-    } else if (argument === "--evidence-kind") {
-      const evidenceKind = argv[index + 1];
-      if (!evidenceKind || evidenceKind.startsWith("-")) throw new Error("--evidence-kind requires an evidence kind");
-      options.checkEvidenceKind = evidenceKind;
-      index += 1;
-    } else if (argument === "--command") {
-      const commandText = argv[index + 1];
-      if (!commandText || commandText.startsWith("-")) throw new Error("--command requires recorded text");
-      options.checkCommand = commandText;
-      index += 1;
-    } else if (argument === "--source") {
-      const sourceText = argv[index + 1];
-      if (!sourceText || sourceText.startsWith("-")) throw new Error("--source requires recorded text");
-      options.checkSource = sourceText;
-      index += 1;
-    } else if (argument.startsWith("--source=")) {
-      const sourceText = argument.slice("--source=".length);
-      if (!sourceText) throw new Error("--source requires recorded text");
-      options.checkSource = sourceText;
-    } else if (argument === "--type") {
-      const typeValue = argv[index + 1];
-      if (!typeValue || typeValue.startsWith("-")) throw new Error("--type requires a terminal type");
-      options.checkType = typeValue;
-      index += 1;
-    } else if (argument.startsWith("--type=")) {
-      const typeValue = argument.slice("--type=".length);
-      if (!typeValue) throw new Error("--type requires a terminal type");
-      options.checkType = typeValue;
-    } else if (argument === "--result") {
-      const resultText = argv[index + 1];
-      if (!resultText || resultText.startsWith("-")) throw new Error("--result requires recorded text");
-      options.checkResult = resultText;
-      index += 1;
-    } else if (argument.startsWith("--result=")) {
-      const resultText = argument.slice("--result=".length);
-      if (!resultText) throw new Error("--result requires recorded text");
-      options.checkResult = resultText;
-    } else if (argument === "--exit-code") {
-      const exitCode = argv[index + 1];
-      if (!exitCode || exitCode.startsWith("-")) throw new Error("--exit-code requires a non-negative integer");
-      if (!/^\d+$/.test(exitCode)) throw new Error("--exit-code requires a non-negative integer");
-      options.checkExitCode = Number(exitCode);
-      index += 1;
-    } else if (argument === "--details") {
-      const details = argv[index + 1];
-      if (!details || details.startsWith("-")) throw new Error("--details requires a JSON object");
-      try {
-        options.checkDetails = JSON.parse(details);
-      } catch {
-        throw new Error("--details must be valid JSON");
+
+    if (argument === command && !commandSeen) {
+      commandSeen = true;
+      continue;
+    }
+
+    if (argument === "--") {
+      if (!commandSeen) {
+        throw new Error("-- is not valid before a command");
       }
-      if (!options.checkDetails || typeof options.checkDetails !== "object" || Array.isArray(options.checkDetails)) {
-        throw new Error("--details must be a JSON object");
+      const passthrough = commandLookup.get("--");
+      if (!passthrough) {
+        throw new Error(`Unknown option: --`);
       }
-      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);
+      options[passthrough.optionDef.targetKey] = argv.slice(index + 1);
+      suppliedFlags.add("--");
       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");
-      index += 1;
-    } else if (argument.startsWith("--path=")) {
-      options.path = argument.slice("--path=".length);
-      if (!options.path || options.path.startsWith("-")) throw new Error("--path requires a directory");
-    } else if (argument === "--version" || argument === "-v") {
-      options.version = true;
-    } else if (!argument.startsWith("-") && command === "policy" && !options.policy) {
-      options.policy = argument;
-    } else if (!argument.startsWith("-") && !command) {
-      command = argument;
+    }
+
+    const { name: optName, inlineValue } = splitLongOption(argument);
+    const activeLookup = commandSeen ? commandLookup : bootstrapLookup;
+    const matched = activeLookup.get(optName);
+
+    if (matched) {
+      const res = applyOption({
+        canonicalName: matched.canonicalName,
+        optionDef: matched.optionDef,
+        inlineValue,
+        argv,
+        index,
+        options,
+        suppliedFlags,
+      });
+      index = res.index;
+      if (res.stop) break;
+      continue;
+    }
+
+    if (commandSeen && command && !argument.startsWith("-")) {
+      const positional = positionalDefs[positionalCursor];
+      if (positional) {
+        options[positional.targetKey] = argument;
+        positionalCursor += 1;
+        continue;
+      }
+    }
+
+    if (!commandSeen) {
+      if (!command) {
+        throw new Error(`Unknown option: ${argument}`);
+      }
+      throw new Error(`Option ${argument} is not valid before a command`);
+    }
+
+    if (command) {
+      throw new Error(`Option ${argument} is not valid for ${command}`);
     } else {
       throw new Error(`Unknown option: ${argument}`);
     }
   }
 
-  if (!command) return { command: null, options };
+  return { command, options };
+}
+
+export function validateCliSemantics({ command, options } = {}) {
+  if (!command) return;
 
-  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}`);
-  }
-  if (![
-    "init",
-    "update",
-  ].includes(command) && options.dryRun) {
-    throw new Error(`Option --dry-run is not valid for ${command}`);
-  }
-  if (!["doctor", "preflight", "complete", "audit", "report"].includes(command) && options.strict) {
-    throw new Error(`Option --strict is not valid for ${command}`);
-  }
-  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}`);
-  }
-  if (command !== "advance" && options.to) {
-    throw new Error(`Option --to is not valid for ${command}`);
-  }
   if (command === "policy" && !options.policy) {
     throw new Error("policy requires a name");
   }
@@ -449,35 +312,12 @@ export function parseArgs(argv) {
   if (command === "bundle" && !options.task) {
     throw new Error("bundle requires --task");
   }
-  if (command !== "bundle" && options.task) {
-    throw new Error(`--task is not valid for ${command}`);
-  }
-  if (command !== "validate-receipt" && options.file) {
-    throw new Error(`Option --file is not valid for ${command}`);
-  }
-  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.continuityFile || options.taskBriefFiles.length > 0 || options.delegatedResultFiles.length > 0)) {
-    throw new Error(`Protocol artifact options are not valid for ${command}`);
-  }
-  const checkOptions = [
-    options.checkId,
-    options.checkKind,
-    options.checkRequirement,
-    options.checkStatus,
-    options.checkEvidenceKind,
-    options.checkCommand,
-    options.checkResult,
-    options.checkExitCode,
-    options.checkDetails,
-    options.checkExecutionRef,
-    options.checkProvenance,
-  ];
-  if (!["record-check", "run-check"].includes(command) && checkOptions.some((value) => value !== null)) {
-    throw new Error(`Check recording options are not valid for ${command}`);
+  if (command === "task-create" && !options.task) {
+    throw new Error("task-create requires --task");
   }
+
   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");
@@ -496,7 +336,12 @@ export function parseArgs(argv) {
       throw new Error("run-check requires -- followed by an exact command argv");
     }
   }
-  return { command, options };
+}
+
+export function parseArgs(argv) {
+  const parsed = parseCliSyntax(argv);
+  validateCliSemantics(parsed);
+  return parsed;
 }
 
 async function packageVersion(packageRoot) {
@@ -547,6 +392,7 @@ export const COMMAND_HANDLERS = Object.freeze({
       platforms: options.platforms,
       behaviorChange: options.behaviorChange,
       executableChange: options.executableChange,
+      taskId: options.task,
     });
     console.log(options.json ? JSON.stringify(result, null, 2) : formatRouteResult(result));
     return 0;
@@ -557,22 +403,22 @@ export const COMMAND_HANDLERS = Object.freeze({
     return 0;
   },
   preflight: async ({ target, packageRoot, options }) => {
-    const result = await runPreflight({ target, packageRoot, strict: options.strict });
+    const result = await runPreflight({ target, packageRoot, strict: options.strict, taskId: options.task });
     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 });
+    const result = await runAdvance({ target, packageRoot, to: options.to, taskId: options.task });
     console.log(options.json ? JSON.stringify(result, null, 2) : formatAdvanceResult(result));
     return 0;
   },
   next: async ({ target, packageRoot, options }) => {
-    const result = await runNext({ target, packageRoot });
+    const result = await runNext({ target, packageRoot, taskId: options.task });
     console.log(options.json ? JSON.stringify(result, null, 2) : formatNextActionResult(result));
     return 0;
   },
   continuity: async ({ target, packageRoot, options }) => {
-    const result = await runContinuity({ target, packageRoot });
+    const result = await runContinuity({ target, packageRoot, taskId: options.task });
     console.log(options.json ? JSON.stringify(result, null, 2) : formatContinuityResult(result));
     return 0;
   },
@@ -586,22 +432,23 @@ export const COMMAND_HANDLERS = Object.freeze({
       changedAreas: options.continuityChangedAreas,
       inspectFirst: options.continuityInspectFirst,
       resumeNote: options.continuityResumeNote,
+      taskId: options.task,
     });
     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 });
+    const result = await runReconcileContinuity({ target, packageRoot, taskId: options.task });
     console.log(options.json ? JSON.stringify(result, null, 2) : formatReconcileContinuityResult(result));
     return 0;
   },
   "clear-continuity": async ({ target, options }) => {
-    const result = await runClearContinuity({ target });
+    const result = await runClearContinuity({ target, taskId: options.task });
     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 });
+    const result = await runPrepareCompletion({ target, packageRoot, taskId: options.task });
     console.log(options.json ? JSON.stringify(result, null, 2) : formatPrepareCompletionResult(result));
     return 0;
   },
@@ -613,6 +460,7 @@ export const COMMAND_HANDLERS = Object.freeze({
       requirement: options.checkRequirement,
       argv: options.commandArgv,
       details: options.checkDetails ?? undefined,
+      taskId: options.task,
     });
     console.log(options.json ? JSON.stringify(result, null, 2) : formatRunCheckResult(result));
     return result.check.status === "passed" ? 0 : 1;
@@ -632,6 +480,7 @@ export const COMMAND_HANDLERS = Object.freeze({
       details: options.checkDetails ?? undefined,
       executionRef: options.checkExecutionRef ?? undefined,
       provenance: options.checkProvenance ?? undefined,
+      taskId: options.task,
     });
     console.log(options.json ? JSON.stringify(result, null, 2) : formatRecordCheckResult(result));
     return 0;
@@ -646,27 +495,28 @@ export const COMMAND_HANDLERS = Object.freeze({
       source: options.checkSource ?? options.checkCommand,
       result: options.checkResult,
       details: options.checkDetails ?? undefined,
+      taskId: options.task,
     });
     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 });
+    const result = await runComplete({ target, packageRoot, strict: options.strict, taskId: options.task });
     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 });
+    const result = await runAudit({ target, packageRoot, strict: options.strict, taskId: options.task });
     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 });
+    const result = await runReport({ target, packageRoot, strict: options.strict, taskId: options.task });
     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 });
+    const result = await runPolicy({ target, packageRoot, name: options.policy, taskId: options.task });
     console.log(options.json ? JSON.stringify(result, null, 2) : formatPolicyResult(result));
     return 0;
   },
@@ -676,7 +526,7 @@ export const COMMAND_HANDLERS = Object.freeze({
     return 0;
   },
   inspect: async ({ target, packageRoot, options }) => {
-    const result = await inspectTarget({ target, packageRoot, contractFile: options.contractFile });
+    const result = await inspectTarget({ target, packageRoot, contractFile: options.contractFile, taskId: options.task });
     console.log(options.json ? JSON.stringify(result, null, 2) : formatInspectResult(result));
     return result.ok ? 0 : 1;
   },
@@ -689,32 +539,74 @@ export const COMMAND_HANDLERS = Object.freeze({
     const result = await runValidateProtocol({
       target,
       packageRoot,
-      stateFile: options.stateFile ?? ARTIFACT_PATHS.state,
-      receiptFile: options.receiptFile ?? ARTIFACT_PATHS.receipt,
-      routeFile: options.routeFile ?? ARTIFACT_PATHS.route,
+      stateFile: options.stateFile,
+      receiptFile: options.receiptFile,
+      routeFile: options.routeFile,
       contractFile: options.contractFile,
       continuityFile: options.continuityFile,
       taskBriefFiles: options.taskBriefFiles,
       delegatedResultFiles: options.delegatedResultFiles,
+      taskId: options.task,
     });
     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 });
+    const result = await runStatus({ target, packageRoot, contractFile: options.contractFile, taskId: options.task });
     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 });
+    const result = await runValidateState({ target, packageRoot, taskId: options.task });
     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 });
+    const result = await runClearState({ target, taskId: options.task });
     console.log(options.json ? JSON.stringify(result, null, 2) : formatClearStateResult(result));
     return 0;
   },
+  "task-create": async ({ target, packageRoot, options }) => {
+    const result = await runTaskCreate({
+      target,
+      packageRoot,
+      taskId: options.task,
+      claims: options.claims,
+      contractFile: options.contractFile,
+    });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatTaskCreateResult(result));
+    return 0;
+  },
+  "task-list": async ({ target, packageRoot, options }) => {
+    const result = await runTaskList({ target, packageRoot });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatTaskListResult(result));
+    return 0;
+  },
+  "task-show": async ({ target, packageRoot, options }) => {
+    const result = await runTaskShow({ target, packageRoot, taskId: options.task });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatTaskShowResult(result));
+    return 0;
+  },
+  "task-scope": async ({ target, packageRoot, options }) => {
+    const result = await runTaskScope({
+      target,
+      packageRoot,
+      taskId: options.task,
+      claims: options.claims,
+    });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatTaskScopeResult(result));
+    return 0;
+  },
+  "task-migrate": async ({ target, packageRoot, options }) => {
+    const result = await runTaskMigrate({ target, packageRoot, dryRun: options.dryRun });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatTaskMigrateResult(result));
+    return 0;
+  },
+  "task-unlock": async ({ target, packageRoot, options }) => {
+    const result = await runTaskUnlock({ target, packageRoot, taskId: options.task, force: options.force });
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatTaskUnlockResult(result));
+    return 0;
+  },
   update: async ({ target, packageRoot, packageVersion, options }) => {
     const result = await runUpdate({ target, dryRun: options.dryRun, packageRoot, packageVersion });
     printActions(result.actions);