# ARCHITECTURE — Zielarchitektur

> **Geltungsbereich:** Red Queen Autonomous Engineering System v1
> **Status:** Zielarchitektur (Contract-Ebene, keine Implementierung)
> **Sprache:** Deutsch (verbindlich)

---

## 1. Systemüberblick

Die Zielarchitektur ist eine **sternförmige Orchestrierung** mit einer einzigen zentralen
Instanz — **Red Queen (Lead Orchestrator)**. Alle Missionen und Aufgaben laufen über Red
Queen; es gibt keinen parallelen, unkontrollierten Datenfluss.

```
 Christian (Mensch / Menschliche Kontrolle)
      │
      ▼
 ┌─────────────────────────┐
 │  RED QUEEN              │  ── Lead Orchestrator (zentrale Instanz)
 │  (Lead Orchestrator)    │
 └────────────┬────────────┘
              │  delegiert (delegate_task)
              ▼
 ┌───────────────────────────────┐
 │  KANBAN (Mission/Work Packages)│
 └──────────────┬────────────────┘
                │
   ┌────────────┼────────────┬──────────────┬──────────────┐
   ▼            ▼            ▼              ▼              ▼
 PLANNER      MAKER       CHECKER       DEBUGGER       TESTER
   └───────────┴────────────┴──────────────┴──────────────┘
                │ (Ergebnisse)
                ▼
 ┌─────────────────────────────────────────┐
 │  DETERMINISTIC SAFETY LAYER             │
 │  • State Validation                     │
 │  • Retry Counter                        │
 │  • Attempt Ledger                       │
 │  • Error Signature                      │
 │  • Oscillation Detection                │
 │  • Circuit Breaker                      │
 └──────────────────┬──────────────────────┘
                    │
                    ▼
            ┌─────────────────┐
            │  Cron / Resume  │
            └────────┬────────┘
                     ▼
                 FORGEJO
            (Repository-Persistenz)

         KNOWLEDGE AGENT (konsolidiert, nur nach validierten Ergebnissen)
```

## 2. Zentrale Instanz: Red Queen

- **Red Queen** ist die **einzige** koordinierende Instanz im normalen Graphen.
- Sie besitzt den Überblick über alle Missionen, Work Packages (WP), Retry- und Circuit-Status.
- Sie steuert `delegate_task` an alle Sub-Rollen.
- **Rain und Alice sind NICHT im normalen Graphen** (siehe `EXTERNAL_REVIEW_CONTRACT.md`):
  - **Rain:** nur als External Second Opinion / Recovery / Independent Reviewer,
    ausschließlich über Christian koordiniert — keine automatische Delegation.
  - **Alice:** ausgeschlossen — keine Integration, keine Abhängigkeit, keine Delegation.

## 3. Datenfluss

1. **Christian** gibt eine Mission vor.
2. **Red Queen** nimmt die Mission auf, erstellt Mission + zugehörige Work Packages (WP) in
   einem zentralen Kontrollorgan (Kanban).
3. **Red Queen** ruft `delegate_task` für PLANNER, MAKER, CHECKER, DEBUGGER, TESTER,
   KNOWLEDGE AGENT gemäß Arbeitsregeln (§5).
4. Sub-Rollen arbeiten im Rahmen ihrer Contracts (`AGENT_CONTRACTS.md`).
5. Ergebnisse passieren den **Deterministic Safety Layer** (Validierung, Retry, Ledger,
   Oscillation, Circuit Breaker).
6. Persistenz erfolgt über **Cron/Resume** und **Forgejo**.

## 4. Deterministic Safety Layer

Alle Zustandsänderungen, Retries und Wiederversuche sind **deterministisch** regliert
(kein LLM-Bauchgefühl). Bestandteile:

| Komponente | Verantwortlichkeit |
|-----------|--------------------|
| **State Validation** | Prüft Gültigkeit von Zustandsübergängen vor jeder Aktion |
| **Retry Counter** | Zählt Wiederholungen und erzwingt Limits |
| **Attempt Ledger** | Unveränderliches Log aller Versuche (siehe SAFETY_CONTRACT) |
| **Error Signature** | Normalisierte Fehlerkennung zur Erkennung von Wiederholungen |
| **Oscillation Detection** | Erkennt A↔B↔A-Zyklen und Fortschrittslosigkeit |
| **Circuit Breaker** | Öffnet bei kritischen Triggern und stoppt Mutationen |

Der Safety Layer ist **nicht delegierbar** und wird von der Red Queen (Lead) aktiviert,
bevor jede Task-Ausführung abgeschlossen wird.

## 5. Arbeitsregeln (Klassifikation → Zuordnung)

| Klassifikation | Bearbeitung | Zusätzliche Gate |
|----------------|-------------|------------------|
| **SMALL** | Red Queen selbst (Direkt-Bearbeitung, kein Sub-Agent nötig) | Standard |
| **MEDIUM / LARGE** | **MAKER** | Standard |
| **CRITICAL** | **MAKER + CHECKER** (Checker erforderlich) | Checker-Gate |
| **DIFFICULT** | **DEBUGGER** (Fehleranalyse) | Standard |
| **SELF-MOD** (Selbstmodifikation) | **erhöhtes Gate** (SI-2/SI-3 laut SELF_IMPROVEMENT_POLICY) | Human/External Gate |

Regeln:
- **SMALL:** Kein Overhead — Red Queen führt direkt aus.
- **CRITICAL** erzwingt **zusätzlich einen CHECKER** (muss PASS).
- **DIFFICULT:** zuerst Debugger (Fehler-Ursache), erst danach Maker zur Korrektur.
- **SELF-MOD:** Jede Änderung an Kern-Systemen erfordert die erhöhten Gates der SI-Policy.

---

## 6. Zuständigkeiten (WHO / WHEN / WHERE)

| Element | WHO | WHEN | WHERE |
|---------|-----|------|-------|
| Missionsannahme | Red Queen | Empfang | Kanban |
| Arbeitsklassifikation | Red Queen | Vor Delegation | Kanban / Planning |
| delegate_task | Red Queen | je Arbeitspaket | Orchestrator |
| Safety Layer | Red Queen (Lead) | jede Transition | Orchestrator |
| Checker-Gate | CHECKER | nach Maker | Prüfschleife |
| Externe Review | Christian → Rain | nur Eskalation | EXTERNAL_REVIEW_CONTRACT |

## 7. Safety Gates & STOP

- **STATE:** Jede Aufgabe wechselt nur über gültige Transitions (MISSION_STATE_MACHINE).
- **SAFETY GATES:** Circuit Breaker kann jede Schleife öffnen (SAFETY_CONTRACT).
- **STOP:** Bei fehlendem Fortschritt, wiederholter Fehler-Signatur oder Zustandsverletzung
  verlangt das System einstoppen und die höchste Gate anrufen.

## 8. Abgrenzung

- In dieser Datei werden **nur** die Architektur-Contracts beschrieben. Implementierungen
  der Runtime, der Kanban-Persistenz, des Orchestrator-Codes oder der Cron-Scheduler sind
  **nicht** Bestandteil und in spätere SI-Phasen einzuordnen.