Add resumable single-case CLI trial with telemetry and Vcore import

docs/first-llm-trial.md

@@ -0,0 +1,117 @@
+# Erster LLM-Test
+
+Der einmalige Testtreiber verbindet vorhandene Komponenten. Er ist kein Daemon:
+genau ein Fall, begrenzte Dispatches, keine Hintergrund-Wiederholungen, keine
+automatische Wiederaufnahme blockierter Fälle. Architektur und Projektcode bleiben
+unverändert. Die bekannte Fehlerlösung gehört nicht in Eingaben oder Prompts.
+
+## Vorbereitung in PowerShell
+
+Alle Befehle aus dem Repository-Hauptverzeichnis ausführen, nicht aus `config/`.
+Python 3.11+ und die installierte Projektumgebung werden vorausgesetzt. Die lokale
+Datei `config/llm.local.toml` muss existieren; API-Schlüssel kommen ausschließlich
+aus den darin benannten Umgebungsvariablen. Das Programm muss aus der PowerShell
+mit diesen Variablen gestartet werden. Es lädt keine `.env` automatisch.
+
+```powershell
+.\.venv\Scripts\python.exe -m viano_bug_analysis.trial check
+```
+
+`CONFIG_READY` bestätigt gültige Konfiguration und vorhandene Schlüssel aller
+aktivierten, zulässigen Anbieter. Es prüft keine Erreichbarkeit, Modellfreigabe,
+Abrechnung oder JSON-Kompatibilität. Es sendet keine Netzwerkanfrage und gibt
+keine Schlüssel aus. Ohne API-Key erscheint `LLM_CREDENTIALS`.
+
+Import des Beispielpaars ohne LLM:
+
+```powershell
+.\.venv\Scripts\python.exe -m viano_bug_analysis.trial prepare --workspace service-data --wowdiag "C:/Users/User/Desktop/Cata Bug fixes/BUG-000020-20261008-130429.tar.gz" --wowsrc "C:/Users/User/Desktop/Cata Bug fixes/WOWSRC-BUG-000020-20261008-130446.tar.gz" --case-id BUG-000020 --package-id trial-BUG-000020
+```
+
+Die Ausgabe `PREPARED` nennt den vollständigen `package`-Pfad in
+`service-data/inbox/`. IDs werden explizit vergeben; Dateinamen liefern keine
+Identität. Ohne `--package-id` entsteht eine UUID. Identische erneute Vorbereitung
+überschreibt keine vorhandene Datei. `service-data/` und `config/*.local.toml`
+sind durch Git ausgeschlossen. Originalarchive bleiben unverändert.
+
+## Echte Verarbeitung
+
+Nur dieser Schritt kann kostenpflichtige LLM-Aufrufe auslösen und bei
+`cloud_allowed` zusammengestellte Falldaten an Cloud-Dienste senden:
+
+```powershell
+.\.venv\Scripts\python.exe -m viano_bug_analysis.trial run --workspace service-data --package "VOLLSTAENDIGER_PACKAGE_PFAD_AUS_PREPARED"
+```
+
+Der erste Lauf validiert die Inbox-Datei, sichert den Original-ZIP im Cache und
+übernimmt ihn in die verwalteten Generationen. Nach bestätigter Aufnahme wird
+die Inbox-Datei quittiert. Andere Inbox-Dateien werden nicht verarbeitet.
+Phase und Dispatchnummer erscheinen auf stderr; das finale JSON auf stdout
+enthält Identität, Zustand, Generation, Routing und ggf. Export-/Retry-Pfad.
+
+Für den ersten Verbindungstest `--max-dispatches 2` ergänzen: Bei einem frischen
+Paket wird der Case deterministisch gebaut und anschließend die Interpretation
+angefragt. Bei Erfolg endet dieser kurze Lauf mit `YIELDED`. Anschließend mit
+den stabilen IDs weiterarbeiten. Bereits bestätigte Schritte werden wiederverwendet.
+
+Nach Aufnahme mit der stabilen Identität fortsetzen:
+
+```powershell
+.\.venv\Scripts\python.exe -m viano_bug_analysis.trial run --workspace service-data --case-id BUG-000020 --package-id trial-BUG-000020
+```
+
+Ein Prozess führt standardmäßig höchstens 100 Dispatches aus. Das ist eine
+konfigurierbare Testlaufgrenze (`--max-dispatches`), kein neues Hypothesenbudget
+und keine Geldgrenze. Investigation macht einen kontrollierten Schritt pro
+Dispatch. Die bestehenden Hypothesenbudgets und Iterationsgrenzen gelten weiter.
+Bei `YIELDED` setzt derselbe Resume-Befehl die Analyse fort.
+
+`RETRY_PENDING`/`DEFERRED` beendet den Lauf sofort mit dem frühesten nächsten
+Zeitpunkt. Nach diesem Zeitpunkt denselben Resume-Befehl ausführen. Kein Sleep
+oder automatischer Neustart: zehn Provider-Runden benötigen wiederholte fällige
+Dispatches. `BLOCKED` bleibt blockiert, auch wenn eine Frist vergeht. Externe
+Testanfragen erhalten ihre Reservierungen; die spätere bestätigte Feedback-
+Integration ist für deren Wiederaufnahme zuständig.
+
+Interpretation/Hypothesen mit ungültiger Antwort werden kontrolliert gestoppt.
+Ein bewusst neuer Versuch kann mit `--attempt-id NEUE-STABILE-ID` erfolgen,
+ohne eine gespeicherte alte Antwort unter derselben Operation zu überschreiben.
+Dies ist kein automatischer Retry und kann erneut Kosten verursachen. Die
+späteren Phasen behalten ihre bestehenden Grenzen für ungültige Antworten.
+Keine automatische neue Analysis Revision oder Budgetzurücksetzung findet statt.
+
+Optionale Konfigurationspfade: `--analysis-config`, `--budget-config`,
+`--investigation-config`, `--diagnosis-config`, `--change-request-config`,
+`--telemetry-config`, `--llm-config`. Ohne Pfade gelten die bestehenden Defaults.
+Bereits eingefrorene Policies nicht zwischen Resume-Läufen ändern; dieselben
+Optionen erneut angeben. Der gesamte Gateway-Konfigurationsfingerprint ist Teil
+der Operation; Änderungen können kontrolliert als Konflikt abgelehnt werden.
+
+## Ergebnis und Diagnose
+
+- `OUTPUT_READY`: validiertes ZIP mit Diagnose und Coding-Auftrag in `outbox/`.
+- `REVIEW`: validiertes ZIP mit Untersuchungsbericht in `review/`; kein Coding-Auftrag.
+- `BLOCKED`: langlebiger verwalteter Fall; Grund und Budgets bleiben erhalten.
+- `YIELDED`, `RETRY_PENDING`, `DEFERRED`, `REJECTED`: kontrollierter Zwischenstand.
+- `ERROR`/`QUARANTINED`: Fehlercode und ggf. Quarantäne-Diagnose prüfen.
+
+Exitcodes: 0 für erfolgreiche Vorbereitung/Prüfung/lokale Ausgabe, 3 für einen
+Zwischen-/Wartezustand, 2 für Fehler, 130 für Abbruch mit Ctrl+C. Ein Review ist
+ein erfolgreiches kontrolliertes Analyseergebnis, kein bewiesener Fix.
+
+```powershell
+.\.venv\Scripts\python.exe -m viano_bug_analysis.telemetry status --workspace service-data
+.\.venv\Scripts\python.exe -m viano_bug_analysis.telemetry errors --workspace service-data
+.\.venv\Scripts\python.exe -m viano_bug_analysis.telemetry events --workspace service-data
+```
+
+Logs, Status und Prometheus-Text liegen in `service-data/runtime/telemetry/`.
+`STOPPED` nach einem beendeten Testlauf ist normal. Stack-Diagnosen enthalten
+keine freien Exceptiontexte, Prompts oder Schlüssel. Der Treiber bleibt bei
+kontrollierten Fehlern ohne rohe Tracebacks. Fallartefakte enthalten hingegen
+die fachlichen LLM-Anfragen/-Antworten und sind entsprechend vertraulich.
+
+Vergleiche anschließend Diagnose, Evidenz und ggf. Änderungsauftrag mit der
+bekannten Fehlerlösung. Ein Live-Test beweist die Modellqualität noch nicht;
+insbesondere fehlende Sollinformationen oder nicht angeschlossene externe
+Research-/Tester-Dienste können zu Wartezuständen oder Review führen.