@karajan-family/code 4.21.0

package/src/hu/auto-generator.js

@@ -0,0 +1,358 @@
+/**
+ * HU Auto-Generator — converts triage subtasks (+ researcher/architect context)
+ * into a certified HU batch ready for hu-sub-pipeline execution.
+ *
+ * Input: original task, triage subtasks, detected stack, researcher/architect context.
+ * Output: HU batch with setup HU (when needed), task HUs with per-HU task_type,
+ *         and a dependency graph (setup blocks everything; remaining linear by default).
+ */
+
+/**
+ * Derive a human-readable project name from a task prompt.
+ * Strips common action verbs + stopwords, takes up to 6 meaningful words,
+ * and title-cases the result. Max 60 chars.
+ */
+export function deriveProjectName(originalTask) {
+  if (!originalTask || typeof originalTask !== "string") return "Untitled Project";
+  const STOPWORDS = new Set([
+    "a", "an", "the", "and", "or", "with", "for", "to", "of", "in", "on",
+    "is", "it", "its", "this", "that", "these", "those", "be", "been", "being",
+    "build", "create", "implement", "make", "develop", "add", "set", "up",
+    "setup", "write", "code", "new", "complete", "from", "scratch",
+    "application", "app", "tool", "system", "project", "using", "use",
+    "full", "full-stack", "fullstack", "stack", "based", "simple", "basic"
+  ]);
+  const words = originalTask
+    .toLowerCase()
+    .replaceAll(/[^\p{L}\p{N}\s-]/gu, " ")
+    .split(/\s+/)
+    .filter(w => w && !STOPWORDS.has(w));
+  const meaningful = words.slice(0, 6);
+  if (meaningful.length === 0) {
+    return originalTask.slice(0, 60).trim() || "Untitled Project";
+  }
+  const titled = meaningful
+    .map(w => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+  return titled.length > 60 ? titled.slice(0, 57) + "..." : titled;
+}
+
+/**
+ * Classify a subtask into a Karajan task_type.
+ * Maps free-text subtask descriptions to {infra|sw|add-tests|doc|refactor|nocode}.
+ */
+export function classifyTaskType(text) {
+  if (!text || typeof text !== "string") return "sw";
+  const t = text.toLowerCase();
+  // Order matters: no-code beats infra (Zapier/Notion setups are no-code, not infra)
+  if (/\b(no-code|nocode|zapier|make\.com|airtable|notion)\b/.test(t)) return "nocode";
+  if (/\b(setup|install|init(?:ialize|iate)?|configure|scaffold|bootstrap)\b/.test(t)) return "infra";
+  if (/\b(docker|ci\/cd|pipeline|deploy|workflow\.yml|github actions?)\b/.test(t)) return "infra";
+  if (/\b(tests?|coverage|spec|vitest|jest|mocha|playwright)\b/.test(t) && !/\b(component|feature|endpoint)\b/.test(t)) return "add-tests";
+  if (/\b(readme|docs?|documentation|guide|tutorial)\b/.test(t)) return "doc";
+  if (/\b(refactor|cleanup|reorganiz|restructure|extract)\b/.test(t)) return "refactor";
+  return "sw";
+}
+
+/**
+ * Decide whether a setup HU is needed.
+ * Needed when: project is new OR stack hints suggest new dependencies.
+ */
+export function needsSetupHu({ isNewProject = false, stackHints = [], subtasks = [] }) {
+  if (isNewProject) return true;
+  if (stackHints.length > 0) return true;
+  // Subtasks mentioning a framework/tool suggest fresh setup
+  const setupKeywords = /\b(npm init|package\.json|workspace|monorepo|vite|vitest|express|astro|next\.js|nestjs)\b/i;
+  return subtasks.some(s => setupKeywords.test(s));
+}
+
+// Stack-hint keyword sets. Used by filterConflictingHints (drop hints
+// from other ecosystems once one is detected) and by
+// resolveLanguageFromHints (pick the canonical language for setup +
+// acceptance_tests templates).
+const HINT_NODE = new Set(["express", "vite", "vitest", "jest", "next", "astro", "react", "vue", "svelte", "nestjs", "monorepo", "workspaces"]);
+const HINT_PYTHON = new Set(["pytest", "flask", "fastapi", "django", "numpy", "pandas"]);
+const HINT_GO = new Set(["gin", "fiber", "go"]);
+const HINT_RUST = new Set(["cargo", "rust"]);
+
+/**
+ * Drop hints from OTHER ecosystems when one is clearly the project's.
+ * Symmetric: previously only node-vs-go was filtered, so a Python
+ * project that also had "vitest" in a stale gitignore would still
+ * receive vitest in its setup HU.
+ */
+function filterConflictingHints(hints) {
+  if (!hints || hints.length === 0) return hints;
+  const setForEachLang = [
+    ["python", HINT_PYTHON],
+    ["go", HINT_GO],
+    ["rust", HINT_RUST],
+    ["node", HINT_NODE],
+  ];
+  const present = setForEachLang.filter(([, set]) => hints.some((h) => set.has(h)));
+  if (present.length <= 1) return hints;
+  // First ecosystem found in the original hints order wins. We keep
+  // ambiguous keywords (those not in any set) and the winner's own
+  // keywords; we drop the explicit losers from competing ecosystems.
+  const winnerSet = present[0][1];
+  const losers = present.slice(1).flatMap(([, s]) => [...s]);
+  return hints.filter((h) => winnerSet.has(h) || !losers.includes(h));
+}
+
+/**
+ * Pick the canonical language for setup + acceptance_test templates
+ * based on the (already filtered) stack hints. Falls back to
+ * javascript so existing Node-centric runs keep their previous shape.
+ * @param {string[]} hints
+ * @returns {"python"|"go"|"rust"|"javascript"}
+ */
+function resolveLanguageFromHints(hints) {
+  if (!hints || hints.length === 0) return "javascript";
+  if (hints.some((h) => HINT_PYTHON.has(h))) return "python";
+  if (hints.some((h) => HINT_GO.has(h))) return "go";
+  if (hints.some((h) => HINT_RUST.has(h))) return "rust";
+  return "javascript";
+}
+
+// HU templates per language. The JS template is the legacy default;
+// the others were missing — every autogenerated HU got vitest /
+// npm-install hardcoded acceptance_tests regardless of stack.
+const HU_TEMPLATES = {
+  javascript: {
+    pkgManager: "npm",
+    setupBullets: [
+      "- Create package.json (with workspaces if monorepo detected from stack hints)",
+      "- Install all runtime + dev dependencies listed in stack hints",
+      "- Install test framework WITH coverage reporter (e.g. vitest + @vitest/coverage-v8)",
+      "- Configure vitest.config.js with coverage.enabled = true",
+      "- Create .env.example with placeholder variables",
+    ],
+    setupCriteria: [
+      "npm install succeeds without errors",
+      "npm test runs without error",
+      "npm run test:coverage runs without error",
+      ".env.example exists",
+    ],
+    setupTests: [
+      "npm install --ignore-scripts 2>&1 && echo PASS || echo FAIL",
+      "npx vitest run 2>&1; test $? -eq 0 && echo PASS || echo FAIL",
+      "npx vitest run --coverage 2>&1 | grep -q 'All files\\|% Stmts' && echo PASS || echo FAIL",
+      "test -f .env.example && echo PASS || echo FAIL",
+    ],
+    taskTests: [
+      "npx vitest run 2>&1; test $? -eq 0 && echo PASS || echo FAIL",
+      "npx vitest run --coverage 2>&1 | grep -q 'All files\\|% Stmts' && echo PASS || echo FAIL",
+    ],
+  },
+  python: {
+    pkgManager: "pip",
+    setupBullets: [
+      "- Create pyproject.toml (preferred) or requirements.txt",
+      "- Create a virtual env: python -m venv .venv",
+      "- Install runtime + dev dependencies (pip install -e . or pip install -r requirements.txt)",
+      "- Install pytest with coverage (pip install pytest pytest-cov)",
+      "- Create .env.example with placeholder variables",
+    ],
+    setupCriteria: [
+      "Project metadata file exists (pyproject.toml or requirements.txt)",
+      "pytest runs without error",
+      "pytest --cov reports a total",
+      ".env.example exists",
+    ],
+    setupTests: [
+      "(test -f pyproject.toml || test -f requirements.txt) && echo PASS || echo FAIL",
+      "python -m pytest 2>&1; test $? -eq 0 && echo PASS || echo FAIL",
+      "python -m pytest --cov 2>&1 | grep -q 'TOTAL\\|coverage' && echo PASS || echo FAIL",
+      "test -f .env.example && echo PASS || echo FAIL",
+    ],
+    taskTests: [
+      "python -m pytest 2>&1; test $? -eq 0 && echo PASS || echo FAIL",
+      "python -m pytest --cov 2>&1 | grep -q 'TOTAL\\|coverage' && echo PASS || echo FAIL",
+    ],
+  },
+  go: {
+    pkgManager: "go",
+    setupBullets: [
+      "- Create go.mod with `go mod init <module>`",
+      "- Install dependencies with `go get` per import",
+      "- Create .env.example with placeholder variables",
+    ],
+    setupCriteria: [
+      "go.mod exists",
+      "go test ./... runs without error",
+      "go test -cover reports coverage",
+      ".env.example exists",
+    ],
+    setupTests: [
+      "test -f go.mod && echo PASS || echo FAIL",
+      "go test ./... 2>&1; test $? -eq 0 && echo PASS || echo FAIL",
+      "go test -cover ./... 2>&1 | grep -q 'coverage:' && echo PASS || echo FAIL",
+      "test -f .env.example && echo PASS || echo FAIL",
+    ],
+    taskTests: [
+      "go test ./... 2>&1; test $? -eq 0 && echo PASS || echo FAIL",
+    ],
+  },
+  rust: {
+    pkgManager: "cargo",
+    setupBullets: [
+      "- Initialise the crate with `cargo init`",
+      "- Add dependencies with `cargo add`",
+      "- Create .env.example with placeholder variables",
+    ],
+    setupCriteria: [
+      "Cargo.toml exists",
+      "cargo test runs without error",
+      ".env.example exists",
+    ],
+    setupTests: [
+      "test -f Cargo.toml && echo PASS || echo FAIL",
+      "cargo test 2>&1; test $? -eq 0 && echo PASS || echo FAIL",
+      "test -f .env.example && echo PASS || echo FAIL",
+    ],
+    taskTests: [
+      "cargo test 2>&1; test $? -eq 0 && echo PASS || echo FAIL",
+    ],
+  },
+};
+
+function templateFor(language) {
+  return HU_TEMPLATES[language] || HU_TEMPLATES.javascript;
+}
+
+/**
+ * Build a MINIMAL setup HU — project structure + deps only.
+ * NEVER includes the full original task. The coder must only do setup.
+ */
+function buildSetupHu({ stackHints, language = "javascript" }) {
+  const tpl = templateFor(language);
+  const deps = stackHints.length > 0
+    ? stackHints.map(h => `- ${h}`).join("\n")
+    : "- (auto-detect from subsequent HUs)";
+  const certifiedText = [
+    `**Setup: initialise the ${language} project + install dependencies (package manager: ${tpl.pkgManager}).**`,
+    "",
+    "SCOPE (do ONLY this, nothing else):",
+    ...tpl.setupBullets,
+    "- Verify by running each acceptance_test command below",
+    "",
+    "DO NOT implement any business logic, API routes, components, or features.",
+    "This HU is ONLY project scaffolding.",
+    "",
+    "Stack hints:",
+    deps,
+  ].join("\n");
+  return {
+    id: "HU-01",
+    title: `Setup: ${language} project structure + dependencies`,
+    task_type: "infra",
+    status: "certified",
+    blocked_by: [],
+    certified: { text: certifiedText },
+    acceptance_criteria: tpl.setupCriteria,
+    acceptance_tests: tpl.setupTests,
+  };
+}
+
+/**
+ * Build a MINIMAL task HU — one specific, focused piece of work.
+ * Includes a short goal reference (max 80 chars) NOT the full task.
+ */
+function buildTaskHu({ id, subtask, projectName, blockedBy, language = "javascript" }) {
+  const taskType = classifyTaskType(subtask);
+  const tpl = templateFor(language);
+  const certifiedText = [
+    `**${subtask}**`,
+    "",
+    `Project: ${projectName}`,
+    "",
+    "SCOPE (do ONLY this, nothing else):",
+    `- Implement: ${subtask}`,
+    "- Add unit tests for the new code",
+    "- Run ALL acceptance_tests listed below and ensure they pass",
+    "- Do NOT touch code outside this subtask's scope",
+    "- Target: <200 lines changed (like an atomic PR)",
+  ].join("\n");
+  return {
+    id,
+    title: subtask.length > 80 ? subtask.slice(0, 77) + "..." : subtask,
+    task_type: taskType,
+    status: "certified",
+    blocked_by: blockedBy,
+    certified: { text: certifiedText },
+    acceptance_criteria: [
+      `${subtask} is implemented and working`,
+      "Unit tests cover the new code",
+      "All acceptance_tests pass",
+    ],
+    acceptance_tests: tpl.taskTests,
+  };
+}
+
+/**
+ * Main entry point: generate a certified HU batch from triage output.
+ *
+ * @param {object} input
+ * @param {string} input.originalTask - the user's raw task
+ * @param {string[]} input.subtasks - triage.subtasks array
+ * @param {string[]} [input.stackHints] - detected stack keywords (e.g. ["nodejs", "vitest"])
+ * @param {boolean} [input.isNewProject] - true when projectDir is empty/fresh
+ * @param {string} [input.researcherContext] - researcher output (optional, used for better HU text)
+ * @param {string} [input.architectContext] - architect output (optional, used for dep graph)
+ * @returns {{ stories: object[], total: number, certified: number, generated: true }}
+ */
+export function generateHuBatch({
+  originalTask,
+  subtasks = [],
+  stackHints = [],
+  isNewProject = false,
+  researcherContext = null,
+  architectContext = null,
+  language = null,
+}) {
+  if (!originalTask || typeof originalTask !== "string") {
+    throw new Error("generateHuBatch: originalTask is required");
+  }
+  if (!Array.isArray(subtasks) || subtasks.length === 0) {
+    throw new Error("generateHuBatch: subtasks array is required");
+  }
+
+  const stories = [];
+  const filteredHints = filterConflictingHints(stackHints);
+  const needsSetup = needsSetupHu({ isNewProject, stackHints: filteredHints, subtasks });
+  // Caller may pass a language explicitly (when it has a real
+  // detectProjectStack result from the filesystem); otherwise fall
+  // back to inferring from the hint keywords. Default 'javascript'
+  // matches the previous behaviour for Node-centric runs.
+  const resolvedLanguage = language || resolveLanguageFromHints(filteredHints);
+  let nextId = 1;
+
+  const projectName = deriveProjectName(originalTask);
+
+  if (needsSetup) {
+    stories.push(buildSetupHu({ stackHints: filteredHints, language: resolvedLanguage }));
+    nextId = 2;
+  }
+
+  // Task HUs: linear dependency chain after setup (conservative default).
+  const setupId = needsSetup ? "HU-01" : null;
+  let previousId = setupId;
+  for (const subtask of subtasks) {
+    const id = `HU-${String(nextId).padStart(2, "0")}`;
+    const blockedBy = [];
+    if (setupId) blockedBy.push(setupId);
+    if (previousId && previousId !== setupId) blockedBy.push(previousId);
+    stories.push(buildTaskHu({ id, subtask, projectName, blockedBy, language: resolvedLanguage }));
+    previousId = id;
+    nextId += 1;
+  }
+
+  return {
+    stories,
+    total: stories.length,
+    certified: stories.length,
+    projectName: deriveProjectName(originalTask),
+    generated: true,
+    source: { triage_subtasks: subtasks.length, researcher: Boolean(researcherContext), architect: Boolean(architectContext) }
+  };
+}

package/src/hu/graph.js

@@ -0,0 +1,71 @@
+/**
+ * Topological sort of HU stories respecting blocked_by dependencies.
+ * Returns ordered array of story IDs (dependencies first).
+ * Throws if circular dependency detected.
+ * @param {Array<{id: string, blocked_by?: string[]}>} stories
+ * @returns {string[]} Sorted story IDs.
+ */
+export function topologicalSort(stories) {
+  const ids = new Set(stories.map(s => s.id));
+  const adj = new Map(); // id -> [dependents]
+  const inDegree = new Map();
+
+  for (const s of stories) {
+    adj.set(s.id, []);
+    inDegree.set(s.id, 0);
+  }
+
+  for (const s of stories) {
+    for (const dep of (s.blocked_by || [])) {
+      if (!ids.has(dep)) throw new Error(`Dependency ${dep} not found in batch`);
+      adj.get(dep).push(s.id);
+      inDegree.set(s.id, (inDegree.get(s.id) || 0) + 1);
+    }
+  }
+
+  const queue = [];
+  for (const [id, degree] of inDegree) {
+    if (degree === 0) queue.push(id);
+  }
+
+  const sorted = [];
+  while (queue.length > 0) {
+    const id = queue.shift();
+    sorted.push(id);
+    for (const dependent of adj.get(id)) {
+      inDegree.set(dependent, inDegree.get(dependent) - 1);
+      if (inDegree.get(dependent) === 0) queue.push(dependent);
+    }
+  }
+
+  if (sorted.length !== stories.length) {
+    throw new Error("Circular dependency detected in HU batch");
+  }
+
+  return sorted;
+}
+
+/**
+ * Check if a story is ready to execute (all its dependencies are done).
+ * @param {{blocked_by?: string[]}} story
+ * @param {{stories: Array<{id: string, status: string}>}} batch
+ * @returns {boolean}
+ */
+export function isStoryReady(story, batch) {
+  if (!story.blocked_by || story.blocked_by.length === 0) return true;
+  return story.blocked_by.every(depId => {
+    const dep = batch.stories.find(s => s.id === depId);
+    return dep && dep.status === "done";
+  });
+}
+
+/**
+ * Get next stories ready for execution (certified + all deps done).
+ * @param {{stories: Array<{id: string, status: string, blocked_by?: string[]}>}} batch
+ * @returns {Array<object>} Stories that are certified and whose deps are all done.
+ */
+export function getNextReadyStories(batch) {
+  return batch.stories.filter(s =>
+    s.status === "certified" && isStoryReady(s, batch)
+  );
+}

package/src/hu/lazy-planner.js

@@ -0,0 +1,109 @@
+/**
+ * Lazy HU Planner — refines HUs one at a time using context from completed HUs.
+ *
+ * Instead of fully planning all HUs upfront, only the first HU is decomposed
+ * with full acceptance criteria. Subsequent HUs are refined lazily before
+ * execution, incorporating learnings from previously completed HUs.
+ */
+import { createAgent } from "../agents/index.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
+
+const SUBAGENT_PREAMBLE = [
+  "IMPORTANT: You are running as a Karajan sub-agent.",
+  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
+  "Do NOT use any MCP tools. Focus only on refining the user story."
+].join(" ");
+
+/**
+ * Build a prompt asking the AI to refine an HU based on context from completed HUs.
+ * @param {object} hu - The HU to refine (with at least id, original.text or certified.text).
+ * @param {Array<object>} completedHus - Array of completed HU results with summaries.
+ * @returns {string} The assembled refinement prompt.
+ */
+export function buildRefinementPrompt(hu, completedHus) {
+  const sections = [SUBAGENT_PREAMBLE];
+
+  sections.push("## HU Refinement");
+  sections.push(
+    "You are a senior product owner. Refine the following user story by adding or updating its acceptance criteria.",
+    "Use the context from previously completed HUs to make the criteria more precise and avoid redundant work."
+  );
+
+  if (completedHus.length > 0) {
+    sections.push("## Previously Completed HUs");
+    for (const completed of completedHus) {
+      const title = completed.certified?.title || completed.id;
+      const summary = completed.resultSummary || completed.certified?.text || completed.original?.text || "No summary available";
+      sections.push(`### ${completed.id} — ${title}\nResult: ${summary}`);
+    }
+  }
+
+  const huText = hu.certified?.text || hu.original?.text || `Implement HU ${hu.id}`;
+  sections.push(`## HU to Refine\n### ${hu.id}\n${huText}`);
+
+  sections.push(
+    "Return a single valid JSON object and nothing else.",
+    `JSON schema: {"id":string,"title":string,"text":string,"acceptanceCriteria":[string]}`,
+    "Rules:",
+    "- Keep the same HU id",
+    "- Refine the description to be more specific based on what was learned",
+    "- Add concrete, testable acceptance criteria",
+    "- Avoid repeating work already done in completed HUs",
+    "- The text field should be the full story description ready for implementation"
+  );
+
+  return sections.join("\n\n");
+}
+
+/**
+ * Refine an HU using AI, incorporating context from completed HUs.
+ * @param {object} hu - The HU story object to refine.
+ * @param {Array<object>} completedHus - Completed HU stories with results.
+ * @param {object} config - Pipeline configuration.
+ * @param {object} logger - Logger instance.
+ * @returns {Promise<object>} Updated HU object with refined description and AC.
+ */
+export async function refineHuWithContext(hu, completedHus, config, logger) {
+  const provider = config?.roles?.hu_reviewer?.provider || config?.roles?.coder?.provider || "claude";
+  const prompt = buildRefinementPrompt(hu, completedHus);
+
+  logger.info(`Lazy planner: refining HU ${hu.id} with context from ${completedHus.length} completed HU(s)`);
+
+  const agent = createAgent(provider, config, logger);
+  let result;
+  try {
+    // KJC-TSK-0413 step C
+    result = await withBrainRecovery({
+      agent, taskArgs: { prompt, role: "hu-reviewer" },
+      role: "lazy-planner", provider, logger,
+    });
+  } catch (err) {
+    logger.warn(`Lazy planner: refinement failed for HU ${hu.id}: ${err.message}`);
+    return hu;
+  }
+
+  if (!result.ok) {
+    logger.warn(`Lazy planner: refinement returned not-ok for HU ${hu.id}`);
+    return hu;
+  }
+
+  const parsed = extractFirstJson(result.output);
+  if (!parsed || !parsed.text) {
+    logger.warn(`Lazy planner: could not parse refinement output for HU ${hu.id}`);
+    return hu;
+  }
+
+  // Update the HU with refined content
+  const refined = { ...hu };
+  refined.certified = {
+    ...(hu.certified || {}),
+    text: parsed.text,
+    title: parsed.title || hu.certified?.title || hu.id,
+    acceptanceCriteria: parsed.acceptanceCriteria || []
+  };
+  refined.needsRefinement = false;
+
+  logger.info(`Lazy planner: HU ${hu.id} refined successfully`);
+  return refined;
+}

package/src/hu/model-router.js

@@ -0,0 +1,108 @@
+// KJC-TSK-0405: dado un HU con complexity score, recomienda coder_model y
+// reviewer_model. El reviewer por defecto usa el provider alternativo al
+// coder (cross-provider review) para que dos cabezas distintas miren el
+// código y se detecten más patrones.
+
+const LEVELS = ["trivial", "simple", "medium", "complex"];
+
+// Mapping complexity score numérico → nivel categórico.
+// 1 → trivial, 2 → simple, 3/4 → medium, 5+ → complex.
+const SCORE_TO_LEVEL = {
+  1: "trivial",
+  2: "simple",
+  3: "medium",
+  4: "medium",
+  5: "complex",
+};
+
+// Defaults por provider — alineados con utils/model-selector.js DEFAULTS.
+// opencode: usa "coder" como alias razonable; el usuario suele definir
+// gemma-local/coder, ollama/coder o similar en opencode.json. Override
+// per-tier vía config.model_routing.by_provider.opencode si quieres
+// rutear distinto por complexity (ej. fast para trivial, coder para
+// complex). aider: null porque aider envuelve a otros providers — no
+// tiene "modelos propios". Si el usuario lo elige, debe configurarlo
+// explícito en config.model_routing.by_provider.aider o vía override
+// del modal por HU.
+const DEFAULT_TIERS = {
+  claude: { trivial: "haiku", simple: "haiku", medium: "sonnet", complex: "opus" },
+  codex: { trivial: "o4-mini", simple: "o4-mini", medium: "o4-mini", complex: "o3" },
+  gemini: { trivial: "gemini-2.0-flash", simple: "gemini-2.0-flash", medium: "gemini-2.5-pro", complex: "gemini-2.5-pro" },
+  opencode: { trivial: "coder", simple: "coder", medium: "coder", complex: "coder" },
+  aider: { trivial: null, simple: null, medium: null, complex: null },
+};
+
+// Cross-provider reviewer default: para cada coder provider, qué provider
+// usa el reviewer por defecto. Dos cabezas distintas miran el código.
+// opencode → claude: pattern "local barato escribe + cloud revisa".
+// aider → claude: aider suele correr en un model pequeño, claude verifica.
+const CROSS_PROVIDER_REVIEWER = {
+  claude: "codex",
+  codex: "claude",
+  gemini: "claude",
+  opencode: "claude",
+  aider: "claude",
+};
+
+// KJC-TSK-0405 step 2: heurística para inferir complexity desde
+// task_type cuando el planner no emite un score explícito. Permite
+// que el model-router asigne modelos razonables sin un triage explícito.
+const TASK_TYPE_COMPLEXITY = {
+  sw: "medium",
+  refactor: "medium",
+  "add-tests": "simple",
+  infra: "trivial",
+  doc: "trivial",
+  spike: "complex",
+  research: "complex",
+  audit: "complex",
+  analysis: "medium",
+  "no-code": "trivial",
+};
+
+export function complexityFromTaskType(taskType) {
+  return TASK_TYPE_COMPLEXITY[taskType] || "medium";
+}
+
+export function complexityToLevel(complexity) {
+  if (typeof complexity === "string" && LEVELS.includes(complexity)) return complexity;
+  if (typeof complexity === "number" && SCORE_TO_LEVEL[complexity]) return SCORE_TO_LEVEL[complexity];
+  return "medium";
+}
+
+/**
+ * @param {object} args
+ * @param {string|number} args.complexity - "trivial" | "simple" | "medium" | "complex" | score 1-5
+ * @param {string} args.coderProvider - "claude" | "codex" | "gemini"
+ * @param {object} args.config - karajan config (lee model_routing si existe)
+ * @returns {{ coder_model: string|null, coder_provider: string, reviewer_model: string|null, reviewer_provider: string }}
+ */
+export function recommendModelsForHu({ complexity, coderProvider, config = {} }) {
+  const level = complexityToLevel(complexity);
+  const routing = config.model_routing || {};
+  const fixed = routing.fixed || {};
+
+  // Merge tiers: defaults + user overrides per provider.
+  const tiers = { ...DEFAULT_TIERS };
+  if (routing.by_provider) {
+    for (const [prov, levels] of Object.entries(routing.by_provider)) {
+      tiers[prov] = { ...(tiers[prov] || {}), ...levels };
+    }
+  }
+
+  const coderTier = tiers[coderProvider];
+  const coderAuto = coderTier ? (coderTier[level] || null) : null;
+  const coder_model = fixed.coder || coderAuto;
+
+  const reviewer_provider = CROSS_PROVIDER_REVIEWER[coderProvider] || "claude";
+  const reviewerTier = tiers[reviewer_provider];
+  const reviewerAuto = reviewerTier ? (reviewerTier[level] || null) : null;
+  const reviewer_model = fixed.reviewer || reviewerAuto;
+
+  return {
+    coder_model,
+    coder_provider: coderProvider,
+    reviewer_model,
+    reviewer_provider,
+  };
+}