karajan-code 2.23.0 → 2.24.0

package/README.md

@@ -345,6 +345,31 @@ Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 
 ## Recent releases
 
+> **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:
+>
+> ```markdown
+> ## Prior context from RAG (auto-retrieved, top N)
+>
+> ### [plan · AUTH-1] /path/to/plan.json
+>
+> <chunk text, truncated 600 chars>
+> ```
+>
+> Because `task` flows through `runPlanningPhases` to researcher / architect / planner via parameter passing, **one mutation feeds six consumers** — no per-stage prompt wrapper, no fan-out through `pipelineFlags`. Triage runs first because its `roleOverrides` gate the rest of the pipeline; the RAG stage runs right after, before `domainCurator`.
+>
+> Workflow:
+>
+> ```bash
+> kj onboard
+> kj rag index
+> yq -i '.rag.preload.enabled = true' ~/.karajan/kj.config.yml
+> kj run task.md  # researcher/architect/planner/coder all see prior context
+> ```
+>
+> **Coming in v2.25.0+**: Camino B (`/kj-rag-query` slash command for Skills hosts), Camino D (Brain decisor heuristic deciding **when** to pre-fetch based on task complexity — refinement on top of C), chokidar watcher for live re-indexing, AST source chunker, BM25 + cosine hybrid scoring.
+>
 > **v2.23.0 released** — Minor. **RAG exposed to agents and humans alike** (KJC-PCS-0049, Steps 7+8+Camino A). After v2.22.0's CLI MVP, the corpus is now reachable from three more places.
 >
 > 1. **MCP tools** `kj_rag_query` + `kj_rag_index` (PR #815). Any MCP-connected agent — Claude Desktop, Cursor, Claude Code, Karajan's own roles — can call them. Tool count 25 → 27. Empty store responds `empty: true` so agents have a deterministic recovery signal.

package/package.json

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

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

@@ -40,6 +40,7 @@ import {
   runResearcherStage, runArchitectStage, runPlannerStage,
   runDiscoverStage, runHuReviewerStage,
 } from "../pre-loop-stages.js";
+import { runRagContextStage } from "../stages/rag-context-stage.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
@@ -123,6 +124,20 @@ export async function runPreLoopStages({ config, logger, emitter, eventBase, ses
   applyTriageOverrides(pipelineFlags, triageResult.roleOverrides);
   await persistStage("triage", triageResult.stageResult);
 
+  // --- RAG preload (KJC-PCS-0049 Camino C, opt-in) ---
+  // Runs only when config.rag.preload.enabled === true. Queries the local
+  // vector store with the task description, prepends the top-K chunks to
+  // the task as a markdown block so researcher/architect/planner/coder
+  // 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" });
+    }
+  }
+
   // --- Brain decisor (opt-in, intent-driven routing) ---
   //
   // When enabled, translates triage output + task text + CLI overrides into a

package/src/orchestrator/stages/rag-context-stage.js

@@ -0,0 +1,60 @@
+// KJC-PCS-0049 Camino C — pre-loop RAG retrieval stage.
+// Runs between triage and domainCurator. When `config.rag.preload.enabled`
+// is true and the corpus has chunks, queries the retriever with the
+// task text and returns a markdown block ready to prepend to the task.
+// Failures degrade gracefully (warn + continue); the rest of the pipeline
+// never sees an exception from this stage.
+import { emitProgress, makeEvent } from "../../utils/events.js";
+import { openVecStore, countChunks } from "../../rag/vec-store.js";
+import { OllamaEmbedder } from "../../rag/embedder.js";
+import { query } from "../../rag/retriever.js";
+
+const DEFAULT_TOP_K = 5;
+const DEFAULT_SCOPE = "all";
+const MAX_CHUNK_CHARS = 600;
+
+/**
+ * Runs the RAG preload stage. Returns:
+ *   { skipped: true, reason }                  — when disabled / empty / error
+ *   { skipped: false, contextBlock, hits }     — markdown block + raw hits
+ *
+ * The caller decides whether to mutate `task` with the contextBlock. We
+ * keep that responsibility at the call site so this module stays pure.
+ */
+export async function runRagContextStage({ config, logger, emitter, eventBase, task }) {
+  const preload = config?.rag?.preload;
+  if (!preload?.enabled) return { skipped: true, reason: "disabled" };
+  if (typeof task !== "string" || task.length === 0) return { skipped: true, reason: "no-task" };
+  try {
+    const dim = config?.rag?.embedder?.dim || 768;
+    const db = openVecStore({ dim });
+    try {
+      if (countChunks(db) === 0) {
+        logger?.info?.("[rag-preload] corpus is empty, skipping (run `kj rag index` to seed)");
+        return { skipped: true, reason: "empty" };
+      }
+      const topK = preload.topK || DEFAULT_TOP_K;
+      const scope = preload.scope || DEFAULT_SCOPE;
+      const cfg = config?.rag?.embedder || {};
+      const embedder = new OllamaEmbedder({ url: cfg.url, model: cfg.model, dim });
+      const hits = await query(db, embedder, task, { topK, scope });
+      if (hits.length === 0) return { skipped: true, reason: "no-hits" };
+      const lines = hits.map((h) => {
+        const label = h.metadata?.hu_id || h.metadata?.symbol || h.metadata?.headingPath?.join(" > ") || "block";
+        const text = h.text.length > MAX_CHUNK_CHARS ? `${h.text.slice(0, MAX_CHUNK_CHARS)}…` : h.text;
+        return `### [${h.kind} · ${label}] ${h.source}\n\n${text}`;
+      });
+      const contextBlock = `## Prior context from RAG (auto-retrieved, top ${hits.length})\n\n${lines.join("\n\n")}`;
+      emitProgress(emitter, makeEvent("rag-preload:hits", { ...eventBase, stage: "rag-preload" }, {
+        message: `RAG preload: injected ${hits.length} chunk(s) into the task context`,
+        detail: { topK, scope, hits: hits.length },
+      }));
+      return { skipped: false, contextBlock, hits };
+    } finally {
+      db.close();
+    }
+  } catch (err) {
+    logger?.warn?.(`[rag-preload] failed (non-blocking): ${err.message}`);
+    return { skipped: true, reason: "error", error: err.message };
+  }
+}