karajan-code 4.7.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.7.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/audit/deterministic-summary.js

@@ -65,7 +65,7 @@ function formatAiSlopBlock(slop) {
 
 function formatInjectionBlock(inj) {
   if (!inj.available) return ["### Prompt-injection scan", `- Status: not available — ${inj.reason || "scan failed"}`, ""];
-  const lines = ["### Prompt-injection scan (specs / domain / onboarding)", `- Files scanned: ${inj.scanned ?? 0}`, `- Findings: ${inj.total ?? 0}`];
+  const lines = ["### Prompt-injection scan (agent-context surface: CLAUDE/AGENTS/GEMINI.md, templates, .rulesync, .karajan)", `- Files scanned: ${inj.scanned ?? 0}`, `- Findings: ${inj.total ?? 0}`];
   if ((inj.total ?? 0) > 0) {
     for (const [severity, items] of Object.entries(groupInjectionBySeverity(inj.findings || []))) {
       if (items.length === 0) continue;

package/src/audit/injection-findings.js

@@ -17,6 +17,15 @@ const SCAN_TARGETS = [
   { rel: ".karajan/specs", kind: "dir" },
   { rel: ".karajan/onboarding", kind: "dir" },
   { rel: ".karajan/domain.md", kind: "file" },
+  // KJC-TSK-0695: the agent-context surface — whatever lands in the host
+  // agent's context every session is the real injection vector.
+  { rel: "CLAUDE.md", kind: "file" },
+  { rel: "AGENTS.md", kind: "file" },
+  { rel: "GEMINI.md", kind: "file" },
+  { rel: ".cursorrules", kind: "file" },
+  { rel: path.join(".github", "copilot-instructions.md"), kind: "file" },
+  { rel: "templates", kind: "dir" },
+  { rel: ".rulesync", kind: "dir" },
 ];
 
 export async function collectInjectionFindings(rootDir, logger = null) {

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")
@@ -379,6 +380,7 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--trend", "Append a sparkline of the harness score across the last 10 runs (uses .karajan/audit-history.db). KJC-TSK-0473.")
     .option("--report-file <path>", "Write the audit report to disk in addition to stdout. <path> may be a file (extension drives format: .md or .json) or a directory (creates audit-<ISO>.<md|json> inside). $KJ_AUDIT_REPORT_DIR env var is used as default directory if no --report-file is given.")
     .option("--deterministic-only", "Skip the LLM analysis entirely. Print/persist only the deterministic findings (basalCost, sonar, stack, growth-delta, webperf). Zero tokens spent. Compatible with --report-file and --json.")
+    .option("--security", "Focused deterministic security pass: prompt-injection scan over the agent-context surface (CLAUDE.md/AGENTS.md/templates/.rulesync/.karajan) + OSV + Semgrep + Sonar. Skips basal-cost, webperf, madge, knip, ai-slop, harness and the LLM — zero tokens. Designed for agents to self-invoke when a task touches sensitive surface (KJC-TSK-0695).")
     .option("-y, --yes", "Auto-confirm the 'Continue with LLM analysis?' prompt. Useful in scripts that want the full audit non-interactively. CI/non-TTY paths already auto-confirm without this flag.")
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "audit", flags, async ({ config, logger }) => {
@@ -402,6 +404,7 @@ export function registerMeta(program, { pkgVersion }) {
           noAiSlop: flags.aiSlop === false,
           reportFile: flags.reportFile || null,
           deterministicOnly: Boolean(flags.deterministicOnly),
+          security: Boolean(flags.security),
           yes: Boolean(flags.yes),
           trend: Boolean(flags.trend),
         });

package/src/commands/audit.js

@@ -237,7 +237,10 @@ function describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHar
   return parts.join(" ");
 }
 
-export async function auditCommand({ task, config, logger, dimensions, json, agentReadiness, path: pathArg, noSonar = false, noOsv = false, noSemgrep = false, noHarness = false, noAiSlop = false, reportFile = null, deterministicOnly = false, yes = false, trend = false, promptFn = null }) {
+export async function auditCommand({ task, config, logger, dimensions, json, agentReadiness, path: pathArg, noSonar = false, noOsv = false, noSemgrep = false, noHarness = false, noAiSlop = false, reportFile = null, deterministicOnly = false, yes = false, trend = false, promptFn = null, security = false }) {
+  // KJC-TSK-0695: --security = the focused pass an agent self-invokes.
+  // Deterministic by definition (zero tokens) and skips non-security stages.
+  if (security) { deterministicOnly = true; noHarness = true; noAiSlop = true; }
   // --agent-readiness is a STANDALONE, deterministic, LLM-free audit
   // dimension. It scores any third-party repo for AI-agent readability
   // (llms.txt presence, page token budgets, robots allowlist, etc.).
@@ -281,6 +284,7 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
       noOsv,
       noSemgrep,
       noAiSlop,
+      ...(security ? { securityOnly: true } : {}),
     };
     const deterministicCtx = await role.collectDeterministic(roleInput);
     const deterministicMd = formatDeterministicSummary(deterministicCtx);

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/config/overrides.js

@@ -77,8 +77,11 @@ const UNDEF_CHECK_FLAGS = [
 ];
 
 function applyRoleOverrides(out, flags) {
+  // A provider override is always a string (`--security codex`). A bare
+  // boolean means the flag belongs to the command itself (`kj audit
+  // --security`, KJC-TSK-0695) and must not become a provider.
   for (const [flag, role] of ROLE_PROVIDER_FLAGS) {
-    if (flags[flag]) out.roles[role].provider = flags[flag];
+    if (typeof flags[flag] === "string" && flags[flag]) out.roles[role].provider = flags[flag];
   }
   // coder/reviewer also update top-level aliases
   if (flags.coder) out.coder = flags.coder;

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."),
   },
@@ -79,6 +82,7 @@ const B = {
       [
         "These findings are never overridable — not even by Solomon arbitration.",
         "PII is never logged; new dependencies need a reason and a pinned version.",
+        "Sensitive surface (auth, user input, secrets, network, deps)? Self-invoke `kj audit --security` — deterministic, zero tokens: prompt-injection over the agent-context files + OSV + Semgrep + Sonar — and remediate the findings before requesting review.",
       ],
       "findings with severity, category and file:line — or an explicit 'no security surface touched'."),
   },

package/src/environment/playbook.js

@@ -66,10 +66,15 @@ Invariants (the git gates enforce these — they are not suggestions):
   and it must be reviewed again. Disagree with a rejection? \`kj solomon\`.
 - Security findings are never overridable — not even by arbitration. You
   absorb the security role: \`kj brief security\` states what must be true.
+  Task touches auth, user input, secrets, network or deps? Run
+  \`kj audit --security\` (zero tokens) and remediate BEFORE the review.
 - A design decision the card's AC don't cover belongs to the USER: record
   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 };
+}

package/src/roles/audit-role.js

@@ -48,13 +48,17 @@ export class AuditRole extends AgentRole {
    *   execute() would gather internally)
    */
   async collectDeterministic(input) {
+    // KJC-TSK-0695: securityOnly = the focused pass an agent self-invokes
+    // when a task touches sensitive surface. Only the security collectors
+    // run (sonar, osv, semgrep, injection) — zero tokens, fast.
+    const securityOnly = typeof input === "object" ? Boolean(input?.securityOnly) : false;
     const noSonar = typeof input === "object" ? Boolean(input?.noSonar) : false;
     const noOsv = typeof input === "object" ? Boolean(input?.noOsv) : false;
     const noSemgrep = typeof input === "object" ? Boolean(input?.noSemgrep) : false;
-    const noMadge = typeof input === "object" ? Boolean(input?.noMadge) : false;
-    const noKnip = typeof input === "object" ? Boolean(input?.noKnip) : false;
+    const noMadge = (typeof input === "object" ? Boolean(input?.noMadge) : false) || securityOnly;
+    const noKnip = (typeof input === "object" ? Boolean(input?.noKnip) : false) || securityOnly;
     const noInjectionScan = typeof input === "object" ? Boolean(input?.noInjectionScan) : false;
-    const noAiSlop = typeof input === "object" ? Boolean(input?.noAiSlop) : false;
+    const noAiSlop = (typeof input === "object" ? Boolean(input?.noAiSlop) : false) || securityOnly;
     const projectDir = this.config?.projectDir || process.cwd();
     let basalCost = null;
     let growthDelta = null;
@@ -67,11 +71,13 @@ export class AuditRole extends AgentRole {
     let deadExports = null;
     let injectionFindings = null;
     let aiSlop = null;
-    try {
-      basalCost = await measureBasalCost(projectDir);
-      const previous = await loadPreviousAudit(projectDir);
-      growthDelta = computeGrowthDelta(basalCost, previous);
-    } catch { /* basal cost is best-effort */ }
+    if (!securityOnly) {
+      try {
+        basalCost = await measureBasalCost(projectDir);
+        const previous = await loadPreviousAudit(projectDir);
+        growthDelta = computeGrowthDelta(basalCost, previous);
+      } catch { /* basal cost is best-effort */ }
+    }
     try {
       stack = await detectProjectStack(projectDir);
     } catch { /* stack detect is best-effort */ }
@@ -80,9 +86,11 @@ export class AuditRole extends AgentRole {
         sonarFindings = await collectSonarFindings(this.config, this.logger);
       } catch { /* sonar fetch is best-effort */ }
     }
-    try {
-      webperf = collectWebPerfInput(stack, this.config);
-    } catch { /* webperf input is best-effort */ }
+    if (!securityOnly) {
+      try {
+        webperf = collectWebPerfInput(stack, this.config);
+      } catch { /* webperf input is best-effort */ }
+    }
     // OSV vulnerabilities — KJC-TSK-0365. Best-effort: missing
     // osv-scanner binary returns available:false and the audit
     // continues without the section.