karajan-code 4.8.0 → 4.9.0

package/library/logical-clocks-lamport.md

@@ -0,0 +1,40 @@
+# Logical clocks & happened-before (Lamport, 1978)
+
+## Problem signature
+
+Events across processes/services need a consistent order, and wall clocks
+disagree: "last write wins" flip-flops between replicas, audit logs interleave
+impossibly, a consumer sees an update before the create it depends on.
+
+## Reach for it when
+
+- Two or more writers/emitters produce events whose CAUSAL order matters
+  (A caused B must never be observed as B before A).
+- You are tempted to "fix it with NTP" or timestamps — clock skew makes
+  timestamp ordering a race, not an order.
+- You need to detect concurrent (conflicting) updates, not just order them:
+  that is the vector-clock extension (one counter per node; compare
+  component-wise; incomparable = concurrent — see Dynamo's usage).
+
+## Do NOT reach for it when
+
+- A single writer (or a single database) already totally orders the events —
+  its sequence/autoincrement/WAL IS the clock. Most CRUD apps live here.
+- You only need "roughly recent first" for humans (feeds, logs for reading):
+  wall-clock timestamps are fine and far simpler.
+- You need a TOTAL order agreed by all nodes: logical clocks give a partial
+  causal order; total order needs consensus (Raft/Paxos) or a sequencer.
+
+## Trade-offs
+
+- Lamport clocks are one counter: tiny, but they cannot tell concurrent from
+  ordered. Vector clocks can, at O(nodes) metadata per event that must be
+  carried, stored and pruned.
+- Causality tracking pushes conflict RESOLUTION to the reader (semantic
+  merge, CRDTs, or ask-the-user) — ordering was the easy half.
+
+## Canonical source
+
+Leslie Lamport, "Time, Clocks, and the Ordering of Events in a Distributed
+System", Communications of the ACM, 1978. The happened-before relation and
+the clock condition come verbatim from it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -48,6 +48,7 @@
   "files": [
     "src/",
     "bin/",
+    "library/",
     "templates/",
     "scripts/",
     "vendor/tree-sitter-grammars/",
@@ -108,7 +109,7 @@
     "express-rate-limit": "^8.5.0",
     "helmet": "^8.1.0",
     "js-yaml": "^4.2.0",
-    "karajan-core": "^1.0.0",
+    "karajan-core": "^1.4.0",
     "karajan-rag": "^1.2.0",
     "knip": "^6.15.0",
     "madge": "^8.0.0",

package/src/cli/register-meta.js

@@ -294,6 +294,7 @@ export function registerMeta(program, { pkgVersion }) {
     .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("--library", "Query the distilled engineering canon (pattern cards shipped with kj + ~/.karajan/library + project .karajan/library) instead of the project corpus. 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")
     .option("--json", "Output the hits as JSON")

package/src/commands/rag.js

@@ -7,6 +7,7 @@ import { makeGovernedEmbedder } from "../rag/governed-embedder.js";
 import { indexProject, indexProjectDelta } from "../rag/indexer.js";
 import { query } from "../rag/retriever.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 { getKarajanHome } from "../utils/paths.js";
 
@@ -47,6 +48,13 @@ export async function ragIndexCommand({ config, logger, flags = {} }) {
       });
     }
     if (totals.head) setLastIndexedCommit(db, slug, totals.head);
+    // KJC-TSK-0697 — the library corpus refreshes on every index run.
+    // Best-effort and cheap: a handful of cards, content-hash dedup.
+    try {
+      await indexLibrary({ db, embedder, logger, projectDir });
+    } catch (err) {
+      logger.warn?.(`[rag] library index failed: ${err.message}`);
+    }
     if (flags.json) {
       process.stdout.write(`${JSON.stringify(totals)}\n`);
     } else {
@@ -87,7 +95,10 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
     // <slug>` overrides. Pre-v2.27 chunks with NULL slug are only visible
     // when no filter is in effect.
     const detected = projectSlug(config?.projectDir || process.cwd());
-    const project = flags.project === "all" ? null : (flags.project || detected || null);
+    // KJC-TSK-0697 — `--library` targets the distilled-canon collection:
+    // its own project namespace plus the kind filter.
+    const library = Boolean(flags.library);
+    const project = library ? LIBRARY_PROJECT : (flags.project === "all" ? null : (flags.project || detected || null));
     // KJC-BUG-0061 follow-up: align the CLI `--json` shape with the MCP
     // handler. The MCP tool responds `{ hits: [], empty: true, topK, scope }`
     // so agents (and the `/kj-rag-query` skill from Camino B) have a
@@ -101,7 +112,12 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
     }
     const mode = flags.mode || "hybrid";
     const alpha = Math.max(0, Math.min(1, Number(flags.alpha) || 0.6));
-    const where = flags.where || null;
+    // 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.
+    const where = library
+      ? (flags.where ? `kind=library AND ${flags.where}` : "kind=library")
+      : (flags.where || null);
     const rerankOpts = flags.rerank ? { model: flags.rerankModel } : null;
     const hits = await query(db, makeGovernedEmbedder(config), text, { topK, scope, project, mode, alpha, where, rerankOpts });
     if (flags.json) {

package/src/environment/briefs.js

@@ -36,6 +36,7 @@ const B = {
         "Behavior changes carry their test in the same step.",
         "Data-model or API changes never share a step with anything else.",
         "No PR beyond ~150 net lines — partition upfront, not at the gate.",
+        "Non-trivial task? Name at least two approaches — one as if the codebase didn't exist — and say why the winner won.",
       ],
       "numbered-free plan: steps {description, files}, risks, out-of-scope."),
   },
@@ -56,6 +57,8 @@ const B = {
       [
         "Check the ADRs before deciding — never against an accepted one.",
         "Prefer the design that deletes code over the one that adds layers.",
+        "One alternative answers: what would you build as if the codebase didn't exist? Picking the legacy-shaped path is fine — picking it by inertia is not.",
+        "Ground that alternative in the canon: `kj rag query --library \"<problem signature>\"` serves distilled pattern cards with when-NOT-to-apply and citations.",
       ],
       "chosen design, discarded alternatives with reasons, affected boundaries."),
   },

package/src/environment/playbook.js

@@ -72,6 +72,9 @@ Invariants (the git gates enforce these — they are not suggestions):
   it as a proposed ADR (\`kj adr add\`) and ask — never bury it in a PR
   bullet. An oversized-diff warning is not an opinion either: partition,
   or get an explicit OK.
+- A non-trivial plan names at least two approaches — one as if the
+  codebase didn't exist — and says why the winner won. Following the
+  legacy line is a choice, never a default.
 - Branch first: never commit on the base branch — every change reaches it
   through an atomic PR (~150 net lines, Conventional Commits). More than one
   task, or the base tree must stay untouched? \`kj worktree start <slug>\`

package/src/rag/library.js

@@ -0,0 +1,62 @@
+/**
+ * library — the distilled engineering canon as its own RAG collection
+ * (KJC-TSK-0697). Markdown cards from `<pkg>/library/`, `~/.karajan/library/`
+ * and `<project>/.karajan/library/` index into the SAME global rag.db,
+ * isolated by project="library" + kind="library", so `kj rag query --library`
+ * reaches the canon and normal project queries never see it. The architect
+ * consults it to ground the greenfield alternative (KJC-TSK-0696).
+ */
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { extname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import os from "node:os";
+
+import { chunkMarkdown } from "./chunker.js";
+import { insertChunk, deleteChunksBySource, findChunkByHash } from "./vec-store.js";
+
+export const LIBRARY_PROJECT = "library";
+
+const SHIPPED_LIBRARY_DIR = fileURLToPath(new URL("../../library", import.meta.url));
+
+/** Existing library dirs, shipped canon first. */
+export function libraryDirs({ pkgLibraryDir = SHIPPED_LIBRARY_DIR, home = os.homedir(), projectDir = process.cwd() } = {}) {
+  const candidates = [pkgLibraryDir, join(home, ".karajan", "library"), join(projectDir, ".karajan", "library")];
+  return candidates.filter((d) => existsSync(d));
+}
+
+/**
+ * Index every markdown card found in the library dirs. Idempotent: chunks
+ * re-index per source and identical bodies skip the embedder (content-hash
+ * dedup within the library project).
+ */
+export async function indexLibrary({ db, embedder, logger = console, pkgLibraryDir, home, projectDir } = {}) {
+  let indexed = 0, failed = 0, files = 0;
+  for (const dir of libraryDirs({ pkgLibraryDir, home, projectDir })) {
+    for (const name of readdirSync(dir)) {
+      if (extname(name).toLowerCase() !== ".md") continue;
+      const path = join(dir, name);
+      files += 1;
+      const chunks = chunkMarkdown(readFileSync(path, "utf8"), { path, kind: "library" });
+      const hashed = chunks.map((ch) => ({ ch, contentHash: createHash("sha256").update(ch.text).digest("hex") }));
+      // Unchanged card (every chunk body already known) → skip before the
+      // delete, so idempotent re-runs never touch the embedder.
+      if (hashed.length && hashed.every(({ contentHash }) => findChunkByHash(db, contentHash, LIBRARY_PROJECT))) continue;
+      deleteChunksBySource(db, path);
+      for (const { ch, contentHash } of hashed) {
+        try {
+          if (findChunkByHash(db, contentHash, LIBRARY_PROJECT)) continue;
+          const embedding = await embedder.embed(ch.text);
+          insertChunk(db, { source: path, kind: "library", text: ch.text, metadata: ch.metadata, embedding, project: LIBRARY_PROJECT, contentHash });
+          indexed += 1;
+        } catch (err) {
+          failed += 1;
+          logger.warn?.(`[rag-library] embed failed for ${path}: ${err.message}`);
+        }
+      }
+    }
+  }
+  if (files) logger.info?.(`[rag-library] ${files} card(s) → ${indexed} chunk(s) (${failed} failed)`);
+  return { files, indexed, failed };
+}