Vorbereitungen zu V1.1

CLAUDE.md

@@ -6,7 +6,6 @@ Dieses Repository implementiert einen lokal gestarteten **PDF-Umbenenner mit KI*
 ## Autoritative Dokumente
 @docs/specs/technik-und-architektur.md
 @docs/specs/fachliche-anforderungen.md
-@docs/specs/meilensteine.md
 
 Für die Umsetzung ist zusätzlich immer das aktuell aktive Arbeitspaket unter `docs/workpackages/` maßgeblich.
 Nicht raten, wenn Dokumente fehlen, unklar sind oder sich widersprechen.
@@ -16,7 +15,6 @@ Die Dokumente haben folgende feste Bedeutung:
 
 - `docs/specs/technik-und-architektur.md` = verbindliche technische Zielarchitektur
 - `docs/specs/fachliche-anforderungen.md` = verbindliche fachliche Regeln
-- `docs/specs/meilensteine.md` = zulässiger Funktionsumfang pro Meilenstein
 - `docs/workpackages/...` = verbindlicher Scope, Reihenfolge und Inhalt des aktuell bearbeiteten Arbeitspakets
 
 Bei Konflikten gilt folgende Priorität:
@@ -27,10 +25,7 @@ Bei Konflikten gilt folgende Priorität:
 2. **Fachliche Anforderungen**
    Verbindliche fachliche Regeln und fachliches Zielverhalten.
 
-3. **Meilensteine**
-   Begrenzen den zulässigen Funktionsumfang auf den aktuellen Entwicklungsstand.
-
-4. **Arbeitspakete**
+3. **Arbeitspakete**
    Definieren den konkret erlaubten Umsetzungsumfang des aktuellen Schritts.
 
 Wenn Dokumente fehlen, unklar sind oder sich widersprechen, nicht raten und keine stillen Annahmen treffen.
@@ -46,8 +41,11 @@ Wenn Dokumente fehlen, unklar sind oder sich widersprechen, nicht raten und kein
 - kein interner Scheduler
 - Log4j2 für Logging
 - SQLite als lokaler Persistenzspeicher
-- OpenAI-kompatible HTTP-Schnittstelle für KI-Zugriff
-- API-Provider, Base-URL und Modellname sind **Konfiguration**, keine Architekturentscheidung
+- KI-Anbindung über genau **eine** der beiden unterstützten Provider-Familien:
+  - **OpenAI-kompatible HTTP-Schnittstelle** (Chat-Completions-Stil)
+  - **native Anthropic Messages API** (Claude-Modelle)
+- Pro Lauf ist genau ein Provider aktiv. Kein Fallback, keine Parallelnutzung.
+- Konkrete Provider-Familie, Base-URL und Modellname sind **Konfiguration**, keine Architekturentscheidung.
 
 ## Verbindliche Modulstruktur
 - `pdf-umbenenner-domain`
@@ -67,6 +65,9 @@ Wenn Dokumente fehlen, unklar sind oder sich widersprechen, nicht raten und kein
 - Keine Vermischung von Dateisystem, PDF-Auslese, SQLite, KI-HTTP, Konfiguration, Logging, Benennungslogik und Retry-Entscheidungen
 - Logging ist technische Infrastruktur, kein fachlicher Port
 - Port-Verträge enthalten weder `Path`/`File` noch NIO- oder JDBC-Typen
+- Der `AiNamingPort` bleibt provider-neutral; provider-spezifische Typen, Header, URLs und Antwortstrukturen leben ausschließlich in der jeweiligen Adapter-Out-Implementierung
+- Es gibt keine gemeinsame „abstrakte KI-Adapter"-Zwischenschicht zwischen Port und konkreten Adaptern
+- Die Bootstrap-Schicht wählt die **eine** aktive `AiNamingPort`-Implementierung anhand der Konfiguration aus
 
 ## Globale fachliche Leitplanken
 - Zielformat: `YYYY-MM-DD - Titel.pdf`
@@ -85,30 +86,18 @@ Wenn Dokumente fehlen, unklar sind oder sich widersprechen, nicht raten und kein
 
 ## Aktiver Implementierungsstand
 
-M1 bis M7 sind vollständig abgeschlossen. Der aktive Stand ist der **Abschlussmeilenstein**:
-Qualitätssicherung, Feinschliff und vollständige Entwicklungsfreigabe des Gesamtstands.
+Die fachliche und technische Basis ist vollständig umgesetzt, dokumentiert, getestet (inkl. PIT-Mutationstests, Smoke-Tests, End-to-End-Tests) und freigegeben.
 
-### Baseline aus M7
-- Vollständige laufübergreifende Retry-Logik (deterministisch + transient)
-- Technischer Sofort-Wiederholversuch für Zielkopierfehler
-- Finalisierung ausgeschöpfter Retry-Rahmen zu `FAILED_FINAL`
-- Vollständige Skip-Semantik (`SUCCESS`, `FAILED_FINAL`)
-- Logging-Mindestumfang vollständig angebunden
-- Sensibilitätsregel für KI-Inhalte im Logging
-- Finale Exit-Code-Semantik und vervollständigte Startvalidierung
+Der aktive Stand ist die Erweiterung **„Zusätzlicher KI-Provider Anthropic Claude über die native Messages API"**. Sie ist eine bewusst minimale Erweiterung des freigegebenen Basisstands.
 
-### Ziel des aktiven Stands
-M8 schließt **ausschließlich nachweisbare Restlücken** des aus M1–M7 entstandenen Gesamtstands:
-- Architekturgrenzen und code-nahe Dokumentation finalisieren
-- Status-, Persistenz- und Zielzustandskonsistenz bereinigen
-- Betreiberrelevante Logging-, Fehlertext- und Startvalidierungsrückmeldungen schärfen
-- Konfigurationsbeispiele, Prompt-Bezug und Betriebsdokumentation konsolidieren
-- Deterministische End-to-End-Testbasis bereitstellen
-- Regressionstests für Kernregeln vervollständigen
-- Kritische Coverage- und Mutationslücken schließen
-- Integrierte Gesamtprüfung mit Befundliste durchführen
-- Nachgewiesene Release-Blocker gezielt beheben
-- Finale Gesamtprüfung und Freigabedokumentation erstellen
+### Ziel der aktiven Erweiterung
+- Der bestehende OpenAI-kompatible KI-Weg bleibt unverändert nutzbar.
+- Zusätzlich wird die **native Anthropic Messages API** als zweite, gleichwertig unterstützte Provider-Familie integriert.
+- Genau **ein** Provider ist pro Lauf aktiv – ausschließlich über Konfiguration ausgewählt.
+- **Kein** automatischer Fallback, **keine** Parallelnutzung, **keine** Profilverwaltung.
+- Der fachliche KI-Vertrag (`NamingProposal` aus Application-/Domain-Sicht) bleibt unverändert.
+- Bestehende Properties-Dateien aus dem Vorgängerstand werden beim ersten Start kontrolliert in das neue Schema migriert; vorher wird automatisch eine `.bak`-Sicherung angelegt.
+- Architekturgrenzen, Persistenzmodell, Statussemantik, Retry-Semantik, Exit-Code-Verhalten und Logging-Mindestumfang bleiben unverändert; sie werden ausschließlich um den Provider-Identifikator und die Provider-Auswahl ergänzt.
 
 ## Statussemantik
 
@@ -136,7 +125,7 @@ M8 schließt **ausschließlich nachweisbare Restlücken** des aus M1–M7 entsta
 - Proposal-Versuch mit fachlich unbrauchbarem Titel oder Datum = inkonsistenter Persistenzzustand = dokumentbezogener technischer Fehler.
 - Inkonsistente Proposal-Zustände werden **nicht stillschweigend geheilt**, sondern als technische Dokumentfehler behandelt.
 
-## Retry-Semantik (aktiver Stand)
+## Retry-Semantik
 
 ### Deterministische Inhaltsfehler
 Deterministische Inhaltsfehler sind insbesondere:
@@ -154,7 +143,7 @@ Regel:
 - Sie bleiben retryable bis der konfigurierte Grenzwert `max.retries.transient` erreicht ist.
 - Der Fehlversuch, der den Grenzwert **erreicht**, finalisiert den Dokumentstatus zu `FAILED_FINAL`.
 - `max.retries.transient` = **Integer >= 1**; der Wert `0` ist ungültige Startkonfiguration.
-- Beispiel: `max.retries.transient = 1` → erster transiente Fehlversuch finalisiert sofort.
+- Die Klassifikation gilt provider-unabhängig: Technische Fehler aus dem aktiven KI-Provider werden in dieselbe transiente Kategorie eingeordnet wie bisher. Der inaktive Provider wird in keiner Fehlersituation als Backup verwendet.
 
 ### Technischer Sofort-Wiederholversuch
 - **Genau ein** zusätzlicher technischer Schreibversuch innerhalb desselben Dokumentlaufs.
@@ -168,10 +157,11 @@ Regel:
 - `FAILED_FINAL` → in späteren Läufen `SKIPPED_FINAL_FAILURE` historisieren, keine Zähleränderung.
 - `FAILED_RETRYABLE`, `READY_FOR_AI`, `PROPOSAL_READY` → verarbeitbar.
 
-## Logging-Mindestumfang (aktiver Stand)
+## Logging-Mindestumfang
 
 Folgende Informationen müssen nachvollziehbar geloggt werden:
 - Laufstart mit Lauf-ID
+- aktiver KI-Provider für den Lauf
 - Laufende
 - erkannte Quelldatei
 - Überspringen bereits erfolgreicher Dateien
@@ -190,13 +180,14 @@ Folgende Informationen müssen nachvollziehbar geloggt werden:
 - Vollständiges KI-`reasoning`: standardmäßig **nicht** ins Log, bleibt in SQLite.
 - Freischaltung nur über expliziten booleschen Konfigurationswert.
 - Default: sicher / nicht loggen.
+- Die Sensibilitätsregel gilt provider-unabhängig.
 
-## Verarbeitungsreihenfolge pro Dokument (aktiver Stand)
+## Verarbeitungsreihenfolge pro Dokument
 
 1. Fingerprint berechnen
 2. Dokument-Stammsatz laden
 3. Terminale Skip-Fälle entscheiden (`SUCCESS` → `SKIPPED_ALREADY_PROCESSED`, `FAILED_FINAL` → `SKIPPED_FINAL_FAILURE`)
-4. Falls nötig: Pfad bis `PROPOSAL_READY` durchlaufen (inkl. KI-Aufruf)
+4. Falls nötig: Pfad bis `PROPOSAL_READY` durchlaufen (inkl. KI-Aufruf über den aktiven Provider)
 5. Führenden `PROPOSAL_READY`-Versuch laden
 6. Finalen Basis-Dateinamen bilden
 7. Dubletten-Suffix im Zielordner bestimmen
@@ -211,14 +202,15 @@ Folgende Informationen müssen nachvollziehbar geloggt werden:
 - Bei technischem Schreibfehler: genau ein Sofort-Wiederholversuch (nur Zielkopierpfad)
 - Bei Persistenzfehler nach erfolgreicher Zielkopie: kein `SUCCESS` setzen, best-effort Rückbau der Zielkopie, Ergebnis bleibt dokumentbezogener technischer Fehler
 
-## Fehlersemantik (aktiver Stand)
+## Fehlersemantik
 - Technische Fehler → `FAILED_RETRYABLE`, Transientfehlerzähler +1
 - Bei Erreichen von `max.retries.transient` → `FAILED_FINAL`
 - Kein Abbruch des Batch-Laufs für andere Dokumente
 - Keine neue finale Fehlerkategorie
 - Vor-Fingerprint-Fehler werden **nicht** als SQLite-Versuch historisiert
+- Provider-spezifische Fehlerausprägungen (HTTP-Fehler, Auth-Fehler, Antwort-Schema-Fehler) werden im jeweiligen Adapter klassifiziert und auf die bestehenden Fehlerkategorien abgebildet. Es entstehen keine neuen Fehlerklassen.
 
-## Persistenz (aktiver Stand)
+## Persistenz
 
 Zwei-Ebenen-Modell bleibt unverändert – keine dritte Wahrheitsquelle.
 
@@ -230,35 +222,40 @@ Zwei-Ebenen-Modell bleibt unverändert – keine dritte Wahrheitsquelle.
 **Versuchshistorie** enthält u.a.:
 - finalen Zieldateinamen
 - Fehlerklasse, Fehlermeldung, Retryable-Flag
+- **Provider-Identifikator des aktiven KI-Providers für den Versuch**
 
 **Invariante:** Der führende `PROPOSAL_READY`-Versuch wird nicht überschrieben.
 Jeder Lauf erzeugt einen **zusätzlichen** neuen Versuchseintrag.
 
+**Rückwärtsverträglichkeit:** Bestehende Datenbestände bleiben lesbar, fortschreibbar und korrekt interpretierbar. Schema-Erweiterungen sind additiv mit definierten Defaultwerten für historische Versuche ohne Provider-Identifikator.
+
 ## Naming-Regel (verbindlich für alle Arbeitspakete)
 In Implementierungen, Kommentaren und JavaDoc dürfen **keine** Meilenstein- oder
 Arbeitspaket-Bezeichner erscheinen:
 
-- Verboten: `M1`, `M2`, `M3`, `M4`, `M5`, `M6`, `M7`, `M8`
+- Verboten: `M1`, `M2`, …, `M8`
 - Verboten: `AP-001`, `AP-002`, … `AP-00x`
+- Verboten: Versionsbezeichner wie `V1.0`, `V1.1` in Code/JavaDoc
 
 Stattdessen werden **zeitlose technische Bezeichnungen** verwendet.
 Bestehende Kommentare mit solchen Bezeichnern, die durch eigene Änderungen berührt werden, sind zu ersetzen.
 
 ## Arbeitsweise
-- Arbeite immer nur im **explizit aktiven Meilenstein** und im **explizit aktiven Arbeitspaket**
-- **Kein Vorgriff** auf spätere Meilensteine oder Arbeitspakete
+- Arbeite immer nur im **explizit aktiven Arbeitspaket**
+- **Kein Vorgriff** auf spätere Arbeitspakete
 - Änderungen klein, fokussiert und architekturtreu halten
 - Keine unnötigen Umbenennungen, keine großflächigen Refactorings ohne Not
 - Vor Änderungen zuerst die betroffenen Dateien und Abhängigkeiten verstehen
 - **Keine Annahmen über Dateipfade.** Typen und Klassen werden per Suche nach Typname gefunden, nicht über vermutete Pfade.
 - Keine Vermutungen: Bei echter Unklarheit oder Dokumentkonflikten knapp nachfragen oder den Konflikt benennen
+- Keine stillen Änderungen am bestehenden OpenAI-kompatiblen KI-Weg
 
 ## Definition of Done pro Arbeitspaket
 Ein Arbeitspaket ist erst fertig, wenn:
 - der Zielumfang des aktuellen Arbeitspakets vollständig umgesetzt ist
 - der Stand konsistent, fehlerfrei und buildbar ist
 - Implementierung, Konfiguration, JavaDoc und Tests ergänzt sind, **soweit für den Stand sinnvoll**
-- keine Inhalte späterer Meilensteine vorweggenommen wurden
+- keine Inhalte späterer Arbeitspakete vorweggenommen wurden
 - der Zwischenstand in sich geschlossen und übergabefähig ist
 
 ## Pflicht-Output-Format nach jedem Arbeitspaket
@@ -279,17 +276,17 @@ Ein Arbeitspaket ist erst fertig, wenn:
 - Nach Änderungen den kleinsten sinnvollen Build-/Test-Umfang ausführen
 - Build-Validierung vom Parent-Root:
   `.\mvnw.cmd clean verify -pl pdf-umbenenner-domain,pdf-umbenenner-application,pdf-umbenenner-adapter-out,pdf-umbenenner-adapter-in-cli,pdf-umbenenner-bootstrap --also-make`
-- M8 hat 10 Arbeitspakete (AP-001 bis AP-010) – Start mit `-EndAp 10`
 - Schlägt der Build fehl: Fehler beheben, erneut bauen, erst dann weiter
 - Vor Abschluss sicherstellen, dass der relevante Maven-Reactor-Stand fehlerfrei ist
 - Fehler nicht kaschieren; Ursachen sauber beheben oder offen benennen
 
 ## Wichtige Betriebsregeln
 - Ungültige Startkonfiguration verhindert den Verarbeitungslauf und führt zu Exit-Code `1`
+- Eine ungültige oder fehlende Provider-Auswahl ist eine ungültige Startkonfiguration
 - Run-Lock verhindert parallele Instanzen; wenn bereits eine Instanz läuft, beendet sich die neue Instanz sofort
 - Exit-Code `0`: Lauf technisch ordnungsgemäß ausgeführt, auch wenn einzelne Dateien fachlich oder transient fehlgeschlagen sind
 - Exit-Code `1`: harter Start-/Bootstrap-Fehler
-- Umgebungsvariable hat Vorrang vor Properties beim API-Key
+- API-Schlüssel: pro Provider eine eigene Umgebungsvariable, Vorrang vor Properties derselben Provider-Familie. Schlüssel verschiedener Provider werden niemals vermischt.
 - Dokumentbezogene Fehler führen **nicht** zu Exit-Code `1`
 
 ## Konfigurationsparameter
@@ -297,9 +294,7 @@ Verbindlich zweckmäßige Parameter:
 - `source.folder` – Quellordner
 - `target.folder` – Zielordner (muss vorhanden oder anlegbar sein, Schreibzugriff erforderlich)
 - `sqlite.file` – SQLite-Datenbankdatei
-- `api.baseUrl` – KI-Basis-URL
-- `api.model` – Modellname
-- `api.timeoutSeconds` – Timeout
+- `ai.provider.active` – aktiver KI-Provider (Pflicht; zulässige Werte sind die Bezeichner der unterstützten Provider-Familien)
 - `max.retries.transient` – max. historisierte transiente Fehlversuche pro Fingerprint (**Integer >= 1**, `0` ist ungültig)
 - `max.pages` – Seitenlimit
 - `max.text.characters` – maximale Zeichenzahl für KI-Eingabe
@@ -307,7 +302,43 @@ Verbindlich zweckmäßige Parameter:
 - `log.ai.sensitive` – sensible KI-Logausgabe freischalten (Boolean, Default: `false`)
 - `runtime.lock.file` – Lock-Datei (optional)
 - `log.directory` – Log-Verzeichnis (optional)
-- `api.key` – API-Key (Umgebungsvariable hat Vorrang)
+
+Pro Provider-Familie existiert ein eigener Parameter-Namensraum mit zweckmäßig:
+- Modellname
+- API-Schlüssel (Umgebungsvariable hat Vorrang)
+- Timeout
+- Basis-URL (optional, wo betrieblich sinnvoll)
+
+Konkretes Schema (zweckmäßig):
+
+```properties
+ai.provider.active=openai-compatible
+
+ai.provider.openai-compatible.baseUrl=...
+ai.provider.openai-compatible.model=...
+ai.provider.openai-compatible.timeoutSeconds=...
+ai.provider.openai-compatible.apiKey=...
+
+ai.provider.claude.baseUrl=...
+ai.provider.claude.model=...
+ai.provider.claude.timeoutSeconds=...
+ai.provider.claude.apiKey=...
+```
+
+### Migration historischer Konfiguration
+Bestehende Properties-Dateien des Vorgängerstands (mit flachen Schlüsseln wie `api.baseUrl`, `api.model`, `api.timeoutSeconds`, `api.key`) werden beim ersten Start erkannt und kontrolliert in das neue Schema überführt.
+
+Verbindlicher Ablauf:
+1. Legacy-Form erkennen
+2. **`.bak`-Sicherung** der Originaldatei anlegen
+3. Inhalt in das neue Schema überführen
+   - Legacy-Werte landen im Namensraum **`openai-compatible`**
+   - `ai.provider.active` wird auf `openai-compatible` gesetzt
+4. Datei in-place schreiben
+5. Datei erneut laden und validieren
+6. Erst danach den normalen Lauf fortsetzen
+
+Alte und neue Struktur sind **kein** dauerhaft gleichrangiges Endformat.
 
 ## Nicht-Ziele / Verbote
 - kein Web-UI
@@ -318,24 +349,15 @@ Verbindlich zweckmäßige Parameter:
 - keine interne Scheduler-Logik
 - keine Architekturbrüche
 - keine neuen Bibliotheken oder Frameworks ohne klare Notwendigkeit und Begründung
-- keine stillen Änderungen an Provider-Bindung oder Architekturprinzipien
+- **keine** automatische Fallback-Umschaltung zwischen KI-Providern
+- **keine** parallele Nutzung mehrerer KI-Provider in einem Lauf
+- **keine** Profilverwaltung mit mehreren Konfigurationen je Provider-Familie
+- **keine** Provider-Familien jenseits der explizit unterstützten (OpenAI-kompatibel, Anthropic Messages API)
+- keine stillen Änderungen am bestehenden OpenAI-kompatiblen KI-Weg
 - kein Sofort-Wiederholversuch außerhalb des Zielkopierpfads
 - keine Reporting- oder Statistikfunktionen
 - keine neue dritte Persistenz-Wahrheitsquelle für Retry-Entscheidungen
 - keine neue Fachfunktionalität jenseits des definierten Zielbilds
-- kein großflächiges Refactoring ohne nachweisbaren M8-Defektbezug
-- keine Metrik-Kosmetik (willkürliche Ausschlüsse, nicht belastbare Testumgehungen)
+- kein großflächiges Refactoring ohne nachweisbaren Defektbezug
 - keine spekulativen Umbauten ohne konkreten Qualitäts- oder Konsistenzbezug
-- kein gleichzeitiger unbeschränkter Review und unbegrenzte Behebung in einem AP
-
-## M8-spezifische Arbeitsregeln
-
-**Review vor Behebung:** Gesamtprüfung (AP-008), Blockerbehebung (AP-009) und Freigabe (AP-010) sind getrennte Arbeitsschritte. Ein AP darf nicht gleichzeitig alles prüfen und alles beheben.
-
-**Nur nachweisbare Restlücken:** Änderungen müssen auf konkrete, belegbare Befunde aus dem realen Projektstand zurückführbar sein.
-
-**Rückwärtsverträglichkeit:** M4–M7-Datenbestände müssen weiterhin lesbar, fortschreibbar und korrekt interpretierbar bleiben.
-
-**Befunddatei im Repository:** AP-008 erzeugt eine im Repository verbleibende Befundliste mit Klassifizierung in Release-Blocker und nicht blockierende Punkte.
-
-**Freigabenachweis:** AP-010 erzeugt eine nachvollziehbare Entwicklungsfreigabe-Dokumentation im Repository, gestützt auf tatsächlich ausgeführte Prüfungen.
+- keine Vermischung von API-Schlüsseln verschiedener Provider-Familien