diff --git a/red-queen-architecture/AGENT_CONTRACTS.md b/red-queen-architecture/AGENT_CONTRACTS.md new file mode 100644 index 0000000..e9df39f --- /dev/null +++ b/red-queen-architecture/AGENT_CONTRACTS.md @@ -0,0 +1,225 @@ +# 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: +GOAL: +SCOPE: +WORK_PACKAGES: + - WP_ID: + DESCRIPTION: + CLASSIFICATION: SMALL|MEDIUM|LARGE|CRITICAL|DIFFICULT|SELF-MOD + DEPENDENCIES: <[WP_ID]> + ESTIMATE: + OWNER_ROLE: +ORDER / SEQUENCING: +RISKS / OPEN QUESTIONS: +``` + +**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: +IMPLEMENTATION_SUMMARY: +FILES_CHANGED: [ ...] +TESTS_RUN: [ ...] +TEST_RESULTS: [] +KNOWN_RISKS: [] +UNRESOLVED_ISSUES: [] +``` + +**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: +VERDICT: PASS|FAIL|BLOCKED +FAIL_REASON: +EVIDENCE: +REQUIRED_CORRECTION: +``` + +**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: +ROOT_CAUSE_HYPOTHESIS: +EVIDENCE: +NEW_STRATEGY: +RISKS: +RECOMMENDED_NEXT_ATTEMPT: +``` + +--- + +## 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: +TEST_NAME: +COMMAND: +EXIT_CODE: <0|1|...> +EXPECTED: +ACTUAL: +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: +BASIS_TASKS: +ACTIONS_TAKEN: [] +NEW_KNOWLEDGE: +CONFLICTS_DETECTED: [] +NEEDS_HUMAN_DECISION: +``` + +--- + +## 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. diff --git a/red-queen-architecture/ARCHITECTURE.md b/red-queen-architecture/ARCHITECTURE.md new file mode 100644 index 0000000..aaa1151 --- /dev/null +++ b/red-queen-architecture/ARCHITECTURE.md @@ -0,0 +1,135 @@ +# 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. diff --git a/red-queen-architecture/EXTERNAL_REVIEW_CONTRACT.md b/red-queen-architecture/EXTERNAL_REVIEW_CONTRACT.md new file mode 100644 index 0000000..7048ad6 --- /dev/null +++ b/red-queen-architecture/EXTERNAL_REVIEW_CONTRACT.md @@ -0,0 +1,75 @@ +# EXTERNAL_REVIEW_CONTRACT — Externe Review (Rain) & Ausschluss (Alice) + +> **Geltungsbereich:** Red Queen Autonomous Engineering System v1 +> **Status:** Verbindlicher Vertrag für externe Beteiligung +> **Sprache:** Deutsch (verbindlich) + +--- + +## 1. Rolle von Rain + +**Rain** ist ausschließlich für **spezielle, externe Fälle** vorgesehen: + +- **External Second Opinion** (unabhängige zweite Meinung zu einem schwierigen Problem). +- **Recovery** (Wiederherstellung nach Block/Circuit Breaker, wo interne Mittel erschöpft sind). +- **Independent Reviewer** (unabhängige Begutachtung, unabhängig von Red-Queen-internen Prüfern). + +**Rain ist NICHT Teil des normalen Graphen.** Rain wird **nicht automatisch** delegiert und +hat **keinen** normalen Stellenwert in der Mission-Ausführung. + +## 2. Wichtige Ausschlüsse / Limits + +- **Keine automatische Delegation** an Rain: Rain wird nur manuell (durch Christian) oder auf + klaren Eskalations-Pfad einbezogen. +- **Keine Root/SSH-Aufträge an Rain.** Rain bekommt **keine** Remote-/Systemzugriffs-Aufträge, + keine Secrets, keine privilegierten Befehle. +- Rain arbeitet **nur auf Basis einer klaren, begrenzten Frage** (nicht Vollzugriff auf System). +- **Alice ist ausgeschlossen**: keine Integration, keine Abhängigkeit, keine Delegation an Alice. + +## 3. Format: "EXTERNAL REVIEW REQUIRED" + +Bevor externe Hilfe (Rain) angefordert wird, erstellt Red Queen einen **strukturierten +Antrag**: + +``` +EXTERNAL REVIEW REQUIRED +MISSION: +TASK: +REASON: +EVIDENCE: +ATTEMPTS: +CURRENT STATE: +RISK: +WHAT NEEDS REVIEWED: +RECOMMENDED QUESTION FOR RAIN: +``` + +## 4. Ablauf / Freigabe-Gate + +1. Red Queen (oder Sub-Agent über Red Queen) erkennt Notwendigkeit der externen Review. +2. Red Queen erstellt den Antrag im oben genannten Format. +3. **STOPP / WAIT FOR CHRISTIAN** — Red Queen wartet auf **Christian**-Entscheidung, ob Rain + einbezogen wird. Kein Selbst-Start der externen Review. +4. **Christian entscheidet über Rain** (Freigabe/Nein). Nur mit christlicher Freigabe darf + Rain einbezogen werden. +5. Rain erhält die begrenzte, konkrete Frage (keine Root/SSH, keine Secrets). +6. Ergebnis → Christian → Red Queen integriert nach Validierung. + +- **WHO:** Red Queen erstellt Antrag; **Christian** genehmigt; Rain antwortet auf die Frage. +- **WHEN:** nur bei Escalation (nicht im normalen Arbeitsfluss). +- **WHERE:** über den strukturierten Kanal; Rain wird über Christian koordiniert. +- **STATE:** Bei externer Review → Mission/WP wird i. d. R. `ESCALATED`/`BLOCKED` und wartet. +- **SAFETY GATE / STOP:** Ohne Christian-Genehmigung keine Rain-Einbindung (STOPP). + +## 5. Regeln für Sub-Agenten + +- Sub-Agenten dürfen **nicht** direkt Rain kontaktieren oder externe Überprüfung anstoßen. +- Kein Sub-Agent delegiert eigenständig an Rain. +- Kein Root/SSH/Secret an Rain (unabhängig vom Anfragetext). +- Alice: keinerlei Einbindung (Abstimmung nur über Christian bei Bedarf, ansonsten aus). + +## 6. Auswirkungen auf den Betrieb + +- Der normale Graph bleibt ohne Rain/Alice: Red Queen + interne Sub-Rollen (PLANNER/MAKER/ + CHECKER/DEBUGGER/TESTER/KNOWLEDGE). +- Externe Review ist eine **Ausnahme**, nie die Regel. diff --git a/red-queen-architecture/MISSION_STATE_MACHINE.md b/red-queen-architecture/MISSION_STATE_MACHINE.md new file mode 100644 index 0000000..a06105c --- /dev/null +++ b/red-queen-architecture/MISSION_STATE_MACHINE.md @@ -0,0 +1,150 @@ +# MISSION_STATE_MACHINE — Zustandsmaschinen + +> **Geltungsbereich:** Red Queen Autonomous Engineering System v1 +> **Status:** Zustandsmaschinen-Spezifikation (NICHT implementiert) +> **Hinweis:** Diese Datei beschreibt das Verhalten; die Implementierung erfolgt in späteren +> Phasen (SELF-IMPROVEMENT-Policy). **Hier wird nichts umgesetzt.** + +--- + +## 1. Überblick + +Es gibt zwei verbundene Zustandsmaschinen: + +1. **MISSION** — der Gesamtvorgang (mehrere Work Packages umfassend). +2. **WORK PACKAGE (WP)** — einzelne Arbeitseinheit innerhalb einer Mission. + +Beide haben **Sonderzustände** für Abweichungen (Block, Pause, Fehler, Eskalation, Abbruch). + +--- + +## 2. Mission-Zustände + +### Reguläre Zustände +| Zustand | Bedeutung | +|---------|-----------| +| `CREATED` | Mission angelegt, noch nicht geplant | +| `PLANNING` | Planung durch PLANNER/Red Queen läuft | +| `READY` | Plan & WP validiert, ausführbar | +| `RUNNING` | WPs werden ausgeführt | +| `REVIEW` | Ergebnisse werden geprüft (Checker/Review) | +| `COMPLETED` | Alle WP DONE, Review abgeschlossen | + +### Sonderzustände +| Zustand | Bedeutung | +|---------|-----------| +| `BLOCKED` | Nicht fortführbar (Circuit Breaker, Konflikt) | +| `PAUSED` | Angehalten (kein Fortschritt), wieder aufnehmbar | +| `FAILED` | Endgültig fehlgeschlagen (nicht weiter) | +| `CANCELLED` | Abgebrochen (Mensch/Red Queen) | +| `ESCALATED` | Weitergereicht an höhere Instanz (Christian / Human Decision) | + +--- + +## 3. Work Package-Zustände + +### Normal +| Zustand | Bedeutung | +|---------|-----------| +| `TODO` | Geplant, nicht angefangen | +| `READY` | Bereit zur Ausführung | +| `IN_PROGRESS` | Wird ausgeführt (Maker/Debugger) | +| `CHECKING` | Ergebnis wird geprüft (Checker/Tester) | +| `DONE` | Akzeptiert (PASS), Task abgeschlossen | + +### Sonder +| Zustand | Bedeutung | +|---------|-----------| +| `FAILED` | Gescheitert (final) | +| `BLOCKED` | Nicht ausführbar (Block) | +| `ESCALATED` | An höhere Instanz weitergeleitet | + +--- + +## 4. Erlaubte Transitions — Mission + +| Von | Nach | Auslöser (WHO) | Erforderliche Evidence | Bemerkung | +|-----|------|----------------|------------------------|-----------| +| `CREATED` | `PLANNING` | Red Queen | Missions-Auftrag vorhanden | – | +| `PLANNING` | `READY` | Red Queen | Plan validiert, WP gültig | – | +| `PLANNING` | `BLOCKED` | Red Queen / Circuit | Plan-validierung fehlt | Block | +| `READY` | `RUNNING` | Red Queen | Start freigegeben | – | +| `RUNNING` | `REVIEW` | Red Queen | WP-DONE-Meilenstein | Prüfphase | +| `REVIEW` | `COMPLETED` | Checker/Red Queen | PASS aller relevanten WP | Fertig | +| `REVIEW` | `RUNNING` | Red Queen | Nachbesserung nötig | Iteration | +| `RUNNING` | `PAUSED` | Red Queen | Fortschrittslosigkeit/Block | Warte | +| `PAUSED` | `RUNNING` | Red Queen | Freigabe vorhanden | – | +| `RUNNING` | `BLOCKED` | Red Queen/Circuit | Trigger dokumentiert | – | +| `BLOCKED` | `PAUSED` | Red Queen | Block gelöst, warte | – | +| `BLOCKED` | `RUNNING` | Red Queen | Freigabe | – | +| `BLOCKED` | `ESCALATED` | Red Queen | Block + Notwendigkeit | – | +| `PAUSED` | `CANCELLED` | Christian | Abbruchanordnung | – | +| `RUNNING` | `FAILED` | Red Queen | Finaler Fehler | – | +| `RUNNING` | `CANCELLED` | Christian | Abbruch | – | +| `BLOCKED` | `CANCELLED` | Christian | Abbruch | – | +| `ESCALATED` | `RUNNING` | Christian/Higher | Entscheidung + Freigabe | – | +| `ESCALATED` | `CANCELLED` | Christian | Entscheidung = Abbruch | – | +| `ESCALATED` | `COMPLETED` | Higher | Entscheidung = OK | – | + +## 4. Erlaubte Transitions — WP + +| Von | Nach | Auslöser (WHO) | Evidence | +|-----|------|------|---------| +| `TODO` | `READY` | Red Queen | Plan/Validierung | +| `READY` | `IN_PROGRESS` | Red Queen (Delegation) | Startgenehmigung | +| `IN_PROGRESS` | `CHECKING` | MAKER/DEBUGGER | Ergebnis erstellt | +| `CHECKING` | `DONE` | CHECKER/Red Queen | PASS | +| `CHECKING` | `IN_PROGRESS` | Red Queen | FAIL→Repair (Repair-Zyklus) | +| `IN_PROGRESS` | `FAILED` | Red Queen | Nicht mehr reparierbar | +| `IN_PROGRESS` | `BLOCKED` | Red Queen/Circuit | Block dokumentiert | +| `BLOCKED` | `IN_PROGRESS` | Red Queen | Block gelöst | +| `BLOCKED` | `ESCALATED` | Red Queen | Weiterleitung | +| `ESCALATED` | `IN_PROGRESS` | Higher/Human | Freigabe | +| `ESCALATED` | `FAILED` | Higher/Human | Entscheidung | + +--- + +## 5. VERBOTENE Transitions + +Alle nicht gelisteten Übergänge sind **verboten** (Hard STOP). Insbesondere: + +| Von | Nach | Grund | +|------|------|-------| +| `RUNNING` | `COMPLETED` | Umgehung der Review-Prüfung | +| `RUNNING` | `DONE` (WP) | Umgehung von CHECKING | +| `CREATED`/`PLANNING` | `COMPLETED` | Kein Abschluss ohne Ausführung+Review | +| `FAILED` | `RUNNING` | Ein FAILED bleibt final, nur Neustart als neue Mission/WP | +| `CANCELLED` | jede aktive | Abgebrochene können nicht reaktiviert werden | +| `BLOCKED` | `COMPLETED` | Block verhindert Abschluss | + +- **WP darf ohne CHECKING nicht DONE werden.** +- **FAILED/CANCELLED sind Endzustände** (nicht ohne neue Anlage zurück). + +--- + +## 6. Transition-Verantwortlichkeiten + +| Transitions-Typ | WHO | +|-----------------|-----| +| Alle normalen Transitionen | Red Queen (Lead) steuert & validiert | +| Genehmigte Korrektur | Red Queen + MAKER | +| Prüfung | CHECKER (frisch, unabhängig) | +| PAUSEN / Block | Red Queen | +| Abbruch | nur Christian (Mensch) | +| Escalation | Red Queen (an Christian/Higher) | + +- Kein Sub-Agent kann selbst eine WP DONE setzen, ohne den Review-Zyklus (CHECKING→PASS). +- Red Queen validiert jede Transition via **State Validation** (Safety Layer) — ungültige + Transitions werden zurückgewiesen. + +--- + +## 7. Recovery-Regeln + +- `FAILED` WP/Mission: **nicht re-aktivieren**, stattdessen neue WP/Mission mit vollem + Review und ggf. Debugger erstellen. +- `BLOCKED`: Block-Ursache klären; wenn Auflösbar → freigeben; sonst `ESCALATED`. +- `PAUSED`: Wiederaufnahme nur mit Freigabe von Red Queen und erneutem State-Validierungs- + Prüfung (verpasste Abhängigkeiten ausschließen). +- Jede Recovery-Entscheidung wird im **Attempt Ledger** (SAFETY_CONTRACT) dokumentiert. +- Bei unklarem Zustand: **STOPP und Human/Christian fragen** (keine Ratesactionen). diff --git a/red-queen-architecture/PARALLEL_EXECUTION.md b/red-queen-architecture/PARALLEL_EXECUTION.md new file mode 100644 index 0000000..35544f3 --- /dev/null +++ b/red-queen-architecture/PARALLEL_EXECUTION.md @@ -0,0 +1,89 @@ +# PARALLEL_EXECUTION — Parallelität und Branch-Safety + +> **Geltungsbereich:** Red Queen Autonomous Engineering System v1 +> **Status:** Verbindlicher Parallelitäts-Contract +> **Sprache:** Deutsch (verbindlich) + +--- + +## 1. Grundregeln + +- **Maximal 3 aktive Work Packages (WPs) gleichzeitig.** +- **Nur unabhängige WPs** dürfen parallel laufen. Bei Abhängigkeit (eine benötigt die andere) + NICHT parallel ausführen. +- Red Queen überwacht Parallelität und erteilt Start-Freigabe (nicht der Sub-Agent). + +## 2. Paralleles Coding — GIT WORKTREE (VERPFLICHTET) + +- **Paralleles Coding ist VERPFLICHTET mit `git worktree` + eigenem branch.** +- **Kein paralleles Coding im selben Working Tree** — kein paralleler MAKER im selben + Arbeitsverzeichnis/`main`. +- Jeder parallele Maker arbeitet in einem **eigenen, isolierten worktree** und **eigenem + Branch**. + +### 2.1 WORKTREE OWNERSHIP +| Feld | Regel | +|------|-------| +| Wer erstellt | Red Queen (Lead) legt worktree je parallel-WP an | +| Eigentümer | Genau EIN Sub-Agent pro worktree/Branch (Owner) | +| Zugriff | Kein anderer Sub-Agent schreibt in fremden worktree | +| Freigabe/Entfernung | Red Queen nach Integration; Owner darf nicht ungefragt löschen | + +### 2.2 BRANCH NAMING +- Format: `rq//` (z. B. `rq/wp-042/fix-signal`). +- Ein Branch gehört genau **einem** worktree/Task. +- Kein Umbenennen/Übernehmen fremder Branches. + +### 2.3 TASK OWNERSHIP +- **EIN TASK = EIN OWNER.** Kein paralleler Konflikt-Owner auf dieselbe Datei im selben Scope. +- Bevor paralleles Coding startet, wird der **FILE SCOPE** der Tasks geprüft: überlappende + Dateien ⇒ Task-Nicht-unabhängig ⇒ nicht parallel. + +### 2.4 FILE SCOPE & LOCKING +- Tasks, die **dieselben Dateien** berühren, dürfen **nicht** parallel laufen (Overlap ⇒ serialisieren). +- **Locking:** Red Queen führt Lock-Liste je Datei; Datei im Lock ⇒ anderer WP wartet. +- Der Owner erwirbt Lock vor Änderung und gibt es nach Merge/Beendigung frei. + +### 2.5 RESULT COLLECTION +- Ergebnis je WP: Owner erstellt Commit auf eigenem Branch; Ergebnis/Test-Protokoll wird an + Red Queen gemeldet (Maker→Checker→Tests→PASS, siehe §3). + +### 2.6 CLEANUP +- Nach erfolgreichem Merge/Integration entfernt Red Queen den worktree und löscht den lokalen + Branch (nur nach Ablage/Integration). Kein ungeordneter Abbruch von Active-Locks. +- Bei Abbruch: Branch/wo manten + Red Queen-Check, worktree sauber räumen. + +--- + +## 3. MAIN BRANCH SAFETY + +- **Sub-Agenten arbeiten NIE direkt auf `main`.** +- Ablauf: `WP → Branch (worktree) → MAKER → Tests → CHECKER → PASS → Integration (durch Red Queen/Christian)` +- **Integration auf main** macht ausschließlich **Red Queen** (nicht der Sub-Agent), nur + nach CHECKER-PASS und validiertem Test. + +### 3.1 Verboten +| Aktion | Verbot | +|--------|--------| +| Force-Push | **Verbiet** überall (insb. auf main) | +| Blind-Merge | Kein Merge ohne Review/Checker-PASS | +| Blind-Rebase | kein Rebase ohne Verständnis/Abhängigkeit | +| History-Rewrite | keine Umschreibung der git-Historie | + +### 3.2 Divergenz +- Falls Branch vs. main divergiert/konfligiert: + - **STOPP** — kein erzwungenes Zusammenführen. + - Red Queen meldet an Christian / Checker und klärt Konflikt. + - Der Konflikt wird offengelegt gemeldet; kein blinder auto-merge. + - Circuit Breaker bei unaufgelöster Divergenz/Regression (siehe SAFETY_CONTRACT). + +--- + +## 4. Koordination + +- Red Queen ist der **einzige** Scheduler; maximale Parallelität = 3, unabhängige WPs. +- Neues paralleles WP wird nur gestartet, wenn Limit nicht erreicht ist und keine Abhängigkeit/ + Datei-Überlappung besteht. +- Vor jedem parallelem Start validiert Red Queen via **State Validation** die WP-Transitions + und FILE-Scope. +- Ergebnisse werden konsolidiert über Red Queen / Knowledge Agent (erst nach PASS). diff --git a/red-queen-architecture/README.md b/red-queen-architecture/README.md new file mode 100644 index 0000000..673856b --- /dev/null +++ b/red-queen-architecture/README.md @@ -0,0 +1,87 @@ +# 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`. diff --git a/red-queen-architecture/ROOT_SSH_GATE.md b/red-queen-architecture/ROOT_SSH_GATE.md new file mode 100644 index 0000000..12d497a --- /dev/null +++ b/red-queen-architecture/ROOT_SSH_GATE.md @@ -0,0 +1,102 @@ +# ROOT_SSH_GATE — Privilegierter Zugriff (Root/SSH) Vertrag + +> **Geltungsbereich:** Red Queen Autonomous Engineering System v1 +> **Status:** Verbindlicher Gate-Vertrag für privilegierte Aktionen (Root/SSH) +> **Sprache:** Deutsch (verbindlich) +> **Verwandt:** SAFETY_CONTRACT.md, EXTERNAL_REVIEW_CONTRACT.md, SELF_IMPROVEMENT_POLICY.md + +--- + +## 1. Grundsatz + +**Root ist KEIN Standardmodus.** Red Queen und alle Sub-Agenten arbeiten standardmäßig +als unprivilegierter Runtime-User. Jede privilegierte Aktion (Root-Befehl, SSH-Zugriff, +Sudo) ist ein **Ausnahmefall** und unterliegt einem obligatorischen Gate. + +Privilegierte Operationen dürfen **nie automatisch, ungeprüft oder als Nebeneffekt** +ausgeführt werden. + +## 2. Klassifikation + +| Kategorie | Beschreibung | Autonomie | +|---|---|---| +| **READ-ONLY Diagnose** | Zustand prüfen ohne Mutation (z. B. `df`, `ps`, Lese-Zugriff auf Config) | **Autonom erlaubt**, sofern selbst keine Änderung verursacht und keine Secret-Ausgabe | +| **Privilegierte Mutation** | Irgendeine Zustandsänderung über Root/SSH/Sudo | **Gate-Pflicht** (Abschnitt 3) | + +READ-ONLY-Diagnose darf autonom erfolgen, **wenn** sie (a) selbst keinen Zustand ändert, +(b) keine Secrets druckt und (c) auf den konkreten Diagnose-Zweck begrenzt ist. Bei +Unsicherheit, ob eine Aktion read-only ist → als Mutation behandeln. + +--- + +## 3. Gate vor jeder privilegierten Mutation + +Vor **jeder** privilegierten Mutation (Root/SSH) MÜSSEN alle Pflichtfelder erfüllt sein: + +| Pflichtfeld | Definition | Beispiel | +|---|---|---| +| **WHY** | Zweck, Problem/Anforderung, die nur privilegiert lösbar ist | "Config-Datei anpassen, die nur root lesen kann" | +| **WHAT** | Exakt welche Aktion/Änderung (eine logische Änderung) | "Eine Zeile in `` ergänzen" | +| **IMPACT** | Erwartete Auswirkung (Zustand vorher → nachher), Risiko | "Betroffene Dienste, keine Downtime erwartet" | +| **DEPENDENCIES** | Was muss vorhanden sein (Backups, Abhängigkeiten, Reihenfolge) | "Backup liegt vor; Dienst stoppt sauber" | +| **BACKUP** | Belegbarer Rollback-Bezug (Snapshot/Backup vorhanden) | "Config unter `` gesichert" | +| **ROLLBACK** | Konkrete Rückabwicklung bei Fehlschlag | "Zeile wieder entfernen / Config restore" | +| **TEST** | Verifikation des Erfolgs nach der Änderung | "Dienst startet, Konfigurationsprüfung OK" | + +Regel: **EINE logische Änderung → VALIDIEREN → TESTEN → erst dann weiter.** + +- **Ein** Commit/Eine Aktion pro Gate-Durchlauf. +- Nach der Änderung zwingend **VALIDIEREN** (ist das erwartete Ergebnis da?). +- Danach **TESTEN** (Verifikation aus TEST-Feld). +- Erst nach erfolgreicher Validierung darf die nächste Änderung beginnen. + +--- + +## 4. Kritische Bereiche (erhöhte Gate-Stufe) + +Folgende Bereiche erfordern **zusätzlich** zur obigen Gate **Christian/Approval**: + +- SSH / Remote-Zugriff +- Firewall / Networking +- Docker / Container-Infrastruktur +- Reverse Proxy +- Authentication / Authorization +- Secrets / Credential-Verwaltung +- Recovery Access (Backup-Zugang) +- Forgejo Security +- Ollama Core-Infrastruktur +- Red Queens eigener Container +- Hermes Runtime +- Zentrale Persistenz (state.db, Kanban, Cron) +- Circuit Breaker / Approval-Gates selbst + +Für diese Bereiche: **Gate = Pflichtfelder (3) + Christian-Approval** — KEINE autonome +privilegierte Mutation. + +--- + +## 5. Zuständigkeit (WHO / WHEN / STOPP) + +| Rolle | Darf | +|---|---| +| **Red Queen (Orchestrator)** | READ-ONLY-Diagnose autonom; privilegierte Mutation nur mit Gate (3); kritische Bereiche nur mit Christian-Approval | +| **Sub-Agenten (Maker/Checker/Debugger/Tester/Knowledge)** | **NIE** selbst Root/SSH-Mutationen. Nur nach ausdrücklicher Freigabe durch Red Queen/Christian mit präzisem, begrenztem Scope | +| **Rain** | **NIE** Root/SSH-Aufträge von Red Queen (siehe EXTERNAL_REVIEW_CONTRACT.md); nur Christian entscheidet über Rain-Einsatz | +| **Christian** | einzige Instanz für kritische Gate-Freigaben | + +**STOPP-Bedingungen (Break):** +- Ein Pflichtfeld aus Abschnitt 3 fehlt oder ist vage → **STOPP**, keine Mutation. +- Unerwartete Berechtigungsänderung / Identity-Mismatch → **STOPP**, Circuit Breaker. +- Kritischer Bereich ohne Christian-Approval → **STOPP**. +- SECRET / Credential wird sichtbar → **STOPP**, Sicherheits-Vorfall. + +**REMAIN-Verstärkung:** Bestehende `safe-root-engineering` / `safe-change-management` +Regeln werden durch diesen Vertrag **nicht abgeschwächt**, sondern übernommen. + +--- + +## 6. Verhältnis zu anderen Contracts + +- **SAFETY_CONTRACT.md** — Retry/Loop/Circuit Breaker (privilegierte Aktion fällt unter dessen Regeln). +- **SELF_IMPROVEMENT_POLICY.md** — Änderungen an Root/SSH-Policy = **SI-3 (Human/External Gate)**. +- **EXTERNAL_REVIEW_CONTRACT.md** — Rain erhält nie Root/SSH-Aufträge von Red Queen. diff --git a/red-queen-architecture/SAFETY_CONTRACT.md b/red-queen-architecture/SAFETY_CONTRACT.md new file mode 100644 index 0000000..b06b2d2 --- /dev/null +++ b/red-queen-architecture/SAFETY_CONTRACT.md @@ -0,0 +1,136 @@ +# SAFETY_CONTRACT — Retry, Loop, Attempt Ledger, Oscillation, Circuit Breaker + +> **Geltungsbereich:** Red Queen Autonomous Engineering System v1 +> **Status:** Verbindlicher Safety-Contract +> **Sprache:** Deutsch (verbindlich) + +--- + +## 1. Prinzip + +Alle Wiederholungs-, Fehler- und Schleifenlogik ist **deterministisch** und wird durch den +**Deterministic Safety Layer** überwacht. Ziel: keine Endlosschleifen, kein Blind-Wiederholen, +kein unkontrollierter Schaden. **Hard Limits werden immer vor Anwendung eines Zählers definiert.** + +## 2. Retry / Loop Contract + +### 2.1 Globale Notbremse +- `max_iterations = 50` ist die **äußerste Notbremse** für die gesamte Mission/Schleife. + Sie wird nur als **letzter Schutz** erreicht und darf im Normalbetrieb nie erreicht werden. + Erreicht ein Zähler `50`, **erzwungener STOPP** (Circuit Breaker) und Escalation. + +### 2.2 Operative Regeln (früher und wirksamer) +| Regel | Limit | Erläuterung | +|-------|-------|-------------| +| Maker→Checker **Repair** | **MAX 3** | Maximal 3 Mal darf ein MAKER nach CHECKER-FAIL korrigieren | +| Gleiche **Error Signature** | **MAX 2** | Gleiche Fehler-Signatur maximal 2 Versuche | +| Gleiche **Lösungsstrategie** | **Nicht blind** | Bei erneuter Fehler-Signatur NIE dieselbe Strategie ungeprüft wiederholen; Strategiewechsel verpflichtend | + +### 2.3 Eskalationskette (nach wiederholtem Fail) +``` +Fehlschlag → + 1) Repair (Maker) [MAX 3] + 2) Gleiche Error-Signatur? → Strategiewechsel (Debugger) [MAX 2] + 3) Debugger (Root Cause, neue Strategie) + 4) Second Opinion (frischer Checker/External) + 5) BLOCK / ESCALATE (an Red Queen → Christian) +``` +- Wenn nach der Eskalationskette **kein Fortschritt** → **BLOCKED/ESCALATED** (siehe + MISSION_STATE_MACHINE) und **STOPP**. +- Kein Sub-Agent darf die Kette überspringen oder von Schritt 5 zurück zu Schritt 1 + springen, ohne dass der Fehler verändert wurde. + +### 2.4 Zähler-Zurücksetzung +- Zähler werden **pro TASK_ID** geführt und nur bei einem tatsächlichen Fortschritt + (neue Erkenntnis, neuer Zustand) zurückgesetzt. Bloßer Zeitablauf setzt nichts zurück. + +--- + +## 3. Attempt Ledger Contract + +**Zweck:** Unveränderliches, nachvollziehbares Log jedes Versuchs — Grundlage für Debugger, +Checker und Oscillation Detection. + +### 3.1 Ledger-Schema (jeder Eintrag) +| Feld | Bedeutung | +|------|-----------| +| `ATTEMPT_ID` | Eindeutige ID dieses Versuchs | +| `TIMESTAMP` | Zeitpunkt | +| `TASK_ID` | Zugehörige Aufgabe | +| `HYPOTHESIS` | Vermutete Ursache/Annahme | +| `STRATEGY` | Gewählter Ansatz | +| `CHANGE` | Was geändert wurde | +| `RESULT` | Ergebnis (PASS/FAIL/…) | +| `ERROR_SIGNATURE` | Normalisierte Fehlerkennung | +| `PROGRESS` | Messbarer Fortschritt (ja/nein, welcher) | + +### 3.2 Regeln +- **WHO:** Red Queen/Safety Layer schreibt jeden Versuch **append-only** in das Ledger. +- **Kein Löschen / kein Überschreiben** historischer Einträge. +- **CHECKER/DEBUGGER** lesen das Ledger, um Duplikat-Strategien zu vermeiden. +- Ohne Ledger-Eintrag keine neue Zählung; Zählung basiert auf Ledger-Daten. + +--- + +## 4. Oscillation Contract + +**Definition von Oscillation:** +- **A→B→A→B** (Zustand/Strategie wechselt ohne echten Fortschritt). +- **Wiederholte Fehler-Signaturen** trotz Wechselversuch. +- **Wiederholte Dateiänderung ohne Fortschritt** (Änderung an derselben Datei, keine messbare + Verbesserung). + +### 4.1 Detektion +- Safety Layer prüft jede neue Attempt gegen das Ledger: + - Fehler-Signatur identisch zu ≥1 Vorgänger → Warnung. + - Datei X ≥3 Mal geändert ohne Progress-Metrik → **Oscillation-Verdacht**. + - Zustandsfolge A→B→A→B erkannt → **Oscillation**. +- **Progress muss messbar sein** (nicht subjektiv). Progress = messbare Metrik + (z. B. "Test X grün", "Anzahl Fehler sinkt", "Doku-Datei angelegt"), belegt in `PROGRESS`. + +### 4.2 Reaktion +- Bei Oscillation: **STOP** der aktuellen Schleife, **Strategiewechsel erzwingen**, + ggf. **DEBUGGER einsetzen**, andernfalls **BLOCK/ESCALATE**. +- **NIE** dieselbe Strategie blind fortsetzen. + +--- + +## 5. Circuit Breaker Contract + +**Zweck:** Harte, automatische Haltesperre bei kritischen Bedingungen. + +### 5.1 Trigger-Liste (mindestens diese Bedingungen öffnen den Breaker) +| Trigger | Beispiel | +|---------|----------| +| **Retry** | operativ Limits überschritten (Repair>3, Signature>2) | +| **Oscillation** | A↔B, wiederholte Signaturen, Dateiänderung ohne Progress | +| **State** | ungültige/verbotene Zustands-Transition | +| **Git** | Konflikt/Diverenz, main-Manipulation (siehe PARALLEL) | +| **Prod** | Betroffenheit von Produktion/Live-System | +| **Secret** | Geheimnis/Token-Abruf/Schlüssel sichtbar | +| **Regression** | bestehende Funktionalität gebrochen (Test-Fail) | +| **SSH** | Remote-Zugriff/Verbindung ohne Freigabe | +| **Disk** | Festplatten-/Speicherprobleme | +| **Approval-Identity** | Unberechtigte Freigabe / Identity-Zweifel | +| **Persistenz** | Persistenz/Repo-Integrität gefährdet | + +### 5.2 Aktionen bei geöffnetem Breaker +1. **STOP** — alle Sub-Agenten/Arbeit sofort beenden (keine neuen Aktionen). +2. **SAVE** — aktuellen Zustand/ledger persistieren (sofern möglich). +3. **NO MUTATION** — keinerlei weitere Änderung an Dateien/Repo/Systemen. +4. **TELEGRAM ALERT** — kritische Meldung an Telegram (siehe TELEGRAM_MISSION_CONTROL). + +### 5.3 Reset / Closing +- Breaker bleibt **offen** bis ein **validierter** Reset erfolgt: + - Ursache behoben & dokumentiert, gültige Zustands-Transition, Freigabe. + - **Human/Christian** bei kritischen Triggern (Prod/Secret/SSH/Persistenz/Identity). +- Reset nur durch Red Queen (Lead) + ggf. Christian; kein selbst-Auto-Reset in kritischen Klassen. + +--- + +## 6. Safety Gates & STOP + +- **WHO:** Red Queen führt die Safety Layer aus; jeder Sub-Agent hält Limits. +- **WHEN:** Vor jeder Transition, vor jeder Retry, vor jeder Aufgabe-Abschluss. +- **WHERE:** Systemweit, auf Mission- und WP-Ebene. +- **STOP:** Jeder Trigger der §5.1 erzwingt sofortiges STOP; Fortsetzung ohne Freigabe verboten. diff --git a/red-queen-architecture/SELF_IMPROVEMENT_POLICY.md b/red-queen-architecture/SELF_IMPROVEMENT_POLICY.md new file mode 100644 index 0000000..94dd375 --- /dev/null +++ b/red-queen-architecture/SELF_IMPROVEMENT_POLICY.md @@ -0,0 +1,75 @@ +# SELF_IMPROVEMENT_POLICY — Selbstverbesserung und Eskalationsstufen + +> **Geltungsbereich:** Red Queen Autonomous Engineering System v1 +> **Status:** Verbindliche Selbstverbesserungs-Policy +> **Sprache:** Deutsch (verbindlich) + +--- + +## 1. Prinzip + +Red Queen darf sich selbst verbessern — aber nur **innerhalb klar definierter Grenzen und +Eskalationsstufen (SI-1 / SI-2 / SI-3)**. Änderungen an **Kern-Systemen** (Sicherheit, +Steuerung, Persistenz, Runtime) erfordern **menschliche/externe Gates**. + +**Für A1 (Architektur-Contracts):** Die **Implementierung dieser Policy** wird **NICHT +automatisiert**. Es wird nur die Policy definiert; die eigentliche Automatisierung von +Selbstverbesserung ist in spätere Phasen gestellt. **KEINE Automation in A1.** + +## 2. Eskalationsstufen + +### SI-1 (LOW) — Autonom innerhalb Grenzen +Betrifft: **ungefährliche** Verbesserungen. +- Neue Skills (gefahrlose), Verbesserung von Skills, Tests, Diagnose, Doku, Retrieval, + Sub-Agent-Prompts. +- **Berechtigt:** Red Queen kann diese **autonom** durchführen, solange sie ungefährlich, + reversibel und im eigenen Scope sind. +- **Grenzen:** keine Änderung an Sicherheit/Steuer/Kern-Systemen. +- **Gate:** Standard (kein Human-Gate erforderlich, aber dokumentiert). + +### SI-2 (HIGH) — INDEPENDENT INTERNAL REVIEW +Betrifft: **Mission/Task Engine, Loop Controller, Maker/Checker (als System), Heartbeat, +Orchestrator**. +- Änderungen an diesen Komponenten wirken auf die Steuer-/Lauf-Logik des Systems. +- **Berechtigt:** Nur nach **UNANGREIFBARER INTERNER REVIEW** (frischer, unabhängiger, + intern verifizierender Sub-Agent/Checker — nicht der Autor). Das ist ein erhöhtes Gate + gegenüber SI-1. +- Der interne Reviewer entscheidet objektiv (keine Maker-Argumentation). +- Gate: Independent Internal Review + Red Queen-Freigabe. + +### SI-3 (CRITICAL) — HUMAN / EXTERNAL GATE +Betrifft (Kern-/Kritische Bereiche): +- **Root Policy, SSH Policy, Recovery, Circuit Breaker, Approval Gates, Auth, Secrets, + zentrale Persistenz, Hermes Runtime, Red-Queen-Container.** +- **Berechtigt:** ausschließlich mit **HUMAN / EXTERNAL GATE** (Christian-Genehmigung). +- Keine autonome Änderung in SI-3; jede Änderung erfordert menschliche/externe Freigabe, + dokumentierte Begründung und Review. +- Externe Beteiligung (falls technisch nötig) nur gemäß EXTERNAL_REVIEW_CONTRACT (Rain) und + über Christian. + +## 4. Ablauf / Zuständigkeiten + +| Aktion | SI-1 | SI-2 | SI-3 | +|--------|------|------|------| +| Autonom | Ja | Nein | Nein | +| Interne Review | Entfällt | Pflicht (frischer Checker) | Zusätzlich human/extern | +| Human/External Gate | Nein | Nein | Pflicht | +| Dokumentation | Ledger + kurze Notiz | Review-Protokoll | Review + Genehmigung | + +- **WHO:** Red Queen führt Änderungen aus; Christian/Human genehmigt SI-3. +- **WHEN:** Vor jeder Selbstverbesserung Stufe prüfen (Klassifikation der Änderung). +- **WHERE:** alle betroffenen Komponenten. +- **Safety Gate / STOP:** Bei Unsicherheit der SI-Stufe → höhere Stufe wählen; SI-3 ohne + Freigabe → **STOPP** und Genehmigungsanfrage (Telegram APPROVAL REQUIRED). + +## 5. KEINE Automation in A1 + +- In der A1-Phase (dieser Architektur-Contracts) ist **keine** Selbstverbesserungs-Automation + umzusetzen. Es wird nur die Policy (Richtlinie) dokumentiert. +- Die automatische Selbstverbesserung wird in einer **späteren Phase** nach Validierung der + Contracts und nach menschlicher Freigabe eingeführt. + +## 6. Verification + +- Jede angewandte Selbstverbesserung wird im Attempt Ledger (SAFETY_CONTRACT) mit + `HYPOTHESIS`/`CHANGE`/`RESULT` dokumentiert und durch eine Review (je nach Stufe) validiert. diff --git a/red-queen-architecture/TELEGRAM_MISSION_CONTROL.md b/red-queen-architecture/TELEGRAM_MISSION_CONTROL.md new file mode 100644 index 0000000..40069fc --- /dev/null +++ b/red-queen-architecture/TELEGRAM_MISSION_CONTROL.md @@ -0,0 +1,88 @@ +# TELEGRAM_MISSION_CONTROL — Kommunikations-Contract + +> **Geltungsbereich:** Red Queen Autonomous Engineering System v1 +> **Status:** Verbindlicher Kommunikations-Contract (Telegram) +> **Sprache:** Deutsch (verbindlich) + +--- + +## 1. Grundsatz + +Telegram dient als **kontrollierte, nicht-spamende** Kommunikationsbrücke zu Christian. +**Keine Mikro-Updates, kein Spam.** Meldungen werden nur bei **signifikanten** Ereignissen +versendet und folgen festen Standardformaten. + +## 2. Standard-Meldungen + +### 2.1 MISSION ACCEPTED +- **WHEN:** Eine Mission wurde von Red Queen angenommen und in PLANNING/CREATED gesetzt. +- **Inhalt:** Missionsname/-ID, Kurz-Klassifikation (SMALL/MEDIUM/…), erwartete Richtung. + +### 2.2 CHECKPOINT +- **WHEN:** Nur bei **sinnvoller Phase** (z. B. Plan steht, kritischer Meilenstein, wichtige + Etappe fertig, in REVIEW gegangen). **NICHT** bei jedem WP. +- **Inhalt:** Task/Phase, Status (z. B. Plan validiert, N kritische WP PASS, Testsumme). + +### 2.3 BLOCKER +- **WHEN:** Ein WP/Mission ist `BLOCKED` oder `FAILED` (nach SAFETY-Kette). +- **Inhalt:** WAS blockt, TASK_ID, Fehler-Signatur, getroffene Maßnahmen, STOP-Status. + +### 2.4 DECISION REQUIRED +- **WHEN:** Eine Entscheidung von Christian/Red Queen-Higher ist nötig (z. B. Human Decision, + Konflikt, Scope-Frage). +- **Inhalt:** Klare Frage, Kontext, Optionen, Konsequenzen bei jeder Option. + +### 2.5 APPROVAL REQUIRED +- **WHEN:** Ein Genehmigungs-Gate (SI-2/SI-3, Integration auf main, externer Zugriff) ist nötig. +- **Inhalt:** Was genehmigt werden soll, Scope, Risiko, wer antworten muss (Christian). + +### 2.6 CRITICAL +- **WHEN:** Circuit Breaker geöffnet / kritischer Trigger (SAFETY_CONTRACT §5) / Prod-/Secret-/ + SSH-/Persistenz-Vorfall. +- **Inhalt:** CRITICAL-Status, Trigger, STOP + NO MUTATION bestätigt, Alarmhinweis. + +### 2.7 MISSION COMPLETE +- **WHEN:** Mission vollständig (alle WP DONE, REVIEW abgeschlossen). +- **Inhalt:** MISSION-ID, Ergebnis-Zusammenfassung, Artefakte/Verweise, ggf. offene Punkte. + +--- + +## 3. Anti-Spam- und Kopplungsregeln + +| Regel | Umsetzung | +|-------|-----------| +| **Keine Micro-Updates** | Kein Meldung je kleinstem Schritt/Sekundär-Detail | +| **Kein Spam** | Keine Wiederholungen; Checkpoints nur bei sinnvoller Phase | +| **CHECKPOINT nur bei sinnvoller Phase** | Phase mit Mehrwert; nicht pro Zwischenschritt | +| **Batching** | Wenn mehrere Meldungen im selben Zeitfenster → zusammenfassen | +| **Dedupe** | identische/konsistente Status nicht erneut senden | +| **Priorität** | CRITICAL / DECISION / APPROVAL → sofort; CHECKPOINT → geordnet | + +--- + +## 4. Autonomes Weiterarbeiten + +Red Queen/Sub-Agenten arbeiten **autonom weiter**, wenn **alle** der folgenden Bedingungen +erfüllt sind: +1. **Mission eindeutig** (klarer Auftrag, keine offenen Scope-Fragen). +2. **Fortschritt** messbar (Progress im Ledger). +3. **Safety eingehalten** (keine überschrittenen Limits, kein offener Circuit Breaker). +4. **Keine Human Decision erforderlich** (kein DECISION/APPROVAL-Trigger). + +Sobald eine dieser Bedingungen fehlt → **STOPP und Meldung** (DECISION/APPROVAL/BLOCKER/CRITICAL), +nicht blind weiterarbeiten. + +## 5. Meldungs-Format + +Jede Meldung nutzt einen festen Präfix, um maschinelle Auswertbarkeit zu gewährleisten: +``` +[MISSION ACCEPTED] / [CHECKPOINT] / [BLOCKER] / [DECISION REQUIRED] / +[APPROVAL REQUIRED] / [CRITICAL] / [MISSION COMPLETE] +``` +Danach folgen Pflichtfeld-Elemente (Task-ID, Status, Grund/Info) gemäß §2. + +## 6. WHO / STOP +- **WHO:** Red Queen versendet Standardmeldungen; Sub-Agenten kommunizieren nicht selbständig + nach außen, sondern über Red Queen. +- **WHERE:** Telegram-Status-Kanal. +- **STOP:** Bei CRITICAL → alle weiteren autonomen Aktionen stoppen; nur Meldung + warten.