@karajan-family/code 4.21.0

package/src/audit/deterministic-summary.js

@@ -0,0 +1,327 @@
+/**
+ * Deterministic-only summary formatter for `kj audit` two-phase mode
+ * (KJC-TSK-0364). Renders the data AuditRole.collectDeterministic()
+ * gathers — basalCost, growth delta, stack, Sonar findings, WebPerf —
+ * as a self-contained markdown block the user can read BEFORE deciding
+ * whether to spend tokens on the LLM analysis.
+ *
+ * Kept in src/audit/ (not src/commands/) so the same formatter can be
+ * reused by future MCP tools and other entrypoints.
+ */
+
+import { groupIssuesBySeverity } from "./sonar-findings.js";
+import { groupVulnerabilitiesBySeverity } from "./osv-findings.js";
+import { groupFindingsBySeverity as groupSemgrepBySeverity } from "./semgrep-findings.js";
+import { groupCyclesBySeverity } from "./circular-deps.js";
+import { groupDeadExportsBySeverity } from "./dead-exports.js";
+import { groupInjectionBySeverity } from "./injection-findings.js";
+
+const MAX_SAMPLE_DEAD_EXPORTS = 10;
+const MAX_SAMPLE_SONAR_PER_SEVERITY = 5;
+const MAX_SAMPLE_OSV_PER_SEVERITY = 5;
+const MAX_SAMPLE_SEMGREP_PER_SEVERITY = 5;
+const MAX_SAMPLE_CYCLES_PER_SEVERITY = 5;
+const MAX_SAMPLE_KNIP_PER_SEVERITY = 5;
+const MAX_SAMPLE_INJECTION_PER_SEVERITY = 5;
+
+/**
+ * @param {{basalCost?: object, growthDelta?: object, stack?: object, sonarFindings?: object, webperf?: object, osvFindings?: object}} ctx
+ * @returns {string} markdown block
+ */
+export function formatDeterministicSummary(ctx) {
+  const lines = ["## Deterministic Findings", ""];
+  lines.push("These are the rule-based findings (no LLM). They cost zero tokens and are always factually accurate. The interactive prompt below asks if you want to extend this with an LLM analysis (which will cost tokens).");
+  lines.push("");
+
+  if (ctx.stack) lines.push(...formatStackBlock(ctx.stack));
+  if (ctx.basalCost) lines.push(...formatBasalCostBlock(ctx.basalCost, ctx.growthDelta));
+  if (ctx.sonarFindings) lines.push(...formatSonarBlock(ctx.sonarFindings));
+  if (ctx.osvFindings) lines.push(...formatOsvBlock(ctx.osvFindings));
+  if (ctx.semgrepFindings) lines.push(...formatSemgrepBlock(ctx.semgrepFindings));
+  if (ctx.infraFindings) lines.push(...formatInfraBlock(ctx.infraFindings));
+  if (ctx.circularDeps) lines.push(...formatCircularDepsBlock(ctx.circularDeps));
+  if (ctx.deadExports) lines.push(...formatDeadExportsBlock(ctx.deadExports));
+  if (ctx.injectionFindings) lines.push(...formatInjectionBlock(ctx.injectionFindings));
+  if (ctx.aiSlop) lines.push(...formatAiSlopBlock(ctx.aiSlop));
+  if (ctx.webperf) lines.push(...formatWebperfBlock(ctx.webperf));
+
+  return lines.join("\n");
+}
+
+function formatAiSlopBlock(slop) {
+  if (!slop.available) return ["### AI-slop tells (deterministic)", `- Status: not available — ${slop.reason || "scan failed"}`, ""];
+  const lines = ["### AI-slop tells (deterministic)", `- Files scanned: ${slop.filesScanned ?? 0}`, `- Score: ${slop.score}/100 (100 = clean)`, `- Findings: ${slop.total ?? 0}`];
+  if ((slop.total ?? 0) > 0) {
+    for (const [cat, n] of Object.entries(slop.byCategory || {})) {
+      if (n > 0) lines.push(`  - ${cat}: ${n}`);
+    }
+    if (Array.isArray(slop.worst) && slop.worst.length > 0) {
+      lines.push("  - Worst offenders:");
+      for (const f of slop.worst) lines.push(`    - ${f.path}:${f.line} [${f.category}] ${f.snippet}`);
+    }
+  }
+  lines.push("");
+  return lines;
+}
+
+function formatInjectionBlock(inj) {
+  if (!inj.available) return ["### Prompt-injection scan", `- Status: not available — ${inj.reason || "scan failed"}`, ""];
+  const lines = ["### Prompt-injection scan (agent-context surface: CLAUDE/AGENTS/GEMINI.md, templates, .rulesync, .karajan)", `- Files scanned: ${inj.scanned ?? 0}`, `- Findings: ${inj.total ?? 0}`];
+  if ((inj.total ?? 0) > 0) {
+    for (const [severity, items] of Object.entries(groupInjectionBySeverity(inj.findings || []))) {
+      if (items.length === 0) continue;
+      lines.push(`  - ${severity} (${items.length}):`);
+      for (const f of items.slice(0, MAX_SAMPLE_INJECTION_PER_SEVERITY)) {
+        const lineSuffix = f.line ? `:${f.line}` : "";
+        lines.push(`    - ${f.file || "(unknown)"}${lineSuffix} [${f.type}] ${f.pattern}`);
+      }
+      if (items.length > MAX_SAMPLE_INJECTION_PER_SEVERITY) lines.push(`    - ... and ${items.length - MAX_SAMPLE_INJECTION_PER_SEVERITY} more in ${severity}`);
+    }
+  }
+  lines.push("");
+  return lines;
+}
+
+function formatCircularDepsBlock(circularDeps) {
+  if (!circularDeps.available) {
+    return ["### Circular Dependencies (architecture)", `- Status: not available — ${circularDeps.reason || "madge not available"}`, ""];
+  }
+  const lines = ["### Circular Dependencies (architecture)"];
+  const suppressedSuffix = circularDeps.suppressedCount ? ` (+${circularDeps.suppressedCount} suppressed)` : "";
+  lines.push(`- Total cycles: ${circularDeps.total ?? 0}${suppressedSuffix}`);
+  if ((circularDeps.total ?? 0) > 0) {
+    const groups = groupCyclesBySeverity(circularDeps.cycles || []);
+    for (const [severity, cycles] of Object.entries(groups)) {
+      if (cycles.length === 0) continue;
+      lines.push(`  - ${severity} (${cycles.length}):`);
+      for (const c of cycles.slice(0, MAX_SAMPLE_CYCLES_PER_SEVERITY)) {
+        const head = (c.cycle || [c.path]).slice(0, 3).join(" → ");
+        const more = (c.cycle?.length || 0) > 3 ? ` → … (${c.cycle.length} files)` : "";
+        lines.push(`    - ${head}${more}`);
+      }
+      if (cycles.length > MAX_SAMPLE_CYCLES_PER_SEVERITY) {
+        lines.push(`    - ... and ${cycles.length - MAX_SAMPLE_CYCLES_PER_SEVERITY} more in ${severity}`);
+      }
+    }
+    if (circularDeps.truncated > 0) lines.push(`  - ... ${circularDeps.truncated} more cycles not shown`);
+  }
+  lines.push("");
+  return lines;
+}
+
+function formatSemgrepBlock(semgrepFindings) {
+  if (!semgrepFindings.available) {
+    return ["### Semgrep SAST", `- Status: not available — ${semgrepFindings.reason || "semgrep not installed"}`, ""];
+  }
+  const lines = ["### Semgrep SAST"];
+  lines.push(`- Total findings: ${semgrepFindings.total ?? 0}`);
+  if ((semgrepFindings.total ?? 0) > 0) {
+    const groups = groupSemgrepBySeverity(semgrepFindings.findings || []);
+    for (const [severity, findings] of Object.entries(groups)) {
+      if (findings.length === 0) continue;
+      lines.push(`  - ${severity} (${findings.length}):`);
+      for (const f of findings.slice(0, MAX_SAMPLE_SEMGREP_PER_SEVERITY)) {
+        const lineSuffix = f.line ? `:${f.line}` : "";
+        const loc = f.file ? `${f.file}${lineSuffix}` : "";
+        lines.push(`    - ${loc} [${f.rule}]`);
+      }
+      if (findings.length > MAX_SAMPLE_SEMGREP_PER_SEVERITY) {
+        lines.push(`    - ... and ${findings.length - MAX_SAMPLE_SEMGREP_PER_SEVERITY} more in ${severity}`);
+      }
+    }
+  }
+  lines.push("");
+  return lines;
+}
+
+// INF-C (KJC-TSK-0760): checkov misconfigs — same shape as the semgrep
+// block; a not-applicable repo (no infra markers) declares it in one line.
+function formatInfraBlock(infraFindings) {
+  if (!infraFindings.available) {
+    return ["### Infra misconfigurations (checkov)", `- Status: not available — ${infraFindings.reason || "checkov not installed"}`, ""];
+  }
+  const lines = ["### Infra misconfigurations (checkov)"];
+  lines.push(`- Total findings: ${infraFindings.total ?? 0}`);
+  const cap = MAX_SAMPLE_SEMGREP_PER_SEVERITY * 3;
+  for (const f of (infraFindings.findings || []).slice(0, cap)) {
+    const lineSuffix = f.line ? `:${f.line}` : "";
+    lines.push(`  - [${f.severity}] ${f.file}${lineSuffix} [${f.rule}] ${f.message}${f.guideline ? ` (${f.guideline})` : ""}`);
+  }
+  const overflow = (infraFindings.total ?? 0) - cap;
+  if (overflow > 0) lines.push(`  - ... and ${overflow} more`);
+  lines.push("");
+  return lines;
+}
+
+function formatOsvBlock(osvFindings) {
+  if (!osvFindings.available) {
+    return ["### OSV Vulnerabilities", `- Status: not available — ${osvFindings.reason || "osv-scanner not installed"}`, ""];
+  }
+  const lines = ["### OSV Vulnerabilities (Dependencies)"];
+  lines.push(`- Total open: ${osvFindings.total ?? 0}`);
+  if ((osvFindings.total ?? 0) > 0) {
+    const groups = groupVulnerabilitiesBySeverity(osvFindings.vulnerabilities || []);
+    for (const [severity, vulns] of Object.entries(groups)) {
+      if (vulns.length === 0) continue;
+      lines.push(`  - ${severity} (${vulns.length}):`);
+      for (const v of vulns.slice(0, MAX_SAMPLE_OSV_PER_SEVERITY)) {
+        const where = v.package ? `${v.package}@${v.version || "?"}` : "(unknown)";
+        const fixed = v.fixed ? ` → fixed in ${v.fixed}` : "";
+        lines.push(`    - ${v.id} ${where}${fixed}`);
+      }
+      if (vulns.length > MAX_SAMPLE_OSV_PER_SEVERITY) {
+        lines.push(`    - ... and ${vulns.length - MAX_SAMPLE_OSV_PER_SEVERITY} more in ${severity}`);
+      }
+    }
+  }
+  lines.push("");
+  return lines;
+}
+
+function formatDeadExportsBlock(deadExports) {
+  if (!deadExports.available) {
+    return ["### Dead Code (knip)", `- Status: not available — ${deadExports.reason || "knip not available"}`, ""];
+  }
+  const lines = ["### Dead Code (knip)"];
+  const exportsTotal = (deadExports.exports || []).length;
+  const filesTotal = (deadExports.files || []).length;
+  lines.push(`- Unused exports/types: ${exportsTotal}`);
+  lines.push(`- Unused files: ${filesTotal}`);
+  if (deadExports.suppressedCount) lines.push(`- Suppressed (FP filter): ${deadExports.suppressedCount}`);
+  const allItems = [...(deadExports.exports || []), ...(deadExports.files || [])];
+  if (allItems.length > 0) {
+    const groups = groupDeadExportsBySeverity(allItems);
+    for (const [severity, items] of Object.entries(groups)) {
+      if (items.length === 0) continue;
+      lines.push(`  - ${severity} (${items.length}):`);
+      for (const item of items.slice(0, MAX_SAMPLE_KNIP_PER_SEVERITY)) {
+        const lineSuffix = item.line ? `:${item.line}` : "";
+        const nameSuffix = item.name ? ` \`${item.name}\`` : "";
+        lines.push(`    - ${item.path}${lineSuffix} [${item.rule}]${nameSuffix}`);
+      }
+      if (items.length > MAX_SAMPLE_KNIP_PER_SEVERITY) {
+        lines.push(`    - ... and ${items.length - MAX_SAMPLE_KNIP_PER_SEVERITY} more in ${severity}`);
+      }
+    }
+  }
+  lines.push("");
+  return lines;
+}
+
+function formatStackBlock(stack) {
+  if (!stack || (!stack.frameworks?.length && !stack.language && !stack.isFrontend && !stack.isBackend)) return [];
+  const lines = ["### Project Stack"];
+  if (stack.language) lines.push(`- Language: ${stack.language}`);
+  if (stack.frameworks?.length) lines.push(`- Frameworks: ${stack.frameworks.join(", ")}`);
+  const tier = stack.isFullstack ? "fullstack (frontend + backend)"
+    : stack.isFrontend ? "frontend-only"
+    : stack.isBackend ? "backend-only"
+    : "unknown";
+  lines.push(`- Tier: ${tier}`);
+  lines.push("");
+  return lines;
+}
+
+function formatBasalCostBlock(basalCost, growthDelta) {
+  const lines = ["### Basal Cost"];
+  lines.push(`- Source: ${basalCost.totalLines} lines across ${basalCost.totalFiles} files`);
+  const deps = basalCost.dependencies || {};
+  if (deps.total) lines.push(`- Dependencies: ${deps.total} (${deps.dependencies} prod + ${deps.devDependencies} dev)`);
+
+  const unused = basalCost.unusedDependencies?.unused;
+  if (Array.isArray(unused) && unused.length > 0) {
+    lines.push(`- Unused dependencies (${unused.length}): ${unused.join(", ")}`);
+  }
+
+  const dead = Array.isArray(basalCost.deadExports) ? basalCost.deadExports : [];
+  if (dead.length > 0) {
+    lines.push(`- Dead exports: ${dead.length}`);
+    for (const de of dead.slice(0, MAX_SAMPLE_DEAD_EXPORTS)) {
+      lines.push(`  - \`${de.name}\` in ${de.file}`);
+    }
+    if (dead.length > MAX_SAMPLE_DEAD_EXPORTS) {
+      lines.push(`  - ... and ${dead.length - MAX_SAMPLE_DEAD_EXPORTS} more`);
+    }
+  } else {
+    lines.push("- Dead exports: 0");
+  }
+
+  if (growthDelta) {
+    lines.push("");
+    lines.push("**Growth since last audit**");
+    lines.push(`- Lines: ${growthDelta.lines >= 0 ? "+" : ""}${growthDelta.lines}`);
+    lines.push(`- Files: ${growthDelta.files >= 0 ? "+" : ""}${growthDelta.files}`);
+    lines.push(`- Dependencies: ${growthDelta.deps >= 0 ? "+" : ""}${growthDelta.deps}`);
+    if (growthDelta.since) lines.push(`- Since: ${growthDelta.since}`);
+  }
+  lines.push("");
+  return lines;
+}
+
+function formatSonarBlock(sonarFindings) {
+  if (!sonarFindings.available) {
+    return ["### SonarQube", `- Status: not available — ${sonarFindings.reason || "host unreachable"}`, ""];
+  }
+  const lines = ["### SonarQube"];
+  if (sonarFindings.qualityGate?.status) lines.push(`- Quality gate: ${sonarFindings.qualityGate.status}`);
+  lines.push(`- Open issues: ${sonarFindings.total ?? 0}`);
+  if ((sonarFindings.total ?? 0) > 0) {
+    const groups = groupIssuesBySeverity(sonarFindings.issues || []);
+    for (const [severity, issues] of Object.entries(groups)) {
+      if (issues.length === 0) continue;
+      lines.push(`  - ${severity} (${issues.length}):`);
+      for (const issue of issues.slice(0, MAX_SAMPLE_SONAR_PER_SEVERITY)) {
+        const lineSuffix = issue.line ? `:${issue.line}` : "";
+        const loc = issue.component ? `${issue.component}${lineSuffix}` : "";
+        const rule = issue.rule ? ` [${issue.rule}]` : "";
+        lines.push(`    - ${loc}${rule} ${issue.message || ""}`.trim());
+      }
+      if (issues.length > MAX_SAMPLE_SONAR_PER_SEVERITY) {
+        lines.push(`    - ... and ${issues.length - MAX_SAMPLE_SONAR_PER_SEVERITY} more in ${severity}`);
+      }
+    }
+  }
+  lines.push("");
+  return lines;
+}
+
+function formatWebperfBlock(webperf) {
+  if (!webperf.available) {
+    return ["### WebPerf", `- Status: not collected — ${webperf.reason || "no frontend signal"}`, ""];
+  }
+  const lines = ["### WebPerf"];
+  if (webperf.mode === "cwv-result" && webperf.cwv) {
+    lines.push(`- Mode: live CWV measurement`);
+    if (webperf.url) lines.push(`- URL: ${webperf.url}`);
+    lines.push(`- Verdict: ${webperf.cwv.pass ? "PASS" : "FAIL"}`);
+    for (const [metric, score] of Object.entries(webperf.cwv.scores || {})) {
+      lines.push(`  - ${metric.toUpperCase()}: ${score.value} (${score.rating})`);
+    }
+  } else {
+    lines.push(`- Mode: static hints only (no live CWV measurement available)`);
+    lines.push(`- LLM phase will scan source for bundle/lazy/img-opt patterns when activated`);
+  }
+  lines.push("");
+  return lines;
+}
+
+/**
+ * Detect whether the deterministic context found any signal worth showing.
+ * If everything came back empty/unavailable, the CLI can skip the
+ * "Continue with LLM?" prompt — there's nothing to compare against.
+ */
+export function deterministicContextHasFindings(ctx) {
+  if (!ctx) return false;
+  if (ctx.basalCost?.deadExports?.length > 0) return true;
+  if (ctx.basalCost?.unusedDependencies?.unused?.length > 0) return true;
+  if (ctx.sonarFindings?.available && (ctx.sonarFindings.total ?? 0) > 0) return true;
+  if (ctx.sonarFindings?.qualityGate?.status === "ERROR") return true;
+  if (ctx.osvFindings?.available && (ctx.osvFindings.total ?? 0) > 0) return true;
+  if (ctx.semgrepFindings?.available && (ctx.semgrepFindings.total ?? 0) > 0) return true;
+  if (ctx.infraFindings?.available && (ctx.infraFindings.total ?? 0) > 0) return true;
+  if (ctx.circularDeps?.available && (ctx.circularDeps.total ?? 0) > 0) return true;
+  if (ctx.deadExports?.available && (ctx.deadExports.total ?? 0) > 0) return true;
+  if (ctx.growthDelta && (Math.abs(ctx.growthDelta.lines || 0) > 100 || Math.abs(ctx.growthDelta.deps || 0) > 0)) return true;
+  if (ctx.aiSlop?.available && (ctx.aiSlop.total ?? 0) > 0) return true;
+  return false;
+}

package/src/audit/harness-scorecard.js

@@ -0,0 +1,100 @@
+// 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.
+//
+// KJC-BUG-0077 — classify failures (docker_missing / image_inaccessible /
+// auth_required / network_error / unknown) and emit an actionable hint
+// alongside the raw stderr so `kj audit` surfaces something better than
+// the opaque "pull access denied" line the registry returns.
+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);
+
+const DOCKER_FAILURE_PATTERNS = [
+  { reason: "image_inaccessible", re: /pull access denied|repository does not exist|manifest unknown|not found: manifest|denied: requested access/i },
+  { reason: "auth_required",      re: /unauthorized|authentication required|login required|requires authentication/i },
+  { reason: "network_error",      re: /no such host|connection refused|dial tcp|i\/o timeout|TLS handshake|net\/http|temporary failure in name resolution/i },
+];
+
+export function classifyDockerFailure(stderr = "") {
+  const s = String(stderr);
+  for (const { reason, re } of DOCKER_FAILURE_PATTERNS) {
+    if (re.test(s)) return reason;
+  }
+  return "unknown";
+}
+
+export function hintForReason(reason, image) {
+  switch (reason) {
+    case "image_inaccessible":
+      return `Image \`${image}\` is not accessible from the public registry (it may have been removed, renamed, or made private). Either run \`kj audit --no-harness\` to skip this step, or override \`audit.harness.image\` with a mirror you control.`;
+    case "auth_required":
+      return `Pulling \`${image}\` requires registry authentication. Run \`docker login <registry>\` first, or override \`audit.harness.image\` with a public mirror.`;
+    case "network_error":
+      return `Network error reaching the registry while pulling \`${image}\`. Retry once connectivity is back; \`kj audit --no-harness\` skips this step in the meantime.`;
+    case "docker_missing":
+      return `Docker is not available on this machine. Install Docker (or run \`kj audit --no-harness\` to silence this).`;
+    default: return null;
+  }
+}
+
+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) {
+    const stderr = r.stderr?.trim() || `exit ${r.exitCode}`;
+    const reason = classifyDockerFailure(stderr);
+    return { pulled: false, reused: false, image: cfg.image, error: stderr, reason };
+  }
+  return { pulled: true, reused: false, image: cfg.image };
+}
+
+export async function runHarnessAssess(repoPath, harness = null) {
+  const cfg = normalizeHarnessConfig(harness || {});
+  if (!(await isDockerAvailable())) {
+    return { ok: false, reason: "docker_missing", image: cfg.image, error: "Docker daemon is not available", hint: hintForReason("docker_missing", cfg.image) };
+  }
+  const pull = await ensureHarnessImage(cfg);
+  if (pull.error) {
+    const reason = pull.reason || "pull_failed";
+    return { ok: false, reason, image: cfg.image, error: pull.error, hint: hintForReason(reason, cfg.image) };
+  }
+  const r = await runCommand(
+    "docker",
+    ["run", "--rm", "-v", `${repoPath}:/repo:ro`, cfg.image, "assess", "/repo", "--format", "json"],
+    { timeout: cfg.assessTimeoutMs },
+  );
+  if (r.exitCode !== 0) {
+    const stderr = r.stderr?.trim() || r.stdout?.trim() || `exit ${r.exitCode}`;
+    const reason = classifyDockerFailure(stderr);
+    return { ok: false, reason, image: cfg.image, error: stderr, hint: hintForReason(reason, cfg.image) };
+  }
+  try {
+    const parsed = JSON.parse(r.stdout);
+    return { ok: true, score: parsed.overall_score, grade: parsed.grade, raw: parsed };
+  } catch (e) { return { ok: false, reason: "invalid_json", error: `Invalid JSON from harness: ${e.message}` }; }
+}

package/src/audit/harness-section.js

@@ -0,0 +1,81 @@
+// 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, reason: res.reason, hint: res.hint, image: cfg.image };
+  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) {
+    const reason = summary.reason ? ` (${summary.reason})` : "";
+    const hint = summary.hint ? `\n\n${summary.hint}\n` : "";
+    return `## Harness Scorecard\n\n_skipped${reason}: ${summary.error}_${hint}\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/audit/infra-findings.js

@@ -0,0 +1,100 @@
+/**
+ * Checkov infra-misconfiguration collector for `kj audit` (INF-C,
+ * KJC-TSK-0760, epic KJC-PCS-0078).
+ *
+ * One tool covers the whole infra surface — terraform, kubernetes, helm,
+ * kustomize, ansible, dockerfiles — so checkov is THE infra scanner (tfsec
+ * and tflint stay out of scope: single dependency to learn and install).
+ * Findings enter the audit through the SAME best-effort channel as
+ * semgrep-findings (KJC-TSK-0366): no infra markers → not-applicable (zero
+ * noise, checkov never runs); missing binary → declared with the install
+ * command; non-zero exit with JSON on stdout (checkov's failed-checks
+ * behavior) rescued; unparseable output degrades SAYING so.
+ */
+
+import { runGoverned, jobsCap } from "../utils/tool-governor.js";
+import { detectInfraMarkers } from "../utils/project-detect.js";
+
+const SCAN_TIMEOUT_MS = 120_000;
+const INSTALL_HINT = "install via 'pipx install checkov' or 'pip install checkov'";
+
+/**
+ * Run checkov on the project and return a structured result.
+ *
+ * @param {string} projectDir - absolute path to the project root
+ * @param {object} [logger]
+ * @returns {Promise<{available: boolean, reason?: string, total?: number, findings?: object[]}>}
+ */
+export async function collectInfraFindings(projectDir, logger = null) {
+  // KJC-BUG-0122 doctrine: external scanners never fire from the unit suite.
+  if (process.env.VITEST && process.env.KJ_ALLOW_REAL_SCANS !== "1") {
+    return { available: false, reason: "real scans disabled under the test runner (set KJ_ALLOW_REAL_SCANS=1 to opt in)" };
+  }
+  if (!(await detectInfraMarkers(projectDir))) {
+    return { available: false, reason: "no infra markers (terraform/helm/kustomize/ansible) — not applicable" };
+  }
+  let stdout;
+  try {
+    const { stdout: out } = await runGoverned(
+      "checkov",
+      ["-d", projectDir || ".", "--output", "json", "--quiet", "--compact", `--parallel-runner-count=${jobsCap()}`],
+      { cwd: projectDir, timeout: SCAN_TIMEOUT_MS + 5000, maxBuffer: 32 * 1024 * 1024 }
+    );
+    stdout = out;
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      if (logger?.warn) logger.warn(`checkov not found in PATH — ${INSTALL_HINT}`);
+      return { available: false, reason: `checkov not installed — ${INSTALL_HINT}` };
+    }
+    if (err.killed) {
+      if (logger?.warn) logger.warn(`checkov timed out after ${SCAN_TIMEOUT_MS}ms`);
+      return { available: false, reason: `checkov timed out after ${SCAN_TIMEOUT_MS}ms` };
+    }
+    // checkov exits non-zero when checks fail, but still emits the report.
+    if (typeof err.stdout === "string" && err.stdout.trim().length > 0) {
+      stdout = err.stdout;
+    } else {
+      if (logger?.warn) logger.warn(`checkov failed: ${err.message}`);
+      return { available: false, reason: `checkov failed: ${err.message}` };
+    }
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch (err) {
+    if (logger?.warn) logger.warn(`checkov output not parseable: ${err.message}`);
+    return { available: false, reason: "checkov output not parseable as JSON" };
+  }
+
+  return { available: true, ...parseCheckovOutput(parsed) };
+}
+
+/**
+ * Convert checkov's JSON (object for one framework, array for several)
+ * into the flat findings list the audit prompt consumes. Checkov OSS may
+ * omit severity — WARNING is the honest default.
+ *
+ * @param {object|object[]} raw
+ * @returns {{total: number, findings: object[]}}
+ */
+export function parseCheckovOutput(raw) {
+  const reports = Array.isArray(raw) ? raw : [raw];
+  const findings = [];
+  for (const report of reports) {
+    const failed = report?.results?.failed_checks;
+    if (!Array.isArray(failed)) continue;
+    for (const c of failed) {
+      findings.push({
+        rule: c.check_id || "(unknown)",
+        severity: String(c.severity || "WARNING").toUpperCase(),
+        framework: report.check_type || "infra",
+        file: String(c.file_path || "").replace(/^\//, ""),
+        line: Array.isArray(c.file_line_range) ? (c.file_line_range[0] ?? 0) : 0,
+        message: c.check_name || "",
+        guideline: c.guideline || null,
+      });
+    }
+  }
+  return { total: findings.length, findings };
+}