karajan-code 2.7.4 → 2.8.0

package/src/canvas/to-flat.js

@@ -0,0 +1,85 @@
+/**
+ * Canvas → flat task string adapter.
+ *
+ * Renders a validated Canvas object as a single markdown blob the
+ * existing planner can consume verbatim. Preserves every section
+ * with its original heading so downstream steps (planner prompt,
+ * coder prompt, plan JSON `task` field) see the same shape.
+ *
+ * The point: Canvas users get planner-time validation (catching
+ * broken acceptance tests before they're persisted) AND benefit from
+ * every existing planner / coder pipeline without those pipelines
+ * needing Canvas awareness. Norms + Safeguards explicitly bracketed
+ * so prompts that scan for them can find them with a regex.
+ */
+
+/**
+ * @param {object} canvas — output of validateCanvas (.canvas)
+ * @returns {string} markdown task ready for the planner
+ */
+export function canvasToTask(canvas) {
+  const lines = [`# ${canvas.title}`, ""];
+
+  // Requirements
+  lines.push("## Requirements", canvas.requirements.problem);
+  if (canvas.requirements.done && canvas.requirements.done.length > 0) {
+    lines.push("", "Definition of done:");
+    for (const d of canvas.requirements.done) lines.push(`- ${d}`);
+  }
+  lines.push("");
+
+  // Entities (optional)
+  if (canvas.entities && canvas.entities.length > 0) {
+    lines.push("## Entities");
+    for (const e of canvas.entities) {
+      const fields = e.fields && e.fields.length > 0 ? ` — fields: ${e.fields.join(", ")}` : "";
+      lines.push(`- ${e.name}${fields}${e.notes ? `. ${e.notes}` : ""}`);
+    }
+    lines.push("");
+  }
+
+  // Approach
+  lines.push("## Approach", canvas.approach, "");
+
+  // Structure (optional content)
+  lines.push("## Structure");
+  if (canvas.structure?.touches?.length > 0) lines.push(`- touches: ${canvas.structure.touches.join(", ")}`);
+  if (canvas.structure?.depends_on?.length > 0) lines.push(`- depends_on: ${canvas.structure.depends_on.join(", ")}`);
+  if (canvas.structure?.contracts?.length > 0) lines.push(`- contracts: ${canvas.structure.contracts.join(", ")}`);
+  lines.push("");
+
+  // Operations — each becomes one HU. Acceptance tests inline so the
+  // planner sees the contract from turn 1.
+  lines.push("## Operations");
+  canvas.operations.forEach((op, i) => {
+    lines.push(`${i + 1}. ${op.title}`);
+    if (op.file_hint) lines.push(`   file: ${op.file_hint}`);
+    if (op.blocked_by && op.blocked_by.length > 0) lines.push(`   depends on: ${op.blocked_by.join(", ")}`);
+    lines.push("   Acceptance:");
+    for (const t of op.acceptance) {
+      // Render shell as one-liner, gherkin as fenced block so newlines survive.
+      if (t.type === "gherkin") {
+        lines.push("   - gherkin:", "     ```gherkin", ...t.content.split("\n").map((l) => `     ${l}`), "     ```");
+      } else {
+        lines.push(`   - shell: \`${t.content}\``);
+      }
+    }
+  });
+  lines.push("");
+
+  // Norms (optional) — bracketed so prompts can find them.
+  if (canvas.norms && canvas.norms.length > 0) {
+    lines.push("## Norms (per-task engineering standards — coder MUST follow)");
+    for (const n of canvas.norms) lines.push(`- ${n}`);
+    lines.push("");
+  }
+
+  // Safeguards (optional) — bracketed similarly.
+  if (canvas.safeguards && canvas.safeguards.length > 0) {
+    lines.push("## Safeguards (non-negotiable invariants — code MUST hold these)");
+    for (const s of canvas.safeguards) lines.push(`- ${s}`);
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

package/src/canvas/validate.js

@@ -0,0 +1,163 @@
+/**
+ * REASONS Canvas validator.
+ *
+ * Schema validation + planner-time sanity checks for acceptance tests.
+ * The schema is enforced via Valibot in canvas/schema.js. This module
+ * adds the bug-class fix: parse-check every shell acceptance test
+ * BEFORE it gets persisted into a plan and BEFORE any LLM is called.
+ *
+ * Catches the 2026-04-29 incident class:
+ *   `length as $n | .filesOver300LOC == $n` → exits non-zero with a
+ *   descriptive error pointing at the offending operation + test
+ *   index, BEFORE the user has paid for any agent run.
+ */
+
+import { spawnSync } from "node:child_process";
+import { safeParseCanvas } from "./schema.js";
+
+/**
+ * Run a single shell acceptance test through `bash -n` (parse-only,
+ * doesn't execute) to catch shell-level syntax errors. Then, if the
+ * test invokes `jq`, also probe the jq query through `jq -n <query>`
+ * with empty input — jq errors there iff the query has bad syntax.
+ *
+ * Trade-off accepted: bash -n won't catch every command-substitution
+ * pitfall (it parses but doesn't expand), and jq -n with empty input
+ * may pass queries that fail at runtime against real input. The point
+ * is to catch the OBVIOUS bugs cheaply, not to be airtight.
+ *
+ * @param {string} cmd
+ * @returns {{ ok: true } | { ok: false, kind: string, error: string }}
+ */
+export function validateShellTest(cmd) {
+  if (typeof cmd !== "string" || cmd.trim().length === 0) {
+    return { ok: false, kind: "empty", error: "shell test is empty" };
+  }
+
+  // Layer 1: bash -n parse-check on the whole command.
+  const bash = spawnSync("bash", ["-n", "-c", cmd], { encoding: "utf8", timeout: 5000 });
+  if (bash.status !== 0) {
+    const err = (bash.stderr || "").trim() || "bash -n rejected the command";
+    return { ok: false, kind: "shell-syntax", error: err };
+  }
+
+  // Layer 2: every `jq '...'` invocation gets its query parse-checked.
+  // Permissive regex: catches `jq -e 'X'`, `jq "X"`, `| jq 'X'`. False
+  // negatives are fine — better to skip a real jq than misinterpret a
+  // shell-quoting edge case.
+  //
+  // We distinguish COMPILE errors (the bug we want to catch — invalid
+  // syntax, e.g. `length as $n | .field` over an array) from RUNTIME
+  // errors (the query is well-formed but fails on null input from
+  // `-n`, like `.foo[]` on null). Only compile errors fail validation;
+  // runtime errors against synthetic input are expected because real
+  // input isn't available at plan-time.
+  const jqRe = /\bjq\b\s+(?:-[a-zA-Z]+\s+)*(?:'([^']+)'|"([^"]+)")/g;
+  for (const m of cmd.matchAll(jqRe)) {
+    const query = m[1] || m[2];
+    if (!query) continue;
+
+    // Static pattern detector for the 2026-04-29 as-binding misuse:
+    // `[expr] | length as $X | .field` and similar. The `as $X`
+    // binds the value to a name but does NOT change the value
+    // flowing through the pipe. The next `.field` is therefore
+    // applied to the array tail (or whatever the previous stage
+    // returned), not to the original root. Always wrong.
+    //
+    // Detection: a pipeline whose tail is `length as $X | .X` (or
+    // any `<terminal-operator> as $X | .field`) is the smell.
+    const asBindingMisuse = /\b(?:length|keys|values|min|max|add|first|last)\s+as\s+\$[A-Za-z_][\w]*\s*\|\s*\.[A-Za-z_]/;
+    if (asBindingMisuse.test(query)) {
+      return {
+        ok: false,
+        kind: "jq-syntax",
+        error: "Likely as-binding misuse: `length as $n | .field` does not change the value flowing through; `.field` is applied to the previous stage's output, not the root. Use `. as $r | <transform> | $r.field` instead.",
+      };
+    }
+
+    const jq = spawnSync("jq", ["-n", query], { encoding: "utf8", timeout: 5000 });
+    if (jq.status !== 0) {
+      const err = (jq.stderr || "").trim() || "jq rejected the query";
+      // jq distinguishes compile errors with these tokens. Anything
+      // else (e.g. "Cannot index null with string") is a runtime error
+      // against the empty input, NOT a syntax bug.
+      const isCompileError = /\b(compile error|syntax error|unexpected|jq: error \(at <stdin>:\d+\): ?$)/i.test(err);
+      if (isCompileError) {
+        return { ok: false, kind: "jq-syntax", error: err };
+      }
+      // Special case: `length as $n | .field` returns "Cannot index
+      // array/number/string with string" on -n input because the as-
+      // binding misuse means `.field` is applied to the wrong thing.
+      // This is exactly the 2026-04-29 bug class. Treat it as syntax-
+      // adjacent: the query is "compilable" but semantically broken
+      // by misuse of as-binding.
+      if (/Cannot index (array|number|string) with string/i.test(err)) {
+        return { ok: false, kind: "jq-syntax", error: err };
+      }
+      // Otherwise let it pass — runtime error against synthetic input
+      // is fine. jq parsed the query successfully.
+    }
+  }
+
+  return { ok: true };
+}
+
+/**
+ * Validate every operation's acceptance tests in a parsed Canvas.
+ * Returns an array of issues; empty array means everything passed.
+ *
+ * @param {object} canvas
+ * @returns {Array<{ operationIndex: number, operationTitle: string, testIndex: number, type: string, content: string, kind: string, error: string }>}
+ */
+export function validateAcceptanceTests(canvas) {
+  const issues = [];
+  if (!canvas || !Array.isArray(canvas.operations)) return issues;
+  canvas.operations.forEach((op, opIdx) => {
+    (op.acceptance || []).forEach((t, tIdx) => {
+      if (t.type === "shell") {
+        const r = validateShellTest(t.content);
+        if (!r.ok) {
+          issues.push({
+            operationIndex: opIdx,
+            operationTitle: op.title,
+            testIndex: tIdx,
+            type: t.type,
+            content: t.content,
+            kind: r.kind,
+            error: r.error,
+          });
+        }
+      } else if (t.type === "gherkin") {
+        // Minimal gherkin sanity: must contain at least one Given AND
+        // one Then. When/And/But are optional. This catches "blank
+        // gherkin" without trying to parse the language.
+        if (!/\bGiven\b/i.test(t.content) || !/\bThen\b/i.test(t.content)) {
+          issues.push({
+            operationIndex: opIdx,
+            operationTitle: op.title,
+            testIndex: tIdx,
+            type: t.type,
+            content: t.content,
+            kind: "gherkin-incomplete",
+            error: "Gherkin scenario must contain at least one Given and one Then.",
+          });
+        }
+      }
+    });
+  });
+  return issues;
+}
+
+/**
+ * Top-level validator. Runs schema + acceptance-test parse-checks.
+ *
+ * @param {unknown} canvas
+ * @returns {{ valid: true, canvas: object } | { valid: false, schemaIssues?: object[], testIssues?: object[] }}
+ */
+export function validateCanvas(canvas) {
+  const schema = safeParseCanvas(canvas);
+  if (!schema.success) return { valid: false, schemaIssues: schema.issues };
+  const testIssues = validateAcceptanceTests(schema.output);
+  if (testIssues.length > 0) return { valid: false, testIssues };
+  return { valid: true, canvas: schema.output };
+}

package/src/checks/binaries.js

@@ -88,7 +88,7 @@ export function createSerenaCheck() {
     applies: (config) => config.serena?.enabled === true,
     describe: "Install Serena via: uvx --from git+https://github.com/oraios/serena serena",
     async detect() {
-      let ok = false;
+      let ok;
       try {
         const res = await runCommand("serena", ["--version"]);
         ok = res.exitCode === 0;

package/src/checks/ports.js

@@ -12,6 +12,8 @@
 
 import { isPortAvailable, findAvailablePort } from "../utils/port-check.js";
 import { getPortOccupant } from "../utils/port-occupant.js";
+import { discoverRunningSonar } from "../sonar/discovery.js";
+import { isSonarReachable } from "../sonar/manager.js";
 import { STRATEGY } from "./types.js";
 
 const DEFAULT_SONAR_PORT = 9000;
@@ -22,58 +24,110 @@ function extractPortFromHost(host, fallback) {
   return m ? Number(m[1]) : fallback;
 }
 
-/**
- * Whether the occupant looks like the Karajan-managed Sonar container.
- * Docker Desktop's proxy is typically `com.docker.backend` / `com.docker.vmnetd`
- * on macOS and `docker-proxy` on Linux. We treat those as OK.
- */
-function isKarajanSonarOccupant(occupant) {
-  if (!occupant?.command) return false;
-  const cmd = occupant.command.toLowerCase();
-  return cmd.includes("docker") || cmd.includes("sonar");
-}
-
 export function createSonarPortCheck() {
   return {
     name: "port:sonar",
     label: "SonarQube port",
-    strategy: STRATEGY.MANUAL,
-    // Since v2.7.4 Sonar is intrinsic to Karajan for code tasks, so the
-    // port check almost always applies. The only legitimate skip is when
-    // the user runs their own external Sonar instance (`external: true`),
-    // in which case the port is managed outside Karajan. The legacy
-    // `sonarqube.enabled` field is ignored (deprecation warning emitted
-    // at config load time — see emitConfigDeprecations in flow-runner.js).
+    // AUTO since v2.7.5 — Karajan now resolves SonarQube discovery on
+    // its own. If a Sonar container is running anywhere (any name, any
+    // image tag), point Karajan at it. If port 9000 is occupied by
+    // someone non-Sonar, rebind to the next free port. Asking the user
+    // to "stop the unknown process" was busywork.
+    strategy: STRATEGY.AUTO,
     applies: (config) => {
       if (config?.sonarqube?.external === true) {
         return { applies: false, reason: "sonarqube.external is true — port managed outside Karajan" };
       }
       return true;
     },
+    describe: "Discover or rebind SonarQube port (no user action needed)",
     async detect({ config }) {
-      const port = extractPortFromHost(config?.sonarqube?.host, DEFAULT_SONAR_PORT);
-      const free = await isPortAvailable(port);
+      const configuredPort = extractPortFromHost(config?.sonarqube?.host, DEFAULT_SONAR_PORT);
+
+      // Step 1 — is there ANY running SonarQube container we can reuse?
+      // Container name doesn't matter; we just need a published host port
+      // that responds to /api/system/status. This avoids "port 9000 is
+      // taken by an unknown process" errors when the unknown process is
+      // actually a perfectly good SonarQube from another project.
+      const discovered = await discoverRunningSonar();
+      if (discovered.found && discovered.reachable) {
+        // If the discovered host matches what's already configured,
+        // there's nothing to fix — happy path.
+        if (discovered.port === configuredPort) {
+          return {
+            ok: true,
+            severity: "info",
+            detail: `Reusing running SonarQube container "${discovered.containerName}" on port ${discovered.port}`,
+          };
+        }
+        // Otherwise we want to rewrite the host config at runtime.
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `Found running SonarQube container "${discovered.containerName}" on port ${discovered.port} (config points at ${configuredPort})`,
+          extra: { remap: { host: discovered.host, port: discovered.port, container: discovered.containerName } },
+        };
+      }
+
+      // Step 2 — no running container. Is the configured port even free?
+      const free = await isPortAvailable(configuredPort);
       if (free) {
-        return { ok: true, severity: "info", detail: `Port ${port} is free (Sonar container not yet running)` };
+        return {
+          ok: true,
+          severity: "info",
+          detail: `Port ${configuredPort} is free (Sonar container will be started on demand)`,
+        };
       }
-      // Busy — is it our container?
-      const occupant = await getPortOccupant(port);
-      if (occupant && isKarajanSonarOccupant(occupant)) {
+
+      // Step 3 — port is busy. Maybe the occupant IS Sonar but not
+      // discovered by `docker ps` (rare: bare-metal Sonar, host-network
+      // container, etc.). HTTP-probe to find out.
+      const probeHost = `http://localhost:${configuredPort}`;
+      if (await isSonarReachable(probeHost)) {
         return {
           ok: true,
           severity: "info",
-          detail: `Port ${port} held by Karajan-managed Sonar (${occupant.command} PID ${occupant.pid})`,
+          detail: `Port ${configuredPort} held by a Sonar instance (HTTP /api/system/status responds) — reusing it`,
         };
       }
-      const who = occupant
-        ? `${occupant.command || "unknown"} (PID ${occupant.pid ?? "?"})`
-        : "unknown process";
+
+      // Step 4 — really not Sonar. Find an alternate free port and tell
+      // the runtime to use it. The compose template's published port is
+      // hardcoded at 9000 so we can't auto-rebind the container itself,
+      // but we CAN warn loudly with a clear, fixable message.
+      const occupant = await getPortOccupant(configuredPort);
+      const alt = await findAvailablePort(configuredPort + 1, 20);
+      if (alt) {
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `Port ${configuredPort} occupied by ${occupant?.command || "unknown"} (PID ${occupant?.pid ?? "?"}). Will rebind Karajan-managed Sonar to ${alt}.`,
+          extra: { remap: { host: `http://localhost:${alt}`, port: alt, fromPort: configuredPort } },
+        };
+      }
+      // Last-resort failure (no free port in the next 20).
       return {
         ok: false,
         severity: "fail",
-        detail: `Port ${port} occupied by ${who}`,
-        fix: `Stop the process holding port ${port} or change sonarqube.host in kj.config.yml.`,
-        extra: { port, occupant },
+        detail: `Port ${configuredPort} occupied by ${occupant?.command || "unknown"} (PID ${occupant?.pid ?? "?"}) and no free port in ${configuredPort + 1}..${configuredPort + 20}`,
+        fix: "Stop the conflicting process or set sonarqube.host in kj.config.yml.",
+      };
+    },
+    async remediate({ extra }) {
+      if (!extra?.remap) {
+        return { fixed: false, detail: "No remap available" };
+      }
+      const { host, container, fromPort } = extra.remap;
+      const detail = container
+        ? `Pointed Karajan at running SonarQube ${container} (${host})`
+        : `Rebound Karajan-managed Sonar from port ${fromPort} to ${host}`;
+      return {
+        fixed: true,
+        detail,
+        // The runner merges this into the runtime config so every
+        // downstream Sonar caller (scanner, manager, MCP handler) sees
+        // the new host without the user touching kj.config.yml.
+        changes: { sonarqube: { host } },
       };
     },
   };

package/src/checks/sonar.js

@@ -36,7 +36,7 @@ export function createSonarStatusCheck() {
       if (!sonarEnabled(config)) {
         return { ok: true, severity: "info", detail: "Disabled in config" };
       }
-      let reachable = false;
+      let reachable;
       try {
         reachable = await isSonarReachable(host);
       } catch {

package/src/checks/system.js

@@ -32,7 +32,7 @@ export function createGitRepoCheck() {
     label: "Git repository",
     strategy: STRATEGY.MANUAL,
     async detect() {
-      let gitOk = false;
+      let gitOk;
       try {
         gitOk = await ensureGitRepo();
       } catch {

package/src/cli/_shared.js

@@ -0,0 +1,30 @@
+import { applyRunOverrides, loadConfig, validateConfig } from "../config.js";
+import { createLogger } from "../utils/logger.js";
+
+/**
+ * Wraps a CLI action so it loads + validates config, builds the logger,
+ * and fires the anonymous cli_command telemetry event before invoking
+ * the real command body. Shared across every register-*.js module so
+ * each one doesn't need to re-import the config plumbing.
+ *
+ * @param {string} pkgVersion       Current kj version (used for telemetry).
+ * @param {string} commandName      The CLI command name being executed.
+ * @param {object} flags            Flags parsed by Commander.
+ * @param {(ctx: { config: object, logger: object, flags: object }) => Promise<any>} fn
+ *                                  Body of the command — receives the merged config + logger.
+ */
+export async function withConfig(pkgVersion, commandName, flags, fn) {
+  const { config } = await loadConfig();
+  const merged = applyRunOverrides(config, flags || {});
+  validateConfig(merged, commandName);
+  const logger = createLogger(merged.output.log_level);
+
+  // Telemetry: anonymous cli_command event (non-blocking).
+  import("../utils/telemetry.js")
+    .then(({ sendTelemetryEvent }) =>
+      sendTelemetryEvent("cli_command", { command: commandName, version: pkgVersion }, merged)
+    )
+    .catch(() => {});
+
+  return fn({ config: merged, logger, flags });
+}

package/src/cli/register-meta.js

@@ -0,0 +1,204 @@
+import { discoverCommand } from "../commands/discover.js";
+import { triageCommand } from "../commands/triage.js";
+import { researcherCommand } from "../commands/researcher.js";
+import { architectCommand } from "../commands/architect.js";
+import { auditCommand } from "../commands/audit.js";
+import { resumeCommand } from "../commands/resume.js";
+import { boardCommand } from "../commands/board.js";
+import { undoCommand } from "../commands/undo.js";
+import { syncCommand } from "../commands/sync.js";
+import { cleanCommand } from "../commands/clean.js";
+import { withConfig } from "./_shared.js";
+
+/**
+ * Register the "meta" / single-role / housekeeping commands: pre-pipeline
+ * analysis (discover, triage, researcher, architect, audit), session
+ * management (resume, board, undo) and maintenance (update, sync, clean).
+ *
+ * Note: `triage` lives here (not in pipeline) because it's a single-role
+ * analysis command in the same family as discover / researcher /
+ * architect / audit, none of which run the full agent loop.
+ */
+export function registerMeta(program, { pkgVersion }) {
+  program
+    .command("discover")
+    .description("Analyze task for gaps, ambiguities and missing info")
+    .argument("[task]", "Task description (or use --task-file)")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
+    .option("--mode <name>", "Discovery mode: gaps|momtest|wendel|classify|jtbd", "gaps")
+    .option("--discover <name>", "Override discover agent")
+    .option("--discover-model <name>", "Override discover model")
+    .option("--json", "Output raw JSON")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "discover", flags, async ({ config, logger }) => {
+        const { resolveTaskInput } = await import("../utils/task-file.js");
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        await discoverCommand({ task: resolvedTask, config, logger, mode: flags.mode, json: flags.json });
+      });
+    });
+
+  program
+    .command("triage")
+    .description("Classify task complexity and recommend pipeline roles")
+    .argument("[task]", "Task description (or use --task-file)")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
+    .option("--triage <name>", "Override triage agent")
+    .option("--triage-model <name>", "Override triage model")
+    .option("--json", "Output raw JSON")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "triage", flags, async ({ config, logger }) => {
+        const { resolveTaskInput } = await import("../utils/task-file.js");
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        await triageCommand({ task: resolvedTask, config, logger, json: flags.json });
+      });
+    });
+
+  program
+    .command("researcher")
+    .description("Research codebase for a task (files, patterns, constraints)")
+    .argument("[task]", "Task description (or use --task-file)")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
+    .option("--researcher <name>", "Override researcher agent")
+    .option("--researcher-model <name>", "Override researcher model")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "researcher", flags, async ({ config, logger }) => {
+        const { resolveTaskInput } = await import("../utils/task-file.js");
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        await researcherCommand({ task: resolvedTask, config, logger });
+      });
+    });
+
+  program
+    .command("architect")
+    .description("Design solution architecture (layers, patterns, contracts)")
+    .argument("[task]", "Task description (or use --task-file)")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
+    .option("--architect <name>", "Override architect agent")
+    .option("--architect-model <name>", "Override architect model")
+    .option("--context <text>", "Additional context (e.g. researcher output)")
+    .option("--json", "Output raw JSON")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "architect", flags, async ({ config, logger }) => {
+        const { resolveTaskInput } = await import("../utils/task-file.js");
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        await architectCommand({ task: resolvedTask, config, logger, context: flags.context, json: flags.json });
+      });
+    });
+
+  program
+    .command("audit")
+    .description("Analyze codebase health (read-only)")
+    .argument("[task]", "Task description. If absent, defaults to a full-codebase analysis. Use --task-file to point at a .md.")
+    .option("--task-file <path>", "Read the task from a file (e.g. .md)")
+    .option("--dimensions <list>", "Comma-separated: security,quality,performance,architecture,testing", "all")
+    .option("--json", "Output raw JSON")
+    .option("--agent-readiness", "Score the repo for AI-agent readability (llms.txt, SKILL.md coverage, page token budgets, robots allowlist, heading hierarchy). LLM-free; uses [path] or cwd as the audit target. See issue #542.")
+    .option("--path <dir>", "Path to audit (used with --agent-readiness; defaults to cwd)")
+    .action(async (task, flags) => {
+      await withConfig(pkgVersion, "audit", flags, async ({ config, logger }) => {
+        let resolvedTask = task;
+        if (flags.taskFile) {
+          const { readTaskFile } = await import("../utils/task-file.js");
+          resolvedTask = await readTaskFile(flags.taskFile, { projectDir: config.projectDir });
+        }
+        await auditCommand({
+          task: resolvedTask || "Analyze the full codebase",
+          config, logger,
+          dimensions: flags.dimensions, json: flags.json,
+          agentReadiness: Boolean(flags.agentReadiness),
+          path: flags.path,
+        });
+      });
+    });
+
+  program
+    .command("resume")
+    .description("Resume a paused session")
+    .argument("<sessionId>")
+    .option("--answer <text>", "Answer to the question that caused the pause")
+    .option("--json", "Output JSON only")
+    .action(async (sessionId, flags) => {
+      await withConfig(pkgVersion, "resume", flags, async ({ config, logger }) => {
+        await resumeCommand({ sessionId, answer: flags.answer, config, logger, flags });
+      });
+    });
+
+  program
+    .command("update")
+    .description("Update karajan-code to the latest version from npm")
+    .action(async () => {
+      // Audit follow-up: was execaCommand (shell parsing). Inputs are
+      // constants today, but the project standard since #555 is execa
+      // with arg arrays (no shell). Migrated for consistency.
+      const { execa } = await import("execa");
+      console.log(`Current version: ${pkgVersion}`);
+      console.log("Checking for updates...");
+      try {
+        const { stdout } = await execa("npm", ["view", "karajan-code", "version"]);
+        const latest = stdout.trim();
+        if (latest === pkgVersion) {
+          console.log(`Already on the latest version (${pkgVersion}).`);
+          return;
+        }
+        console.log(`Updating ${pkgVersion} → ${latest}...`);
+        await execa("npm", ["install", "-g", "karajan-code@latest"], { stdio: "inherit" });
+        console.log(`Updated to ${latest}. Restart Claude to pick up the new MCP server.`);
+      } catch (err) {
+        console.error(`Update failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  program
+    .command("board [action]")
+    .description("Manage HU Board (start|stop|status|open)")
+    .option("--port <number>", "Port (default: 4000)", "4000")
+    .action(async (action = "start", opts) => {
+      await withConfig(pkgVersion, "board", opts, async ({ config, logger }) => {
+        const port = Number(opts.port) || config.hu_board?.port || 4000;
+        await boardCommand({ action, port, logger });
+      });
+    });
+
+  program
+    .command("undo")
+    .description("Revert last pipeline run")
+    .option("--hard", "Discard all changes (default: soft reset, keeps changes staged)")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "undo", flags, async ({ logger }) => {
+        const result = await undoCommand({ hard: !!flags.hard, logger });
+        if (!result.ok) process.exit(1);
+      });
+    });
+
+  program
+    .command("sync")
+    .description("Detect drift between code and the latest plan. Read-only report (issue #540 MVP).")
+    .option("--plan <planId>", "Sync against a specific plan instead of the latest")
+    .option("--json", "Emit machine-readable JSON instead of human output")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "sync", flags, async ({ config, logger }) => {
+        await syncCommand({ config, logger, planId: flags.plan, json: flags.json });
+      });
+    });
+
+  program
+    .command("clean")
+    .description("Garbage-collect stale plans, sessions and HU batches (dry-run by default)")
+    .option("--yes", "Actually delete — without this flag, only prints what would be removed")
+    .option("--nuke", "Retention=0 everywhere + wipe HU board DB. \"I want it all gone\"")
+    .option("--plan-days <n>", "Keep finalised plans (approved/rejected/executed) for N days (default: 30)")
+    .option("--draft-days <n>", "Keep draft plans for N days (default: 60)")
+    .option("--session-days <n>", "Keep finalised sessions for N days (default: 7)")
+    .option("--hu-days <n>", "Keep HU story batches for N days (default: 14)")
+    .action(async (flags) => {
+      await cleanCommand({
+        yes: Boolean(flags.yes),
+        nuke: Boolean(flags.nuke),
+        planDays: flags.planDays ? Number(flags.planDays) : undefined,
+        draftDays: flags.draftDays ? Number(flags.draftDays) : undefined,
+        sessionDays: flags.sessionDays ? Number(flags.sessionDays) : undefined,
+        huDays: flags.huDays ? Number(flags.huDays) : undefined,
+      });
+    });
+}