@xenonbyte/da-vinci-workflow 0.1.25 → 0.2.1

package/lib/cli.js

@@ -16,7 +16,10 @@ const {
   writePenFromPayloadFiles,
   snapshotPenFile,
   ensurePenFile,
-  comparePenSync
+  comparePenSync,
+  comparePenBaselineAlignment,
+  formatPenBaselineAlignmentReport,
+  syncPenSource
 } = require("./pen-persistence");
 const {
   acquirePencilLock,
@@ -42,37 +45,349 @@ const {
   loadIconAliases,
   expandQueryWithAliases
 } = require("./icon-aliases");
+const { sleepSync } = require("./utils");
 const {
   runDesignSupervisorReview,
   formatDesignSupervisorReviewReport
 } = require("./supervisor-review");
+const {
+  bootstrapProjectArtifacts,
+  formatBootstrapProjectReport
+} = require("./workflow-bootstrap");
+const {
+  deriveWorkflowStatus,
+  formatWorkflowStatusReport,
+  formatNextStepReport
+} = require("./workflow-state");
+const { lintRuntimeSpecs, formatLintSpecReport } = require("./lint-spec");
+const { runScopeCheck, formatScopeCheckReport } = require("./scope-check");
+const { lintTasks, formatLintTasksReport } = require("./lint-tasks");
+const { lintBindings, formatLintBindingsReport } = require("./lint-bindings");
+const { generatePlanningSidecars, formatGenerateSidecarsReport } = require("./sidecars");
+const {
+  verifyBindings,
+  verifyImplementation,
+  verifyStructure,
+  verifyCoverage,
+  formatVerifyReport
+} = require("./verify");
+const { diffSpec, formatDiffSpecReport } = require("./diff-spec");
+const { scaffoldFromBindings, formatScaffoldReport } = require("./scaffold");
+const { writeExecutionSignal } = require("./execution-signals");
+
+const DEFAULT_MAX_PREFLIGHT_STDIN_BYTES = 1024 * 1024;
+const DEFAULT_MAX_STDIN_TRANSIENT_RETRIES = 2000;
+const DEFAULT_MAX_STDIN_TRANSIENT_BACKOFF_MS = 25;
+const OPTION_FLAGS_WITH_VALUES = new Set([
+  "--home",
+  "--platform",
+  "--project",
+  "--mode",
+  "--change",
+  "--query",
+  "--baseline",
+  "--prefer-source",
+  "--family",
+  "--top",
+  "--catalog",
+  "--aliases",
+  "--pencil-design",
+  "--status",
+  "--source",
+  "--executed-reviewers",
+  "--codex-bin",
+  "--max-images",
+  "--review-timeout-ms",
+  "--review-concurrency",
+  "--review-retries",
+  "--review-retry-delay-ms",
+  "--review-retry-max-delay-ms",
+  "--issue-list",
+  "--revision-outcome",
+  "--timeout-ms",
+  "--ops-file",
+  "--input",
+  "--output",
+  "--from",
+  "--to",
+  "--pen",
+  "--nodes-file",
+  "--variables-file",
+  "--version",
+  "--owner",
+  "--wait-ms"
+]);
+
+const HELP_OPTION_SPECS = [
+  { flag: "--platform <value>", description: "codex, claude, gemini, or all" },
+  { flag: "--home <path>", description: "override HOME for installation targets" },
+  { flag: "--project <path>", description: "override project path for audit" },
+  {
+    flag: "--catalog <path>",
+    description: "icon catalog path for icon-search/icon-sync (default: ~/.da-vinci/icon-catalog.json)"
+  },
+  {
+    flag: "--aliases <path>",
+    description: "icon alias mapping file for icon-search (default: ~/.da-vinci/icon-aliases.json)"
+  },
+  {
+    flag: "--pencil-design <path>",
+    description: "explicit pencil-design.md path for supervisor-review"
+  },
+  { flag: "--query <text>", description: "icon-search query text" },
+  {
+    flag: "--baseline <path>",
+    description: "comparison .pen path for multi-source baseline alignment checks (repeatable, supports comma-separated values)"
+  },
+  {
+    flag: "--prefer-source <path>",
+    description: "explicit baseline source of truth when compared .pen hashes diverge"
+  },
+  {
+    flag: "--sync-preferred-source",
+    description: "copy `--prefer-source` into project `--pen` when hashes diverge (begin command only)"
+  },
+  {
+    flag: "--family <value>",
+    description: "icon-search family filter: all, material, rounded, outlined, sharp, lucide, feather, phosphor"
+  },
+  { flag: "--status <value>", description: "PASS, WARN, or BLOCK for supervisor-review" },
+  { flag: "--source <value>", description: "review source: skill, manual, inferred" },
+  { flag: "--executed-reviewers <csv>", description: "reviewer skills that executed this review" },
+  { flag: "--run-reviewers", description: "execute configured reviewer skills through codex exec" },
+  {
+    flag: "--review-concurrency <value>",
+    description: "max parallel reviewer executions (default 2)"
+  },
+  {
+    flag: "--review-retries <value>",
+    description: "retry count per reviewer before failing (default 1)"
+  },
+  {
+    flag: "--review-retry-delay-ms <value>",
+    description: "initial retry delay in milliseconds (default 400, exponential backoff)"
+  },
+  {
+    flag: "--review-retry-max-delay-ms <value>",
+    description: "cap reviewer retry backoff delay in milliseconds (default 5000)"
+  },
+  {
+    flag: "--codex-bin <path>",
+    description: "codex executable path for --run-reviewers (default: codex)"
+  },
+  { flag: "--max-images <value>", description: "max screenshots attached to reviewer runs (default 6)" },
+  { flag: "--review-timeout-ms <value>", description: "timeout per reviewer run in milliseconds" },
+  { flag: "--issue-list <text>", description: "supervisor-review issue summary" },
+  { flag: "--revision-outcome <text>", description: "supervisor-review revision result summary" },
+  { flag: "--top <value>", description: "icon-search result count (1-50, default 8)" },
+  { flag: "--timeout-ms <value>", description: "network timeout for icon-sync requests" },
+  {
+    flag: "--strict",
+    description: "enable strict failure mode for commands that support advisory defaults (for example icon-sync, lint-spec)"
+  },
+  {
+    flag: "--continue-on-error",
+    description: "print BLOCK/FAIL command results without throwing process errors"
+  },
+  { flag: "--json", description: "print structured JSON output when supported by the command" },
+  { flag: "--pen <path>", description: "registered .pen path for sync checks" },
+  {
+    flag: "--from <path>",
+    description: "source path for sync-pen-source, or baseline sidecars directory for diff-spec"
+  },
+  { flag: "--to <path>", description: "destination .pen path for sync-pen-source" },
+  { flag: "--ops-file <path>", description: "Pencil batch operations file for preflight" },
+  { flag: "--input <path>", description: "input .pen file for snapshot-pen" },
+  { flag: "--output <path>", description: "output .pen file for write-pen or snapshot-pen" },
+  { flag: "--nodes-file <path>", description: "JSON payload from batch_get for write-pen" },
+  { flag: "--variables-file <path>", description: "JSON payload from get_variables for write-pen" },
+  { flag: "--verify-open", description: "reopen the written .pen with Pencil after writing" },
+  { flag: "--version <value>", description: "explicit .pen version when writing from MCP payloads" },
+  { flag: "--mode <value>", description: "integrity or completion" },
+  { flag: "--change <id>", description: "scope completion audit to one change id" },
+  { flag: "--wait-ms <value>", description: "wait for the global Pencil lock before failing" },
+  { flag: "--owner <value>", description: "human-readable lock owner label" },
+  { flag: "--force", description: "overwrite bootstrap placeholders or force commands that explicitly support it" }
+];
+
+function readLimitedStdin(maxBytes = DEFAULT_MAX_PREFLIGHT_STDIN_BYTES, options = {}) {
+  const limit =
+    Number.isFinite(Number(maxBytes)) && Number(maxBytes) > 0
+      ? Number(maxBytes)
+      : DEFAULT_MAX_PREFLIGHT_STDIN_BYTES;
+  const maxTransientRetries =
+    Number.isFinite(Number(options.maxTransientRetries)) && Number(options.maxTransientRetries) >= 0
+      ? Number(options.maxTransientRetries)
+      : DEFAULT_MAX_STDIN_TRANSIENT_RETRIES;
+  const maxBackoffMs =
+    Number.isFinite(Number(options.maxBackoffMs)) && Number(options.maxBackoffMs) > 0
+      ? Number(options.maxBackoffMs)
+      : DEFAULT_MAX_STDIN_TRANSIENT_BACKOFF_MS;
+  const chunks = [];
+  let totalBytes = 0;
+  let transientReadRetries = 0;
+
+  while (true) {
+    const chunk = Buffer.allocUnsafe(64 * 1024);
+    let bytesRead;
+    try {
+      bytesRead = fs.readSync(0, chunk, 0, chunk.length, null);
+    } catch (error) {
+      if (error && (error.code === "EAGAIN" || error.code === "EINTR")) {
+        transientReadRetries += 1;
+        if (transientReadRetries > maxTransientRetries) {
+          throw new Error(
+            `Unable to read stdin after ${transientReadRetries} transient retry attempts (${error.code}).`
+          );
+        }
+        sleepSyncMs(Math.min(5 * transientReadRetries, maxBackoffMs));
+        continue;
+      }
+      throw error;
+    }
+    transientReadRetries = 0;
+    if (bytesRead === 0) {
+      break;
+    }
+
+    totalBytes += bytesRead;
+    if (totalBytes > limit) {
+      throw new Error(
+        `Piped stdin payload exceeds ${limit} bytes. Use \`--ops-file <path>\` for larger preflight batches.`
+      );
+    }
+
+    chunks.push(Buffer.from(chunk.subarray(0, bytesRead)));
+  }
+
+  return Buffer.concat(chunks, totalBytes).toString("utf8");
+}
+
+function sleepSyncMs(durationMs) {
+  sleepSync(durationMs, "back off stdin retries");
+}
+
+function collectOptionEntries(args, name) {
+  const entries = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === name) {
+      const next = args[index + 1];
+      if (next === undefined || String(next).startsWith("-")) {
+        entries.push({
+          form: "split",
+          hasValue: false,
+          value: ""
+        });
+        continue;
+      }
+      entries.push({
+        form: "split",
+        hasValue: true,
+        value: next
+      });
+      index += 1;
+      continue;
+    }
+
+    if (String(arg).startsWith(`${name}=`)) {
+      entries.push({
+        form: "inline",
+        hasValue: true,
+        value: String(arg).slice(name.length + 1)
+      });
+    }
+  }
+
+  return entries;
+}
 
 function getOption(args, name) {
-  const direct = args.find((arg) => arg.startsWith(`${name}=`));
-  if (direct) {
-    return direct.slice(name.length + 1);
+  const entries = collectOptionEntries(args, name);
+  if (entries.length === 0) {
+    return undefined;
   }
 
-  const index = args.indexOf(name);
-  if (index >= 0) {
-    return args[index + 1];
+  const values = entries.filter((entry) => entry.hasValue).map((entry) => String(entry.value));
+  if (values.length === 0) {
+    return undefined;
   }
+  const uniqueValues = Array.from(new Set(values));
+  if (uniqueValues.length > 1) {
+    throw new Error(
+      `\`${name}\` was provided with conflicting values (${uniqueValues.join(", ")}). ` +
+        "Use a single value format (`--flag=value` or `--flag value`)."
+    );
+  }
+
+  return values[values.length - 1];
+}
 
-  return undefined;
+function getOptionValues(args, name) {
+  return collectOptionEntries(args, name)
+    .filter((entry) => entry.hasValue)
+    .map((entry) => entry.value);
 }
 
-function getPositionalArgs(args, optionsWithValues = []) {
+function shouldContinueOnError(args) {
+  return Array.isArray(args) && args.includes("--continue-on-error");
+}
+
+function emitOrThrowOnStatus(status, blockedStatuses, output, continueOnError) {
+  if (!Array.isArray(blockedStatuses) || !blockedStatuses.includes(status)) {
+    return false;
+  }
+  if (continueOnError) {
+    console.log(output);
+    return true;
+  }
+  throw new Error(output);
+}
+
+function getIntegerOption(args, name, options = {}) {
+  const raw = getOption(args, name);
+  if (raw === undefined) {
+    return undefined;
+  }
+
+  const parsed = Number.parseInt(String(raw), 10);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`\`${name}\` must be an integer.`);
+  }
+
+  if (Number.isFinite(options.min) && parsed < options.min) {
+    throw new Error(`\`${name}\` must be >= ${options.min}.`);
+  }
+  if (Number.isFinite(options.max) && parsed > options.max) {
+    throw new Error(`\`${name}\` must be <= ${options.max}.`);
+  }
+  return parsed;
+}
+
+function getCommaSeparatedOptionValues(args, name) {
+  return getOptionValues(args, name)
+    .flatMap((value) => String(value || "").split(","))
+    .map((value) => value.trim())
+    .filter(Boolean);
+}
+
+function getPositionalArgs(args, optionsWithValues = OPTION_FLAGS_WITH_VALUES) {
+  const optionNames =
+    optionsWithValues instanceof Set ? Array.from(optionsWithValues) : [...optionsWithValues];
+  const optionsWithValuesSet =
+    optionsWithValues instanceof Set ? optionsWithValues : new Set(optionsWithValues);
   const positional = [];
 
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
 
-    if (optionsWithValues.includes(arg)) {
+    if (optionsWithValuesSet.has(arg)) {
       index += 1;
       continue;
     }
 
-    if (optionsWithValues.some((name) => arg.startsWith(`${name}=`))) {
+    if (optionNames.some((name) => String(arg).startsWith(`${name}=`))) {
       continue;
     }
 
@@ -87,16 +402,68 @@ function getPositionalArgs(args, optionsWithValues = []) {
 }
 
 function formatStatus(status) {
-  return [
+  const lines = [
     `Da Vinci v${status.version}`,
     `Home: ${status.homeDir}`,
     `Codex: prompt=${status.codex.prompt ? "yes" : "no"} skill=${status.codex.skill ? "yes" : "no"}`,
     `Claude: command=${status.claude.command ? "yes" : "no"} actions=${status.claude.actionSet ? "yes" : "no"}`,
     `Gemini: command=${status.gemini.command ? "yes" : "no"} actions=${status.gemini.actionSet ? "yes" : "no"}`
-  ].join("\n");
+  ];
+
+  appendStatusIssues(lines, "codex prompt", status.codex.promptMissing, status.codex.promptMismatched, status.codex.promptUnreadable);
+  appendStatusIssues(lines, "codex skill", status.codex.skillMissing, status.codex.skillMismatched, status.codex.skillUnreadable);
+  appendStatusIssues(lines, "claude command", status.claude.commandMissing, status.claude.commandMismatched, status.claude.commandUnreadable);
+  appendStatusIssues(lines, "claude actions", status.claude.actionSetMissing, status.claude.actionSetMismatched, status.claude.actionSetUnreadable);
+  appendStatusIssues(lines, "gemini command", status.gemini.commandMissing, status.gemini.commandMismatched, status.gemini.commandUnreadable);
+  appendStatusIssues(lines, "gemini actions", status.gemini.actionSetMissing, status.gemini.actionSetMismatched, status.gemini.actionSetUnreadable);
+
+  return lines.join("\n");
+}
+
+function appendStatusIssues(lines, label, missing = [], mismatched = [], unreadable = []) {
+  if (missing.length > 0) {
+    lines.push(`  ${label} missing: ${missing.join(", ")}`);
+  }
+  if (mismatched.length > 0) {
+    lines.push(`  ${label} stale/mismatched: ${mismatched.join(", ")}`);
+  }
+  if (unreadable.length > 0) {
+    lines.push(`  ${label} unreadable: ${unreadable.join(", ")}`);
+  }
+}
+
+function persistExecutionSignal(projectPath, changeId, surface, result, strict = false) {
+  try {
+    writeExecutionSignal(projectPath, {
+      changeId: changeId || "global",
+      surface,
+      status: result.status,
+      advisory: strict ? false : true,
+      strict,
+      failures: result.failures || [],
+      warnings: result.warnings || [],
+      notes: result.notes || []
+    });
+  } catch (error) {
+    // Signals are advisory metadata and should not break command execution.
+    const code = error && error.code ? String(error.code).toUpperCase() : "";
+    if (code === "EACCES" || code === "ENOSPC") {
+      return;
+    }
+
+    const message = error && error.message ? error.message : String(error);
+    console.error(
+      `Warning: failed to persist execution signal (${surface}) for change ${changeId || "global"}: ${message}`
+    );
+  }
 }
 
 function printHelp() {
+  const optionLines = HELP_OPTION_SPECS.map((optionSpec) => {
+    const paddedFlag = optionSpec.flag.padEnd(30, " ");
+    return `  ${paddedFlag}${optionSpec.description}`;
+  });
+
   console.log(
     [
       "Da Vinci CLI",
@@ -105,104 +472,437 @@ function printHelp() {
       "  da-vinci install --platform codex,claude,gemini",
       "  da-vinci uninstall --platform codex,claude,gemini",
       "  da-vinci status",
+      "  da-vinci workflow-status [--project <path>] [--change <id>] [--json]",
+      "  da-vinci next-step [--project <path>] [--change <id>] [--json]",
+      "  da-vinci lint-spec [--project <path>] [--change <id>] [--strict] [--json]",
+      "  da-vinci scope-check [--project <path>] [--change <id>] [--strict] [--json]",
+      "  da-vinci lint-tasks [--project <path>] [--change <id>] [--strict] [--json]",
+      "  da-vinci lint-bindings [--project <path>] [--change <id>] [--strict] [--json]",
+      "  da-vinci generate-sidecars [--project <path>] [--change <id>] [--json]",
+      "  da-vinci verify-bindings [--project <path>] [--change <id>] [--strict] [--json]",
+      "  da-vinci verify-implementation [--project <path>] [--change <id>] [--strict] [--json]",
+      "  da-vinci verify-structure [--project <path>] [--change <id>] [--strict] [--json]",
+      "  da-vinci verify-coverage [--project <path>] [--change <id>] [--strict] [--json]",
+      "  da-vinci diff-spec [--project <path>] [--change <id>] [--from <sidecars-dir>] [--json]",
+      "  da-vinci scaffold [--project <path>] [--change <id>] [--output <path>] [--json]",
       "  da-vinci validate-assets",
+      "  da-vinci bootstrap-project --project <path> [--change <id>] [--force]",
       "  da-vinci audit [project-path]",
       "  da-vinci icon-sync [--output <path>] [--timeout-ms <value>] [--strict]",
       "  da-vinci icon-search --query <text> [--family <value>] [--top <value>] [--catalog <path>] [--aliases <path>] [--json]",
-      "  da-vinci supervisor-review --project <path> --change <id> [--run-reviewers] [--review-concurrency <value>] [--review-retries <value>] [--review-retry-delay-ms <value>] [--source <skill|manual|inferred>] [--executed-reviewers <csv>] [--status <PASS|WARN|BLOCK>] [--issue-list <text>] [--revision-outcome <text>] [--write] [--json]",
+      "  da-vinci supervisor-review --project <path> --change <id> [--run-reviewers] [--review-concurrency <value>] [--review-retries <value>] [--review-retry-delay-ms <value>] [--review-retry-max-delay-ms <value>] [--source <skill|manual|inferred>] [--executed-reviewers <csv>] [--status <PASS|WARN|BLOCK>] [--issue-list <text>] [--revision-outcome <text>] [--write] [--json]",
       "  da-vinci preflight-pencil --ops-file <path>",
       "  da-vinci ensure-pen --output <path>",
       "  da-vinci write-pen --output <path> --nodes-file <path> [--variables-file <path>]",
       "  da-vinci check-pen-sync --pen <path> --nodes-file <path> [--variables-file <path>]",
+      "  da-vinci check-pen-baseline --pen <path> --baseline <path>[,<path>...] [--baseline <path>] [--prefer-source <path>]",
+      "  da-vinci sync-pen-source --from <path> --to <path>",
       "  da-vinci snapshot-pen --input <path> --output <path>",
       "  da-vinci pencil-lock acquire --project <path>",
       "  da-vinci pencil-lock release --project <path>",
       "  da-vinci pencil-lock status",
-      "  da-vinci pencil-session begin --project <path> --pen <path>",
+      "  da-vinci pencil-session begin --project <path> --pen <path> [--baseline <path>[,<path>...]] [--prefer-source <path>] [--sync-preferred-source]",
       "  da-vinci pencil-session persist --project <path> --pen <path> --nodes-file <path> [--variables-file <path>]",
       "  da-vinci pencil-session end --project <path> --pen <path> --nodes-file <path> [--variables-file <path>]",
       "  da-vinci pencil-session status --project <path>",
       "  da-vinci --version",
       "",
       "Options:",
-      "  --platform <value>   codex, claude, gemini, or all",
-      "  --home <path>        override HOME for installation targets",
-      "  --project <path>     override project path for audit",
-      "  --catalog <path>     icon catalog path for icon-search/icon-sync (default: ~/.da-vinci/icon-catalog.json)",
-      "  --aliases <path>     icon alias mapping file for icon-search (default: ~/.da-vinci/icon-aliases.json)",
-      "  --pencil-design <path> explicit pencil-design.md path for supervisor-review",
-      "  --query <text>       icon-search query text",
-      "  --family <value>     icon-search family filter: all, material, rounded, outlined, sharp, lucide, feather, phosphor",
-      "  --status <value>     PASS, WARN, or BLOCK for supervisor-review",
-      "  --source <value>     review source: skill, manual, inferred",
-      "  --executed-reviewers <csv> reviewer skills that executed this review",
-      "  --run-reviewers      execute configured reviewer skills through codex exec",
-      "  --review-concurrency <value> max parallel reviewer executions (default 2)",
-      "  --review-retries <value> retry count per reviewer before failing (default 1)",
-      "  --review-retry-delay-ms <value> initial retry delay in milliseconds (default 400, exponential backoff)",
-      "  --codex-bin <path>   codex executable path for --run-reviewers (default: codex)",
-      "  --max-images <value> max screenshots attached to reviewer runs (default 6)",
-      "  --review-timeout-ms <value> timeout per reviewer run in milliseconds",
-      "  --issue-list <text>  supervisor-review issue summary",
-      "  --revision-outcome <text> supervisor-review revision result summary",
-      "  --top <value>        icon-search result count (1-50, default 8)",
-      "  --timeout-ms <value> network timeout for icon-sync requests",
-      "  --strict             fail icon-sync when any upstream source request fails",
-      "  --json               print structured JSON for icon-search",
-      "  --pen <path>         registered .pen path for sync checks",
-      "  --ops-file <path>    Pencil batch operations file for preflight",
-      "  --input <path>       input .pen file for snapshot-pen",
-      "  --output <path>      output .pen file for write-pen or snapshot-pen",
-      "  --nodes-file <path>  JSON payload from batch_get for write-pen",
-      "  --variables-file <path> JSON payload from get_variables for write-pen",
-      "  --verify-open        reopen the written .pen with Pencil after writing",
-      "  --version <value>    explicit .pen version when writing from MCP payloads",
-      "  --mode <value>       integrity or completion",
-      "  --change <id>        scope completion audit to one change id",
-      "  --wait-ms <value>    wait for the global Pencil lock before failing",
-      "  --owner <value>      human-readable lock owner label",
-      "  --force              force a lock release held by another project"
+      ...optionLines
     ].join("\n")
   );
 }
 
-async function runCli(argv) {
-  const [command] = argv;
-  const homeDir = getOption(argv, "--home");
-  const positionalArgs = getPositionalArgs(argv.slice(1), [
+async function handleIconSearchCommand(argv, homeDir) {
+  const family = getOption(argv, "--family") || "all";
+  const top = getIntegerOption(argv, "--top", { min: 1, max: 50 });
+  const queryOption = getOption(argv, "--query");
+  const catalogPath = getOption(argv, "--catalog");
+  const aliasesPath = getOption(argv, "--aliases");
+  const iconPositional = getPositionalArgs(argv.slice(1), [
     "--home",
-    "--platform",
-    "--project",
-    "--mode",
-    "--change",
     "--query",
     "--family",
     "--top",
     "--catalog",
-    "--aliases",
-    "--pencil-design",
-    "--status",
-    "--source",
-    "--executed-reviewers",
-    "--codex-bin",
-    "--max-images",
-    "--review-timeout-ms",
-    "--review-concurrency",
-    "--review-retries",
-    "--review-retry-delay-ms",
-    "--issue-list",
-    "--revision-outcome",
-    "--timeout-ms",
-    "--ops-file",
-    "--input",
-    "--output",
+    "--aliases"
+  ]);
+  const query = queryOption || iconPositional.join(" ").trim();
+
+  if (!query) {
+    throw new Error("`icon-search` requires `--query <text>` or positional query text.");
+  }
+
+  let loadedCatalog = null;
+  let loadedCatalogPath = null;
+  let catalogLoadError = null;
+  let loadedAliases = null;
+  let loadedAliasesPath = null;
+  let aliasesLoadError = null;
+  let aliasExpansion = {
+    extraTokens: [],
+    matchedAliases: []
+  };
+
+  try {
+    const loaded = loadIconCatalog({
+      catalogPath,
+      homeDir
+    });
+    loadedCatalog = loaded.catalog;
+    loadedCatalogPath = loaded.catalogPath;
+  } catch (error) {
+    catalogLoadError = error.message || String(error);
+  }
+
+  try {
+    const loaded = loadIconAliases({
+      aliasPath: aliasesPath,
+      homeDir
+    });
+    loadedAliases = loaded;
+    loadedAliasesPath = loaded.aliasPath;
+    aliasExpansion = expandQueryWithAliases(query, loaded.aliases);
+  } catch (error) {
+    aliasesLoadError = error.message || String(error);
+  }
+
+  const result = searchIconLibrary(query, {
+    family,
+    top,
+    catalog: loadedCatalog ? loadedCatalog.icons : [],
+    extraQueryTokens: aliasExpansion.extraTokens
+  });
+  const jsonOutput = argv.includes("--json");
+
+  const resultWithMeta = {
+    ...result,
+    catalog: {
+      path: loadedCatalogPath || "(unresolved)",
+      loaded: Boolean(loadedCatalog),
+      iconCount: loadedCatalog ? loadedCatalog.iconCount : 0,
+      generatedAt: loadedCatalog ? loadedCatalog.generatedAt : null,
+      error: catalogLoadError
+    },
+    aliases: {
+      path: loadedAliasesPath || "(unresolved)",
+      loaded: loadedAliases ? Boolean(loadedAliases.loaded) : false,
+      available: Boolean(loadedAliases),
+      source: loadedAliases ? loadedAliases.source : null,
+      matched: aliasExpansion.matchedAliases.length,
+      extraTokens: aliasExpansion.extraTokens,
+      error: aliasesLoadError
+    }
+  };
+
+  if (jsonOutput) {
+    console.log(JSON.stringify(resultWithMeta, null, 2));
+    return;
+  }
+
+  if (resultWithMeta.catalog.loaded) {
+    console.log(
+      `Icon catalog: ${resultWithMeta.catalog.path} (${resultWithMeta.catalog.iconCount} icons, ${resultWithMeta.catalog.generatedAt})`
+    );
+  } else if (resultWithMeta.catalog.error) {
+    console.log(
+      `Icon catalog: ${resultWithMeta.catalog.path} (load failed: ${resultWithMeta.catalog.error}; using built-in fallback index)`
+    );
+  } else {
+    console.log(
+      `Icon catalog: ${resultWithMeta.catalog.path} (not found; using built-in fallback index; run \`da-vinci icon-sync\`)`
+    );
+  }
+
+  if (resultWithMeta.aliases.available) {
+    console.log(
+      `Icon aliases: ${resultWithMeta.aliases.path} (${resultWithMeta.aliases.source}, matched ${resultWithMeta.aliases.matched})`
+    );
+  } else if (resultWithMeta.aliases.error) {
+    console.log(
+      `Icon aliases: ${resultWithMeta.aliases.path} (load failed: ${resultWithMeta.aliases.error})`
+    );
+  } else {
+    console.log(
+      `Icon aliases: ${resultWithMeta.aliases.path} (not found; using built-in defaults only)`
+    );
+  }
+
+  console.log(formatIconSearchReport(result));
+}
+
+async function handleSupervisorReviewCommand(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    console.log(
+      [
+        "da-vinci supervisor-review",
+        "",
+        "Usage:",
+        "  da-vinci supervisor-review --project <path> --change <id> [--run-reviewers] [--review-concurrency <value>] [--review-retries <value>] [--review-retry-delay-ms <value>] [--review-retry-max-delay-ms <value>] [--source <skill|manual|inferred>] [--executed-reviewers <csv>] [--status <PASS|WARN|BLOCK>] [--issue-list <text>] [--revision-outcome <text>] [--write] [--json]",
+        "  da-vinci supervisor-review --project <path> --pencil-design <path> [--run-reviewers] [--review-concurrency <value>] [--review-retries <value>] [--review-retry-delay-ms <value>] [--review-retry-max-delay-ms <value>] [--source <skill|manual|inferred>] [--executed-reviewers <csv>] [--status <PASS|WARN|BLOCK>] [--issue-list <text>] [--revision-outcome <text>] [--write] [--json]",
+        "",
+        "Notes:",
+        "  - omit --status to infer a conservative review status from current design artifacts",
+        "  - use --run-reviewers to execute configured reviewer skills automatically via codex exec",
+        "  - `design-supervisor review` is a compatibility alias for this command"
+      ].join("\n")
+    );
+    return;
+  }
+
+  const projectPath = getOption(argv, "--project") || process.cwd();
+  const changeId = getOption(argv, "--change");
+  const pencilDesignPath = getOption(argv, "--pencil-design");
+  const status = getOption(argv, "--status");
+  const source = getOption(argv, "--source");
+  const executedReviewers = getOption(argv, "--executed-reviewers");
+  const codexBin = getOption(argv, "--codex-bin");
+  const maxImages = getIntegerOption(argv, "--max-images", { min: 0 });
+  const reviewerTimeoutMs = getIntegerOption(argv, "--review-timeout-ms", { min: 1 });
+  const reviewConcurrency = getIntegerOption(argv, "--review-concurrency", { min: 1 });
+  const reviewerRetries = getIntegerOption(argv, "--review-retries", { min: 0 });
+  const reviewerRetryDelayMs = getIntegerOption(argv, "--review-retry-delay-ms", { min: 0 });
+  const reviewerRetryMaxDelayMs = getIntegerOption(argv, "--review-retry-max-delay-ms", {
+    min: 0
+  });
+  const issueList = getOption(argv, "--issue-list");
+  const revisionOutcome = getOption(argv, "--revision-outcome");
+  const write = argv.includes("--write");
+  const acceptWarn = argv.includes("--accept-warn");
+  const runReviewers = argv.includes("--run-reviewers");
+  const jsonOutput = argv.includes("--json");
+
+  const result = await runDesignSupervisorReview({
+    projectPath,
+    changeId,
+    pencilDesignPath,
+    status,
+    source,
+    executedReviewers,
+    codexBin,
+    maxImages,
+    reviewerTimeoutMs,
+    reviewConcurrency,
+    reviewerRetries,
+    reviewerRetryDelayMs,
+    reviewerRetryMaxDelayMs,
+    issueList,
+    revisionOutcome,
+    write,
+    acceptWarn,
+    runReviewers
+  });
+
+  if (jsonOutput) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(formatDesignSupervisorReviewReport(result));
+}
+
+function handlePencilLockCommand(argv, homeDir) {
+  const subcommand = getPositionalArgs(argv.slice(1), [
+    "--home",
+    "--project",
+    "--owner",
+    "--wait-ms"
+  ])[0];
+  const projectPath = getOption(argv, "--project") || process.cwd();
+  const owner = getOption(argv, "--owner");
+  const waitMs = getIntegerOption(argv, "--wait-ms", { min: 0 });
+  const force = argv.includes("--force");
+
+  if (!subcommand || ["acquire", "release", "status"].includes(subcommand) === false) {
+    throw new Error("`pencil-lock` requires one of: acquire, release, status.");
+  }
+
+  if (subcommand === "acquire") {
+    const result = acquirePencilLock({
+      projectPath,
+      owner,
+      waitMs,
+      homeDir
+    });
+    console.log(`${result.alreadyHeld ? "Reused" : "Acquired"} Pencil lock at ${result.lockPath}`);
+    console.log(`Project: ${result.lock.projectPath}`);
+    console.log(`Owner: ${result.lock.owner}`);
+    return;
+  }
+
+  if (subcommand === "release") {
+    const result = releasePencilLock({
+      projectPath,
+      force,
+      homeDir
+    });
+    if (!result.hadLock) {
+      console.log(`No Pencil lock was present at ${result.lockPath}`);
+      return;
+    }
+    console.log(`Released Pencil lock at ${result.lockPath}`);
+    console.log(`Previous project: ${result.lock.projectPath}`);
+    return;
+  }
+
+  const result = getPencilLockStatus({ homeDir });
+  console.log(`Lock path: ${result.lockPath}`);
+  if (!result.lock) {
+    console.log("Status: unlocked");
+    return;
+  }
+  console.log("Status: locked");
+  console.log(`Project: ${result.lock.projectPath}`);
+  console.log(`Owner: ${result.lock.owner}`);
+  console.log(`PID: ${result.lock.pid}`);
+}
+
+function handlePencilSessionCommand(argv, homeDir) {
+  const subcommand = getPositionalArgs(argv.slice(1), [
+    "--home",
+    "--project",
     "--pen",
+    "--baseline",
+    "--prefer-source",
     "--nodes-file",
     "--variables-file",
     "--version",
     "--owner",
     "--wait-ms"
-  ]);
+  ])[0];
+  const projectPath = getOption(argv, "--project") || process.cwd();
+  const penPath = getOption(argv, "--pen");
+  const baselinePaths = getCommaSeparatedOptionValues(argv, "--baseline");
+  const preferredSource = getOption(argv, "--prefer-source");
+  const nodesFile = getOption(argv, "--nodes-file");
+  const variablesFile = getOption(argv, "--variables-file");
+  const version = getOption(argv, "--version");
+  const verifyWithPencil = argv.includes("--verify-open");
+  const owner = getOption(argv, "--owner");
+  const waitMs = getIntegerOption(argv, "--wait-ms", { min: 0 });
+  const force = argv.includes("--force");
+  const syncPreferredSource = argv.includes("--sync-preferred-source");
+
+  if (!subcommand || ["begin", "persist", "end", "status"].includes(subcommand) === false) {
+    throw new Error("`pencil-session` requires one of: begin, persist, end, status.");
+  }
+
+  if (subcommand === "begin") {
+    if (!penPath) {
+      throw new Error("`pencil-session begin` requires `--pen <path>`.");
+    }
+    if (preferredSource && baselinePaths.length === 0) {
+      throw new Error("`pencil-session begin --prefer-source` requires at least one `--baseline <path>`.");
+    }
+    if (syncPreferredSource && !preferredSource) {
+      throw new Error("`pencil-session begin --sync-preferred-source` requires `--prefer-source <path>`.");
+    }
+    if (syncPreferredSource && baselinePaths.length === 0) {
+      throw new Error("`pencil-session begin --sync-preferred-source` requires at least one `--baseline <path>`.");
+    }
+
+    const result = beginPencilSession({
+      projectPath,
+      penPath,
+      baselinePaths,
+      preferredSource,
+      syncPreferredSource,
+      version,
+      verifyWithPencil,
+      owner,
+      waitMs,
+      homeDir
+    });
+
+    console.log(`Began Pencil session for ${result.projectRoot}`);
+    console.log(`Pen path: ${result.penPath}`);
+    console.log(`Session state: ${result.sessionStatePath}`);
+    console.log(`Snapshot hash: ${result.session.lastPersistedHash}`);
+    if (result.session.baselineCheck) {
+      console.log(`Baseline status: ${result.session.baselineCheck.status}`);
+      console.log(`Baseline decision: ${result.session.baselineCheck.decision}`);
+    }
+    if (result.session.baselineSync) {
+      console.log(`Baseline synced from: ${result.session.baselineSync.sourcePath}`);
+    }
+    return;
+  }
+
+  if (subcommand === "persist") {
+    if (!penPath || !nodesFile) {
+      throw new Error("`pencil-session persist` requires `--pen <path>` and `--nodes-file <path>`.");
+    }
+
+    const result = persistPencilSession({
+      projectPath,
+      penPath,
+      nodesFile,
+      variablesFile,
+      version,
+      verifyWithPencil,
+      homeDir
+    });
+
+    console.log(`Persisted Pencil session for ${result.projectRoot}`);
+    console.log(`Pen path: ${result.penPath}`);
+    console.log(`Session state: ${result.sessionStatePath}`);
+    console.log(`Snapshot hash: ${result.session.lastPersistedHash}`);
+    console.log(`In sync: ${result.syncResult.inSync ? "yes" : "no"}`);
+    return;
+  }
+
+  if (subcommand === "end") {
+    if (!penPath) {
+      throw new Error("`pencil-session end` requires `--pen <path>`.");
+    }
+    if (!nodesFile && !force) {
+      throw new Error(
+        "`pencil-session end` requires `--nodes-file <path>` (and `--variables-file <path>` when available). Use `--force` only for emergency lock release."
+      );
+    }
+
+    const result = endPencilSession({
+      projectPath,
+      penPath,
+      nodesFile,
+      variablesFile,
+      version,
+      homeDir,
+      force
+    });
+
+    console.log(`Ended Pencil session for ${result.projectRoot}`);
+    console.log(`Pen path: ${result.penPath}`);
+    console.log(`Session state: ${result.sessionStatePath}`);
+    console.log(`Final status: ${result.session.status}`);
+    if (result.syncResult) {
+      console.log(`Final sync verified: ${result.syncResult.inSync ? "yes" : "no"}`);
+    } else if (force) {
+      console.log("Final sync verified: skipped (force shutdown)");
+    }
+    return;
+  }
+
+  const result = getPencilSessionStatus({
+    projectPath,
+    homeDir
+  });
+
+  console.log(`Project: ${result.projectRoot}`);
+  console.log(`Session state: ${result.sessionStatePath}`);
+  console.log(`Session status: ${result.session ? result.session.status : "missing"}`);
+  console.log(`Lock status: ${result.lockStatus.lock ? "locked" : "unlocked"}`);
+  if (result.session) {
+    console.log(`Pen path: ${result.session.penPath}`);
+    console.log(`Last persisted hash: ${result.session.lastPersistedHash || "(missing)"}`);
+  }
+}
+
+async function runCli(argv) {
+  const [command] = argv;
+  const homeDir = getOption(argv, "--home");
+  const positionalArgs = getPositionalArgs(argv.slice(1), OPTION_FLAGS_WITH_VALUES);
+  const continueOnError = shouldContinueOnError(argv);
 
   if (!command || command === "help" || command === "--help" || command === "-h") {
     printHelp();
@@ -237,6 +937,216 @@ async function runCli(argv) {
     return;
   }
 
+  if (command === "workflow-status") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const result = deriveWorkflowStatus(projectPath, { changeId });
+
+    if (argv.includes("--json")) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    console.log(formatWorkflowStatusReport(result));
+    return;
+  }
+
+  if (command === "next-step") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const result = deriveWorkflowStatus(projectPath, { changeId });
+
+    if (argv.includes("--json")) {
+      console.log(JSON.stringify(result.nextStep || null, null, 2));
+      return;
+    }
+
+    console.log(formatNextStepReport(result));
+    return;
+  }
+
+  if (command === "lint-spec") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const strict = argv.includes("--strict");
+    const result = lintRuntimeSpecs(projectPath, { changeId, strict });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "lint-spec", result, strict);
+    const useJson = argv.includes("--json");
+    const output = useJson ? JSON.stringify(result, null, 2) : formatLintSpecReport(result);
+
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+
+    console.log(output);
+    return;
+  }
+
+  if (command === "scope-check") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const strict = argv.includes("--strict");
+    const result = runScopeCheck(projectPath, { changeId, strict });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "scope-check", result, strict);
+    const useJson = argv.includes("--json");
+    const output = useJson ? JSON.stringify(result, null, 2) : formatScopeCheckReport(result);
+
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+
+    console.log(output);
+    return;
+  }
+
+  if (command === "lint-tasks") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const strict = argv.includes("--strict");
+    const result = lintTasks(projectPath, { changeId, strict });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "lint-tasks", result, strict);
+    const useJson = argv.includes("--json");
+    const output = useJson ? JSON.stringify(result, null, 2) : formatLintTasksReport(result);
+
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+
+    console.log(output);
+    return;
+  }
+
+  if (command === "lint-bindings") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const strict = argv.includes("--strict");
+    const result = lintBindings(projectPath, { changeId, strict });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "lint-bindings", result, strict);
+    const useJson = argv.includes("--json");
+    const output = useJson ? JSON.stringify(result, null, 2) : formatLintBindingsReport(result);
+
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+
+    console.log(output);
+    return;
+  }
+
+  if (command === "generate-sidecars") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const result = generatePlanningSidecars(projectPath, { changeId, write: true });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "generate-sidecars", result, false);
+    const useJson = argv.includes("--json");
+    const output = useJson ? JSON.stringify(result, null, 2) : formatGenerateSidecarsReport(result);
+
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+
+    console.log(output);
+    return;
+  }
+
+  if (command === "verify-bindings") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const strict = argv.includes("--strict");
+    const result = verifyBindings(projectPath, { changeId, strict });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "verify-bindings", result, strict);
+    const useJson = argv.includes("--json");
+    const output = useJson
+      ? JSON.stringify(result, null, 2)
+      : formatVerifyReport(result, "Da Vinci verify-bindings");
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+    console.log(output);
+    return;
+  }
+
+  if (command === "verify-implementation") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const strict = argv.includes("--strict");
+    const result = verifyImplementation(projectPath, { changeId, strict });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "verify-implementation", result, strict);
+    const useJson = argv.includes("--json");
+    const output = useJson
+      ? JSON.stringify(result, null, 2)
+      : formatVerifyReport(result, "Da Vinci verify-implementation");
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+    console.log(output);
+    return;
+  }
+
+  if (command === "verify-structure") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const strict = argv.includes("--strict");
+    const result = verifyStructure(projectPath, { changeId, strict });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "verify-structure", result, strict);
+    const useJson = argv.includes("--json");
+    const output = useJson
+      ? JSON.stringify(result, null, 2)
+      : formatVerifyReport(result, "Da Vinci verify-structure");
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+    console.log(output);
+    return;
+  }
+
+  if (command === "verify-coverage") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const strict = argv.includes("--strict");
+    const result = verifyCoverage(projectPath, { changeId, strict });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "verify-coverage", result, strict);
+    const useJson = argv.includes("--json");
+    const output = useJson
+      ? JSON.stringify(result, null, 2)
+      : formatVerifyReport(result, "Da Vinci verify-coverage");
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+    console.log(output);
+    return;
+  }
+
+  if (command === "diff-spec") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const fromDir = getOption(argv, "--from");
+    const result = diffSpec(projectPath, { changeId, fromDir });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "diff-spec", result, false);
+    const useJson = argv.includes("--json");
+    const output = useJson ? JSON.stringify(result, null, 2) : formatDiffSpecReport(result);
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+    console.log(output);
+    return;
+  }
+
+  if (command === "scaffold") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const outputDir = getOption(argv, "--output");
+    const result = scaffoldFromBindings(projectPath, { changeId, outputDir });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "scaffold", result, false);
+    const useJson = argv.includes("--json");
+    const output = useJson ? JSON.stringify(result, null, 2) : formatScaffoldReport(result);
+    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
+      return;
+    }
+    console.log(output);
+    return;
+  }
+
   if (command === "validate-assets") {
     const result = validateAssets();
     console.log(`Da Vinci v${result.version} assets are complete (${result.requiredAssets} required files).`);
@@ -250,17 +1160,26 @@ async function runCli(argv) {
     const result = auditProject(projectPath, { mode, changeId });
     const report = formatAuditReport(result);
 
-    if (result.status === "FAIL") {
-      throw new Error(report);
+    if (emitOrThrowOnStatus(result.status, ["FAIL"], report, continueOnError)) {
+      return;
     }
 
     console.log(report);
     return;
   }
 
+  if (command === "bootstrap-project") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const force = argv.includes("--force");
+    const result = bootstrapProjectArtifacts(projectPath, { changeId, force });
+    console.log(formatBootstrapProjectReport(result));
+    return;
+  }
+
   if (command === "icon-sync") {
     const outputPath = getOption(argv, "--output") || getOption(argv, "--catalog");
-    const timeoutMs = getOption(argv, "--timeout-ms");
+    const timeoutMs = getIntegerOption(argv, "--timeout-ms", { min: 1 });
     const strict = argv.includes("--strict");
 
     const result = await syncIconCatalog({
@@ -275,129 +1194,7 @@ async function runCli(argv) {
   }
 
   if (command === "icon-search") {
-    const family = getOption(argv, "--family") || "all";
-    const topRaw = getOption(argv, "--top");
-    const queryOption = getOption(argv, "--query");
-    const catalogPath = getOption(argv, "--catalog");
-    const aliasesPath = getOption(argv, "--aliases");
-    const iconPositional = getPositionalArgs(argv.slice(1), [
-      "--home",
-      "--query",
-      "--family",
-      "--top",
-      "--catalog",
-      "--aliases"
-    ]);
-    const query = queryOption || iconPositional.join(" ").trim();
-
-    if (!query) {
-      throw new Error("`icon-search` requires `--query <text>` or positional query text.");
-    }
-
-    let top;
-    if (topRaw !== undefined) {
-      top = Number.parseInt(topRaw, 10);
-      if (!Number.isFinite(top) || top < 1 || top > 50) {
-        throw new Error("`icon-search --top` must be an integer between 1 and 50.");
-      }
-    }
-
-    let loadedCatalog = null;
-    let loadedCatalogPath = null;
-    let catalogLoadError = null;
-    let loadedAliases = null;
-    let loadedAliasesPath = null;
-    let aliasesLoadError = null;
-    let aliasExpansion = {
-      extraTokens: [],
-      matchedAliases: []
-    };
-
-    try {
-      const loaded = loadIconCatalog({
-        catalogPath,
-        homeDir
-      });
-      loadedCatalog = loaded.catalog;
-      loadedCatalogPath = loaded.catalogPath;
-    } catch (error) {
-      catalogLoadError = error.message || String(error);
-    }
-
-    try {
-      const loaded = loadIconAliases({
-        aliasPath: aliasesPath,
-        homeDir
-      });
-      loadedAliases = loaded;
-      loadedAliasesPath = loaded.aliasPath;
-      aliasExpansion = expandQueryWithAliases(query, loaded.aliases);
-    } catch (error) {
-      aliasesLoadError = error.message || String(error);
-    }
-
-    const result = searchIconLibrary(query, {
-      family,
-      top,
-      catalog: loadedCatalog ? loadedCatalog.icons : [],
-      extraQueryTokens: aliasExpansion.extraTokens
-    });
-    const jsonOutput = argv.includes("--json");
-
-    const resultWithMeta = {
-      ...result,
-      catalog: {
-        path: loadedCatalogPath || "(unresolved)",
-        loaded: Boolean(loadedCatalog),
-        iconCount: loadedCatalog ? loadedCatalog.iconCount : 0,
-        generatedAt: loadedCatalog ? loadedCatalog.generatedAt : null,
-        error: catalogLoadError
-      },
-      aliases: {
-        path: loadedAliasesPath || "(unresolved)",
-        loaded: loadedAliases ? Boolean(loadedAliases.loaded) : false,
-        available: Boolean(loadedAliases),
-        source: loadedAliases ? loadedAliases.source : null,
-        matched: aliasExpansion.matchedAliases.length,
-        extraTokens: aliasExpansion.extraTokens,
-        error: aliasesLoadError
-      }
-    };
-
-    if (jsonOutput) {
-      console.log(JSON.stringify(resultWithMeta, null, 2));
-      return;
-    }
-
-    if (resultWithMeta.catalog.loaded) {
-      console.log(
-        `Icon catalog: ${resultWithMeta.catalog.path} (${resultWithMeta.catalog.iconCount} icons, ${resultWithMeta.catalog.generatedAt})`
-      );
-    } else if (resultWithMeta.catalog.error) {
-      console.log(
-        `Icon catalog: ${resultWithMeta.catalog.path} (load failed: ${resultWithMeta.catalog.error}; using built-in fallback index)`
-      );
-    } else {
-      console.log(
-        `Icon catalog: ${resultWithMeta.catalog.path} (not found; using built-in fallback index; run \`da-vinci icon-sync\`)`
-      );
-    }
-
-    if (resultWithMeta.aliases.available) {
-      console.log(
-        `Icon aliases: ${resultWithMeta.aliases.path} (${resultWithMeta.aliases.source}, matched ${resultWithMeta.aliases.matched})`
-      );
-    } else if (resultWithMeta.aliases.error) {
-      console.log(
-        `Icon aliases: ${resultWithMeta.aliases.path} (load failed: ${resultWithMeta.aliases.error})`
-      );
-    } else {
-      console.log(
-        `Icon aliases: ${resultWithMeta.aliases.path} (not found; using built-in defaults only)`
-      );
-    }
-
-    console.log(formatIconSearchReport(result));
+    await handleIconSearchCommand(argv, homeDir);
     return;
   }
 
@@ -408,7 +1205,7 @@ async function runCli(argv) {
     if (opsFile) {
       operations = readOperations(opsFile);
     } else if (!process.stdin.isTTY) {
-      operations = fs.readFileSync(0, "utf8");
+      operations = readLimitedStdin();
     } else {
       throw new Error("`preflight-pencil` requires `--ops-file <path>` or piped stdin input.");
     }
@@ -416,8 +1213,8 @@ async function runCli(argv) {
     const result = preflightPencilBatch(operations);
     const report = formatPencilPreflightReport(result);
 
-    if (result.status === "FAIL") {
-      throw new Error(report);
+    if (emitOrThrowOnStatus(result.status, ["FAIL"], report, continueOnError)) {
+      return;
     }
 
     console.log(report);
@@ -425,69 +1222,7 @@ async function runCli(argv) {
   }
 
   if (command === "supervisor-review") {
-    if (argv.includes("--help") || argv.includes("-h")) {
-      console.log(
-        [
-          "da-vinci supervisor-review",
-          "",
-          "Usage:",
-          "  da-vinci supervisor-review --project <path> --change <id> [--run-reviewers] [--review-concurrency <value>] [--review-retries <value>] [--review-retry-delay-ms <value>] [--source <skill|manual|inferred>] [--executed-reviewers <csv>] [--status <PASS|WARN|BLOCK>] [--issue-list <text>] [--revision-outcome <text>] [--write] [--json]",
-          "  da-vinci supervisor-review --project <path> --pencil-design <path> [--run-reviewers] [--review-concurrency <value>] [--review-retries <value>] [--review-retry-delay-ms <value>] [--source <skill|manual|inferred>] [--executed-reviewers <csv>] [--status <PASS|WARN|BLOCK>] [--issue-list <text>] [--revision-outcome <text>] [--write] [--json]",
-          "",
-          "Notes:",
-          "  - omit --status to infer a conservative review status from current design artifacts",
-          "  - use --run-reviewers to execute configured reviewer skills automatically via codex exec",
-          "  - `design-supervisor review` is a compatibility alias for this command"
-        ].join("\n")
-      );
-      return;
-    }
-
-    const projectPath = getOption(argv, "--project") || process.cwd();
-    const changeId = getOption(argv, "--change");
-    const pencilDesignPath = getOption(argv, "--pencil-design");
-    const status = getOption(argv, "--status");
-    const source = getOption(argv, "--source");
-    const executedReviewers = getOption(argv, "--executed-reviewers");
-    const codexBin = getOption(argv, "--codex-bin");
-    const maxImages = getOption(argv, "--max-images");
-    const reviewerTimeoutMs = getOption(argv, "--review-timeout-ms");
-    const reviewConcurrency = getOption(argv, "--review-concurrency");
-    const reviewerRetries = getOption(argv, "--review-retries");
-    const reviewerRetryDelayMs = getOption(argv, "--review-retry-delay-ms");
-    const issueList = getOption(argv, "--issue-list");
-    const revisionOutcome = getOption(argv, "--revision-outcome");
-    const write = argv.includes("--write");
-    const acceptWarn = argv.includes("--accept-warn");
-    const runReviewers = argv.includes("--run-reviewers");
-    const jsonOutput = argv.includes("--json");
-
-    const result = await runDesignSupervisorReview({
-      projectPath,
-      changeId,
-      pencilDesignPath,
-      status,
-      source,
-      executedReviewers,
-      codexBin,
-      maxImages,
-      reviewerTimeoutMs,
-      reviewConcurrency,
-      reviewerRetries,
-      reviewerRetryDelayMs,
-      issueList,
-      revisionOutcome,
-      write,
-      acceptWarn,
-      runReviewers
-    });
-
-    if (jsonOutput) {
-      console.log(JSON.stringify(result, null, 2));
-      return;
-    }
-
-    console.log(formatDesignSupervisorReviewReport(result));
+    await handleSupervisorReviewCommand(argv);
     return;
   }
 
@@ -577,11 +1312,69 @@ async function runCli(argv) {
     console.log(`State file: ${result.statePath}`);
     console.log(`Snapshot hash: ${result.liveHash}`);
     if (!result.usedStateFile) {
-      console.log("State file was missing; sync comparison fell back to hashing the disk .pen file directly.");
+      console.log(
+        result.stateHash
+          ? "State file hash was stale; sync comparison fell back to hashing the disk .pen file directly."
+          : "State file was missing; sync comparison fell back to hashing the disk .pen file directly."
+      );
     }
     return;
   }
 
+  if (command === "check-pen-baseline") {
+    const penPath = getOption(argv, "--pen");
+    const baselinePaths = getCommaSeparatedOptionValues(argv, "--baseline");
+    const preferredSource = getOption(argv, "--prefer-source");
+
+    if (!penPath || baselinePaths.length === 0) {
+      throw new Error(
+        "`check-pen-baseline` requires `--pen <path>` and at least one `--baseline <path>`."
+      );
+    }
+
+    const result = comparePenBaselineAlignment({
+      penPath,
+      baselinePaths,
+      preferredSource
+    });
+
+    if (
+      emitOrThrowOnStatus(
+        result.status,
+        ["BLOCK"],
+        [
+          "Baseline alignment check failed.",
+          formatPenBaselineAlignmentReport(result)
+        ].join("\n"),
+        continueOnError
+      )
+    ) {
+      return;
+    }
+
+    console.log(formatPenBaselineAlignmentReport(result));
+    return;
+  }
+
+  if (command === "sync-pen-source") {
+    const sourcePath = getOption(argv, "--from");
+    const targetPath = getOption(argv, "--to");
+
+    if (!sourcePath || !targetPath) {
+      throw new Error("`sync-pen-source` requires `--from <path>` and `--to <path>`.");
+    }
+
+    const result = syncPenSource({
+      sourcePath,
+      targetPath
+    });
+
+    console.log(`Synced .pen source from ${result.sourcePath} to ${result.targetPath}`);
+    console.log(`State file: ${result.statePath}`);
+    console.log(`Snapshot hash: ${result.state.snapshotHash}`);
+    return;
+  }
+
   if (command === "snapshot-pen") {
     const inputPath = getOption(argv, "--input");
     const outputPath = getOption(argv, "--output");
@@ -610,175 +1403,12 @@ async function runCli(argv) {
   }
 
   if (command === "pencil-lock") {
-    const subcommand = getPositionalArgs(argv.slice(1), [
-      "--home",
-      "--project",
-      "--owner",
-      "--wait-ms"
-    ])[0];
-    const projectPath = getOption(argv, "--project") || process.cwd();
-    const owner = getOption(argv, "--owner");
-    const waitMs = getOption(argv, "--wait-ms");
-    const force = argv.includes("--force");
-
-    if (!subcommand || ["acquire", "release", "status"].includes(subcommand) === false) {
-      throw new Error("`pencil-lock` requires one of: acquire, release, status.");
-    }
-
-    if (subcommand === "acquire") {
-      const result = acquirePencilLock({
-        projectPath,
-        owner,
-        waitMs,
-        homeDir
-      });
-      console.log(`${result.alreadyHeld ? "Reused" : "Acquired"} Pencil lock at ${result.lockPath}`);
-      console.log(`Project: ${result.lock.projectPath}`);
-      console.log(`Owner: ${result.lock.owner}`);
-      return;
-    }
-
-    if (subcommand === "release") {
-      const result = releasePencilLock({
-        projectPath,
-        force,
-        homeDir
-      });
-      if (!result.hadLock) {
-        console.log(`No Pencil lock was present at ${result.lockPath}`);
-        return;
-      }
-      console.log(`Released Pencil lock at ${result.lockPath}`);
-      console.log(`Previous project: ${result.lock.projectPath}`);
-      return;
-    }
-
-    const result = getPencilLockStatus({ homeDir });
-    console.log(`Lock path: ${result.lockPath}`);
-    if (!result.lock) {
-      console.log("Status: unlocked");
-      return;
-    }
-    console.log("Status: locked");
-    console.log(`Project: ${result.lock.projectPath}`);
-    console.log(`Owner: ${result.lock.owner}`);
-    console.log(`PID: ${result.lock.pid}`);
+    handlePencilLockCommand(argv, homeDir);
     return;
   }
 
   if (command === "pencil-session") {
-    const subcommand = getPositionalArgs(argv.slice(1), [
-      "--home",
-      "--project",
-      "--pen",
-      "--nodes-file",
-      "--variables-file",
-      "--version",
-      "--owner",
-      "--wait-ms"
-    ])[0];
-    const projectPath = getOption(argv, "--project") || process.cwd();
-    const penPath = getOption(argv, "--pen");
-    const nodesFile = getOption(argv, "--nodes-file");
-    const variablesFile = getOption(argv, "--variables-file");
-    const version = getOption(argv, "--version");
-    const verifyWithPencil = argv.includes("--verify-open");
-    const owner = getOption(argv, "--owner");
-    const waitMs = getOption(argv, "--wait-ms");
-    const force = argv.includes("--force");
-
-    if (!subcommand || ["begin", "persist", "end", "status"].includes(subcommand) === false) {
-      throw new Error("`pencil-session` requires one of: begin, persist, end, status.");
-    }
-
-    if (subcommand === "begin") {
-      if (!penPath) {
-        throw new Error("`pencil-session begin` requires `--pen <path>`.");
-      }
-
-      const result = beginPencilSession({
-        projectPath,
-        penPath,
-        version,
-        verifyWithPencil,
-        owner,
-        waitMs,
-        homeDir
-      });
-
-      console.log(`Began Pencil session for ${result.projectRoot}`);
-      console.log(`Pen path: ${result.penPath}`);
-      console.log(`Session state: ${result.sessionStatePath}`);
-      console.log(`Snapshot hash: ${result.session.lastPersistedHash}`);
-      return;
-    }
-
-    if (subcommand === "persist") {
-      if (!penPath || !nodesFile) {
-        throw new Error("`pencil-session persist` requires `--pen <path>` and `--nodes-file <path>`.");
-      }
-
-      const result = persistPencilSession({
-        projectPath,
-        penPath,
-        nodesFile,
-        variablesFile,
-        version,
-        verifyWithPencil,
-        homeDir
-      });
-
-      console.log(`Persisted Pencil session for ${result.projectRoot}`);
-      console.log(`Pen path: ${result.penPath}`);
-      console.log(`Session state: ${result.sessionStatePath}`);
-      console.log(`Snapshot hash: ${result.session.lastPersistedHash}`);
-      console.log(`In sync: ${result.syncResult.inSync ? "yes" : "no"}`);
-      return;
-    }
-
-    if (subcommand === "end") {
-      if (!penPath) {
-        throw new Error("`pencil-session end` requires `--pen <path>`.");
-      }
-      if (!nodesFile && !force) {
-        throw new Error(
-          "`pencil-session end` requires `--nodes-file <path>` (and `--variables-file <path>` when available). Use `--force` only for emergency lock release."
-        );
-      }
-
-      const result = endPencilSession({
-        projectPath,
-        penPath,
-        nodesFile,
-        variablesFile,
-        version,
-        homeDir,
-        force
-      });
-
-      console.log(`Ended Pencil session for ${result.projectRoot}`);
-      console.log(`Pen path: ${result.penPath}`);
-      console.log(`Session state: ${result.sessionStatePath}`);
-      console.log(`Final status: ${result.session.status}`);
-      if (result.syncResult) {
-        console.log(`Final sync verified: ${result.syncResult.inSync ? "yes" : "no"}`);
-      }
-      return;
-    }
-
-    const result = getPencilSessionStatus({
-      projectPath,
-      homeDir
-    });
-
-    console.log(`Project: ${result.projectRoot}`);
-    console.log(`Session state: ${result.sessionStatePath}`);
-    console.log(`Session status: ${result.session ? result.session.status : "missing"}`);
-    console.log(`Lock status: ${result.lockStatus.lock ? "locked" : "unlocked"}`);
-    if (result.session) {
-      console.log(`Pen path: ${result.session.penPath}`);
-      console.log(`Last persisted hash: ${result.session.lastPersistedHash || "(missing)"}`);
-    }
+    handlePencilSessionCommand(argv, homeDir);
     return;
   }
 
@@ -786,5 +1416,6 @@ async function runCli(argv) {
 }
 
 module.exports = {
-  runCli
+  runCli,
+  readLimitedStdin
 };