@clear-capabilities/agentic-security-scanner 0.162.0 → 0.163.1

package/src/posture/evaluation/score.js

@@ -0,0 +1,174 @@
+// End-to-end scoring of an evaluation run (QA-003.AC03).
+//
+// The rule that makes this a measurement and not a flattering one: a known
+// positive that sat behind a timeout, an error, an unavailable tree or a
+// quarantine is a MISS. The end-to-end metrics keep every such case in the
+// denominator. A second set, "conditional on completion", is reported beside
+// them and is labelled as such; it never replaces them.
+//
+// What is NOT scored, and is counted with its reason instead of vanishing:
+//   - targets with no adjudicated label            (unlabeled-target)
+//   - labels that are only candidates / disputed   (label-not-adjudicated)
+//   - findings no adjudicated label accounts for   (no-adjudicated-label), which
+//     go to a review queue: they may be genuine, so they are never auto-FPs.
+//
+// False positives are counted ONLY on adjudicated negatives (patched code, safe
+// real code, near-misses), one per ROOT CAUSE: repeated alerts for the same flaw
+// (`clusterAlerts`) score once and are reported in `alertsCollapsed`; the operational
+// alert burden is report.js's job and is never hidden by this. The score also carries
+// `perTarget` tallies, which is what the grouped bootstrap resamples. Pure: no fs, no clock.
+
+import { SCHEMA_VERSION } from '../assurance/schema-kit.js';
+import { digestOf } from '../assurance/identity.js';
+import { isScoreable, matchFinding, matchNegative, reviewQueue, populationCounts } from './labels.js';
+
+const SCORE_SCHEMA = 'agentic-security/evaluation-score';
+
+const rate = (n, d) => (d > 0 ? n / d : null);
+
+function countsOf(tp, fn, fp, tn) {
+  const precision = rate(tp, tp + fp);
+  const recall = rate(tp, tp + fn);
+  const f1 = tp + fp + fn === 0 ? null : (2 * tp) / (2 * tp + fp + fn);
+  return { tp, fn, fp, tn, precision, recall, f1 };
+}
+
+function bump(map, key, field) {
+  if (!map[key]) map[key] = { tp: 0, fn: 0, fp: 0, tn: 0 };
+  map[key][field]++;
+}
+
+const finalize = (m) => Object.fromEntries(Object.keys(m).sort().map((k) => [k, countsOf(m[k].tp, m[k].fn, m[k].fp, m[k].tn)]));
+
+/** Micro (pooled counts) and macro (mean of per-group F1 over groups where F1 is defined). */
+export function aggregate(byGroup) {
+  const rows = Object.values(byGroup);
+  const sum = rows.reduce((s, r) => ({ tp: s.tp + r.tp, fn: s.fn + r.fn, fp: s.fp + r.fp, tn: s.tn + r.tn }), { tp: 0, fn: 0, fp: 0, tn: 0 });
+  const defined = rows.filter((r) => r.f1 !== null);
+  return { micro: countsOf(sum.tp, sum.fn, sum.fp, sum.tn), macroF1: defined.length ? defined.reduce((s, r) => s + r.f1, 0) / defined.length : null, groups: rows.length };
+}
+
+const findingKey = (f) => `${f.file}|${f.line}|${f.family}|${f.cwe}`;
+
+/**
+ * Collapse repeated alerts to root causes (QA-004.AC02). Findings in the same file and family whose lines chain within
+ * `lineWindow` of one another are one root cause: the same sink reported by two detectors, or a single flaw reported on its
+ * source line and its sink line, is one defect, not several. A finding with no line cannot be placed and stays alone. Returns
+ * clusters in a stable order; each carries every member so the operational alert count is still available.
+ */
+export function clusterAlerts(findings, lineWindow = 3) {
+  const sorted = [...findings].sort((a, b) => String(a.file).localeCompare(String(b.file)) || String(a.family).localeCompare(String(b.family)) || (a.line ?? -1) - (b.line ?? -1));
+  const clusters = [];
+  for (const f of sorted) {
+    const last = clusters[clusters.length - 1];
+    const prev = last && last.members[last.members.length - 1];
+    const joins = prev && prev.file === f.file && prev.family === f.family && Number.isInteger(prev.line) && Number.isInteger(f.line) && f.line - prev.line <= lineWindow;
+    if (joins) last.members.push(f); else clusters.push({ file: f.file, family: f.family, line: f.line, members: [f] });
+  }
+  return clusters;
+}
+
+/**
+ * @param {object} o
+ * @param {object} o.run         a run record (runner.js)
+ * @param {object} o.protocol    the protocol the run is bound to (matching policy comes from it)
+ * @param {object[]} o.defects   defect labels
+ * @param {object[]} o.negatives negative labels
+ */
+export function scoreRun({ run, protocol, defects = [], negatives = [] }) {
+  const policy = protocol.matching;
+  const outcomeOf = new Map(run.outcomes.map((o) => [`${o.targetId}|${o.variant}`, o]));
+  const inRun = new Set(run.outcomes.map((o) => o.targetId));
+
+  const e2e = { lang: {}, family: {} }; const cond = { lang: {}, family: {} };
+  const misses = []; const falsePositives = []; const negativeFailures = []; const matchedFinding = new Set();
+  const unscored = { unlabeledTargets: [], nonAdjudicatedLabels: 0, unlabeledFindings: { count: 0, byReason: {} }, positivesOutsideRun: 0 };
+  const queue = [];
+
+  const labelledTargets = new Set();
+  // Per-target tallies (end to end), so an interval can resample whole targets/groups instead of pretending cases are independent.
+  const perTarget = {};
+  const tally = (targetId, language, field, n = 1) => {
+    if (!perTarget[targetId]) perTarget[targetId] = { language, tp: 0, fn: 0, fp: 0, tn: 0 };
+    perTarget[targetId][field] += n;
+  };
+  const scoreable = (l) => {
+    if (isScoreable(l)) return true;
+    unscored.nonAdjudicatedLabels++;
+    return false;
+  };
+
+  for (const l of defects.filter(scoreable)) {
+    if (!inRun.has(l.targetId)) { unscored.positivesOutsideRun++; continue; }
+    labelledTargets.add(l.targetId);
+    const o = outcomeOf.get(`${l.targetId}|pre`);
+    const completed = o?.status === 'completed';
+    const hit = completed ? o.findings.find((f) => matchFinding(f, l, policy).matched) : null;
+    if (hit) {
+      matchedFinding.add(`${l.targetId}|pre|${findingKey(hit)}`);
+      for (const [m, k] of [[e2e.lang, l.language], [e2e.family, l.family], [cond.lang, l.language], [cond.family, l.family]]) bump(m, k, 'tp');
+      tally(l.targetId, l.language, 'tp');
+    } else {
+      const reason = !o ? 'no-outcome' : completed ? 'not-detected' : o.status;
+      misses.push({ labelId: l.id, targetId: l.targetId, reason, detail: o?.failureReason || null });
+      for (const [m, k] of [[e2e.lang, l.language], [e2e.family, l.family]]) bump(m, k, 'fn');
+      tally(l.targetId, l.language, 'fn');
+      if (completed) for (const [m, k] of [[cond.lang, l.language], [cond.family, l.family]]) bump(m, k, 'fn');
+    }
+  }
+
+  for (const n of negatives.filter(scoreable)) {
+    if (!inRun.has(n.targetId)) continue;
+    labelledTargets.add(n.targetId);
+    const o = outcomeOf.get(`${n.targetId}|${n.variant}`);
+    if (o?.status !== 'completed') {
+      negativeFailures.push({ labelId: n.id, targetId: n.targetId, variant: n.variant, reason: o?.status || 'no-outcome', detail: o?.failureReason || null });
+      continue;
+    }
+    const hits = new Map();
+    for (const f of o.findings) {
+      if (matchNegative(f, n).matched) hits.set(findingKey(f), f);
+      else if ((n.scope.files || []).includes(f.file)) queue.push({ targetId: n.targetId, variant: n.variant, finding: f, reason: 'finding-in-negative-scope-other-family' });
+    }
+    for (const f of hits.values()) matchedFinding.add(`${n.targetId}|${n.variant}|${findingKey(f)}`);
+    if (hits.size) {
+      // One false positive per ROOT CAUSE, not per alert: repeated alerts for the same flaw are reported in `alertsCollapsed` and
+      // in the operational burden, never silently hidden and never multiplied into the precision denominator.
+      const clusters = clusterAlerts([...hits.values()], policy.lineWindow);
+      for (const c of clusters) falsePositives.push({ labelId: n.id, targetId: n.targetId, kind: n.kind, finding: { file: c.members[0].file, line: c.members[0].line, family: c.family }, alertsCollapsed: c.members.length });
+      for (const [m, k] of [[e2e.lang, n.language], [e2e.family, n.family], [cond.lang, n.language], [cond.family, n.family]]) { for (let i = 0; i < clusters.length; i++) bump(m, k, 'fp'); }
+      tally(n.targetId, n.language, 'fp', clusters.length);
+    } else {
+      for (const [m, k] of [[e2e.lang, n.language], [e2e.family, n.family], [cond.lang, n.language], [cond.family, n.family]]) bump(m, k, 'tn');
+      tally(n.targetId, n.language, 'tn');
+    }
+  }
+
+  // Findings no adjudicated label accounts for: unscored, queued for review, never auto-FP.
+  for (const o of run.outcomes) {
+    if (o.status !== 'completed') continue;
+    for (const f of o.findings) {
+      if (matchedFinding.has(`${o.targetId}|${o.variant}|${findingKey(f)}`)) continue;
+      if (queue.some((q) => q.targetId === o.targetId && q.variant === o.variant && q.finding === f)) continue;
+      unscored.unlabeledFindings.count++;
+      unscored.unlabeledFindings.byReason['no-adjudicated-label'] = (unscored.unlabeledFindings.byReason['no-adjudicated-label'] || 0) + 1;
+      queue.push({ targetId: o.targetId, variant: o.variant, finding: f, reason: 'no-adjudicated-label' });
+    }
+  }
+  for (const id of [...inRun].sort()) if (!labelledTargets.has(id)) unscored.unlabeledTargets.push({ targetId: id, reason: 'unlabeled-target' });
+
+  const endToEnd = { byLanguage: finalize(e2e.lang), byFamily: finalize(e2e.family) };
+  const conditional = { byLanguage: finalize(cond.lang), byFamily: finalize(cond.family) };
+  const completed = run.outcomes.filter((o) => o.status === 'completed').length;
+  const score = {
+    schema: SCORE_SCHEMA, schemaVersion: SCHEMA_VERSION, runId: run.runId, protocolHash: run.protocolHash, split: run.split,
+    endToEnd: { ...endToEnd, ...aggregate(endToEnd.byLanguage), label: 'end-to-end: failures on known positives are misses' },
+    conditional: { ...conditional, ...aggregate(conditional.byLanguage), label: 'conditional on completion: additional, never a replacement' },
+    completion: { outcomes: run.outcomes.length, completed, rate: rate(completed, run.outcomes.length), totals: run.totals },
+    misses, falsePositives, negativeFailures, unscored, perTarget,
+    reviewQueue: reviewQueue(queue),
+    population: populationCounts(defects, negatives),
+  };
+  score.scoreHash = digestOf({ ...score, reviewQueue: undefined });
+  return score;
+}

package/src/posture/evaluation/synthetic.js

@@ -0,0 +1,90 @@
+// A SYNTHETIC evaluation suite, for exercising the machinery only.
+//
+// Everything here is authored by the tooling's developers: the code under
+// `test/fixtures/evaluation-synthetic/`, the "reviewers", the commits and the
+// licence. Every protocol and label it produces carries `synthetic: true`, and
+// gates.js refuses to let a synthetic population satisfy any real-code gate. Do
+// not read a score computed from this suite as an accuracy figure for the
+// engine: three tiny files cannot support one.
+
+import * as path from 'node:path';
+import { digestOf } from '../assurance/identity.js';
+import { digestTree, targetDigestOf } from './runner.js';
+import { freezeProtocol, CORE_LANGUAGES, PREREGISTERED_THRESHOLDS, DEFAULT_MATCHING } from './protocol.js';
+import { buildDefectLabel, buildNegativeLabel } from './labels.js';
+
+const SYNTHETIC_LICENSE = 'synthetic-test-fixture';
+const SHA = (c) => c.repeat(40);
+
+const TARGETS = [
+  { id: 'syn-sqli-js', language: 'javascript', upstream: 'example.invalid/synthetic/sqli-js', preCommit: SHA('1'), postCommit: SHA('2'), split: 'dev' },
+  { id: 'syn-cmd-py', language: 'python', upstream: 'example.invalid/synthetic/cmd-py', preCommit: SHA('3'), postCommit: SHA('4'), split: 'dev' },
+  { id: 'syn-nearmiss-js', language: 'javascript', upstream: 'example.invalid/synthetic/nearmiss-js', preCommit: SHA('5'), postCommit: null, split: 'sealed' },
+];
+
+const reviewers = (tag) => [
+  { reviewerId: `synthetic-reviewer-a-${tag}`, verdict: 'confirmed' },
+  { reviewerId: `synthetic-reviewer-b-${tag}`, verdict: 'confirmed' },
+];
+const adjudication = (tag) => ({ status: 'adjudicated', independent: true, reviewers: reviewers(tag) });
+
+/** Directory for one variant of a synthetic target. */
+const syntheticTargetDir = (fixturesDir, id, variant) => path.join(fixturesDir, id, variant);
+
+export function buildSyntheticSuite({ fixturesDir, thresholds = { ...PREREGISTERED_THRESHOLDS }, limits } = {}) {
+  const targets = TARGETS.map((t) => {
+    const pre = digestTree(syntheticTargetDir(fixturesDir, t.id, 'pre'));
+    const post = t.postCommit ? digestTree(syntheticTargetDir(fixturesDir, t.id, 'post')) : null;
+    const { split, ...rest } = t;
+    return { ...rest, pairId: `pair-${t.id}`, advisoryIds: [], license: SYNTHETIC_LICENSE, digest: targetDigestOf({ pre, post }) };
+  });
+  const splits = { dev: TARGETS.filter((t) => t.split === 'dev').map((t) => t.id).sort(), sealed: TARGETS.filter((t) => t.split === 'sealed').map((t) => t.id).sort() };
+  const draft = {
+    synthetic: true,
+    engine: { version: '0.0.0-synthetic', bundleDigest: digestOf('synthetic-engine') },
+    measurement: { commit: SHA('b'), cleanTree: true },
+    tools: { node: 'synthetic' },
+    models: [],
+    datasetLicenses: { [SYNTHETIC_LICENSE]: 'authored for tooling tests; not real-world code' },
+    scope: { languages: [...CORE_LANGUAGES], families: ['sql-injection', 'command-injection'] },
+    matching: { ...DEFAULT_MATCHING },
+    limits: { perTargetTimeoutMs: 120000, spendCeilingUsd: 0, replicates: 3, ...(limits || {}) },
+    thresholds,
+    targets,
+    splits,
+    grouping: { method: 'union-find', keys: ['pair', 'upstream', 'advisory', 'commit', 'template'], salt: 'synthetic' },
+  };
+  const frozen = freezeProtocol(draft);
+
+  const base = (tag) => ({ synthetic: true, adjudication: adjudication(tag), proposedBy: { role: 'worker', id: 'synthetic-proposer' } });
+  const defects = [
+    buildDefectLabel({
+      ...base('d1'), targetId: 'syn-sqli-js', rootCauseId: 'synthetic-root-cause-sqli-js', affected: { commit: SHA('1') },
+      language: 'javascript', family: 'sql-injection', cwe: 'CWE-89', location: { file: 'app.js', startLine: 8, endLine: 8 },
+      evidence: [{ ref: 'synthetic-review-note-sqli', producer: 'human' }],
+    }),
+    buildDefectLabel({
+      ...base('d2'), targetId: 'syn-cmd-py', rootCauseId: 'synthetic-root-cause-cmd-py', affected: { commit: SHA('3') },
+      language: 'python', family: 'command-injection', cwe: 'CWE-78', location: { file: 'tool.py', startLine: 11, endLine: 11 },
+      evidence: [{ ref: 'synthetic-review-note-cmd', producer: 'human' }],
+    }),
+  ];
+  const negatives = [
+    buildNegativeLabel({
+      ...base('n1'), targetId: 'syn-sqli-js', variant: 'post', kind: 'patched', language: 'javascript', family: 'sql-injection',
+      scope: { files: ['app.js'] }, pairedDefectId: defects[0].id, rationale: 'synthetic: parameterised query, reviewed as not injectable',
+    }),
+    buildNegativeLabel({
+      ...base('n2'), targetId: 'syn-cmd-py', variant: 'post', kind: 'patched', language: 'python', family: 'command-injection',
+      scope: { files: ['tool.py'] }, pairedDefectId: defects[1].id, rationale: 'synthetic: argument list and allow-list check, reviewed as not injectable',
+    }),
+    buildNegativeLabel({
+      ...base('n3'), targetId: 'syn-nearmiss-js', variant: 'pre', kind: 'near-miss', language: 'javascript', family: 'sql-injection',
+      scope: { files: ['report.js'] }, rationale: 'synthetic: query assembled from constants only, reviewed as not injectable',
+    }),
+  ];
+  return { protocol: frozen.ok ? frozen.protocol : null, freezeErrors: frozen.errors, draft, defects, negatives, fixturesDir };
+}
+
+/** resolveTarget for the runner over the synthetic fixtures. */
+export const syntheticResolver = (fixturesDir) => (target, variant) => ({ dir: syntheticTargetDir(fixturesDir, target.id, variant) });

package/src/posture/evaluation/why-missed.js

@@ -0,0 +1,219 @@
+// Why-missed instrumentation across the analysis pipeline (QA-005.AC01, QA-005.AC03).
+//
+// For a labelled DEVELOPMENT miss, name the EARLIEST stage that lost the defect, or say `unknown` and why. The stages, in the
+// order a defect travels through the engine:
+//
+//   scan-execution   the scan never completed (timeout, error, unavailable, quarantined): nothing downstream ran
+//   parser-ir        the file did not lower to an IR function, or the parser failed on it
+//   source-modelling no untrusted source was recognised anywhere the flow could start
+//   propagation      a source and a sink were both recognised near the defect, and no flow joined them
+//   sink-modelling   no sink (or, for non-flow families, no detector rule) was recognised at the defect
+//   filters          a candidate existed and a precision filter (guard recognition, safe-shape, sanitized) dropped it
+//   suppression      a candidate existed and policy dropped it (ignore pragma, custom rule, learned feedback, validator)
+//   deduplication    a candidate existed and was collapsed into a finding that carries a different location
+//   attribution      a finding for this defect was REPORTED, at a location or under a family that does not match the label
+//
+// The order of DETERMINATION differs from the order of travel, deliberately: a candidate observed downstream (a dropped finding,
+// a deduplicated loser, a mislocated report) PROVES every earlier stage worked, so those are checked first and name the stage that
+// lost it. Only when no candidate was observed anywhere do the early stages explain the miss, and among them the first failed
+// stage wins. Sources are checked before sinks, and propagation is blamed only when BOTH endpoints were recognised.
+//
+// Honesty rules: evidence is the engine's own diagnostics (a suppression ledger entry carries file, line, id, cwe and family), not
+// a guess from the label; when there is no diagnostic evidence the answer is `unknown`, never a plausible-sounding stage. The
+// instrument only runs over the DEVELOPMENT split: the sealed split's per-case outcomes are not available to detector work.
+
+import { stageWorkspace, engineEnvironment } from './custody.js';
+import { defaultScanFn } from './runner.js';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+export const STAGES = Object.freeze(['scan-execution', 'parser-ir', 'source-modelling', 'propagation', 'sink-modelling', 'filters', 'suppression', 'deduplication', 'attribution']);
+export const UNKNOWN = 'unknown';
+
+// Families whose detection is a source-to-sink flow; the rest (weak crypto, hardcoded secrets, misconfiguration) are pattern rules.
+const FLOW_FAMILIES = new Set([
+  'sql-injection', 'nosql-injection', 'command-injection', 'path-traversal', 'xss', 'ssrf', 'deserialization', 'insecure-deserialization',
+  'open-redirect', 'code-injection', 'xxe', 'ldap-injection', 'xpath-injection', 'ssti', 'prototype-pollution', 'response-splitting', 'log-injection',
+]);
+const IR_EXT = /\.(?:js|jsx|mjs|cjs|ts|tsx|py|java|cs|kt|kts|go|php|rb|rs|c|cc|cpp|cxx|h|hpp)$/i;
+
+// A ledger reason names its mechanism by prefix. Filters judge a candidate not to be a real flow; suppressions are policy.
+const FILTER_REASON = /^(?:guard-recognized:|sanitized:|universal-|bench-safe-shape|bench-category|primary-cwe|safe-sink-shape|sanitizer-gate)/;
+const SUPPRESSION_REASON = /^(?:inline[- ]pragma|custom-rule|llm-validator|learned|rules-disable|no-vuln-name)/;
+
+const norm = (p) => String(p || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
+
+function windowOf(label, policy) {
+  const w = Number.isInteger(policy?.lineWindow) ? policy.lineWindow : 3;
+  return { lo: label.location.startLine - w, hi: label.location.endLine + w };
+}
+const inWindow = (line, win) => Number.isInteger(line) && line >= win.lo && line <= win.hi;
+
+function familyOf(entry) { return entry.family ?? null; }
+function sameKind(entry, label) {
+  // A ledger entry or finding agrees with the label by family or CWE. With neither recorded the identity is location-only.
+  if (familyOf(entry) && familyOf(entry) === label.family) return 'family';
+  if (entry.cwe && label.cwe && String(entry.cwe).toUpperCase() === String(label.cwe).toUpperCase()) return 'cwe';
+  if (!familyOf(entry) && !entry.cwe) return 'location-only';
+  return null;
+}
+
+/**
+ * Classify ONE labelled miss.
+ * @param {object} o
+ * @param {object} o.label       an adjudicated defect label
+ * @param {object|null} o.outcome the run outcome for the label's target (variant 'pre')
+ * @param {object|null} o.diagnostics the scan child's diagnostics block for that target, or null
+ * @param {object} [o.policy]    the protocol's matching policy
+ * @param {string} [o.layer]     the configuration that produced the outcome
+ */
+export function classifyMiss({ label, outcome, diagnostics, policy, layer = 'deep-taint' }) {
+  const base = { labelId: label.id, targetId: label.targetId, language: label.language, family: label.family, location: label.location };
+  const done = (stage, reason, evidence = {}) => ({ ...base, stage, reason, evidence, deterministic: true });
+  if (!outcome) return done('scan-execution', 'no-outcome-recorded');
+  if (outcome.status !== 'completed') return done('scan-execution', `scan-${outcome.status}`, { failureReason: outcome.failureReason || null });
+  if (!diagnostics) return done(UNKNOWN, 'no-diagnostic-evidence', { note: 'the target was not re-scanned with diagnostics, so no stage can be named' });
+
+  const win = windowOf(label, policy);
+  const file = norm(label.location.file);
+  const here = (e) => norm(e.file) === file;
+
+  // ---- a candidate was REPORTED but does not match: attribution
+  const reported = (outcome.findings || []).filter(here);
+  let best = null;
+  for (const f of reported) {
+    const kind = sameKind(f, label);
+    if (!kind || kind === 'location-only') continue;
+    const inRange = inWindow(f.line, win);
+    if (inRange) continue; // would have matched; not a miss caused by attribution
+    if (!Number.isInteger(f.line)) { best = best || { f, distance: Infinity, why: 'finding-has-no-line' }; continue; }
+    const distance = f.line < win.lo ? win.lo - f.line : f.line - win.hi;
+    if (!best || distance < best.distance) best = { f, distance, why: 'right-file-and-family-wrong-line' };
+  }
+  if (best) return done('attribution', best.why, { reported: { id: best.f.id ?? null, line: best.f.line ?? null, family: best.f.family ?? null, cwe: best.f.cwe ?? null }, distanceLines: Number.isFinite(best.distance) ? best.distance : null });
+
+  // ---- a candidate was COLLAPSED into a winner elsewhere: deduplication
+  // Only the FINAL winner of a bucket counts: a winner that was itself collapsed into a later one is not where the candidate ended up.
+  const allDedupes = diagnostics.stageEvidence?.dedupe || [];
+  const laterLosers = new Set(allDedupes.map((d) => d.loser?.id).filter(Boolean));
+  const dedupes = allDedupes.filter((d) => !laterLosers.has(d.winner?.id) && norm(d.loser?.file || d.file) === file && inWindow(d.loser?.line, win) && (d.family === label.family || !d.family));
+  const dedupeHit = dedupes.find((d) => !(norm(d.winner?.file) === file && inWindow(d.winner?.line, win)));
+  if (dedupeHit) return done('deduplication', 'collapsed-into-winner-at-other-location', { loser: dedupeHit.loser, winner: dedupeHit.winner });
+
+  // ---- a candidate was DROPPED with a recorded reason: filters or suppression
+  const dropped = (diagnostics.suppressions || [])
+    .filter((s) => here(s) && inWindow(s.line, win) && sameKind(s, label))
+    .sort((a, b) => String(a.reason).localeCompare(String(b.reason)) || (a.line ?? 0) - (b.line ?? 0));
+  if (dropped.length) {
+    const d = dropped[0];
+    const stage = SUPPRESSION_REASON.test(d.reason) ? 'suppression' : FILTER_REASON.test(d.reason) ? 'filters' : 'filters';
+    return done(stage, d.reason.split(':').slice(0, 2).join(':'), { ledger: { id: d.id ?? null, line: d.line, family: d.family ?? null, cwe: d.cwe ?? null, reason: d.reason, identity: sameKind(d, label) }, alsoDropped: dropped.length - 1 });
+  }
+
+  // ---- a finding of ANOTHER family sits at the defect's location and no candidate of this family was observed anywhere: it was reported under the wrong family
+  const wrongFamily = reported.find((f) => inWindow(f.line, win) && !sameKind(f, label));
+  if (wrongFamily) return done('attribution', 'right-location-wrong-family', { reported: { id: wrongFamily.id ?? null, line: wrongFamily.line, family: wrongFamily.family ?? null, cwe: wrongFamily.cwe ?? null } });
+
+  // ---- nothing observed anywhere: the early stages explain it
+  const flow = FLOW_FAMILIES.has(label.family) && layer !== 'deterministic-only';
+  if (!flow) {
+    return done('sink-modelling', layer === 'deterministic-only' && FLOW_FAMILIES.has(label.family) ? 'no-pattern-rule-fired-and-taint-layer-not-run' : 'no-detector-rule-fired', { family: label.family });
+  }
+  const ir = diagnostics.ir || {};
+  const entry = ir.files ? ir.files[label.location.file] ?? ir.files[file] : undefined;
+  const ext = (/\.[A-Za-z0-9]+$/.exec(file) || [''])[0].replace('.', '').toLowerCase();
+  if (IR_EXT.test(file)) {
+    if (ir.parseFailures?.byLanguage && ir.parseFailures.byLanguage[ext] > 0) return done('parser-ir', 'ir-parse-failure', { parseFailures: ir.parseFailures.byLanguage[ext], firstError: ir.parseFailures.firstError ?? null });
+    if (entry && (!entry.lowered || (entry.functions || []).length === 0)) return done('parser-ir', 'no-function-lowered', { file: label.location.file });
+  }
+  const sources = (diagnostics.sources || []);
+  const sinks = (diagnostics.sinks || []);
+  const sourcesInFile = sources.filter(here);
+  if (sourcesInFile.length === 0 && sources.length === 0) return done('source-modelling', 'no-source-recognized', { sourcesRecognized: 0 });
+  if (sourcesInFile.length === 0) return done('source-modelling', 'no-source-in-defect-file', { sourcesRecognizedElsewhere: sources.length });
+  const wide = { lo: win.lo - 10, hi: win.hi + 10 };
+  const sinkNear = sinks.some((s) => here(s) && inWindow(s.line, wide));
+  if (!sinkNear) return done('sink-modelling', 'no-sink-recognized-near-defect', { sourcesInFile: sourcesInFile.length });
+  return done('propagation', 'source-and-sink-recognized-no-flow', { sourcesInFile: sourcesInFile.length });
+}
+
+/** Classify every miss in a score. `diagnosticsFor(targetId)` returns that target's diagnostics or null. */
+export function classifyMisses({ score, defects, run, diagnosticsFor, policy, layer }) {
+  const byId = new Map(defects.map((d) => [d.id, d]));
+  const outcomeOf = new Map((run?.outcomes || []).map((o) => [`${o.targetId}|${o.variant}`, o]));
+  const classified = [];
+  for (const miss of score.misses || []) {
+    const label = byId.get(miss.labelId);
+    if (!label) { classified.push({ labelId: miss.labelId, targetId: miss.targetId, stage: UNKNOWN, reason: 'label-not-supplied', evidence: {}, deterministic: true }); continue; }
+    classified.push(classifyMiss({ label, outcome: outcomeOf.get(`${miss.targetId}|pre`) || null, diagnostics: diagnosticsFor ? diagnosticsFor(miss.targetId) : null, policy, layer }));
+  }
+  classified.sort((a, b) => String(a.labelId).localeCompare(String(b.labelId)));
+  return classified;
+}
+
+export function stageCounts(classified) {
+  const byStage = Object.fromEntries([...STAGES, UNKNOWN].map((s) => [s, 0]));
+  const byReason = {};
+  for (const c of classified) {
+    byStage[c.stage] = (byStage[c.stage] || 0) + 1;
+    byReason[`${c.stage}:${c.reason}`] = (byReason[`${c.stage}:${c.reason}`] || 0) + 1;
+  }
+  return { total: classified.length, byStage, byReason };
+}
+
+/**
+ * Before/after view of a fix (QA-005.AC03). Recovered defects are labels that were misses before and are not after; each is
+ * listed with the stage that lost it and the finding that now matches. New false positives are named, never netted away.
+ */
+export function compareMisses({ before, after, scoreBefore, scoreAfter }) {
+  const afterMissed = new Set(after.map((c) => c.labelId));
+  const recovered = before.filter((c) => !afterMissed.has(c.labelId));
+  const fpKey = (x) => `${x.targetId}|${x.finding?.file}|${x.finding?.family}|${x.finding?.line}`;
+  const fpBefore = new Set((scoreBefore.falsePositives || []).map(fpKey));
+  const newFalsePositives = (scoreAfter.falsePositives || []).filter((x) => !fpBefore.has(fpKey(x)));
+  const verdict = recovered.length === 0 ? 'no-recovery' : newFalsePositives.length ? 'recovered-with-new-false-positives' : 'recovered-without-new-false-positives';
+  return {
+    verdict,
+    stageCounts: { before: stageCounts(before), after: stageCounts(after) },
+    recovered: recovered.map((c) => ({ labelId: c.labelId, targetId: c.targetId, lostAtStage: c.stage, reason: c.reason })),
+    falsePositives: { before: (scoreBefore.falsePositives || []).length, after: (scoreAfter.falsePositives || []).length, newFalsePositives },
+    precisionNote: 'a recovery that adds a false positive is reported as such and does not count as a clean improvement',
+  };
+}
+
+/**
+ * Re-scan the DEVELOPMENT targets that have a miss, with diagnostics on, and return `Map(targetId -> diagnostics)`.
+ * The sealed split is refused outright: its per-case outcomes are not material for detector work.
+ */
+export async function collectDiagnostics({ protocol, score, defects, resolveTarget, protectedTerms = [], scanFn = defaultScanFn, layer = 'deep-taint', timeoutMs }) {
+  const sealed = new Set(protocol.splits.sealed);
+  const missTargets = [...new Set((score.misses || []).map((m) => m.targetId))];
+  const refused = missTargets.filter((t) => sealed.has(t));
+  if (refused.length) return { ok: false, errors: [{ code: 'SEALED_ACCESS', path: 'score.misses', message: `why-missed analysis is for development misses; ${refused.length} sealed target(s) refused` }], diagnostics: new Map() };
+  const byTarget = new Map();
+  for (const d of defects) { if (!byTarget.has(d.targetId)) byTarget.set(d.targetId, []); byTarget.get(d.targetId).push(d); }
+  const out = new Map();
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'eval-diag-'));
+  try {
+    for (const targetId of missTargets.sort()) {
+      const target = protocol.targets.find((t) => t.id === targetId);
+      if (!target) continue;
+      const r = await resolveTarget(target, 'pre');
+      if (!r?.dir) continue;
+      const staged = stageWorkspace({ srcDir: r.dir, destDir: path.join(root, targetId.replace(/[^\w.-]/g, '_')), terms: protectedTerms });
+      if (!staged.ok) continue;
+      try {
+        const files = [...new Set((byTarget.get(targetId) || []).map((d) => d.location.file))];
+        const env = engineEnvironment({ PATH: process.env.PATH, LANG: 'C', HOME: root, AGENTIC_SECURITY_DIAG_FILES: JSON.stringify(files) });
+        const res = await scanFn(staged.destDir, { layer, timeoutMs: timeoutMs || protocol.limits.perTargetTimeoutMs, env, diagnose: true });
+        if (res?.diagnostics) out.set(targetId, res.diagnostics);
+      } catch { /* a target that cannot be diagnosed stays `unknown`, which is the honest answer */ } finally {
+        fs.rmSync(staged.destDir, { recursive: true, force: true });
+      }
+    }
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+  return { ok: true, errors: [], diagnostics: out };
+}

package/src/posture/fleet.js

@@ -167,6 +167,10 @@ function _provenanceDebtForRepo(findings, now = Date.now()) {
 export async function runFleet({
   repos = [], concurrency = 4, stateFile, runScan,
   resume = true, previous = null, onProgress = () => {},
+  // X-704: repositories whose every durable portfolio work unit is verified and current
+  // (portfolio/work-units.js `fullyVerifiedRepositories`). They are skipped like a resumed completed repo,
+  // and, as with a resumed repo, the skip is reported in `skipped` rather than counted as scanned.
+  portfolioVerified = [],
 } = {}) {
   if (typeof runScan !== 'function') {
     return { ok: false, reason: 'no runScan supplied' };
@@ -176,7 +180,7 @@ export async function runFleet({
   const skipped = [];
 
   const queue = repos.filter((r) => {
-    if (resume && state.completed[r]) { skipped.push(r); return false; }
+    if ((resume && state.completed[r]) || portfolioVerified.includes(r)) { skipped.push(r); return false; }
     return true;
   });
 
@@ -408,8 +412,13 @@ export function renderFleetSummary(rollup) {
     if (prov.reposWithNoProvenDebt.length) bits.push(`${prov.reposWithNoProvenDebt.length} repo(s) with no complete-status provenance`);
     provClause = ` PROVENANCE: ${bits.join('; ')}.`;
   }
+  // X-707: portfolio progress is its own clause, present only when the `portfolio-assurance` feature attached it
+  // (portfolio/progress.js `attachPortfolioProgress`), so flag-off output is byte-identical. It states verified units and
+  // repositories separately from the scan counts above: a finished controller is not a passing portfolio.
+  const pp = rollup.portfolioProgress;
+  const portfolioClause = pp ? ` PORTFOLIO: ${pp.units.verified}/${pp.units.total} unit(s) verified, ${pp.coverage.fullyVerified}/${pp.coverage.total} repo(s) fully verified, ${pp.review.pending} pending human review; ${pp.completion.statement}` : '';
   return `${head}${rollup.scanned} repo(s) scanned, ${rollup.total} finding(s)`
-    + `${sev ? ` (${sev})` : ''}, ${rollup.proven} execution-proven.${nf}${govClause}${provClause}`;
+    + `${sev ? ` (${sev})` : ''}, ${rollup.proven} execution-proven.${nf}${govClause}${provClause}${portfolioClause}`;
 }
 
 /**

package/src/posture/invariants/cli.js

@@ -0,0 +1,95 @@
+// `agentic-security invariants <export|coverage|regress>` (X-405 to X-407 CLI surface).
+//
+//   invariants export   --invariant <file> --fixture <dir> [--ledger <file>] [--commit <sha>] [--seed <n>] [--output <file>] [--json]
+//       The reproducible scenario package for one contract (see export.js). Builds nothing and runs nothing when the
+//       `invariant-scenarios` feature is off. Exit 0 ok, 1 refused (disabled, rejected, unsupported, blocked), 2 usage.
+//   invariants coverage --invariant <file> | --invariants-dir <dir> [--ledger <file>] [--results <file>] [--json]
+//       The bounded business-coverage report (see coverage.js). `--results` is a JSON array of `{ invariantId, result }` where
+//       `result` is what `verifyInvariant` returned; without it the report is the static inventory with every contract's
+//       transitions listed as untested, which is the honest answer when nothing was run. Exit 0, 1 refused, 2 usage.
+//   invariants regress  <artifact.json>
+//       Re-execute a regression artifact from the file alone (see repair.js). Exit 0 every leg settled as recorded, 1 a leg did
+//       not (or the artifact is invalid), 3 not run (a prerequisite is unmet or the feature is off): not-run is not a pass.
+//
+// The logic lives here, not in bin/, so the same functions are exercised by tests without spawning the CLI; bin/ only
+// dispatches. Paths are the operator's own and are resolved against the working directory (the MCP tool, which takes paths from
+// an agent, confines them to its session root instead).
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { resolveAssuranceConfig } from '../assurance/config.js';
+import { exportFromFiles } from './export.js';
+import { businessCoverage } from './coverage.js';
+import { runRegressionArtifact } from './repair.js';
+import { readJsonFile } from './project-input.js';
+
+const USAGE = [
+  'Usage: agentic-security invariants export   --invariant <file> --fixture <dir> [--ledger <file>] [--commit <sha>] [--seed <n>] [--output <file>] [--json]',
+  '       agentic-security invariants coverage --invariant <file> | --invariants-dir <dir> [--ledger <file>] [--results <file>] [--json]',
+  '       agentic-security invariants regress  <artifact.json>',
+].join('\n');
+
+const abs = (cwd, p) => path.resolve(cwd, String(p));
+
+/**
+ * @param {{ _: string[], flags: object }} args  parsed arguments; `_[0]` is `invariants`, `_[1]` the sub-command
+ * @param {{ cwd?: string, out?: (s: string) => void, err?: (s: string) => void, env?: object }} [io]
+ * @returns {Promise<number>} the exit code
+ */
+export async function runInvariantsCommand(args, io = {}) {
+  const cwd = io.cwd || process.cwd();
+  const out = io.out || ((s) => process.stdout.write(s));
+  const err = io.err || ((s) => process.stderr.write(s));
+  const sub = args._[1];
+  const flags = args.flags || {};
+  const config = resolveAssuranceConfig({ scanRoot: cwd, env: io.env || process.env });
+  const emit = (value, lines) => out(flags.json ? `${JSON.stringify(value, null, 2)}\n` : `${lines.join('\n')}\n`);
+
+  if (sub === 'export') {
+    if (typeof flags.invariant !== 'string' || typeof flags.fixture !== 'string') { err(`${USAGE}\n`); return 2; }
+    const r = exportFromFiles({
+      invariantPath: abs(cwd, flags.invariant), fixturePath: abs(cwd, flags.fixture), ledgerPath: typeof flags.ledger === 'string' ? abs(cwd, flags.ledger) : undefined,
+      commit: typeof flags.commit === 'string' ? flags.commit : undefined, seed: flags.seed !== undefined ? Number(flags.seed) : undefined, config,
+    });
+    if (r.status !== 'ok') { err(`agentic-security invariants export: ${r.status}: ${r.reason ?? ''}\n`); return 1; }
+    const text = `${JSON.stringify(r.export, null, 2)}\n`;
+    if (typeof flags.output === 'string') {
+      fs.writeFileSync(abs(cwd, flags.output), text);
+      out(`wrote ${r.export.scenarios.length} scenario(s) to ${flags.output}${r.withheld.length ? `; ${r.withheld.length} withheld (secret-looking content)` : ''}\n`);
+    } else out(text);
+    return 0;
+  }
+
+  if (sub === 'coverage') {
+    let files = [];
+    if (typeof flags.invariant === 'string') files = [abs(cwd, flags.invariant)];
+    else if (typeof flags['invariants-dir'] === 'string') {
+      try { files = fs.readdirSync(abs(cwd, flags['invariants-dir'])).filter((f) => f.endsWith('.json')).sort().map((f) => path.join(abs(cwd, flags['invariants-dir']), f)); } catch { err('agentic-security invariants coverage: the invariants directory is unreadable\n'); return 1; }
+    } else { err(`${USAGE}\n`); return 2; }
+    const docs = [];
+    for (const f of files) {
+      const j = readJsonFile(f);
+      if (!j.ok) { err(`agentic-security invariants coverage: ${path.basename(f)}: ${j.reason}\n`); return 1; }
+      docs.push(j.value);
+    }
+    let ledger; let results = [];
+    if (typeof flags.ledger === 'string') { const l = readJsonFile(abs(cwd, flags.ledger)); if (!l.ok) { err(`agentic-security invariants coverage: the ledger: ${l.reason}\n`); return 1; } ledger = l.value; }
+    if (typeof flags.results === 'string') { const rr = readJsonFile(abs(cwd, flags.results)); if (!rr.ok || !Array.isArray(rr.value)) { err('agentic-security invariants coverage: --results must be a JSON array of { invariantId, result }\n'); return 1; } results = rr.value; }
+    const byId = new Map(results.filter((x) => x && typeof x.invariantId === 'string').map((x) => [x.invariantId, x.result]));
+    const cov = businessCoverage({ entries: docs.map((invariant) => ({ invariant, result: byId.get(invariant.id) ?? null })), ledger });
+    emit(cov, cov.lines);
+    return 0;
+  }
+
+  if (sub === 'regress') {
+    const file = args._[2];
+    if (!file) { err(`${USAGE}\n`); return 2; }
+    const a = readJsonFile(abs(cwd, file));
+    if (!a.ok) { err(`agentic-security invariants regress: ${a.reason}\n`); return 1; }
+    const r = await runRegressionArtifact(a.value, { config });
+    emit(r, [`regression artifact: ${r.status}`, r.summary, ...r.legs.map((l) => `  ${l.matched ? 'ok ' : 'FAIL'} ${l.role}: expected ${l.expected}, got ${l.outcome ?? l.status}`)]);
+    return r.status === 'passed' ? 0 : (r.status === 'prerequisite-unmet' || r.status === 'disabled') ? 3 : 1;
+  }
+
+  err(`agentic-security invariants: unrecognized sub-command "${sub}"\n${USAGE}\n`);
+  return 2;
+}