BACKLOG_EVAL.md

# Eval-System Backlog — AgentArena + MetaMetaMeta

**Stand:** 2026-03-19 (nach E2 Erfolg: additionalContext wirkt 0/3 vs 6/6)
**Status:** Backlog — nicht in Scope der aktuellen Session

---

## Kern-Erkenntnis

Mit `clean_home` Isolation in AgentArena koennen wir ALLE Meta-Features evaluieren:
- CLAUDE.md Varianten
- Sidecar-NG Injections
- Hook-Konfigurationen
- Skills
- Effort-Levels
- Modelle
- Temperatur

Das ist der eigentliche Durchbruch — nicht nur der voiceLanguage-Test.

---

## Parameter-Explosion (das Problem)

Jede Evaluation hat potenziell diese Dimensionen:

| Parameter | Werte | Beispiel |
|-----------|-------|----------|
| Model | 3+ | sonnet-4.6, opus-4.6, haiku-4.5 |
| Effort Level | 4 | low, medium, high, max |
| CLAUDE.md | N | minimal, full, custom |
| Sidecar Injection | on/off | mit/ohne Regeln |
| Hook Config | N | keine, Sidecar-NG, custom |
| Skills | N | pro Skill |
| Temperature | 3+ | 0.0, 0.5, 1.0 |
| Prompt-Variante | N | deutsch, englisch, vage, praezise |

**Naive Full Factorial:** 3 x 4 x 3 x 2 x 3 x N x 3 x N = tausende Kombinationen x pass@3 = zehntausende Runs

**Loesung (aus Research):**
1. **Screening:** Fractional Factorial Design — 8 Runs statt 32 um Haupteffekte zu finden
2. **Dann:** Bayesian Optimization (Optuna/W&B) fuer die wichtigsten Parameter
3. **Gold Set:** 10 handkuratierte Tasks als Schnelltest bei jeder Aenderung

---

## Evaluations-Dimensionen (die 4 Sauelen)

### 1. Reliability (pass@k)
- Wiederholbarkeit: 3x derselbe Test, wie oft klappt es?
- Unbiased Estimator: `pass@k = 1 - C(n-c, k) / C(n, k)`
- **Fuer statistische Signifikanz bei 5% Improvement: ~400 Runs**
- Fuer "dirty minimum" internes Testing: ~50 Runs
- Wilson Score Intervals statt naive Prozente

### 2. Token-Effizienz / Kosten
- Tokens pro geloestem Task
- Cost per successful run vs cost per failed run
- Prompt Efficiency Score: `(Success Rate) / (Tokens * Latency)`

### 3. Output-Qualitaet (Pass/Fail)
- Funktionaler Judge (exit code)
- Regression (bestehende Tests weiterhin gruen?)
- Lint + Complexity Delta

### 4. Alignment (das Neue)
- Wurde die Aufgabe SO umgesetzt wie gewuenscht?
- Beispiel Tetris: "rote Steine und gruene Bloecke" — stimmt die Farbe?
- Braucht LLM-as-Judge oder Screenshot-Vergleich
- Schwierigster Punkt — subjektiv, schwer automatisierbar

---

## Visualisierung (aus Research)

### Empfohlen:
1. **Radar Charts** — zeigt das "Profil" eines Agents (Reasoning, Cost, Speed, Tools, Reliability)
2. **Pareto Frontier** — X=Kosten (log), Y=Score → zeigt welche Agents "dominated" werden
3. **Heatmap/Matrix** — Parameter x Task → Farbe = pass rate

### AgentArena hat bereits:
- Leaderboard (pass@1, pass@3, avg_cost, composite_score)
- Matrix View (harness x model)
- Run Detail (trajectory, diff viewer)

### Fehlt:
- Radar Charts pro Agent
- Pareto Frontier (Cost vs Score)
- Experiment-Vergleich (vorher/nachher)
- Alignment-Visualisierung

---

## Konkrete naechste Testcases (TODO)

### T1: Effort-Level Impact (sofort machbar)
- Denselben voiceLanguage-Test mit `--effort low/medium/high` laufen lassen
- CLI-Flag: `claude --print --effort {level}`
- Hypothese: low effort = mehr Halluzinationen, high = besser aber teurer
- **Implementation:** Nur `cmd.extend(["--effort", level])` im Adapter + 3 neue Agents

### T2: Weitere Bug-Typen
- Nicht nur Config-Keys, auch:
  - File-ohne-Read-editieren
  - Falsche Datei editieren
  - Erfundene API-Endpoints
  - Import-Fehler (nicht-existierende Module)

### T3: Prompt-Sprache
- Derselbe Task auf Deutsch vs Englisch
- Hypothese: Englische Prompts = bessere Compliance?

### T4: CLAUDE.md Laenge
- Minimal (2 Zeilen) vs Full (Samuels echte 200-Zeilen CLAUDE.md)
- Hypothese: Mehr Regeln = besser? Oder Information Overload?

### T5: Skill-Evaluation
- Skills einzeln testen: Tut der Skill was er soll?
- Z.B. /checkpoint: Erstellt er wirklich einen Git-Snapshot?

---

## Tooling-Empfehlungen (aus Research)

| Tool | Zweck | Prioritaet |
|------|-------|-----------|
| **Inspect AI** | Modulares Eval-Framework (UK AI Security Institute) | Evaluieren |
| **Optuna** | Bayesian Hyperparameter-Optimierung | Spaeter |
| **W&B / MLflow** | Experiment-Tracking + Trajectory-Visualisierung | Spaeter |
| **Wilson Score** | Statistische Konfidenzintervalle | Einbauen |

---

## Claude Code CLI Flags (verifiziert)

```
--effort <level>          low, medium, high, max
--max-budget-usd <amount> Kostenlimit (nur mit --print)
--model <model>           Modell-Auswahl
--verbose                 Noetig fuer stream-json mit --print
--dangerously-skip-permissions  Keine Permission-Prompts
--output-format stream-json     NDJSON Output
```

---

## KRITISCH: Sandbox-Isolation (Sicherheit)

**Problem:** Claude Code Adapter laeuft auf dem Host mit `--dangerously-skip-permissions`.
Jeder Run hat volle User-Rechte (Dateisystem, Netzwerk, Bash). Kein Sandboxing.
`clean_home` isoliert nur ~/.claude/ Config, NICHT den Prozess.

**Risiko:** Claude kann theoretisch beliebige Commands ausfuehren, Dateien lesen/loeschen.
Fuer eigene harmlose Tests akzeptabel, fuer Produktion/fremde Prompts NICHT.

**Loesung (Optionen):**
1. **Custom Docker Image** mit claude CLI vorinstalliert (npm install -g @anthropic-ai/claude-code)
   - Vorteil: Echte Isolation, passt in bestehende Sandbox-Architektur
   - Aufwand: Docker Image bauen + testen, API Key reinreichen
2. **bubblewrap/firejail** Sandboxing um den CLI-Prozess
   - Vorteil: Leichtgewichtig, kein Docker noetig
   - Aufwand: Capability-Config, Filesystem-Allowlist
3. **Dedizierter User** mit eingeschraenkten Rechten
   - Vorteil: Einfach, `su arena-runner`
   - Aufwand: User anlegen, Permissions konfigurieren

**Prioritaet:** HOCH — vor jedem produktiven Einsatz oder fremden Prompts loesen.

---

## Nicht jetzt (Scope-Guard)

- [ ] Sandbox-Isolation fuer Claude Code Runs (siehe oben)
- [ ] Eval-Dashboard bauen
- [ ] Statistische Tests implementieren
- [ ] Prompt-Alignment LLM-as-Judge
- [ ] W&B Integration
- [ ] Fractional Factorial Design automatisieren
- [ ] Screenshot-basierte Alignment-Checks

**Samuel's Regel:** E2 ist fertig. Alles hier ist Backlog fuer spaeter.