karajan-code 2.32.0 → 2.34.0

package/README.md

@@ -345,6 +345,31 @@ Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 
 ## Recent releases
 
+> **v2.34.0 released** — Minor. Two epics in one window. **KJC-PCS-0052 "Multi-language RAG"** — Python, Rust, Go and Java join JS/TS as first-class citizens of the local RAG index (AST chunkers via `web-tree-sitter` + multi-lang watcher + audit/onboarder multi-stack manifest sniffer), so a polyglot repo gets the same semantic retrieval surface as a single-language one. **KJC-PCS-0053 "RAG Quality & Observability"** — `kj rag eval` ships a frozen golden-query harness with `recall@k + MRR` (CI-gated via `--min-recall`), content-hash dedup skips redundant embeddings, optional MMR diversification returns *different* chunks instead of five near-duplicates, and `docs/RAG.md` gains a six-questions deep-dive documenting the system end-to-end. `kj rag index --since <ref>` + a post-merge git hook keep the index in sync with `git pull` / merge without manual intervention.
+>
+> - **`vec_store_meta` + `kj rag index --since`** (PR #882, KJC-TSK-0455 PR1): per-project last-indexed-commit stamp; `--since auto` resolves it; explicit refs honoured; missing baseline falls back to a full index with a friendly warning. Idempotent.
+> - **Post-merge hook + pre-run drift check** (PR #883, KJC-TSK-0455 PR2): new `kj rag install-hooks` writes `.git/hooks/post-merge` so `git pull` auto-triggers a delta re-index. Pre-run drift check emits a one-line hint when `HEAD` is ahead of the last indexed SHA by more than N files.
+> - **Language registry + Python canary** (PR #884, KJC-TSK-0474): new `src/lang/registry.js` with `adapterForPath(file)`; the indexer + watcher both route through it. Python lands as the first non-JS adapter to exercise the registry shape from day one.
+> - **Python AST chunker** (PR #886, KJC-TSK-0478) and **Rust AST chunker** (PR #888, KJC-TSK-0479): web-tree-sitter walkers + regex fallbacks, grammars vendored under `vendor/tree-sitter-grammars/*.wasm` so SEA binaries stay self-contained.
+> - **Indexer prepares Python / Rust grammars** (PR #889, KJC-TSK-0480): `prepareAdapters()` awaits the grammar loads before walking so the first file doesn't pay the cold-load tax mid-batch.
+> - **Go AST chunker** (PR #890, KJC-TSK-0481): tree-sitter walker + regex fallback. Method receivers rendered explicitly so retrieval surfaces method-vs-function disambiguation without re-parsing.
+> - **Multi-stack manifest sniffer for `basal-cost`** (PR #891, KJC-TSK-0476): `kj audit` now reads Python (`pyproject.toml`, `requirements*.txt`), Rust (`Cargo.toml`), Go (`go.mod`) and Java (`pom.xml`, `build.gradle*`) manifests alongside `package.json`. Cost estimates no longer assume JS/TS.
+> - **Multi-stack frameworks in audit bundle** (PR #892, KJC-TSK-0477): the audit bundle JSON gains a `stacks` field listing detected language stacks + framework hints (Django, Flask, Actix, Tokio, Gin, Echo, Spring, Quarkus...). Onboarder + audit role render polyglot reality.
+> - **Java AST chunker** (PR #893, KJC-TSK-0486): two-level walker (class / interface / enum / record → method / constructor) + regex fallback. Inner classes flattened with `Outer$Inner` symbols.
+> - **`docs/RAG.md` six-questions deep-dive** (PR #894, KJC-TSK-0485): per-language chunker table, six-provider embedder matrix, hybrid + rerank + metadata filter, update strategy table, validation tiers. Excluded from the shrink-budget gate.
+> - **Watcher derived from language registry** (PR #895, KJC-TSK-0482): `kj watch` matcher no longer hard-codes JS/TS. Python / Rust / Go / Java sources trigger live re-index.
+> - **Content-hash skip-on-match** (PR #896, KJC-TSK-0484 PR-A): each chunk gains a `sha256` column; identical bodies skip the Ollama call. Re-indexing identical files now costs zero embeddings.
+> - **MMR diversification in retriever** (PR #898, KJC-TSK-0484 PR-B): optional `rag.search.mmr` over the top-N candidates; lambda (`rag.search.mmrLambda`, default 0.5) trades pure cosine relevance for diversity. Off by default.
+> - **Retrieval-quality harness** (PR #899, KJC-TSK-0483 PR-A): pure `runEval(queries, runQuery, { topK, ks })` scoring recall@k (binary) + MRR. `tests/rag/golden-queries.json` ships 20 entries covering the public surface of `src/rag/`.
+> - **`kj rag eval` CLI + baseline docs** (PR #900, KJC-TSK-0483 PR-B): subcommand wires the harness to the indexed corpus, emits aggregate + per-query report (human or `--json`), and sets `process.exitCode = 1` when `--min-recall <n>` is set and aggregate falls below — drop-in CI gate after `kj rag index`.
+
+> **v2.33.0 released** — Minor. **AI Harness Scorecard golden metric (KJC-PCS-0051, Plan B)** — every `kj audit` now boots a Docker one-shot of `addyosmani/ai-harness-scorecard`, gets a deterministic 0–100 score + A–F grade, persists it to a per-project `audit-history.db`, and on the next run renders the delta vs the previous baseline plus an optional Unicode-bar trend sparkline. One golden number for "how AI-friendly is this repo today vs last week," zero LLM tokens spent.
+>
+> - **Harness Docker one-shot** (PR #877, KJC-TSK-0470): `src/audit/harness-runner.js` runs `docker run --rm -v <repo>:/repo addyosmani/ai-harness-scorecard analyze`, parses the verdict, auto-skips on missing Docker. `--no-harness` opts out.
+> - **`kj audit` integrates the score** (PR #878, KJC-TSK-0471): new harness-section renderer; JSON output gains `harnessScore`; runs during the deterministic phase so `--deterministic-only` users get it too.
+> - **Per-project audit history** (PR #879, KJC-TSK-0472): `.karajan/audit-history.db` (better-sqlite3 + WAL + `PRAGMA user_version=1`) persists every run. SEA bundle stubbed (degrades gracefully); npm install unlocks history.
+> - **Diff + trend sparkline** (PR #880, KJC-TSK-0473): `src/audit/audit-history-display.js` (pure module, safe in SEA) computes overall delta + per-category deltas + biggest improvement/regression + stale-baseline flag (>30 days). New `--trend` flag prints a `▁▂▃▄▅▆▇█` sparkline over the last N runs.
+>
 > **v2.32.0 released** — Minor. **AI Harness Scorecard hardening (KJC-PCS-0051)** — Plan A closes five FAILs from the external scorecard audit in one sprint: Prettier `--check`, Coverage v8 reports, Conventional Commits enforcement, nightly drift detection, and an unsafe-code lint policy. Plus two bug fixes shipped alongside.
 >
 > - **Prettier `--check` CI job** (PR #868, KJC-TSK-0464): new `format` job blocks PRs whose formatting drifts from `.prettierrc.json`. Scope narrow at first (`.github/workflows/`, root config); future PRs fold in more dirs under the shrink-budget cap.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.32.0",
+  "version": "2.34.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -37,6 +37,7 @@
     "bin/",
     "templates/",
     "scripts/",
+    "vendor/tree-sitter-grammars/",
     "packages/hu-board/src/",
     "packages/hu-board/public/",
     "packages/hu-board/package.json",
@@ -85,7 +86,8 @@
     "knip": "^6.14.1",
     "madge": "^8.0.0",
     "sqlite-vec": "^0.1.9",
-    "valibot": "^1.3.1"
+    "valibot": "^1.3.1",
+    "web-tree-sitter": "^0.26.9"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

package/scripts/esbuild-sea.config.mjs

@@ -191,6 +191,15 @@ const ragStubPlugin = {
   },
 };
 
+// KJC-TSK-0472 — audit-history sqlite stub (same reasoning as rag/hu-board stubs).
+const auditHistoryStubPlugin = {
+  name: "audit-history-stub",
+  setup(b) {
+    b.onResolve({ filter: /[\\/]audit[\\/]audit-history\.js$/ }, (a) => ({ path: a.path, namespace: "ahs" }));
+    b.onLoad({ filter: /.*/, namespace: "ahs" }, () => ({ contents: "module.exports = { __esModule: false, persistAuditRun: () => ({ ok: false, error: 'history disabled in SEA' }), getAuditHistoryDbPath: () => null, openAuditHistoryDb: () => null, recordAuditRun: () => null, listRecentRuns: () => [], countRuns: () => 0, pruneOldRuns: () => 0, getLatestPreviousRun: () => null, getRecentScores: () => [] };", loader: "js" }));
+  },
+};
+
 /** @type {import('esbuild').BuildOptions} */
 export const seaBuildOptions = {
   entryPoints: ["src/cli.js"],
@@ -221,6 +230,6 @@ export const seaBuildOptions = {
   // throws → collector returns available:false. npm installs get knip
   // resolved normally from node_modules.
   external: ["better-sqlite3", "madge", "knip", "oxc-parser", "oxc-resolver"],
-  plugins: [seaTransformPlugin, huBoardStubPlugin, ragStubPlugin],
+  plugins: [seaTransformPlugin, huBoardStubPlugin, ragStubPlugin, auditHistoryStubPlugin],
   logLevel: "info",
 };

package/scripts/git-hooks/post-merge

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# KJC-TSK-0455 — Auto-refresh the local RAG index after a merge so retrieval
+# never serves stale code. Installed by `kj rag install-hooks`. The marker
+# in this comment is how the installer tells kj-managed hooks from user hooks.
+set -euo pipefail
+if ! command -v kj >/dev/null 2>&1; then exit 0; fi
+kj rag index --since auto >/dev/null 2>&1 || true

package/src/audit/audit-history-display.js

@@ -0,0 +1,61 @@
+// KJC-TSK-0473 — Pure display helpers for audit history (diff + sparkline).
+// No DB / native-module deps; safe to bundle into the SEA binary.
+
+const SPARK_BARS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"];
+
+function scoreOf(c) {
+  if (!c || typeof c !== "object") return null;
+  return typeof c.score === "number" ? c.score : typeof c.percent === "number" ? c.percent : null;
+}
+
+export function computeHistoryDiff(currentHarness, previousRow) {
+  if (!currentHarness || typeof currentHarness.score !== "number") return null;
+  if (!previousRow || typeof previousRow.score !== "number") return { previousScore: null, firstRun: true };
+  let prevCats = {};
+  try { prevCats = previousRow.categories_json ? JSON.parse(previousRow.categories_json) || {} : {}; } catch { /* keep empty */ }
+  const currCats = currentHarness.categories || {};
+  const categoryDeltas = [];
+  for (const name of Object.keys(currCats)) {
+    const cur = scoreOf(currCats[name]);
+    const prev = scoreOf(prevCats[name]);
+    if (typeof cur === "number" && typeof prev === "number") {
+      categoryDeltas.push({ name, current: cur, previous: prev, delta: cur - prev });
+    }
+  }
+  const sorted = [...categoryDeltas].sort((a, b) => b.delta - a.delta);
+  const t = previousRow.timestamp ? Date.parse(previousRow.timestamp) : NaN;
+  const ageDays = Number.isNaN(t) ? null : Math.floor((Date.now() - t) / 86400000);
+  return {
+    previousScore: previousRow.score,
+    previousGrade: previousRow.grade || null,
+    previousTimestamp: previousRow.timestamp,
+    delta: currentHarness.score - previousRow.score,
+    categoryDeltas,
+    biggestImprovement: sorted.find((c) => c.delta > 0) || null,
+    biggestRegression: [...sorted].reverse().find((c) => c.delta < 0) || null,
+    baselineAgeDays: ageDays,
+    baselineStale: ageDays != null && ageDays > 30,
+  };
+}
+
+export function formatHistoryDiff(diff) {
+  if (!diff) return "";
+  if (diff.firstRun) return "_First run for this project — no baseline yet._";
+  const arrow = diff.delta > 0 ? "↑" : diff.delta < 0 ? "↓" : "=";
+  const sign = diff.delta > 0 ? "+" : "";
+  const prevDate = (diff.previousTimestamp || "").slice(0, 10);
+  const lines = [`**Δ ${sign}${diff.delta} ${arrow} vs run anterior** (${prevDate}, ${diff.previousScore}/100 ${diff.previousGrade || ""})`];
+  if (diff.baselineStale) lines.push(`> ⚠ baseline antigua (${diff.baselineAgeDays} días) — considera ejecutar \`kj audit\` con más frecuencia.`);
+  if (diff.biggestImprovement) lines.push(`- Mayor mejora: **${diff.biggestImprovement.name}** (+${diff.biggestImprovement.delta})`);
+  if (diff.biggestRegression) lines.push(`- Mayor regresión: **${diff.biggestRegression.name}** (${diff.biggestRegression.delta})`);
+  return lines.join("\n");
+}
+
+export function formatTrendSparkline(scores) {
+  const xs = (scores || []).map((r) => (typeof r === "number" ? r : r?.score)).filter((n) => typeof n === "number");
+  if (xs.length === 0) return "";
+  if (xs.length === 1) return `Score trend: ${xs[0]} (single run)`;
+  const min = Math.min(...xs), max = Math.max(...xs), range = max - min || 1;
+  const bars = xs.map((n) => SPARK_BARS[Math.min(SPARK_BARS.length - 1, Math.floor(((n - min) / range) * (SPARK_BARS.length - 1)))]).join("");
+  return `Score trend (last ${xs.length} runs): ${xs[0]} ${bars} ${xs[xs.length - 1]}`;
+}

package/src/audit/audit-history.js

@@ -0,0 +1,102 @@
+// KJC-TSK-0472 — Per-project audit history (sqlite at .karajan/audit-history.db).
+import path from "node:path";
+import fs from "node:fs";
+import Database from "better-sqlite3";
+
+const SCHEMA_VERSION = 1;
+
+export function getAuditHistoryDbPath(projectDir) {
+  return path.join(projectDir, ".karajan", "audit-history.db");
+}
+
+export function openAuditHistoryDb(projectDir) {
+  const dbPath = getAuditHistoryDbPath(projectDir);
+  fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+  const db = new Database(dbPath);
+  db.pragma("journal_mode = WAL");
+  migrate(db);
+  return db;
+}
+
+function migrate(db) {
+  const current = db.pragma("user_version", { simple: true });
+  if (current >= SCHEMA_VERSION) return;
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS audits (
+      run_id TEXT PRIMARY KEY,
+      timestamp TEXT NOT NULL,
+      git_sha TEXT,
+      score INTEGER,
+      grade TEXT,
+      categories_json TEXT,
+      raw_report_path TEXT
+    );
+    CREATE TABLE IF NOT EXISTS findings (
+      run_id TEXT NOT NULL,
+      category TEXT,
+      check_id TEXT,
+      status TEXT,
+      weight REAL,
+      FOREIGN KEY(run_id) REFERENCES audits(run_id) ON DELETE CASCADE
+    );
+    CREATE INDEX IF NOT EXISTS idx_audits_timestamp ON audits(timestamp DESC);
+    CREATE INDEX IF NOT EXISTS idx_findings_run_id ON findings(run_id);
+  `);
+  db.pragma(`user_version = ${SCHEMA_VERSION}`);
+}
+
+// `harness` may be null (--no-harness / docker offline): row still inserted with NULL score.
+export function recordAuditRun(db, { runId, timestamp, gitSha, harness, rawReportPath }) {
+  const categories = harness?.categories ? JSON.stringify(harness.categories) : null;
+  const checks = Array.isArray(harness?.checks) ? harness.checks : [];
+  const insertRun = db.prepare(`INSERT INTO audits (run_id, timestamp, git_sha, score, grade, categories_json, raw_report_path) VALUES (?, ?, ?, ?, ?, ?, ?)`);
+  const insertFinding = db.prepare(`INSERT INTO findings (run_id, category, check_id, status, weight) VALUES (?, ?, ?, ?, ?)`);
+  db.transaction(() => {
+    insertRun.run(runId, timestamp, gitSha || null, harness?.score ?? null, harness?.grade ?? null, categories, rawReportPath || null);
+    for (const c of checks) {
+      insertFinding.run(runId, c.category || null, c.name || c.id || null, c.passed ? "pass" : "fail", typeof c.weight === "number" ? c.weight : null);
+    }
+  })();
+  return { runId, inserted: 1 + checks.length };
+}
+
+export function listRecentRuns(db, limit = 10) {
+  return db.prepare(`SELECT run_id, timestamp, git_sha, score, grade FROM audits ORDER BY timestamp DESC LIMIT ?`).all(limit);
+}
+
+// KJC-TSK-0473 — Fetch previous run (excluding current) for diff rendering.
+export function getLatestPreviousRun(db, currentTimestamp) {
+  return db.prepare(`SELECT run_id, timestamp, git_sha, score, grade, categories_json FROM audits WHERE timestamp < ? AND score IS NOT NULL ORDER BY timestamp DESC LIMIT 1`).get(currentTimestamp || new Date().toISOString()) || null;
+}
+
+// KJC-TSK-0473 — Score timeline (ASC) for sparkline rendering.
+export function getRecentScores(db, limit = 10) {
+  const rows = db.prepare(`SELECT timestamp, score FROM audits WHERE score IS NOT NULL ORDER BY timestamp DESC LIMIT ?`).all(limit);
+  return rows.reverse();
+}
+
+export function countRuns(db) {
+  return db.prepare(`SELECT COUNT(*) AS n FROM audits`).get().n;
+}
+
+export function pruneOldRuns(db, keep = 50) {
+  const ids = db.prepare(`SELECT run_id FROM audits ORDER BY timestamp DESC LIMIT -1 OFFSET ?`).all(keep).map((r) => r.run_id);
+  if (ids.length === 0) return 0;
+  const ph = ids.map(() => "?").join(",");
+  db.transaction(() => { db.prepare(`DELETE FROM findings WHERE run_id IN (${ph})`).run(...ids); db.prepare(`DELETE FROM audits WHERE run_id IN (${ph})`).run(...ids); })();
+  return ids.length;
+}
+
+// High-level helper used by `kj audit`. Errors returned via `ok` so a broken db never breaks the audit.
+export function persistAuditRun(projectDir, payload) {
+  try {
+    const db = openAuditHistoryDb(projectDir);
+    recordAuditRun(db, payload);
+    const n = countRuns(db);
+    db.close();
+    return { ok: true, total: n, pruneHint: n > 100 };
+  } catch (e) {
+    return { ok: false, error: e?.message || String(e) };
+  }
+}
+

package/src/audit/basal-cost.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { getKarajanHome } from "../utils/paths.js";
+import { sniffManifests, summariseStack } from "../utils/manifest-sniff.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -59,16 +60,16 @@ async function countLines(filePath) {
   }
 }
 
-async function countDependencies(projectDir) {
-  const pkgPath = path.join(projectDir, "package.json");
-  try {
-    const pkg = JSON.parse(await fs.readFile(pkgPath, "utf8"));
-    const deps = Object.keys(pkg.dependencies || {});
-    const devDeps = Object.keys(pkg.devDependencies || {});
-    return { dependencies: deps.length, devDependencies: devDeps.length, total: deps.length + devDeps.length };
-  } catch {
-    return { dependencies: 0, devDependencies: 0, total: 0 };
+function countDependenciesFromStack(stack) {
+  // Suma deps + devDeps de TODOS los manifests detectados (multi-stack).
+  // Si no hay manifests, devuelve ceros — coherente con repos sin paquete.
+  let deps = 0;
+  let devDeps = 0;
+  for (const m of stack.manifests) {
+    deps += m.deps;
+    devDeps += m.devDeps;
   }
+  return { dependencies: deps, devDependencies: devDeps, total: deps + devDeps };
 }
 
 function runDepcheck(projectDir) {
@@ -231,8 +232,11 @@ export async function measureBasalCost(projectDir) {
     totalLines += await countLines(f);
   }
 
-  const depInfo = await countDependencies(projectDir);
-  const depcheck = await runDepcheck(projectDir);
+  const stack = summariseStack(await sniffManifests(projectDir));
+  const depInfo = countDependenciesFromStack(stack);
+  // depcheck solo aplica a Node; en stacks puros no-Node lo saltamos.
+  const hasNode = stack.manifests.some((m) => m.stack === "node");
+  const depcheck = hasNode ? await runDepcheck(projectDir) : { unused: [], note: "depcheck skipped (no package.json)" };
   const deadExports = await findDeadExports(sourceFiles);
 
   return {
@@ -240,7 +244,8 @@ export async function measureBasalCost(projectDir) {
     totalFiles: sourceFiles.length,
     dependencies: depInfo,
     unusedDependencies: depcheck,
-    deadExports
+    deadExports,
+    stack
   };
 }
 

package/src/audit/harness-scorecard.js

@@ -0,0 +1,51 @@
+// KJC-TSK-0470 — Bootstrap Docker de ai-harness-scorecard.
+// One-shot container: detect Docker, auto-pull on first run (cache hit
+// thereafter), execute `assess <repo>` with the project mounted read-only.
+// No compose, no port discovery — assess is a single process that exits.
+import { runCommand } from "../utils/process.js";
+
+const D = { image: "markmishaev76/ai-harness-scorecard:latest", pullTimeoutMs: 300000, assessTimeoutMs: 180000 };
+const pos = (v, d) => (Number(v) > 0 ? Number(v) : d);
+
+export function normalizeHarnessConfig(h = {}) {
+  return {
+    enabled: h.enabled !== false,
+    image: h.image || D.image,
+    pullTimeoutMs: pos(h.pull_timeout_ms, D.pullTimeoutMs),
+    assessTimeoutMs: pos(h.assess_timeout_ms, D.assessTimeoutMs),
+  };
+}
+
+export async function isDockerAvailable() {
+  try {
+    const r = await runCommand("docker", ["version", "--format", "{{.Server.Version}}"], { timeout: 10000 });
+    return r.exitCode === 0;
+  } catch { return false; }
+}
+
+export async function isHarnessImagePresent(image) {
+  const r = await runCommand("docker", ["images", "-q", image], { timeout: 10000 });
+  return r.exitCode === 0 && r.stdout.trim().length > 0;
+}
+
+export async function ensureHarnessImage(harness = null) {
+  const cfg = normalizeHarnessConfig(harness || {});
+  if (await isHarnessImagePresent(cfg.image)) return { pulled: false, reused: true, image: cfg.image };
+  const r = await runCommand("docker", ["pull", cfg.image], { timeout: cfg.pullTimeoutMs });
+  if (r.exitCode !== 0) return { pulled: false, reused: false, image: cfg.image, error: r.stderr?.trim() || `exit ${r.exitCode}` };
+  return { pulled: true, reused: false, image: cfg.image };
+}
+
+export async function runHarnessAssess(repoPath, harness = null) {
+  const cfg = normalizeHarnessConfig(harness || {});
+  const r = await runCommand(
+    "docker",
+    ["run", "--rm", "-v", `${repoPath}:/repo:ro`, cfg.image, "assess", "/repo", "--format", "json"],
+    { timeout: cfg.assessTimeoutMs },
+  );
+  if (r.exitCode !== 0) return { ok: false, error: r.stderr?.trim() || r.stdout?.trim() || `exit ${r.exitCode}` };
+  try {
+    const parsed = JSON.parse(r.stdout);
+    return { ok: true, score: parsed.overall_score, grade: parsed.grade, raw: parsed };
+  } catch (e) { return { ok: false, error: `Invalid JSON from harness: ${e.message}` }; }
+}

package/src/audit/harness-section.js

@@ -0,0 +1,77 @@
+// KJC-TSK-0471 — Harness Scorecard audit stage.
+// Runs the markmishaev76/ai-harness-scorecard container after the deterministic
+// phase, persists scorecard.json + scorecard-report.md under
+// .karajan/audit-runs/<ts>/, and returns a summary the renderer surfaces as a
+// "Harness Health Score" markdown block. KJC-TSK-0472 will consume the
+// persisted artefacts to build audit-history.db.
+import fs from "node:fs/promises";
+import path from "node:path";
+import { normalizeHarnessConfig, runHarnessAssess } from "./harness-scorecard.js";
+
+const CATEGORIES = [
+  ["architectural_docs", "Architectural Docs", 20],
+  ["mechanical_constraints", "Mechanical Constraints", 25],
+  ["testing_stability", "Testing & Stability", 25],
+  ["review_drift_prevention", "Review & Drift Prevention", 15],
+  ["ai_specific_safeguards", "AI-Specific Safeguards", 15],
+];
+const labelFor = (k) => CATEGORIES.find(([key]) => key === k)?.[1] || k;
+const ts = () => new Date().toISOString().replaceAll(/[:.]/g, "-");
+
+export async function runHarnessSection({ projectDir, harnessConfig = null, runAssess = runHarnessAssess } = {}) {
+  const cfg = normalizeHarnessConfig(harnessConfig || {});
+  if (!cfg.enabled) return { ok: true, skipped: true, reason: "disabled" };
+  const res = await runAssess(projectDir, cfg);
+  if (!res.ok) return { ok: false, error: res.error };
+  const outDir = path.join(projectDir, ".karajan", "audit-runs", ts());
+  await fs.mkdir(outDir, { recursive: true });
+  const scorecardPath = path.join(outDir, "scorecard.json");
+  const rawReportPath = path.join(outDir, "scorecard-report.md");
+  await fs.writeFile(scorecardPath, JSON.stringify(res.raw, null, 2), "utf8");
+  await fs.writeFile(rawReportPath, res.raw?.report_markdown || res.raw?.markdown || "", "utf8");
+  return {
+    ok: true, score: res.score, grade: res.grade,
+    categories: res.raw?.categories || {},
+    checks: Array.isArray(res.raw?.checks) ? res.raw.checks : [],
+    scorecardPath, rawReportPath, image: cfg.image,
+  };
+}
+
+export function formatHarnessSection(summary) {
+  if (!summary || summary.skipped) return "";
+  if (!summary.ok) return `## Harness Scorecard\n\n_skipped: ${summary.error}_\n`;
+  const lines = [
+    `## Harness Health Score: ${summary.score}/100 (${summary.grade})`,
+    "",
+    "| Category | Weight | Score |",
+    "| --- | --- | --- |",
+  ];
+  for (const [key, label, weight] of CATEGORIES) {
+    const score = summary.categories?.[key]?.score ?? "—";
+    lines.push(`| ${label} | ${weight}% | ${score} |`);
+  }
+  const checks = Array.isArray(summary.checks) ? summary.checks : [];
+  if (checks.length) {
+    const groups = new Map();
+    for (const c of checks) {
+      const k = c.category || "other";
+      if (!groups.has(k)) groups.set(k, []);
+      groups.get(k).push(c);
+    }
+    lines.push("", "### Checks");
+    for (const [k, list] of groups) {
+      lines.push(`- **${labelFor(k)}**`);
+      for (const c of list) lines.push(`  - ${c.passed ? "✓" : "✗"} ${c.name}${c.detail ? ` — ${c.detail}` : ""}`);
+    }
+  }
+  return lines.join("\n") + "\n";
+}
+
+export function harnessSummaryForJson(summary) {
+  if (!summary?.ok || summary.skipped) return null;
+  return {
+    score: summary.score, grade: summary.grade,
+    categories: summary.categories, checks: summary.checks,
+    rawReportPath: summary.rawReportPath, scorecardPath: summary.scorecardPath,
+  };
+}

package/src/checks/harness-scorecard.js

@@ -0,0 +1,41 @@
+// KJC-TSK-0470 — `kj doctor` check for the AI Harness Scorecard image.
+// Reports Disabled / Docker missing / Image not pulled / OK. The image
+// is pulled lazily by `kj audit` on first use; this check is informational.
+import { isDockerAvailable, isHarnessImagePresent, normalizeHarnessConfig } from "../audit/harness-scorecard.js";
+import { STRATEGY } from "./types.js";
+
+function harnessEnabled(config) { return config?.audit?.harness?.enabled !== false; }
+
+function createHarnessScorecardCheck() {
+  return {
+    name: "harness-scorecard",
+    label: "AI Harness Scorecard (audit)",
+    strategy: STRATEGY.NONE,
+    async detect({ config }) {
+      const cfg = normalizeHarnessConfig(config?.audit?.harness || {});
+      if (!harnessEnabled(config)) {
+        return { ok: true, severity: "info", detail: "Disabled in config (audit.harness.enabled=false)" };
+      }
+      let docker; try { docker = await isDockerAvailable(); } catch { docker = false; }
+      if (!docker) return {
+        ok: false, severity: "warn",
+        detail: "Docker not available — kj audit will skip the harness step.",
+        fix: "Install Docker (or run `kj audit --no-harness` to silence this).",
+        extra: { docker: false, image: cfg.image },
+      };
+      let cached; try { cached = await isHarnessImagePresent(cfg.image); } catch { cached = false; }
+      if (!cached) return {
+        ok: true, severity: "info",
+        detail: `Will be pulled on first \`kj audit\` run (${cfg.image}).`,
+        extra: { docker: true, cached: false, image: cfg.image },
+      };
+      return {
+        ok: true, severity: "info",
+        detail: `Image cached locally (${cfg.image}).`,
+        extra: { docker: true, cached: true, image: cfg.image },
+      };
+    },
+  };
+}
+
+export function getHarnessScorecardChecks() { return [createHarnessScorecardCheck()]; }

package/src/cli/register-meta.js

@@ -3,7 +3,7 @@ import { triageCommand } from "../commands/triage.js";
 import { researcherCommand } from "../commands/researcher.js";
 import { architectCommand } from "../commands/architect.js";
 import { onboardCommand } from "../commands/onboard.js";
-import { ragIndexCommand, ragQueryCommand } from "../commands/rag.js";
+import { ragIndexCommand, ragQueryCommand, ragInstallHooksCommand, ragEvalCommand } from "../commands/rag.js";
 import { watchStartCommand, watchStopCommand, watchStatusCommand } from "../commands/watch.js";
 import { auditCommand } from "../commands/audit.js";
 import { resumeCommand } from "../commands/resume.js";
@@ -104,12 +104,21 @@ export function registerMeta(program, { pkgVersion }) {
   rag.command("index")
     .description("Index plans + onboarding (and optionally project sources) into the local vector store")
     .option("--with-sources", "Also index the projectDir's JS/TS files")
+    .option("--since <ref>", "Only re-index files changed since <ref> ('auto' uses the last indexed commit; falls back to full index if unset). KJC-TSK-0455.")
     .option("--json", "Output the totals as JSON")
     .action(async (flags) => {
       await withConfig(pkgVersion, "rag-index", flags, async ({ config, logger }) => {
         await ragIndexCommand({ config, logger, flags });
       });
     });
+  rag.command("install-hooks")
+    .description("Install the post-merge git hook so the RAG index auto-refreshes after pulls/merges (KJC-TSK-0455)")
+    .option("--json", "Output the result as JSON")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "rag-install-hooks", flags, async ({ config, logger }) => {
+        await ragInstallHooksCommand({ config, logger, flags });
+      });
+    });
   rag.command("query <text>")
     .description("Run a semantic query against the indexed RAG corpus")
     .option("--scope <scope>", "plans | code | onboarding | all (default: all)", "all")
@@ -136,6 +145,20 @@ export function registerMeta(program, { pkgVersion }) {
         await ragQueryCommand({ text, config, logger, flags: { ...flags, mode: ragMode } });
       });
     });
+  // KJC-TSK-0483 — `kj rag eval` runs the golden-query harness and reports
+  // recall@5/recall@10/MRR. `--min-recall` turns it into a CI gate.
+  rag.command("eval")
+    .description("Score the retriever against a golden query set (recall@k + MRR)")
+    .option("--golden <path>", "Path to golden queries JSON (default: tests/rag/golden-queries.json)")
+    .option("--top-k <n>", "Number of hits to retrieve per query (default: 10)", "10")
+    .option("--min-recall <n>", "Fail (exit 1) if aggregated recall@5 falls below this threshold")
+    .option("--project <slug>", "Filter by project slug. Pass 'all' to query across every indexed project.")
+    .option("--json", "Emit the full report as JSON")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "rag-eval", flags, async ({ config, logger }) => {
+        await ragEvalCommand({ config, logger, flags });
+      });
+    });
 
   // KJC-TSK-0441 — `kj watch [start|stop|status]` for live RAG re-index.
   const watch = program.command("watch").description("Live RAG re-index daemon");
@@ -161,6 +184,8 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--no-sonar", "Skip the SonarQube findings collector (faster, less context). Sonar findings are also skipped automatically when SonarQube is unreachable.")
     .option("--no-osv", "Skip the OSV-Scanner vulnerability collector. Findings are also skipped automatically when osv-scanner is not installed.")
     .option("--no-semgrep", "Skip the Semgrep SAST collector. Findings are also skipped automatically when semgrep is not installed (install via 'pipx install semgrep' or 'brew install semgrep').")
+    .option("--no-harness", "Skip the AI Harness Scorecard stage (Docker one-shot). Auto-skipped when Docker is unavailable. Each run is also persisted to .karajan/audit-history.db (KJC-TSK-0472) for diff/trend tracking.")
+    .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("-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.")
@@ -182,9 +207,11 @@ export function registerMeta(program, { pkgVersion }) {
           noSonar: flags.sonar === false,
           noOsv: flags.osv === false,
           noSemgrep: flags.semgrep === false,
+          noHarness: flags.harness === false,
           reportFile: flags.reportFile || null,
           deterministicOnly: Boolean(flags.deterministicOnly),
           yes: Boolean(flags.yes),
+          trend: Boolean(flags.trend),
         });
       });
     });

package/src/cli/register-pipeline.js

@@ -110,6 +110,7 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--skip-role <role...>", "Force one or more roles OFF regardless of triage (e.g. --skip-role tester security)")
     .option("--force-role <role...>", "Force one or more roles ON regardless of triage")
     .option("--skip-spec-review", "Bypass the spec-reviewer pre-pipeline audit")
+    .option("--no-rag-update", "Skip the pre-run RAG drift check (KJC-TSK-0455). Same as config.rag.autoUpdate.onRun=false.")
     .option("--dry-run", "Show what would be executed without running anything")
     .option("--json", "Output JSON only (no styled display)")
     .option("-q, --quiet", "Show only stage status lines, suppress raw agent output (default)")