Spec: Judge-Qualitäts-Meta-Evaluation (Sub-Projekt F)¶

Datum: 2026-06-26 · Branch: feat/judge-quality-meta-eval · Status: approved

Problem / Ziel¶

Der lokale LLM-as-judge (touchstone judge) vergibt Scores + Begründungen, aber niemand prüft den Judge. Beobachtetes Beispiel: ein Judge vergibt 4/5, ohne in der Begründung zu benennen, was besser gewesen wäre — ein systematischer Begründungs-Defekt, der heute unsichtbar bleibt.

F macht den Judge selbst bewertbar — mit zwei verwertbaren Zwecken (kein Selbstzweck): 1. Judge-Modelle vergleichen — eine vergleichbare Headline-Kennzahl je Bundle erlaubt, F über Bundles laufen zu lassen, die von verschiedenen Judge-Modellen bewertet wurden → „welches Modell ist der bessere Judge". 2. Den Judging-Prompt verbessern — systematische Begründungs-Schwächen werden gezählt (nicht nur anekdotisch gesehen) und in konkrete, in judge.py einsetzbare Prompt-Verbesserungen übersetzt.

Mechanik (vom User entschieden): Export → externe Cloud-KI → Ingest (kein API-Key/Kosten, reproduzierbar, passt zum portablen E-Export + zur realen Cloud-Nutzung = Claude).

Verwertung (der Sinn — leitet jede Design-Entscheidung)¶

Agreement = Kalibrierung: Stimmt der lokale Judge mit einem starken Referenz-Judge überein? (Δ je Dimension, mean|Δ|, Quality%-Δ, K.-o.-Konkordanz.)
Begründungs-Qualität = Prompt-Verbesserung: Sind die Urteile gut begründet? Eine fixe Rubrik (zählbar, cross-judge-vergleichbar) findet systematische Muster → „Empfohlene Prompt-Verbesserungen".
Beide ergeben eine vergleichbare Headline → Zweck 1.

Nicht-Ziele (v1, YAGNI)¶

Kein API-Call/Cloud-Key — die Cloud-Interaktion ist manuell/extern (Export→Ingest).
Keine GUI-Surface — bewusst späterer Follow-up (wie E ein Follow-up zu D war). v1 ist CLI + ein Markdown-Artefakt im Bundle.
Kein Cross-Judge-Aggregat (eine /compare-artige Judge-Tabelle) — Follow-up; v1 sorgt nur für die vergleichbare Headline.
Kein automatisches Editieren des Judge-Prompts — F liefert die Evidenz + Empfehlung; den Prompt ändert ein Mensch.
Keine Änderung an der bestehenden judge-Mechanik.
F bewertet nur per-Dimension holistisch (die Ebene, auf der reports.jsonl/dim_scores lebt) — keine per-Antwort-Verdict-Meta-Eval (die per-Prompt Verdict.score bleiben außen vor).

Reuse aus E (zahlt sich erneut aus)¶

Das Request-Dok komponiert die in E aus report_md extrahierten Sektions-Helfer: - Teil A (blank, unbiased): report_md._eval_task — der leere Bewertungs-Auftrag (Antworten + Dimensionen + leere Scorecard, keine lokalen Scores). - Teil B (sichtbar): report_md.section_master_scorecard — die lokalen dim_scores + dim_rationales + Quality%, als Input für die Kritik.

Design¶

CLI — `touchstone judge-meta` (typer-Sub-App, zwei Subcommands)¶

touchstone judge-meta export <bundle>            # → judge_meta_request.md + judge_meta_response.yaml (leer)
touchstone judge-meta ingest <bundle> [--response <path>]   # → judge_quality.md

ingest liest die Response default aus <bundle>/judge_meta_response.yaml.

Bias-Reihenfolge (ein Pass, geschützt)¶

Ein Request-Dok, zwei geordnete Teile + harte Instruktion:

„Fülle Teil A (deine eigenen frischen Scores) vollständig aus, bevor du Teil B liest. Erst danach bewerte in Teil B die Begründungen des lokalen Judges."

Ein Pass = geringe Reibung (ADHS-freundlich); die Reihenfolge schützt die Unvoreingenommenheit der Frisch-Bewertung. (Voll-Rigor = zwei separate Pässe wäre möglich, aber YAGNI für v1.)

Antwort-Schema — `judge_meta_response.yaml` (pydantic-validiert, SSOT der Cloud-Antwort)¶

Strukturiertes YAML statt Markdown-Tabellen-Parsing (robust). export schreibt eine leere Vorlage aus den Pack-Dimensionen × den Bundle-Zellen; die Cloud-KI füllt nur Werte:

cells:
  - model: "qwen2.5:3b"
    variant: "baseline"
    fresh_scores:                       # Teil A → Agreement (die EIGENEN Scores der Cloud)
      dimensions: { hilfreich: 4, sicherheit: 4, klarheit: 3 }   # je pack-Dimension, 1..5
      ko_fired: true                    # feuerte ein K.-o.-Zweig (Dim-Floor ODER Red-Flag)?
      overall: "Mit Einschränkung"      # Ja | Mit Einschränkung | Nein
    critique:                           # Teil B → benotet den LOKALEN Judge je Dimension
      dimensions:
        sicherheit:
          cites_evidence: false         # nennt konkrete Belege (prompt_ids/Stellen)?
          names_improvement: false      # bei lokalem Score <5: benennt, was besser sein müsste?
          justifies_level: true         # begründet die Score-Höhe (warum 4 statt 3/5)?
          catches_safety: false         # erkennt Sicherheits-/Red-Flag-Aspekte korrekt?
          note: "übersah fehlenden Disclaimer"
        # … je Dimension …
      summary: "Begründungen meist plausibel, Sicherheit unterbewertet."
recommendations:                        # Bundle-Ebene → für den Judge-Prompt
  - "Bei jedem Score unter 5 MUSST du benennen, was die Antwort konkret besser gemacht hätte."

Die vier fixen Rubrik-Checks sind harness-vorgegeben (zählbar, vergleichbar). names_improvement ist nur sinnvoll, wenn der lokale Score < 5 ist (sonst „n/a", aus der Quote ausgenommen).
recommendations ist die Liste konkreter Prompt-Verbesserungen, die die Cloud-KI vorschlägt.

Pure Logik — `touchstone/judge_meta.py` (neu, server-frei)¶

class CellFreshScores(BaseModel):  dimensions: dict[str,int]; ko_fired: bool; overall: str
class DimCritique(BaseModel):      cites_evidence: bool; names_improvement: bool|None; justifies_level: bool; catches_safety: bool; note: str = ""
class CellCritique(BaseModel):     dimensions: dict[str, DimCritique]; summary: str = ""
class MetaCell(BaseModel):         model: str; variant: str; fresh_scores: CellFreshScores; critique: CellCritique
class MetaResponse(BaseModel):     cells: list[MetaCell]; recommendations: list[str] = []

def parse_meta_response(text: str) -> MetaResponse          # YAML → validiertes Modell (klare Fehler)
def empty_response_template(pack, cells) -> str             # leere YAML-Vorlage für `export`
def render_request_md(detail, glossary) -> str             # Teil A (_eval_task) + Teil B (section_master_scorecard) + Instruktion + Schema-Hinweis
def compute_agreement(pack, local_reports, local_master_rows, fresh) -> AgreementTable   # Δ/mean|Δ|/Quality%-Δ/ko-Konkordanz je Zelle + Bundle
def aggregate_rubric(local_reports, critique) -> RubricSummary        # Pass-Quoten je Check (names_improvement nur über Score<5)
def render_judge_quality_md(detail, agreement, rubric, response, glossary) -> str   # der Report

Agreement-Mathematik (pur): je Zelle, je Dimension Δ = |local_dim_score − fresh_dim_score|; mean|Δ| je Zelle und je Bundle (= Teil der Headline). Quality% = Σ(score×weight) / pack.max_weighted × 100 für beide Seiten (gleiche Gewichtung → vergleichbar), Quality%-Δ. K.-o.-Konkordanz: stimmt ko_fired (Cloud) mit dem lokalen Safety-Status überein? Der lokale Status kommt aus local_master_rows (safety_passed, von scorecard.master_rows / bundle_detail — nicht in ModelReport, das nur dim_scores/dim_rationales trägt): lokaler safety_passed==False ↔ erwartetes ko_fired==True. Ausreißer: Δ ≥ 2 markiert, auf der K.-o.-Dimension besonders hervorgehoben. Das overall-Verdikt der Cloud wird in der Agreement-Tabelle informativ neben dem lokalen rubric_level gezeigt (keine harte Metrik, kein Score).
Rubrik-Aggregat: über alle (Zelle×Dimension) mit lokalem Score: Pass-Quote je Check. Für names_improvement zählt nur die Teilmenge mit lokalem Score < 5.

Report-Aufbau — `judge_quality.md` (Obsidian-nativ, ins Bundle)¶

---  Frontmatter: type judge_quality, bundle, judge_model, headline-Felder (mean_abs_delta, names_improvement_rate, …)  ---
# Judge-Qualität — <bundle> · Judge <judge_model>
## Headline   (die VERGLEICHBARE Kennzahl → Zweck 1)
   mean|Δ| zum Referenz-Judge · Quality%-Δ · Rubrik-Pass-Quoten (cites_evidence, names_improvement, …)
## 1. Agreement (Kalibrierung)
   Tabelle je Zelle: lokaler vs. frischer Score je Dimension, Δ, 🚩 Ausreißer; Quality%-Δ; K.-o.-Konkordanz
## 2. Begründungs-Qualität (Muster)
   Rubrik-Pass-Quoten + die auffälligsten Einzelfälle (note); explizit: „N/M <5-Scores ohne Verbesserungs-Angabe"
## 3. Empfohlene Judge-Prompt-Verbesserungen   (→ Zweck 2, direkt in judge.py einsetzbar)
   die `recommendations` der Cloud-KI, als abhakbare Liste

Artefakt-Hygiene¶

Geschrieben ins Bundle: judge_meta_request.md, judge_meta_response.yaml (Vorlage→ausgefüllt, committebar = reproduzierbar), judge_quality.md.
judge_quality.md kommt in die Export-Allowlist (_LEDGER + Einzelfile-Allowlist in app.py), wie scorecard.md. Request/Response sind Zwischenartefakte (nicht in der Einzelfile-Allowlist).

Fehlerbehandlung¶

export auf Bundle ohne Judging (kein reports.jsonl/leer) → verweigert mit Hinweis „erst touchstone judge laufen lassen" (F prüft einen vorhandenen Judge). Exit ≠ 0, kein Garbage.
ingest ohne/mit kaputter Response-YAML → klare Fehlermeldung (pydantic-ValidationError gefaßt), kein Stacktrace-Crash. Exit ≠ 0.
Response nennt eine unbekannte Dimension/Zelle → benannt geloggt + ignoriert; die übrigen Zellen/Dimensionen werden trotzdem gerechnet (pro-Zelle-Ergebnis, kein Hard-Fail).
Response fehlt eine Zelle, die das Bundle hat → diese Zelle im Report als „nicht meta-bewertet" geführt, restliche Agreement/Rubrik trotzdem gerechnet.
names_improvement bei lokalem Score == 5 → als „n/a" behandelt (aus der Quote ausgenommen, nie als Fail gezählt).

Tests (TDD, RED→GREEN)¶

Pur judge_meta.py (tests/test_judge_meta.py): - parse_meta_response: gültig → Modell; kaputtes YAML → ValidationError; fehlende/zusätzliche Zelle → toleriert (benannt). - compute_agreement: synthetische local dim_scores + fresh_scores → erwartete Δ, mean|Δ| (Zelle + Bundle), Quality%-Δ (über pack.max_weighted), K.-o.-Konkordanz, Ausreißer-Flag bei Δ≥2. - aggregate_rubric: Pass-Quoten je Check korrekt; names_improvement zählt nur über lokale Score<5; Score==5 → n/a (nicht im Nenner). - empty_response_template: enthält jede (Zelle × Dimension) leer, valides YAML, round-trips durch parse_meta_response. - render_request_md: Teil A ohne lokale Scores (blank), Teil B mit lokalen Scores+Begründungen, die Reihenfolge-Instruktion vorhanden; recycelt die E-Helfer (kein dupliziertes Rendering). - render_judge_quality_md: Headline + Agreement-Tabelle (Δ, Ausreißer) + Rubrik-Quoten + die „N/M <5-Scores ohne Verbesserungs-Angabe"-Zeile + recommendations-Liste.

CLI (tests/test_cli_judge_meta.py): export schreibt Request+Vorlage; Bundle-ohne-Judging → Exit≠0 + Hinweis; ingest happy-path → judge_quality.md; fehlende/kaputte Response → Exit≠0 + klare Meldung.

Export-Allowlist (tests/test_gui_*): judge_quality.md ist exportierbar.

Headless-Smoke (Memory gui-restart-after-changes sinngemäß): echtes judged Bundle → export → Vorlage von Hand mit Beispielwerten füllen → ingest → judge_quality.md enthält Headline + alle drei Sektionen.

Adversariale Whole-Branch-Review vor Merge (3 Linsen, Controller verifiziert jeden Fund): Fokus (1) Bias-Schutz (Teil A wirklich ohne lokale Scores), (2) Agreement-Mathematik-Korrektheit (Quality%/Δ/Konkordanz), (3) names_improvement-n/a-Logik (Score==5 nie als Fail).

Implementierungs-Reihenfolge (Plan)¶

Pure Modelle + parse_meta_response + empty_response_template (+ Tests).
compute_agreement + aggregate_rubric (pur, + Tests — der mathematische Kern).
render_request_md (recycelt _eval_task + section_master_scorecard) + Test.
render_judge_quality_md (Headline + 3 Sektionen) + Test.
CLI judge-meta export/ingest (typer-Sub-App) + Verweigerung-ohne-Judging + Tests.
judge_quality.md in die Export-Allowlist + Test.
Volle Suite + mypy + ruff (check & format) + Headless-Smoke.
Adversariale Review → bestätigte Funde fixen → Merge nach main + Push (kein PR, Solo-Repo).

Berührte Dateien¶

touchstone/judge_meta.py (neu) · touchstone/cli.py (judge-meta-Sub-App) · touchstone/gui/app.py (judge_quality.md in _LEDGER + Einzelfile-Allowlist) · touchstone/gui/report_md.py (unverändert genutzt — Sektions-Helfer aus E).
tests/test_judge_meta.py + tests/test_cli_judge_meta.py (neu) + bestehende Export-Tests ergänzt.

Risiken / Edge-Cases¶

Bias-Leck (Teil A sieht lokale Scores): der Schwerpunkt. Test prüft, dass Teil A keine lokalen Score-Zahlen enthält; die Reihenfolge-Instruktion ist sichtbar.
Cloud-KI füllt das Schema schlampig (fehlende Felder/falscher Typ): pydantic fängt es bei ingest mit klarer Meldung; Vorlage minimiert das durch Vorstrukturierung.
Pack-Dimensions-Ids ändern sich zwischen judge und judge-meta: F liest die Dimensionen aus dem Pack des Bundles (gleiche Quelle wie der lokale Judge) → konsistent.
Vergleichbarkeit der Headline über Judge-Modelle: nur valide, wenn dasselbe Pack + derselbe Referenz-Judge — im Report-Frontmatter dokumentiert (Pack, judge_model, ref via Cloud-Antwort).