feat: opt-in LLM root-cause surface (BYO-key, default OFF, findings-only)

[rlaope]

Summary

Adds an opt-in LLM root-cause surface that narrates the likely root cause from the existing deterministic doctor/GC findings. It is default OFF, bring-your-own-key, and findings-only — it never fabricates metrics, and the deterministic template output (explain/gcwhy/doctor) remains the default and the fallback.

Safety posture (the whole point)

• Default OFF. Disabled unless BOTH argus.llm.enabled=true (or ARGUS_LLM_ENABLED=true) and ARGUS_LLM_API_KEY are set.
• Zero network call when disabled. The gate lives in LlmRootCause; when not activatable, no provider is even constructed. A unit test asserts the provider factory never runs.
• BYO-key. The key is read only from the environment and is never persisted by Argus.
• Findings-only, no hallucinated metrics. The prompt payload is serialized purely from the structured Finding objects, and the system instruction explicitly forbids the model from inventing any number. A unit test feeds known findings and asserts every number in the prompt is a subset of the numbers in the findings.
• Deterministic output always wins. The deterministic findings are always printed first; the LLM block is clearly labelled advisory and appended alongside. If the feature is off or the call fails, a skip note prints and the deterministic findings stand on their own.
• No LLM SDK dependency. The real provider uses the JDK HttpClient against a provider-neutral OpenAI-compatible chat endpoint (ARGUS_LLM_ENDPOINT / ARGUS_LLM_MODEL override the defaults).

Surfaces

• argus doctor --rca — appends an advisory root cause after the health report.
• argus explain --llm --bundle=<snapshot.tar.gz> — offline path: reads findings out of a snapshot bundle, prints them deterministically, then appends the advisory.

Acceptance criteria & how verified

1. Findings → prompt serializer — FindingsPrompt.serialize/buildPrompt; deterministic output remains the default/fallback. ✅
2. Pluggable provider behind a gate — LlmProvider interface, HttpLlmProvider (JDK HttpClient, no SDK), LlmConfig gate. Unit test disabled_neverInvokesProvider asserts the provider is never constructed/invoked when disabled (also enabledWithoutKey_neverInvokesProvider). ✅
3. Findings-only guarantee — prompt_containsOnlyNumbersFromFindings: a stub captures the prompt and asserts its numbers are a subset of the findings' numbers; system instruction contains "do not invent". ✅
4. Advisory labelling + deterministic always shown — LlmAdvisoryRenderer labels the block advisory and prints after the deterministic findings. ✅
5. Offline bundle path — BundleFindings.fromBundle (JDK-only tar.gz reader). bundlePath_feedsFindingsToProvider exercises bundle → findings → prompt with a stub. ✅

Extra: providerFailure_fallsBackToFindings confirms a provider error is caught and the findings still flow through.

Tests & build (fresh)

• ./gradlew :argus-cli:test --tests 'io.argus.cli.llm.LlmRootCauseTest' → BUILD SUCCESSFUL, tests="6" skipped="0" failures="0" errors="0".
• ./gradlew :argus-cli:test (full CLI suite) → BUILD SUCCESSFUL.
• ./gradlew :argus-cli:fatJar → BUILD SUCCESSFUL (argus-cli-1.5.0-all.jar).
• Smoke test with the fatJar (no key set) confirmed default-OFF: deterministic findings print, advisory is skipped with the disabled note, no network.

i18n parity

8 new llm.rca.* keys added to all four locales (printf %s):

• messages_en.properties: 667 keys
• messages_ko.properties: 667 keys
• messages_ja.properties: 667 keys
• messages_zh.properties: 667 keys

🤖 Generated with Claude Code