karajan-code 2.8.0 → 2.10.0

package/README.md

@@ -23,7 +23,7 @@
 
 ---
 
-> **v2.8.0 released** — Audit-driven hardening release. The 2026-04-30 self-audit (`kj audit`) flagged 13 issues across security, code quality, performance, architecture and testing; this release closes all of them in 16 PRs with 0 user-visible API changes. Highlights: (1) **Security**: every `child_process` call in `src/` now uses tokenised arg arrays (no shell expansion) — closed 7 sites that took template strings. (2) **FASE 1 e2e suite**: 7 scenarios + fake-coder/sonar fixtures cover the 5-bug class from the 2026-04-27 demo regression (zombie-HU, saveSession-missing, Repairer unfixable, zombi-status, audit smoke). 23 e2e tests in 6s. (3) **File splits**: `cli.js` 699→113 LOC, `commands/plan.js` 549→14 LOC (shim) + sub-commands, `iteration-loop.js` 513→311 LOC, `pre-loop.js` 626→435 LOC. Each big driver now under the 600-LOC ceiling. (4) **ESLint ratcheted**: 57 warnings closed in `src/`, then `no-unused-vars` / `no-useless-assignment` / `no-useless-escape` / `preserve-caught-error` switched warn→error so regressions fail CI. New rules ban `console.*` outside CLI paths and `globalThis.__KJ_*` outside `test-harness.js`. (5) **BREAKING**: `engines.node` 18→20.10.0 (Node 18 LTS hit EOL 2025-04-30). See [CHANGELOG.md](./CHANGELOG.md) for the full punch list and [MIGRATION-v2.md](./MIGRATION-v2.md) for v1→v2 breaking changes.
+> **v2.10.0 released** — Agent-readiness release. Karajan is now the first orchestrator with a full agent-readability surface: an `llms.txt` index at the root, a `SKILL.md` per CLI command under `docs/agents/`, and a static auditor that scores any third-party repo against the same shape. Highlights: (1) **`kj audit --agent-readiness`** scores any repo 0–100 across seven checks (llms.txt, robots AI-bot allowlist, page token budgets ≤ 32 KB, heading hierarchy, agents/README, SKILL.md coverage). LLM-free, deterministic, JSON-able. Karajan-on-Karajan: **100/100**. (2) **Six new SKILL.md files** (`kj doctor / init / board / review / resume / clean`) under `docs/agents/`, all with the same `What it does · Inputs · Outputs · Side effects · Failure modes · Example` contract; CI guards every link in `llms.txt` resolves. (3) **Webperf quality gate inside the iteration loop** (`pipeline.perf.enabled`): PASS continues, FAIL pushes blocking-metric feedback to the coder, scanner-missing skips best-effort. (4) **HU Board hardening**: binds 127.0.0.1 by default, opt-in `--bind 0.0.0.0` enforces an auto-generated token, helmet headers, rate limiting at 300 req/min — "safe by default on a coffee-shop WiFi". (5) **a11y skills auto-route**: tasks mentioning `accessibility / WCAG / ARIA / screen reader / keyboard nav` automatically pull the `frontend-ui-engineering` skill. (6) **Asciinema demo scripts** under `docs/demos/` so the recordings re-record per release instead of rotting. 5 PRs merged (#605–#609 + #610), 4358/4358 tests passing. See [CHANGELOG.md](./CHANGELOG.md) for the full punch list.
 
 You describe what you want to build. Karajan orchestrates multiple AI agents to plan it, implement it, test it, review it with SonarQube, and iterate. No babysitting required.
 
@@ -113,6 +113,19 @@ cd wrappers/python && pip install .
 
 That's it. `kj init` auto-detects your installed agents and installs RTK for token optimization.
 
+### Optional scanners for `kj audit` + `kj webperf`
+
+Karajan auto-skips any scanner that isn't installed. Add the ones that match your projects:
+
+| Tool | Install | What you get |
+|------|---------|--------------|
+| **SonarQube** | `docker compose -f ~/sonarqube/docker-compose.yml up -d` | Code quality + security rules with line-precision in `kj audit` |
+| **OSV-Scanner** | `go install github.com/google/osv-scanner@latest` | Dependency CVE coverage broader than `npm audit` |
+| **Semgrep** | `pipx install semgrep` | SAST: XSS, SQLi, taint flow, secrets — equivalent to `snyk code`, free for OSS |
+| **Lighthouse** | `npm install -g lighthouse` | Core Web Vitals + opportunities for `kj webperf` (auto-feeds `kj audit`) |
+
+Skip any per-run with `--no-sonar`, `--no-osv`, `--no-semgrep`. See [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md#optional-scanners--kj-audit--kj-webperf) for full table.
+
 ## Three ways to use Karajan
 
 Karajan installs **three commands**: `kj`, `kj-tail`, and `karajan-mcp`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.8.0",
+  "version": "2.10.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/audit/agent-readiness.js

@@ -104,10 +104,15 @@ const CHECKS = [
       if (!fs.existsSync(docsDir)) return { ok: true, hint: null, details: { docsDirPresent: false } };
       const violations = [];
       for (const f of listMarkdownFiles(docsDir)) {
-        const text = safeRead(f);
-        const h1Count = (text.match(/^#\s+/gm) || []).length;
+        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 });
+          violations.push({ file: path.relative(rootDir, f), h1Count, mdH1Count, htmlH1Count });
           continue;
         }
         // Check for skipped levels (#### without preceding ###, etc.)
@@ -166,6 +171,19 @@ 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.replace(/^([ \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;

package/src/audit/basal-cost.js

@@ -92,14 +92,68 @@ function runDepcheck(projectDir) {
   });
 }
 
+// Regexes hoisted to module scope so they're compiled once instead of per file.
+// Naming: *Re catches static/syntactic patterns; we still rely on the import set
+// being a superset (false negative > false positive in audit context).
+const EXPORT_RE = /export\s+(?:default\s+)?(?:function|class|const|let|var|async\s+function)\s+(\w+)/g;
+const NAMED_EXPORT_RE = /export\s*\{([^}]+)\}/g;
+const STATIC_NAMED_IMPORT_RE = /import\s+\{([^}]+)\}\s+from/g;
+const DEFAULT_IMPORT_RE = /import\s+(\w+)\s+from/g;
+// Namespace import (`import * as ns from <path>`) — knip-equivalent: mark
+// the target file as fully-consumed because we cannot statically know
+// which `ns.X` accesses happen.
+const NAMESPACE_IMPORT_RE = /import\s+\*\s+as\s+\w+\s+from\s+["']([^"']+)["']/g;
+// Any dynamic `await import(<path>)` — destructured, late-bound, or
+// member-accessed. Conservatively mark the target as fully-consumed:
+// trying to enumerate downstream destructuring/member-access patterns is
+// fragile (the same test may use parenthesised assignment with no const,
+// or bind first and `.foo`-access later). A false-negative here (one
+// extra "live" export we can't prove dead) is always cheaper than a
+// false-positive in audit context.
+const DYNAMIC_IMPORT_RE = /\bawait\s+import\s*\(\s*["']([^"']+)["']\s*\)/g;
+// Re-export bridges (`export { x } from <path>` and `export * from <path>`)
+// — both consume from the target file (the re-exporter is itself another
+// file consumer downstream).
+const RE_EXPORT_NAMED_RE = /export\s*\{([^}]+)\}\s*from\s*["']([^"']+)["']/g;
+const RE_EXPORT_STAR_RE = /export\s*\*\s*from\s*["']([^"']+)["']/g;
+// Export preceded by a JSDoc block with `@internal` is opt-out: documented as
+// dynamic-import-only or test-fixture surface that the regex passes can't see.
+const INTERNAL_EXPORT_RE = /\/\*\*[\s\S]*?@internal[\s\S]*?\*\/\s*export\s+(?:default\s+)?(?:function|class|const|let|var|async\s+function)\s+(\w+)/g;
+
+function resolveImportSpecifier(fromFile, specifier) {
+  // Only resolve project-relative paths; bare specifiers (npm packages) and
+  // node: builtins are not in our exportMap and don't matter here.
+  if (!specifier.startsWith(".") && !specifier.startsWith("/")) return null;
+  const base = path.resolve(path.dirname(fromFile), specifier);
+  // Caller will probe both with and without explicit extensions.
+  return base.endsWith(".js") || base.endsWith(".mjs") || base.endsWith(".cjs")
+    || base.endsWith(".ts") || base.endsWith(".tsx")
+    ? base
+    : `${base}.js`;
+}
+
+// Strip every string literal (template, double, single) from the content
+// before scanning for export declarations. Test files routinely embed
+// sample source code inside fixtures (template literals for plugin
+// modules, double-quoted diff lines for prompt tests, etc.). At top level
+// `export ...` is a statement, never an expression, so it can never
+// legitimately appear inside a quoted string in real code — meaning the
+// strip is safe for export detection. We do NOT use this stripped view
+// for import detection: the import regexes anchor on `import {...} from`
+// regardless of the path string, but the namespace/dynamic-import passes
+// need the actual path inside the quotes to resolve the target module.
+function stripStringLiterals(content) {
+  return content
+    .replace(/`[^`]*`/g, "``")
+    .replace(/"(?:\\.|[^"\\])*"/g, '""')
+    .replace(/'(?:\\.|[^'\\])*'/g, "''");
+}
+
 async function findDeadExports(sourceFiles) {
   const exportMap = new Map(); // file -> [exportName]
+  const internalExportsByFile = new Map(); // file -> Set<exportName>
   const importedNames = new Set();
-
-  const exportRe = /export\s+(?:default\s+)?(?:function|class|const|let|var|async\s+function)\s+(\w+)/g;
-  const namedExportRe = /export\s*\{([^}]+)\}/g;
-  const importRe = /import\s+\{([^}]+)\}\s+from/g;
-  const defaultImportRe = /import\s+(\w+)\s+from/g;
+  const fullyConsumedFiles = new Set(); // resolved file paths reached via `import *` or bound dynamic import
 
   for (const file of sourceFiles) {
     let content;
@@ -108,12 +162,13 @@ async function findDeadExports(sourceFiles) {
     } catch {
       continue;
     }
+    const exportContent = stripStringLiterals(content);
 
     const exports = [];
-    for (const match of content.matchAll(exportRe)) {
+    for (const match of exportContent.matchAll(EXPORT_RE)) {
       exports.push(match[1]);
     }
-    for (const match of content.matchAll(namedExportRe)) {
+    for (const match of exportContent.matchAll(NAMED_EXPORT_RE)) {
       const names = match[1].split(",").map(n => n.trim().split(/\s+as\s+/).pop().trim());
       exports.push(...names);
     }
@@ -121,18 +176,46 @@ async function findDeadExports(sourceFiles) {
       exportMap.set(file, exports);
     }
 
-    for (const match of content.matchAll(importRe)) {
+    // Collect `@internal`-tagged exports up front so the dead-pass can skip them.
+    const internalSet = new Set();
+    for (const match of exportContent.matchAll(INTERNAL_EXPORT_RE)) {
+      internalSet.add(match[1]);
+    }
+    if (internalSet.size > 0) {
+      internalExportsByFile.set(file, internalSet);
+    }
+
+    for (const match of content.matchAll(STATIC_NAMED_IMPORT_RE)) {
       const names = match[1].split(",").map(n => n.trim().split(/\s+as\s+/)[0].trim());
       for (const name of names) importedNames.add(name);
     }
-    for (const match of content.matchAll(defaultImportRe)) {
+    for (const match of content.matchAll(DEFAULT_IMPORT_RE)) {
       importedNames.add(match[1]);
     }
+    for (const match of content.matchAll(NAMESPACE_IMPORT_RE)) {
+      const resolved = resolveImportSpecifier(file, match[1]);
+      if (resolved) fullyConsumedFiles.add(resolved);
+    }
+    for (const match of content.matchAll(DYNAMIC_IMPORT_RE)) {
+      const resolved = resolveImportSpecifier(file, match[1]);
+      if (resolved) fullyConsumedFiles.add(resolved);
+    }
+    for (const match of content.matchAll(RE_EXPORT_NAMED_RE)) {
+      const names = match[1].split(",").map(n => n.trim().split(/\s+as\s+/)[0].trim());
+      for (const name of names) importedNames.add(name);
+    }
+    for (const match of content.matchAll(RE_EXPORT_STAR_RE)) {
+      const resolved = resolveImportSpecifier(file, match[1]);
+      if (resolved) fullyConsumedFiles.add(resolved);
+    }
   }
 
   const dead = [];
   for (const [file, exports] of exportMap) {
+    if (fullyConsumedFiles.has(file)) continue; // module imported via * or bound await import — can't tell which exports are used
+    const internalSet = internalExportsByFile.get(file);
     for (const name of exports) {
+      if (internalSet?.has(name)) continue; // explicitly opted out via @internal
       if (!importedNames.has(name)) {
         dead.push({ file, name });
       }

package/src/audit/deterministic-summary.js

@@ -0,0 +1,200 @@
+/**
+ * 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";
+
+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;
+
+/**
+ * @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.webperf) lines.push(...formatWebperfBlock(ctx.webperf));
+
+  return lines.join("\n");
+}
+
+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 loc = f.file ? `${f.file}${f.line ? `:${f.line}` : ""}` : "";
+        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;
+}
+
+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 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 loc = issue.component ? `${issue.component}${issue.line ? `:${issue.line}` : ""}` : "";
+        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.growthDelta && (Math.abs(ctx.growthDelta.lines || 0) > 100 || Math.abs(ctx.growthDelta.deps || 0) > 0)) return true;
+  return false;
+}

package/src/audit/osv-findings.js

@@ -0,0 +1,162 @@
+/**
+ * OSV-Scanner findings collector for `kj audit` (KJC-TSK-0365).
+ *
+ * Wraps Google's `osv-scanner` CLI and feeds its results into the audit
+ * prompt as a deterministic vulnerability section. OSV.dev's database
+ * pulls from GitHub Advisory Database, GLSA, PyPI advisories, Go vuln
+ * DB and others — broader coverage than `npm audit` alone, with no
+ * account, token, or upload (the scanner runs locally and only the
+ * advisory data is fetched on demand).
+ *
+ * This module follows the same pattern as src/audit/sonar-findings.js:
+ *   - Best-effort: missing binary or scan errors return
+ *     {available: false, reason} and the audit continues without the
+ *     section.
+ *   - Severity-grouped: helps the LLM (and the deterministic summary)
+ *     prioritise the worst issues without scrolling.
+ *   - Capped: only the first MAX_OSV_VULNS_IN_PROMPT entries land in
+ *     the prompt, with overflow markers per severity, so an
+ *     out-of-control result list cannot blow the token budget.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+const SCAN_TIMEOUT_MS = 60_000;
+const SEVERITY_ORDER = ["CRITICAL", "HIGH", "MEDIUM", "LOW", "MODERATE"];
+
+/**
+ * Run osv-scanner 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, vulnerabilities?: object[]}>}
+ */
+export async function collectOsvFindings(projectDir, logger = null) {
+  let stdout;
+  try {
+    const { stdout: out } = await execFileAsync(
+      "osv-scanner",
+      ["--format=json", "--recursive", projectDir || "."],
+      { cwd: projectDir, timeout: SCAN_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 }
+    );
+    stdout = out;
+  } catch (err) {
+    // osv-scanner exits with non-zero when vulnerabilities are found, so
+    // err.code 1 is NORMAL — we still want the stdout. Real failures are
+    // ENOENT (binary missing) or stdout empty.
+    if (err.code === "ENOENT") {
+      if (logger?.warn) logger.warn("osv-scanner not found in PATH — install via 'go install github.com/google/osv-scanner@latest'");
+      return { available: false, reason: "osv-scanner not installed" };
+    }
+    if (err.killed) {
+      if (logger?.warn) logger.warn(`osv-scanner timed out after ${SCAN_TIMEOUT_MS}ms`);
+      return { available: false, reason: `osv-scanner timed out after ${SCAN_TIMEOUT_MS}ms` };
+    }
+    if (typeof err.stdout === "string" && err.stdout.trim().length > 0) {
+      stdout = err.stdout;
+    } else {
+      if (logger?.warn) logger.warn(`osv-scanner failed: ${err.message}`);
+      return { available: false, reason: `osv-scanner failed: ${err.message}` };
+    }
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch (err) {
+    if (logger?.warn) logger.warn(`osv-scanner output not parseable: ${err.message}`);
+    return { available: false, reason: "osv-scanner output not parseable as JSON" };
+  }
+
+  return { available: true, ...parseOsvOutput(parsed) };
+}
+
+/**
+ * Flatten the osv-scanner JSON shape into a flat list of vulnerabilities.
+ * The scanner emits results[].packages[].vulnerabilities[].
+ *
+ * @param {object} raw - parsed osv-scanner JSON
+ * @returns {{total: number, vulnerabilities: object[]}}
+ */
+export function parseOsvOutput(raw) {
+  const flat = [];
+  const results = Array.isArray(raw?.results) ? raw.results : [];
+  for (const result of results) {
+    const source = result.source?.path || result.source || "";
+    const packages = Array.isArray(result.packages) ? result.packages : [];
+    for (const pkg of packages) {
+      const name = pkg.package?.name || "";
+      const version = pkg.package?.version || "";
+      const ecosystem = pkg.package?.ecosystem || "";
+      const vulns = Array.isArray(pkg.vulnerabilities) ? pkg.vulnerabilities : [];
+      const groups = Array.isArray(pkg.groups) ? pkg.groups : [];
+      for (const vuln of vulns) {
+        flat.push({
+          id: vuln.id || vuln.aliases?.[0] || "UNKNOWN",
+          aliases: vuln.aliases || [],
+          severity: extractSeverity(vuln, groups),
+          summary: vuln.summary || vuln.details?.split("\n")[0] || "",
+          package: name,
+          version,
+          ecosystem,
+          source,
+          fixed: extractFixedVersion(vuln),
+        });
+      }
+    }
+  }
+  return { total: flat.length, vulnerabilities: flat };
+}
+
+/**
+ * Resolve a vulnerability's effective severity. osv-scanner reports
+ * CVSS (per-vuln) and a separate `groups[].severity` (per scanner run).
+ * Group severity wins when present because it reflects scanner policy.
+ */
+function extractSeverity(vuln, groups) {
+  // Group-level severity (scanner-resolved, includes ecosystem context)
+  for (const group of groups) {
+    if (group.ids?.includes(vuln.id) && group.severity) {
+      return String(group.severity).toUpperCase();
+    }
+  }
+  // Per-vuln CVSS — pick the highest score
+  const severities = Array.isArray(vuln.severity) ? vuln.severity : [];
+  for (const sev of severities) {
+    if (sev?.severity) return String(sev.severity).toUpperCase();
+  }
+  // database_specific severity (GHSA-style)
+  if (vuln.database_specific?.severity) {
+    return String(vuln.database_specific.severity).toUpperCase();
+  }
+  return "UNKNOWN";
+}
+
+function extractFixedVersion(vuln) {
+  const ranges = vuln.affected?.[0]?.ranges || [];
+  for (const range of ranges) {
+    const events = range.events || [];
+    for (const event of events) {
+      if (event.fixed) return event.fixed;
+    }
+  }
+  return null;
+}
+
+/**
+ * Group vulnerabilities by severity, preserving canonical ordering
+ * (CRITICAL → HIGH → MEDIUM/MODERATE → LOW → UNKNOWN).
+ */
+export function groupVulnerabilitiesBySeverity(vulnerabilities) {
+  const groups = Object.fromEntries(SEVERITY_ORDER.map(s => [s, []]));
+  groups.UNKNOWN = [];
+  for (const vuln of vulnerabilities || []) {
+    const sev = (vuln.severity || "UNKNOWN").toUpperCase();
+    if (groups[sev]) groups[sev].push(vuln);
+    else groups.UNKNOWN.push(vuln);
+  }
+  return groups;
+}