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

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';
 
@@ -73,6 +73,7 @@ import { signLastScan } from '../posture/integrity.js';
 // doesn't have to reach through the `_internal` underscore-prefixed export.
 import { createCostLedger, parseCapUsd, renderCostCeiling } from './cost-ceiling.js';
 import { localEndpointConfig } from './local-endpoint.js';
+import { resolveProvider, buildProviderRequest, providerMatrix } from './providers.js';
 
 // The output cap we request. Shared with the cost estimate so the ceiling
 // charges exactly what we permit the model to produce.
@@ -83,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}}
@@ -124,49 +124,36 @@ Snippet (single line, trusted from scanner output): {{snippet}}
 Reply now with the JSON object on the last line of your response. Nothing else after it.
 `;
 
+// Delegates to the provider seam (PRD Epic 3). Kept as a thin adapter rather
+// than deleted: every call site, test and cost-ceiling path already speaks this
+// shape, and changing a seam and all its consumers at once is how a refactor
+// becomes a regression. `_localPresetRefusal` still carries a REFUSAL
+// distinctly from "nothing configured" — the local preset declining a remote
+// endpoint must not read as an absent config.
 function endpointConfig() {
-  // R11 — the local path is checked FIRST, ahead of the BYO endpoint, because
-  // it is the only mode that makes a promise about where data goes. If the
-  // operator asked for `local`, a stray AGENTIC_SECURITY_LLM_ENDPOINT pointing
-  // at a remote host must not quietly win: it is refused, and the tier stays
-  // off. Silently honouring it would break the one guarantee the preset exists
-  // to provide.
-  if ((process.env.AGENTIC_SECURITY_LLM_PRESET || '').toLowerCase() === 'local') {
-    const r = localEndpointConfig();
-    if (!r.ok) {
-      _localPresetRefusal = r.reason;
-      return null;
-    }
-    _localPresetRefusal = null;
-    return r.config;
-  }
-  // Explicit BYO endpoint always wins (unchanged behaviour).
-  const endpoint = process.env.AGENTIC_SECURITY_LLM_ENDPOINT;
-  if (endpoint) {
-    return { endpoint, apiKey: process.env.AGENTIC_SECURITY_LLM_API_KEY, model: process.env.AGENTIC_SECURITY_LLM_MODEL || 'unknown', preset: null };
-  }
-  // #18 — first-class Anthropic preset. Opt-in via AGENTIC_SECURITY_LLM_PRESET=anthropic
-  // + a key (AGENTIC_SECURITY_LLM_API_KEY or ANTHROPIC_API_KEY): makes the FP-suppression
-  // validator reachable with just a key — no BYO endpoint URL or request-shape wrangling.
-  // Offline-degrading: no key → null (validator no-ops; no runtime cloud call by default).
-  if ((process.env.AGENTIC_SECURITY_LLM_PRESET || '').toLowerCase() === 'anthropic') {
-    const apiKey = process.env.AGENTIC_SECURITY_LLM_API_KEY || process.env.ANTHROPIC_API_KEY;
-    if (!apiKey) return null;
-    return {
-      endpoint: 'https://api.anthropic.com/v1/messages',
-      apiKey,
-      model: process.env.AGENTIC_SECURITY_LLM_MODEL || 'claude-haiku-4-5',
-      preset: 'anthropic',
-    };
-  }
-  return null;
+  const r = resolveProvider({ role: 'validate' });
+  if (!r.ok) { _localPresetRefusal = r.reason || null; return null; }
+  _localPresetRefusal = null;
+  const c = r.config;
+  return {
+    endpoint: c.endpoint,
+    apiKey: c.apiKey,
+    model: c.model,
+    preset: c.provider === 'anthropic' ? 'anthropic' : (c.provider === 'local' ? 'local' : null),
+    provider: c.provider,
+    egress: c.egress,
+    _shape: c.shape,
+  };
 }
 
 // Shape the request for the target: the Anthropic Messages API needs an
 // x-api-key header (added by the caller), an anthropic-version header, and a
 // {model, max_tokens, messages:[…]} body with the reply in content[].text. The
 // generic path posts {prompt, model} with a Bearer header. Pure — no I/O.
-function buildRequest(model, prompt, preset) {
+function buildRequest(model, prompt, preset, shape) {
+  // A resolved provider carries its own wire shape; use it. The hand-written
+  // branches below remain for callers that pass only a preset string.
+  if (shape) return buildProviderRequest({ shape, model, apiKey: null }, prompt, MAX_OUTPUT_TOKENS);
   if (preset === 'anthropic') {
     return {
       headers: { 'Content-Type': 'application/json', 'anthropic-version': '2023-06-01' },
@@ -347,8 +334,8 @@ function renderPrompt(finding, fileContents, challenge, nonce) {
     .replace('{{context}}', sterileContext || '(no surrounding code available)');
 }
 
-async function callEndpoint(endpoint, apiKey, model, prompt, preset = null) {
-  const { headers, body, extractText, extractUsage } = buildRequest(model, prompt, preset);
+async function callEndpoint(endpoint, apiKey, model, prompt, preset = null, shape = null) {
+  const { headers, body, extractText, extractUsage } = buildRequest(model, prompt, preset, shape);
   if (apiKey) {
     if (preset === 'anthropic') headers['x-api-key'] = apiKey;
     else headers['Authorization'] = `Bearer ${apiKey}`;
@@ -520,7 +507,7 @@ export async function validateOne(finding, fileContents, scanRoot, ledger = null
     }
   }
 
-  const resp = await callEndpoint(cfg.endpoint, cfg.apiKey, cfg.model, prompt, cfg.preset);
+  const resp = await callEndpoint(cfg.endpoint, cfg.apiKey, cfg.model, prompt, cfg.preset, cfg._shape);
   // Record actual usage when the endpoint reports it, else the estimate. An
   // unreported call is never free — but the two are recorded DISTINCTLY, so
   // the reported spend can say which it is. Presenting an upper bound as a
@@ -629,6 +616,8 @@ export async function validateMany(findings, { fileContents, scanRoot, concurren
     findings.costCeiling = ledger.state();
     findings.costCeilingSummary = renderCostCeiling(ledger.state());
   }
+  // Which provider each role would use. No keys, ever — this is reported.
+  findings.providerMatrix = providerMatrix();
   const _cs = cacheStats();
   findings.validatorCache = _cs;
   if (_cs.unverified > 0) {

package/src/llm-validator/providers.js

@@ -0,0 +1,227 @@
+// PRD Epic 3 — the model-neutral seam.
+//
+// The deterministic engine has never depended on a model. The only coupling was
+// here, in how an AI call is shaped: one hardcoded pair of request builders and
+// one `endpointConfig` that knew about exactly two presets. This module makes
+// the provider a parameter instead, so an OpenAI or Gemini shop — or a
+// regulated org that cannot send code to any vendor — is a configuration
+// change rather than a fork.
+//
+// WHAT A PROVIDER IS. Endpoint, auth header shape, request body, and how to
+// read text and token usage back out. Nothing else. Prompt construction,
+// redaction, response validation, the challenge/nonce cross-check and the cost
+// ceiling all stay upstream and apply identically to every provider — those are
+// the security properties, and they must not become per-vendor.
+//
+// PER-ROLE PINNING. The strong pipelines route cheap models at triage and
+// frontier models at synthesis. `resolveProvider({ role })` reads a per-role
+// override before the global one, so `AGENTIC_SECURITY_LLM_MODEL_VERIFY` can
+// point at something cheap while `..._FIX` points at something capable. Roles
+// are a closed set: an unknown role would silently fall back to the global
+// model, which is how a "cheap verify" quietly becomes an expensive one.
+//
+// GRACEFUL DEGRADATION IS THE DEFAULT. No provider configured means no AI
+// stages — the engine still returns its deterministic findings. That is the
+// existing behaviour and it is load-bearing: adding providers must not make the
+// scanner require one.
+//
+// THE LOCAL PATH KEEPS ITS GUARANTEE. `local` still routes through
+// `local-endpoint.js`, which enforces loopback on the host literal. A provider
+// abstraction must not become a way to smuggle a remote endpoint into the mode
+// whose entire promise is that nothing leaves the machine.
+
+import { localEndpointConfig } from './local-endpoint.js';
+
+// Roles the pipeline dispatches under. Closed set on purpose — see above.
+export const ROLES = Object.freeze([
+  'validate',   // the FP-suppression validator (the original caller)
+  'verify',     // adversarial verification (Epic 2) — cheap tier by default
+  'explain',    // human-facing explanation
+  'fix',        // patch synthesis
+  'poc',        // proof-of-concept synthesis (Epic 1)
+  'logic',      // cross-file business-logic reasoning (Epic 6)
+]);
+
+const ANTHROPIC_VERSION = '2023-06-01';
+
+// ── Request/response shapes, one per wire protocol ──────────────────────────
+//
+// Kept as data rather than subclasses: each is four small functions, and a flat
+// table makes it obvious what a new provider must supply.
+const SHAPES = {
+  anthropic: {
+    headers: () => ({ 'Content-Type': 'application/json', 'anthropic-version': ANTHROPIC_VERSION }),
+    auth: (h, key) => { if (key) h['x-api-key'] = key; },
+    body: (model, prompt, maxTokens) => ({ model, max_tokens: maxTokens, messages: [{ role: 'user', content: prompt }] }),
+    text: (j) => (Array.isArray(j?.content) ? j.content.filter(b => b?.type === 'text').map(b => b.text || '').join('') : ''),
+    usage: (j) => (j?.usage && Number.isFinite(j.usage.input_tokens)
+      ? { inputTokens: j.usage.input_tokens, outputTokens: j.usage.output_tokens || 0 } : null),
+  },
+  // OpenAI-compatible: also what most local servers speak, which is why the
+  // `local` provider reuses it rather than inventing a third shape.
+  openai: {
+    headers: () => ({ 'Content-Type': 'application/json' }),
+    auth: (h, key) => { if (key) h.Authorization = `Bearer ${key}`; },
+    body: (model, prompt, maxTokens) => ({ model, max_tokens: maxTokens, messages: [{ role: 'user', content: prompt }] }),
+    text: (j) => j?.choices?.[0]?.message?.content || j?.choices?.[0]?.text || '',
+    usage: (j) => {
+      const u = j?.usage; if (!u) return null;
+      const inputTokens = u.prompt_tokens ?? u.input_tokens;
+      const outputTokens = u.completion_tokens ?? u.output_tokens ?? 0;
+      return Number.isFinite(inputTokens) ? { inputTokens, outputTokens } : null;
+    },
+  },
+  // The LEGACY generic shape: `{prompt, model}` with a permissive extractor.
+  // This is what BYO endpoints and local servers have always been sent, and
+  // existing deployments speak it. Assuming OpenAI-compatibility here would
+  // silently break every one of them, so the OpenAI shape is used ONLY when the
+  // operator explicitly asks for the openai preset.
+  generic: {
+    headers: () => ({ 'Content-Type': 'application/json' }),
+    auth: (h, key) => { if (key) h.Authorization = `Bearer ${key}`; },
+    body: (model, prompt) => ({ prompt, model }),
+    text: (j) => (j && (j.response || j.text || j.content || j.output
+      || j.choices?.[0]?.message?.content || j.message?.content)) || '',
+    usage: (j) => {
+      const u = j?.usage; if (!u) return null;
+      const inputTokens = u.prompt_tokens ?? u.input_tokens;
+      const outputTokens = u.completion_tokens ?? u.output_tokens ?? 0;
+      return Number.isFinite(inputTokens) ? { inputTokens, outputTokens } : null;
+    },
+  },
+  gemini: {
+    headers: () => ({ 'Content-Type': 'application/json' }),
+    // Gemini takes the key on the query string; the caller appends it, so the
+    // header set stays empty rather than carrying a bearer token that the API
+    // would ignore.
+    auth: () => {},
+    body: (model, prompt, maxTokens) => ({
+      contents: [{ role: 'user', parts: [{ text: prompt }] }],
+      generationConfig: { maxOutputTokens: maxTokens },
+    }),
+    text: (j) => (j?.candidates?.[0]?.content?.parts || []).map(p => p?.text || '').join(''),
+    usage: (j) => {
+      const u = j?.usageMetadata; if (!u) return null;
+      return Number.isFinite(u.promptTokenCount)
+        ? { inputTokens: u.promptTokenCount, outputTokens: u.candidatesTokenCount || 0 } : null;
+    },
+  },
+};
+
+const DEFAULT_MODEL = {
+  anthropic: 'claude-haiku-4-5',
+  openai: 'gpt-4o-mini',
+  gemini: 'gemini-2.0-flash',
+  local: 'local-model',
+};
+
+function _envKey(role, suffix) {
+  return `AGENTIC_SECURITY_LLM_${suffix}_${String(role).toUpperCase()}`;
+}
+
+/** Per-role override, falling back to the global setting. */
+function _forRole(env, role, suffix) {
+  if (role && ROLES.includes(role)) {
+    const v = env[_envKey(role, suffix)];
+    if (v) return v;
+  }
+  return env[`AGENTIC_SECURITY_LLM_${suffix}`];
+}
+
+/**
+ * Resolve the provider for a role.
+ *
+ * @returns {{ok:true, config:object} | {ok:false, reason:string|null}}
+ *   `ok:false` with `reason:null` means "no AI configured", which is the normal
+ *   default and NOT an error. A non-null reason means a configuration was
+ *   supplied and refused — those must be surfaced, not silently treated the
+ *   same as "off".
+ */
+export function resolveProvider({ role = 'validate', env = process.env } = {}) {
+  const explicit = (_forRole(env, role, 'PRESET') || '').toLowerCase();
+  const model = _forRole(env, role, 'MODEL');
+
+  // 1. Local — checked first because it is the only mode that makes a promise
+  //    about where data goes, and a stray endpoint must not override it.
+  if (explicit === 'local') {
+    const r = localEndpointConfig(env);
+    if (!r.ok) return { ok: false, reason: r.reason };
+    return {
+      ok: true,
+      config: {
+        provider: 'local', shape: SHAPES.generic, endpoint: r.config.endpoint,
+        apiKey: r.config.apiKey, model: model || r.config.model,
+        egress: 'loopback-only', role,
+      },
+    };
+  }
+
+  // 2. Explicit BYO endpoint — checked BEFORE the vendor presets because that
+  //    is the documented precedence: an operator who names an endpoint means
+  //    that endpoint, even with a preset also set. Reversing it would silently
+  //    redirect traffic to a vendor.
+  const byoEndpoint = _forRole(env, role, 'ENDPOINT');
+  if (byoEndpoint) {
+    return {
+      ok: true,
+      config: {
+        provider: 'byo', shape: SHAPES.generic, endpoint: byoEndpoint,
+        apiKey: _forRole(env, role, 'API_KEY') || null,
+        model: model || 'unknown', egress: 'remote', role,
+      },
+    };
+  }
+
+  // 3. Explicit vendor presets.
+  if (explicit === 'anthropic' || explicit === 'openai' || explicit === 'gemini') {
+    const apiKey = _forRole(env, role, 'API_KEY')
+      || (explicit === 'anthropic' ? env.ANTHROPIC_API_KEY
+        : explicit === 'openai' ? env.OPENAI_API_KEY
+          : env.GEMINI_API_KEY || env.GOOGLE_API_KEY);
+    // No key -> the tier is off, not broken. Same offline-degrading rule the
+    // anthropic preset has always had.
+    if (!apiKey) return { ok: false, reason: null };
+    const m = model || DEFAULT_MODEL[explicit];
+    const endpoint = (
+      explicit === 'anthropic' ? 'https://api.anthropic.com/v1/messages'
+        : explicit === 'openai' ? 'https://api.openai.com/v1/chat/completions'
+          : `https://generativelanguage.googleapis.com/v1beta/models/${m}:generateContent?key=${encodeURIComponent(apiKey)}`
+    );
+    return {
+      ok: true,
+      config: {
+        provider: explicit, shape: SHAPES[explicit], endpoint,
+        apiKey: explicit === 'gemini' ? null : apiKey, model: m, egress: 'remote', role,
+      },
+    };
+  }
+
+  // 4. Nothing configured — deterministic engine only.
+  return { ok: false, reason: null };
+}
+
+/** Build the HTTP call for a resolved provider. Pure. */
+export function buildProviderRequest(config, prompt, maxTokens) {
+  const headers = config.shape.headers();
+  config.shape.auth(headers, config.apiKey);
+  return {
+    headers,
+    body: config.shape.body(config.model, prompt, maxTokens),
+    extractText: config.shape.text,
+    extractUsage: config.shape.usage,
+  };
+}
+
+/** Which provider each role would use, for reporting. Never includes keys. */
+export function providerMatrix(env = process.env) {
+  const out = {};
+  for (const role of ROLES) {
+    const r = resolveProvider({ role, env });
+    out[role] = r.ok
+      ? { provider: r.config.provider, model: r.config.model, egress: r.config.egress }
+      : { provider: null, reason: r.reason || 'not configured' };
+  }
+  return out;
+}
+
+export const _internals = { SHAPES, DEFAULT_MODEL, _forRole };

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.
@@ -98,6 +123,31 @@ Wired in `bin/agentic-security.js` after every filter and after `makeDeterminist
 credibility, orthogonal to `confidence`/`exploitability`: whether the bug was
 *run*, not just reasoned about.
 
+**The five proof classes** (`poc-inprocess.js`), and what each observes:
+
+| Family | Evidence |
+|---|---|
+| `command-injection`, `code-injection` | the injected payload itself writes the marker |
+| `webhook-missing-signature-verification` | the handler is observed *accepting* an unsigned request |
+| `sql-injection` | the payload reaches a stubbed driver inside the **SQL text** rather than as a bound parameter |
+| `path-traversal` | a sentinel planted outside the served directory comes back out of the handler |
+
+The last two need no running application, which is the point: the SQL question
+("text or bound parameter?") is settled where the query crosses into the driver,
+and the traversal question is settled by what the handler hands back. A
+parameterised query and a `basename`-guarded read both reach `proof-failed` by
+**execution**, not by a source pattern.
+
+Classes deliberately absent, with reasons, are listed in the module header —
+IDOR (needs two identities and a populated store; a PoC built on invented state
+proves something about the invention), SSRF (the sandbox denies egress, so a
+failed fetch is confinement talking), XSS (a marker file cannot observe a DOM).
+
+`extraFiles` on a PoC carries support files that are **not** the vulnerable
+source (the SQL driver stub). `mergePocFiles` merges it under `requires`, which
+always wins — otherwise a template could replace the code it is supposed to
+exploit and prove a fact about itself.
+
 **The four tiers** (`PROOF_TIERS`, most-proven first):
 
 - `execution-proven` — a generated PoC ran inside the sandbox and the sandbox
@@ -236,6 +286,57 @@ State lives at `<scanRoot>/.agentic-security/scan-checkpoint.jsonl`; like every
 other module here, nothing throws — a failure to open, read or append degrades to
 "no checkpoint", i.e. a normal full scan.
 
+## The autonomous loop, the fleet, and the two things that judge them
+
+**`autopilot.js`** is the chain — scan → prove → validate → fix → **re-verify** —
+and nothing else. Every stage is injected, so the orchestration is testable
+without an engine or a model; `scripts/autopilot.mjs` is where the real stages
+get wired (a real scan, a real sandboxed exploit, a deterministic-then-model fix,
+and the real gate).
+
+The rule that makes it safe to automate: a fix is applied **only** if the PoC
+that proved the bug no longer fires **and** the test suite still passes. Anything
+else is `NEEDS_REVIEW` and is not written. A re-scan proves the *detector* went
+quiet; only re-running the exploit proves the hole is shut. Gates are ON by
+default — `apply` is an explicit opt-in — and the outcome set (`OUTCOMES`) is
+closed, because the report groups on it and an undeclared value would vanish
+from every count. `maxFindings` is reported as `capped`, never applied silently.
+
+The CLI refuses to start with no confinement backend (the gate's verdict
+requires executing something) and refuses a dirty git tree by default (the test
+leg writes the candidate patch to disk and restores it in a `finally`, so a
+clean tree is what makes a crash recoverable). A VERIFIED_FIXED reached with no
+test runner detected is counted and reported separately — the exploit stopped
+firing, but nothing checked the application still works.
+
+**`fleet.js`** rolls many repositories into one offline page. `renderFleetHtml`
+emits no scripts and no external references, and a repo that FAILED to scan
+always forces a non-zero exit: an unscanned repo is unknown, not clean.
+
+**`logic-claims.js` (PRD Epic 6)** is the business-logic tier's other half. The
+deterministic side already existed (`sast/logic.js`, `posture/business-logic.js`);
+what did not was any way to be *wrong* about a claim from the reviewing agent,
+which is prose and was the only tier nothing could disagree with. Three offline
+lenses can refute one: `citation` (the file exists and the line is inside it),
+`quotation` (the quoted snippet is at the cited line ±3), and `corroboration`
+(for kinds that assert something checkable — "this route has no authentication"
+against a handler that plainly authenticates). Verdicts go through
+`verification-separation.js`, so a lens can never vote on a claim it produced.
+Recall-preserving: a refuted claim is `quarantined`, never deleted, never
+severity-touched. Wired in `engine.js`, which reads
+`.agentic-security/logic-claims.json` from the scan root and lands the results
+on `scan.logicVulns` with a summary at `scan.logicClaims`.
+
+**`comparison.js` (PRD Epic 7.2)** scores this engine head-to-head against
+participants **the operator supplies** — the repository ships the harness and the
+answer key, never a participant, and a test asserts no tool name appears in
+either file. Two properties are the whole module: every rate is computed over the
+**intersection** of entries *all* participants completed (two tools scored over
+different subsets are not comparable, and the difference is invisible in the
+output), and an entry a participant could not run is **unscored**, never counted
+as a miss. Matching is CWE-only so nobody is scored on this engine's vocabulary.
+Driver: `scripts/comparison.mjs`, over the CVE-replay corpus.
+
 ## Gotchas
 
 - The seed `calibration-seed.json` is small (n < 30 for several families). Don't treat it as a held-out set — that's `holdout-eval.js`'s job, against an externally-supplied JSONL.

package/src/posture/accuracy-scorecard.js

@@ -121,7 +121,14 @@ export function buildScorecard(inputs) {
       notGeneralRecall: true,
       notGeneralFalsePositiveRate: true,
       f1Emitted: false,
-      f1OmissionReason: 'no labelled real-world population is available to measure precision over, so any F1 would combine denominators that do not describe the same population',
+      // Was: "no labelled real-world population is available". That stopped
+      // being true when bench/independent/ was built, and a stale justification
+      // is worse than none — it argues against a measurement that now exists.
+      // No F1 is emitted FOR THE CURATED CORPUS, and the reason is narrower:
+      // its `post/` fixtures are authored here to be silent, so its precision
+      // denominator describes fixture design rather than engine behaviour.
+      // F1 over the independent population IS reported, in its own section.
+      f1OmissionReason: 'the curated corpus authors both its vulnerable and its fixed fixtures, so an F1 over it would measure fixture design, not accuracy; F1 over the labelled third-party population is reported separately from bench/independent/RESULT.json',
     },
     corpus: {
       measuredThisRun: true,
@@ -138,6 +145,17 @@ export function buildScorecard(inputs) {
       corpusBaseline: committed.corpusBaseline
         ? { source: 'bench/cve-replay/corpus-baseline.json', generatedAt: committed.corpusBaseline.generatedAt, total: committed.corpusBaseline.total, passing: committed.corpusBaseline.passing }
         : null,
+      independent: committed.independent
+        ? {
+          source: 'bench/independent/RESULT.json',
+          measuredAt: committed.independent.measuredAt || null,
+          engineVersion: committed.independent.engineVersion || null,
+          population: committed.independent.population || null,
+          overall: committed.independent.overall || null,
+          wide: committed.independent.wide || null,
+          byLanguage: committed.independent.byLanguage || null,
+        }
+        : null,
       proofCorpus: proof
         ? {
           source: 'bench/proof-corpus/results/summary.json',
@@ -307,6 +325,46 @@ export function renderScorecardMarkdown(m) {
   }
   L.push('Per-file counts are in `docs/scorecard.json`.');
   L.push('');
+  const ind = m.committedInputs.independent;
+  if (ind && ind.overall) {
+    L.push('## Independent evaluation population — the number that matters');
+    L.push('');
+    L.push('Everything above is a **regression net**: its fixtures and its labels are both');
+    L.push('written here, which is why its detection rate sits at the ceiling by');
+    L.push('construction. `bench/independent/` is the other instrument — real upstream code');
+    L.push('at the commit where a vulnerability really existed, with the CWE assigned by a');
+    L.push('public advisory database rather than by this project.');
+    L.push('');
+    L.push(`**Measured ${ind.measuredAt} on engine ${ind.engineVersion}, ` +
+      `n=${ind.population?.scoredEntries}, ${ind.population?.unscored} unscored** ` +
+      '(*committed artifact*, `' + ind.source + '` — read, not re-run: scoring takes ~32 minutes).');
+    L.push('');
+    L.push('| | Advisory-local (**the claim**) | Wide (diagnostic) |');
+    L.push('| --- | --- | --- |');
+    L.push(`| Precision | **${formatRate(ind.overall.precision?.n, ind.overall.precision?.d)}** | ${formatRate(ind.wide?.precision?.n, ind.wide?.precision?.d)} |`);
+    L.push(`| Recall | **${formatRate(ind.overall.recall?.n, ind.overall.recall?.d)}** | ${formatRate(ind.wide?.recall?.n, ind.wide?.recall?.d)} |`);
+    L.push(`| F1 | **${ind.overall.f1 === null || ind.overall.f1 === undefined ? 'n/a' : ind.overall.f1.toFixed(3)}** | ${ind.wide?.f1 === null || ind.wide?.f1 === undefined ? 'n/a' : ind.wide.f1.toFixed(3)} |`);
+    L.push('');
+    if (ind.byLanguage) {
+      L.push('| Language | n | Recall | Precision |');
+      L.push('| --- | --- | --- | --- |');
+      for (const [k, v] of Object.entries(ind.byLanguage)) {
+        L.push(`| ${k} | ${v.entries} | ${formatRate(v.recall?.n, v.recall?.d)} | ${formatRate(v.precision?.n, v.precision?.d)} |`);
+      }
+      L.push('');
+    }
+    L.push('**Quote the advisory-local column.** "Wide" scores the same scans without');
+    L.push('restricting findings to the files the advisory\'s fix commit touched — it asks');
+    L.push('only whether the CWE appeared *anywhere* in the package. Over scopes holding up');
+    L.push('to 1740 findings that is close to asking whether the codebase contains the bug');
+    L.push('class at all, a question with a much easier yes. It is kept because it is the');
+    L.push('only way to tell whether a change moved the engine or moved the benchmark.');
+    L.push('');
+    L.push('Against ~100% on the curated corpus above. **That gap is the most useful number');
+    L.push('in this document**, and publishing it is the point of the exercise. The figure');
+    L.push('went DOWN when the benchmark was corrected, and is published that way.');
+    L.push('');
+  }
   L.push('## Committed artifacts referenced (not re-run by this command)');
   L.push('');
   const cb = m.committedInputs.corpusBaseline;

package/src/posture/agents-memory.js

@@ -29,6 +29,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { statePath, stateWritesEnabled } from './state-dir.js';
 const MEMORY_FILE = '.agentic-security/AGENTS.md';
 const ARCHIVE_FILE = '.agentic-security/AGENTS.md.archive';
 const MAX_BYTES = 20 * 1024;
@@ -36,8 +37,8 @@ const MAX_ENTRY_BYTES = 2 * 1024;
 const ARCHIVE_MAX_BYTES = 200 * 1024;
 const HEADER = '# AGENTS.md\n\nAgent-authored continual-learning notes. Each entry: timestamp + agent name + one short paragraph. New entries appended at the bottom; oldest entries rotate to AGENTS.md.archive when this file exceeds 20 KB.\n\n';
 
-function _resolve(scanRoot) { return path.join(scanRoot, MEMORY_FILE); }
-function _archivePath(scanRoot) { return path.join(scanRoot, ARCHIVE_FILE); }
+function _resolve(scanRoot) { return statePath(scanRoot, 'AGENTS.md'); }
+function _archivePath(scanRoot) { return statePath(scanRoot, 'AGENTS.md.archive'); }
 
 export function readAgentsMemory(scanRoot) {
   const fp = _resolve(scanRoot);
@@ -65,7 +66,8 @@ export function appendAgentsMemory(scanRoot, { agent, body }) {
   const entry = `\n## ${ts}  agent: ${agent}\n\n${snippet}\n`;
   try {
     const fp = _resolve(scanRoot);
-    fs.mkdirSync(path.dirname(fp), { recursive: true });
+    if (!stateWritesEnabled()) return;
+  fs.mkdirSync(path.dirname(fp), { recursive: true });
     if (!fs.existsSync(fp)) fs.writeFileSync(fp, HEADER);
     fs.appendFileSync(fp, entry);
     _maybeRotate(scanRoot);