@clear-capabilities/agentic-security-scanner 0.195.26 → 0.195.28

package/src/pipeline/evidence-record.js

@@ -0,0 +1,112 @@
+// Evidence contract (PRD FR 10): additive scan-record and finding-record fields. Nothing here replaces an existing
+// field; every field is derived from data the scan already holds or from read-only git queries on the scan root.
+
+import * as crypto from 'node:crypto';
+import * as cp from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { hardenGitArgs, hardenGitEnv } from '../util/git-hardening.js';
+
+export const SCAN_RECORD_SCHEMA = 'scan-record/1';
+export const FINDING_RECORD_SCHEMA = 'finding-record/1';
+const DIRTY_CAP = 200;
+
+const sha = (s) => crypto.createHash('sha256').update(s).digest('hex');
+
+function git(root, args) {
+  const r = cp.spawnSync('git', hardenGitArgs(args), { cwd: root, env: hardenGitEnv({}), encoding: 'buffer', maxBuffer: 64 * 1024 * 1024 });
+  return r.status === 0 ? r.stdout.toString('utf8') : null;
+}
+
+/** Source commit and digests of the files that differ from it, so a result is tied to the exact code scanned. */
+export function sourceState(root) {
+  const inside = git(root, ['rev-parse', '--is-inside-work-tree']);
+  if (!inside || inside.trim() !== 'true') return { vcs: 'none', commit: null, dirty: null, dirtyFiles: [], dirtyFilesTruncated: false };
+  const commit = (git(root, ['rev-parse', 'HEAD']) || '').trim() || null;
+  const status = git(root, ['status', '--porcelain=v1', '-z', '--untracked-files=normal']);
+  const entries = (status || '').split('\0').filter(Boolean).map((e) => ({ code: e.slice(0, 2), file: e.slice(3) }));
+  const dirtyFiles = entries.slice(0, DIRTY_CAP).map((e) => {
+    let digest = null;
+    try { const abs = path.join(root, e.file); if (fs.lstatSync(abs).isFile()) digest = sha(fs.readFileSync(abs)); } catch { /* deleted */ }
+    return { file: e.file, status: e.code.trim() || '?', sha256: digest };
+  });
+  return { vcs: 'git', commit, dirty: entries.length > 0, dirtyFiles, dirtyFilesTruncated: entries.length > DIRTY_CAP, dirtyCount: entries.length };
+}
+
+/** Flags that shaped the run, with values that could carry secrets or local paths reduced to their names. */
+export function invocationSummary(argv) {
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) continue;
+    let [k, v] = a.split(/=(.*)/s, 2);
+    // `--flag value`: keep a short non-path value so the record shows the format and mode that were chosen.
+    if (v === undefined && argv[i + 1] !== undefined && !argv[i + 1].startsWith('-') && /^[A-Za-z0-9_.,:-]{1,40}$/.test(argv[i + 1]) && !argv[i + 1].includes('/')) v = argv[i + 1];
+    out.push(/key|token|secret|password/i.test(k) ? `${k}=<redacted>` : (v !== undefined ? `${k}=${v}` : k));
+  }
+  return out;
+}
+
+export function buildScanRecord({ root, scan, meta, argv = [], engineVersion, mode }) {
+  const h = scan.scanHealth || {};
+  const model = scan.aiAssistance || null;
+  return {
+    schema: SCAN_RECORD_SCHEMA,
+    tool: { name: 'agentic-security', version: engineVersion || null },
+    source: sourceState(root),
+    invocation: { flags: invocationSummary(argv), mode: mode || (meta && meta.mode) || 'full' },
+    ignorePolicy: scan.scope ? { mode: scan.scope.policy.mode, ruleDigest: scan.scope.policy.ruleDigest, trackedFileSemantics: scan.scope.policy.trackedFileSemantics } : { mode: 'legacy-walk', ruleDigest: null, trackedFileSemantics: false },
+    rules: { rulesetVersion: scan._rulesetVersion || null, rulesetSource: scan._rulesetVersionSource || null },
+    model: model ? { provider: model.provider, model: model.model, egress: model.egress, stages: model.stages } : { configured: false },
+    capability: { status: h.status || null, conditions: Array.isArray(h.conditions) ? h.conditions.length : 0 },
+    fileCounts: { scanned: scan.filesScanned ?? null, skipped: scan.scope ? scan.scope.skippedCount : null, included: scan.scope ? scan.scope.includedCount : null },
+    // Wall-clock time differs on every run, so deterministic mode leaves it out and the record stays byte-identical.
+    elapsedMs: process.env.AGENTIC_SECURITY_DETERMINISTIC === '1' ? null : (meta && meta.durationMs != null ? meta.durationMs : null),
+  };
+}
+
+/** The span a finding occupies: source line through sink line when both are known, else its own line. */
+function spanOf(f) {
+  const lines = [f.line, f.source && f.source.line, f.sink && f.sink.line].filter((n) => Number.isInteger(n));
+  if (!lines.length) return null;
+  return { startLine: Math.min(...lines), endLine: Math.max(...lines) };
+}
+
+/** Finding record. `fileContents` maps scan-relative path to text. Existing fields are untouched. */
+export function annotateFindingRecords(findings, fileContents, { engineVersion = null } = {}) {
+  for (const f of findings || []) {
+    if (!f || f.record) continue;
+    const text = fileContents && (fileContents instanceof Map ? fileContents.get(f.file) : fileContents[f.file]);
+    f.record = {
+      schema: FINDING_RECORD_SCHEMA,
+      stableId: f.stableId || null,
+      path: f.file || null,
+      sourceHash: typeof text === 'string' ? sha(text) : null,
+      span: spanOf(f),
+      ruleFamily: f.family || null,
+      ruleVersion: engineVersion,
+      originalSeverity: f.originalSeverity || f.severity || null,
+      confidence: typeof f.confidence === 'number' ? f.confidence : null,
+      disposition: f.disposition || null,
+      evidence: {
+        sourceToSink: f.source || f.sink ? { source: f.source || null, sink: f.sink || null } : null,
+        guards: f.falsification ? [f.falsification] : [],
+        missingEvidence: (f.dispositionDetail && f.dispositionDetail.missingEvidence) || [],
+      },
+      reviewerVerdicts: Array.isArray(f.reviewerVerdicts) ? f.reviewerVerdicts : [],
+      modelOpinion: f.validator_verdict ? { verdict: f.validator_verdict, confidence: f.llm_confidence ?? null } : null,
+      remediation: f.fix || f.remediation || null,
+    };
+  }
+  return findings;
+}
+
+/**
+ * Raw and displayed findings must reconcile: every raw item is either displayed or accounted for by a named reason.
+ * Returns { ok, raw, displayed, accounted, gap }.
+ */
+export function reconcileFindings({ raw, displayed, hidden = {} }) {
+  const accounted = Object.values(hidden).reduce((a, b) => a + b, 0);
+  const gap = raw - displayed - accounted;
+  return { ok: gap === 0, raw, displayed, accounted, gap };
+}

package/src/pipeline/scan-health.js

@@ -42,6 +42,17 @@ export const SCAN_HEALTH_SCHEMA_VERSION = 1;
  *   never a fabricated all-zero summary.
  * @returns {object} scanHealth per PRD §10.3, additive fields only.
  */
+// The per-file table travels with the record up to this many files; beyond it only the count is kept
+// (the aggregate stages, rates and incomplete lists above are always present).
+const HASKELL_BYFILE_INLINE_MAX = 2000;
+function summarizeHaskellCoverage(h) {
+  if (!h) return null;
+  const n = h.byFile ? Object.keys(h.byFile).length : 0;
+  if (n <= HASKELL_BYFILE_INLINE_MAX) return { ...h, byFileCount: n };
+  const { byFile, ...rest } = h;
+  return { ...rest, byFileCount: n, byFileOmitted: true };
+}
+
 export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engineErrors = null, deepStatus = null, analyzerCoverage = null, lineageStatus = null, languageCoverage = null, supplyChain = null } = {}) {
   const conditions = [];
   const safeAnnotatorErrors = Array.isArray(annotatorErrors) ? annotatorErrors : [];
@@ -130,7 +141,7 @@ export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engin
     schemaVersion: SCAN_HEALTH_SCHEMA_VERSION,
     status,
     ...(trustFindings.length ? { buildTrust: { findings: trustFindings.length, uncertain: trustUncertain } } : {}),
-    ...(languageCoverage ? { languageCoverage: { totals: languageCoverage.totals ?? null, byKind: languageCoverage.byKind ?? null, ...(languageCoverage.limitations ? { limitations: languageCoverage.limitations } : {}), ...(languageCoverage.capabilities ? { capabilities: languageCoverage.capabilities } : {}), ...(languageCoverage.optionalModes ? { optionalModes: languageCoverage.optionalModes } : {}) } } : {}),
+    ...(languageCoverage ? { languageCoverage: { totals: languageCoverage.totals ?? null, byKind: languageCoverage.byKind ?? null, ...(languageCoverage.limitations ? { limitations: languageCoverage.limitations } : {}), ...(languageCoverage.capabilities ? { capabilities: languageCoverage.capabilities } : {}), ...(languageCoverage.optionalModes ? { optionalModes: languageCoverage.optionalModes } : {}), ...(languageCoverage.haskell ? { haskell: summarizeHaskellCoverage(languageCoverage.haskell) } : {}) } } : {}),
     files: {
       expected: scanMeta?.checkpoint?.total ?? null,
       scanned: scanMeta?.filesScanned ?? null,

package/src/posture/CLAUDE.md

@@ -906,7 +906,7 @@ are both pre-existing unrelated fields.
 | `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` |
+| `dag-walk.js` | (M3 §3.1) non-first-parent DAG walk + revert/cherry-pick detection for `--provenance deep`. Since 0.195.27 (GA-05) `origin-resolver.js` applies the revert and cherry-pick annotation to EVERY origin deep mode resolves, not only the ones the retry loop found, and a `Reapply "..."` subject (git's name for a revert of a revert since 2.43) counts as a revert; the diff inversion still decides. The corpus `bench/provenance-accuracy` holds ten adverse histories (revert, cherry-pick, squash, amend, `git mv`, dirty file, first-parent merge, conflict resolution, transitive lockfile, unreachable provider) and the contract is `docs/reference/finding-provenance-contract.md` |
 | `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 |
@@ -918,7 +918,7 @@ are both pre-existing unrelated fields.
 | `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` |
+| `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`. Since 0.195.27 a provider that errs or does not answer returns `{unavailable, reason}` instead of `null`, and the coordinator records a limitation naming the provider and the reason; `null` means "no pull request names this commit" and nothing else |
 | `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 |
 
@@ -1014,6 +1014,14 @@ Turns a PROVEN finding into a validated detection, hunts local historical logs f
 * **Redaction before persistence or display** (`redact.js`), on top of the proof store's secret scrubber. Records live under `.agentic-security/dnr/` (registered in `artifact-registry.js`, evidence class, encrypted by policy, tamper-evident).
 * **Names:** a detection is not a finding rule. `rule-compiler/` promotes DETECTION rules for the scanner; `dnr/` produces RESPONSE rules for a SIEM, a WAF or a log search. Do not merge them.
 
+## Finding-to-rule compiler: `rule-compiler/` (PRD 3, GA-07)
+
+`cli.js` (`rules synthesize|evaluate|promote|status|rollback|deprecate|cost|regress`), `ir.js`, `corpus.js`, `mutation.js`, `promotion.js`, `proposal.js`, `lifecycle.js`, `store.js`, `regression.js` and `eligibility.js`; contract `docs/reference/rule-compiler-contract.md`, guide `docs/guides/rule-compiler.md`, tests `test/rule-compiler/` and `test/cli/rule-compiler-cli.test.js` (`test:posture`). Since 0.195.27 (GA-07 §2 and §3):
+
+* **`negative-corpus.js`** is the shared negative corpus shipped with the scanner: safe snippets as strings in a module (no build step, identical everywhere) that `regression.js` puts in front of the shared false-positive corpus, so every evaluation, promotion and regression is held to it. Keep every entry free of the unsafe form; a vulnerable snippet here fails a correct rule. Directories named in `AGENTIC_SECURITY_RULES_FP_CORPUS` are held to as well.
+* **The ledger is portable.** `store.js` `saveLedger(root, ledger, { authorKey })` writes `ledger.json.author.sig` (Ed25519, the key `promote --sign-key` takes) beside the per-install HMAC signature, and `loadLedger` accepts a ledger whose chain verifies and whose author signature verifies against `AGENTIC_SECURITY_RULES_PUBLIC_KEY` or the rule-pack trust store when the HMAC does not (another install, a CI runner). A project-local key file alone is not trust. The ledger object carries `verifiedBy` (`install-key`, `author-key`, `unsigned-accepted`), stripped before it is written.
+* **Promotion records what was reviewed.** `--scope` is required; the ledger entry and `promotionEvent.evidence` carry digests of the evaluation, the provenance and both corpus halves (`regression.js` `corpusHash`), and `regress` reports a rule whose corpus changed after the review. `promotion.js` `dependentExamples` refuses an independent example that equals the original, its patch or a generated mutation after whitespace is collapsed.
+
 ## Eval Lab and the policy router: `evaluation/lab/`, `routing/policy-router.js` (PRD 6)
 
 Measures a deterministic baseline and model arms, and routes tasks from the measurements. Entry points `evaluation/lab/cli.js` (`cmdEval`, `cmdModelsLab`) and `routing/policy-router.js`; guide `docs/guides/eval-lab.md`; tests `test/eval-lab/`, `test/cli/eval-lab-cli.test.js`.

package/src/posture/artifact-registry.js

@@ -253,6 +253,8 @@ export const ARTIFACT_REGISTRY = [
   { name: 'integrations.yml', kind: 'file', classification: 'operator-config' },
   { name: 'profile.yml', kind: 'file', classification: 'operator-config' },
   { name: 'sca-policy.yml', kind: 'file', classification: 'operator-config' },
+  { name: 'haskell-budget.json', kind: 'file', classification: 'generated', retentionClass: 'scan', source: 'src/language/haskell-budget-state.js (saveBudgetState)', note: 'Haskell parse budgets in effect and every file left unanalysed when one was hit, with a content digest, so the next scan can say what finished since. Rewritten by every scan that has Haskell work left.' },
+  { name: 'haskell-models.json', kind: 'file', classification: 'operator-config', note: 'reviewed project models for Haskell wrappers; only ever loaded by language/haskell-project-models.js' },
   { name: 'suppressions.yml', kind: 'file', classification: 'operator-config', note: 'audit-tier suppression config; only ever loaded, never saved, by posture/suppressions.js' },
   { name: 'network-policy.json', kind: 'file', classification: 'operator-config', note: 'documented as an Inputs-section artifact in posture/network-policy-import.js, not a scanner-written digest' },
   { name: 'privacy-taxonomy.json', kind: 'file', classification: 'operator-config', note: 'FR-402 privacy data-classification taxonomy overrides/additions — read by dataflow/privacy-taxonomy.js, never written by the scanner' },

package/src/posture/custom-rules.js

@@ -436,6 +436,7 @@ export async function runRuleTests(scanRoot, fixtureGlob) {
   const files = await globFiles(fixtureGlob);
   console.log(`Loaded ${rules.length} rule(s); testing against ${files.length} file(s).\n`);
   let fired = 0;
+  let failures = 0;
   for (const fp of files) {
     let content = '';
     try { content = fs.readFileSync(fp, 'utf8'); } catch { continue; }
@@ -446,12 +447,16 @@ export async function runRuleTests(scanRoot, fixtureGlob) {
       if (findings.length) {
         fired++;
         const verdict = expectClean ? 'FAIL (false positive)' : 'PASS';
+        if (expectClean) failures++;
         console.log(`  [${verdict}] ${r.id} → ${fp}:${findings[0].line}`);
       } else if (expectFire) {
+        failures++;
         console.log(`  [FAIL (missed)] ${r.id} → ${fp}`);
       }
     }
   }
-  console.log(`\n${fired} match(es) across ${files.length} file(s).`);
-  return { ok: true, rules: rules.length, fired };
+  // GA-07 §3 (0.195.27): `ok` reports the verdicts, not merely that the run finished. It used to be `true` whatever the fixtures
+  // said, so `rule test` could never fail a build; a missed vulnerable fixture or a hit on a clean one is now a failure.
+  console.log(`\n${fired} match(es) across ${files.length} file(s)${failures ? `, ${failures} FAILED` : ''}.`);
+  return { ok: failures === 0, rules: rules.length, fired, failures };
 }

package/src/posture/drift.js

@@ -78,7 +78,21 @@ export function driftBetween(scanA, scanB) {
   // Findings — use kind+file+line+vuln as the stable key.
   const allFindingsA = [...(scanA.findings || []), ...(scanA.logicVulns || [])];
   const allFindingsB = [...(scanB.findings || []), ...(scanB.logicVulns || [])];
-  const findings = _diffSets(allFindingsA, allFindingsB, _findingKey);
+  // A claim grouped under an equivalent primary (llm-validator/claim-groups.js) is still present: it keeps its identity for drift,
+  // so grouping never shows a finding as fixed, and ungrouping never shows one as new.
+  const findings = _diffSets([...allFindingsA, ...(scanA.groupedClaims || [])], [...allFindingsB, ...(scanB.groupedClaims || [])], _findingKey);
+  // PRD FR 01: a finding that disappeared because the newer scan did not cover its file is out of scope, never fixed.
+  const outOfScope = [];
+  if (scanB.scope && Array.isArray(scanB.scope.included)) {
+    const inB = new Set(scanB.scope.included);
+    const keep = [];
+    for (const f of findings.removed) (f && f.file && !inB.has(f.file) ? outOfScope : keep).push(f);
+    findings.removed = keep;
+    findings.outOfScope = outOfScope;
+  } else {
+    findings.outOfScope = [];
+    findings.scopeUnknown = !!(scanB.scope && scanB.scope.includedOmitted);
+  }
   const severity = _severityDelta(allFindingsA, allFindingsB);
   const authBoundaries = _authBoundaryDelta(scanA.routes || [], scanB.routes || []);
   const dataClasses = _dataClassDelta(scanA.routes || [], scanB.routes || []);
@@ -163,6 +177,10 @@ export function driftToMarkdown(drift) {
     lines.push(`**Findings fixed: ${drift.findings.removed.length}**`);
     lines.push('');
   }
+  if (drift.findings.outOfScope && drift.findings.outOfScope.length) {
+    lines.push(`**Findings not covered by this scan (out of scope, not fixed): ${drift.findings.outOfScope.length}**`);
+    lines.push('');
+  }
   if (drift.dataClasses.newlyExposed.length) {
     lines.push(`**Newly exposed data classes: ${drift.dataClasses.newlyExposed.join(', ')}**`);
     lines.push('');

package/src/posture/provenance/coordinator.js

@@ -101,7 +101,7 @@ const MAX_CONCURRENCY = 4;
 // quotient: a 200-finding scan under a 60s global budget divides to 300ms,
 // which is less than a single `git blame`'s own 2s timeout and would starve
 // every finding equally instead of a few. 2s is one blame's worth of work.
-const MIN_PER_FINDING_BUDGET_MS = 2000;
+export const MIN_PER_FINDING_BUDGET_MS = 2000;
 
 // FR-PROV-022: an 8s-timeout-capped network call per finding is not
 // automatically bounded by the scan's own deadlineAt -- N findings x up to
@@ -563,7 +563,11 @@ async function resolveAndCache(finding, ctx, cacheKey, isSca, isTransitiveSca, i
       const fetchPRFn = ctx.providerName === 'github' ? fetchPRMetadataGithub : fetchPRMetadataGitlab;
       const fetchCodeownersFn = ctx.providerName === 'github' ? fetchCodeownersGithub : fetchCodeownersGitlab;
       const pr = await fetchPRFn(scanRoot, originResult.findingOrigin.commit, ctx.remoteUrl, ctx.providerConfig);
-      if (pr) {
+      if (pr && pr.unavailable) {
+        // GA-05 (0.195.27): forge metadata that could not be fetched is recorded, never silently absent. The origin,
+        // status and confidence above are unaffected: they come from local history, which the provider cannot change.
+        provenance.limitations.push(`provider metadata unavailable (${ctx.providerName}: ${pr.reason}); the origin commit is unaffected, only the pull request and code owner enrichment is missing`);
+      } else if (pr) {
         const codeowners = await fetchCodeownersFn(scanRoot, ctx.remoteUrl, ctx.providerConfig);
         provenance.providerEnrichment = {
           provider: ctx.providerName,

package/src/posture/provenance/dag-walk.js

@@ -81,9 +81,13 @@ export async function checkAbsentInSomeParent(scanRoot, sha, replay) {
 }
 
 // git's own convention when using `git revert` (no -n/--no-edit override):
-// "Revert \"<original subject>\"". Message alone is spoofable, so this is
-// only the FIRST half of detection — see detectRevert.
-const REVERT_MESSAGE_RE = /^Revert "/;
+// "Revert \"<original subject>\"". Since git 2.43 a revert of a revert is
+// titled "Reapply \"<original subject>\"" instead (GA-05, 0.195.27: found by
+// the corpus case `revert-reintroduces`, whose origin commit is exactly that
+// shape); it is still a revert, and the diff inversion below still decides.
+// Message alone is spoofable, so this is only the FIRST half of detection —
+// see detectRevert.
+const REVERT_MESSAGE_RE = /^(?:Revert|Reapply) "/;
 
 /**
  * A commit is a real revert only when its message matches git's own Revert

package/src/posture/provenance/origin-resolver.js

@@ -55,6 +55,20 @@ function relevantFiles(finding) {
   return [...files];
 }
 
+// GA-05 (0.195.27): revert and cherry-pick detection used to run only in deep mode's retry loop, which the standard walk reaches
+// only after it has MISSED. A standard-walk hit (the common case: the origin commit's first parent lacks the finding) therefore
+// never carried `revertOf` or `cherryPickOf`, even in deep mode. Whether the origin commit is a revert or a cherry-pick is a
+// property of that commit, not of which walk found it, so a deep-mode result is annotated the same way wherever it was resolved.
+// Standard mode is unchanged (the detection costs git processes, which is what the mode exists to make optional).
+function annotateNonLinear(scanRoot, origin, sha, candidates, mode) {
+  if (mode !== 'deep') return origin;
+  const { isRevert, revertsCommit } = detectRevert(scanRoot, sha, candidates);
+  const { isCherryPick, originalCommit } = detectCherryPick(scanRoot, sha);
+  origin.revertOf = isRevert ? revertsCommit : null;
+  origin.cherryPickOf = isCherryPick ? originalCommit : null;
+  return origin;
+}
+
 function originFrom(meta, { absentInParents }) {
   return {
     commit: meta.commit, authorName: meta.authorName, authorEmail: meta.authorEmail,
@@ -283,7 +297,7 @@ export async function resolveOrigin(scanRoot, finding, { since, deadlineAt, repo
       // and confidence.js will cap this at MEDIUM.
       return {
         status: 'complete', method: PROVENANCE_METHOD.SEMANTIC_REPLAY, commitsConsidered,
-        findingOrigin: originFrom(meta, { absentInParents: [] }),
+        findingOrigin: annotateNonLinear(scanRoot, originFrom(meta, { absentInParents: [] }), sha, candidates, mode),
         parentBoundaryVerified: false,
       };
     }
@@ -304,7 +318,7 @@ export async function resolveOrigin(scanRoot, finding, { since, deadlineAt, repo
 
     return {
       status: 'complete', method: PROVENANCE_METHOD.SEMANTIC_REPLAY, commitsConsidered,
-      findingOrigin: originFrom(meta, { absentInParents: [parent] }),
+      findingOrigin: annotateNonLinear(scanRoot, originFrom(meta, { absentInParents: [parent] }), sha, candidates, mode),
       parentBoundaryVerified: true, absenceEvidence: presentInParent.reason,
     };
   }

package/src/posture/provenance/providers/github.js

@@ -23,7 +23,10 @@ export async function fetchPRMetadata(scanRoot, commitSha, remoteUrl, config) {
       headers: { Authorization: `Bearer ${config.token}`, Accept: 'application/vnd.github+json' },
       signal: AbortSignal.timeout(8000),
     });
-    if (!r.ok) return null;
+    // GA-05 (0.195.27): a provider that answered with an error, or did not answer, is reported as UNAVAILABLE, which the
+    // coordinator records as a limitation on the finding. It is a different fact from "no pull request names this commit"
+    // (null), and folding the two together hid every outage, bad token and wrong base URL behind an empty enrichment.
+    if (!r.ok) return { unavailable: true, reason: `http-${r.status}` };
     const prs = await r.json();
     if (!Array.isArray(prs) || prs.length === 0) return null;
     const pr = prs[0];
@@ -33,8 +36,8 @@ export async function fetchPRMetadata(scanRoot, commitSha, remoteUrl, config) {
       approvals: null, // GitHub's PR-list-by-commit endpoint doesn't include review state; a real approvals count needs a second call, deliberately not made here to keep this a single-request enrichment.
       mergedAt: pr.merged_at || null,
     };
-  } catch {
-    return null;
+  } catch (e) {
+    return { unavailable: true, reason: e && e.name === 'TimeoutError' ? 'timeout' : 'network' };
   }
 }
 

package/src/posture/provenance/providers/gitlab.js

@@ -21,7 +21,9 @@ export async function fetchPRMetadata(scanRoot, commitSha, remoteUrl, config) {
       headers: { 'PRIVATE-TOKEN': config.token },
       signal: AbortSignal.timeout(8000),
     });
-    if (!r.ok) return null;
+    // GA-05 (0.195.27): an error reply or no reply is UNAVAILABLE (recorded as a limitation by the coordinator), which is a
+    // different fact from "no merge request names this commit" (null). See providers/github.js for the reasoning.
+    if (!r.ok) return { unavailable: true, reason: `http-${r.status}` };
     const mrs = await r.json();
     if (!Array.isArray(mrs) || mrs.length === 0) return null;
     const mr = mrs[0];
@@ -31,8 +33,8 @@ export async function fetchPRMetadata(scanRoot, commitSha, remoteUrl, config) {
       approvals: typeof mr.upvotes === 'number' ? mr.upvotes : null,
       mergedAt: mr.merged_at || null,
     };
-  } catch {
-    return null;
+  } catch (e) {
+    return { unavailable: true, reason: e && e.name === 'TimeoutError' ? 'timeout' : 'network' };
   }
 }
 

package/src/posture/reachability-filter.js

@@ -25,12 +25,12 @@ const SEVERITY_DEMOTE = {
 // keeps full severity. route-reachable-via-function and function-reachable
 // both keep full severity because the vulnerable function is provably
 // called; import-reachable also keeps full severity (imported = uncertain
-// but plausible). The lower three tiers get demoted.
+// but plausible). manifest-only and transitive-only record only that no use was
+// observed, which is unknown reachability, and unknown reachability cannot lower
+// severity (PRD FR 08). Only positive evidence (unreachable, build-only) demotes.
 const DEMOTE_SCA_TIERS = new Set([
   'unreachable',       // function never called from project
   'build-only',        // dev/build-time dependency only
-  'manifest-only',     // declared, but no use observed
-  'transitive-only',   // transitive dep, scope unclear
 ]);
 
 export function demoteUnreachable(findings, opts = {}) {

package/src/posture/rule-compiler/cli.js

@@ -11,8 +11,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { statePath } from '../state-dir.js';
-import { packTrust, signPublishedRule } from './store.js';
-import { sharedFalsePositiveCorpus, falsePositiveHits, regressRules, promotedRuleIds } from './regression.js';
+import { packTrust, signPublishedRule, publicKeyOf } from './store.js';
+import { sharedFalsePositiveCorpus, falsePositiveHits, regressRules, promotedRuleIds, corpusHash } from './regression.js';
 import { draftRuleIR, validateRuleIR, ruleIRDigest } from './ir.js';
 import { checkEligibility } from './eligibility.js';
 import { buildCorpus } from './corpus.js';
@@ -39,7 +39,7 @@ export async function cmdRules(args, root) {
   const sub = args._[1];
   // GA-07: a ledger that failed its integrity check (broken chain, bad or missing signature) refuses EVERY command, not only the
   // ones that change state; nothing below can read a tampered history as fact or write over it.
-  if (['synthesize', 'evaluate', 'promote', 'status', 'rollback', 'cost', 'regress'].includes(sub)) {
+  if (['synthesize', 'evaluate', 'promote', 'status', 'rollback', 'deprecate', 'cost', 'regress'].includes(sub)) {
     const guard = loadLedger(root);
     if (guard.tampered) { console.error(`Refusing: rule lifecycle ledger failed its integrity check (${guard.tamperReason}).`); return 4; }
   }
@@ -48,12 +48,25 @@ export async function cmdRules(args, root) {
   if (sub === 'promote') return cmdPromote(args, root);
   if (sub === 'status') return cmdStatus(args, root);
   if (sub === 'rollback') return cmdRollback(args, root);
+  if (sub === 'deprecate') return cmdDeprecate(args, root);
   if (sub === 'cost') return cmdCost(args, root);
   if (sub === 'regress') return cmdRegress(args, root);
-  console.error('usage: rules synthesize <finding-id> --spec <file.json> [--auto] [--max-attempts N] | evaluate <rule-id> | promote <rule-id> --reviewed-by <person> [--scope <text>] | status [rule-id] | rollback <rule-id> | cost <rule-id> | regress [rule-id]');
+  console.error('usage: rules synthesize <finding-id> --spec <file.json> [--auto] [--max-attempts N] | evaluate <rule-id> | promote <rule-id> --reviewed-by <person> --scope <text> [--sign-key <base64>] | status [rule-id] | rollback <rule-id> | deprecate <rule-id> | cost <rule-id> | regress [rule-id]');
   return 4;
 }
 
+/** The operator's Ed25519 key, when given: it signs the published rule AND the ledger, so a clone without this install's HMAC key can
+ * still verify the lifecycle history (store.js loadLedger). Never stored. */
+function authorKeyFrom(args) { return args.flags['sign-key'] ?? process.env.AGENTIC_SECURITY_PRIVATE_KEY ?? null; }
+
+/** Every command that changes the ledger saves it through here, so an author signature made at promotion is renewed by a later
+ * rollback or evaluation run with the same key instead of going stale (a stale one would read as tampering on the next clone). */
+function persistLedger(root, ledger, args) {
+  const r = saveLedger(root, ledger, { authorKey: authorKeyFrom(args) });
+  if (!r.ok && r.reason) console.error(r.reason);
+  return r;
+}
+
 // `--spec` carries exactly what a model or a human proposed: id/title/severity/cwe/family/languages/match/
 // remediation plus the corpus inputs (originalCode/patchedCode/nearbyCleanCode/protectedVariantsCode). This
 // command never invents a pattern; it only drafts the IR, checks eligibility and records DRAFT->CANDIDATE.
@@ -86,10 +99,16 @@ async function cmdSynthesize(args, root) {
   if (errs.length) { console.error(`Invalid rule: ${errs.join('; ')}`); return 4; }
 
   const ledger = loadLedger(root);
-  const draft = recordTransition(ledger, { ruleId: ir.id, from: null, to: 'DRAFT', reason: `drafted from ${findingId}`, actor: args.flags.actor || 'agent' });
-  if (!draft.ok) { console.error(draft.reason); return 4; }
-  const cand = recordTransition(ledger, { ruleId: ir.id, from: 'DRAFT', to: 'CANDIDATE', reason: 'eligibility passed', evidence: { eligibility: elig }, actor: args.flags.actor || 'agent' });
-  saveLedger(root, ledger);
+  // GA-07 (0.195.27): a rule that was rolled back re-enters as a CANDIDATE (the ledger's ROLLED_BACK -> CANDIDATE edge), keeping its
+  // history; any other existing state refuses, so a promoted or validated rule cannot be silently re-drafted over.
+  const current = stateOf(ledger, ir.id);
+  if (current !== null && current !== 'ROLLED_BACK') { console.error(`Rule ${ir.id} already exists in state ${current}; roll it back first, or choose another id.`); return 4; }
+  if (current === null) {
+    const draft = recordTransition(ledger, { ruleId: ir.id, from: null, to: 'DRAFT', reason: `drafted from ${findingId}`, actor: args.flags.actor || 'agent' });
+    if (!draft.ok) { console.error(draft.reason); return 4; }
+  }
+  const cand = recordTransition(ledger, { ruleId: ir.id, from: current === null ? 'DRAFT' : 'ROLLED_BACK', to: 'CANDIDATE', reason: current === null ? 'eligibility passed' : `re-entered after rollback; eligibility passed (drafted again from ${findingId})`, evidence: { eligibility: elig }, actor: args.flags.actor || 'agent' });
+  persistLedger(root, ledger, args);
   saveIR(root, { ...ir, state: 'CANDIDATE' });
   saveCorpus(root, ir.id, { ...corpusSpec, fileNames: spec.fileNames ?? [], discoveryCost: spec.discoveryCost ?? (args.flags['discovery-cost-usd'] ? { usd: Number(args.flags['discovery-cost-usd']), tokens: Number(args.flags['discovery-tokens']) || null, model: spec.model ?? null } : null) });
   if (synthesis) saveSynthesis(root, ir.id, { attempts: synthesis.attempts, best: synthesis.best });
@@ -119,9 +138,8 @@ async function cmdEvaluate(args, root) {
   if (fpHits.length) { gate.pass = false; gate.reasons.push(`fires on ${fpHits.length} of ${fpItems.length} item(s) in the shared false-positive corpus: ${fpHits.slice(0, 3).map((h) => h.label).join(', ')}${fpHits.length > 3 ? ', ...' : ''}`); }
   const cur = stateOf(ledger, id);
   if (gate.pass && cur === 'CANDIDATE') recordTransition(ledger, { ruleId: id, from: 'CANDIDATE', to: 'VALIDATED', reason: 'promotion gate passed', evidence: { score: gate.evaluation.score }, actor: args.flags.actor || 'agent' });
-  saveLedger(root, ledger);
+  persistLedger(root, ledger, args);
   saveEvaluation(root, id, gate);
-  const corpusHash = (list) => sha256(JSON.stringify(list.map((x) => [x.label, x.code]).sort()));
   const prev = loadProvenance(root, id);
   saveProvenance(root, id, {
     schema: 'agentic-security/rule-provenance', version: 1, ruleId: id, ruleVersion: 1, ruleHash: ruleIRDigest(ir),
@@ -159,7 +177,13 @@ async function cmdPromote(args, root) {
   if (!id) { console.error('usage: rules promote <rule-id> --reviewed-by <person> [--scope <text>] [--reason <text>]'); return 4; }
   const reviewer = args.flags['reviewed-by'];
   if (!isStr(reviewer) || NOT_A_REVIEWER.test(reviewer.trim())) {
-    console.error('usage: rules promote <rule-id> --reviewed-by <person>. A promotion records the person who reviewed the rule and its scope; a model or agent recommendation is not a review, so nothing is promoted without a named reviewer.');
+    console.error('usage: rules promote <rule-id> --reviewed-by <person> --scope <text>. A promotion records the person who reviewed the rule and its scope; a model or agent recommendation is not a review, so nothing is promoted without a named reviewer.');
+    return 4;
+  }
+  // GA-07 §3 (0.195.27): the reviewed SCOPE (what the rule is for, where it applies, what it must not flag) is part of the review
+  // record, not an optional note; a promotion without one records nothing a later reader could hold the rule to.
+  if (!isStr(args.flags.scope)) {
+    console.error('usage: rules promote <rule-id> --reviewed-by <person> --scope <text>. The reviewed scope is recorded with the promotion; state what the rule covers and where it applies.');
     return 4;
   }
   const ledger = loadLedger(root);
@@ -196,16 +220,32 @@ async function cmdPromote(args, root) {
   if (fpNow.length) { console.error(`Promotion refused: ${id} fires on ${fpNow.length} item(s) of the shared false-positive corpus (${fpNow.slice(0, 3).map((h) => h.label).join(', ')}). Re-evaluate or narrow the rule.`); return 1; }
   const pub = publishCustomRule(root, ir);
   if (!pub.ok) { console.error(`Promotion refused: ${pub.reason}`); return 4; }
-  const scope = isStr(args.flags.scope) ? args.flags.scope : null;
-  const review = { reviewer: reviewer.trim(), scope, independent: prov.benchmarkResults?.independent ?? null };
-  const t = recordTransition(ledger, { ruleId: id, from: 'VALIDATED', to: 'PROMOTED', reason: args.flags.reason || 'promoted', evidence: review, actor: args.flags.actor || reviewer.trim() });
-  saveLedger(root, ledger);
-  saveProvenance(root, id, { ...prov, promotionEvent: { at: new Date().toISOString(), actor: args.flags.actor || reviewer.trim(), reviewer: reviewer.trim(), scope, reason: args.flags.reason || 'promoted', ruleHash: ruleIRDigest(ir) } });
+  const scope = args.flags.scope.trim();
+  // GA-07 §3 (0.195.27): the evidence the reviewer looked at, digested into the promotion: the evaluation and provenance records
+  // as they stood, and the two corpus halves. `rules regress` re-derives the corpus digests and reports a rule whose corpus moved
+  // after the review as no longer the reviewed one.
+  const corpusNow = buildCorpus(ir, loadCorpus(root, id) ?? {});
+  const evidence = {
+    reviewer: reviewer.trim(), scope, independent: prov.benchmarkResults?.independent ?? null, ruleHash: ruleIRDigest(ir),
+    evaluationDigest: sha256(JSON.stringify(readJsonArg(path.join(statePath(root, 'rule-compiler', id), 'evaluation.json')))),
+    provenanceDigest: sha256(JSON.stringify({ ...prov, promotionEvent: undefined })),
+    positiveCorpusHash: corpusHash(corpusNow.positives), negativeCorpusHash: corpusHash(corpusNow.negatives),
+    sharedFalsePositiveItems: sharedFalsePositiveCorpus(root, ledger, id).length,
+  };
+  const t = recordTransition(ledger, { ruleId: id, from: 'VALIDATED', to: 'PROMOTED', reason: args.flags.reason || 'promoted', evidence, actor: args.flags.actor || reviewer.trim() });
+  const saved = persistLedger(root, ledger, args);
+  saveProvenance(root, id, { ...prov, promotionEvent: { at: new Date().toISOString(), actor: args.flags.actor || reviewer.trim(), reviewer: reviewer.trim(), scope, reason: args.flags.reason || 'promoted', ruleHash: ruleIRDigest(ir), evidence } });
   console.log(`Rule ${id}: VALIDATED -> PROMOTED. Published to ${pub.file}.`);
   // Publishing is not trusting. Rule packs are signature-checked so a rule dropped into a repository cannot run in someone's CI; sign this
-  // one with the operator's key when there is one, and say plainly whether the scanner will load it.
-  const key = args.flags['sign-key'] ?? process.env.AGENTIC_SECURITY_PRIVATE_KEY;
-  if (key) { const sg = signPublishedRule(pub.file, key); console.log(sg.ok ? `  signed: ${pub.file}.sig` : `  could not sign (${sg.reason}); the rule is published unsigned`); }
+  // one with the operator's key when there is one, and say plainly whether the scanner will load it. The same key author-signs the
+  // ledger, which is what lets `rules regress` on another machine (CI) verify the history without this install's HMAC key.
+  const key = authorKeyFrom(args);
+  if (key) {
+    const sg = signPublishedRule(pub.file, key); console.log(sg.ok ? `  signed: ${pub.file}.sig` : `  could not sign (${sg.reason}); the rule is published unsigned`);
+    console.log(saved.authorSigned ? `  ledger author-signed; another machine verifies it with AGENTIC_SECURITY_RULES_PUBLIC_KEY=${publicKeyOf(key)}` : '  ledger NOT author-signed; rules regress on another machine will refuse it');
+  } else {
+    console.log('  no --sign-key: the ledger carries only this install\'s signature, so rules regress on another machine (CI) will refuse it; promote with --sign-key <base64> to make it portable');
+  }
   const trust = packTrust(root, id);
   console.log(trust.live ? `  The scanner will load it (${trust.via}).` : `  NOT LIVE YET: the scanner will refuse this rule (${trust.reason}). To make it live: ${trust.remediation}.`);
   if (!t.ok) console.error(t.reason);
@@ -218,9 +258,10 @@ async function cmdRegress(args, root) {
   if (ledger.tampered) { console.error(`Refusing: rule lifecycle ledger failed its integrity check (${ledger.tamperReason}).`); return 4; }
   const only = args._[2] ?? null;
   const results = regressRules(root, ledger, { only, thresholds: args.flags.thresholds ? readJsonArg(args.flags.thresholds) : undefined });
-  if (args.flags.json) console.log(JSON.stringify({ results }, null, 2));
+  if (args.flags.json) console.log(JSON.stringify({ ledgerVerifiedBy: ledger.verifiedBy ?? null, results }, null, 2));
   else if (!results.length) console.log(only ? `No promoted rule ${only}.` : 'No rule is PROMOTED; nothing to regress.');
   else for (const r of results) { console.log(`${r.id}: ${r.status.toUpperCase()}${r.precision != null ? `  precision ${fmtPct(r.precision)}  recall ${fmtPct(r.recall)}  false-positive corpus hits ${r.fpCorpusHits}` : ''}`); for (const m of r.reasons) console.log(`  - ${m}`); }
+  if (!args.flags.json && results.length) console.log(`ledger verified by ${ledger.verifiedBy === 'author-key' ? `the author key (${ledger.authorKeyId})` : ledger.verifiedBy === 'install-key' ? 'this install\'s key' : 'nothing (unsigned, accepted by AGENTIC_SECURITY_RULES_UNSIGNED=1)'}`);
   if (only && !results.length) return 4;
   return results.every((r) => r.status === 'ok') ? 0 : 1;
 }
@@ -233,11 +274,25 @@ async function cmdRollback(args, root) {
   if (cur !== 'PROMOTED') { console.error(`Rule ${id} is not PROMOTED (current: ${cur ?? 'unknown'}); nothing to roll back.`); return 4; }
   const un = unpublishCustomRule(root, id);
   const t = recordTransition(ledger, { ruleId: id, from: 'PROMOTED', to: 'ROLLED_BACK', reason: args.flags.reason || 'operator rollback', actor: args.flags.actor || 'operator' });
-  saveLedger(root, ledger);
+  persistLedger(root, ledger, args);
   console.log(`Rule ${id}: PROMOTED -> ROLLED_BACK.${un.ok ? '' : ` (warning: could not remove published rule file: ${un.reason})`}`);
   return t.ok ? 0 : 1;
 }
 
+/** `rules deprecate <rule-id>`: retire a promoted rule for good (PROMOTED -> DEPRECATED, a terminal state); the published file is removed. */
+async function cmdDeprecate(args, root) {
+  const id = args._[2];
+  if (!id) { console.error('usage: rules deprecate <rule-id> [--reason text]'); return 4; }
+  const ledger = loadLedger(root);
+  const cur = stateOf(ledger, id);
+  if (cur !== 'PROMOTED') { console.error(`Rule ${id} is not PROMOTED (current: ${cur ?? 'unknown'}); only a promoted rule can be deprecated (roll back a candidate instead).`); return 4; }
+  const un = unpublishCustomRule(root, id);
+  const t = recordTransition(ledger, { ruleId: id, from: 'PROMOTED', to: 'DEPRECATED', reason: args.flags.reason || 'operator deprecation', actor: args.flags.actor || 'operator' });
+  persistLedger(root, ledger, args);
+  console.log(`Rule ${id}: PROMOTED -> DEPRECATED (terminal).${un.ok ? '' : ` (warning: could not remove published rule file: ${un.reason})`}`);
+  return t.ok ? 0 : 1;
+}
+
 async function cmdStatus(args, root) {
   const ledger = loadLedger(root);
   const id = args._[2];