@clear-capabilities/agentic-security-scanner 0.143.0 → 0.145.0

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,129 @@ 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.
+
+## Finding provenance — `provenance/` (20 modules)
+
+The only SUBDIRECTORY under `posture/`, because it is a pipeline rather than an
+annotator: twenty small modules that together answer "which commit introduced
+this finding, and how sure are we?" Everything outside the subdirectory sees one
+function, `annotateGitProvenance(findings, ctx)` from `coordinator.js`, wired in
+`engine.js` after every finding has been appended.
+
+**Read the naming rule before you touch anything here.** The exported function is
+`annotateGitProvenance` — NOT `annotateProvenance` (taken by
+`sca/sigstore-verify.js`, build attestations) and NOT `annotateFindingProvenance`
+(taken by `posture/provenance.js`, parser-corroboration signals). `engine.js`
+imports all three; either alternative name is a duplicate binding, and the second
+takes a findings array as its first argument exactly like this one, so a wrong
+import would RUN rather than fail. The field is `finding.findingProvenance`,
+never bare `.provenance` — `finding.provenance` and `supplyChainEntry.provenance`
+are both pre-existing unrelated fields.
+
+**The pipeline**, in call order — all LIVE-WIRED into `engine.js`'s scan unless noted:
+
+| Module | Answers |
+|---|---|
+| `coordinator.js` | the integration point — budget, cache, per-finding dispatch, the terminal-status guarantee |
+| `git-evidence.js` | the only Git wrapper (`getRepoState`, `blameLine`, `candidateCommitsForLine`, `getBlobAtCommit`, `commitMeta`) |
+| `origin-resolver.js` | which commit introduced a SAST finding |
+| `dag-walk.js` | (M3 §3.1) non-first-parent DAG walk + revert/cherry-pick detection for `--provenance deep` |
+| `predicate-replay.js` | was this finding's condition true at commit X (calls `runFullScan` on that commit's blobs) |
+| `sca-origin.js` | which commit moved a directly-declared dependency version into an advisory's vulnerable range |
+| `transitive-sca.js` | (M3 §3.2) the same question for a TRANSITIVE dependency, re-deriving lockfile ancestry per historical commit |
+| `branch-entry.js` | which branch/PR merge brought the origin commit into the current branch |
+| `evidence-attribution.js` | the path:line:commit triples for source / sink / manifest |
+| `confidence.js` | HIGH / MEDIUM / LOW plus the reasons behind it |
+| `lifecycle.js` | the introduce / remediate / reintroduce ledger |
+| `cache.js` | per-(HEAD, stableId, ruleset, boundary, mode) memo under its own top-level `.agentic-security/provenance-cache/` (split out from `provenance/` so it can carry a `'cache'` retentionClass the permanent lifecycle ledger must not get — see artifact-registry.js) |
+| `schema.js` | the status/method/role/confidence enums, `emptyProvenance`, `redactFindingProvenance`, `isProvenanceHealthy` |
+| `validate.js` | shape assertion for tests |
+| `missing-control-resolver.js` | (M3 §3.3, FR-PROV-017) when a previously-observed safeguard disappeared — **wired into `coordinator.js`**: `resolveMissingControlOrigin` calls `resolveMissingControl` for any finding with `missingControlCandidate:true` (today, `sast/rate-limit.js`'s findings) |
+| `providers/config.js`, `providers/github.js`, `providers/gitlab.js` | (M3 §3.4, FR-PROV-022) GitHub/GitLab PR-metadata + CODEOWNERS fetch, config resolved from `.agentic-security/provenance-providers.yml` / token env vars — **wired into `coordinator.js`**: `resolveProviderConfig` is resolved once per scan in `annotateGitProvenance`, and `fetchPRMetadata`/`fetchCodeowners` are called per `complete`-status finding (capped, see `MAX_PROVIDER_ENRICHMENTS_PER_SCAN`), landing on `findingProvenance.providerEnrichment` |
+| `repo-lineage.js` | (M4 §4.2) loads + fully verifies an operator-declared `.agentic-security/repo-lineage.json` cross-repo link (local clones only, no remote fetch) — used by `origin-resolver.js`'s root-commit case, not a standalone-unwired module |
+| `ai-authorship.js` | (M4 §4.3) extensible AI-authorship verifier registry (`registerAIAuthorshipVerifier`/`resolveAIAuthorship`), defaults to `{status:'unknown', verifier:null}` with nothing registered (today's real state) — wired into `origin-resolver.js`'s `originFrom`, so every SAST `findingOrigin` carries `aiAuthorship`; scoped to SAST only, not direct/transitive SCA origins |
+
+**Four invariants, each with a test that fails if you relax it:**
+
+- **Terminal status, always.** After `annotateGitProvenance` returns, every
+  finding carries a `findingProvenance` with one of `complete` / `partial` /
+  `uncommitted` / `not_available` / `budget_exhausted` / `error`. There is no
+  path — missing git binary, malformed finding, downstream throw — that leaves
+  the field absent. `engine.js` additionally backstops every channel OUTSIDE
+  the `_runAnnotator` wrapper, because that wrapper swallows throws —
+  `findings` and `supplyChain` with a full not_available/error catch-all as
+  before; since Task 11, `secrets` and blameable `logicVulns` go through REAL
+  resolution (real stableIds backfilled, real `annotateGitProvenance` calls
+  made), so their outside-the-wrapper coverage narrowed to a defensive
+  catch-all for whatever the real call somehow didn't reach, plus the 3
+  synthetic-line `logicVulns` producers (`license-policy:`/`deploy-platform:`/
+  `stack-playbook:`), which stay on a permanent, principled not_available —
+  never routed through `resolveOrigin` at all, not merely deferred.
+- **Never false certainty.** A shallow clone cannot reach `complete`; an
+  unverifiable parent boundary degrades to `partial` with its reason carried
+  through. `origin-resolver.js` decides this on the `shallow` flag of the
+  repoState object, and it must come from the REAL `getRepoState()` — pass it a
+  stub and the guarantee is gone.
+- **The lifecycle ledger only closes findings on a COMPLETE scan.** `applyScan`'s
+  remediation pass turns absence into the claim "this was fixed," which is sound
+  only if the scan looked everywhere. `runScan.js` computes `completeScan` (false
+  for `--changed-since`/`--pr` and for caller-supplied `fileContents`) and threads
+  it through `runFullScan` to `updateLifecycle`. `updateLifecycle` is also gated on
+  the `scanRoot` being **a directory that exists** — not merely truthy.
+  `resolveProjectRoot` honours a caller-supplied scanRoot only when it resolves to
+  a real directory; for `null`, for a typo'd path, or for a file, it falls back to
+  walking up from the PROCESS CWD. Both doors led to the same corruption: a scan
+  that never looked at your project writing your project's ledger, and then —
+  finding nothing while still claiming `completeScan` — remediating every open
+  finding in it. `agentic-security scan ./typo` is the reachable form. This repo's
+  own checkout accumulated a 1.1 MB ledger of spurious events that way.
+- **One budget for the whole scan.** `engine.js` computes ONE `deadlineAt` and
+  passes it to all five of its `annotateGitProvenance` calls (SAST findings,
+  direct SCA deps, transitive SCA deps per Task 7, then secrets and blameable
+  logicVulns per Task 11); a caller-supplied `deadlineAt`/`perFindingBudgetMs`
+  wins over the coordinator's own computation. Inside, each finding gets
+  `max(2s, remaining/count)` so one deep-history finding cannot starve the rest.
+  `budget_exhausted` is the one result that is **never cached** — it is a property
+  of the run, not the repository, and caching it would pin a timeout in place
+  until HEAD moved.
+
+**Re-entrancy brake.** `predicate-replay.js` calls `runFullScan` back on historical
+blobs, so every internal re-scan must pass `provenance:false` or the pass recurses
+without bound. Present callers: `history-scan.js` (×3), `pr-delta.js`,
+`fix-verify.js`, `compare.js`; `lsp/server.js` uses the wider
+`withStateWritesDisabled`.
+
+**Privacy.** Author emails are collected but redacted by `redactFindingProvenance`
+at every output boundary (`report/index.js`, `mcp/tools.js`) unless
+`AGENTIC_SECURITY_INCLUDE_AUTHOR_EMAIL=1` / `--include-author-email`. Separately,
+`AGENTIC_SECURITY_PSEUDONYMIZE_AUTHORS=1` / `--pseudonymize-authors` (PRD Section 8)
+replaces `authorName` with a stable `Contributor-XXXXXXXX` pseudonym instead of
+withholding it — `redactFindingProvenance` applies the same treatment to
+`providerEnrichment.reviewers`/`codeowners` (FR-PROV-022's PR-reviewer logins and
+raw CODEOWNERS lines), not just `findingOrigin`. Both `report/index.js` and
+`mcp/tools.js` read the env var per call to build the redaction options
+(`mcp/tools.js` deliberately never reads `AGENTIC_SECURITY_INCLUDE_AUTHOR_EMAIL`
+itself — an agent caller gets no raw email regardless of that flag); the
+`auditor-walkthrough.js` narrative reads it too, for the one `earliestOrigin`
+field that bypasses `redactFindingProvenance` entirely (see that module's own
+comment on why).
+
+**At rest, `provenance/cache.js` stores the UNREDACTED record, on purpose.**
+Redaction is a read-time/output-time concern — the same cached record gets
+replayed back out through `redactFindingProvenance` differently per output
+call (default vs. `--include-author-email` vs. `--pseudonymize-authors`), which
+only works if the cache holds one raw, policy-independent copy. Pre-redacting
+at write time would freeze whichever policy was active when the entry was
+cached, breaking that per-call flexibility for every later reader (second
+independent Finding Provenance PRD audit). The accepted mitigation is a
+permissions floor, not encryption: every `cacheSet` chmods the entry file to
+`0600` and the `provenance-cache/` directory to `0700` (same posture as
+`integrity.js`'s per-install HMAC key). This defeats other local users/processes
+reading the cache; it does not defeat root or the same OS user. See
+`cache.js`'s own header for the full tradeoff writeup, including why
+encryption-at-rest was considered and deferred.
+
 ## 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,12 +113,28 @@ 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
  *   committed    { corpusBaseline, proofCorpus } — read from committed files,
  *                labelled as such in the output, never used to derive a rate
+ *   scan         optional — a scan-shaped object (`{findings, secrets,
+ *                supplyChain}`, trimmed to just those arrays) from a run over
+ *                a full (non-shallow) Git clone, used ONLY to compute
+ *                provenanceCoverage below. `scripts/scorecard.mjs` passes
+ *                `selfScan.provenanceScan` — the self-scan harness
+ *                (bench/self-scan/measure.mjs) already runs a real
+ *                `runScan()` over this project's own full git clone with
+ *                provenance resolution on by default, so this reuses that
+ *                run's already-computed `findingProvenance` rather than
+ *                performing a second scan. Still optional: a caller with no
+ *                such scan renders "not measured this run" rather than a
+ *                fabricated rate. See PRD Success Metrics.
  */
 export function buildScorecard(inputs) {
   const corpus = aggregateCorpus(inputs.corpusDetail);
@@ -159,6 +175,14 @@ export function buildScorecard(inputs) {
       byTier: corpus.byTier,
     },
     selfScan: { measuredThisRun: true, targets, polyglot: selfScan.polyglot || { total: 0, byLanguage: {} } },
+    // PRD Success Metrics: "Provenance coverage >=95% complete or uncommitted
+    // for P0-supported findings in full Git clones." `inputs.scan` is
+    // optional (see the JSDoc above) — absent when no caller yet supplies a
+    // real scan, in which case this reports "not measured" rather than a
+    // fabricated 0/0.
+    provenanceCoverage: inputs.scan
+      ? { measuredThisRun: true, ...computeProvenanceCoverage(inputs.scan) }
+      : { measuredThisRun: false },
     taintRecall: (() => {
       const lr = inputs.layerRecall;
       if (!lr) {
@@ -190,6 +214,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
@@ -213,6 +269,28 @@ export function buildScorecard(inputs) {
   };
 }
 
+// PRD Success Metrics: "Provenance coverage >=95% complete or uncommitted
+// for P0-supported findings in full Git clones." P0-supported scope per
+// the PRD's own Release Scope table: code (SAST), secrets, IaC/config,
+// direct dependency findings. Secrets now get real origin resolution
+// (Task 11 -- `engine.js` calls `annotateGitProvenance` on `scan.secrets`
+// with a real per-pattern-backfilled stableId, the same as SAST findings),
+// so this metric no longer has a structural reason to read lower for the
+// secrets share of the denominator than for any other P0-scoped channel.
+export function computeProvenanceCoverage(scan) {
+  const p0Findings = [
+    ...(scan.findings || []),
+    ...(scan.secrets || []),
+    ...(scan.supplyChain || []).filter((s) => s.type === 'vulnerable_dep' && s.isDirect),
+  ];
+  const d = p0Findings.length;
+  const n = p0Findings.filter((f) => {
+    const status = f.findingProvenance?.status;
+    return status === 'complete' || status === 'uncommitted';
+  }).length;
+  return { n, d };
+}
+
 function rateRow(r) {
   return `| ${r.key} | ${r.entries} | ${formatRate(r.detection.n, r.detection.d)} | ${formatRate(r.silence.n, r.silence.d)} |`;
 }
@@ -241,6 +319,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');
@@ -428,6 +512,24 @@ export function renderScorecardMarkdown(m) {
   }
   L.push('Per-file counts are in `docs/scorecard.json`.');
   L.push('');
+  if (m.provenanceCoverage && m.provenanceCoverage.measuredThisRun) {
+    L.push('## Provenance coverage');
+    L.push('');
+    L.push('PRD Success Metric: **>=95% of P0-scoped findings (SAST + secrets + direct**');
+    L.push('**dependency findings) resolve to `complete` or `uncommitted` git provenance**');
+    L.push('in a full (non-shallow) clone. Transitive dependency findings are excluded —');
+    L.push('the PRD\'s Release Scope table names direct dependency findings only.');
+    L.push('');
+    L.push('| P0-scoped findings — complete/uncommitted provenance |');
+    L.push('| --- |');
+    L.push(`| ${formatRate(m.provenanceCoverage.n, m.provenanceCoverage.d)} |`);
+    L.push('');
+    L.push('Secrets, SAST, and direct-dependency findings all resolve through the same');
+    L.push('git-origin resolution pipeline, so a gap in this rate reflects the clone');
+    L.push('itself (shallow history, uncommitted lines the pipeline could not blame) —');
+    L.push('not a channel this measurement structurally cannot yet cover.');
+    L.push('');
+  }
   // PRD F12.6 — the honest scorecard publishes the LIMITS too, not only the
   // rates. Three claims this project makes are only meaningful with their
   // caveat attached, and each caveat was invisible before this section:
@@ -532,6 +634,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 +718,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');