feat(scan): add --fail-on-epss CI gate

[vibgrate-team]

Summary

vg scan --fail-on-epss <threshold> exits 2 when any advisory from --vulns or --full has an EPSS score at or above the threshold. The threshold is a probability from 0 to 1. A score equal to the threshold fails.

A missing score is not compared, and it is not treated as 0. A present 0 is a real score: --fail-on-epss 0 fails on it, and --fail-on-epss 0.01 does not. The gate reads scores already on the advisories. It does not contact an EPSS service. Offline and --package-manifest scans use the scores in that bundle.

When there is no score to compare — vulnerability detection was not requested, the advisory feed could not be reached, or every advisory omitted epss — the command prints EPSS is absent; --fail-on-epss <threshold> was not compared. and exits 0. A vulnerability pass that ran and found no advisories passes.

A value that is not a number, or a number outside 0 to 1, stops the command before the scan with exit 1 and error: --fail-on-epss must be a number from 0 to 1.

failOnEpss in .vibgrate/config.yml or vibgrate.config.json is the same threshold. Passing --fail-on-epss replaces it. A config value of the wrong type stops the scan and names the key. The failure line does not include the rejected value.

The failure line is Failing: N advisory/advisories at or above EPSS <threshold>. Matching advisories are listed on stderr. --fail-on runs first, then this gate, then --drift-budget and --drift-worsening. With --junit, the gates suite includes a fail-on-epss case: a <failure> on a breach, a <skipped> case when no score was compared, and a passing case when every compared score is below the threshold. The XML is written, then the process exits 2.

Related issues

Fixes #420

Checklist

• pnpm test passes
• pnpm lint is clean
• pnpm typecheck is clean
• Docs updated (README / DOCS / ARCHITECTURE) where behavior changed
• Determinism preserved — identical input still produces identical graph.json / report output (content-hashed IDs, stable sorts; no time, randomness, or filesystem-order dependence)
• No proprietary or internal references — public, Apache-2.0 content only
• Commits use Conventional Commits and are signed off (git commit -s, DCO)

Notes for reviewers

Covered by src/reporting/epss-gate.test.ts and src/reporting/commands/scan-epss-gate.test.ts (offline manifest, no network). A bad flag exits 1 (ERROR) before the scan.