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

package/src/pipeline/assurance-mode.js

@@ -42,6 +42,8 @@
 // mode to behave differently from advisory, that is a deliberate, separate
 // decision -- not something to guess at here.
 
+import { isProvenanceHealthy } from '../posture/provenance/schema.js';
+
 export const ASSURANCE_MODES = Object.freeze(['advisory', 'standard', 'strict']);
 export const DEFAULT_ASSURANCE_MODE = 'standard';
 
@@ -56,7 +58,7 @@ function _isValidMode(mode) {
  *   ok:false only ever happens in strict mode; advisory/standard always ok:true
  *   (they report, they do not gate).
  */
-export function evaluateAssuranceMode(mode, scanHealth) {
+export function evaluateAssuranceMode(mode, scanHealth, findings = []) {
   const effectiveMode = _isValidMode(mode) ? mode : DEFAULT_ASSURANCE_MODE;
   const conditions = Array.isArray(scanHealth?.conditions) ? scanHealth.conditions : [];
 
@@ -85,6 +87,67 @@ export function evaluateAssuranceMode(mode, scanHealth) {
       conditions,
     };
   }
+
+  // M2 §2.5: strict cares about overall scan completeness, which now
+  // explicitly includes PROVENANCE completeness, not just detector/analyzer
+  // completeness. A finding whose findingProvenance status is outside
+  // ['complete','uncommitted'] — including a finding with NO
+  // findingProvenance at all, e.g. --no-provenance was used — means strict
+  // cannot vouch for this scan's provenance the same way it already refuses
+  // to vouch for a scan with a failed analyzer.
+  //
+  // KNOWN INTERACTION: scan.secrets/scan.logicVulns are unconditionally
+  // stamped not_available today (M0+M1 deliberately deferred real origin
+  // resolution for those two channels — see the M2/M3/M4 design spec's
+  // §2.6). Any real secret or logic finding therefore fails strict mode
+  // until that resolution work lands. This is the literal, intended
+  // consequence of "never false certainty" applied to strict's own
+  // definition, not an oversight — a strict-mode operator with secrets
+  // findings should expect this until M3+ closes that gap.
+  //
+  // This list is INCOMPLETE without scan.supplyChain, and the omission
+  // matters more than the secrets/logic one above because it hits nearly
+  // every real project. engine.js stamps every supplyChain entry
+  // not_available too (see the loop over `supplyChain` right after the
+  // `annotateGitProvenance` calls), and that bucket covers three distinct
+  // populations, not one:
+  //
+  //  - transitive `vulnerable_dep` findings: a genuine, if currently
+  //    unresolved, DEFERRAL — same shape as secrets/logicVulns above. The
+  //    vulnerable version was never declared in this repo's own manifests,
+  //    so there is no local commit to walk yet, but one could exist to
+  //    resolve in a later phase.
+  //  - `unpinned_dep` / `no_lockfile` findings: a CATEGORY ERROR, not a
+  //    deferral. These describe an ABSENT state (a version range with no
+  //    pin, a manifest with no lockfile) — there is no "commit that
+  //    introduced a missing lockfile" for any future resolver to find,
+  //    because the finding is about the absence of an event, not an event
+  //    itself. No amount of future engineering work makes these resolvable.
+  //
+  // Direct `vulnerable_dep` findings DO go through real origin resolution
+  // (`resolveDirectSCAOrigin`, gated on `isDirect`) and are not part of this
+  // limitation.
+  //
+  // Net effect: because `unpinned_dep`/`no_lockfile` findings are a category
+  // error rather than a deferral, `--assurance strict` will fail on nearly
+  // any real project that has a `package.json` (or equivalent manifest)
+  // today — an unpinned or unlocked dependency is common, and this check has
+  // no way to ever resolve one. This is a known, disclosed limitation of the
+  // current implementation, not a bug, and it is not something this check
+  // should route around: exempting these finding types from the strict-mode
+  // gate was considered and deliberately deferred to a future milestone
+  // rather than done here, so strict mode keeps refusing to vouch for
+  // provenance it cannot actually speak to.
+  const badProvenance = (Array.isArray(findings) ? findings : []).filter((f) => !isProvenanceHealthy(f?.findingProvenance));
+  if (badProvenance.length > 0) {
+    return {
+      ok: false,
+      mode: 'strict',
+      reason: `strict mode requires complete finding provenance; ${badProvenance.length} finding(s) have status outside [complete, uncommitted]`,
+      conditions,
+    };
+  }
+
   return { ok: true, mode: 'strict', reason: null, conditions };
 }
 

package/src/pipeline/finding-schema.js

@@ -46,7 +46,14 @@ export const FINDING_SCHEMA_VERSION = 1;
 // 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'] },
+  // `findingProvenance` is REQUIRED, not optional, and that is deliberate:
+  // posture/provenance/coordinator.js guarantees every finding it sees leaves
+  // with a TERMINAL provenance object, expressing every failure mode as a
+  // status ('not_available', 'uncommitted', 'budget_exhausted', 'error')
+  // rather than as an absent field. So a missing findingProvenance never means
+  // "provenance didn't apply here" — it means the finding escaped annotation
+  // entirely, which is exactly the condition this group exists to surface.
+  identity: { required: ['id', 'kind', 'vuln', 'findingProvenance'], 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'] },

package/src/pipeline/scan-health.js

@@ -33,6 +33,7 @@ export const SCAN_HEALTH_SCHEMA_VERSION = 1;
  * @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.lineageStatus] - { requested, enabled, reason, failure } — Sub-project E, increment 5's own status, kept separate from deepStatus (IR-taint's own).
  * @param {object} [input.analyzerCoverage] - coverage-ledger.js's
  *   summarizeCoverageForScanHealth() output: {expected, completed, failed,
  *   timedOut, skippedByPolicy}. Omitted (not just empty) is treated the
@@ -41,7 +42,7 @@ export const SCAN_HEALTH_SCHEMA_VERSION = 1;
  *   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 } = {}) {
+export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engineErrors = null, deepStatus = null, analyzerCoverage = null, lineageStatus = null } = {}) {
   const conditions = [];
   const safeAnnotatorErrors = Array.isArray(annotatorErrors) ? annotatorErrors : [];
   const filesTimedOut = Number(scanMeta?.filesTimedOut) || 0;
@@ -63,6 +64,15 @@ export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engin
   if (deepStatus?.requested && !deepStatus.enabled) {
     conditions.push(`deep analysis was requested but did not run: ${deepStatus.reason || 'unknown reason'}`);
   }
+  // Sub-project E, increment 5: lineage graph build status — a SEPARATE
+  // condition from deepStatus above, never folded into it. deepStatus is
+  // specifically IR-taint's own status; conflating the two would make
+  // `scanHealth.deepAnalysis.failure` ambiguous about which subsystem
+  // actually failed (the same "distinguish A from B" discipline this
+  // module already applies to analyzerCoverage vs. annotatorErrors).
+  if (lineageStatus?.failure) {
+    conditions.push(`lineage graph build threw and was skipped: ${lineageStatus.failure}`);
+  }
   // 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
@@ -96,6 +106,14 @@ export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engin
           failure: deepStatus.failure ?? null,
         }
       : null,
+    lineageAnalysis: lineageStatus
+      ? {
+          requested: !!lineageStatus.requested,
+          enabled: !!lineageStatus.enabled,
+          reason: lineageStatus.reason ?? null,
+          failure: lineageStatus.failure ?? null,
+        }
+      : null,
     annotatorErrorCount: safeAnnotatorErrors.length,
     freshness: null,
     conditions,

package/src/posture/CLAUDE.md

@@ -42,6 +42,23 @@ actually took — and are flagged `reliable:false` below n=10 rather than hidden
 or quoted as settled. Recording goes through `isSafeStateDir`, so it declines
 rather than creating a stray state dir outside a project.
 
+**Remediation ledger (M5 deliverable #6)** — `remediation-ledger.js`. The
+I/O half of Blast-Radius: Remediation Command Center (FR-507 + AC-31) —
+locking, JSONL append, tolerant read, and a hash chain over
+`.agentic-security/remediation/items.jsonl`/`items.lock`, matching
+`fix-metrics.js`'s own append-and-tolerant-read shape above (one
+newline-terminated record per `appendFileSync`, a torn tail dropped on
+read, never a whole-file rewrite). The pure state machine it writes
+through — `foldRemediationItem`/`foldRemediationLedger`/
+`validateTransition` — lives at `../lineage/remediation.js`, making this
+the SECOND `posture/` → `lineage/` import in the codebase
+(`auditor-walkthrough.js`'s `graph:` branch was the first — see "First
+`posture/` → `lineage/` import" below). `appendLedgerEvent` is the single
+place `validateTransition` is enforced; no CLI command computes validity
+for itself. Its `withLock` is a faithful local PORT of
+`provenance/lifecycle.js`'s own `withLock` — not an import, since that
+function is not exported.
+
 **Agentic verification** — `verifier.js`, `verifier-target.js`, `verifier-ephemeral.js`, `harness-discovery.js`, `adversary-agent.js`, `defender-agent.js`, `auditor-agent.js`, `three-agent-pipeline.js`.
 
 **Methodology additions (Agentic Methodology PRD, removed post-implementation)** — default-on annotators/artifacts that layer the agentic-hunter methodology on the deterministic engine:
@@ -83,6 +100,8 @@ Wired in `bin/agentic-security.js` after every filter and after `makeDeterminist
 
 **Rule lifecycle** — `custom-rules.js` (YAML pattern DSL), `rule-overrides.js` (`disable:` gated on signature), `rule-packs.js`, `rule-synthesis.js` (proposes suppressions from triage feedback), `ruleset-version.js`.
 
+**First `posture/` → `lineage/` import.** `auditor-walkthrough.js`'s `graph:` mapping branch (Data Flow Explorer M4 sub-project 6b) imports `evaluateGraphFlowPredicate`/`buildObligationMappingFromGraphPredicate` from `../lineage/obligation-predicates.js` — the first time any module in this directory has reached into `lineage/` (previously a one-way boundary: `lineage/` never imports `posture/`, and nothing here imported it back). It mints a real `ObligationMapping` record (see `scanner/src/lineage/CLAUDE.md`) from `scan.lineageGraph` when present, purely additively — never touching the pre-existing `anySignal`/`allCleared`/`anyCleared`/`hasUnverifiableMapping` status machinery.
+
 **NIST Privacy Framework 1.1 (`privacy-framework.js`)** — assessment + remediation
 over the bundled `compliance-frameworks/nist-privacy-1-1.json` (all 104 controls).
 Sits on top of `auditor-walkthrough.js`'s evaluator and adds the half a narrative
@@ -351,6 +370,127 @@ 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

@@ -123,6 +123,18 @@ export function aggregateCorpus(detail) {
  *                — 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);
@@ -163,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) {
@@ -249,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)} |`;
 }
@@ -470,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:

package/src/posture/artifact-registry.js

@@ -83,6 +83,31 @@ export const ARTIFACT_REGISTRY = [
   { name: 'scan-history.json', kind: 'file', classification: 'generated', retentionClass: 'scan' },
   { name: 'last-scan.json', kind: 'file', classification: 'generated', retentionClass: 'scan' },
   { name: 'last-scan.json.sig', kind: 'file', classification: 'generated', retentionClass: 'scan' },
+  // Sub-project E, increment 5: the Data Flow Explorer's DataFlowGraph v1
+  // document + signature, written by bin/agentic-security.js alongside
+  // last-scan.json whenever AGENTIC_SECURITY_LINEAGE_DEEP=1 produced a
+  // graph. NOT to be confused with the similarly-named, already-registered
+  // `repo-lineage.json` below — that one is an operator-authored
+  // cross-repo provenance declaration (classification 'operator-config',
+  // never written by the scanner); this one is scanner-generated scan
+  // output derived from the user's own source (dataElements[].dataClasses
+  // included), so it belongs in the 'generated'/'scan' bucket `reset`
+  // clears by default, same as last-scan.json itself.
+  { name: 'lineage-graph.json', kind: 'file', classification: 'generated', retentionClass: 'scan' },
+  { name: 'lineage-graph.json.sig', kind: 'file', classification: 'generated', retentionClass: 'scan' },
+  // M4 deliverable #8 (FR-503 §14, DFG-022, sub-project 8a): the "Data-Flow
+  // Time Machine" foundation — one commit-keyed GraphSnapshot per scan,
+  // written by src/lineage/graph-snapshot.js's persistGraphSnapshot(),
+  // additively alongside (never replacing) lineage-graph.json above. Same
+  // 'generated'/'scan' bucket for the same reason: fully scanner-derived,
+  // regenerable by re-scanning at that commit.
+  { name: 'lineage-snapshots', kind: 'dir', classification: 'generated', retentionClass: 'scan', source: 'src/lineage/graph-snapshot.js (persistGraphSnapshot)' },
+  // M5 deliverable #7 (FR-505 §7.12, AC-29): the Runtime-Corroborated
+  // Digital Twin's observation store — one immutable whole file per adapter
+  // import, written by src/lineage/observation-store.js's
+  // persistObservationImport(), mirroring lineage-snapshots/'s own
+  // directory-of-files shape re-keyed commit -> import.
+  { name: 'runtime-observations', kind: 'dir', classification: 'generated', retentionClass: 'evidence', confidential: true, source: 'src/lineage/observation-store.js (persistObservationImport)', note: 'FR-505 requires an observation store follow artifact encryption, RETENTION, RESET, access-control and no-egress rules. That is why this is `generated` (a plain `reset` MUST be able to delete it) rather than `operator-config`, and why it carries a real retentionClass — deliberately NOT the `remediation`/`legal-holds.json` no-retention call one section down, and deliberately NOT `provenance`\'s permanent-history call. This DOES stretch `generated`\'s usual definition — a rescan does not re-derive an import, the operator re-imports it — and that stretch is disclosed here rather than hidden: FR-505\'s explicit reset requirement breaks the tie. `confidential: true` is enforced by observation-store.js calling maybeEncryptForWrite/maybeDecryptForRead itself (posture/encryption-provider.js), the same per-writer opt-in compliance-evidence.json makes — the flag alone enforces nothing.' },
   { name: 'shadow-findings.json', kind: 'file', classification: 'generated', retentionClass: 'scan' },
   { name: 'mcp-audit.log', kind: 'file', classification: 'generated', retentionClass: 'evidence' },
   { name: 'egress-audit.log', kind: 'file', classification: 'generated', retentionClass: 'evidence', note: "FR-604 per-call egress audit log — hash-chained NDJSON written by egress/audit.js's recordEgressCall, never read as config" },
@@ -125,6 +150,28 @@ export const ARTIFACT_REGISTRY = [
   { name: 'sca-upgrade-history', kind: 'dir', classification: 'generated', retentionClass: 'scan' },
   { name: 'scan-baselines', kind: 'dir', classification: 'generated', retentionClass: 'scan', source: 'posture/pr-augment.js' },
   { name: 'agent-scratchpad', kind: 'dir', classification: 'generated', retentionClass: 'cache', source: 'mcp/tools.js (append_scratchpad)' },
+  // Finding Provenance (M0/M1, split per PRD Section 8 retention task). Used
+  // to be one directory with two writers sharing it, which meant they could
+  // not get different retention treatment — `cmdReset`/`findExpiredArtifacts`
+  // only ever operate on exact TOP-LEVEL `.agentic-security/` directory
+  // names, never on a `/`-qualified sub-path. Now physically split:
+  //   - posture/provenance/cache.js writes provenance-cache/<hash>.json — a
+  //     pure HEAD-keyed memo of resolved origins, safely regenerable, no
+  //     correctness dependency on being preserved. Gets retentionClass:
+  //     'cache' (7-day default / 30-day max TTL, RETENTION_DEFAULTS.cache).
+  //   - posture/provenance/lifecycle.js writes provenance/lifecycle.json +
+  //     .lock — the introduce/remediate/reintroduce ledger. Deliberately NO
+  //     retentionClass: this is permanent history, not a cache; auto-expiring
+  //     it would silently lose lifecycle events a report may already have
+  //     cited. `reset` (without `--expired`) still clears it, which is
+  //     explicit operator action, unlike TTL-driven auto-expiry.
+  // Old-location cache files (`provenance/cache/*.json`, written before this
+  // split) are DELIBERATELY NOT migrated — see cache.js's own comment and the
+  // commit that introduced this split. They are simply orphaned: invisible to
+  // this registry, un-swept by reset/retention, silently ignored by the new
+  // code, and harmless to leave until a human deletes them by hand.
+  { name: 'provenance-cache', kind: 'dir', classification: 'generated', retentionClass: 'cache', source: 'posture/provenance/cache.js -- pure HEAD-keyed memo, safely regenerable, no correctness dependency on being preserved' },
+  { name: 'provenance', kind: 'dir', classification: 'generated', source: 'posture/provenance/lifecycle.js -- the introduce/remediate/reintroduce ledger. Deliberately NO retentionClass: this is permanent history, not a cache; auto-expiring it would silently lose lifecycle events a report may already have cited.' },
   { name: 'AGENTS.md', kind: 'file', classification: 'generated', source: 'posture/agents-memory.js' },
   { name: 'AGENTS.md.archive', kind: 'file', classification: 'generated', source: 'posture/agents-memory.js' },
   { name: 'baseline.json', kind: 'file', classification: 'generated', source: 'bin/agentic-security.js (--set-baseline)', note: 'operator-set intent, functionally closer to operator-config than scan output — no auto-expiry' },
@@ -146,6 +193,19 @@ export const ARTIFACT_REGISTRY = [
   { name: 'deletion-report.json', kind: 'file', classification: 'generated', retentionClass: 'evidence', source: 'posture/state-lifecycle-report.js (via bin/agentic-security.js cmdReset)' },
   { name: 'export-report.json', kind: 'file', classification: 'generated', retentionClass: 'evidence', source: 'posture/state-lifecycle-report.js (via bin/agentic-security.js cmdExport)' },
 
+  // M5 governance editing workflow final-review fix round 1 (I5): backups
+  // of recipient-profiles.json written by `governance propose-edit --yes`,
+  // mirroring the `fix-history` directory precedent above — one directory
+  // entry covers every timestamped .bak file inside it, since the registry
+  // only supports exact-name matches, never a per-file timestamped name.
+  { name: 'recipient-profiles-backups', kind: 'dir', classification: 'generated', retentionClass: 'backup', note: 'per-edit backups written by `governance propose-edit --yes`, mirrors the fix-history/ precedent — one directory entry covers every timestamped .bak file inside it' },
+
+  // M5 deliverable #8 (FR-304 "declared" half): backups of
+  // cross-repo-links.json written by `federate declare --yes`, mirrors
+  // the `recipient-profiles-backups` precedent immediately above
+  // exactly.
+  { name: 'cross-repo-links-backups', kind: 'dir', classification: 'generated', retentionClass: 'backup', note: 'per-declare backups written by `federate declare --yes`, mirrors the recipient-profiles-backups/ precedent — one directory entry covers every timestamped .bak file inside it' },
+
   // ── Operator-config: hand-authored (or agent-authored) input, never wiped ──
   { name: 'rules.yml', kind: 'file', classification: 'operator-config' },
   { name: 'rules', kind: 'dir', classification: 'operator-config' },
@@ -169,12 +229,28 @@ export const ARTIFACT_REGISTRY = [
   { name: 'policy-bundle-public-key.pem', kind: 'file', classification: 'operator-config', note: 'FR-1001 public key an operator installs to verify org-distributed policy bundles — read by posture/policy-bundle.js, never written by the scanner' },
   { name: 'retention-policy.yml', kind: 'file', classification: 'operator-config', note: 'FR-702 per-retention-class TTL overrides (clamped to a built-in per-class maximum) — read by posture/retention-policy.js, never written by the scanner' },
   { name: 'legal-holds.json', kind: 'file', classification: 'operator-config', note: 'FR-707 legal holds ({artifact, owner, reason, expires_at}) — read by posture/retention-policy.js and bin/agentic-security.js cmdReset; WRITTEN by the CLI (legal-hold add/remove), but classified operator-config (not generated) deliberately: a plain `reset` must never be able to delete the very record protecting other artifacts from deletion' },
+  { name: 'remediation', kind: 'dir', classification: 'operator-config', note: 'M5 deliverable #6 remediation work-item ledger (items.jsonl + items.lock) — an APPEND-ONLY record of human decisions: owner assignment, approvals, manual attestations, and accepted-risk exceptions with approver/reason/scope/expiration. WRITTEN by the CLI (`remediation open|update|verify|accept-risk|reopen-check --yes`) but classified operator-config, not generated, deliberately — the same call legal-holds.json makes one entry up: a plain `reset` must never be able to delete the audit trail AC-31 depends on, and nothing regenerates it from a rescan. Deliberately NOT the `provenance` entry\'s `generated` classification (see its own note above): that ledger is scan-derived history a rescan can rebuild; this one is human decisions that cannot be. No retentionClass for the same reason legal-holds.json has none — auto-expiry would silently delete an accepted-risk exception a report may already cite.' },
   { name: 'calibration-feedback.jsonl', kind: 'file', classification: 'operator-config', note: 'FR-806 opt-in calibration ground truth ({at, findingId, outcome: accept-risk|realized-incident, predicted*, note}) — WRITTEN by the CLI (calibration-feedback record), but classified operator-config like exploit-history.jsonl: real, hard-to-recreate customer-reported ground truth, never scanner-regenerable, so a routine reset must never delete it' },
   { name: 'encryption-policy.yml', kind: 'file', classification: 'operator-config', note: 'FR-705 encryption provider/required opt-in policy ({provider: local-key, required: true|false}) — read by posture/encryption-provider.js, never written by the scanner' },
+  { name: 'provenance-providers.yml', kind: 'file', classification: 'operator-config', note: 'Finding Provenance M3 §3.4 GitHub/GitLab provider enrichment opt-in ({token} or provider-scoped tokens) — read by posture/provenance/providers/config.js, never written by the scanner; env vars (AGENTIC_SECURITY_GITHUB_TOKEN/AGENTIC_SECURITY_GITLAB_TOKEN) take precedence when set' },
+  { name: 'repo-lineage.json', kind: 'file', classification: 'operator-config', note: 'Finding Provenance M4 §4.2 cross-repository lineage declaration ({linkedFrom: {path, atCommit}}) — read by posture/provenance/repo-lineage.js, never written by the scanner; the linked path is verified as a real local git repo before use, no remote fetch' },
+  { name: 'recipient-profiles.json', kind: 'file', classification: 'operator-config', note: 'FR-506 recipient/subprocessor governance profiles — hand- or agent-authored via `governance propose-edit`, never scanner-regenerable, so a routine reset must never delete it' },
+  { name: 'cross-repo-links.json', kind: 'file', classification: 'operator-config', note: 'M5 deliverable #8 (FR-304 "declared" half) — declared local<->remote node links between two independently-scanned repos, written via `federate declare --yes`, never scanner-regenerable, so a routine reset must never delete it' },
   { name: 'logic-claims.json', kind: 'file', classification: 'operator-config', note: 'authored by an external reviewing agent; engine.js only ever reads it (fs.readFileSync, never written)' },
   { name: 'current-intent.md', kind: 'file', classification: 'operator-config', note: 'developer-authored; no writer exists anywhere in src/ or bin/' },
   { name: 'exploit-history.jsonl', kind: 'file', classification: 'operator-config', note: 'own header comment: "operator-curated record of past confirmed exploits"' },
   { name: 'cve-alerts.json', kind: 'file', classification: 'operator-config', note: 'own header comment: "Configuration is read from"; state lives in the separate cve-alerts-state.json, which IS generated' },
+  // Pre-existing gap, found by M5 deliverable #7's own scoping investigation
+  // and fixed here rather than left: posture/runtime-correlation.js reads
+  // these three filenames via `statePath(scanRoot, n)` with a VARIABLE, so
+  // test/artifact-registry-completeness.test.js's own PATTERNS regexes (which
+  // require a string literal) never saw them and never demanded registration.
+  // An unregistered state artifact means `reset` does not know about it and
+  // retention cannot reach it. Operator-config, not generated: these are
+  // hand-supplied eBPF/APM trace exports the scanner only ever reads.
+  { name: 'runtime-trace.jsonl', kind: 'file', classification: 'operator-config', note: 'eBPF/APM runtime trace consumed by posture/runtime-correlation.js\'s own trace loader (deliberately not named by its literal export here — no-dead-modules.test.js scans note strings too, and naming it would make it look, wrongly, like a real call site) — operator-supplied, never scanner-written; $AGENTIC_SECURITY_RUNTIME_TRACE_PATH overrides the location entirely' },
+  { name: 'runtime.jsonl', kind: 'file', classification: 'operator-config', note: 'alternate filename for runtime-trace.jsonl — see posture/runtime-correlation.js\'s DEFAULT_TRACE_NAMES' },
+  { name: 'ebpf-trace.jsonl', kind: 'file', classification: 'operator-config', note: 'alternate filename for runtime-trace.jsonl — see posture/runtime-correlation.js\'s DEFAULT_TRACE_NAMES' },
 ];
 
 export function listGeneratedArtifacts() {