@karajan-family/code 4.62.1 → 4.64.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karajan-family/code",
-  "version": "4.62.1",
+  "version": "4.64.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/advanced-commands.js

@@ -33,7 +33,7 @@ export const META_COMMANDS = ["advanced", "help"];
 export const ADVANCED_GROUPS = [
   { title: "Pipeline (piezas sueltas)", commands: ["autorun", "code", "review", "solomon", "agent", "scan", "tournament"] },
   { title: "Análisis pre-run", commands: ["discover", "triage", "researcher", "architect", "onboard", "brief"] },
-  { title: "Búsqueda / RAG", commands: ["rag", "qmd", "watch"] },
+  { title: "Búsqueda / RAG", commands: ["rag", "qmd", "watch", "doc"] },
   { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar", "privacy", "release", "policy", "rules", "rulesync", "claims", "steward", "pr-size"] },
   { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "worktree", "undo", "standby", "sentinel", "identity", "security", "handoff"] },
   { title: "Infra / setup", commands: ["install-tools", "ollama", "skills", "roles", "agents", "env"] },

package/src/cli/register-meta.js

@@ -29,6 +29,7 @@ import { mutateCommand } from "../commands/mutate.js";
 import { hardenCommand } from "../commands/harden.js";
 import { telemetryPreviewCommand, telemetryStatusCommand } from "../commands/telemetry.js";
 import { envInstallCommand, briefCommand } from "../commands/env.js";
+import { docCommand } from "../commands/doc.js";
 import { runReleaseCheck } from "../checks/release-check.js";
 import { agentRunCommand } from "../commands/agent-run.js";
 import { reportIssueCommand } from "../commands/report-issue.js";
@@ -75,7 +76,7 @@ export function registerMeta(program, { pkgVersion }) {
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "discover", flags, async ({ config, logger }) => {
         const { resolveTaskInput } = await import("../utils/task-file.js");
-        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger, indexFirstBytes: config.docs?.indexFirstBytes });
         await discoverCommand({ task: resolvedTask, config, logger, mode: flags.mode, json: flags.json });
       });
     });
@@ -91,7 +92,7 @@ export function registerMeta(program, { pkgVersion }) {
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "triage", flags, async ({ config, logger }) => {
         const { resolveTaskInput } = await import("../utils/task-file.js");
-        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger, indexFirstBytes: config.docs?.indexFirstBytes });
         await triageCommand({ task: resolvedTask, config, logger, json: flags.json });
       });
     });
@@ -106,7 +107,7 @@ export function registerMeta(program, { pkgVersion }) {
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "researcher", flags, async ({ config, logger }) => {
         const { resolveTaskInput } = await import("../utils/task-file.js");
-        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger, indexFirstBytes: config.docs?.indexFirstBytes });
         await researcherCommand({ task: resolvedTask, config, logger });
       });
     });
@@ -123,7 +124,7 @@ export function registerMeta(program, { pkgVersion }) {
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "architect", flags, async ({ config, logger }) => {
         const { resolveTaskInput } = await import("../utils/task-file.js");
-        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger, indexFirstBytes: config.docs?.indexFirstBytes });
         await architectCommand({ task: resolvedTask, config, logger, context: flags.context, json: flags.json });
       });
     });
@@ -353,6 +354,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")
@@ -531,6 +543,29 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // KJC-TSK-1183 — a long markdown document is read by index: the headings first, then only the
+  // sections a task needs, each one whole and exactly as the file has it.
+  const doc = program.command("doc").description("Read a markdown document by index: headings first, whole sections on demand");
+  doc.command("index")
+    .description("List the headings of a markdown file with their level and line (a heading inside a code block is text)")
+    .argument("<file>", "Markdown file")
+    .option("--json", "Machine-readable output")
+    .action(async (file, flags) => {
+      await withConfig(pkgVersion, "doc-index", flags, async () => {
+        docCommand({ action: "index", file, flags });
+      });
+    });
+  doc.command("section")
+    .description("Print one section whole, as the file has it, up to the next heading of the same or a higher level; an unknown heading lists the available ones")
+    .argument("<file>", "Markdown file")
+    .argument("<heading>", "Heading title, exact or case-insensitive")
+    .option("--json", "Machine-readable output")
+    .action(async (file, heading, flags) => {
+      await withConfig(pkgVersion, "doc-section", flags, async () => {
+        docCommand({ action: "section", file, heading, flags });
+      });
+    });
+
   // KJC-TSK-0712 — memory is the reminder, the check is the guarantee.
   const release = program.command("release").description("Release ceremony helpers");
   release.command("check")
@@ -784,10 +819,11 @@ 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", "Re-score the top-N candidates with a cross-encoder (needs @huggingface/transformers; or rag.search.rerank.enabled in kj.config.yml)")
+    .option("--rerank-top-n <n>", "Candidates the cross-encoder re-scores before the top-K is cut (default 40, or rag.search.rerank.top_n)")
     .option("--rerank-model <name>", "Cross-encoder model id. Default: Xenova/ms-marco-MiniLM-L-6-v2")
     .option("--json", "Output the hits as JSON")
     .action(async (text, flags) => {
@@ -807,7 +843,11 @@ 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("--rerank", "Measure with the cross-encoder rerank on (needs @huggingface/transformers)")
+    .option("--rerank-top-n <n>", "Candidates the cross-encoder re-scores before the top-K is cut (default 40)")
     .option("--json", "Emit the full report as JSON")
     .action(async (flags) => {
       await withConfig(pkgVersion, "rag-eval", flags, async ({ config, logger }) => {

package/src/cli/register-pipeline.js

@@ -153,7 +153,7 @@ export function registerPipeline(program, { pkgVersion }) {
             effectiveTask = plan.task;
           }
         }
-        const resolvedTask = await resolveTaskInput({ task: effectiveTask, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        const resolvedTask = await resolveTaskInput({ task: effectiveTask, taskFile: flags.taskFile, projectDir: config.projectDir, logger, indexFirstBytes: config.docs?.indexFirstBytes });
         const res = await runCommandHandler({ task: resolvedTask, config, logger, flags });
         // KJC-TSK-0674 (issue #1289): an aborted run (spec-review cancel,
         // unanswerable non-interactive gate) must be observable by CI.

package/src/cli/register-plan.js

@@ -52,7 +52,7 @@ export function registerPlan(program, { pkgVersion }) {
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "plan", flags, async ({ config, logger }) => {
         const { resolveTaskInput } = await import("../utils/task-file.js");
-        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger, indexFirstBytes: config.docs?.indexFirstBytes });
 
         // REASONS Canvas auto-detection: a SPEC that contains
         // `## REASONS:Section` headings is treated as a structured

package/src/commands/doc.js

@@ -0,0 +1,26 @@
+// KJC-TSK-1183 — `kj doc index <file>` and `kj doc section <file> <heading>`: a long markdown
+// document is read by index, the headings first and only the sections a task needs, each one
+// whole and exactly as the file has it. The headings are the index; nothing extra to keep in sync.
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { indexMarkdown, sectionOf } from "../docs/markdown-index.js";
+
+export function docCommand({ action, file, heading = null, flags = {}, cwd = process.cwd(), out = process.stdout }) {
+  if (!file) throw new Error("usage: kj doc index <file> | kj doc section <file> <heading>");
+  const path = resolve(cwd, file);
+  const text = readFileSync(path, "utf8"); // a missing file fails loud, with the path
+  if (action === "index") {
+    const headings = indexMarkdown(text);
+    if (flags.json) out.write(`${JSON.stringify({ file: path, headings })}\n`);
+    else for (const h of headings) out.write(`${"  ".repeat(h.level - 1)}${"#".repeat(h.level)} ${h.title}  (line ${h.line})\n`);
+    return headings;
+  }
+  if (action === "section") {
+    if (!heading) throw new Error("usage: kj doc section <file> <heading>");
+    const section = sectionOf(text, heading);
+    if (flags.json) out.write(`${JSON.stringify({ file: path, ...section })}\n`);
+    else out.write(section.text); // exactly as the file has it, nothing added
+    return section;
+  }
+  throw new Error(`unknown action "${action}": use index | section`);
+}

package/src/commands/hu.js

@@ -13,7 +13,10 @@ 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 { assertGhIdentity } from "../hu/gh-identity.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 +60,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 +197,24 @@ 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);
+  // KJC-TSK-1186: the shared board is written as the active gh account; with an identity declared
+  // it must be that one, said with the remedy before any gh call instead of a GraphQL permission error.
+  if (board.backend === "github") (deps.assertGhIdentity ?? assertGhIdentity)({ 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 +225,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 rerankOpts = rerankOptionsFor({ config, flags, logger });
+    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`);
@@ -185,6 +193,28 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
   }
 }
 
+// KJC-TSK-1181 (RAG-D2): the cross-encoder, from the flag or from rag.search.rerank in the config
+// (enabled, top_n, model). Without the library or the model the retrieval answers alone and the
+// install is said once per process, never on every query, never in silence.
+const rerankWarned = new Set();
+export function rerankOptionsFor({ config, flags = {}, logger }) {
+  const cfg = config?.rag?.search?.rerank ?? {};
+  const enabled = flags.rerank === true || (flags.rerank !== false && cfg.enabled === true);
+  if (!enabled) return null;
+  const topN = flags.rerankTopN ?? cfg.top_n;
+  if (topN !== undefined && !(Number.isInteger(Number(topN)) && Number(topN) > 0)) throw new Error(`rag.search.rerank.top_n must be a positive integer, got ${JSON.stringify(topN)}`);
+  const key = config?.projectDir || "rerank";
+  return {
+    model: flags.rerankModel || cfg.model || undefined,
+    ...(topN === undefined ? {} : { topN: Number(topN) }),
+    onUnavailable: (err) => {
+      if (rerankWarned.has(key)) return;
+      rerankWarned.add(key);
+      logger.warn(`[rag] rerank skipped: ${err.message}. Install it with npm install @huggingface/transformers; the retrieval answered without it`);
+    },
+  };
+}
+
 // 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
@@ -199,22 +229,42 @@ export async function ragEvalCommand({ config, logger, flags = {} }) {
     const detected = projectSlug(config?.projectDir || process.cwd());
     const project = flags.project === "all" ? null : (flags.project || detected || null);
     const embedder = makeGovernedEmbedder(config);
-    const runQuery = async (text, k) => query(db, embedder, text, { topK: k, scope: "all", project });
+    // KJC-TSK-1181: measured with the cross-encoder too, so its default is a number, not a hunch.
+    const rerankOpts = rerankOptionsFor({ config, flags, logger });
+    const runQuery = async (text, k) => query(db, embedder, text, { topK: k, scope: "all", project, rerankOpts });
     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/config/defaults.js

@@ -274,6 +274,9 @@ const DEFAULTS = {
     // safe default blocks them (local ollama/onnx always allowed).
     sensitivity: "internal"
   },
+  // KJC-TSK-1183 — a document over this size (task file, ADR) reaches the roles as its headings
+  // index; they fetch a section whole with `kj doc section` when the task needs it.
+  docs: { indexFirstBytes: 12000 },
   // Opt-in. Set by the `kj init` wizard (explicit consent prompt in the OS
   // locale). When the key is absent or false, no events are sent. See
   // src/utils/telemetry.js and the Privacy & Telemetry section of README.md.

package/src/docs/index-first.js

@@ -0,0 +1,31 @@
+// KJC-TSK-1183 — Roles read long documents by index. Over the limit, a document reaches the prompt
+// as its preamble plus its headings and the command that fetches one section whole; under it, or
+// without headings to index, it travels as it is.
+import { indexMarkdown } from "./markdown-index.js";
+
+export const DEFAULT_INDEX_FIRST_BYTES = 12000;
+const PREAMBLE_MAX = 1500;
+const shellQuote = (s) => (/^[A-Za-z0-9_./:@%+=-]+$/.test(s) ? s : ["'", s.replaceAll("'", String.raw`'\''`), "'"].join(""));
+
+/**
+ * What the agent reads instead of the whole document, or null when the whole fits or there is
+ * nothing to index (fewer than two headings: a single one covers it all).
+ * @param {{ path: string, text: string, limit?: number }} doc
+ */
+export function indexFirstView({ path, text, limit = DEFAULT_INDEX_FIRST_BYTES }) {
+  if (!Number.isInteger(limit) || limit <= 0 || text.length <= limit) return null;
+  const headings = indexMarkdown(text);
+  if (headings.length < 2) return null;
+  const preamble = text.split("\n").slice(0, headings[1].line - 1).join("\n").trim().slice(0, PREAMBLE_MAX);
+  const index = headings.map((h) => `${"  ".repeat(h.level - 1)}- ${h.title}`).join("\n");
+  const file = shellQuote(path);
+  return [
+    preamble,
+    "",
+    `_This document is ${text.length} characters, over the ${limit} read-whole limit, so it is read by index. Its headings:_`,
+    "",
+    index,
+    "",
+    `Read a section whole only when the task needs it: \`kj doc section ${file} "<heading>"\` (the index again: \`kj doc index ${file}\`).`,
+  ].join("\n");
+}