Explanation — warum es so gebaut ist

Diese Seite ist das Verständnis-Narrativ (Diátaxis „explanation"): die große Linie, warum der Harness diese Form hat. Das Detail je Entscheidung — Kontext, erwogene Alternativen, Auswirkungen — lebt als einzeln referenzierbare Records unter ../decisions/; jeder Absatz hier verlinkt seinen ADR.

Performance-Messung

Auf Apple-Silicon ist der Engpass der vereinheitlichte Speicher; an der RAM-Schwelle springt die Latenz. Darum Verteilung statt Mittelwert (P50/P95, CV%) statt eines verwischenden Schnitts (ADR-0003). Speicher/Throttling werden nie aus dem Request-Thread geschätzt, sondern von einem entkoppelten Host-Sampler gemessen und per Zeitfenster gemergt (ADR-0002). Die maschinen-vergleichbare Speicherzahl ist das Modell-Delta (Peak − Baseline), nicht der nackte System-Peak (ADR-0004). Warmup wird verworfen, der Cold-Start separat ausgewiesen (ADR-0005). Berichtet wird gegen die echten prompt_tokens aus usage, nicht gegen den Ziel-Bucket (Tokenizer variieren pro Modell; Spalten-Detail: ../reference/metrics-and-schema.md).

Schnittstelle

OpenAI-kompatibel ist die einzige Schnittstelle — kein engine-spezifischer Code außer client.py, der Maschinenwechsel (M1 ↔ M5) ist ein Config-Tausch (ADR-0001).

Qualitäts-Eval

Generierung (deterministisch, auf der Maschine) ist sauber von Bewertung (LLM/Mensch, danach) getrennt; ein Use-Case ist ein Pack = Daten, kein Code (ADR-0006). Die Master-Dimensionen werden holistisch bewertet; die Nachvollziehbarkeit trägt die belegte Begründung (zitierte prompt_ids), nicht eine erfundene Dimension→Prompt-Matrix (ADR-0007). Das Sicherheits-K.-o. hat zwei unabhängige Wurzeln (Dimensions-Boden + Red-Flag) mit konfigurierbarem red_flag_scope (ADR-0008).

Judge-Härtung (Thinking-Modelle)

Ein „Thinking"-Modell kann sein Budget ins Reasoning schreiben → leerer Content. Das zählt nicht als 1, sondern unscored; ein Pre-Flight warnt vorab, und die Eval lässt Modelle per Default frei antworten (ADR-0009). Ein Runaway-Guard bindet jeden Judge-Call (Timeout · keine Retries · Circuit-Breaker), damit ein durchdrehendes Modell den Lauf nicht hängt (ADR-0010). Thinking wird zudem aktiv unterdrückt (suppress_thinking via extra_body), sodass ein hybrides Modell ohne LM-Studio-Eingriff parsebaren Content liefert (ADR-0011). Der holistische Judge-Prompt ist gegen Begründungs-Defekte gehärtet (belegte Beobachtung · Score-Höhe begründen · Fix benennen · sicherheits-gescopte Reconciliation) (ADR-0012). Und der Judge selbst ist bewertbar: eine Meta-Eval misst Kalibrierung + Begründungs-Qualität (ADR-0013).

GUI & Betrieb

Die GUI ist ein out-of-process Control-Plane — sie spawnt die Messung als Subprozess und misst nie im eigenen Prozess; runs/ bleibt SSOT (ADR-0014). Die Nacht-Queue fährt viele Modelle sequenziell als isolierte Subprozesse (ein Modell/Run, reset+settle, Watchdog) (ADR-0015).