karajan-code 4.49.4 → 4.50.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.49.4",
+  "version": "4.50.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -60,7 +60,6 @@
     "packages/ai-trash/src/",
     "packages/ai-trash/bin/",
     "packages/ai-trash/package.json",
-    "docs/karajan-code-logo-small.png",
     "docs/README.es.md",
     "LICENSE",
     "README.md"

package/src/cli/register-meta.js

@@ -315,6 +315,7 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--scope <text>", "Scope of the story (files/areas)")
     .option("--task-type <type>", "sw | infra | doc | add-tests | refactor")
     .option("--criteria <text>", "Legacy alias for a single acceptance criterion")
+    .option("--ref <id>", "Id of this card's replica in the external tracker (Planning Game, Jira, Linear...)")
     .option("--json", "Machine-readable output")
     .action(async (title, flags) => {
       await withConfig(pkgVersion, "hu", flags, async ({ config }) => {

package/src/commands/hu.js

@@ -62,15 +62,9 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
   const projectDir = config?.projectDir || process.cwd();
   const emit = (obj, human) => { console.log(flags.json ? JSON.stringify(obj) : human); return obj; };
 
-  // KJC-TSK-0684 (issue #1287): with an external board declared, kj never
-  // maintains a parallel HU Board — writes are refused with the pointer.
-  if (config?.state_backend === "external" && (action === "add" || action === "move")) {
-    const name = config?.board?.name || "an external board";
-    throw new Error(
-      `this project's board lives in ${name} (state_backend: external) — create and move cards there, `
-      + `through your agent's MCP/tools. kj does not mirror external boards.`
-    );
-  }
+  // KJC-BUG-0305 (issue #2042): the HU Board is always kj's board. An external
+  // tracker coexists with it: each HU points at its replica there (--ref).
+  const externalBoard = config?.state_backend === "external" ? (config?.board?.name || "the external board") : null;
 
   if (action === "list") {
     const plans = await listPlans(projectDir);
@@ -84,12 +78,14 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
           // KJC-TSK-0661: provenance — where a card came from is part of
           // the card. Older HUs predate the stamp: shown as "?".
           created_by: h.created_by || null, created_at: h.createdAt || null,
+          external_ref: h.external_ref || null,
         });
       }
     }
     if (flags.json) { console.log(JSON.stringify(rows)); return rows; }
     for (const r of rows) {
-      const origin = `${r.plan} · by ${r.created_by || "?"}${r.created_at ? ` · ${r.created_at.slice(0, 10)}` : ""}`;
+      const suffixes = [r.created_at?.slice(0, 10), r.external_ref].filter(Boolean).map((s) => ` · ${s}`).join("");
+      const origin = `${r.plan} · by ${r.created_by || "?"}${suffixes}`;
       console.log(`${(r.short_id || r.id).padEnd(28)} ${r.status.padEnd(8)} ${r.title}  [${origin}]`);
     }
     if (rows.length === 0) console.log("no HUs yet — create one with: kj hu add \"<story>\"");
@@ -164,7 +160,11 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
       task_type: flags.taskType || undefined,
     });
     hu.created_by = creatorLabel();
+    if (flags.ref) hu.external_ref = String(flags.ref).trim();
     await savePlan(projectDir, plan);
+    if (externalBoard && !hu.external_ref) {
+      console.log(`→ replicate it in ${externalBoard} through your agent's MCP/tools and link both: kj hu add ... --ref <id in ${externalBoard}>`);
+    }
     const missing = [];
     if (hu.acceptance_criteria.length === 0) missing.push("acceptance criteria (--ac \"...\")");
     if (hu.acceptance_tests.length === 0) missing.push("tests (--tests \"...\")");
@@ -174,7 +174,7 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
     return emit({
       id: hu.id, short_id: hu.short_id, status: hu.status, created_by: hu.created_by,
       acceptance_criteria: hu.acceptance_criteria, acceptance_tests: hu.acceptance_tests,
-      scope: hu.scope, task_type: hu.task_type,
+      scope: hu.scope, task_type: hu.task_type, external_ref: hu.external_ref || null,
     }, `✓ HU created: ${hu.short_id || hu.id} (pending, by ${hu.created_by}) — it shows up in \`kj board\``);
   }
 

package/src/commands/rag.js

@@ -10,6 +10,7 @@ import { indexFile, indexProject, indexProjectDelta, sourceKind } from "../rag/i
 import { indexableReason, ragExclude } from "../rag/indexable.js";
 import { fileIndexState } from "../rag/coverage.js";
 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";
@@ -166,7 +167,8 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
     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 hits = 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, alpha, where, 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`);
     } else {

package/src/commands/steward.js

@@ -113,7 +113,10 @@ export async function stewardSweepCommand({ flags = {}, config = {}, logger = co
   try {
     const sync = await syncProposedWork({ projectDir, config, results, sweptAt: report.sweptAt });
     if (!sync.synced) logger.warn?.(`⚠ steward: broken invariants not carded — ${sync.reason}`);
-    else if (sync.created || sync.updated || sync.resolved) logger.info?.(`steward board: ${sync.created} card(s) proposed, ${sync.updated} updated, ${sync.resolved} resolved`);
+    else if (sync.created || sync.updated || sync.resolved) {
+      logger.info?.(`steward board: ${sync.created} card(s) proposed, ${sync.updated} updated, ${sync.resolved} resolved`);
+      if (sync.replicateIn) logger.info?.(`→ replicate them in ${sync.replicateIn} through your agent's board tools (kj hu list shows them)`);
+    }
   } catch (err) { logger.warn?.(`⚠ steward: carding the broken invariants failed (${err.message}) — the report and the seal stand`); }
 
   // A report nobody can see is not shared state — say it, do not fix their tree.

package/src/environment/playbook.js

@@ -30,20 +30,20 @@ const TARGET_FILES = {
 
 // ENV-D1 (KJC-TSK-0642): the tracking invariant names the CHOSEN state
 // backend — a playbook that says "board or PG" makes the host guess.
-// KJC-TSK-0684 (issue #1287): external boards (Linear, Trello, Jira…) are
-// first-class — card-first points at THE project's board, worked through
-// the host agent's own MCP/tools. kj never mirrors it: a half-empty
-// parallel board is worse than none.
+// KJC-BUG-0305 (issue #2042, replaces KJC-TSK-0684): the HU Board is always
+// kj's board. An external board (Linear, Trello, Jira…) coexists with it: the
+// host agent replicates each card there through its own MCP/tools, and
+// `kj hu add --ref` links the two.
 const BACKEND_TRACKING = {
   "hu-board": "Every piece of work has a tracked story/bug in the HU Board (`kj hu add` / `kj board`) before it starts — and `kj hu list` BEFORE `kj hu add`: reuse the existing card if one covers the work. Cards are permanent — never delete or recreate one; discard with `kj hu move <id> skipped`. `kj brief board` explains the board.",
-  "planning-game": "Every piece of work has a tracked card in the Planning Game MCP before it starts (In Progress while you work it).",
 };
 
 const externalTracking = (boardName) =>
-  `Every piece of work has a tracked card in ${boardName} — the project's board — before it starts (use its MCP/tools; move the card as you work it). kj does not mirror it: never create a parallel HU Board.`;
+  `Every piece of work has a card in the HU Board before it starts (\`kj hu list\`, then \`kj hu add --ref <id>\`) and its replica in ${boardName}, created through its MCP/tools; move both as you work it.`;
 
 function trackingLine(stateBackend, boardName) {
   if (stateBackend === "external") return externalTracking(boardName || "the project's external board");
+  if (stateBackend === "planning-game") return externalTracking("the Planning Game");
   return BACKEND_TRACKING[stateBackend] || BACKEND_TRACKING["hu-board"];
 }
 

package/src/mcp/handlers/rag-handler.js

@@ -9,6 +9,7 @@ import { makeGovernedEmbedder } from "../../rag/governed-embedder.js";
 import { indexProject } from "../../rag/indexer.js";
 import { ragExclude } from "../../rag/indexable.js";
 import { query } from "../../rag/retriever.js";
+import { pathNamedHits, withPathNamedHits } from "../../rag/path-hits.js";
 import { getKarajanHome } from "../../utils/paths.js";
 import { resolveProjectDir, buildConfig, responseText, failPayload } from "../shared-helpers.js";
 
@@ -40,7 +41,9 @@ export async function handleRagQuery(args, server) {
         const remedy = emptyIndexRemedy({ slug: project, legacyPath: join(getKarajanHome(), "rag.db"), dim });
         return responseText({ hits: [], empty: true, topK, scope, project, remedy });
       }
-      const hits = await query(db, makeGovernedEmbedder(config), text, { topK, scope, project });
+      const ranked = await query(db, makeGovernedEmbedder(config), text, { topK, scope, project });
+      // KJC-BUG-0348: a file the question names comes first, as in the CLI.
+      const hits = withPathNamedHits(pathNamedHits(db, text, { project, projectDir }), ranked, topK);
       return responseText({ hits, empty: false, topK, scope, project });
     } finally { db.close(); }
   } catch (err) {

package/src/rag/path-hits.js

@@ -0,0 +1,36 @@
+/**
+ * KJC-BUG-0348 (#2115): ranking alone decides what a query returns, and in a
+ * large index a freshly indexed file (an .astro page) never made the top hits,
+ * neither by its path nor by its text: the rag-first gate kept blocking it.
+ * A query that NAMES an indexed file returns that file first, deterministically.
+ */
+import { isAbsolute, relative } from "node:path";
+
+// A path-like token: segments joined by "/" ending in a file extension.
+const PATH_TOKEN = /[\w@.-]+(?:\/[\w@.-]+)*\.[A-Za-z0-9]+/g;
+
+const parseMetadata = (raw) => {
+  try { return raw ? JSON.parse(raw) : {}; } catch { return {}; }
+};
+
+/** @returns {object[]} the first chunk of each indexed file of `project` the text names */
+export function pathNamedHits(db, text, { project, projectDir }) {
+  const tokens = [...new Set(String(text || "").match(PATH_TOKEN) ?? [])];
+  if (!project || tokens.length === 0) return [];
+  const sources = db.prepare("SELECT DISTINCT source FROM chunks WHERE project_slug = ?").all(project).map((r) => r.source);
+  const named = sources.filter((source) => {
+    const rel = (isAbsolute(source) ? relative(projectDir, source) : source).split("\\").join("/");
+    return tokens.some((t) => rel === t || rel.endsWith(`/${t}`));
+  });
+  const first = db.prepare("SELECT id, source, kind, text, metadata, project_slug FROM chunks WHERE project_slug = ? AND source = ? ORDER BY id LIMIT 1");
+  return named.map((source) => {
+    const row = first.get(project, source);
+    return { ...row, metadata: parseMetadata(row.metadata), distance: 0, score: 0, matchedBy: "path" };
+  });
+}
+
+/** The named files first, then the ranked hits, never the same chunk twice, at most topK. */
+export function withPathNamedHits(named, ranked, topK) {
+  const ids = new Set(named.map((h) => h.id));
+  return [...named, ...ranked.filter((h) => !ids.has(h.id))].slice(0, topK);
+}

package/src/review/card-first.js

@@ -2,8 +2,8 @@
  * Card-first gate (KJC-TSK-0686, MG-A of épica KJC-PCS-0068): the rule
  * that work starts from a card moves from playbook text into the gate.
  * hu-board → the branch must reference a LIVE card (block by default);
- * planning-game/external → card-shaped reference required (warn default,
- * block via method_gates.card_first). Exemptions explicit and visible:
+ * planning-game/external → a live HU on the HU Board first, else a card-shaped
+ * reference (warn default, block via method_gates.card_first). Exemptions explicit and visible:
  * base branch and configured prefixes (releases). No escape (ADR 0015): a
  * gate an agent can switch off is a suggestion.
  */
@@ -40,7 +40,8 @@ async function findLiveCardInBranch(projectDir, branch) {
   for (const meta of await listPlans(projectDir)) {
     const plan = await loadPlan(projectDir, meta.planId);
     for (const h of plan.hus || []) {
-      for (const ref of [h.short_id, h.id]) {
+      // KJC-BUG-0353: an HU is also named by the id of its replica in an external tracker.
+      for (const ref of [h.short_id, h.id, h.external_ref]) {
         if (ref && refInBranch(ref, needle)) {
           if (LIVE_STATUSES.has(h.status)) return { ref, live: true, status: h.status };
           closedHit = { ref, live: false, status: h.status };
@@ -83,6 +84,10 @@ export async function checkCardFirst({ config = {}, projectDir = process.cwd(),
   // result names its level so nobody mistakes branch-ref for tracker.
   const boardName = config.board?.name || backend;
   const effective = policy === "auto" ? "warn" : policy;
+  // KJC-BUG-0353: the HU Board is always kj's board (KJC-BUG-0305) — a live HU
+  // the branch names, or whose replica it names, is checked here, not guessed.
+  const huHit = await findLiveCardInBranch(projectDir, branch);
+  if (huHit?.live) return { ok: true, mode: "pass", ref: huHit.ref, level: "hu-board" };
   if (CARD_REF_RE.test(branch)) {
     const ref = branch.match(CARD_REF_RE)[0];
     const { verifyFn = verifyCardAlive } = deps;
@@ -105,7 +110,8 @@ export async function checkCardFirst({ config = {}, projectDir = process.cwd(),
         reason: `branch references ${ref} but the card could not be verified against ${boardName} — ${v.note} (board.unverifiable: block refuses to approve a check kj did not make)`,
       };
     }
-    return { ok: true, mode: "pass", ref, level: v.level, ...(v.note ? { note: v.note } : {}) };
+    const huNote = `no live HU on the HU Board links ${ref}: kj hu add "…" --ref ${ref}`;
+    return { ok: true, mode: "pass", ref, level: v.level, note: v.note ? `${v.note}; ${huNote}` : huNote };
   }
   const reason = `no card reference in branch "${branch}" — card-first on ${boardName}: create the card there and name the branch after it (e.g. feat/ABC-123-summary)`;
   return effective === "block"

package/src/steward/proposed-work.js

@@ -7,11 +7,9 @@
  * a daily sweep must never flood the board with twins — and a green
  * invariant resolves it with the green evidence.
  *
- * kj only writes the board it owns (hu-board). planning-game and external
- * boards are never mirrored (KJC-TSK-0684: a half-empty parallel board is
- * worse than none): there the sweep reports synced:false LOUDLY, and the
- * Sentinel's inevitable notice (STW-C) pushes the host agent — who does
- * have the board's MCP — to card them.
+ * KJC-BUG-0305: the HU Board is always kj's board, so the cards land there on
+ * every backend. With planning-game or an external board the result names it
+ * (replicateIn): the host agent, who has that board's MCP, replicates them.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -34,13 +32,11 @@ const cardText = (r, brokenSince) => [
  */
 export async function syncProposedWork({ projectDir, config = {}, results = [], sweptAt }) {
   const backend = config.state_backend || "hu-board";
-  if (backend !== "hu-board") {
-    return { synced: false, reason: `the board lives in ${backend} — kj never mirrors a board it does not own; card the broken invariants through your agent's board tools` };
-  }
+  const replica = backend === "hu-board" ? {} : { replicateIn: backend };
   const map = readMap(projectDir);
   const broken = results.filter((r) => r.verdict === "broken");
   const okAgain = results.filter((r) => r.verdict === "ok" && map[r.id]);
-  if (broken.length === 0 && okAgain.length === 0) return { synced: true, created: 0, updated: 0, resolved: 0 };
+  if (broken.length === 0 && okAgain.length === 0) return { synced: true, created: 0, updated: 0, resolved: 0, ...replica };
 
   const plan = await backlogPlan(projectDir);
   let created = 0, updated = 0, resolved = 0;
@@ -64,5 +60,5 @@ export async function syncProposedWork({ projectDir, config = {}, results = [],
   await savePlan(projectDir, plan);
   fs.mkdirSync(path.dirname(mapPath(projectDir)), { recursive: true });
   fs.writeFileSync(mapPath(projectDir), `${JSON.stringify(map, null, 2)}\n`);
-  return { synced: true, created, updated, resolved };
+  return { synced: true, created, updated, resolved, ...replica };
 }