# RED QUEEN AUTONOMOUS ENGINEERING SYSTEM v1 — Architektur-Contracts

> **System:** Red Queen Autonomous Engineering System v1
> **Version:** 1.0 (A1-Architektur-Contracts)
> **Status:** Vertrags-Spezifikation (NICHT Runtime-Implementierung)
> **Sprache:** Deutsch (verbindlich)

---

## 1. Zweck

Dieses Dokumentenbündel definiert **verbindliche Architektur- und Safety-Contracts** für das
RED QUEEN AUTONOMOUS ENGINEERING SYSTEM v1. Die Contracts beschreiben, **wie** autonome
Engineering-Missionen strukturiert, delegiert, validiert, gemonitort und abgesichert werden.

Es gilt der Grundsatz: **Die Contracts steuern die Architektur, nicht umgekehrt.**
Abweichungen von einem Contract sind nur über das dafür vorgesehene Eskalations- und
Genehmigungsverfahren möglich (siehe `SAFETY_CONTRACT.md`).

## 2. Umfang und Abgrenzung

- **Enthalten:** Verträge für Orchestrierung, Agenten-Rollen, Zustandsmaschinen, Safety,
  Parallelität, Selbstverbesserung, Telegram-Kommunikation und externe Review-Gates.
- **NICHT enthalten:** Implementierung der Runtime, konkreter Quellcode, Deployment,
  tatsächliche Werte, Zugangsdaten, Endpunkte oder Betriebs-Konfiguration.
- **Dieses Bündel ist die verbindliche Vertrags-Grundlage.** Laufende Implementierung
  erfolgt in nachfolgenden Phasen (SELF-IMPROVEMENT-Policy, Phasenstufen).

## 3. Datei-Übersicht

| Datei | Inhalt | Kurzbeschreibung |
|-------|--------|------------------|
| `README.md` | Einstieg & Index | Zweck, Umfang, Prioritätsprinzip, Datei-Übersicht |
| `ARCHITECTURE.md` | Zielarchitektur | Knoten, Datenfluss, Arbeitsregeln, zentrale Instanz |
| `AGENT_CONTRACTS.md` | Rollen-Verträge | PLANNER/MAKER/CHECKER/DEBUGGER/TESTER/KNOWLEDGE |
| `MISSION_STATE_MACHINE.md` | Zustandsmaschinen | Mission- und Work-Package-Lifecycle |
| `SAFETY_CONTRACT.md` | Safety & Retry | Retry/Loop, Attempt Ledger, Oscillation, Circuit Breaker |
| `PARALLEL_EXECUTION.md` | Parallelität | Worktrees, Branch-Safety, Merge-Policy |
| `ROOT_SSH_GATE.md` | Privilegierter Zugriff | Root/SSH-Gate, Pflichtfelder, kritische Bereiche |
| `SELF_IMPROVEMENT_POLICY.md` | Selbstverbesserung | SI-1/SI-2/SI-3 Eskalationsstufen |
| `TELEGRAM_MISSION_CONTROL.md` | Kommunikation | Standardmeldungen, Anti-Spam-Regeln |
| `EXTERNAL_REVIEW_CONTRACT.md` | Externe Review | Rain-Nutzung, Alice-Ausschluss, Christian-Gate |

**Kern-Dateien:** Die 9 Contracts + dieses README. Keine unnötige Fragmentierung.

---

## 4. Prioritätsprinzip

Bei der Umsetzung gilt das folgende Prioritätsprinzip (höchste zuerst). Eine Lösung einer
höheren Stufe gewinnt immer gegen eine Lösung einer niedrigeren Stufe:

```
1. HERMES NATIVE   → Verwendung vorhandener Hermes-Kernfunktionen und nativer Fähigkeiten
2. CONFIG          → Konfiguration bestehender nativer Komponenten (ohne Code)
3. SKILL           → Wiederverwendbare Skills (Hermes-Konzept), Prozeduren/Muster
4. MINIMAL CUSTOM  → Minimaler, gezielter eigener Code nur, wenn Stufe 1–3 nicht reichen
5. EXTERNAL        → Externe Dienste/Werkzeuge nur als letzte Instanz
```

**Vertragsregeln:**
- **WHO:** Red Queen Lead Orchestrator prüft bei jeder technischen Lösung das Prioritätsprinzip.
- **WHEN:** Vor jedem Implementierungsschritt und jedem Architekturentscheid.
- **WHERE:** Gilt systemweit, für jede Codezeile und jeden integrierten Dienst.
- **PERMISSIONS:** Externe Dienste (Stufe 5) benötigen immer eine explizite Zulassung.
- **STOP:** Ein Vorstoß auf EXTERNAL ohne dokumentierte Begründung wird zurückgewiesen.

---

## 5. Verbindlichkeit und Leseart

- **MUSS/MUSS NICHT/SOLL/SOLL NICHT** folgen RFC 2119 (MUST/MUST NOT/SHOULD/SHOULD NOT).
- **WHO/WHEN/WHERE/PERMISSIONS/STATE/SAFETY GATES/STOP** sind Pflichtfelder aller Contracts.
- **STATE/Safety Gates** definieren Zustandsübergänge und Halt-/Eskalationspunkte.
- Jede Änderung an diesen Contracts unterliegt der SELF-IMPROVEMENT-Policy (SI-Stufe 2/3).

---

## 6. Schnellstart für Sub-Agenten

1. Zuerst `ARCHITECTURE.md` lesen (Rollen, Datenfluss, Arbeitsregeln).
2. Dann den rollenspezifischen Vertrag in `AGENT_CONTRACTS.md` zwingend einhalten.
3. Safety-Regeln aus `SAFETY_CONTRACT.md` beachten (Retry/Loop, Circuit Breaker).
4. Bei paralleler Arbeit `PARALLEL_EXECUTION.md` einhalten.
5. Privilegierte Aktionen (Root/SSH) nur gemäß `ROOT_SSH_GATE.md`.
6. Berichterstattung über Telegram gemäß `TELEGRAM_MISSION_CONTROL.md`.
7. Externe Fälle (Rain/Recovery) nur gemäß `EXTERNAL_REVIEW_CONTRACT.md`.

---

## 7. Implementierungsstatus

- **A1 (abgeschlossen, Commit `3d738e6`):** Architektur- & Safety-Contracts (dieses Bündel).
- **A2 (abgeschlossen):** Erste laufende Implementierung der Persistenzen-State-Machines
  unter `../a2/` (Mission-State- & Work-Package-State-Machine, minimaler Missions-Metadata-Layer
  auf nativer Hermes-Kanban-Basis, deterministische Tests). Siehe `../a2/README` / Module.
  Contracts in diesem Bündel bleiben die verbindliche Vertragsquelle; `a2/` ist die zugehörige Implementierung.