Arbeitspakete für M5 angelegt

docs/workpackages/M5 - Arbeitspakete.md

@@ -0,0 +1,669 @@
+# M5 - Arbeitspakete
+
+## Geltungsbereich
+
+Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M5 – KI-Integration, Prompt-Bezug und validierter Benennungsvorschlag**.
+
+Die Meilensteine **M1**, **M2**, **M3** und **M4** werden als vollständig umgesetzt vorausgesetzt.
+
+Die Arbeitspakete sind bewusst so geschnitten, dass:
+
+- **KI 1** daraus je Arbeitspaket einen klaren Einzel-Prompt ableiten kann,
+- **KI 2** genau dieses eine Arbeitspaket in **einem Durchgang** vollständig umsetzen kann,
+- nach **jedem** Arbeitspaket wieder ein **fehlerfreier, buildbarer Stand** vorliegt.
+
+Die Reihenfolge der Arbeitspakete ist verbindlich.
+
+## Zusätzliche Schnittregeln für die KI-Bearbeitung
+
+- Pro Arbeitspaket nur die **minimal notwendigen Querschnitte** durch Domain, Application, Adapter und Bootstrap ändern.
+- Keine Annahmen treffen, die nicht durch dieses Dokument oder die verbindlichen Spezifikationen gedeckt sind.
+- Kein Vorgriff auf **M6+**.
+- Kein Umbau bestehender M1–M4-Strukturen ohne direkten M5-Bezug.
+- Neue Typen, Ports, Statuswerte, Migrationen und Adapter so schneiden, dass sie aus einem einzelnen Arbeitspaket heraus **klar benennbar, testbar und reviewbar** sind.
+- M5 darf bestehende M4-Persistenz **gezielt evolvieren**, aber nicht stillschweigend neu erfinden.
+- Jeder positive M5-Zwischenstand muss bereits so modelliert sein, dass **M6 darauf ohne Statusbruch** aufsetzen kann.
+- M5 endet fachlich mit einem **persistierten, validierten Benennungsvorschlag**; **nicht** mit einer Zielkopie.
+
+## Explizit nicht Bestandteil von M5
+
+- physische Zielkopie in den Zielordner
+- finales Dateinamensformat `YYYY-MM-DD - Titel.pdf` als technische Ausgabeoperation
+- Dublettenbehandlung `(1)`, `(2)` im Zielordner
+- Windows-Zeichenbereinigung für den finalen Zieldateinamen
+- Zielpfad- und Zieldateinamenspersistenz
+- atomisches Schreiben oder temporäre Zieldateien
+- vollständige End-to-End-Erfolgssemantik des späteren Produktiv-Endstands aus M6
+- Logging-Feinschliff des Endstands aus M7
+- vollständige laufübergreifende Retry-Logik späterer Meilensteine für alle Fehlerarten jenseits des in M5 konkret benötigten Umfangs
+- manuelle Nachbearbeitung oder Benutzerinteraktion
+
+## Verbindliche M5-Regeln für **alle** Arbeitspakete
+
+### 1. Status- und Übergangssemantik zwischen M4, M5 und M6
+
+Die in M4 verwendete positive Zwischenbedeutung von `SUCCESS` reicht ab M5 **nicht mehr aus**, weil M5 einen validierten Benennungsvorschlag erzeugt, M6 aber erst die Zielkopie schreibt.
+
+Daher gilt ab M5 verbindlich:
+
+- `SUCCESS` ist ab M5 **für den echten Enderfolg nach M6 reserviert**.
+- M5 führt die beiden **nicht-terminalen positiven Statuswerte** ein:
+  - `READY_FOR_AI` = Dokument ist fachlich bis einschließlich M3 vorbereitet, aber es liegt noch **kein** gültiger M5-Benennungsvorschlag vor.
+  - `PROPOSAL_READY` = ein gültiger M5-Benennungsvorschlag ist persistent vorhanden; das Dokument ist **für M5 abgeschlossen**, aber **noch nicht** im Sinne von M6 erfolgreich kopiert.
+- Bereits vorhandene **M4-Altbestände** mit positivem Status `SUCCESS`, aber **ohne** M5-Benennungsvorschlag, müssen in M5 **kontrolliert in `READY_FOR_AI` überführt** werden.
+- Die bestehenden negativen bzw. Skip-Statuswerte bleiben erhalten:
+  - `FAILED_RETRYABLE`
+  - `FAILED_FINAL`
+  - `SKIPPED_ALREADY_PROCESSED`
+  - `SKIPPED_FINAL_FAILURE`
+- Für M5-spezifische Wiederholungsläufe gilt:
+  - `PROPOSAL_READY` wird **nicht erneut per KI verarbeitet**,
+  - `SUCCESS` wird **nicht erneut verarbeitet**,
+  - `FAILED_FINAL` wird **nicht erneut verarbeitet**,
+  - `READY_FOR_AI` und `FAILED_RETRYABLE` bleiben verarbeitbar.
+- Für M6 gilt bereits als verbindliche Übergaberegel:
+  - `PROPOSAL_READY` ist **kein terminaler Gesamterfolg**, sondern der fachlich korrekte Eingangszustand für Dateinamensbildung und Zielkopie.
+
+### 2. Externer Prompt-Bezug
+
+- Der Prompt ist in M5 **nicht** im Code fest verdrahtet.
+- Die Anwendung lädt den fachlich verwendeten Prompt aus einer **externen Datei**.
+- Der für einen KI-Versuch verwendete Prompt muss über einen **stabilen Prompt-Identifikator** nachvollziehbar sein, mindestens über den Prompt-Dateinamen oder einen gleichwertig stabilen Identifikator.
+
+### 3. Deterministische KI-Anfragezusammensetzung
+
+M5 führt **kein frei erfundenes Templating-System** ein.
+
+Stattdessen gilt:
+
+- Die Application erzeugt für den KI-Port eine **vollständig deterministische Anfrage-Repräsentation**.
+- Diese Repräsentation besteht mindestens aus:
+  - Prompt-Inhalt,
+  - Prompt-Identifikator,
+  - begrenztem Dokumenttext,
+  - tatsächlich gesendeter Zeichenzahl,
+  - der verbindlichen JSON-only-Erwartung für `date`, `title`, `reasoning`.
+- Die Zusammensetzung von Prompt und Dokumenttext erfolgt über einen **festen, dokumentierten technischen Aufbau**, damit KI 2 dies ohne Interpretationsspielraum umsetzen kann.
+- Provider-spezifische Features für strukturiertes Output dürfen **optional intern** verwendet werden, sind aber **nicht** Voraussetzung des M5-Designs.
+
+### 4. KI-Konfiguration und effektiver API-Key
+
+Für M5 müssen die bereits im Zielbild vorgesehenen KI-relevanten Konfigurationswerte technisch nutzbar und verdrahtet sein, insbesondere:
+
+- `api.baseUrl`
+- `api.model`
+- `api.timeoutSeconds`
+- `max.text.characters`
+- `prompt.template.file`
+
+Der API-Key bleibt Konfiguration; die bestehende Prioritätsregel **Umgebungsvariable vor Properties** bleibt verbindlich.
+
+Zusätzlich gilt für M5:
+
+- der **effektive** API-Key muss nicht nur aufgelöst, sondern auch **tatsächlich im HTTP-Adapter verwendet** werden,
+- die Verwendung muss automatisiert testbar nachgewiesen sein.
+
+### 5. Begrenzung des an die KI gesendeten Inhalts
+
+- Die maximale Zeichenzahl des an die KI gegebenen Dokumentinhalts ist konfigurierbar.
+- Die Begrenzung muss **vor dem KI-Aufruf** technisch angewendet werden.
+- Die tatsächlich an die KI gesendete Zeichenzahl muss verfügbar und persistierbar sein.
+- Die Begrenzung verändert **nicht** den extrahierten Originaltext im M3-/M4-Sinne, sondern nur den **für M5 verwendeten KI-Eingabetext**.
+
+### 6. Vollständige M5-Regel für Titel und Datum
+
+M5 muss die fachliche Regel **operational vollständig** umsetzen, ohne unzuverlässige Heuristik-Experimente einzuführen.
+
+Daher gilt kombinatorisch:
+
+- Der **Prompt-Vertrag** bindet die KI verbindlich an die nicht rein technisch prüfbaren Erwartungen:
+  - Titel auf Deutsch,
+  - verständlich,
+  - hinreichend eindeutig,
+  - Eigennamen unverändert.
+- Die **Application-Validierung** prüft zusätzlich alle in M5 **objektiv prüfbaren** Regeln:
+  - `title` vorhanden,
+  - `reasoning` vorhanden,
+  - Basistitel max. 20 Zeichen,
+  - keine unzulässigen Sonderzeichen außer Leerzeichen,
+  - keine generischen Platzhaltertitel,
+  - vorhandenes `date` ist als `YYYY-MM-DD` interpretierbar.
+- M5 führt **keine** spekulative Sprachdetektion, keine unsichere Eigennamen-Normalisierung und keine weichen Heuristiken für „Verständlichkeit“ ein, die fachlich eher neue Fehler erzeugen würden.
+
+### 7. Technischer Antwortvertrag der KI
+
+Die KI-Antwort muss in M5 als **genau ein parsebares JSON-Objekt** verarbeitet werden.
+
+Zweckmäßiges Schema im M5-Sinn:
+
+```json
+{
+  "date": "2026-02-11",
+  "title": "Stromabrechnung",
+  "reasoning": "..."
+}
+```
+
+Dabei gilt:
+
+- `title` ist verpflichtend,
+- `reasoning` ist verpflichtend,
+- `date` ist optional,
+- zusätzliche Felder dürfen technisch toleriert werden, sind aber für M5 fachlich irrelevant,
+- zusätzlicher Freitext außerhalb des JSON-Objekts macht die Antwort **technisch unbrauchbar**.
+
+### 8. Technisch unbrauchbare vs. fachlich unbrauchbare KI-Ergebnisse
+
+Für M5 ist diese Unterscheidung verbindlich:
+
+**Technisch unbrauchbare KI-Ergebnisse** sind insbesondere:
+- KI nicht erreichbar,
+- Timeout,
+- technisch fehlgeschlagener HTTP-Aufruf,
+- nicht parsebare KI-Antwort,
+- technisch unvollständige Antwort ohne verpflichtende Strukturbestandteile,
+- zusätzlicher Text außerhalb des erwarteten einzelnen JSON-Objekts.
+
+Diese Fälle sind im M5-Sinn **dokumentbezogene technische Fehler**.
+
+**Fachlich unbrauchbare KI-Ergebnisse** sind insbesondere:
+- unbrauchbarer oder generischer Titel,
+- Titel verletzt die technisch prüfbaren Titelregeln des Zielbilds,
+- die KI liefert ein `date`, dieses ist aber nicht interpretierbar oder unbrauchbar.
+
+Diese Fälle sind im M5-Sinn **deterministische Inhaltsfehler**.
+
+### 9. Datumsauflösung und Datumsquelle
+
+- Liefert die KI ein gültiges `date`, wird dieses als aufgelöstes Datum verwendet.
+- Liefert die KI **kein** `date`, setzt die Anwendung den Fallback über die technische Uhr (`ClockPort`) auf das aktuelle Datum.
+- Liefert die KI ein `date`, dieses ist aber unbrauchbar, ist das **kein** Fallback-Fall, sondern ein fachlicher Fehlerfall.
+- Die Datumsquelle muss im M5-Stand nachvollziehbar und persistierbar sein.
+
+### 10. M5-Benennungsvorschlag und führende Quelle für M6
+
+Der M5-Benennungsvorschlag besteht mindestens aus:
+
+- aufgelöstem Datum,
+- Datumsquelle,
+- validiertem Basistitel,
+- KI-Begründung (`reasoning`).
+
+**Nicht** Bestandteil des M5-Benennungsvorschlags sind:
+
+- finaler vollständiger Dateiname,
+- Dubletten-Suffix,
+- Zielpfad,
+- physische Zielkopie.
+
+Für die Übergabe an M6 gilt verbindlich:
+
+- die **führende Quelle** des gültigen M5-Benennungsvorschlags ist der **neueste Versuchshistorieneintrag mit Ergebnisstatus `PROPOSAL_READY`**,
+- M5 führt **keine parallele zweite Wahrheitsquelle** für Datum/Titel/Reasoning im Dokument-Stammsatz ein,
+- der Dokument-Stammsatz enthält in M5 weiterhin den Gesamtstatus und die Zähler, nicht aber redundante M6-Zieldaten.
+
+### 11. Erweiterung der Versuchshistorie in M5
+
+Die bereits in M4 vorhandene Versuchshistorie wird in M5 gezielt erweitert. Für jeden dokumentbezogenen, identifizierten M5-Versuch müssen mindestens speicherbar sein:
+
+- Modellname,
+- Prompt-Identifikator oder Prompt-Dateiname,
+- verarbeitete Seitenzahl,
+- an die KI gesendete Zeichenzahl,
+- KI-Rohantwort,
+- KI-Reasoning,
+- aufgelöstes Datum,
+- Datumsquelle,
+- validierter Titel.
+
+Nicht Bestandteil der M5-Versuchshistorie sind Zielpfad oder finaler Zieldateiname.
+
+### 12. Fehlersemantik und Zählerfortschreibung in M5
+
+M5 erweitert die in M4 bereits vorhandene Fehlersemantik:
+
+- dokumentbezogene **technische** KI-Fehler nach erfolgreicher Fingerprint-Ermittlung bleiben retryable und laufen über den **Transientfehlerzähler**,
+- fachlich **deterministische** KI-Ergebnisfehler laufen über den **Inhaltsfehlerzähler**,
+- die bestehende M4-Regel „erster deterministischer Inhaltsfehler retryable, zweiter final“ bleibt erhalten und gilt auch für M5-deterministische Inhaltsfehler,
+- Skip-Fälle aus M4 bleiben unverändert erhalten,
+- Vor-Fingerprint-Fehler bleiben weiterhin **nicht historisierte** Laufereignisse.
+
+### 13. Kein Vorgriff auf M6
+
+M5 endet fachlich mit einem **persistierten, validierten Benennungsvorschlag**. M5 führt **keine** Zielkopie aus und erzeugt **keinen** finalen Zieldateinamen als technische Dateisystemoperation.
+
+---
+
+## AP-001 M5-Kernobjekte, Statusmodell und KI-/Prompt-Port-Verträge präzisieren
+
+### Voraussetzung
+Keine. Dieses Arbeitspaket ist der M5-Startpunkt.
+
+### Ziel
+Die M5-relevanten Typen, positiven Zwischenstatus, KI-/Prompt-Verträge und Ergebnissemantiken werden eindeutig eingeführt, damit spätere Arbeitspakete ohne Interpretationsspielraum implementiert werden können.
+
+### Muss umgesetzt werden
+- Neue M5-relevante Kernobjekte bzw. Application-nahe Typen anlegen, insbesondere für:
+  - externen Prompt-Bezug,
+  - Prompt-Identifikator,
+  - deterministische KI-Anfrage-Repräsentation,
+  - KI-Rohantwort,
+  - parsebares KI-Antwortmodell,
+  - validierten Benennungsvorschlag,
+  - Datumsquelle,
+  - KI-bezogene Nachvollziehbarkeitsdaten pro Versuch,
+  - technische vs. fachliche KI-Fehlerklassifikation.
+- Das Statusmodell gezielt um die nicht-terminalen positiven Zwischenstatus erweitern:
+  - `READY_FOR_AI`
+  - `PROPOSAL_READY`
+- Die Semantik dieser Statuswerte in JavaDoc und ggf. `package-info` so dokumentieren, dass klar ist:
+  - `READY_FOR_AI` ist **M5-verarbeitbar**,
+  - `PROPOSAL_READY` ist **für M5 abgeschlossen**, aber **für M6 weiterverarbeitbar**,
+  - `SUCCESS` bleibt ab M5 dem echten M6-Enderfolg vorbehalten.
+- Outbound-Ports definieren für:
+  - Laden des externen Prompts,
+  - KI-Aufruf über eine OpenAI-kompatible Schnittstelle.
+- Port-Verträge so schneiden, dass **weder `Path`/`File` noch HTTP-/JSON-Bibliothekstypen** in Domain oder Application durchsickern.
+- Rückgabemodelle so anlegen, dass spätere Arbeitspakete ohne Zusatzannahmen unterscheiden können zwischen:
+  - technisch erfolgreichem KI-Aufruf mit Rohantwort,
+  - technischem KI-Fehler,
+  - parsebarer Antwort,
+  - technisch unbrauchbarer Antwort,
+  - fachlich validiertem Benennungsvorschlag,
+  - fachlich unbrauchbarem Benennungsvorschlag.
+- M5-spezifische Semantik von `date`, `title` und `reasoning` in JavaDoc eindeutig beschreiben.
+- Explizit dokumentieren, dass M5 **keinen finalen Zieldateinamen** und **keine Zielkopie** erzeugt.
+- Explizit dokumentieren, dass die führende Quelle für M6 **der neueste Versuch mit `PROPOSAL_READY`** ist.
+
+### Explizit nicht Teil
+- Prompt-Datei laden
+- HTTP-Adapter
+- KI-JSON-Parsing
+- fachliche Titel- und Datumsvalidierung
+- Persistenzanpassungen
+- Batch-Integration
+
+### Fertig wenn
+- die M5-relevanten Typen und Port-Verträge vorhanden sind,
+- technische und fachliche M5-Ergebnisarten klar unterscheidbar modelliert sind,
+- die positiven Zwischenstatus ohne Widerspruch zu M6 definiert sind,
+- Domain und Application frei von Infrastrukturtypen bleiben,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-002 Externen Prompt laden, stabil identifizieren und deterministische KI-Anfrage zusammensetzen
+
+### Voraussetzung
+AP-001 ist abgeschlossen.
+
+### Ziel
+Der fachlich verwendete Prompt wird aus einer externen Datei geladen, stabil identifizierbar gemacht und gemeinsam mit dem Dokumenttext in eine eindeutig definierte, deterministische KI-Anfrage-Repräsentation überführt.
+
+### Muss umgesetzt werden
+- Adapter-Out für das Laden der externen Prompt-Datei implementieren.
+- Aus dem geladenen Prompt einen **stabilen Prompt-Identifikator** ableiten, mindestens über den Prompt-Dateinamen oder einen gleichwertig stabilen Identifikator.
+- Sicherstellen, dass leerer oder technisch unbrauchbarer Prompt nicht als gültige M5-Eingabe weitergereicht wird.
+- Einen **fest dokumentierten technischen Aufbau** der KI-Anfrage-Repräsentation implementieren, der mindestens enthält:
+  - Prompt-Inhalt,
+  - Prompt-Identifikator,
+  - Dokumenttext als eigener Block,
+  - die JSON-only-Erwartung für `date`, `title`, `reasoning`.
+- Die Zusammensetzung so schneiden, dass KI 2 **ohne implizite Entscheidung** weiß, in welcher Reihenfolge Prompt und Dokumenttext zusammengeführt werden.
+- Den Mechanismus so schneiden, dass **kein frei erfundenes Templating-System** eingeführt werden muss.
+- JavaDoc für Prompt-Bezug, Identifikator, deterministische Zusammensetzung, JSON-only-Vertrag und M5-Nicht-Ziele ergänzen.
+
+### Explizit nicht Teil
+- HTTP-Aufruf zur KI
+- Textbegrenzung
+- KI-Antwortvalidierung
+- Batch-Integration
+- Persistenz der Prompt-Metadaten
+
+### Fertig wenn
+- der Prompt aus einer externen Datei technisch ladbar ist,
+- ein stabiler Prompt-Identifikator bereitsteht,
+- die KI-Anfrage-Repräsentation deterministisch aufgebaut wird,
+- kein freies Ad-hoc-Templating eingeführt wurde,
+- der Stand weiterhin fehlerfrei buildbar ist.
+
+---
+
+## AP-003 OpenAI-kompatiblen KI-HTTP-Adapter mit wirksamer Konfiguration und kontrolliertem technischem Fehlerverhalten implementieren
+
+### Voraussetzung
+AP-001 und AP-002 sind abgeschlossen.
+
+### Ziel
+Ein technisch gekapselter Adapter kann einen M5-KI-Aufruf gegen eine OpenAI-kompatible HTTP-Schnittstelle ausführen, den **effektiven** API-Key tatsächlich verwenden und eine Rohantwort oder einen kontrollierten technischen Fehler liefern.
+
+### Muss umgesetzt werden
+- OpenAI-kompatiblen HTTP-Adapter im Adapter-Out implementieren.
+- Basis-URL, Modellname, Timeout und API-Zugriff aus der vorhandenen Konfiguration technisch nutzbar machen.
+- Den Adapter so schneiden, dass Domain und Application nur mit dem **abstrakten KI-Port** arbeiten.
+- Eine technische Rohantwort liefern, die in späteren Arbeitspaketen geparst und validiert werden kann.
+- Kontrolliertes Fehlerverhalten mindestens für folgende Fälle umsetzen:
+  - Timeout,
+  - nicht erreichbarer Endpunkt,
+  - technisch fehlgeschlagener HTTP-Aufruf,
+  - sonstige technische Kommunikationsfehler.
+- Sicherstellen, dass der **effektive API-Key** gemäß bestehender Prioritätsregel im Adapter **real verwendet** wird.
+- Sicherstellen, dass keine HTTP-, Authentifizierungs- oder JSON-Implementierungsdetails in Domain oder Application durchsickern.
+- JavaDoc für OpenAI-Kompatibilität, technische Fehlergrenzen, Konfigurationsnutzung und M5-Nicht-Ziele ergänzen.
+
+### Explizit nicht Teil
+- fachliche Validierung der KI-Antwort
+- Persistenz
+- Batch-Orchestrierung
+- Textbegrenzung
+- Datums-Fallback
+- finaler Benennungsvorschlag
+
+### Fertig wenn
+- der KI-Port technisch implementiert ist,
+- Konfiguration für Basis-URL, Modellname, Timeout und effektiven API-Key wirksam verwendet wird,
+- Rohantwort und technische Fehler kontrolliert über den Port geliefert werden,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-004 Textbegrenzung, KI-JSON-Parsing, vollständige M5-Validierung und Datumsauflösung umsetzen
+
+### Voraussetzung
+AP-001 bis AP-003 sind abgeschlossen.
+
+### Ziel
+Die Anwendung kann einen begrenzten Dokumenttext für den KI-Aufruf vorbereiten, die KI-Rohantwort als JSON interpretieren und daraus entweder einen validierten Benennungsvorschlag oder einen eindeutig klassifizierten Fehler ableiten.
+
+### Muss umgesetzt werden
+- Konfigurierbare Begrenzung des an die KI zu sendenden Dokumenttexts umsetzen.
+- Sicherstellen, dass die Begrenzung **vor dem KI-Aufruf** angewendet wird.
+- Tatsächlich gesendete Zeichenzahl technisch erfassen und für spätere Persistenz bereitstellen.
+- Parsing der KI-Rohantwort als **genau ein JSON-Objekt** implementieren.
+- Technische Antwortvalidierung umsetzen:
+  - `title` vorhanden und nicht leer,
+  - `reasoning` vorhanden und nicht leer,
+  - `date` optional,
+  - zusätzlicher Freitext außerhalb des JSON-Objekts führt zu technischer Ungültigkeit.
+- Fachliche M5-Validierung für die **objektiv prüfbaren** Titel- und Datumsregeln umsetzen, insbesondere:
+  - Basistitel max. 20 Zeichen,
+  - keine unzulässigen Sonderzeichen außer Leerzeichen,
+  - keine generischen Platzhaltertitel,
+  - ein vorhandenes `date` muss als `YYYY-MM-DD` interpretierbar sein.
+- Den nicht rein technisch prüfbaren Teil der fachlichen Titelregel explizit über den **Prompt-Vertrag** absichern und dies im Code/JavaDoc sauber dokumentieren:
+  - Deutsch,
+  - verständlich,
+  - hinreichend eindeutig,
+  - Eigennamen unverändert.
+- Explizit umsetzen:
+  - fehlendes `date` → Fallback über `ClockPort`,
+  - vorhandenes, aber unbrauchbares `date` → fachlicher Fehler,
+  - parsebare, aber fachlich unbrauchbare Titel → fachlicher Fehler.
+- Einen validierten M5-Benennungsvorschlag bereitstellen, der mindestens enthält:
+  - aufgelöstes Datum,
+  - Datumsquelle,
+  - validierten Titel,
+  - KI-Reasoning.
+- JavaDoc für Begrenzungsregel, Antwortvalidierung, Datums-Fallback und operative Vollständigkeit der Titelregel ergänzen.
+
+### Explizit nicht Teil
+- HTTP-Adapter
+- SQLite-Schemaerweiterung
+- Batch-Integration
+- Status- und Zählerfortschreibung
+- finale Dateinamensbildung
+- Zielkopie
+
+### Fertig wenn
+- Dokumenttext begrenzt werden kann,
+- parsebare und unparsebare KI-Antworten sauber unterscheidbar sind,
+- fehlendes Datum korrekt auf den Clock-Fallback läuft,
+- fachlich unbrauchbare Titel und Datumswerte sauber erkannt werden,
+- ein validierter M5-Benennungsvorschlag technisch verfügbar ist,
+- der Build weiterhin fehlerfrei ist.
+
+---
+
+## AP-005 SQLite-Schema von M4 nach M5 evolvieren, Altbestände migrieren und Versuchshistorie um M5-Nachvollziehbarkeit erweitern
+
+### Voraussetzung
+AP-001 bis AP-004 sind abgeschlossen.
+
+### Ziel
+Die bestehende M4-Persistenz wird kontrolliert auf den M5-Stand erweitert, inklusive der **idempotenten Migration positiver M4-Altbestände** und der Erweiterung der Versuchshistorie um die M5-Nachvollziehbarkeit.
+
+### Muss umgesetzt werden
+- Das bestehende SQLite-Schema **evolvieren**, nicht neu erfinden.
+- Die Schema-Initialisierung so erweitern, dass ein vorhandenes M4-Schema kontrolliert auf den M5-Stand gebracht werden kann.
+- Die Versuchshistorie um die für M5 benötigten Felder erweitern, insbesondere für:
+  - Modellname,
+  - Prompt-Identifikator oder Prompt-Dateiname,
+  - verarbeitete Seitenzahl,
+  - an die KI gesendete Zeichenzahl,
+  - KI-Rohantwort,
+  - KI-Reasoning,
+  - aufgelöstes Datum,
+  - Datumsquelle,
+  - validierten Titel.
+- Die Persistenz so erweitern, dass die neuen nicht-terminalen positiven Statuswerte fachlich konsistent speicherbar sind:
+  - `READY_FOR_AI`
+  - `PROPOSAL_READY`
+- Eine **idempotente M4→M5-Altbestandsmigration** vorsehen, die mindestens sicherstellt:
+  - M4-Dokumente mit positivem Altstatus `SUCCESS`, aber ohne M5-Benennungsvorschlag, werden kontrolliert nach `READY_FOR_AI` überführt,
+  - diese Migration ist mehrfach ausführbar, ohne Daten zu beschädigen,
+  - bestehende negative und terminale Fehlerzustände bleiben unangetastet.
+- Sicherstellen, dass:
+  - bestehende M4-Daten weiterhin lesbar bleiben,
+  - die M5-Erweiterung idempotent initialisierbar ist,
+  - keine M6+-Felder für Zielpfad oder finalen Zieldateinamen angelegt werden.
+- Repository-Mapping der Versuchshistorie auf die neuen M5-Felder erweitern.
+- Falls für Tests oder Use-Case-Integration nötig, passende Lesefähigkeiten ergänzen, ohne spätere Reporting-Funktionalität vorwegzunehmen.
+- JavaDoc für Schemaevolution, Altbestandsmigration, Rückwärtsverträglichkeit und M5-Nachvollziehbarkeit ergänzen.
+
+### Explizit nicht Teil
+- Batch-Use-Case-Integration
+- KI-Aufruf
+- Status- und Zählerentscheidungen im laufenden Batch
+- Zielpfad- oder Dateinamenspersistenz
+- M6-Dateisystemfunktionalität
+
+### Fertig wenn
+- das M4-Schema kontrolliert auf M5 erweitert werden kann,
+- M4-Altbestände mit positivem Zwischenstatus idempotent auf die M5-Semantik überführt werden,
+- die neuen M5-Felder in der Versuchshistorie technisch schreib- und lesbar sind,
+- bestehende M4-Daten nicht unbrauchbar werden,
+- keine M6+-Persistenzfelder eingeführt wurden,
+- der Stand fehlerfrei buildbar bleibt.
+
+---
+
+## AP-006 M5-Entscheidungslogik und Batch-Integration für KI-Aufruf, Fehlerklassifikation, Statusfortschreibung und persistierten Benennungsvorschlag umsetzen
+
+### Voraussetzung
+AP-001 bis AP-005 sind abgeschlossen.
+
+### Ziel
+Der bestehende M4-Lauf wird zu einem echten M5-Lauf erweitert, der nach erfolgreicher M3-Vorprüfung per KI einen validierten Benennungsvorschlag erzeugt, KI-bezogene Versuchsdaten persistiert und die positive Statussemantik so fortschreibt, dass M6 ohne Statusbruch anknüpfen kann.
+
+### Muss umgesetzt werden
+- Den bestehenden Batch-Use-Case so erweitern, dass pro geeignetem Dokument nach M4-Identifikation und nach bestandener M3-Vorprüfung zusätzlich gilt:
+  1. Prompt laden,
+  2. Dokumenttext begrenzen,
+  3. deterministische KI-Anfrage erzeugen,
+  4. KI-Aufruf durchführen,
+  5. KI-Rohantwort technisch verarbeiten,
+  6. Benennungsvorschlag validieren,
+  7. Versuchshistorie mit M5-Nachvollziehbarkeit fortschreiben,
+  8. Status und Zähler im vorhandenen Rahmen konsistent fortschreiben.
+- Sicherstellen, dass **kein KI-Aufruf** erfolgt bei:
+  - Vor-Fingerprint-Fehlern,
+  - terminalen Skip-Fällen aus M4,
+  - M3-Inhaltsfehlern,
+  - sonstigen Fällen, die den Dokumentlauf bereits vor der KI sauber beendet haben.
+- Die positiven Dokumentzustände explizit wie folgt behandeln:
+  - M4-Altbestand `SUCCESS` ohne M5-Benennungsvorschlag wird **nicht** als terminal erfolgreich übersprungen, sondern gilt nach Migration bzw. Normalisierung als `READY_FOR_AI`,
+  - gültiger M5-Benennungsvorschlag führt zu `PROPOSAL_READY`, **nicht** zu `SUCCESS`,
+  - bestehendes `PROPOSAL_READY` führt in M5 zu **keinem erneuten KI-Aufruf**.
+- M5-Fehlerfälle explizit wie folgt in den bestehenden Status- und Zählerrahmen überführen:
+  - technischer KI-Fehler oder technisch unbrauchbare KI-Antwort → dokumentbezogener technischer Fehler, retryable, **Transientfehlerzähler +1**,
+  - parsebare, aber fachlich unbrauchbare KI-Antwort → deterministischer Inhaltsfehler, **Inhaltsfehlerzähler** nach bestehender Regel fortschreiben,
+  - gültiger Benennungsvorschlag → `PROPOSAL_READY`, Fehlerzähler unverändert.
+- Sicherstellen, dass bei dokumentbezogenen KI-Fehlern der Batch-Lauf für andere Dokumente kontrolliert weiterläuft.
+- Für identifizierte Dokumente sicherstellen, dass Versuchshistorie und Stammsatz konsistent fortgeschrieben werden und kein teilpersistierter Zustand zurückbleibt.
+- Sicherstellen, dass die führende Quelle für M6 **der neueste Versuch mit `PROPOSAL_READY`** bleibt und nicht implizit aus anderen Daten rekonstruiert werden muss.
+- Sicherstellen, dass KI-Rohantwort standardmäßig **in SQLite**, aber nicht als M6-/M7-Funktionalität fehlmodelliert wird.
+- JavaDoc für M5-Laufreihenfolge, KI-Grenze, Fehlerklassifikation, positive Statusfortschreibung und Persistenzkonsistenz ergänzen.
+
+### Explizit nicht Teil
+- physische Zielkopie
+- finale Dateinamensbildung
+- Dublettenbehandlung
+- Zielpfad- und Zieldateinamenspersistenz
+- M6- oder M7-Feinschliff
+
+### Fertig wenn
+- der Batch-Lauf für geeignete Dokumente tatsächlich einen KI-basierten Benennungsvorschlag erzeugt,
+- M4-Altbestände mit positivem Zwischenstatus korrekt in die M5-Verarbeitung überführt werden,
+- gültige M5-Ergebnisse als `PROPOSAL_READY` und **nicht** als `SUCCESS` persistiert werden,
+- M5-spezifische technische und fachliche KI-Fehler sauber unterschieden werden,
+- der validierte Benennungsvorschlag persistiert wird,
+- KI-Aufrufe nur an den fachlich zulässigen Stellen erfolgen,
+- der Lauf trotz dokumentbezogener KI-Fehler kontrolliert weiterarbeitet,
+- weiterhin keine M6+-Funktionalität enthalten ist.
+
+---
+
+## AP-007 Bootstrap- und CLI-Anpassungen für M5-Konfiguration, Startvalidierung, Schemaevolution und vollständige Verdrahtung durchführen
+
+### Voraussetzung
+AP-001 bis AP-006 sind abgeschlossen.
+
+### Ziel
+Der Programmeinstieg ist sauber an den M5-Lauf angepasst; die KI-relevante Konfiguration wird validiert, die M5-Schemaevolution einschließlich Altbestandsmigration wird beim Start wirksam, alle M5-Bausteine sind verdrahtet und harte Startfehler führen weiterhin kontrolliert zu Exit-Code 1.
+
+### Muss umgesetzt werden
+- Bootstrap-Verdrahtung auf die neuen M5-Ports, Adapter, Validierungs- und Persistenzbausteine erweitern.
+- M5-relevante Konfiguration ergänzen bzw. verdrahten, insbesondere für:
+  - `api.baseUrl`
+  - `api.model`
+  - `api.timeoutSeconds`
+  - `max.text.characters`
+  - `prompt.template.file`
+- Startvalidierung so ergänzen, dass mindestens geprüft wird:
+  - Prompt-Datei ist vorhanden und technisch lesbar,
+  - `max.text.characters` ist gültig und technisch nutzbar,
+  - Timeout ist gültig,
+  - KI-Basis-URL und Modellname sind vorhanden,
+  - ein effektiver API-Key gemäß bestehender Prioritätsregel verfügbar ist.
+- Die bestehende M4-Schema-Initialisierung mit der M5-Schemaevolution und der M4→M5-Altbestandsmigration sauber kombinieren.
+- Sicherstellen, dass harte Start-, Verdrahtungs-, Konfigurations- oder Initialisierungsfehler weiterhin zu **Exit-Code 1** führen.
+- Sicherstellen, dass dokumentbezogene KI-Fehler **nicht** als Startfehler fehlmodelliert werden.
+- JavaDoc und `package-info` für aktualisierte Verdrahtung, Konfiguration, Schemaevolution und Modulgrenzen ergänzen.
+
+### Explizit nicht Teil
+- Logging-Feinschliff des Endstands
+- M6-Dateisystemverdrahtung
+- Zielkopie
+- Dublettenlogik
+- spätere Betriebsoptimierungen
+
+### Fertig wenn
+- das Programm im M5-Stand vollständig startbar ist,
+- alle M5-Bausteine korrekt verdrahtet sind,
+- die M5-Startvalidierung greift,
+- die M5-Schemaevolution einschließlich Altbestandsmigration beim Start wirksam wird,
+- harte Startfehler weiterhin kontrolliert zu Exit-Code 1 führen,
+- der Build fehlerfrei bleibt.
+
+---
+
+## AP-008 Tests für Prompt-Bezug, KI-Adapter, Validierung, Altbestandsmigration, Statussemantik, Schemaevolution und M5-Ablauf vervollständigen
+
+### Voraussetzung
+AP-001 bis AP-007 sind abgeschlossen.
+
+### Ziel
+Der vollständige M5-Zielzustand wird automatisiert abgesichert und als konsistenter Übergabestand nachgewiesen.
+
+### Muss umgesetzt werden
+- Unit-Tests für den externen Prompt-Bezug implementieren, insbesondere für:
+  - Prompt-Datei wird geladen,
+  - leerer oder technisch ungültiger Prompt wird abgelehnt,
+  - stabiler Prompt-Identifikator wird geliefert,
+  - deterministische Zusammensetzung der KI-Anfrage bleibt reproduzierbar.
+- Tests für Textbegrenzung und tatsächlich gesendete Zeichenzahl implementieren.
+- Tests für KI-JSON-Parsing und technische Antwortvalidierung implementieren, insbesondere für:
+  - gültiges JSON,
+  - ungültiges JSON,
+  - fehlendes `title`,
+  - fehlendes `reasoning`,
+  - optionales `date`,
+  - zusätzlicher Text außerhalb des JSON-Objekts.
+- Tests für fachliche M5-Validierung implementieren, insbesondere für:
+  - gültigen Titel,
+  - generischen Titel,
+  - Titel mit unzulässigen Sonderzeichen,
+  - Titel über 20 Zeichen,
+  - gültiges KI-Datum,
+  - fehlendes Datum mit Clock-Fallback,
+  - unbrauchbares vorhandenes Datum.
+- Adapter-Tests für den KI-Port ergänzen, insbesondere für:
+  - erfolgreiche Rohantwort,
+  - Timeout,
+  - technisch fehlgeschlagenen HTTP-Aufruf,
+  - Verwendung des **effektiven API-Keys** im tatsächlichen HTTP-Request,
+  - Vorrang der Umgebungsvariable vor `api.key` aus Properties im real genutzten Adapterpfad.
+- Repository- und Schema-Tests gegen SQLite ergänzen, insbesondere für:
+  - Evolution eines M4-Schemas auf M5,
+  - Persistenz und Auslesen der neuen M5-Versuchshistorienfelder,
+  - Rückwärtsverträglichkeit bestehender M4-Daten,
+  - idempotente Migration von M4-Altbeständen `SUCCESS` nach `READY_FOR_AI`.
+- Integrationstests für den M5-Ablauf ergänzen, insbesondere:
+  - gültiger M5-Happy-Path mit persistiertem Benennungsvorschlag endet in `PROPOSAL_READY`, **nicht** in `SUCCESS`,
+  - technisch unbrauchbare KI-Antwort führt zu retryablem technischem Fehler,
+  - fachlich unbrauchbare KI-Antwort führt zu deterministischem Inhaltsfehler,
+  - bei fehlendem `date` wird der Clock-Fallback verwendet,
+  - bei M3-Inhaltsfehlern erfolgt kein KI-Aufruf,
+  - bestehendes `PROPOSAL_READY` wird im M5-Wiederholungslauf nicht erneut per KI verarbeitet,
+  - M4-Altbestände mit positivem Zwischenstatus werden im M5-Lauf nicht fälschlich als final erfolgreich übersprungen,
+  - die führende Quelle für M6 ist der neueste Versuch mit `PROPOSAL_READY`,
+  - es erfolgt weiterhin **keine Zielkopie**.
+- Tests für Bootstrap- und Startverhalten ergänzen, insbesondere:
+  - ungültige M5-Konfiguration führt zu Exit-Code 1,
+  - M5-Schemaevolution einschließlich Altbestandsmigration wird beim Start wirksam,
+  - dokumentbezogene KI-Fehler führen **nicht** zu Exit-Code 1.
+- Den M5-Stand abschließend auf Konsistenz, Architekturtreue und Nicht-Vorgriff auf M6+ prüfen.
+
+### Explizit nicht Teil
+- Tests für Zielkopie
+- Tests für Dublettenbehandlung im Zielordner
+- Tests für finalen Zieldateinamen
+- Tests für M6-/M7-Endverhalten
+
+### Fertig wenn
+- die Test-Suite für den M5-Umfang grün ist,
+- die wichtigsten M5-Randfälle automatisiert abgesichert sind,
+- die positive Statussemantik M4→M5→M6 ohne Lücke nachgewiesen ist,
+- der definierte M5-Zielzustand vollständig erreicht ist,
+- ein fehlerfreier, übergabefähiger Stand vorliegt.
+
+---
+
+## Abschlussbewertung
+
+Die Arbeitspakete decken den vollständigen M5-Zielumfang aus den verbindlichen Spezifikationen ab und schließen zusätzlich die zuvor offene **Status- und Übergangssemantik zwischen M4, M5 und M6** sauber:
+
+- externer Prompt-Bezug
+- deterministische KI-Anfrage-Zusammensetzung
+- OpenAI-kompatibler KI-Aufruf
+- konfigurierbarer KI-Zugriff einschließlich wirksam genutztem effektivem API-Key
+- Begrenzung des an die KI gesendeten Inhalts
+- technische und fachliche Validierung der KI-Antwort
+- Datums-Fallback durch die Anwendung
+- persistierter, validierter Benennungsvorschlag
+- Erweiterung der Versuchshistorie um M5-Nachvollziehbarkeit
+- idempotente M4→M5-Altbestandsmigration
+- positive Zwischenstatus `READY_FOR_AI` und `PROPOSAL_READY` als saubere Brücke zu M6
+- Tests für Prompt, KI-Adapter, Validierung, Datumsauflösung, Schemaevolution, Altbestandsmigration und M5-Ablauf
+
+Gleichzeitig bleiben die Grenzen zu M1–M4 sowie zu M6+ gewahrt. Insbesondere werden **keine** Zielkopie, **keine** Dublettenbehandlung im Zielordner und **keine** finale Dateinamensbildung vorweggenommen.