@clear-capabilities/agentic-security-scanner 0.133.0 → 0.136.2

package/src/discovery/memory.js

@@ -0,0 +1,163 @@
+// Cross-run discovery memory — PRD Phase 3 / C4.
+//
+// WHAT WAS MISSING
+// ----------------
+// `judge.js` dedupes a hunt against `last-scan.json` and the triage ledger, so
+// it knows what the RULE ENGINE found and what a human dismissed. It has never
+// known what a PREVIOUS HUNT found. Two consequences, both bad:
+//
+//   1. Every run re-proposes, re-confirms and re-refutes the same candidates.
+//      That is three LLM calls per candidate per run, spent to rediscover
+//      something already judged — the exact waste the Phase 0 budget exists to
+//      bound, being incurred deliberately.
+//   2. A second run cannot be *additive*. Without a record of what was already
+//      examined, "hunt again" means "hunt the same thing again" rather than
+//      "hunt what we missed".
+//
+// This is that record. It turns a sequence of independent runs into a campaign.
+//
+// WHAT IS AND IS NOT REMEMBERED
+// -----------------------------
+// Remembered: every candidate ever JUDGED, with the verdict and the run that
+// produced it. Also every focus area ever hunted, so coverage can become a plan
+// instead of a report.
+//
+// NOT remembered: refuted candidates as if they were settled forever. A
+// refutation is a majority opinion from three prompts on one day, not a proof.
+// It suppresses re-reporting, and `--forget-refuted` exists precisely because a
+// verdict made by a weaker model, or before a sanitiser was removed, must be
+// re-openable. A memory you cannot clear is a memory that eventually lies.
+//
+// THE PRECEDENT THIS FOLLOWS
+// --------------------------
+// `judge.js` deliberately suppresses only `fp` triage verdicts and re-reports
+// `tp` ones, because a prior true positive that is still in the code is still a
+// bug. The same asymmetry holds here: a candidate previously judged FRESH is
+// re-reported (it was never fixed), while one previously REFUTED is held back
+// until something changes.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { stateWritesEnabled } from '../posture/state-dir.js';
+const MEMORY_SCHEMA = 'agentic-security/discovery-memory@1';
+export const MEMORY_FILE = path.join('.agentic-security', 'discovery-memory.json');
+
+function emptyMemory() {
+  return { schema: MEMORY_SCHEMA, runs: 0, candidates: {}, areas: {} };
+}
+
+/** A stable identity for a candidate across runs. */
+export function memoryKey(candidate) {
+  // Location + family, matching judge.js's PRIMARY duplicate key. Deliberately
+  // NOT stableId: that is location-fuzzy by design and collides across distinct
+  // findings in one file, which is tolerable for a single scan's dedupe and
+  // corrosive when it accumulates across every run ever made.
+  const file = candidate?.file ?? '?';
+  const line = candidate?.line ?? '?';
+  const family = candidate?.family ?? candidate?.lens ?? '?';
+  return `${file}:${line}:${family}`;
+}
+
+/** Read the memory. Anything unreadable or unrecognised yields an empty one. */
+export function loadMemory(scanRoot) {
+  try {
+    const doc = JSON.parse(fs.readFileSync(path.join(scanRoot, MEMORY_FILE), 'utf8'));
+    if (doc?.schema !== MEMORY_SCHEMA) return emptyMemory();
+    return { ...emptyMemory(), ...doc };
+  } catch {
+    // A corrupt memory must degrade to "remember nothing", never to a crash and
+    // never to a partially-trusted record. Re-hunting is cheap next to acting on
+    // a half-read ledger.
+    return emptyMemory();
+  }
+}
+
+/** Persist. Failure is non-fatal — the run still produced its report. */
+export function saveMemory(scanRoot, memory) {
+  try {
+    const p = path.join(scanRoot, MEMORY_FILE);
+    if (!stateWritesEnabled()) return;
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(memory, null, 2) + '\n');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Should this candidate be held back because a previous run already judged it?
+ *
+ * Only a REFUTED verdict suppresses. Everything else — fresh, duplicate,
+ * suppressed-by-triage — is re-evaluated, because those states are about the
+ * code and the code may have changed.
+ */
+export function previouslyRefuted(memory, candidate) {
+  const rec = memory?.candidates?.[memoryKey(candidate)];
+  return Boolean(rec && rec.verdict === 'refuted');
+}
+
+/** Fold this run's outcome into the memory. Returns a NEW memory object. */
+export function rememberRun(memory, { fresh = [], refutedCandidates = [], areas = [], at }) {
+  const next = {
+    ...emptyMemory(),
+    ...memory,
+    candidates: { ...(memory?.candidates || {}) },
+    areas: { ...(memory?.areas || {}) },
+  };
+  next.runs = (memory?.runs || 0) + 1;
+  const stamp = at || new Date().toISOString();
+
+  for (const f of fresh) {
+    next.candidates[memoryKey(f)] = { verdict: 'fresh', run: next.runs, at: stamp };
+  }
+  for (const c of refutedCandidates) {
+    next.candidates[memoryKey(c)] = { verdict: 'refuted', run: next.runs, at: stamp };
+  }
+  for (const a of areas) {
+    const prev = next.areas[a.id] || { hunts: 0 };
+    next.areas[a.id] = {
+      label: a.label,
+      hunts: prev.hunts + (a.hunted ? 1 : 0),
+      lastRun: a.hunted ? next.runs : (prev.lastRun ?? null),
+      files: a.files ?? prev.files ?? null,
+    };
+  }
+  return next;
+}
+
+/**
+ * Turn the memory into a PLAN: which areas have never been successfully hunted.
+ *
+ * This is the half that makes a second run additive rather than repetitive. A
+ * coverage report says what happened; this says what to do next.
+ */
+export function nextWavePlan(memory, areas) {
+  const unhunted = [];
+  const stale = [];
+  for (const a of areas || []) {
+    const rec = memory?.areas?.[a.id];
+    if (!rec || rec.hunts === 0) unhunted.push(a.label || a.id);
+    else if (rec.lastRun !== memory.runs) stale.push(a.label || a.id);
+  }
+  return {
+    unhunted,
+    stale,
+    // Stated as a sentence because this lands in a report a human reads, and
+    // "3 areas" without saying which ones is not actionable.
+    summary: unhunted.length
+      ? `${unhunted.length} focus area(s) have NEVER been successfully hunted: ${unhunted.slice(0, 5).join(', ')}` +
+        (unhunted.length > 5 ? `, +${unhunted.length - 5} more` : '')
+      : 'every focus area has been hunted at least once',
+  };
+}
+
+/** Drop refuted verdicts so they can be re-examined. */
+export function forgetRefuted(memory) {
+  const candidates = {};
+  for (const [k, v] of Object.entries(memory?.candidates || {})) {
+    if (v?.verdict !== 'refuted') candidates[k] = v;
+  }
+  return { ...emptyMemory(), ...memory, candidates };
+}

package/src/discovery/partition.js

@@ -0,0 +1,92 @@
+//
+// Split the codebase into disjoint focus areas so parallel hunters cannot
+// converge on the same code.
+//
+// WHY THE CALL GRAPH AND NOT DIRECTORIES: a directory split hands one
+// subsystem to several hunters whenever a feature spans folders, and hands
+// unrelated code to one hunter whenever a folder is a grab bag. Weakly-
+// connected components over call edges group code that actually talks to
+// itself, which is the unit a hunter can reason about end to end.
+//
+// FILES, NOT FUNCTIONS, ARE THE ATOM. A hunter reads whole files. If two
+// components share a file they are merged, otherwise the same source lands in
+// two hunters' context and the convergence this module exists to prevent
+// comes straight back.
+import * as crypto from 'node:crypto';
+
+export function focusAreaId(files) {
+  const canon = [...new Set(files || [])].sort().join('\n');
+  return crypto.createHash('sha256').update(canon).digest('hex').slice(0, 12);
+}
+
+// Union-find over file paths.
+function makeDSU() {
+  const parent = new Map();
+  const find = (x) => {
+    if (!parent.has(x)) parent.set(x, x);
+    let r = x;
+    while (parent.get(r) !== r) r = parent.get(r);
+    while (parent.get(x) !== r) { const n = parent.get(x); parent.set(x, r); x = n; }
+    return r;
+  };
+  const union = (a, b) => { const ra = find(a), rb = find(b); if (ra !== rb) parent.set(ra, rb); };
+  return { find, union };
+}
+
+function labelFor(files) {
+  if (files.length === 1) return files[0];
+  const parts = files[0].split('/');
+  for (let i = parts.length - 1; i > 0; i--) {
+    const prefix = parts.slice(0, i).join('/') + '/';
+    if (files.every(f => f.startsWith(prefix))) return prefix;
+  }
+  return files[0] + ` (+${files.length - 1})`;
+}
+
+export function partitionCallGraph(callGraph, opts = {}) {
+  const fns = callGraph?.functions;
+  if (!fns || typeof fns.get !== 'function' || fns.size === 0) return [];
+  const maxAreas = Number.isInteger(opts.maxAreas) && opts.maxAreas > 0 ? opts.maxAreas : 8;
+
+  const dsu = makeDSU();
+  for (const fn of fns.values()) if (fn?.file) dsu.find(fn.file);
+  for (const e of callGraph.edges || []) {
+    const a = fns.get(e?.caller)?.file;
+    const b = fns.get(e?.callee)?.file;
+    if (a && b) dsu.union(a, b);
+  }
+
+  const filesByRoot = new Map();
+  for (const fn of fns.values()) {
+    if (!fn?.file) continue;
+    const root = dsu.find(fn.file);
+    if (!filesByRoot.has(root)) filesByRoot.set(root, new Set());
+    filesByRoot.get(root).add(fn.file);
+  }
+
+  const fnsByFile = new Map();
+  for (const fn of fns.values()) {
+    if (!fn?.file) continue;
+    if (!fnsByFile.has(fn.file)) fnsByFile.set(fn.file, []);
+    fnsByFile.get(fn.file).push(fn.qid);
+  }
+
+  const build = (files, label) => {
+    const sorted = [...files].sort();
+    const functions = sorted.flatMap(f => (fnsByFile.get(f) || [])).sort();
+    return { id: focusAreaId(sorted), label: label ?? labelFor(sorted), files: sorted, functions, size: functions.length };
+  };
+
+  let areas = [...filesByRoot.values()].map(s => build(s));
+  // Deterministic ranking: biggest first, ties broken by id so two runs on the
+  // same graph produce the same order.
+  areas.sort((a, b) => b.size - a.size || (a.id < b.id ? -1 : 1));
+
+  if (areas.length > maxAreas) {
+    const kept = areas.slice(0, maxAreas - 1);
+    const tail = areas.slice(maxAreas - 1);
+    kept.push(build(tail.flatMap(a => a.files), 'misc'));
+    areas = kept;
+  }
+  return areas;
+}

package/src/engine.js

@@ -71,6 +71,8 @@ import { scanWebhook } from './sast/webhook.js';
 import { scanClientSide } from './sast/client-side.js';
 import { scanPromptFirewall } from './sast/prompt-firewall.js';
 import { scanLlmRedteam } from './posture/llm-redteam.js';
+import { assessPrivacyFramework, persistPrivacyFramework } from './posture/privacy-framework.js';
+import { safeWriteState as _safeWriteState, statePath, statePath as _statePath } from './posture/state-dir.js';
 import { scanContainer } from './sca/container.js';
 import { detectDepConfusion } from './sca/dep-confusion.js';
 import { loadLicensePolicy, evaluateLicensePolicy } from './posture/license-policy.js';
@@ -142,6 +144,7 @@ import { scanIacReachability } from './posture/iac-reachability.js';
 import { scanIamPolicies } from './posture/iam-policy.js';
 import { scanContainerRuntime } from './posture/container-runtime.js';
 import { scanBusinessLogic as scanBusinessLogicV2 } from './posture/business-logic.js';
+import { ingestLogicClaims } from './posture/logic-claims.js';
 import { annotateNarration } from './posture/flow-narration.js';
 import { applyPathConstraints } from './posture/path-predicates.js';
 // Phase 3 (Sentinel-parity Layer 1 + 2) — IR + interprocedural taint engine.
@@ -584,7 +587,16 @@ const SANITIZER_PATTERNS=[{regex:/(?:escape|escapeHtml|htmlspecialchars|encodeUR
 {regex:/(?:re\.escape|preg_quote|Regexp\.escape)\s*\(/g,type:"Regex Escaping"}];
 const ROUTE_PATTERNS=[{regex:/(?:app|router)\s*\.\s*(get|post|put|patch|delete|all|options|head)\s*\(\s*['"`]([^'"`]+)['"`]/g,fw:"Express",mI:1,pI:2},{regex:/@(?:app|blueprint|bp)\s*\.\s*route\s*\(\s*['"]([^'"]+)['"]\s*(?:,\s*methods\s*=\s*\[([^\]]+)\])?/g,fw:"Flask",pI:1,mtI:2},{regex:/path\s*\(\s*['"]([^'"]+)['"]/g,fw:"Django",pI:1},{regex:/@(?:app|router)\s*\.\s*(get|post|put|patch|delete)\s*\(\s*['"]([^'"]+)['"]/g,fw:"FastAPI",mI:1,pI:2},{regex:/Route\s*::\s*(get|post|put|patch|delete|any)\s*\(\s*['"]([^'"]+)['"]/g,fw:"Laravel",mI:1,pI:2},{regex:/router\s*\.\s*(get|post|put|patch|delete)\s*\(\s*['"]([^'"]+)['"]/g,fw:"Koa/Express",mI:1,pI:2},{regex:/\[Http(Get|Post|Put|Delete|Patch)\s*\(\s*["']?([^"'\]]*)/g,fw:"ASP.NET",mI:1,pI:2},{regex:/['"`](\/api\/[a-zA-Z0-9\/:_\-{}]+)['"`]/g,fw:"API",pI:1}];
 const AUTH_PATTERNS=[/(?:authenticate|isAuthenticated|requireAuth|passport\.authenticate|jwt\.verify|verifyToken|authMiddleware|checkAuth|protect|authorize)\s*[\(,]/gi,/(?:middleware|use)\s*\(\s*(?:auth|jwt|token|session)/gi,/(?:isAuthorized|expressJwt|security\.isAuthorized|denyAll)\s*[\(]/gi,/passport\.(?:authenticate|initialize|session)\s*\(/gi];
-const IGNORE_DIRS=new Set(["node_modules",".git","__pycache__","vendor","dist","build",".next","venv","env",".venv","target","bin","obj",".cache","coverage","bower_components","tests","test","__tests__","spec","mocks"]);
+// `.agentic-security` is OUR OWN OUTPUT and must never be scanned input.
+// (NON_MUTATING_SCAN_PRD S4.) A scan writes threat-model.json,
+// exploit-bundles.json and scan-history.json into the tree it scanned, and those
+// files contain CWE identifiers. Without this, the second scan of any directory
+// reads the first scan's conclusions as source code — measured on the
+// independent benchmark as 220 polluted trees and 544 state files carrying
+// `CWE-` strings, which silently turned an accuracy measurement into the engine
+// grading itself. Scanning our own state is never useful and is exactly how
+// output becomes input.
+const IGNORE_DIRS=new Set(["node_modules",".git","__pycache__","vendor","dist","build",".next","venv","env",".venv","target","bin","obj",".cache","coverage","bower_components","tests","test","__tests__","spec","mocks",".agentic-security"]);
 const CODE_EXTS=new Set(["js","jsx","ts","tsx","mjs","cjs","py","rb","php","java","go","cs","rs","vue","svelte","html","htm","ejs","hbs","pug","erb","twig","graphql","gql","kt","scala","swift","dart","ex","exs","tf","tfvars","dockerfile","c","cc","cpp","cxx","h","hh","hpp","hxx","sol"]);
 // Feat-2: IaC manifest filenames that aren't extension-based.
 const IAC_FILENAMES = new Set(['Dockerfile', 'Containerfile', 'docker-compose.yml', 'docker-compose.yaml', 'Chart.yaml']);
@@ -2293,6 +2305,80 @@ function _resetSuppressions(){ _suppressionLog.length = 0; }
 function _pfrMetaOnly(ta){ if(!ta||typeof ta!=='object')return {}; const o={}; for(const k of Object.keys(ta)){ if(k==='findings'||k==='sources'||k==='sinks'||k==='sanitizers')continue; o[k]=ta[k]; } return o; }
 function _getSuppressions(){ return [..._suppressionLog]; }
 
+// ── inline suppression pragma ───────────────────────────────────────────────
+//
+// `// agentic-security-ignore: <rule-id>` on the offending line. This is
+// documented in the root CLAUDE.md and `pr-comment.js` tells every reviewer to
+// use it — and until now NOTHING implemented it. A suppression mechanism that
+// silently does nothing is worse than not having one: a developer writes the
+// pragma, sees the finding again, and concludes the scanner is noisy rather
+// than that the pragma is dead.
+//
+// MATCHED ON THE LINE, AND ON THE RULE. A bare pragma with no rule id
+// suppresses every finding on that line; with an id it suppresses only findings
+// whose id, vuln or CWE contains it. Line-scoped rather than file-scoped on
+// purpose — a file-wide opt-out is how a whole module quietly leaves coverage.
+//
+// EVERY SUPPRESSION IS LOGGED to the same ledger custom rules use, so
+// `--include-suppressed` and the suppression summary show them. A suppression
+// nobody can see is indistinguishable from a finding that never fired.
+const _IGNORE_PRAGMA_RE = /(?:\/\/|#|\/\*|<!--)\s*agentic-security-ignore\s*:?\s*([^\n*]*?)\s*(?:\*\/|-->)?\s*$/;
+
+function _pragmaOnLine(content, line){
+  if (typeof content !== 'string' || !Number.isInteger(line) || line < 1) return null;
+  const lines = content.split('\n');
+  if (line > lines.length) return null;
+  const m = lines[line - 1].match(_IGNORE_PRAGMA_RE);
+  if (!m) return null;
+  return { rule: (m[1] || '').trim() };
+}
+
+function _pragmaSuppresses(pragma, f){
+  if (!pragma) return false;
+  if (!pragma.rule) return true;              // bare pragma: this line, any rule
+  const want = pragma.rule.toLowerCase();
+  const hay = `${f.id || ''} ${f.vuln || ''} ${f.cwe || ''} ${f.family || ''}`.toLowerCase();
+  return hay.includes(want);
+}
+
+// Filter one findings array in place. Returns the number removed.
+// Filter one findings array in place against inline pragmas. Returns the count.
+//
+// CALLED TWICE per scan, deliberately: once after the cross-file passes and
+// again after deep-mode IR findings are appended. See both call sites.
+//
+// KNOWN LIMITATION — a finding with no integer `line` can never be suppressed.
+// The guard below skips it, because a line-scoped pragma has nothing to match
+// against. This is not hypothetical: `struct:` detectors emit findings with no
+// `line` property at all (the line survives only inside the id string, e.g.
+// `struct:app.js:22:Mass_Assignment`), so a false positive from one of those
+// cannot be silenced by a pragma and has to be fixed at the source instead.
+//
+// A file-scoped fallback was considered and REJECTED. Widening a line pragma to
+// a whole file would silently suppress findings the author never looked at, and
+// silent over-suppression in a security tool is worse than the gap it closes.
+// The real fix is for struct detectors to carry a `line`; that changes finding
+// output repo-wide, moves the self-scan baseline, and belongs in its own change.
+function _applyIgnorePragmas(arr, fc){
+  if (!Array.isArray(arr)) return 0;
+  let removed = 0;
+  for (let i = arr.length - 1; i >= 0; i--) {
+    const f = arr[i];
+    const file = f && (f.file || f.sink?.file);
+    const line = f && Number(f.line ?? f.sink?.line);
+    if (!file || !Number.isInteger(line)) continue;
+    const pragma = _pragmaOnLine(fc[file], line);
+    if (!_pragmaSuppresses(pragma, f)) continue;
+    _suppressionLog.push({
+      vuln: f.vuln, file, line, snippet: f.snippet || '',
+      reason: `inline pragma: agentic-security-ignore${pragma.rule ? ': ' + pragma.rule : ''}`,
+    });
+    arr.splice(i, 1);
+    removed++;
+  }
+  return removed;
+}
+
 // FP-9 / Feat-4: custom rules loaded from .agentic-security/rules.{yml,yaml,json}
 // at scan root. Mutates SOURCE/SINK/SANITIZER pattern arrays in place when active;
 // snapshot lengths from the first call so subsequent scans can restore baseline.
@@ -2326,7 +2412,7 @@ async function _loadCustomRules(scanRoot){
   _customIgnorePaths = [];
   let raw = null, parsedObj = null;
   for (const ext of ['rules.yml', 'rules.yaml', 'rules.json']) {
-    const p = path.join(scanRoot, '.agentic-security', ext);
+    const p = statePath(scanRoot, ext);
     try { raw = fs.readFileSync(p, 'utf8'); } catch { continue; }
     try {
       if (ext.endsWith('.json')) parsedObj = JSON.parse(raw);
@@ -7894,6 +7980,18 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
   // AGENTIC_SECURITY_TREE_SITTER=1; degrades to no-op without the optional dep).
   if(process.env.AGENTIC_SECURITY_TREE_SITTER==='1'){try{aF.push(...await scanTreeSitterSinks(fc));}catch(_){}}
   let finalFindings;try{finalFindings=dedupeFindingsWithEvidence(aF);}catch(_){finalFindings=dd(aF,f=>f.id);}
+  // Inline `agentic-security-ignore` pragmas, pass 1 of 2. This covers every
+  // finding that exists BY THIS POINT — the pattern detectors, the cross-file
+  // passes, and the logic and secrets buckets, which are the ones a developer
+  // is most likely to want silenced on a specific line.
+  //
+  // It does NOT cover deep-mode IR findings: those are appended much further
+  // down (search `finalFindings.push(...irFindings)`), so a second pass runs
+  // there. For years this call carried a comment claiming it ran "after every
+  // cross-file pass has appended", which was false for the deep path — a
+  // correctly-formed pragma on the exact line of an ir-taint finding did
+  // nothing, silently, in the mode the CLI actually uses.
+  try{ _applyIgnorePragmas(finalFindings, fc); _applyIgnorePragmas(aLogic, fc); _applyIgnorePragmas(aSecrets, fc); }catch(_){}
   // #1 — centralized SSRF/path guard recognition: drop CWE-918/CWE-22 findings
   // on code hardened by a host allow/deny check or a path containment guard,
   // regardless of which detector emitted them. Opt out: AGENTIC_SECURITY_NO_GUARD_RECOGNITION=1.
@@ -7995,6 +8093,7 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
   // can tell "didn't run" from "ran cleanly." The array is surfaced as
   // scan.annotatorErrors in the report; an empty array means clean.
   let _executionProofSummary = null, _vulnHistory = null;
+  let _logicClaims = null;
   const _annotatorErrors = [];
   const _runAnnotator = (phase, fn) => {
     try { return fn(); }
@@ -8123,7 +8222,7 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
         if (r && r.piiFields) {
           try {
             const dpia = emitDpiaArtifact(r.piiFields, r.findings || []);
-            fs.writeFileSync(path.join(scanRoot, '.agentic-security', 'dpia.md'), dpia);
+            _safeWriteState(_statePath(scanRoot, 'dpia.md'), dpia);
           } catch (_) {}
         }
       });
@@ -8372,6 +8471,18 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
         f.validator_verdict = 'unvalidated';
       }
       finalFindings.push(...irFindings);
+      // Pragma pass 2 of 2 — see the pass-1 comment far above. Deep-mode IR
+      // findings land here, long after pass 1 ran, so without this an
+      // `agentic-security-ignore` on an ir-taint finding is inert. Deep mode is
+      // what the CLI uses outside CI and taint findings are the ones users most
+      // want to silence, so the documented feature did nothing in the case that
+      // mattered most.
+      //
+      // Re-running over the already-filtered array is safe and does not
+      // double-log: pass 1's removals are gone from `finalFindings`, so only the
+      // newly-appended IR findings can match here, and each suppression reaches
+      // the ledger exactly once.
+      try{ _applyIgnorePragmas(finalFindings, fc); }catch(_){}
       // Java SCA enrichment: use deep-mode IR call graph to improve Java function reachability
       try {
         for (const sc of supplyChain) {
@@ -8465,6 +8576,25 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
   catch (e) { _annotatorErrors.push({ phase: '_enrichWithScorecard', err: String((e && e.message) || e) }); }
   // 0.8.0 Feat-10: license policy
   try{const lp=loadLicensePolicy(scanRoot);if(lp){const lv=evaluateLicensePolicy(annotatedComponents,lp);aLogic.push(...lv);}}catch(_){}
+  // PRD Epic 6: business-logic claims from a reviewing agent, put through the
+  // deterministic refutation lenses before they are allowed anywhere near the
+  // report. A claim citing a file that was never scanned, misquoting the code,
+  // or contradicted by the handler it names comes back quarantined. Refuted
+  // claims are KEPT — the tier's contract is recall-preserving, same as
+  // falsification's — so the reader can see what the reviewer said and why no
+  // second party could corroborate it.
+  try {
+    if (scanRoot) {
+      const raw = fs.readFileSync(statePath(scanRoot, 'logic-claims.json'), 'utf8');
+      const parsed = JSON.parse(raw);
+      const incoming = Array.isArray(parsed) ? parsed : (parsed && parsed.claims) || [];
+      if (incoming.length) {
+        const r = ingestLogicClaims(incoming, { fileContents: fc });
+        _logicClaims = r.summary;
+        aLogic.push(...r.claims);
+      }
+    }
+  } catch(_) { /* absent or unreadable → the tier simply contributes nothing */ }
   // Phase 4 / Item 7 of the SCA improvement plan: load sca-policy.yml and
   // apply accept-risk / SLA / major-version-freeze rules. supplyChain
   // findings get suppressed/tagged in place.
@@ -8651,6 +8781,7 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
   // Each is opt-in via env var. They produce machine-readable artifacts
   // (threat-model.json/.md, dpia.md, compliance-evidence.json/.md,
   // sbom-history/<sha>.json, exploit-bundles/) under .agentic-security/.
+  let _privacyFramework = null;
   let _threatModel = null, _apiContractFindings = [], _sbomDiff = null,
       _complianceReport = null, _exploitBundles = null, _pqcPlan = null,
       _licenseGraph = null, _attributions = null, _taxonomySummary = null;
@@ -8718,6 +8849,29 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
         if (_pqcPlan) persistPqcPlan(scanRoot, _pqcPlan);
       } catch (_) {}
     }
+    // NIST Privacy Framework 1.1 assessment.
+    //
+    // The ASSESSMENT is default-on and lands on `scan.privacyFramework`, like
+    // every other posture artifact. Its FINDINGS are opt-in
+    // (AGENTIC_SECURITY_PRIVACY_FRAMEWORK=1), because appending them to
+    // scan.findings would change every severity count, gate verdict and
+    // baseline in every downstream consumer — a compliance opinion should not
+    // silently become a build failure for projects that never asked for it.
+    // Turn them on and they flow through triage and /fix like any finding.
+    if (process.env.AGENTIC_SECURITY_NO_PRIVACY_FRAMEWORK !== '1') {
+      try {
+        _privacyFramework = assessPrivacyFramework(scanRoot, {
+          findings: finalFindings, components: annotatedComponents,
+          // filesScanned feeds the vacuous-satisfaction guard: a clean signal
+          // from a run that read no files is not evidence of compliance.
+          filesScanned: files.length,
+        });
+        if (_privacyFramework) persistPrivacyFramework(scanRoot, _privacyFramework);
+        if (_privacyFramework && process.env.AGENTIC_SECURITY_PRIVACY_FRAMEWORK === '1') {
+          finalFindings.push(..._privacyFramework.findings);
+        }
+      } catch (_) {}
+    }
     // Exploit bundles — per-family PoC + Jest + pytest + remediation for
     // top-N critical/high findings.
     if (process.env.AGENTIC_SECURITY_NO_EXPLOIT_BUNDLES !== '1') {
@@ -8726,9 +8880,11 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
         if (bundles.size) {
           _exploitBundles = {};
           for (const [id, b] of bundles) _exploitBundles[id] = b;
-          const bundlePath = path.join(scanRoot, '.agentic-security', 'exploit-bundles.json');
-          try { fs.mkdirSync(path.dirname(bundlePath), { recursive: true }); } catch {}
-          try { fs.writeFileSync(bundlePath, JSON.stringify(_exploitBundles, null, 2)); } catch {}
+          // Through the seam, so `--no-state` withholds the artifact. The
+          // bundles stay on the scan result either way — a read-only scan must
+          // report the same thing, it just must not leave it behind.
+          _safeWriteState(_statePath(scanRoot, 'exploit-bundles.json'),
+            JSON.stringify(_exploitBundles, null, 2));
         }
       } catch (_) {}
     }
@@ -8762,7 +8918,7 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
   // Addition #3 — root-cause sweep: from confirmed findings, find sibling instances
   // detectors missed, with total-count accounting. Confirmed-only (cheap by default).
   let _rootCauseSweep = null; try { _rootCauseSweep = sweepRootCauses(finalFindings, fc); } catch { _rootCauseSweep = null; }
-  return{entrypointInventory:_entrypointInventory,rootCauseSweep:_rootCauseSweep,routes:dd(aR,r=>`${r.method}:${r.path}:${r.file}:${r.line}`),findings:finalFindings,sources:aSrc,sinks:aSink,sanitizers:aSan,filesScanned:files.length,crossFileCount:cf.length,logicVulns:aLogic,supplyChain,components:annotatedComponents,secrets:aSecrets,ciphers:{atRest:aCiphersRest,inTransit:aCiphersTransit},pfr,fc,suppressions:_getSuppressions(),_v3,_scanMeta,_engineErrors:{cppDataflowParseErrors:_cppDataflowParseErrors.value},annotatorErrors:_annotatorErrors,executionProof:_executionProofSummary,vulnHistory:_vulnHistory,threatModel:_threatModel,sbomDiff:_sbomDiff,complianceReport:_complianceReport,exploitBundles:_exploitBundles,pqcPlan:_pqcPlan,licenseGraph:_licenseGraph,attributions:_attributions,attackTaxonomy:_taxonomySummary};}
+  return{entrypointInventory:_entrypointInventory,rootCauseSweep:_rootCauseSweep,routes:dd(aR,r=>`${r.method}:${r.path}:${r.file}:${r.line}`),findings:finalFindings,sources:aSrc,sinks:aSink,sanitizers:aSan,filesScanned:files.length,crossFileCount:cf.length,logicVulns:aLogic,supplyChain,components:annotatedComponents,secrets:aSecrets,ciphers:{atRest:aCiphersRest,inTransit:aCiphersTransit},pfr,fc,suppressions:_getSuppressions(),_v3,_scanMeta,_engineErrors:{cppDataflowParseErrors:_cppDataflowParseErrors.value},annotatorErrors:_annotatorErrors,executionProof:_executionProofSummary,logicClaims:_logicClaims,vulnHistory:_vulnHistory,threatModel:_threatModel,privacyFramework:_privacyFramework,sbomDiff:_sbomDiff,complianceReport:_complianceReport,exploitBundles:_exploitBundles,pqcPlan:_pqcPlan,licenseGraph:_licenseGraph,attributions:_attributions,attackTaxonomy:_taxonomySummary};}
 
 // Post-aggregation classification: every source becomes "unsafe"|"safe"; every sink becomes "confirmed"|"safe".
 // Orphans (no finding linkage) are bucketed by file-local heuristic so the UI shows binary states only.

package/src/integrations/tickets.js

@@ -19,17 +19,18 @@ import * as cp from 'node:child_process';
 import { buildJiraIssue } from './index.js';
 import { escapeMarkdown } from '../util/untrusted.js';
 
-function statePath(scanRoot) {
-  return path.join(scanRoot, '.agentic-security', 'tickets.json');
+import { statePath } from '../posture/state-dir.js';
+function _ticketsPath(scanRoot) {
+  return statePath(scanRoot, 'tickets.json');
 }
 export function readState(scanRoot) {
-  const fp = statePath(scanRoot);
+  const fp = _ticketsPath(scanRoot);
   if (!fs.existsSync(fp)) return {};
   try { return JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { return {}; }
 }
 function writeState(scanRoot, state) {
-  fs.mkdirSync(path.dirname(statePath(scanRoot)), { recursive: true });
-  fs.writeFileSync(statePath(scanRoot), JSON.stringify(state, null, 2));
+  fs.mkdirSync(path.dirname(_ticketsPath(scanRoot)), { recursive: true });
+  fs.writeFileSync(_ticketsPath(scanRoot), JSON.stringify(state, null, 2));
 }
 
 function findingTitle(f) {
@@ -148,7 +149,7 @@ const SEV_RANK = { critical: 4, high: 3, medium: 2, low: 1, info: 0 };
 
 export async function syncTickets({ scanRoot, provider, severity = 'high', repo, teamId, dryRun = false }) {
   const minRank = SEV_RANK[severity] ?? 3;
-  const lastScanPath = path.join(scanRoot, '.agentic-security', 'last-scan.json');
+  const lastScanPath = statePath(scanRoot, 'last-scan.json');
   if (!fs.existsSync(lastScanPath)) return { ok: false, error: 'no last-scan.json — run a scan first' };
   const last = JSON.parse(fs.readFileSync(lastScanPath, 'utf8'));
   const allFindings = [...(last.findings || []), ...(last.secrets || []), ...(last.supplyChain || [])];

package/src/ir/ir-stats.js

@@ -4,7 +4,7 @@
 // language, how many of the files we claim to support did we actually turn
 // into IR? That is the difference between recognising an extension and
 // supporting a language, and it is the headline metric of the proof corpus
-// bench (docs/PROOF_CORPUS_PRD.md §5.4).
+// bench (the Proof Corpus PRD §5.4 (removed post-implementation)).
 //
 // Enable by setting AGENTIC_SECURITY_IR_STATS to an output path. The sidecar
 // deliberately contains NO timestamp so two runs over identical input produce

package/src/ir/parser-cpp.js

@@ -1,7 +1,7 @@
 // C / C++ IR frontend.
 //
 // Hand-rolled, following the parser-cs.js / parser-go.js template. See
-// docs/PROOF_CORPUS_PRD.md §6.3 for why this is not tree-sitter or libclang:
+// the Proof Corpus PRD §6.3 (removed post-implementation) for why this is not tree-sitter or libclang:
 // the build excludes the tree-sitter deps from the bundle, and libclang would
 // require native bindings plus a compile database we deliberately never build.
 //

package/src/leaderboard.js

@@ -27,6 +27,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { summarizeForBadge } from './badge.js';
 
+import { statePath } from './posture/state-dir.js';
 // Grade thresholds. Critical findings dominate; high/medium contribute
 // secondarily. These numbers are heuristic — calibrate against the
 // public leaderboard corpus once data lands.
@@ -90,7 +91,7 @@ function _deltaTrend(history) {
  */
 export function leaderboardRowFor({ scanRoot, repo, badgeBase = 'https://agentic-security.dev/badge' } = {}) {
   if (!repo) throw new Error('leaderboardRowFor: repo slug is required');
-  const lastScanPath = path.join(scanRoot || '.', '.agentic-security', 'last-scan.json');
+  const lastScanPath = statePath(scanRoot || '.', 'last-scan.json');
   let scan = null;
   try { scan = JSON.parse(fs.readFileSync(lastScanPath, 'utf8')); } catch {}
   const summary = summarizeForBadge(scan);
@@ -98,7 +99,7 @@ export function leaderboardRowFor({ scanRoot, repo, badgeBase = 'https://agentic
   const topCwe = _topCwe(scan);
 
   // Optional scan history for the trend signal.
-  const historyPath = path.join(scanRoot || '.', '.agentic-security', 'scan-history.jsonl');
+  const historyPath = statePath(scanRoot || '.', 'scan-history.jsonl');
   let history = [];
   if (fs.existsSync(historyPath)) {
     try {

package/src/llm-validator/consistency.js

@@ -24,6 +24,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { validateOne } from './index.js';
 
+import { statePath, stateWritesEnabled } from '../posture/state-dir.js';
 // Build a deterministic test finding from the project's last-scan.json,
 // or accept a hand-crafted one. Returns a clone safe to mutate per trial.
 export function makeTrialFinding(template) {
@@ -60,9 +61,12 @@ export async function measureConsistency({
       // If useCache is false, we want each trial to bypass the cache; we
       // simulate by mutating the finding's file in a way the cache key
       // hashes over. Simpler: clear the per-scanRoot cache before each trial.
-      if (!useCache && scanRoot) {
+      // `stateWritesEnabled()` gates the DELETE as well as any write: removing
+      // files from the scanned tree is a mutation like any other, and under a
+      // read-only scan there is no cache to clear anyway. (PRD M1)
+      if (!useCache && scanRoot && stateWritesEnabled()) {
         try {
-          const cacheDir = path.join(scanRoot, '.agentic-security', 'llm-cache');
+          const cacheDir = statePath(scanRoot, 'llm-cache');
           if (fs.existsSync(cacheDir)) {
             for (const e of fs.readdirSync(cacheDir)) fs.unlinkSync(path.join(cacheDir, e));
           }