feat: Sprint 1 — IPA hardening, regression framework, ground-truth review

Track A (Backend):
- Compound word IPA decomposition (schoolbag→school+bag)
- Trailing garbled IPA fragment removal after brackets (R21 fix)
- Regression runner with DB persistence, history endpoints
- Page crop determinism verified with tests

Track B (Frontend):
- OCR Regression dashboard (/ai/ocr-regression)
- Ground Truth Review workflow (/ai/ocr-ground-truth)
  with split-view, confidence highlighting, inline edit,
  batch mark, progress tracking

Track C (Docs):
- OCR-Pipeline.md v5.0 (Steps 5e-5h)
- Regression testing guide
- mkdocs.yml nav update

Track D (Infra):
- TrOCR baseline benchmark script
- run-regression.sh shell script
- Migration 008: regression_runs table

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs-src/development/regression-testing.md

@@ -0,0 +1,166 @@
+# OCR Pipeline Regression Testing
+
+**Stand:** 2026-03-23
+
+---
+
+## Uebersicht
+
+Das Regression Framework stellt sicher, dass Aenderungen an der OCR-Pipeline keine bestehenden
+Ergebnisse verschlechtern. Ground-Truth Sessions dienen als Referenz — nach jeder Code-Aenderung
+wird die Pipeline neu ausgefuehrt und das Ergebnis mit der Referenz verglichen.
+
+---
+
+## Ground Truth markieren
+
+### Via Admin-UI (empfohlen)
+
+1. Oeffne die OCR Pipeline: [/ai/ocr-pipeline](https://macmini:3002/ai/ocr-pipeline)
+2. Lade eine Session und fuehre alle Pipeline-Schritte aus
+3. Pruefe das Ergebnis im Grid Editor (Schritt 10)
+4. Korrigiere Fehler falls noetig (Inline-Edit)
+5. Klicke **"Als Ground Truth markieren"**
+
+### Via API
+
+```bash
+# Bestehende Session als Ground Truth markieren
+curl -X POST "http://macmini:8086/api/v1/ocr-pipeline/sessions/{session_id}/mark-ground-truth"
+
+# Ground Truth entfernen
+curl -X DELETE "http://macmini:8086/api/v1/ocr-pipeline/sessions/{session_id}/mark-ground-truth"
+
+# Alle Ground-Truth Sessions auflisten
+curl "http://macmini:8086/api/v1/ocr-pipeline/ground-truth-sessions"
+```
+
+### Via Ground-Truth Review UI
+
+Fuer die Massenpruefung von 50-100 Sessions:
+
+1. Oeffne [/ai/ocr-ground-truth](https://macmini:3002/ai/ocr-ground-truth)
+2. Filter auf "Offen" (ungeprueft)
+3. Split-View: Bild links, Grid rechts pruefen
+4. Korrekte Zeilen mit Haekchen bestaetigen
+5. Fehler inline korrigieren
+6. "Markieren & Weiter" fuer naechste Session
+
+---
+
+## Regression ausfuehren
+
+### Via Shell-Script (CI/CD)
+
+```bash
+# Standard: macmini:8086
+./scripts/run-regression.sh
+
+# Custom URL
+./scripts/run-regression.sh http://localhost:8086
+
+# Exit-Codes:
+# 0 = alle bestanden
+# 1 = Fehler gefunden
+# 2 = Verbindungsfehler
+```
+
+### Via Admin-UI
+
+1. Oeffne [/ai/ocr-regression](https://macmini:3002/ai/ocr-regression)
+2. Klicke **"Alle Tests starten"**
+3. Ergebnis: Pass/Fail pro Session mit Diff-Details
+
+### Via API
+
+```bash
+# Alle Ground-Truth Sessions testen
+curl -X POST "http://macmini:8086/api/v1/ocr-pipeline/regression/run?triggered_by=script"
+
+# Einzelne Session testen
+curl -X POST "http://macmini:8086/api/v1/ocr-pipeline/sessions/{session_id}/regression/run"
+
+# Verlauf abrufen
+curl "http://macmini:8086/api/v1/ocr-pipeline/regression/history?limit=20"
+```
+
+---
+
+## Ergebnisse lesen
+
+### Diff-Typen
+
+| Typ | Beschreibung |
+|-----|-------------|
+| `structural_changes` | Anzahl Zonen, Spalten oder Zeilen hat sich geaendert |
+| `text_change` | Text einer Zelle hat sich geaendert |
+| `cell_missing` | Zelle war in der Referenz, fehlt jetzt |
+| `cell_added` | Neue Zelle die in der Referenz nicht existierte |
+| `col_type_change` | Spaltentyp einer Zelle hat sich geaendert |
+
+### Status-Bewertung
+
+- **pass**: Keine Diffs → Code-Aenderung hat keine Auswirkung
+- **fail**: Diffs gefunden → pruefen ob gewollt (Feature) oder ungewollt (Regression)
+- **error**: Pipeline-Fehler → Build oder Config-Problem
+
+### Verlauf
+
+Alle Laeufe werden in der Tabelle `regression_runs` persistiert:
+
+```sql
+SELECT id, run_at, status, total, passed, failed, errors, duration_ms, triggered_by
+FROM regression_runs
+ORDER BY run_at DESC
+LIMIT 10;
+```
+
+---
+
+## Best Practices
+
+### Ground-Truth Sessions waehlen
+
+Decke verschiedene Seitentypen ab:
+
+- Woerterbuchseiten (2-3 Spalten, IPA-Klammern)
+- Uebungsseiten (Tabellen, Checkboxen)
+- Seiten mit Illustrationen
+- Seiten ohne IPA (reines Deutsch-Vokabular)
+- Verschiedene Verlage und Layouts
+
+### Workflow vor jedem Commit
+
+```bash
+# 1. Regression laufen lassen
+./scripts/run-regression.sh
+
+# 2. Bei Failure: Diff pruefen
+#    - Gewollte Aenderung? → Ground Truth aktualisieren
+#    - Ungewollte Regression? → Code fixen
+
+# 3. Bei Pass: Commit
+git add . && git commit -m "fix: ..."
+```
+
+---
+
+## Datenbank-Schema
+
+```sql
+CREATE TABLE regression_runs (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    run_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    status VARCHAR(20) NOT NULL,          -- pass, fail, error
+    total INT NOT NULL DEFAULT 0,
+    passed INT NOT NULL DEFAULT 0,
+    failed INT NOT NULL DEFAULT 0,
+    errors INT NOT NULL DEFAULT 0,
+    duration_ms INT,
+    results JSONB NOT NULL DEFAULT '[]',  -- Detail-Ergebnisse pro Session
+    triggered_by VARCHAR(50) DEFAULT 'manual'
+);
+```
+
+Ground-Truth Referenzen werden im `ground_truth` JSONB-Feld der
+`ocr_pipeline_sessions` Tabelle gespeichert.

docs-src/services/klausur-service/OCR-Pipeline.md

@@ -1,7 +1,7 @@
 # OCR Pipeline - Schrittweise Seitenrekonstruktion
 
-**Version:** 4.7.0
-**Status:** Produktiv (Schritte 1–10 + Grid Editor implementiert)
+**Version:** 5.0.0
+**Status:** Produktiv (Schritte 1–10 + Grid Editor + Regression Framework)
 **URL:** https://macmini:3002/ai/ocr-pipeline
 
 ## Uebersicht
@@ -1197,6 +1197,62 @@ des Headwords der vorherigen Zeile). Diese werden von PaddleOCR als garbled Text
 4. Schlaegt IPA im Britfone-Woerterbuch nach
 5. Beruecksichtigt alle Wortteile (z.B. "close sth. down" → `[klˈəʊz dˈaʊn]`)
 
+### Compound Word IPA Decomposition (Step 5e)
+
+Zusammengesetzte Woerter wie "schoolbag" oder "blackbird" haben oft keinen eigenen
+IPA-Eintrag im Woerterbuch. Die Funktion `_decompose_compound()` zerlegt sie:
+
+1. Probiere jede Teilungsposition (min. 3 Zeichen pro Teil)
+2. Wenn beide Teile im Woerterbuch stehen → IPA verketten
+3. Waehle die Teilung mit dem laengsten ersten Teil
+
+**Beispiele:**
+
+| Eingabe | Zerlegung | IPA |
+|---------|-----------|-----|
+| schoolbag | school + bag | skˈuːl + bæɡ |
+| blackbird | black + bird | blæk + bˈɜːd |
+| ice-cream | ice + cream | aɪs + kɹˈiːm |
+
+### Trailing Garbled Fragment Removal (Step 5f)
+
+Nach korrekt erkanntem IPA (z.B. `seat [sˈiːt]`) haengt OCR manchmal
+eine garbled Kopie der IPA-Transkription an: `seat [sˈiːt] belt si:t belt`.
+
+**`_strip_post_bracket_garbled()`** erkennt und entfernt diese:
+
+1. Alles nach dem letzten `]` scannen
+2. Woerter mit IPA-Markern (`:`, `ə`, `ɪ` etc.) → garbled, entfernen
+3. Echte Woerter (Woerterbuch, Deutsch, Delimiter) → behalten
+4. **Multi-Wort-Headword:** "belt" ist ein echtes Wort, aber wenn danach
+   garbled IPA kommt, wird nur "belt" behalten, der Rest entfernt
+
+### Regression Framework (Step 5g)
+
+Ground-Truth Sessions koennen als Referenz markiert werden. Nach jeder
+Code-Aenderung vergleicht `POST /regression/run` die aktuelle Pipeline-Ausgabe
+mit den gespeicherten Referenzen:
+
+- **Strukturelle Diffs:** Zonen, Spalten, Zeilen (Anzahl-Aenderungen)
+- **Zellen-Diffs:** Text-Aenderungen, fehlende/neue Zellen, col_type-Aenderungen
+- **Persistenz:** Ergebnisse in `regression_runs` Tabelle fuer Trend-Analyse
+- **Shell-Script:** `scripts/run-regression.sh` fuer CI-Integration
+
+Admin-UI: [/ai/ocr-regression](https://macmini:3002/ai/ocr-regression)
+
+### Ground Truth Review Workflow (Step 5h)
+
+Admin-UI fuer effiziente Massenpruefung von Sessions:
+
+- **Split-View:** Original-Bild links, erkannter Grid rechts
+- **Confidence-Highlighting:** Niedrige Konfidenz rot hervorgehoben
+- **Quick-Accept:** Korrekte Zeilen mit einem Klick bestaetigen
+- **Inline-Edit:** Text direkt im Grid korrigieren
+- **Session-Queue:** Automatisch naechste Session laden
+- **Batch-Mark:** Mehrere Sessions gleichzeitig als Ground Truth markieren
+
+Admin-UI: [/ai/ocr-ground-truth](https://macmini:3002/ai/ocr-ground-truth)
+
 ### `en_col_type` Erkennung
 
 Die Erkennung der Englisch-Headword-Spalte nutzt **Bracket-IPA-Pattern-Count**
@@ -1536,6 +1592,7 @@ cd klausur-service/backend && pytest tests/test_paddle_kombi.py -v  # 36 Tests
 
 | Datum | Version | Aenderung |
 |-------|---------|----------|
+| 2026-03-23 | 5.0.0 | **Phase 1 Sprint 1:** Compound-IPA-Zerlegung (`_decompose_compound`), Trailing-Garbled-Fragment-Entfernung (Multi-Wort-Headwords), Regression Framework mit DB-Persistenz + History + Shell-Script, Ground-Truth Review Workflow UI, Page-Crop Determinismus verifiziert. Admin-Seiten: `/ai/ocr-regression`, `/ai/ocr-ground-truth`. |
 | 2026-03-20 | 4.7.0 | Grid Editor: Zone Merging ueber Bilder (`image_overlays`), Heading Detection (Farbe + Hoehe), Ghost-Filter (borderless-aware), Oversized Word Box Removal, IPA Phonetic Correction (Britfone), IPA Continuation Detection, `en_col_type` via Bracket-Count. 27 Tests. |
 | 2026-03-16 | 4.6.0 | Strukturerkennung (Schritt 8): Region-basierte Grafikerkennung (`cv_graphic_detect.py`) mit Zwei-Pass-Verfahren (Farbregionen + schwarze Illustrationen), Wort-Ueberlappungs-Filter, Box/Zonen/Farb-Analyse. Schritt laeuft nach Worterkennung. |
 | 2026-03-12 | 4.5.0 | Kombi-Modus (PaddleOCR + Tesseract): Beide Engines laufen parallel, Koordinaten werden IoU-basiert gematcht und confidence-gewichtet gemittelt. Ungematchte Tesseract-Woerter (Bullets, Symbole) werden hinzugefuegt. 3er-Toggle in OCR Overlay. |