karajan-code 2.24.0 → 2.25.0

package/README.md

@@ -345,6 +345,14 @@ Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 
 ## Recent releases
 
+> **v2.25.0 released** — Minor. **RAG Camino B + Camino D** (KJC-PCS-0049). Closes the consumer-surface plan. Skills hosts can now invoke RAG via `/kj-rag-query` without MCP, and the pre-loop retrieval stage from v2.24.0 only fires when triage signals make it worthwhile.
+>
+> Camino B — `/kj-rag-query <text> [--scope <s>] [--top-k <n>]` slash command shipped by `kj init` to `.claude/commands/`. Thin wrapper over `kj rag query`; passes flags through, surfaces `empty:true` as a one-line hint, renders hits as background context rather than raw JSON. For Claude Code / Cursor instances loaded without MCP.
+>
+> Camino D — Brain decisor heuristic in `src/orchestrator/stages/rag-preload-decisor.js`. New `config.rag.preload.policy`: `always` (v2.24.0 behaviour, kept for back-compat), `never` (benchmarking), `auto` (default). In `auto` mode, retrieval fires when triage decomposes, level ∈ {complex, high, epic}, task body ≥ 200 chars, or `config.rag.preload.brownfield` is set. Otherwise the stage persists `{ skipped: true, reason: 'auto:low-value' }` and the pipeline pays no retrieval cost on trivial tasks.
+>
+> **Coming in v2.26.0+**: chokidar watcher for live re-indexing, AST source chunker (tree-sitter / `@babel/parser`), BM25 + cosine hybrid scoring.
+>
 > **v2.24.0 released** — Minor. **RAG Camino C — pre-loop auto-retrieval** (KJC-PCS-0049). After v2.23.0 taught the agents that `kj_rag_query` exists, Karajan now injects prior context for them automatically: a new pre-loop stage queries the vec store with the task description and prepends the top-K chunks to the task before any LLM call.
 >
 > Opt-in: `config.rag.preload.enabled = false` by default. Five guards before the retrieval fires (`disabled`, `no-task`, empty corpus, no hits, error). The stage never throws — best-effort enrichment, opt-out by default, opt-back-out on failure. When all guards pass, the task receives an extra block:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.24.0",
+  "version": "2.25.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/commands/init.js

@@ -544,7 +544,7 @@ async function installSkills(logger, interactive) {
 
   if (installed > 0) {
     logger.info(`Installed ${installed} Karajan skill(s) in .claude/commands/`);
-    logger.info("Available as slash commands: /kj-run, /kj-code, /kj-review, /kj-test, /kj-security, /kj-discover, /kj-architect, /kj-sonar");
+    logger.info("Available as slash commands: /kj-run, /kj-code, /kj-review, /kj-test, /kj-security, /kj-discover, /kj-architect, /kj-sonar, /kj-rag-query");
   } else {
     logger.info("All skills already installed.");
   }

package/src/orchestrator/drivers/pre-loop.js

@@ -41,6 +41,7 @@ import {
   runDiscoverStage, runHuReviewerStage,
 } from "../pre-loop-stages.js";
 import { runRagContextStage } from "../stages/rag-context-stage.js";
+import { shouldPreloadRag } from "../stages/rag-preload-decisor.js";
 // TSK-0336: triage goes through the StageRegistry / StageExecutor contract
 // so canRun / execute / onFailure are actually exercised in production.
 // The registry is a singleton with TriageStage / CoderStage / ReviewerStage
@@ -131,10 +132,24 @@ export async function runPreLoopStages({ config, logger, emitter, eventBase, ses
   // all see prior context without having to call kj_rag_query themselves.
   // Empty store / network / etc. degrade to no-op via the stage itself.
   if (!resumeSkip("ragPreload")) {
-    const ragRes = await runRagContextStage({ config, logger, emitter, eventBase, task });
-    if (!ragRes.skipped && ragRes.contextBlock) {
-      task = `${task}\n\n${ragRes.contextBlock}`;
-      await persistStage("ragPreload", { hits: ragRes.hits.length, scope: config?.rag?.preload?.scope || "all" });
+    // KJC-TSK-0434 (Camino D): Brain decisor heuristic — skip retrieval
+    // when triage + task shape say it would be low-value. Defaults to
+    // policy=auto; `always`/`never` are escape hatches.
+    const decision = shouldPreloadRag({ triage: triageResult.stageResult, task, config });
+    if (!decision.pull) {
+      await persistStage("ragPreload", { skipped: true, reason: decision.reason });
+    } else {
+      const ragRes = await runRagContextStage({ config, logger, emitter, eventBase, task });
+      if (!ragRes.skipped && ragRes.contextBlock) {
+        task = `${task}\n\n${ragRes.contextBlock}`;
+        await persistStage("ragPreload", {
+          hits: ragRes.hits.length,
+          scope: config?.rag?.preload?.scope || "all",
+          decisor: decision.reason,
+        });
+      } else {
+        await persistStage("ragPreload", { skipped: true, reason: ragRes.reason, decisor: decision.reason });
+      }
     }
   }
 

package/src/orchestrator/stages/rag-preload-decisor.js

@@ -0,0 +1,58 @@
+// KJC-TSK-0434 — RAG Camino D: Brain decisor heuristic for retrieval.
+// Decides WHETHER to pay the cost of running the RAG preload stage based
+// on signals from triage + task shape, instead of pre-fetching every run.
+//
+// Returns `{ pull: boolean, reason: string }`. The pre-loop driver
+// skips `runRagContextStage` when `pull === false`.
+//
+// Policies (config.rag.preload.policy):
+//   - "always"  : pull regardless (back-compat with v2.24.0 behaviour)
+//   - "never"   : never pull (useful for benchmarking, debugging)
+//   - "auto"    : heuristic — pull only when triage signals complexity,
+//                 decomposition, or when the task body is long enough
+//                 to suggest non-trivial scope. Default.
+
+const DEFAULT_POLICY = "auto";
+const COMPLEX_LEVELS = new Set(["complex", "high", "epic"]);
+const LONG_TASK_CHARS = 200;
+
+/**
+ * @param {object} params
+ * @param {object} [params.triage]   - triage stage result (may be null)
+ * @param {string} [params.task]     - the user task text
+ * @param {object} [params.config]   - full karajan config
+ * @returns {{ pull: boolean, reason: string }}
+ */
+export function shouldPreloadRag({ triage, task, config } = {}) {
+  const policy = config?.rag?.preload?.policy || DEFAULT_POLICY;
+
+  if (policy === "always") return { pull: true, reason: "policy:always" };
+  if (policy === "never") return { pull: false, reason: "policy:never" };
+
+  // policy === "auto" — apply heuristic.
+  // Brownfield is an explicit user signal — if onboarding produced a
+  // brief and config marks the project as brownfield, prior context is
+  // almost always worth pulling.
+  if (config?.rag?.preload?.brownfield === true) {
+    return { pull: true, reason: "auto:brownfield" };
+  }
+
+  // Triage said this is big enough to decompose → multi-HU run benefits
+  // from prior context fed to researcher/architect/planner.
+  if (triage?.shouldDecompose === true) {
+    return { pull: true, reason: "auto:decompose" };
+  }
+
+  // Triage classified the task as complex / high-effort.
+  if (triage?.level && COMPLEX_LEVELS.has(String(triage.level).toLowerCase())) {
+    return { pull: true, reason: "auto:complex" };
+  }
+
+  // Long task body usually means a brief with context, motivation and
+  // non-trivial scope — worth checking the RAG.
+  if (typeof task === "string" && task.length >= LONG_TASK_CHARS) {
+    return { pull: true, reason: "auto:long-task" };
+  }
+
+  return { pull: false, reason: "auto:low-value" };
+}

package/templates/skills/kj-rag-query.md

@@ -0,0 +1,50 @@
+# kj-rag-query — Query Project RAG index
+
+Query the Project RAG (vector store + embedder) and return the top-K most relevant chunks of the indexed project: plans, onboarding briefs, and (optionally) source code.
+
+Use this when you need prior context about the project before deciding, refactoring, planning, or coding — without scanning the filesystem manually.
+
+## Your task
+
+$ARGUMENTS
+
+## How it works
+
+This skill is a thin wrapper over the Karajan CLI:
+
+```
+kj rag query "<text>" [--scope <all|plans|onboarding|code>] [--top-k <n>] [--json]
+```
+
+Parse `$ARGUMENTS` as the natural-language query plus optional flags:
+
+- `--scope <s>`: restrict retrieval to one source bucket. Default: `all`.
+  - `plans` → indexed plan JSON files (HU titles, scope, blocked_by).
+  - `onboarding` → onboarding briefs from `~/.karajan/onboarding/`.
+  - `code` → indexed source files (only present if user ran `kj rag index --with-sources`).
+- `--top-k <n>`: number of chunks to return. Default: 3. Max recommended: 10.
+- `--json`: emit raw JSON (use when piping into another tool).
+
+If `$ARGUMENTS` is empty, print a one-line usage hint and stop.
+
+## Behavior contract
+
+1. **Empty store**: if the CLI replies with `empty: true`, do NOT block the conversation. Tell the user once: "RAG index is empty — run `kj rag index` to seed it" and continue without prior context.
+2. **Zero hits**: if the store has chunks but no match scored above threshold, say "no relevant prior context" and continue.
+3. **Hits returned**: render each as a short block — `[score] source — snippet` — and use them as background context for the user's actual question. Do NOT dump raw JSON unless `--json` was passed.
+4. **Never re-validate flags**. Pass `--scope`/`--top-k` straight to the CLI; the CLI is the source of truth.
+
+## Examples
+
+User: `/kj-rag-query how does the retriever rank chunks`
+→ `kj rag query "how does the retriever rank chunks"`
+
+User: `/kj-rag-query auth flow --scope plans --top-k 5`
+→ `kj rag query "auth flow" --scope plans --top-k 5`
+
+User: `/kj-rag-query --scope onboarding architecture`
+→ `kj rag query "architecture" --scope onboarding`
+
+## Why this exists (Camino B)
+
+Hosts that load Karajan as Skills (Claude Code without MCP, Cursor without MCP) cannot reach the `kj_rag_query` MCP tool. This skill bridges that gap with the same retrieval contract.