fix(dashboard): Overlap-Guard auf Routing-Corpus mit n_total-Gewichtung (#314)

[TillQuandel]

Closes #314.

Problem

Der n≥20-Guard für den accept-Delta nutzt seit #312 accept_n (geroutete Notes) als Nenner. Der zweite Reliability-Baustein — der PDF-Overlap-Guard in version_delta() — bezog pdf_notes aber weiterhin aus den EVALUIERTEN Zeilen (quality_by_version[v]["pdf_notes"]), nicht aus dem vollen Routing-Corpus (runs_by_version[ver]["pdfs"]).

Konstruierbare Irreführung: Eine Version mit accept_n>=20 aus disjunkten Routing-PDFs, deren wenige Eval-Notes zufällig geteilte PDFs treffen, wurde pdf_overlap hoch und das Delta „reliable" ausgewiesen — obwohl der Routing-Corpus tatsächlich ausgetauscht war.

Neue Berechnungsgrundlage

runs_by_version erhält beim Befüllen (Log-Run-Schleife) ein neues Feld pdf_n_total: {pdf_group_key: Summe n_total} je Version, mit dem kanonischen D._pdf_group_key-Schlüssel (SSoT mit dem PDF-Filter). kpi_trend["pdf_notes"] wird jetzt aus runs_by_version[v]["pdf_n_total"] gespeist statt aus quality_by_version[v]["pdf_notes"].

Gewichtungsformel: Der Overlap-Anteil einer Version ist die Summe der n_total (geroutete Notes) aller PDFs, die auch in der Vergleichsversion vorkommen, geteilt durch die Gesamtsumme n_total der neuesten Version — also notengewichteter Anteil des gerouteten Corpus auf gemeinsamen Quellen, nicht bloße Mengen-Schnittmenge der PDF-Keys.

version_delta() selbst (Schwellwerte, reliable/reason-Anzeige) bleibt unverändert — nur die Grundgesamtheit der Overlap-Berechnung wechselt. quality_by_version[v]["pdf_notes"] (Eval-Notes je PDF) bleibt als eigenständige, weiterhin korrekte Diagnose im Export bestehen. Fehlen für eine Version komplett die Routing-Logs, fällt der Guard mangels Daten auf reines n≥20-Verhalten zurück (pdf_overlap=None, dasselbe Fail-open-Verhalten wie beim fehlenden pdf_notes-Key).

RED-Nachweis (TDD)

Neuer Test test_build_data_uses_routing_corpus_not_eval_sample_for_overlap konstruiert genau das Issue-Szenario: Routing-Corpus zwischen v1/v2 komplett disjunkt (je 25 geroutete Notes auf unterschiedlichen PDFs, accept_n>=20 in beiden), Eval-Stichprobe (10 Notes je Version) trifft zufällig dieselbe PDF-Quelle.

• Vor dem Fix: pdf_overlap == 1.0 (eval-basiert, 100% "Überlappung") → RED, Assertion == 0.0 schlug fehl.
• Nach dem Fix: pdf_overlap == 0.0 (routing-basiert, disjunkter Corpus) → reliable=False, reason="pdf_mix".

Zweiter neuer Test test_build_data_no_routing_logs_falls_back_to_n_guard_only dokumentiert das Fail-open-Verhalten, wenn für eine Version gar keine Routing-Logs vorliegen. Bestehender Integrationstest test_build_data_flags_pdf_mix_delta_via_kpi_trend um passende Routing-Log-Runs ergänzt (gleiche Zahlen wie vorher, jetzt über den korrekten Pfad verifiziert statt zufällig über die Eval-Zeilen).

Suite-Zahlen

• uv run pytest generative/tests/test_dashboard_delta_pdf_overlap.py -q → 10 passed
• uv run pytest generative/tests/ -k dashboard -q → 393 passed, 1337 deselected
• uv run pytest generative lib/decision_engine/tests shared/tests -q → 6183 passed, 3 skipped, 8 deselected
• uv run ruff check . → All checks passed
• uv run ruff format --check . → 301 files already formatted

Geänderte Dateien

• generative/eval_dashboard_server.py
• generative/tests/test_dashboard_delta_pdf_overlap.py

Sperrzonen

orchestrator.py, agents/extractor.py, eval_quality_v4.py, tools/pdf_enrich.py, config.py nicht angefasst.