178 lines
7.6 KiB
Markdown
178 lines
7.6 KiB
Markdown
# Red Queen — A4: Bounded Orchestrator (V1)
|
||
|
||
Der **Bounded Orchestrator** verbindet erstmals kontrolliert die A1-Architektur,
|
||
den A2 **Mission/WP-State** (`missions.db`, autoritativ für Transitionen), den A3
|
||
**Deterministic Safety Layer** (`safety.db`, verbindliche Safety-Decision) und
|
||
die **Hermes-native `delegate_task`**-Sub-Agenten (Planner/Maker/Checker) zu
|
||
einer **expliziten, garantiert endenden** Build-Pipeline:
|
||
|
||
```
|
||
MISSION → VALIDATE STATE → VALIDATE SAFETY → PLAN → VALIDATE PLAN
|
||
→ CREATE WORK PACKAGES → SELECT RUNNABLE WP → MAKER → TEST
|
||
→ FRESH CHECKER → SAFETY DECISION → STATE UPDATE → NEXT BOUNDED STEP
|
||
→ FINALIZE / STOP
|
||
```
|
||
|
||
**WICHTIG:** A4 ist **KEIN 24/7-System.** Kein Heartbeat, kein Mission-Cron, kein
|
||
dauerhafter Worker, kein while-True-Agentloop, kein Background-Daemon, kein
|
||
Self-Improvement-Automation, keine automatische Rain-Eskalation. A4 läuft nur nach
|
||
einem **expliziten Start** und endet **garantiert** (bounded).
|
||
|
||
---
|
||
|
||
## Architektur-Prinzip
|
||
|
||
**Red Queen (ein Hermes-Agent) ist der Orchestrator.** Der echte Sub-Agenten-Versand
|
||
(Planner/Maker/Checker) läuft über die Hermes-native `delegate_task`-Engine — ein
|
||
Python-Prozess kann diese NICHT aufrufen. Deshalb implementiert A4 die
|
||
**deterministische Orchestrierungs-Logik** als reine, inaktive Python-Library
|
||
(`Orchestrator`), die Red Queen als **Entscheidungs- und State-Maschine** importiert
|
||
und ansteuert:
|
||
|
||
- Die **Library** entscheidet deterministisch: was ist runnable, Safety-Gate,
|
||
Risk>Size, Approval-Gate, Completion-Gate, Bounded-Run-Limits, Repair-Flow,
|
||
idempotente Wiederaufnahme, Restart-Persistenz.
|
||
- **Red Queen selbst** startet die tatsächlichen Child-Agenten (Planner/Maker/Checker)
|
||
über `delegate_task`, übergibt ihnen das von der Library erzeugte
|
||
Dispatch-Contract und führt das Ergebnis über `apply_child_result` zurück.
|
||
- Für Tests wird ein simuliertes `ChildDispatcher`-Callable injiziert — die Library
|
||
selbst startet nichts und läuft nie zyklisch.
|
||
|
||
---
|
||
|
||
## Datenfluss & Gates
|
||
|
||
| Schritt | Mechanik | Verbindlich |
|
||
|---------|----------|-------------|
|
||
| 1. Plan erhalten | von Planner | Output-Format laut AGENT_CONTRACTS |
|
||
| 2. Plan-Validierung | `PlanValidator.validate()` | §6; ungültig → REJECT, keine Ausführung |
|
||
| 3. WP-Anlage | A2 `MissionStore` | kein direkter SQL außerhalb A2-APIs |
|
||
| 4. Runnable-Selection | `select_runnable()` | §8; DONE-Deps + READY + Safety CLOSED + Scope erlaubt |
|
||
| 5. Consistency-Gate | `_consistency_gate()` | §9: A2-State + A3-Check vor JEDER Mutation |
|
||
| 6. Risk-Klassifikation | `classify_risk()` | §26/27: RISK überschreibt SIZE |
|
||
| 7. Approval-Gate | `requires_approval()` | §25: CRITICAL/Approval-Target → APPROVAL_REQUIRED |
|
||
| 8. Dispatch | `build_maker_contract` / `build_checker_contract` | Minimum-Necessary-Context |
|
||
| 9. Safety-Decision | A3 `evaluate_next_action` | verbindlich |
|
||
| 10. Repair-Flow | RETRY max 3 / gleiche Error-Sig max 2 | SAFETY_CONTRACT |
|
||
| 11. Circuit-Enforcement | Circuit OPEN → NO MUTATION | §19 |
|
||
| 12. Completion-Gate | `mission_completion_gate()` | §20 + Final-Review-Gate |
|
||
| 13. Bounded-Run | `run_bounded()` | §22: endet garantiert |
|
||
|
||
---
|
||
|
||
## A2/A3-Integration
|
||
|
||
A4 **importiert** und nutzt die bestehenden Module (kein Duplikat):
|
||
|
||
```python
|
||
from a2.rq_mission import MissionStore # autoritativ für Mission-/WP-Transitions
|
||
from a3.rq_safety import SafetyStore # verbindliche Safety-Decision
|
||
```
|
||
|
||
- A2 (`missions.db`) ist die **autoritative Quelle** für Mission-/WP-State und
|
||
erlaubte Transitionen.
|
||
- A3 (`safety.db`) ist die **verbindliche Safety-Decision** (`evaluate_next_action`,
|
||
`check_safety_state`, `record_attempt`, `open_circuit`).
|
||
- A4 selbst hält **keine neue zentrale DB**; Run-Flags/Sub-Agent-Evidence werden
|
||
über A2/A3-APIs bzw. den A3-Safety-Evidence-Mechanismus persistiert.
|
||
- Import-Lösung: `sys.path` wird um Repo-Root und `a4/` ergänzt
|
||
(`Path(__file__).resolve().parent.parent`).
|
||
|
||
---
|
||
|
||
## Planner/Maker/Checker-Contract
|
||
|
||
| Rolle | Output | Gate |
|
||
|-------|--------|------|
|
||
| **Planner** | WORK_PACKAGES / DEPENDENCIES / RISK_CLASS / ORDER / TEST_REQUIREMENTS | Red Queen validiert deterministisch (§6) |
|
||
| **Maker** | IMPLEMENTATION_SUMMARY / FILES_CHANGED / TESTS_RUN / TEST_RESULTS | Nie final PASS |
|
||
| **Checker** | PASS / FAIL / Verdict | **FRESH** Child, ohne Maker-Argumentation |
|
||
|
||
`build_maker_contract` und `build_checker_contract` erzeugen die
|
||
**Minimum-Necessary-Context**-Contracts. Der Checker-Contract enthält bewusst
|
||
**keine** Maker-Rechtfertigung (AGENT_CONTRACTS §3). Werte werden secret-redacted.
|
||
|
||
---
|
||
|
||
## Bounded Run (Limits aus Konstanten)
|
||
|
||
```python
|
||
MAX_WORK_PACKAGES_PER_RUN = 12
|
||
MAX_REPAIR_CYCLES = 3 # entspricht A3 MAX_MAKER_CHECKER_REPAIRS
|
||
MAX_CHILDREN_ACTIVE = 3
|
||
MAX_BOUNDED_RUNTIME = 1000 # Sekunden / Steps
|
||
```
|
||
|
||
`run_one_step()` führt **GENAU EINEN** deterministischen Schritt aus und endet
|
||
**garantiert** (keine Rekursion). `run_bounded()` stoppt bei
|
||
`MISSION_COMPLETED / BLOCKED / ESCALATED / CIRCUIT_OPEN / NO_RUNNABLE_WP /
|
||
RUN_BUDGET_REACHED / ERROR` — kein self-reschedule.
|
||
|
||
---
|
||
|
||
## Approval Gates
|
||
|
||
WP, die laut `ROOT_SSH_GATE` einen **kritischen Bereich** berühren (SSH, Firewall,
|
||
Auth, Secrets, Recovery, Red Queen Runtime, Circuit Breaker, Root Policy, Live
|
||
Trading) → `ST_APPROVAL_REQUIRED`, **keine Ausführung**. Red Queen legt den Antrag
|
||
im `EXTERNAL_REVIEW`-Format vor und wartet auf Christian.
|
||
|
||
---
|
||
|
||
## Failure Handling / Idempotenz
|
||
|
||
- **Failure:** `evaluate_next_action`-Decision wird verbindlich befolgt
|
||
(RETRY / DEBUG / SECOND_OPINION / BLOCK / CIRCUIT_BREAK). Repair max 3, gleiche
|
||
Error-Signatur max 2. Kein implizit PASS, kein endlos Spawn.
|
||
- **SECOND_OPINION → KEIN automatisches Rain** (nur interner frischer Child oder
|
||
BLOCK; Rain ausschließlich Christian-gated, EXTERNAL_REVIEW_CONTRACT).
|
||
- **Idempotenz:** DONE-WP wird nie erneut Maker; bereits registrierter Attempt
|
||
nicht doppelt; COMPLETED-Mission nie erneut; gleiche Child-Task-ID nie doppelt
|
||
gewertet.
|
||
- **Restart:** State in A2/A3-DBs persistent; nach Restart wird der Zustand gelesen,
|
||
ohne doppelte WP-Ausführung oder verlorene Attempts.
|
||
|
||
---
|
||
|
||
## Sub-Agent-Evidence (§30)
|
||
|
||
`make_child_evidence()` erzeugt einen maschinenlesbaren Evidence-Record
|
||
(Child Role, Child Task ID, Mission ID, WP ID, Start, Result, Verdict) —
|
||
**KEINE Chain-of-Thought**. Credentials werden redactiert (nur EXISTS/LENGTH/redacted).
|
||
|
||
---
|
||
|
||
## CLI
|
||
|
||
`rq_orchestrator_cli.py` — `--json`, Exit-Code 2 bei `OrchestratorError` (A2/A3-Muster):
|
||
|
||
```
|
||
plan Plan validieren + WP-Anlage
|
||
run-one-step Einen deterministischen Schritt ausführen
|
||
run-bounded Begrenzter Run (endet garantiert)
|
||
complete Completion-Gate prüfen / Final-Review
|
||
status Status abfragen
|
||
evaluate A3-Safety-Decision
|
||
approve Approval registrieren
|
||
```
|
||
|
||
---
|
||
|
||
## Test Harness
|
||
|
||
`python3 a4/test_a4.py` — isolierte, deterministische Tests (temp-DBs, kein Netz,
|
||
kein hermes). Injiziert simulierte `ChildDispatcher`. Exit-Code 0 = PASS.
|
||
Deckt A4 §6–§33 ab: Plan-/Dependency-Validierung, Runnable-Selection, A2/A3-
|
||
Consistency-Gate, Maker/Checker-Contract, Checker-Pass/Fail, Retry allowed/denied,
|
||
Retry-4-Impossible, Circuit-open-blocks-Maker, Approval-Gate, Risk-overrides-Size,
|
||
No-Runnable-Stop, Completion-/Final-Review-Gate, Idempotent-WP, Restart-Resume,
|
||
Child-Failure, Reason-Codes, Secret-safe-Logging.
|
||
|
||
---
|
||
|
||
## Known Limitations
|
||
|
||
- A4 selbst führt **keine** echte `delegate_task` aus (das macht Red Queen).
|
||
- Kein automatisches Rain; kein Heartbeat/Cron/Daemon.
|
||
- DEBUG ist als Schnittpunkt implementiert (leitet an A5-Debugger/Strategiewechsel
|
||
weiter), erzwingt aber keine interne Debugger-Logik.
|