feat(completeness): add --incomplete-policy to control exit behavior on incomplete scan data

[luojiyin1987]

Summary

Add --incomplete-policy warn|error (default: warn) to control exit code when scan detection data is incomplete.

Behavior

Scenario	warn	error
Scan complete	normal	normal
Remediation gap	warning, normal exit	warning, normal exit
Detection gap	warning, normal --fail-on	EXIT_ERROR (3)

error only targets detection-impact incomplete data. Remediation gaps are never affected by this flag.

Changes

• src/types.ts — IncompletePolicy type, field on ParsedOptions
• src/cli/args.ts — default warn, parse --incomplete-policy warn|error
• src/cli/help.ts — help text + example
• src/scan/completeness.ts — shouldFailForIncompleteScan() helper
• src/index.ts — single-folder exit code
• src/scan/multi-folder-scan.ts — multi-folder exit code, shared aggregated completeness
• action.yml — incomplete-policy input (empty default for old CLI compat)
• tests/helpers.test.ts — updated expectations

Design decisions

• Ratchet unaffected. --ratchet detection gap check runs independently. incompletePolicy does not override it.
• EXIT_ERROR (3) over EXIT_FINDINGS (1). Incomplete scan is more severe than findings.
• Action backward compat. Empty default means old CLI versions don't see unknown args.

Closes #898

[luojiyin1987]

Addressed all three review items:

P1 — Behavioral tests (+16 tests, 1446 → 1462):

• tests/helpers.test.ts: 7 tests — default warn, parse warn/error, = form, invalid values throw
• tests/cli-integration.test.ts: 4 tests — detection+warn → exit 0, detection+error → EXIT_ERROR, remediation+error → exit 0, ratchet+detection+warn → still EXIT_ERROR
• tests/multi-folder-scan.test.ts: 5 tests — detection+warn → exit 0, detection+error → EXIT_ERROR, remediation+error → exit 0, multi-folder detection → EXIT_ERROR, ratchet+detection+warn → still EXIT_ERROR

P2 — Action fix step: Added INPUT_INCOMPLETE_POLICY env + conditional arg passing in the Apply security fixes step, so incomplete-policy: error applies to both the scan and the fix rescan.

P3 — Docs:

• website/docs/cli-reference.md: Added --incomplete-policy row in CI / Automation options table
• website/docs/workflow-integration.md: Added Fail closed on incomplete detection data subsection with CLI and GitHub Actions examples

[sonukapoor]

Hey @luojiyin1987, thanks for this - the completeness work you've done has been great. There's an existing PR (#941) for the same feature that has priority since it came first. I've asked that contributor to address the outstanding changes within the next 48 hours. If they don't respond we'll close #941 and come back to yours. Will keep you posted!

[luojiyin1987]

No worries at all — I'm not in a rush. Happy to wait and see how #941 goes. Thanks for keeping me posted! @sonukapoor

[sonukapoor]

Nice work on this one. I went through all the changed files and the logic is correct end-to-end.

A few things I verified explicitly: shouldFailForIncompleteScan() returns false immediately for anything that isn't "error", and it correctly delegates to getCompletenessImpact().hasDetectionGap - so remediation gaps are genuinely unaffected regardless of the policy setting. The ratchet path in index.ts exits well before the shouldFailForIncompleteScan check, so those two code paths are truly independent. Multi-folder aggregation via aggregateMultiFolderCompleteness() correctly sums detection diagnostics across all folders before the policy check fires, so a detection gap in any one subfolder propagates to the exit code.

Test coverage is solid - you hit all the meaningful combinations: detection gap + warn (exit 0), detection gap + error (exit 3), remediation gap + error (still exit 0), multi-folder detection gap + error (exit 3), and ratchet + detection gap + warn (exit 3 regardless of policy). Left a couple of small notes inline - neither is a blocker, just things worth a quick look.

[sonukapoor]

Merged - thank you @luojiyin1987! The --incomplete-policy work has been great throughout the whole completeness series.