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

package/src/llm-validator/index.js

@@ -33,6 +33,26 @@
 //      file:line mismatch → verdict='escalate' (KEEP the finding). The
 //      validator can NEVER silently reject a finding it didn't successfully
 //      verify.
+//   8. A `reject` cannot DELETE a strongly-provenanced finding (IR-TAINT,
+//      MULTI-SINK, execution-proven) — it is demoted to `escalate` and the
+//      refusal is recorded. See `applyValidatorVerdicts`.
+//   9. The response cache is HMAC-signed and verified on read; an unsigned,
+//      tampered or foreign-keyed entry is a MISS, never a verdict.
+//
+// WHAT ITEMS 1-6 DO AND DO NOT BUY, stated precisely because an earlier version
+// of this header overstated it. The delimiters, challenge and file:line echo
+// defend against a FORGED or REPLAYED response — they prove the reply came from
+// a model that saw this prompt and judged this finding. They do NOT prevent the
+// model being PERSUADED by instructions inside the code it legitimately read:
+// such a reply echoes the challenge correctly because the model really did see
+// it. Item 4 asks the model to self-report injection attempts, and the
+// `/prompt-injection/i` check in `validateResponse` acts on that — but it only
+// fires when the model volunteers the phrase, so "reject, and don't mention
+// injection" walks past it.
+//
+// That is why items 8 and 9 exist. The property "an attacker cannot cause a
+// finding to be deleted" is now enforced structurally for findings real
+// analysis produced, rather than inferred from prompt hardening.
 //   6. The reasoning string is sanitized before storing/rendering — stops
 //      secondary markdown/HTML injection into reports.
 //   7. Concurrent worker pool replaced with deterministic sorted iteration
@@ -46,10 +66,22 @@ import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { statePath, ensureStateDir, safeWriteState } from '../posture/state-dir.js';
 import { redactSecrets } from './redact.js';
+import { signLastScan } from '../posture/integrity.js';
 
 // Bump on every prompt change so the cache invalidates. Exported as a
 // stable public symbol (premortem 4R-15) so the validator-cache GC subcommand
 // 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';
+
+// The output cap we request. Shared with the cost estimate so the ceiling
+// charges exactly what we permit the model to produce.
+const MAX_OUTPUT_TOKENS = 512;
+
+// Why the local preset declined, if it did. Surfaced on the batch so a refusal
+// reads as a refusal rather than as "no endpoint configured".
+let _localPresetRefusal = null;
+
 export const PROMPT_VERSION = 'v2.0-hardened';
 const CACHE_DIR = '.agentic-security/llm-cache';
 
@@ -93,6 +125,21 @@ Reply now with the JSON object on the last line of your response. Nothing else a
 `;
 
 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) {
@@ -123,14 +170,30 @@ function buildRequest(model, prompt, preset) {
   if (preset === 'anthropic') {
     return {
       headers: { 'Content-Type': 'application/json', 'anthropic-version': '2023-06-01' },
-      body: { model, max_tokens: 512, messages: [{ role: 'user', content: prompt }] },
+      body: { model, max_tokens: MAX_OUTPUT_TOKENS, messages: [{ role: 'user', content: prompt }] },
       extractText: (j) => (Array.isArray(j?.content) ? j.content.filter(b => b?.type === 'text').map(b => b.text || '').join('') : ''),
+      // R12 — real token usage, so the cost ledger books what was actually
+      // spent instead of the worst case it had to assume beforehand.
+      extractUsage: (j) => (j?.usage && Number.isFinite(j.usage.input_tokens)
+        ? { inputTokens: j.usage.input_tokens, outputTokens: j.usage.output_tokens || 0 }
+        : null),
     };
   }
   return {
     headers: { 'Content-Type': 'application/json' },
     body: { prompt, model },
     extractText: (j) => (j && (j.response || j.text || j.content || j.output || j.choices?.[0]?.message?.content || j.message?.content)) || '',
+    // OpenAI-compatible servers (and most local ones) report usage in this
+    // shape. A server that reports nothing yields null, and the ledger then
+    // records an ESTIMATE and says so — it never silently presents one as the
+    // other.
+    extractUsage: (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;
+    },
   };
 }
 
@@ -150,15 +213,78 @@ function cacheKey(finding, fileHash, modelId) {
   return crypto.createHash('sha256').update(material).digest('hex');
 }
 
+// The cache is INTEGRITY-PROTECTED, and it has to be: a cache hit assigns a
+// verdict directly, and a `reject` verdict DELETES a finding. That made the
+// cache a deletion primitive — planting one JSON file under
+// `.agentic-security/llm-cache/` removed a critical finding with no model call
+// and no network, deterministically. The key is derivable by anyone with repo
+// access (file hash, path, prompt version, model id are all knowable), and the
+// realistic delivery vector is not a repo write at all: CI restores cache
+// directories between runs.
+//
+// `last-scan.json` has been HMAC-signed for exactly this reason. The cache that
+// can delete findings had nothing. Same mechanism, same key handling — no
+// second crypto path is introduced.
+//
+// AN UNVERIFIABLE ENTRY IS A MISS, NEVER A VERDICT. That includes the entry
+// being unsigned, signed under a different install key, or structurally
+// malformed. The cost of a miss is one model call; the cost of trusting a
+// planted entry is a silently deleted vulnerability.
+function _cacheSignable(value) {
+  // Sign the fields that carry meaning. Signing the serialised object would
+  // make the signature depend on key order and on any field added later.
+  return [
+    String(value?.verdict ?? ''),
+    String(value?.confidence ?? ''),
+    String(value?.reasoning ?? ''),
+    String(value?.model ?? ''),
+    String(value?.prompt_version ?? ''),
+  ].join('\u0000');
+}
+
+// A cache entry that EXISTS but does not verify is a different event from an
+// ordinary miss, and it must be countable. In CI the per-install key is
+// regenerated every run (nothing persists `$XDG_CONFIG_HOME`), so a restored
+// cache directory verifies against nothing and the hit rate is silently zero —
+// the operator pays for every call twice over and sees no signal. Fail-closed is
+// right; failing closed invisibly is not.
+const _cacheStats = { hits: 0, misses: 0, unverified: 0 };
+function cacheStats() { return { ..._cacheStats }; }
+function _resetCacheStatsForTests() { _cacheStats.hits = 0; _cacheStats.misses = 0; _cacheStats.unverified = 0; }
+
 function readCache(scanRoot, key) {
   const fp = statePath(scanRoot, 'llm-cache', key + '.json');
-  if (!fs.existsSync(fp)) return null;
-  try { return JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { return null; }
+  if (!fs.existsSync(fp)) { _cacheStats.misses++; return null; }
+  let raw;
+  try { raw = JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { _cacheStats.unverified++; return null; }
+  if (!raw || typeof raw !== 'object') { _cacheStats.unverified++; return null; }
+
+  // Verdict allowlist on READ, mirroring validateResponse. A cached verdict is
+  // as much untrusted input as a model response is.
+  if (!['accept', 'reject', 'escalate'].includes(raw.verdict)) { _cacheStats.unverified++; return null; }
+
+  const sig = typeof raw.sig === 'string' ? raw.sig : null;
+  if (!sig) { _cacheStats.unverified++; return null; }
+  let expected;
+  try { expected = signLastScan(_cacheSignable(raw)); } catch { _cacheStats.unverified++; return null; }
+  // Constant-time compare; length mismatch short-circuits before timingSafeEqual
+  // (which throws on unequal lengths).
+  if (sig.length !== expected.length) { _cacheStats.unverified++; return null; }
+  try {
+    if (!crypto.timingSafeEqual(Buffer.from(sig, 'utf8'), Buffer.from(expected, 'utf8'))) {
+      _cacheStats.unverified++; return null;
+    }
+  } catch { _cacheStats.unverified++; return null; }
+  _cacheStats.hits++;
+  return raw;
 }
 
 function writeCache(scanRoot, key, value) {
   const fp = statePath(scanRoot, 'llm-cache', key + '.json');
-  safeWriteState(fp, JSON.stringify(value, null, 2));
+  let signed = value;
+  try { signed = { ...value, sig: signLastScan(_cacheSignable(value)) }; }
+  catch { return; } // cannot sign -> do not cache; an unsignable entry would never be read back
+  safeWriteState(fp, JSON.stringify(signed, null, 2));
 }
 
 function fileHashOf(fileContents, file) {
@@ -222,7 +348,7 @@ function renderPrompt(finding, fileContents, challenge, nonce) {
 }
 
 async function callEndpoint(endpoint, apiKey, model, prompt, preset = null) {
-  const { headers, body, extractText } = buildRequest(model, prompt, preset);
+  const { headers, body, extractText, extractUsage } = buildRequest(model, prompt, preset);
   if (apiKey) {
     if (preset === 'anthropic') headers['x-api-key'] = apiKey;
     else headers['Authorization'] = `Bearer ${apiKey}`;
@@ -231,7 +357,7 @@ async function callEndpoint(endpoint, apiKey, model, prompt, preset = null) {
     const r = await fetch(endpoint, { method: 'POST', headers, body: JSON.stringify(body) });
     if (!r.ok) return { ok: false, error: `HTTP ${r.status}` };
     const j = await r.json().catch(() => null);
-    return { ok: true, text: String(extractText(j) || '') };
+    return { ok: true, text: String(extractText(j) || ''), usage: extractUsage ? extractUsage(j) : null };
   } catch (e) {
     return { ok: false, error: e.message };
   }
@@ -322,7 +448,7 @@ export function validateResponse(obj, { challenge, file, line }) {
 // Pre-flight (premortem 2R2.2): findings WITHOUT a precise file:line cannot
 // be cross-checked against the LLM response (the model can trivially echo
 // empty/zero values). Such findings are marked unvalidated and KEPT.
-export async function validateOne(finding, fileContents, scanRoot) {
+export async function validateOne(finding, fileContents, scanRoot, ledger = null) {
   const cfg = endpointConfig();
   if (!cfg) {
     finding.validator_verdict = 'unvalidated';
@@ -371,7 +497,40 @@ export async function validateOne(finding, fileContents, scanRoot) {
   const challenge = crypto.randomBytes(8).toString('hex');
   const nonce     = crypto.randomBytes(8).toString('hex');
   const prompt = renderPrompt(finding, fileContents, challenge, nonce);
+
+  // R12 — the hard ceiling. Checked BEFORE the call, against a conservative
+  // estimate: input from the prompt we are about to send, output at the full
+  // max_tokens we allow. Charging the worst case is the only direction that
+  // cannot overshoot, and checking afterwards would let a call blow the cap
+  // and report the overrun as already spent.
+  const _est = {
+    inputTokens: Math.ceil(prompt.length / 4),
+    outputTokens: MAX_OUTPUT_TOKENS,
+  };
+  if (ledger) {
+    const afford = ledger.canAfford(_est);
+    if (!afford.ok) {
+      // Explicitly unvalidated, with the reason. NOT downgraded to a cheaper
+      // model and NOT treated as accepted — a finding nobody checked must not
+      // read like one that passed.
+      finding.validator_verdict = 'unvalidated';
+      finding.unvalidated = true;
+      finding.validator_skipped_reason = afford.reason;
+      return { verdict: 'unvalidated', error: 'cost-ceiling' };
+    }
+  }
+
   const resp = await callEndpoint(cfg.endpoint, cfg.apiKey, cfg.model, prompt, cfg.preset);
+  // 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
+  // measurement is the defect this distinction exists to prevent: the estimate
+  // charges the full max_tokens for output, which most replies never reach.
+  if (ledger) {
+    const u = resp?.usage;
+    if (u) ledger.record(u, { measured: true });
+    else ledger.record(_est, { measured: false });
+  }
   if (!resp.ok) {
     finding.validator_verdict = 'unvalidated';
     finding.unvalidated = true;
@@ -420,7 +579,9 @@ export async function validateMany(findings, { fileContents, scanRoot, concurren
     for (const f of findings) {
       f.validator_verdict = 'unvalidated';
       f.unvalidated = true;
+      if (_localPresetRefusal) f.validator_skipped_reason = _localPresetRefusal;
     }
+    if (_localPresetRefusal) findings.localPathRefusal = _localPresetRefusal;
     return findings;
   }
   const candidates = findings.filter(f =>
@@ -432,11 +593,28 @@ export async function validateMany(findings, { fileContents, scanRoot, concurren
     const kb = (b.stableId || b.id || '');
     return ka < kb ? -1 : ka > kb ? 1 : 0;
   });
+  // R12 — one ledger for the whole batch. A per-call cap would be no cap at
+  // all: N calls each under the limit is how you get an N-times overrun.
+  let ledger = null;
+  try {
+    const capUsd = parseCapUsd();
+    if (capUsd != null) ledger = createCostLedger({ capUsd, model: cfg.model });
+  } catch (e) {
+    // A malformed cap is fatal for the tier, not ignored. Continuing with "no
+    // cap" would turn a typo into unlimited spend.
+    for (const f of findings) {
+      f.validator_verdict = 'unvalidated';
+      f.unvalidated = true;
+      f.validator_skipped_reason = e.message;
+    }
+    return findings;
+  }
+
   let i = 0;
   async function worker() {
     while (i < candidates.length) {
       const idx = i++;
-      try { await validateOne(candidates[idx], fileContents, scanRoot); }
+      try { await validateOne(candidates[idx], fileContents, scanRoot, ledger); }
       catch (e) {
         // FAIL-CLOSED on exception too.
         candidates[idx].validator_verdict = 'escalate';
@@ -445,6 +623,25 @@ export async function validateMany(findings, { fileContents, scanRoot, concurren
     }
   }
   await Promise.all(Array.from({ length: Math.max(1, concurrency) }, () => worker()));
+  if (ledger) {
+    // Surfaced on the batch so a report can state what was spent and, more
+    // importantly, what was NOT checked because the ceiling bound.
+    findings.costCeiling = ledger.state();
+    findings.costCeilingSummary = renderCostCeiling(ledger.state());
+  }
+  const _cs = cacheStats();
+  findings.validatorCache = _cs;
+  if (_cs.unverified > 0) {
+    // Loud, because the common cause is structural rather than an attack: a CI
+    // runner that regenerates the per-install key every run can never verify a
+    // restored cache, so every call is re-paid silently.
+    try {
+      process.stderr.write(
+        `agentic-security: ${_cs.unverified} validator-cache entr(y/ies) present but UNVERIFIED `
+        + '(treated as misses). If this is CI, the per-install HMAC key is probably regenerated each '
+        + 'run — set AGENTIC_SECURITY_HMAC_KEY to a stable secret, or expect a permanent 0% hit rate.\n');
+    } catch {}
+  }
   for (const f of findings) {
     if (f.validator_verdict) continue;
     f.validator_verdict = 'unvalidated';
@@ -453,16 +650,48 @@ export async function validateMany(findings, { fileContents, scanRoot, concurren
   return findings;
 }
 
+// Provenance strong enough that a model's opinion must not delete it. These
+// findings were produced by real analysis — an interprocedural taint path, a
+// multi-sink correlation, or a proof-of-concept that actually executed — so a
+// `reject` against one is far more likely to be a manipulated or mistaken
+// verdict than a correct dismissal.
+const _STRONG_PARSERS = new Set(['IR-TAINT', 'MULTI-SINK']);
+function _stronglyProvenanced(f) {
+  return _STRONG_PARSERS.has(f?.parser) || f?.proofTier === 'execution-proven';
+}
+
 // Apply validator verdicts: reject → drop, escalate → keep but mark, accept →
 // boost confidence. Returns { kept, dropped }.
 //
-// Asymmetry: only 'reject' drops a finding. 'escalate' KEEPS it. This is the
-// design that makes prompt-injection of the validator harmless — the worst
-// an attacker can produce is escalate (= no effect on the kept-set).
+// THE ASYMMETRY, AND WHY IT USED TO BE OVERSTATED. Only `reject` drops;
+// `escalate` and `accept` keep. This comment previously concluded from that
+// that "prompt-injection of the validator is harmless — the worst an attacker
+// can produce is escalate". That was FALSE, and the falseness mattered because
+// it stopped anyone looking: the model reads adversary-controlled source, and
+// the only thing converting an injected `reject` into `escalate` was a regex in
+// `validateResponse` testing whether the model VOLUNTEERED the phrase
+// "prompt-injection" in its reasoning. An injected instruction that says
+// "reject, and do not mention injection" walks straight past it. The
+// challenge/nonce cross-check defends against forged and replayed responses —
+// not against a model being persuaded by content it legitimately read.
+//
+// So the guarantee is now enforced structurally rather than asserted:
+// a `reject` can never delete a strongly-provenanced finding. For those, the
+// worst any verdict can do is demote to `escalate`, which keeps them. The claim
+// and the code now agree.
 export function applyValidatorVerdicts(findings) {
   const kept = [];
   const dropped = [];
   for (const f of findings) {
+    if (f.validator_verdict === 'reject' && _stronglyProvenanced(f)) {
+      // Downgrade rather than drop, and record why, so this is visible in the
+      // report instead of looking like an ordinary escalate.
+      f.validator_verdict = 'escalate';
+      f.validator_reject_refused = 'strong provenance: a model verdict may not delete a '
+        + 'taint-proven, multi-sink or execution-proven finding';
+      kept.push(f);
+      continue;
+    }
     if (f.validator_verdict === 'reject') {
       f._droppedBy = 'llm-validator';
       dropped.push(f);
@@ -478,4 +707,4 @@ export function applyValidatorVerdicts(findings) {
   return { kept, dropped };
 }
 
-export const _internal = { PROMPT_VERSION, renderPrompt, parseLastJsonObject, validateResponse, sanitizeReasoning, cacheKey, endpointConfig, buildRequest };
+export const _internal = { PROMPT_VERSION, renderPrompt, parseLastJsonObject, validateResponse, sanitizeReasoning, cacheKey, endpointConfig, buildRequest, readCache, writeCache, ensureCacheDir, cacheStats, _resetCacheStatsForTests };

package/src/llm-validator/local-endpoint.js

@@ -0,0 +1,90 @@
+// R11 — the local / offline model path.
+//
+// A BYO endpoint already existed (`AGENTIC_SECURITY_LLM_ENDPOINT`), and you
+// could always point it at something on localhost. What did not exist is a
+// path that GUARANTEES the prompt never leaves the machine. That distinction
+// is the whole feature: the reason to run a local model is usually that the
+// code being analysed must not be sent anywhere, and a configuration that
+// merely happens to be local today provides no such assurance. One typo, one
+// inherited environment variable, and source is on someone else's server.
+//
+// So the `local` preset ENFORCES loopback. An endpoint that resolves to
+// anything other than a loopback literal is refused outright rather than
+// called. The check is on the host literal, not on DNS: resolving a name would
+// mean trusting a resolver, and a name that answers 127.0.0.1 today can answer
+// something else tomorrow. Only literal loopback forms are accepted, so the
+// guarantee cannot be undone by a DNS entry.
+//
+// OFFLINE DEGRADATION. A local server that is not running is the normal case,
+// not an error: the validator tier is optional and the scan must complete
+// without it. An unreachable local endpoint leaves findings `unvalidated` with
+// a reason naming the endpoint, exactly like every other validator failure.
+// The connect timeout is short for the same reason — a dead port must not hang
+// a scan.
+
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]', '0.0.0.0']);
+
+export const DEFAULT_LOCAL_ENDPOINT = 'http://127.0.0.1:11434/v1/chat/completions';
+export const DEFAULT_LOCAL_TIMEOUT_MS = 20000;
+
+/**
+ * Is this URL unambiguously loopback?
+ *
+ * Deliberately strict and literal. Anything unparseable, non-http(s), or
+ * hostname-based is NOT loopback — the answer to "am I sure this stays on this
+ * machine?" must be yes or no, never "probably".
+ */
+export function isLoopbackUrl(url) {
+  let u;
+  try { u = new URL(String(url)); } catch { return false; }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return false;
+  const host = u.hostname.toLowerCase();
+  if (LOOPBACK_HOSTS.has(host)) return true;
+  // The whole 127.0.0.0/8 block is loopback.
+  if (/^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host)) {
+    return host.split('.').slice(1).every(o => Number(o) >= 0 && Number(o) <= 255);
+  }
+  return false;
+}
+
+/**
+ * Resolve the local-preset configuration.
+ *
+ * @returns {{ok:true, config:object} | {ok:false, reason:string}}
+ */
+export function localEndpointConfig(env = process.env) {
+  const endpoint = env.AGENTIC_SECURITY_LLM_ENDPOINT || DEFAULT_LOCAL_ENDPOINT;
+  if (!isLoopbackUrl(endpoint)) {
+    return {
+      ok: false,
+      reason: `the 'local' preset refuses a non-loopback endpoint: ${endpoint}. `
+        + 'The point of the local path is that source never leaves this machine, so a remote '
+        + 'address is refused rather than silently used. Only literal loopback addresses are '
+        + 'accepted — a hostname is not, because a resolver could point it anywhere. '
+        + 'Use AGENTIC_SECURITY_LLM_PRESET=anthropic (or a BYO endpoint) to call out deliberately.',
+    };
+  }
+  const timeoutRaw = Number(env.AGENTIC_SECURITY_LLM_TIMEOUT_MS);
+  return {
+    ok: true,
+    config: {
+      endpoint,
+      // No key. A local server that demands one can still receive it via the
+      // BYO path; the local preset does not invent credentials.
+      apiKey: env.AGENTIC_SECURITY_LLM_API_KEY || null,
+      model: env.AGENTIC_SECURITY_LLM_MODEL || 'local-model',
+      preset: 'local',
+      timeoutMs: Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? timeoutRaw : DEFAULT_LOCAL_TIMEOUT_MS,
+      // Stated so a report can say plainly that nothing left the machine.
+      egress: 'loopback-only',
+    },
+  };
+}
+
+/** Human explanation of the current local-path state. */
+export function renderLocalPath(cfg) {
+  if (!cfg) return null;
+  return `LLM validator: local path, ${cfg.endpoint} (loopback-enforced, no egress), model '${cfg.model}'.`;
+}
+
+export const _internals = { LOOPBACK_HOSTS };

package/src/posture/accuracy-scorecard.js

@@ -263,17 +263,48 @@ export function renderScorecardMarkdown(m) {
   L.push('');
   L.push('## Precision-side signal: self-scan (measured this run)');
   L.push('');
-  L.push('The engine scanned this repository\'s own hand-reviewed source. These are');
-  L.push('absolute finding counts, not a rate — there is no labelled ground truth');
-  L.push('over this code, so no precision figure is derived from it. What it');
-  L.push('supports is a movement claim: any change in these counts between');
-  L.push('releases is a real change in what the engine reports on unchanged code.');
+  L.push('The engine scanned its own repository. These are absolute finding');
+  L.push('counts, not a rate — there is no labelled ground truth over this code,');
+  L.push('so no precision figure is derived from it. What it supports is a');
+  L.push('movement claim: any change in these counts between releases is a real');
+  L.push('change in what the engine reports on unchanged code.');
+  L.push('');
+  L.push('**The two halves are not the same kind of evidence, so they are not');
+  L.push('reported together.** `hooks/` and `scripts/` were reviewed by hand,');
+  L.push('finding by finding. `scanner/src` was not: it is the engine itself, at a');
+  L.push('scale no one has read line by line, and a scanner\'s own source contains');
+  L.push('sink patterns as DATA — rule tables, catalogs, remediation strings — so a');
+  L.push('large share of its findings are self-referential rather than defects.');
+  L.push('Treat it as a tripwire, never as a quality figure.');
+  L.push('');
+  // Split deliberately. Both halves used to sit under a single "hand-reviewed"
+  // sentence; when `scanner/src` was added to the gate its 594 findings
+  // inherited a review claim that was true of 48 findings and false of these.
+  // Widening a gate must not silently upgrade what its numbers assert.
+  const REVIEWED = new Set(['hooks', 'scripts']);
+  const entries = Object.entries(m.selfScan.targets);
+  const reviewed = entries.filter(([k]) => REVIEWED.has(k));
+  const unreviewed = entries.filter(([k]) => !REVIEWED.has(k));
+
+  L.push('### Hand-reviewed targets');
   L.push('');
   L.push('| Target | Findings |');
   L.push('| --- | --- |');
-  for (const [k, v] of Object.entries(m.selfScan.targets)) L.push(`| \`${k}\` | ${v.total} |`);
+  for (const [k, v] of reviewed) L.push(`| \`${k}\` | ${v.total} |`);
   L.push(`| \`polyglot\` fixture (expected 0) | ${m.selfScan.polyglot.total} |`);
   L.push('');
+  if (unreviewed.length) {
+    L.push('### Drift tripwire — NOT hand-reviewed, NOT a precision signal');
+    L.push('');
+    L.push('| Target | Findings |');
+    L.push('| --- | --- |');
+    for (const [k, v] of unreviewed) L.push(`| \`${k}\` | ${v.total} |`);
+    L.push('');
+    L.push('These counts exist so that a rule which starts firing somewhere new is');
+    L.push('visible per file. Nobody has adjudicated them, and quoting the total as');
+    L.push('a false-positive count would be wrong in both directions.');
+    L.push('');
+  }
   L.push('Per-file counts are in `docs/scorecard.json`.');
   L.push('');
   L.push('## Committed artifacts referenced (not re-run by this command)');

package/src/posture/corpus-match.js

@@ -7,14 +7,26 @@
 // gate uses, it would cheerfully commit entries that fail CI. One
 // implementation, two callers.
 //
-// THE PRE/POST ASYMMETRY IS DELIBERATE AND PRESERVED VERBATIM. The `pre`
-// matcher accepts a hit on `vuln` OR `family` and regex-tests `cwe`; the
-// `post` matcher is strict on `vuln` and requires an exact `cwe`. This means
-// an entry faces a looser bar to score a TP than an FP, which
-// `bench/cve-replay/CONTRIBUTING.md` records as known imprecision to resolve
-// before the corpus grows toward 500. It is reproduced here rather than
-// quietly fixed: changing it would silently re-verdict entries across the
-// whole committed baseline, which is a corpus migration, not a refactor.
+// THE PRE/POST MATCHERS ARE NOW SYMMETRIC. They were not: `pre` accepted a hit
+// on `vuln` OR `family` and regex-tested `cwe`, while `post` was strict on
+// `vuln` and required an exact `cwe`. An entry therefore faced a LOOSER bar to
+// score a true positive than a false positive, which flatters the corpus —
+// exactly the direction a measurement must not lean. `CONTRIBUTING.md` recorded
+// it as known imprecision to resolve before the corpus grows toward 500.
+//
+// WHICH DIRECTION, AND WHY. The two sides were unified on the LOOSE predicate,
+// not the strict one. The question a corpus entry asks is "does the scanner
+// still report this vulnerability?", and a scanner that reports it under the
+// family name rather than the exact vuln string is still reporting it. Loose-
+// on-both means an entry must genuinely go quiet to score `post:TN` — a HIGHER
+// bar for a pass. Unifying on the strict predicate would instead have made
+// `pre:TP` harder and `post:TN` easier, i.e. it would have made the corpus
+// easier to satisfy. When a symmetry fix can go either way, take the direction
+// that makes the gate harder to pass.
+//
+// This re-verdicts every committed entry, so it is a corpus migration: the full
+// baseline was re-run against it and any entry whose verdict moved was fixed or
+// recorded, never baselined over.
 //
 // The scanner emits into several arrays — `findings` (SAST), `secrets`,
 // `supplyChain` (SCA) and `logicVulns` (business-logic + behavioural) — and a
@@ -35,18 +47,21 @@ function _any(scan, predicate) {
   return false;
 }
 
+// One predicate, both sides. See the header for why the symmetric form is the
+// LOOSE one.
+function _matches(f, manifest, matcher) {
+  return (matcher.test(f.vuln || '') || matcher.test(f.family || '')) &&
+    (manifest?.cwe ? f.cwe === manifest.cwe || matcher.test(f.cwe || '') : true);
+}
+
 /** Did the vulnerable (`pre/`) tree produce a matching finding? */
 export function preHit(scan, manifest, matcher = matcherFor(manifest)) {
-  return _any(scan, f =>
-    (matcher.test(f.vuln || '') || matcher.test(f.family || '')) &&
-    (manifest?.cwe ? f.cwe === manifest.cwe || matcher.test(f.cwe || '') : true));
+  return _any(scan, f => _matches(f, manifest, matcher));
 }
 
 /** Did the fixed (`post/`) tree still produce a matching finding? */
 export function postHit(scan, manifest, matcher = matcherFor(manifest)) {
-  return _any(scan, f =>
-    matcher.test(f.vuln || '') &&
-    (manifest?.cwe ? f.cwe === manifest.cwe : true));
+  return _any(scan, f => _matches(f, manifest, matcher));
 }
 
 export const _internals = { CHANNELS };