@karajan-family/code 4.21.0

package/src/config/overrides.js

@@ -0,0 +1,220 @@
+/**
+ * CLI-flag overrides applied on top of a loaded config.
+ *
+ * `applyRunOverrides(config, flags)` takes the merged config from the
+ * loader plus the CLI flags (also forwarded from MCP tool args) and
+ * produces the final config the orchestrator operates on. Overrides are
+ * declarative where possible (ROLE_PROVIDER_FLAGS, ROLE_MODEL_FLAGS,
+ * PIPELINE_ENABLE_FLAGS, SCALAR_FLAGS, UNDEF_CHECK_FLAGS) and imperative
+ * only where the mapping is not 1:1 (methodology, CI, output mode,
+ * deprecated flags like `--no-sonar`).
+ *
+ * Extracted from `src/config.js` in TSK-0332 (Oleada 2 of the v2.7.4
+ * audit refactor). Public API: `applyRunOverrides`. The apply* helpers
+ * are internal.
+ */
+
+import { mergeDeep } from "./loader.js";
+import { DEFAULTS } from "./defaults.js";
+import { safeParseConfig, formatConfigIssues } from "./schema.js";
+
+const ROLE_PROVIDER_FLAGS = [
+  ["planner", "planner"], ["coder", "coder"], ["reviewer", "reviewer"],
+  ["refactorer", "refactorer"], ["solomon", "solomon"], ["researcher", "researcher"],
+  ["tester", "tester"], ["security", "security"], ["triage", "triage"],
+  ["discover", "discover"], ["architect", "architect"]
+];
+
+// Role model flags: [flagName, roleName] — truthy check, String coercion
+const ROLE_MODEL_FLAGS = [
+  ["plannerModel", "planner"], ["coderModel", "coder"], ["reviewerModel", "reviewer"],
+  ["refactorerModel", "refactorer"], ["solomonModel", "solomon"], ["discoverModel", "discover"],
+  ["architectModel", "architect"]
+];
+
+// Pipeline enable flags: [flagName, pipelineKey] — !== undefined check, Boolean coercion
+const PIPELINE_ENABLE_FLAGS = [
+  ["enablePlanner", "planner"], ["enableRefactorer", "refactorer"],
+  ["enableSolomon", "solomon"], ["enableResearcher", "researcher"],
+  ["enableTester", "tester"], ["enableSecurity", "security"], ["enableImpeccable", "impeccable"],
+  ["enablePerf", "perf"],
+  ["enableTriage", "triage"], ["enableDiscover", "discover"],
+  ["enableArchitect", "architect"],
+  ["enableHuReviewer", "hu_reviewer"]
+];
+
+const AUTO_SIMPLIFY_FLAG = "autoSimplify";
+
+// 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; }],
+  ["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); }],
+  ["parallel", (out, v) => { out.session.max_parallel_hus = Number(v); }],
+  ["baseBranch", (out, v) => { out.base_branch = v; }],
+  ["coderFallback", (out, v) => { out.coder_options.fallback_coder = v; }],
+  ["reviewerFallback", (out, v) => { out.reviewer_options.fallback_reviewer = v; }],
+  ["taskType", (out, v) => { out.taskType = String(v); }],
+  ["branchPrefix", (out, v) => { out.git.branch_prefix = String(v); }]
+];
+
+// 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); }],
+  ["autoPr", (out, v) => { out.git.auto_pr = Boolean(v); }],
+  ["autoRebase", (out, v) => { out.git.auto_rebase = Boolean(v); }],
+  ["enableSerena", (out, v) => { out.serena.enabled = Boolean(v); }]
+];
+
+function applyRoleOverrides(out, flags) {
+  // A provider override is always a string (`--security codex`). A bare
+  // boolean means the flag belongs to the command itself (`kj audit
+  // --security`, KJC-TSK-0695) and must not become a provider.
+  for (const [flag, role] of ROLE_PROVIDER_FLAGS) {
+    if (typeof flags[flag] === "string" && flags[flag]) {
+      // A model pin belongs to the provider it was written for — switching
+      // provider by flag drops it (KJC-TSK-0729: codex's pinned mini reached
+      // agy, which answered with its model list instead of a verdict). An
+      // explicit --<role>-model flag re-pins below, after this loop.
+      if (out.roles[role].provider && out.roles[role].provider !== flags[flag]) out.roles[role].model = null;
+      out.roles[role].provider = flags[flag];
+    }
+  }
+  // coder/reviewer also update top-level aliases
+  if (flags.coder) out.coder = flags.coder;
+  if (flags.reviewer) out.reviewer = flags.reviewer;
+
+  for (const [flag, role] of ROLE_MODEL_FLAGS) {
+    if (flags[flag]) out.roles[role].model = String(flags[flag]);
+  }
+  // reviewerModel also updates reviewer_options
+  if (flags.reviewerModel) out.reviewer_options.model = String(flags.reviewerModel);
+}
+
+function applyPipelineOverrides(out, flags) {
+  for (const [flag, key] of PIPELINE_ENABLE_FLAGS) {
+    if (flags[flag] !== undefined) out.pipeline[key].enabled = Boolean(flags[flag]);
+  }
+  if (flags.enableReviewer !== undefined) {
+    out.pipeline.reviewer = out.pipeline.reviewer || {};
+    out.pipeline.reviewer.enabled = Boolean(flags.enableReviewer);
+  }
+}
+
+function applyScalarAndBooleanOverrides(out, flags) {
+  for (const [flag, setter] of SCALAR_FLAGS) {
+    if (flags[flag]) setter(out, flags[flag]);
+  }
+  for (const [flag, setter] of UNDEF_CHECK_FLAGS) {
+    if (flags[flag] !== undefined) setter(out, flags[flag]);
+  }
+}
+
+function applyMethodologyOverride(out, flags) {
+  if (!flags.methodology) return;
+  const methodology = String(flags.methodology).toLowerCase();
+  out.development.methodology = methodology;
+  out.development.require_test_changes = methodology === "tdd";
+}
+
+function applyCiOverride(out, flags) {
+  out.ci = out.ci || { enabled: false };
+  if (flags.enableCi === undefined) return;
+  out.ci.enabled = Boolean(flags.enableCi);
+  // CI requires git automation (commit + push + PR)
+  if (out.ci.enabled) {
+    out.git.auto_commit = true;
+    out.git.auto_push = true;
+    out.git.auto_pr = true;
+  }
+}
+
+function applyOutputModeOverrides(out, flags) {
+  out.output = out.output || {};
+  // --verbose explicitly overrides quiet
+  if (flags.verbose === true) {
+    out.output.quiet = false;
+  } else if (flags.quiet === true) {
+    out.output.quiet = true;
+  }
+  // quiet defaults to true (set in DEFAULTS)
+}
+
+function applyMiscOverrides(out, flags) {
+  if (flags[AUTO_SIMPLIFY_FLAG] !== undefined) out.pipeline.auto_simplify = Boolean(flags[AUTO_SIMPLIFY_FLAG]);
+  // `--no-sonar` and `sonarqube.enabled: false` are deprecated since v2.7.4.
+  // Sonar is intrinsic to Karajan for code tasks (sw/refactor/add-tests) and
+  // skipped for non-code tasks (audit/doc/infra/analysis/no-code) by policy.
+  // The flag is still accepted to avoid breaking scripts; it now emits a
+  // warning at run start and is otherwise ignored. See preflight-checks.js
+  // and flow-runner.js for the actual gate (resolvedPolicies.sonar).
+  // --step: per-iteration supervision gate (KJC-TSK-0628).
+  if (flags.step === true) out.session.iteration_gate = true;
+
+  if (flags.noSonar || flags.sonar === false) {
+    out._deprecated = out._deprecated || {};
+    out._deprecated.noSonarFlag = true;
+  }
+  out.sonarcloud = out.sonarcloud || {};
+  if (flags.enableSonarcloud === true) out.sonarcloud.enabled = true;
+  if (flags.noSonarcloud === true || flags.sonarcloud === false) out.sonarcloud.enabled = false;
+
+  out.planning_game = out.planning_game || {};
+  if (flags.pgTask) out.planning_game.enabled = true;
+  if (flags.pgProject) out.planning_game.project_id = flags.pgProject;
+
+  out.model_selection = out.model_selection || { enabled: true, tiers: {}, role_overrides: {} };
+  if (flags.smartModels === true) out.model_selection.enabled = true;
+  if (flags.smartModels === false || flags.noSmartModels === true) out.model_selection.enabled = false;
+}
+
+export function applyRunOverrides(config, flags) {
+  const out = mergeDeep(config, {});
+  out.coder_options = out.coder_options || {};
+  out.reviewer_options = out.reviewer_options || {};
+  out.session = out.session || {};
+  out.git = out.git || {};
+  out.development = out.development || {};
+  out.sonarqube = out.sonarqube || {};
+  // Precedence: explicit top-level value (including null = opt-out) wins;
+  // the legacy session.max_budget_usd location next; the shipped default
+  // (KJC-TSK-0621: 5) last. When top-level still carries the default, a
+  // session-level value — including an explicit null — takes over.
+  if (out.max_budget_usd === undefined) {
+    out.max_budget_usd = out.session.max_budget_usd !== undefined ? out.session.max_budget_usd : DEFAULTS.max_budget_usd;
+  } else if (out.max_budget_usd === DEFAULTS.max_budget_usd && out.session.max_budget_usd !== undefined) {
+    out.max_budget_usd = out.session.max_budget_usd;
+  }
+  out.budget = mergeDeep(DEFAULTS.budget, out.budget || {});
+  out.roles = mergeDeep(DEFAULTS.roles, out.roles || {});
+  out.pipeline = mergeDeep(DEFAULTS.pipeline, out.pipeline || {});
+  out.serena = out.serena || { enabled: false };
+
+  applyRoleOverrides(out, flags);
+  applyPipelineOverrides(out, flags);
+  applyScalarAndBooleanOverrides(out, flags);
+  applyMethodologyOverride(out, flags);
+  applyCiOverride(out, 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/config/role-resolver.js

@@ -0,0 +1,171 @@
+/**
+ * Role provider/model resolution + config validation.
+ *
+ * `resolveRole(config, role)` returns `{ provider, model }` for a role
+ * given the fully-overridden config, respecting legacy single-provider
+ * shortcuts (`coder: "claude"`) and per-role overrides
+ * (`roles.coder.provider`). Handles model compatibility (gemini models
+ * are dropped from a claude provider, etc.) so the agent subprocess
+ * never sees an incompatible `--model` flag.
+ *
+ * `validateConfig(config, commandName)` is the run-time guard called by
+ * every CLI command before spawning agents: it asserts every required
+ * role has a provider, otherwise throws with an actionable message
+ * ("Set 'roles.planner.provider' or pass '--planner <name>'").
+ *
+ * Extracted from `src/config.js` in TSK-0332 (Oleada 2 of the v2.7.4
+ * audit refactor). Public API: `resolveRole`, `validateConfig`. The
+ * inference helpers are internal.
+ */
+
+/**
+ * Check if a model string is compatible with an agent provider.
+ * Only returns false when the model clearly belongs to a DIFFERENT family.
+ * Returns true if we can't determine or if the model is ambiguous.
+ *
+ * KJC-BUG-0144: exported and family-based — an agent may serve another
+ * family's models (agy is Google's Antigravity, gemini family), and the
+ * same check now guards BaseAgent.getRoleModel so per-role defaults
+ * (e.g. start's haiku) never reach a provider from another family.
+ */
+const AGENT_MODEL_SIGNATURES = {
+  claude: ["claude", "sonnet", "opus", "haiku"],
+  codex: ["o4-", "o3-", "gpt-", "codex"],
+  gemini: ["gemini", "flash-"]
+};
+
+// Single-family CLIs: they only serve their own vendor's models. Agents NOT
+// in this map (aider, opencode, copilot, kimi...) are multi-model hosts —
+// they route to arbitrary models, so any model name is allowed there.
+const AGENT_FAMILY = { claude: "claude", codex: "codex", gemini: "gemini", agy: "gemini" };
+
+function modelFamily(model) {
+  const lower = model.toLowerCase();
+  for (const [family, signatures] of Object.entries(AGENT_MODEL_SIGNATURES)) {
+    if (signatures.some(s => lower.includes(s))) return family;
+  }
+  return null;
+}
+
+export function isModelCompatible(agent, model) {
+  if (!model || !agent) return true;
+  const agentFamily = AGENT_FAMILY[agent];
+  if (!agentFamily) return true; // multi-model host — bring your own model
+  const family = modelFamily(model);
+  if (!family) return true; // ambiguous/custom/local — allow it
+  return family === agentFamily;
+}
+
+// Roles that inherit provider/model from the coder when not explicitly configured
+const CODER_INHERITED_ROLES = new Set([
+  "planner", "refactorer", "solomon", "researcher", "tester", "security",
+  "impeccable", "triage", "discover", "architect", "audit",
+  "hu_reviewer", "hu-reviewer",
+  "spec_reviewer", "spec-reviewer",
+]);
+
+function resolveProvider(roleConfig, role, roles, legacyCoder, legacyReviewer) {
+  if (roleConfig.provider) return roleConfig.provider;
+
+  // If model has "provider/model" format (e.g. "gemini/pro"), extract the provider
+  if (roleConfig.model && roleConfig.model.includes("/")) {
+    const inferredProvider = roleConfig.model.split("/")[0].toLowerCase();
+    if (AGENT_MODEL_SIGNATURES[inferredProvider]) return inferredProvider;
+  }
+
+  if (role === "coder") return legacyCoder;
+  if (role === "reviewer") return legacyReviewer;
+  if (CODER_INHERITED_ROLES.has(role)) return roles.coder?.provider || legacyCoder;
+  return null;
+}
+
+function resolveModel(roleConfig, role, config) {
+  if (roleConfig.model) {
+    // Strip "provider/" prefix from models like "gemini/pro" → "pro"
+    const model = roleConfig.model.includes("/")
+      ? roleConfig.model.split("/").slice(1).join("/")
+      : roleConfig.model;
+    return { model, inherited: false };
+  }
+  if (role === "coder") return { model: config?.coder_options?.model ?? null, inherited: false };
+  if (role === "reviewer") return { model: config?.reviewer_options?.model ?? null, inherited: false };
+  if (CODER_INHERITED_ROLES.has(role)) {
+    const model = config?.coder_options?.model ?? null;
+    return { model, inherited: !!model };
+  }
+  return { model: null, inherited: false };
+}
+
+export function resolveRole(config, role) {
+  const roles = config?.roles || {};
+  const roleConfig = roles[role] || {};
+  const legacyCoder = config?.coder || null;
+  const legacyReviewer = config?.reviewer || null;
+
+  const provider = resolveProvider(roleConfig, role, roles, legacyCoder, legacyReviewer);
+  let { model } = resolveModel(roleConfig, role, config);
+
+  // Drop model if incompatible with the resolved provider (inherited or explicit)
+  if (provider && model && !isModelCompatible(provider, model)) {
+    model = null;
+  }
+
+  return { provider, model };
+}
+
+// Pipeline roles checked when commandName is "run": [pipelineKey, roleName]
+const RUN_PIPELINE_ROLES = [
+  ["reviewer", "reviewer"], ["triage", "triage"], ["planner", "planner"],
+  ["refactorer", "refactorer"], ["researcher", "researcher"],
+  ["tester", "tester"], ["security", "security"], ["impeccable", "impeccable"]
+];
+
+// Direct command-to-role mapping for non-"run" commands
+const COMMAND_ROLE_MAP = {
+  discover: ["discover"],
+  plan: ["planner"],
+  code: ["coder"],
+  review: ["reviewer"]
+};
+
+function requiredRolesFor(commandName, config) {
+  if (commandName !== "run") {
+    return COMMAND_ROLE_MAP[commandName] || [];
+  }
+  const required = ["coder"];
+  for (const [pipelineKey, roleName] of RUN_PIPELINE_ROLES) {
+    const pipelineEntry = config?.pipeline?.[pipelineKey];
+    // reviewer defaults to enabled (only excluded if explicitly false)
+    const isEnabled = pipelineKey === "reviewer"
+      ? pipelineEntry?.enabled !== false
+      : Boolean(pipelineEntry?.enabled);
+    if (isEnabled) required.push(roleName);
+  }
+  return required;
+}
+
+export function validateConfig(config, commandName = "run") {
+  const errors = [];
+  if (!new Set(["paranoid", "strict", "standard", "relaxed", "custom"]).has(config.review_mode)) {
+    errors.push(`Invalid review_mode: ${config.review_mode}`);
+  }
+  if (!new Set(["tdd", "standard"]).has(config.development?.methodology)) {
+    errors.push(`Invalid development.methodology: ${config.development?.methodology}`);
+  }
+
+  const requiredRoles = requiredRolesFor(commandName, config);
+  for (const role of requiredRoles) {
+    const { provider } = resolveRole(config, role);
+    if (!provider) {
+      errors.push(
+        `Missing provider for required role '${role}'. Set 'roles.${role}.provider' or pass '--${role} <name>'`
+      );
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(errors.join("\n"));
+  }
+
+  return config;
+}

package/src/config/schema.js

@@ -0,0 +1,299 @@
+/**
+ * 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"
+);
+
+/**
+ * KJC-TSK-0415: fallback chain. Cuando provider primario hits
+ * QUOTA_EXHAUSTED_* con cooldown > max_wait_hours, switch a fallback.
+ * Recursivo — el fallback puede tener su propio fallback.
+ */
+const RoleFallback = v.looseObject({
+  provider: v.string("fallback.provider required (claude|codex|gemini|opencode|aider)"),
+  model: v.optional(v.nullable(v.string())),
+  max_wait_hours: v.optional(v.pipe(v.number(), v.minValue(0)), 12),
+  // Recursivo. Schema permite cualquier shape compatible con RoleFallback.
+  fallback: v.optional(v.lazy(() => RoleFallback)),
+});
+
+/**
+ * Role entry — provider + model, both nullable. Extra keys allowed.
+ * KJC-TSK-0415: campo fallback opcional para Plan B en quota exhausted.
+ */
+const RoleEntry = v.looseObject({
+  provider: v.optional(v.nullable(v.string())),
+  model: v.optional(v.nullable(v.string())),
+  fallback: v.optional(RoleFallback),
+});
+
+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),
+  start: 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),
+  perf: 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()),
+  // KJC-TSK-0398: opt-in flag; module lands in PR1, integration in PR3.
+  require_red_then_green: 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()),
+}));
+
+/**
+ * skills.addyosmani subtree (KJC-TSK-0327). Governs the addyosmani/agent-skills
+ * catalog provider: enabled flag, refresh TTL and repo URL.
+ */
+const SkillsAddyosmani = v.looseObject({
+  enabled: v.optional(v.boolean()),
+  refreshDays: v.optional(v.pipe(
+    v.number(),
+    v.minValue(0, "skills.addyosmani.refreshDays must be >= 0")
+  )),
+  repoUrl: v.optional(v.string()),
+});
+
+/**
+ * skills.* subtree. `sources` controls which providers Karajan consults and in
+ * what order (addyosmani → openskills → local by default). `mode` is the
+ * existing regex/semantic/auto/none knob from semantic-detector.js.
+ */
+const Skills = v.optional(v.looseObject({
+  mode: v.optional(v.picklist(["auto", "regex", "semantic", "none"], "skills.mode must be one of: auto | regex | semantic | none")),
+  sources: v.optional(v.array(v.string())),
+  addyosmani: v.optional(SkillsAddyosmani),
+}));
+
+/**
+ * KJC-TSK-0407: routing automático de modelos por HU según complexity.
+ *   - by_provider: override de tiers per provider (claude/codex/gemini).
+ *     Cada provider mapea level → modelo. Sobreescribe defaults del router.
+ *   - fixed.coder / fixed.reviewer: si presentes, override TOTAL — todas
+ *     las HUs usan esos modelos independientemente del score. Útil para
+ *     forzar Sonnet en todo el proyecto, por ejemplo.
+ */
+const ModelRouting = v.optional(v.looseObject({
+  by_provider: v.optional(v.record(
+    v.string(),
+    v.looseObject({
+      trivial: v.optional(v.string()),
+      simple: v.optional(v.string()),
+      medium: v.optional(v.string()),
+      complex: v.optional(v.string()),
+    })
+  )),
+  fixed: v.optional(v.looseObject({
+    coder: v.optional(v.nullable(v.string())),
+    reviewer: v.optional(v.nullable(v.string())),
+  })),
+}));
+
+/**
+ * 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")
+  ))),
+  // ENV-D1 (KJC-TSK-0642): where work items live — the integrated HU Board
+  // or the user's Planning Game. The v4 playbook renders per backend.
+  state_backend: v.optional(v.picklist(
+    // KJC-TSK-0709 caught the drift: "external" shipped in v4.5.0 (any
+    // board via the agent's own MCP/tools) but this picklist never learned it.
+    ["hu-board", "planning-game", "external"],
+    "state_backend must be \"hu-board\", \"planning-game\" or \"external\""
+  )),
+  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()),
+  skills: Skills,
+  model_routing: ModelRouting,
+});
+
+/**
+ * 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");
+}