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

package/bin/agentic-security.js

@@ -8,6 +8,7 @@ import { createRequire } from 'node:module';
 const __require = createRequire(import.meta.url);
 const PKG_VERSION = __require('../package.json').version;
 import { signLastScan as _signLastScan, verifyLastScan as _verifyLastScanShared } from '../src/posture/integrity.js';
+import { isProvenanceHealthy, sanitizeForTerminal } from '../src/posture/provenance/schema.js';
 import { runScan } from '../src/runScan.js';
 
 // Every command is dispatched as `process.exit(await cmdX(args))`, and
@@ -61,14 +62,16 @@ import { listPacks, loadPack, applyPacks } from '../src/posture/rule-packs.js';
 import { writeLockfile, verifyLockfile, makeDeterministic, isDeterministic } from '../src/posture/deterministic.js';
 import { enrichWithEPSS } from '../src/posture/epss.js';
 import { enrichWithBlastRadius } from '../src/posture/blast-radius.js';
-import { applyCustomRules, runRuleTests, loadCustomRules } from '../src/posture/custom-rules.js';
-import { applyFix, undoLast, undoAll, listHistory, preview as previewDiff, compactLog } from '../src/posture/fix-history.js';
+import { applyCustomRules, runRuleTests, loadCustomRules, customRulesFreshness } from '../src/posture/custom-rules.js';
+import { undoLast, undoAll, listHistory, preview as previewDiff, compactLog } from '../src/posture/fix-history.js';
+import { applyVerifiedFix, confinePath } from '../src/fix/apply-fix-service.js';
 import { syncTickets } from '../src/integrations/tickets.js';
 import { decide as decideNextAction, explain as explainDecision } from '../src/posture/router.js';
 import * as triage from '../src/posture/triage.js';
 import { buildSlackDigest, buildDiscordDigest, postWebhook, buildJiraIssue, buildPrComment, buildSiemEvent, loadIntegrationConfig } from '../src/integrations/index.js';
 
 import { stateDir, statePath } from '../src/posture/state-dir.js';
+import { listGeneratedArtifacts } from '../src/posture/artifact-registry.js';
 // last-scan.json integrity helpers — implementation in posture/integrity.js
 // so the MCP server tools can share verification.
 function _verifyLastScan(body, sigFile) {
@@ -103,6 +106,17 @@ Commands:
   validator-cache stats|gc     Inspect / prune .agentic-security/llm-cache/ (use --older-than <days> --dry-run)
   verify [--finding <id>]      Re-run the verifier loop on last-scan findings (use --live --target <url> to execute PoCs)
   reset [--yes] [--keep ...]   Right-to-delete: wipe accumulated learned state under .agentic-security/ (preserves operator-authored config)
+                               --expired    only remove artifacts past their retention-class TTL
+                               Every run writes a deletion-report.json proving what was planned/deleted/preserved/failed.
+  export --out <dir>           Copy every present .agentic-security/ artifact to <dir> with a manifest (export-manifest.json,
+                               unsigned) proving what was exported and what failed — for migration or legal-preservation purposes.
+  legal-hold add --artifact <name> --owner <id> --reason <text> [--expires <date>]
+                               Exempt a registered artifact from retention TTL and reset (both --expired and plain)
+  legal-hold remove --artifact <name>   Lift a hold
+  legal-hold list [--all]      List active holds (--all also shows past holds whose expires_at has passed)
+  calibration-feedback record --finding-id <id> --outcome accepted-risk|realized-incident [--note <text>]
+                               Opt-in: report a real-world outcome for a past finding, for calibration validation
+  calibration-report [--format cli|json]   Aggregated, privacy-preserving calibration report from recorded feedback
   rule-synth [--dry-run]       Auto-synthesise suppression rules from repeated FP verdicts (proposes — does not activate)
   compliance [--privacy]       Assess the last scan against NIST Privacy Framework 1.1
                                --list                 show bundled + BYO frameworks
@@ -136,6 +150,9 @@ Options:
   --fail-on-new                (ci) block ONLY on findings this PR introduced vs
                                the baseline ref — never the pre-existing backlog
   --policy <file.rego>         ci-mode policy-as-code gate; deny[] rules fail the build (FR-SDLC-9)
+  --assurance advisory|standard|strict  (ci) incomplete-analysis behavior (default: standard).
+                               strict fails the build when any analyzer failed, timed out,
+                               or was silently skipped by policy — independent of --fail-on (FR-204)
   --columns standard|mitre|capec|owasp  Pro-mode column set (default: standard)
   --confidence <0..1>          Override per-profile confidence threshold
   --firehose                   Show ALL findings (ignore confidence threshold)
@@ -169,9 +186,20 @@ Options:
   --no-epss                    Skip EPSS exploit-prediction enrichment (default: enabled)
   --no-blast-radius            Skip blast-radius / cost framing (default: enabled)
   --verbose                    Include fix bodies + taxonomy in CLI output
+                               (with --firehose, also prints each finding's git-origin provenance)
   --output <file>              Write report to file instead of stdout
   --machine-output             Always write .agentic-security/findings.{sarif,json,csv}
 
+Finding provenance (which commit introduced each finding):
+  --provenance <standard|deep> Resolution depth (default: standard; deep explores non-linear ancestry — merges, reverts, cherry-picks)
+  --no-provenance              Skip git-history provenance entirely (findings report not_available)
+  --provenance-since <ref>     Do not walk history earlier than this git ref/commit
+  --provenance-timeout <ms>    Whole-scan provenance budget in MILLISECONDS (default 60000)
+  --include-author-email       Keep commit author emails in output (redacted by default)
+  --pseudonymize-authors       Replace commit author names with a stable Contributor-XXXXXXXX id
+  --require-provenance         Report unresolved provenance as a scan-health condition
+                               (downgrades scanHealth.status to 'partial'; never changes the exit code)
+
 Exit codes:
   0 = clean   1 = low/medium   2 = high   3 = critical   4 = error`;
 
@@ -377,6 +405,112 @@ function parseArgs(argv) {
   return args;
 }
 
+// The only values `--provenance` accepts. Used both to validate an inline
+// `--provenance=<mode>` and to decide whether a following bare token is this
+// flag's value at all — see the comment inside the parser.
+const PROVENANCE_MODES = new Set(['standard', 'deep']);
+
+// Finding Provenance (M0/M1) — CLI flags that set the env vars engine.js
+// (Task 15) and report/index.js (Task 16) already read:
+// AGENTIC_SECURITY_NO_PROVENANCE, AGENTIC_SECURITY_PROVENANCE_MODE,
+// AGENTIC_SECURITY_PROVENANCE_SINCE, AGENTIC_SECURITY_PROVENANCE_TIMEOUT_MS,
+// AGENTIC_SECURITY_INCLUDE_AUTHOR_EMAIL,
+// AGENTIC_SECURITY_PSEUDONYMIZE_AUTHORS. `requireProvenance` is consumed
+// directly by cmdScan (post-scan scanHealth augmentation), not via an env var.
+// Kept as a pure function (argv in, plain object out) so it's unit-testable
+// without invoking the CLI dispatch or touching process.env.
+export function parseProvenanceFlags(argv) {
+  // OPT-IN, not opt-out (0.145.0). Provenance was on by default through M0-M4,
+  // and the release gate caught what that costs: time-to-first-finding on a
+  // 207-file tree went 4.5s -> 45s, a 7.6x regression on the ONE metric
+  // bench/ttff/runner.mjs's own header calls the binding constraint for this
+  // product's vibecoder ICP ("how long until the FIRST useful result, not
+  // aggregate F1"). Resolving history for every finding is simply not what a
+  // first-time user is waiting for. It stays one flag away, and CI/compliance
+  // callers that DO want it pass `--provenance` explicitly.
+  //
+  // `disabled` therefore starts true, and any provenance-shaped flag flips it
+  // off — asking for `--provenance-since` or `--require-provenance` is asking
+  // for provenance, and making the user also pass a bare `--provenance`
+  // alongside it would be a papercut with no upside.
+  const result = { mode: 'standard', since: null, timeoutMs: undefined, includeEmail: false, pseudonymize: false, requireProvenance: false, disabled: true, warning: null };
+  const warnings = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (typeof a !== 'string' || !a.startsWith('--')) continue;
+    // BOTH `--flag value` and `--flag=value`, because parseArgs() above accepts
+    // both for every other flag in this CLI and an operator has no way to know
+    // this one parser is different. Exact-string matching silently ignored
+    // `--provenance=deep` / `--provenance-since=v1.0.0` /
+    // `--provenance-timeout=30000` — no warning, defaults quietly used.
+    //
+    // Split on the FIRST `=` and keep the whole remainder, rather than
+    // parseArgs's `split('=', 2)` which drops everything after a second `=`.
+    // A git ref (`--provenance-since=refs/tags/v1=rc1`) is a legal value and
+    // truncating it would be a worse failure than the one being fixed.
+    const eq = a.indexOf('=');
+    const key = eq === -1 ? a : a.slice(0, eq);
+    const inline = eq === -1 ? undefined : a.slice(eq + 1);
+    // `--flag value` consumes the NEXT argv entry only when there is no inline
+    // value; a value that itself starts with `--` is another flag, not this
+    // one's argument.
+    const takeValue = () => {
+      if (inline !== undefined) return inline;
+      const next = argv[i + 1];
+      if (next !== undefined && !String(next).startsWith('--')) { i++; return next; }
+      return undefined;
+    };
+
+    if (key === '--no-provenance') result.disabled = true;
+    else if (key === '--provenance') {
+      result.disabled = false;
+      // The SPACE form only claims the next token when it actually names a
+      // mode. `--provenance` is legal on its own (provenance is on by default;
+      // the flag is how you say "standard, explicitly"), and this CLI's target
+      // is nearly always a positional — `scan --provenance ./src` must scan
+      // `./src`, not report `unrecognised mode './src'`. parseArgs() does its
+      // own positional collection over the same argv, so consuming here never
+      // steals the path from it, but the warning would still be a lie.
+      //
+      // The INLINE form has no such ambiguity: `--provenance=x` can only ever
+      // be a mode, so an unknown one is a typo worth naming.
+      const v = inline !== undefined
+        ? inline
+        : (PROVENANCE_MODES.has(String(argv[i + 1])) ? argv[++i] : undefined);
+      if (v === 'deep' || v === 'standard' || v === undefined) {
+        result.mode = v || 'standard';
+      } else {
+        warnings.push(`unrecognised --provenance mode '${v}' (expected standard|deep), running standard`);
+      }
+    } else if (key === '--provenance-since') { result.since = takeValue() ?? null; result.disabled = false; }
+    else if (key === '--provenance-timeout') {
+      // MILLISECONDS, and validated as such. `parseInt` alone turned
+      // `--provenance-timeout 30s` into 30 — a 30-MILLISECOND budget that
+      // expires before the first `git blame` returns, so every finding came
+      // back `budget_exhausted` and nothing said why. A missing value produced
+      // NaN, which `if (_provFlags.timeoutMs)` then discarded silently. Both
+      // now warn and fall back to the engine default rather than inventing a
+      // budget the operator did not ask for. The unit is fixed by the env var
+      // this flag feeds, AGENTIC_SECURITY_PROVENANCE_TIMEOUT_MS.
+      const raw = takeValue();
+      if (raw === undefined) {
+        warnings.push('--provenance-timeout requires a value in milliseconds; using the default budget');
+      } else if (!/^\d+$/.test(String(raw).trim()) || parseInt(raw, 10) <= 0) {
+        warnings.push(`--provenance-timeout expects a positive integer number of MILLISECONDS, got '${raw}'; using the default budget`);
+      } else {
+        result.timeoutMs = parseInt(raw, 10);
+        result.disabled = false;
+      }
+    }
+    else if (key === '--include-author-email') { result.includeEmail = true; result.disabled = false; }
+    else if (key === '--pseudonymize-authors') { result.pseudonymize = true; result.disabled = false; }
+    else if (key === '--require-provenance') { result.requireProvenance = true; result.disabled = false; }
+  }
+  // One field, so a caller that prints `warning` cannot drop the second one.
+  result.warning = warnings.length ? warnings.join('; ') : null;
+  return result;
+}
+
 async function cmdScan(args) {
   // NON_MUTATING_SCAN_PRD S1 — a scan is an observation; --no-state makes it one.
   if (args.flags['no-state']) {
@@ -472,12 +606,67 @@ async function cmdScan(args) {
     process.stderr.write(`[pr-mode] scanning files changed since: ${changedSince}\n`);
   }
 
+  // Finding Provenance (M0/M1) — translate --provenance/--no-provenance/etc.
+  // into the env vars engine.js already reads. Must run before runScan()
+  // below, same as the --deep/--no-deep wiring above.
+  const _provFlags = parseProvenanceFlags(process.argv.slice(2));
+  if (_provFlags.warning) console.error(`Warning: ${_provFlags.warning}`);
+  if (_provFlags.disabled) process.env.AGENTIC_SECURITY_NO_PROVENANCE = '1';
+  process.env.AGENTIC_SECURITY_PROVENANCE_MODE = _provFlags.mode;
+  if (_provFlags.since) process.env.AGENTIC_SECURITY_PROVENANCE_SINCE = _provFlags.since;
+  if (_provFlags.timeoutMs) process.env.AGENTIC_SECURITY_PROVENANCE_TIMEOUT_MS = String(_provFlags.timeoutMs);
+  if (_provFlags.includeEmail) process.env.AGENTIC_SECURITY_INCLUDE_AUTHOR_EMAIL = '1';
+  if (_provFlags.pseudonymize) process.env.AGENTIC_SECURITY_PSEUDONYMIZE_AUTHORS = '1';
+
   const { scan, meta } = await runScan(target, {
     changedSince,
     onProgress: (p) => {
       if (process.stderr.isTTY) process.stderr.write(`\r[${p.phase}] ${p.current}/${p.total} ${p.file}     `);
     },
   });
+  // --require-provenance: flag (never fail) any finding whose provenance
+  // isn't resolved, via scanHealth — deliberately independent of the
+  // severity-based exit code computed by exitCodeFor() at the end of this
+  // function. 'uncommitted' is a legitimate terminal status (the finding is
+  // in a file with no git history yet), not an incomplete one.
+  if (_provFlags.requireProvenance) {
+    // ALL FOUR channels (scanner/CLAUDE.md: findings / secrets / supplyChain /
+    // logicVulns). Checking only `scan.findings` made the flag report a clean
+    // bill of provenance health for a scan whose SCA and secrets findings had
+    // none — and report/index.js's normalizeFindings ships all four to the
+    // user as findings, so "every finding" has to mean all four here too.
+    const incomplete = [];
+    for (const [channel, bucket] of [
+      ['findings', scan.findings], ['secrets', scan.secrets],
+      ['supplyChain', scan.supplyChain], ['logicVulns', scan.logicVulns],
+    ]) {
+      for (const f of (bucket || [])) {
+        if (!f || typeof f !== 'object') continue;
+        if (isProvenanceHealthy(f.findingProvenance)) continue;
+        incomplete.push(f.id || f.stableId || `${channel}:${f.name || f.file || f.type || 'entry'}`);
+      }
+    }
+    if (incomplete.length > 0) {
+      // Written the way EVERY other scan-health signal is written — a sentence
+      // in `conditions[]` plus a `complete` -> `partial` status demotion (see
+      // pipeline/scan-health.js's applyFreshness, the same "patch it on from
+      // bin/ after the engine already built scanHealth" pattern). The previous
+      // version set a bespoke `scanHealth.provenanceIncomplete` key that NO
+      // consumer reads: pipeline/assurance-mode.js and
+      // posture/compliance-policy.js both read `status`/`conditions[]` only, so
+      // --require-provenance changed no behaviour anywhere. The array is still
+      // carried, for a consumer that wants the ids, but it is no longer the
+      // only trace.
+      const condition = `--require-provenance: ${incomplete.length} finding(s) have unresolved provenance`;
+      scan.scanHealth = {
+        ...(scan.scanHealth || {}),
+        conditions: [...(Array.isArray(scan.scanHealth?.conditions) ? scan.scanHealth.conditions : []), condition],
+        status: (scan.scanHealth?.status ?? 'complete') === 'complete' ? 'partial' : scan.scanHealth.status,
+        provenanceIncomplete: incomplete,
+      };
+    }
+  }
+
   // The BOM/attestation emitters stamp the producing engine's version into
   // their metadata; carry the real package version so it can never drift.
   if (meta && meta.engineVersion == null) meta.engineVersion = PKG_VERSION;
@@ -600,6 +789,18 @@ async function cmdScan(args) {
     }
   } catch {}
 
+  // FR-207: custom rule pack freshness. This is the one freshness leg that
+  // cannot be computed inside engine.js -- the pattern-rule DSL only runs
+  // here, after scan.scanHealth already exists -- so it's patched on via
+  // the same applyFreshness() engine.js uses for the other four legs (see
+  // that function's header comment in pipeline/scan-health.js).
+  if (scan.scanHealth) {
+    try {
+      const { applyFreshness } = await import('../src/pipeline/scan-health.js');
+      scan.scanHealth = applyFreshness(scan.scanHealth, { customRules: customRulesFreshness(targetAbs) });
+    } catch {}
+  }
+
   // EPSS exploit-prediction enrichment (skipped under --no-network / --deterministic).
   // Bumps severity on actively-exploited CVEs so they sort to the top.
   if (!args.flags['no-epss'] && !isDeterministic() && !noNet) {
@@ -717,7 +918,20 @@ async function cmdScan(args) {
   // per-finding list (with inline why-it-matters / how-it-fires / fix depth) so
   // "Show ALL findings" actually shows them. Add --verbose for full narration + code.
   if (args.flags.firehose && (!format || format === 'ship' || format === 'summary')) {
-    body += '\n\n' + toCLI(scan, { verbose });
+    // `provenance` reuses --verbose rather than adding a seventh provenance
+    // flag: --verbose already means "print the extra per-finding narration"
+    // (explainParts's why/how/fix bodies), and the provenance block is exactly
+    // that kind of detail. Before this, explainProvenance()/toCLI's
+    // `{provenance}` option had NO production caller at all — it was reachable
+    // only from its own unit test, so a feature that was built, reviewed and
+    // shipped could never be seen by a user.
+    //
+    // Gated on provenance actually having run, too: with --no-provenance (or
+    // AGENTIC_SECURITY_NO_PROVENANCE=1) every finding carries a `not_available`
+    // record, and printing five lines of "we did not look" per finding is noise
+    // the operator explicitly opted out of.
+    const provenanceOn = !_provFlags.disabled && process.env.AGENTIC_SECURITY_NO_PROVENANCE !== '1';
+    body += '\n\n' + toCLI(scan, { verbose, provenance: verbose && provenanceOn });
   }
 
   // v3 next-gen — supplementary blocks for human-readable formats. These
@@ -975,8 +1189,23 @@ async function cmdCi(args) {
   const findings = normalizeFindings(scan);
   const sev = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
   for (const f of findings) sev[f.severity] = (sev[f.severity] || 0) + 1;
+  // FR-206: "reports show both finding count and scan-health status." A
+  // 0-finding scan-exit is not the same claim as "the scan actually
+  // finished cleanly" — an annotator error, a file timeout, or a skipped
+  // analyzer already demotes scan.scanHealth.status to 'partial'
+  // (scan-health.js), but until this line nothing in `ci`'s own printed
+  // report ever surfaced it, so a broken analyzer could pass CI silently.
+  // This is a REPORT fix, not a gate-policy change: whether an incomplete
+  // scan should itself FAIL the build regardless of --fail-on is FR-204's
+  // job (assurance modes advisory/standard/strict), not yet implemented —
+  // deliberately not conflated with this fix.
+  const _health = scan.scanHealth;
+  const _healthLine = (_health && _health.status && _health.status !== 'complete')
+    ? `[ci] ⚠ scan-health=${_health.status} — ${(_health.conditions || [])[0] || 'analysis did not complete cleanly'}${(_health.conditions || []).length > 1 ? ` (+${_health.conditions.length - 1} more)` : ''}\n`
+    : `[ci] scan-health=${_health && _health.status ? _health.status : 'unknown'}\n`;
   process.stderr.write(
     `[ci] ${findings.length} findings — ${sev.critical} critical · ${sev.high} high · ${sev.medium} medium · ${sev.low} low\n` +
+    _healthLine +
     (_canWriteCi
       ? `[ci] artifacts: .agentic-security/findings.{json,sarif,junit.xml}\n`
       : `[ci] artifacts: NOT written (state writes refused — set AGENTIC_SECURITY_DEBUG=1 for the reason)\n`) +
@@ -1000,6 +1229,23 @@ async function cmdCi(args) {
     }
     process.stderr.write(`[ci] policy gate PASSED (${r.runner}, 0 denials)\n`);
   }
+  // FR-204: assurance modes. Runs ALONGSIDE --fail-on and --policy, same
+  // precedent as FR-SDLC-9's policy gate above — any of the three can fail
+  // the build independently. `standard` (the default) never fails here;
+  // `strict` fails the build when the scan itself was not fully complete,
+  // regardless of how few/no findings resulted from the incomplete run.
+  const { evaluateAssuranceMode, ASSURANCE_MODES, DEFAULT_ASSURANCE_MODE } = await import('../src/pipeline/assurance-mode.js');
+  const assuranceMode = args.flags.assurance || DEFAULT_ASSURANCE_MODE;
+  if (!ASSURANCE_MODES.includes(assuranceMode)) {
+    console.error(`[ci] --assurance must be one of: ${ASSURANCE_MODES.join('|')} (got '${assuranceMode}')`);
+    return 1;
+  }
+  const assuranceVerdict = evaluateAssuranceMode(assuranceMode, scan.scanHealth, findings);
+  if (!assuranceVerdict.ok) {
+    console.error(`[ci] assurance gate FAILED (mode=${assuranceMode}): ${assuranceVerdict.reason}`);
+    return 1;
+  }
+  if (assuranceMode === 'strict') process.stderr.write(`[ci] assurance gate PASSED (mode=strict)\n`);
   // R24 (PRD §5): PR-native net-new gate. With --fail-on-new and a baseline
   // ref, block ONLY on findings this PR INTRODUCED (vs the base ref), never on
   // the pre-existing backlog — the posture teams actually leave enabled.
@@ -1142,6 +1388,17 @@ async function cmdTriage(args) {
     console.log(`  Open:    critical=${t.openBySev.critical} high=${t.openBySev.high} medium=${t.openBySev.medium} low=${t.openBySev.low}`);
     if (t.medianMttrDays != null) console.log(`  MTTR median: ${t.medianMttrDays.toFixed(1)} days`);
     console.log(`  Total open: ${t.totalOpen}`);
+    // FR-907: longitudinal production feedback — aggregates 5 already-
+    // separate mechanisms (user suppression, accepted risk, invalid
+    // finding, fixed finding, verification outcome) into one view, rather
+    // than requiring an operator to check 5 different files by hand.
+    const { productionFeedbackReport, renderProductionFeedbackSummary } = await import('../src/posture/production-feedback.js');
+    const feedback = productionFeedbackReport(target, { sinceDays: days });
+    const feedbackSummary = renderProductionFeedbackSummary(feedback);
+    if (feedbackSummary) {
+      console.log('');
+      console.log(feedbackSummary);
+    }
     return 0;
   }
   console.error('triage list | assign <id> <assignee> | transition <id> <state> | trend [--since N]');
@@ -1586,57 +1843,263 @@ async function cmdReset(args) {
     console.log(`No state to reset at ${stateDirPath}`);
     return 0;
   }
-  const WIPE = new Set([
-    'validator-metrics.json',
-    'triage-feedback.json',
-    'scan-history.json',
-    'last-scan.json',
-    'last-scan.json.sig',
-    'shadow-findings.json',
-    'mcp-audit.log',
-    'hook-throttle.json',
-    'tickets.json',
-    'streak.json',
-    'findings.json',
-    'findings.sarif',
-    'findings.csv',
-  ]);
-  const WIPE_DIRS = new Set([
-    'llm-cache',
-    'fix-history',
-    'fix-plans',
-  ]);
+  // FR-703 (assurance-hardening PRD): registry-driven, not enumeration-
+  // driven. The registry (src/posture/artifact-registry.js) is built from an
+  // audit of every state-writing call site in src/ and bin/, not a
+  // hand-maintained list that drifts as new artifacts are added — see that
+  // module's header for the classification rules (generated vs
+  // operator-config) and the corrections it made to this project's own PRD
+  // evidence table along the way.
+  const GENERATED = new Set(listGeneratedArtifacts().map(a => a.name));
   const keep = new Set((args.flags.keep || '').split(',').filter(Boolean));
-  const targets = [];
-  for (const entry of await fsp.readdir(stateDirPath, { withFileTypes: true })) {
-    if (keep.has(entry.name)) continue;
-    if (WIPE.has(entry.name) || WIPE_DIRS.has(entry.name)) {
-      targets.push({ name: entry.name, dir: entry.isDirectory() });
+  // FR-702: `--expired` narrows the reset to only artifacts that are past
+  // their retention-class TTL (cache/scan/evidence/ticket/backup — see
+  // posture/retention-policy.js), rather than every registered generated
+  // artifact. Reuses this same command's existing confirm/keep/preserve
+  // machinery — a second, parallel deletion pathway would be a second
+  // place to get path-safety wrong.
+  let targets;
+  if (args.flags.expired) {
+    const { findExpiredArtifacts } = await import('../src/posture/retention-policy.js');
+    targets = findExpiredArtifacts(scanRoot)
+      .filter(a => !keep.has(a.name))
+      .map(a => ({ name: a.name, dir: a.isDir, ageDays: a.ageDays, ttlDays: a.ttlDays, retentionClass: a.retentionClass }));
+  } else {
+    targets = [];
+    for (const entry of await fsp.readdir(stateDirPath, { withFileTypes: true })) {
+      if (keep.has(entry.name)) continue;
+      if (GENERATED.has(entry.name)) {
+        targets.push({ name: entry.name, dir: entry.isDirectory() });
+      }
     }
   }
+  // FR-707: an artifact under an active legal hold is pulled OUT of the
+  // deletion targets regardless of mode — a hold must protect against a
+  // PLAIN `reset --yes` too (which otherwise deletes every registered
+  // 'generated' artifact unconditionally), not just `--expired`, which
+  // retention-policy.js's own findExpiredArtifacts already excludes on its
+  // own as a second, defense-in-depth enforcement of the same guarantee.
+  const { loadLegalHolds, isUnderHold } = await import('../src/posture/legal-hold.js');
+  const holds = loadLegalHolds(scanRoot);
+  const heldDetail = [];
+  targets = targets.filter(t => {
+    const hold = isUnderHold(t.name, holds);
+    if (!hold) return true;
+    heldDetail.push({ name: t.name, dir: !!t.dir, reason: `active legal hold (owner: ${hold.owner}, reason: ${hold.reason})` });
+    return false;
+  });
   if (!targets.length) {
-    console.log(`Nothing to reset under ${stateDirPath}.`);
+    console.log(args.flags.expired ? `Nothing expired under ${stateDirPath}.` : `Nothing to reset under ${stateDirPath}.`);
+    if (heldDetail.length) {
+      console.log(`Preserving ${heldDetail.length} artifact(s) under active legal hold: ${heldDetail.map(h => h.name).sort().join(', ')}`);
+    }
     return 0;
   }
-  console.log(`agentic-security reset — will remove from ${stateDirPath}:`);
-  for (const t of targets) console.log(`  ${t.name}${t.dir ? '/' : ''}`);
+  console.log(`agentic-security reset${args.flags.expired ? ' --expired' : ''} — will remove from ${stateDirPath}:`);
+  for (const t of targets) {
+    const ttlNote = args.flags.expired ? `  (${t.retentionClass}, ${t.ageDays.toFixed(1)}d old, ttl ${t.ttlDays}d)` : '';
+    console.log(`  ${t.name}${t.dir ? '/' : ''}${ttlNote}`);
+  }
   console.log('');
-  console.log('Preserving operator-authored config: rules.yml, rules/, license-policy.yml, trusted-keys.json, ruleset-version.json');
+  // FR-703: report what is ACTUALLY present and being left alone, rather
+  // than a hardcoded 5-name string that drifted behind the real config
+  // surface (risk-config.yml, profile.yml, suppressions.yml, and others were
+  // silently omitted from the old message even though they were already
+  // correctly never wiped).
+  const targetNames = new Set(targets.map(t => t.name));
+  const heldNames = new Set(heldDetail.map(h => h.name));
+  const preserved = heldDetail.map(h => h.name + (h.dir ? '/' : ''));
+  const preservedDetail = heldDetail.map(h => ({ name: h.name, reason: h.reason }));
+  for (const entry of await fsp.readdir(stateDirPath, { withFileTypes: true })) {
+    if (keep.has(entry.name) || targetNames.has(entry.name) || heldNames.has(entry.name)) continue;
+    if (!args.flags.expired && GENERATED.has(entry.name)) continue;
+    preserved.push(entry.name + (entry.isDirectory() ? '/' : ''));
+    preservedDetail.push({
+      name: entry.name,
+      reason: args.flags.expired && GENERATED.has(entry.name)
+        ? 'generated artifact still within its retention TTL'
+        : 'operator-authored configuration',
+    });
+  }
+  if (preserved.length) {
+    console.log(args.flags.expired
+      ? `Preserving operator-authored config and generated artifacts still within their TTL: ${preserved.sort().join(', ')}`
+      : `Preserving operator-authored config: ${preserved.sort().join(', ')}`);
+  }
+  // FR-706: every reset invocation — dry-run or applied — leaves a durable,
+  // structured record of what it planned, deleted, preserved, or failed to
+  // delete, not just console output that vanishes once the terminal
+  // scrolls past it.
+  const { buildDeletionReport, writeDeletionReport } = await import('../src/posture/state-lifecycle-report.js');
+  const mode = args.flags.expired ? 'reset --expired' : 'reset';
   if (!args.flags.yes) {
     console.log('');
     console.log('Pass --yes to proceed (or --keep <name,name> to spare specific items).');
+    writeDeletionReport(scanRoot, buildDeletionReport({
+      mode, dryRun: true, root: scanRoot,
+      items: targets.map(t => ({
+        name: t.name, dir: !!t.dir, status: 'planned',
+        retentionClass: t.retentionClass || null, ageDays: t.ageDays ?? null, ttlDays: t.ttlDays ?? null,
+      })),
+      preserved: preservedDetail,
+    }));
     return 0;
   }
+  const outcomes = [];
   for (const t of targets) {
     const p = path.join(stateDirPath, t.name);
+    const base = { name: t.name, dir: !!t.dir, retentionClass: t.retentionClass || null, ageDays: t.ageDays ?? null, ttlDays: t.ttlDays ?? null };
     try {
       if (t.dir) await fsp.rm(p, { recursive: true, force: true });
       else await fsp.rm(p, { force: true });
+      outcomes.push({ ...base, status: 'deleted' });
     } catch (e) {
       console.error(`reset: failed to remove ${p}: ${e.message}`);
+      outcomes.push({ ...base, status: 'failed', error: e.message });
     }
   }
-  console.log(`Reset ${targets.length} item(s). Operator-authored config preserved.`);
+  const failedCount = outcomes.filter(o => o.status === 'failed').length;
+  console.log(`Reset ${outcomes.length - failedCount} item(s)${failedCount ? `, ${failedCount} failed` : ''}. Operator-authored config preserved.`);
+  const reportPath = writeDeletionReport(scanRoot, buildDeletionReport({
+    mode, dryRun: false, root: scanRoot, items: outcomes, preserved: preservedDetail,
+  }));
+  if (reportPath) console.log(`Deletion report: ${path.relative(scanRoot, reportPath)}`);
+  return failedCount ? 1 : 0;
+}
+
+// `agentic-security export --out <dir> [--root <path>]`
+//
+// FR-706 (assurance-hardening PRD): the "exported" half of "operators can
+// prove what was exported, deleted, retained, or failed." Copies every
+// CURRENTLY-PRESENT registered artifact — generated AND operator-config —
+// from .agentic-security/ into an operator-chosen destination, alongside a
+// manifest naming exactly what was copied (with a content hash for files)
+// and what failed. Unlike `reset`, classification does not gate inclusion:
+// an export is a snapshot for the operator's own records, migration, or
+// legal-preservation purposes, not a deletion decision.
+async function cmdExport(args) {
+  const scanRoot = path.resolve(args.flags.root || '.');
+  const stateDirPath = stateDir(scanRoot);
+  if (!fs.existsSync(stateDirPath)) {
+    console.log(`No state to export at ${stateDirPath}`);
+    return 0;
+  }
+  if (!args.flags.out) {
+    console.error('export: --out <dir> is required.');
+    return 2;
+  }
+  const outDir = path.resolve(args.flags.out);
+  await fsp.mkdir(outDir, { recursive: true });
+
+  const { ARTIFACT_REGISTRY } = await import('../src/posture/artifact-registry.js');
+  const { buildExportReport, writeExportReport } = await import('../src/posture/state-lifecycle-report.js');
+  const { createHash } = await import('node:crypto');
+  const present = new Set((await fsp.readdir(stateDirPath, { withFileTypes: true })).map(e => e.name));
+
+  const items = [];
+  for (const artifact of ARTIFACT_REGISTRY) {
+    if (!present.has(artifact.name)) continue;
+    const src = path.join(stateDirPath, artifact.name);
+    const dest = path.join(outDir, artifact.name);
+    try {
+      await fsp.mkdir(path.dirname(dest), { recursive: true });
+      if (artifact.kind === 'dir') {
+        await fsp.cp(src, dest, { recursive: true });
+        items.push({ name: artifact.name, classification: artifact.classification, retentionClass: artifact.retentionClass || null, status: 'exported', sha256: null });
+      } else {
+        await fsp.copyFile(src, dest);
+        const sha256 = createHash('sha256').update(fs.readFileSync(src)).digest('hex');
+        items.push({ name: artifact.name, classification: artifact.classification, retentionClass: artifact.retentionClass || null, status: 'exported', sha256 });
+      }
+    } catch (e) {
+      items.push({ name: artifact.name, classification: artifact.classification, retentionClass: artifact.retentionClass || null, status: 'failed', error: e.message });
+    }
+  }
+
+  const report = buildExportReport({ root: scanRoot, outDir, items });
+  const manifestPath = path.join(outDir, 'export-manifest.json');
+  await fsp.writeFile(manifestPath, JSON.stringify(report, null, 2) + '\n');
+  writeExportReport(scanRoot, report); // last-action record kept under .agentic-security/ too, same as deletion-report.json
+
+  const failedCount = items.filter(i => i.status === 'failed').length;
+  console.log(`Exported ${items.length - failedCount} artifact(s) to ${outDir}${failedCount ? `, ${failedCount} failed` : ''}.`);
+  console.log(`Manifest: ${manifestPath}`);
+  return failedCount ? 1 : 0;
+}
+
+// `agentic-security legal-hold add --artifact <name> --owner <id> --reason <text> [--expires <date>]`
+// `agentic-security legal-hold remove --artifact <name>`
+// `agentic-security legal-hold list [--all]`
+//
+// FR-707 (assurance-hardening PRD): identity-bound (--owner), reasoned
+// (--reason), time-bounded where applicable (--expires is optional — an
+// indefinite hold has no end date), and auditable (`list` reads back
+// exactly what was recorded). See posture/legal-hold.js for the full
+// design rationale and how this is enforced inside `cmdReset`.
+async function cmdLegalHold(args) {
+  const scanRoot = path.resolve(args.flags.root || '.');
+  const sub = args._[1];
+  const { addLegalHold, removeLegalHold, listLegalHolds } = await import('../src/posture/legal-hold.js');
+
+  if (sub === 'add') {
+    const result = addLegalHold(scanRoot, {
+      artifact: args.flags.artifact, owner: args.flags.owner, reason: args.flags.reason, expires_at: args.flags.expires,
+    });
+    if (!result.ok) { console.error(`legal-hold add: ${result.reason}`); return 2; }
+    console.log(`Legal hold placed on "${result.hold.artifact}" (owner: ${result.hold.owner}${result.hold.expires_at ? `, expires ${result.hold.expires_at}` : ', indefinite'}).`);
+    return 0;
+  }
+  if (sub === 'remove') {
+    if (!args.flags.artifact) { console.error('legal-hold remove: --artifact <name> is required.'); return 2; }
+    const removedCount = removeLegalHold(scanRoot, args.flags.artifact);
+    console.log(removedCount ? `Removed ${removedCount} hold(s) on "${args.flags.artifact}".` : `No hold found on "${args.flags.artifact}".`);
+    return 0;
+  }
+  if (sub === 'list' || !sub) {
+    const holds = listLegalHolds(scanRoot, { includeExpired: !!args.flags.all });
+    if (!holds.length) { console.log(args.flags.all ? 'No legal holds recorded (ever).' : 'No active legal holds.'); return 0; }
+    for (const h of holds) {
+      console.log(`  ${h.artifact}  owner=${h.owner}  reason="${h.reason}"  expires=${h.expires_at || 'never'}  created=${h.created_at}`);
+    }
+    return 0;
+  }
+  console.error(`legal-hold: unknown subcommand "${sub}" (expected add|remove|list).`);
+  return 2;
+}
+
+// `agentic-security calibration-feedback record --finding-id <id> --outcome accepted-risk|realized-incident [--note <text>]`
+// `agentic-security calibration-report`
+//
+// FR-806 (assurance-hardening PRD): genuinely opt-in — nothing here is ever
+// written by a scan. See posture/calibration-feedback.js for the full
+// scoping rationale (why "aggregated" means within-installation, why the
+// record snapshots only prediction signals and never file/line/vuln text).
+async function cmdCalibrationFeedback(args) {
+  const scanRoot = path.resolve(args.flags.root || '.');
+  const sub = args._[1];
+  const { recordCalibrationFeedback, OUTCOMES } = await import('../src/posture/calibration-feedback.js');
+
+  if (sub === 'record') {
+    const result = recordCalibrationFeedback(scanRoot, {
+      findingId: args.flags['finding-id'], outcome: args.flags.outcome, note: args.flags.note,
+    });
+    if (!result.ok) { console.error(`calibration-feedback record: ${result.reason}`); return 2; }
+    // The persisted record.findingId is privacy-safe (a hash), not the
+    // caller's own input -- echo back what the operator actually typed.
+    console.log(`Recorded "${result.record.outcome}" for finding ${args.flags['finding-id']}.`);
+    return 0;
+  }
+  console.error(`calibration-feedback: unknown subcommand "${sub}" (expected record --finding-id <id> --outcome ${OUTCOMES.join('|')} [--note <text>]).`);
+  return 2;
+}
+
+async function cmdCalibrationReport(args) {
+  const scanRoot = path.resolve(args.flags.root || '.');
+  const { buildCalibrationReport, renderCalibrationReportSummary } = await import('../src/posture/calibration-feedback.js');
+  const report = buildCalibrationReport(scanRoot);
+  if (args.flags.format === 'json') { writeStdout(JSON.stringify(report, null, 2) + '\n'); return 0; }
+  const summary = renderCalibrationReportSummary(report);
+  console.log(summary || 'No calibration feedback recorded yet — this is opt-in; see `calibration-feedback record --help`.');
   return 0;
 }
 
@@ -1885,6 +2348,53 @@ async function cmdCompliance(args) {
 
 async function cmdAttest(args) {
   const scanRoot = path.resolve(args.flags.root || '.');
+
+  if (args.flags.provenance) {
+    const {
+      buildProvenanceEvidenceBundle, signProvenanceEvidenceBundle, ensureKeyPair,
+    } = await import('../src/posture/provenance-evidence-bundle.js');
+
+    let scan;
+    try { scan = JSON.parse(fs.readFileSync(statePath(scanRoot, 'last-scan.json'), 'utf8')); }
+    catch { console.error('No .agentic-security/last-scan.json — run a scan first.'); return 2; }
+
+    const findings = scan.findings || [];
+    const wanted = args.flags.provenance === true ? undefined : args.flags.provenance;
+    // `--provenance` alone (boolean flag) attests every finding WITH
+    // findingProvenance present; `--provenance <id>` scopes to one.
+    const subset = (wanted ? findings.filter((f) => f.id === wanted || f.stableId === wanted) : findings)
+      .filter((f) => f.findingProvenance);
+    if (!subset.length) {
+      console.error(wanted ? `No finding matching "${wanted}" with findingProvenance.` : 'No findings with findingProvenance to attest.');
+      return 2;
+    }
+
+    const kp = ensureKeyPair();
+    if (kp.created) console.error(`Generated a new signing key at ${kp.privateKey} (public: ${kp.publicKey}).`);
+
+    const outDir = statePath(scanRoot, 'attestations');
+    fs.mkdirSync(outDir, { recursive: true });
+    // repoIdentity: best-effort, from the same `git remote` lookup other
+    // provenance modules avoid (no such lookup exists yet) — keep it simple,
+    // pass null when unavailable rather than inventing a git-remote reader
+    // here. A future task can enrich this; the field degrades honestly.
+    const meta = { engineVersion: scan.engineVersion || null, repoIdentity: null, head: scan.commit || null };
+
+    let n = 0;
+    for (const f of subset) {
+      const bundle = signProvenanceEvidenceBundle(buildProvenanceEvidenceBundle(f, meta), kp.privateKeyPem);
+      const name = `provenance-${(f.stableId || f.id || `finding-${n}`)}.json`.replace(/[^\w.-]/g, '_');
+      fs.writeFileSync(path.join(outDir, name), JSON.stringify(bundle, null, 2) + '\n');
+      n++;
+    }
+    console.log(`Signed ${n} provenance evidence bundle(s) → ${path.relative(scanRoot, outDir)}/`);
+    console.log(`Public key (share this with whoever verifies): ${kp.publicKey}`);
+    console.log('');
+    console.log('A bundle proves its contents are unmodified since signing. It does NOT');
+    console.log('prove the origin commit is correctly identified — read confidence.level.');
+    return 0;
+  }
+
   const {
     ensureKeyPair, buildEvidenceBundle, signEvidenceBundle,
   } = await import('../src/posture/evidence-bundle.js');
@@ -1989,8 +2499,15 @@ async function cmdVerifyAttestation(args) {
   if (!file) { console.error('Usage: agentic-security verify-attestation <bundle.json|last-scan.json> [--public-key <path>] [--against <project-path>]'); return 2; }
 
   let bundle;
-  try { bundle = JSON.parse(fs.readFileSync(path.resolve(file), 'utf8')); }
-  catch (e) { console.error(`Could not read bundle: ${e.message}`); return 2; }
+  try {
+    const raw = fs.readFileSync(path.resolve(file), 'utf8');
+    // FR-705: transparently decrypt if this is an encrypted artifact (e.g.
+    // an encrypted compliance-evidence.json) — a no-op for any plaintext
+    // file, including every artifact from before encryption was ever
+    // configured.
+    const { maybeDecryptForRead } = await import('../src/posture/encryption-provider.js');
+    bundle = JSON.parse(maybeDecryptForRead(raw));
+  } catch (e) { console.error(`Could not read bundle: ${e.message}`); return 2; }
 
   const runAttestation = _asRunAttestation(bundle);
   if (runAttestation) return cmdVerifyRunAttestation(runAttestation, args);
@@ -2000,6 +2517,55 @@ async function cmdVerifyAttestation(args) {
   try { publicKeyPem = fs.readFileSync(path.resolve(keyFile), 'utf8'); }
   catch { console.error(`Could not read public key at ${keyFile}. Pass --public-key <path>.`); return 2; }
 
+  // FR-505: a compliance evidence manifest (@type: ComplianceEvidence) is a
+  // third distinct shape this same command can be handed — auto-detected
+  // the same way run-attestation-vs-finding-bundle already is, rather than
+  // adding a fourth CLI command for what is, from an operator's point of
+  // view, the same question ("is this artifact exactly what was signed").
+  if (bundle['@type'] === 'ComplianceEvidence') {
+    const { verifyComplianceEvidence } = await import('../src/posture/compliance-evidence-signing.js');
+    const cr = verifyComplianceEvidence(bundle, publicKeyPem);
+    if (!cr.ok) { console.error(`✗ INVALID — ${cr.reason}`); return 1; }
+    console.log('✓ VALID — the compliance evidence manifest is exactly what the signer produced.');
+    console.log('');
+    console.log(`  framework: ${bundle.framework}  version: ${bundle.version}`);
+    console.log(`  generated: ${bundle.generatedAt}`);
+    if (bundle.evidenceDigest) console.log(`  evidence digest: ${bundle.evidenceDigest}`);
+    console.log(`  compliant: ${bundle.summary?.compliant ?? 'n/a'}  non-compliant: ${bundle.summary?.nonCompliant ?? 'n/a'}  stale: ${bundle.summary?.stale ?? 0}  gap: ${bundle.summary?.gap ?? 0}`);
+    return 0;
+  }
+
+  // Finding Provenance PRD M4 §4.1: a provenance evidence bundle
+  // (schema: agentic-security/provenance-evidence@1) is a fourth distinct
+  // shape this same command can be handed — same auto-detection chain as
+  // the ComplianceEvidence branch above, dispatched by schema marker
+  // rather than a new CLI verb. Must be checked BEFORE the fallback
+  // verifyEvidenceBundle() call below, which assumes evidence-bundle.js's
+  // own shape (`.evidence`, `.finding` with severity/vuln/file/line) and
+  // would misinterpret a provenance bundle.
+  const { verifyProvenanceEvidenceBundle, PROVENANCE_BUNDLE_SCHEMA } = await import('../src/posture/provenance-evidence-bundle.js');
+  if (bundle.schema === PROVENANCE_BUNDLE_SCHEMA) {
+    const pr = verifyProvenanceEvidenceBundle(bundle, publicKeyPem);
+    if (!pr.ok) { console.error(`✗ INVALID — ${pr.reason}`); return 1; }
+    const p = bundle.provenance || {};
+    console.log('✓ VALID — the provenance record is exactly what the signer attested.');
+    console.log('');
+    console.log(`  finding: ${bundle.finding?.stableId || bundle.finding?.id || '?'}`);
+    console.log(`  status: ${p.status || 'n/a'}   method: ${p.method || 'n/a'}`);
+    // FR-PROV-026: findingOrigin.authorName is untrusted git commit metadata
+    // (this bundle's signature only proves the BUNDLE wasn't tampered with —
+    // it says nothing about what the original commit author put in their
+    // name — see the "Signed, portable evidence" section of the root
+    // CLAUDE.md), printed straight to the terminal by `verify-attestation`.
+    if (p.findingOrigin) console.log(`  origin: ${p.findingOrigin.commit || '?'} by ${sanitizeForTerminal(p.findingOrigin.authorName) || '?'} on ${p.findingOrigin.authorDate || '?'}`);
+    console.log(`  confidence: ${p.confidence?.level || 'n/a'} (${p.confidence?.score ?? 'n/a'})`);
+    if ((p.limitations || []).length) console.log(`  limitations: ${p.limitations.join('; ')}`);
+    console.log('');
+    console.log(`  proves:        ${bundle.proves}`);
+    console.log(`  does NOT prove: ${bundle.doesNotProve}`);
+    return 0;
+  }
+
   const r = verifyEvidenceBundle(bundle, publicKeyPem);
   if (!r.ok) {
     console.error(`✗ INVALID — ${r.reason}`);
@@ -2016,6 +2582,84 @@ async function cmdVerifyAttestation(args) {
   return 0;
 }
 
+// FR-1001 (assurance-hardening PRD): "effective policy is explainable."
+// Loads whichever organization/repository/environment policy bundles exist
+// under .agentic-security/policy-bundles/, verifies each against an
+// operator-supplied public key, merges the valid ones (most-specific-wins),
+// and prints BOTH the effective policy with per-key provenance AND every
+// rejected bundle's scope and reason — a rejection is reported, never
+// silently absent, so "tampered or expired policy is rejected" is visible
+// through this same real command, not just a library-level guarantee.
+async function cmdPolicyExplain(args) {
+  const scanRoot = path.resolve(args.flags.root || '.');
+  const { loadPolicyBundles, loadPolicyPublicKey, resolveEffectivePolicy } = await import('../src/posture/policy-bundle.js');
+  const entries = loadPolicyBundles(scanRoot);
+  if (!entries.length) {
+    console.log('No policy bundles found under .agentic-security/policy-bundles/ (organization.json, repository.json, environment.json).');
+    return 0;
+  }
+  let publicKeyPem = null;
+  const keyFile = args.flags['public-key'];
+  if (keyFile) {
+    try { publicKeyPem = fs.readFileSync(path.resolve(keyFile), 'utf8'); }
+    catch (e) { console.error(`Could not read public key at ${keyFile}: ${e.message}`); return 2; }
+  } else {
+    publicKeyPem = loadPolicyPublicKey(scanRoot);
+  }
+  const { effective, provenance, accepted, rejected } = resolveEffectivePolicy(entries, publicKeyPem);
+
+  console.log(`Accepted (${accepted.length}): ${accepted.join(', ') || 'none'}`);
+  if (rejected.length) {
+    console.log(`Rejected (${rejected.length}):`);
+    for (const r of rejected) console.log(`  ✗ ${r.scope}: ${r.reason}`);
+  }
+  console.log('');
+  console.log('Effective policy:');
+  const keys = Object.keys(effective).sort();
+  if (!keys.length) {
+    console.log('  (empty — no accepted bundle contributed any key)');
+  } else {
+    for (const k of keys) console.log(`  ${k} = ${JSON.stringify(effective[k])}  [from: ${provenance[k]}]`);
+  }
+  return 0;
+}
+
+// FR-1001: the operator-facing signing side, mirroring cmdAttest's own
+// generate-key-if-absent pattern. Genuinely optional — an org can sign
+// bundles with any Ed25519 tooling that produces the same canonical bytes
+// (canonicalPolicyBytes is exported for exactly that interop reason) — but
+// without SOME real caller for ensurePolicyKeyPair, this codebase's own
+// dead-module guard is right to flag it: a key-generation function nobody
+// calls is exactly the kind of code this project's premortems exist to
+// catch, per posture/CLAUDE.md's dead-module convention.
+async function cmdPolicySign(args) {
+  const scanRoot = path.resolve(args.flags.root || '.');
+  const { ensurePolicyKeyPair, buildPolicyBundle, signPolicyBundle } = await import('../src/posture/policy-bundle.js');
+  const scope = args.flags.scope;
+  if (!['organization', 'repository', 'environment'].includes(scope)) {
+    console.error('Usage: agentic-security policy-sign --scope <organization|repository|environment> --policy <json-file> [--expires <ISO-date>] [--out <path>]');
+    return 2;
+  }
+  const policyFile = args.flags.policy;
+  if (!policyFile) { console.error('--policy <json-file> is required (the policy object to sign).'); return 2; }
+  let policy;
+  try { policy = JSON.parse(fs.readFileSync(path.resolve(policyFile), 'utf8')); }
+  catch (e) { console.error(`Could not read --policy file: ${e.message}`); return 2; }
+
+  const kp = ensurePolicyKeyPair();
+  if (kp.created) console.error(`Generated a new policy-signing key at ${kp.privateKey} (public: ${kp.publicKey}). Distribute the PUBLIC key to every repository that must trust bundles you sign.`);
+
+  const bundle = buildPolicyBundle(scope, policy, { expiresAt: args.flags.expires || null });
+  if (!bundle) { console.error('Could not build a bundle — check --scope and that --policy is a JSON object.'); return 2; }
+  const signed = signPolicyBundle(bundle, kp.privateKeyPem);
+
+  const outFile = args.flags.out || `${scope}.json`;
+  fs.writeFileSync(path.resolve(outFile), JSON.stringify(signed, null, 2) + '\n');
+  console.log(`✓ signed ${scope} policy bundle written to ${outFile}`);
+  console.log(`  public key for verification: ${kp.publicKey}`);
+  return 0;
+}
+
 async function cmdRuleSynth(args) {
   const scanRoot = path.resolve(args.flags.root || '.');
   const { synthesizeRules } = await import('../src/posture/rule-synthesis.js');
@@ -2099,11 +2743,15 @@ async function cmdFix(args) {
     return 0;
   }
 
-  // Both --preview and --apply require an actual replacement to operate on.
-  // For now we accept either f.fix.replacement (full new file content) or
-  // f.fix.replaceLine (single-line replacement). Anything else falls back
-  // to the template output and tells the user to run the security-fixer subagent.
-  const absFile = path.resolve(scanRoot, f.file);
+  // FR-303 (assurance-hardening PRD): confine BEFORE the first read, not just
+  // before the write — a traversal or symlink-planted f.file was previously
+  // followed unquestioned for both the preview diff and the apply write (no
+  // check existed on this path at all, unlike MCP's apply_fix). Applies to
+  // preview too since both modes read from the same (until now, unconfined)
+  // location.
+  let absFile;
+  try { absFile = confinePath(scanRoot, f.file, 'finding.file'); }
+  catch (e) { console.error(`path-escape refused: ${e.message}`); return 4; }
   if (!fs.existsSync(absFile)) { console.error(`File not found: ${absFile}`); return 4; }
   const originalContent = await fsp.readFile(absFile, 'utf8');
   let newContent = null;
@@ -2127,16 +2775,56 @@ async function cmdFix(args) {
     return 0;
   }
 
-  // --apply. Premortem 4R-8: pass stableId from the engine directly so the
-  // recover() cross-check is robust against line-number drift (f.id is
-  // `${file}:${line}:${rule}` and rotates when the user edits the file).
-  const entry = await applyFix({
-    scanRoot, file: f.file, originalContent, newContent,
-    findingId: f.id, stableId: f.stableId || null,
-    ruleId: f.cwe || f.title, vuln: f.vuln || f.title,
+  // --apply. FR-301/FR-302/FR-304 (assurance-hardening PRD): this used to
+  // WARN on failed integrity and apply anyway, and skip verification
+  // entirely (no rescan, no lint) — the same write-time safety gate MCP's
+  // apply_fix already enforces for its caller-patch branch is now required
+  // here too, through the one shared service.
+  if (sigVerified !== true) {
+    console.error(`Refusing to apply: last-scan.json integrity check ${sigVerified === false ? 'failed (tampered)' : 'could not verify (unsigned)'} — re-run \`agentic-security scan\` to refresh.`);
+    return 4;
+  }
+  // FR-307/D-0024: before this, the CLI had no way to supply approval
+  // evidence at all — a high-impact change (auth/authZ/crypto/PII/schema/
+  // infra-privilege/public-API) was unconditionally refused via --apply
+  // with no path to ever approve it, since fixMeta was never built here.
+  // --approved-by/--approval-reason are optional and no-op for a candidate
+  // that isn't high-impact — only apply-fix-service.js's own gate decides
+  // whether they were needed.
+  const approvedBy = args.flags['approved-by'] || null;
+  const approvalReason = args.flags['approval-reason'] || null;
+  // FR-1003: --author is optional and only has an effect when an operator
+  // has opted into separation-of-duties in authorized-approvers.json — see
+  // approver-registry.js's checkSeparationOfDuties.
+  const patchAuthor = args.flags['author'] || null;
+  const fixMeta = (approvedBy || approvalReason || patchAuthor)
+    ? { approval: { approvedBy: approvedBy || '', reason: approvalReason || '' }, ...(patchAuthor ? { author: patchAuthor } : {}) }
+    : null;
+  const result = await applyVerifiedFix({
+    scanRoot,
+    finding: { file: f.file, id: f.id, stableId: f.stableId || null, ruleId: f.cwe || f.title, vuln: f.vuln || f.title },
+    files: { [f.file]: newContent },
+    fixMeta,
   });
-  console.log(`✓ applied fix ${entry.id}  (file: ${entry.file})`);
+  if (!result.ok) {
+    console.error(`Refusing to apply: ${result.reason}`);
+    if (result.budgetExceeded) console.error(`  (${result.attempts}/${result.maxAttempts} attempts already made for this finding)`);
+    return 4;
+  }
+  const entry = result.written[0];
+  console.log(`✓ applied fix ${entry.historyId}  (file: ${entry.file})`);
   console.log(`  backup: ${entry.backupPath}`);
+  // FR-305: this used to unconditionally print "lint" as part of the
+  // verified line, even when the linter was skipped (not installed) or no
+  // test runner existed — claiming a required leg ran when it did not is
+  // exactly the mislabeling FR-305 exists to prevent. Say plainly when the
+  // pass was degraded and name what was skipped.
+  if (result.verifiedFull) {
+    console.log('  verified: yes — fully verified (rescan clean, no new medium+ finding, lint, tests)');
+  } else {
+    const degraded = (result.verify?.degradedLegs || []).join('; ') || 'a required leg';
+    console.log(`  verified: yes, but NOT fully verified — rescan clean, no new medium+ finding; ${degraded}`);
+  }
   console.log(`  revert with: agentic-security undo`);
   return 0;
 }
@@ -2308,10 +2996,16 @@ async function main() {
       case 'validator-cache': process.exit(await cmdValidatorCache(args));
       case 'verify':   process.exit(await cmdVerify(args));
       case 'reset':    process.exit(await cmdReset(args));
+      case 'export':   process.exit(await cmdExport(args));
+      case 'legal-hold': process.exit(await cmdLegalHold(args));
+      case 'calibration-feedback': process.exit(await cmdCalibrationFeedback(args));
+      case 'calibration-report': process.exit(await cmdCalibrationReport(args));
       case 'hunt':     process.exit(await cmdHunt(args));
       case 'compliance': process.exit(await cmdCompliance(args));
       case 'attest':   process.exit(await cmdAttest(args));
       case 'verify-attestation': process.exit(await cmdVerifyAttestation(args));
+      case 'policy-explain': process.exit(await cmdPolicyExplain(args));
+      case 'policy-sign': process.exit(await cmdPolicySign(args));
       case 'rule-synth': process.exit(await cmdRuleSynth(args));
       case 'digest':   process.exit(await cmdDigest(args));
       case 'setup':    process.exit(await cmdSetup(args));
@@ -2517,4 +3211,31 @@ async function main() {
   }
 }
 
-main();
+// Guard against running as the CLI entry point vs. being `import`ed (e.g. by
+// scanner/test/cli/provenance-flags.test.js, which imports parseProvenanceFlags
+// for a unit test). Without this, any import of this module — for a single
+// named export — re-runs the entire CLI dispatch and calls process.exit(),
+// killing whatever process did the importing.
+//
+// `import.meta.url === file://${process.argv[1]}` looks equivalent but is
+// NOT: when this script is invoked through a symlink (exactly what
+// `npm install -g`, `npx`, and `node_modules/.bin/<name>` all do for a
+// package's `bin` entries — which is the documented `npx
+// @clear-capabilities/agentic-security-scanner` install path), Node
+// resolves `import.meta.url` to the symlink's realpath while
+// `process.argv[1]` stays the symlink path as invoked, so the two never
+// match, the guard is always false, and the CLI silently exits with no
+// output. `import.meta.main` is resolved correctly through a symlink —
+// verified live through an actual symlink, not just read about — see the
+// Task 17 fix report. It was added in Node v24.2.0 (backported to
+// v22.18.0) and is currently Stability 1.0 (early development) per Node's
+// own docs — NOT stable, and NOT available on v20.11 as an earlier
+// version of this comment incorrectly claimed. Concretely: it is
+// `undefined` on Node 24.0.0/24.1.x, which satisfy this repo's declared
+// `engines.node: ">=24.0.0"` floor, so `import.meta.main` alone would
+// reproduce this exact bug (main() silently never runs) on a plain
+// non-symlinked invocation under those two point releases. The `??`
+// fallback below covers that gap without bumping the engines floor.
+if (import.meta.main ?? (import.meta.url === `file://${process.argv[1]}`)) {
+  main();
+}