@clear-capabilities/agentic-security-scanner 0.195.29 → 0.195.30

package/src/posture/logic-claims.js

@@ -40,7 +40,7 @@
 // lenses live here in deterministic code rather than in the agent's prompt: a
 // reviewer asked to double-check itself is the same party voting twice.
 
-import { recordProducer, recordVerdict, consensusOf } from './verification-separation.js';
+import { recordProducer, recordVerdict, consensusOf, refutationRemoves } from './verification-separation.js';
 import { inferredInvariant } from './invariants/lifecycle.js';
 
 export const PRODUCER = 'agent:logic-reviewer';
@@ -132,7 +132,7 @@ export function verifyLogicClaim(claim, fileContents) {
   // ── citation ──────────────────────────────────────────────────────────────
   if (content === null) {
     recordVerdict(finding, {
-      verifierId: VERIFIER_CITATION, lens: 'citation', verdict: 'refuted',
+      verifierId: VERIFIER_CITATION, lens: 'citation', verdict: 'refuted', evidence: { kind: 'deterministic' },
       reason: `no file '${claim.file}' was scanned, so the cited location does not exist`,
     });
     finding.consensus = consensusOf(finding);
@@ -143,12 +143,12 @@ export function verifyLogicClaim(claim, fileContents) {
   const line = Number(claim.line);
   if (!Number.isInteger(line) || line < 1 || line > total) {
     recordVerdict(finding, {
-      verifierId: VERIFIER_CITATION, lens: 'citation', verdict: 'refuted',
+      verifierId: VERIFIER_CITATION, lens: 'citation', verdict: 'refuted', evidence: { kind: 'deterministic' },
       reason: `cited line ${claim.line} is outside ${claim.file} (${total} lines)`,
     });
   } else {
     recordVerdict(finding, {
-      verifierId: VERIFIER_CITATION, lens: 'citation', verdict: 'upheld',
+      verifierId: VERIFIER_CITATION, lens: 'citation', verdict: 'upheld', evidence: { kind: 'deterministic' },
       reason: `${claim.file}:${line} exists`,
     });
   }
@@ -158,7 +158,7 @@ export function verifyLogicClaim(claim, fileContents) {
   // snippet is UNDECIDED here, not upheld — silence is not corroboration.
   if (!claim.snippet || !String(claim.snippet).trim()) {
     recordVerdict(finding, {
-      verifierId: VERIFIER_QUOTATION, lens: 'quotation', verdict: 'undecided',
+      verifierId: VERIFIER_QUOTATION, lens: 'quotation', verdict: 'undecided', evidence: { kind: 'deterministic' },
       reason: 'the claim quotes no source, so there is nothing to check it against',
     });
   } else {
@@ -170,19 +170,19 @@ export function verifyLogicClaim(claim, fileContents) {
     const anywhere = _normalize(content);
     if (window.includes(want)) {
       recordVerdict(finding, {
-        verifierId: VERIFIER_QUOTATION, lens: 'quotation', verdict: 'upheld',
+        verifierId: VERIFIER_QUOTATION, lens: 'quotation', verdict: 'upheld', evidence: { kind: 'deterministic' },
         reason: 'the quoted source appears at the cited line',
       });
     } else if (anywhere.includes(want)) {
       // Right file, wrong line. Not a fabrication, but the location is not
       // usable as-is, so it is not corroboration either.
       recordVerdict(finding, {
-        verifierId: VERIFIER_QUOTATION, lens: 'quotation', verdict: 'undecided',
+        verifierId: VERIFIER_QUOTATION, lens: 'quotation', verdict: 'undecided', evidence: { kind: 'deterministic' },
         reason: 'the quoted source is in the file but not at the cited line',
       });
     } else {
       recordVerdict(finding, {
-        verifierId: VERIFIER_QUOTATION, lens: 'quotation', verdict: 'refuted',
+        verifierId: VERIFIER_QUOTATION, lens: 'quotation', verdict: 'refuted', evidence: { kind: 'deterministic' },
         reason: 'the quoted source does not appear in the cited file',
       });
     }
@@ -193,30 +193,31 @@ export function verifyLogicClaim(claim, fileContents) {
   if (finding.kind === 'missing-authentication') {
     const hit = AUTH_HINTS.find((re) => re.test(block));
     recordVerdict(finding, hit
-      ? { verifierId: VERIFIER_CORROBORATION, lens: 'authz', verdict: 'refuted',
+      ? { verifierId: VERIFIER_CORROBORATION, lens: 'authz', verdict: 'refuted', evidence: { kind: 'deterministic' },
         reason: `the handler around this line does authenticate (${hit.source})` }
-      : { verifierId: VERIFIER_CORROBORATION, lens: 'authz', verdict: 'upheld',
+      : { verifierId: VERIFIER_CORROBORATION, lens: 'authz', verdict: 'upheld', evidence: { kind: 'deterministic' },
         reason: 'no authentication marker anywhere in the enclosing handler' });
   } else if (finding.kind === 'missing-authorization' || finding.kind === 'missing-ownership-check') {
     const hit = OWNERSHIP_HINTS.find((re) => re.test(block));
     recordVerdict(finding, hit
-      ? { verifierId: VERIFIER_CORROBORATION, lens: 'authz', verdict: 'refuted',
+      ? { verifierId: VERIFIER_CORROBORATION, lens: 'authz', verdict: 'refuted', evidence: { kind: 'deterministic' },
         reason: `the handler around this line does scope the record to a user (${hit.source})` }
-      : { verifierId: VERIFIER_CORROBORATION, lens: 'authz', verdict: 'upheld',
+      : { verifierId: VERIFIER_CORROBORATION, lens: 'authz', verdict: 'upheld', evidence: { kind: 'deterministic' },
         reason: 'no ownership scoping in the enclosing handler' });
   } else {
     // No deterministic lens exists for this kind. Said out loud rather than
     // counted as agreement — an unchecked claim and a corroborated one must
     // not read the same in the consensus.
     recordVerdict(finding, {
-      verifierId: VERIFIER_CORROBORATION, lens: 'authz', verdict: 'undecided',
+      verifierId: VERIFIER_CORROBORATION, lens: 'authz', verdict: 'undecided', evidence: { kind: 'deterministic' },
       reason: `no deterministic lens covers claim kind '${finding.kind}'`,
     });
   }
 
   finding.consensus = consensusOf(finding);
   // Quarantine, not deletion — the same contract falsification uses.
-  finding.quarantined = finding.consensus.verdict === 'refuted';
+  // threat-model FR-04.3: a critical claim is quarantined only on a refutation with sufficient independent authority
+  finding.quarantined = refutationRemoves(finding, finding.consensus);
   return finding;
 }
 

package/src/posture/sibling-queue.js

@@ -0,0 +1,69 @@
+// Sibling review queue for a confirmed root cause (threat-model PRD FR-05.3, AC-05C).
+//
+// The root-cause sweep (`root-cause-sweep.js`) finds structural siblings of a confirmed finding and counts them exactly. Its
+// `mitigated` count means only that a DETECTOR already reports a finding at that location: detector coverage, not a repair. This
+// queue turns one sweep into reviewable items, each with the predicate that discovered it and a binding to its source line, and keeps
+// six states apart:
+//
+//   detector-reported         a detector reports this location (the sweep's legacy `mitigated`)
+//   candidate                 a structural sibling nobody has looked at
+//   independently-confirmed   a reviewer or verifier other than the producer confirmed it
+//   repair-proposed           a fix has been proposed for it
+//   repaired                  a fix has been applied to it
+//   verified                  a replay-verified repair record for THIS sibling (its own hypothesis id) exists
+//
+// A state is raised only by evidence that names the sibling by its id. A verification record for one corrected sibling never closes
+// another, however similar. Totals come from the sweep's exact counts; the per-state counts cover the sampled items, and `unsampled`
+// is what the sample left out, so the numbers reconcile when the sweep capped its list.
+import crypto from 'node:crypto';
+import { validateVerificationRecord } from './assurance/verification-record.js';
+
+const SIBLING_STATES = Object.freeze(['detector-reported', 'candidate', 'independently-confirmed', 'repair-proposed', 'repaired', 'verified']);
+const RANK = Object.fromEntries(SIBLING_STATES.map((s, i) => [s, i]));
+const MAX_QUEUE = 100;
+
+/** The stable id of one sibling: its file, line and the exact text of the matched line. */
+export const siblingId = (file, line, snippet) => `sibling:${crypto.createHash('sha256').update(`${file}\u0000${line}\u0000${snippet}`).digest('hex').slice(0, 24)}`;
+
+function raise(item, state, basis) { if (RANK[state] > RANK[item.state]) { item.state = state; item.basis = basis; } }
+
+/**
+ * @param {object} sweep    one entry of `sweepRootCauses(...).sweeps`
+ * @param {{evidence?: {siblingId:string, kind:'confirmation'|'repair-proposal'|'repair'|'verification', by?:string, record?:object}[], producer?:string}} o
+ */
+export function buildSiblingQueue(sweep, { evidence = [], producer = null } = {}) {
+  if (!sweep || typeof sweep !== 'object') return { ok: false, reason: 'no sweep' };
+  const items = (sweep.instances || []).slice(0, MAX_QUEUE).map((m) => ({
+    id: siblingId(m.file, m.line, m.snippet), file: m.file, line: m.line,
+    discovery: { fromFindingId: sweep.fromFindingId ?? null, sinkPattern: sweep.sinkPattern ?? null, sourcePattern: sweep.sourcePattern ?? null },
+    state: m.status === 'mitigated-or-known' ? 'detector-reported' : 'candidate',
+    basis: m.status === 'mitigated-or-known' ? 'a detector reports a finding at this location (detector coverage, not a repair)' : 'structural sibling of the confirmed root cause',
+    rejected: [],
+  }));
+  const byId = new Map(items.map((it) => [it.id, it]));
+  for (const e of evidence) {
+    const it = e && byId.get(e.siblingId);
+    if (!it) continue; // evidence for a sibling not in this queue changes nothing here
+    if (e.kind === 'confirmation') {
+      if (!e.by || (producer && e.by === producer)) { it.rejected.push({ kind: e.kind, reason: 'a confirmation must come from a party other than the producer' }); continue; }
+      raise(it, 'independently-confirmed', `confirmed by ${String(e.by).slice(0, 60)}`);
+    } else if (e.kind === 'repair-proposal') raise(it, 'repair-proposed', 'a repair was proposed');
+    else if (e.kind === 'repair') raise(it, 'repaired', 'a repair was applied');
+    else if (e.kind === 'verification') {
+      const r = e.record;
+      const v = r ? validateVerificationRecord(r) : { ok: false };
+      if (!v.ok) { it.rejected.push({ kind: e.kind, reason: 'the verification record failed validation' }); continue; }
+      if (r.hypothesisId !== it.id) { it.rejected.push({ kind: e.kind, reason: 'the record verifies another sibling' }); continue; }
+      if (!r.repair || r.repair.status !== 'replay-verified') { it.rejected.push({ kind: e.kind, reason: 'the record is not a replay-verified repair' }); continue; }
+      raise(it, 'verified', `replay-verified repair record ${String(r.id).slice(0, 24)}`);
+    }
+  }
+  const counts = Object.fromEntries(SIBLING_STATES.map((s) => [s, 0]));
+  for (const it of items) counts[it.state]++;
+  const found = Number(sweep.found ?? items.length);
+  return {
+    ok: true, fromFindingId: sweep.fromFindingId ?? null, items,
+    totals: { found, detectorReported: Number(sweep.mitigated ?? 0), candidatesAtDiscovery: Number(sweep.candidates ?? 0), sampled: items.length, unsampled: Math.max(0, found - items.length), byState: counts },
+    note: 'detector-reported means a detector covers the location; only a verified item has a replay-verified repair of its own',
+  };
+}

package/src/posture/triage-memory.js

@@ -17,9 +17,18 @@
 // why") rather than on calibration math.
 //
 // Opt-out: AGENTIC_SECURITY_NO_TRIAGE_MEMORY=1
+//
+// Threat-model PRD FR-05 (TM-07): a family/directory bucket, and any legacy free-text record, is ADVISORY history. It is attached to
+// a finding so a reviewer can see it, and it never changes the finding's confidence. Only an EXACT decision (the same stable finding
+// id in the same file) applies, and for a critical or high finding it also needs a named reviewer, an expiry that has not passed, a
+// scope that matches this scan, an unchanged source fingerprint and a signature made with this install's key. Each finding's
+// `pastDecision.status` says which: applied, advisory, expired, stale, out-of-scope or rejected. The free-text reason stays in the
+// memory file and is never copied into a report.
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { signLastScan } from './integrity.js';
 
 import { stateDir, stateWritesEnabled } from './state-dir.js';
 const MEMORY_FILE = 'triage-memory.jsonl';
@@ -40,11 +49,15 @@ function _bucketKey(finding) {
  * triage-memory.jsonl (structured). Idempotent — repeated calls add a
  * single new line; existing entries are not deduped (history is a feature).
  */
-export function recordDecision(scanRoot, finding, decision, reason) {
+export function recordDecision(scanRoot, finding, decision, reason, opts = {}) {
   if (!scanRoot || !finding || !decision) return null;
   if (!['wont-fix', 'false-positive'].includes(decision)) return null;
   if (!stateWritesEnabled()) return false;
   try { fs.mkdirSync(_stateDir(scanRoot), { recursive: true }); } catch {}
+  // a retried call with the same decision for the same finding adds nothing (idempotent under retry)
+  const sid = finding.stableId || finding.id || null;
+  const prior = loadMemory(scanRoot).find((e) => e.stableId && e.stableId === sid && e.decision === decision && e.file === (finding.file || finding.file_path || '') && (e.reviewer || null) === (opts.reviewer || null) && (e.expires || null) === (opts.expires || null));
+  if (prior) return prior;
 
   const entry = {
     at: new Date().toISOString(),
@@ -58,7 +71,14 @@ export function recordDecision(scanRoot, finding, decision, reason) {
     file: finding.file || finding.file_path || '',
     line: finding.line || 0,
     id: finding.id || finding.stableId || null,
+    // exact binding (FR-05.1): the stable id, the source fingerprint the decision was made on, and its scope, reviewer and expiry
+    stableId: sid,
+    fingerprint: findingFingerprint(finding),
+    ...(opts.reviewer ? { reviewer: String(opts.reviewer).slice(0, 120) } : {}),
+    ...(opts.expires ? { expires: String(opts.expires) } : {}),
+    ...(opts.scope ? { scope: pickScope(opts.scope) } : {}),
   };
+  if (entry.reviewer && entry.expires) entry.sig = signEntry(entry);
   try { fs.appendFileSync(_memPath(scanRoot), JSON.stringify(entry) + '\n'); } catch {}
 
   // Narrative entry in AGENTS.md — short, human-readable, surfaced at SessionStart.
@@ -67,7 +87,7 @@ export function recordDecision(scanRoot, finding, decision, reason) {
     `- Finding: ${entry.vuln || entry.family || 'unknown'} at ${entry.file}:${entry.line}`,
     `- Bucket: \`${entry.bucket}\``,
     reason ? `- Why: ${entry.reason}` : null,
-    `- Future scans should treat similar findings under this bucket as already-reviewed.`,
+    `- Advisory only: similar findings under this bucket are NOT reviewed by this decision; each new finding is judged on its own.`,
     '',
   ].filter(Boolean).join('\n');
   try { fs.appendFileSync(_agentsPath(scanRoot), '\n' + narrative); } catch {}
@@ -78,16 +98,59 @@ export function recordDecision(scanRoot, finding, decision, reason) {
 /**
  * Load past decisions from triage-memory.jsonl.
  */
-export function loadMemory(scanRoot) {
+export function loadMemory(scanRoot) { return loadMemoryWithDiagnostics(scanRoot).entries; }
+
+const MAX_MEMORY_BYTES = 8 * 1024 * 1024;
+/** Load past decisions with bounded diagnostics: malformed lines (a torn write) are counted and skipped, never fatal. */
+export function loadMemoryWithDiagnostics(scanRoot) {
   const fp = _memPath(scanRoot);
-  if (!fs.existsSync(fp)) return [];
+  const out = { entries: [], malformed: 0, unreadable: false, truncated: false };
+  let text;
   try {
-    return fs.readFileSync(fp, 'utf8')
-      .split('\n').filter(Boolean)
-      .map(l => { try { return JSON.parse(l); } catch { return null; } })
-      .filter(Boolean);
-  } catch { return []; }
+    const st = fs.statSync(fp);
+    if (st.size > MAX_MEMORY_BYTES) out.truncated = true;
+    const fd = fs.openSync(fp, 'r');
+    try { const buf = Buffer.alloc(Math.min(st.size, MAX_MEMORY_BYTES)); fs.readSync(fd, buf, 0, buf.length, 0); text = buf.toString('utf8'); } finally { fs.closeSync(fd); }
+  } catch (e) { if (e && e.code !== 'ENOENT') out.unreadable = true; return out; }
+  for (const l of text.split('\n')) {
+    if (!l.trim()) continue;
+    try { const e = JSON.parse(l); if (e && typeof e === 'object' && !Array.isArray(e)) out.entries.push(e); else out.malformed++; } catch { out.malformed++; }
+  }
+  return out;
+}
+
+// ── exact decisions (threat-model FR-05) ─────────────────────────────────────────────────────────────────────────────────────────────
+const SCOPE_KEYS = ['repository', 'environment', 'tenant'];
+function pickScope(s) { const o = {}; for (const k of SCOPE_KEYS) if (s && s[k]) o[k] = String(s[k]).slice(0, 120); return o; }
+/** The source fingerprint a decision is bound to: the finding record's source hash when there is one, else its location and snippet. */
+function findingFingerprint(f) {
+  const h = f.findingRecord?.sourceHash || f.record?.sourceHash || f.sourceHash;
+  if (h) return String(h);
+  return crypto.createHash('sha256').update(JSON.stringify([f.file || '', f.line || 0, f.cwe || '', String(f.snippet || '').slice(0, 400)])).digest('hex');
+}
+const SIGNED_FIELDS = ['decision', 'stableId', 'file', 'fingerprint', 'reviewer', 'expires', 'scope'];
+function canonicalEntry(e) { return JSON.stringify(SIGNED_FIELDS.map((k) => [k, e[k] ?? null])); }
+function signEntry(e) { return signLastScan(canonicalEntry(e)); }
+function signatureValid(e) {
+  if (typeof e.sig !== 'string') return false;
+  const want = signEntry(e);
+  return want.length === e.sig.length && crypto.timingSafeEqual(Buffer.from(want, 'hex'), Buffer.from(e.sig, 'hex'));
 }
+const CONSEQUENTIAL = new Set(['critical', 'high']);
+
+/** How one exact decision bears on one finding now: applied | expired | out-of-scope | stale | advisory | rejected, with a reason code. */
+function judgeExact(e, f, ctx) {
+  const now = ctx.now ?? Date.now();
+  if (e.expires && !(Date.parse(e.expires) > now)) return { status: 'expired', code: 'expired' };
+  for (const k of SCOPE_KEYS) if (e.scope && e.scope[k] && ctx[k] && e.scope[k] !== ctx[k]) return { status: 'out-of-scope', code: `${k}-differs` };
+  if (e.fingerprint && e.fingerprint !== findingFingerprint(f)) return { status: 'stale', code: 'source-changed' };
+  if (CONSEQUENTIAL.has(f.severity)) {
+    if (!e.reviewer || !e.expires) return { status: 'advisory', code: 'unreviewed-or-unexpiring' };
+    if (!signatureValid(e)) return { status: 'rejected', code: e.sig ? 'signature-invalid' : 'unsigned' };
+  }
+  return { status: 'applied', code: 'exact-match' };
+}
+const reasonDigest = (r) => (r ? crypto.createHash('sha256').update(String(r)).digest('hex').slice(0, 16) : null);
 
 /**
  * Annotator: for each finding, check if its (family, file-glob) bucket
@@ -97,11 +160,18 @@ export function loadMemory(scanRoot) {
  * Does NOT remove findings — only annotates. UI / report layer decides
  * how to display.
  */
-export function suppressByPastDecisions(scanRoot, findings) {
+export function suppressByPastDecisions(scanRoot, findings, ctx = {}) {
   if (process.env.AGENTIC_SECURITY_NO_TRIAGE_MEMORY === '1') return { applied: 0 };
   if (!Array.isArray(findings) || findings.length === 0) return { applied: 0 };
-  const memory = loadMemory(scanRoot);
-  if (!memory.length) return { applied: 0 };
+  const diag = loadMemoryWithDiagnostics(scanRoot);
+  const memory = diag.entries;
+  if (!memory.length) return { applied: 0, diagnostics: { malformed: diag.malformed, unreadable: diag.unreadable, truncated: diag.truncated } };
+  const exactById = new Map();
+  for (const e of memory) {
+    if (!e.stableId) continue;
+    const k = `${e.stableId}\u0000${e.file || ''}`;
+    if (!exactById.has(k) || exactById.get(k).at < e.at) exactById.set(k, e);
+  }
 
   // Build bucket → most-recent decision map.
   const bucketDecision = new Map();
@@ -111,24 +181,34 @@ export function suppressByPastDecisions(scanRoot, findings) {
     }
   }
 
-  let applied = 0;
+  let applied = 0; let advisory = 0;
+  const byStatus = {};
   for (const f of findings) {
-    const key = _bucketKey(f);
-    const past = bucketDecision.get(key);
+    const exact = exactById.get(`${f.stableId || f.id || ''}\u0000${f.file || f.file_path || ''}`);
+    const past = exact || bucketDecision.get(_bucketKey(f));
     if (!past) continue;
-    f.pastDecision = {
-      decision: past.decision,
-      at: past.at,
-      reason: past.reason,
-      sameBucket: true,
-    };
-    // Soft demote: drop confidence and add a tag explaining why.
-    if (typeof f.confidence === 'number') f.confidence = Math.max(0.2, f.confidence * 0.5);
+    const j = exact ? judgeExact(exact, f, ctx) : { status: 'advisory', code: 'family-directory-bucket' };
+    byStatus[j.status] = (byStatus[j.status] || 0) + 1;
+    // the reason is a digest here: the free text stays in the memory file and never reaches a report
+    f.pastDecision = { status: j.status, basis: exact ? 'exact' : 'bucket', reasonCode: j.code, decision: past.decision, at: past.at, reasonDigest: reasonDigest(past.reason), ...(exact && exact.reviewer ? { reviewer: exact.reviewer } : {}), ...(exact && exact.expires ? { expires: exact.expires } : {}), sameBucket: !exact };
     f.tags = Array.isArray(f.tags) ? f.tags : [];
-    if (!f.tags.includes('past-decision')) f.tags.push('past-decision');
-    applied++;
+    if (j.status === 'applied') {
+      // an exact, in-scope decision: the soft demote and tag, as before
+      if (typeof f.confidence === 'number') f.confidence = Math.max(0.2, f.confidence * 0.5);
+      if (!f.tags.includes('past-decision')) f.tags.push('past-decision');
+      applied++;
+    } else {
+      if (!f.tags.includes('past-decision-advisory')) f.tags.push('past-decision-advisory');
+      advisory++;
+    }
   }
-  return { applied, total: findings.length };
+  return { applied, advisory, byStatus, total: findings.length, diagnostics: { malformed: diag.malformed, unreadable: diag.unreadable, truncated: diag.truncated } };
+}
+
+/** True only for a past decision that applies; an advisory, expired, stale, out-of-scope or rejected one leaves the finding open. */
+export function pastDecisionApplies(pd) {
+  if (pd === true) return true; // a legacy boolean marker set by an older caller
+  return !!pd && typeof pd === 'object' && (pd.status === undefined || pd.status === 'applied');
 }
 
 /**

package/src/posture/verification-separation.js

@@ -86,7 +86,7 @@ export function assertSeparation(finding, verifierId) {
  * nothing — when separation fails or the verdict is not one of
  * VERIFICATION_VERDICTS. Never touches severity, never removes anything.
  */
-export function recordVerdict(finding, { verifierId, lens, verdict, reason } = {}) {
+export function recordVerdict(finding, { verifierId, lens, verdict, reason, evidence } = {}) {
   if (!finding || typeof finding !== 'object') return _refuse('no finding');
   if (!lens) return _refuse('no lens');
   if (!VERIFICATION_VERDICTS.includes(verdict)) {
@@ -100,6 +100,7 @@ export function recordVerdict(finding, { verifierId, lens, verdict, reason } = {
     lens: String(lens),
     verdict,
     ...(reason ? { reason: String(reason) } : {}),
+    ...(evidence && typeof evidence === 'object' ? { evidence: _evidence(evidence) } : {}),
   };
   const list = finding.verification.verdicts;
   const i = list.findIndex(v => v.verifierId === entry.verifierId && v.lens === entry.lens);
@@ -107,10 +108,29 @@ export function recordVerdict(finding, { verifierId, lens, verdict, reason } = {
   return { ok: true, recorded: entry };
 }
 
+// Threat-model PRD FR-04.3 (TM-06): what a verdict rests on. Votes that share an observation, a generator or a lineage are ONE piece of
+// evidence however many lenses they come through; a verdict with none declared counts as its verifier's own. `kind` says what sort of
+// evidence it is: 'effect' (an observed effect), 'deterministic' (a check of the code itself) or 'reasoning' (an argument, a model).
+const EVIDENCE_KINDS = new Set(['effect', 'deterministic', 'reasoning']);
+function _evidence(e) {
+  const out = {};
+  for (const k of ['observationId', 'generator', 'lineage']) if (e[k]) out[k] = String(e[k]).slice(0, 120);
+  if (EVIDENCE_KINDS.has(e.kind)) out.kind = e.kind;
+  return out;
+}
+function _groupKey(v) {
+  const e = v.evidence || {};
+  return e.observationId ? `observation:${e.observationId}` : e.lineage ? `lineage:${e.lineage}` : e.generator ? `generator:${e.generator}` : `verifier:${v.verifierId}`;
+}
+
 /**
- * Majority across every recorded verdict. Ties — including "no verdicts at
- * all" — are 'undecided'. `lenses` is the sorted set of perspectives that
- * actually voted, so a caller can see whether a verdict is one-eyed or a panel.
+ * Majority across INDEPENDENT evidence groups (threat-model FR-04.3). Each group (a shared observation, generator or lineage, else one
+ * verifier) has one vote, the majority of its own verdicts; two lenses from one verifier are one vote. Ties, including "no verdicts at
+ * all", are 'undecided'. The per-lens counts (`upheld`, `refuted`, `undecided`) and `lenses` are kept for compatibility and for the
+ * reviewer. `conflict` is true when independent groups disagree. `refutationAuthority` says whether the refutation could remove a
+ * critical finding from the actionable queue: 'sufficient' only with no conflict and at least one refuting group backed by effect or
+ * deterministic evidence; a correlated majority or reasoning alone is 'advisory'. A generator that produced the finding cannot
+ * corroborate it.
  */
 export function consensusOf(finding) {
   const list = (finding && finding.verification && Array.isArray(finding.verification.verdicts))
@@ -124,8 +144,36 @@ export function consensusOf(finding) {
     else if (v.verdict === 'refuted') refuted++;
     else if (v.verdict === 'undecided') undecided++;
   }
+  const producer = finding && finding.verification && finding.verification.producer;
+  const groups = new Map();
+  let selfAuthored = 0;
+  for (const v of list) {
+    if (!v || !VERIFICATION_VERDICTS.includes(v.verdict)) continue;
+    if (producer && v.evidence && v.evidence.generator && `detector:${v.evidence.generator}` === producer) { selfAuthored++; continue; }
+    const k = _groupKey(v);
+    const g = groups.get(k) || { key: k, upheld: 0, refuted: 0, undecided: 0, kinds: new Set(), lenses: new Set() };
+    g[v.verdict]++; if (v.evidence && v.evidence.kind) g.kinds.add(v.evidence.kind); g.lenses.add(String(v.lens));
+    groups.set(k, g);
+  }
+  const vote = (g) => (g.upheld > g.refuted ? 'upheld' : g.refuted > g.upheld ? 'refuted' : 'undecided');
+  const independent = { upheld: 0, refuted: 0, undecided: 0, groups: groups.size };
+  for (const g of groups.values()) independent[vote(g)]++;
   let verdict = 'undecided';
-  if (upheld > refuted) verdict = 'upheld';
-  else if (refuted > upheld) verdict = 'refuted';
-  return { verdict, upheld, refuted, undecided, lenses: [...lenses].sort() };
+  if (independent.upheld > independent.refuted) verdict = 'upheld';
+  else if (independent.refuted > independent.upheld) verdict = 'refuted';
+  const conflict = independent.upheld > 0 && independent.refuted > 0;
+  const strongRefuter = [...groups.values()].some((g) => vote(g) === 'refuted' && (g.kinds.has('effect') || g.kinds.has('deterministic')));
+  const refutationAuthority = verdict !== 'refuted' ? 'none' : (!conflict && strongRefuter ? 'sufficient' : 'advisory');
+  return {
+    verdict, upheld, refuted, undecided, lenses: [...lenses].sort(),
+    independent, conflict, refutationAuthority, ...(selfAuthored ? { selfAuthoredExcluded: selfAuthored } : {}),
+    groups: [...groups.values()].map((g) => ({ key: g.key, vote: vote(g), lenses: [...g.lenses].sort(), kinds: [...g.kinds].sort() })).sort((a, b) => a.key.localeCompare(b.key)),
+  };
+}
+
+/** Whether a refuted consensus may take a finding of this severity out of the actionable queue. Critical needs sufficient authority. */
+export function refutationRemoves(finding, consensus = consensusOf(finding)) {
+  if (!consensus || consensus.verdict !== 'refuted') return false;
+  if (finding && finding.severity === 'critical') return consensus.refutationAuthority === 'sufficient';
+  return true;
 }

package/src/report/index.js

@@ -776,6 +776,10 @@ export function toJSON(scan, meta={}, opts={}){
     // hand-built `scan` object in a test), same convention as the S7 fields
     // above; a real scan always computes it.
      ...(scan.scanRecord ? { scanRecord: scan.scanRecord } : {}),
+     // Threat-model FR-01.1: the scan scope (policy, exact totals, reasons, overrides, coverage conditions, the inventory digest and
+     // bounded samples) whenever the scan computed one. Absent for a legacy (non-Git-scoped) scan, which therefore cannot satisfy a
+     // strict scope gate.
+     ...(scan.scope ? { scope: scan.scope } : {}),
      ...(scan.reportView ? { reportView: scan.reportView } : {}),
      ...(scan.dispositionCounts ? { dispositionCounts: scan.dispositionCounts } : {}),
      // PRD FR 05: every candidate stays discoverable. Equivalent claims grouped under a primary are listed here, and the

package/src/runScan.js

@@ -301,11 +301,16 @@ export async function runScan(rootDir, opts = {}) {
       // The included list itself lets a later comparison tell "no longer reported because it was fixed" from "no longer reported
       // because a narrower scan did not look". Kept only when small enough not to bloat the record.
       ...(scopeInventory.included.length <= 5000 ? { included: scopeInventory.included } : { includedOmitted: true }),
+      // Threat-model FR-01.1: the digest covers every decision before the caps below; the lists are samples, the counts are exact.
+      inventoryDigest: scopeInventory.digest,
       skippedCount: scopeInventory.skipped.length,
       skippedByReason: reasons,
+      skippedSampled: scopeInventory.skipped.length > 500,
       skipped: scopeInventory.skipped.slice(0, 500),
       overrides: scopeInventory.overrides,
       coverageConditions: scopeInventory.skipped.filter((x) => x.coverageCondition).slice(0, 100),
+      // eligibility is not analysis: how many eligible files were actually read, and how many were too large to read
+      read: { files: Object.keys(fileContents || {}).length + Object.keys(depFileContents || {}).length, oversize: Array.isArray(sizeSkipped) ? sizeSkipped.length : 0 },
     };
   }
   // FR 10: additive evidence contract. Finding records carry the source hash and span; the scan record ties the run to a commit,

package/src/scope/flags.js

@@ -35,6 +35,7 @@ export function renderScopePreview(inv, { maxLines = 40 } = {}) {
   const p = inv.policy;
   L.push(`Scope mode: ${p.mode}${p.respectGitignore ? '' : ' (git ignore rules disabled)'}; tracked-file semantics: ${p.trackedFileSemantics ? 'yes' : 'no'}`);
   if (p.ruleDigest) L.push(`Effective ignore-rule digest: ${p.ruleDigest}`);
+  if (inv.digest) L.push(`Inventory digest: ${inv.digest}`);
   for (const d of p.disclosures) L.push(`Disclosure: ${d}`);
   L.push(`Included: ${inv.included.length} file(s)`);
   for (const f of inv.included.slice(0, maxLines)) L.push(`  + ${f}`);

package/src/scope/inventory.js

@@ -220,7 +220,23 @@ export function buildScanInventory(root, o = {}) {
   }
 
   included.sort();
-  return { included, skipped, overrides, policy };
+  return { included, skipped, overrides, policy, digest: inventoryDigest({ included, skipped, overrides, policy }) };
+}
+
+/**
+ * Threat-model FR-01.1: a deterministic digest over the COMPLETE normalized eligibility decisions (every included path, every skipped
+ * path and its reason, every override, and the policy), computed before any display cap. Two scans with the same digest made the same
+ * eligibility decisions; an `--include-path` changes it. Eligibility is not analysis: a file can be eligible and still not be read.
+ */
+export function inventoryDigest({ included, skipped, overrides, policy }) {
+  const canon = {
+    v: 1,
+    policy: { mode: policy.mode, respectGitignore: !!policy.respectGitignore, trackedFileSemantics: !!policy.trackedFileSemantics, ruleDigest: policy.ruleDigest ?? null },
+    included: [...included].sort(),
+    skipped: skipped.map((x) => `${x.path}\u0000${x.reason}`).sort(),
+    overrides: overrides.map((x) => `${x.path}\u0000${x.overrode}`).sort(),
+  };
+  return crypto.createHash('sha256').update(JSON.stringify(canon)).digest('hex');
 }
 
 function walkAll(root) {

package/src/scope/release-scope.js

@@ -0,0 +1,80 @@
+// Release scope reconciliation (threat-model PRD FR-01.2, AC-01B, AC-01C).
+//
+// An ordinary scan reports its own scope and is never failed by this module. A QUALIFIED release claim reconciles the scan against
+// what actually ships: the authoritative build or package inventory, the route manifest and the artifact's source binding. Every
+// critical shipped unit and route ends in one of: covered, excluded (with the scope's reason), excepted (a scoped, independently
+// verified compensating control that has not expired), unsupported or unknown. The gate is satisfied only when every critical item is
+// covered or excepted and the binding is current. A report with no scope (a legacy or non-Git-scoped scan) cannot satisfy it.
+//
+// Pure: report and declarations in, decision out. No file is read.
+
+const norm = (p) => String(p ?? '').replace(/\\/g, '/').replace(/^\.\//, '');
+// `/records/:id`, `/records/{id}` and `/records/<id>` are the same template
+const routeKey = (method, path) => `${String(method ?? 'GET').toUpperCase()} ${String(path ?? '').replace(/(?::[A-Za-z_]\w*|\{[^}/]+\}|<[^>/]+>)/g, ':p').replace(/\/+$/, '') || '/'}`;
+
+function exceptionFor(exceptions, kind, key, now) {
+  for (const e of exceptions || []) {
+    if (!e || e.kind !== kind || norm(e.target) !== norm(key)) continue;
+    const c = e.compensatingControl;
+    if (!c || !c.id || !c.verifiedBy || c.independent !== true) return { ok: false, reason: 'the exception names no independently verified compensating control' };
+    if (!e.expires || !(Date.parse(e.expires) > now)) return { ok: false, reason: e.expires ? 'the exception has expired' : 'the exception has no expiry' };
+    return { ok: true, control: c.id, expires: e.expires };
+  }
+  return null;
+}
+
+/**
+ * @param {object} report  the JSON report (`scope`, `routes`, `scanRecord`)
+ * @param {{shipped?:{path:string,critical?:boolean,provenance?:string}[], routes?:{method:string,path:string,critical?:boolean}[],
+ *          artifact?:{sourceCommit?:string}|null, exceptions?:object[], now?:number}} d
+ */
+export function evaluateReleaseScope(report, d = {}) {
+  const now = d.now ?? Date.now();
+  const reasons = [];
+  const items = [];
+  const scope = report && report.scope;
+  if (!scope) {
+    return { status: 'unresolved', reasons: [{ code: 'scope-missing', detail: 'the report carries no scan scope (a legacy or non-Git-scoped scan), so what it covered cannot be shown' }], items };
+  }
+  const included = Array.isArray(scope.included) ? new Set(scope.included.map(norm)) : null;
+  const skippedByPath = new Map((scope.skipped || []).map((s) => [norm(s.path), s]));
+  const skippedUnder = (p) => { for (const [k, s] of skippedByPath) if (k.endsWith('/') ? p.startsWith(k) : (p === k || p.startsWith(`${k}/`))) return s; return null; };
+
+  for (const u of d.shipped || []) {
+    const p = norm(u.path);
+    let outcome; let reason = null;
+    if (included && included.has(p)) outcome = 'covered';
+    else if (skippedUnder(p)) { outcome = 'excluded'; reason = skippedUnder(p).reason; }
+    else if (!included) { outcome = 'unknown'; reason = 'the scan recorded only counts for its included files (too many to list), so this file cannot be confirmed'; }
+    else { outcome = 'unknown'; reason = 'the shipped file is neither in the scan\'s inventory nor among its recorded exclusions'; }
+    if (outcome !== 'covered') {
+      const ex = exceptionFor(d.exceptions, 'file', p, now);
+      if (ex && ex.ok) { outcome = 'excepted'; reason = `compensating control ${ex.control} until ${ex.expires}`; }
+      else if (ex) reason = `${reason}; ${ex.reason}`;
+    }
+    items.push({ kind: 'file', target: p, critical: u.critical !== false, outcome, reason, provenance: u.provenance ?? 'build-inventory' });
+  }
+
+  const scanned = new Set((report.routes || []).filter((r) => r && r.path && r.path !== '(file-based)').map((r) => routeKey(r.method, r.path)));
+  for (const r of d.routes || []) {
+    const key = routeKey(r.method, r.path);
+    let outcome = scanned.has(key) ? 'covered' : 'unknown';
+    let reason = outcome === 'covered' ? null : 'no route in the scanned code matches this manifest entry';
+    if (outcome !== 'covered') {
+      const ex = exceptionFor(d.exceptions, 'route', key, now);
+      if (ex && ex.ok) { outcome = 'excepted'; reason = `compensating control ${ex.control} until ${ex.expires}`; }
+      else if (ex) reason = `${reason}; ${ex.reason}`;
+    }
+    items.push({ kind: 'route', target: key, critical: r.critical !== false, outcome, reason, provenance: 'route-manifest' });
+  }
+
+  const source = report.scanRecord && report.scanRecord.source;
+  if (d.artifact && d.artifact.sourceCommit) {
+    if (!source || !source.commit) reasons.push({ code: 'binding-unknown', detail: 'the report records no source commit, so the artifact cannot be bound to it' });
+    else if (source.commit !== d.artifact.sourceCommit) reasons.push({ code: 'stale-binding', detail: `the artifact was built from ${String(d.artifact.sourceCommit).slice(0, 12)} but the scan was of ${String(source.commit).slice(0, 12)}` });
+    else if (source.dirty) reasons.push({ code: 'dirty-input', detail: 'the scanned tree had uncommitted changes, so it is not exactly the artifact\'s source' });
+  } else reasons.push({ code: 'artifact-unbound', detail: 'no artifact source commit was declared, so the scan is not bound to what ships' });
+
+  for (const it of items) if (it.critical && it.outcome !== 'covered' && it.outcome !== 'excepted') reasons.push({ code: `${it.kind}-${it.outcome}`, detail: `${it.target}: ${it.reason}` });
+  return { status: reasons.length ? 'unresolved' : 'satisfied', reasons, items, inventoryDigest: scope.inventoryDigest ?? null };
+}