Bound investigation prompts and paginate research evidence

docs/investigation-prompt-window-v1.md

@@ -0,0 +1,102 @@
+# Begrenztes Arbeitsfenster für die Hypothesenuntersuchung
+
+## Ziel und Geltungsbereich
+
+Normale Untersuchungsschritte sollen ungefähr 10.000 Zeichen umfassen. Kein
+Aufruf der Untersuchungsphase darf 20.000 Zeichen überschreiten. Das gilt auch
+für Initialabfragen, gemeinsame Startbewertungen, Checkpoints und Reparaturen.
+Caseinterpretation, Hypothesenplanung und finale Diagnose werden nicht gekürzt.
+Es gibt keine neue finanzielle Abbruchgrenze.
+
+Gezählt werden Unicode-Zeichen der System- und übrigen Nachrichten sowie des
+zusätzlich übertragenen Antwortschemas. Gecachte Inhalte zählen vollständig.
+Eine identische Schemaangabe, die Gemini lediglich aus der Nachricht in den
+Präfix verschiebt, wird bei der Vorprüfung nicht doppelt gezählt. Die Adapter
+prüfen anschließend den vollständigen logischen Providerinput, einschließlich
+Cachepräfix und gegebenenfalls nativem Antwortschema. JSON-HTTP-Escaping und
+Providerparameter wie Timeout oder Modellname sind keine Promptzeichen.
+Untersuchungsaufrufe speichern zusätzlich `outcome.prompt_size` mit Nachrichten-
+und konservativer Gesamtzeichenzahl, Richtwert und Obergrenze. Die tatsächliche
+Providerdarstellung wird nach der Cachepartition nochmals geprüft.
+
+Der Vorprüfung bleiben 1.500 Zeichen Reserve für Transportinstruktionen und
+Präfixrahmen. Der 10.000-Zeichen-Richtwert darf für benötigte aktuelle Ergebnisse
+überschritten werden, die harte Grenze niemals. Tokens und Denkarbeit lassen
+sich daraus nicht exakt ableiten; der kostenpflichtige Qualitätstest steht aus.
+
+## Darstellung und Validierung
+
+`config/investigation.bounded.toml` aktiviert `prompt_window_version = 1` mit
+schlanker Schleife v2 und gemeinsamer Startbewertung. Die Policy wird für eine
+neue Analyserevision eingefroren. Bereits gespeicherte Kontexte und Requests
+werden nicht umgeschrieben. Alte Presets bleiben für reproduzierbare lokale
+Vergleiche erhalten; übergroße alte Anfragen werden von der allgemeinen
+Sicherheitsprüfung vor dem Provideraufruf abgelehnt.
+
+Das Arbeitsfenster enthält die aktuelle Hypothese, beobachtetes/erwartetes
+Verhalten, relevante Entities, den Arbeitsstand und benötigte Ergebnisfenster.
+Interne Source-Konfiguration, Provenienzverwaltung und Budgetbuchhaltung werden
+nicht ständig mitübertragen. Die Werkzeugprofile bleiben mit Namen und Zweck
+sichtbar. Die vollständigen Ausführungsregeln und Bindungen bleiben im Controller.
+
+Der strenge Antwort-/Werkzeugvertrag wird einmal in kompakter struktureller
+Notation beschrieben: Pflichtfelder, optionale Felder, Alternativen, Typen,
+Enums und Arraygrenzen. Das Provider-Schema prüft die äußere Form; anschließend
+gelten weiterhin die vollständigen lokalen Schema-, Referenz-, Parameter- und
+Zustandsprüfungen. Die kompakte Darstellung autorisiert keine weiteren Aktionen.
+Unklare oder erfundene Aktionen/Belege werden weiterhin abgelehnt.
+
+Der Cache kann den festen Vertrag und den gezielten Fallkontext verlustfrei
+auslagern; der vollständige rekonstruierte Input muss dieselbe Grenze einhalten.
+Kurze Präfixe können unterhalb anbieterseitiger Cache-Mindestgrößen liegen.
+Sie werden nicht künstlich aufgebläht, um einen Cache zu erzwingen. Vorhandene
+bevorzugte/verpflichtende Cache-Policies bleiben maßgeblich.
+
+## Rechercheergebnisse und Wachstum
+
+Neue und explizit nachgeladene Ergebnisse haben Vorrang. Zusätzliche ältere
+Rohbelege werden nur aufgenommen, solange der Größenrichtwert Platz lässt.
+Ein begrenzter Katalog zeigt die letzten IDs und den Umfang des Archivs.
+Das Archiv bleibt vollständig im Case; seine fehlende Darstellung behauptet
+weder die Abwesenheit von Evidenz noch deren Löschung.
+
+Große Ergebnisse werden als `json_fragment` mit Seitenindex, Seitenanzahl,
+Zeichenposition, Gesamtlänge und SHA-256 der vollständigen bisherigen
+Modelldarstellung angeboten. Eine Seite enthält höchstens 1.600 Zeichen des
+serialisierten Belegs. Die JSON-Fragmente sind ausdrücklich keine vollständigen
+Queryantworten. Seiten können mitten in einem JSON-Token enden; erst die
+Verkettung aller Fragmente ergibt die vollständige JSON-Darstellung. Strukturierte
+Query-/Coverageinformationen und vorhandene relationale Aggregationen bleiben
+zusätzlich sichtbar. Deren Aussagekraft bleibt auf den erklärten Scope begrenzt.
+
+Mit `{"kind":"recall","evidence_refs":["E000001"],"page":1}` wird eine
+andere nullbasierte Seite lokal nachgeladen, ohne externe Wiederholungsquery.
+Pro Aktion wird ein Beleg gelesen. Ungültige IDs oder Seiten werden abgelehnt.
+Seitenwahl und Request bleiben nach Wiederaufnahme nachvollziehbar. Das nächste
+normale Arbeitsfenster trägt nicht alle früher gelesenen Seiten weiter.
+
+Ein Checkpoint wird unabhängig von der abgeschalteten periodischen Vier-Schritt-
+Regel angefordert, wenn die bereits bewerteten Sitzungsergebnisse mehr als 4.000
+Bytes oder das Sitzungsprotokoll mehr als 2.000 Bytes umfassen. Das ist ein
+Bedarfsauslöser, keine weitere Promptobergrenze. Auch Checkpoints nutzen begrenzte
+Ergebnisfenster und dürfen zum Nachlesen `recall` wählen, bevor sie konsolidieren.
+In diesem Fall bleibt die provisorische Sitzung erhalten. Erst eine erfolgreiche
+Konsolidierung leert sie. Die vorhandene Delta-Verarbeitung bewahrt frühere
+Findings; die Darstellung kennzeichnet ausgelassene Findings und Gegenbelege.
+
+Passt selbst der notwendige Grundkontext nicht unter die Sicherheitsgrenze,
+wird der Fall kontrolliert mit `INVESTIGATION_PROMPT_LIMIT` zurückgestellt.
+Es wird kein kostenpflichtiger übergroßer Request gesendet und kein Text still
+abgeschnitten. Das interne JSON-Kontextlimit ist weiterhin eine getrennte,
+konfigurierbare Sicherheitsgrenze und wird hierdurch nicht aufgehoben.
+
+## Lokale Verifikation
+
+`tests/test_investigation_window.py` prüft unter anderem harte Grenzen vor dem
+Provider, Reparatur-/Reviewversionen, exakte Seitendarstellung, begrenztes Wachstum
+bis 138 Ergebnissen, strenge Aktionsvalidierung, Cache-Rekonstruktion,
+Startbewertung, Wiederaufnahme und Abschluss.
+
+Die Größenmessung an gespeicherten Bug-20-Kontexten liegt getrennt vom Paket in
+`docs/test-results/token-usage/investigation-window-offline-20261020.json`.
+Sie enthält keine Prompts und ist kein Nachweis gleicher LLM-Ergebnisqualität.