karajan-code 2.32.0 → 2.33.0

package/README.md

@@ -345,6 +345,13 @@ Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 
 ## Recent releases
 
+> **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.33.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

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/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/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

@@ -161,6 +161,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 +184,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/commands/audit.js

@@ -11,6 +11,9 @@ import { withCliRunLog } from "../utils/cli-run-log.js";
 import { createCliProgressReporter } from "../utils/cli-progress.js";
 import { runAgentReadiness, formatAgentReadinessReport } from "../audit/agent-readiness.js";
 import { formatDeterministicSummary } from "../audit/deterministic-summary.js";
+import { runHarnessSection, formatHarnessSection, harnessSummaryForJson } from "../audit/harness-section.js";
+import { persistAuditRun, openAuditHistoryDb, getLatestPreviousRun, getRecentScores } from "../audit/audit-history.js";
+import { computeHistoryDiff, formatHistoryDiff, formatTrendSparkline } from "../audit/audit-history-display.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -191,20 +194,43 @@ async function buildReportHeader(projectDir, invocation) {
   return lines.join("\n");
 }
 
-function describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, json, deterministicOnly, yes }) {
+function composeHistoryBlock({ diffMd, trendMd }) {
+  const parts = [];
+  if (diffMd) parts.push(diffMd);
+  if (trendMd) parts.push(trendMd);
+  return parts.length ? `\n\n## Harness Score History\n${parts.join("\n\n")}` : "";
+}
+
+// KJC-TSK-0473 — Resolve diff vs previous run + optional trend sparkline.
+// Errors silenced: history is a nice-to-have; a broken db must not break audit.
+function loadAuditHistoryContext(projectDir, currentHarness, { showTrend = false } = {}) {
+  let db;
+  try {
+    db = openAuditHistoryDb(projectDir);
+    if (!db) return { diff: null, diffMd: "", trendMd: "" };
+    const previous = currentHarness?.score != null ? getLatestPreviousRun(db, new Date().toISOString()) : null;
+    const diff = currentHarness?.score != null ? computeHistoryDiff(currentHarness, previous) : null;
+    const trendMd = showTrend ? formatTrendSparkline(getRecentScores(db, 10)) : "";
+    return { diff, diffMd: formatHistoryDiff(diff), trendMd };
+  } catch { return { diff: null, diffMd: "", trendMd: "" }; }
+  finally { try { db?.close(); } catch { /* noop */ } }
+}
+
+function describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHarness, json, deterministicOnly, yes }) {
   const parts = ["kj audit"];
   if (task && task !== "Analyze the full codebase") parts.push(JSON.stringify(task));
   if (dimensions && dimensions !== "all") parts.push(`--dimensions=${dimensions}`);
   if (noSonar) parts.push("--no-sonar");
   if (noOsv) parts.push("--no-osv");
   if (noSemgrep) parts.push("--no-semgrep");
+  if (noHarness) parts.push("--no-harness");
   if (deterministicOnly) parts.push("--deterministic-only");
   if (yes) parts.push("--yes");
   if (json) parts.push("--json");
   return parts.join(" ");
 }
 
-export async function auditCommand({ task, config, logger, dimensions, json, agentReadiness, path: pathArg, noSonar = false, noOsv = false, noSemgrep = false, reportFile = null, deterministicOnly = false, yes = false, promptFn = null }) {
+export async function auditCommand({ task, config, logger, dimensions, json, agentReadiness, path: pathArg, noSonar = false, noOsv = false, noSemgrep = false, noHarness = false, reportFile = null, deterministicOnly = false, yes = false, trend = false, promptFn = null }) {
   // --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.).
@@ -247,6 +273,27 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
     const deterministicCtx = await role.collectDeterministic(roleInput);
     const deterministicMd = formatDeterministicSummary(deterministicCtx);
 
+    // KJC-TSK-0471 — Harness Scorecard (Docker one-shot, golden metric).
+    // Runs after the deterministic phase, before the LLM. Auto-skipped on
+    // --no-harness or if `runHarnessSection` surfaces an error (graceful
+    // degradation: a missing Docker daemon must not break `kj audit`).
+    let harnessSummary = null;
+    if (!noHarness) {
+      try {
+        harnessSummary = await runHarnessSection({
+          projectDir: config?.projectDir || process.cwd(),
+          harnessConfig: config?.audit?.harness || null,
+        });
+        if (harnessSummary?.ok && !harnessSummary.skipped) {
+          runLog.logText(`[audit] harness score=${harnessSummary.score}/100 grade=${harnessSummary.grade}`);
+        }
+      } catch (e) {
+        harnessSummary = { ok: false, error: e?.message || String(e) };
+        runLog.logText(`[audit] harness skipped: ${harnessSummary.error}`);
+      }
+    }
+    const harnessMd = formatHarnessSection(harnessSummary);
+
     // --json suppresses the interactive flow regardless: it would mangle
     // a script's stdout. JSON consumers always get the full audit unless
     // they explicitly pass deterministicOnly.
@@ -263,23 +310,28 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
     if (!runLlm) {
       // Deterministic-only path. Produce the report from what we already
       // have, persist it (md or json), and exit. Zero tokens spent.
+      const harnessJson = harnessSummaryForJson(harnessSummary);
+      const currentHarness = harnessSummary?.ok && !harnessSummary.skipped ? harnessSummary : null;
+      const history = loadAuditHistoryContext(config?.projectDir || process.cwd(), currentHarness, { showTrend: trend });
+      const historyMd = composeHistoryBlock(history);
       const stdoutContent = json
-        ? JSON.stringify({ deterministic: deterministicCtx, mode: "deterministic-only" }, null, 2)
-        : (deterministicOnly ? deterministicMd : ""); // already printed above when interactive
-      if (json || deterministicOnly) console.log(stdoutContent);
+        ? JSON.stringify({ deterministic: deterministicCtx, harnessScore: harnessJson, harnessScoreDiff: history.diff, mode: "deterministic-only" }, null, 2)
+        : (deterministicOnly ? `${deterministicMd}\n${harnessMd}${historyMd}` : `${harnessMd}${historyMd}`);
+      if (json || deterministicOnly || harnessMd) console.log(stdoutContent);
 
       if (reportPath) {
         let payload;
         if (reportPath.endsWith(".json")) {
-          payload = JSON.stringify({ deterministic: deterministicCtx, mode: "deterministic-only" }, null, 2);
+          payload = JSON.stringify({ deterministic: deterministicCtx, harnessScore: harnessJson, harnessScoreDiff: history.diff, mode: "deterministic-only" }, null, 2);
         } else {
-          const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, json, deterministicOnly, yes }));
-          payload = header + deterministicMd + "\n";
+          const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHarness, json, deterministicOnly, yes }));
+          payload = `${header}${deterministicMd}\n${harnessMd}${historyMd}`;
         }
         await fs.writeFile(reportPath, payload, "utf8");
         runLog.logText(`[audit] report written (deterministic-only) → ${reportPath}`);
         logger.info(`Audit report written: ${reportPath}`);
       }
+      persistAuditRun(config?.projectDir || process.cwd(), { runId: new Date().toISOString(), timestamp: new Date().toISOString(), gitSha: null, harness: harnessSummary?.ok && !harnessSummary.skipped ? harnessSummary : null, rawReportPath: reportPath });
       logger.info("Audit completed (deterministic-only).");
       return { ok: true, mode: "deterministic-only", reportPath: reportPath || undefined };
     }
@@ -306,18 +358,22 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
       runLog.logText(`[audit] usage tokens=${usage.total_tokens} cost=$${(usage.cost_usd ?? 0).toFixed(4)} duration=${(usage.durationMs / 1000).toFixed(1)}s`);
     }
 
+    const harnessJson = harnessSummaryForJson(harnessSummary);
+    const currentHarness = harnessSummary?.ok && !harnessSummary.skipped ? harnessSummary : null;
+    const history = loadAuditHistoryContext(config?.projectDir || process.cwd(), currentHarness, { showTrend: trend });
+    const historyMd = composeHistoryBlock(history);
     let stdoutContent;
     if (json) {
       const jsonPayload = parsed
-        ? { ...parsed, usage: usage || undefined }
-        : { ...roleResult, usage: usage || undefined };
+        ? { ...parsed, harnessScore: harnessJson, harnessScoreDiff: history.diff, usage: usage || undefined }
+        : { ...roleResult, harnessScore: harnessJson, harnessScoreDiff: history.diff, usage: usage || undefined };
       stdoutContent = JSON.stringify(jsonPayload, null, 2);
     } else if (parsed?.summary?.overallHealth) {
-      stdoutContent = formatAudit(parsed, usage);
+      stdoutContent = `${formatAudit(parsed, usage)}\n${harnessMd}${historyMd}`;
     } else if (parsed?.raw) {
-      stdoutContent = parsed.raw + (usage ? `\n\n${formatUsageSummary(usage) || ""}` : "");
+      stdoutContent = parsed.raw + (usage ? `\n\n${formatUsageSummary(usage) || ""}` : "") + `\n${harnessMd}${historyMd}`;
     } else {
-      stdoutContent = roleResult.summary || "Audit complete.";
+      stdoutContent = `${roleResult.summary || "Audit complete."}\n${harnessMd}${historyMd}`;
     }
     console.log(stdoutContent);
 
@@ -325,11 +381,11 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
       let payload;
       if (reportPath.endsWith(".json")) {
         const jsonPayload = parsed
-          ? { ...parsed, usage: usage || undefined }
-          : { ...roleResult, usage: usage || undefined };
+          ? { ...parsed, harnessScore: harnessJson, harnessScoreDiff: history.diff, usage: usage || undefined }
+          : { ...roleResult, harnessScore: harnessJson, harnessScoreDiff: history.diff, usage: usage || undefined };
         payload = JSON.stringify(jsonPayload, null, 2);
       } else {
-        const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, json, deterministicOnly, yes }));
+        const header = await buildReportHeader(config?.projectDir, describeInvocation({ task, dimensions, noSonar, noOsv, noSemgrep, noHarness, json, deterministicOnly, yes }));
         payload = header + stdoutContent + "\n";
       }
       await fs.writeFile(reportPath, payload, "utf8");
@@ -337,6 +393,7 @@ export async function auditCommand({ task, config, logger, dimensions, json, age
       logger.info(`Audit report written: ${reportPath}`);
     }
 
+    persistAuditRun(config?.projectDir || process.cwd(), { runId: new Date().toISOString(), timestamp: new Date().toISOString(), gitSha: null, harness: harnessSummary?.ok && !harnessSummary.skipped ? harnessSummary : null, rawReportPath: reportPath });
     logger.info("Audit completed.");
     return { ok: true, reportPath: reportPath || undefined };
   });

package/src/commands/doctor.js

@@ -19,6 +19,7 @@ import { getConfigFileChecks } from "../checks/config-files.js";
 import { getBinaryChecks } from "../checks/binaries.js";
 import { getSonarChecks } from "../checks/sonar.js";
 import { getOllamaChecks } from "../checks/ollama.js";
+import { getHarnessScorecardChecks } from "../checks/harness-scorecard.js";
 import { getCiChecks } from "../checks/ci.js";
 import { getRtkChecks } from "../checks/rtk.js";
 import { getNodeChecks } from "../checks/node.js";
@@ -54,6 +55,7 @@ function buildChecks(config, { projectOnly = false } = {}) {
     ...getBinaryChecks(),
     ...getSonarChecks(),
     ...getOllamaChecks(),
+    ...getHarnessScorecardChecks(),
     ...getPortChecks(),
     ...getTokenChecks(config),
     ...getMcpHealthChecks(),