pdf-umbenenner/docs/workpackages/M5 - Arbeitspakete.md

# 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.