@clear-capabilities/agentic-security-scanner 0.142.0 → 0.144.0

package/src/pipeline/finding-schema.js

@@ -0,0 +1,101 @@
+// Finding schema (assurance-hardening PRD, Milestone 0, FR-105).
+//
+// The PRD's §10.1 envelope (schemaVersion/stableId/producerId/... in ten
+// named groups) describes an IDEAL shape. This engine's actual canonical
+// shape already exists — it is report/index.js's `normalizeFindings()`,
+// which every JSON/SARIF/HTML/CSV/JUnit/OSCAL output format calls (verified
+// by grepping every call site in report/index.js, oscal.js, and
+// bin/agentic-security.js before writing this module — see
+// docs/implementation/assurance-hardening-decisions.md D-0003's rule: read
+// the existing mechanism before building a parallel one). `normalizeFindings`
+// already enforces an explicit allowlist with an honest `null` default for
+// every optional field, which is most of what FR-105 asks for; it was simply
+// never versioned or independently callable as "does this finding satisfy
+// the contract".
+//
+// This module does two things, both additive (Milestone 0 scope — no gate
+// wiring, no new required fields, nothing gets rejected):
+//   1. Names FINDING_SCHEMA_VERSION so future breaking changes to the
+//      normalizeFindings shape have something to bump (FR-105 acceptance:
+//      "select a supported output contract during migration" per §12.1's
+//      `--schema-version` flag, not yet wired to a CLI flag in this cycle).
+//   2. Provides describeFindingCompleteness(), a pure, non-throwing function
+//      that reports which of the CURRENT canonical fields a given finding
+//      actually has non-null values for — observability, not enforcement.
+//      Full enforcement (every producer's output must pass validation before
+//      it can reach a reporter) is Milestone 1's FR-103/FR-104, which
+//      requires producer isolation (FR-201) to exist first so a rejected
+//      finding can be attributed to the producer that emitted it.
+//
+// One MCP correctness bug was found and fixed alongside this (not scope
+// creep — it's the exact FR-105 acceptance criterion "...and MCP outputs
+// derive from the same validated object"): mcp/tools.js's scan_diff hand-
+// rolled a 3-of-4-channel finding merge instead of calling
+// normalizeFindings(), which both risked field-mapping drift and silently
+// excluded the supplyChain channel. Fixed in mcp/tools.js; see that file's
+// comment for the residual limitation (scan_diff still never populates
+// depFileContents, so supply-chain detection does not reach it today for an
+// unrelated, deeper reason this schema module does not address).
+
+export const FINDING_SCHEMA_VERSION = 1;
+
+// Field groups mirror the PRD's §10.1 structure, using the CURRENT field
+// names normalizeFindings() actually produces (see decision D-0003: extend
+// what exists, don't invent a parallel vocabulary no real finding uses).
+// `required` fields are ones every finding channel (sast/secret/logic/sca)
+// sets to a real (non-null) value today; `optional` fields are legitimately
+// null on many findings (e.g. a finding no annotator has enriched yet).
+export const FINDING_FIELD_GROUPS = {
+  identity: { required: ['id', 'kind', 'vuln'], optional: ['stableId'] },
+  location: { required: ['file', 'line'], optional: ['snippet'] },
+  classification: { required: ['severity'], optional: ['cwe', 'owaspLlm', 'family', 'parser', 'tags', 'description'] },
+  confidence: { required: [], optional: ['confidence', 'confidenceTier', 'calibrated_confidence', 'calibration_reason'] },
+  evidence: { required: [], optional: ['proof', 'falsification', 'verification', 'chain', 'sources', 'corroboration'] },
+  privacy: { required: [], optional: ['dataClasses'] },
+  compliance: { required: [], optional: [] }, // no per-finding controlRefs today — compliance mapping is scan-level (FR-501/E5)
+  remediation: { required: [], optional: ['fix', 'remediation'] },
+  risk: { required: [], optional: ['exploitability', 'exploitabilityTier', 'compositeRisk', 'compositeRiskTier', 'crownJewelScore', 'riskDollars'] },
+  lifecycle: { required: [], optional: ['triage', 'quarantined', 'unreachable'] },
+};
+
+/**
+ * Reports, for one normalized finding (i.e. an item from
+ * report/index.js#normalizeFindings' output — this function does NOT accept
+ * a raw pre-normalization finding), which canonical groups have their
+ * required fields present and which optional fields are populated.
+ *
+ * Pure, non-throwing, additive-only: does not mutate the finding, does not
+ * gate anything, and is not called from engine.js's default pipeline. It
+ * exists to be run over a real scan's output for observability (a future
+ * `--explain-health`-style report, per PRD §12.1) — see this module's
+ * header comment for what is deliberately NOT yet true of it.
+ *
+ * @param {object} finding - one entry from normalizeFindings(scan)
+ * @returns {{schemaVersion:number, missingRequiredFields:string[], populatedOptionalFields:string[], missingOptionalFields:string[], isComplete:boolean}}
+ */
+export function describeFindingCompleteness(finding) {
+  const f = finding && typeof finding === 'object' ? finding : {};
+  const missingRequiredFields = [];
+  const populatedOptionalFields = [];
+  const missingOptionalFields = [];
+
+  const isPopulated = (v) => v !== null && v !== undefined && !(Array.isArray(v) && v.length === 0);
+
+  for (const group of Object.values(FINDING_FIELD_GROUPS)) {
+    for (const field of group.required) {
+      if (!isPopulated(f[field])) missingRequiredFields.push(field);
+    }
+    for (const field of group.optional) {
+      if (isPopulated(f[field])) populatedOptionalFields.push(field);
+      else missingOptionalFields.push(field);
+    }
+  }
+
+  return {
+    schemaVersion: FINDING_SCHEMA_VERSION,
+    missingRequiredFields,
+    populatedOptionalFields,
+    missingOptionalFields,
+    isComplete: missingRequiredFields.length === 0,
+  };
+}

package/src/pipeline/legacy-compat.js

@@ -0,0 +1,101 @@
+// Legacy field compatibility adapter (assurance-hardening PRD, Milestone 1,
+// FR-108: "Publish a compatibility adapter for legacy finding consumers.
+// Existing integrations receive a deprecation warning and equivalent legacy
+// fields for one documented transition period.")
+//
+// This codebase's own stated convention (repeated three times across
+// CHANGELOG.md: "No breaking changes. All new capabilities are additive")
+// means a finding field should almost never be renamed or removed out from
+// under an existing consumer. But it can happen for a good reason — this
+// same session's FR-804 renamed `riskDollars.confidenceFloor` to
+// `confidenceWeight` because the old name was actively misleading (the
+// field stopped being a floor once the bug it named was fixed) — and when
+// it does, a consumer reading the old field name should not silently start
+// getting `undefined`. That rename is the concrete, real case this adapter
+// exists for, not a hypothetical one.
+//
+// LEGACY_FIELD_ALIASES names every known rename. applyLegacyCompat(finding)
+// backfills the OLD dotted path from the NEW one's current value whenever
+// the new value is present and nothing already occupies the old path — an
+// existing integration reading the deprecated name keeps working, unchanged,
+// for the documented transition period. legacyFieldDeprecationNotice()
+// turns that into the single, honest, report-level notice FR-108 asks for,
+// rather than silently reintroducing the old shape forever with no signal
+// that it is scheduled for removal.
+
+export const LEGACY_FIELD_ALIASES = Object.freeze([
+  Object.freeze({
+    oldPath: 'riskDollars.confidenceFloor',
+    newPath: 'riskDollars.confidenceWeight',
+    deprecatedInVersion: '0.143.0', // FR-804, same session as this adapter
+    sunsetAfter: '2027-02-24', // ~6 months from this adapter's introduction
+    reason: "renamed because the field stopped being a floor — Math.max(0.4, f.confidence || 0.8)'s unconditional floor and 0-as-falsy inflation were removed as part of FR-804's fix",
+  }),
+]);
+
+function _getPath(obj, dottedPath) {
+  return dottedPath.split('.').reduce((o, k) => (o && typeof o === 'object' ? o[k] : undefined), obj);
+}
+
+function _setPath(obj, dottedPath, value) {
+  const parts = dottedPath.split('.');
+  let o = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    // Only backfill onto a parent object that already exists — if
+    // riskDollars itself is null/absent, there is nothing to attach a
+    // legacy alias to, and creating a fake `{confidenceFloor: ...}` shell
+    // would be actively misleading (it would look like a real annotation
+    // that never ran).
+    if (o[parts[i]] == null || typeof o[parts[i]] !== 'object') return false;
+    o = o[parts[i]];
+  }
+  o[parts[parts.length - 1]] = value;
+  return true;
+}
+
+/**
+ * Backfill deprecated field names on ONE finding from their current
+ * replacements. Mutates the finding in place (matches every other
+ * annotator's convention in this codebase). Additive only — never
+ * overwrites a value already present at the old path, so a caller that set
+ * the legacy field explicitly (e.g. a hand-built test fixture) is never
+ * clobbered.
+ *
+ * @returns {string[]} which legacy field paths were actually backfilled —
+ *   empty for the common, eventual steady state where nothing legacy fired.
+ */
+export function applyLegacyCompat(finding) {
+  if (!finding || typeof finding !== 'object') return [];
+  const applied = [];
+  for (const alias of LEGACY_FIELD_ALIASES) {
+    const newValue = _getPath(finding, alias.newPath);
+    if (newValue === undefined) continue; // nothing to backfill from
+    if (_getPath(finding, alias.oldPath) !== undefined) continue; // already set — don't clobber
+    if (_setPath(finding, alias.oldPath, newValue)) applied.push(alias.oldPath);
+  }
+  if (applied.length) finding._legacyFields = applied;
+  return applied;
+}
+
+/**
+ * A single, report-level deprecation notice summarizing every legacy alias
+ * actually used across a finding set. Returns null when none fired.
+ */
+export function legacyFieldDeprecationNotice(findings) {
+  if (!Array.isArray(findings)) return null;
+  const used = new Set();
+  for (const f of findings) {
+    if (Array.isArray(f?._legacyFields)) for (const p of f._legacyFields) used.add(p);
+  }
+  if (used.size === 0) return null;
+  const fields = [...used].sort().map(oldPath => {
+    const alias = LEGACY_FIELD_ALIASES.find(a => a.oldPath === oldPath);
+    return alias
+      ? { oldPath, newPath: alias.newPath, deprecatedInVersion: alias.deprecatedInVersion, sunsetAfter: alias.sunsetAfter, reason: alias.reason }
+      : { oldPath, newPath: null, deprecatedInVersion: null, sunsetAfter: null, reason: null };
+  });
+  return {
+    message: 'This report includes deprecated legacy field name(s), backfilled from their current replacements for backward compatibility. Update integrations to read the new field name(s) before the documented sunset date.',
+    fields,
+  };
+}

package/src/pipeline/producer-collector.js

@@ -0,0 +1,48 @@
+// Producer collector (assurance-hardening PRD, Milestone 1, FR-102).
+//
+// The one place a "late producer" (see producer-registry.js's header for
+// exactly which ones — the cross-language/business-logic/privacy group
+// A-03 evidenced) is allowed to append to the shared finding array. Before
+// this, each of these ~12 call sites in engine.js did its own
+// `try { ...; if (x?.length) finalFindings.push(...x); } catch(_) {}` —
+// functionally fine for not crashing the scan, but each one silently
+// swallowed a producer exception with no diagnostic (a producer could be
+// broken for months and nothing would ever say so) and there was no single
+// place enforcing "only a REGISTERED producer may append here."
+//
+// This does not change engine.js's ~90 core SAST/SCA/secrets detector call
+// sites (see producer-registry.js's header for why that is out of scope).
+
+import { isRegisteredProducer } from './producer-registry.js';
+
+/**
+ * @param {object[]} finalFindings - mutated in place (push only)
+ * @param {Array<{phase:string, err:string}>} diagnostics - mutated in place (push only), same
+ *   shape as engine.js's _annotatorErrors so both surfaces read as one list
+ * @param {string} producerId - MUST be registered via producer-registry.js's registerProducer()
+ * @param {() => (Array|{findings:Array}|null|undefined)} thunk - runs the actual producer;
+ *   may return a bare findings array (matches every one of these producers' current shape) or
+ *   an object with a .findings array (forward-compatible with a future AnalyzerResult shape)
+ * @returns {{status:'completed'|'failed'|'unregistered', count:number}}
+ */
+export function collectProducerResult(finalFindings, diagnostics, producerId, thunk) {
+  if (!isRegisteredProducer(producerId)) {
+    const msg = `producer "${producerId}" is not registered — refusing to collect its output`;
+    diagnostics.push({ phase: `producer:${producerId}`, err: msg });
+    return { status: 'unregistered', count: 0 };
+  }
+  let result;
+  try {
+    result = thunk();
+  } catch (e) {
+    diagnostics.push({ phase: `producer:${producerId}`, err: String((e && e.message) || e) });
+    return { status: 'failed', count: 0 };
+  }
+  const findings = Array.isArray(result) ? result : (Array.isArray(result?.findings) ? result.findings : null);
+  if (!findings || !findings.length) return { status: 'completed', count: 0 };
+  for (const f of findings) {
+    if (f && typeof f === 'object' && f.producerId === undefined) f.producerId = producerId;
+  }
+  finalFindings.push(...findings);
+  return { status: 'completed', count: findings.length };
+}

package/src/pipeline/producer-registry.js

@@ -0,0 +1,112 @@
+// Producer registry (assurance-hardening PRD, Milestone 1, FR-101).
+//
+// engine.js's core ~90 SAST/SCA/secrets detectors are called synchronously
+// inside one large per-file loop and are NOT converted to registry entries
+// by this change — that is a much larger, separate undertaking (every one
+// of those call sites would need to change shape) and is explicitly out of
+// scope here. What this registry DOES cover: the "late producers" that
+// append findings AFTER the main per-file loop and AFTER the primary
+// enrichment chain has already run once — cross-language taint (5
+// boundary types), IaC-reachability, IAM-policy, container-runtime,
+// business-logic-v2, specification-drift, concurrency, and privacy-taint.
+// These are exactly the producers the PRD's A-03 evidence cites (findings
+// that bypass stableId/confidence/calibration because they arrive after
+// engine.js's enrichment chain already finished). See
+// pipeline/producer-collector.js for how registration is enforced at the
+// point findings are actually collected, and pipeline/enrichment-completion.js
+// for how any finding that still lacks the standard fields (regardless of
+// producer) gets them before the collection is frozen.
+
+const KNOWN_PHASES = Object.freeze(['sast', 'sca', 'secrets', 'cross-language', 'business-logic', 'privacy']);
+
+const _registry = new Map();
+
+/**
+ * @param {object} def
+ * @param {string} def.id - unique producer id
+ * @param {string} def.version - producer version string (semver-ish, not enforced)
+ * @param {string} def.phase - one of KNOWN_PHASES
+ * @param {string[]} [def.languages] - languages this producer applies to, or [] for language-agnostic
+ * @param {string[]} [def.dependsOn] - ids of producers that must be registered (and are logically upstream)
+ * @throws on duplicate id, unknown phase, or a dependency cycle
+ */
+export function registerProducer(def) {
+  if (!def || typeof def !== 'object') throw new Error('registerProducer: definition required');
+  const { id, version, phase, languages = [], dependsOn = [] } = def;
+  if (typeof id !== 'string' || !id) throw new Error('registerProducer: id required');
+  if (_registry.has(id)) throw new Error(`registerProducer: duplicate producer id "${id}"`);
+  if (typeof version !== 'string' || !version) throw new Error(`registerProducer: "${id}" missing version`);
+  if (!KNOWN_PHASES.includes(phase)) {
+    throw new Error(`registerProducer: "${id}" has unknown phase "${phase}" — must be one of ${KNOWN_PHASES.join(', ')}`);
+  }
+  if (!Array.isArray(dependsOn)) throw new Error(`registerProducer: "${id}" dependsOn must be an array`);
+
+  _registry.set(id, { id, version, phase, languages: [...languages], dependsOn: [...dependsOn] });
+  const cycle = _findCycle();
+  if (cycle) {
+    _registry.delete(id); // don't leave the registry in a broken state
+    throw new Error(`registerProducer: dependency cycle detected: ${cycle.join(' -> ')}`);
+  }
+}
+
+/** Topological cycle check over the current registry. Returns the cycle path, or null. */
+function _findCycle() {
+  const WHITE = 0, GRAY = 1, BLACK = 2;
+  const color = new Map([..._registry.keys()].map(id => [id, WHITE]));
+  const path = [];
+  function visit(id) {
+    color.set(id, GRAY);
+    path.push(id);
+    const def = _registry.get(id);
+    for (const dep of def?.dependsOn || []) {
+      if (!_registry.has(dep)) continue; // an unregistered dependency is reported separately, not a cycle
+      const c = color.get(dep);
+      if (c === GRAY) return [...path.slice(path.indexOf(dep)), dep];
+      if (c === WHITE) {
+        const found = visit(dep);
+        if (found) return found;
+      }
+    }
+    path.pop();
+    color.set(id, BLACK);
+    return null;
+  }
+  for (const id of _registry.keys()) {
+    if (color.get(id) === WHITE) {
+      const found = visit(id);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+export function isRegisteredProducer(id) {
+  return _registry.has(id);
+}
+
+export function getProducer(id) {
+  return _registry.get(id) || null;
+}
+
+export function listProducers() {
+  return [..._registry.values()];
+}
+
+/** Every dependsOn id must itself be a registered producer. For tests/CI, not called at runtime. */
+export function validateNoUnregisteredDependencies() {
+  const missing = [];
+  for (const def of _registry.values()) {
+    for (const dep of def.dependsOn) {
+      if (!_registry.has(dep)) missing.push(`${def.id} depends on unregistered producer "${dep}"`);
+    }
+  }
+  return missing;
+}
+
+// Test-only: reset the module-level registry between test files/cases.
+// Never called from production code paths.
+export function _resetForTests() {
+  _registry.clear();
+}
+
+export const KNOWN_PHASES_FOR_TESTS = KNOWN_PHASES;

package/src/pipeline/scan-health.js

@@ -0,0 +1,144 @@
+// Scan health (assurance-hardening PRD, Milestone 0, FR-206).
+//
+// PRD principle: "Separate 'no findings' from 'analysis complete'." Before
+// this module, a scan that hit an annotator exception, timed out on files, or
+// silently downgraded deep-analysis mode reported the same shape as a clean
+// complete scan — the only signals (`annotatorErrors`, `_scanMeta.filesTimedOut`)
+// existed on the result object already, but nothing summarized them into a
+// single status a caller could gate on or a human could read as a headline.
+//
+// This is additive-only (Milestone 0 scope): computeScanHealth() is a pure
+// function over signals the engine already collects, and its output is a new
+// field on the scan result. No existing gate, exit code, or CLI behavior
+// changes when this field is added.
+//
+// `analyzers` (PRD section 10.3) went from a hardcoded `null` to a real,
+// computed summary once FR-201 (every detector call site isolated,
+// {file,analyzer,err} captured), FR-202 (real preemptive deadlines, a
+// _timeout:true marker per killed file), and FR-203 (pipeline/
+// coverage-ledger.js, the actual per-file x per-analyzer status
+// computation) all existed for it to be computed FROM — reporting it
+// before then would have looked more precise than the underlying analysis
+// supported, which is exactly the failure mode this module exists to
+// prevent (see this file's own header history in git blame for that
+// reasoning, kept as a decision record even though the gap it names is
+// now closed).
+
+export const SCAN_HEALTH_SCHEMA_VERSION = 1;
+
+/**
+ * @param {object} input
+ * @param {object|null} input.scanMeta - engine's `_scanMeta` (filesScanned, filesSkipped,
+ *   filesDenseSkipped, filesTimedOut, checkpoint, ...).
+ * @param {Array<{phase:string, err:string}>} input.annotatorErrors
+ * @param {object} [input.engineErrors] - e.g. { cppDataflowParseErrors }
+ * @param {object} [input.deepStatus] - { requested, enabled, inCi, ciOverrideAllowed, reason, failure }
+ * @param {object} [input.analyzerCoverage] - coverage-ledger.js's
+ *   summarizeCoverageForScanHealth() output: {expected, completed, failed,
+ *   timedOut, skippedByPolicy}. Omitted (not just empty) is treated the
+ *   same as the old `null` — a caller that hasn't wired FR-203's ledger in
+ *   yet (e.g. a hand-built scan object in a test) gets `analyzers: null`,
+ *   never a fabricated all-zero summary.
+ * @returns {object} scanHealth per PRD §10.3, additive fields only.
+ */
+export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engineErrors = null, deepStatus = null, analyzerCoverage = null } = {}) {
+  const conditions = [];
+  const safeAnnotatorErrors = Array.isArray(annotatorErrors) ? annotatorErrors : [];
+  const filesTimedOut = Number(scanMeta?.filesTimedOut) || 0;
+
+  if (safeAnnotatorErrors.length > 0) {
+    conditions.push(`${safeAnnotatorErrors.length} annotator(s) threw and were skipped: ${
+      [...new Set(safeAnnotatorErrors.map(e => e.phase))].join(', ')
+    }`);
+  }
+  if (filesTimedOut > 0) {
+    conditions.push(`${filesTimedOut} file(s) exceeded the per-file analysis timeout`);
+  }
+  if (engineErrors?.cppDataflowParseErrors > 0) {
+    conditions.push(`${engineErrors.cppDataflowParseErrors} C/C++ dataflow parse error(s)`);
+  }
+  if (deepStatus?.failure) {
+    conditions.push(`deep analysis (IR-taint) threw and fell back to pattern-only results: ${deepStatus.failure}`);
+  }
+  if (deepStatus?.requested && !deepStatus.enabled) {
+    conditions.push(`deep analysis was requested but did not run: ${deepStatus.reason || 'unknown reason'}`);
+  }
+  // FR-203: a detector that threw on at least one file (captured via
+  // FR-201's runDetector isolation) is a real analysis gap distinct from
+  // an ANNOTATOR error above — annotators run post-detection over the
+  // whole finding set; detectors run per-file and produce the findings
+  // themselves, so a failed detector can mean a real vulnerability was
+  // never even looked for. This condition did not exist before FR-203's
+  // ledger made "which analyzer, how many files" computable.
+  if (analyzerCoverage && analyzerCoverage.failed > 0) {
+    conditions.push(`${analyzerCoverage.failed} analyzer(s) threw on at least one file`);
+  }
+
+  const status = conditions.length > 0 ? 'partial' : 'complete';
+
+  return {
+    schemaVersion: SCAN_HEALTH_SCHEMA_VERSION,
+    status,
+    files: {
+      expected: scanMeta?.checkpoint?.total ?? null,
+      scanned: scanMeta?.filesScanned ?? null,
+      skipped: (Number(scanMeta?.filesSkipped) || 0) + (Number(scanMeta?.filesDenseSkipped) || 0),
+      timedOut: filesTimedOut,
+    },
+    analyzers: analyzerCoverage || null,
+    deepAnalysis: deepStatus
+      ? {
+          requested: !!deepStatus.requested,
+          enabled: !!deepStatus.enabled,
+          inCi: !!deepStatus.inCi,
+          ciOverrideAllowed: !!deepStatus.ciOverrideAllowed,
+          reason: deepStatus.reason ?? null,
+          failure: deepStatus.failure ?? null,
+        }
+      : null,
+    annotatorErrorCount: safeAnnotatorErrors.length,
+    freshness: null,
+    conditions,
+  };
+}
+
+// FR-207 ("Add freshness checks for vulnerability feeds, calibration data,
+// rulesets, and policies — stale dependencies are visible and can fail
+// strict policy"). Deliberately NOT folded into computeScanHealth() itself:
+// the five freshness signals (KEV, EPSS, calibration, custom rules,
+// compliance evidence) are computed in two different places at two
+// different times relative to computeScanHealth's own call site —
+// engine.js has kev/epss/calibration/compliance available before it builds
+// scanHealth, but the custom-rules pattern-DSL only runs in
+// bin/agentic-security.js, AFTER scanHealth already exists on the scan
+// object. A single merge/condition/status function usable from both call
+// sites (once up front, once as a later patch) is simpler and less
+// duplicative than threading a partial value through computeScanHealth
+// twice. Each leg is additive: a leg not present in `freshnessPartial`
+// leaves scanHealth's existing `freshness` object and conditions
+// untouched, exactly like every other optional input this module accepts.
+const FRESHNESS_CONDITION_BUILDERS = {
+  kev: (f) => (f?.stale === true) ? `KEV catalog is stale (${f.ageDays} day(s) old) — recently-added CVEs may not be reflected` : null,
+  epss: (f) => (f?.stale === true) ? `EPSS exploit-probability data is stale (${f.ageDays} day(s) old)` : null,
+  calibration: (f) => (f?.stale === true) ? `calibration data is stale (${f.ageDays} day(s) old${f.generatedAt ? `, last generated ${f.generatedAt}` : ''})` : null,
+  customRules: (f) => (f?.stale === true) ? `${f.staleFiles.length} custom rule file(s) exceed their configured review interval` : null,
+  compliance: (f) => (Number(f?.stale) > 0) ? `${f.stale} compliance control(s) have stale evidence` : null,
+};
+
+export function applyFreshness(scanHealth, freshnessPartial) {
+  if (!scanHealth || !freshnessPartial) return scanHealth;
+  const freshness = { ...(scanHealth.freshness || {}), ...freshnessPartial };
+  const newConditions = [];
+  for (const [key, value] of Object.entries(freshnessPartial)) {
+    const build = FRESHNESS_CONDITION_BUILDERS[key];
+    const msg = build ? build(value) : null;
+    if (msg) newConditions.push(msg);
+  }
+  if (!newConditions.length) return { ...scanHealth, freshness };
+  return {
+    ...scanHealth,
+    freshness,
+    conditions: [...scanHealth.conditions, ...newConditions],
+    status: scanHealth.status === 'complete' ? 'partial' : scanHealth.status,
+  };
+}

package/src/posture/CLAUDE.md

@@ -349,6 +349,8 @@ output), and an entry a participant could not run is **unscored**, never counted
 as a miss. Matching is CWE-only so nobody is scored on this engine's vocabulary.
 Driver: `scripts/comparison.mjs`, over the CVE-replay corpus.
 
+**State artifact registry (assurance-hardening PRD FR-701/FR-703)** — `artifact-registry.js`. The registry `cmdReset` (bin/agentic-security.js) now iterates instead of two hardcoded WIPE/WIPE_DIRS Sets. Every known `.agentic-security/` artifact is classified `generated` (scanner-written, safe to delete on reset) or `operator-config` (hand- or agent-authored input, never deleted) — built from an audit of every `statePath()`/`stateDir()` call site, not guessed from filenames; several looked generated by name but turned out to be inputs (`.agentic-security/logic-claims.json`, `.agentic-security/exploit-history.jsonl`, `.agentic-security/cve-alerts.json`, `.agentic-security/network-policy.json`, `.agentic-security/current-intent.md` — see the module's own header for the evidence behind each). Guarded by a completeness test (`test/artifact-registry-completeness.test.js`) that scans for every `statePath()`/`stateDir()` literal and fails if one isn't registered — a `no-dead-modules.test.js`-style drift guard, not a snapshot.
+
 ## Gotchas
 
 - The seed `calibration-seed.json` is small (n < 30 for several families). Don't treat it as a held-out set — that's `holdout-eval.js`'s job, against an externally-supplied JSONL.

package/src/posture/accuracy-scorecard.js

@@ -113,7 +113,11 @@ export function aggregateCorpus(detail) {
 
 /**
  * Build the machine-readable scorecard model. `inputs`:
- *   provenance   { engineVersion, bundleSha256, commit, nodeVersion, generatedAt }
+ *   provenance   { engineVersion, bundleSha256, commit, nodeVersion, generatedAt,
+ *                  corpusVersion?, scope? } — the last two are FR-901's
+ *                  "corpus version" and "scope" fields; optional so a
+ *                  caller with no corpus baseline to hash still gets a
+ *                  valid scorecard rather than a thrown error.
  *   corpusDetail per-entry records from a corpus run performed THIS run
  *   selfScan     { targets: {name:{total,byFile}}, polyglot: {total,byLanguage} }
  *                — measured THIS run
@@ -190,6 +194,38 @@ export function buildScorecard(inputs) {
           overall: committed.independent.overall || null,
           wide: committed.independent.wide || null,
           byLanguage: committed.independent.byLanguage || null,
+          // FR-904: "rule authors cannot optimize against the full scored
+          // population" — bench/independent/runner.mjs's T0.7 already
+          // computes a deterministic (id-hashed) held-out slice, scored
+          // separately and never tuned against, but the published scorecard
+          // used to report only the merged `overall` figures, so the one
+          // number this requirement is actually about never reached a
+          // release artifact anyone reads. Passed through unmodified —
+          // absent (null) on any committed RESULT.json predating T0.7.
+          heldOut: committed.independent.heldOut || null,
+          development: committed.independent.development || null,
+        }
+        : null,
+      // FR-905: "publish false-positive adjudication and coverage
+      // methodology." Three of the four named categories were already
+      // published (unsupported cases via population.unscored above; the
+      // qualitative FP/unlabeled-output methodology in
+      // bench/independent/README.md's "Honest limits" section) — this is
+      // the fourth: WHY a false negative is a false negative, broken down
+      // by mechanism (bench/independent/why-missed.mjs). Read from a
+      // committed file for the same reason `independent` above is — the
+      // full population's diagnostic run is measured in minutes, far too
+      // long to sit inside `npm run scorecard`. Absent (null) until
+      // why-missed.mjs has been run at least once and its summary
+      // committed.
+      whyMissed: committed.whyMissed
+        ? {
+          source: 'bench/independent/why-missed-summary.json',
+          measuredAt: committed.whyMissed.measuredAt || null,
+          scope: committed.whyMissed.scope || null,
+          total: committed.whyMissed.total ?? null,
+          skipped: committed.whyMissed.skipped ?? null,
+          byBucket: committed.whyMissed.byBucket || null,
         }
         : null,
       proofCorpus: proof
@@ -241,6 +277,12 @@ export function renderScorecardMarkdown(m) {
   }
   L.push(`| Node | ${p.nodeVersion || 'unknown'} |`);
   L.push(`| Corpus entries | ${c.totalEntries} (${c.scoredEntries} scored) |`);
+  // FR-901: "Published results identify engine version, corpus version,
+  // commit, scope, and date" — corpusVersion (a content hash, independent
+  // of the engine's own commit) and scope (what was actually measured)
+  // close the two named fields the rows above didn't already cover.
+  if (p.corpusVersion) L.push(`| Corpus version | \`${p.corpusVersion}\` |`);
+  if (p.scope) L.push(`| Scope | ${p.scope} |`);
   L.push(`| ${TIMESTAMP_MARKER} | ${p.generatedAt || 'unknown'} |`);
   L.push('');
   L.push('## What these numbers are, and what they are not');
@@ -532,6 +574,57 @@ export function renderScorecardMarkdown(m) {
     L.push('in this document**, and publishing it is the point of the exercise. The figure');
     L.push('went DOWN when the benchmark was corrected, and is published that way.');
     L.push('');
+    // FR-904 (assurance-hardening PRD): "rule authors cannot optimize
+    // against the full scored population." T0.7's held-out slice is a
+    // no-op section (silently omitted) on a RESULT.json predating it —
+    // never a fabricated 0/0 row pretending to be data.
+    if (ind.heldOut && ind.development) {
+      L.push('### Held-out slice — never tuned against');
+      L.push('');
+      L.push('`bench/independent/runner.mjs` splits the population by a deterministic hash of');
+      L.push('each entry\'s id (T0.7) — a fixed 20% held-out slice, stable across runs and');
+      L.push('population growth, that detector development never sees scored results for.');
+      L.push('This is the number that answers whether the figures above reflect genuine');
+      L.push('accuracy or tuning against the population being measured.');
+      L.push('');
+      L.push('| | Held-out (never tuned against) | Development |');
+      L.push('| --- | --- | --- |');
+      L.push(`| Entries | ${ind.heldOut.entries} | ${ind.development.entries} |`);
+      L.push(`| Precision | ${formatRate(ind.heldOut.localized?.precision?.n, ind.heldOut.localized?.precision?.d)} | ${formatRate(ind.development.localized?.precision?.n, ind.development.localized?.precision?.d)} |`);
+      L.push(`| Recall | ${formatRate(ind.heldOut.localized?.recall?.n, ind.heldOut.localized?.recall?.d)} | ${formatRate(ind.development.localized?.recall?.n, ind.development.localized?.recall?.d)} |`);
+      const heldF1 = ind.heldOut.localized?.f1;
+      const devF1 = ind.development.localized?.f1;
+      L.push(`| F1 | ${heldF1 === null || heldF1 === undefined ? 'n/a' : heldF1.toFixed(3)} | ${devF1 === null || devF1 === undefined ? 'n/a' : devF1.toFixed(3)} |`);
+      L.push('');
+    }
+    // FR-905: the 4th named category ("missed findings" methodology) —
+    // WHY a false negative is a false negative, broken down by mechanism.
+    // Omitted entirely (not a fabricated zero row) until why-missed.mjs has
+    // been run and its summary committed.
+    const wm = m.committedInputs.whyMissed;
+    if (wm) {
+      L.push('### Missed findings — why, not just how many');
+      L.push('');
+      L.push(`**Measured ${wm.measuredAt}** (*committed artifact*, \`${wm.source}\`) — ` +
+        `${wm.total} false negative(s) diagnosed${wm.skipped ? `, ${wm.skipped} skipped (not fetched)` : ''}.`);
+      L.push('');
+      L.push('Each is classified into exactly one mechanism: does something fire and get');
+      L.push('suppressed (by an ignore pragma, a sanitizer, a custom rule, or the');
+      L.push('guard-recognition window), does a finding land on the wrong file or CWE, or');
+      L.push('does nothing fire at all. This is the difference the raw recall number above');
+      L.push('cannot show by itself — "this shape does not occur in these real advisories"');
+      L.push('and "a real detection was masked downstream" look identical as one number and');
+      L.push('very different once broken down this way.');
+      L.push('');
+      if (wm.byBucket && Object.keys(wm.byBucket).length) {
+        L.push('| Mechanism | Count |');
+        L.push('| --- | --- |');
+        for (const [bucket, count] of Object.entries(wm.byBucket).sort((a, b) => b[1] - a[1])) {
+          L.push(`| ${bucket} | ${count} |`);
+        }
+        L.push('');
+      }
+    }
   }
   L.push('## Committed artifacts referenced (not re-run by this command)');
   L.push('');
@@ -565,6 +658,8 @@ export function renderScorecardMarkdown(m) {
   L.push('| Corpus drift gate | `npm run bench:cve-replay:check` |');
   L.push('| Self-scan counts | `node bench/self-scan/measure.mjs --json` |');
   L.push('| Self-scan drift gate | `npm run bench:self-scan:check` |');
+  L.push('| Independent population (read, not re-run — ~32 minutes) | `npm run bench:independent` |');
+  L.push('| Missed-findings mechanism breakdown (read, not re-run) | `npm run bench:independent:why-missed -- --all` |');
   L.push('| This whole document | `npm run scorecard` |');
   L.push('');
   L.push('Running `npm run scorecard` twice on an unchanged tree produces an');