Add scenario suggest CLI for static-to-dynamic bridge

[pengfei-threemoonslab]

Summary

• New agents-shipgate scenario suggest --from <report.json> --out <scenarios.yaml> command turns static findings into deterministic adversarial scenario suggestions, one row per (scenario_type, tool) pair, traceable back to source findings.
• Closes the static-to-dynamic loop: every critical/high mapped finding gets at least one concrete sandbox scenario; --strict makes coverage holes a CI failure (exit 20).
• Extracts scenario_type_for_finding() from capability_diff._diff_spec() so the in-report grouping (apply_capability_diff) and the new YAML export share one predicate and cannot drift.

Type

• CLI or GitHub Action behavior
• Report, schema, or SARIF output (new YAML export — report.json schema unchanged)
• Documentation only (additive — STABILITY.md + AGENTS.md)

Verification

CI is authoritative for python -m ruff check ., python -m compileall -q src tests, and python -m pytest.

Additional local checks run:

• pytest tests/test_scenario_suggest.py -v — 13/13 passing
• pytest -q (full suite) — green, no regressions
• ruff check src/agents_shipgate tests/test_scenario_suggest.py — clean
• Smoke against samples/support_refund_agent/expected/report.json → 16 scenarios, --strict exit 0
• Smoke against samples/simple_openai_api_agent/expected/report.json → 12 scenarios, --strict exit 0 (the two unmapped SHIP-API-RETRY-WITHOUT-IDEMPOTENCY high findings are correctly excluded from the predicate, not silently swallowed — covered by test [codex] Implement v0.3 ADK and SARIF support #9)

Release-readiness notes

• No user-code import added to default scan paths
• No network access added to default scan paths
• New or changed check IDs are documented in docs/checks.md (no new check IDs — this command consumes existing findings)
• Report/schema changes are additive or documented in STABILITY.md (YAML envelope {scenarios, coverage_gaps?} documented as a 0.x stable contract; report.json schema unchanged)

Reviewer notes

• The coverage predicate is honest: findings whose scenario_type_for_finding() is None (e.g. SHIP-API-RETRY-WITHOUT-IDEMPOTENCY, currently in MISSING_CONTROL_CHECKS but absent from CHECK_DIFF_MAP) are explicitly outside the --strict predicate's scope. This is documented and tested rather than papered over.
• A latent gap surfaced by this work: adding SHIP-API-RETRY-WITHOUT-IDEMPOTENCY → idempotency_retry to CHECK_DIFF_MAP is a one-line follow-up, but it changes the baseline of which findings produce scenarios — better in its own PR.
• The golden YAML lives at tests/fixtures/scenario_suggest/support_refund_agent.expected.yaml. If wording in _ADVERSARIAL_GOAL_TEMPLATES or _scenario_text changes, regenerate via agents-shipgate scenario suggest --from samples/support_refund_agent/expected/report.json --out tests/fixtures/scenario_suggest/support_refund_agent.expected.yaml and review the diff.
• Exit code 20 reuses the existing strict-gate convention from STABILITY.md rather than inventing a new code.

🤖 Generated with Claude Code