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

package/src/discovery/llm-invoke.js

@@ -13,7 +13,11 @@ export async function defaultLlmInvoke(prompt, opts = {}) {
   // variable they set. Reaching it is this module's entire purpose; no
   // request-controlled input exists anywhere on this path, and an operator who
   // can set this variable can already run code.
-  const res = await fetch(process.env.AGENTIC_SECURITY_LLM_ENDPOINT, { // agentic-security-ignore: CWE-918
+  // `opts.endpoint` lets the consensus caller target one specific provider.
+  // Absent, it falls back to the single configured endpoint — so the ordinary
+  // single-model path is byte-identical to what it was before consensus existed.
+  const endpoint = opts.endpoint || process.env.AGENTIC_SECURITY_LLM_ENDPOINT;
+  const res = await fetch(endpoint, { // agentic-security-ignore: CWE-918
     method: 'POST',
     headers: { 'content-type': 'application/json' },
     body: JSON.stringify({ prompt }),
@@ -24,8 +28,93 @@ export async function defaultLlmInvoke(prompt, opts = {}) {
   return typeof body === 'string' ? body : (body?.text ?? JSON.stringify(body));
 }
 
+// --- PRD Phase 3 / C2: multi-model consensus --------------------------------
+//
+// One model's opinion is one model's opinion. Asking several INDEPENDENT
+// endpoints the same question and keeping only what a majority agree on
+// collapses the idiosyncratic failures of any single one — a model that
+// hallucinates a sink, or that is simply having a bad day on a prompt shape.
+//
+// WHY IT LIVES HERE AND NOWHERE ELSE. Every LLM call in the discovery layer
+// already funnels through `resolveLlmInvoke`. Consensus is therefore a property
+// of the seam, not of the hunter or the panel, and adding a provider cannot
+// require touching either.
+//
+// WHAT CONSENSUS DOES AND DOES NOT MEAN. It reduces variance. It does NOT make
+// the answer true — three models can agree and all be wrong, which is precisely
+// why the deterministic confirmation gate still runs afterwards and still sets
+// severity. Consensus is a noise filter in front of the real check, never a
+// replacement for it.
+//
+// A provider that errors is EXCLUDED from the vote, not counted as dissent —
+// the same rule `disprove.js` applies to its voters, for the same reason: an
+// outage must never look like disagreement.
+// Internal: read by resolveLlmInvoke below. Exporting it with no external
+// caller is shipped dead code by the dead-module guard's definition.
+const DEFAULT_CONSENSUS_ENV = 'AGENTIC_SECURITY_LLM_ENDPOINTS';
+
+/** Split a comma-separated endpoint list into distinct URLs. */
+export function parseEndpoints(raw) {
+  return String(raw || '')
+    .split(',')
+    .map(s => s.trim())
+    .filter(Boolean)
+    .filter((v, i, a) => a.indexOf(v) === i); // duplicates would fake agreement
+}
+
+/**
+ * Combine N responses into one, keeping the most common answer.
+ *
+ * Ties are resolved towards the FIRST endpoint listed, deterministically, rather
+ * than arbitrarily — a caller ordering their endpoints by trust should get the
+ * behaviour that ordering implies, and a random tie-break would make the whole
+ * pipeline non-reproducible.
+ */
+export function consensusOf(responses) {
+  const usable = (responses || []).filter(r => typeof r === 'string' && r.trim());
+  if (usable.length === 0) return { value: null, agreement: 0, voters: 0 };
+  const counts = new Map();
+  for (const r of usable) counts.set(r, (counts.get(r) || 0) + 1);
+  let best = usable[0];
+  let bestCount = counts.get(best);
+  for (const r of usable) {
+    const c = counts.get(r);
+    if (c > bestCount) { best = r; bestCount = c; }
+  }
+  return { value: best, agreement: bestCount / usable.length, voters: usable.length };
+}
+
+/**
+ * An llmInvoke that queries several endpoints and returns the consensus answer.
+ * Returns null when no endpoint answered — the callers already treat a null or
+ * a throw as degradation, so an all-providers-down run degrades honestly.
+ */
+function makeConsensusInvoke(endpoints, { timeoutMs } = {}) {
+  const list = parseEndpoints(endpoints);
+  if (list.length === 0) return null;
+  return async (prompt) => {
+    const answers = await Promise.all(list.map(async (url) => {
+      try { return await defaultLlmInvoke(prompt, { timeoutMs, endpoint: url }); }
+      catch { return null; } // excluded from the vote, never counted as dissent
+    }));
+    const { value } = consensusOf(answers);
+    if (value === null) throw new Error('no LLM endpoint answered');
+    return value;
+  };
+}
+
 export function resolveLlmInvoke(opts = {}) {
+  // Precedence, most explicit first: an injected callback beats configuration,
+  // and a multi-endpoint list beats a single endpoint. A caller who supplied
+  // their own function must always get exactly that function.
   if (opts.llmInvoke) return opts.llmInvoke;
+
+  const multi = opts.endpoints || process.env[DEFAULT_CONSENSUS_ENV];
+  if (multi) {
+    const consensus = makeConsensusInvoke(multi, { timeoutMs: opts.timeoutMs });
+    if (consensus) return consensus;
+  }
+
   if (!process.env.AGENTIC_SECURITY_LLM_ENDPOINT) return null;
   return (prompt) => defaultLlmInvoke(prompt, { timeoutMs: opts.timeoutMs });
 }

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/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';
@@ -585,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']);
@@ -2401,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);
@@ -8211,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 (_) {}
         }
       });
@@ -8574,7 +8585,7 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
   // second party could corroborate it.
   try {
     if (scanRoot) {
-      const raw = fs.readFileSync(path.join(scanRoot, '.agentic-security', 'logic-claims.json'), 'utf8');
+      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) {
@@ -8770,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;
@@ -8837,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') {
@@ -8845,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 (_) {}
     }
@@ -8881,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,logicClaims:_logicClaims,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));
           }

package/src/llm-validator/index.js

@@ -64,7 +64,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
-import { statePath, ensureStateDir, safeWriteState } from '../posture/state-dir.js';
+import { ensureStateDir, safeWriteState, statePath } from '../posture/state-dir.js';
 import { redactSecrets } from './redact.js';
 import { signLastScan } from '../posture/integrity.js';
 
@@ -84,7 +84,6 @@ const MAX_OUTPUT_TOKENS = 512;
 let _localPresetRefusal = null;
 
 export const PROMPT_VERSION = 'v2.0-hardened';
-const CACHE_DIR = '.agentic-security/llm-cache';
 
 // System preamble — embeds a per-request challenge token the model MUST
 // echo, and a strict instruction-priority frame. {{challenge}} and {{nonce}}

package/src/mcp/audit.js

@@ -27,6 +27,7 @@ import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { redactArgsBlob } from './redact.js';
 
+import { stateDir } from '../posture/state-dir.js';
 const MAX_ARG_BYTES = 1024;
 const GENESIS = 'GENESIS';
 const REMOTE_TIMEOUT_MS = 1500;
@@ -87,7 +88,7 @@ export function auditCall({ sessionRoot, tool, args, outcome, reason }) {
     let hasMarker = false;
     for (const m of MARKERS) { try { if (fs.existsSync(path.join(sessionRoot, m))) { hasMarker = true; break; } } catch {} }
     if (!hasMarker) return;
-    const dir = path.join(sessionRoot, '.agentic-security');
+    const dir = stateDir(sessionRoot);
     fs.mkdirSync(dir, { recursive: true });
     const logFile = path.join(dir, 'mcp-audit.log');
     const entry = {

package/src/mcp/tools.js

@@ -157,7 +157,7 @@ function _scratchpadAbs(sessionRoot, relPath) {
 }
 
 function _scratchpadTotalBytes(sessionRoot) {
-  const base = path.join(sessionRoot, '.agentic-security', 'agent-scratchpad');
+  const base = statePath(sessionRoot, 'agent-scratchpad');
   if (!fs.existsSync(base)) return 0;
   let total = 0;
   const walk = (dir) => {
@@ -222,8 +222,8 @@ function _confine(sessionRoot, candidate, label) {
 }
 
 function _readLastScanVerified(sessionRoot, { allowUnsigned = false } = {}) {
-  const stateDir = path.join(sessionRoot, '.agentic-security');
-  const scanFile = path.join(stateDir, 'last-scan.json');
+  const stateDirPath = stateDir(sessionRoot);
+  const scanFile = path.join(stateDirPath, 'last-scan.json');
   const sigFile = scanFile + '.sig';
   if (!fs.existsSync(scanFile)) return { scan: null, status: 'missing' };
   const body = fs.readFileSync(scanFile, 'utf8');
@@ -1013,6 +1013,7 @@ export const read_scratchpad = {
 import { appendAgentsMemory as _appendAgentsMemory, readAgentsMemory as _readAgentsMemory } from '../posture/agents-memory.js';
 import { lookupCve as _lookupCve } from '../posture/cve-lookup.js';
 
+import { stateDir, statePath } from '../posture/state-dir.js';
 export const append_agents_memory = {
   name: 'append_agents_memory',
   description: 'Append a short narrative entry to AGENTS.md — agent-authored continual-learning notes. Use at session end to record "what worked / what didn\'t / what I\'d try differently next time" so the next agent can pick up the lesson. Bounded: 2 KB per entry, 20 KB total before rotation to AGENTS.md.archive. Use sparingly — narrative, not structured data.',

package/src/posture/CLAUDE.md

@@ -44,7 +44,7 @@ rather than creating a stray state dir outside a project.
 
 **Agentic verification** — `verifier.js`, `verifier-target.js`, `verifier-ephemeral.js`, `harness-discovery.js`, `adversary-agent.js`, `defender-agent.js`, `auditor-agent.js`, `three-agent-pipeline.js`.
 
-**Methodology additions (`docs/AGENTIC_METHODOLOGY_PRD.md`)** — default-on annotators/artifacts that layer the agentic-hunter methodology on the deterministic engine:
+**Methodology additions (Agentic Methodology PRD, removed post-implementation)** — default-on annotators/artifacts that layer the agentic-hunter methodology on the deterministic engine:
 - `falsification.js` — default falsification pass. For each taint-style finding, tries to DISPROVE it (locate a context-matched control on the path, reusing `dataflow/sanitizer-proof.js`'s shape rules read-only); a blocked finding is demoted + `quarantined`, never removed and never severity-touched (recall-preserving, like `proof-gate`). Wired after `annotateProofGate`. Opt out: `AGENTIC_SECURITY_NO_FALSIFICATION=1`. Optional LLM tier over survivors when an endpoint is configured.
 - `entrypoint-inventory.js` — attack-surface completeness ledger. Enumerates every entry point (HTTP/queue/cron/CLI/env/upload/webhook) with a disposition each; on `scan.entrypointInventory`.
 - `root-cause-sweep.js` — from confirmed findings, finds sibling instances detectors missed with total-count accounting (`found === candidates + mitigated`); on `scan.rootCauseSweep`. Searches the corpus **once per distinct sink pattern**, not once per finding — findings deriving the same pattern share one walk and one set of (read-only) match records. The counts are always exact; the materialised `instances` list is a bounded sample (`INSTANCE_SAMPLE_LIMIT`, 100) and says so via `instancesTruncated`. Both properties are load-bearing on large corpora: the per-finding walk was O(findings × corpus-bytes) and the instance records were O(findings × matches), which together exhausted a 6 GB heap on a 40k-file suite. If you touch this module, keep the own-site exclusion **per pattern group** — resolving it globally makes a group subtract an exclusion it never matched and drives counts negative.
@@ -80,6 +80,31 @@ Wired in `bin/agentic-security.js` after every filter and after `makeDeterminist
 
 **Rule lifecycle** — `custom-rules.js` (YAML pattern DSL), `rule-overrides.js` (`disable:` gated on signature), `rule-packs.js`, `rule-synthesis.js` (proposes suppressions from triage feedback), `ruleset-version.js`.
 
+**NIST Privacy Framework 1.1 (`privacy-framework.js`)** — assessment + remediation
+over the bundled `compliance-frameworks/nist-privacy-1-1.json` (all 104 controls).
+Sits on top of `auditor-walkthrough.js`'s evaluator and adds the half a narrative
+cannot give you: a gap becomes a FINDING (`family: privacy-compliance`,
+`CWE-359`) carrying an actionable remediation, so it flows through triage and
+`/fix`.
+
+Four buckets, and the bucket is always stated: `gap` (mapped signal failing —
+the ONLY bucket that emits a finding), `engine-gap` (NIST rates it code-testable
+but this engine has no signal — disclosed by name, never a pass), `manual` (NIST
+rates it not code-testable), `satisfied`. NIST's own `codeTestable` rating is
+carried per control and is what separates "nobody checked" from "we checked and
+it is fine" — 48 of 104 are governance controls no scanner can assess, and
+reporting those as passed is the failure mode the module exists to prevent.
+
+Two guards are load-bearing. **Findings are opt-in**
+(`AGENTIC_SECURITY_PRIVACY_FRAMEWORK=1`); the assessment always lands on
+`scan.privacyFramework` and at `.agentic-security/privacy-framework.{json,md}`,
+but appending to `scan.findings` by default would change every severity count
+and gate verdict downstream. And the **vacuous-satisfaction guard**: a
+`family:`-mapped control clears when no findings of that family are open, which
+is also true of a scan that read zero files — so when nothing was examined every
+mapped control degrades to `engine-gap` instead of reporting as satisfied. That
+one was caught by the module's own test, not in review.
+
 **Posture artifacts** — `sbom.js`, `aibom.js`, `api-inventory.js`, `threat-model.js`, `trust-boundary-diagram.js`, `stack-playbook.js`, `deploy-platform.js`, `license-policy.js`, `material-change.js`, `mttr.js`, `streak.js`, `scorecard.js`, `security-trend.js`.
 
 **Why this fired** — `why-fired.js`. Runs LAST so it reflects every annotation. Customer-facing provenance.