@clear-capabilities/agentic-security-scanner 0.195.21 → 0.195.23

package/src/posture/provenance/coordinator.js

@@ -206,6 +206,14 @@ function describePartial(isScaLike, reason) {
         reasons: ['rename_detected_not_followed'],
       };
     }
+    // GA-05: the parent of the candidate commit could not be inspected (the replay there failed), so absence in it is unproven.
+    // This is not "we could not see far enough" (shallow) and not "it was never true" (never confirmed): it is "we do not know".
+    if (reason === 'parent-not-inspectable') {
+      return {
+        limitation: 'a candidate commit was found but the replay in its parent failed, so absence there is unproven; the introducing commit is the earliest observable, not a verified boundary',
+        reasons: ['parent_not_inspectable'],
+      };
+    }
     return {
       limitation: reason
         ? `earliest observable — history could not confirm a verified parent boundary (${reason})`

package/src/posture/provenance/origin-resolver.js

@@ -25,6 +25,9 @@
 
 import { candidateCommitsForLine, candidateCommitsForFiles, commitMeta, getBlobAtCommit, isAncestor } from './git-evidence.js';
 import { replayAt } from './predicate-replay.js';
+
+/** Test seam: a replacement `replayAt` (same signature) so a replay failure in a parent commit can be produced on demand. */
+export const _replayHooks = { replayAt: null };
 import { PROVENANCE_METHOD } from './schema.js';
 import { checkAbsentInSomeParent, detectRevert, detectCherryPick } from './dag-walk.js';
 import { loadRepoLineage } from './repo-lineage.js';
@@ -230,7 +233,7 @@ export async function resolveOrigin(scanRoot, finding, { since, deadlineAt, repo
   const replayCache = new Map();
   const replay = (sha) => {
     if (replayCache.has(sha)) return replayCache.get(sha);
-    const p = replayAt(scanRoot, sha, files, stableId, { deep: needsDeepReplay(finding) });
+    const p = (_replayHooks.replayAt || replayAt)(scanRoot, sha, files, stableId, { deep: needsDeepReplay(finding) });
     replayCache.set(sha, p);
     return p;
   };
@@ -286,13 +289,23 @@ export async function resolveOrigin(scanRoot, finding, { since, deadlineAt, repo
     }
 
     const presentInParent = await replay(parent);
-    const absentInParent = !presentInParent.present;
-    if (!absentInParent) continue; // predicate already true in parent — keep walking older candidates
+    if (presentInParent.present) continue; // predicate already true in parent — keep walking older candidates
+    // GA-05: `present: false` is proof of absence only when the parent WAS inspected and the predicate did not reproduce
+    // (`stableId-not-reproduced`), or the file did not exist there at all (`no-files-at-commit`: a file that is new in this
+    // commit). A parent the replay could not inspect (`replay-error`) proves nothing, so the boundary is not verified and the
+    // answer is `partial` with that reason, never `complete`.
+    if (presentInParent.reason === 'replay-error') {
+      return {
+        status: 'partial', reason: 'parent-not-inspectable', commitsConsidered,
+        findingOrigin: originFrom(meta, { absentInParents: [] }),
+        method: PROVENANCE_METHOD.SEMANTIC_REPLAY, parentBoundaryVerified: false,
+      };
+    }
 
     return {
       status: 'complete', method: PROVENANCE_METHOD.SEMANTIC_REPLAY, commitsConsidered,
       findingOrigin: originFrom(meta, { absentInParents: [parent] }),
-      parentBoundaryVerified: true,
+      parentBoundaryVerified: true, absenceEvidence: presentInParent.reason,
     };
   }
 

package/src/posture/rule-compiler/cli.js

@@ -8,9 +8,11 @@
 // model call — this is the deterministic half; a model may PROPOSE the candidate pattern this CLI is handed, but
 // it never decides promotion).
 import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
 import { statePath } from '../state-dir.js';
 import { packTrust, signPublishedRule } from './store.js';
-import { sharedFalsePositiveCorpus, falsePositiveHits, regressRules } from './regression.js';
+import { sharedFalsePositiveCorpus, falsePositiveHits, regressRules, promotedRuleIds } from './regression.js';
 import { draftRuleIR, validateRuleIR, ruleIRDigest } from './ir.js';
 import { checkEligibility } from './eligibility.js';
 import { buildCorpus } from './corpus.js';
@@ -35,6 +37,12 @@ function readJsonArg(pathOrInline) {
 
 export async function cmdRules(args, root) {
   const sub = args._[1];
+  // GA-07: a ledger that failed its integrity check (broken chain, bad or missing signature) refuses EVERY command, not only the
+  // ones that change state; nothing below can read a tampered history as fact or write over it.
+  if (['synthesize', 'evaluate', 'promote', 'status', 'rollback', 'cost', 'regress'].includes(sub)) {
+    const guard = loadLedger(root);
+    if (guard.tampered) { console.error(`Refusing: rule lifecycle ledger failed its integrity check (${guard.tamperReason}).`); return 4; }
+  }
   if (sub === 'synthesize') return cmdSynthesize(args, root);
   if (sub === 'evaluate') return cmdEvaluate(args, root);
   if (sub === 'promote') return cmdPromote(args, root);
@@ -42,7 +50,7 @@ export async function cmdRules(args, root) {
   if (sub === 'rollback') return cmdRollback(args, root);
   if (sub === 'cost') return cmdCost(args, root);
   if (sub === 'regress') return cmdRegress(args, root);
-  console.error('usage: rules synthesize <finding-id> --spec <file.json> [--auto] [--max-attempts N] | evaluate <rule-id> | promote <rule-id> | status [rule-id] | rollback <rule-id> | cost <rule-id>');
+  console.error('usage: rules synthesize <finding-id> --spec <file.json> [--auto] [--max-attempts N] | evaluate <rule-id> | promote <rule-id> --reviewed-by <person> [--scope <text>] | status [rule-id] | rollback <rule-id> | cost <rule-id> | regress [rule-id]');
   return 4;
 }
 
@@ -61,7 +69,7 @@ async function cmdSynthesize(args, root) {
   // The candidate pattern is the model's or the person's, when they gave one. Without one, or with --auto, the synthesis loop proposes
   // from the vulnerable and patched code, scores each attempt on the real corpus and its mutations, and revises (see proposal.js).
   let finalSpec = spec; let synthesis = null;
-  const corpusSpec = { originalCode: spec.originalCode, patchedCode: spec.patchedCode ?? null, nearbyCleanCode: spec.nearbyCleanCode ?? [], protectedVariantsCode: spec.protectedVariantsCode ?? [] };
+  const corpusSpec = { originalCode: spec.originalCode, patchedCode: spec.patchedCode ?? null, nearbyCleanCode: spec.nearbyCleanCode ?? [], protectedVariantsCode: spec.protectedVariantsCode ?? [], independentVulnerableCode: spec.independentVulnerableCode ?? [], independentCleanCode: spec.independentCleanCode ?? [] };
   const leak = checkLeakage(JSON.stringify(corpusSpec), { benchmarkNames: args.flags['benchmark-names'] ? String(args.flags['benchmark-names']).split(',') : [], fileNames: spec.fileNames ?? [] });
   if (!leak.ok) { console.error(`Refusing: the material for this rule shows benchmark or answer-key signals (${leak.offendingTerms.join('; ')}). Nothing was written.`); return 4; }
   if (args.flags.auto || (!spec.match && !spec.sink)) {
@@ -120,7 +128,7 @@ async function cmdEvaluate(args, root) {
     originatingFinding: ir.provenance.originatingFindingId, originatingCommit: ir.provenance.originatingCommit, evidenceState: ir.provenance.evidenceState,
     generatingModel: ir.provenance.model, promptConfigVersion: ir.provenance.promptConfigVersion,
     positiveCorpusHash: corpusHash(corpus.positives), negativeCorpusHash: corpusHash(corpus.negatives),
-    benchmarkResults: { precision: gate.evaluation.score.precision, recall: gate.evaluation.score.recall, tp: gate.evaluation.score.tp, fp: gate.evaluation.score.fp, fn: gate.evaluation.score.fn, tn: gate.evaluation.score.tn, protectedFailures: gate.evaluation.score.protectedFailures, thresholds: gate.evaluation.thresholds, gate: gate.pass ? 'passed' : 'failed', reasons: gate.reasons },
+    benchmarkResults: { precision: gate.evaluation.score.precision, recall: gate.evaluation.score.recall, tp: gate.evaluation.score.tp, fp: gate.evaluation.score.fp, fn: gate.evaluation.score.fn, tn: gate.evaluation.score.tn, protectedFailures: gate.evaluation.score.protectedFailures, independent: gate.independent, thresholds: gate.evaluation.thresholds, gate: gate.pass ? 'passed' : 'failed', reasons: gate.reasons },
     leakageCheck: leakage, mutatorCoverage: mutatorCoverage(corpusSpec.originalCode), discoveryCost: corpusSpec.discoveryCost ?? prev?.discoveryCost ?? null,
     promotionEvent: prev?.promotionEvent ?? null, evaluatedAt: new Date().toISOString(),
   });
@@ -136,23 +144,63 @@ async function cmdEvaluate(args, root) {
 function isStr(v) { return typeof v === 'string' && v.length > 0; }
 const fmtPct = (n) => (n == null ? 'unmeasured' : `${(n * 100).toFixed(1)}%`);
 
+/** Does this commit exist in the project's history? `true`, `false`, or `null` when the project is not a git repository. */
+function commitExists(root, sha) {
+  if (!fs.existsSync(path.join(root, '.git'))) return null;
+  try { execFileSync('git', ['cat-file', '-e', `${sha}^{commit}`], { cwd: root, stdio: 'ignore' }); return true; } catch { return false; }
+}
+
+const NOT_A_REVIEWER = /^(?:agent|model|auto|bot|llm|ai)$/i;
+
+// Promotion is a reviewed, human decision (GA-07). It needs the reviewer's name, a rule that is exactly the one that was evaluated, a
+// provenance that checks out, and no conflict with a rule that already exists; a model's recommendation on its own promotes nothing.
 async function cmdPromote(args, root) {
   const id = args._[2];
-  if (!id) { console.error('usage: rules promote <rule-id>'); return 4; }
+  if (!id) { console.error('usage: rules promote <rule-id> --reviewed-by <person> [--scope <text>] [--reason <text>]'); return 4; }
+  const reviewer = args.flags['reviewed-by'];
+  if (!isStr(reviewer) || NOT_A_REVIEWER.test(reviewer.trim())) {
+    console.error('usage: rules promote <rule-id> --reviewed-by <person>. A promotion records the person who reviewed the rule and its scope; a model or agent recommendation is not a review, so nothing is promoted without a named reviewer.');
+    return 4;
+  }
   const ledger = loadLedger(root);
   if (ledger.tampered) { console.error(`Refusing: rule lifecycle ledger failed its integrity check (${ledger.tamperReason}).`); return 4; }
   if (stateOf(ledger, id) !== 'VALIDATED') { console.error(`Rule ${id} is not VALIDATED (run rules evaluate first); refusing to promote.`); return 4; }
   const ir = loadIR(root, id);
   if (!ir) { console.error(`No rule IR found for ${id}.`); return 4; }
+  // the rule promoted must be the rule evaluated: an IR edited after `rules evaluate` has no evidence
+  const prov = loadProvenance(root, id);
+  if (!prov) { console.error(`Promotion refused: no evaluation record for ${id}; run rules evaluate first.`); return 4; }
+  if (prov.ruleHash !== ruleIRDigest(ir)) { console.error(`Promotion refused: the rule ${id} changed after it was evaluated (evaluated ${String(prov.ruleHash).slice(0, 12)}, now ${ruleIRDigest(ir).slice(0, 12)}); run rules evaluate again.`); return 4; }
+  // a named originating commit must be real history, not a typed-in string
+  const commit = ir.provenance?.originatingCommit;
+  if (commit) {
+    const exists = commitExists(root, commit);
+    if (exists === false) { console.error(`Promotion refused: originating commit ${commit} is not in this repository's history (invalid provenance).`); return 4; }
+    if (exists === null) { console.error(`Promotion refused: originating commit ${commit} cannot be verified because this project is not a git repository.`); return 4; }
+  }
+  // conflicts: a hand-written rule file with the same id, or a promoted rule with the identical match
+  const live = statePath(root, 'rules', `${id}.yml`);
+  let firstLine = null; // null: no file there (or unreadable, which is treated as absent below only when the read fails with ENOENT)
+  try { firstLine = fs.readFileSync(live, 'utf8').split('\n')[0]; } catch (e) { if (e.code !== 'ENOENT') firstLine = ''; }
+  if (firstLine !== null && !firstLine.startsWith('# Compiled by the rule compiler')) { console.error(`Promotion refused: a rule file that the compiler did not write already exists at ${live}; choose another rule id or remove that file deliberately.`); return 4; }
+  for (const other of promotedRuleIds(ledger)) {
+    if (other === id) continue;
+    const oir = loadIR(root, other);
+    if (oir && JSON.stringify(oir.match) === JSON.stringify(ir.match) && JSON.stringify(oir.languages) === JSON.stringify(ir.languages)) {
+      console.error(`Promotion refused: ${id} duplicates the promoted rule ${other} (identical match on the same languages); roll one back or narrow this one.`);
+      return 4;
+    }
+  }
   // other rules may have been promoted since this one was evaluated: hold it to the false-positive corpus as it is NOW
   const fpNow = falsePositiveHits(ir, sharedFalsePositiveCorpus(root, ledger, id));
   if (fpNow.length) { console.error(`Promotion refused: ${id} fires on ${fpNow.length} item(s) of the shared false-positive corpus (${fpNow.slice(0, 3).map((h) => h.label).join(', ')}). Re-evaluate or narrow the rule.`); return 1; }
   const pub = publishCustomRule(root, ir);
   if (!pub.ok) { console.error(`Promotion refused: ${pub.reason}`); return 4; }
-  const t = recordTransition(ledger, { ruleId: id, from: 'VALIDATED', to: 'PROMOTED', reason: args.flags.reason || 'promoted', actor: args.flags.actor || 'operator' });
+  const scope = isStr(args.flags.scope) ? args.flags.scope : null;
+  const review = { reviewer: reviewer.trim(), scope, independent: prov.benchmarkResults?.independent ?? null };
+  const t = recordTransition(ledger, { ruleId: id, from: 'VALIDATED', to: 'PROMOTED', reason: args.flags.reason || 'promoted', evidence: review, actor: args.flags.actor || reviewer.trim() });
   saveLedger(root, ledger);
-  const prov = loadProvenance(root, id);
-  if (prov) saveProvenance(root, id, { ...prov, promotionEvent: { at: new Date().toISOString(), actor: args.flags.actor || 'operator', reason: args.flags.reason || 'promoted', ruleHash: ruleIRDigest(ir) } });
+  saveProvenance(root, id, { ...prov, promotionEvent: { at: new Date().toISOString(), actor: args.flags.actor || reviewer.trim(), reviewer: reviewer.trim(), scope, reason: args.flags.reason || 'promoted', ruleHash: ruleIRDigest(ir) } });
   console.log(`Rule ${id}: VALIDATED -> PROMOTED. Published to ${pub.file}.`);
   // Publishing is not trusting. Rule packs are signature-checked so a rule dropped into a repository cannot run in someone's CI; sign this
   // one with the operator's key when there is one, and say plainly whether the scanner will load it.

package/src/posture/rule-compiler/corpus.js

@@ -20,11 +20,15 @@ function toRuntimeRule(ir) {
 
 const EXT = { javascript: 'x.js', typescript: 'x.ts', python: 'x.py', go: 'x.go', ruby: 'x.rb', java: 'x.java', rust: 'x.rs', csharp: 'x.cs', php: 'x.php', any: 'x.txt' };
 
-export function buildCorpus(ir, { originalCode, patchedCode = null, nearbyCleanCode = [], protectedVariantsCode = [] } = {}) {
+export function buildCorpus(ir, { originalCode, patchedCode = null, nearbyCleanCode = [], protectedVariantsCode = [], independentVulnerableCode = [], independentCleanCode = [] } = {}) {
   const positives = [{ label: 'original', code: originalCode }];
   for (const v of generateVariants(originalCode)) positives.push({ label: `sibling:${v.mutator}`, code: v.code });
+  // Independent examples (GA-07): vulnerable and safe code that is NOT the source finding and NOT a mutation of it, supplied by the
+  // reviewer from other places. They are never mutated, so they score as what they are: evidence from outside the rule's own material.
+  independentVulnerableCode.forEach((code, i) => positives.push({ label: `independent-vulnerable-${i}`, code }));
 
   const negatives = [];
+  independentCleanCode.forEach((code, i) => negatives.push({ label: `independent-clean-${i}`, code }));
   if (patchedCode) {
     negatives.push({ label: 'patched', code: patchedCode });
     for (const v of generateVariants(patchedCode)) negatives.push({ label: `patched-sibling:${v.mutator}`, code: v.code });
@@ -60,6 +64,10 @@ export function scoreRule(ir, corpus) {
   const recall = corpus.positives.length === 0 ? null : tp / corpus.positives.length;
   // "Protected negative failures" per PRD 3: a rule firing on a sanitizer/guard-carrying variant specifically.
   const protectedFailures = negResults.filter((n) => n.label.startsWith('protected-') && n.fired).length;
+  // Independent evidence, counted apart: how many examples from outside the finding's own material there were, and how they scored.
+  const indPos = posResults.filter((p) => p.label.startsWith('independent-vulnerable-'));
+  const indNeg = negResults.filter((n) => n.label.startsWith('independent-clean-'));
+  const independent = { positives: indPos.length, negatives: indNeg.length, detected: indPos.filter((p) => p.fired).length, falseAlarms: indNeg.filter((n) => n.fired).length };
 
-  return { precision, recall, tp, fp, tn, fn, protectedFailures, positives: posResults, negatives: negResults };
+  return { precision, recall, tp, fp, tn, fn, protectedFailures, independent, positives: posResults, negatives: negResults };
 }

package/src/posture/rule-compiler/ir.js

@@ -74,9 +74,18 @@ export function validateRuleIR(ir) {
   return errs;
 }
 
+/** JSON with every object's keys sorted at every depth, so the digest does not depend on insertion order. */
+function stableStringify(v) {
+  if (Array.isArray(v)) return `[${v.map(stableStringify).join(',')}]`;
+  if (v && typeof v === 'object') return `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(v[k])}`).join(',')}}`;
+  return JSON.stringify(v);
+}
+
 export function ruleIRDigest(ir) {
   const { state: _s, ...rest } = ir;
-  return sha256(JSON.stringify(rest, Object.keys(rest).sort()));
+  // Until 0.195.23 this passed the TOP-LEVEL key list as the JSON replacer, which also filters nested objects: `match.pattern` and
+  // every structural regex were serialized as `{}`, so the digest never covered the one thing a rule is. Sorted at every depth now.
+  return sha256(stableStringify(rest));
 }
 
 /** Build a DRAFT rule IR. Caller supplies the candidate pattern — this module never invents one. */

package/src/posture/rule-compiler/promotion.js

@@ -4,7 +4,11 @@
 // actually recorded, and nothing in this module writes to it.
 import { scoreRule } from './corpus.js';
 
-export const PROMOTION_DEFAULTS = Object.freeze({ minPrecision: 0.95, minRecall: 0.80, maxProtectedFailures: 0 });
+// Since 0.195.23 (GA-07) promotion also needs independent evidence: at least one vulnerable and one safe example that are not the
+// source finding or a mutation of it, and the rule must detect every independent vulnerable example and stay quiet on every
+// independent safe one. The synthesis loop still scores attempts without them (`evaluateRule`); only the promotion decision
+// (`gatePromotion`) requires them, so a candidate can be proposed before a reviewer has gathered the outside examples.
+export const PROMOTION_DEFAULTS = Object.freeze({ minPrecision: 0.95, minRecall: 0.80, maxProtectedFailures: 0, minIndependentVulnerable: 1, minIndependentClean: 1 });
 
 // Deliberately independent of posture/evaluation/custody.js: that module's term list and guard are reserved for
 // the evaluation custodian's sealed-label boundary (QA-002.AC03), and a test enforces that nothing outside
@@ -59,5 +63,11 @@ export function gatePromotion({ ir, corpus, leakageCheck, thresholds } = {}) {
   const evalResult = evaluateRule(ir, corpus, thresholds);
   const reasons = [...evalResult.reasons];
   if (!leakageCheck || leakageCheck.ok !== true) reasons.push(leakageCheck ? `leakage check failed: ${leakageCheck.offendingTerms.join(', ')}` : 'leakage check was not run');
-  return { pass: reasons.length === 0, reasons, evaluation: evalResult };
+  const t = evalResult.thresholds;
+  const ind = evalResult.score.independent ?? { positives: 0, negatives: 0, detected: 0, falseAlarms: 0 };
+  if (ind.positives < t.minIndependentVulnerable) reasons.push(`${ind.positives} independent vulnerable example(s) beyond the source finding and its mutations (min ${t.minIndependentVulnerable}): supply independentVulnerableCode`);
+  else if (ind.detected < ind.positives) reasons.push(`misses ${ind.positives - ind.detected} of ${ind.positives} independent vulnerable example(s)`);
+  if (ind.negatives < t.minIndependentClean) reasons.push(`${ind.negatives} independent safe example(s) (min ${t.minIndependentClean}): supply independentCleanCode`);
+  else if (ind.falseAlarms > 0) reasons.push(`fires on ${ind.falseAlarms} of ${ind.negatives} independent safe example(s)`);
+  return { pass: reasons.length === 0, reasons, evaluation: evalResult, independent: ind };
 }

package/src/posture/rule-compiler/regression.js

@@ -41,7 +41,7 @@ function operatorFalsePositives(root) {
   return out;
 }
 
-function promotedRuleIds(ledger) {
+export function promotedRuleIds(ledger) {
   return [...new Set(ledger.entries.map((e) => e.ruleId))].filter((id) => stateOf(ledger, id) === 'PROMOTED');
 }
 

package/src/posture/rule-compiler/store.js

@@ -7,6 +7,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { statePath, ensureStateDir, safeWriteState } from '../state-dir.js';
 import { newLedger, verifyLedger } from './lifecycle.js';
+import { signLastScan, verifyLastScan } from '../integrity.js';
 import { compileToCustomRule } from './ir.js';
 import { verifyRulePack, loadTrustedKeys, signRulePack } from '../rule-pack-signing.js';
 
@@ -15,20 +16,39 @@ const EXT = { javascript: 'js', typescript: 'ts', python: 'py', go: 'go', ruby:
 
 function ruleDir(scanRoot, id) { return statePath(scanRoot, DIR, id); }
 
-export function loadLedger(scanRoot) {
+/**
+ * The lifecycle ledger is hash-chained (lifecycle.js) AND signed with the per-install HMAC key (the same key as last-scan.json),
+ * since 0.195.23 (GA-07): the chain alone could be recomputed by anyone who could edit the file. A ledger that fails either check,
+ * or that cannot be parsed, is returned WITH `tampered: true` and its reason, and `saveLedger` refuses to write it, so a bad ledger
+ * is never quietly replaced by a fresh one and its history lost. An unsigned ledger with entries (written before 0.195.23) is
+ * accepted only with AGENTIC_SECURITY_RULES_UNSIGNED=1, the same switch that accepts an unsigned rules override, and is signed on
+ * its next save.
+ */
+export function loadLedger(scanRoot, env = process.env) {
   const f = statePath(scanRoot, DIR, 'ledger.json');
   if (!fs.existsSync(f)) return newLedger();
-  try {
-    const ledger = JSON.parse(fs.readFileSync(f, 'utf8'));
-    const v = verifyLedger(ledger);
-    return v.ok ? ledger : { ...newLedger(), tampered: true, tamperReason: v.reason };
-  } catch { return newLedger(); }
+  let text;
+  try { text = fs.readFileSync(f, 'utf8'); } catch (e) { return { ...newLedger(), tampered: true, tamperReason: `cannot read the ledger: ${e.message}` }; }
+  let ledger;
+  try { ledger = JSON.parse(text); } catch (e) { return { ...newLedger(), tampered: true, tamperReason: `the ledger is not valid JSON: ${e.message}` }; }
+  if (!ledger || !Array.isArray(ledger.entries)) return { ...newLedger(), tampered: true, tamperReason: 'the ledger has no entries array' };
+  const v = verifyLedger(ledger);
+  if (!v.ok) return { ...ledger, tampered: true, tamperReason: v.reason };
+  const sig = verifyLastScan(text, `${f}.sig`);
+  if (sig === false) return { ...ledger, tampered: true, tamperReason: 'the ledger signature does not verify under this install key' };
+  if (sig === null && ledger.entries.length && env.AGENTIC_SECURITY_RULES_UNSIGNED !== '1') {
+    return { ...ledger, tampered: true, tamperReason: 'the ledger is unsigned (written before 0.195.23 or by another tool); set AGENTIC_SECURITY_RULES_UNSIGNED=1 once to accept and re-sign it' };
+  }
+  return ledger;
 }
 
 export function saveLedger(scanRoot, ledger) {
+  if (ledger?.tampered) return { ok: false, reason: `refusing to overwrite a ledger that failed its integrity check (${ledger.tamperReason})` };
   if (!ensureStateDir(scanRoot)) return { ok: false, reason: 'no safe state directory for this project' };
   const f = statePath(scanRoot, DIR, 'ledger.json');
-  return { ok: safeWriteState(f, JSON.stringify(ledger, null, 2)) };
+  const text = JSON.stringify(ledger, null, 2);
+  const ok = safeWriteState(f, text) && safeWriteState(`${f}.sig`, signLastScan(text));
+  return { ok };
 }
 
 export function saveIR(scanRoot, ir) {

package/src/posture/strategic-metrics.js

@@ -63,7 +63,7 @@ export function evidenceConversion(findings) {
   const byState = Object.fromEntries(EVIDENCE_STATES.map((s) => [s, 0]));
   for (const f of list) byState[evidenceStateOf(f)]++;
   const converted = list.length - byState['single-signal'];
-  return { ...rate(converted, list.length), byState, basis: 'findings that reached corroborated or stronger, over all findings' };
+  return { status: list.length ? 'measured' : 'unmeasured', ...rate(converted, list.length), byState, basis: 'findings that reached corroborated or stronger, over all findings of the last scan' };
 }
 
 const strongest = (a) => {
@@ -72,21 +72,52 @@ const strongest = (a) => {
   return disappeared && a.testsRan === true && a.testsOk !== false && a.pocOk === true;
 };
 
+const isoOrNull = (v) => (typeof v === 'string' && !Number.isNaN(Date.parse(v)) ? v : null);
+
+/**
+ * One attempt per finding (GA-11): a fix tried five times is one remediation, not five, so the LATEST recorded attempt for each
+ * finding id is the one counted and the earlier ones are reported as `repeated`. An attempt with no finding id cannot be matched to
+ * another and counts on its own. Order is by `at` where every record has one, else by position in the log.
+ */
+function dedupeAttempts(attempts) {
+  const list = Array.isArray(attempts) ? attempts.filter((a) => a && typeof a === 'object') : [];
+  const latest = new Map();
+  const loose = [];
+  list.forEach((a, i) => {
+    const key = typeof a.stableId === 'string' && a.stableId ? a.stableId : (typeof a.findingId === 'string' && a.findingId ? a.findingId : null);
+    if (!key) { loose.push(a); return; }
+    const prev = latest.get(key);
+    const newer = !prev || (isoOrNull(a.at) && isoOrNull(prev.at) ? Date.parse(a.at) >= Date.parse(prev.at) : i > prev._i);
+    if (newer) latest.set(key, Object.assign(Object.create(null), a, { _i: i }));
+  });
+  const kept = [...latest.values()].map((a) => { const { _i, ...rest } = a; return rest; }).concat(loose);
+  return { attempts: kept, recorded: list.length, repeated: list.length - kept.length };
+}
+
+/** The time span the recorded attempts cover: `from` and `to` are the earliest and latest `at`, or `null` when none carries one. */
+function attemptsWindow(attempts) {
+  const times = (Array.isArray(attempts) ? attempts : []).map((a) => a && isoOrNull(a.at)).filter(Boolean).sort();
+  return { from: times[0] ?? null, to: times[times.length - 1] ?? null };
+}
+
 /** Of the fix attempts, how many reached the strongest verification tier. A lower bound: some classes have no independent proof to run. */
 export function verifiedRemediationRate(attempts) {
-  const list = Array.isArray(attempts) ? attempts.filter((a) => a && typeof a === 'object') : [];
+  const { attempts: list, recorded, repeated } = dedupeAttempts(attempts);
   const full = list.filter(strongest).length;
   const disappearedOnly = list.filter((a) => typeof a.verifiedFull !== 'boolean' && (a.rescanOk === true || (a.ok === true && a.rescanOk !== false)) && !(a.testsRan === true && a.testsOk !== false) && a.pocOk !== true).length;
+  const failed = list.filter((a) => a.ok === false || a.verifiedFull === false).length;
   return {
+    status: list.length ? 'measured' : 'unmeasured',
     ...rate(full, list.length),
-    disappearedOnly,
-    basis: 'attempts that passed the re-scan, the project tests and the independent attack replay, over all attempts. A lower bound where a class has no replay',
+    recorded, repeated, failed, disappearedOnly,
+    window: attemptsWindow(attempts),
+    basis: 'the latest attempt per finding that passed the re-scan, the project tests and the independent attack replay, over the latest attempt per finding. A lower bound where a class has no replay',
   };
 }
 
-/** Nothing measures it independently of the rule compiler's own corpus, so it is reported as not measured. */
+/** Nothing measures it independently of the rule compiler's own corpus, so it is reported as unmeasured, with the reason. */
 export function securityLearningRate() {
-  return { status: 'not-measured', reason: 'the rule compiler grades its rules against a corpus built from the same finding; no independent measurement of novel weaknesses converted into reusable knowledge exists' };
+  return { status: 'unmeasured', reason: 'the rule compiler grades its rules against a corpus built from the same finding and the reviewer-supplied independent examples; no independent longitudinal measurement of novel weaknesses converted into reusable knowledge exists' };
 }
 
 /**
@@ -95,11 +126,21 @@ export function securityLearningRate() {
  * @param {object[]} [o.fixAttempts] fix verification attempts
  */
 export function computeStrategicMetrics({ scan = null, fixAttempts = [] } = {}) {
+  const attempts = Array.isArray(fixAttempts) ? fixAttempts : [];
   return {
     schema: STRATEGIC_METRICS_SCHEMA, version: STRATEGIC_METRICS_VERSION,
+    // The scope and time basis (GA-11): these are per-scan figures for ONE scan plus the attempts recorded on this machine, never an
+    // organisation trend. The scan is named by its id and start time; the attempts by the span their timestamps cover.
+    scope: {
+      kind: 'per-scan',
+      scanId: scan && typeof scan.scanId === 'string' ? scan.scanId : null,
+      scanStartedAt: scan ? isoOrNull(scan.startedAt) : null,
+      attempts: { ...attemptsWindow(attempts), recorded: attempts.filter((a) => a && typeof a === 'object').length },
+      trend: 'not a trend: one scan and this machine\'s recorded attempts; compare scans by scanId to see movement',
+    },
     assuranceCoverage: assuranceCoverage(scan && scan.scanHealth),
     evidenceConversion: evidenceConversion(scan && scan.findings),
-    verifiedRemediationRate: verifiedRemediationRate(fixAttempts),
+    verifiedRemediationRate: verifiedRemediationRate(attempts),
     securityLearningRate: securityLearningRate(),
   };
 }
@@ -109,6 +150,7 @@ const pc = (r) => (r && r.percent !== null && r.percent !== undefined ? `${r.per
 export function renderStrategicMetrics(m) {
   const ac = m.assuranceCoverage; const ec = m.evidenceConversion; const vr = m.verifiedRemediationRate;
   const L = [];
+  if (m.scope) L.push(`Scope: one scan${m.scope.scanId ? ` (${m.scope.scanId}${m.scope.scanStartedAt ? `, started ${m.scope.scanStartedAt}` : ''})` : ''} and ${m.scope.attempts.recorded} fix attempt(s) recorded on this machine${m.scope.attempts.from ? ` between ${m.scope.attempts.from} and ${m.scope.attempts.to}` : ''}; not a trend`);
   L.push(`Assurance Coverage: ${ac.percent === null ? 'not measurable' : `${ac.percent}% (the lower of the two components)`}${ac.scanStatus ? `; scan ${ac.scanStatus}` : ''}`);
   if (ac.files) L.push(`  files: ${ac.files.numerator} of ${ac.files.denominator} completed (${pc(ac.files)}); ${ac.files.skipped} skipped, ${ac.files.unanalysed} not analysed, ${ac.files.timedOut} timed out`);
   if (ac.analyzers) L.push(`  analyzers: ${ac.analyzers.numerator} of ${ac.analyzers.denominator} completed (${pc(ac.analyzers)}); ${ac.analyzers.failed} failed, ${ac.analyzers.timedOut} timed out`);
@@ -117,6 +159,7 @@ export function renderStrategicMetrics(m) {
   L.push(`  ${EVIDENCE_STATES.map((s) => `${s} ${ec.byState[s]}`).join(', ')}`);
   L.push(`Verified Remediation Rate: ${vr.numerator} of ${vr.denominator} fix attempts reached the strongest verification tier (${pc(vr)})${vr.denominator ? '; a lower bound where a class has no attack replay' : ''}`);
   if (vr.disappearedOnly) L.push(`  ${vr.disappearedOnly} satisfied only the re-scan, which is also what deleting the code produces`);
+  if (vr.repeated) L.push(`  ${vr.recorded} attempt(s) recorded; ${vr.repeated} earlier attempt(s) on the same finding counted once, by the latest`);
   L.push(`Security Learning Rate: not measured. ${m.securityLearningRate.reason}`);
   return L.join('\n');
 }

package/src/report/index.js

@@ -5,6 +5,7 @@ import { alertFace, approveFace } from './mascot.js';
 import { SCANNER_VERSION } from '../posture/version.js';
 import { proofBlock } from '../posture/proof-artifact.js';
 import { portfolioAssuranceEnabled, scanVerdictWording, NOT_A_GUARANTEE } from '../posture/portfolio/wording.js';
+import { assuranceDecision } from '../posture/assurance/decision.js';
 import { applyLegacyCompat, legacyFieldDeprecationNotice } from '../pipeline/legacy-compat.js';
 // Finding Provenance (M0/M1). NOTE the name: `findingProvenance` is the
 // git-origin record from posture/provenance/. It is NOT `finding.provenance`
@@ -1661,11 +1662,13 @@ export function toShipVerdict(scan, options = {}) {
   // findings on a scan that didn't finish cleanly is "we don't know," not
   // "safe."
   const scanIncomplete = scan.scanHealth && scan.scanHealth.status && scan.scanHealth.status !== 'complete';
+  // One decision for every surface (posture/assurance/decision.js, 0.195.22): a result with NO scan health is `unknown`, never clean.
+  const decision = assuranceDecision({ actionable: actionable.length, scanHealth: scan.scanHealth || null });
 
   const lines = [];
   const bar = '─────────────────────────────────────────';
   // Patch the mascot reacts to the result — APPROVE if clean, ALERT if findings.
-  const clean = actionable.length === 0 && !scanIncomplete;
+  const clean = decision.decision === 'deployable';
   lines.push(clean ? approveFace({ color }) : alertFace({ color }));
   lines.push(bar);
   // X-703.AC03: with the `portfolio-assurance` feature on, the headline is the bounded claim followed by scope and gaps. Off
@@ -1675,14 +1678,12 @@ export function toShipVerdict(scan, options = {}) {
     const w = scanVerdictWording({ clean, scanIncomplete: !!scanIncomplete, actionableCount: actionable.length });
     lines.push(c(`  ${w.icon}  ${w.headline}`, w.tier === 'ok' ? SEV_COLOR.low + BOLD : w.tier === 'incomplete' ? SEV_COLOR.high + BOLD : SEV_COLOR.critical + BOLD));
     lines.push(c(`  Scope: completed supported checks only${scanIncomplete ? '; gaps listed below' : '; no gaps recorded by scan health'}. ${NOT_A_GUARANTEE}`, DIM));
-  } else if (clean) {
-    lines.push(c('  ✅  Safe to deploy', SEV_COLOR.low + BOLD));
-  } else if (actionable.length === 0) {
-    lines.push(c('  ⚠️  Scan incomplete — cannot confirm safe to deploy', SEV_COLOR.high + BOLD));
   } else {
-    lines.push(c('  ❌  Not safe to deploy', SEV_COLOR.critical + BOLD));
+    const tone = decision.decision === 'deployable' ? SEV_COLOR.low : decision.decision === 'not_deployable' ? SEV_COLOR.critical : SEV_COLOR.high;
+    lines.push(c(`  ${decision.icon}  ${decision.headline}`, tone + BOLD));
   }
   lines.push(bar);
+  if (decision.decision === 'unknown') lines.push(c(`  ${decision.reason}`, SEV_COLOR.high));
   if (scanIncomplete) {
     const conditions = Array.isArray(scan.scanHealth.conditions) ? scan.scanHealth.conditions : [];
     lines.push(c(`  ${scan.scanHealth.status}: ${conditions[0] || 'analysis did not complete cleanly'}${conditions.length > 1 ? ` (+${conditions.length - 1} more)` : ''}`, SEV_COLOR.high));

package/src/sca/llm-function-extract.js

@@ -10,6 +10,8 @@ import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { evaluateEgress } from '../egress/policy.js';
+import { modelFetch } from '../egress/transport.js';
+import { resolveProvider, buildProviderRequest } from '../llm-validator/providers.js';
 
 const CACHE_DIR = process.env.XDG_CONFIG_HOME
   ? path.join(process.env.XDG_CONFIG_HOME, 'agentic-security', 'llm-sca-cache')
@@ -37,24 +39,26 @@ export function isLlmScaEnabled() {
   return process.env.AGENTIC_SECURITY_LLM_SCA === '1';
 }
 
-function _endpointConfig() {
-  const endpoint = process.env.AGENTIC_SECURITY_LLM_ENDPOINT;
-  const apiKey = process.env.AGENTIC_SECURITY_LLM_API_KEY;
-  const model = process.env.AGENTIC_SECURITY_LLM_MODEL || 'unknown';
-  return endpoint ? { endpoint, apiKey, model } : null;
+// The provider is resolved the same way the validator resolves it (GA-06.3): the `local` preset refuses a non-loopback endpoint here
+// too, instead of this module reading the raw endpoint variable and calling it regardless. The Ollama provider speaks a different
+// protocol and this extractor does not implement it, so it is treated as not configured.
+function _endpointConfig(env = process.env) {
+  const r = resolveProvider({ role: 'validate', env });
+  if (!r.ok || r.config.provider === 'ollama') return null;
+  return { endpoint: r.config.endpoint, apiKey: r.config.apiKey, model: r.config.model || 'unknown', shape: r.config.shape };
 }
 
 async function _askLlm(prompt, config) {
-  const headers = { 'Content-Type': 'application/json' };
-  if (config.apiKey) headers['Authorization'] = `Bearer ${config.apiKey}`;
-  const resp = await fetch(config.endpoint, {
+  const req = buildProviderRequest(config, prompt, 256);
+  const resp = await modelFetch(config.endpoint, {
     method: 'POST',
-    headers,
-    body: JSON.stringify({ prompt, model: config.model }),
-    signal: AbortSignal.timeout(15000),
-  });
+    headers: req.headers,
+    body: JSON.stringify(req.body),
+  }, { timeoutMs: 15000 });
   if (!resp.ok) return null;
-  const text = await resp.text();
+  let text = await resp.text();
+  // a vendor shape wraps the model's text in its own envelope; the generic shape's reply is searched as it came
+  try { const t = req.extractText(JSON.parse(text)); if (typeof t === 'string' && t) text = t; } catch { /* not an envelope */ }
   const jsonMatch = text.match(/\{[^{}]*"functions"\s*:\s*\[[^\]]*\][^{}]*\}/);
   if (!jsonMatch) return null;
   try { return JSON.parse(jsonMatch[0]); } catch { return null; }