@karajan-family/code 4.21.0

package/src/prompts/prompt-resolver.js

@@ -0,0 +1,120 @@
+/**
+ * Provider-aware role template resolver.
+ *
+ * Extends the legacy `resolveRoleMdPath()` contract from base-role.js to
+ * support per-provider variants without breaking existing consumers.
+ *
+ * Lookup order (first match wins):
+ *
+ *   1. <projectDir>/.karajan/roles/{role}/{provider}.md   project override, per provider
+ *   2. <projectDir>/.karajan/roles/{role}/default.md      project override, default
+ *   3. <projectDir>/.karajan/roles/{role}.md              project override, legacy flat
+ *   4. <karajanHome>/roles/{role}/{provider}.md           user home, per provider
+ *   5. <karajanHome>/roles/{role}/default.md              user home, default
+ *   6. <karajanHome>/roles/{role}.md                      user home, legacy flat
+ *   7. <built-in>/templates/roles/{role}/{provider}.md    built-in, per provider
+ *   8. <built-in>/templates/roles/{role}/default.md       built-in, default
+ *   9. <built-in>/templates/roles/{role}.md               built-in, legacy flat (back-compat)
+ *
+ * When `provider` is undefined/null the per-provider entries are skipped and
+ * only the default + legacy tiers are tried.
+ *
+ * If a provider is supplied but no per-provider file exists, we emit a
+ * one-time `prompt-resolver:fallback` event/log entry so the user knows their
+ * config asked for a variant that isn't present.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getKarajanHome } from "../utils/paths.js";
+import { getTemplatesRoot } from "../utils/templates-root.js";
+import { normalizeProvider } from "../utils/provider-env.js";
+
+/**
+ * Compute the full list of candidate file paths for a role template.
+ *
+ * @param {string} role                - role slug (e.g. "coder")
+ * @param {string|null|undefined} provider - provider slug or CLI name;
+ *                                           normalized internally
+ * @param {string|null|undefined} projectDir
+ * @returns {{ perProvider: string[], default: string[], legacy: string[], all: string[], provider: string|null }}
+ */
+export function resolveRolePromptPaths(role, provider, projectDir) {
+  if (!role || typeof role !== "string") {
+    throw new Error("resolveRolePromptPaths: role name is required");
+  }
+  const normalized = provider ? normalizeProvider(provider) : null;
+  const canonical = normalized && normalized.length > 0 ? normalized : null;
+
+  const homes = [];
+  if (projectDir) homes.push(path.join(projectDir, ".karajan", "roles"));
+  homes.push(path.join(getKarajanHome(), "roles"));
+
+  homes.push(path.join(getTemplatesRoot(), "roles"));
+
+  const perProvider = [];
+  const defaults = [];
+  const legacy = [];
+
+  for (const home of homes) {
+    if (canonical) {
+      perProvider.push(path.join(home, role, `${canonical}.md`));
+    }
+    defaults.push(path.join(home, role, "default.md"));
+    legacy.push(path.join(home, `${role}.md`));
+  }
+
+  // Interleave: for each home, try per-provider first, then default, then
+  // legacy. This gives the user's project override precedence over the
+  // built-in default even when they only supplied a legacy flat file.
+  const all = [];
+  for (const home of homes) {
+    if (canonical) all.push(path.join(home, role, `${canonical}.md`));
+    all.push(path.join(home, role, "default.md"));
+    all.push(path.join(home, `${role}.md`));
+  }
+
+  return { perProvider, default: defaults, legacy, all, provider: canonical };
+}
+
+/**
+ * Return the contents of the first existing candidate path. Returns null if
+ * no template is found.
+ *
+ * @param {string[]} paths
+ * @returns {Promise<{content: string, path: string}|null>}
+ */
+export async function readFirstExisting(paths) {
+  for (const p of paths) {
+    try {
+      const content = await fs.readFile(p, "utf8");
+      return { content, path: p };
+    } catch { /* file not found, keep trying */ }
+  }
+  return null;
+}
+
+/**
+ * Load role instructions resolved for a specific provider.
+ *
+ * @param {Object} args
+ * @param {string} args.role
+ * @param {string|null|undefined} args.provider
+ * @param {string|null|undefined} args.projectDir
+ * @param {{ warn?: Function, debug?: Function }} [args.logger]
+ * @returns {Promise<{ instructions: string|null, path: string|null, resolvedProvider: string|null, fellBack: boolean }>}
+ */
+export async function loadRoleInstructions({ role, provider, projectDir, logger } = {}) {
+  const { all, provider: canonical } = resolveRolePromptPaths(role, provider, projectDir);
+  const hit = await readFirstExisting(all);
+  if (!hit) {
+    return { instructions: null, path: null, resolvedProvider: canonical, fellBack: !!canonical };
+  }
+  // Detect fallback: if the user asked for a provider but we matched a path
+  // that is NOT a per-provider file, we consider it a fallback and warn.
+  const fellBack = !!canonical && !hit.path.endsWith(`${canonical}.md`);
+  if (fellBack && logger?.debug) {
+    logger.debug(`prompt-resolver: role "${role}" has no "${canonical}" variant, using ${path.basename(hit.path)}`);
+  }
+  return { instructions: hit.content, path: hit.path, resolvedProvider: canonical, fellBack };
+}

package/src/prompts/reviewer.js

@@ -0,0 +1,75 @@
+import { buildRtkInstructions } from "./rtk-snippet.js";
+import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
+import { getLanguageInstruction } from "../utils/locale.js";
+import { section, buildPromptLayout, joinLayout, STABLE, VOLATILE } from "./prompt-layout.js";
+import { clipDiff } from "./diff-clip.js";
+import { buildSplitSignal } from "./split-signal.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 reviewing the code."
+].join(" ");
+
+const SUBAGENT_PREAMBLE_SERENA = [
+  "IMPORTANT: You are running as a Karajan sub-agent.",
+  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
+  "Focus only on reviewing the code."
+].join(" ");
+
+const SERENA_INSTRUCTIONS = [
+  "## Serena MCP — symbol-level code navigation",
+  "You have access to Serena MCP tools for efficient code review.",
+  "Use these to verify context without reading entire files:",
+  "- `find_symbol(name)` — locate a function, class, or variable definition",
+  "- `find_referencing_symbols(name)` — find all callers/references of a symbol",
+  "Use Serena to check how changed symbols are used across the codebase.",
+  "Fall back to reading files only when Serena tools are not sufficient."
+].join("\n");
+
+/**
+ * Build the reviewer prompt as a { stable, volatile } layout (Φ1,
+ * KJC-PCS-0057). The stable block (preamble, mode, scope rules, JSON
+ * schema, serena/rtk, contexts, review rules, skills) is identical
+ * across reviews of the same project, so prefix-caching providers hit
+ * on it; the per-review content (task context + git diff, up to 12 KB
+ * and always different) goes last.
+ */
+export async function buildReviewerPromptLayout({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null, domainContext = null, projectDir = null, language = "en", provider = null }) {
+  const { body: clippedDiff, note: clipNote } = clipDiff(diff);
+  // KJC-BUG-0138: full diff on purpose — the moved-to side survives clipping.
+  const splitSignal = buildSplitSignal(diff);
+
+  const langInstruction = getLanguageInstruction(language);
+  const rtkSnippet = buildRtkInstructions({ rtkAvailable });
+  let skillSection = null;
+  if (projectDir) {
+    const skills = await loadAvailableSkills(projectDir);
+    skillSection = buildSkillSection(skills, { provider, role: "reviewer" });
+  }
+
+  return buildPromptLayout([
+    section(serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE, STABLE),
+    section(langInstruction, STABLE),
+    section(`You are a code reviewer in ${mode} mode.`, STABLE),
+    section("CRITICAL SCOPE RULE: Only review changes that are part of the diff below. Do NOT flag issues in unchanged code, missing features planned for future tasks, or improvements outside the scope of this task. If the diff is correct for what the task asks, approve it — even if the broader codebase has other issues.", STABLE),
+    section("Only block approval for issues IN THE DIFF that are bugs, security vulnerabilities, or clear violations of the review rules.", STABLE),
+    section("Return only one valid JSON object and nothing else.", STABLE),
+    section("JSON schema:", STABLE),
+    section('{"approved":boolean,"blocking_issues":[{"id":string,"severity":"critical|high|medium|low","category":"security|correctness|performance|style|other","file":string,"line":number,"description":string,"suggested_fix":string}],"non_blocking_suggestions":[string],"summary":string,"confidence":number}', STABLE),
+    section(serenaEnabled ? SERENA_INSTRUCTIONS : null, STABLE),
+    section(rtkSnippet, STABLE),
+    section(productContext ? `## Product Context\n${productContext}` : null, STABLE),
+    section(domainContext ? `## Domain Context\n${domainContext}` : null, STABLE),
+    section(`Review rules:\n${reviewRules}`, STABLE),
+    section(skillSection, STABLE),
+    section(`Task context:\n${task}`, VOLATILE),
+    section(`Git diff:\n${clippedDiff}`, VOLATILE),
+    section(clipNote, VOLATILE),
+    section(splitSignal, VOLATILE),
+  ]);
+}
+
+export async function buildReviewerPrompt(options) {
+  return joinLayout(await buildReviewerPromptLayout(options));
+}

package/src/prompts/rtk-snippet.js

@@ -0,0 +1,25 @@
+/**
+ * RTK (Rust Token Killer) prompt instruction snippet.
+ * Injected into coder/reviewer prompts when RTK is detected.
+ */
+const RTK_INSTRUCTIONS = [
+  "## Token Optimization (RTK detected)",
+  "RTK is installed. Prefix ALL Bash tool calls with `rtk` to reduce token usage:",
+  "- Use `rtk git status` instead of `git status`",
+  "- Use `rtk git diff` instead of `git diff`",
+  "- Use `rtk ls` instead of `ls`",
+  "- Use `rtk find` instead of `find`",
+  "- Use `rtk grep` instead of `grep`",
+  "- Use `rtk cat` instead of `cat`",
+  "This does NOT apply to non-Bash tools (Read, Write, Edit, Glob, Grep)."
+].join("\n");
+
+/**
+ * Build RTK instructions when RTK is detected.
+ * @param {{ rtkAvailable?: boolean }} options
+ * @returns {string}
+ */
+export function buildRtkInstructions({ rtkAvailable = false } = {}) {
+  if (!rtkAvailable) return "";
+  return RTK_INSTRUCTIONS;
+}

package/src/prompts/spec-reviewer.js

@@ -0,0 +1,66 @@
+// Prompt builder for the `spec-reviewer` role (KJC-PCS-0048 PR 1).
+// Mirrors src/prompts/triage.js — project-level override at
+// `<projectDir>/.karajan/roles/spec-reviewer.md` is injected via `instructions`.
+
+const SUBAGENT_PREAMBLE = [
+  "IMPORTANT: You are running as a Karajan sub-agent.",
+  "Do NOT execute or plan the task. Do NOT mention Karajan.",
+  "Do NOT use any MCP tools. Your only job is to audit the user's spec.",
+].join(" ");
+
+const VALID_CATEGORIES = [
+  "ambiguity", "missing_scope", "missing_ac", "contradiction",
+  "stack", "assumptions", "out_of_scope",
+];
+
+const SCHEMA_HINT = JSON.stringify({
+  severity: "ok|info|warn|fail",
+  findings: [{
+    id: "F-001",
+    severity: "info|warn|fail",
+    category: VALID_CATEGORIES.join("|"),
+    message: "concrete description",
+    suggestion: "concrete sentence the user can paste",
+  }],
+  reasoning: "one or two sentences",
+}, null, 2);
+
+export function buildSpecReviewerPrompt({ spec, instructions } = {}) {
+  const sections = [SUBAGENT_PREAMBLE];
+  if (instructions) sections.push(instructions);
+  sections.push(
+    "You are the **Spec Reviewer** for Karajan Code.",
+    `Categories (pick one per finding): ${VALID_CATEGORIES.join(", ")}.`,
+    "Severity: `info` (nuance), `warn` (real gap), `fail` (unworkable). Top-level severity is the WORST of any finding (or `ok` if none).",
+    "Return JSON only:",
+    "```json", SCHEMA_HINT, "```",
+    "## Spec to audit", "```", String(spec || "").trim(), "```",
+  );
+  return sections.join("\n");
+}
+
+/**
+ * Build the refine prompt — used when the user picks `[r]efine`. The
+ * agent must rewrite the spec to fix the listed findings, returning
+ * ONLY the rewritten spec (no JSON, no preamble, no fence). The refine
+ * loop will persist this verbatim as `spec-v2.md`.
+ */
+export function buildSpecRefinerPrompt({ originalSpec, findings, instructions } = {}) {
+  const sections = [SUBAGENT_PREAMBLE];
+  if (instructions) sections.push(instructions);
+  const findingsBlock = (findings || []).map((f, i) => {
+    const idx = i + 1;
+    return `${idx}. [${f.severity}/${f.category}] ${f.message}${f.suggestion ? `\n   Fix: ${f.suggestion}` : ""}`;
+  }).join("\n");
+  sections.push(
+    "Your task: produce a rewritten version of the user's spec that addresses every finding listed below.",
+    "Output the rewritten spec verbatim — no JSON, no preamble, no markdown fences, no commentary.",
+    "Preserve the user's intent; do not invent new requirements or scope beyond the existing spec.",
+    "## Original spec", "```", String(originalSpec || "").trim(), "```",
+    "## Findings to address", findingsBlock || "(none — pass-through)",
+    "## Rewritten spec",
+  );
+  return sections.join("\n");
+}
+
+export { VALID_CATEGORIES };

package/src/prompts/split-signal.js

@@ -0,0 +1,82 @@
+/**
+ * split-signal — KJC-BUG-0138 (issue #1364). A file split is not a coverage
+ * deletion, but the reviewer doesn't correlate a file losing content with new
+ * files gaining it (4/13 pure-refactor PRs falsely rejected). Deterministic
+ * pre-analysis, zero LLM: significant removed lines reappearing verbatim among
+ * another file's ADDITIONS in the same diff are moves — when ≥ MIN_RATIO of a
+ * file's removals move, the reviewer gets the correlation as a pipeline note.
+ * Exact `--- a/` / `+++ b/` headers only (BUG-0132: `++content` ≠ header).
+ */
+
+const MIN_REMOVED = 10; // fewer significant removals ⇒ too small to misread
+const MIN_RATIO = 0.5; // below this, the removal is mostly a real removal
+
+// Braces/punctuation reappear by accident — only letter-bearing lines count.
+function significant(text) {
+  const t = text.trim();
+  return t.length >= 10 && /[a-zA-Z]/.test(t);
+}
+
+/** @returns {string|null} pipeline note, or null when nothing moved. Feed the
+ * PRE-CLIPPING diff: the added side must inform even when clipped away. */
+export function buildSplitSignal(diff) {
+  if (!diff) return null;
+  const removedByFile = new Map();
+  const addedByFile = new Map();
+  let src = null;
+  let dst = null;
+  for (const raw of diff.split("\n")) {
+    if (raw.startsWith("--- ")) {
+      src = raw.startsWith("--- a/") ? raw.slice(6) : null;
+      continue;
+    }
+    if (raw.startsWith("+++ ")) {
+      dst = raw.startsWith("+++ b/") ? raw.slice(6) : null;
+      continue;
+    }
+    if (raw.startsWith("+") && dst && significant(raw.slice(1))) {
+      const counts = addedByFile.get(dst) ?? new Map();
+      const t = raw.slice(1).trim();
+      counts.set(t, (counts.get(t) ?? 0) + 1);
+      addedByFile.set(dst, counts);
+    } else if (raw.startsWith("-") && src && significant(raw.slice(1))) {
+      const lines = removedByFile.get(src) ?? [];
+      lines.push(raw.slice(1).trim());
+      removedByFile.set(src, lines);
+    }
+  }
+
+  const findings = [];
+  for (const [file, removed] of removedByFile) {
+    if (removed.length < MIN_REMOVED) continue;
+    const dests = new Map();
+    let moved = 0;
+    for (const text of removed) {
+      for (const [other, counts] of addedByFile) {
+        if (other === file) continue; // in-place edits are not moves
+        const n = counts.get(text) ?? 0;
+        if (n > 0) {
+          counts.set(text, n - 1); // each added line vouches for ONE removal
+          dests.set(other, (dests.get(other) ?? 0) + 1);
+          moved++;
+          break;
+        }
+      }
+    }
+    if (moved / removed.length >= MIN_RATIO) {
+      const where = [...dests.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 4)
+        .map(([d, n]) => `${d} (${n})`)
+        .join(", ");
+      findings.push(`- ${file}: ${moved} of ${removed.length} significant removed lines reappear ADDED in ${where}`);
+    }
+  }
+  if (findings.length === 0) return null;
+
+  return [
+    "NOTE FROM THE KJ PIPELINE (deterministic pre-analysis, not from the author): this diff MOVES content between files:",
+    ...findings,
+    "Moved content is a file split/relocation, not a deletion. Before reporting removed tests or lost coverage, check the ADDED side listed above in this SAME diff. Do not treat moved lines as deleted.",
+  ].join("\n");
+}

package/src/prompts/start-decision.js

@@ -0,0 +1,52 @@
+// KJC-TSK-0569 (Onboard B) — prompt + intent schema for the StartDecidor.
+//
+// The decider only DECIDES (one intent from a closed set); the safe HOW is
+// deterministic (0570 maps the intent to a saved command). Keep this prompt
+// tight: it routes, it never executes.
+const PREAMBLE = [
+  "IMPORTANT: You are running as a Karajan sub-agent (the `kj start` decider).",
+  "Do NOT mention Karajan, do NOT use MCP tools, do NOT execute anything.",
+  "Your only job: read the project assessment and pick ONE next-step intent.",
+].join(" ");
+
+/** Closed set of intents. Anything else degrades to ASK_USER. */
+export const INTENTS = new Set([
+  "ASSESS_ONLY",
+  "RECOMMEND_HARDEN",
+  "RECOMMEND_INDEX",
+  "START_TASK",
+  "PROPOSE_PLAN",
+  "ASK_USER",
+]);
+
+const INTENT_GUIDE = [
+  "- ASSESS_ONLY: the project is healthy and the user gave no goal — just report.",
+  "- RECOMMEND_HARDEN: quality gaps exist (no tests/CI, drifting checks, missing config).",
+  "- RECOMMEND_INDEX: the codebase has no knowledge index yet.",
+  "- START_TASK: the user stated a concrete thing to build or fix.",
+  "- PROPOSE_PLAN: legacy/large project, or a goal that needs a modernization/feature plan.",
+  "- ASK_USER: intent is unclear — ask ONE open question to disambiguate.",
+].join("\n");
+
+/**
+ * @param {{userMessage?: string, assessment?: string, instructions?: string}} input
+ * @returns {string}
+ */
+export function buildStartDecisionPrompt({ userMessage = "", assessment = "", instructions } = {}) {
+  const sections = [PREAMBLE];
+  if (instructions) sections.push(instructions);
+  sections.push(
+    "You route the next step for a project the user just opened with `kj start`.",
+    "## Project assessment (read-only signals)",
+    assessment || "(no assessment available)",
+    "## User goal",
+    userMessage.trim() || "(none given)",
+    "## Intents",
+    INTENT_GUIDE,
+    "Pick the single best intent. Prefer a concrete next step over ASK_USER when the assessment is clear.",
+    "If you pick ASK_USER, put the open question in questionToAsk.",
+    "Return a single valid JSON object and nothing else.",
+    'JSON schema: {"intent":"ASSESS_ONLY|RECOMMEND_HARDEN|RECOMMEND_INDEX|START_TASK|PROPOSE_PLAN|ASK_USER","rationale":string,"questionToAsk":string}',
+  );
+  return sections.join("\n\n");
+}

package/src/prompts/tool-correctness-judge.js

@@ -0,0 +1,31 @@
+// KJC-TSK-0375 — Prompt builder for the ToolCorrectnessJudge role.
+// Inspired by deepeval's tool-correctness metric.
+
+const PREAMBLE = "IMPORTANT: You are running as a Karajan sub-agent. "
+  + "Do NOT use any MCP tools, do NOT mention Karajan. "
+  + "Your job is to judge another agent's tool choices.";
+
+export function buildToolCorrectnessJudgePrompt({ task, toolCalls, instructions }) {
+  const calls = toolCalls
+    .map((c, i) => `${i + 1}. **${c.tool}** — args: ${JSON.stringify(c.args)}`)
+    .join("\n");
+  const body = [
+    "You are the ToolCorrectnessJudge for Karajan Code.",
+    "Input: (a) a task description and (b) the ordered tool calls an LLM coder",
+    "made (Read/Edit/Write/Bash/Glob/Grep/MultiEdit). Judge each call on:",
+    "  - tool choice: right tool for the intent?",
+    "  - argument quality: paths plausible, commands valid, no garbage placeholders?",
+    "Per-call verdict: `correct=true|false` + one-sentence `reason`.",
+    "Aggregate into a single 0-100 score:",
+    "  - 100 = every call right with clean args",
+    "  - 70-99 = mostly right, minor missteps",
+    "  - 40-69 = several wrong choices, budget wasted",
+    "  - 0-39 = predominantly bad, retry advised",
+    "Return a single valid JSON object and nothing else.",
+    'Schema: {"score":0-100,"summary":string,"breakdown":[{"tool":string,"args":object,"correct":boolean,"reason":string}]}',
+  ].join("\n");
+  const sections = [PREAMBLE];
+  if (instructions) sections.push(instructions);
+  sections.push(body, `## Task\n${task}`, `## Tool calls (${toolCalls.length})\n${calls || "(no tool calls captured)"}`);
+  return sections.join("\n\n");
+}

package/src/prompts/triage.js

@@ -0,0 +1,57 @@
+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 task complexity triage."
+].join(" ");
+
+const ROLE_DESCRIPTIONS = [
+  { role: "planner", description: "Generates an implementation plan before coding. Useful for complex multi-file tasks." },
+  { role: "researcher", description: "Investigates the codebase for context before coding. Useful when understanding existing code is needed." },
+  { role: "tester", description: "Runs dedicated testing pass after coding. Ensures tests exist and pass." },
+  { role: "security", description: "Audits code for security vulnerabilities. Checks auth, input validation, injection risks." },
+  { role: "refactorer", description: "Cleans up and refactors code after the main implementation." },
+  { role: "reviewer", description: "Reviews the code diff for quality issues. Standard quality gate." },
+  { role: "architect", description: "Designs solution architecture — layers, patterns, data model, API contracts, tradeoffs. Activate when task creates new module/app, affects data model/APIs, complexity is medium/complex, or design is ambiguous." },
+  { role: "hu-reviewer", description: "Certifies user stories before coding. Activate for medium/complex tasks that need story decomposition." }
+];
+
+export function buildTriagePrompt({ task, instructions, availableRoles }) {
+  const sections = [SUBAGENT_PREAMBLE];
+
+  if (instructions) {
+    sections.push(instructions);
+  }
+
+  const roles = availableRoles || ROLE_DESCRIPTIONS;
+
+  sections.push(
+    "You are a task triage agent for Karajan Code, a multi-agent coding orchestrator.",
+    "Analyze the following task and determine which pipeline roles should be activated.",
+    "## Available Roles",
+    roles.map((r) => `- **${r.role}**: ${r.description}`).join("\n"),
+    "## Decision Guidelines",
+    [
+      "- **planner**: Enable for complex tasks (multi-file, architectural changes, data model changes). Disable for simple fixes.",
+      "- **researcher**: Enable when the task needs codebase context, API understanding, or investigation. Disable for standalone new files.",
+      "- **tester**: Enable for any task with logic, APIs, components, services. Disable ONLY for pure documentation, comments, or CSS-only changes.",
+      "- **security**: Enable for authentication, APIs, user input handling, data access, external integrations. Disable for UI-only or doc changes.",
+      "- **refactorer**: Enable only when explicitly requested or when the task is a refactoring task.",
+      "- **reviewer**: Enable for most tasks as a quality gate. Disable only for trivial, single-line changes.",
+      "- **architect**: Enable when creating new modules/apps, changing data models or APIs, medium/complex tasks, or when design approach is ambiguous. Disable for simple fixes, doc-only, or CSS-only changes.",
+      "- **hu-reviewer**: Enable for medium/complex tasks that benefit from story decomposition and certification. Disable for trivial/simple tasks, doc-only, or CSS-only changes.",
+      "- **audit/analysis taskType**: Set taskType to \"audit\" or \"analysis\" for tasks that only require reading/inspecting code without making changes (e.g., audit, review, analyze, check, verify, inspect, scan, auditar, revisar, analizar, comprobar, verificar, inspeccionar). The coder and reviewer will be skipped entirely for these tasks.",
+      "- **no-code taskType**: Use no-code when the task is about data analysis, document generation, SQL queries, CSV transformation, report generation, or any non-programming task. The coder will generate output (not source code), and TDD/SonarQube will be disabled. The reviewer still runs to validate logic/correctness.",
+      "",
+      "Note: coder is ALWAYS active for coding tasks — you don't need to decide on it. However, for audit/analysis taskTypes the coder is skipped."
+    ].join("\n"),
+    "Classify the task complexity, determine its taskType, recommend only the necessary pipeline roles, and assess whether the task should be decomposed into smaller subtasks.",
+    "Keep the reasoning short and practical.",
+    "Return a single valid JSON object and nothing else.",
+    'JSON schema: {"level":"trivial|simple|medium|complex","roles":["planner|researcher|refactorer|reviewer|tester|security|architect|hu-reviewer"],"taskType":"sw|infra|doc|add-tests|refactor|audit|analysis|no-code","reasoning":string,"shouldDecompose":boolean,"subtasks":string[]}',
+    `## Task\n${task}`
+  );
+
+  return sections.join("\n\n");
+}
+
+export { ROLE_DESCRIPTIONS };

package/src/rag/auto-update.js

@@ -0,0 +1,72 @@
+// KJC-TSK-0455 PR2 — Pre-run drift check + post-merge hook installer.
+// Keeps the local RAG index aligned with HEAD so retrieval never serves
+// stale code without the user having to run `kj rag index` by hand.
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execa } from "execa";
+
+import { openVecStore, projectSlug, getLastIndexedCommit, setLastIndexedCommit } from "./vec-store.js";
+import { indexProjectDelta } from "./indexer.js";
+import { makeGovernedEmbedder } from "./governed-embedder.js";
+
+const HOOK_SRC = resolve(fileURLToPath(import.meta.url), "../../../scripts/git-hooks/post-merge");
+
+export async function maybeAutoUpdate({ projectDir, config, logger = console, flags = {} } = {}) {
+  // commander turns `--no-rag-update` into flags.ragUpdate === false.
+  if (flags?.ragUpdate === false || config?.rag?.autoUpdate?.onRun === false) return { skipped: true };
+  if (!projectDir || !existsSync(join(projectDir, ".git"))) return { skipped: true };
+  let head;
+  try { const r = await execa("git", ["-C", projectDir, "rev-parse", "HEAD"]); head = r.stdout.trim(); }
+  catch { return { skipped: true }; }
+  const slug = projectSlug(projectDir);
+  const db = openVecStore({ dim: config?.rag?.embedder?.dim || 768 });
+  try {
+    const since = getLastIndexedCommit(db, slug);
+    if (!since || since === head) return { skipped: true, head };
+    logger.info?.(`[rag] drift detected (${since.slice(0, 7)} → ${head.slice(0, 7)}); running delta update`);
+    const totals = await indexProjectDelta(projectDir, { db, embedder: makeGovernedEmbedder(config), since, logger });
+    if (totals.head) setLastIndexedCommit(db, slug, totals.head);
+    return { ran: true, totals };
+  } catch (err) {
+    logger.warn?.(`[rag] auto-update failed (${err.message}); continuing without refresh`);
+    return { failed: true, error: err.message };
+  } finally { db.close(); }
+}
+
+// KJC-BUG-0100 — Resolve the hooks dir git actually honours. When a repo is
+// hardened `git config core.hooksPath` points at `.karajan/hooks` and git
+// ignores `.git/hooks/` entirely, so a hook written there never fires.
+export async function resolveHooksDir(projectDir) {
+  if (!existsSync(join(projectDir, ".git"))) throw new Error(`Not a git repository: ${projectDir}`);
+  let hooksPath = "";
+  try {
+    const r = await execa("git", ["-C", projectDir, "config", "--local", "core.hooksPath"]);
+    hooksPath = r.stdout.trim();
+  } catch { /* unset → git uses .git/hooks */ }
+  if (hooksPath) {
+    return { dir: isAbsolute(hooksPath) ? hooksPath : join(projectDir, hooksPath), hooksPath };
+  }
+  return { dir: join(projectDir, ".git", "hooks"), hooksPath: "" };
+}
+
+export async function installPostMergeHook({ projectDir, logger = console } = {}) {
+  const { dir: hooksDir, hooksPath } = await resolveHooksDir(projectDir);
+  if (!existsSync(hooksDir)) mkdirSync(hooksDir, { recursive: true });
+  const target = join(hooksDir, "post-merge");
+  const src = readFileSync(HOOK_SRC, "utf8");
+  if (existsSync(target)) {
+    const current = readFileSync(target, "utf8");
+    // Another kj-managed hook (e.g. harden's post-merge) already reindexes.
+    if (!current.includes("KJC-TSK-0455") && /kj\s+rag\s+index/.test(current)) {
+      return { skipped: true, covered: true, target, hooksPath };
+    }
+    if (!current.includes("KJC-TSK-0455")) {
+      logger.warn?.(`[rag] ${target} already exists and was not installed by kj; leaving untouched`);
+      return { skipped: true, target, hooksPath };
+    }
+  }
+  writeFileSync(target, src);
+  chmodSync(target, 0o755);
+  return { installed: true, target, hooksPath };
+}

package/src/rag/chunker-ast.js

@@ -0,0 +1,56 @@
+// KJC-TSK-0444 — AST-aware source chunker. Replaces the regex-based
+// chunkSource for JS/TS/JSX files. Each top-level declaration (function,
+// class, var/const, export named/default) becomes one chunk whose `text`
+// is the literal source slice [node.start, node.end]. Comments
+// immediately preceding a declaration are folded in (JSDoc + leading
+// line comments) so the chunk reads like a doc-aware snippet.
+//
+// Falls back to the regex chunker if @babel/parser cannot parse the
+// file (errorRecovery: true catches most cases; a hard syntax error
+// returns null so the caller can fall back).
+import { parse } from "@babel/parser";
+
+const PLUGINS = ["typescript", "jsx", "decorators-legacy", "classProperties", "topLevelAwait"];
+
+export function chunkSourceAST(text, { path = "<src>", limit = 800, overlap = 100 } = {}) {
+  let ast;
+  try { ast = parse(text, { sourceType: "module", errorRecovery: true, plugins: PLUGINS }); }
+  catch { return null; }
+  const body = ast?.program?.body;
+  if (!Array.isArray(body) || body.length === 0) return null;
+  const out = [];
+  for (const node of body) {
+    const sym = extractSymbol(node);
+    const start = leadingCommentsStart(node);
+    const slice = text.slice(start, node.end ?? start);
+    if (!slice.trim()) continue;
+    if (slice.length <= limit) out.push({ text: slice, metadata: { source: path, kind: "code", symbol: sym } });
+    else for (const piece of windowText(slice, limit, overlap)) out.push({ text: piece, metadata: { source: path, kind: "code", symbol: sym } });
+  }
+  return out.length === 0 ? null : out;
+}
+
+function extractSymbol(node) {
+  if (node.type === "ExportNamedDeclaration" && node.declaration) return extractSymbol(node.declaration);
+  if (node.type === "ExportDefaultDeclaration") return "default";
+  if (node.id?.name) return node.id.name;
+  if (node.declarations?.[0]?.id?.name) return node.declarations[0].id.name;
+  return null;
+}
+
+function leadingCommentsStart(node) {
+  const lc = node.leadingComments;
+  if (Array.isArray(lc) && lc.length > 0) return lc[0].start ?? node.start ?? 0;
+  return node.start ?? 0;
+}
+
+function windowText(text, limit, overlap) {
+  if (text.length <= limit) return [text];
+  const step = Math.max(1, limit - overlap);
+  const out = [];
+  for (let i = 0; i < text.length; i += step) {
+    out.push(text.slice(i, i + limit));
+    if (i + limit >= text.length) break;
+  }
+  return out;
+}