@karajan-family/code 4.21.0

package/src/audit/injection-findings.js

@@ -0,0 +1,114 @@
+/**
+ * Prompt-injection findings collector for `kj audit` (KJC-TSK-0498).
+ * Scans `.karajan/specs/**`, `.karajan/domain.md` and
+ * `.karajan/onboarding/**` reusing `src/utils/injection-guard.js`.
+ * Best-effort: missing folders return `scanned: 0`.
+ */
+
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { scanForInjection } from "../utils/injection-guard.js";
+
+const MAX_FILE_BYTES = 256 * 1024;
+const MAX_DEPTH = 6;
+const SEVERITY_BY_TYPE = { directive: "HIGH", unicode: "MEDIUM", comment_block: "LOW" };
+
+const SCAN_TARGETS = [
+  { rel: ".karajan/specs", kind: "dir" },
+  { rel: ".karajan/onboarding", kind: "dir" },
+  { rel: ".karajan/domain.md", kind: "file" },
+  // KJC-TSK-0695: the agent-context surface — whatever lands in the host
+  // agent's context every session is the real injection vector.
+  { rel: "CLAUDE.md", kind: "file" },
+  { rel: "AGENTS.md", kind: "file" },
+  { rel: "GEMINI.md", kind: "file" },
+  { rel: ".cursorrules", kind: "file" },
+  { rel: path.join(".github", "copilot-instructions.md"), kind: "file" },
+  { rel: "templates", kind: "dir" },
+  { rel: ".rulesync", kind: "dir" },
+];
+
+export async function collectInjectionFindings(rootDir, logger = null) {
+  if (!rootDir) return { available: false, reason: "rootDir not provided" };
+  const findings = [];
+  let scanned = 0;
+  try {
+    for (const target of SCAN_TARGETS) {
+      const abs = path.join(rootDir, target.rel);
+      const files = target.kind === "dir"
+        ? await listFiles(abs, 0)
+        : (await fileExists(abs)) ? [abs] : [];
+      for (const file of files) {
+        scanned += 1;
+        const content = await safeRead(file);
+        if (!content) continue;
+        const result = scanForInjection(content);
+        if (result.clean) continue;
+        for (const f of result.findings) {
+          findings.push({
+            file: path.relative(rootDir, file),
+            type: f.type,
+            pattern: f.pattern,
+            snippet: f.snippet,
+            line: f.line,
+            severity: SEVERITY_BY_TYPE[f.type] || "LOW",
+          });
+        }
+      }
+    }
+  } catch (err) {
+    if (logger?.warn) logger.warn(`injection-findings collector failed: ${err.message}`);
+    return { available: false, reason: `collector failed: ${err.message}` };
+  }
+  return { available: true, scanned, total: findings.length, findings };
+}
+
+export function groupInjectionBySeverity(findings) {
+  const groups = { HIGH: [], MEDIUM: [], LOW: [] };
+  for (const f of findings || []) {
+    const sev = (f.severity || "LOW").toUpperCase();
+    if (groups[sev]) groups[sev].push(f);
+    else groups.LOW.push(f);
+  }
+  return groups;
+}
+
+async function listFiles(dir, depth) {
+  if (depth > MAX_DEPTH) return [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of entries) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const nested = await listFiles(abs, depth + 1);
+      out.push(...nested);
+    } else if (entry.isFile()) {
+      out.push(abs);
+    }
+  }
+  return out;
+}
+
+async function fileExists(file) {
+  try {
+    const s = await stat(file);
+    return s.isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function safeRead(file) {
+  try {
+    const s = await stat(file);
+    if (s.size > MAX_FILE_BYTES) return null;
+    return await readFile(file, "utf8");
+  } catch {
+    return null;
+  }
+}

package/src/audit/issue-filter.js

@@ -0,0 +1,133 @@
+// Generalised deterministic false-positive filter for kj audit collectors.
+//
+// Originally introduced as `src/sonar/issue-filter.js` in v2.16.0 (KJC-TSK-0416)
+// for Sonar findings. Generalised here so every collector (sonar, knip, madge,
+// osv, semgrep, …) can reuse the same two mechanisms:
+//
+//   1. Static rules: { tool, rule, filePattern, reason }. Match by tool name
+//      + rule id + path pattern. Catalogue below + extensible per project via
+//      config.audit.false_positives. Legacy `config.sonar.false_positives` is
+//      honoured for backwards compatibility.
+//   2. Inline ignore: `// karajan-audit-ignore: <tool>:<ruleId>` on the issue
+//      line or the previous one. Legacy `// karajan-sonar-ignore: <ruleId>`
+//      keeps working when the issue's tool is "sonar".
+//
+// Issues filtered out are kept in the `suppressed` list with `_suppressedBy`
+// metadata for auditability — no silent dropping.
+
+import fs from "node:fs";
+import { escapeRegExp } from "../utils/escape-regexp.js";
+
+export const DEFAULT_FALSE_POSITIVES = [
+  {
+    tool: "sonar",
+    rule: "javascript:S2699",
+    filePattern: /tests\/architecture\//,
+    reason: "Structural tests assert via expect(offenders, msg).toEqual([]) — Sonar misses the custom-message form",
+  },
+  // Knip — v2.17 audit/dead-exports collector.
+  {
+    tool: "knip",
+    rule: "unused-files",
+    filePattern: /(?:^|\/)tests\/fixtures\//,
+    reason: "Test fixtures are loaded by file path at runtime, not statically imported — knip can't see them",
+  },
+  {
+    tool: "knip",
+    rule: "unused-files",
+    filePattern: /(?:^|\/)examples\//,
+    reason: "Example projects are user-facing entry points, not consumed by the parent project's source",
+  },
+  {
+    tool: "knip",
+    rule: "unused-exports",
+    filePattern: /(?:^|\/)(?:index|main)\.(?:js|ts|mjs|cjs|jsx|tsx)$/,
+    reason: "Barrel re-exports in index.{js,ts} are legitimate public API surface even when no in-tree caller uses them",
+  },
+  // Madge — v2.17 audit/circular-deps collector.
+  {
+    tool: "madge",
+    rule: "circular-import",
+    filePattern: /node_modules\//,
+    reason: "Cycles inside node_modules are upstream's problem, not ours — defensive default since madge excludes node_modules by config",
+  },
+];
+
+export function hasInlineIgnore(filePath, line, ruleId, tool = "sonar") {
+  if (!filePath || !line || !ruleId) return false;
+  if (!fs.existsSync(filePath)) return false;
+  try {
+    const lines = fs.readFileSync(filePath, "utf8").split("\n");
+    const idx = line - 1;
+    const candidates = [lines[idx], lines[idx - 1]].filter(Boolean);
+    const escapedRule = escapeRegExp(ruleId);
+    const escapedTool = escapeRegExp(tool);
+    // New generalised marker + legacy sonar-only marker.
+    const reAudit = new RegExp(`karajan-audit-ignore\\s*:\\s*${escapedTool}:${escapedRule}\\b`);
+    const reLegacy = tool === "sonar"
+      ? new RegExp(`karajan-sonar-ignore\\s*:\\s*${escapedRule}\\b`)
+      : null;
+    return candidates.some((l) => reAudit.test(l) || (reLegacy && reLegacy.test(l)));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Filter a list of normalised audit findings into kept + suppressed.
+ *
+ * @param {object[]} issues  Each issue must carry { tool, rule, component|path, line? }.
+ *                           `tool` defaults to "sonar" for backwards compat.
+ * @param {object} [opts]
+ * @param {object[]} [opts.extraRules]   Rules from config.audit.false_positives
+ *                                       (or legacy config.sonar.false_positives).
+ * @param {string} [opts.projectRoot]    Used to resolve component → absolute path.
+ * @returns {{ kept: object[], suppressed: object[] }}
+ */
+export function filterFalsePositives(issues, opts = {}) {
+  if (!Array.isArray(issues)) return { kept: [], suppressed: [] };
+  const rules = [...DEFAULT_FALSE_POSITIVES, ...(opts.extraRules || [])].map((r) => ({
+    tool: r.tool || "sonar",
+    rule: r.rule,
+    filePattern: r.filePattern instanceof RegExp ? r.filePattern : new RegExp(String(r.filePattern || ".*")),
+    reason: r.reason,
+  }));
+  const projectRoot = opts.projectRoot || process.cwd();
+  const kept = [];
+  const suppressed = [];
+
+  for (const issue of issues) {
+    const tool = issue.tool || "sonar";
+    const path = componentToPath(issue.component) || issue.path || "";
+    let matched = null;
+
+    // 1. Static rules.
+    for (const rule of rules) {
+      if (rule.tool === tool && issue.rule === rule.rule && rule.filePattern.test(path)) {
+        matched = { tool, rule: rule.rule, path, reason: rule.reason };
+        break;
+      }
+    }
+
+    // 2. Inline ignore (only checked if no static rule matched).
+    if (!matched && issue.rule && issue.line && path) {
+      const absPath = path.startsWith("/") ? path : `${projectRoot}/${path}`;
+      if (hasInlineIgnore(absPath, issue.line, issue.rule, tool)) {
+        matched = { tool, rule: issue.rule, path, reason: "inline `// karajan-audit-ignore`" };
+      }
+    }
+
+    if (matched) {
+      suppressed.push({ ...issue, _suppressedBy: matched });
+    } else {
+      kept.push(issue);
+    }
+  }
+  return { kept, suppressed };
+}
+
+function componentToPath(component) {
+  if (typeof component !== "string") return "";
+  const colonIdx = component.indexOf(":");
+  return colonIdx >= 0 ? component.slice(colonIdx + 1) : component;
+}

package/src/audit/osv-findings.js

@@ -0,0 +1,167 @@
+/**
+ * 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 { runGoverned } from "../utils/tool-governor.js";
+
+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) {
+  // KJC-BUG-0122: same kill-switch as semgrep — external scanners never
+  // fire from the unit suite; e2e opts in with KJ_ALLOW_REAL_SCANS=1.
+  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)" };
+  }
+  let stdout;
+  try {
+    // KJC-TSK-0668: governed run — single-flight across kj processes and a
+    // timeout that kills the whole process tree (osv-scanner is I/O-bound,
+    // no jobs flag to cap).
+    const { stdout: out } = await runGoverned(
+      "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/v2/cmd/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;
+}

package/src/audit/plan-adherence.js

@@ -0,0 +1,224 @@
+/**
+ * Plan adherence metric — KJC-TSK-0376 (deepeval-inspired).
+ * Pure offline 0-100 score: how faithfully did the coder follow the plan?
+ * Components (weighted): commit_attribution 40%, acceptance_tests 30%,
+ * scope_discipline 20%, dependency_order 10%. Components return null
+ * when no data; aggregator redistributes the weight.
+ * See docs/plan-adherence.md (PR-C) for the full spec.
+ */
+
+import { escapeRegExp } from "../utils/escape-regexp.js";
+
+const WEIGHTS = {
+  commit_attribution: 40,
+  acceptance_tests: 30,
+  scope_discipline: 20,
+  dependency_order: 10,
+};
+
+/**
+ * Build a regex that matches the HU id anywhere in a commit message
+ * (case-insensitive, word-boundary friendly). The `_` and `-` characters
+ * appear inside HU ids so we anchor on whole-token rather than \b.
+ */
+function huIdMatcher(huId) {
+  const escaped = escapeRegExp(huId);
+  return new RegExp(`(^|[^a-z0-9])${escaped}([^a-z0-9]|$)`, "i");
+}
+
+/**
+ * Slugify an HU title for branch-name / scope matching. Mirrors the
+ * `buildHuBranchName` slug rule (lowercase, non-alnum → "-").
+ */
+function slugify(text) {
+  return String(text || "")
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]+/g, "-")
+    .replaceAll(/(^-+)|(-+$)/g, "");
+}
+
+/**
+ * Try to attribute a single commit to one of the plan's HUs.
+ *
+ * Order of evidence, strongest first:
+ *   1. The HU id appears in the commit message.
+ *   2. The HU id appears in the branch name where the commit lives
+ *      (commit.branch is supplied by listCommitsBetween's caller when
+ *      it knows the per-HU branches).
+ *   3. The HU title slug matches the commit message.
+ *
+ * Returns the matched huId, or null when none of the above fires.
+ */
+export function attributeCommitToHu(commit, hus) {
+  if (!commit || !Array.isArray(hus) || hus.length === 0) return null;
+  const msg = String(commit.message || "");
+  const branch = String(commit.branch || "");
+  for (const hu of hus) {
+    if (!hu?.id) continue;
+    const matcher = huIdMatcher(hu.id);
+    if (matcher.test(msg)) return hu.id;
+    if (branch && matcher.test(branch)) return hu.id;
+  }
+  // Fallback: title slug
+  for (const hu of hus) {
+    const slug = slugify(hu.title);
+    if (!slug || slug.length < 6) continue;
+    if (slugify(msg).includes(slug)) return hu.id;
+  }
+  return null;
+}
+
+/**
+ * Component 1: commit attribution. Returns null when the run produced
+ * no commits at all (avoids penalising analysis-only or doc-only runs).
+ */
+export function computeCommitAttribution(commits, plan) {
+  if (!Array.isArray(commits) || commits.length === 0) return null;
+  if (!plan?.hus || plan.hus.length === 0) return null;
+  let attributed = 0;
+  for (const commit of commits) {
+    if (attributeCommitToHu(commit, plan.hus)) attributed += 1;
+  }
+  return Math.round((attributed / commits.length) * 100);
+}
+
+/**
+ * Component 2: acceptance test coverage. Heuristic: each HU declares
+ * `acceptance_tests`. We check whether at least one commit from that
+ * HU's pool has a `test:`-prefixed message. Per-HU score (1 or 0),
+ * averaged across HUs that DO declare tests. Returns null when no HU
+ * declares acceptance tests.
+ */
+export function computeAcceptanceTestCoverage(commits, plan) {
+  if (!plan?.hus || plan.hus.length === 0) return null;
+  if (!Array.isArray(commits) || commits.length === 0) return null;
+  const husWithTests = plan.hus.filter(
+    (hu) => Array.isArray(hu?.acceptance_tests) && hu.acceptance_tests.length > 0,
+  );
+  if (husWithTests.length === 0) return null;
+
+  let covered = 0;
+  for (const hu of husWithTests) {
+    const huCommits = (commits || []).filter(
+      (c) => attributeCommitToHu(c, [hu]) === hu.id,
+    );
+    const hasTestCommit = huCommits.some((c) =>
+      /^test[:(]/i.test(String(c.message || "").trim()),
+    );
+    if (hasTestCommit) covered += 1;
+  }
+  return Math.round((covered / husWithTests.length) * 100);
+}
+
+/**
+ * Component 3: scope discipline. For each file changed by the run, we
+ * try to match it against at least one HU's id slug, title slug, or
+ * `scope` text. A file that matches no HU is flagged as out-of-scope.
+ * Returns null when the run changed no files.
+ */
+export function computeScopeDiscipline(filesChanged, plan) {
+  if (!Array.isArray(filesChanged) || filesChanged.length === 0) return null;
+  if (!plan?.hus || plan.hus.length === 0) return null;
+  const huKeywords = plan.hus.map((hu) => ({
+    id: hu.id,
+    matchers: [
+      slugify(hu.id),
+      slugify(hu.title),
+      // Pull alpha-rich words from `scope` text (length >= 4).
+      ...String(hu.scope || "")
+        .toLowerCase()
+        .split(/[^a-z]+/)
+        .filter((w) => w.length >= 4),
+    ].filter(Boolean),
+  }));
+  let inScope = 0;
+  for (const file of filesChanged) {
+    const slug = slugify(file);
+    const matched = huKeywords.some((hk) =>
+      hk.matchers.some((m) => slug.includes(m) || file.includes(m)),
+    );
+    if (matched) inScope += 1;
+  }
+  return Math.round((inScope / filesChanged.length) * 100);
+}
+
+/**
+ * Component 4: dependency order. For every `(parent, child)` edge
+ * declared via `child.blocked_by`, check that the EARLIEST commit
+ * attributed to `parent` is older than the EARLIEST commit attributed
+ * to `child`. Returns null when no dependency edges exist.
+ *
+ * `commits` are expected oldest-first (the shape `listCommitsBetween`
+ * returns). When that's not the case the score still makes sense — we
+ * just compare relative positions in the array.
+ */
+export function computeDependencyOrder(commits, plan) {
+  if (!plan?.hus || plan.hus.length === 0) return null;
+  const edges = [];
+  for (const hu of plan.hus) {
+    for (const parentId of hu.blocked_by || []) {
+      edges.push([parentId, hu.id]);
+    }
+  }
+  if (edges.length === 0) return null;
+  if (!Array.isArray(commits) || commits.length === 0) return null;
+
+  // Build huId → first commit index (oldest first attribution).
+  const firstIndex = new Map();
+  commits.forEach((commit, idx) => {
+    const huId = attributeCommitToHu(commit, plan.hus);
+    if (huId && !firstIndex.has(huId)) firstIndex.set(huId, idx);
+  });
+
+  let respected = 0;
+  let evaluable = 0;
+  for (const [parentId, childId] of edges) {
+    const p = firstIndex.get(parentId);
+    const c = firstIndex.get(childId);
+    if (p === undefined || c === undefined) continue; // can't evaluate
+    evaluable += 1;
+    if (p < c) respected += 1;
+  }
+  if (evaluable === 0) return null;
+  return Math.round((respected / evaluable) * 100);
+}
+
+/**
+ * Aggregator: compute every component and weight them. Components
+ * that return `null` are excluded and their weight redistributed
+ * proportionally across the rest, so a run that legitimately has no
+ * acceptance tests or no dependencies isn't penalised.
+ *
+ * Returns the full structured result (see file header for shape).
+ */
+export function computePlanAdherenceScore({ commits, plan, filesChanged }) {
+  const breakdown = {
+    commit_attribution: computeCommitAttribution(commits, plan),
+    acceptance_tests: computeAcceptanceTestCoverage(commits, plan),
+    scope_discipline: computeScopeDiscipline(filesChanged, plan),
+    dependency_order: computeDependencyOrder(commits, plan),
+  };
+
+  // Weighted average over non-null components only.
+  let totalWeight = 0;
+  let weightedSum = 0;
+  for (const [key, weight] of Object.entries(WEIGHTS)) {
+    const value = breakdown[key];
+    if (value === null || value === undefined) continue;
+    totalWeight += weight;
+    weightedSum += value * weight;
+  }
+  const score = totalWeight === 0 ? null : Math.round(weightedSum / totalWeight);
+
+  // Per-HU detail: was the HU "touched" (attributed at least one commit)?
+  const hu_scores = (plan?.hus || []).map((hu) => {
+    const huCommits = (commits || []).filter(
+      (c) => attributeCommitToHu(c, [hu]) === hu.id,
+    );
+    const issues = [];
+    if (huCommits.length === 0) issues.push("no commit attributed");
+    return { huId: hu.id, attributed: huCommits.length > 0, issues };
+  });
+
+  return { score, breakdown, hu_scores };
+}