@clear-capabilities/agentic-security-scanner 0.74.0

package/src/posture/three-agent-pipeline.js

@@ -0,0 +1,74 @@
+// Three-agent adversarial review pipeline.
+//
+// Composes the existing single-step adversary-agent (red team) with the
+// defender-agent and auditor-agent into a single bounded cascade per
+// finding:
+//
+//     red.runAgent(finding, target)  →  attack transcript + outcome
+//     blue.runDefender(finding, red) →  hardening recommendations
+//     auditor.runAuditor(finding, red, blue) → final verdict
+//
+// Each phase is hash-chained; the final output is a structured envelope
+// the slash command can render. Without a configured LLM endpoint, every
+// phase short-circuits to its static-analysis equivalent — the cascade
+// still produces a useful artifact (static hardening + static verdict).
+
+import { runAgent as runRedTeam } from './adversary-agent.js';
+import { runDefender } from './defender-agent.js';
+import { runAuditor } from './auditor-agent.js';
+
+const DEFAULT_RED_BUDGET = { maxCalls: 30, maxWallMs: 8 * 60 * 1000 };
+
+export async function runThreeAgentReview(finding, opts = {}) {
+  const target = opts.target || '';
+  const startedAt = new Date().toISOString();
+
+  // Phase 1 — red team.
+  const red = await runRedTeam(finding, {
+    target,
+    maxCalls: opts.maxCalls ?? DEFAULT_RED_BUDGET.maxCalls,
+    maxWallMs: opts.maxWallMs ?? DEFAULT_RED_BUDGET.maxWallMs,
+    llmInvoke: opts.redLlmInvoke,
+    executeTool: opts.redExecuteTool,
+  });
+
+  // Phase 2 — blue team. Reads the red transcript.
+  const blue = await runDefender(finding, red.transcript, {
+    llmInvoke: opts.blueLlmInvoke,
+  });
+
+  // Phase 3 — auditor. Reads both prior transcripts.
+  const audit = await runAuditor(finding, red.transcript, blue, {
+    llmInvoke: opts.auditorLlmInvoke,
+  });
+
+  return {
+    startedAt,
+    finishedAt: new Date().toISOString(),
+    finding: {
+      stableId: finding?.stableId || null,
+      file: finding?.file || null,
+      line: finding?.line || null,
+      vuln: finding?.vuln || null,
+      family: finding?.family || null,
+      severity: finding?.severity || null,
+    },
+    red: {
+      outcome: red.outcome,
+      toolCallCount: (red.transcript?.entries || []).filter(e => e.tool).length,
+      transcriptHead: red.transcript?.chainHead || null,
+    },
+    blue: {
+      mode: blue.mode,
+      recommendations: blue.recommendations || [],
+      transcriptHead: blue.transcript?.chainHead || null,
+    },
+    auditor: {
+      verdict: audit.verdict,
+      rationale: audit.rationale,
+      mode: audit.mode,
+      transcriptHead: audit.transcript?.chainHead || null,
+    },
+    target,
+  };
+}

package/src/posture/triage.js

@@ -0,0 +1,146 @@
+// Pro-only triage layer (R6). JSON-backed store at .agentic-security/triage.json.
+// Tracks state, assignees, comments, and transitions per finding. Computes
+// MTTR and trend stats from the transition log.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const STORE_PATH = '.agentic-security/triage.json';
+
+export const STATES = ['open', 'in-progress', 'fixed', 'wont-fix', 'false-positive'];
+
+function _storePath(scanRoot) {
+  return path.join(scanRoot || process.cwd(), STORE_PATH);
+}
+
+export function loadTriage(scanRoot) {
+  const fp = _storePath(scanRoot);
+  if (!fs.existsSync(fp)) return { findings: {}, transitions: [] };
+  try { return JSON.parse(fs.readFileSync(fp, 'utf8')); }
+  catch (_) { return { findings: {}, transitions: [] }; }
+}
+
+function _save(scanRoot, data) {
+  const fp = _storePath(scanRoot);
+  fs.mkdirSync(path.dirname(fp), { recursive: true });
+  fs.writeFileSync(fp, JSON.stringify(data, null, 2));
+}
+
+// Sync the triage store with the latest scan: new findings become 'open',
+// findings no longer surfaced become 'fixed' (with a transition entry).
+export function syncWithScan(scanRoot, findings) {
+  const data = loadTriage(scanRoot);
+  const now = new Date().toISOString();
+  const seen = new Set();
+  for (const f of findings) {
+    const id = f.id || `${f.file}:${f.line}:${f.vuln}`;
+    seen.add(id);
+    if (!data.findings[id]) {
+      data.findings[id] = {
+        id,
+        file: f.file,
+        line: f.line,
+        vuln: f.vuln,
+        severity: f.severity,
+        state: 'open',
+        assignee: null,
+        opened_at: now,
+        comments: [],
+      };
+      data.transitions.push({ id, from: null, to: 'open', at: now });
+    }
+  }
+  // Auto-close findings that scanner no longer sees.
+  for (const id of Object.keys(data.findings)) {
+    const cur = data.findings[id];
+    if (seen.has(id)) continue;
+    if (cur.state === 'fixed' || cur.state === 'wont-fix' || cur.state === 'false-positive') continue;
+    cur.state = 'fixed';
+    cur.fixed_at = now;
+    data.transitions.push({ id, from: 'open', to: 'fixed', at: now, automatic: true });
+  }
+  _save(scanRoot, data);
+  return data;
+}
+
+export function assign(scanRoot, id, assignee) {
+  const data = loadTriage(scanRoot);
+  if (!data.findings[id]) return { ok: false, error: 'unknown finding id' };
+  data.findings[id].assignee = assignee;
+  data.findings[id].assigned_at = new Date().toISOString();
+  _save(scanRoot, data);
+  return { ok: true };
+}
+
+export function transition(scanRoot, id, toState, comment) {
+  const data = loadTriage(scanRoot);
+  if (!data.findings[id]) return { ok: false, error: 'unknown finding id' };
+  if (!STATES.includes(toState)) return { ok: false, error: `invalid state: ${toState}` };
+  const cur = data.findings[id];
+  const from = cur.state;
+  cur.state = toState;
+  if (toState === 'fixed') cur.fixed_at = new Date().toISOString();
+  data.transitions.push({ id, from, to: toState, at: new Date().toISOString(), comment });
+  _save(scanRoot, data);
+  return { ok: true };
+}
+
+export function comment(scanRoot, id, author, body) {
+  const data = loadTriage(scanRoot);
+  if (!data.findings[id]) return { ok: false, error: 'unknown finding id' };
+  data.findings[id].comments.push({ author, body, at: new Date().toISOString() });
+  _save(scanRoot, data);
+  return { ok: true };
+}
+
+export function list(scanRoot, filter = {}) {
+  const data = loadTriage(scanRoot);
+  let out = Object.values(data.findings);
+  if (filter.state) out = out.filter(f => f.state === filter.state);
+  if (filter.severity) out = out.filter(f => f.severity === filter.severity);
+  if (filter.assignee) out = out.filter(f => f.assignee === filter.assignee);
+  if (filter.unassigned) out = out.filter(f => !f.assignee);
+  return out;
+}
+
+// Trends across the last N days. Returns counts by severity, opened/closed
+// pairs, and median MTTR.
+export function trend(scanRoot, sinceDays = 30) {
+  const data = loadTriage(scanRoot);
+  const cutoff = Date.now() - sinceDays * 86400000;
+  const findings = Object.values(data.findings);
+  const recent = data.transitions.filter(t => new Date(t.at).getTime() >= cutoff);
+
+  const opened = recent.filter(t => t.to === 'open').length;
+  const closed = recent.filter(t => t.to === 'fixed').length;
+
+  const openBySev = { critical: 0, high: 0, medium: 0, low: 0 };
+  for (const f of findings) {
+    if (f.state === 'open' || f.state === 'in-progress') {
+      openBySev[f.severity] = (openBySev[f.severity] || 0) + 1;
+    }
+  }
+
+  // MTTR: for each finding fixed in window, (fixed_at - opened_at).
+  const mttrMs = [];
+  for (const f of findings) {
+    if (!f.fixed_at) continue;
+    if (new Date(f.fixed_at).getTime() < cutoff) continue;
+    const dur = new Date(f.fixed_at).getTime() - new Date(f.opened_at).getTime();
+    if (dur > 0) mttrMs.push(dur);
+  }
+  mttrMs.sort((a, b) => a - b);
+  const medianMttr = mttrMs.length
+    ? mttrMs[Math.floor(mttrMs.length / 2)] / 86400000
+    : null;
+
+  return {
+    sinceDays,
+    opened,
+    closed,
+    net: closed - opened,
+    openBySev,
+    medianMttrDays: medianMttr,
+    totalOpen: findings.filter(f => f.state === 'open' || f.state === 'in-progress').length,
+  };
+}

package/src/posture/trust-boundary-diagram.js

@@ -0,0 +1,115 @@
+// FR-UX-10 — Living trust-boundary diagram.
+//
+// Auto-generate a Mermaid diagram of the project's trust boundaries: HTTP
+// edges (with method+path), queue producers/consumers, gRPC servers, DB
+// edges, IaC-exposed resources. Findings on edges render as decorations.
+//
+// We emit Mermaid (text). The HTML report can render it natively;
+// PR-comment bot can render the source.
+//
+// Output:
+//   {
+//     mermaid: string,     // the Mermaid source
+//     nodes:   [...],      // {id, kind, label}
+//     edges:   [...],      // {from, to, kind, label?}
+//     decorations: [...],  // {nodeId, severity, vuln}
+//   }
+
+import { buildAssetInventory, buildTrustBoundaries } from './threat-model.js';
+
+function sanitizeId(s) {
+  return String(s).replace(/[^A-Za-z0-9_]/g, '_').slice(0, 40);
+}
+
+function nodeFor(b) {
+  if (b.type === 'http-route' || b.type === 'http-route-py' || b.type === 'http-route-java') {
+    return { kind: 'route', id: 'route_' + sanitizeId(b.label || `${b.file}_${b.line}`), label: b.label || `route@${b.file}:${b.line}` };
+  }
+  if (b.type === 'queue-producer') {
+    return { kind: 'queue', id: 'qprod_' + sanitizeId(`${b.file}_${b.line}`), label: `producer: ${b.file}:${b.line}` };
+  }
+  if (b.type === 'queue-consumer') {
+    return { kind: 'queue', id: 'qcons_' + sanitizeId(`${b.file}_${b.line}`), label: `consumer: ${b.file}:${b.line}` };
+  }
+  if (b.type === 'grpc-server') {
+    return { kind: 'grpc', id: 'grpc_' + sanitizeId(`${b.file}_${b.line}`), label: `grpc@${b.file}:${b.line}` };
+  }
+  if (b.type === 'db-edge') {
+    return { kind: 'db', id: 'db_' + sanitizeId(`${b.file}_${b.line}`), label: `db@${b.file}:${b.line}` };
+  }
+  return null;
+}
+
+function findingsForNode(node, findings, boundary) {
+  if (!Array.isArray(findings)) return [];
+  return findings.filter(f =>
+    f && f.file === boundary.file &&
+    Math.abs((f.line || 0) - (boundary.line || 0)) <= 25
+  );
+}
+
+export function buildTrustBoundaryDiagram(findings, fileContents) {
+  const boundaries = buildTrustBoundaries(fileContents);
+  const assets = buildAssetInventory(fileContents);
+
+  const nodes = new Map();
+  const edges = [];
+  const decorations = [];
+
+  // INTERNET ── route ── service-internal
+  const INTERNET = { id: 'INTERNET', kind: 'external', label: 'Internet' };
+  const APP = { id: 'APP', kind: 'app', label: 'Application' };
+  nodes.set('INTERNET', INTERNET);
+  nodes.set('APP', APP);
+
+  for (const b of boundaries) {
+    const n = nodeFor(b);
+    if (!n) continue;
+    if (!nodes.has(n.id)) nodes.set(n.id, n);
+    if (n.kind === 'route') edges.push({ from: INTERNET.id, to: n.id, kind: 'http' });
+    if (n.kind === 'route') edges.push({ from: n.id, to: APP.id, kind: 'invoke' });
+    if (n.kind === 'queue') edges.push({ from: APP.id, to: n.id, kind: 'queue' });
+    if (n.kind === 'grpc') edges.push({ from: INTERNET.id, to: n.id, kind: 'grpc' });
+    if (n.kind === 'db') edges.push({ from: APP.id, to: n.id, kind: 'db' });
+    for (const f of findingsForNode(n, findings, b)) {
+      decorations.push({ nodeId: n.id, severity: f.severity, vuln: (f.vuln || '').slice(0, 60), file: f.file, line: f.line });
+    }
+  }
+
+  // Assets → as terminal nodes off APP
+  for (const a of assets.slice(0, 12)) {
+    const id = 'asset_' + sanitizeId(`${a.category}_${a.name || a.file}`);
+    if (!nodes.has(id)) nodes.set(id, { id, kind: 'asset', label: `${a.category}: ${a.name || ''}` });
+    edges.push({ from: APP.id, to: id, kind: 'asset' });
+  }
+
+  // Render Mermaid
+  const lines = ['flowchart LR'];
+  for (const n of nodes.values()) {
+    const safe = n.label.replace(/"/g, "'").slice(0, 60);
+    if (n.kind === 'external') lines.push(`  ${n.id}((${safe}))`);
+    else if (n.kind === 'asset') lines.push(`  ${n.id}[/"${safe}"/]`);
+    else if (n.kind === 'db') lines.push(`  ${n.id}[("${safe}")]`);
+    else lines.push(`  ${n.id}["${safe}"]`);
+  }
+  for (const e of edges) lines.push(`  ${e.from} -->|${e.kind}| ${e.to}`);
+  // Severity-styled class assignments for decorated nodes.
+  const decoratedSeverities = new Map();
+  for (const d of decorations) {
+    const rank = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+    const prev = decoratedSeverities.get(d.nodeId);
+    if (!prev || (rank[d.severity] ?? 9) < (rank[prev] ?? 9)) decoratedSeverities.set(d.nodeId, d.severity);
+  }
+  for (const [id, sev] of decoratedSeverities) lines.push(`  class ${id} sev_${sev};`);
+  lines.push('  classDef sev_critical fill:#ffcccc,stroke:#a00,stroke-width:2px;');
+  lines.push('  classDef sev_high fill:#ffe0b2,stroke:#c60,stroke-width:2px;');
+  lines.push('  classDef sev_medium fill:#fff3cd,stroke:#a80;');
+  lines.push('  classDef sev_low fill:#e8eaf6,stroke:#557;');
+
+  return {
+    mermaid: lines.join('\n'),
+    nodes: [...nodes.values()],
+    edges,
+    decorations,
+  };
+}

package/src/posture/type-narrowing.js

@@ -0,0 +1,129 @@
+// FR-SEM-10 — Whole-program type narrowing (heuristic).
+//
+// When a function parameter is declared `any` / `unknown` / `interface{}` /
+// `dynamic` but in practice every call site passes a typed value, downstream
+// taint analysis sees the wide type and falsely warns "could be anything."
+// This module performs a callsite-based narrowing pass: for each function
+// with a wide parameter type, look at all call sites in the project; if every
+// argument is provably typed (literal, typed variable, typed return), narrow
+// the parameter for analysis purposes.
+//
+// The pass is INFORMATIONAL ONLY — it does not silently drop findings. It
+// annotates `f.typeNarrowed: { from, to, callSites }` and lowers confidence
+// by a small amount on the affected finding so downstream ranking accounts
+// for the narrowing without erasing the finding.
+//
+// Languages covered (regex-level):
+//   TypeScript : `(x: any)` / `(x: unknown)`
+//   Python     : `def f(x: Any)` / `def f(x)`  (no annotation = implicit any)
+//   Go         : `interface{}` / `any`
+
+const TS_ANY_PARAM_RE = /function\s+(\w+)\s*\(([^)]*\b\w+\s*:\s*(?:any|unknown)[^)]*)\)/g;
+const TS_ANY_ARROW_RE = /const\s+(\w+)\s*=\s*\(([^)]*\b\w+\s*:\s*(?:any|unknown)[^)]*)\)\s*=>/g;
+const PY_ANY_PARAM_RE = /def\s+(\w+)\s*\(([^)]*\b\w+\s*:\s*(?:Any|object)[^)]*)\)/g;
+const GO_ANY_PARAM_RE = /func\s+(\w+)\s*\(([^)]*\b\w+\s+(?:interface\{\}|any)[^)]*)\)/g;
+
+function extractWideParamFns(text, lang) {
+  if (!text) return [];
+  const out = [];
+  const patterns = {
+    ts: [TS_ANY_PARAM_RE, TS_ANY_ARROW_RE],
+    py: [PY_ANY_PARAM_RE],
+    go: [GO_ANY_PARAM_RE],
+  };
+  for (const re of (patterns[lang] || [])) {
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(text))) {
+      out.push({ name: m[1], params: m[2], pos: m.index });
+    }
+  }
+  return out;
+}
+
+function inferLang(filePath) {
+  if (/\.(ts|tsx)$/i.test(filePath)) return 'ts';
+  if (/\.py$/i.test(filePath)) return 'py';
+  if (/\.go$/i.test(filePath)) return 'go';
+  return null;
+}
+
+// Detect whether a call-site argument is "narrowly typed": literal, typed
+// expression, member of a known-typed object. We deliberately under-approximate
+// — we only narrow when every observed call passes a clearly-typed value.
+function isNarrowlyTypedArg(arg) {
+  const t = arg.trim();
+  if (!t) return false;
+  if (/^["'`]/.test(t)) return true;                        // string literal
+  if (/^-?\d/.test(t)) return true;                          // number literal
+  if (/^(?:true|false|null|undefined|None|nil)$/.test(t)) return true;
+  if (/^\{/.test(t) || /^\[/.test(t)) return true;           // object/array literal
+  if (/\bas\s+\w+/.test(t)) return true;                     // TS cast
+  if (/<[\w.<>,\s]+>/.test(t) && /^\w+</.test(t)) return true; // generic typed call
+  return false;
+}
+
+export function findNarrowableFunctions(fileContents) {
+  if (!fileContents || typeof fileContents !== 'object') return [];
+  const fns = [];
+  for (const [fp, text] of Object.entries(fileContents)) {
+    const lang = inferLang(fp);
+    if (!lang) continue;
+    if (!text || typeof text !== 'string') continue;
+    for (const fn of extractWideParamFns(text, lang)) {
+      fns.push({ name: fn.name, declaredIn: fp, lang });
+    }
+  }
+  return fns;
+}
+
+// Find call sites of `name` across all files; classify each argument.
+// Returns { totalCalls, narrowCalls, examples[] }.
+function probeCallSites(name, fileContents) {
+  const re = new RegExp(`\\b${name}\\s*\\(\\s*([^)]{0,200})\\)`, 'g');
+  let total = 0, narrow = 0;
+  const examples = [];
+  for (const [fp, text] of Object.entries(fileContents)) {
+    if (!text || typeof text !== 'string') continue;
+    re.lastIndex = 0;
+    let m;
+    while ((m = re.exec(text))) {
+      total++;
+      const args = m[1].split(',').slice(0, 1);
+      if (args.every(isNarrowlyTypedArg)) {
+        narrow++;
+        if (examples.length < 3) examples.push({ file: fp, snippet: m[0].slice(0, 80) });
+      }
+    }
+  }
+  return { totalCalls: total, narrowCalls: narrow, examples };
+}
+
+export function annotateTypeNarrowing(findings, fileContents) {
+  if (!Array.isArray(findings) || !fileContents) return findings;
+  const fns = findNarrowableFunctions(fileContents);
+  if (!fns.length) return findings;
+  const fnIndex = new Map();
+  for (const fn of fns) fnIndex.set(fn.name, fn);
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue;
+    const enclosing = f.enclosingFunction || f.functionName || f.fnName;
+    if (!enclosing || !fnIndex.has(enclosing)) continue;
+    const probe = probeCallSites(enclosing, fileContents);
+    if (probe.totalCalls === 0) continue;
+    if (probe.narrowCalls / probe.totalCalls >= 0.95) {
+      f.typeNarrowed = {
+        from: 'any/unknown/interface{}',
+        to: 'callsite-uniform-typed',
+        callSites: probe.totalCalls,
+        narrowed: probe.narrowCalls,
+        examples: probe.examples,
+      };
+      if (typeof f.confidence === 'number') {
+        f.confidence = Math.max(0, f.confidence - 0.10);
+        f._narrowedConfidenceAdjust = -0.10;
+      }
+    }
+  }
+  return findings;
+}

package/src/posture/validator-metrics.js

@@ -0,0 +1,179 @@
+// Per-CWE precision/recall metrics persistence.
+//
+// PRD success metric §5: "Recall on top-25 CWE classes ≥ 0.92." Tracking
+// this requires running a labelled benchmark and persisting the per-family
+// scorecard so /security-trend, /report-card, and the dashboard can
+// surface the trend over time.
+//
+// File location: .agentic-security/validator-metrics.json
+//
+// Shape:
+//   {
+//     "history": [
+//       { "when": "2026-05-18T...", "benchmark": "owasp-benchmark-v1.2",
+//         "mode": "blind+strict",
+//         "aggregate": { "tp": ..., "fp": ..., "fn": ..., "precision": ..., "recall": ..., "f1": ... },
+//         "perFamily": { "<family>": { "tp": ..., "fp": ..., "fn": ..., "precision": ..., "recall": ..., "f1": ... } }
+//       }
+//     ],
+//     "floors": {
+//       "perFamily": { "default": { "recall": 0.92 }, "<family>": { "recall": 0.92, "precision": 0.85 } },
+//       "aggregate": { "f1": 0.90 }
+//     }
+//   }
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const FILE = '.agentic-security/validator-metrics.json';
+const HISTORY_CAP = 100;
+
+function _filePath(scanRoot) { return path.join(scanRoot || process.cwd(), FILE); }
+
+function _read(scanRoot) {
+  const fp = _filePath(scanRoot);
+  if (!fs.existsSync(fp)) return { history: [], floors: { perFamily: { default: { recall: 0.92 } }, aggregate: { f1: 0.90 } } };
+  try { return JSON.parse(fs.readFileSync(fp, 'utf8')); }
+  catch { return { history: [], floors: { perFamily: { default: { recall: 0.92 } }, aggregate: { f1: 0.90 } } }; }
+}
+
+function _write(scanRoot, data) {
+  const fp = _filePath(scanRoot);
+  try {
+    fs.mkdirSync(path.dirname(fp), { recursive: true });
+    fs.writeFileSync(fp, JSON.stringify(data, null, 2));
+  } catch { /* swallow — telemetry is best-effort */ }
+}
+
+function _round(n) { return Math.round(n * 10000) / 10000; }
+
+function _computeStats(tp, fp, fn) {
+  const precision = tp / Math.max(tp + fp, 1e-9);
+  const recall    = tp / Math.max(tp + fn, 1e-9);
+  const f1        = (2 * precision * recall) / Math.max(precision + recall, 1e-9);
+  return { precision: _round(precision), recall: _round(recall), f1: _round(f1) };
+}
+
+// Record one benchmark run.
+//   benchmark: 'owasp-benchmark-v1.2' | 'sard-juliet-java' | 'cve-replay' | ...
+//   mode: 'blind+strict' | 'non-blind+strict' | 'non-blind+wildcard'
+//   perFamily: { fam: { tp, fp, fn } }
+export function recordRun(scanRoot, { benchmark, mode, tp, fp, fn, perFamily }) {
+  const data = _read(scanRoot);
+  const entry = {
+    when: new Date().toISOString(),
+    benchmark, mode,
+    aggregate: { tp, fp, fn, ..._computeStats(tp, fp, fn) },
+    perFamily: {},
+  };
+  for (const [fam, c] of Object.entries(perFamily || {})) {
+    if (!c) continue;
+    entry.perFamily[fam] = { tp: c.tp || 0, fp: c.fp || 0, fn: c.fn || 0, ..._computeStats(c.tp || 0, c.fp || 0, c.fn || 0) };
+  }
+  data.history = data.history || [];
+  data.history.push(entry);
+  if (data.history.length > HISTORY_CAP) data.history = data.history.slice(-HISTORY_CAP);
+  _write(scanRoot, data);
+  return entry;
+}
+
+// Record one PRODUCTION-TRIAGE outcome (operator marked a finding tp/fp).
+// This is the per-CWE quality signal from real-world use, complementing the
+// per-benchmark numbers above. Without this, the only feedback the engine
+// gets is OWASP-Benchmark-tuned; with it, customer-real-world precision
+// trends are visible in /security-trend.
+//
+//   benchmark: 'production-triage' (fixed string, used as the storage key)
+//   verdict:   'tp' | 'fp' | 'wontfix'
+//   family:    the finding's family name
+//
+// Aggregated per-CWE counts are stored under
+// data.productionTriage[family] = { tp, fp, wontfix, lastAt }.
+// summarize() and a future /security-trend command surface this.
+export function recordTriage(scanRoot, { family, verdict, stableId }) {
+  if (!family || !['tp', 'fp', 'wontfix'].includes(verdict)) return null;
+  const data = _read(scanRoot);
+  data.productionTriage = data.productionTriage || {};
+  const row = data.productionTriage[family] = data.productionTriage[family] || { tp: 0, fp: 0, wontfix: 0, lastAt: null };
+  row[verdict] = (row[verdict] || 0) + 1;
+  row.lastAt = new Date().toISOString();
+  // Cap per-family rows so a runaway triage script can't bloat the file.
+  if ((row.tp || 0) + (row.fp || 0) + (row.wontfix || 0) > 10_000) {
+    // Stop accumulating; the trend is well-established by now.
+    row._capped = true;
+    return row;
+  }
+  void stableId;
+  _write(scanRoot, data);
+  return row;
+}
+
+// Read the latest entry and compare against floors.
+export function getLatest(scanRoot, benchmark) {
+  const data = _read(scanRoot);
+  const matches = (data.history || []).filter(e => !benchmark || e.benchmark === benchmark);
+  return matches[matches.length - 1] || null;
+}
+
+// Identify families that violate their floors in the latest run.
+//   { aggregateBelowFloor: bool, familiesBelowFloor: [{fam, metric, value, floor}] }
+export function checkFloors(scanRoot, benchmark) {
+  const data = _read(scanRoot);
+  const latest = getLatest(scanRoot, benchmark);
+  if (!latest) return { aggregateBelowFloor: false, familiesBelowFloor: [], latest: null };
+  const floors = data.floors || {};
+  const out = { aggregateBelowFloor: false, familiesBelowFloor: [], latest };
+  const aggMin = (floors.aggregate || {}).f1;
+  if (typeof aggMin === 'number' && latest.aggregate.f1 < aggMin) {
+    out.aggregateBelowFloor = true;
+    out.aggregateFloor = aggMin;
+  }
+  const perFamFloors = floors.perFamily || {};
+  const defaultFamFloor = perFamFloors.default || {};
+  for (const [fam, stats] of Object.entries(latest.perFamily || {})) {
+    const famFloor = { ...defaultFamFloor, ...(perFamFloors[fam] || {}) };
+    for (const metric of ['precision', 'recall', 'f1']) {
+      if (typeof famFloor[metric] === 'number' && stats[metric] < famFloor[metric]) {
+        out.familiesBelowFloor.push({ fam, metric, value: stats[metric], floor: famFloor[metric] });
+      }
+    }
+  }
+  return out;
+}
+
+// Convenience: render a short human summary including both benchmark
+// numbers AND the production-triage trend (per-CWE TP/FP from real-world
+// operator verdicts via /triage).
+export function summarize(scanRoot, benchmark) {
+  const latest = getLatest(scanRoot, benchmark);
+  const data = _read(scanRoot);
+  const lines = [];
+  if (latest) {
+    const r = latest.aggregate;
+    const fams = Object.entries(latest.perFamily || {})
+      .sort((a, b) => b[1].tp - a[1].tp);
+    lines.push(`Benchmark: ${latest.benchmark} (${latest.mode}) @ ${latest.when.slice(0, 16)}`);
+    lines.push(`  F1=${r.f1} P=${r.precision} R=${r.recall} (TP=${r.tp} FP=${r.fp} FN=${r.fn})`);
+    for (const [fam, s] of fams.slice(0, 10)) {
+      lines.push(`  · ${fam.padEnd(20)} P=${s.precision} R=${s.recall} (TP=${s.tp} FP=${s.fp} FN=${s.fn})`);
+    }
+  } else {
+    lines.push('(no benchmark metrics yet)');
+  }
+  // Production-triage trend (R3.3 / P1-11 — this is the real-world signal,
+  // not the benchmark proxy).
+  const triage = data.productionTriage || {};
+  const fams = Object.entries(triage)
+    .filter(([, c]) => (c.tp || 0) + (c.fp || 0) > 0)
+    .sort((a, b) => ((b[1].fp || 0) - (a[1].fp || 0)));
+  if (fams.length) {
+    lines.push('');
+    lines.push('Production-triage trend (real-world precision proxy):');
+    for (const [fam, c] of fams.slice(0, 10)) {
+      const total = (c.tp || 0) + (c.fp || 0);
+      const pHat = total ? (c.tp / total).toFixed(2) : '?';
+      lines.push(`  · ${fam.padEnd(20)} P≈${pHat} (TP=${c.tp || 0} FP=${c.fp || 0} wontfix=${c.wontfix || 0})`);
+    }
+  }
+  return lines.join('\n');
+}