EVIDENCE_CONTRACT.md

# Evidence Contract

Stand: 2026-05-04

## Zweck

Dieser Contract definiert, wann eine Aussage aus einem Projekt, Experiment oder Agentenlauf als belastbare Erkenntnis gelten darf.

Er ist harness-agnostisch: Hermes, Codex, Claude Code, Aider, OpenCode, AgentArena oder ein manuelles Experiment koennen denselben Contract verwenden.

Kernregel:

> Metriken beweisen Leistung innerhalb eines Rahmens. Sie beweisen nicht automatisch, dass der Rahmen selbst sinnvoll oder uebertragbar ist.

Ergaenzende Arbeitsregel:

> Kein agentischer Projektschritt ohne kleinen Realitaetskontakt.

## Erkenntnisstufen

| Stufe | Bedeutung | Erlaubte Aussage |
|---|---|---|
| `intuition` | Erfahrung, Bauchgefuehl, Plausibilitaet | "Das koennte funktionieren." |
| `observation` | Ein belegtes Einzelereignis | "In diesem Run ist X passiert." |
| `evidence` | Reproduzierbar in definiertem Setup | "Unter diesen Bedingungen trat X wiederholt auf." |
| `working_rule` | Stark genug fuer vorlaeufige Praxis | "Bis Gegenbeweis nutzen wir X als Regel." |
| `theory` | Erklaert, begrenzt uebertragbar, falsifizierbar | "X wirkt vermutlich wegen Y, gueltig fuer Z." |

## Pflichtfelder Fuer Claims

Jeder relevante Projekt-Claim bekommt diese Felder.

```yaml
claim: ""
claim_evidence_level: "blocked|insufficient|intuition|observation|evidence|working_rule|theory"
method_evidence_level: "none|intuition|observation|evidence|working_rule|theory"

scope:
  project: ""
  harness: ""
  model: ""
  task_set: ""
  time_window: ""
  commit_or_version: ""

experiment:
  baseline: ""
  intervention: ""
  controlled_variables: []
  changed_variables: []
  run_count: 0
  repetitions_per_task: 0

measurement:
  primary_metric: ""
  secondary_metrics: []
  judge_used: false
  judge_role: ""
  success_rule: ""
  falsifier: ""

artifacts:
  logs: []
  reports: []
  database: ""
  diffs: []
  screenshots: []

method_check:
  baseline_stable: "yes|no|unknown"
  tasks_discriminative: "yes|no|unknown"
  infra_errors_dominant: "yes|no|unknown"
  metric_matches_question: "yes|no|unknown"
  treatment_effect_blocked: "yes|no"
  transfer_limit: ""

conclusion:
  allowed_claim: ""
  forbidden_claim: ""
  method_learning: ""
  next_clean_test: ""
```

## Boden-Kette Fuer Projektschritte

Jeder neue Projekt- oder Build-Schritt braucht einen beobachtbaren Boden.

Vor dem Schritt:

```yaml
purpose_sentence: "Dieses Projekt ist erfolgreich, wenn [Nutzer] [Aufgabe] besser/schneller/sicherer erledigt."
step:
  name: ""
  input: ""
  action: ""
  expected_output: ""
  validation: ""
  fail_condition: ""
```

Nach dem Schritt:

```yaml
step_result:
  status: "PASS|FAIL|UNCLEAR"
  evidence_artifact: ""
  next_step: ""
```

Regeln:

- `PASS` erlaubt den naechsten Boden.
- `FAIL` verlangt Ursachenanalyse oder Fix.
- `UNCLEAR` verlangt bessere Messung, nicht Weiterbau.
- Ohne beobachtbares Artefakt ist der Schritt Theorie und wird nicht gebaut.
- Kein Projekt laeuft laenger als 1 Stunde ohne PASS/FAIL/UNCLEAR-Artefakt.

Meta-Ebenen sind nur erlaubt, wenn ein echter Artefakt-Fehler sie verlangt.

## Evidence Split Rule

Jeder Claim muss auf zwei Evidenzachsen bewertet werden:

1. **Claim-Evidenz:** Wie stark ist die Evidenz fuer den urspruenglichen inhaltlichen Claim?
2. **Methoden-Evidenz:** Was lernen wir ueber Messaufbau, Harness, Task-Auswahl, Baseline-Stabilitaet oder Evaluierbarkeit?

Diese beiden Achsen duerfen nicht vermischt werden.

Beispiel:

- Claim-Evidenz: `blocked` fuer "Karpathy-Regeln verbessern Aider/SWE-bench-Lite."
- Methoden-Evidenz: `evidence` fuer "Das aktuelle Harness/Task-Setup ist nicht stabil und diskriminativ genug, um diesen Treatment Effect zu messen."

Spezialfall Treatment Effect:

Wenn Baseline instabil ist, Tasks nicht diskriminativ sind, Fail-Fast ausgeloest wurde oder Infrastrukturfehler dominieren:

- Claim-Evidenz fuer den Treatment Effect = `blocked`, `insufficient` oder maximal `intuition`.
- Methoden-Evidenz = `evidence`, falls die blockierenden Gates durch Artefakte belegt sind.
- Erlaubte Schlussfolgerung = Der aktuelle Messaufbau ist nicht stabil genug, um den Treatment Effect zu messen.
- Nicht erlaubte Schlussfolgerung = Die getestete Regel funktioniert oder funktioniert nicht.

Scope-Ausnahme:

Diese Blockade gilt fuer uebertragbare oder task-klassenweite Treatment-Effect-Claims.
Sie gilt nicht automatisch fuer einen explizit task-lokalen Claim, wenn:

- der Claim auf genau einen konkreten Fall begrenzt ist,
- Baseline und Intervention innerhalb dieses Falls mehrfach verglichen wurden,
- die Metrik fuer diesen Fall hart und passend ist,
- die Transfergrenze explizit blockiert wird.

Dann ist erlaubt:

- Claim-Evidenz = `evidence` fuer den engen task-lokalen Effekt.
- Methoden-Evidenz = `evidence`, wenn der Messrahmen fuer diesen engen Fall sauber war.
- Nicht erlaubt bleibt jede Generalisierung auf andere Tasks, Task-Klassen, Modelle oder Harnesses.

Beispiel:

- "Sidecar wirkt im E2/voiceLanguage-Config-Fall" kann `evidence` sein.
- "Sidecar wirkt bei Config-Key-Tasks allgemein" bleibt blockiert, solange weniger als zwei weitere diskriminative Tasks existieren.

## Methodische Gates

Ein Claim darf nicht hoeher als `observation` eingestuft werden, wenn nur ein Einzelrun vorliegt.

Ein Claim darf nicht hoeher als `evidence` eingestuft werden, wenn keine Baseline existiert.

Ein Treatment-Effect-Claim ist blockiert, wenn:

- Fail-Fast ausgeloest wurde,
- weniger als zwei diskriminative Tasks vorhanden sind,
- Infrastrukturfehler das Ergebnis dominieren,
- die Task-Auswahl nicht zur behaupteten Faehigkeit passt,
- Judge-Scores die harte Metrik ueberstimmen.

Wenn ein Treatment-Effect-Claim blockiert ist, ist die Analyse nicht beendet.
Der Agent muss danach einen zweiten Claim pruefen:

> Hat der Fehlschlag selbst eine belastbare Methoden-Erkenntnis erzeugt?

Ein blockierter Treatment-Effect kann `method evidence` erzeugen, wenn:

- der Blocker durch Artefakte belegt ist,
- der Blocker den Messrahmen betrifft, nicht nur einen zufaelligen Run,
- klar ist, welche Messvoraussetzung verletzt wurde,
- daraus ein konkreter naechster Test fuer den Messaufbau folgt.

Erlaubte Methoden-Erkenntnisse:

- "Das Task-Set war nicht diskriminativ genug."
- "Die Baseline war nicht stabil genug fuer Treatment-Effect-Schaetzung."
- "Infrastrukturfehler dominierten die Messung."
- "Die harte Metrik traf die eigentliche Frage nicht."

Nicht erlaubt:

- "Es gibt keine Erkenntnis."
- "Die Intervention wirkt nicht."
- "Die Regel ist widerlegt."
- "Der Treatment-Effekt ist null."

Ein Claim darf erst `working_rule` werden, wenn:

- die Evidenz wiederholbar ist,
- der Geltungsbereich explizit begrenzt ist,
- mindestens ein plausibler Gegenfall benannt ist,
- klar ist, was noch nicht behauptet werden darf.

Ein Claim darf erst `theory` werden, wenn:

- ein Wirkmechanismus formuliert ist,
- die Theorie falsifizierbar ist,
- alternative Erklaerungen benannt wurden,
- Uebertragbarkeit begrenzt und nicht nur behauptet ist.

## Standardfragen

Vor jedem Experiment:

1. Was ist der genaue Claim?
2. Welche Baseline gilt?
3. Welche Variable wird isoliert veraendert?
4. Was waere ein Gegenbeweis?
5. Welche Aussage ist nach dem Ergebnis maximal erlaubt?

Nach jedem Experiment:

1. Hat die Messung wirklich die Frage getroffen?
2. War die Task-Auswahl diskriminativ?
3. Waren Fehler fachlich oder infrastrukturell?
4. Sind harte Metriken und Judge getrennt?
5. Welche Uebertragung ist erlaubt, welche nicht?
6. Wenn der Treatment-Effect blockiert ist: Welche Methoden-Erkenntnis bleibt?

## Beispiele

### MetaMetaMeta E2

Erlaubt:

> In der voiceLanguage-Config-Aufgabe verhinderte konkrete Sidecar-Injection in den beobachteten Runs das Schreiben nicht existierender Config-Keys.

Nicht erlaubt:

> Sidecar-Injection verbessert alle Agentenaufgaben.

### FirstRealHarnessEvaluation Karpathy

Erlaubt:

> Das Projekt zeigte, dass der aktuelle Harness/Task-Aufbau noch nicht stabil genug war, um Karpathy-Regel-Treatment-Effects belastbar zu messen.

Nicht erlaubt:

> Karpathy-Regeln funktionieren nicht.