karajan-code 4.62.1 → 4.63.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.62.1",
+  "version": "4.63.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -115,7 +115,7 @@
     "express-rate-limit": "^8.5.0",
     "helmet": "^8.1.0",
     "js-yaml": "^4.2.0",
-    "karajan-core": "^1.5.0",
+    "karajan-core": "^1.6.0",
     "karajan-rag": "^1.2.0",
     "knip": "^6.15.0",
     "madge": "^8.0.0",

package/packages/hu-board/src/plan-mutations.js

@@ -86,6 +86,13 @@ function readPlan(filePath) {
   return JSON.parse(raw);
 }
 
+// KJC-TSK-1166 (ADR 0025): a plan that mirrors the shared board is a view. The truth is
+// in the issues; the board shows it and refuses to edit it, so the two never diverge.
+function mirrorGuard(plan) {
+  if (!plan?.readonly) return null;
+  return { ok: false, error: `this plan mirrors the shared board (${plan.readonly}) and is read-only here: change it with kj hu move` };
+}
+
 function writePlan(filePath, plan) {
   writeJsonAtomicSync(filePath, plan);
 }
@@ -110,6 +117,8 @@ export function setHuStatus({ planId, huId, status, projectId }) {
   if (!filePath) return { ok: false, error: `plan not found: ${planId}` };
 
   const plan = readPlan(filePath);
+  const mirrored = mirrorGuard(plan);
+  if (mirrored) return mirrored;
   if (!Array.isArray(plan.hus)) return { ok: false, error: 'plan has no hus[]' };
 
   const existed = updateHuStatus(plan, huId, status);
@@ -153,6 +162,8 @@ export function setHuFields({ planId, huId, patch, projectId }) {
   if (!filePath) return { ok: false, error: `plan not found: ${planId}` };
 
   const plan = readPlan(filePath);
+  const mirrored = mirrorGuard(plan);
+  if (mirrored) return mirrored;
   if (!Array.isArray(plan.hus)) return { ok: false, error: 'plan has no hus[]' };
 
   // KJC-TSK-0401: si el patch toca blocked_by, validar antes de
@@ -188,6 +199,8 @@ export function setHuFailResult({ planId, huId, blocker, projectId }) {
   const filePath = findPlanFilePath(planId, projectId);
   if (!filePath) return { ok: false, error: `plan not found: ${planId}` };
   const plan = readPlan(filePath);
+  const mirrored = mirrorGuard(plan);
+  if (mirrored) return mirrored;
   if (!Array.isArray(plan.hus)) return { ok: false, error: 'plan has no hus[]' };
   const hu = plan.hus.find(h => h.id === huId);
   if (!hu) return { ok: false, error: `hu not found: ${huId}` };
@@ -220,6 +233,8 @@ export async function revertHuFromSnapshot({ planId, huId, projectId }) {
   const filePath = findPlanFilePath(planId, projectId);
   if (!filePath) return { ok: false, error: `plan not found: ${planId}` };
   const plan = readPlan(filePath);
+  const mirrored = mirrorGuard(plan);
+  if (mirrored) return mirrored;
   const hu = plan.hus?.find(h => h.id === huId);
   if (!hu) return { ok: false, error: `hu not found: ${huId}` };
   const snapshotSha = hu.outcome?.snapshot_sha;
@@ -287,6 +302,8 @@ export function renameProject({ projectId, name }) {
         const filePath = join(projDir, f);
         try {
           const plan = readPlan(filePath);
+          // A mirror of the shared board keeps its own name; the rename goes on with the rest.
+          if (plan.readonly) continue;
           plan.name = trimmed;
           plan.updatedAt = new Date().toISOString();
           writePlan(filePath, plan);
@@ -316,6 +333,8 @@ export function markPlanReady({ planId, projectId }) {
   if (!filePath) return { ok: false, error: `plan not found: ${planId}` };
 
   const plan = readPlan(filePath);
+  const mirrored = mirrorGuard(plan);
+  if (mirrored) return mirrored;
   if (!Array.isArray(plan.hus) || plan.hus.length === 0) {
     return { ok: false, error: 'plan has no hus[]' };
   }
@@ -354,6 +373,8 @@ export function runPlan({ planId, projectId, taskOverride, huIds = null } = {})
   if (!filePath) return { ok: false, error: `plan not found: ${planId}` };
 
   const plan = readPlan(filePath);
+  const mirrored = mirrorGuard(plan);
+  if (mirrored) return mirrored;
   if (!Array.isArray(plan.hus) || plan.hus.length === 0) {
     return { ok: false, error: 'plan has no hus[]' };
   }

package/src/cli/register-meta.js

@@ -353,6 +353,17 @@ export function registerMeta(program, { pkgVersion }) {
         await huCommand({ config, action: "list", flags });
       });
     });
+  // KJC-TSK-1166 (ADR 0025): the HUs created before the shared board, moved to it once.
+  hu.command("migrate")
+    .description("Move every live local HU (pending or running) to the shared board, once: an issue each, status and old id kept")
+    .requiredOption("--to <backend>", "github")
+    .option("--dry-run", "Say what would move, touching nothing")
+    .option("--json", "Machine-readable output")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "hu", flags, async ({ config }) => {
+        await huCommand({ config, action: "migrate", flags });
+      });
+    });
   // KJC-TSK-1163 (ADR 0025): the team board, turned on once per repo.
   hu.command("backend <backend>")
     .description("Turn the repo's HU Board on: github (shared, in GitHub Issues) or local; writes .karajan/board.yml for a PR")
@@ -784,8 +795,8 @@ export function registerMeta(program, { pkgVersion }) {
     // first call). Internally we rebind to `flags.mode` so the handler
     // in src/commands/rag.js stays untouched.
     .option("--rag-mode <mode>", "hybrid (default) | semantic (cosine only) | keyword (BM25 only)", "hybrid")
-    .option("--alpha <n>", "Hybrid weight for semantic component (0..1). Default 0.6", "0.6")
-    .option("--where <clause>", "Metadata filter, e.g. 'symbol=loadConfig' or 'hu_id=HU-003 AND kind=plan'")
+    .option("--alpha <n>", "Deprecated: hybrid fusion is reciprocal rank since 4.63; tune rag.search.rrf_k (default 60) in kj.config.yml", "0.6")
+    .option("--where <clause>", "Metadata filter: 'symbol=loadConfig', 'hu_id=HU-003 AND kind=plan', or a prefix with ~= such as 'source~=src/billing' (relative to the project)")
     .option("--library", "Query the distilled engineering canon (pattern cards shipped with kj + ~/.karajan/library, in ~/.karajan/library.db) instead of the project corpus; a project's own .karajan/library cards live in its index and answer normal queries. Cards carry problem signatures, when-NOT-to-apply and canonical citations (KJC-TSK-0697).")
     .option("--rerank", "Apply cross-encoder rerank to top-K (needs @huggingface/transformers, slower but more precise)")
     .option("--rerank-model <name>", "Cross-encoder model id. Default: Xenova/ms-marco-MiniLM-L-6-v2")
@@ -807,6 +818,8 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--golden <path>", "Path to golden queries JSON (default: tests/rag/golden-queries.json)")
     .option("--top-k <n>", "Number of hits to retrieve per query (default: 10)", "10")
     .option("--min-recall <n>", "Fail (exit 1) if aggregated recall@5 falls below this threshold")
+    .option("--save-baseline <path>", "Write recall@k, MRR and latency to this file as the frozen baseline")
+    .option("--baseline <path>", "Fail (exit 1) if recall@k, MRR or p95 latency got worse than that baseline")
     .option("--project <slug>", "Filter by project slug. Pass 'all' to query across every indexed project.")
     .option("--json", "Emit the full report as JSON")
     .action(async (flags) => {

package/src/commands/hu.js

@@ -13,7 +13,9 @@ import { readIdentity } from "../identity/store.js";
 import { effectiveGitEmail } from "../identity/detect.js";
 import { roleSkills } from "../skills/role-skills.js";
 import { readBoardConfig, setBoardBackend } from "../hu/board-config.js";
-import { createHu, listHus, claim, setStatus, assertNotHeld } from "../hu/github-board.js";
+import { createHu, listHus, claim, setStatus, assertNotHeld, isOffline } from "../hu/github-board.js";
+import { listWithCache, queueMove, flushQueue } from "../hu/team-board-cache.js";
+import { writeTeamMirror } from "../hu/team-board-mirror.js";
 
 // KJC-TSK-0661 (Jorge's friction): every HU records WHO created it — the
 // board must never show work nobody can trace. Host agent env → that agent;
@@ -57,20 +59,91 @@ function linesOf(v) {
 /** KJC-TSK-1163: kj hu add on the shared board; the same no-duplicates rule, checked against the issues. */
 async function addToTeamBoard({ repo, title, flags, deps, emit }) {
   if (flags.id) throw new Error(`--id is not used with the shared board: GitHub gives each HU its id (the issue number)`);
-  const { identical, similar } = findTitleMatches(title, await (deps.listTeamHus ?? listHus)({ repo }));
-  if (identical.length > 0) {
-    throw new Error(`An HU with this title already exists: ${identical[0].short_id} (status: ${identical[0].status}). Work that card or move it with: kj hu move ${identical[0].short_id} <status>`);
-  }
-  if (similar.length > 0) {
-    const candidates = similar.map((h) => `  · ${h.short_id} (${h.status}) "${h.title}"`).join("\n");
-    console.warn("⚠ possible duplicate — check before working it:\n" + candidates);
+  let hu;
+  try {
+    const { identical, similar } = findTitleMatches(title, await (deps.listTeamHus ?? listHus)({ repo }));
+    if (identical.length > 0) {
+      throw new Error(`An HU with this title already exists: ${identical[0].short_id} (status: ${identical[0].status}). Work that card or move it with: kj hu move ${identical[0].short_id} <status>`);
+    }
+    if (similar.length > 0) {
+      const candidates = similar.map((h) => `  · ${h.short_id} (${h.status}) "${h.title}"`).join("\n");
+      console.warn("⚠ possible duplicate — check before working it:\n" + candidates);
+    }
+    hu = await (deps.createTeamHu ?? createHu)({
+      repo, title, acceptanceCriteria: [...linesOf(flags.ac), ...linesOf(flags.criteria)], tests: linesOf(flags.tests), ref: flags.ref ? String(flags.ref).trim() : null,
+    });
+  } catch (err) {
+    // KJC-TSK-1165: an id is only ever minted by GitHub; nothing is created offline.
+    if (isOffline(err)) throw new Error(`creating a HU needs the network: GitHub gives it its id and no local one is made up (${err.message})`, { cause: err });
+    throw err;
   }
-  const hu = await (deps.createTeamHu ?? createHu)({
-    repo, title, acceptanceCriteria: [...linesOf(flags.ac), ...linesOf(flags.criteria)], tests: linesOf(flags.tests), ref: flags.ref ? String(flags.ref).trim() : null,
-  });
   return emit({ ...hu, board: "github", repo }, `✓ HU created: ${hu.short_id} (pending) in the shared board, issue #${hu.number} of ${repo}`);
 }
 
+/**
+ * KJC-TSK-1166: every live local HU (pending or running) becomes an issue with its criteria,
+ * tests and old id; a running one is claimed and moved by whoever migrates. The local card is
+ * marked skipped and points at its issue, so a second run has nothing left to move.
+ */
+async function migrateToTeamBoard({ projectDir, repo, who, dryRun, deps, emit }) {
+  const migrated = [];
+  const skipped = [];
+  for (const meta of await listPlans(projectDir)) {
+    const plan = await loadPlan(projectDir, meta.planId);
+    for (const h of plan.hus || []) {
+      const label = h.short_id || h.id;
+      const unfinished = h.migrated_to && h.migration_pending; // the issue exists, its running state does not yet
+      if (!unfinished && (h.migrated_to || !["pending", "running"].includes(h.status))) { skipped.push(label); continue; }
+      if (dryRun) { migrated.push({ from: label, to: h.migrated_to ?? null, status: h.migration_pending ?? h.status }); continue; }
+      const status = h.migration_pending ?? h.status;
+      if (!h.migrated_to) {
+        const was = `was ${label}`;
+        const issue = await (deps.createTeamHu ?? createHu)({ repo, title: h.title, acceptanceCriteria: h.acceptance_criteria ?? [], tests: h.acceptance_tests ?? [], ref: h.external_ref ? `${h.external_ref} · ${was}` : was });
+        // Persisted the moment the issue exists: a retry after a failure further on never
+        // creates it twice; what is still owed to it (its running state) is remembered.
+        h.migrated_to = issue.short_id;
+        h.external_ref = [h.external_ref, issue.short_id].filter(Boolean).join(" · ");
+        if (status === "running") h.migration_pending = "running";
+        await savePlan(projectDir, plan);
+      }
+      if (h.migration_pending === "running") {
+        const number = Number(h.migrated_to.slice(3));
+        await (deps.claimTeamHu ?? claim)({ repo, number, who, release: false });
+        await (deps.setTeamStatus ?? setStatus)({ repo, number, status: "running" });
+        delete h.migration_pending;
+      }
+      updateHuStatus(plan, h.id, "skipped");
+      await savePlan(projectDir, plan);
+      migrated.push({ from: label, to: h.migrated_to, status });
+    }
+  }
+  const verb = dryRun ? "would move" : "moved";
+  const lines = migrated.map((m) => `  ${m.from} → ${m.to ?? "(new issue)"} [${m.status}]`).join("\n");
+  const detail = lines ? "\n" + lines : "";
+  return emit({ migrated, skipped, dryRun }, `✓ ${verb} ${migrated.length} HU(s) to the shared board of ${repo}${detail}\n  skipped ${skipped.length} (finished, discarded or already moved)`);
+}
+
+/** KJC-TSK-1165: apply the moves queued offline; conflicts are said, never forced; still offline is silent. */
+async function applyQueuedMoves({ projectDir, repo, deps }) {
+  let now = null; // status of every HU as GitHub has it, read once, kept up to date as moves apply
+  const apply = async (op) => {
+    now ??= new Map((await (deps.listTeamHus ?? listHus)({ repo })).map((h) => [h.number, h.status]));
+    // The HU moved while this clone was offline: the newer state wins, the queued move is a conflict.
+    if (op.expected && now.get(op.number) !== op.expected) {
+      const err = new Error(`HU-${op.number} is ${now.get(op.number) ?? "gone"} now and was ${op.expected} when the move was queued`);
+      err.name = "BoardRejectedError";
+      throw err;
+    }
+    if (op.status === "running" || op.release) await (deps.claimTeamHu ?? claim)({ repo, number: op.number, who: op.who, release: op.release });
+    else await (deps.assertNotHeld ?? assertNotHeld)({ repo, number: op.number, who: op.who });
+    await (deps.setTeamStatus ?? setStatus)({ repo, number: op.number, status: op.status });
+    now.set(op.number, op.status);
+  };
+  const r = await flushQueue({ projectDir, apply });
+  if (r.applied) console.warn(`✓ ${r.applied} queued move(s) applied to the shared board`);
+  for (const c of r.conflicts) console.warn(`⚠ ${c}`);
+}
+
 /** KJC-TSK-1164: kj hu move on the shared board; starting it claims it (the assignee) first. */
 async function moveOnTeamBoard({ repo, args, flags, deps, emit, who }) {
   const [ref, status] = args;
@@ -123,8 +196,21 @@ export async function huCommand({ config = null, action, args = [], flags = {},
     return emit(r, `✓ HU Board: ${where} — commit ${files} in a PR so the whole team inherits it`);
   }
   const board = await (deps.boardConfig ?? readBoardConfig)(projectDir);
+  const who = deps.who === undefined ? workerOf(projectDir) : deps.who;
+  // KJC-TSK-1166 (TEAM-GH-E): the HUs created before the shared board, moved to it once.
+  if (action === "migrate") {
+    if (flags.to !== "github") throw new Error("usage: kj hu migrate --to github [--dry-run]");
+    if (board.backend !== "github") throw new Error("the shared board is off in this repo: turn it on first with kj hu backend github");
+    return migrateToTeamBoard({ projectDir, repo: board.repo, who, dryRun: Boolean(flags.dryRun), deps, emit });
+  }
+  // KJC-TSK-1165 (TEAM-GH-D): moves made without network go first, once GitHub answers.
+  if (board.backend === "github") await applyQueuedMoves({ projectDir, repo: board.repo, deps });
   if (board.backend === "github" && action === "list") {
-    const rows = (await (deps.listTeamHus ?? listHus)({ repo: board.repo })).map((h) => ({ ...h, id: h.short_id, plan: "github" }));
+    const { source, rows: hus, updatedAt } = await listWithCache({ projectDir, repo: board.repo, list: deps.listTeamHus ?? listHus });
+    if (source === "cache") console.warn(`⚠ GitHub did not answer: this is the local copy of the board from ${updatedAt}`);
+    // KJC-TSK-1166: what GitHub answered is what kj board shows, as a read-only plan.
+    else await writeTeamMirror(projectDir, hus, { repo: board.repo });
+    const rows = hus.map((h) => ({ ...h, id: h.short_id, plan: "github" }));
     if (flags.json) { console.log(JSON.stringify(rows)); return rows; }
     for (const r of rows) {
       const held = r.claimed_by ? " · held by " + r.claimed_by : "";
@@ -135,7 +221,18 @@ export async function huCommand({ config = null, action, args = [], flags = {},
   }
   // KJC-BUG-0392: a zero-padded id (HU-0104) is a local HU from before the shared board: it stays local.
   const legacyLocal = /^HU-0\d+$/i.test(String(args[0] ?? ""));
-  if (board.backend === "github" && action === "move" && !legacyLocal) return moveOnTeamBoard({ repo: board.repo, args, flags, deps, emit, who: deps.who === undefined ? workerOf(projectDir) : deps.who });
+  if (board.backend === "github" && action === "move" && !legacyLocal) {
+    try {
+      return await moveOnTeamBoard({ repo: board.repo, args, flags, deps, emit, who });
+    } catch (err) {
+      // Offline: the move waits in the queue; GitHub still decides when it is applied.
+      if (!isOffline(err)) throw err;
+      const number = Number(/^(?:HU-|#)(\d+)$/i.exec(args[0])[1]);
+      queueMove({ projectDir, number, status: args[1], who, release: Boolean(flags.release) });
+      console.warn(`⚠ GitHub did not answer: HU-${number} → ${args[1]} queued, applied when GitHub answers again`);
+      return emit({ id: `HU-${number}`, status: args[1], queued: true }, `⏳ HU-${number} → ${args[1]} (queued)`);
+    }
+  }
 
   if (action === "list") {
     const plans = await listPlans(projectDir);

package/src/commands/rag.js

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, relative } from "node:path";
 // KJC-PCS-0049 Step 6 — `kj rag` command group. Two subcommands:
 //   kj rag index [--project <slug>] [--with-sources]
@@ -13,7 +13,7 @@ import { query } from "../rag/retriever.js";
 import { pathNamedHits, withPathNamedHits } from "../rag/path-hits.js";
 import { installPostMergeHook, maybeAutoUpdate } from "../rag/auto-update.js";
 import { indexLibrary, LIBRARY_PROJECT } from "../rag/library.js";
-import { loadGoldenQueries, runEval } from "../rag/eval.js";
+import { compareToBaseline, loadGoldenQueries, runEval } from "../rag/eval.js";
 import { getKarajanHome } from "../utils/paths.js";
 import { countProjectChunks, countProjectSources, emptyIndexRemedy, migrateProjectIndex } from "../rag/migrate.js";
 import { openLibraryStore, openProjectStore, projectDbPath } from "../rag/project-store.js";
@@ -38,7 +38,7 @@ async function indexFiles({ files, projectDir, db, embedder, slug, logger, json,
       logger.warn?.(`[rag] ${out}: not indexed`);
       continue;
     }
-    const r = await indexFile(abs, { db, embedder, logger, project: slug, kind: sourceKind() });
+    const r = await indexFile(abs, { db, embedder, logger, project: slug, kind: sourceKind(), root: projectDir });
     totals.indexed += r.indexed; totals.failed += r.failed; totals.files += 1;
   }
   const deleted = totals.deleted ? `, ${totals.deleted} chunks deleted` : "";
@@ -160,14 +160,22 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
       logger.warn("[rag] this project's index holds none of its own files (only plans or briefs): run kj rag index --with-sources");
     }
     const mode = flags.mode || "hybrid";
-    const alpha = Math.max(0, Math.min(1, Number(flags.alpha) || 0.6));
+    // KJC-TSK-1180 (RAG-C, core 1.6.0): hybrid fusion is reciprocal rank; `alpha` weighs nothing
+    // any more, so a value that is still around is said once, never silently ignored.
+    if ((flags.alpha !== undefined && flags.alpha !== "0.6") || config?.rag?.search?.alpha !== undefined) {
+      logger.warn("[rag] alpha no longer applies: hybrid fusion is reciprocal rank (RRF); tune rag.search.rrf_k instead and drop alpha from the config");
+    }
+    const rrfK = config?.rag?.search?.rrf_k;
+    if (rrfK !== undefined && !(Number.isInteger(rrfK) && rrfK > 0)) throw new Error(`rag.search.rrf_k must be a positive integer, got ${JSON.stringify(rrfK)}`);
+    // KJC-TSK-1180 (RAG-B3): a relative `source~=` prefix is placed under this project's root.
+    const whereRoot = config?.projectDir || process.cwd();
     // Safe by grammar: parseWhere (core where-parser.js) accepts ONLY
     // AND-joined key=value pairs — an OR or parens never parses, so the
     // composed clause cannot leak past the kind filter; it fails loudly.
     let where = flags.where || null;
     if (library) where = flags.where ? `kind=library AND ${flags.where}` : "kind=library";
     const rerankOpts = flags.rerank ? { model: flags.rerankModel } : null;
-    const ranked = await query(db, makeGovernedEmbedder(config), text, { topK, scope, project, mode, alpha, where, rerankOpts });
+    const ranked = await query(db, makeGovernedEmbedder(config), text, { topK, scope, project, mode, rrfK, where, whereRoot, rerankOpts });
     const hits = library ? ranked : withPathNamedHits(pathNamedHits(db, text, { project, projectDir: config?.projectDir || process.cwd() }), ranked, topK);
     if (flags.json) {
       process.stdout.write(`${JSON.stringify(hits)}\n`);
@@ -201,20 +209,38 @@ export async function ragEvalCommand({ config, logger, flags = {} }) {
     const embedder = makeGovernedEmbedder(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] });
+    const { aggregate: agg } = report;
     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)}`);
+      const lat = agg.latency ? ` · latency mean=${agg.latency.meanMs}ms p95=${agg.latency.p95Ms}ms` : "";
+      logger.info(`[rag-eval] ${agg.n} queries · recall@5=${agg.recall["@5"].toFixed(3)} · recall@10=${agg.recall["@10"].toFixed(3)} · MRR=${agg.mrr.toFixed(3)}${lat}`);
       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}`);
+    if (Number.isFinite(minRecall) && agg.recall["@5"] < minRecall) {
+      logger.error?.(`[rag-eval] recall@5=${agg.recall["@5"].toFixed(3)} below --min-recall=${minRecall}`);
       process.exitCode = 1;
     }
+    // KJC-TSK-1170 (RAG-E): freeze the numbers, or fail when they got worse than the frozen ones.
+    if (flags.saveBaseline) {
+      const doc = { measuredAt: new Date().toISOString(), golden: goldenPath, topK, embedder: config?.rag?.embedder ?? null, search: config?.rag?.search ?? null, aggregate: agg };
+      writeFileSync(flags.saveBaseline, `${JSON.stringify(doc, null, 2)}\n`, "utf8");
+      logger.info(`[rag-eval] baseline saved to ${flags.saveBaseline}`);
+    }
+    if (flags.baseline) {
+      const base = JSON.parse(readFileSync(flags.baseline, "utf8"));
+      const check = compareToBaseline(agg, base.aggregate ?? base);
+      if (!check.ok) {
+        logger.error?.(`[rag-eval] worse than the baseline ${flags.baseline}:\n  - ${check.problems.join("\n  - ")}`);
+        process.exitCode = 1;
+      } else {
+        logger.info(`[rag-eval] not worse than the baseline ${flags.baseline}`);
+      }
+    }
     return report;
   } finally {
     db.close();

package/src/hu/github-board.js

@@ -12,11 +12,16 @@ export const STATUSES = ["pending", "running", "done", "failed", "skipped"];
 const statusLabel = (s) => `kj:${s}`;
 
 /** gh could not reach GitHub: the caller may queue the change, never invent data. */
-export class BoardOfflineError extends Error {}
+export class BoardOfflineError extends Error { name = "BoardOfflineError"; }
 /** GitHub answered and said no (permissions, missing repo...). */
-export class BoardRejectedError extends Error {}
+export class BoardRejectedError extends Error { name = "BoardRejectedError"; }
 /** The HU is running and someone else holds it: taking it over is explicit (release). */
-export class HuClaimedError extends Error {}
+export class HuClaimedError extends Error { name = "HuClaimedError"; }
+
+// KJC-TSK-1165: by name, not only instanceof: a test runner may load this module twice.
+export const isOffline = (err) => err instanceof BoardOfflineError || err?.name === "BoardOfflineError";
+/** GitHub answered and refused (rejected, or the HU is held by someone else): a conflict, not a failure of kj. */
+export const isRefusal = (err) => err instanceof BoardRejectedError || err instanceof HuClaimedError || ["BoardRejectedError", "HuClaimedError"].includes(err?.name);
 
 // gh is not localized: these are the network failures it prints.
 const OFFLINE = /dial tcp|no such host|could not resolve host|connection refused|i\/o timeout|network is unreachable|error connecting to/i;
@@ -48,6 +53,18 @@ export async function createHu({ repo, title, acceptanceCriteria = [], tests = [
   const url = (await gh(run, ["issue", "create", "-R", repo, "--title", title, "--body", body, "--label", HU_LABEL, "--label", statusLabel("pending")])).trim();
   const number = Number(/\/issues\/(\d+)$/.exec(url)?.[1]);
   if (!Number.isInteger(number)) throw new BoardRejectedError(`gh issue create returned no issue URL: ${url}`);
+  // KJC-BUG-0395 (HU-2408): GitHub answered the create and left the issue without its labels, so
+  // the next move refused it as "not a kj HU". An HU the board does not recognise is not announced:
+  // the labels are checked, put back once, and a second absence is said loud.
+  const wanted = [HU_LABEL, statusLabel("pending")];
+  const labelsOf = async () => new Set(JSON.parse(await gh(run, ["issue", "view", String(number), "-R", repo, "--json", "labels"])).labels.map((l) => l.name));
+  let have = await labelsOf();
+  if (wanted.some((l) => !have.has(l))) {
+    await gh(run, ["issue", "edit", String(number), "-R", repo, ...wanted.filter((l) => !have.has(l)).flatMap((l) => ["--add-label", l])]);
+    have = await labelsOf();
+    const missing = wanted.filter((l) => !have.has(l));
+    if (missing.length) throw new BoardRejectedError(`issue #${number} was created without ${missing.join(", ")} and gh could not add them: the board does not recognise it, add the labels by hand`);
+  }
   return { short_id: `HU-${number}`, number, status: "pending", title };
 }
 

package/src/hu/team-board-cache.js

@@ -0,0 +1,84 @@
+/**
+ * KJC-TSK-1165 (TEAM-GH-D, ADR 0025): the local copy of the shared board, and the
+ * queue of moves made without network. The copy is a cache, never the truth: it
+ * is rewritten on every answer from GitHub and only read when GitHub does not
+ * answer. A queued move is applied when the network is back; one GitHub rejects
+ * (someone else holds the HU) is reported and dropped, never forced. Creating a
+ * HU offline is refused elsewhere: an id is only ever minted by GitHub.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { isOffline, isRefusal } from "./github-board.js";
+
+const CACHE_FILE = ".karajan/board-cache.json";
+// A fresh object every time: a shared default array would carry one read's queue into the next.
+const empty = () => ({ hus: null, updatedAt: null, queue: [] });
+
+export function readCache(projectDir) {
+  try {
+    return { ...empty(), ...JSON.parse(fs.readFileSync(path.join(projectDir, CACHE_FILE), "utf8")) };
+  } catch (err) {
+    if (err.code === "ENOENT") return empty();
+    throw err;
+  }
+}
+
+function writeCache(projectDir, cache) {
+  const file = path.join(projectDir, CACHE_FILE);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(cache, null, 2)}\n`, "utf8");
+}
+
+/** The HUs from GitHub (and the copy refreshed), or the copy when GitHub cannot be reached. */
+export async function listWithCache({ projectDir, repo, list }) {
+  try {
+    const rows = await list({ repo });
+    writeCache(projectDir, { ...readCache(projectDir), hus: rows, updatedAt: new Date().toISOString() });
+    return { source: "github", rows };
+  } catch (err) {
+    const cache = readCache(projectDir);
+    if (!isOffline(err) || !cache.hus) throw err;
+    return { source: "cache", rows: cache.hus, updatedAt: cache.updatedAt };
+  }
+}
+
+/**
+ * Remember a move to apply when the network is back. `expected` is the status the local
+ * copy shows now (null when the copy does not know the HU): when it is applied, a HU that
+ * moved meanwhile is a conflict, not something to overwrite. The copy takes the move so a
+ * second queued move on the same HU expects the first one's result.
+ */
+export function queueMove({ projectDir, number, status, who, release }) {
+  const cache = readCache(projectDir);
+  const row = cache.hus?.find((h) => h.number === number) ?? null;
+  cache.queue.push({ number, status, who, release: Boolean(release), expected: row?.status ?? null, queuedAt: new Date().toISOString() });
+  if (row) row.status = status;
+  writeCache(projectDir, cache);
+  return cache.queue.length;
+}
+
+/**
+ * Apply the queue in order. A move GitHub refuses is a conflict: reported, dropped, the
+ * HU stays as the other person left it. Still offline: stop, keep the rest for later.
+ * Any other error is kj's own: it surfaces, and the move stays queued.
+ * @returns {Promise<{applied: number, conflicts: string[], pending: number}>}
+ */
+export async function flushQueue({ projectDir, apply }) {
+  const cache = readCache(projectDir);
+  const conflicts = [];
+  let applied = 0;
+  while (cache.queue.length > 0) {
+    const op = cache.queue[0];
+    try {
+      await apply(op);
+      applied += 1;
+    } catch (err) {
+      if (isOffline(err)) break;
+      if (!isRefusal(err)) throw err;
+      conflicts.push(`HU-${op.number} → ${op.status} (queued ${op.queuedAt}) not applied: ${err.message}`);
+    }
+    cache.queue.shift();
+    writeCache(projectDir, cache);
+  }
+  return { applied, conflicts, pending: cache.queue.length };
+}

package/src/hu/team-board-mirror.js

@@ -0,0 +1,26 @@
+/**
+ * KJC-TSK-1166 (TEAM-GH-E, ADR 0025): what `kj board` shows of the shared board. The web
+ * board reads plans, so the shared board is mirrored into one read-only plan per project,
+ * rewritten from the issues every time kj reads them. It is a view: changing it is done
+ * with kj hu move, never from the web, and the board refuses to edit it.
+ */
+import { savePlan } from "../plan/plan-store.js";
+
+export const MIRROR_PLAN_ID = "plan_github-board";
+
+/** The shared board as a plan the web board can show, marked read-only. */
+export async function writeTeamMirror(projectDir, rows, { repo }) {
+  const now = new Date().toISOString();
+  const plan = {
+    version: 2, planId: MIRROR_PLAN_ID, name: "github", alias: "github",
+    task: `Shared HU Board: GitHub Issues of ${repo}`,
+    status: "ready", readonly: "github", createdAt: now,
+    hus: rows.map((r) => ({
+      id: r.short_id, short_id: r.short_id, title: r.title, status: r.status,
+      claimed_by: r.claimed_by ?? null, created_by: "github", external_ref: `${repo}#${r.number}`,
+      acceptance_criteria: [], acceptance_tests: [], createdAt: now, updatedAt: now,
+    })),
+  };
+  await savePlan(projectDir, plan);
+  return plan;
+}

package/src/lang/chunk-go.js

@@ -8,6 +8,7 @@
 // `type_declaration` contiene type_spec(s); usamos el primero como symbol.
 
 import { getLoaded, loadLanguage } from "./tree-sitter-loader.js";
+import { spanChunks } from "./chunk-span.js";
 
 const DEFAULT_LIMIT = 800;
 const DEFAULT_OVERLAP = 100;
@@ -21,16 +22,6 @@ 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) {
@@ -74,21 +65,5 @@ function marksViaRegex(text) {
 }
 
 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;
+  return spanChunks(text, marksViaAST(text) ?? marksViaRegex(text), { path, language: "go", limit, overlap });
 }

package/src/lang/chunk-java.js

@@ -4,6 +4,7 @@
 // sin prefijar (coherente con chunk-go), el RAG ya lleva contexto del fichero.
 
 import { getLoaded, loadLanguage } from "./tree-sitter-loader.js";
+import { spanChunks } from "./chunk-span.js";
 
 const DEFAULT_LIMIT = 800;
 const DEFAULT_OVERLAP = 100;
@@ -23,17 +24,6 @@ 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;
@@ -47,14 +37,15 @@ function marksViaAST(text) {
   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 className = nameOf(child);
+    if (className) marks.push({ idx: child.startIndex, symbol: className });
     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 });
+      const memberName = nameOf(m);
+      // KJC-TSK-1171: a member knows its class (by name); the chunk says both.
+      if (memberName) marks.push({ idx: m.startIndex, symbol: memberName, parent: className });
     }
   }
   marks.sort((a, b) => a.idx - b.idx);
@@ -70,21 +61,5 @@ function marksViaRegex(text) {
 }
 
 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;
+  return spanChunks(text, marksViaAST(text) ?? marksViaRegex(text), { path, language: "java", limit, overlap });
 }