feat(cli): add --fail-on flag to make the CI gate threshold configurable

[dmchaledev]

Summary

• The CLI's exit-code gate was hardcoded to fail only on D or F grades. Teams with stricter security policies had no way to fail a pipeline on a C (or better) without awkward workarounds like || true and manual grade checks.
• Adds a --fail-on <grade> flag that exits 1 when the result is at or below the specified grade threshold.
• Default is D, so existing pipelines are fully backward-compatible.

Usage

# Same as before — exits 1 on D or F (default)
security-headers https://staging.example.com

# Stricter gate: fail on C, D, or F
security-headers https://staging.example.com --fail-on C

# Fail on anything below A+
security-headers https://staging.example.com --fail-on A

# Invalid grade prints a clear error and exits 1
security-headers https://example.com --fail-on Z
# → Invalid --fail-on value: "Z". Valid grades: A+, A, B, C, D, F

Changes

• src/cli.ts: parse --fail-on, validate against the grade list, replace hardcoded D/F check with gradeAtOrBelow(report.grade, failOn)
• README.md: document the new flag with an example

Test plan

• All 82 existing tests pass (npm test)
• TypeScript compiles (pre-existing @types/node errors in cli.ts are unrelated — typecheck was failing before this PR on the same lines)
• Manual: --fail-on C exits 1 on a C-graded site, 0 on a B-graded site
• Manual: invalid grade value prints error and exits 1
• Manual: omitting --fail-on behaves identically to before

https://claude.ai/code/session_01PT1hTSyhxp3S3pjWUmxwvA

---

Generated by Claude Code