@karajan-family/code 4.21.0

package/src/audit/agent-readiness.js

@@ -0,0 +1,259 @@
+/**
+ * kj audit --agent-readiness — score a repo for AI-agent readability.
+ *
+ * Static, deterministic, NO LLM call. Inspired by addyosmani/agentic-seo.
+ * Catches the failure modes that make repos invisible to Cursor /
+ * Cline / Aider / Claude Code:
+ *   - no llms.txt → agents have to crawl the README
+ *   - oversized doc pages → agents truncate or drop them
+ *   - JS-only docs → agents can't render
+ *   - broken heading hierarchy → agents misinfer structure
+ *   - no robots allowlist → some agents skip silently
+ *
+ * Returns a 0-100 score + per-check detail + top remediation hints.
+ * Pure data transformation: filesystem reads in, analysis out.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { escapeRegExp } from "../utils/escape-regexp.js";
+
+const PAGE_BYTE_LIMIT = 32 * 1024; // ≈ 8K tokens, the typical agent budget per fetch
+
+/**
+ * Catalogue of checks. Each check has:
+ *   - id          — stable identifier
+ *   - weight      — points contributed when ok
+ *   - run         — (rootDir) => { ok, hint, details }
+ */
+const CHECKS = [
+  {
+    id: "llms-txt-present",
+    weight: 25,
+    description: "llms.txt at repo root",
+    run(rootDir) {
+      const p = path.join(rootDir, "llms.txt");
+      const ok = fs.existsSync(p) && fs.statSync(p).isFile();
+      return ok
+        ? { ok: true, hint: null, details: { path: p } }
+        : { ok: false, hint: "Add llms.txt at repo root with a single-fetch index of docs + commands.", details: {} };
+    },
+  },
+  {
+    id: "llms-txt-valid",
+    weight: 10,
+    description: "llms.txt has at least one section heading and one link",
+    run(rootDir) {
+      const p = path.join(rootDir, "llms.txt");
+      if (!fs.existsSync(p)) return { ok: false, hint: "llms.txt missing — see llms-txt-present.", details: {} };
+      const text = safeRead(p);
+      const hasSection = /^##\s+/m.test(text);
+      const hasLink = /\[[^\]]+\]\([^)]+\)/.test(text);
+      const ok = hasSection && hasLink;
+      return ok
+        ? { ok: true, hint: null, details: { hasSection, hasLink } }
+        : { ok: false, hint: "Add `## Section` headings and `[label](path)` links to llms.txt.", details: { hasSection, hasLink } };
+    },
+  },
+  {
+    id: "robots-allowlist",
+    weight: 10,
+    description: "robots.txt explicitly Allows AI crawlers",
+    run(rootDir) {
+      // Check root or public/.
+      const candidates = ["robots.txt", "public/robots.txt", "static/robots.txt"];
+      const found = candidates.find((c) => fs.existsSync(path.join(rootDir, c)));
+      if (!found) return { ok: false, hint: "Add robots.txt with `User-agent: GPTBot|ClaudeBot|PerplexityBot\\nAllow: /` blocks.", details: {} };
+      const text = safeRead(path.join(rootDir, found));
+      const aiBots = ["GPTBot", "ClaudeBot", "PerplexityBot", "anthropic-ai", "Google-Extended"];
+      const allowed = aiBots.filter((bot) => new RegExp(`User-agent:\\s*${escapeRegExp(bot)}[\\s\\S]*?Allow:\\s*/`, "i").test(text));
+      const ok = allowed.length > 0;
+      return ok
+        ? { ok: true, hint: null, details: { found, allowed } }
+        : { ok: false, hint: `robots.txt found at ${found} but no AI crawler explicitly Allowed. Add explicit User-agent: ClaudeBot blocks.`, details: { found, allowed } };
+    },
+  },
+  {
+    id: "page-token-budget",
+    weight: 15,
+    description: "every .md doc fits within ≈ 8K tokens (32 KB raw)",
+    run(rootDir) {
+      const docsDir = path.join(rootDir, "docs");
+      if (!fs.existsSync(docsDir)) {
+        // No docs/ at all is its own kind of agent-unfriendly, but
+        // not strictly a budget violation. Pass with a hint.
+        return { ok: true, hint: "No docs/ directory found. Consider adding one.", details: { docsDirPresent: false } };
+      }
+      const oversized = listMarkdownFiles(docsDir).filter((f) => fs.statSync(f).size > PAGE_BYTE_LIMIT);
+      if (oversized.length === 0) {
+        return { ok: true, hint: null, details: { oversizedCount: 0 } };
+      }
+      const sample = oversized.slice(0, 3).map((f) => `${path.relative(rootDir, f)} (${(fs.statSync(f).size / 1024).toFixed(1)} KB)`);
+      return {
+        ok: false,
+        hint: `Split or trim ${oversized.length} oversized doc(s): ${sample.join(", ")}.`,
+        details: { oversizedCount: oversized.length, sample },
+      };
+    },
+  },
+  {
+    id: "heading-hierarchy",
+    weight: 10,
+    description: "each .md has exactly one H1 and no skipped levels",
+    run(rootDir) {
+      const docsDir = path.join(rootDir, "docs");
+      if (!fs.existsSync(docsDir)) return { ok: true, hint: null, details: { docsDirPresent: false } };
+      const violations = [];
+      for (const f of listMarkdownFiles(docsDir)) {
+        const text = stripFencedCodeBlocks(safeRead(f));
+        // Count BOTH markdown `# ` and HTML `<h1>` headings — bilingual
+        // README-style files often use a centered `<h1 align="center">`
+        // banner, which is still semantically the document's H1.
+        const mdH1Count = (text.match(/^#\s+/gm) || []).length;
+        const htmlH1Count = (text.match(/<h1[\s>]/gi) || []).length;
+        const h1Count = mdH1Count + htmlH1Count;
+        if (h1Count !== 1) {
+          violations.push({ file: path.relative(rootDir, f), h1Count, mdH1Count, htmlH1Count });
+          continue;
+        }
+        // Check for skipped levels (#### without preceding ###, etc.)
+        const headings = [...text.matchAll(/^(#{1,6})\s/gm)].map((m) => m[1].length);
+        let prev = 0;
+        for (const lvl of headings) {
+          if (prev > 0 && lvl > prev + 1) {
+            violations.push({ file: path.relative(rootDir, f), reason: `H${prev}→H${lvl} skip` });
+            break;
+          }
+          prev = lvl;
+        }
+      }
+      if (violations.length === 0) {
+        return { ok: true, hint: null, details: { violationsCount: 0 } };
+      }
+      const sample = violations.slice(0, 3);
+      return {
+        ok: false,
+        hint: `Fix heading hierarchy in ${violations.length} doc(s): ${sample.map((v) => v.file).join(", ")}.`,
+        details: { violationsCount: violations.length, sample },
+      };
+    },
+  },
+  {
+    id: "agents-readme",
+    weight: 10,
+    description: "docs/agents/README.md as agent entry point",
+    run(rootDir) {
+      const p = path.join(rootDir, "docs/agents/README.md");
+      const ok = fs.existsSync(p);
+      return ok
+        ? { ok: true, hint: null, details: { path: p } }
+        : { ok: false, hint: "Create docs/agents/README.md as the agent-facing index (links from llms.txt).", details: {} };
+    },
+  },
+  {
+    id: "skill-md-coverage",
+    weight: 20,
+    description: "at least one SKILL.md per declared CLI capability",
+    run(rootDir) {
+      const skillDir = path.join(rootDir, "docs/agents");
+      if (!fs.existsSync(skillDir)) return { ok: false, hint: "Create docs/agents/ with one SKILL.<command>.md per CLI capability.", details: {} };
+      const skillFiles = fs.readdirSync(skillDir).filter((f) => /^SKILL\..+\.md$/.test(f));
+      if (skillFiles.length === 0) {
+        return { ok: false, hint: "Add SKILL.<command>.md files documenting each CLI capability.", details: { skillFilesCount: 0 } };
+      }
+      // We don't enumerate the user's own CLI here (out of scope for a
+      // generic auditor). At least 1 SKILL.md is the minimum signal.
+      return { ok: true, hint: null, details: { skillFilesCount: skillFiles.length } };
+    },
+  },
+];
+
+function safeRead(p) {
+  try { return fs.readFileSync(p, "utf8"); } catch { return ""; }
+}
+
+/**
+ * Replace every fenced code block (```…``` or ~~~…~~~) with blank lines
+ * of the same line count so heading regexes don't accidentally match
+ * shell comments inside bash code blocks (`# install foo`). Preserving
+ * line counts keeps later byte-offset checks stable.
+ */
+function stripFencedCodeBlocks(text) {
+  return text.replaceAll(/^([ \t]*)(```|~~~)[^\n]*\n([\s\S]*?)\n\1\2[^\n]*$/gm, (match) => {
+    const lineCount = match.split("\n").length;
+    return "\n".repeat(lineCount - 1);
+  });
+}
+
+function listMarkdownFiles(dir, out = []) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.name.startsWith(".") || e.name === "node_modules") continue;
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) listMarkdownFiles(p, out);
+    else if (e.isFile() && e.name.endsWith(".md")) out.push(p);
+  }
+  return out;
+}
+
+/**
+ * Run every agent-readiness check against `rootDir`. Returns a
+ * report with score, per-check results, and ranked remediation hints.
+ *
+ * @param {string} rootDir — absolute path to the repo root to audit
+ * @returns {{ score: number, checks: object[], topFixes: object[] }}
+ */
+export function runAgentReadiness(rootDir) {
+  const checks = [];
+  let earned = 0;
+  let possible = 0;
+  for (const c of CHECKS) {
+    possible += c.weight;
+    let result;
+    try {
+      result = c.run(rootDir);
+    } catch (err) {
+      result = { ok: false, hint: `Check threw: ${err.message}`, details: { error: err.message } };
+    }
+    if (result.ok) earned += c.weight;
+    checks.push({
+      id: c.id,
+      description: c.description,
+      weight: c.weight,
+      score: result.ok ? c.weight : 0,
+      ok: result.ok,
+      hint: result.hint,
+      details: result.details || {},
+    });
+  }
+  const score = possible === 0 ? 0 : Math.round((earned / possible) * 100);
+  const topFixes = checks
+    .filter((c) => !c.ok && c.hint)
+    .sort((a, b) => b.weight - a.weight)
+    .slice(0, 5)
+    .map((c, i) => ({
+      priority: i + 1,
+      checkId: c.id,
+      weightLost: c.weight,
+      action: c.hint,
+    }));
+  return { score, possible, earned, checks, topFixes };
+}
+
+/**
+ * Render the report in plain text for the human terminal.
+ */
+export function formatAgentReadinessReport({ score, checks, topFixes }, rootDir) {
+  const lines = [`Agent Readiness — ${rootDir}: ${score}/100`, ""];
+  for (const c of checks) {
+    const tick = c.ok ? "✓" : "✗";
+    const pts = `(+${c.score})`.padStart(6);
+    lines.push(`  ${tick} ${c.description.padEnd(50)} ${pts}${c.hint ? "  " + c.hint : ""}`);
+  }
+  if (topFixes.length > 0) {
+    lines.push("", "Top fixes:");
+    for (const f of topFixes) {
+      lines.push(`  ${f.priority}. [${f.checkId}] ${f.action}`);
+    }
+  }
+  return lines.join("\n");
+}

package/src/audit/ai-slop-findings.js

@@ -0,0 +1,102 @@
+// AI-slop tells detector — KJC-TSK-0503. Deterministic, offline,
+// regex-based scanner over JS/TS source. Five categories:
+// tautologic-comments, banner-separators, boilerplate-docstrings,
+// magic-fallbacks, redundant-jsdoc. Score 100 = clean.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const FILE_EXTS = new Set([".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx"]);
+const IGNORE_DIRS = new Set([
+  "node_modules", "dist", "build", "coverage",
+  ".git", ".karajan", "public", ".next", ".nuxt", ".vercel", ".cache",
+]);
+const VERB = "(?:returns?|gets?|sets?|fetches?|loads?|saves?|creates?|builds?|makes?|computes?|handles?|checks?|validates?)";
+const LINE_PATTERNS = {
+  "banner-separators": /\/[/*]\s*[=*\-_#~]{5,}/,
+  "magic-fallbacks": /(\?\?|\|\|)\s*(?:""|''|null|undefined)\s*(?:\)|;|,|$)/,
+  "redundant-jsdoc": new RegExp(`@param\\s+\\{[^}]+\\}\\s+(\\w+)\\s+(?:-\\s*)?(?:the\\s+)?\\1\\s+(?:parameter|argument|value)`, "i"),
+};
+const TAUT_RE = new RegExp(`^\\s*//\\s*${VERB}\\s+(?:the\\s+|a\\s+|an\\s+)?(\\w+)\\s*\\.?\\s*$`, "i");
+const DOC_RE = new RegExp(`^\\s*/\\*\\*\\s*${VERB}\\s+(?:the\\s+|a\\s+|an\\s+)?(\\w+)\\s*\\.?\\s*\\*/\\s*$`, "i");
+const DECL_RE = /^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function|const|let|var|class)\s+(\w+)/;
+
+export const CATEGORIES = Object.freeze([
+  "tautologic-comments", "banner-separators", "boilerplate-docstrings",
+  "magic-fallbacks", "redundant-jsdoc",
+]);
+
+function nextDecl(lines, from) {
+  for (let j = from; j < Math.min(from + 3, lines.length); j++) {
+    const m = lines[j]?.match(DECL_RE);
+    if (m) return m[1];
+  }
+  return null;
+}
+const stem = (a, b) => { const al = a.toLowerCase(), bl = b.toLowerCase(); return al === bl || al.includes(bl) || bl.includes(al); };
+
+export function scanText(relPath, text) {
+  const out = [];
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNo = i + 1;
+    for (const [category, re] of Object.entries(LINE_PATTERNS)) {
+      if (re.test(line)) out.push({ path: relPath, line: lineNo, category, snippet: line.trim().slice(0, 100) });
+    }
+    const t = line.match(TAUT_RE);
+    if (t) {
+      const decl = nextDecl(lines, i + 1);
+      if (decl && stem(decl, t[1])) out.push({ path: relPath, line: lineNo, category: "tautologic-comments", snippet: line.trim().slice(0, 100) });
+    }
+    const d = line.match(DOC_RE);
+    if (d) {
+      const decl = nextDecl(lines, i + 1);
+      if (decl && stem(decl, d[1])) out.push({ path: relPath, line: lineNo, category: "boilerplate-docstrings", snippet: line.trim().slice(0, 100) });
+    }
+  }
+  return out;
+}
+
+function listSourceFiles(root) {
+  const out = [];
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (IGNORE_DIRS.has(e.name) || e.name.startsWith(".")) continue;
+        stack.push(full);
+      } else if (FILE_EXTS.has(path.extname(e.name))) out.push(full);
+    }
+  }
+  return out;
+}
+
+export async function collectAiSlop(rootDir, opts = {}) {
+  const maxLOC = Number.isFinite(opts.maxLOC) ? opts.maxLOC : 200_000;
+  const maxWorst = Number.isFinite(opts.maxWorst) ? opts.maxWorst : 10;
+  try {
+    const findings = [];
+    let totalLOC = 0, filesScanned = 0;
+    for (const file of listSourceFiles(rootDir)) {
+      if (totalLOC >= maxLOC) break;
+      let content;
+      try { content = fs.readFileSync(file, "utf-8"); } catch { continue; }
+      findings.push(...scanText(path.relative(rootDir, file) || file, content));
+      totalLOC += content.split(/\r?\n/).length;
+      filesScanned++;
+    }
+    const byCategory = Object.fromEntries(CATEGORIES.map((c) => [c, 0]));
+    for (const f of findings) byCategory[f.category]++;
+    const density = totalLOC > 0 ? (findings.length / totalLOC) * 100 : 0;
+    const score = Math.max(0, Math.min(100, Math.round(100 - density * 100)));
+    const worst = findings.slice().sort((a, b) => (a.path === b.path ? a.line - b.line : a.path.localeCompare(b.path))).slice(0, maxWorst);
+    return { available: true, filesScanned, totalLOC, total: findings.length, score, byCategory, worst };
+  } catch (err) {
+    return { available: false, reason: err?.message || String(err) };
+  }
+}

package/src/audit/audit-fallback.js

@@ -0,0 +1,66 @@
+// Resilient provider/model fallback for the `kj audit` CLI (KJC-BUG-0094).
+// The CLI audit calls AuditRole.executeWithDeterministic directly, bypassing
+// the orchestrator's recovery paths, so a dead configured model (e.g. an
+// inherited "claude-fable-5") killed the command. The LLM phase now tries:
+// configured provider+model → same provider default model → remaining known
+// providers. First success wins; the deterministic context is reused.
+import { resolveRole } from "../config.js";
+import { AuditRole } from "../roles/audit-role.js";
+
+const KNOWN_PROVIDERS = ["claude", "codex", "gemini"];
+
+/** Ordered, de-duplicated fallback candidates for the audit role. */
+export function buildAuditFallbackCandidates(config) {
+  const effective = resolveRole(config, "audit");
+  const primary = effective.provider || "claude";
+  const candidates = [{ provider: primary, model: effective.model ?? null }];
+  if (effective.model) candidates.push({ provider: primary, model: null });
+  for (const p of KNOWN_PROVIDERS) {
+    if (p !== primary) candidates.push({ provider: p, model: null });
+  }
+  const seen = new Set();
+  return candidates.filter((c) => {
+    const key = `${c.provider}::${c.model ?? ""}`;
+    return seen.has(key) ? false : (seen.add(key), true);
+  });
+}
+
+// Pin the audit role to a provider/model. Sets BOTH the per-role override and
+// `coder_options.model` (the audit role inherits its model from the coder
+// bucket); a null model neutralizes both so the provider default is used.
+export function withAuditProvider(config, provider, model) {
+  return {
+    ...config,
+    roles: { ...(config?.roles || {}), audit: { ...(config?.roles?.audit || {}), provider, model: model ?? undefined } },
+    coder_options: { ...(config?.coder_options || {}), model: model ?? undefined },
+  };
+}
+
+/** Run the audit LLM phase with automatic provider/model fallback. */
+export async function runAuditWithFallback({
+  config, logger, roleInput, deterministicCtx, available, candidates, onFallback, createRole,
+}) {
+  const makeRole = createRole || ((cfg) => new AuditRole({ config: cfg, logger }));
+  const all = candidates || buildAuditFallbackCandidates(config);
+  const usable = available ? all.filter((c) => available.includes(c.provider)) : all;
+  if (usable.length === 0) {
+    throw new Error("No available audit provider — install claude, codex, or gemini, or set roles.audit.provider");
+  }
+
+  let last = null;
+  let attempts = 0;
+  for (const cand of usable) {
+    attempts += 1;
+    if (attempts > 1) onFallback?.(cand, attempts);
+    const role = makeRole(withAuditProvider(config, cand.provider, cand.model));
+    const meta = { provider: cand.provider, model: cand.model ?? null };
+    try {
+      const result = await role.executeWithDeterministic(roleInput, deterministicCtx);
+      if (result?.ok) return { ...result, ...meta, attempts };
+      last = { ...result, ...meta };
+    } catch (err) {
+      last = { ok: false, result: { error: err.message, provider: cand.provider }, summary: `Audit failed: ${err.message}`, ...meta };
+    }
+  }
+  return { ...last, attempts, exhausted: 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) };
+  }
+}
+