Arbeitspakete für M7 erstellt

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.