From 7e4193a1738748b844c4e6181743c3bfb29e917e Mon Sep 17 00:00:00 2001 From: Marcus van Elst Date: Tue, 7 Apr 2026 14:20:01 +0200 Subject: [PATCH] =?UTF-8?q?Arbeitspakete=20f=C3=BCr=20M7=20erstellt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/workpackages/M7 - Arbeitspakete.md | 540 ++++++++++++++++++++++++ 1 file changed, 540 insertions(+) create mode 100644 docs/workpackages/M7 - Arbeitspakete.md diff --git a/docs/workpackages/M7 - Arbeitspakete.md b/docs/workpackages/M7 - Arbeitspakete.md new file mode 100644 index 0000000..55c34c0 --- /dev/null +++ b/docs/workpackages/M7 - Arbeitspakete.md @@ -0,0 +1,540 @@ +# M7 - Arbeitspakete + +## Geltungsbereich + +Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M7 – Fehlerbehandlung, Retry-Logik, Logging und betriebliche Robustheit**. + +Die Meilensteine **M1**, **M2**, **M3**, **M4**, **M5** und **M6** 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 **M8+**. +- Kein Umbau bestehender M1–M6-Strukturen ohne direkten M7-Bezug. +- Neue Typen, Entscheidungsregeln, Konfigurationswerte, Repository-Erweiterungen und Adapter so schneiden, dass sie aus einem einzelnen Arbeitspaket heraus **klar benennbar, testbar und reviewbar** sind. +- M7 schärft und vervollständigt die bereits vorhandene Fehler- und Statussemantik aus M3–M6, erfindet sie aber nicht stillschweigend neu. +- M7 muss vorhandene M4–M6-Datenbestände **weiterhin lesen und korrekt fortschreiben** können. +- Jeder positive M7-Zwischenstand muss bereits einen **robusten, wiederholt ausführbaren Task-Scheduler-Lauf** liefern, auch wenn der Retry-, Logging- und Exit-Code-Endstand erst mit späteren Arbeitspaketen vollständig erreicht wird. +- Ein Arbeitspaket darf nur dann auf Repository- oder Persistenzfähigkeiten aufbauen, wenn diese entweder bereits aus M1–M6 vorhanden sind oder im unmittelbar vorhergehenden Arbeitspaket explizit hergestellt wurden. + +## Explizit nicht Bestandteil von M7 + +- neue KI-Funktionalität oder Prompt-Evolution jenseits der robusten Weiterverwendung des M5-Stands +- neue fachliche Benennungsregeln über M5/M6 hinaus +- neue Dateisystem-Funktionalität jenseits des M6-Zielkopiepfads und des in M7 konkret geforderten technischen Sofort-Wiederholversuchs +- Reporting-, Statistik- oder Monitoring-Funktionen +- Web-UI, REST-API oder Benutzerinteraktion +- OCR, Inhaltsänderung von PDFs oder manuelle Nachbearbeitung +- abschließender Gesamt-Feinschliff, großflächige Refactorings oder generelle Qualitätskampagnen aus **M8** + +## Verbindliche M7-Regeln für **alle** Arbeitspakete + +### 1. M7 schließt die Betriebslücke zwischen M6 und dem finalen Zielbild + +M6 liefert den vollständigen Erfolgspfad, aber noch nicht die vollständige betriebliche Robustheit des Endstands. Ab M7 gilt daher verbindlich: + +- `SUCCESS` bleibt der echte terminale Enderfolg. +- `FAILED_FINAL` bleibt der terminale Endfehler. +- `FAILED_RETRYABLE` darf nur solange bestehen bleiben, wie **mindestens ein weiterer Scheduler-Lauf fachlich zulässig** ist. +- `SKIPPED_ALREADY_PROCESSED` und `SKIPPED_FINAL_FAILURE` bleiben reine historisierte Skip-Ergebnisse und verändern selbst keine Fehlerzähler. +- Dokumentbezogene Fehler dürfen den Gesamtbatch nicht unnötig abbrechen. + +### 2. Vollständige Retry-Regel für deterministische Inhaltsfehler + +Ab M7 gilt die vollständige fachliche Regel über spätere Läufe hinweg: + +- deterministische Inhaltsfehler erhalten **genau einen** späteren Wiederholungsversuch, +- der **erste** historisierte deterministische Inhaltsfehler eines Fingerprints führt zu `FAILED_RETRYABLE`, +- der **zweite** historisierte deterministische Inhaltsfehler desselben Fingerprints führt zu `FAILED_FINAL`. + +Für M7 sind mindestens alle bereits aus M3–M6 konkret erzeugbaren deterministischen Inhaltsfehler in diesen Regelrahmen einzuordnen, insbesondere: + +- kein brauchbarer Text, +- Seitenlimit überschritten, +- fachlich unbrauchbarer oder generischer Titel, +- vorhandenes, aber unbrauchbares KI-Datum. + +Bereits vorhandene oder künftig im bestehenden Fachmodell erzeugte Mehrdeutigkeitsfälle laufen in denselben deterministischen Inhaltsfehler-Rahmen und erzeugen **kein** unsicheres Ergebnis. + +### 3. Vollständige Retry-Regel für transiente technische Fehler + +Ab M7 gilt für dokumentbezogene technische Fehler nach erfolgreicher Fingerprint-Ermittlung: + +- sie laufen über den **Transientfehlerzähler**, +- sie bleiben nur bis zum konfigurierten Grenzwert retryable, +- nach Ausschöpfen der zulässigen transienten Fehlversuche wird der Dokumentstatus `FAILED_FINAL`. + +Für die M7-Implementierung ist `max.retries.transient` verbindlich als **maximal zulässige Anzahl historisierter transienter Fehlversuche pro Fingerprint** zu interpretieren. Der Fehlversuch, der diesen Grenzwert erreicht, finalisiert den Dokumentstatus. + +Zusätzlich gilt: + +- `max.retries.transient` ist ein **ganzzahliger Wert >= 1**. +- Der Wert `0` ist **ungültige Startkonfiguration**. +- Beispiel: `1` bedeutet, dass bereits der **erste** historisierte transiente Fehlversuch finalisiert. +- Beispiel: `2` bedeutet, dass der **erste** historisierte transiente Fehlversuch retryable bleibt und der **zweite** finalisiert. + +### 4. Technischer Sofort-Wiederholversuch ist strikt auf den Zielkopierpfad begrenzt + +Der in der Zielarchitektur vorgesehene technische Sofort-Wiederholversuch wird in M7 exakt wie folgt umgesetzt: + +- **genau ein** zusätzlicher technischer Schreibversuch innerhalb desselben Dokumentlaufs, +- ausschließlich für Fehler beim physischen Zielkopierpfad aus M6, +- **kein** erneuter KI-Aufruf, +- **keine** erneute fachliche Titel-/Datumsableitung, +- **keine** Ausweitung auf Prompt-Laden, KI-HTTP, SQLite oder sonstige Adapter. + +Der Sofort-Wiederholversuch ist ein technischer Mechanismus innerhalb desselben Laufs und **kein** zusätzlicher fachlicher Retry-Lauf im Sinne der laufübergreifenden Retry-Regeln. + +### 5. Skip-Semantik des Endstands + +Ab M7 gilt vollständig: + +- `SUCCESS` wird in späteren Läufen **nicht erneut verarbeitet**, sondern mit `SKIPPED_ALREADY_PROCESSED` historisiert. +- `FAILED_FINAL` wird in späteren Läufen **nicht erneut verarbeitet**, sondern mit `SKIPPED_FINAL_FAILURE` historisiert. +- `FAILED_RETRYABLE`, `READY_FOR_AI` und `PROPOSAL_READY` bleiben verarbeitbar, soweit der jeweilige Dokumentzustand dies fachlich zulässt. +- Ein nach M6 noch offenes `PROPOSAL_READY` darf in M7 weiterhin sauber bis zum echten Enderfolg finalisiert werden. + +### 6. Logging-Mindestumfang des Endstands + +Das Logging muss ab M7 mindestens folgende Informationen nachvollziehbar liefern: + +- Laufstart, +- Laufende, +- Lauf-ID, +- erkannte Quelldatei, +- Überspringen bereits erfolgreicher Dateien, +- Überspringen final fehlgeschlagener Dateien, +- erzeugter Zielname, +- Retry-Entscheidung, +- Fehler mit Klassifikation. + +Die Logs müssen so geschnitten werden, dass dokumentbezogene Entscheidungen pro Fingerprint bzw. Kandidat nachvollziehbar bleiben, ohne zusätzliche Infrastrukturtypen in Domain oder Application zu ziehen. + +Zusätzlich gilt für die Korrelation: + +- sobald ein Fingerprint erfolgreich bestimmt wurde, müssen dokumentbezogene Logeinträge diesen Fingerprint oder eine daraus eindeutig ableitbare Referenz enthalten, +- solange noch kein Fingerprint vorliegt, erfolgt die Korrelation mindestens über Lauf-ID und erkannte Quelldatei bzw. Kandidatenbezug, +- M7 führt hierfür **keine** neue Persistenz-Wahrheit und **keine** zusätzliche Tracking-Ebene ein. + +### 7. Sensibilitätsregel für KI-Inhalte im Logging + +Ab M7 gilt verbindlich: + +- die vollständige KI-Rohantwort bleibt in **SQLite** speicherbar, +- die vollständige KI-Rohantwort wird **standardmäßig nicht** ins Log geschrieben, +- `reasoning` wird ebenfalls **standardmäßig nicht** vollständig ins Log geschrieben, +- die Ausgabe sensibler KI-Inhalte ist nur über eine **explizite Konfiguration** zulässig, +- M7 führt hierfür einen klar dokumentierten, booleschen Konfigurationswert ein, +- der Default muss auf **sicher/nicht loggen** stehen. + +Als sensible KI-Inhalte gelten in M7 mindestens: + +- vollständige KI-Rohantwort, +- vollständiges KI-`reasoning`. + +### 8. Exit-Code-Endsemantik + +Ab M7 ist das Exit-Code-Verhalten final: + +- `0`, wenn der Lauf technisch ordnungsgemäß durchgeführt wurde, auch wenn einzelne Dokumente fachlich oder transient fehlgeschlagen sind, +- `1` nur bei harten Start-, Bootstrap-, Verdrahtungs-, Konfigurations- oder Initialisierungsfehlern. + +Dokumentbezogene Fehler dürfen **nicht** als harte Startfehler fehlmodelliert werden. + +### 9. Konfigurationsvalidierung des Endstands + +M7 vervollständigt die Startvalidierung insbesondere für: + +- `max.retries.transient`, +- M7-relevante Logging-Konfiguration, +- bestehende M1–M6-Startparameter, soweit sie für einen robusten Batch-Lauf weiterhin zwingend sind. + +Ungültige M7-Startkonfiguration verhindert den Laufbeginn und führt zu **Exit-Code 1**. + +### 10. Keine zweite Wahrheitsquelle für Fehler- und Retry-Entscheidungen + +M7 nutzt weiterhin die bestehende Kombination aus: + +- Dokument-Stammsatz für Gesamtstatus und Zähler, +- Versuchshistorie für einzelne Versuchsdaten und Nachvollziehbarkeit. + +M7 führt **keine** parallele, dritte Wahrheitsquelle für Retry-Zustände, Logging-Entscheidungen oder Fehlerhistorien ein. + +--- + +## AP-001 M7-Kernobjekte, vollständige Fehlersemantik und Retry-/Logging-Verträge präzisieren + +### Voraussetzung +Keine. Dieses Arbeitspaket ist der M7-Startpunkt. + +### Ziel +Die M7-relevanten Typen, vollständigen Fehler- und Retry-Bedeutungen, Logging-bezogenen Entscheidungsobjekte und technischen Grenzen werden eindeutig eingeführt, damit spätere Arbeitspakete ohne Interpretationsspielraum implementiert werden können. + +### Muss umgesetzt werden +- Neue M7-relevante Kernobjekte bzw. Application-nahe Typen anlegen, insbesondere für: + - vollständige Retry-Entscheidung, + - Ausschöpfungszustand eines Retry-Rahmens, + - technische Sofort-Wiederholungsentscheidung für den Zielkopierpfad, + - dokumentbezogene Fehlerklassifikation des Endstands, + - Logging-Ereignis bzw. Logging-relevante Dokumententscheidung, + - Sensitivitätsentscheidung für KI-Inhalte im Logging. +- Die bestehende Status- und Fehlersemantik in JavaDoc und ggf. `package-info` so schärfen, dass klar ist: + - wann `FAILED_RETRYABLE` noch zulässig ist, + - wann ein Dokumentstatus wegen ausgeschöpfter Retry-Regeln in `FAILED_FINAL` übergeht, + - dass der technische Sofort-Wiederholversuch **nicht** zum laufübergreifenden Retry-Zähler gehört, + - dass dokumentbezogene Fehler den Gesamtbatch nicht zu Exit-Code 1 eskalieren. +- Application-seitige Verträge definieren oder gezielt erweitern für: + - Ableitung der Retry-Entscheidung aus Status, Fehlerart, Zählern und Konfiguration, + - Ableitung einer protokollierbaren Dokumententscheidung, + - Ableitung der Zielkopier-Sofort-Wiederholung, + - Auflösung der Sensitivitätsregel für KI-Logausgaben, + - Korrelation dokumentbezogener Logging-Ereignisse ohne Infrastrukturtypen im Kern. +- Port-Verträge so schneiden, dass weder Log4j2-, NIO-, JDBC- noch HTTP-Typen in Domain oder Application durchsickern. +- Rückgabemodelle so anlegen, dass spätere Arbeitspakete ohne Zusatzannahmen unterscheiden können zwischen: + - retryablem Inhaltsfehler, + - finalem Inhaltsfehler, + - retryablem technischem Fehler, + - finalisiertem technischem Fehler nach ausgeschöpftem Transient-Rahmen, + - technischem Zielschreibfehler mit zulässigem Sofort-Wiederholversuch, + - dokumentbezogener Entscheidung mit M7-logbarem Ergebnis. +- Explizit dokumentieren, dass M7 keine neue Persistenz-Wahrheit für Retry-Entscheidungen einführt. +- Explizit dokumentieren, dass `max.retries.transient` als historisierter Fehlversuchs-Grenzwert interpretiert wird und als gültiger Konfigurationswert nur **Integer >= 1** zulässig ist. +- Explizit dokumentieren, dass sensible KI-Logausgaben in M7 mindestens vollständige KI-Rohantwort und vollständiges KI-`reasoning` umfassen. + +### Explizit nicht Teil +- konkrete Retry-Implementierung im Batch-Lauf +- konkrete Log4j2-Konfiguration +- konkrete Zielkopier-Wiederholung +- Bootstrap-Anpassungen +- Tests des Endstands + +### Fertig wenn +- die M7-relevanten Typen und Verträge vorhanden sind, +- Retry-, Finalisierungs-, Sensitivitäts- und Logging-Korrelationssemantik eindeutig dokumentiert ist, +- Domain und Application frei von Infrastrukturtypen bleiben, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-002 Vollständige Retry-Entscheidungslogik für deterministische Inhaltsfehler und transiente technische Fehler implementieren + +### Voraussetzung +AP-001 ist abgeschlossen. + +### Ziel +Die fachlich vollständige laufübergreifende Retry-Entscheidung des Endstands ist als klarer, testbarer Baustein im Kern implementiert und kann von Batch-Lauf, Logging und Persistenz konsistent verwendet werden. + +### Muss umgesetzt werden +- Einen zentralen M7-Baustein implementieren, der aus vorhandener Fehlerart, bestehendem Dokumentstatus, Fehlerzählern und Konfiguration die verbindliche Retry-Entscheidung ableitet. +- Die vollständige deterministische Inhaltsfehlerregel explizit umsetzen: + - erster historisierter deterministischer Inhaltsfehler → `FAILED_RETRYABLE`, + - zweiter historisierter deterministischer Inhaltsfehler → `FAILED_FINAL`. +- Die vollständige transiente Fehlerregel explizit umsetzen: + - dokumentbezogene technische Fehler bleiben nur bis `max.retries.transient` retryable, + - der Fehlversuch, der den Grenzwert erreicht, finalisiert den Status zu `FAILED_FINAL`. +- Die Randfälle der Grenzwertinterpretation explizit abdecken, insbesondere: + - `max.retries.transient = 1`, + - Skip-Fälle ohne Zähleränderung, + - bereits bestehende M4–M6-Datenbestände mit historischen Fehlerzählern. +- Die Entscheidungslogik so schneiden, dass sie konsistent für bereits bestehende M4–M6-Datenbestände nutzbar bleibt und keine Sonderbehandlung außerhalb des zentralen Regelwerks erzwingt. +- Explizit sicherstellen, dass Skip-Fälle keine Fehlerzähler verändern. +- Explizit sicherstellen, dass der technische Sofort-Wiederholversuch **nicht** in diese laufübergreifende Retry-Entscheidung einfließt. +- JavaDoc für Regelherkunft, Zählerbedeutung, Grenzwertinterpretation und Nicht-Ziele von M7 ergänzen. + +### Explizit nicht Teil +- Batch-Use-Case-Integration +- Persistenzfortschreibung im konkreten Dokumentlauf +- Zielkopier-Wiederholung +- Logging-Konfiguration +- Exit-Code-Logik + +### Fertig wenn +- die Retry-Entscheidung zentral und testbar implementiert ist, +- deterministische und transiente Fehler vollständig und widerspruchsfrei abgedeckt sind, +- bestehende M4–M6-Zähler- und Statusdaten ohne Sonderlogik anschlussfähig bleiben, +- der Stand fehlerfrei buildbar bleibt. + +--- + +## AP-003 Technischen Sofort-Wiederholversuch für den Zielkopierpfad aus M6 implementieren + +### Voraussetzung +AP-001 und AP-002 sind abgeschlossen. + +### Ziel +Der in der Zielarchitektur vorgesehene einmalige technische Sofort-Wiederholversuch für Zielkopierfehler wird sauber umgesetzt, ohne KI, Persistenzlogik oder laufübergreifende Retry-Semantik zu vermischen. + +### Muss umgesetzt werden +- Den bestehenden M6-Zielkopierpfad so erweitern, dass bei einem technischen Schreibfehler **genau ein** zusätzlicher technischer Sofort-Wiederholversuch innerhalb desselben Dokumentlaufs möglich ist. +- Sicherstellen, dass der Sofort-Wiederholversuch ausschließlich für den physischen Zielkopierpfad gilt, insbesondere für: + - temporäre Zieldatei nicht anlegbar, + - Kopieren scheitert, + - finaler Move/Rename scheitert, + - technisches Cleanup nach erstem Schreibfehler nur teilweise erfolgreich. +- Sicherstellen, dass dabei **kein** erneuter KI-Aufruf, **keine** erneute fachliche Proposal-Ableitung und **keine** neue Statusneubewertung außerhalb des M7-Regelrahmens stattfindet. +- Den Mechanismus so schneiden, dass der zweite technische Versuch mit demselben fachlichen Dokumentkontext läuft und der Batch-Lauf danach genau **ein** dokumentbezogenes Ergebnis für Persistenz und Statusfortschreibung ableiten kann. +- Technische Aufräumarbeiten zwischen erstem und zweitem Versuch kontrolliert kapseln. +- JavaDoc für Reichweite, Grenzen und Abgrenzung zu laufübergreifenden Retries ergänzen. + +### Explizit nicht Teil +- endgültige Status- und Zählerfortschreibung im Batch-Lauf +- Logging-Endstand +- Bootstrap-Anpassungen +- Erweiterung auf andere Fehlerarten als Zielkopierschreibfehler + +### Fertig wenn +- genau ein technischer Sofort-Wiederholversuch für Zielkopierfehler möglich ist, +- kein KI- oder Fachpfad unzulässig erneut ausgelöst wird, +- das Ergebnis kontrolliert an den späteren Batch-/Persistenzpfad übergeben werden kann, +- der Stand fehlerfrei buildbar bleibt. + +--- + +## AP-004 Logging-Infrastruktur, Korrelation und Sensibilitätsregel für M7 vorbereiten + +### Voraussetzung +AP-001 ist abgeschlossen. + +### Ziel +Die Logging-Infrastruktur ist für den M7-Endstand vorbereitet, die Sensibilitätsregel für KI-Inhalte ist technisch korrekt verdrahtet und dokumentbezogene Ereignisse können später im Batch-Lauf konsistent und eindeutig korreliert geloggt werden. + +### Muss umgesetzt werden +- Die bestehende Logging-Infrastruktur gezielt so erweitern, dass der in M7 geforderte Mindestumfang später ohne zusätzliche Architekturbrüche angebunden werden kann. +- Einen klar dokumentierten, booleschen Konfigurationswert für sensible KI-Logausgaben einführen und verdrahten. +- Sicherstellen, dass die vollständige KI-Rohantwort standardmäßig **nicht** geloggt wird. +- Sicherstellen, dass vollständiges KI-`reasoning` standardmäßig **nicht** vollständig geloggt wird. +- Sicherstellen, dass die vollständige KI-Rohantwort und das vollständige KI-`reasoning` weiterhin in SQLite verbleiben können und M7 hier keine Reduktion oder Löschung der Nachvollziehbarkeit einführt. +- Einen M7-tauglichen Mechanismus für dokumentbezogene Log-Korrelation vorbereiten, insbesondere: + - Lauf-ID-basierte Korrelation vor erfolgreicher Fingerprint-Ermittlung, + - Fingerprint- oder eindeutig ableitbare Dokumentreferenz nach erfolgreicher Fingerprint-Ermittlung. +- Die logbaren Ereignis- und Entscheidungsmodelle aus AP-001 an die Logging-Infrastruktur anbinden, ohne dass fachliche Entscheidungslogik in technische Logger-Aufrufe zerfällt. +- Bereits auf dieser Stufe die nicht dokumentgebundenen Pflicht-Logpunkte sauber verdrahten, insbesondere: + - Laufstart, + - Laufende, + - harte Startfehler, soweit auf aktuellem Stand erreichbar. +- JavaDoc und ggf. `package-info` für Logging-Sensibilität, Korrelation, Mindestumfangsvorbereitung und Architekturgrenzen ergänzen. + +### Explizit nicht Teil +- vollständige Batch-Integration aller dokumentbezogenen M7-Logpunkte +- Finalisierung der Retry- und Skip-Hooks im Dokumentlauf +- Startvalidierung des Endstands +- finale Exit-Code-Verdrahtung +- Tests des gesamten Endstands + +### Fertig wenn +- die Logging-Infrastruktur den M7-Endstand ohne Zusatzannahmen tragen kann, +- die Sensibilitätsregel standardmäßig auf „nicht loggen" steht, +- sensible KI-Inhalte nur über explizite Konfiguration logbar sind, +- dokumentbezogene Log-Korrelation technisch vorbereitet ist, +- der Stand fehlerfrei buildbar bleibt. + +--- + +## AP-005 Repository-, Persistenz- und Nachvollziehbarkeitsanpassungen für den M7-Endstand ergänzen + +### Voraussetzung +AP-001, AP-002 und AP-004 sind abgeschlossen. + +### Ziel +Die bestehende Persistenz aus M4–M6 unterstützt die vollständige M7-Fehler-, Retry-, Skip- und Logging-Nachvollziehbarkeit ohne neue Wahrheitsquelle und ohne unnötige Schema-Neuerfindung. + +### Muss umgesetzt werden +- Prüfen und gezielt ergänzen, welche Repository-Fähigkeiten für den M7-Endstand tatsächlich fehlen, ohne das bestehende Zwei-Ebenen-Modell neu zu entwerfen. +- Bestehende Repository-Operationen so erweitern oder schärfen, dass sie für M7 reproduzierbar unterstützen: + - Finalisierung ausgeschöpfter Retry-Rahmen, + - konsistente Fortschreibung von Inhalts- und Transientfehlerzählern, + - historisierte Skip-Ereignisse, + - dokumentbezogene Fehlerklassifikation und Retryable-Flag im Endstand, + - lesende Auswertung der bestehenden Versuchshistorie, soweit für Retry- und Skip-Entscheidungen zwingend erforderlich, + - konsistente Nachvollziehbarkeit zwischen Log-Entscheidung und SQLite-Historie. +- Falls für den M7-Endstand zusätzliche lesende Auswertungen der bestehenden Versuchshistorie nötig sind, diese gezielt ergänzen, ohne Reporting- oder Statistikfunktionalität vorwegzunehmen. +- Nur dann eine Schemaevolution vornehmen, wenn sie für den M7-Zielstand **zwingend** erforderlich ist; andernfalls ausdrücklich beim bestehenden M6-Schema bleiben. +- Sicherstellen, dass bestehende M4–M6-Datenbestände lesbar und korrekt fortschreibbar bleiben. +- Sicherstellen, dass der spätere Batch-Lauf aus AP-006 alle für M7 notwendigen Persistenzoperationen bereits vorfindet und **keine** impliziten Repository-Erweiterungen mehr nachschieben muss. +- JavaDoc für Nachvollziehbarkeit, bestehende Persistenz-Wahrheit und M7-Grenzen ergänzen. + +### Explizit nicht Teil +- vollständige Batch-Use-Case-Integration der M7-Regeln +- neue dritte Persistenzebene +- Reporting/Analytics +- Bootstrap-Anpassungen +- Logging-Framework-Konfiguration +- M8-Gesamtreview + +### Fertig wenn +- die Persistenz den vollständigen M7-Endstand konsistent unterstützt, +- keine unnötige Schema-Neuerfindung oder Parallelwahrheit eingeführt wurde, +- bestehende M4–M6-Datenbestände anschlussfähig bleiben, +- der Stand fehlerfrei buildbar bleibt. + +--- + +## AP-006 M7-Batch-Integration für Skip-Logik, Finalisierung ausgeschöpfter Retries, Logging-Hooks und konsistente Fehlerfortschreibung umsetzen + +### Voraussetzung +AP-001 bis AP-005 sind abgeschlossen. + +### Ziel +Der bestehende M6-Lauf wird zum vollständigen M7-Lauf erweitert, der Retry-Entscheidungen, Finalisierung, Skip-Verhalten, Sofort-Wiederholversuch, dokumentbezogene Logging-Hooks und konsistente Status-/Persistenzfortschreibung zusammenführt. + +### Muss umgesetzt werden +- Den bestehenden Batch-Use-Case so erweitern, dass pro Dokument die vollständigen M7-Regeln wirksam werden. +- Folgende Regeln explizit umsetzen: + - `SUCCESS` → kein erneuter fachlicher Durchlauf, stattdessen `SKIPPED_ALREADY_PROCESSED` historisieren, + - `FAILED_FINAL` → kein erneuter fachlicher Durchlauf, stattdessen `SKIPPED_FINAL_FAILURE` historisieren, + - `FAILED_RETRYABLE`, `READY_FOR_AI` und `PROPOSAL_READY` bleiben verarbeitbar, + - deterministische Inhaltsfehler werden nach dem zweiten historisierten Auftreten finalisiert, + - transiente technische Fehler werden bei Erreichen des Grenzwerts `max.retries.transient` finalisiert. +- Sicherstellen, dass der technische Sofort-Wiederholversuch aus AP-003 ausschließlich im Zielkopierpfad wirkt und danach in **genau eine** dokumentbezogene Status- und Persistenzfortschreibung mündet. +- Sicherstellen, dass dokumentbezogene Fehler und Finalisierungen den Batch-Lauf für andere Dokumente nicht unnötig abbrechen. +- Sicherstellen, dass Historie und Stammsatz pro identifiziertem Dokument weiterhin konsistent fortgeschrieben werden und kein teilpersistierter M7-Zustand zurückbleibt. +- Vor-Fingerprint-Fehler weiterhin ausdrücklich **nicht** als SQLite-Versuch historisieren. +- Die vorbereitete Logging-Infrastruktur aus AP-004 an den fachlich relevanten Batch-Entscheidungspunkten anbinden, so dass der finale M7-Mindestumfang vollständig erreicht wird, insbesondere: + - erkannte Quelldatei, + - Überspringen bereits erfolgreicher Dateien, + - Überspringen final fehlgeschlagener Dateien, + - erzeugter Zielname, + - Retry-Entscheidung, + - Fehler mit Klassifikation. +- Sicherstellen, dass dokumentbezogene Logs nach erfolgreicher Fingerprint-Ermittlung den Fingerprint oder eine eindeutig ableitbare Referenz enthalten und vor erfolgreicher Fingerprint-Ermittlung mindestens über Lauf-ID und Kandidatenbezug korreliert werden können. +- JavaDoc für M7-Laufreihenfolge, Finalisierung ausgeschöpfter Retries, Skip-Regeln, Logging-Hooks und Fehlerfortschreibung ergänzen. + +### Explizit nicht Teil +- Bootstrap- und Startvalidierungsanpassungen +- finale Exit-Code-Verdrahtung +- End-to-End-Tests +- M8-Feinschliff + +### Fertig wenn +- der Batch-Lauf die vollständige M7-Retry- und Skip-Semantik umsetzt, +- ausgeschöpfte Retry-Rahmen zu `FAILED_FINAL` führen, +- der Sofort-Wiederholversuch korrekt in den Dokumentlauf integriert ist, +- der finale dokumentbezogene Logging-Mindestumfang des M7-Stands vollständig angebunden ist, +- dokumentbezogene Fehler den Gesamtbatch kontrolliert weiterlaufen lassen, +- der Stand fehlerfrei buildbar bleibt. + +--- + +## AP-007 Bootstrap-, Startvalidierungs- und Exit-Code-Finalisierung für den M7-Endstand durchführen + +### Voraussetzung +AP-001 bis AP-006 sind abgeschlossen. + +### Ziel +Der Programmeinstieg ist sauber auf den M7-Endstand verdrahtet; die finale Startvalidierung greift, dokumentbezogene Fehler werden korrekt von Startfehlern getrennt und das endgültige Exit-Code-Verhalten ist vollständig umgesetzt. + +### Muss umgesetzt werden +- Bootstrap-Verdrahtung auf die neuen M7-Bausteine erweitern. +- M7-relevante Konfiguration ergänzen bzw. validieren, insbesondere für: + - `max.retries.transient` als **Integer >= 1**, + - den booleschen Konfigurationswert für sensible KI-Logausgaben, + - bestehende M1–M6-Parameter, soweit sie für den robusten Endstand zwingend benötigt werden. +- Startvalidierung so vervollständigen, dass ungültige M7-Konfiguration den Lauf **vor** dem Batch-Beginn stoppt. +- Sicherstellen, dass harte Start-, Verdrahtungs-, Konfigurations- oder Initialisierungsfehler weiterhin zu **Exit-Code 1** führen. +- Sicherstellen, dass dokumentbezogene Fehler aus M3–M7 **nicht** zu Exit-Code 1 eskalieren, solange der Batch-Lauf technisch ordnungsgemäß durchgeführt werden konnte. +- Die M7-Logging-Verdrahtung so in den Startpfad integrieren, dass Laufstart, Laufende und harte Startfehler nachvollziehbar protokolliert werden. +- JavaDoc und `package-info` für aktualisierte Verdrahtung, Konfigurationsvalidierung, Exit-Code-Endsemantik und Modulgrenzen ergänzen. + +### Explizit nicht Teil +- komplette Test-Suite +- M8-Qualitätsmaßnahmen +- neue fachliche Verarbeitung jenseits des M7-Zielbilds + +### Fertig wenn +- das Programm im M7-Stand vollständig startbar ist, +- die M7-Startvalidierung greift, +- das finale Exit-Code-Verhalten vollständig umgesetzt ist, +- dokumentbezogene Fehler nicht als Startfehler fehlmodelliert werden, +- der Build fehlerfrei bleibt. + +--- + +## AP-008 Tests für Retry-Abläufe über mehrere Läufe, Sofort-Wiederholversuch, Logging-Sensibilität und Exit-Code-Endverhalten vervollständigen + +### Voraussetzung +AP-001 bis AP-007 sind abgeschlossen. + +### Ziel +Der vollständige M7-Zielzustand wird automatisiert abgesichert und als konsistenter Übergabestand nachgewiesen. + +### Muss umgesetzt werden +- Tests für Retry-Abläufe über mehrere Läufe implementieren, insbesondere für: + - erster deterministischer Inhaltsfehler → `FAILED_RETRYABLE`, + - zweiter deterministischer Inhaltsfehler → `FAILED_FINAL`, + - transiente technische Fehler bleiben bis zum konfigurierten Grenzwert retryable, + - der transiente Fehlversuch am Grenzwert finalisiert zu `FAILED_FINAL`, + - `max.retries.transient = 1` finalisiert beim ersten historisierten transienten Fehlversuch, + - `max.retries.transient = 0` wird als ungültige Startkonfiguration abgewiesen. +- Tests für finale Fehlerzustände ergänzen, insbesondere: + - `FAILED_FINAL` wird im Wiederholungslauf historisiert übersprungen, + - `SUCCESS` wird im Wiederholungslauf historisiert übersprungen, + - Skip-Ereignisse verändern keine Fehlerzähler. +- Tests für den technischen Sofort-Wiederholversuch im Zielkopierpfad ergänzen, insbesondere: + - erster Schreibversuch scheitert, zweiter gelingt, + - beide Schreibversuche scheitern, + - kein erneuter KI-Aufruf, + - kein zusätzlicher laufübergreifender Retry-Zähler durch den Sofort-Wiederholversuch. +- Tests für Logging-Sensibilitätsregel ergänzen, soweit automatisierbar, insbesondere: + - vollständige KI-Rohantwort wird standardmäßig nicht geloggt, + - vollständiges KI-`reasoning` wird standardmäßig nicht vollständig geloggt, + - vollständige KI-Rohantwort bleibt in SQLite verfügbar, + - vollständiges KI-`reasoning` bleibt in SQLite verfügbar, + - explizite Freischaltung sensibler KI-Logausgabe wirkt nur kontrolliert. +- Tests für Logging-Korrelation ergänzen, soweit automatisierbar, insbesondere: + - vor erfolgreicher Fingerprint-Ermittlung ist Kandidatenbezug über Lauf-ID und Quelldatei nachvollziehbar, + - nach erfolgreicher Fingerprint-Ermittlung tragen dokumentbezogene Logs den Fingerprint oder eine eindeutig ableitbare Referenz. +- Tests für finales Exit-Code-Verhalten ergänzen, insbesondere: + - `0` bei technisch ordnungsgemäßem Lauf trotz dokumentbezogener Fehler, + - `1` bei harter ungültiger Startkonfiguration, + - `1` bei harten Bootstrap-/Initialisierungsfehlern, + - dokumentbezogene Fehler aus M3–M7 führen nicht zu Exit-Code 1. +- Tests für Konfigurationsvalidierung ergänzen, insbesondere: + - ungültiges `max.retries.transient`, + - ungültige Logging-Sensitivitätskonfiguration, + - M7-Startkonfiguration verhindert bei Ungültigkeit den Laufbeginn. +- Integrationstests für den vollständigen M7-Ablauf ergänzen, insbesondere: + - robuster Happy-Path mit `SUCCESS`, + - dokumentbezogene Teilfehler blockieren den Batch nicht, + - ausgeschöpfte Retry-Rahmen führen stabil zu terminalen Skip-Folgeläufen, + - bestehendes `PROPOSAL_READY` kann weiter bis zum Enderfolg finalisiert werden, + - M4–M6-Altbestände bleiben anschlussfähig. +- Den M7-Stand abschließend auf Konsistenz, Architekturtreue und Nicht-Vorgriff auf M8+ prüfen. + +### Explizit nicht Teil +- M8-Gesamtfreigabe +- zusätzliche Qualitätskampagnen außerhalb des M7-Zielumfangs + +### Fertig wenn +- die Test-Suite für den M7-Umfang grün ist, +- die wichtigsten Retry-, Finalisierungs-, Logging-, Korrelation- und Exit-Code-Randfälle automatisiert abgesichert sind, +- der definierte M7-Zielzustand vollständig erreicht ist, +- ein fehlerfreier, übergabefähiger Stand vorliegt. + +--- + +## Abschlussbewertung + +Die Arbeitspakete decken den vollständigen M7-Zielumfang aus den verbindlichen Spezifikationen ab und schließen die betriebliche Lücke zwischen dem M6-Erfolgspfad und dem final robusten Endstand sauber: + +- vollständige Retry-Logik über spätere Läufe +- saubere Finalisierung nach ausgeschöpften Retry-Rahmen +- technischer Sofort-Wiederholversuch ausschließlich für Zielkopierfehler +- vollständige Skip-Semantik für `SUCCESS` und `FAILED_FINAL` +- finaler Logging-Mindestumfang +- Sensibilitätsregel für KI-Inhalte im Logging +- präzise Korrelation zwischen Logs und dokumentbezogenen Entscheidungen +- finale Exit-Code-Semantik +- vervollständigte Startvalidierung +- konsistente Nachvollziehbarkeit in Logs und SQLite +- Tests für Mehrlauf-Retries, Sofort-Wiederholversuch, Logging-Sensibilität und Exit-Code-Endverhalten + +Gleichzeitig bleiben die Grenzen zu M1–M6 sowie zu M8+ gewahrt. Insbesondere werden **keine** neuen Fachfunktionen, **kein** M8-Gesamtfeinschliff und **keine** unnötigen Parallelwahrheiten für Persistenz oder Retry-Zustände eingeführt.