Add durable bounded corrections for early LLM phases and validated review

docs/early-correction-v1.md

@@ -0,0 +1,95 @@
+# Begrenzte Korrektur früher LLM-Antworten
+
+Der Testtreiber aktiviert Korrekturen standardmäßig für Interpretation und
+Hypothesengenerierung. Bibliotheksaufrufe können `correction_config=CorrectionConfig()`
+übergeben. Bestehende direkte Aufrufe ohne diese Option behalten ihr bisheriges
+Verhalten; eine bereits gespeicherte Korrektur-Policy wird automatisch übernommen.
+Bestätigte alte Ergebnisse bleiben unverändert wiederverwendbar.
+
+```toml
+[correction]
+max_invalid_responses = 3
+```
+
+Mit `--correction-config config/correction.local.toml` lässt sich die Grenze im
+Testtreiber konfigurieren. Sie wird beim ersten aktivierten Dispatch pro Phase
+und Analysis Revision eingefroren. Dieselbe Config bei Wiederaufnahme verwenden;
+nachträgliche Änderungen werden vor einem weiteren Modellaufruf abgelehnt.
+Die Beispielkonfiguration liegt in `config/correction.example.toml`.
+
+## Ablauf
+
+Ein Dispatch verarbeitet höchstens eine fällige Provider-Runde. Ungültige
+Modellantworten ergeben `REJECTED`. Der Testtreiber setzt mit dem nächsten Dispatch
+fort; `--max-dispatches 1` gibt stattdessen `YIELDED` zurück. Die nächste Anfrage
+enthält den ursprünglichen Context/Schema, einen festen Korrektur-Systemprompt,
+die verworfene JSON-Antwort (falls verfügbar) und deterministisches Feedback.
+
+Bei Quellenfehlern nennt das Feedback beispielsweise Feld, Source-ID, tatsächlichen
+Quellentyp und erlaubte Typen. Bei Hypothesen werden doppelte Titel/Mechanismen,
+ungültige Quellen, Mengen- und Grounding-Regeln erläutert. Für andere Fehler steht
+der kontrollierte Validierungscode mit allgemeinen Korrekturanforderungen zur
+Verfügung. Schema-/Transportfehler, deren verworfener Body nicht gespeichert wird,
+erhalten keine erfundene vorherige Antwort. Anbieter-Error-Bodies bleiben ausgeschlossen.
+
+Die vorherige Antwort ist untrusted candidate data; sie wird niemals zur neuen
+Faktengrundlage. Jede neue Antwort durchläuft wieder die vollständige Prüfung.
+Es gibt kein automatisches Entfernen falscher Quellen, keine Teilübernahme und
+kein Lockern der Quellenregeln. Hypothesen und Budgetkonten entstehen erst nach
+Annahme des vollständigen gültigen Hypothesensatzes.
+
+## Grenzen und Persistenz
+
+`max_invalid_responses` zählt ungültige Antworten, einschließlich des ersten
+Versuchs und früherer bestätigter Modellfehler in derselben Phase/Revision.
+Ein neuer Prozess oder eine andere `--attempt-id` setzt diesen Zähler nicht zurück.
+Bereits vorhandene fachliche Fehler werden bei Aktivierung anhand ihrer gebundenen
+LLM-Aufrufe übernommen; wiederholtes Lesen desselben Fehlers zählt nicht erneut.
+
+Policy und Dispatch-Beschreibung werden vor der Anfrage als unveränderliche
+Artefakte unter `analysis/interpretations/NNNN/corrections/` beziehungsweise
+`analysis/hypotheses/NNNN/corrections/` gespeichert. Stabile interne Versuchs-IDs
+trennen Modellkorrekturen. Provider-Retries innerhalb eines Versuchs verwenden
+dagegen dieselbe eingefrorene Anfrage und Operation, einschließlich ihres
+Konfigurationsfingerprints. Die Transportkonfiguration während eines ausstehenden
+Retries nicht wechseln. `--attempt-id` ist in diesem Modus kein manueller Reset.
+
+Provider-Ausfälle/Timeouts/Backoff verbrauchen keinen Modellfehler-Versuch. Sie
+behalten die bestehenden Regeln: `RETRY_PENDING`, `DEFERRED`, nach Ausschöpfung
+`BLOCKED`. Konfigurations-, Credential-, Größen- und Infrastrukturfehler werden
+nicht als fachliche Fehlantwort automatisch wiederholt. Ein Absturz zwischen
+Provider-Antwort und Speicherung kann weiterhin den unbestätigten Aufruf wiederholen.
+Ein gespeicherter Erfolg oder Fehler wird dagegen ohne erneuten Remote-Aufruf verarbeitet.
+
+Nach Ausschöpfung entsteht `FAILED_TO_ANALYZE/review` mit
+`MODEL_VALIDATION_EXHAUSTED`, Fehlerreferenzen, Context-Hash, offenen Fragen und
+empfohlenen menschlichen Aktionen. Das ist ein früher Fehlerbericht, kein erfundener
+Diagnosebericht. OutputValidator prüft seine Policy-, Context-, Fehler-/Call- und
+Checkpoint-Bindung sowie Input-Frische und veröffentlicht ein validiertes Review-ZIP.
+Es entstehen weder Diagnose noch Coding-Auftrag. Bereits vorhandene Budgets werden
+nicht geändert; neue Modelldispatches sind keine Investigation-Budgetbuchungen.
+LLM-Tokens/Anbieterkosten werden weiterhin separat durch Telemetrie erfasst.
+
+Der JSON-Vertrag ist `early-correction-v1.schema.json`. Originale, verworfene
+Antworten und ältere Generationen bleiben erhalten. Fall-ID, Paket-ID und
+Analysis Revision bleiben gleich; bestätigte Artefakte erhöhen package_generation.
+Korrekturartefakte sind nach Checkpoint deklarierte Analyseausgaben und werden
+nicht erneut als Rohinputs des CaseBuilders interpretiert. Unbekannte Dateien
+bleiben Rohinput und unverändert erhalten.
+
+## Fortsetzung des aktuellen BUG-20-Tests
+
+Die bisherige Historie enthält zwei fachlich abgelehnte Interpretationen. Mit
+der Default-Grenze von drei bleibt genau ein weiterer Modellfehler erlaubt.
+Provider-Ausfälle zählen dabei nicht. Der erste echte Korrekturversuch kann so
+aus der PowerShell mit API-Key gestartet werden:
+
+```powershell
+.\.venv\Scripts\python.exe -m viano_bug_analysis.trial run --workspace service-data --llm-config config/llm.timeout300.local.toml --case-id BUG-000020 --package-id trial-BUG-000020 --max-dispatches 1
+```
+
+Bei akzeptierter Interpretation endet dieser begrenzte Lauf mit `YIELDED` und
+vorhandenem Interpretationsartefakt. Bei erneut ungültiger Antwort veröffentlicht
+der Treiber Review. Mit derselben Config und mehr Dispatches kann eine erfolgreiche
+Interpretation anschließend zur Hypothesengenerierung und Untersuchung fortgesetzt werden.
+Es gibt keine automatische neue Revision oder Wiederaufnahme eines Review-Falls.