fix(eval-dashboard): Re-Eval-Dedup je Note in KPI-Aggregation + Corpus-Overlap-Guard fuer Versions-Delta

[TillQuandel]

Befund (Statistik-Review 2026-07-15, 3 unabhängige Opus-Statistiker, konvergent + adversarial bestätigt)

Fix 1 — Re-Eval-Doppelzählung (Pseudoreplikation). note_evals enthält mehrere Eval-Zeilen derselben Note innerhalb einer pipeline_version (Re-Evals + identische Duplikat-Inserts). Beleg auf der Produktionskopie: v0.3.140 = 52 Zeilen von nur 40 distinct Notes (12 Duplikate); v0.3.143 = 30 Zeilen / 22 distinct Notes (8 Duplikate). Die gepoolte Fehlerquote/Coverage zählte Anker mehrfach-evaluierter Notes mehrfach — Bias nach unten, weil oft re-evaluierte Notes tendenziell gute Raten haben. Zusätzlich: die Kachel zeigte n=40 (distinct Notes), die Pooling-Basis war aber 52 Zeilen — inkonsistent.

Fix 2 — reliable-Flag beim Versions-Delta prüft nur n, nicht Corpus-Vergleichbarkeit. version_delta() (generative/eval_dashboard.py) markierte ein Delta ab n≥20 in beiden Versionen als belastbar — unabhängig davon, ob beide Versionen überhaupt denselben PDF-Corpus evaluieren. Auf der Produktionskopie wird so ein +2,7pp-Hall-Delta 140→143 als "reliable" gefärbt, obwohl die Versionen nur 3 von 9/5 PDFs teilen — reines PDF-Mix-Artefakt.

Fix

Fix 1: Neue Funktion _dedup_latest_per_note() (generative/eval_dashboard.py) hält pro (pipeline_version, note) nur die neueste Eval-Zeile (max timestamp, Tie-Break eval_id). Note-Identität normalisiert über _note_key() — Namespace-Prefix (vault__/inbox__/merge__) gestrippt, da eine Note zwischen zwei Re-Evals den Namespace wechseln kann (Routing-Änderung). Angewendet an allen Stellen, die note_evals je Version poolen:

• _calc_kpis (generative/eval_dashboard.py:568ff) — KPI-Kachel
• _calc_pdf_table (generative/eval_dashboard.py:866ff) — per-PDF-Tabelle, dieselbe Basis wie die Kachel
• quality_by_version-Aufbau im Server (generative/eval_dashboard_server.py:710ff) — Sparkline/kpi_trend

generative/calibration/collect.py (Kalibrierung) zusätzlich mit ORDER BY timestamp deterministisch auf "neueste Zeile gewinnt" gebracht (vorher implizite, unspezifizierte Zeilenreihenfolge).

Fix 2: reliable zusätzlich an den notengewichteten Corpus-Overlap gekoppelt (_DELTA_MIN_PDF_OVERLAP = 0.5, als Konstante konfigurierbar) — Anteil der Notes der neuesten Version, deren PDF-Quelle auch in der Vergleichsversion vorkommt. Server liefert dafür kpi_trend["pdf_notes"] ({pdf_group_key: n_notes} je Version, generative/eval_dashboard_server.py). Neues reason-Feld ("n_lt_20" vs. "pdf_mix") im Rückgabewert von version_delta() lässt den Client zwischen den beiden Nicht-belastbar-Gründen unterscheiden. Ohne pdf_notes (ältere Aufrufer/Tests) bleibt reines n≥20-Verhalten rückwärtskompatibel. Tooltip-Texte in internal/dashboard/eval_dashboard.html an allen 3 Stellen ergänzt (KPI-Kachel-Chip, Spark-Row-Delta, Insights-Text) — vorher suggerierte der Text durchgängig "belastbar ab n≥20".

Zahlen-Beleg (C:/tmp/kpi-db.db, read-only, eigenes Verify-Skript gegen die echten Fix-Funktionen)

FIX 1
v0.3.140: 52 Zeilen -> 40 distinct Notes (12 Duplikate)
  ALT (Pooling-Basis=52): 7.5 %   NEU (Pooling-Basis=40): 9.5 %
v0.3.143: 30 Zeilen -> 22 distinct Notes (8 Duplikate)
  ALT (Pooling-Basis=30): 10.2 %  NEU (Pooling-Basis=22): 12.0 %

FIX 2 -- Delta 140->143
ALT: hall 140=7.5% hall 143=10.2% delta=+2.7pp  reliable=True   reason=None
NEU: hall 140=9.5% hall 143=12.0% delta=+2.5pp  reliable=False  reason=pdf_mix  pdf_overlap=0.364

n blieb in beiden Versionen bei [40, 22] (distinct Notes war schon vor Fix 1 die n-Basis) — der alte n≥20-Guard allein hätte reliable=True belassen; erst der Corpus-Overlap-Guard fängt das PDF-Mix-Artefakt.

Tests (TDD, RED vor Implementierung verifiziert)

• generative/tests/test_dashboard_reeval_dedup.py (14 Tests): _note_key-Normalisierung (Prefix-Drift), _dedup_latest_per_note (Tie-Break, Fallback ohne Identifier, leere Liste), Integration in _calc_kpis/_calc_pdf_table (hall + coverage nutzen dieselbe deduplizierte Basis wie n).
• generative/tests/test_dashboard_delta_pdf_overlap.py (8 Tests, inkl. Produktionsmuster-Fixture 140/143 und ein build_data()-Server-Integrationstest): Overlap-Schwelle, Prioritäts-Reihenfolge der reason-Codes, Rückwärtskompatibilität ohne pdf_notes.

Bestehende Tests unverändert grün — synthetische Fixtures ohne note_path/pdf_notes durchlaufen Dedup/Overlap-Guard über die dokumentierten Fallback-Pfade unverändert; keine Altwerte mussten angepasst werden.

Suite

Volle Suite (via uv run pytest, Worktree-lokales .venv nach uv sync --extra dev — die editable atomic-notes-Installation zeigte sonst auf das Hauptrepo statt den Worktree): 5913 passed, 3 skipped, 0 failed. ruff check . + ruff format --check: clean.

Quelle: Statistik-Review 2026-07-15

Adversariale Kontrolle + Nachbesserung (2026-07-15)

Kontroll-Verdikt: merge-tauglich, 1 MEDIUM-Finding, 2 LOW-Punkte.

MEDIUM (gefixt, Commit ca1e2c9): _chart_scatter_versioned (eval_dashboard_server.py) deduplizierte nicht — der Scatter zeigte 52 Punkte (v0.3.140), während die KPI-Kachel nach Fix 1 korrekt "40 evaluierte Notes" sagte; re-evaluierte Notes erschienen doppelt ("Asynchronous E-Learning" bei x=0,0 UND x=29,4). Fix: quality_rows vor dem Punkte-Aufbau je pipeline_version gruppieren und mit _dedup_latest_per_note deduplizieren (gleiche Basis wie KPI/Trend; Dedup bewusst je Version, nicht global — dieselbe Note in zwei Versionen bleibt zwei Punkte). RED verifiziert (4 statt 2 Punkte vor dem Fix), 2 neue Tests. Beleg auf der DB-Kopie: Scatter-Punkte v0.3.140 52→40, v0.3.143 30→22; der Doppel-Punkt ist jetzt einfach (nur x=29,4, die neueste Eval-Zeile). Suite nach Nachbesserung: 5915 passed, 3 skipped; ruff clean.

LOW (Doku-Notiz, keine Code-Änderung):

• Die 50%-Schwelle _DELTA_MIN_PDF_OVERLAP ist post-hoc gewählt (der Produktionsfall 140→143 liegt mit 36,4 % darunter), aber robust: jede Schwelle im Bereich 0.4–0.6 klassifiziert den Beleg-Fall identisch. Als Konstante konfigurierbar, falls sich die Wahl in der Praxis als zu streng/lax zeigt.
• Rows mit pdf=NULL fallen aus pdf_notes heraus (leerer Gruppen-Key wird übersprungen) und zählen damit nicht in den Overlap-Nenner. Auf den Realdaten gibt es keine solchen Zeilen (kein Trigger); sollte das auftreten, wäre der Overlap gegenüber der ehrlichen Basis überschätzt — bewusst nicht spekulativ behandelt.