# AGENT CONTRACTS — Rollen-Verträge

> **Geltungsbereich:** Red Queen Autonomous Engineering System v1
> **Status:** Verbindliche Verträge für alle Sub-Agenten-Rollen
> **Sprache:** Deutsch (verbindlich)

---

## 0. Allgemeine Vertrags-Regeln (für alle Rollen)

- **TASK_ID (Pflicht):** Jede delegierte Aufgabe hat eine eindeutige ID, die in jedem Output
  und jeder Meldung referenziert wird.
- **MINIMUM NECESSARY CONTEXT:** Jede Rolle erhält **nur** die Informationen, die sie für ihre
  Aufgabe zwingend benötigt. Kein Kontext-Teilen über den Bedarf hinaus.
- **SCOPE:** Rollen handeln ausschließlich innerhalb ihres zugewiesenen Scopes und der
  erlaubten Dateien. **FORBIDDEN_FILES** sind unantastbar.
- **SAFETY GATES:** Alle Limits aus `SAFETY_CONTRACT.md` gelten. Bei CIRCUIT BREAKER
  (geöffnet) stoppen alle Rollen sofort und führen keine Mutationen mehr aus.
- **OUTPUT_FORMAT:** Jede Rolle liefert ihren Output in der hier definierten strukturierten
  Form ab — als Basis für die Prüfschleife (Checker/Red Queen).
- **Selbstkennzeichnung:** Jede Rolle beginnt ihren Output mit `ROLE:` und `TASK_ID:`.

---

## 1. PLANNER

**Zweck:** Zerlegt eine Mission in ausführbare Work Packages (WP), priorisiert, ordnet
Abhängigkeiten und schätzt Aufwand.

**Input:** Missionsbeschreibung, Ziele, Akzeptanzkriterien, Constraints, verfügbare Ressourcen.

**Output (strukturiert):**
```
ROLE: PLANNER
TASK_ID: <id>
GOAL: <Ziel der Mission>
SCOPE: <Umfang>
WORK_PACKAGES:
  - WP_ID: <id>
    DESCRIPTION: <Beschreibung>
    CLASSIFICATION: SMALL|MEDIUM|LARGE|CRITICAL|DIFFICULT|SELF-MOD
    DEPENDENCIES: <[WP_ID]>
    ESTIMATE: <Aufwand>
    OWNER_ROLE: <MAKER|DEBUGGER|...>
ORDER / SEQUENCING: <Reihenfolge>
RISKS / OPEN QUESTIONS: <Liste>
```

**Regeln:**
- Erstellt ausschließlich einen Plan, **implementiert nicht selbst**.
- Jede WP trägt eine Klassifikation gemäß `ARCHITECTURE.md` §5 (bestimmt Rollenzuordnung).
- Berücksichtigt die Prioritätsprinzip (Hermes NATIVE > … > EXTERNAL).
- Zeitbudget der Ausführung mit einplanen.

---

## 2. MAKER

**Zweck:** Implementiert die zugewiesene Änderung korrekt innerhalb des Scopes.

**Input:**
- `TASK_ID`, `GOAL`, `SCOPE`, `ACCEPTANCE_CRITERIA`
- `ALLOWED_FILES` / `FORBIDDEN_FILES`
- `INPUT` (Spezifikation, Vorlagen, Referenz-Test)
- `TOOLS` / `PERMISSIONS` / `TIME_BUDGET`

**Output (Pflicht, strukturiert):**
```
IDENTIFIER: MAKER
TASK_ID: <id>
IMPLEMENTATION_SUMMARY: <Kurzfassung der Umsetzung>
FILES_CHANGED: [<Pfad> ...]
TESTS_RUN: [<Beschreibung> ...]
TEST_RESULTS: [<PASS|FAIL ...>]
KNOWN_RISKS: [<Liste>]
UNRESOLVED_ISSUES: [<Liste>]
```

**Regeln:**
- **MAKER darf NIEMALS final PASS entscheiden.** Der PASS muss immer durch eine unabhängige
  Prüfung (CHECKER/Test/Red Queen) erfolgen.
- Berichtet ehrlich auch über fehlgeschlagene Tests und offene Risiken.
- Verändert nur `ALLOWED_FILES`; `FORBIDDEN_FILES` bleiben unberührt.
- Hält TIME_BUDGET ein; bei Überschreitung STOP und an Red Queen melden.
- Führt Tests aus, wo möglich, und dokumentiert die Ergebnisse.

---

## 3. CHECKER

**Zweck:** Unabhängige, objektive Prüfung eines MAKER-Ergebnisses gegen Requirement,
Akzeptanzkriterien und Architektur-/Security-Regeln.

**Input (ohne Maker-Argumentation):**
- Requirement + Akzeptanzkriterien (AC)
- Diff / geänderte Dateien
- Test-Ergebnisse / Ausführungsergebnisse
- Architektur- und Security-Regeln (z. B. Prioritätsprinzip, Safety-Regeln)

**Regeln:**
- **CHECKER MUSS ein FRESH child sein** (frische, unabhängige Instanz, getrennt vom Maker).
- **CHECKER erhält NICHT die Maker-Argumentation** (kein Rechtfertigungstext des Makers).
  Prüfung allein gegen Requirement/AC/Diff/Tests/Regeln.
- **CHECKER entscheidet ausschließlich:** `PASS`, `FAIL` oder `BLOCKED`.
- **Bei FAIL:** liefert `FAIL_REASON` + `EVIDENCE` + `REQUIRED_CORRECTION`.
- **Bei BLOCKED:** liefert Grund für den Block (fehlende Info/Klärungsbedarf).
- **CHECKER implementiert standardmäßig nicht selbst.** Er gibt Anweisungen zur Korrektur,
  der MAKER führt sie aus. Ausnahme nur auf explizite Anweisung von Red Queen.

**Output (strukturiert):**
```
IDENTIFIER: CHECKER
TASK_ID: <id>
VERDICT: PASS|FAIL|BLOCKED
FAIL_REASON: <bei FAIL>
EVIDENCE: <objektive Belege>
REQUIRED_CORRECTION: <bei FAIL, konkrete Anweisung>
```

**Zusätzlich bei PASS:** Checker bestätigt, dass Safety-Regeln und Architektur eingehalten wurden.

---

## 4. DEBUGGER

**Zweck:** Findet die Grundursache (Root Cause) eines Fehlers und empfiehlt eine neue Strategie.

**Input:**
- `TASK_ID`, `GOAL`, `SCOPE`
- Fehlerbeschreibung, Logs, Stacktrace, konkrete Symptome
- `ERROR_SIGNATURE` (normalisiert)
- `ATTEMPT_LEDGER` (bisherige Versuche aus dem Ledger)
- Liste bisheriger Lösungsansätze

**Regeln:**
- **Debugger MEIDET dieselbe fehlgeschlagene Strategie** (kein blindes Wiederholen).
- Untersucht die Ursache, NICHT nur das Symptom.
- Nutzt den `ATTEMPT_LEDGER`, um Duplikat-Strategien zu vermeiden.
- Liefert eine **neue**, begründete Strategie.

**Output (strukturiert):**
```
IDENTIFIER: DEBUGGER
TASK_ID: <id>
ROOT_CAUSE_HYPOTHESIS: <vermutete Ursache>
EVIDENCE: <Belege für die Hypothese>
NEW_STRATEGY: <neuer Ansatz, anders als bisherige>
RISKS: <Liste der Risiken der neuen Strategie>
RECOMMENDED_NEXT_ATTEMPT: <konkreter nächster Schritt>
```

---

## 5. TESTER

**Zweck:** Reproduzierbare, deterministische Validierung. **LLM-Ersatz:** Der Test sorgt
dafür, dass "Erfolg" maschinell und wiederholbar belegt wird, nicht durch LLM-Behauptungen.

**Input:**
- `TASK_ID`, `GOAL`
- Die durchzuführenden Validierungsschritte / Testfälle
- Erwartete Ergebnisse (EXPECTED)

**Regeln:**
- Tests MÜSSEN reproduzierbar sein (feste Befehle, deterministische Umgebung).
- Tester ersetzt nicht das LLM, sondern macht Ergebnisse maschinell prüfbar.
- Liefert nüchterne, nachprüfbare Fakten (keine Interpretation).

**Output (strukturiert, pro Test):**
```
IDENTIFIER: TESTER
TASK_ID: <id>
TEST_NAME: <Name>
COMMAND: <exakter auszuführender Befehl>
EXIT_CODE: <0|1|...>
EXPECTED: <erwartetes Ergebnis>
ACTUAL: <tatsächliches Ergebnis>
PASS/FAIL: <PASS|FAIL>
```

---

## 6. KNOWLEDGE AGENT

**Zweck:** Konsolidierung und Ablage von Wissen (Dokumentation, Notes) auf Basis
**validierter** Ergebnisse.

**Regeln:**
- **KNOWLEDGE arbeitet NUR nach validierten Ergebnissen** (erst wenn PASS/verifiziert vorliegt).
  Keine Wissensbildung aus ungeprüften oder abgebrochenen Versuchen.
- **Konsolidiert:** fasst Erkenntnisse aus mehreren WPs zusammen, vermeidet Duplikate.
- **Erkennt Duplikate/Konflikte** zwischen bestehenden und neuen Inhalten.
- Ablauf: `DETECT → VERIFY → RESOLVE`; andernfalls **HUMAN DECISION**.
- **KEINE stillen Überschreibungen:** existierende Inhalte werden nicht einfach überschrieben;
  Konflikte werden offengelegt und gemeldet.
- DETECT: Konflikt/Duplikat entdecken. VERIFY: mit validierten Fakten prüfen.
  RESOLVE: bereinigen/konsolidieren. Ohne eindeutige Validierung → HUMAN DECISION an Christian.

**Output (strukturiert):**
```
IDENTIFIER: KNOWLEDGE
TASK_ID: <id>
BASIS_TASKS: <validierte TASK_IDs>
ACTIONS_TAKEN: [<z.B. dokumentiert, konsolidiert, konflikt gemeldet>]
NEW_KNOWLEDGE: <Pfad/Beschreibung>
CONFLICTS_DETECTED: [<Liste>]
NEEDS_HUMAN_DECISION: <ja|nein>
```

---

## 7. Zuständigkeiten & Safety Gates

| Rolle | WHO | DARF NICHT | STATE GATE |
|-------|-----|-----------|------------|
| PLANNER | sub-agent | implementieren | Plan validiert, bevor READY |
| MAKER | sub-agent | final PASS, Forbidden Files ändern | Ergebnis → Checker |
| CHECKER | **FRESH child**, unabhängig | Maker-Argumentation erhalten, selbst implementieren (Standard) | PASS→OK, FAIL→Repair |
| DEBUGGER | sub-agent | fehlgeschlagene Strategie wiederholen | Root Cause+Neue Strategie |
| TESTER | sub-agent | LLM-Behauptungen statt Tests | Testdurchlauf + PASS/FAIL |
| KNOWLEDGE | sub-agent | unvalidierte Übernahme, stille Überschreibung | validiertes Ergebnis |

- **STOP:** Jede Rolle stoppt und ruft Red Queen (oder Escalation) bei: Block, unklarem Scope,
  wiederholter Fehler-Signatur, offenem Circuit Breaker, oder fehlender gültiger
  Zustands-Transition.