karajan-code 2.32.0 → 2.34.0

package/src/commands/audit.js

@@ -11,6 +11,9 @@ import { withCliRunLog } from "../utils/cli-run-log.js";
 import { createCliProgressReporter } from "../utils/cli-progress.js";
 import { runAgentReadiness, formatAgentReadinessReport } from "../audit/agent-readiness.js";
 import { formatDeterministicSummary } from "../audit/deterministic-summary.js";
+import { runHarnessSection, formatHarnessSection, harnessSummaryForJson } from "../audit/harness-section.js";
+import { persistAuditRun, openAuditHistoryDb, getLatestPreviousRun, getRecentScores } from "../audit/audit-history.js";
+import { computeHistoryDiff, formatHistoryDiff, formatTrendSparkline } from "../audit/audit-history-display.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -191,20 +194,43 @@ async function buildReportHeader(projectDir, invocation) {
   return lines.join("\n");
 }
 
-function describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, json, deterministicOnly, yes }) {
+function composeHistoryBlock({ diffMd, trendMd }) {
+  const parts = [];
+  if (diffMd) parts.push(diffMd);
+  if (trendMd) parts.push(trendMd);
+  return parts.length ? `\n\n## Harness Score History\n${parts.join("\n\n")}` : "";
+}
+
+// KJC-TSK-0473 — Resolve diff vs previous run + optional trend sparkline.
+// Errors silenced: history is a nice-to-have; a broken db must not break audit.
+function loadAuditHistoryContext(projectDir, currentHarness, { showTrend = false } = {}) {
+  let db;
+  try {
+    db = openAuditHistoryDb(projectDir);
+    if (!db) return { diff: null, diffMd: "", trendMd: "" };
+    const previous = currentHarness?.score != null ? getLatestPreviousRun(db, new Date().toISOString()) : null;
+    const diff = currentHarness?.score != null ? computeHistoryDiff(currentHarness, previous) : null;
+    const trendMd = showTrend ? formatTrendSparkline(getRecentScores(db, 10)) : "";
+    return { diff, diffMd: formatHistoryDiff(diff), trendMd };
+  } catch { return { diff: null, diffMd: "", trendMd: "" }; }
+  finally { try { db?.close(); } catch { /* noop */ } }
+}
+
+function describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHarness, json, deterministicOnly, yes }) {
   const parts = ["kj audit"];
   if (task && task !== "Analyze the full codebase") parts.push(JSON.stringify(task));
   if (dimensions && dimensions !== "all") parts.push(`--dimensions=${dimensions}`);
   if (noSonar) parts.push("--no-sonar");
   if (noOsv) parts.push("--no-osv");
   if (noSemgrep) parts.push("--no-semgrep");
+  if (noHarness) parts.push("--no-harness");
   if (deterministicOnly) parts.push("--deterministic-only");
   if (yes) parts.push("--yes");
   if (json) parts.push("--json");
   return parts.join(" ");
 }
 
-export async function auditCommand({ task, config, logger, dimensions, json, agentReadiness, path: pathArg, noSonar = false, noOsv = false, noSemgrep = false, reportFile = null, deterministicOnly = false, yes = false, promptFn = null }) {
+export async function auditCommand({ task, config, logger, dimensions, json, agentReadiness, path: pathArg, noSonar = false, noOsv = false, noSemgrep = false, noHarness = false, reportFile = null, deterministicOnly = false, yes = false, trend = false, promptFn = null }) {
   // --agent-readiness is a STANDALONE, deterministic, LLM-free audit
   // dimension. It scores any third-party repo for AI-agent readability
   // (llms.txt presence, page token budgets, robots allowlist, etc.).
@@ -247,6 +273,27 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
     const deterministicCtx = await role.collectDeterministic(roleInput);
     const deterministicMd = formatDeterministicSummary(deterministicCtx);
 
+    // KJC-TSK-0471 — Harness Scorecard (Docker one-shot, golden metric).
+    // Runs after the deterministic phase, before the LLM. Auto-skipped on
+    // --no-harness or if `runHarnessSection` surfaces an error (graceful
+    // degradation: a missing Docker daemon must not break `kj audit`).
+    let harnessSummary = null;
+    if (!noHarness) {
+      try {
+        harnessSummary = await runHarnessSection({
+          projectDir: config?.projectDir || process.cwd(),
+          harnessConfig: config?.audit?.harness || null,
+        });
+        if (harnessSummary?.ok && !harnessSummary.skipped) {
+          runLog.logText(`[audit] harness score=${harnessSummary.score}/100 grade=${harnessSummary.grade}`);
+        }
+      } catch (e) {
+        harnessSummary = { ok: false, error: e?.message || String(e) };
+        runLog.logText(`[audit] harness skipped: ${harnessSummary.error}`);
+      }
+    }
+    const harnessMd = formatHarnessSection(harnessSummary);
+
     // --json suppresses the interactive flow regardless: it would mangle
     // a script's stdout. JSON consumers always get the full audit unless
     // they explicitly pass deterministicOnly.
@@ -263,23 +310,28 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
     if (!runLlm) {
       // Deterministic-only path. Produce the report from what we already
       // have, persist it (md or json), and exit. Zero tokens spent.
+      const harnessJson = harnessSummaryForJson(harnessSummary);
+      const currentHarness = harnessSummary?.ok && !harnessSummary.skipped ? harnessSummary : null;
+      const history = loadAuditHistoryContext(config?.projectDir || process.cwd(), currentHarness, { showTrend: trend });
+      const historyMd = composeHistoryBlock(history);
       const stdoutContent = json
-        ? JSON.stringify({ deterministic: deterministicCtx, mode: "deterministic-only" }, null, 2)
-        : (deterministicOnly ? deterministicMd : ""); // already printed above when interactive
-      if (json || deterministicOnly) console.log(stdoutContent);
+        ? JSON.stringify({ deterministic: deterministicCtx, harnessScore: harnessJson, harnessScoreDiff: history.diff, mode: "deterministic-only" }, null, 2)
+        : (deterministicOnly ? `${deterministicMd}\n${harnessMd}${historyMd}` : `${harnessMd}${historyMd}`);
+      if (json || deterministicOnly || harnessMd) console.log(stdoutContent);
 
       if (reportPath) {
         let payload;
         if (reportPath.endsWith(".json")) {
-          payload = JSON.stringify({ deterministic: deterministicCtx, mode: "deterministic-only" }, null, 2);
+          payload = JSON.stringify({ deterministic: deterministicCtx, harnessScore: harnessJson, harnessScoreDiff: history.diff, mode: "deterministic-only" }, null, 2);
         } else {
-          const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, json, deterministicOnly, yes }));
-          payload = header + deterministicMd + "\n";
+          const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHarness, json, deterministicOnly, yes }));
+          payload = `${header}${deterministicMd}\n${harnessMd}${historyMd}`;
         }
         await fs.writeFile(reportPath, payload, "utf8");
         runLog.logText(`[audit] report written (deterministic-only) → ${reportPath}`);
         logger.info(`Audit report written: ${reportPath}`);
       }
+      persistAuditRun(config?.projectDir || process.cwd(), { runId: new Date().toISOString(), timestamp: new Date().toISOString(), gitSha: null, harness: harnessSummary?.ok && !harnessSummary.skipped ? harnessSummary : null, rawReportPath: reportPath });
       logger.info("Audit completed (deterministic-only).");
       return { ok: true, mode: "deterministic-only", reportPath: reportPath || undefined };
     }
@@ -306,18 +358,22 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
       runLog.logText(`[audit] usage tokens=${usage.total_tokens} cost=$${(usage.cost_usd ?? 0).toFixed(4)} duration=${(usage.durationMs / 1000).toFixed(1)}s`);
     }
 
+    const harnessJson = harnessSummaryForJson(harnessSummary);
+    const currentHarness = harnessSummary?.ok && !harnessSummary.skipped ? harnessSummary : null;
+    const history = loadAuditHistoryContext(config?.projectDir || process.cwd(), currentHarness, { showTrend: trend });
+    const historyMd = composeHistoryBlock(history);
     let stdoutContent;
     if (json) {
       const jsonPayload = parsed
-        ? { ...parsed, usage: usage || undefined }
-        : { ...roleResult, usage: usage || undefined };
+        ? { ...parsed, harnessScore: harnessJson, harnessScoreDiff: history.diff, usage: usage || undefined }
+        : { ...roleResult, harnessScore: harnessJson, harnessScoreDiff: history.diff, usage: usage || undefined };
       stdoutContent = JSON.stringify(jsonPayload, null, 2);
     } else if (parsed?.summary?.overallHealth) {
-      stdoutContent = formatAudit(parsed, usage);
+      stdoutContent = `${formatAudit(parsed, usage)}\n${harnessMd}${historyMd}`;
     } else if (parsed?.raw) {
-      stdoutContent = parsed.raw + (usage ? `\n\n${formatUsageSummary(usage) || ""}` : "");
+      stdoutContent = parsed.raw + (usage ? `\n\n${formatUsageSummary(usage) || ""}` : "") + `\n${harnessMd}${historyMd}`;
     } else {
-      stdoutContent = roleResult.summary || "Audit complete.";
+      stdoutContent = `${roleResult.summary || "Audit complete."}\n${harnessMd}${historyMd}`;
     }
     console.log(stdoutContent);
 
@@ -325,11 +381,11 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
       let payload;
       if (reportPath.endsWith(".json")) {
         const jsonPayload = parsed
-          ? { ...parsed, usage: usage || undefined }
-          : { ...roleResult, usage: usage || undefined };
+          ? { ...parsed, harnessScore: harnessJson, harnessScoreDiff: history.diff, usage: usage || undefined }
+          : { ...roleResult, harnessScore: harnessJson, harnessScoreDiff: history.diff, usage: usage || undefined };
         payload = JSON.stringify(jsonPayload, null, 2);
       } else {
-        const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, json, deterministicOnly, yes }));
+        const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHarness, json, deterministicOnly, yes }));
         payload = header + stdoutContent + "\n";
       }
       await fs.writeFile(reportPath, payload, "utf8");
@@ -337,6 +393,7 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
       logger.info(`Audit report written: ${reportPath}`);
     }
 
+    persistAuditRun(config?.projectDir || process.cwd(), { runId: new Date().toISOString(), timestamp: new Date().toISOString(), gitSha: null, harness: harnessSummary?.ok && !harnessSummary.skipped ? harnessSummary : null, rawReportPath: reportPath });
     logger.info("Audit completed.");
     return { ok: true, reportPath: reportPath || undefined };
   });

package/src/commands/doctor.js

@@ -19,6 +19,7 @@ import { getConfigFileChecks } from "../checks/config-files.js";
 import { getBinaryChecks } from "../checks/binaries.js";
 import { getSonarChecks } from "../checks/sonar.js";
 import { getOllamaChecks } from "../checks/ollama.js";
+import { getHarnessScorecardChecks } from "../checks/harness-scorecard.js";
 import { getCiChecks } from "../checks/ci.js";
 import { getRtkChecks } from "../checks/rtk.js";
 import { getNodeChecks } from "../checks/node.js";
@@ -54,6 +55,7 @@ function buildChecks(config, { projectOnly = false } = {}) {
     ...getBinaryChecks(),
     ...getSonarChecks(),
     ...getOllamaChecks(),
+    ...getHarnessScorecardChecks(),
     ...getPortChecks(),
     ...getTokenChecks(config),
     ...getMcpHealthChecks(),

package/src/commands/rag.js

@@ -2,10 +2,12 @@
 //   kj rag index [--project <slug>] [--with-sources]
 //   kj rag query <text>   [--scope plans|code|onboarding|all] [--top-k N] [--json]
 // Closes the v2.22.0 RAG MVP end-to-end from the terminal.
-import { openVecStore, countChunks, projectSlug } from "../rag/vec-store.js";
+import { openVecStore, countChunks, projectSlug, getLastIndexedCommit, setLastIndexedCommit } from "../rag/vec-store.js";
 import { makeEmbedder } from "../rag/embedders/factory.js";
-import { indexProject } from "../rag/indexer.js";
+import { indexProject, indexProjectDelta } from "../rag/indexer.js";
 import { query } from "../rag/retriever.js";
+import { installPostMergeHook } from "../rag/auto-update.js";
+import { loadGoldenQueries, runEval } from "../rag/eval.js";
 import { getKarajanHome } from "../utils/paths.js";
 
 function openDb(config) {
@@ -16,15 +18,39 @@ export async function ragIndexCommand({ config, logger, flags = {} }) {
   const projectDir = config?.projectDir || process.cwd();
   const db = openDb(config);
   try {
-    const totals = await indexProject(projectDir, {
-      db, embedder: makeEmbedder(config),
-      karajanHome: getKarajanHome(), logger,
-      withSources: Boolean(flags.withSources),
-    });
+    const slug = projectSlug(projectDir);
+    const embedder = makeEmbedder(config);
+    const sinceFlag = flags.since;
+    // KJC-TSK-0455 — `--since auto` resolves to the last commit we indexed;
+    // an explicit ref is honoured as-is. Without a baseline (first-time
+    // index) we fall back to a full reindex with a friendly warning so the
+    // hook in PR2 stays a no-op-friendly entrypoint.
+    let since = null;
+    if (sinceFlag) {
+      since = sinceFlag === "auto" ? getLastIndexedCommit(db, slug) : sinceFlag;
+      if (!since) logger.warn?.("[rag] --since auto: no previous index recorded; running full index");
+    }
+    let totals;
+    if (since) {
+      try {
+        totals = await indexProjectDelta(projectDir, { db, embedder, since, logger });
+      } catch (err) {
+        logger.warn?.(`[rag] delta index failed (${err.message}); falling back to full index`);
+        totals = null;
+      }
+    }
+    if (!totals) {
+      totals = await indexProject(projectDir, {
+        db, embedder,
+        karajanHome: getKarajanHome(), logger,
+        withSources: Boolean(flags.withSources),
+      });
+    }
+    if (totals.head) setLastIndexedCommit(db, slug, totals.head);
     if (flags.json) {
       process.stdout.write(`${JSON.stringify(totals)}\n`);
     } else {
-      logger.info(`[rag] indexed ${totals.indexed} chunk(s) across ${totals.files} file(s) (${totals.failed} failed)`);
+      logger.info(`[rag] indexed ${totals.indexed} chunk(s) across ${totals.files} file(s) (${totals.failed} failed${totals.deleted ? `, ${totals.deleted} chunks deleted` : ""})`);
     }
     return totals;
   } finally {
@@ -32,6 +58,18 @@ export async function ragIndexCommand({ config, logger, flags = {} }) {
   }
 }
 
+// KJC-TSK-0455 — `kj rag install-hooks` wires the post-merge hook so the
+// local index keeps up after `git pull` / merges. Opt-in to keep us from
+// silently writing under `.git/hooks/`; pre-run drift check covers users
+// who never run it.
+export async function ragInstallHooksCommand({ config, logger, flags = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const res = installPostMergeHook({ projectDir, logger });
+  if (flags.json) process.stdout.write(`${JSON.stringify(res)}\n`);
+  else if (res.installed) logger.info(`[rag] installed post-merge hook at ${res.target}`);
+  return res;
+}
+
 export async function ragQueryCommand({ text, config, logger, flags = {} }) {
   if (!text) throw new Error("kj rag query: text argument required");
   const db = openDb(config);
@@ -75,3 +113,39 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
     db.close();
   }
 }
+
+// KJC-TSK-0483 — `kj rag eval`. Runs the retriever against a golden query
+// set and reports recall@5, recall@10 and MRR per query and aggregated.
+// Exit code != 0 when `--min-recall` is set and the aggregated recall@5
+// falls below the threshold — lets CI fail noisily on retrieval regressions.
+const DEFAULT_GOLDEN = "tests/rag/golden-queries.json";
+export async function ragEvalCommand({ config, logger, flags = {} }) {
+  const db = openDb(config);
+  try {
+    const goldenPath = flags.golden || DEFAULT_GOLDEN;
+    const queries = loadGoldenQueries(goldenPath);
+    const topK = Math.max(1, Number(flags.topK) || 10);
+    const detected = projectSlug(config?.projectDir || process.cwd());
+    const project = flags.project === "all" ? null : (flags.project || detected || null);
+    const embedder = makeEmbedder(config);
+    const runQuery = async (text, k) => query(db, embedder, text, { topK: k, scope: "all", project });
+    const report = await runEval(queries, runQuery, { topK, ks: [5, 10] });
+    if (flags.json) {
+      process.stdout.write(`${JSON.stringify(report)}\n`);
+    } else {
+      logger.info(`[rag-eval] ${report.aggregate.n} queries · recall@5=${report.aggregate.recall["@5"].toFixed(3)} · recall@10=${report.aggregate.recall["@10"].toFixed(3)} · MRR=${report.aggregate.mrr.toFixed(3)}`);
+      for (const r of report.results) {
+        const rank = r.firstRank == null ? "—" : `#${r.firstRank}`;
+        logger.info(`  [${rank}] ${r.query}`);
+      }
+    }
+    const minRecall = Number(flags.minRecall);
+    if (Number.isFinite(minRecall) && report.aggregate.recall["@5"] < minRecall) {
+      logger.error?.(`[rag-eval] recall@5=${report.aggregate.recall["@5"].toFixed(3)} below --min-recall=${minRecall}`);
+      process.exitCode = 1;
+    }
+    return report;
+  } finally {
+    db.close();
+  }
+}

package/src/commands/run.js

@@ -12,6 +12,7 @@ import { resolveRole } from "../config.js";
 import { parseCardId } from "../planning-game/adapter.js";
 import { confirmCwd } from "../utils/cwd-confirm.js";
 import { runSpecReview } from "../spec-review/run-spec-review.js";
+import { maybeAutoUpdate } from "../rag/auto-update.js";
 
 function createCliAskQuestion(opts = {}) {
   const { sessionId = null } = opts;
@@ -84,6 +85,13 @@ export async function runCommandHandler({ task, config, logger, flags }) {
     }
   }
 
+  // KJC-TSK-0455 — Pre-run drift check. Default ON; opt out with
+  // --no-rag-update (flag) or config.rag.autoUpdate.onRun=false. If the
+  // local index is behind HEAD we re-embed the delta before the agents
+  // start reading from the RAG store; on any failure we log and move on
+  // so a broken vector store never blocks a run.
+  await maybeAutoUpdate({ projectDir, config, logger, flags });
+
   // Best-effort session cleanup before starting
   try {
     const { cleanupExpiredSessions } = await import("../session-cleanup.js");

package/src/config/defaults.js

@@ -189,6 +189,13 @@ const DEFAULTS = {
     devtools_mcp: false,
     thresholds: { lcp: 2500, cls: 0.1, inp: 200 }
   },
+  rag: {
+    // KJC-TSK-0455 — Auto-refresh the local RAG index. `onRun` runs a
+    // delta re-index before every `kj run`; `onCommit` is consulted by
+    // `kj rag install-hooks` to decide whether to install the post-merge
+    // hook. Both default ON; flip to false to opt out without uninstalling.
+    autoUpdate: { onCommit: true, onRun: true }
+  },
   telemetry: true,
   guards: {
     output: {

package/src/lang/chunk-go.js

@@ -0,0 +1,94 @@
+// KJC-PCS-0052 PR-B.2.3 — Go source chunker (tree-sitter + regex fallback).
+// Mismo contrato síncrono que chunk-rust: AST si el caller awaited
+// `prepareGo()` antes, regex si no. Top-level: func / method / type.
+//
+// `method_declaration` (con receiver) y `function_declaration` se tratan
+// igual — symbol es el nombre, sin componer "Recv.Method" (coherente con
+// Python: del scope se ocupa la búsqueda semántica, no el chunk).
+// `type_declaration` contiene type_spec(s); usamos el primero como symbol.
+
+import { getLoaded, loadLanguage } from "./tree-sitter-loader.js";
+
+const DEFAULT_LIMIT = 800;
+const DEFAULT_OVERLAP = 100;
+const NAMED_KINDS = new Set([
+  "function_declaration",
+  "method_declaration",
+]);
+const TOP_RE = /^(?:func(?:\s+\([^)]+\))?|type)\s+([A-Za-z_]\w*)/gm;
+
+export async function prepareGo() {
+  return loadLanguage("go");
+}
+
+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;
+}
+
+function symbolForType(node) {
+  for (const spec of node.namedChildren) {
+    if (spec.type === "type_spec" || spec.type === "type_alias") {
+      const nameNode = spec.childForFieldName("name");
+      if (nameNode) return nameNode.text;
+    }
+  }
+  return null;
+}
+
+function marksViaAST(text) {
+  const entry = getLoaded("go");
+  if (!entry) return null;
+  let tree;
+  try {
+    tree = entry.parser.parse(text);
+  } catch {
+    return null;
+  }
+  const marks = [];
+  for (const child of tree.rootNode.namedChildren) {
+    let symbol = null;
+    if (NAMED_KINDS.has(child.type)) {
+      const nameNode = child.childForFieldName("name");
+      if (nameNode) symbol = nameNode.text;
+    } else if (child.type === "type_declaration") {
+      symbol = symbolForType(child);
+    }
+    if (symbol) marks.push({ idx: child.startIndex, symbol });
+  }
+  return marks;
+}
+
+function marksViaRegex(text) {
+  const marks = [];
+  TOP_RE.lastIndex = 0;
+  let m;
+  while ((m = TOP_RE.exec(text)) !== null) marks.push({ idx: m.index, symbol: m[1] });
+  return marks;
+}
+
+export function chunkGo(text, { path = "<src>", limit = DEFAULT_LIMIT, overlap = DEFAULT_OVERLAP } = {}) {
+  const marks = marksViaAST(text) ?? marksViaRegex(text);
+  if (marks.length === 0) {
+    return windowText(text, limit, overlap).map((piece) => ({
+      text: piece,
+      metadata: { source: path, kind: "code", symbol: null, language: "go" },
+    }));
+  }
+  const out = [];
+  for (let i = 0; i < marks.length; i += 1) {
+    const start = marks[i].idx;
+    const end = i + 1 < marks.length ? marks[i + 1].idx : text.length;
+    const body = text.slice(start, end);
+    for (const piece of windowText(body, limit, overlap)) {
+      out.push({ text: piece, metadata: { source: path, kind: "code", symbol: marks[i].symbol, language: "go" } });
+    }
+  }
+  return out;
+}

package/src/lang/chunk-java.js

@@ -0,0 +1,90 @@
+// KJC-PCS-0052 PR-B.2.5 — Java chunker (tree-sitter + regex fallback).
+// Walker 2 niveles: top-level emite class/interface/enum/record; segundo pase
+// desciende al body por method_declaration / constructor_declaration. Symbol
+// sin prefijar (coherente con chunk-go), el RAG ya lleva contexto del fichero.
+
+import { getLoaded, loadLanguage } from "./tree-sitter-loader.js";
+
+const DEFAULT_LIMIT = 800;
+const DEFAULT_OVERLAP = 100;
+const CONTAINER_KINDS = new Set([
+  "class_declaration",
+  "interface_declaration",
+  "enum_declaration",
+  "record_declaration",
+]);
+const MEMBER_KINDS = new Set([
+  "method_declaration",
+  "constructor_declaration",
+]);
+const TOP_RE = /^[ \t]*(?:public\s+|private\s+|protected\s+|static\s+|final\s+|abstract\s+|sealed\s+|non-sealed\s+)*(class|interface|enum|record)\s+([A-Za-z_]\w*)/gm;
+
+export async function prepareJava() {
+  return loadLanguage("java");
+}
+
+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;
+}
+
+function nameOf(node) {
+  const n = node.childForFieldName("name");
+  return n ? n.text : null;
+}
+
+function marksViaAST(text) {
+  const entry = getLoaded("java");
+  if (!entry) return null;
+  let tree;
+  try { tree = entry.parser.parse(text); } catch { return null; }
+  const marks = [];
+  for (const child of tree.rootNode.namedChildren) {
+    if (!CONTAINER_KINDS.has(child.type)) continue;
+    const s = nameOf(child);
+    if (s) marks.push({ idx: child.startIndex, symbol: s });
+    const body = child.childForFieldName("body");
+    if (!body) continue;
+    for (const m of body.namedChildren) {
+      if (!MEMBER_KINDS.has(m.type)) continue;
+      const ms = nameOf(m);
+      if (ms) marks.push({ idx: m.startIndex, symbol: ms });
+    }
+  }
+  marks.sort((a, b) => a.idx - b.idx);
+  return marks;
+}
+
+function marksViaRegex(text) {
+  const marks = [];
+  TOP_RE.lastIndex = 0;
+  let m;
+  while ((m = TOP_RE.exec(text)) !== null) marks.push({ idx: m.index, symbol: m[2] });
+  return marks;
+}
+
+export function chunkJava(text, { path = "<src>", limit = DEFAULT_LIMIT, overlap = DEFAULT_OVERLAP } = {}) {
+  const marks = marksViaAST(text) ?? marksViaRegex(text);
+  if (marks.length === 0) {
+    return windowText(text, limit, overlap).map((piece) => ({
+      text: piece,
+      metadata: { source: path, kind: "code", symbol: null, language: "java" },
+    }));
+  }
+  const out = [];
+  for (let i = 0; i < marks.length; i += 1) {
+    const start = marks[i].idx;
+    const end = i + 1 < marks.length ? marks[i + 1].idx : text.length;
+    const body = text.slice(start, end);
+    for (const piece of windowText(body, limit, overlap)) {
+      out.push({ text: piece, metadata: { source: path, kind: "code", symbol: marks[i].symbol, language: "java" } });
+    }
+  }
+  return out;
+}

package/src/lang/chunk-python.js

@@ -0,0 +1,88 @@
+// KJC-PCS-0052 PR-B.2.1 — Python source chunker (tree-sitter + regex fallback).
+// Top-level `def`/`async def`/`class` siguen siendo la frontera de chunk, pero
+// ahora con dos caminos:
+//   1. AST (web-tree-sitter): si el caller hizo `await preparePython()` antes
+//      del indexado, leemos el árbol y capturamos solo nodos cuyo `parent.type`
+//      es `module` — eso excluye métodos anidados sin depender de la
+//      indentación visual y captura decoradores (`decorated_definition`)
+//      apuntando al def/class real subyacente.
+//   2. Regex: fallback síncrono para entornos sin tree-sitter listo (tests
+//      legacy, primera invocación antes de `preparePython`). Misma semántica
+//      que PR-B.
+//
+// El contrato externo no cambia: `chunkPython(text, opts)` es síncrono y
+// devuelve `[{ text, metadata: { source, kind, symbol, language } }]`.
+
+import { getLoaded, loadLanguage } from "./tree-sitter-loader.js";
+
+const DEFAULT_LIMIT = 800;
+const DEFAULT_OVERLAP = 100;
+const TOP_RE = /^(?:async\s+)?(?:def|class)\s+([A-Za-z_]\w*)/gm;
+
+export async function preparePython() {
+  return loadLanguage("python");
+}
+
+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;
+}
+
+function marksViaAST(text) {
+  const entry = getLoaded("python");
+  if (!entry) return null;
+  let tree;
+  try {
+    tree = entry.parser.parse(text);
+  } catch {
+    return null;
+  }
+  const marks = [];
+  for (const child of tree.rootNode.namedChildren) {
+    let defNode = null;
+    if (child.type === "function_definition" || child.type === "class_definition") {
+      defNode = child;
+    } else if (child.type === "decorated_definition") {
+      defNode = child.childForFieldName("definition");
+    }
+    if (!defNode) continue;
+    const nameNode = defNode.childForFieldName("name");
+    if (!nameNode) continue;
+    marks.push({ idx: child.startIndex, symbol: nameNode.text });
+  }
+  return marks;
+}
+
+function marksViaRegex(text) {
+  const marks = [];
+  TOP_RE.lastIndex = 0;
+  let m;
+  while ((m = TOP_RE.exec(text)) !== null) marks.push({ idx: m.index, symbol: m[1] });
+  return marks;
+}
+
+export function chunkPython(text, { path = "<src>", limit = DEFAULT_LIMIT, overlap = DEFAULT_OVERLAP } = {}) {
+  const marks = marksViaAST(text) ?? marksViaRegex(text);
+  if (marks.length === 0) {
+    return windowText(text, limit, overlap).map((piece) => ({
+      text: piece,
+      metadata: { source: path, kind: "code", symbol: null, language: "python" },
+    }));
+  }
+  const out = [];
+  for (let i = 0; i < marks.length; i += 1) {
+    const start = marks[i].idx;
+    const end = i + 1 < marks.length ? marks[i + 1].idx : text.length;
+    const body = text.slice(start, end);
+    for (const piece of windowText(body, limit, overlap)) {
+      out.push({ text: piece, metadata: { source: path, kind: "code", symbol: marks[i].symbol, language: "python" } });
+    }
+  }
+  return out;
+}