fix(chunker): Outline-first Kapitel-Split (#345)

[TillQuandel]

Closes #345 (PR 1 des Implementierungsplans #345/#346, Revision 4).

Architektur-Kurzfassung

split_by_chapters(text, pdf_path) bekommt einen Outline-first-Pfad: Kapitelgrenze = fitz-aufgelöste PDF-Lesezeichen-Zielseite statt fragilem Titel-Matching im Volltext.

1. Outline lesen (get_toc(simple=False), Zielseite aus dem fitz-aufgelösten Tupel-Element; NUL-Padding-Bereinigung).
2. Hauptebene wählen — Front-/Backmatter-Filter (_FRONTMATTER_RE als SSoT + verzeichnis-Substring + Plan-Termliste), Root-Descend (genau 1 Wurzel → eine Ebene tiefer, Moser-Muster), Duplikat-Merge (Seitenabstand ≤1, längerer Titel gewinnt), Sanity ≥2/≤60.
3. Physisch→Marker-Seiten-Map, zwei Zweige: PageLabels nutzbar → Label je physischer Seite (Issue-Zitier-Seite bei PDFs ohne /PageLabels = physischer Index statt gedruckter Seite (Offset-Sonderdrucke) #95-Klasse); sonst Zählung nicht-leerer Seiten (Drift real 3–39 Seiten). physical_pages_by_anchor bleibt VERBOTEN ([MITTEL] Seitenanker systematisch um ~4-6 PDF-Seiten verschoben — auch bei perfekten Eval-Werten #342-Erbe).
4. Validierung statt Matching — Titel-Wort-Overlap ≥50 % im ~400-Zeichen-Fenster ab Marker; Fehlschlag → HiPS-Kaskade (Substring → Fuzzy 80 %); bleibt es dabei → Grenze verwerfen + ins Vorsegment mergen; >50 % Fehlschläge → Outline verwerfen.
5. Degenerations-Guards (Median-Segment <400 Wörter, Riesensegment >70 %) → Normalpfad. Offset-Voting-Kreuzcheck (Plateau-Tie-Break Richtung Map) als Confidence-Flag. Diagnose-Zeile N Kapitel erkannt (Quelle: outline, Validierung M/N, K Grenzen verworfen).
6. Ohne nutzbare Outline transparenter Fallback auf exakt das bisherige Verhalten. Ohne pdf_path (Alt-Aufrufer/eval) unverändert.

Dazu: _TOC_TRAIL_RE nur erweitert (gespacte Dot-Leader, römische Seitenzahlen — _CHAPTER_RE/_is_real_chapter_match unangetastet); Chunk.source; extract_overview(text, chapters=chunks)-Injektion (ein Split pro Lauf); orchestrator-Aufrufstellen + harter by-chapter-Abbruch bei degeneriertem Split (der 15,5-h-/32-Mio-Token-/0-Notes-Lauf) statt Warnung.

Geänderte Dateien

• generative/pipeline/pdf_chunker.py — Outline-Logik, _TOC_TRAIL_RE, Chunk.source, extract_overview(chapters=).
• generative/config.py — MAX_SANE_OUTLINE_CHAPTERS, MIN_CHAPTER_SEGMENT_WORDS.
• generative/orchestrator.py — split_by_chapters(pdf_path=…), extract_overview(chapters=…), by-chapter-Abbruch-Guard.
• generative/tests/test_outline_chapter_split.py, test_by_chapter_degeneration_abort.py (neu).

RED-Nachweis (vor dem Fix)

• [MITTEL] split_by_chapters erkennt keine echten Kapitel — TOC-Eintraege werden Mikro-Kapitel (by-chapter unbrauchbar) #345-Repro: Klingenberg über den Heuristik-Pfad (= altes Verhalten) = 117 Mikro-Chunks (jeder TOC-Eintrag ein „Kapitel"); Outline-Pfad = 9. Test test_klingenberg_chapter_count_and_source prüft heuristik > 3× outline.
• TOC-Trail: die alte _TOC_TRAIL_RE (\.{2,}|\s{3,}) matcht die realen Klingenberg-Zeilen mit gespacten Dot-Leadern (1 Einleitung . . . . 1) NICHT → sie wurden fälschlich zu Kapiteln. Erweiterung fängt sie (5 parametrisierte Negativtests aus echten Zeilen).

Akzeptanzkriterien v4 PR 1

• (a) 5-Bücher-Fixture — test_real_book_outline_split (Klingenberg/DAMA/Kuhlen/Gantert/Hobohm): Quelle outline, Kapitelzahl im Band, 100 % der Grenzen passieren das Validierungs-Gate. Kuhlen (39-Seiten-Drift, kein PageLabels) = eigener Test, 6 Teile A–F. Echte PDFs sind Tills Privatbestand → pytest.skip ohne ATOMIC_AGENT_TEST_BOOK_DIR (in CI übersprungen); lokal 8/8 grün verifiziert.
• (b) Klingenberg 8–10 Kapitel (real 9), Quelle outline.
• (c) Fallback — test_no_outline_falls_back_to_normal_path (synthetisch, läuft überall) + test_no_pdf_path_is_backward_compatible.
• (d) TOC-Trail-Negativtests aus echten Klingenberg-Zeilen (5 parametrisiert + römisch + Nicht-Über-Filterung).
• (e) Overview-Budget — test_overview_budget_from_chapters ≤1700 Wörter (real Klingenberg 1554 vs. 88.725 Volltext; N2-Baseline war ~21k).
• (f) Bestehende Suite grün (inkl. unverändertes test_chapter_regex.py).
• (g) synthetisches PageLabels-Fixture — test_labels_branch_maps_to_printed_label (Druckseite = phys+100 → Grenze mappt auf [S. 103], nicht den phys. Index).
• (h) Moser-Single-Root-Fixture — test_root_descend_single_root (1 Wurzel, 3 L2-Kinder).

Suite-Zahlen

uv run pytest generative lib/decision_engine/tests shared/tests -q → 6268 passed, 11 skipped (davon 8 echte Buch-Tests ohne gesetztes ATOMIC_AGENT_TEST_BOOK_DIR), 9 deselected, 0 failed (418 s). Mit gesetztem Buch-Verzeichnis zusätzlich 8/8 echte Buch-Tests grün (197 s). ruff check + ruff format --check sauber.

Abweichungen vom Plan (mit Begründung)

• Skip-Termliste exakt an Plan §1 ausgerichtet (nicht an die breitere Probe-Regex): bare literatur/abbildung als Substring droppten fälschlich Ganterts echtes Kapitel „Zweiter Teil. … Literatur, Bücher, Medien". Regressionstest test_gantert_keeps_literatur_content_chapter. Folge: einzelne Backmatter-Sektionen (z. B. „Weiterführende Literatur") können als validierte Chunks durchrutschen — harmlos (echte Dokumentsektionen), kein Verlust von Inhaltskapiteln.
• Offset-Voting als Confidence-Flag implementiert (verändert den Split nicht): Plateau-Tie-Break „Map-Marker ∈ Treffermenge" statt naiver Erst-Fundstelle — sonst feuerte „map-confidence niedrig" durch Running-Heads auf jedem Buch (Kolumnentitel-Plateau). Der per-Kapitel-Validierungs-Merge bleibt der bestimmende Akzeptanzmechanismus.
• Real-Buch-Tests referenzieren die PDFs über ATOMIC_AGENT_TEST_BOOK_DIR (Default config.LITERATURE_DIR) und skippen bei Abwesenheit — keine hartcodierten Pfade, CI-tauglich; die synthetischen Fixtures (c/d/e/g/h) sind die dauerhafte Abdeckung.
• Validierungs-Test nutzt _validate_boundary (die echte Gate-Funktion inkl. Fuzzy) statt nacktem Wort-Overlap: Klingenberg-Body hat Encoding-Mojibake („Datenqualit�t"), Hobohm-Teil-Divider zeigt auf die erste Inhaltsseite („Informationsforschung") — beide korrekte Grenzen, die reiner Overlap fälschlich abgelehnt hätte.