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

package/src/posture/policy-bundle.js

@@ -0,0 +1,274 @@
+// Signed, portable policy bundles (assurance-hardening PRD FR-1001).
+//
+// "Support signed portable policy bundles with organization, repository, and
+// environment inheritance" | "Tampered or expired policy is rejected;
+// effective policy is explainable."
+//
+// WHY REUSE evidence-bundle.js's Ed25519 SCHEME, NOT integrity.js's HMAC
+// -------------------------------------------------------------------------
+// A policy bundle is authored by one party (typically a central security
+// team, "the organization") and distributed to many repositories that never
+// had the signing key. integrity.js's per-install symmetric HMAC is
+// tamper-evidence for the SAME install that wrote it — a different install
+// verifying a bundle it didn't sign is exactly the case that scheme cannot
+// serve. evidence-bundle.js already solved this for findings: Ed25519,
+// verify with only the public key. This module reuses that primitive
+// directly (canonicalisation shape, allowlist-signed-fields discipline,
+// exclusive-create key generation) rather than inventing a third signing
+// mechanism, per this session's own established "survey before building a
+// parallel primitive" practice (see D-0023/D-0025 for the same discipline
+// applied to identity and exception mechanisms respectively).
+//
+// EA-03 LESSON, APPLIED HERE FROM THE START
+// -------------------------------------------------------------------------
+// evidence-bundle.js's own history (see its EA-03 comment) is the reason
+// `canonicalPolicyBytes` signs an explicit ALLOWLIST and `verifyPolicyBundle`
+// REJECTS any top-level key outside it: a bundle with a field stapled on
+// after signing must fail verification, not silently pass with the addition
+// unverified. Getting this right on the first pass — rather than discovering
+// the gap the way evidence-bundle.js did — is the entire point of writing it
+// down here.
+//
+// SCOPE — WHAT THIS MODULE DOES NOT DO
+// -------------------------------------------------------------------------
+// It does not invent a policy SCHEMA — `policy` is an opaque object; whatever
+// keys a bundle carries (egress rules, severity floors, approved providers,
+// anything else this repo already treats as policy) are merged the same way.
+// It does not implement deep/recursive merging — inheritance is shallow,
+// top-level-key override (organization -> repository -> environment, most
+// specific wins per key), matching how every other flat policy config file
+// in this repo (egress-policy.yml, compliance-severity-policy.json, …) is
+// already shaped. A future consumer needing nested-key inheritance is new,
+// separate scope, not assumed here.
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import { ensureKeyPair as ensureKeyPairAt } from './evidence-bundle.js';
+import { statePath } from './state-dir.js';
+
+export const POLICY_BUNDLE_SCHEMA = 'agentic-security/policy-bundle@1';
+
+export const SCOPES = ['organization', 'repository', 'environment'];
+// Inheritance order — later entries override earlier ones, per top-level key.
+const INHERITANCE_ORDER = ['organization', 'repository', 'environment'];
+
+function keyDir() {
+  const xdg = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(xdg, 'agentic-security', 'policy-bundles');
+}
+
+/** A SEPARATE Ed25519 keypair from evidence-bundle.js's finding-attestation
+ * key — signing "this policy is authentic" and "this finding really came
+ * from a scan run by me" are different trust domains and must not share a
+ * key. Reuses evidence-bundle.js's hardened, race-safe generation logic
+ * directly (its exclusive-create collision handling is the kind of code
+ * worth NOT re-implementing) rather than duplicating it — the separation
+ * that matters is the DIRECTORY (`policy-bundles/`, isolated from
+ * evidence-bundle.js's own key dir), not the leaf filenames, which are
+ * `attest-key.pem`/`attest-key.pub.pem` regardless of caller (a
+ * evidence-bundle.js internal, not overridable here) — a readability wart,
+ * not a security one, since the directory is what prevents key reuse. */
+export function ensurePolicyKeyPair(dir = keyDir()) {
+  return ensureKeyPairAt(dir);
+}
+
+/**
+ * Deterministic JSON, keys sorted at every level — identical algorithm to
+ * evidence-bundle.js's canonicalJson (duplicated rather than imported: it is
+ * a pure, three-line function, and importing it would couple this module's
+ * signature format to evidence-bundle.js's internals for no real benefit).
+ */
+function canonicalJson(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value ?? null);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map(k => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(',')}}`;
+}
+
+// The complete set of fields a legitimately-built bundle carries, BEFORE
+// signing. This is the signed allowlist AND (in verifyPolicyBundle) the
+// complete set of keys a signed bundle is permitted to have alongside
+// `signature` — see the EA-03 note above for why both matter.
+const BUNDLE_FIELDS = ['schema', 'scope', 'policy', 'issuedAt', 'expiresAt'];
+const BUNDLE_TOP_LEVEL_KEYS = new Set([...BUNDLE_FIELDS, 'signature']);
+
+export function canonicalPolicyBytes(bundle) {
+  const signed = {};
+  for (const k of BUNDLE_FIELDS) signed[k] = bundle[k] ?? null;
+  return Buffer.from(canonicalJson(signed), 'utf8');
+}
+
+/**
+ * Build an unsigned bundle. `policy` is caller-supplied and opaque — this
+ * module does not validate its shape, only its provenance and freshness.
+ */
+export function buildPolicyBundle(scope, policy, { issuedAt, expiresAt } = {}) {
+  if (!SCOPES.includes(scope)) return null;
+  if (!policy || typeof policy !== 'object' || Array.isArray(policy)) return null;
+  return {
+    schema: POLICY_BUNDLE_SCHEMA,
+    scope,
+    policy,
+    issuedAt: issuedAt ?? new Date().toISOString(),
+    expiresAt: expiresAt ?? null,
+  };
+}
+
+/** Sign a bundle. Returns a new object; the input is not mutated. */
+export function signPolicyBundle(bundle, privateKeyPem) {
+  const sig = crypto.sign(null, canonicalPolicyBytes(bundle), privateKeyPem);
+  return {
+    ...bundle,
+    signature: { algorithm: 'ed25519', canonicalisation: POLICY_BUNDLE_SCHEMA, value: sig.toString('base64') },
+  };
+}
+
+/**
+ * Verify a bundle: signature authenticity AND freshness. Never throws — a
+ * malformed or tampered bundle from an untrusted source (a repo checking out
+ * whatever an org distributed) is an expected input, not exceptional.
+ *
+ * @returns {{ok: boolean, reason: string|null}}
+ */
+export function verifyPolicyBundle(bundle, publicKeyPem, { now = Date.now() } = {}) {
+  if (!bundle || typeof bundle !== 'object') return { ok: false, reason: 'bundle is not an object' };
+  if (bundle.schema !== POLICY_BUNDLE_SCHEMA) return { ok: false, reason: `unrecognised schema: ${bundle.schema}` };
+  if (!SCOPES.includes(bundle.scope)) return { ok: false, reason: `unrecognised scope: ${bundle.scope}` };
+  const unknownKeys = Object.keys(bundle).filter(k => !BUNDLE_TOP_LEVEL_KEYS.has(k));
+  if (unknownKeys.length) {
+    return { ok: false, reason: `unrecognised top-level key(s) not covered by the signature: ${unknownKeys.join(', ')}` };
+  }
+  const sig = bundle.signature;
+  if (!sig?.value) return { ok: false, reason: 'bundle is unsigned' };
+  if (sig.algorithm !== 'ed25519') return { ok: false, reason: `unsupported algorithm: ${sig.algorithm}` };
+  if (!publicKeyPem) return { ok: false, reason: 'no public key supplied' };
+  let sigOk = false;
+  try {
+    sigOk = crypto.verify(null, canonicalPolicyBytes(bundle), publicKeyPem, Buffer.from(sig.value, 'base64'));
+  } catch (e) {
+    return { ok: false, reason: `verification error: ${e.message}` };
+  }
+  if (!sigOk) return { ok: false, reason: 'signature does not match the bundle contents — it was modified after signing' };
+  if (bundle.expiresAt) {
+    const exp = Date.parse(bundle.expiresAt);
+    if (!Number.isFinite(exp)) return { ok: false, reason: `expiresAt is not a valid date: ${bundle.expiresAt}` };
+    if (exp < now) return { ok: false, reason: `policy expired on ${bundle.expiresAt}` };
+  }
+  return { ok: true, reason: null };
+}
+
+/**
+ * Merge verified bundles into one effective policy, in inheritance order
+ * (organization -> repository -> environment; most specific wins per key).
+ * A tampered or expired bundle is EXCLUDED from the merge (rejected, not
+ * silently dropped — its scope and reason are reported so a rejection is
+ * visible, not just absent). `provenance[key]` names which scope's bundle
+ * last set that key — the "effective policy is explainable" half of the
+ * acceptance criterion.
+ *
+ * @param {Array<{scope: string, bundle: object}>} entries
+ * @param {string} publicKeyPem
+ * @returns {{effective: object, provenance: Record<string,string>,
+ *   accepted: string[], rejected: Array<{scope:string, reason:string}>}}
+ */
+export function resolveEffectivePolicy(entries, publicKeyPem, { now = Date.now() } = {}) {
+  const byScope = new Map();
+  for (const e of entries || []) {
+    if (e && SCOPES.includes(e.scope)) byScope.set(e.scope, e.bundle);
+  }
+  const effective = {};
+  const provenance = {};
+  const accepted = [];
+  const rejected = [];
+  for (const scope of INHERITANCE_ORDER) {
+    const bundle = byScope.get(scope);
+    if (!bundle) continue;
+    const v = verifyPolicyBundle(bundle, publicKeyPem, { now });
+    if (!v.ok) { rejected.push({ scope, reason: v.reason }); continue; }
+    accepted.push(scope);
+    for (const [k, val] of Object.entries(bundle.policy)) {
+      effective[k] = val;
+      provenance[k] = scope;
+    }
+  }
+  return { effective, provenance, accepted, rejected };
+}
+
+/**
+ * Load whichever policy bundle files exist under
+ * `.agentic-security/policy-bundles/{organization,repository,environment}.json`.
+ * Degrades gracefully — a missing directory or missing/malformed individual
+ * file is simply absent from the result, never thrown. Read-first-in-try/
+ * catch throughout (no existsSync-then-readFileSync — D-0012/D-0022).
+ */
+export function loadPolicyBundles(scanRoot) {
+  if (!scanRoot) return [];
+  const entries = [];
+  for (const scope of SCOPES) {
+    let fp;
+    try { fp = statePath(scanRoot, 'policy-bundles', `${scope}.json`); } catch { continue; }
+    let raw;
+    try { raw = fs.readFileSync(fp, 'utf8'); } catch { continue; }
+    try {
+      const bundle = JSON.parse(raw);
+      if (bundle && typeof bundle === 'object') entries.push({ scope, bundle });
+    } catch { /* malformed — skip, do not throw */ }
+  }
+  return entries;
+}
+
+/**
+ * Read the operator-supplied public key an org distributes alongside its
+ * bundles, from `.agentic-security/policy-bundle-public-key.pem`. Returns
+ * null (not a throw) if absent or unreadable — resolution then rejects
+ * every bundle for lack of a key, same as any other "no public key
+ * supplied" case in verifyPolicyBundle.
+ */
+export function loadPolicyPublicKey(scanRoot) {
+  if (!scanRoot) return null;
+  let fp;
+  try { fp = statePath(scanRoot, 'policy-bundle-public-key.pem'); } catch { return null; }
+  try { return fs.readFileSync(fp, 'utf8'); } catch { return null; }
+}
+
+/**
+ * FR-1006 ("policy drift"): does this repository's LOCALLY resolved effective
+ * policy diverge from what the organization-scope bundle alone specifies —
+ * and is anything the repo is relying on actually being rejected (tampered
+ * or expired) rather than enforced? Both are GOVERNANCE gaps, distinct from
+ * risk findings, which is the exact distinction FR-1006's acceptance
+ * criterion asks fleet output to make.
+ *
+ * No bundles configured at all is a no-op (`null`), matching this session's
+ * established convention: drift can only be reported relative to a
+ * baseline, and a repo with no organization bundle has no baseline to drift
+ * from.
+ *
+ * @returns {{accepted: string[], rejected: Array<{scope,reason}>,
+ *   overrides: Array<{key, organizationValue, effectiveValue, overriddenBy}>}
+ *   | null}
+ */
+export function computePolicyDrift(scanRoot) {
+  const entries = loadPolicyBundles(scanRoot);
+  if (!entries.length) return null;
+  const publicKeyPem = loadPolicyPublicKey(scanRoot);
+  const { effective, provenance, accepted, rejected } = resolveEffectivePolicy(entries, publicKeyPem);
+
+  const overrides = [];
+  const orgEntry = entries.find(e => e.scope === 'organization');
+  if (orgEntry && accepted.includes('organization')) {
+    for (const [key, organizationValue] of Object.entries(orgEntry.bundle.policy || {})) {
+      const overriddenBy = provenance[key];
+      if (overriddenBy && overriddenBy !== 'organization' && !_deepEqual(effective[key], organizationValue)) {
+        overrides.push({ key, organizationValue, effectiveValue: effective[key], overriddenBy });
+      }
+    }
+  }
+  return { accepted, rejected, overrides };
+}
+
+function _deepEqual(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}

package/src/posture/pre-incident-archaeology.js

@@ -12,8 +12,10 @@
 //     introducingCommit: { sha, author, ts, message } | null,
 //   }
 //
-// We invoke `git log` and `git show` via the shell. If the project is not a
-// git repository (no `.git` at root), we return `{ available: false }`.
+// We invoke `git log` and `git show` via `execFileSync` (an argv array, NOT
+// a shell) against `root` — the SCANNED project's repository, not this
+// project's own trusted checkout. If the project is not a git repository
+// (no `.git` at root), we return `{ available: false }`.
 //
 // This is intentionally light: we do not re-run the SAST detector on every
 // historical revision. We use a simple substring-presence probe — does the
@@ -21,10 +23,30 @@
 // Sufficient for the common case and dramatically cheaper than full
 // re-scanning. Customers who want forensic-grade archaeology can re-run the
 // scanner against `git checkout`-ed historical revisions.
+//
+// Hardened + de-shelled per FR-PROV-024 / the second Finding Provenance PRD
+// audit sweep (found missing here by a follow-up review that grepped for
+// `child_process` usage beyond just `execFileSync('git'` call sites). Before
+// this fix, `gitShow` built a SHELL command string
+// (`` `git show ${sha}:"${file}"` ``) from `file`, which is a finding's
+// repo-relative path — attacker-controlled in a hostile repo. Double quotes
+// in `sh` do NOT suppress `$(...)`/backticks, so a repo containing a file
+// literally named `a$(cmd).js` would execute `cmd` via command substitution
+// the moment this ran. Switching to `execFileSync` with an argv array
+// removes the shell entirely — there is no interpreter left to interpret
+// `$(...)`, so this is not "quote it better," it closes the injection class
+// outright. `sha` here always originates from THIS module's own
+// `gitLogForFile` (`%H`, real git-produced hex), but is still validated
+// against the same SHA_RE every other resolver in this codebase uses, on
+// the same "never trust, always validate" convention as
+// provenance/git-evidence.js.
 
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { hardenGitArgs, hardenGitEnv } from '../util/git-hardening.js';
+
+const SHA_RE = /^[0-9a-f]{4,40}$/i;
 
 function isGitRepo(root) {
   try {
@@ -34,9 +56,10 @@ function isGitRepo(root) {
 
 function gitLogForFile(root, file, limit = 50) {
   try {
-    const out = execSync(
-      `git log --pretty=format:%H%x1f%an%x1f%aI%x1f%s --max-count=${limit} -- "${file}"`,
-      { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }
+    const out = execFileSync(
+      'git',
+      hardenGitArgs(['log', '--pretty=format:%H%x1f%an%x1f%aI%x1f%s', `--max-count=${limit}`, '--', file]),
+      { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: hardenGitEnv() },
     );
     return out.split(/\n/).filter(Boolean).map(line => {
       const [sha, author, ts, message] = line.split('\x1f');
@@ -46,8 +69,17 @@ function gitLogForFile(root, file, limit = 50) {
 }
 
 function gitShow(root, sha, file) {
+  if (typeof sha !== 'string' || !SHA_RE.test(sha)) return null;
   try {
-    return execSync(`git show ${sha}:"${file}"`, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    // `./` makes git resolve `file` relative to cwd (root) — same convention
+    // as provenance/git-evidence.js's getBlobAtCommit, and load-bearing for
+    // the same reason: it also keeps a `file` that happens to start with
+    // `-` from being parsed as a flag once concatenated onto `sha:`.
+    // `--no-textconv`: this is the blob-cat form of `show` (`<sha>:<path>`,
+    // not a diff) — VERIFIED not reachable via a hostile textconv driver in
+    // current git (same as git-evidence.js's getBlobAtCommit), kept for
+    // defense-in-depth/uniformity.
+    return execFileSync('git', hardenGitArgs(['show', '--no-textconv', `${sha}:./${file}`]), { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: hardenGitEnv() });
   } catch { return null; }
 }
 

package/src/posture/privacy-framework.js

@@ -36,6 +36,8 @@
 
 import { loadFramework, evaluateFramework } from './auditor-walkthrough.js';
 import { statePath, safeWriteState } from './state-dir.js';
+import { EVIDENCE_GRADE_DISCLAIMER_SHORT } from './evidence-grade-wording.js';
+import { PROVENANCE_COMPLIANCE_DISCLAIMER } from './provenance/schema.js';
 
 export const PRIVACY_FRAMEWORK_ID = 'nist-privacy-1-1';
 
@@ -118,6 +120,24 @@ function severityFor(controlId) {
  * Returns `{ frameworkId, controls[], summary, findings[] }`. Never throws:
  * posture modules degrade to a null result rather than failing a scan.
  */
+// FR-405 (assurance-hardening PRD): controls whose ENTIRE mapping depends on
+// privacy-taint's signal — a "clean" (present) result from a NON-IR-backed
+// run (deep mode off, the default path) is not real evidence for these
+// specifically, even when the scan otherwise examined real files and is
+// `assessable` for every other control. Deliberately conservative: a control
+// with an ADDITIONAL, independent mapping (e.g. CT.DP-P1's `family:data-
+// exposure` alongside `family:pii-exposure`) is left alone, because that
+// other signal may still be real and this module cannot attribute which
+// specific mapping produced a "present" verdict. Confirmed by direct
+// execution against this exact framework file that CT.DP-P4/CT.DP-P5 (both
+// codeTestable:'yes', both mapped ONLY to `module:privacy-taint`) currently
+// read `satisfied` from a run with zero real IR-backed analysis — see
+// decisions.md for the reproduction.
+function _isPurelyPrivacyTaintDependent(control) {
+  const mapsTo = Array.isArray(control?.mapsTo) ? control.mapsTo : [];
+  return mapsTo.length > 0 && mapsTo.every(m => m === 'module:privacy-taint' || m === 'family:pii-exposure');
+}
+
 export function assessPrivacyFramework(scanRoot, scan, opts = {}) {
   const fw = loadFramework(scanRoot, PRIVACY_FRAMEWORK_ID);
   if (!fw) return null;
@@ -131,6 +151,9 @@ export function assessPrivacyFramework(scanRoot, scan, opts = {}) {
   const assessable = filesScanned > 0
     || (Array.isArray(scan?.findings) && scan.findings.length > 0)
     || (Array.isArray(scan?.components) && scan.components.length > 0);
+  // `null` (never ran) and `false` (ran but degraded) are both "not real
+  // IR-backed evidence" for the gate below; only `true` clears it.
+  const privacyIrBacked = scan?.privacyIrBacked === true;
 
   const controls = [];
   const findings = [];
@@ -138,7 +161,9 @@ export function assessPrivacyFramework(scanRoot, scan, opts = {}) {
 
   for (const r of evaluation) {
     const c = r.control || {};
-    const bucket = bucketOf(r, { assessable });
+    const privacyTaintGated = !privacyIrBacked && _isPurelyPrivacyTaintDependent(c);
+    const controlAssessable = assessable && !privacyTaintGated;
+    const bucket = bucketOf(r, { assessable: controlAssessable });
     summary[bucket] += 1;
     summary.total += 1;
 
@@ -153,9 +178,11 @@ export function assessPrivacyFramework(scanRoot, scan, opts = {}) {
     };
     if (bucket === 'engine-gap') {
       // Named, not counted as a pass. See the header.
-      row.disclosure = (Array.isArray(c.mapsTo) && c.mapsTo.length && !assessable)
-        ? 'This control is mapped, but the scan examined no files — a clean signal from a run that read nothing is not evidence. NOT assessed.'
-        : `NIST rates this control code-testable (${row.codeTestable}), but this engine has no signal for it. It was NOT assessed.`;
+      row.disclosure = privacyTaintGated
+        ? 'This control depends entirely on privacy-taint\'s signal, which ran without a real IR this scan (deep mode off, or an unsupported language) — a "no findings" result in that mode is not real evidence. NOT assessed.'
+        : (Array.isArray(c.mapsTo) && c.mapsTo.length && !assessable)
+          ? 'This control is mapped, but the scan examined no files — a clean signal from a run that read nothing is not evidence. NOT assessed.'
+          : `NIST rates this control code-testable (${row.codeTestable}), but this engine has no signal for it. It was NOT assessed.`;
     }
     if (bucket === 'manual') {
       row.disclosure = 'NIST rates this control not code-testable — it is a governance, policy, or process control and is outside any scanner\'s reach.';
@@ -183,6 +210,19 @@ export function assessPrivacyFramework(scanRoot, scan, opts = {}) {
       parser: 'COMPLIANCE',
       family: 'privacy-compliance',
       complianceControl: { framework: PRIVACY_FRAMEWORK_ID, id: c.id, codeTestable: c.codeTestable || 'no' },
+      controlRefs: r.controlRefs || [],
+      // PRD Section 8 REQUIRED DISCLAIMER. `derivedProvenance` carries an
+      // origin commit, author and confidence onto a COMPLIANCE claim, and
+      // `compliance --privacy --format json` prints this object straight to
+      // stdout -- a second human-facing surface for the same data the auditor
+      // walkthrough disclaims inline. Found by a review of the walkthrough
+      // fix, which had asserted renderWalkthrough was the only consumer. The
+      // disclaimer travels ON the record rather than beside it, because a
+      // JSON consumer can slice a single finding out of the array and the
+      // caveat has to survive that.
+      derivedProvenance: r.derivedProvenance
+        ? { ...r.derivedProvenance, disclaimer: PROVENANCE_COMPLIANCE_DISCLAIMER }
+        : null,
     });
   }
 
@@ -228,8 +268,9 @@ function renderPrivacyMarkdown(result) {
   L.push(`| Satisfied | ${result.summary.satisfied} | Mapped, and the signal is clean |`);
   L.push('');
   L.push('> A control in *Not assessed* or *Manual* is not evidence of compliance.');
-  L.push('> This document organizes scanner evidence; it does not certify anything.');
-  L.push('> A licensed assessor is responsible for the attestation.');
+  // FR-507: sourced from evidence-grade-wording.js so this artifact stays in
+  // sync with every other compliance-adjacent disclaimer in the codebase.
+  L.push(`> ${EVIDENCE_GRADE_DISCLAIMER_SHORT}`);
   L.push('');
   for (const bucket of BUCKETS) {
     const rows = result.controls.filter(c => c.bucket === bucket);

package/src/posture/production-feedback.js

@@ -0,0 +1,179 @@
+// FR-907 (assurance-hardening PRD): "Add longitudinal production feedback
+// measurement | Metrics separate user suppression, accepted risk, invalid
+// finding, fixed finding, and verification outcome."
+//
+// Read-only aggregation over 5 ALREADY-BUILT, separate mechanisms — this
+// module invents no new storage of its own, only a unified view:
+//
+//   user-suppression     -> triage-memory.jsonl (decision:'wont-fix'),
+//                            accepted.json (vibecoder soft-accept, dated),
+//                            suppressions.yml (pro exception, undated)
+//   invalid-finding       -> triage-memory.jsonl (decision:'false-positive')
+//   accepted-risk         -> sca-policy.yml's accept-risk[] (undated snapshot
+//                            — the policy file has no per-entry creation
+//                            timestamp, only an optional future `expires`)
+//   fixed-finding          -> fix-history/log.json (dated via `appliedAt`,
+//                            status-tagged: applied/pending/reverted/failed)
+//   verification-outcome  -> fix-metrics.jsonl (dated via `at`, ok-tagged)
+//
+// "Longitudinal" means: every event that HAS a real timestamp is usable in
+// a time-bucketed trend; every event that does NOT (accept-risk entries,
+// pro suppressions — neither schema records when the entry was added) is
+// still counted in its category total but reported separately as
+// "undated" rather than silently smeared across the time window or
+// silently dropped. Same disclosed-gap discipline this codebase already
+// uses elsewhere (privacy-framework.js's engine-gap bucket, accuracy-
+// scorecard.js's excluded-from-denominator entries) — a number without
+// its caveat is not a measurement.
+//
+// Never throws (posture convention): each of the 5 reads is wrapped
+// independently, so a missing or malformed source degrades only that ONE
+// category to empty, never blocks the other four. Every underlying reader
+// (loadSoftAccepted, loadProSuppressions, loadMemory, loadScaPolicy,
+// readLog, loadFixAttempts) already degrades gracefully on its own; the
+// wrapping here is defense in depth against a reader whose contract
+// changes later, not a claim that today's readers can throw.
+
+import { loadSoftAccepted, loadProSuppressions } from './suppressions.js';
+import { loadMemory } from './triage-memory.js';
+import { loadScaPolicy } from './sca-policy.js';
+import { readLog } from './fix-history.js';
+import { loadFixAttempts } from './fix-metrics.js';
+
+const MS_PER_DAY = 86400000;
+
+// The 5 categories named verbatim in FR-907's own acceptance criterion.
+export const CATEGORIES = Object.freeze([
+  'user-suppression', 'accepted-risk', 'invalid-finding', 'fixed-finding', 'verification-outcome',
+]);
+
+function _safe(fn) {
+  try { return fn(); } catch { return []; }
+}
+
+/**
+ * One unified event per underlying record, tagged with which of the 5
+ * PRD-named categories it belongs to. `at` is an ISO timestamp or null
+ * when the source schema has no per-entry creation date. `raw` keeps the
+ * original record for drill-down — never re-derived from the unified
+ * shape, so nothing is lost in translation.
+ */
+export function collectFeedbackEvents(scanRoot) {
+  const events = [];
+
+  for (const e of _safe(() => loadSoftAccepted(scanRoot))) {
+    events.push({
+      category: 'user-suppression', source: 'suppressions.js:accepted.json',
+      at: e.accepted_at || null, findingId: e.id || null, file: e.file || null,
+      line: e.line ?? null, outcome: 'soft-accepted', raw: e,
+    });
+  }
+  for (const e of _safe(() => loadProSuppressions(scanRoot))) {
+    events.push({
+      category: 'user-suppression', source: 'suppressions.js:suppressions.yml',
+      at: null, findingId: e.finding_id || null, file: e.file || null,
+      line: null, outcome: 'pro-exception', raw: e,
+    });
+  }
+  for (const e of _safe(() => loadMemory(scanRoot))) {
+    if (e.decision === 'wont-fix') {
+      events.push({
+        category: 'user-suppression', source: 'triage-memory.js',
+        at: e.at || null, findingId: e.id || null, file: e.file || null,
+        line: e.line ?? null, outcome: 'wont-fix', raw: e,
+      });
+    } else if (e.decision === 'false-positive') {
+      events.push({
+        category: 'invalid-finding', source: 'triage-memory.js',
+        at: e.at || null, findingId: e.id || null, file: e.file || null,
+        line: e.line ?? null, outcome: 'false-positive', raw: e,
+      });
+    }
+  }
+  const scaPolicy = _safe(() => loadScaPolicy(scanRoot));
+  const acceptRisk = scaPolicy && Array.isArray(scaPolicy.acceptRisk) ? scaPolicy.acceptRisk : [];
+  for (const e of acceptRisk) {
+    events.push({
+      category: 'accepted-risk', source: 'sca-policy.js',
+      at: null, findingId: e.cve || e.package || null, file: null,
+      line: null, outcome: 'accept-risk', raw: e,
+    });
+  }
+  for (const e of _safe(() => readLog(scanRoot))) {
+    events.push({
+      category: 'fixed-finding', source: 'fix-history.js',
+      at: e.appliedAt || null, findingId: e.findingId || e.stableId || null,
+      file: e.file || null, line: null, outcome: e.status || 'unknown', raw: e,
+    });
+  }
+  for (const e of _safe(() => loadFixAttempts(scanRoot))) {
+    events.push({
+      category: 'verification-outcome', source: 'fix-metrics.js',
+      at: e.at || null, findingId: e.stableId || null, file: null,
+      line: null, outcome: e.ok ? 'verified' : 'not-verified', raw: e,
+    });
+  }
+
+  return events;
+}
+
+/**
+ * Bucket events by day within a rolling `sinceDays`-day window — the same
+ * cutoff-window shape as posture/triage.js's own trend(). An event with no
+ * timestamp (or an unparseable one) cannot be placed on a time axis: it is
+ * counted once in `undated` per category rather than silently dropped or
+ * silently smeared into the window.
+ */
+export function summarizeFeedbackTrend(events, { sinceDays = 30, now = Date.now() } = {}) {
+  const cutoff = now - sinceDays * MS_PER_DAY;
+  const byCategory = {};
+  for (const cat of CATEGORIES) byCategory[cat] = { total: 0, inWindow: 0, undated: 0 };
+
+  const dayBuckets = new Map(); // 'YYYY-MM-DD' -> { category: count }
+  for (const ev of Array.isArray(events) ? events : []) {
+    if (!ev || !CATEGORIES.includes(ev.category)) continue;
+    byCategory[ev.category].total++;
+    const t = ev.at ? Date.parse(ev.at) : NaN;
+    if (!Number.isFinite(t)) { byCategory[ev.category].undated++; continue; }
+    if (t < cutoff) continue;
+    byCategory[ev.category].inWindow++;
+    const dayKey = new Date(t).toISOString().slice(0, 10);
+    if (!dayBuckets.has(dayKey)) dayBuckets.set(dayKey, {});
+    const bucket = dayBuckets.get(dayKey);
+    bucket[ev.category] = (bucket[ev.category] || 0) + 1;
+  }
+
+  const series = [...dayBuckets.entries()]
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([day, counts]) => ({ day, counts }));
+  return { sinceDays, byCategory, series };
+}
+
+/**
+ * Convenience wrapper: collect + summarize in one call — same pattern as
+ * fix-metrics.js's fixDurationReport(scanRoot).
+ */
+export function productionFeedbackReport(scanRoot, opts) {
+  const events = collectFeedbackEvents(scanRoot);
+  return { events, ...summarizeFeedbackTrend(events, opts) };
+}
+
+/**
+ * One block of human-readable summary, or null when nothing was measured
+ * at all — same "null when nothing measured" contract as
+ * renderFixDurationSummary, so a caller can skip the section entirely
+ * rather than print an empty header.
+ */
+export function renderProductionFeedbackSummary(report) {
+  if (!report || !Array.isArray(report.events) || !report.events.length) return null;
+  const lines = [`Production feedback (last ${report.sinceDays}d):`];
+  for (const cat of CATEGORIES) {
+    const c = report.byCategory[cat];
+    if (!c || c.total === 0) continue;
+    const undatedNote = c.undated ? `, ${c.undated} undated` : '';
+    lines.push(`  ${cat}: ${c.inWindow} in window / ${c.total} total${undatedNote}`);
+  }
+  return lines.length > 1 ? lines.join('\n') : null;
+}
+
+export const _internals = { MS_PER_DAY };