# 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.