karajan-code 2.4.1 → 2.6.0

package/src/commands/plan.js

@@ -4,13 +4,11 @@ import { resolveRole } from "../config.js";
 import { buildPlannerPrompt } from "../prompts/planner.js";
 import { parseMaybeJsonString } from "../review/parser.js";
 
+// ---- Formatting helpers ----
+
 function formatPlan(plan) {
   const lines = [];
-
-  if (plan.approach) {
-    lines.push("## Approach", plan.approach, "");
-  }
-
+  if (plan.approach) lines.push("## Approach", plan.approach, "");
   if (plan.steps?.length) {
     lines.push("## Steps");
     for (let i = 0; i < plan.steps.length; i++) {
@@ -20,27 +18,39 @@ function formatPlan(plan) {
     }
     lines.push("");
   }
-
   if (plan.risks?.length) {
     lines.push("## Risks");
-    for (const risk of plan.risks) {
-      lines.push(`- ${risk}`);
-    }
+    for (const risk of plan.risks) lines.push(`- ${risk}`);
     lines.push("");
   }
-
   if (plan.outOfScope?.length) {
     lines.push("## Out of scope");
-    for (const item of plan.outOfScope) {
-      lines.push(`- ${item}`);
-    }
+    for (const item of plan.outOfScope) lines.push(`- ${item}`);
     lines.push("");
   }
+  return lines.join("\n");
+}
 
+function formatHuTable(hus) {
+  if (!hus?.length) return "  (no HUs)";
+  const lines = [];
+  const maxTitle = Math.min(50, Math.max(...hus.map(h => h.title?.length || 0)));
+  lines.push(`  ${"ID".padEnd(30)} ${"Title".padEnd(maxTitle)} ${"Type".padEnd(10)} ${"Status".padEnd(10)} Deps`);
+  lines.push(`  ${"─".repeat(30)} ${"─".repeat(maxTitle)} ${"─".repeat(10)} ${"─".repeat(10)} ${"─".repeat(15)}`);
+  for (const hu of hus) {
+    const title = (hu.title || "").slice(0, maxTitle).padEnd(maxTitle);
+    const deps = (hu.blocked_by || []).join(", ") || "—";
+    lines.push(`  ${hu.id.padEnd(30)} ${title} ${(hu.task_type || "sw").padEnd(10)} ${(hu.status || "?").padEnd(10)} ${deps}`);
+  }
   return lines.join("\n");
 }
 
-export async function planCommand({ task, config, logger, json, context }) {
+// ---- Subcommand handlers ----
+
+/**
+ * kj plan "task" — generate plan + HUs
+ */
+export async function planGenerateCommand({ task, config, logger, json, context }) {
   const plannerRole = resolveRole(config, "planner");
   await assertAgentsAvailable([plannerRole.provider]);
 
@@ -54,43 +64,217 @@ export async function planCommand({ task, config, logger, json, context }) {
     : undefined;
   const result = await planner.runTask({ prompt, role: "planner", silenceTimeoutMs, timeoutMs });
 
-  if (!result.ok) {
-    throw new Error(result.error || result.output || "Planner failed");
-  }
+  if (!result.ok) throw new Error(result.error || result.output || "Planner failed");
 
   const parsed = parseMaybeJsonString(result.output);
 
-  // Persist plan
-  let planId = null;
-  try {
-    const { savePlan } = await import("../plan/plan-store.js");
-    const projectDir = config.projectDir || process.cwd();
-    planId = await savePlan(projectDir, {
-      task,
-      researchContext: null,
-      architectContext: null,
-      plan: parsed || result.output,
-      raw: result.output
+  // Create v2 plan with HUs from planner steps
+  const { createPlanV2 } = await import("../plan/plan-schema.js");
+  const { addHu } = await import("../plan/plan-hu-ops.js");
+  const { savePlan } = await import("../plan/plan-store.js");
+  const { deriveProjectName, classifyTaskType } = await import("../hu/auto-generator.js");
+
+  const projectDir = config.projectDir || process.cwd();
+  const plan = createPlanV2(task);
+  plan.name = deriveProjectName(task);
+  plan.approach = parsed?.approach || (typeof parsed === "string" ? parsed : (typeof result.output === "string" ? result.output : null));
+  plan.risks = parsed?.risks || [];
+  plan.outOfScope = parsed?.outOfScope || [];
+
+  // Convert planner steps → HUs
+  const steps = parsed?.steps || [];
+  let prevId = null;
+  for (const step of steps) {
+    const desc = typeof step === "string" ? step : step.description || step.title || JSON.stringify(step);
+    const hu = addHu(plan, {
+      title: desc.slice(0, 80),
+      task_type: classifyTaskType(desc),
+      scope: desc,
+      blocked_by: prevId ? [prevId] : [],
+      acceptance_tests: [
+        "npx vitest run 2>&1; test $? -eq 0 && echo PASS || echo FAIL"
+      ]
     });
-  } catch (err) {
-    logger.warn(`Plan persistence failed: ${err.message}`);
+    prevId = hu.id;
   }
 
+  const planId = await savePlan(projectDir, plan);
+
   if (json) {
-    const jsonOutput = parsed || result.output;
-    const outputObj = typeof jsonOutput === "object" ? { ...jsonOutput, planId } : { plan: jsonOutput, planId };
-    console.log(JSON.stringify(outputObj, null, 2));
+    console.log(JSON.stringify(plan, null, 2));
     return;
   }
 
   if (parsed?.approach) {
     console.log(formatPlan(parsed));
+  } else if (plan.approach) {
+    console.log(plan.approach);
+  }
+  console.log(`\n## HUs (${plan.hus.length})`);
+  console.log(formatHuTable(plan.hus));
+  console.log(`\nPlan saved: ${planId} (${plan.hus.length} HUs, status: ${plan.status})`);
+  console.log(`Review:  kj plan show ${planId}`);
+  console.log(`Approve: kj plan ready ${planId}`);
+  console.log(`Execute: kj run --plan ${planId} "${task.slice(0, 40)}..."`);
+}
+
+/**
+ * kj plan list
+ */
+export async function planListCommand({ config }) {
+  const { listPlans } = await import("../plan/plan-store.js");
+  const projectDir = config.projectDir || process.cwd();
+  const plans = await listPlans(projectDir);
+
+  if (plans.length === 0) {
+    console.log("No plans found. Create one with: kj plan \"your task\"");
+    return;
+  }
+
+  console.log(`Plans for ${projectDir}:\n`);
+  for (const p of plans) {
+    const husInfo = p.huCount > 0 ? ` (${p.huCount} HUs)` : "";
+    const status = p.status !== "draft" ? ` [${p.status}]` : "";
+    console.log(`  ${p.planId}  ${(p.name || p.task || "").slice(0, 50)}${husInfo}${status}`);
+    console.log(`    Created: ${p.createdAt}`);
+  }
+}
+
+/**
+ * kj plan show <planId>
+ */
+export async function planShowCommand({ config, planId }) {
+  const { loadPlan } = await import("../plan/plan-store.js");
+  const projectDir = config.projectDir || process.cwd();
+  const plan = await loadPlan(projectDir, planId);
+
+  if (!plan) {
+    console.error(`Plan not found: ${planId}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(`Plan: ${plan.planId}`);
+  console.log(`Task: ${plan.task}`);
+  console.log(`Name: ${plan.name || "—"}`);
+  console.log(`Status: ${plan.status}`);
+  console.log(`Version: ${plan.version}`);
+  console.log(`Created: ${plan.createdAt}`);
+
+  if (plan.approach) {
+    console.log(`\n## Approach\n${plan.approach}`);
+  }
+
+  if (plan.hus?.length > 0) {
+    console.log(`\n## HUs (${plan.hus.length})`);
+    console.log(formatHuTable(plan.hus));
   } else {
-    console.log(result.output);
+    console.log("\nNo HUs defined. Add with: kj plan add-hu " + planId);
+  }
+}
+
+/**
+ * kj plan ready <planId>
+ */
+export async function planReadyCommand({ config, planId }) {
+  const { loadPlan, savePlan } = await import("../plan/plan-store.js");
+  const { certifyAllHus } = await import("../plan/plan-hu-ops.js");
+  const { validatePlan } = await import("../plan/plan-schema.js");
+  const projectDir = config.projectDir || process.cwd();
+
+  const plan = await loadPlan(projectDir, planId);
+  if (!plan) { console.error(`Plan not found: ${planId}`); process.exitCode = 1; return; }
+
+  const validation = validatePlan(plan);
+  if (!validation.valid) {
+    console.error("Plan validation failed:");
+    for (const err of validation.errors) console.error(`  - ${err}`);
+    process.exitCode = 1;
+    return;
   }
 
-  if (planId) {
-    console.log(`\nPlan saved: ${planId}`);
-    console.log(`Use it with: kj run --plan ${planId} "<task>"`);
+  if (plan.hus.length === 0) {
+    console.error("Cannot approve a plan with 0 HUs.");
+    process.exitCode = 1;
+    return;
   }
+
+  const count = certifyAllHus(plan);
+  await savePlan(projectDir, plan);
+  console.log(`✅ ${count} HUs certified. Plan status: ready`);
+  console.log(`Execute: kj run --plan ${planId} "${(plan.task || "").slice(0, 40)}..."`);
 }
+
+/**
+ * kj plan validate <planId>
+ */
+export async function planValidateCommand({ config, planId }) {
+  const { loadPlan } = await import("../plan/plan-store.js");
+  const { validatePlan } = await import("../plan/plan-schema.js");
+  const projectDir = config.projectDir || process.cwd();
+
+  const plan = await loadPlan(projectDir, planId);
+  if (!plan) { console.error(`Plan not found: ${planId}`); process.exitCode = 1; return; }
+
+  const result = validatePlan(plan);
+  if (result.valid) {
+    console.log(`✅ Plan ${planId} is valid (${plan.hus.length} HUs, status: ${plan.status})`);
+  } else {
+    console.error(`❌ Plan ${planId} has ${result.errors.length} error(s):`);
+    for (const err of result.errors) console.error(`  - ${err}`);
+    process.exitCode = 1;
+  }
+}
+
+/**
+ * kj plan delete <planId>
+ */
+export async function planDeleteCommand({ config, planId }) {
+  const { deletePlan } = await import("../plan/plan-store.js");
+  const projectDir = config.projectDir || process.cwd();
+  const ok = await deletePlan(projectDir, planId);
+  console.log(ok ? `Deleted: ${planId}` : `Not found: ${planId}`);
+}
+
+/**
+ * kj plan add-hu <planId> --title "..." --type sw --deps hu_xxx
+ */
+export async function planAddHuCommand({ config, planId, title, type, deps, scope }) {
+  const { loadPlan, savePlan } = await import("../plan/plan-store.js");
+  const { addHu } = await import("../plan/plan-hu-ops.js");
+  const projectDir = config.projectDir || process.cwd();
+
+  const plan = await loadPlan(projectDir, planId);
+  if (!plan) { console.error(`Plan not found: ${planId}`); process.exitCode = 1; return; }
+
+  const hu = addHu(plan, {
+    title: title || "New HU",
+    task_type: type || "sw",
+    scope: scope || null,
+    blocked_by: deps ? deps.split(",").map(d => d.trim()) : []
+  });
+
+  await savePlan(projectDir, plan);
+  console.log(`Added: ${hu.id} — ${hu.title}`);
+}
+
+/**
+ * kj plan remove-hu <planId> <huId>
+ */
+export async function planRemoveHuCommand({ config, planId, huId }) {
+  const { loadPlan, savePlan } = await import("../plan/plan-store.js");
+  const { removeHu } = await import("../plan/plan-hu-ops.js");
+  const projectDir = config.projectDir || process.cwd();
+
+  const plan = await loadPlan(projectDir, planId);
+  if (!plan) { console.error(`Plan not found: ${planId}`); process.exitCode = 1; return; }
+
+  const ok = removeHu(plan, huId);
+  if (!ok) { console.error(`HU not found: ${huId}`); process.exitCode = 1; return; }
+
+  await savePlan(projectDir, plan);
+  console.log(`Removed: ${huId}`);
+}
+
+// Keep backward compat — old callers import planCommand
+export const planCommand = planGenerateCommand;

package/src/commands/resume.js

@@ -2,7 +2,7 @@ import { EventEmitter } from "node:events";
 import readline from "node:readline";
 import { resumeFlow } from "../orchestrator.js";
 import { createActivityLog } from "../activity-log.js";
-import { printEvent } from "../utils/display.js";
+import { printEvent } from "../utils/display/event-handlers.js";
 
 function createCliAskQuestion() {
   return async (question, context) => {

package/src/commands/run.js

@@ -3,7 +3,8 @@ import readline from "node:readline";
 import { runFlow } from "../orchestrator.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { createActivityLog } from "../activity-log.js";
-import { printHeader, printEvent } from "../utils/display.js";
+import { printHeader } from "../utils/display/header.js";
+import { printEvent } from "../utils/display/event-handlers.js";
 import { resolveRole } from "../config.js";
 import { parseCardId } from "../planning-game/adapter.js";
 

package/src/commands/skills.js

@@ -0,0 +1,49 @@
+/**
+ * `kj skills` — manage the local OpenSkills cache.
+ *
+ * Subcommands:
+ *   - list         : print cached skills with their age and freshness.
+ *   - clear-cache  : delete all cached metadata (forces re-install on next session).
+ */
+
+import { listCached, clearCache, getCacheRoot, DEFAULT_TTL_MS } from "../skills/skills-cache.js";
+
+function humanAge(cachedAt) {
+  const ms = Date.now() - Date.parse(cachedAt);
+  if (!Number.isFinite(ms) || ms < 0) return "unknown";
+  const days = ms / (24 * 60 * 60 * 1000);
+  if (days < 1) return `${Math.max(1, Math.round(ms / (60 * 60 * 1000)))}h ago`;
+  return `${days.toFixed(1)}d ago`;
+}
+
+export async function skillsCommand({ action = "list" } = {}) {
+  switch (action) {
+    case "list":
+      return listAction();
+    case "clear-cache":
+      return clearAction();
+    default:
+      console.error(`Unknown action: ${action}. Use: list | clear-cache`);
+      return 1;
+  }
+}
+
+async function listAction() {
+  const cache = await listCached();
+  if (cache.length === 0) {
+    console.log(`No cached skills at ${getCacheRoot()}`);
+    return 0;
+  }
+  console.log(`Cached skills (TTL ${Math.round(DEFAULT_TTL_MS / 86400000)}d) at ${getCacheRoot()}:\n`);
+  for (const entry of cache) {
+    const flag = entry.fresh ? "FRESH" : "STALE";
+    console.log(`  ${flag}  ${entry.name}  (${humanAge(entry.cachedAt)})`);
+  }
+  return 0;
+}
+
+async function clearAction() {
+  const { removed } = await clearCache();
+  console.log(`Cleared ${removed} cached skill${removed === 1 ? "" : "s"} from ${getCacheRoot()}`);
+  return 0;
+}

package/src/config/schema.js

@@ -0,0 +1,222 @@
+/**
+ * Central Valibot schema for Karajan's configuration surface (KJC-TSK-0318).
+ *
+ * Origin: this schema is based on Jorge del Casar's original work in PR #379
+ * (closed). The full 650-line mirror-of-DEFAULTS approach he proposed drifted
+ * heavily against `main` by the time it was reviewed, so this file takes the
+ * same intent — validating Karajan config at load time with Valibot — but
+ * narrows the scope to the handful of fields where validation actually
+ * catches real bugs (review_mode, methodology, max_iterations, percentage
+ * budgets, port numbers). Everything else is defined with `v.looseObject` /
+ * `v.unknown()` so existing consumers who touch undeclared keys keep working.
+ *
+ * The runtime DEFAULTS object still lives in src/config.js — it is the source
+ * of truth for default values. This schema exists to reject invalid input
+ * early (e.g. `max_iterations: 0`, `review_mode: "yolo"`) with a clear error,
+ * and to give downstream consumers a typed handle via `KarajanConfig`.
+ *
+ * @typedef {import("valibot").InferOutput<typeof ConfigSchema>} KarajanConfig
+ */
+
+import * as v from "valibot";
+
+/**
+ * Positive integer (>= 1). Used where 0 / negative would be a clear bug
+ * (max_iterations, port, most timeout knobs when they gate the loop itself).
+ */
+const PositiveInt = v.pipe(
+  v.number("must be a number"),
+  v.integer("must be an integer"),
+  v.minValue(1, "must be >= 1")
+);
+
+/**
+ * Non-negative integer (>= 0). Used for retry counts where 0 is a valid
+ * "don't retry" signal.
+ */
+const NonNegativeInt = v.pipe(
+  v.number("must be a number"),
+  v.integer("must be an integer"),
+  v.minValue(0, "must be >= 0")
+);
+
+/**
+ * review_mode picklist — anything outside this set is a typo.
+ */
+const ReviewMode = v.picklist(
+  ["paranoid", "strict", "standard", "relaxed", "custom"],
+  "review_mode must be one of: paranoid | strict | standard | relaxed | custom"
+);
+
+const Methodology = v.picklist(
+  ["tdd", "standard"],
+  "development.methodology must be one of: tdd | standard"
+);
+
+/**
+ * Role entry — provider + model, both nullable. Extra keys allowed.
+ */
+const RoleEntry = v.looseObject({
+  provider: v.optional(v.nullable(v.string())),
+  model: v.optional(v.nullable(v.string())),
+});
+
+const RolesMap = v.optional(v.looseObject({
+  planner: v.optional(RoleEntry),
+  coder: v.optional(RoleEntry),
+  reviewer: v.optional(RoleEntry),
+  refactorer: v.optional(RoleEntry),
+  solomon: v.optional(RoleEntry),
+  researcher: v.optional(RoleEntry),
+  tester: v.optional(RoleEntry),
+  security: v.optional(RoleEntry),
+  impeccable: v.optional(RoleEntry),
+  triage: v.optional(RoleEntry),
+  discover: v.optional(RoleEntry),
+  architect: v.optional(RoleEntry),
+  hu_reviewer: v.optional(RoleEntry),
+}));
+
+const PipelineEntry = v.looseObject({
+  enabled: v.optional(v.boolean()),
+});
+
+const PipelineMap = v.optional(v.looseObject({
+  planner: v.optional(PipelineEntry),
+  refactorer: v.optional(PipelineEntry),
+  solomon: v.optional(PipelineEntry),
+  researcher: v.optional(PipelineEntry),
+  tester: v.optional(PipelineEntry),
+  security: v.optional(PipelineEntry),
+  impeccable: v.optional(PipelineEntry),
+  triage: v.optional(PipelineEntry),
+  discover: v.optional(PipelineEntry),
+  architect: v.optional(PipelineEntry),
+  hu_reviewer: v.optional(PipelineEntry),
+  auto_simplify: v.optional(v.boolean()),
+}));
+
+const Development = v.optional(v.looseObject({
+  methodology: v.optional(Methodology),
+  require_test_changes: v.optional(v.boolean()),
+  test_file_patterns: v.optional(v.array(v.string())),
+  source_file_extensions: v.optional(v.array(v.string())),
+}));
+
+const Git = v.optional(v.looseObject({
+  auto_commit: v.optional(v.boolean()),
+  auto_push: v.optional(v.boolean()),
+  auto_pr: v.optional(v.boolean()),
+  auto_rebase: v.optional(v.boolean()),
+  branch_prefix: v.optional(v.string()),
+}));
+
+const ReviewerOptions = v.optional(v.looseObject({
+  output_format: v.optional(v.string()),
+  require_schema: v.optional(v.boolean()),
+  model: v.optional(v.nullable(v.string())),
+  deterministic: v.optional(v.boolean()),
+  retries: v.optional(NonNegativeInt, 1),
+  fallback_reviewer: v.optional(v.nullable(v.string())),
+}));
+
+const CoderOptions = v.optional(v.looseObject({
+  model: v.optional(v.nullable(v.string())),
+  auto_approve: v.optional(v.boolean()),
+  fallback_coder: v.optional(v.nullable(v.string())),
+}));
+
+const HuBoard = v.optional(v.looseObject({
+  enabled: v.optional(v.boolean()),
+  port: v.optional(v.pipe(
+    v.number("hu_board.port must be a number"),
+    v.integer(),
+    v.minValue(1, "hu_board.port must be >= 1"),
+    v.maxValue(65535, "hu_board.port must be <= 65535")
+  )),
+  auto_start: v.optional(v.boolean()),
+}));
+
+/**
+ * Budget warn threshold: 0-100 percent. Anything outside is nonsense.
+ */
+const Budget = v.optional(v.looseObject({
+  warn_threshold_pct: v.optional(v.pipe(
+    v.number(),
+    v.minValue(0, "budget.warn_threshold_pct must be 0-100"),
+    v.maxValue(100, "budget.warn_threshold_pct must be 0-100")
+  )),
+  currency: v.optional(v.string()),
+  exchange_rate_eur: v.optional(v.number()),
+  pricing: v.optional(v.unknown()),
+}));
+
+/**
+ * Main config schema. `looseObject` lets every consumer that reads an
+ * undeclared key keep working while the schema catches the bugs we care
+ * about.
+ */
+export const ConfigSchema = v.looseObject({
+  coder: v.optional(v.string()),
+  reviewer: v.optional(v.string()),
+  roles: RolesMap,
+  pipeline: PipelineMap,
+  review_mode: v.optional(ReviewMode),
+  max_iterations: v.optional(PositiveInt, 5),
+  hu_max_iterations: v.optional(PositiveInt, 3),
+  max_budget_usd: v.optional(v.nullable(v.pipe(
+    v.number(),
+    v.minValue(0, "max_budget_usd must be >= 0")
+  ))),
+  review_rules: v.optional(v.string()),
+  coder_rules: v.optional(v.string()),
+  base_branch: v.optional(v.string()),
+  coder_options: CoderOptions,
+  reviewer_options: ReviewerOptions,
+  development: Development,
+  git: Git,
+  hu_board: HuBoard,
+  budget: Budget,
+  language: v.optional(v.string()),
+  hu_language: v.optional(v.string()),
+  policies: v.optional(v.record(v.string(), v.unknown())),
+  telemetry: v.optional(v.boolean()),
+});
+
+/**
+ * Parse a raw merged config against the schema. Returns the normalized
+ * config or throws a Valibot ValiError. Call sites should wrap this in a
+ * try/catch that re-throws with a friendlier prefix.
+ *
+ * @param {unknown} input
+ * @returns {KarajanConfig}
+ */
+export function parseConfig(input) {
+  return v.parse(ConfigSchema, input);
+}
+
+/**
+ * Safe variant — returns { success, data } | { success: false, issues } so
+ * callers can decide how to report errors without catching ValiError.
+ * @param {unknown} input
+ */
+export function safeParseConfig(input) {
+  const result = v.safeParse(ConfigSchema, input);
+  if (result.success) return { success: true, data: result.output };
+  return {
+    success: false,
+    issues: result.issues.map(i => ({
+      path: (i.path || []).map(p => p.key).join("."),
+      message: i.message,
+    })),
+  };
+}
+
+/**
+ * Aggregate Valibot issues into a single readable string. Used by loadConfig
+ * to produce actionable error messages instead of the default ValiError dump.
+ * @param {Array<{path: string, message: string}>} issues
+ */
+export function formatConfigIssues(issues) {
+  return issues.map(i => (i.path ? `${i.path}: ${i.message}` : i.message)).join("\n");
+}

package/src/config.js

@@ -3,6 +3,11 @@ import path from "node:path";
 import yaml from "js-yaml";
 import { ensureDir, exists } from "./utils/fs.js";
 import { getKarajanHome } from "./utils/paths.js";
+import { safeParseConfig, formatConfigIssues } from "./config/schema.js";
+
+/**
+ * @typedef {import("./config/schema.js").KarajanConfig} KarajanConfig
+ */
 
 const DEFAULTS = {
   coder: "claude",
@@ -266,6 +271,16 @@ export async function loadConfig(projectDir) {
     merged.budget = mergeDeep(merged.budget || {}, { pricing: projectPricing });
   }
 
+  // KJC-TSK-0318 — schema-validate the merged config so invalid values
+  // (review_mode typos, max_iterations=0, out-of-range ports) surface at
+  // load time with a clear error instead of crashing deep inside the
+  // orchestrator. safeParse + explicit error prefix keeps the message
+  // actionable.
+  const validation = safeParseConfig(merged);
+  if (!validation.success) {
+    throw new Error(`Invalid Karajan config:\n${formatConfigIssues(validation.issues)}`);
+  }
+
   return { config: merged, path: configPath, exists: globalExists, hasProjectConfig: !!projectConfig };
 }
 
@@ -303,10 +318,13 @@ const PIPELINE_ENABLE_FLAGS = [
 
 const AUTO_SIMPLIFY_FLAG = "autoSimplify";
 
-// Scalar flags: [flagName, setter] — truthy check
+// Scalar flags: [flagName, setter] — truthy check.
+// Note: max_iterations was previously here but `0` was silently ignored
+// (truthy check skipped it). It now lives in UNDEF_CHECK_FLAGS so
+// `--max-iterations 0` reaches the schema validator and errors cleanly
+// instead of falling through to the default (KJC-TSK-0318).
 const SCALAR_FLAGS = [
   ["mode", (out, v) => { out.review_mode = v; }],
-  ["maxIterations", (out, v) => { out.max_iterations = Number(v); }],
   ["maxIterationMinutes", (out, v) => { out.session.max_iteration_minutes = Number(v); }],
   ["maxTotalMinutes", (out, v) => { out.session.max_total_minutes = Number(v); }],
   ["checkpointInterval", (out, v) => { out.session.checkpoint_interval_minutes = Number(v); }],
@@ -317,8 +335,11 @@ const SCALAR_FLAGS = [
   ["branchPrefix", (out, v) => { out.git.branch_prefix = String(v); }]
 ];
 
-// Boolean/undefined-check flags: [flagName, setter] — !== undefined check
+// Boolean/undefined-check flags: [flagName, setter] — !== undefined check.
+// These preserve falsy values (false, 0) so --no-rebase correctly sets
+// auto_rebase=false and --reviewer-retries 0 correctly disables retries.
 const UNDEF_CHECK_FLAGS = [
+  ["maxIterations", (out, v) => { out.max_iterations = Number(v); }],
   ["reviewerRetries", (out, v) => { out.reviewer_options.retries = Number(v); }],
   ["autoCommit", (out, v) => { out.git.auto_commit = Boolean(v); }],
   ["autoPush", (out, v) => { out.git.auto_push = Boolean(v); }],
@@ -431,6 +452,14 @@ export function applyRunOverrides(config, flags) {
   applyMiscOverrides(out, flags);
   applyOutputModeOverrides(out, flags);
 
+  // KJC-TSK-0318 — re-run schema validation after overrides so CLI flags
+  // that would produce an invalid config (e.g. --max-iterations 0) fail
+  // fast with the same clear message loadConfig would have produced.
+  const validation = safeParseConfig(out);
+  if (!validation.success) {
+    throw new Error(`Invalid Karajan config after CLI overrides:\n${formatConfigIssues(validation.issues)}`);
+  }
+
   return out;
 }
 

package/src/guards/policy-resolver.js

@@ -1,3 +1,11 @@
+/**
+ * Policy resolution: map task type + config toggles to concrete pipeline
+ * flags (TDD, Sonar, reviewer retries, tests required, coder required, ...).
+ *
+ * @typedef {import("../types/policy.js").ResolvedPolicies} ResolvedPolicies
+ * @typedef {import("../types/config.js").KarajanConfig} KarajanConfig
+ */
+
 export const VALID_TASK_TYPES = new Set(["sw", "infra", "doc", "add-tests", "refactor", "audit", "analysis", "no-code"]);
 
 export const DEFAULT_POLICIES = {