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

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.