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:

{
  "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.