@clear-capabilities/agentic-security-scanner 0.86.0 → 0.119.1

package/src/ir/tree-sitter-loader.js

@@ -0,0 +1,108 @@
+// Tree-sitter parser loader (roadmap #8) — OPTIONAL, runtime-lazy, degrades.
+//
+// web-tree-sitter + tree-sitter-wasms are OPTIONAL dependencies (pinned to an
+// ABI-matched pair: web-tree-sitter 0.20.8 ↔ tree-sitter-wasms 0.1.13). They
+// are NOT bundled into dist (the build marks them `--external`), so the
+// committed bundle stays self-contained and small; this loader requires them
+// lazily at runtime and returns null when they're absent. That keeps the
+// scanner fully bootable offline / without the optional deps — long-tail
+// languages simply fall back to the existing pattern detectors.
+//
+// Long-tail languages this unlocks (no first-class IR parser today):
+// rust, solidity, cpp, c, go, swift, dart. (js/ts/py/java/etc. already have
+// dedicated IR parsers and don't need this.)
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+// language → prebuilt grammar wasm shipped by tree-sitter-wasms.
+const GRAMMAR_WASM = {
+  rust: 'tree-sitter-rust.wasm',
+  solidity: 'tree-sitter-solidity.wasm',
+  cpp: 'tree-sitter-cpp.wasm',
+  c: 'tree-sitter-c.wasm',
+  go: 'tree-sitter-go.wasm',
+  swift: 'tree-sitter-swift.wasm',
+  dart: 'tree-sitter-dart.wasm',
+};
+
+const EXT_TO_LANG = {
+  rs: 'rust', sol: 'solidity', cpp: 'cpp', cc: 'cpp', cxx: 'cpp', hpp: 'cpp',
+  c: 'c', h: 'c', go: 'go', swift: 'swift', dart: 'dart',
+};
+
+export function treeSitterLangOf(file) {
+  if (typeof file !== 'string') return null;
+  const ext = file.split('.').pop().toLowerCase();
+  return EXT_TO_LANG[ext] || null;
+}
+
+let _Parser; // undefined = not tried, null = unavailable, fn = the class
+let _initPromise = null;
+const _langCache = new Map(); // language → Language | null
+const _parserCache = new Map(); // language → Parser | null
+
+async function _ensureRuntime() {
+  if (_Parser === null) return null;
+  if (_Parser) return _Parser;
+  try {
+    // 0.20 API: the module's default export IS the Parser class.
+    const mod = require('web-tree-sitter');
+    _Parser = mod && (mod.Parser || mod.default || mod);
+    if (!_initPromise) _initPromise = _Parser.init();
+    await _initPromise;
+    return _Parser;
+  } catch {
+    _Parser = null; // optional dep absent or failed to init → degrade.
+    return null;
+  }
+}
+
+function _grammarPath(language) {
+  const file = GRAMMAR_WASM[language];
+  if (!file) return null;
+  try { return require.resolve('tree-sitter-wasms/out/' + file); } catch { return null; }
+}
+
+// Returns a ready-to-use Parser for `language`, or null if tree-sitter or the
+// grammar isn't available. Cached per language. `parser.parse(src)` is then
+// synchronous, so callers can parse inside a sync loop after awaiting this.
+export async function getParserFor(language) {
+  if (_parserCache.has(language)) return _parserCache.get(language);
+  const Parser = await _ensureRuntime();
+  if (!Parser) { _parserCache.set(language, null); return null; }
+  try {
+    let Lang = _langCache.get(language);
+    if (Lang === undefined) {
+      const wasm = _grammarPath(language);
+      Lang = wasm ? await Parser.Language.load(wasm) : null;
+      _langCache.set(language, Lang);
+    }
+    if (!Lang) { _parserCache.set(language, null); return null; }
+    const p = new Parser();
+    p.setLanguage(Lang);
+    _parserCache.set(language, p);
+    return p;
+  } catch {
+    _parserCache.set(language, null);
+    return null;
+  }
+}
+
+export async function isTreeSitterAvailable() {
+  return (await _ensureRuntime()) != null;
+}
+
+// Walk every named node, invoking cb(node). Iterative to avoid deep recursion.
+export function walkNamed(root, cb) {
+  if (!root) return;
+  const stack = [root];
+  while (stack.length) {
+    const n = stack.pop();
+    cb(n);
+    for (let i = n.namedChildCount - 1; i >= 0; i--) stack.push(n.namedChild(i));
+  }
+}
+
+export const _internals = { GRAMMAR_WASM, EXT_TO_LANG, _grammarPath };

package/src/mcp/tools.js

@@ -16,7 +16,7 @@ import * as fs from 'node:fs';
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
-import { applyFix as applyFixHistory } from '../posture/fix-history.js';
+import { applyFix as applyFixHistory, fixAcceptanceRate } from '../posture/fix-history.js';
 import { verifyLastScan } from '../posture/integrity.js';
 import { redactString, redactFinding } from './redact.js';
 
@@ -578,7 +578,11 @@ export const apply_fix = {
       }
       throw e;
     }
-    return { _meta: META, applied: true, historyId: entry.id, file: f.file, backupPath: entry.backupPath, integrity: status, attemptOrdinal: entry.attemptOrdinal };
+    // R25 (PRD §5): surface the running auto-fix acceptance rate after each
+    // applied fix, so the closed loop reports its own success metric.
+    let acceptance = null;
+    try { acceptance = fixAcceptanceRate(ctx.sessionRoot); } catch { /* metric is best-effort */ }
+    return { _meta: META, applied: true, historyId: entry.id, file: f.file, backupPath: entry.backupPath, integrity: status, attemptOrdinal: entry.attemptOrdinal, acceptance };
   },
 };
 

package/src/posture/corpus-status.js

@@ -0,0 +1,74 @@
+// Corpus coverage / gap reporter (roadmap #10).
+//
+// "Scale the ground-truth corpus" is a data-acquisition effort, not a code one
+// — but you can't prioritize what you can't see. This turns the CVE-replay
+// corpus into an actionable coverage map: progress toward the target size, and
+// exactly which CWE×language cells have zero ground-truth entries. It measures
+// the existing corpus only; it never invents entries.
+
+// The corpus's declared target families/languages (mirrors bench manifest).
+export const TARGET_CWES = [
+  'CWE-22', 'CWE-78', 'CWE-79', 'CWE-89', 'CWE-90', 'CWE-94', 'CWE-113',
+  'CWE-327', 'CWE-329', 'CWE-338', 'CWE-352', 'CWE-502', 'CWE-601', 'CWE-611',
+  'CWE-643', 'CWE-798', 'CWE-916', 'CWE-918', 'CWE-1321', 'CWE-1333',
+];
+export const TARGET_LANGUAGES = [
+  'javascript', 'python', 'java', 'go', 'ruby', 'php', 'csharp', 'kotlin',
+];
+
+// Pure analyzer. `entries` = [{ cwe, language, family, cve, tier? }, …].
+export function analyzeCorpus(entries, opts = {}) {
+  const target = opts.target || 500;
+  const cwes = opts.cweFamilies || TARGET_CWES;
+  const langs = opts.languages || TARGET_LANGUAGES;
+  const list = Array.isArray(entries) ? entries : [];
+
+  const byLanguage = {}, byCwe = {}, matrix = {};
+  for (const e of list) {
+    const lang = (e && e.language) || 'unknown';
+    const cwe = (e && e.cwe) || 'unknown';
+    byLanguage[lang] = (byLanguage[lang] || 0) + 1;
+    byCwe[cwe] = (byCwe[cwe] || 0) + 1;
+    (matrix[cwe] || (matrix[cwe] = {}))[lang] = (matrix[cwe][lang] || 0) + 1;
+  }
+
+  // Empty cells in the target CWE×language matrix = prioritized gaps.
+  const gaps = [];
+  for (const cwe of cwes) {
+    for (const lang of langs) {
+      if (!(matrix[cwe] && matrix[cwe][lang])) gaps.push({ cwe, language: lang });
+    }
+  }
+  const cellsTotal = cwes.length * langs.length;
+  return {
+    total: list.length,
+    target,
+    progressPct: Math.round((list.length / target) * 100),
+    remainingToTarget: Math.max(0, target - list.length),
+    byLanguage,
+    byCwe,
+    matrix,
+    cellsTotal,
+    cellsCovered: cellsTotal - gaps.length,
+    gapCount: gaps.length,
+    gaps,
+  };
+}
+
+export function summarizeCorpusStatus(r) {
+  if (!r) return 'corpus: (no data)';
+  const lines = [
+    `corpus: ${r.total}/${r.target} entries (${r.progressPct}%, ${r.remainingToTarget} to target)`,
+    `matrix: ${r.cellsCovered}/${r.cellsTotal} CWE×language cells covered (${r.gapCount} gaps)`,
+  ];
+  // Top under-covered languages (fewest entries among target languages).
+  const langCounts = Object.entries(r.byLanguage).sort((a, b) => a[1] - b[1]);
+  if (langCounts.length) {
+    lines.push('thinnest languages: ' + langCounts.slice(0, 3).map(([l, n]) => `${l}=${n}`).join(', '));
+  }
+  // A few example gaps to act on first.
+  if (r.gaps.length) {
+    lines.push('example gaps: ' + r.gaps.slice(0, 6).map(g => `${g.cwe}/${g.language}`).join(', '));
+  }
+  return lines.join('\n');
+}

package/src/posture/coverage-report.js

@@ -0,0 +1,113 @@
+// Analysis-coverage honesty report (roadmap #5 + #6).
+//
+// A "perfect" SAST scanner must publish its blind spots, not hide them. This
+// module turns three things the engine already knows internally into an
+// explicit, user-facing coverage summary:
+//
+//   1. Per-language ANALYSIS TIER — which languages in this scan got the full
+//      IR + taint engine vs. only pattern (regex) detectors. The taint engine
+//      is wired for js/ts/py/java/cs/kt/go/php/rb; everything else
+//      (c/c++/rust/swift/solidity/dart/…) is pattern-only today.
+//   2. Files SKIPPED and why (too large, too dense, timed out).
+//   3. UNMODELED-SINK candidates (#5) — calls that match a dangerous shape but
+//      have NO finding at their line, i.e. likely recall blind spots to verify.
+//
+// All of this is informational; it never changes a finding's severity.
+
+// Languages that flow through the Layer-1 IR + Layer-2 taint engine.
+export const IR_TAINT_LANGS = new Set(['js', 'ts', 'py', 'java', 'cs', 'kt', 'go', 'php', 'rb']);
+
+const EXT_TO_LANG = {
+  js: 'js', jsx: 'js', mjs: 'js', cjs: 'js', ts: 'ts', tsx: 'ts',
+  py: 'py', pyw: 'py', java: 'java', go: 'go', rb: 'rb', php: 'php',
+  cs: 'cs', kt: 'kt', kts: 'kt', swift: 'swift', rs: 'rs',
+  c: 'c', h: 'c', cpp: 'cpp', cc: 'cpp', cxx: 'cpp', hpp: 'cpp',
+  sol: 'sol', dart: 'dart', scala: 'scala', m: 'objc',
+};
+
+export function langOfFile(file) {
+  if (typeof file !== 'string') return null;
+  const ext = file.split('.').pop().toLowerCase();
+  return EXT_TO_LANG[ext] || null;
+}
+
+// Given the list of scanned files, report which languages got IR-taint vs.
+// pattern-only analysis, with a per-language file count.
+export function computeAnalysisTiers(fileList) {
+  const counts = {};
+  for (const f of fileList || []) {
+    const l = langOfFile(f);
+    if (!l) continue;
+    counts[l] = (counts[l] || 0) + 1;
+  }
+  const irTaint = {}, patternOnly = {};
+  for (const [lang, n] of Object.entries(counts)) {
+    (IR_TAINT_LANGS.has(lang) ? irTaint : patternOnly)[lang] = n;
+  }
+  return {
+    irTaint,        // { js: 12, py: 4 }
+    patternOnly,    // { rs: 3, sol: 1 }  → flow analysis NOT applied
+    languages: Object.keys(counts).sort(),
+  };
+}
+
+// Dangerous-call shapes worth surfacing when no finding lands on their line.
+// Deliberately conservative + cross-language; this is a "did we miss a sink?"
+// prompt for the user, emitted at info level only.
+const DANGER_TOKENS = [
+  [/\beval\s*\(/, 'eval'],
+  [/\bnew\s+Function\s*\(/, 'Function-constructor'],
+  [/\bvm\.\s*runIn\w+\s*\(/, 'vm.runIn*'],
+  [/\bchild_process\b|\bexecSync?\s*\(|\bspawnSync?\s*\(/, 'child_process'],
+  [/\bdeserialize\s*\(|readObject\s*\(|ObjectInputStream\b/, 'deserialize'],
+  [/\byaml\.\s*load\s*\(|\bsafe_load\b/, 'yaml.load'],
+  [/\bpickle\.\s*loads?\s*\(/, 'pickle.load'],
+  [/\bMarshal\.\s*load\b|\bunserialize\s*\(/, 'unserialize'],
+  [/\bRuntime\b[\s\S]{0,40}\.exec\s*\(|\bProcessBuilder\b/, 'Runtime.exec/ProcessBuilder'],
+  [/\bos\.\s*system\s*\(|\bsubprocess\.\s*(?:call|run|Popen)\s*\(/, 'os.system/subprocess'],
+  [/\.innerHTML\s*=|\bdangerouslySetInnerHTML\b/, 'innerHTML'],
+];
+
+// Scan file contents for danger tokens that have NO finding on their line.
+// findings: array with {file,line}. fc: { path: content }. Returns a capped
+// example list + total count. Lines are 1-based to match finding lines.
+export function countUnmodeledSinkCandidates(fc, findings, opts = {}) {
+  const cap = opts.cap || 12;
+  const covered = new Set();
+  for (const f of findings || []) {
+    if (f && f.file && typeof f.line === 'number') covered.add(`${f.file}:${f.line}`);
+  }
+  const examples = [];
+  let count = 0;
+  for (const [file, content] of Object.entries(fc || {})) {
+    if (typeof content !== 'string') continue;
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      for (const [re, token] of DANGER_TOKENS) {
+        if (!re.test(lines[i])) continue;
+        if (covered.has(`${file}:${i + 1}`)) continue; // already flagged → modelled
+        count++;
+        if (examples.length < cap) examples.push({ file, line: i + 1, token });
+        break; // one token per line is enough
+      }
+    }
+  }
+  return { count, examples };
+}
+
+// One-line CLI summary of an analysis-coverage object.
+export function summarizeCoverage(meta) {
+  if (!meta) return 'coverage: (none)';
+  const t = meta.analysisTier || {};
+  const irLangs = Object.keys(t.irTaint || {});
+  const patLangs = Object.keys(t.patternOnly || {});
+  const parts = [
+    `scanned=${meta.filesScanned ?? '?'}`,
+    `skipped=${(meta.filesSkipped || 0) + (meta.filesDenseSkipped || 0)}`,
+    `timedOut=${meta.filesTimedOut || 0}`,
+    `ir-taint=[${irLangs.join(',')}]`,
+  ];
+  if (patLangs.length) parts.push(`pattern-only=[${patLangs.join(',')}]`);
+  if (meta.unmodeledSinkCandidates?.count) parts.push(`unmodeled-sink-candidates=${meta.unmodeledSinkCandidates.count}`);
+  return parts.join(' · ');
+}

package/src/posture/fix-history.js

@@ -31,6 +31,30 @@ export function readLog(scanRoot) {
   if (!fs.existsSync(fp)) return [];
   try { return JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { return []; }
 }
+// R25 (PRD §5): auto-fix acceptance rate. The closed loop (apply → verify →
+// re-scan for SAST; dry-run + test-gate + rollback for SCA upgrades) already
+// exists; this surfaces the OUTCOME metric the PRD asks to track — the fraction
+// of RESOLVED fix attempts that landed and stuck. Pure aggregation over the
+// fix-history log; still-'pending' entries are excluded from the denominator.
+export function acceptanceFromEntries(entries) {
+  const counts = { applied: 0, pending: 0, reverted: 0, failed: 0, other: 0 };
+  for (const e of (Array.isArray(entries) ? entries : [])) {
+    const s = (e && e.status) || 'other';
+    if (counts[s] != null) counts[s]++; else counts.other++;
+  }
+  const accepted = counts.applied;
+  const resolved = counts.applied + counts.reverted + counts.failed;
+  return {
+    acceptanceRate: resolved > 0 ? Number((accepted / resolved).toFixed(4)) : null,
+    accepted, resolved, pending: counts.pending,
+    total: Array.isArray(entries) ? entries.length : 0, counts,
+  };
+}
+
+export function fixAcceptanceRate(scanRoot) {
+  return acceptanceFromEntries(readLog(scanRoot));
+}
+
 function writeLog(scanRoot, log) {
   ensure(scanRoot);
   fs.writeFileSync(logPath(scanRoot), JSON.stringify(log, null, 2));

package/src/posture/holdout-eval.js

@@ -23,6 +23,25 @@ import { brierScore, computeBrierOnHeldOut, wilsonInterval } from './calibration
 
 const ECE_BINS_DEFAULT = 10;
 
+// Map a labeled sample to a source language. Prefer an explicit `language`
+// field; otherwise derive it from the `file` extension. Keeps per-language
+// metrics meaningful even for older corpora that only carry a file path.
+const EXT_TO_LANG = {
+  js: 'js', jsx: 'js', mjs: 'js', cjs: 'js', ts: 'ts', tsx: 'ts',
+  py: 'py', java: 'java', go: 'go', rb: 'rb', php: 'php',
+  cs: 'cs', kt: 'kt', kts: 'kt', swift: 'swift', rs: 'rs',
+  c: 'c', h: 'c', cpp: 'cpp', cc: 'cpp', cxx: 'cpp', hpp: 'cpp',
+  sol: 'sol', dart: 'dart',
+};
+export function languageOf(o) {
+  if (o && typeof o.language === 'string' && o.language) return o.language;
+  if (o && typeof o.file === 'string') {
+    const ext = o.file.split('.').pop().toLowerCase();
+    if (EXT_TO_LANG[ext]) return EXT_TO_LANG[ext];
+  }
+  return 'unknown';
+}
+
 export function parseLabeledJsonl(text) {
   if (typeof text !== 'string' || !text.length) return [];
   const out = [];
@@ -39,6 +58,7 @@ export function parseLabeledJsonl(text) {
       if (p === null || a === null) continue;
       out.push({
         family: typeof o.family === 'string' ? o.family : 'unknown',
+        language: languageOf(o),
         stableId: typeof o.stableId === 'string' ? o.stableId : null,
         predicted: Math.max(0, Math.min(1, p)),
         actual: a,
@@ -98,6 +118,27 @@ export function perFamily(samples) {
   return fams;
 }
 
+// Per-language precision/recall breakdown (roadmap #9). The "perfect
+// multi-language SAST" claim is only defensible with per-language ground
+// truth — a corpus that's 90% JS can hide poor Ruby precision behind a
+// healthy aggregate. Mirrors perFamily, keyed by sample.language, and adds
+// a per-language precision so a regression in one language is visible.
+export function perLanguage(samples) {
+  const langs = {};
+  for (const s of samples) {
+    const l = s.language || 'unknown';
+    if (!langs[l]) langs[l] = { tp: 0, fp: 0, n: 0, precision: 0 };
+    langs[l].n++;
+    if (s.actual === 1) langs[l].tp++;
+    else if (s.actual === 0) langs[l].fp++;
+  }
+  for (const l of Object.keys(langs)) {
+    const { tp, fp } = langs[l];
+    langs[l].precision = (tp + fp) > 0 ? Number((tp / (tp + fp)).toFixed(4)) : 0;
+  }
+  return langs;
+}
+
 // One-shot evaluation: Brier + ECE + per-family TP/FP + overall precision.
 // Returns null only when there's truly no data; never returns a tautological
 // zero.
@@ -124,14 +165,30 @@ export function evaluateHeldOut(samples) {
     precision,
     precisionCi95: ci,
     perFamily: fams,
+    perLanguage: perLanguage(samples),
     notes: [
       ...(samples.length < 100 ? ['n<100: Brier and ECE have wide confidence; treat as directional, not decision-grade.'] : []),
       ...(brierR.brier !== null && brierR.brier > 0.10 ? [`brier=${brierR.brier.toFixed(3)} exceeds PRD target 0.10`] : []),
       ...(ece && ece.ece > 0.05 ? [`ece=${ece.ece.toFixed(3)} exceeds 0.05 calibration target`] : []),
+      // Per-language regression surfacing: a language with enough samples
+      // whose precision trails the aggregate by >0.15 is the failure the
+      // aggregate would otherwise mask.
+      ...Object.entries(perLanguage(samples))
+        .filter(([, m]) => m.n >= 20 && precision - m.precision > 0.15)
+        .map(([lang, m]) => `language '${lang}' precision=${m.precision.toFixed(3)} (n=${m.n}) trails aggregate ${precision.toFixed(3)}`),
     ],
   };
 }
 
+// Per-language dashboard line: one row per language, sorted by sample count.
+export function summarizePerLanguage(result) {
+  if (!result || !result.ok || !result.perLanguage) return 'per-language: no data';
+  return Object.entries(result.perLanguage)
+    .sort((a, b) => b[1].n - a[1].n)
+    .map(([lang, m]) => `${lang}: precision=${m.precision.toFixed(3)} (tp=${m.tp} fp=${m.fp} n=${m.n})`)
+    .join('\n');
+}
+
 // CLI-friendly summary line.
 export function summarize(result) {
   if (!result || !result.ok) return `held-out: ${result?.reason || 'unknown error'}`;

package/src/posture/provenance.js

@@ -0,0 +1,39 @@
+// R17 (PRD §5) — finding provenance: "one issue, many signals".
+//
+// dedupeFindingsWithEvidence() already collapses findings that share a
+// (file, sink-line, family) into ONE finding and accumulates the parsers that
+// fired into `evidence`. This annotator turns that into an explicit, queryable
+// corroboration signal on EVERY finding (not just merged ones):
+//
+//   finding.corroborationCount : number of DISTINCT independent analyses that
+//                                flagged this exact issue (≥1).
+//   finding.corroboration.by   : sorted list of those signal sources.
+//   finding.multiSignal        : true when ≥2 independent sources agree.
+//
+// Independent confirmation lowers the odds of a false positive, so the engine
+// ranks multi-signal findings above single-signal ones at equal severity. It
+// deliberately does NOT touch the calibrated `confidence` field — calibration
+// is fit/measured held-out (see posture/CLAUDE.md) and must not be perturbed by
+// a ranking heuristic.
+
+export function annotateFindingProvenance(findings) {
+  if (!Array.isArray(findings)) return findings;
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue;
+    const sources = new Set();
+    if (f.parser) sources.add(f.parser);
+    // Parsers merged in by the dedup pass.
+    if (Array.isArray(f.evidence)) for (const e of f.evidence) if (e) sources.add(e);
+    // The Layer-3 LLM validator accepting a finding is an independent signal.
+    if (f.validator_verdict === 'accept') sources.add('llm-validator');
+    // A dynamically-confirmed finding (reserved for the DAST loop) is the
+    // strongest independent signal.
+    if (f.dynamicallyConfirmed === true) sources.add('dynamic');
+    if (sources.size === 0) sources.add(f.parser || 'UNKNOWN');
+    const by = [...sources].sort();
+    f.corroboration = { count: by.length, by };
+    f.corroborationCount = by.length;
+    if (by.length >= 2) f.multiSignal = true;
+  }
+  return findings;
+}

package/src/posture/router.js

@@ -27,7 +27,34 @@ function ageHours(fp) {
   return (Date.now() - fs.statSync(fp).mtimeMs) / 3_600_000;
 }
 
-export function decide({ scanRoot, intent }) {
+// Compare the two most-recent scan-history entries to tell the user whether
+// they're trending safer or more exposed. Returns {} when there isn't enough
+// history to say anything honest. (premortem: never invent a trend from one
+// data point.)
+export function computeScanTrend(scanRoot) {
+  const hist = readJson(path.join(scanRoot, '.agentic-security', 'scan-history.json'));
+  if (!Array.isArray(hist) || hist.length < 2) return {};
+  const cur = hist[hist.length - 1];
+  const prev = hist[hist.length - 2];
+  const sevOf = (e) => (e?.critical || 0) + (e?.high || 0);
+  const delta = sevOf(cur) - sevOf(prev);
+  let trend = 'flat';
+  if (delta < 0) trend = 'improving';
+  else if (delta > 0) trend = 'regressing';
+  const n = Math.abs(delta);
+  const whatChanged =
+    trend === 'improving' ? `${n} fewer critical+high than last scan — keep going.`
+    : trend === 'regressing' ? `${n} more critical+high than last scan — new risk crept in.`
+    : 'No change in critical+high since last scan.';
+  return { trend, whatChanged };
+}
+
+export function decide(opts) {
+  const base = baseDecision(opts);
+  return { ...base, ...computeScanTrend(opts.scanRoot) };
+}
+
+function baseDecision({ scanRoot, intent }) {
   const stateDir = path.join(scanRoot, '.agentic-security');
   const lastScan = readJson(path.join(stateDir, 'last-scan.json'));
   const scanAge = ageHours(path.join(stateDir, 'last-scan.json'));
@@ -102,8 +129,11 @@ export function explain(decision) {
     ``,
     `  Action:  ${decision.action}`,
     `  Why:     ${decision.reason}`,
-    `  Run:     ${decision.command}`,
-    ``,
   ];
+  if (decision.trend) {
+    const arrow = decision.trend === 'improving' ? '↓' : decision.trend === 'regressing' ? '↑' : '→';
+    lines.push(`  Trend:   ${arrow} ${decision.whatChanged}`);
+  }
+  lines.push(`  Run:     ${decision.command}`, ``);
   return lines.join('\n');
 }

package/src/posture/sca-verdict.js

@@ -0,0 +1,130 @@
+// R12 (PRD §5) — deterministic SCA decision-first verdict.
+//
+// Turns the enrichment signals already on each `vulnerable_dep` finding
+// (compositeRiskTier, kev, epss, reachabilityTier, mitigationVerdict,
+// fixedVersions, policy suppression/freeze) into ONE verdict from a closed enum,
+// so the default SCA output is a decision ("fix these 5, auto-merge these 40,
+// ignore these 255 — here's why") rather than a CVE dump.
+//
+// This codifies the ordered procedure documented for the `sca-triager` agent so
+// it runs without an LLM. The agent remains for nuanced/uncertain cases; this
+// gives every dep a defensible default verdict deterministically.
+//
+// Verdict enum (must match the agent + downstream /fix --sca):
+//   AUTO_MERGE_PATCH · WAIT_FOR_PATCH · MANUAL_REVIEW · ACCEPT_RISK · WONT_FIX
+
+export const SCA_VERDICTS = ['AUTO_MERGE_PATCH', 'WAIT_FOR_PATCH', 'MANUAL_REVIEW', 'ACCEPT_RISK', 'WONT_FIX'];
+
+const REACHABLE_TIERS = new Set(['route-reachable-via-function', 'function-reachable', 'import-reachable']);
+const UNREACHABLE_TIERS = new Set(['unreachable', 'build-only', 'manifest-only', 'transitive-only']);
+
+// Parse a version into {major,minor,patch}. Tolerates leading 'v', ranges, and
+// pre-release/build suffixes. Returns null when no leading numeric core exists.
+export function parseVersion(v) {
+  if (v == null) return null;
+  const m = String(v).match(/(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+  if (!m) return null;
+  return { major: +m[1], minor: m[2] != null ? +m[2] : 0, patch: m[3] != null ? +m[3] : 0 };
+}
+
+// Classify the smallest bump from `current` to `fixed`: 'patch' | 'minor' |
+// 'major' | 'none' (fixed <= current) | 'unknown' (unparseable).
+export function bumpKind(current, fixed) {
+  const c = parseVersion(current);
+  const f = parseVersion(fixed);
+  if (!c || !f) return 'unknown';
+  if (f.major > c.major) return 'major';
+  if (f.major < c.major) return 'none';
+  if (f.minor > c.minor) return 'minor';
+  if (f.minor < c.minor) return 'none';
+  if (f.patch > c.patch) return 'patch';
+  return 'none';
+}
+
+function isReachable(sc) {
+  // Default to "reachable" when the tier is unknown — fail toward review, not
+  // toward auto-accept (never silently ACCEPT_RISK something we couldn't place).
+  if (sc.reachabilityTier == null) return true;
+  return REACHABLE_TIERS.has(sc.reachabilityTier);
+}
+
+/**
+ * Compute the verdict for one vulnerable_dep finding. Pure. Returns
+ * { verdict, reason, expiryDays? }. Follows the documented ordered procedure;
+ * the first matching rule wins.
+ */
+export function computeScaVerdict(sc, opts = {}) {
+  const testsDetected = !!opts.testsDetected;
+  const tier = sc.reachabilityTier;
+  const fixed = Array.isArray(sc.fixedVersions) ? sc.fixedVersions.filter(Boolean) : [];
+  const riskTier = sc.compositeRiskTier;
+  const bump = fixed.length ? bumpKind(sc.version, fixed[0]) : null;
+
+  // 1. Already suppressed by policy (accept-risk match) → pass-through.
+  if (sc.suppressed || sc.suppressionReason) {
+    return { verdict: 'ACCEPT_RISK', reason: sc.suppressionReason || 'matched existing accept-risk in sca-policy.yml' };
+  }
+  // 2. No fixed version exists → nothing to upgrade yet.
+  if (!fixed.length) {
+    return { verdict: 'WAIT_FOR_PATCH', reason: `no fixed version published${sc.osvId ? ` for ${sc.osvId}` : ''}` };
+  }
+  // 3. KEV-listed AND reachable → urgent. Same-major fix auto-merges; else review.
+  if ((sc.kev || sc.kevListed) && isReachable(sc)) {
+    if (bump === 'patch' || bump === 'minor') {
+      return { verdict: 'AUTO_MERGE_PATCH', reason: `KEV-listed and reachable; ${bump} bump to ${fixed[0]}` };
+    }
+    return { verdict: 'MANUAL_REVIEW', reason: 'KEV-listed but fix requires a major-version bump' };
+  }
+  // 4. Environment-mitigated in prod → accept with re-evaluation window.
+  if (sc.mitigationVerdict === 'mitigated-in-prod') {
+    return { verdict: 'ACCEPT_RISK', reason: 'mitigated in production (WAF / network policy / auth gate)', expiryDays: 90 };
+  }
+  // 5. Unreachable (in prod or by tier) → accept; low real exposure.
+  if (sc.mitigationVerdict === 'unreachable-in-prod' || (tier && UNREACHABLE_TIERS.has(tier))) {
+    return { verdict: 'ACCEPT_RISK', reason: `not reachable (${sc.mitigationVerdict || tier})`, expiryDays: 180 };
+  }
+  // 6. Major-version freeze policy → human decision.
+  if (sc.majorVersionFrozen) {
+    return { verdict: 'MANUAL_REVIEW', reason: 'package is on the major-version-freeze list' };
+  }
+  // 7. Fix requires a major bump → breaking-change review.
+  if (bump === 'major') {
+    return { verdict: 'MANUAL_REVIEW', reason: `fix requires a major-version bump (${sc.version} → ${fixed[0]}); review breaking changes` };
+  }
+  // 8. Patch-only bump at high/critical risk → safe auto-merge.
+  if (bump === 'patch' && (riskTier === 'high' || riskTier === 'critical')) {
+    return { verdict: 'AUTO_MERGE_PATCH', reason: `patch bump to ${fixed[0]} at ${riskTier} risk` };
+  }
+  // 9. EPSS says exploited-now + reachable + same-major → urgency overrides minor/patch distinction.
+  if ((sc.exploitedNow || (typeof sc.epssPercentile === 'number' && sc.epssPercentile >= 0.95)) && isReachable(sc) && (bump === 'patch' || bump === 'minor')) {
+    return { verdict: 'AUTO_MERGE_PATCH', reason: `high EPSS (exploited in the wild) and reachable; ${bump} bump to ${fixed[0]}` };
+  }
+  // 10. Minor bump at critical risk WITH tests present → auto-merge (tests catch breakage).
+  if (bump === 'minor' && riskTier === 'critical' && testsDetected) {
+    return { verdict: 'AUTO_MERGE_PATCH', reason: `minor bump to ${fixed[0]} at critical risk; project has tests` };
+  }
+  // 11. Anything else (minor bump at non-critical risk, 'none', unclear) → human.
+  return { verdict: 'MANUAL_REVIEW', reason: bump === 'none' ? 'no upgrade path resolves the advisory; review manually' : `${bump || 'unclear'} bump — defer to human triage` };
+}
+
+/**
+ * Annotate every vulnerable_dep in supplyChain with `scaVerdict` +
+ * `scaVerdictReason` (+ `scaVerdictExpiryDays` when applicable). Mutates and
+ * returns supplyChain. Returns a per-verdict count map on `supplyChain._scaVerdictCounts`.
+ */
+export function annotateScaVerdicts(supplyChain, opts = {}) {
+  if (!Array.isArray(supplyChain)) return supplyChain;
+  const counts = { AUTO_MERGE_PATCH: 0, WAIT_FOR_PATCH: 0, MANUAL_REVIEW: 0, ACCEPT_RISK: 0, WONT_FIX: 0 };
+  for (const sc of supplyChain) {
+    if (!sc || sc.type !== 'vulnerable_dep') continue;
+    const { verdict, reason, expiryDays } = computeScaVerdict(sc, opts);
+    sc.scaVerdict = verdict;
+    sc.scaVerdictReason = reason;
+    if (expiryDays) sc.scaVerdictExpiryDays = expiryDays;
+    if (counts[verdict] != null) counts[verdict]++;
+  }
+  try {
+    Object.defineProperty(supplyChain, '_scaVerdictCounts', { value: counts, enumerable: false, configurable: true });
+  } catch { /* frozen array — ignore */ }
+  return supplyChain;
+}