diff --git a/docs/workpackages/M6 - Arbeitspakete.md b/docs/workpackages/M6 - Arbeitspakete.md new file mode 100644 index 0000000..f6da468 --- /dev/null +++ b/docs/workpackages/M6 - Arbeitspakete.md @@ -0,0 +1,525 @@ +# M6 - Arbeitspakete + +## Geltungsbereich + +Dieses Dokument beschreibt ausschließlich die Arbeitspakete für den definierten Meilenstein **M6 – Dateinamensbildung, Dublettenbehandlung und Zielkopie**. + +Die Meilensteine **M1**, **M2**, **M3**, **M4** und **M5** 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 **M7+**. +- Kein Umbau bestehender M1–M5-Strukturen ohne direkten M6-Bezug. +- Neue Typen, Ports, Statusübergänge, Migrationen und Adapter so schneiden, dass sie aus einem einzelnen Arbeitspaket heraus **klar benennbar, testbar und reviewbar** sind. +- M6 baut auf dem in M5 persistierten, validierten Benennungsvorschlag auf und führt **keine zweite Wahrheitsquelle** für Datum, Titel oder Reasoning ein. +- Jedes Arbeitspaket muss so präzise sein, dass **KI 1** keine offenen Fach- oder Architekturentscheidungen an **KI 2** delegieren muss. +- M6 endet fachlich mit dem **echten Enderfolg**: korrekt benannte Zielkopie vorhanden und Erfolg konsistent persistiert. + +## Explizit nicht Bestandteil von M6 + +- fachliche Retry-Logik des Endstands über mehrere spätere Läufe hinaus, soweit sie über die bereits vorhandene Minimalfehlersemantik hinausgeht +- technischer Sofort-Wiederholversuch für Zielkopierfehler innerhalb desselben Laufs +- Logging-Feinschliff und Sensibilitätsregeln des Endstands aus M7 +- neue KI-Funktionalität, Prompt-Evolution oder M5-Fachlogik jenseits der für M6 nötigen Weiterverwendung +- manuelle Nachbearbeitung oder Benutzerinteraktion +- Reporting-, Statistik- oder Auswertungsfunktionen +- spätere Betriebsoptimierungen, die nicht für den M6-Zielstand notwendig sind + +## Verbindliche M6-Regeln für **alle** Arbeitspakete + +### 1. Führende Quelle des Benennungsvorschlags + +- Die führende Quelle für Datum, Datumsquelle, validierten Titel und Reasoning bleibt in M6 der **neueste Versuchshistorieneintrag mit Ergebnisstatus `PROPOSAL_READY`**. +- M6 rekonstruiert diesen Benennungsvorschlag **nicht** aus dem Dokument-Stammsatz. +- M6 erzeugt **keinen neuen KI-Aufruf**, wenn bereits ein nutzbarer `PROPOSAL_READY`-Versuch vorliegt. +- Ein Dokumentzustand `PROPOSAL_READY` ohne lesbaren, konsistenten `PROPOSAL_READY`-Versuch gilt in M6 als **dokumentbezogener technischer Fehler**, nicht als stiller Anlass für eine heimliche Neuinterpretation. +- Ein geladener `PROPOSAL_READY`-Versuch mit fachlich oder technisch unbrauchbaren Kernwerten für Datum oder Titel gilt ebenfalls als **inkonsistenter Persistenzzustand** und damit als **dokumentbezogener technischer Fehler**. + +### 2. Positive Status- und Übergangssemantik in M6 + +Ab M6 gilt verbindlich: + +- `READY_FOR_AI` bleibt verarbeitbar. +- `FAILED_RETRYABLE` bleibt verarbeitbar. +- `PROPOSAL_READY` ist der **fachlich korrekte Eingangszustand** für Dateinamensbildung, Dublettenbehandlung und Zielkopie. +- `SUCCESS` ist ab M6 der **echte terminale Enderfolg** nach erfolgreicher Zielkopie und konsistenter Persistenz. +- `FAILED_FINAL` bleibt terminal und wird nicht erneut fachlich verarbeitet. +- `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. + +### 3. Verbindliche Dateinamensregeln in M6 + +Der finale Zieldateiname folgt technisch verbindlich diesem Muster: + +```text +YYYY-MM-DD - Titel.pdf +``` + +Dabei gilt: + +- das Datum stammt aus dem führenden M5-Benennungsvorschlag, +- der Titel stammt aus dem führenden M5-Benennungsvorschlag, +- die **20 Zeichen** gelten nur für den **Basistitel**, +- das Dubletten-Suffix zählt **nicht** zu diesen 20 Zeichen, +- die fachliche Titelregel **„keine Sonderzeichen außer Leerzeichen“** bleibt auch in M6 verbindlich abgesichert, +- Windows-unzulässige Zeichen werden nur im Rahmen der **technischen Dateisystemzulässigkeit** kontrolliert entfernt oder ersetzt, +- diese technische Bereinigung darf **keine neue fachliche Titelinterpretation** erzeugen, +- wenn ein geladener Proposal-Titel entgegen der M5-Semantik die fachlichen Titelregeln verletzt, wird dieser Zustand **nicht stillschweigend geheilt**, sondern als **inkonsistenter technischer Dokumentzustand** behandelt, +- die Quelldatei bleibt unverändert. + +### 4. Dublettenregel in M6 + +- Die Dublettenregel wird im **Zielordner** physisch gegen bereits vorhandene Dateien aufgelöst. +- Der erste freie Name ist zu verwenden: + - `YYYY-MM-DD - Titel.pdf` + - `YYYY-MM-DD - Titel(1).pdf` + - `YYYY-MM-DD - Titel(2).pdf` + - usw. +- Das Suffix wird unmittelbar vor `.pdf` angehängt. +- Die Dublettenauflösung ist rein technisch und führt **keine** neue fachliche Titelvariante ein. + +### 5. Zielkopie und Dateisystemsemantik + +- M6 erzeugt bei Erfolg **eine Kopie** im Zielordner. +- Die Quelldatei wird **nicht** verändert, verschoben, gelöscht oder überschrieben. +- Die Zielerzeugung erfolgt über eine temporäre Zieldatei mit anschließendem finalem Move/Rename, soweit dies im Zielkontext technisch möglich ist. +- M6 führt **keinen** fachlichen oder technischen Sofort-Mehrfachversuch für die Zielkopie ein; dieser ist M7 vorbehalten. + +### 6. Persistenzerweiterung und Historisierung in M6 + +Die Persistenz wird in M6 gezielt erweitert: + +- Der **Dokument-Stammsatz** speichert zusätzlich mindestens: + - letzten Zielpfad, + - letzten Zieldateinamen. +- Die **Versuchshistorie** speichert zusätzlich mindestens: + - finalen Zieldateinamen. +- Datum, Datumsquelle, validierter Titel und Reasoning bleiben weiterhin führend in der Versuchshistorie des `PROPOSAL_READY`-Versuchs und werden nicht redundant in den Stammsatz gespiegelt. +- Ein M6-Enderfolg oder M6-Fehler wird als **zusätzlicher neuer Versuch** historisiert; der führende `PROPOSAL_READY`-Versuch bleibt dabei **unverändert erhalten**. +- M6 überschreibt oder ersetzt **nicht** nachträglich den führenden Proposal-Versuch, sondern baut fachlich und historisch auf ihm auf. + +### 7. Reihenfolge pro Dokument in M6 + +Die Verarbeitung eines einzelnen Kandidaten erfolgt in M6 verbindlich in dieser Reihenfolge: + +1. Fingerprint berechnen +2. Dokument-Stammsatz laden +3. terminale Skip-Fälle entscheiden +4. falls nötig den bestehenden M5-Pfad bis zu einem gültigen Benennungsvorschlag ausführen +5. führenden `PROPOSAL_READY`-Versuch laden +6. finalen Basis-Dateinamen bilden +7. Dubletten-Suffix im Zielordner bestimmen +8. Zielkopie technisch schreiben +9. einen **neuen** M6-Versuch für Enderfolg oder technischen Fehler historisieren +10. Dokument-Stammsatz konsistent fortschreiben + +### 8. Erfolg und Konsistenz in M6 + +- `SUCCESS` darf erst gesetzt werden, wenn: + 1. die Zielkopie erfolgreich geschrieben wurde, + 2. der finale Zieldateiname bestimmt ist, + 3. die zugehörige Persistenz konsistent fortgeschrieben wurde. +- Es darf **kein** Fall entstehen, in dem ein Dokument als `SUCCESS` persistiert ist, ohne dass die Zielkopie erfolgreich vorliegt. +- Wenn die Persistenz nach erfolgreicher Zielkopie scheitert, ist **kein** `SUCCESS` zu setzen; ein best-effort Rückbau der neu erzeugten Zielkopie ist in M6 zweckmäßig und architekturtreu vorzusehen. +- Wenn dieser Rückbau selbst nur teilweise gelingt, bleibt der Fall ein **dokumentbezogener technischer Fehler**; M6 erfindet daraus weder einen Erfolg noch eine neue finale Fehlerkategorie. + +### 9. Fehlersemantik in M6 + +- Technische Fehler bei Proposal-Quelllesung, Zielpfadbildung, Dublettenauflösung, Zielkopie oder M6-relevanter Persistenz nach erfolgreicher Fingerprint-Ermittlung sind in M6 **dokumentbezogene technische Fehler**. +- Diese Fehler bleiben retryable und laufen über den **Transientfehlerzähler**. +- M6 führt **keine** neue finale Fehlerkategorie nur für Zielkopierfehler ein. +- Dokumentbezogene M6-Fehler dürfen den Batch-Lauf für andere Dokumente nicht unnötig abbrechen. + +### 10. Kein Vorgriff auf M7 + +M6 liefert den vollständigen Erfolgspfad für Dateinamensbildung, Dublettenbehandlung und Zielkopie, aber ausdrücklich **nicht**: + +- den technischen Sofort-Wiederholversuch beim Schreiben, +- den finalen Logging-Feinschliff, +- die vollständige Betriebsrobustheit und Retry-Ausarbeitung des Endstands. + +--- + +## AP-001 M6-Kernobjekte, Zielerfolgssemantik und Port-Verträge präzisieren + +### Voraussetzung +Keine. Dieses Arbeitspaket ist der M6-Startpunkt. + +### Ziel +Die M6-relevanten Typen, Erfolgskriterien, Zielartefakt-Begriffe und Port-Verträge werden eindeutig eingeführt, damit spätere Arbeitspakete ohne Interpretationsspielraum implementiert werden können. + +### Muss umgesetzt werden +- Neue M6-relevante Kernobjekte bzw. Application-nahe Typen anlegen, insbesondere für: + - finalen Dateinamenkandidaten, + - Dublettenauflösung bzw. Namenskollision, + - Zielartefakt-Planung, + - Zielschreib-Ergebnis, + - M6-bezogene Persistenzdaten für den Enderfolg, + - lesbaren führenden Benennungsvorschlag aus dem neuesten `PROPOSAL_READY`-Versuch, + - inkonsistenten Proposal-Quellzustand. +- Die M6-Statussemantik in JavaDoc und ggf. `package-info` so schärfen, dass klar ist: + - `PROPOSAL_READY` ist M6-verarbeitbar, + - `SUCCESS` ist nur nach echter Zielkopie plus konsistenter Persistenz zulässig, + - `SUCCESS` und `FAILED_FINAL` bleiben terminale Skip-Zustände, + - ein inkonsistenter Zustand `PROPOSAL_READY` ohne lesbare führende Versuchsdaten ein technischer Dokumentfehler ist, + - ein M6-Endversuch zusätzlich zum Proposal-Versuch historisiert wird und diesen nicht ersetzt. +- Outbound-Ports definieren oder gezielt erweitern für: + - Laden des führenden `PROPOSAL_READY`-Versuchs, + - technische Dublettenauflösung im Zielordner, + - Zielkopie/Schreiboperation, + - Persistenz der M6-Zieldaten. +- Port-Verträge so schneiden, dass **weder `Path`/`File` noch NIO-/JDBC-Typen** in Domain oder Application durchsickern. +- Rückgabemodelle so anlegen, dass spätere Arbeitspakete ohne Zusatzannahmen unterscheiden können zwischen: + - nutzbarem führenden Benennungsvorschlag, + - fehlendem oder inkonsistentem Proposal-Quellzustand, + - erfolgreicher Dublettenauflösung, + - technischem Zielschreibfehler, + - technischem Persistenzfehler nach Zielkopie, + - konsistentem M6-Enderfolg. +- Explizit dokumentieren, dass M6 **keine zweite Wahrheitsquelle** für Datum, Titel und Reasoning einführt. +- Explizit dokumentieren, dass M6 **keinen Sofort-Wiederholversuch** der Zielkopie einführt. + +### Explizit nicht Teil +- konkrete Dateisystem-Implementierung +- konkrete SQLite-Schemaänderungen +- Batch-Integration +- reale Zielkopie +- Tests für das Endverhalten + +### Fertig wenn +- die M6-relevanten Typen und Port-Verträge vorhanden sind, +- Zielerfolg, Proposal-Quelle, inkonsistente Proposal-Zustände und technische Fehlerarten klar unterscheidbar modelliert sind, +- Domain und Application frei von Infrastrukturtypen bleiben, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-002 Technische Dateinamensbildung für den finalen M6-Basisnamen implementieren + +### Voraussetzung +AP-001 ist abgeschlossen. + +### Ziel +Aus dem führenden M5-Benennungsvorschlag kann ein technischer, finaler M6-Basisdateiname im Zielformat erzeugt werden, ohne bereits eine physische Zielkopie oder Dublettenauflösung im Dateisystem auszuführen. + +### Muss umgesetzt werden +- Einen M6-Baustein für die technische Dateinamensbildung implementieren. +- Das verbindliche Zielformat exakt umsetzen: + +```text +YYYY-MM-DD - Titel.pdf +``` + +- Den Basistitel aus dem führenden M5-Benennungsvorschlag übernehmen und technisch in einen final verwendbaren M6-Basisdateinamen überführen. +- Die fachliche Titelregel **„keine Sonderzeichen außer Leerzeichen“** im M6-Kontext explizit absichern: + - regulärer Happy-Path: der bereits validierte M5-Titel wird unverändert weiterverwendet, + - inkonsistenter Persistenzfall: ein geladener Proposal-Titel, der diese Regel verletzt, wird **nicht** stillschweigend fachlich umgedeutet, sondern als technischer Dokumentfehler behandelt. +- Windows-unzulässige Zeichen kontrolliert entfernen oder ersetzen, **soweit dies ausschließlich der technischen Dateisystemzulässigkeit dient**. +- Sicherstellen, dass die **20-Zeichen-Regel** ausschließlich für den **Basistitel** gilt und nicht für ein späteres Dubletten-Suffix. +- Keine neue fachliche Titelinterpretation einführen; M6 baut auf dem bereits validierten M5-Titel auf. +- Einen defensiven technischen Schutz für inkonsistente Persistenzzustände vorsehen, falls ein geladener Proposal-Titel oder Proposal-Datumswert entgegen der M5-Semantik nicht verwertbar ist. +- JavaDoc für Zielformat, fachliche Titelregel, Windows-Kompatibilität, Basistitelbegriff und Nicht-Ziele von M6 ergänzen. + +### Explizit nicht Teil +- Dublettenprüfung gegen den Zielordner +- physische Zielkopie +- Persistenzänderungen +- Batch-Orchestrierung +- Zielpfadbildung im Dateisystem + +### Fertig wenn +- aus einem nutzbaren M5-Benennungsvorschlag deterministisch ein M6-Basisdateiname erzeugt werden kann, +- das Zielformat exakt eingehalten wird, +- die fachliche Titelregel und die technische Windows-Kompatibilität **klar getrennt** behandelt werden, +- inkonsistente Proposal-Daten nicht stillschweigend fachlich bereinigt werden, +- weiterhin keine physische Zielkopie oder Dublettenauflösung erfolgt, +- der Stand fehlerfrei buildbar bleibt. + +--- + +## AP-003 Zielordnerzugriff, Dublettenauflösung und Zielpfadplanung im Adapter-Out implementieren + +### Voraussetzung +AP-001 und AP-002 sind abgeschlossen. + +### Ziel +Der Zielordner kann technisch bewertet werden, der erste freie finale Zieldateiname im Zielkontext wird bestimmt und eine konsistente Zielpfadplanung steht für die spätere Kopieroperation bereit. + +### Muss umgesetzt werden +- Dateisystem-Adapter für den Zielordnerzugriff implementieren. +- Technische Dublettenauflösung im Zielordner umsetzen. +- Den ersten freien Namen nach folgender Regel bestimmen: + - ohne Suffix, + - dann `(1)`, `(2)`, … direkt vor `.pdf`. +- Sicherstellen, dass das Dubletten-Suffix **nicht** in die 20-Zeichen-Regel des Basistitels eingerechnet wird. +- Die Zielpfadplanung so schneiden, dass sie den finalen Zielnamen und eine technische temporäre Zieldatei im Zielkontext vorbereiten kann. +- Technische Fehler beim Lesen des Zielordners oder bei der Namensauflösung kontrolliert in den Port-Vertrag überführen. +- JavaDoc für Zielordnerzugriff, Kollisionserkennung, Suffixlogik und technische Grenzen ergänzen. + +### Explizit nicht Teil +- tatsächliches Kopieren der Datei +- Persistenz von Zielpfad oder Zieldateiname +- Batch-Use-Case-Integration +- M7-Sofort-Wiederholversuch + +### Fertig wenn +- der Zielordner technisch ausgewertet werden kann, +- der erste freie finale Zieldateiname korrekt bestimmbar ist, +- eine temporäre und finale Zielpfadplanung bereitsteht, +- technische Fehler kontrolliert über den Port geliefert werden, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-004 Zielkopie mit temporärer Zieldatei und finalem Move/Rename implementieren + +### Voraussetzung +AP-001 bis AP-003 sind abgeschlossen. + +### Ziel +Eine Quelldatei kann als M6-Zielartefakt technisch in den Zielordner kopiert werden, wobei temporäre Zielerzeugung und finaler Move/Rename sauber gekapselt sind. + +### Muss umgesetzt werden +- Einen Adapter-Out für die physische Zielkopie implementieren. +- Die Zielerzeugung so umsetzen, dass mindestens folgender technischer Ablauf möglich ist: + 1. Kopie in eine temporäre Zieldatei im Zielkontext, + 2. finaler Move/Rename auf den zuvor geplanten finalen Zieldateinamen. +- Sicherstellen, dass die Quelldatei unverändert bleibt. +- Kontrolliertes technisches Fehlerverhalten mindestens für folgende Fälle umsetzen: + - Zielordner nicht schreibbar, + - temporäre Zieldatei nicht anlegbar, + - Kopieren scheitert, + - finaler Move/Rename scheitert, + - technische Aufräumarbeiten nach Fehler nur teilweise möglich. +- Das Ergebnis so modellieren, dass spätere Arbeitspakete zwischen erfolgreicher Zielerzeugung, technischem Schreibfehler und technischem Teil-Cleanup unterscheiden können. +- JavaDoc für Zielkopie, temporäre Datei, finalen Move/Rename und Quellunverändertheit ergänzen. + +### Explizit nicht Teil +- Statusfortschreibung im Use Case +- Persistenz von Enderfolg oder Zielpfad +- Batch-Integration +- technischer Sofort-Wiederholversuch im selben Lauf + +### Fertig wenn +- eine Zielkopie technisch erzeugt werden kann, +- temporäre und finale Schreibschritte sauber gekapselt sind, +- die Quelldatei unverändert bleibt, +- technische Zielschreibfehler kontrolliert abgebildet werden, +- der Build weiterhin fehlerfrei ist. + +--- + +## AP-005 SQLite-Schema von M5 nach M6 evolvieren und M6-Zieldaten sowie Proposal-Quelle gezielt nutzbar machen + +### Voraussetzung +AP-001 bis AP-004 sind abgeschlossen. + +### Ziel +Die bestehende M5-Persistenz wird kontrolliert auf den M6-Stand erweitert, sodass Zielpfad, finaler Zieldateiname und der führende `PROPOSAL_READY`-Versuch technisch sauber nutzbar sind, ohne die M5-Historie umzudeuten oder zu überschreiben. + +### Muss umgesetzt werden +- Das bestehende SQLite-Schema **evolvieren**, nicht neu erfinden. +- Die Schema-Initialisierung so erweitern, dass ein vorhandenes M5-Schema kontrolliert auf den M6-Stand gebracht werden kann. +- Den Dokument-Stammsatz um die für M6 benötigten Felder erweitern, mindestens für: + - letzten Zielpfad, + - letzten Zieldateinamen. +- Die Versuchshistorie um das für M6 benötigte Feld erweitern, mindestens für: + - finalen Zieldateinamen. +- Repository-Mapping so erweitern, dass die neuen M6-Zieldaten technisch schreib- und lesbar sind. +- Eine gezielte Lesefähigkeit bereitstellen oder erweitern, um den **neuesten Versuch mit `PROPOSAL_READY`** als führende Proposal-Quelle für M6 zu laden. +- Explizit sicherstellen, dass M6 bei Enderfolg oder technischem M6-Fehler **einen neuen Versuchseintrag** anlegt und den führenden Proposal-Versuch **nicht überschreibt**. +- Sicherstellen, dass: + - bestehende M5-Daten weiterhin lesbar bleiben, + - die M6-Erweiterung idempotent initialisierbar ist, + - keine M7+-Felder vorweggenommen werden, + - keine redundante zweite Persistenzwahrheit für Datum, Titel und Reasoning im Stammsatz entsteht. +- JavaDoc für Schemaevolution, führende Proposal-Quelle, neue M6-Versuchseinträge, M6-Zieldaten und Rückwärtsverträglichkeit ergänzen. + +### Explizit nicht Teil +- Batch-Use-Case-Integration +- reale Zielkopie +- Status- und Zählerentscheidungen im laufenden Dokumentprozess +- M7-Retry-Ausarbeitung + +### Fertig wenn +- das M5-Schema kontrolliert auf M6 erweitert werden kann, +- Zielpfad und Zieldateiname technisch persistierbar sind, +- der neueste `PROPOSAL_READY`-Versuch gezielt lesbar ist, +- M6-Enderfolg/-Fehler historisch **zusätzlich** speicherbar sind, ohne den Proposal-Versuch zu ersetzen, +- bestehende M5-Daten nicht unbrauchbar werden, +- der Stand fehlerfrei buildbar bleibt. + +--- + +## AP-006 M6-Entscheidungslogik und Batch-Integration für Enderfolg, Proposal-Quelle, Skip-Semantik und technische Fehlerfortschreibung umsetzen + +### Voraussetzung +AP-001 bis AP-005 sind abgeschlossen. + +### Ziel +Der bestehende M5-Lauf wird zu einem echten M6-Lauf erweitert, der aus geeigneten Dokumenten eine korrekt benannte Zielkopie erzeugt, den Enderfolg als `SUCCESS` persistiert und technische M6-Fehler sauber im vorhandenen Zähler- und Statusrahmen fortschreibt. + +### Muss umgesetzt werden +- Den bestehenden Batch-Use-Case so erweitern, dass pro geeignetem Dokument zusätzlich gilt: + 1. terminale Skip-Fälle auswerten, + 2. falls nötig den M5-Pfad bis zu einem gültigen `PROPOSAL_READY` durchlaufen, + 3. bei vorhandenem `PROPOSAL_READY` den führenden Proposal-Versuch laden, + 4. finalen Basisdateinamen bilden, + 5. Dubletten-Suffix im Zielordner bestimmen, + 6. Zielkopie erzeugen, + 7. **einen neuen M6-Versuch** für Enderfolg oder technischen Fehler historisieren, + 8. Stammsatz konsistent fortschreiben. +- Sicherstellen, dass **kein neuer KI-Aufruf** erfolgt, wenn bereits ein nutzbarer `PROPOSAL_READY`-Versuch vorliegt. +- Sicherstellen, dass ein Dokument mit Status `PROPOSAL_READY` im M6-Lauf **nicht** fälschlich übersprungen wird, sondern in die M6-Finalisierung geht. +- Folgende Regeln explizit umsetzen: + - `SUCCESS` → kein erneuter fachlicher Durchlauf, stattdessen `SKIPPED_ALREADY_PROCESSED` + - `FAILED_FINAL` → kein erneuter fachlicher Durchlauf, stattdessen `SKIPPED_FINAL_FAILURE` + - gültige Zielkopie plus konsistente Persistenz → `SUCCESS` + - technischer Fehler bei Proposal-Quelllesung, inkonsistentem Proposal-Zustand, Zielpfadbildung, Dublettenauflösung, Zielkopie oder M6-Persistenz → `FAILED_RETRYABLE`, **Transientfehlerzähler +1** +- Sicherstellen, dass der finale Zieldateiname und der Zielpfad bei echtem Enderfolg konsistent persistiert werden. +- Sicherstellen, dass bei erfolgreicher Zielkopie, aber scheiternder Persistenz **kein** `SUCCESS` entsteht. +- Für den Fall einer nachgelagerten Persistenzstörung nach bereits erzeugter Zielkopie einen **best-effort Rückbau** des neu erzeugten Zielartefakts vorsehen, ohne M7-Retry-Verhalten vorwegzunehmen. +- Sicherstellen, dass dokumentbezogene M6-Fehler den Batch-Lauf für andere Dokumente kontrolliert weiterlaufen lassen. +- JavaDoc für M6-Laufreihenfolge, Proposal-Quelle, echte Enderfolgssemantik, neue M6-Historisierung, Skip-Regeln und Fehlerfortschreibung ergänzen. + +### Explizit nicht Teil +- technischer Sofort-Wiederholversuch der Zielkopie +- Logging-Feinschliff des Endstands +- M7-spezifische Retry-Ausarbeitung +- Reporting oder Auswertung + +### Fertig wenn +- der Batch-Lauf geeignete Dokumente bis zur korrekt benannten Zielkopie verarbeiten kann, +- bestehende `PROPOSAL_READY`-Dokumente in M6 korrekt finalisiert werden, +- inkonsistente Proposal-Zustände kontrolliert als technische Dokumentfehler behandelt werden, +- `SUCCESS` nur nach echter Zielkopie plus konsistenter Persistenz gesetzt wird, +- M6-Enderfolg und M6-Fehler als **zusätzliche** Historieneinträge entstehen, +- technische M6-Fehler sauber als retryable fortgeschrieben werden, +- weiterhin keine M7+-Funktionalität enthalten ist. + +--- + +## AP-007 Bootstrap- und CLI-Anpassungen für Zielordner-Konfiguration, M6-Schemaevolution und vollständige Verdrahtung durchführen + +### Voraussetzung +AP-001 bis AP-006 sind abgeschlossen. + +### Ziel +Der Programmeinstieg ist sauber an den M6-Lauf angepasst; Zielordner-Konfiguration, M6-Schemaevolution und alle neuen M6-Bausteine sind verdrahtet und harte Startfehler führen weiterhin kontrolliert zu Exit-Code 1. + +### Muss umgesetzt werden +- Bootstrap-Verdrahtung auf die neuen M6-Ports, Adapter und Persistenzbausteine erweitern. +- M6-relevante Konfiguration ergänzen bzw. verdrahten, insbesondere für: + - `target.folder` +- Startvalidierung so ergänzen, dass mindestens geprüft wird: + - Zielordner ist vorhanden oder technisch anlegbar, + - Zielordner ist als Verzeichnis nutzbar, + - Zielordner ist für den M6-Schreibpfad technisch verwendbar, + - M6-relevante Persistenzkonfiguration bleibt nutzbar. +- Die bestehende M5-Schemainitialisierung sauber mit der M6-Schemaevolution kombinieren. +- Sicherstellen, dass harte Start-, Verdrahtungs-, Konfigurations- oder Initialisierungsfehler weiterhin zu **Exit-Code 1** führen. +- Sicherstellen, dass dokumentbezogene M6-Fehler **nicht** als Startfehler fehlmodelliert werden. +- JavaDoc und `package-info` für aktualisierte Verdrahtung, Konfiguration, Zielordner-Validierung und Modulgrenzen ergänzen. + +### Explizit nicht Teil +- Logging-Feinschliff des Endstands +- M7-Retry-Mechanik +- spätere Betriebsoptimierungen + +### Fertig wenn +- das Programm im M6-Stand vollständig startbar ist, +- alle M6-Bausteine korrekt verdrahtet sind, +- die M6-Startvalidierung greift, +- harte Startfehler weiterhin kontrolliert zu Exit-Code 1 führen, +- der Build fehlerfrei bleibt. + +--- + +## AP-008 Tests für Dateinamensbildung, Dublettenbehandlung, Zielkopie, Schemaevolution, Proposal-Konsistenz, Statussemantik und M6-Ablauf vervollständigen + +### Voraussetzung +AP-001 bis AP-007 sind abgeschlossen. + +### Ziel +Der vollständige M6-Zielzustand wird automatisiert abgesichert und als konsistenter Übergabestand nachgewiesen. + +### Muss umgesetzt werden +- Unit-Tests für die technische Dateinamensbildung implementieren, insbesondere für: + - korrektes Zielformat `YYYY-MM-DD - Titel.pdf`, + - fachliche Titelregel „keine Sonderzeichen außer Leerzeichen“ im M6-Kontext, + - Windows-Zeichenbereinigung, + - unveränderte 20-Zeichen-Regel des Basistitels, + - unveränderte Wirkung des Dubletten-Suffixes außerhalb des Basistitels. +- Tests für die Dublettenauflösung im Zielordner implementieren, insbesondere für: + - kein vorhandener Konflikt → Basename wird verwendet, + - vorhandener Konflikt → `(1)`, `(2)`, …, + - Suffix wird unmittelbar vor `.pdf` gesetzt. +- Adapter-Tests für die Zielkopie ergänzen, insbesondere für: + - erfolgreiche Zielerzeugung über temporäre Datei plus finalen Move/Rename, + - Quelldatei bleibt unverändert, + - technischer Kopierfehler, + - technischer Rename-/Move-Fehler, + - best-effort Cleanup nach technischem Fehler. +- Repository- und Schema-Tests gegen SQLite ergänzen, insbesondere für: + - Evolution eines M5-Schemas auf M6, + - Persistenz und Auslesen von Zielpfad und Zieldateiname im Dokument-Stammsatz, + - Persistenz und Auslesen des finalen Zieldateinamens in der Versuchshistorie, + - gezieltes Laden des neuesten `PROPOSAL_READY`-Versuchs, + - zusätzliche M6-Historisierung ohne Überschreiben des Proposal-Versuchs. +- Integrationstests für den M6-Ablauf ergänzen, insbesondere: + - gültiger M6-Happy-Path endet in `SUCCESS`, **nicht** in `PROPOSAL_READY`, + - vorhandenes `PROPOSAL_READY` wird ohne erneuten KI-Aufruf finalisiert, + - bestehendes `SUCCESS` wird im Wiederholungslauf historisiert übersprungen, + - bestehendes `FAILED_FINAL` wird im Wiederholungslauf historisiert übersprungen, + - technischer M6-Zielkopierfehler führt zu retryablem technischem Fehler und erhöht den Transientfehlerzähler, + - erfolgreicher Zielschreibpfad mit scheiternder Persistenz führt **nicht** zu `SUCCESS`, + - bei M3- oder M5-Vorfehlern erfolgt keine unzulässige M6-Finalisierung, + - Status `PROPOSAL_READY`, aber **kein** lesbarer führender Proposal-Versuch führt zu dokumentbezogenem technischem Fehler, + - lesbarer Proposal-Versuch mit inkonsistentem Titel- oder Datumswert führt zu dokumentbezogenem technischem Fehler, + - es entsteht weiterhin **keine** M7-Sofort-Wiederholung. +- Tests für Bootstrap- und Startverhalten ergänzen, insbesondere: + - ungültige M6-Konfiguration führt zu Exit-Code 1, + - nicht nutzbarer Zielordner führt zu Exit-Code 1, + - M6-Schemaevolution wird beim Start wirksam, + - dokumentbezogene M6-Fehler führen **nicht** zu Exit-Code 1. +- Den M6-Stand abschließend auf Konsistenz, Architekturtreue und Nicht-Vorgriff auf M7+ prüfen. + +### Explizit nicht Teil +- Tests für M7-Sofort-Wiederholversuch +- Tests für finalen Logging-Feinschliff +- Tests für spätere Betriebsoptimierungen + +### Fertig wenn +- die Test-Suite für den M6-Umfang grün ist, +- die wichtigsten M6-Randfälle einschließlich Proposal-Inkonsistenzen automatisiert abgesichert sind, +- der definierte M6-Zielzustand vollständig erreicht ist, +- ein fehlerfreier, übergabefähiger Stand vorliegt. + +--- + +## Abschlussbewertung + +Die Arbeitspakete decken den vollständigen M6-Zielumfang aus den verbindlichen Spezifikationen ab und schließen die Brücke von **M5 `PROPOSAL_READY`** zum echten Produktiv-Enderfolg **M6 `SUCCESS`** sauber: + +- technische Dateinamensbildung im Format `YYYY-MM-DD - Titel.pdf` +- explizite Trennung zwischen fachlicher Titelregel und technischer Windows-Kompatibilität +- Dublettenbehandlung im Zielordner mit `(1)`, `(2)`, … +- Zielpfadplanung und physische Zielkopie +- Persistenzerweiterung um Zielpfad und finalen Zieldateinamen +- Nutzung des neuesten `PROPOSAL_READY`-Versuchs als führende Quelle +- saubere Statussemantik `PROPOSAL_READY` → `SUCCESS` +- zusätzliche M6-Historisierung ohne Überschreiben der M5-Proposal-Historie +- technische Fehlerfortschreibung für Proposal-Quell-, Zielkopier- und Persistenzfehler +- Tests für Dateinamen, Dubletten, Zielkopie, Proposal-Konsistenz, Schemaevolution und End-to-End-M6-Ablauf + +Gleichzeitig bleiben die Grenzen zu M1–M5 sowie zu M7+ gewahrt. Insbesondere werden **kein** Sofort-Wiederholversuch der Zielkopie, **kein** finaler Logging-Feinschliff und **keine** weitergehende Betriebsrobustheit des Endstands vorweggenommen.