trading-system-docs/red-queen-architecture

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.