========================================
RICKBRAIN PROJECT COMPENDIUM
Generated: 2026-04-26
========================================


========================================
FILE: 00-MOC-Trading-System.md
========================================
---
aliases: [Trading-System, Hybrid AI-Trading System, SuperBrain]
tags: [moc, system, architecture]
related: [[10-MOC-Blackboxen]], [[11-MOC-Schnittstellen]], [[13-MOC-Agenten]], [[01-system-architektur]]
trust: canonical
last_reviewed: 2026-04-19
---
# 00. Map of Content: Trading-System

Dies ist der zentrale Einstiegspunkt (Hub) für das Hybrid AI-Trading System.

## Architektur & Kern-Design
- [[01-system-architektur|System-Architektur & 3+1 Blackbox Design]]
- Konzept: [[two-repo-pattern|Two-Repo Pattern]] (Brain vs. Execution)

## Die Blackboxen (MOC)
- [[10-MOC-Blackboxen|MOC Blackboxen]] (Übersicht der 3+1 Boxen)

## Wichtige Konzepte
- [[07-memory-and-infra|07. The OS: Memory & Infrastructure]]
- [[07-memory-and-infra|Memory & Infrastruktur]]
- [[09-testing-strategie|Testing-Strategie]]

## Entwicklungsrichtlinien
- [[DECISIONS|Entscheidungs-Log (Veto & Richtung)]]
- [[PROJECT-BRAIN|Projekt Status & Übersicht]]
- [[DOC-SPEC|Doku-Spezifikation]]


========================================
FILE: CHAPTER-STATUS.md
========================================
# Kapitelstatus — Hybrid AI-Trading System

| Nr | Datei | Titel | Status | Zuletzt |
|---|---|---|---|---|
| 00 | docs/00-MOC-Trading-System.md | Map of Content (MOC) | ✅ Fertig | 2026-04-19 (C-6: MOC befüllt, SSOT-Verzeichnis) |
| 01 | docs/01-system-architektur.md | System-Architektur & 3+1 Blackbox Design | ✅ Fertig | 2026-04-19 (Audit: B-2 config_hash→Ref Kap.10, B-3 SUSPEND→Ref Kap.05) |
| 02 | docs/02-blackbox-data.md | Blackbox 1: Data Engine | ✅ Fertig | 2026-04-19 (Audit: A-3 OpenBB Graceful Degradation dokumentiert) |
| 03 | docs/03-blackbox-agents.md | Blackbox 2: The Scientist (Agenten) | ✅ Fertig | 2026-04-19 (Audit: A-1 COLD_START, C-3 2-Level Fusion, C-4 Promise Graphs→I/O-Vertrag, B-4 Double-Dip SSOT) |
| 04 | docs/04-blackbox-mt5.md | Blackbox 3: MT5 Execution Bridge | ✅ Fertig | 2026-04-19 (Audit: A-6 Broker-Kontowechsel, B-3/B-4 SSOT-Refs) |
| 05 | docs/05-schnittstellen.md | API & Schnittstellen-Spezifikation | ✅ Fertig | 2026-04-19 (Audit: A-2 ZMQ seq_id, A-1 COLD_START Ref, B-4 Double-Dip→Ref Kap.03) |
| 06 | docs/06-projekt-management.md | Meta-Ebene: Super Productivity | ⚠️ DEPRECATED | 2026-04-19 (C-5: Inhalt in Kap. 07 §12 integriert) |
| 07 | docs/07-memory-and-infra.md | The OS: Memory & Infrastructure | ✅ Fertig | 2026-04-19 (Audit: B-2 config_hash→Ref Kap.10, C-5 Kap.06-Merge als §12) |
| 08 | docs/08-backtesting-lab.md | The Improvement Lab (Box 4) | ✅ Fertig | 2026-04-19 (Audit: B-1 Doppelter Content Fix, C-1 ClickHouse→Parquet, C-2 gs-quant→QuantStats, A-4 Schema-Validation, B-6 Parquet Ferry→Ref) |
| 09 | docs/09-testing-strategie.md | V1 Testing-Strategie | ✅ Fertig | 2026-04-19 (G-08 CI/CD Runner-Trennung spezifiziert) |
| 10 | docs/10-configuration.md | Konfigurationsmanagement | ✅ Fertig | 2026-04-19 (Audit: B-5 Timeframe H4→M5 Bugfix) |
| 98 | docs/98-implementation-guide.md | Umsetzungsleitfaden — Von Architektur zu Code | ✅ Fertig | 2026-04-26 (Neu: Mock-Architektur, Autonomie-Matrix, Interface Contracts, Coding-Konventionen) |
| 99 | docs/99-deploy-runbook.md | Deploy-Runbook | ✅ Fertig | 2026-04-19 (Audit: A-5 Disaster Recovery Playbook mit RPO/RTO) |
| -- | AGENT-COOKBOOK.md | Agent Onboarding Guide | ✅ Fertig | 2026-04-19 (Neues Cookbook für Agenten-Onboarding) |
| -- | .clinerules/workflows/*.md | CLI Workflows | ✅ Fertig | 2026-04-19 (4 neue: /cookbook, /orient, /sprint, /audit) |
| -- | -- | SuperBrain-Transformation | ✅ Fertig | 2026-04-11 (MOCs, WikiLinks, Concepts abgeschlossen) |

## Legende
⬜ Offen  |  🔄 In Arbeit  |  ✅ Fertig  |  🔍 Im Review  |  ⚠️ DEPRECATED

========================================
FILE: IMPL-STATUS.md
========================================
# Implementation Status — Task Tracker

> **Maschinenlesbar.** Agenten lesen diese Datei, um Dependencies zu prüfen und die nächste offene Task zu finden.
> Supervisor setzt PENDING_REVIEW Tasks auf APPROVED oder REJECTED.

## Legende

| Status | Bedeutung |
|--------|-----------|
| ⬜ OPEN | Noch nicht begonnen |
| 🔄 IN_PROGRESS | Agent arbeitet daran |
| 🔍 PENDING_REVIEW | Code fertig, wartet auf Supervisor-Review |
| ✅ APPROVED | Supervisor hat reviewed und approved |
| ❌ REJECTED | Supervisor hat rejected — Grund steht in der Notiz |
| ⚠️ BLOCKED | Agent steckt fest — Supervisor-Input nötig |

---

## Phase 0: Foundation

| Task | Beschreibung | Status | Agent | Review |
|------|-------------|--------|-------|--------|
| 0.1 | `shared/config_hash.py` — SHA-256 | ⬜ OPEN | — | — |
| 0.2 | `shared/logging_setup.py` — structlog Config | ⬜ OPEN | — | — |
| 0.3 | `compliance.yaml` + `thresholds.json` (Referenzwerte) | ⬜ OPEN | — | — |
| 0.4 | Pydantic Schemas: ComplianceConfig, AgentThresholds | ⬜ OPEN | — | — |
| 0.5 | `shared/contracts/*.py` — Alle Interface Contracts | ⬜ OPEN | — | — |
| 0.6 | `tests/mocks/mock_mt5.py` — MockMT5 Client | ⬜ OPEN | — | — |
| 0.7 | `tests/mocks/mock_zmq.py` — MockZMQ PUB/SUB | ⬜ OPEN | — | — |
| 0.8 | `tests/mocks/mock_smtp.py` — MockSMTP | ⬜ OPEN | — | — |
| 0.9 | `pyproject.toml` + `requirements.txt` (beide Repos) | ⬜ OPEN | — | — |

## Phase 1: Box 3 — MT5 Execution Bridge

| Task | Beschreibung | Status | Agent | Review |
|------|-------------|--------|-------|--------|
| 1.1 | `bridge/app.py` — FastAPI Skeleton + uvicorn | ⬜ OPEN | — | — |
| 1.2 | `bridge/models.py` — Pydantic Request/Response | ⬜ OPEN | — | — |
| 1.3 | `bridge/middleware.py` — Rate-Limit + Config-Hash Check | ⬜ OPEN | — | — |
| 1.4 | `risk/risk_dictator.py` — Volume, Spread, Stop-Level | ⬜ OPEN | — | — |
| 1.5 | `risk/floating_dd.py` — Floating DD Killswitch | ⬜ OPEN | — | — |
| 1.6 | `risk/compliance.py` — PF-01 bis PF-06 | ⬜ OPEN | — | — |
| 1.7 | `risk/cooldown.py` — Anti-Revenge Timer | ⬜ OPEN | — | — |
| 1.8 | `execution/mt5_wrapper.py` — Thread-safe Lock | ⬜ OPEN | — | — |
| 1.9 | `execution/order_manager.py` — order_send + Reconciliation | ⬜ OPEN | — | — |
| 1.10 | `execution/trade_lifecycle.py` — State Machine (0/1) | ⬜ OPEN | — | — |
| 1.11 | `watchdog/heartbeat.py` — Ping-Handler + Position-Report | ⬜ OPEN | — | — |
| 1.12 | `watchdog/suspend.py` — SUSPEND Mode Logic | ⬜ OPEN | — | — |
| 1.13 | `watchdog/safe_mode.py` — Autonomous Panic Liquidation | ⬜ OPEN | — | — |
| 1.14 | `watchdog/shutdown.py` — 3-Step Graceful Shutdown | ⬜ OPEN | — | — |
| 1.15 | `alerting/smtp_alerts.py` — SMTP E-Mail | ⬜ OPEN | — | — |
| 1.16 | `ipc/global_vars.py` — GlobalVariable Wrapper | ⬜ OPEN | — | — |

## Phase 2: Box 1 — Data Engine

| Task | Beschreibung | Status | Agent | Review |
|------|-------------|--------|-------|--------|
| 2.1 | `data_pull/mt5_fetcher.py` — copy_rates_from, Multi-TF | ⬜ OPEN | — | — |
| 2.2 | `data_pull/health_checks.py` — Lücken, Anomalien | ⬜ OPEN | — | — |
| 2.3 | `features/engineering.py` — 15 Features | ⬜ OPEN | — | — |
| 2.4 | `features/normalization.py` — Z-Score | ⬜ OPEN | — | — |
| 2.5 | `streaming/zmq_publisher.py` — ZMQ PUB | ⬜ OPEN | — | — |
| 2.6 | `streaming/payload.py` — Payload-Wrapping | ⬜ OPEN | — | — |
| 2.7 | `ferry/parquet_writer.py` — Atomic Staging | ⬜ OPEN | — | — |
| 2.8 | `ferry/ferry_daemon.py` — rsync an Box 4 | ⬜ OPEN | — | — |

## Phase 3: Box 2 — The Scientist

| Task | Beschreibung | Status | Agent | Review |
|------|-------------|--------|-------|--------|
| 3.1 | `receiver/zmq_subscriber.py` — ZMQ SUB + asyncio.Queue | ⬜ OPEN | — | — |
| 3.2 | `receiver/seq_validator.py` — seq_id Prüfung | ⬜ OPEN | — | — |
| 3.3 | `receiver/staleness.py` — Staleness Monitor | ⬜ OPEN | — | — |
| 3.4 | `analysis/entropy.py` — Von-Neumann Entropie | ⬜ OPEN | — | — |
| 3.5 | `analysis/gatekeeper.py` — 2-Trigger Wake-Up | ⬜ OPEN | — | — |
| 3.6 | `analysis/regime.py` — SJM/HMM Regime Detection | ⬜ OPEN | — | — |
| 3.7 | `analysis/decision_matrix.py` — State Resolution | ⬜ OPEN | — | — |
| 3.8 | `orchestration/agent_modes.py` — COLD_START, Scout, Manager | ⬜ OPEN | — | — |
| 3.9 | `orchestration/fusion.py` — 2-Level Fusion | ⬜ OPEN | — | — |
| 3.10 | `orchestration/double_dip.py` — Double-Dip Prevention | ⬜ OPEN | — | — |
| 3.11 | `output/signal_client.py` — REST POST /signal | ⬜ OPEN | — | — |
| 3.12 | `output/heartbeat_client.py` — REST POST /ping | ⬜ OPEN | — | — |
| 3.13 | `output/cooldown.py` — 429 Handling | ⬜ OPEN | — | — |
| 3.14 | `context/openbb_provider.py` — OpenBB Polling | ⬜ OPEN | — | — |
| 3.15 | `context/degradation.py` — Graceful Degradation | ⬜ OPEN | — | — |

## Phase 4: Integration & E2E

| Task | Beschreibung | Status | Agent | Review |
|------|-------------|--------|-------|--------|
| 4.1 | DRY_RUN Modus (Box 1 → Parquet, Box 3 → Mock) | ⬜ OPEN | — | — |
| 4.2 | E2E Pipeline: Tick → Agent → Signal → Mock-MT5 | ⬜ OPEN | — | — |
| 4.3 | Config-Hash Sync Test (beide Seiten) | ⬜ OPEN | — | — |
| 4.4 | Chaos Test: VPN-Drop → SUSPEND → Reconnect | ⬜ OPEN | — | — |
| 4.5 | Chaos Test: MT5 Restart → WAITING_FOR_SYNC | ⬜ OPEN | — | — |
| 4.6 | Chaos Test: Panic Timeout → Hard Close | ⬜ OPEN | — | — |
| 4.7 | Rollback-Test: Defekter Commit → Auto-Revert | ⬜ OPEN | — | — |
| 4.8 | Promtail + Loki Setup (Box 4) | ⬜ OPEN | — | — |

## Phase 6: Box 4 — Lab (parallel ab Phase 2)

| Task | Beschreibung | Status | Agent | Review |
|------|-------------|--------|-------|--------|
| 6.1 | `ingestion/parquet_receiver.py` — Empfang + Rename | ⬜ OPEN | — | — |
| 6.2 | `ingestion/schema_validator.py` — Pandera | ⬜ OPEN | — | — |
| 6.3 | `backtesting/runner.py` — numpy/ffn Pipeline | ⬜ OPEN | — | — |
| 6.4 | `backtesting/walk_forward.py` — Walk-Forward | ⬜ OPEN | — | — |
| 6.5 | `tracking/mlflow_setup.py` — MLflow SQLite | ⬜ OPEN | — | — |
| 6.6 | `promotion/promote_model.py` — Staging → Prod | ⬜ OPEN | — | — |

---

*Zuletzt aktualisiert: 2026-04-26*


========================================
FILE: PROJECT-BRAIN.md
========================================
---
aliases: []
tags: []
related: [[00-MOC-Trading-System]]
trust: canonical
last_reviewed: 2026-04-19
---
# PROJECT-BRAIN — Hybrid AI-Trading System (3-Blackbox)

## Projekt auf einen Blick
Das Projekt ist eine Weiterentwicklung der MASTER_SPEC_V2 und zielt auf ein voll modulares, agentenbasiertes Tradingsystem ab. Das System ist in drei voneinander isolierte "Blackboxen" unterteilt: (1) Datenbeschaffung (fin data), (2) Agenten-Netzwerk zur Analyse und State-Generierung, und (3) Risikogemanagte Ausführung im MT5. 
Wir gehen beim Umfang sehr tief ins Detail. Die Erkenntnisse werden aus umfassenden Chatverläufen extrahiert.

## Zielgruppe
Das Dokument dient als **Architektur- und Entwicklungs-Referenz**. Es richtet sich primär an Entwickler und Systemarchitekten.

## Ziel des Dokuments
Das Dokument ist die "Single Source of Truth", um Projektwissen aus diversen Chatverläufen zu optimieren, zu bündeln und Architektur-Wildwuchs ("lose Fäden") insbesondere an den Schnittstellen zu verhindern.

## Wichtige Unveränderliche Fakten (Immutable Facts)
Diese Parameter bilden die harte Grenze des Systems und überschreiben alle anderen architektonischen Annahmen:
- **Trading-Stil:** Swing Trading.
- **Trade-Dauer (Hold Time):** ca. 2 Stunden bis 2 Wochen.
- **Latenz-Anforderung:** 3 bis 5 Minuten für den gesamten Prozess (Ticks → Feature Engineering → Agent Analysis → State Generation) sind völlig ausreichend. High-Frequency Trading (HFT) Metriken wie PCIe-Bandbreiten-Optimierung oder Millisekunden-Latenz sind *nicht* relevant. Qualität der Signal-Entscheidung schlägt pure Rechengeschwindigkeit.

## Wichtige Entscheidungen
- [2026-04-06]: Cline wird als primärer Doku-Agent eingesetzt (ersetzt Gemini 3.1 Pro / Antigravity native Regeln). Vollständige Integration des PULL-PROCESS-PUSH Workflows via CLINE.md.
- [2026-04-11]: Schnittstellen-Härtung (Box 1 ↔ Box 2): `msgpack_numpy` anstelle von `pickle` aus Sicherheitsgründen spezifiziert. ZMQ High-Water-Marks und Error Handling Taxonomie etabliert.
- [2026-04-12]: **Sprint 5 abgeschlossen:** Kap. 07 (Infra & Security) vollständig erweitert — Tailscale VPN ACL, VPS Hardening (UFW/Fail2ban), OpenClaw YAML-Config-Skelett, Context/Evidence Gates als Python-Skripte, Two-Repo Deployment Pipeline mit Config-Hash.
- [2026-04-12]: **Sprint 6 abgeschlossen:** Kap. 08 (Improvement Lab) erweitert — Lab-Projektstruktur, Backtesting-Framework (VectorBT/Backtrader), Walk-Forward-Validation, Model Promotion CLI mit Evidence Gate.
- [2026-04-12]: **BMAD-002 Fix:** 5 fatale Architektur-Logikfehler (Hot-Path Blindspots) behoben. Implementierung von Sequence-Numbers (statt NTP), Graceful Degradation für OpenBB, Atomic Renames für Parquet Transfers, MQL5 Wake-up Logic und einem konfigurierbaren Autonomous Safe Mode (Panic Liquidation).
- [2026-04-12]: **Sprint 7 abgeschlossen:** Kap. 01 (Architektur) bereinigt — Phantom-Tools Tabelle (7 verworfene Konzepte dokumentiert), Schnittstellen-Matrix ergänzt, Validation Layer um Config-Hash erweitert.
- [2026-04-12]: **BMAD-001 Fix:** ZMQ↔REST Widerspruch in Kap. 10 §10.3 korrigiert. `config_hash` wird als JSON-Feld im REST-Payload (`POST /api/v1/signal`) übertragen — ZMQ gilt ausschließlich für Box 1→Box 2 (Kap. 05 §1). Siehe `DECISIONS.md`.
- [2026-04-12]: **Sprint 2 abgeschlossen:** PF-04 (Minimum Trading Days Counter) und PF-06 (Weekend Holding Rules) in Kap. 04 §7 ergänzt. Alle 10 Kapitel jetzt ✅ Fertig.
- [2026-04-12]: **Ref-Cleanup abgeschlossen:** `agent-orchestration.md` (CrewAI) via `INDEX.md` als deprecated markiert. Neue Refs für OpenBB und Prop-Firm-Rules (`prop-firm-compliance.md`) angelegt.
- [2026-04-12]: **Multi-Agent Koordination:** Abschnitt 9 in CLINE.md etabliert. Strikte Privilegien-Trennung: Nur der Supervisor-Agent (cline-local) darf Core-State-Dateien modifizieren, um Schreibkonflikte zu verhindern.
- [2026-04-12]: **Logic & Optimization Audit (Session):** Vollständiger Cross-Chapter-Audit aller 10 Kapitel + Runbook durchgeführt. 20 Findings (F-01..F-20) identifiziert und durch den User abgeschlossen. Alle Widersprüche (ACL, Cron, Hash-Algo, OpenBB-Lokation, GPU-Phantom, API-Pfad, Typos) sind behoben.
- [2026-04-12]: **SOTA Deep Audit (Session):** Architektur gegen 2026-SOTA Patterns bewertet. Ergebnis: 82% SOTA-konform, 67% produktionsreif. 12 neue Gaps (G-01..G-12) identifiziert — darunter 3 kritische (Observability/Structured Logging, SOPS Secrets, Broker-Time). Alle Gaps im Kanban eingetragen.
- [2026-04-12]: **G-05 abgeschlossen:** Rollback-Mechanismus für Brain (Linux `health_check.py` + `deploy_brain.sh`) und Muscle (Windows `Deploy-Muscle.ps1`) in Kap. 99 §8 spezifiziert. Cooldown-Guard (15min Lockfile), SMTP-Alerts und Entscheidungsmatrix für 5 Eskalations-Szenarien definiert.
- [2026-04-12]: **G-04 abgeschlossen:** Pydantic v2 BaseSettings Schema für `compliance.yaml` (Box 3, alle PF-01..PF-06 Regeln) und `thresholds.json` (Box 2, Entropie/Hysterese/Timeframes) in Kap. 10 §10.5 spezifiziert. Startup-Fail-Fast Sequenz und gemeinsame `compute_config_hash()` Funktion definiert.
- [2026-04-12]: **SOTA Gaps G-01, G-02, G-03 abgeschlossen:** Kritische Ops-Lücken geschlossen. Structured Logging inkl. `trace_id` (Kap. 05/07), Secrets Management via SOPS/age (Kap. 07/99) und Broker-Server-Time Reset (Kap. 04/10) sind nun vollumfänglich spezifiziert. Das System ist bereit für die Code-Phase.
- [2026-04-19]: **Sprint G (Architecture Hardening) abgeschlossen:** Vollständige Härtung der Pipeline mit G-06 bis G-12. Implementierung des `MLflow` Trackers im Lab V1, Deep-Check `/health` Endpoint mit rigorosem MT5-Locking, Spezifikation von physisch getrennten CI/CD Runnern mit Production-Veto, Circuit-Breaker FastAPI Rate-Limiting + Alerting Hub, 3-Step Graceful Shutdown Logik, nativen OS Log-Rotationsstrategien und isoliertem `Grafana Loki + Promtail` Monitoring ohne Prometheus Overengineering. Das System ist zu 100% "Implementation Ready".
- [2026-04-19]: **Sprint I (Docs Audit & Refactoring) abgeschlossen:** 20 Changes über 10 Dateien. 3 Bugs gefixt (B-1 Duplikat, B-5 Timeframe, C-6 leere MOC). 6 Architektur-Lücken geschlossen (A-1 COLD_START, A-2 ZMQ seq_id, A-3 OpenBB Degradation, A-4 Parquet Schema-Validation, A-5 Disaster Recovery mit RPO/RTO, A-6 Broker-Wechsel). 5 Redundanzen konsolidiert (config_hash, SUSPEND, Double-Dip, Parquet Ferry — jeweils auf SSOT-Refs). 5 Vereinfachungen (ClickHouse→Parquet, gs-quant→QuantStats, 3-Level→2-Level Fusion, Promise Graphs entfernt, Kap. 06 in Kap. 07 §12 integriert). MOC befüllt mit SSOT-Verzeichnis.
- [2026-04-06]: Perplexity MCP aktiv und funktional — wird für Recherche (Trading-Papers, API-Dokus, [[prop-firm-compliance|Prop-Firm]]-Regeln) eingesetzt.
- [2026-04-05]: Projekt initialisiert.
- [2026-04-05]: Architektur-Festlegung auf 3 entkoppelte Blackboxen (Data, Agents, MT5).
- [2026-04-05]: Konzept der "kurzen Chatverläufe" etabliert -> Agenten müssen sich bei neuem Chat selbstständig via `PROJECT-BRAIN.md` synchronisieren.
- [2026-04-05]: **Entropie-Definition fixiert ([[entropy-inversion|Entropy Inversion Hypothesis]], Arella):** Hohe Entropie = Stabil/Gesund/Gefaltet → Trading **erlaubt** (Meinungsvielfalt, orthogonale Indikatoren). Niedrige Entropie = Kollaps/Entfaltet → Trading **verboten** (Panik, Herdenverhalten). → Ref: `refs/papers/market-folding.md`
- [2026-04-05]: **Super Productivity 18.0 Setup:** Wird als isolierte "Shadow-CTO" / Execution-Console-Meta-Ebene gehandhabt und in Kapitel 06 definiert, um Agentenkontrolle logisch vom Trading-Bot-Loop zu trennen.
- [2026-04-05]: **Infrastruktur-Entscheidung:** Exklusiver OpenClaw + GitHub Stack auf Hetzner VPS. Striktes deterministisches Gedächtnis via `decisions.md`. Verzicht auf Vektor-Datenbanken (z.B. OpenFang) zur Vermeidung von "[[context-gate|Context Poisoning]]".
- [2026-04-05]: **Software/Tool-Synergie (Powerhouse):** Konkretes Tool-Mapping auf das 3-Blackbox System zur Reduzierung von Eigenentwicklungen. Nutzung von *Superalgos* (Quantitative Präzision, Box 1/2), *OpenClaw* (Logik-Synthese/MCP, Box 2) und *CUA* (Physische GUI-Ausführung als Fallback für fehlende APIs in Box 3).
- [2026-04-05]: **QuantConnect/VectorBT entfernt.** Direkte Python↔MT5 Bridge bleibt Kernarchitektur. Backtesting-Modul wird separat und zu einem späteren Zeitpunkt ergänzt.
- [2026-04-05]: **Referenz-System (`refs/`) eingeführt.** Tiefes Detailwissen (Papers, Patterns, Tools) wird aus den Kapiteln ausgelagert und über `refs/INDEX.md` referenziert.
- [2026-04-05]: **`DECISIONS.md` als 4. Pflichtdatei** im PULL-PROCESS-PUSH Zyklus etabliert. Strukturiertes Veto-Log für menschliche Korrekturen.
- [2026-04-05]: **Agent Composition Model (Kiebitz-Extraktion)**: Festlegung auf modulare "Regime-Klassifizierer" (Agents), Configuration-driven "Dynamic Phases" mit Threshold-Hysterese und strengem Event-Sourced Audit Trail anstatt starr codierter "Scout->Sniper" Phasen. Alter Kiebitz Tech-Stack (Firebase) abgelehnt.
- [2026-04-05]: **[[prop-firm-compliance|Prop-Firm]] Compliance & Gatekeeper**: Box 2 schaltet sich nur über ein ressourcenschonendes 2-Stufen-Modell (Gatekeeper) ein. Box 3 bekommt einen [[capital-allocator|Capital Allocator]] (Confidence basiert) und einen tick_überwachten Floating Equity Killswitch (Risk-Diktator), um starre [[prop-firm-compliance|Prop-Firm]] DD-Regeln einzuhalten.
- [2026-04-05]: **RL-Training & Temporal Graphs**: Trainingszyklen für Proximal Policy Optimization (PPO) des Meta-Agents (Allocator) und GATs (Graph Attention Networks) für Entropie-Berechnung werden architektonisch explizit in Box 4 (The Improvement Lab) verbannt. Die Live-Systeme werten nur vortrainierte Modelle aus.
- [2026-04-05]: **State & CPU Optimierung**: Blackbox 2 sendet nur noch States (0, 1), wobei 0 einen "Tight Trailing Mode" auslöst. Vollständige Auslegung auf CPU-Berechnungen (NumPy), da keine GPU auf dem Linux-VPS vorhanden ist.

## Offene Fragen
- **(keine)** — Die umfassende Architektur-Härtung (Sprint-Fixes F-01 bis F-18) ist vollumfänglich abgeschlossen. Alle verbliebenen "Happy Path"-Lücken der Schnittstellen (ZMQ, SMTP-Alerts) und Infrastruktur-Grenzen (CPU-only, Tailscale VPN) wurden detailliert spezifiziert und in den Kern-Kapiteln sowie der `DECISIONS.md` fixiert. Das Projekt ist nun offiziell **Implementation Ready**.

## Terminologie / Konventionen
Siehe DOC-SPEC.md → Glossar


========================================
FILE: DECISIONS.md
========================================
---
aliases: []
tags: []
related: [[00-MOC-Trading-System]]
trust: canonical
last_reviewed: 2026-04-19
---
# DECISIONS — Hybrid AI-Trading System

*Strukturiertes Veto- und Richtungslog. Jede Korrektur, Ablehnung oder Kursänderung durch den menschlichen Supervisor wird hier dauerhaft protokolliert. Diese Datei wird bei jedem Session-Start geladen (PULL-Pflicht).*

## Legende
| Typ | Bedeutung |
|---|---|
| `VETO` | Ablehnung eines Vorschlags oder einer Richtung |
| `RICHTUNG` | Strategische Weichenstellung |
| `FIX` | Korrektur eines Fehlers oder Widerspruchs |
| `SCOPE` | Umfangsbegrenzung oder Verschiebung |

## Log

| Datum | Typ | Entscheidung | Begründung |
|---|---|---|---|
| 2026-04-05 | `RICHTUNG` | Exklusiver OpenClaw + GitHub Stack. Kein OpenFang, keine Vektor-DBs. | Vermeidung von "[[context-gate|Context Poisoning]]" durch fremde Frameworks. Deterministisches Gedächtnis via Git. |
| 2026-04-05 | `FIX` | Entropie-Definition auf **[[entropy-inversion|Entropy Inversion Hypothesis]]** (Arella) fixiert: H↑ = Stabil/Gesund → Go. H↓ = Kollaps/Panik → No-Go. | MASTER_SPEC_V2 ist die korrekte Quelle. Vorherige Definition in PROJECT-BRAIN war invertiert. |
| 2026-04-05 | `SCOPE` | QuantConnect/VectorBT entfernt. Direkte Python↔MT5 Bridge bleibt. Backtesting-Modul wird separat und später ergänzt. | Fokus auf Kern-Pipeline. Kein Tool-Bloat. |
| 2026-04-05 | `RICHTUNG` | Referenz-System (`refs/`) eingeführt. Tiefes Detailwissen wird aus den Kapiteln ausgelagert und referenziert. | Verhindert Aufblähen der Kern-Dokumentation. |
| 2026-04-05 | `RICHTUNG` | `DECISIONS.md` als 4. Pflichtdatei im PULL-PROCESS-PUSH Zyklus etabliert. | Agenten müssen vor jeder Aktion auch das Veto-Log lesen. |
| 2026-04-05 | `RICHTUNG` | Transition zum **Action Model** (Gemini 3). Fokus auf On-Demand Skills statt monolithischem Kontext. | Vermeidung von "Tool Bloat" und Maximierung der Token-Effizienz. |
| 2026-04-05 | `FIX` | QuantConnect Veto bekräftigt. Direkte Python↔MT5 Bridge ist gesetzt. | Trotz PDF-Empfehlungen: Latenz- und Lokale-Kontroll-Priorität. |
| 2026-04-05 | `RICHTUNG` | Performance First: Pinned Memory & CUDA Streams für Box 1/2. | Vermeidung von GPU Starvation bei 2026-Niveau AI-Workloads (NVIDIA Nsight). |
| 2026-04-05 | `SCOPE` | **Live vs. Lab Split:** `ffn`, `gs-quant` und historische Analysen komplett aus Box 2 verbannt. | Box 2 ist purer *Live-Execution Hot-Path* (Millisekunden). Alles Historische gehört in das zukünftige *Backtesting/Improvement Lab (Box 4)*. |
| 2026-04-05 | `RICHTUNG` | **Agent Composition Model adaptiert:** Das modulare Agenten-System (Thresholds, Event-Sourcing, dynamische Phasen) wird in Box 2 integriert. Alter Kiebitz-Fokus (insb. Firebase/React-Web-Overhead) wird nicht weiter verfolgt, Priorität liegt auf dem aktuellen Design. **FastAPI bleibt jedoch essenzieller Bestandteil der MT5-Bridge**. | Konzepte überlegen starr codierten Phasen. Zu viel Web-Overhead würde das OpenClaw-Setup destabilisieren, FastAPI allein ist aber als performanter lokaler Daemon gesetzt. |
| 2026-04-05 | `RICHTUNG` | **Infrastruktur-Split "Brain vs Muscle":** Box 1 & Box 3 laufen physisch auf einem Windows Server (Aufgrund MT5 Python Library Zwang). Box 2 & Box 4 laufen auf dem Hetzner Linux VPS. Kommunikation via Tailscale VPN. | Löst den logischen Widerspruch der MT5-Bibliothek unter Linux. Minimiert Latenz der Validation Middleware am Order-Terminal. |
| 2026-04-05 | `FIX` | **[[parquet-ferry|Parquet Ferry]] (Historic Data Push):** Box 1 übernimmt nativ (`windows`) den MT5 Data Pull historischer Ticks und pusht parquets asynchron an Box 4 (`linux`), da Box 4 aufgrund des Betriebssystems keinen MT5 Zugriff hat. | Behebt den logischen Architektur-Bruch. Linux darf keine MT5-Bibliothek benötigen. |
| 2026-04-05 | `RICHTUNG` | **Watchdog [[graceful-degradation|Graceful Degradation]]:** Abschaffung des harschen "Dead Man's Switch" (Kill All Positions). Das System setzt in Zukunft voll auf *Broker-Side Stop-Loss* (Schicht 1) und blockiert als Watchdog-Reaktion (Schicht 2) `SUSPEND` nur noch Pending Orders und Neu-Trades. | Ein Ping-Verlust (z.B. VPN-Zucken) führt nicht mehr zur Panik-Liquidierung laufender, durch SL geschützter Swing-Trades (Vermeidung von Spread-Kosten). |
| 2026-04-05 | `SCOPE` | **State `-1` (Short) entfernt:** Das System handelt in V1 ausschließlich Long. Erwartete States sind strikt `{0, 1}`. | Reduziert Komplexität der Doku und initialen Entwicklungszeit erheblich (E-01). |
| 2026-04-05 | `RICHTUNG` | **Multi-Timeframe:** State-Berechnung basiert auf mehreren Timeframes (zwei bis drei definieren), nicht auf einem einzelnen fixen. | Präzisere Markteinschätzung (E-02). |
| 2026-04-05 | `SCOPE` | **Asset-Universum MVP:** Initialer Fokus auf Bitcoin (und ggf. eine ausgewählte Aktie) als Test-Setup. Die Architektur muss jedoch zwingend für das gesamte MT5/FTMO-Universum voll skalierbar gebaut werden. | MVP-Ansatz zur schnellen Evaluation ohne architektonische Einbahnstraße zu bauen (E-03). |
| 2026-04-05 | `FIX` | **Hardware-Limitierung (CPU-only):** Keine dedizierte GPU auf dem Linux VPS vorhanden. Vorherige Entscheidungen zu CUDA Streams / Pinned Memory sind hiermit obsolet. | Faktische Hardware-Gegebenheit. Doku wird vollständig auf CPU-Optimierung (NumPy, Paralleles Processing) umgeschrieben (E-04). |
| 2026-04-05 | `SCOPE` | **Account-Typ:** Hedging, aber zwingend uni-direktional. | Erlaubt Staffelung des gleichen Assets, vermeidet aber [[prop-firm-compliance|Prop-Firm]] Pönalen durch gleichzeitiges Long/Short. (Da V1 ohnehin nur Long macht, ist dies automatisch erfüllt) (E-05). |
| 2026-04-05 | `RICHTUNG` | **MT5 EA Design:** Ein einziger "Master Watchdog EA" (Chart-unabhängig) überwacht das globale Portfolio-Risiko. | Minimiert Fehlerquellen und Ressourcen, da Python via `MetaTrader5` API die konkreten Assets bereits chart-less bedient (E-06). |
| 2026-04-05 | `RICHTUNG` | **Python↔MQL5 IPC:** Kommunikation reduziert auf reines [[heartbeat-protocol|Heartbeat-Protokoll]] via `GlobalVariableSet()` im MT5-Speicher. | Extrem schnell, erfordert keine unsicheren DLLs. Genialer Nebeneffekt: Ein Terminal-Crash löscht den [[heartbeat-protocol|Heartbeat]]-Speicher → Automatischer SUSPEND beim Neustart (E-07). |
| 2026-04-05 | `RICHTUNG` | **[[prop-firm-compliance|Prop-Firm]] Compliance:** Generisches, konfigurierbares Regelwerk (JSON/YAML Configs für Static/Trailing DD, News, Hold-Times) anstelle von starr codierter FTMO-Logik. | Maximale Flexibilität für die Skalierung auf unterschiedliche Geldgeber-Typen (E-08). |
| 2026-04-05 | `RICHTUNG` | **State 0 (Neutral) Handling:** Kein sofortiger Market Close. Stattdessen Wechsel in einen "Tight Trailing Mode", der den Trade bei einer Gegenbewegung per SL aus dem Markt drängt (Graceful Exit). | Minimiert Spread-Verschleiß und Slippage bei flackernden KI-Signalen, schützt aber Kapital (E-09). |
| 2026-04-05 | `RICHTUNG` | **Trade Lifecycle ([[trade-lifecycle|Trailing SL]] & [[trade-lifecycle|Partial Close]]):** Hybrides System: Initialer Hard-Stop → [[trade-lifecycle|Partial Close]] (z.B. 50%) & Break-Even SL bei `1R` Profit → Breiter [[trade-lifecycle|Trailing SL]] für den Rest der Dauer. Parameter müssen in Config auslagerbar sein. | Perfekter Schutz vor [[prop-firm-compliance|Prop-Firm]] Trailing-Drawdown Verletzungen. Gewinne werden aktiv gesichert, statt wieder auf 0 zu fallen (E-10). |
| 2026-04-05 | `RICHTUNG` | **OpenBB Integration:** Wird fest in die Architektur committet. Dient nicht zwingend nur als reiner News-Filter, sondern als erweiterter Knotenpunkt für Financial Data Pulls. | Stabile, verlässliche Quelle für fundamentale/externe Metadaten (E-11). |
| 2026-04-05 | `SCOPE` | **CUA (Computer Use Agent) gestrichen:** Der physische "Mausklick"-Fallback für Broker ohne API wird komplett aus der Doku und Architektur verworfen. | Reduziert architektonischen Ballast. MT5 API ist als einziger Execution-Tunnel gesetzt und völlig ausreichend (E-13). |
| 2026-04-05 | `RICHTUNG` | **Alerting:** Initiale SUSPEND / Killswitch Benachrichtigungen an den Supervisor werden simpel und verlässlich per E-Mail (SMTP) abgewickelt. | MVP-Ansatz. Es braucht in V1 keine Over-Engineering via Telegram oder n8n (E-16). |
| 2026-04-06 | `FIX` | **Sprint 1 Kap. 03:** §1 Entropie-Features explizit benannt (RSI, BBW, NATR, VolOsc, CMF). §5 [[decision-matrix|Decision Matrix]] (Signal Matrix) als neues Kapitel eingefügt: Kombinierte Logik SJM-State × Entropy-Factor → System-State. | Klärung der Kern-Entscheidungslogik. Safe Zone = Bull + H↑. Alle anderen Kombinationen = Flat. |
| 2026-04-11 | `RICHTUNG` | **ZMQ Serialisierung (E-14):** `msgpack_numpy` (oder Arrow) ersetzt `pickle` vollständig auf der Box 1 ↔ Box 2 Pipeline. | Security: Verhindert Remote Code Execution Schwachstellen durch kompromittierte Pickles. |
| 2026-04-11 | `RICHTUNG` | **Split-Brain Protection (Kap. 10):** Payload Hash-Locking etabliert. Box 3 erzwingt zwingend einen `config_hash` Match in jedem Payload vor Order-Ausführung. | Verhindert Config-Desync Panic zwischen Linux VPS und Windows Server bei asynchronen Git-Deployments. |
| 2026-04-12 | `RICHTUNG` | **Sprint 5 (Kap. 07):** Konkrete Infrastruktur-Spezifikation in Doku aufgenommen — Tailscale ACL JSON, UFW/Fail2ban Setup, OpenClaw YAML-Config-Skelett, Python-basierte Context/Evidence Gates, Two-Repo Deployment Pipeline. | Doku enthielt nur Konzepte ohne Implementierungs-Details. Sprint 5 liefert konkrete Configs und CLI-Skripte als Architektur-Referenz. |
| 2026-04-12 | `RICHTUNG` | **Sprint 6 (Kap. 08):** Lab-Struktur erweitert — Verzeichnisbaum, VectorBT/Backtrader-Evaluation, Walk-Forward-Validation Diagramm, `run_backtest.py` und `promote_model.py` CLI-Skripte. | Backtesting war nur konzeptionell beschrieben. Sprint 6 liefert konkrete Projektstruktur und Evidence-gesteuerte Model Promotion. |
| 2026-04-12 | `RICHTUNG` | **Sprint 7 (Kap. 01):** Phantom-Tools Tabelle eingeführt — 7 verworfene Konzepte (CUDA, QuantConnect, Vektor-DBs, CUA, State -1, Firebase, Dead Man's Switch) explizit dokumentiert, Schnittstellen-Matrix ergänzt. | Architektur-Doku enthielt veraltete Referenzen auf verworfene Tools. Phantom-Tools Tabelle verhindert zukünftiges Reintroduzieren. |
| 2026-04-12 | `FIX` | **BMAD-001: ZMQ↔REST Widerspruch Kap. 10 korrigiert:** Der `config_hash` wird als JSON-Feld im bestehenden REST-Payload (`POST /api/v1/signal`) übertragen, nicht via ZMQ. ZMQ gilt ausschließlich für Box 1→Box 2 (Kap. 05 §1). Kapitel 10 Intro, §10.3 und Refs entsprechend korrigiert. | Widerspruch zwischen Kap. 05 §2 (REST/FastAPI für Box 2→3) und Kap. 10 (fälschlich ZMQ). REST ist für Swing-Trade SLAs völlig ausreichend. |
| 2026-04-12 | `RICHTUNG` | **Multi-Agent Koordination (CLINE.md)**: Strikte Trennung Supervisor vs. Task-Agent bezüglich Datei-Schreibrechten etabliert. | Behebt die Dateikorruption vom 2026-04-06. Task-Agents werfen Tickets nur in die Inbox, der Meta-Agent pflegt die Core-Files. |
| 2026-04-12 | `FIX` | **BMAD-002: Architecture Flaws & Hot-Path Resolution:** Umstellung auf Sequence-Numbers (Tick-IDs) statt NTP (<5ms) Vorgabe. OpenBB Fallback auf "Blind-Flight Context" ohne Pipeline Pause. MQL5 `WAITING_FOR_SYNC` Wake-Up integriert. Parquet Ferry via Atomar-Rename, Autonomous Safe Mode (Panic Liquidation nach config Timeout) ergänzt. Chaos Engineering Tests spezifiziert. | "Happy Path" Annahmen (stabiles VPN, NTP-Sync, OpenBB-Verfügbarkeit) hätten zu Live-Crashes geführt. Entkopplung von Third-Party Abhängigkeiten sichert den Hot-Path ab. |
| 2026-04-12 | `FIX` | **BMAD-003: Double-Sided Locking & Idempotent Sync:** Der 5-s Ping (Box 2→3) überträgt ab sofort idempotent den `current_state` und `config_hash`, um MT5 nach einem Windows-Reboot autonom heilen zu können (ansonsten wäre FastAPI blind geblieben). The Parquet Ferry streamt nun als `.tmp` bis zum TCP-EOF auf Linux, dann atomares Rename (verhindert C-Engine read crashes im Lab während asynchroner VPN-Transfers). | Beseitigt Memory-Wipes und Data-Engineering Antipatterns, die erst im Sequential-Thinking-Audit offengelegt wurden. |
| 2026-04-12 | `FIX` | **F-01: ACL-Widerspruch ZMQ PUB/SUB behoben.** Muscle (Box 1, Windows) bindet Port 5555 als ZMQ PUB. Brain (Box 2, Linux) verbindet sich per `connect()` als SUB auf 5555. Tailscale ACLs und Windows Firewall wurden angepasst (Muscle Inbound statt Outbound auf 5555). | Löst den Widerspruch zwischen "Muscle darf keine Verbindung zu Brain aufbauen" und dem ZMQ Flow. Die uni-direktionale Brain→Muscle Architektur bleibt auf Netzwerk-Ebene strikt intakt. |
| 2026-04-12 | `FIX` | **F-02: Cron-Syntax Fix im Deploy-Runbook.** Die fehlerhafte Cronjob-Syntax `* */5 * * *` für den 5-Minuten Git-Sync auf Linux wurde zu `*/5 * * * *` korrigiert. | Verhindert, dass der Git-Sync fälschlicherweise "jede Minute, aber nur in jeder 5. Stunde" statt "alle 5 Minuten" ausgeführt wird, was zu Config-Desyncs geführt hätte. |
| 2026-04-12 | `FIX` | **F-03: OpenBB Lokation (Kap. 02/04) Widerspruch behoben.** Verweis auf OpenBB in Box 1 im Risk-Diktator (Kap. 04) auf Box 2 (Linux) korrigiert, konform mit der Architektur aus Kap. 02. | Einheitliche Zuordnung der External Data Layer (OpenBB) auf den Hetzner VPS (Box 2). |
| 2026-04-12 | `FIX` | **F-04: Config-Hash Algo auf SHA-256 vereinheitlicht.** Diskrepanzen zwischen SHA-1 (Kap. 10 / Runbook) und SHA-256 (Kap. 07 / Lab) wurden zugunsten von SHA-256 (File-Hashing zur Laufzeit) aufgelöst. | Stellt sicher, dass das Split-Brain Protection Feature überall denselben Hash-Algorithmus verwendet und nicht fälschlicherweise auf Git Commit-Hashes (SHA-1) vertraut. |
| 2026-04-12 | `FIX` | **F-05: Kap. 02 §3 Verwaiste Inhalte restrukturiert.** Zwei verlorene Bulletpoints am Ende des Dokuments (Array-Konditionierung und Z-Score Normalisierung) wurden in die logisch zugehörige §3 "Normalisierungs-Pipeline" verschoben. | Stellt den logischen Lesefluss und die inhaltliche Vollständigkeit der MLOps Vorverarbeitung wieder her. |
| 2026-04-12 | `FIX` | **F-06: GPU-Phantom in Kap. 02 §4 entfernt.** Im Architektur-Beschluss E-04 wurde der irrige Verweis gelöscht, dass GPU-Ressourcen für das Improvement Lab reserviert seien. | Korrigiert einen faktischen Hardware-Widerspruch, da der Hetzner Linux VPS (auf dem Box 4 läuft) nachweislich keine dedizierte GPU besitzt. |
| 2026-04-12 | `FIX` | **F-07: ZMQ Staleness-Monitor auf Box 2 (Kap. 05 §1) spezifiziert.** Es wurde ein aktiver *Time-Since-Last-Message Monitor* in der Box 1 ↔ Box 2 ZMQ-Schnittstelle definiert. | Da das ZMQ PUB/SUB Pattern Verbindungsabrüche potenziell "stumm" ignoriert, verhindert der Monitor, dass Box 2 auf Basis veralteter Daten weiter Inferenz betreibt. |
| 2026-04-12 | `FIX` | **F-08: API-Pfad auf `/api/v1/signal` vereinheitlicht.** Inkonsistenzen in den API-Pfad-Benennungen in Kap. 09 (Testing) und Kap. 99 (Deploy Runbook) wurdem zu `/api/v1/signal` standardisiert. | Vermeidet potentielle Konfigurationsfehler beim Routing zwischen FastAPI (Box 3) und Agenten (Box 2). |
| 2026-04-12 | `FIX` | **F-09: DOC-SPEC.md aktualisiert.** Die Definition der Architektur-Struktur (Kapitel 01-08) in der `DOC-SPEC.md` wurde um die nachgereichten Kapitel 09 (Testing), 10 (Konfiguration) und 99 (Deploy Runbook) vervollständigt. | Sichert die Konsistenz des zentralen Inhaltsverzeichnisses. |
| 2026-04-12 | `FIX` | **F-10: Parquet Ferry Timing (Kap. 08 vs 05) korrigiert.** Der alte Verweis auf einen "Batch Sync am Wochenende" in Kap. 08 wurde entfernt. Die Ferry agiert konform mit Kap. 05 als kontinuierlicher Background-Stream mit atomarem Rename. | Behebt den inhaltlichen Widerspruch zwischen asynchronem Daemon-Streaming und starren Cronjob-Batches. |
| 2026-04-12 | `FIX` | **F-11: Code-Typo in Kap. 09 §2.4 behoben.** Der syntaktisch falsche Python-Decorator `@gst` wurde durch den korrekten Hypothesis-Decorator `@given` abgelöst. | Verhindert Copy-Paste Errors bei der zukünftigen Überführung der Spezifikation in echten Code. |
| 2026-04-12 | `FIX` | **F-12: DECISIONS.md Metadaten aktualisiert.** Das `last_reviewed` Frontmatter-Attribut wurde auf `2026-04-12` gesetzt. | Hält den PULL-Status der wichtigsten Veto-Akte im System transparent. |
| 2026-04-12 | `FIX` | **F-13: Windows-SMTP Alerting in Kap. 99 ergänzt.** Sektion 7 des Deploy-Runbooks wurde umgebaut. Neben dem Linux-Health-Cron ist nun exakt aufgeführt, wie die Windows .env Datei bzgl. SMTP (für SUSPEND / Risk-Kills) konfiguriert werden muss. | Schließt das fehlende Glied der Alerting-Doku, da Box 3 auf Windows E-Mails generiert, ohne einen Postfix-Daemon zu nutzen. |
| 2026-04-12 | `SCOPE` | **F-14: Referenz `performance-profiling.md` veraltet.** Das File wurde formal im Header und im `INDEX.md` als `[DEPRECATED]` markiert. | Bereinigt konsequent letzte Überbleibsel des GPU-Phantoms, da Themen wie PyTorch CUDA-Streams und Pinned Memory auf dem verwendeten Hetzner-Server obsolet sind. |
| 2026-04-12 | `SCOPE` | **F-15: Fallback für gs-quant ergänzt.** Das pure Python-Package `QuantStats` wurde in Kap. 05 und Kap. 08 als offizielle Ausweichmöglichkeit für die oft konfliktbehaftete Goldman Sachs Library definiert. | Schützt das Improvement Lab vor Build-Fehlern, die oft mit schwergewichtigen C++ / Cython Abhänigigkeiten von gs-quant unter Linux-Servern einhergehen. |
| 2026-04-12 | `FIX` | **F-16: Code-Formatierung in Kap. 09 behoben.** Die fehlerhafte doppelte Vergabe der Überschriften-Nummer `4.2` wurde bereinigt. | Sichert die inhaltliche Lesbarkeit. |
| 2026-04-12 | `SCOPE` | **F-17: Kap. 06 inhaltlich ausgebaut.** Die Themen Timeboxing/Pomodoro-Strategie und die potenzielle Post-MVP Nutzung der Super Productivity REST-API für Agent-Handoffs wurden präzisiert. | Verhindert "Overengineering-Holes" für den menschlichen Supervisor durch klare Timeboxing-Regeln auf Basis des Blackbox-Splits. |
| 2026-04-12 | `FIX` | **F-18: Code-Formatierung in Kap. 07 behoben.** Fehlenedes Leerzeichen bei `11.1Repository-Struktur` wurde hinzugefügt. | Formale Kosmetik. |
| 2026-04-12 | `SCOPE` | **F-19: PROJECT-BRAIN Status auf Implementation Ready gesetzt.** Die "Offene Fragen" Sektion in der Projekt-Wurzel wurde aktualisiert, um abzubilden, dass Phase 1 (Spezifikation + Härtung) vollständig und fehlerfrei abgeschlossen ist. | Markiert den finalen Abschluss der rein konzeptionellen Phase des Projekts. |
| 2026-04-12 | `FIX` | **F-20: VectorBT API-Aufruf in Kap. 08 korrigiert.** Ein Pseudo-Aufruf von `YFPrices` (externe Yahoo API) wurde im CLI-Beispielscript entfernt und so umgeschrieben, dass er wie vorgesehen den reinen Pandas-DataFrame der Parquet-Ferry nutzt. | Konsistenz mit dem Offline-Mantra des Improvement Labs. |
| 2026-04-12 | `RICHTUNG` | **SOTA Deep Audit:** System gegen 2026-SOTA Patterns bewertet. 82% SOTA-konform, 67% produktionsreif. 12 neue Gaps (G-01..G-12) identifiziert — G-01 (Observability), G-02 (SOPS Secrets), G-03 (Broker-Time) als kritisch eingestuft. | Cross-Chapter-Konsistenz nach F-20-Fixes ist hoch (95%), aber Ops-Tooling fehlt. Systemstärken: Resilience Design, Split-Brain Protection, Entropie-Gatekeeper — alle ⭐⭐⭐⭐⭐. |
| 2026-04-12 | `RICHTUNG` | **G-01: Structured Logging Standard festgelegt.** Alle REST-Payloads (Signal + Ping) und ZMQ-Frames müssen künftig ein `trace_id` (UUID4) Feld enthalten. Python-seitig wird `structlog` als Logging-Library gesetzt. | Ohne Correlation IDs ist Debugging über 2-Node-Architektur (Brain + Muscle) im Live-Betrieb nicht möglich. Kritische Lücke vor Code-Implementierung zu schließen. |
| 2026-04-12 | `RICHTUNG` | **G-02: Secrets Management via SOPS/age.** Keine Plaintext-Secrets in `.env`. Erzwungene Verschlüsselung via Mozilla SOPS mit asymmetrischen `age`-Keys. | Schutz sensibler Broker-Daten und SMTP-Passwörter in Git-basierten Deployment-Pipelines. |
| 2026-04-12 | `RICHTUNG` | **G-03: Broker-Server-Time als Daily-Loss-Zeitquelle festgelegt.** Floating-DD-Reset darf ausschließlich gegen `mt5.symbol_info_tick().time` (Broker-Server-Zeit) berechnet werden, nicht gegen lokale VPS-UTC-Zeit. | Prop-Firms (z.B. FTMO) verwenden ihre eigene Server-Zeit (EET/EEST) für den Mitternachts-Reset. Falscher Zeitbezug = sofortige Challenge-Disqualifikation. |
| 2026-04-12 | `RICHTUNG` | **G-04: Pydantic v2 BaseSettings Config-Validation.** Beide Boxes validieren ihre Konfiguration via Pydantic beim Start (Fail-Fast). `compliance.yaml` (Box 3): alle PF-01..PF-06 Felder typisiert und mit Bounds versehen. `thresholds.json` (Box 2): Entropie-Gate, Hysterese, Timeframes. `compute_config_hash()` als shared Utility definiert. | Eliminiert Silent-Misconfig. Falsche Werte (z.B. `max_daily_loss_pct > 1.0`, invertierte Entropy-Thresholds) werden abgefangen, bevor eine Live-Verbindung aufgebaut wird. |
| 2026-04-12 | `RICHTUNG` | **G-05: Rollback-Mechanismus (Deploy-Guard).** Nach jedem `git pull` prüft ein Health-Check-Script (Python/PowerShell) Services und FastAPI `/health`. Bei Failure: `git revert HEAD --no-edit` + Service-Restart + SMTP-Alert. Cooldown-Lockfile (15min) verhindert Rollback-Loops. | Verhindert, dass ein defekter Commit auf `main` das Live-Trading-System lahmlegt ohne manuelle Intervention in der Nacht. |
| 2026-04-19 | `SCOPE` | **G-06: MLflow V1 Tracking ohne VectorBT.** Im The Lab (Box 4) wird MLflow statt DVC für das lokale Experiment-Tracking präferiert. VectorBT bleibt konsequent gestrichen. Metriken stammen ausschließlich aus ffn, gs-quant oder numpy-Logik. | Reduziert Tool-Bloat und bleibt innerhalb des CPU-Optimierungs-Paradigmas. SQLite Tracking on Box 4 ist ideal für V1. |
| 2026-04-19 | `RICHTUNG` | **G-07: Deep-Check `/health` Endpoint & MT5-Locking.** Der Readiness-Probe in Box 3 sichert ab, ob `algo_trades_allowed` aktiv und der Terminal verbunden ist, inkl. `config_hash`-Delivery zum Split-Brain Schutz. Jeder `mt5.*` Check ist zudem strukturell durch das globale `threading.Lock()` abzusichern. | Verhindert Race-Conditions mit dem asynchronen Watchdog-Loop und sichert Automations-Rollbacks ab. |
| 2026-04-19 | `VETO` | **G-08: Strikte CI/CD Infrastruktur-Trennung.** GitHub Actions / Local Runner dürfen NIEMALS auf Box 3 (The Muscle) laufen. E2E Tests mit lokalem MT5 bedürfen eines designierten isolierten Windows-Staging Servers. | Box 3 ist ein purer Execution Hot-Path. Ein CI/CD Speicher-Leck oder CPU-Spike könnte den Echtgeld-Prozess vernichten. |
| 2026-04-19 | `RICHTUNG` | **G-09: Circuit-Breaker Rate-Limit & Alerting.** Auf dem Box 3 Endpoint `POST /api/v1/signal` gilt ein Hardlimit (12 req/min) -> HTTP 429. Box 3 agiert als alleiniger Alert-Hub per SMTP. Box 2 geht bei HTTP 429 in "Stasis/Cooldown" (5 Min State Freeze), bleibt aber alert-seitig silent. | Schützt Box 3 gegen Amok laufende Agent-Loops (Pounding) und Tailscale-Tunnel-Überlastung durch Backoff-Cooldown Parameter. |
| 2026-04-19 | `RICHTUNG` | **G-10: 3-Step Graceful Shutdown (NSSM & Systemd).** Service-Stops müssen offene Sockets (ZMQ) kappen passiv (`TimeoutStopSec=15`). Box 3 fängt Signale (`SIGINT`/`SIGTERM`) ab: 1. Stop FastAPI Ingress, 2. Cancel async Watchdog-Threads, 3. Lock + `mt5.shutdown()`. | Beugt MT5-COM-Zombie-Lecks und Address-Blockaden bei Auto-Deployments/Rollbacks vor. |
| 2026-04-19 | `RICHTUNG` | **G-11 & G-12: MVP Observability (Zero Metric-Scraping).** Verzicht auf Prometheus in V1. Stattdessen nutzen wir OS-Level Log-Rotation (logrotate + copytruncate auf Linux / NSSM native AppRotate auf Windows) und Promtail -> Grafana Loki. Letzteres läuft sicherheitsbetont ausschließlich per Tailscale VPN (-not 0.0.0.0) auf Box 4 (The Lab). | Hält CPU-Overhead auf Box 2 und 3 zu 100% für Trading frei. Kein Web-Expose schützt das System vor Angriffen. JSON-Logs (structlog) liefern "gratis" Metriken durch Loki. |
| 2026-04-19 | `RICHTUNG` | **Sprint H (Architecture Hardening Part 2) abgeschlossen:** Implementierung des 3-Stufen Wake-Up/Orchestrierungs-Modells (Scout/Manager, LLM-Fusion 10s Timeout), Feedback-Loop (Position-Report via IPC Heartbeat), und asymmetrischer Hysterese (Tight Trailing). All logic gaps closed. | Refines hot-path resilience and resolves the dual Box2 vs Box3 context dissonance. |
| 2026-04-19 | `FIX` | **Sprint I — Docs Audit B-1: Doppelter Content in Kap. 08 entfernt.** Die gesamte Datei enthielt Zeilen 1–32 als exakte Kopie des Inhalts ab Zeile 33 (Copy-Paste Bug). | Korrupte Datei hätte bei Agent-PULL zu Halluzinationen geführt (doppelter Frontmatter). |
| 2026-04-19 | `FIX` | **Sprint I — Docs Audit B-5: Timeframe M5 vs. H4 korrigiert.** Das Referenz-Konfigurationsbeispiel in Kap. 10 `thresholds.json` listete `"primary": "H4"` statt `"M5"` (konform mit Kap. 02). | Widerspruch hätte bei code-generierenden Agenten zu falschem Timeframe in der Live-Config geführt. |
| 2026-04-19 | `RICHTUNG` | **Sprint I — A-1: Box 2 COLD_START Modus definiert.** Box 2 startet nach Crash/Restart im `COLD_START`-Zustand: Keine Entropie, keine Agenten. Wartet auf ersten Heartbeat-Response mit `active_trades` Array. Leitet daraus Scout vs. Manager Modus ab. | Verhindert undefiniertes Verhalten bei Agent-Restart (fehlende State-Persistenz). |
| 2026-04-19 | `RICHTUNG` | **Sprint I — A-2: ZMQ Sequence Number (`seq_id`) eingeführt.** Monoton steigende uint64 in jedem ZMQ-Paket. Box 2 verwirft Out-of-Order Pakete (typisch nach VPN-Reconnect). | PUB/SUB garantiert keine Reihenfolge bei Reconnects. Ohne seq_id: Inferenz auf falscher Datenbasis. |
| 2026-04-19 | `SCOPE` | **Sprint I — A-3: OpenBB kein Fallback-API in V1.** Bei OpenBB-Totalausfall: Context Layer fällt weg, System operiert auf reinem MT5-Tick-Stream. Kein FRED/Yahoo als Backup. Confidence-Penalty bleibt dauerhaft aktiv. | FRED/Yahoo-Integration wäre Over-Engineering für V1. Tick-Stream allein reicht für defensive Inferenz. |
| 2026-04-19 | `RICHTUNG` | **Sprint I — C-1/C-2: ClickHouse und gs-quant gestrichen.** Parquet ist alleiniger Storage-Layer im Lab. QuantStats + ffn sind der offizielle Stresstest/Metriken-Stack. | ClickHouse: unnötiger DB-Server-Overhead auf VPS. gs-quant: fragile C++/Cython Build-Dependencies unter Linux. |
| 2026-04-19 | `RICHTUNG` | **Sprint I — C-3: 3-Level Fusion → 2-Level.** Level 1 = Deterministischer Konsens (Gewichtung + Veto). Level 2 = LLM Fallback bei Grauzone. Level 1+2 des alten Modells waren de facto ein Schritt. | Reduziert konzeptuelle Komplexität ohne funktionalen Verlust. |
| 2026-04-19 | `SCOPE` | **Sprint I — C-5: Kap. 06 in Kap. 07 §12 integriert.** Eigenständiges Kapitel mit nur 36 Zeilen (rein operativer Meta-Content) als Abschnitt in Infrastructure-Kapitel überführt. Kap. 06 bleibt als Deprecated-Redirect erhalten. | Reduziert Verzeichnisbaum-Overhead. Kein anderes Kapitel referenzierte Kap. 06 als Abhängigkeit. |
| 2026-04-19 | `RICHTUNG` | **Sprint I — SSOT-Architektur:** Kanonische Stellen für 5 Kern-Konzepte fixiert: config_hash→Kap.10, SUSPEND→Kap.05, Double-Dip→Kap.03, Parquet Ferry Technik→Kap.05, Lab-Verarbeitung→Kap.08. Alle anderen Stellen nutzen `→ Ref: [[SSOT]]`. | Verhindert Inkonsistenzen bei Updates und Agent-Halluzinationen durch widersprüchliche Prompts. |




========================================
FILE: DOC-SPEC.md
========================================
# DOC-SPEC — Hybrid AI-Trading System

## Sprache & Ton
Klar, deskriptiv, State-of-the-Art fachlich auf Deutsch. Keine Marketing-Visionen, rein technische Präzision.

## Struktur-Konventionen
- **Deep Dive:** Jedes Modul/jede Blackbox wird tiefgehend analysiert. Informationen werden durch den Agenten selbstständig aus Roh-Chatverläufen extrapoliert.
- Kapitel beginnen mit: kursiver Zusammenfassung (2-3 Sätze)
- Kapitel enden mit: Querverweisen zu verwandten Kapiteln und klaren Schnittstellendefinitionen.
- Überschriften: # Titel, ## Hauptabschnitte, ### Unterabschnitte

## ⚠️ CORE WORKFLOWS: CLI, GTD & BMAD Framework ⚠️
Um bei häufigen Chat-Wechseln absolut bullet-proof zu arbeiten (kein Informationsverlust!), gelten für ALLE Agenten exakte terminologische Abgrenzungen:

1. **Die Agent-Runtime (PULL-PROCESS-PUSH):** 
   - **PULL:** Zwingendes Auslesen von `PROJECT-BRAIN.md`, `DOC-SPEC.md`, `CHAPTER-STATUS.md` und `DECISIONS.md` vor jedem Task.
   - **PROCESS:** Evaluierung, Extrapolation, Code/Text-Generierung.
   - **PUSH:** Schreiben der Status-Dateien. Erst wenn `CHAPTER-STATUS` und Co. geupdatet sind, ist ein Job "Done".

2. **Das GTD (Getting Things Done) Modell:**
   - Dient dem sicheren Entleeren des Arbeitsspeichers: Lose Ideen werden sofort ins `Kanban`, die `Knowledge/inbox` oder `TEST-LAB-LOG` **ge-captured**, um den Fokus auf den Kern-Task nicht zu verlieren.

3. **Das BMAD (Build-Measure-Analyze-Decide) Modell:**
   - Dient als reines Incident-Response System. Kommt es zu Widersprüchen in der Blackbox-Logik, verhindert BMAD blindes "Fixen". Es erzwingt das Aufstellen einer Root-Cause-Hypothese vor jeglicher Code-Mutation.

## Referenz-Konvention
Tiefes Detailwissen (mathematische Herleitungen, Paper-Zusammenfassungen, Architektur-Patterns) wird **nicht** in die Kapitel geschrieben, sondern im Verzeichnis `refs/` abgelegt.
- **Struktur:** `refs/papers/` (Akademisches), `refs/patterns/` (Architektur-Konzepte), `refs/tools/` (Tool-Evaluierungen)
- **Übersicht:** `refs/INDEX.md` listet alle Referenzen mit Kapitel-Zuordnung
- **Kapitel verweisen** per Inline-Link: `→ Ref: [Titel](../refs/path/file.md)`
- **Jede Ref-Datei** beginnt mit `## Quelle` und endet mit `## Relevanz für das System`

## Glossar
| Begriff | Definition |
|---|---|
| Blackbox 1 (Data) | Autonomes Modul zur Beschaffung und Normalisierung finanzieller Marktdaten. |
| Blackbox 2 (Agents) | Analytisches Hirn; wertet Daten anhand von Metriken aus und berechnet System-States. |
| Blackbox 3 (MT5) | Ausführungsmodul; empfängt States und exekutiert Orders inkl. hartem Risikomanagement. |
| SOTA | "State of the Art" - Orientierung an neuester empirischer Forschung. |
| DECISIONS.md | Strukturiertes Veto-Log. Persistiert jede menschliche Korrektur mit Datum, Typ und Begründung. |
| Context Gate | Mechanisches Skript, das Agenten zwingt, Kontext (decisions.md, Memory) zu laden, bevor sie handeln. |
| Evidence Gate | Mechanisches Skript, das Beweise (Commit-Hash, Tests) verlangt, bevor ein Task als "Done" gilt. |
| Entropy Inversion | H↑ = Stabil/Gesund (Go), H↓ = Kollaps/Panik (No-Go). Basiert auf Arella (Market Folding). |

## Kapitelstruktur
| Nr | Titel | Beschreibung |
|---|---|---|
| 01 | System-Architektur & 3-Blackbox Design | High-level Übersicht, Isolation der Module und Sicherheit. |
| 02 | Blackbox 1: Data Engine | Pipeline, APIs und Normalisierung. |
| 03 | Blackbox 2: The Scientist (Agenten) | Analytische Metriken, State-Berechnung. |
| 04 | Blackbox 3: MT5 Execution Bridge | Watchdog, Async Timer, Hard-Stops, Order Management. |
| 05 | API & Schnittstellen-Spezifikation | Wie die 3+1 Boxen miteinander kommunizieren. |
| 06 | Meta-Ebene: Projektmanagement | ⚠️ DEPRECATED → integriert in Kap. 07 §12 |
| 07 | The OS: Memory & Infrastructure | Hetzner VPS, OpenClaw + GitHub Stack, mechanische Gates, Archivar. |
| 08 | The Improvement Lab (Box 4) | Backtesting, RL-Training (PPO), Offline-Staging von Modellen. |
| 09 | V1 Testing-Strategie | Test-Pyramide, Mocks, CLI-Tests (Pytest), Paper-Trading. |
| 10 | Konfigurationsmanagement | GitOps, File-Hashing (SHA-256), Split-Brain Protection. |
| 98 | Umsetzungsleitfaden | Mock-Architektur, Interface Contracts, Coding-Konventionen, Phasenplan. |
| 99 | Deploy Runbook | Checklisten, Firewall-Regeln, NSSM/Systemd Setup, Sync-Cronjobs. |


========================================
FILE: AGENT-COOKBOOK.md
========================================
# 🍳 Agent Cookbook — RickBrain Trading System

*Copy-Paste dieses Dokument in jeden neuen Chat. Es gibt dir sofort Orientierung.*

---

## 1. Quick Start (5 Schritte)

```
1. /cookbook    → Dieser Guide
2. /pull        → Agent-Sync starten
3. PROJECT-BRAIN.md → Was ist das Projekt?
4. CHAPTER-STATUS.md → Was ist fertig?
5. IMPL-STATUS.md → Welche Code-Tasks sind offen?
```

---

## 2. Must-Read Kapitel

| Kap | Titel | Wann lesen |
|-----|-------|------------|
| **00** | MOC (Übersicht) | Immer zuerst |
| **01** | System-Architektur | Überblick |
| **03** | Blackbox 2: Agenten | Bei Signal/State-Fragen |
| **04** | Blackbox 3: MT5 Bridge | Bei Execution/Order-Fragen |
| **05** | Schnittstellen | Bei Box-Kommunikation |
| **10** | Konfiguration | Bei Config-Änderungen |
| **98** | Umsetzungsleitfaden | **PFLICHT** vor dem Coding — Mock-Architektur, Contracts, Phasenplan |

---

## 3. Slash-Commands (clinerules/workflows)

| Command | Nutzen | Datei |
|---------|--------|-------|
| `/cookbook` | Dieser Guide | workflows/cookbook.md |
| `/pull` | Session-Sync | workflows/pull.md |
| `/sota` | NotebookLM Export | workflows/sota.md |
| `/bmad` | Incident Response | workflows/bmad.md |
| `/ticket` | Handoff an Agenten | workflows/ticket.md |
| `/sprint` | Sprint-Tasks abarbeiten | workflows/sprint.md |
| `/audit` | Kapitel-Check | workflows/audit.md |
| `/implement` | **Code implementieren** | workflows/implement.md |
| `/review` | **Code reviewen/approven** (Mobile-optimiert) | workflows/review.md |
| `/run` | Queue abarbeiten | workflows/run.md |
| `/capture` | Idee speichern | workflows/capture.md |
| `/clarify` | Frage klären | workflows/clarify.md |
| `/evaluate` | Evaluation | workflows/evaluate.md |

---

## 4. SSOT (Single Source of Truth)

**Bevor du irgendwo änderst, prüfe hier wo die kanonische Quelle ist:**

| Was | Kanonische Stelle | Andere Kapitel |
|-----|-------------------|----------------|
| `config_hash` | Kap. 10 | 01, 04, 05, 07 |
| `SUSPEND` | Kap. 05 §3 | 01, 04, 99 |
| `Double-Dip` | Kap. 03 §3 | 04, 05 |
| `Parquet Ferry` | Kap. 05 §4 | 02, 08 |
| `Decision Matrix` | Kap. 03 §5 | — |

→ Ref: [[00-MOC-Trading-System|Kap. 00: MOC]] für vollständiges SSOT-Verzeichnis

---

## 5. Die 3+1 Blackboxen

```
┌─────────────────────────────────────────────────────────────┐
│                    RICKBRAIN SYSTEM                         │
├──────────────────────┬──────────────────────────────────────┤
│  BOX 1 (Windows)     │  BOX 2 (Linux VPS)                   │
│  Data Engine         │  The Scientist (Agenten)              │
│  - MT5 Data Pull     │  - Entropie-Berechnung               │
│  - Normalisierung    │  - State-Generierung (0/1)           │
│                      │                                      │
├──────────────────────┼──────────────────────────────────────┤
│  BOX 3 (Windows)     │  BOX 4 (Linux VPS)                   │
│  MT5 Execution       │  The Improvement Lab                  │
│  - Order-Ausführung │  - Backtesting                        │
│  - Risk-Diktator     │  - Model Training (RL/PPO)            │
└──────────────────────┴──────────────────────────────────────┘
         ↕ Tailscale VPN ↕
```

---

## 6. Decision Flow

```
Dokumentation:                    Code:
User Request                      /implement next
     ↓                                 ↓
/pull → Agent-Sync               IMPL-STATUS.md lesen
     ↓                                 ↓
Kapitel lesen (MOC zuerst!)      Kap. 98 + Fachkapitel lesen
     ↓                                 ↓
Änderung durchführen             Code + Tests schreiben
     ↓                                 ↓
/push → Status updaten           Review-Summary → /review
     ↓                                 ↓
Done!                            Supervisor approved → Done!
```

---

## 7. Bei Fragen...

| Problem | Lösung |
|---------|--------|
| Kapitel nicht gefunden? | → MOC (Kap. 00) |
| Widerspruch gefunden? | → `/bmad` |
| Config ändern? | → Kap. 10 lesen |
| Test schreiben? | → Kap. 09 lesen |
| Anderen Agenten fragen? | → `/ticket` |
| Idee für später? | → `/capture` |

---

## 8. Pflicht-Dateien (PULL-Reihenfolge)

**Für Doku-Agenten:**
```
1. PROJECT-BRAIN.md  → Projekt-Kontext
2. DOC-SPEC.md       → Stil und Kapitelstruktur
3. DECISIONS.md      → Alle Entscheidungen / Vetos
4. CHAPTER-STATUS.md → Was ist fertig?
```

**Für Coding-Agenten:**
```
1. docs/98-implementation-guide.md → Pflichtlektüre (Contracts, Mocks, Konventionen)
2. IMPL-STATUS.md    → Welche Tasks sind offen / in progress?
3. DECISIONS.md      → Veto-Log (was ist VERBOTEN)
4. Das Fachkapitel der Box, an der du arbeitest
```

**Nur OpenClaw (VPS):** SYSTEM.md und SOUL.md existieren nur im OpenClaw-Workspace, nicht lokal.

---

*Zuletzt aktualisiert: 2026-04-26*


========================================
FILE: OPEN_TASKS.md
========================================
# 📋 Master-Taskliste — Gap-Resolution

> [!WARNING]
> **[DEPRECATED — Implementation Ready]**
> Alle Sprints und offenen Punkte aus dieser Liste sind abgeschlossen. Die nächste Phase (Code) beginnt.

**Erstellungsdatum:** 2026-04-05  
**Grundlage:** gap_analysis.md (v3) + gap_analysis_v4_external.md  
**Offene Gaps:** 0  
**Methode:** Entscheidungen ERST klären, dann Kapitel-weise abarbeiten

---

## ✅ PHASE 0: Offene Entscheidungen (ABGESCHLOSSEN)

> [!NOTE]
> Alle 16 kritischen Blockerfragen (E-01 bis E-16) wurden am 2026-04-05 gemeinsam mit dem Supervisor analysiert und archiviert.  
> **Die verbindlichen Ergebnisse liegen in `DECISIONS.md`.** Die Doku-Sprints (ab Phase 1) sind nun vollständig entblockt.

### Architektur-Grundlagen

**E-01: Wird State `-1` (Short) im V1 gebraucht?**
Die Signal Matrix produziert nur `{0, 1}`. Entweder:
- a) Shorting für V1 entfernen → States werden `{0, 1}` → Doku vereinfacht sich
- b) Short-Bedingung definieren → z.B. `Bear + H↑ = Short (-1)`?
→ Antwort: ___

**E-02: Welcher Primary Timeframe?**
Rolling Window `N=50` von welchen Kerzen?
- a) H1 (50 Stunden = ~2 Handelstage)
- b) H4 (50 × 4h = ~8 Tage)
- c) M15 (50 × 15min = ~12.5h)
- d) Multi-Timeframe (z.B. Trend auf D1, Entry auf H1)?
→ Antwort: ___

**E-03: Welches Asset-Universum für V1?**
- a) Nur Forex Majors (EURUSD, GBPUSD, USDJPY, etc.)
- b) Forex + Indizes (US30, NAS100, GER40)
- c) Forex + Indizes + Gold/Silber
- d) Alles inkl. Krypto
→ Antwort: ___

**E-04: Hat der Hetzner VPS eine GPU?**
Kap. 02/08 referenzieren CUDA Streams. Falls keine GPU:
- Alle CUDA-Referenzen werden zu CPU-Optimierung umgeschrieben
- Temporal Graph Training (Box 4) braucht ggf. externes GPU-Cluster
→ Antwort: ___

### MT5 & Execution

**E-05: MT5 Account-Modus: Hedging oder Netting?**
Beeinflusst direkt die Trade-Lifecycle-Logik.
- Hedging: Mehrere Positionen pro Symbol möglich
- Netting: Nur eine Net-Position pro Symbol
→ Antwort: ___

**E-06: MQL5 EA Design: Ein EA für alle Symbole oder ein EA pro Symbol?**
- a) Ein Master-EA auf einem Chart, pollt alle Symbole via Timer
- b) Ein EA pro Chart/Symbol
→ Antwort: ___

**E-07: Python↔MQL5 IPC-Methode?**
- a) GlobalVariableSet() (double only, 64KB Limit, geht bei Restart verloren)
- b) Datei-IPC (JSON-Files in einem shared Ordner)
- c) Named Pipes / Sockets
→ Antwort: ___

### Prop-Firm Compliance

**E-08: Welche Prop-Firm ist das primäre Ziel?**
Regeln variieren stark. Für V1:
- a) FTMO (Static DD, Midnight-CEST Reset, Best-Day Rule)
- b) Apex (Trailing DD, 7 Min-Days, 2min News)
- c) TFT (Static DD, 15min News Blackout, kein Weekend Holding)
- d) Generisch konfigurierbar
→ Antwort: ___

**E-09: State-Transitions bei State-Wechsel?**
Wenn Box 2 den State von `1` (Long) auf `0` (Neutral) wechselt:
- a) Position sofort schließen
- b) Position halten (SL/TP schützt), nur keine neuen Trades
- c) Trailing-SL nachziehen, nicht aktiv schließen
→ Antwort: ___

**E-10: Gibt es Trailing Stops oder nur fixen ATR-SL?**
- a) Nur fixer ATR-SL bei Entry (Kein Nachziehen)
- b) ATR-SL bei Entry + Trailing-SL Nachführung bei Gewinn
- c) ATR-SL bei Entry + Breakeven-Move nach X Pips
→ Antwort: ___

### Infrastruktur

**E-11: OpenBB — Committen oder entfernen?**
- a) Committen → Wo läuft es? Box 1 (Windows) oder Box 2 (Linux)?
- b) Entfernen → News-Filter über alternative Quelle (welche?)
→ Antwort: ___

**E-12: Superalgos — Committen oder entfernen?**
- a) Committen → Integration spezifizieren
- b) Entfernen → „potenziell" rausnehmen
→ Antwort: ___

**E-13: CUA (Computer Use Agent) — Committen oder entfernen?**
- a) Committen → Welche Broker ohne API?
- b) Entfernen → MT5 API ist ausreichend
→ Antwort: ___

**E-14: ZMQ Serialisierung?**
- a) `msgpack_numpy` (schnell, sicher, leichtgewichtig)
- b) Apache Arrow IPC (Zero-Copy, optimal für große Arrays)
- c) Protobuf (Schema-basiert, streng typisiert)
→ Antwort: ___

**E-15: Testing-Strategie Scope für V1?**
- a) Nur Unit-Tests (pytest) für kritische Berechnungen (Entropie, SL-Berechnung)
- b) Unit + Integration (ZMQ, FastAPI Endpoints)
- c) Unit + Integration + Paper-Trading Dry-Run Modus
→ Antwort: ___

**E-16: Alerting-Kanal für SUSPEND/Killswitch?**
- a) Telegram Bot
- b) E-Mail (SMTP)
- c) n8n → Super Productivity
- d) Mehrere Kanäle
→ Antwort: ___

---

## 📦 PHASE 1: Abarbeitbare Sprint-Pakete

> Jedes Paket ist ein `/doc-chapter`-Aufruf. Die Tasks sind so formuliert, dass Gemini sie direkt als Kapitel-Erweiterung schreiben kann.

---

### Sprint 1: Kap. 03 — Kern-Entscheidungslogik fixieren
**Voraussetzung:** E-01 (Short-Logik), E-02 (Timeframe)

- [ ] **§5 NEU: Decision Matrix (Signal Matrix)**
  Füge nach §4 einen neuen Abschnitt ein, der die kombinierte Entscheidungslogik zeigt:
  - Tabelle: SJM-State × Entropie-Factor → System-State
  - Referenz auf `refs/papers/jump-models.md` (die Matrix dort)
  - Klärung: Wann wird State `-1` (Short) produziert? (abhängig von E-01)

- [ ] **§1 Update: Entropie-Features benennen**
  Ergänze im Gatekeeper-Abschnitt eine Referenz, dass die 5 konkreten Features (RSI, BBW, NATR, VolOsc, CMF) in der Ref-Datei spezifiziert sind. Aktueller Text sagt nur „5-Feature-Korrelationsmatrix" ohne die Features zu nennen oder explizit auf die Ref zu verweisen.

---

### Sprint 2: Kap. 04 — Execution Layer vervollständigen
**Voraussetzung:** E-05 (Hedging/Netting), E-06 (EA Design), E-07 (IPC), E-08 (Prop-Firm), E-09 (State Transitions), E-10 (Trailing SL)

- [x] **§5 NEU: Trade Lifecycle (State Transitions)**
  Definiere exakt:
  - Was passiert bei `1→0`, `1→-1`, `-1→0`, `-1→1`
  - Berücksichtige Hedging vs. Netting (E-05)
  - Trailing-SL / Partial-Close Strategie (E-10)

- [x] **§2 Update: MQL5 EA-Architektur detaillieren**
  Ergänze:
  - Ein EA oder pro Symbol (E-06)
  - Python↔MQL5 IPC-Methode (E-07)
  - Thread-Safety: Alle `mt5.*` Calls durch `threading.Lock()` serialisieren (MT-04)
  - Hinweis: `GlobalVariableSet()` limitation (64KB, double-only, Restart-Verlust)

- [x] **§4 Update: Risk-Diktator erweitern**
  Ergänze:
  - Volume Normalization (`volume_step` Check) (MT-01)
  - Stop-Level Validation (`trade_stops_level` Mindestabstand) (MT-02)
  - Post-Send Reconciliation (`positions_get()` Check nach `order_send()`) (MT-03)
  - News-Auto-Close: X Minuten vor High-Impact Events (aus Ref migrieren) (G-13)
  - Daily Loss: Berechnung gegen Midnight-Balance (Timezone-aware, E-08) (PF-01)

- [x] **§6 NEU: Prop-Firm Compliance Module**
  Neuer Abschnitt:
  - Static vs. Trailing Drawdown (konfigurierbar) (PF-02)
  - Consistency Rules (Best-Day-Limit konfigurierbar) (PF-03)
  - Minimum Trading Days Counter (PF-04)
  - News-Blackout-Fenster (konfigurierbar pro Firm) (PF-05)
  - Weekend-Holding Regeln (konfigurierbar) (PF-06)
  - Account Phase State Machine (Challenge → Verification → Funded) (ADM-01)

---

### Sprint 3: Kap. 05 — Schnittstellen härten
**Voraussetzung:** E-14 (Serialisierung)

- [ ] **§1 Update: ZMQ-Pipeline härten**
  Ergänze:
  - Serialisierung: msgpack_numpy / Arrow statt pickle (Security!) (NET-01)
  - High-Water-Mark Settings (z.B. SNDHWM=100000) (G-22)
  - Reconnection-Handling bei VPN-Drops (Exponential Backoff) (NET-02)
  - Optional: CURVE Encryption als Defense-in-Depth (NET-03)

- [ ] **§3 Update: Watchdog-Freshness konkretisieren**
  Ergänze:
  - Freshness-Threshold: konkreter Wert (z.B. 30s für Swing Trading) (NET-04)
  - Clock-Sync Anforderung: NTP/chronyd auf beiden Maschinen, Ziel <5ms Skew (G-18)
  - SUSPEND-Eskalation: Wie wird der Mensch benachrichtigt? (E-16) (G-14)

- [ ] **§6 NEU: Error Handling & Retry-Policy**
  Neuer Abschnitt:
  - Error Taxonomy: Welche Fehler → Retry vs. Abort vs. Alert
  - `mt5.order_send()` Retcode-Handling (Requote, Invalid Stops, Market Closed)
  - FastAPI 500 → Retry mit Backoff
  - ZMQ Message Corruption → Discard + Log
  - Parquet Ferry rsync-Failure → Retry + Alert

---

### Sprint 4: Kap. 02 — Data Engine präzisieren
**Voraussetzung:** E-02 (Timeframe), E-03 (Assets), E-04 (GPU), E-11 (OpenBB)

- [ ] **§1 Update: Asset Universe & Timeframe definieren**
  Ergänze:
  - Explizite Asset-Klassen-Liste (E-03)
  - Primary Timeframe für Rolling Window (E-02)
  - Hinweis auf Volume-Indikator-Limitations bei Forex (Tick-Volume ≠ Real Volume)

- [ ] **§2 Update: Datenfenster konkretisieren**
  - `N=50` welcher Kerzen → konkreter Timeframe-Bezug

- [ ] **§4 Update: GPU-Abhängigkeit klären**
  - Falls GPU vorhanden (E-04=Ja): CUDA-Referenzen bleiben
  - Falls keine GPU: Umschreiben auf CPU-only Optimierung (NumPy, Parallel Processing)
  - Pinned Memory / Async Transfer nur relevant wenn GPU vorhanden

- [ ] **§5 NEU: External Data Layer (OpenBB) spezifizieren** (falls E-11=Committen)
  - Welche OpenBB-Endpoints
  - Auf welcher Box
  - Poll-Frequenz
  - Freshness-Handling (wie alt darf External Data sein?)

---

### Sprint 5: Kap. 07 — Infra & Security
**Voraussetzung:** E-16 (Alerting)

- [ ] **§7 NEU: Secrets Management**
  - Alle Credential-Typen auflisten (MT5, OpenBB, Tailscale, Gemini, GitHub)
  - Speicher-Strategie: `.env` Files mit Encryption oder OS Keychain
  - Rotations-Policy

- [ ] **§8 NEU: API Authentication**
  - FastAPI Endpoints: `X-API-Key` Header + HMAC Signing
  - ZMQ: CURVE Encryption Keys
  - Key-Verteilung über Tailscale

- [ ] **§9 NEU: Alerting-Pipeline**
  - SUSPEND / Killswitch → Alert-Kanal (E-16)
  - Error-Tickets → n8n → Super Productivity (vorhandenes Konzept aus Kap. 06 detaillieren)
  - Health-Monitoring der Einzelboxen (wer prüft Box 1 und Box 2?)

- [ ] **§4 Update: Startup/Shutdown Sequenz**
  - Boot-Reihenfolge: Box 1 → Box 2 → Box 3
  - Warm-up Phase: N Datenpunkte sammeln vor erster Analyse
  - Graceful Shutdown: Maintenance-Mode Signal
  - Recovery nach Totalausfall

---

### Sprint 6: Kap. 08 — Lab erweitern
**Voraussetzung:** E-04 (GPU)

- [ ] **§5 NEU: Model Validation Criteria**
  - Minimum Acceptance Metrics: Sharpe Ratio, Max DD, Information Ratio
  - Walk-Forward Analysis Requirement
  - Out-of-Sample Testing Pflicht

- [ ] **§6 NEU: Concept Drift Detection**
  - Live-Performance-Monitoring Loop in Box 2
  - Wenn Live-Sharpe < Threshold → Auto-Flag für Retraining
  - Trigger: Model-Degradation-Alert an Super Productivity

---

### Sprint 7: Kap. 01 — High-Level aktualisieren

- [ ] **§1 Update: Phantom-Tools bereinigen (nach E-11/12/13)**
  - Superalgos: committen oder „potenziell" entfernen
  - CUA: committen oder entfernen
  - OpenBB: committen mit Integration-Hinweis oder entfernen

---

### Sprint 8: Konfiguration & Testing

- [ ] **Kap. 07 §10 NEU oder Anhang: Konfigurationsmanagement**
  - Zentrale `config.yaml` Struktur mit allen Magic Numbers
  - Kategorisiert: Risk, Data, Timing, Prop-Firm, LLM
  - Hinweis auf Konfigurierbarkeit pro Prop-Firm / Account Phase

- [ ] **Kap. 09 NEU oder Anhang: Testing-Strategie** (abhängig von E-15)
  - Unit-Test Scope (Entropie, SL-Berechnung, Volume-Normalization)
  - Integration-Test Scope (ZMQ, FastAPI, Heartbeat)
  - Paper Trading / Dry-Run Modus
  - Acceptance Criteria für Lab → Live Promotion

---

### Ref-Cleanup (parallel möglich)

- [ ] `refs/tools/agent-orchestration.md`: Header `[DEPRECATED]` ergänzen. CrewAI ≠ aktuelle Architektur. Verweis auf Kap. 03 Agent Composition Model.
- [ ] `refs/tools/qlib-evaluation.md`: Zeile 22 korrigieren: „Vorlage für Box 3" → „Konzeptionelle Grundlage für Box 4 (Lab)".
- [ ] `refs/INDEX.md`: Deprecation-Marker für `agent-orchestration.md` eintragen.
- [ ] **NEU** `refs/tools/openbb-evaluation.md` anlegen (falls E-11=Committen).
- [ ] **NEU** `refs/patterns/prop-firm-compliance.md` anlegen (Details aus PF-01 bis PF-06).

---

## State-Dateien Update (nach jedem Sprint)

- [ ] `CHAPTER-STATUS.md` aktualisieren
- [ ] `PROJECT-BRAIN.md` → Offene Fragen aktualisieren (aktuell: „keine")
- [ ] `DECISIONS.md` → Neue Entscheidungen aus E-01 bis E-16 eintragen
- [ ] `DOC-SPEC.md` → Ggf. Kap. 09 in Kapitelstruktur ergänzen


========================================
FILE: SETUP-GUIDE.md
========================================
# Antigravity Doku-Workflow Setup

> Antigravity als autonomes Projektplanungs- und Dokumentationssystem nutzen —
> ohne Coding-Fokus, mit persistentem Kontext und Gemini 3.1 Pro.

---

## Konzept

Antigravity ist für Coding gebaut, lässt sich aber durch **Rules + Workflows**
vollständig umnutzen. Dieser Stack besteht aus:

| Komponente | Zweck |
|---|---|
| `GEMINI.md` | Dem Agenten erklären: "Du bist kein Coder, du bist Doku-Assistent" |
| `.agent/rules/doc-rules.md` | Immer aktive Verhaltensregeln |
| `.agent/workflows/*.md` | Slash-Commands für deinen Workflow |
| `guanyang/antigravity-skills` | Skills für Planung, Kontext, Co-Authoring |
| Persistente State-Dateien | Context Rot verhindern |

---

## Schritt 1 — guanyang Skills installieren

```bash
# Repo klonen (einmalig)
git clone https://github.com/guanyang/antigravity-skills.git ~/antigravity-skills

# Global installieren (für alle Projekte)
mkdir -p ~/.gemini/antigravity/skills
ln -s ~/antigravity-skills/skills/* ~/.gemini/antigravity/skills/
```

Danach verfügbar in Antigravity:
- `@[brainstorming]` — Anforderungen klären
- `@[doc-coauthoring]` — Kollaboratives Schreiben
- `@[writing-plans]` — Detaillierte Specs
- `@[planning-with-files]` — Dateibasiertes Planungssystem
- `@[executing-plans]` — Pläne mit Checkpoints ausführen
- `@[context-degradation]` — Context Rot diagnostizieren & fixen
- `@[memory-systems]` — Langzeit-Gedächtnis für Agenten

Updates:
```bash
cd ~/antigravity-skills && git pull
```

---

## Schritt 2 — Config-Dateien ins Projekt kopieren

Für jedes neue Dokumentations-Projekt:

```
dein-projekt/
├── GEMINI.md                        ← Kopieren aus diesem Kit
├── .agent/
│   ├── rules/
│   │   └── doc-rules.md             ← Kopieren aus diesem Kit
│   └── workflows/
│       ├── doc-init.md              ← /doc-init
│       ├── doc-chapter.md           ← /doc-chapter N
│       ├── doc-review.md            ← /doc-review N
│       └── doc-status.md            ← /doc-status
└── docs/                            ← Wird automatisch erstellt
```

### Schnell-Installation via GSD-Methode

```bash
cd dein-projekt
git clone https://github.com/toonight/get-shit-done-for-antigravity.git gsd-tmp
cp -r gsd-tmp/.agent ./ && cp -r gsd-tmp/.gemini ./ && rm -rf gsd-tmp
# Jetzt GEMINI.md und .agent/ aus diesem Kit drüberkopieren (überschreiben)
```

---

## Schritt 3 — Antigravity öffnen und starten

```
1. Antigravity öffnen → Projektordner laden
2. Im Chat: /doc-init
3. Agent stellt Fragen → du antwortest
4. Agent erstellt PROJECT-BRAIN.md, DOC-SPEC.md, CHAPTER-STATUS.md
5. Danach mit /doc-chapter 1 starten
```

---

## Der Workflow im Überblick

```
/doc-init
  → Agent fragt: Thema, Zielgruppe, Umfang, Kapitelstruktur
  → Erstellt: PROJECT-BRAIN.md + DOC-SPEC.md + CHAPTER-STATUS.md

/doc-chapter 1
  → Agent liest BRAIN + SPEC → klärt Fragen → schreibt docs/01-kapitelname.md
  → Aktualisiert CHAPTER-STATUS.md

/doc-review 1
  → Agent liest Kapitel → prüft Konsistenz, Lücken, Stil
  → Schlägt konkrete Änderungen vor → erst nach Freigabe

/doc-status
  → Überblick über alle Kapitel (fertig / offen / in Arbeit)
  → Zeigt nächste empfohlene Aktion
```

---

## Context Rot verhindern

Das größte Problem bei langen Doku-Projekten in Gemini 3.1 Pro.
Dieser Stack löst es durch:

1. **PROJECT-BRAIN.md** — Wird bei jedem Workflow als erstes gelesen
2. **CHAPTER-STATUS.md** — Aktueller Stand, immer aktuell gehalten
3. **Kurze Sessions** — Je Workflow-Call nur 1 Kapitel bearbeiten
4. **Skill nutzen** — `@[context-degradation]` wenn der Agent "vergesslich" wirkt

---

## Community-Ressourcen

- GSD für Antigravity: https://github.com/toonight/get-shit-done-for-antigravity
- guanyang Skills: https://github.com/guanyang/antigravity-skills
- Awesome Skills Katalog: https://github.com/sickn33/antigravity-awesome-skills
- Google SDD Codelab: https://codelabs.developers.google.com/sdd-adk-antigravity
- r/google_antigravity: https://reddit.com/r/google_antigravity


========================================
FILE: GEMINI.md
========================================
# Projektregeln — Dokumentations-Assistent

Du bist kein Coding-Assistent. Du bist ein **Dokumentations- und Planungsassistent**.
Deine Aufgabe ist es, strukturierte, mehrteilige Projektdokumentation zu erarbeiten —
gemeinsam mit dem Nutzer, iterativ, in klar abgegrenzten Phasen.

---

## Deine Rolle

- **Kein Code generieren**, außer es wird explizit verlangt
- **Immer Fragen stellen**, bevor du inhaltlich arbeitest
- **Konsistenz wahren** — Terminologie, Stil und Struktur bleiben über alle Kapitel gleich
- **Dateien als Gedächtnis nutzen** — vor jeder Aktion `PROJECT-BRAIN.md` und `CHAPTER-STATUS.md` lesen

---

## Pflichtverhalten

### Vor jedem Schreibvorgang
1. `PROJECT-BRAIN.md` lesen (Gesamtkontext)
2. `DOC-SPEC.md` lesen (Stil, Zielgruppe, Struktur)
3. `CHAPTER-STATUS.md` lesen (aktueller Stand)
4. Erst dann: schreiben, planen oder überarbeiten

### Dateinamen
- Kapitel: `docs/NN-slug.md` (z.B. `docs/01-einfuehrung.md`)
- Immer mit führender Zahl (01, 02, 03 ...)
- Slug: Deutsch, Bindestrich, keine Umlaute in Dateinamen

### Stil
- Sprache: Deutsch, außer der Nutzer schreibt auf Englisch
- Klar und direkt — kein Marketing-Jargon
- Technische Begriffe beim ersten Vorkommen pro Kapitel erklären
- Konsistente Terminologie (Glossar in `DOC-SPEC.md` beachten)

---

## Sicherheitsregeln

- NIEMALS Terminal-Commands ohne explizite Bestätigung ausführen
- NIEMALS Dateien außerhalb des Projektordners lesen oder schreiben
- Vor destruktiven Aktionen (Datei löschen, überschreiben): immer fragen

---

## Kontext-Degradation

Wenn du merkst, dass dein Kontext unvollständig ist:
1. Sage es explizit: "Ich lese nochmal die State-Dateien"
2. Lese `PROJECT-BRAIN.md`, `DOC-SPEC.md`, `CHAPTER-STATUS.md`
3. Fahre erst danach fort

Nutze `@[context-degradation]` wenn das Problem anhält.

---

## Workflow-Referenz

| Command | Zweck |
|---|---|
| `/doc-init` | Neues Doku-Projekt initialisieren |
| `/doc-chapter N` | Kapitel N schreiben |
| `/doc-review N` | Kapitel N reviewen und verbessern |
| `/doc-status` | Projektstand anzeigen |

@./.agent/rules/doc-rules.md


========================================
FILE: CLINE.md
========================================
# Cline-Regeln — Hybrid AI-Trading System

> Du bist ein **Dokumentations-, Planungs- und Coding-Assistent** für das Hybrid AI-Trading System.
> Diese Datei ist bei JEDER Session zu laden — vor jeder Aktion.

---

## 1. PULL-PROCESS-PUSH Zyklus (PFLICHT)

### PULL — Vor JEDEM Task MUSS ich lesen:

**Immer:**
1. `PROJECT-BRAIN.md` — Gesamtkontext und getroffene Entscheidungen
2. `DECISIONS.md` — Veto-Log: Welche Richtungen wurden abgelehnt/fixiert?
3. `CHAPTER-STATUS.md` — Was ist fertig, was ist offen?

**Bei Doku-Tasks zusätzlich:**
4. `DOC-SPEC.md` — Stil, Zielgruppe, Kapitelstruktur, Glossar
5. `TEST-LAB-LOG.md` — Bisherige Learnings und bekannte Fehler (falls vorhanden)

**Bei Coding-Tasks zusätzlich:**
4. `docs/98-implementation-guide.md` — Contracts, Mocks, Konventionen (PFLICHT!)
5. `IMPL-STATUS.md` — Welche Tasks sind offen, in progress, blockiert?

**Kein Raten. Keine Annahmen.** Wenn eine Datei nicht existiert, sage ich es explizit.

### PROCESS — Aufgabe bearbeiten:
- Chatlog evaluieren
- Schnittstellen extrapolieren
- Kapitel verfassen (`docs/...`) ODER Code + Tests schreiben (via `/implement`)

### PUSH — NACH jedem Task MUSS ich updaten:
1. `CHAPTER-STATUS.md` → Status setzen, Datum eintragen
2. `PROJECT-BRAIN.md` → Neue Erkenntnisse ergänzen
3. `DECISIONS.md` → Neue Veto/Korrekturen loggen (Typ, Datum, Begründung)
4. Bei Coding-Tasks: `IMPL-STATUS.md` → Task-Status updaten

**Erst wenn die State-Dateien geupdatet sind, ist der Job "Done".**

---

## 2. Dokumentationsstil

### Sprache
- **Deutsch**, technisch präzise, kein Marketing-Jargon
- Glossar aus DOC-SPEC.md strikt beachten
- Abkürzungen beim ersten Vorkommen pro Kapitel ausschreiben

### Kapitelstruktur (PFLICHT)
```markdown
# [Kapitelname]

*[Kurze Zusammenfassung, 2-3 Sätze, kursiv]*

## [Hauptabschnitt]
[Inhalt]

### [Unterabschnitt]
[Inhalt]

---
→ Verwandte Kapitel: [Kapitel N: Titel] | [Kapitel M: Titel]
```

### Dateinamen
- `docs/NN-slug.md` (z.B. `docs/01-system-architektur.md`)
- Führende Zahl (01, 02, 03...)
- Slug: Deutsch, Bindestrich, keine Umlaute

### Qualitätsregeln
- Keine Lückenfüller ("Dies ist wichtig", "Wie bereits erwähnt")
- Keine Wiederholungen des vorherigen Satzes
- Konkrete Beispiele statt abstrakter Beschreibungen
- Listenelemente parallel formulieren (alle Nomen ODER alle Verben, nicht gemischt)
- Überschriften-Hierarchie: `#` nur Dateititel, `##` Hauptabschnitte, `###` Unterabschnitte
- Maximale Kapiteltiefe: `####`

---

## 3. Test-Lab Evaluationsmodus

Ich befinde mich permanent im **Test-Lab Evaluationsmodus**. Ich muss mein Verhalten transparent machen.

### 3-Stufen Entscheidungslogik

**Stufe 1 — Direkt ausführen** (eindeutig, ≤1 Schritt)
- Sofort liefern
- Kurze Test-Lab-Notiz am Ende (Ampel + Score + 1 Optimierungspunkt)

**Stufe 2 — Micro-Plan** (klar, 2-5 Schritte)
1. Verständnis (2-5 Punkte)
2. Offene Punkte / Risiken
3. Vorschlag für nächsten Schritt
4. Ausführen
5. Vollständige Test-Lab-Notiz

**Stufe 3 — Full Plan** (mehrdeutig, riskant, >5 Schritte)
1. Volles 5-Punkte-Raster
2. **Freigabe abwarten** vor Execution
3. Vollständige Test-Lab-Notiz

**Grenzfälle:** Immer eine Stufe HÖHER wählen. Lieber zu viel planen als zu wenig.

### Scoring-Rubric (nach jeder Stufe 2+3 Antwort)

| Dimension | 1 (schlecht) | 5 (perfekt) |
|---|---|---|
| **V** — Verständnis | Aufgabe falsch verstanden | Sofort präzise verstanden, Kontext geprüft |
| **P** — Planung | Kein Plan, Chaos | Minimal, präzise, jeder Schritt hat klaren Zweck |
| **U** — Unsicherheits-Management | Unsicherheit ignoriert | Sofort identifiziert, priorisiert, adressiert |
| **R** — Regelkonformität | Rules ignoriert | Rules proaktiv geprüft, korrekt angewendet |
| **E** — Effizienz | Massiv aufgebläht | Minimal notwendig, kein überflüssiger Satz |

**Ampellogik:**
- 🟢 grün: Alle ≥ 3, kein Wert = 1
- 🟡 gelb: Mind. eine = 2 ODER Gesamt < 18
- 🔴 rot: Mind. eine = 1 ODER Gesamt < 13

**Score-Format:**
```
Test-Lab-Notiz
- Status: 🟢/🟡/🔴
- Score: V:_ P:_ U:_ R:_ E:_ = __/25
- Größtes Risiko: [spezifisch]
- Sinnvollste Optimierung: [konkret]
```

---

## 4. Anti-Patterns (VERBOTEN)

| Anti-Pattern | Bedeutung |
|---|---|
| ❌ Fakten-Fiktion | Annahmen als bestätigte Fakten darstellen |
| ❌ Scope Creep | Stille Erweiterungen — keine unangefragten Features |
| ❌ Wort-Wüste | Unnötig lange Antworten ohne klare Struktur |
| ❌ Sicherheits-Fassade | Vorgetäuschte Sicherheit bei vagen Anforderungen |
| ❌ Stil vor Substanz | Eleganz vor Denkqualität |
| ❌ Halluzinierte Pfade | Dateipfad referenzieren, ohne gelesen zu haben |
| ❌ Phantom-Bestätigung | Behaupten, etwas sei geändert, ohne es getan zu haben |
| ❌ Compliance Theater | Regeln zitieren, aber nicht befolgen |
| ❌ Confident Hallucination | Unsicherheit mit eloquenter Sprache überdecken |
| ❌ Grün-Bias | Test-Lab-Notiz reflexartig auf grün setzen |
| ❌ Cargo-Cult-Planung | Raster ausfüllen, ohne nachzudenken |
| ❌ Antwort-Eskalation | Essay auf eine Ja/Nein-Frage |
| ❌ Routing Modification | Eigenmächtiges Ändern, Umbennen oder Modifizieren von Agenten-Inboxes oder Handoff-Routing-Pfaden |


---

## 5. Runtime & Framework Commands (BMAD / GTD)

Diese Slash-Commands fungieren als "State Machine Trigger". Sie steuern den PULL/PROCESS/PUSH Zyklus und sichern die Integrität unserer Wissensdatenbank (SuperBrain), indem sie harte Logikkettenprüfungen und das Suchen nach "Blind Spots" erzwingen.

### 5.1 Cline Runtime (Integrität der Wissensbasis)
- `@pull.md` → **State Sync:** Erzwingt sofortigen Re-Read der 4 Core-Dateien (`PROJECT-BRAIN.md`, `DOC-SPEC.md`, `CHAPTER-STATUS.md`, `DECISIONS.md`). Verhindert Context-Drift und Sichert den aktuellen Entwicklungsstand.
- `@push.md` → **State Commit:** Beendet den aktuellen Task. Schreibt autonom Fortschritte, offene Knotenpunkte und Status-Updates sauber in die Core-Dateien zurück.

### 5.2 GTD Framework (Workflow & Actionability)
- `@capture.md [Text/Idee]` → **Inbox:** Nimmt lose Gedanken, offene Strukturfragen oder Code-Konzepte auf und legt sie asynchron als Backlog-Ticket/Inbox ab, ohne den aktuellen Fokus und Kontext der aktuellen Ausarbeitung zu zerstören.
- `@clarify.md [Kapitel/Konzept]` → **Deep Logic Check:** Vor dem Dokumentieren prüft Cline die Anforderung aktiv auf Unbedachtes ("Blind Spots"). Sind alle architektonischen Logikketten von Box 1 (Data) bis Box 3 (MT5) valide bedacht? Widerspricht etwas dem Veto-Log (`DECISIONS.md`)?
- `@ticket.md [Für X] [Problem]` → **Agent Handoff:** Beauftragt formal einen anderen System-Agenten (z.B. Rick) via `00-System/handoff-protocol.md` mit einer Execution in Box 1 oder 3.

### 5.3 Test-Lab & BMAD (Validierung)
- `@evaluate.md` → Triggert manuell das harte 5-Punkte Test-Lab Raster zur sofortigen Selbstüberprüfung meiner Logik.
- `@bmad.md [Problem]` → Build-Measure-Analyze-Decide: Triggert eine systematische Lösungsfindung bei Dokumentations-Widersprüchen oder Architektur-Konflikten. Stoppt jeden Code/Text, um rein logisch eine Problem-Hypothese aufzustellen.

---

## 6. Perplexity MCP Integration

Bei Recherchen zu Trading-Konzepten, API-Dokumentationen, Prop-Firm-Regeln oder akademischen Papers nutze ich:

```xml
<use_mcp_tool>
<server_name>github.com/pashpashpash/perplexity-mcp</server_name>
<tool_name>search</tool_name>
<arguments>
{
  "query": "Suchanfrage hier",
  "detail_level": "normal"
}
</arguments>
</use_mcp_tool>
```

Für technische Dokumentation:
```xml
<use_mcp_tool>
<server_name>github.com/pashpashpash/perplexity-mcp</server_name>
<tool_name>get_documentation</tool_name>
<arguments>
{
  "query": "Technologie/API",
  "context": "Spezifischer Kontext"
}
</arguments>
</use_mcp_tool>
```

---

## 7. Kontext-Degradation

Wenn ich merke, dass mein Kontext unvollständig ist:
1. Sage es EXPLIZIT: "Ich lese nochmal die State-Dateien"
2. Lese `PROJECT-BRAIN.md`, `DOC-SPEC.md`, `CHAPTER-STATUS.md`, `DECISIONS.md`
3. Fahre erst danach fort

---

## 8. Persistenz: TEST-LAB-LOG.md

**Wann eintragen:**
- Bei jeder Dimension mit Score ≤ 2 (PFLICHT)
- Bei wiederholten Mustern (empfohlen)
- Bei Nutzer-Kritik (PFLICHT)

**Format:**
```markdown
## YYYY-MM-DD | [Kontext] | [Kategorie] | [Dimension]: [Score]

- **Aufgabe:** Was war der Auftrag?
- **Problem:** Was ist schiefgelaufen?
- **Ursache:** Warum? (Root Cause)
- **Korrektur:** Was habe ich korrigiert?
- **Nutzer-Feedback:** [Optional]

---

## 9. Multi-Agent Koordination & Task Management

Um Konflikte in einem System mit mehreren Agenten (z. B. lokaler Cline vs. VPS-Rick) zu vermeiden, gelten harte Koordinationsregeln:

### 9.1 State-Dateien & Supervisor-Rolle
- **Nur der ausführende Supervisor-Agent** (oft lokaler Cline, da am nächsten am Git-Repo) hat Schreibzugriff auf die Core-State-Dateien (`PROJECT-BRAIN.md`, `CHAPTER-STATUS.md`, `DECISIONS.md`, `30-Kanban/Main Kanban.md`).
- Task-Agenten (z. B. ein Code-Reviewer oder ein extern modellierter Agent in der Inbox) werfen ihre Ergebnisse nur in die `Inbox` (z. B. als `@ticket.md`).
- Der Supervisor nimmt die Tickets aus der Inbox, prüft sie und trägt die Ergebnisse verifiziert in die State-Dateien ein.

### 9.2 Datei-Modifikationen (Safety First)
- Bei Änderungen an bestehenden Codes oder Konfigurationen ist die Such-und-Ersetzen-Methode (`old_text` / Regex oder `replace_file_content` via Tool) dem blinden Einfügen vorzuziehen. Überschreibe nie eine Datei komplett, wenn du nur zwei Zeilen änderst.

### 9.3 Dependencies zwischen Sprints
- Blockierende Abhängigkeiten zwischen Sprints müssen in den Metadaten des Tickets oder im Kanban (Backlog) explizit vermerkt werden (`depends_on: [ID]`). Ein Sprint wird NICHT gestartet, wenn sein Blocker noch in `Todo` oder `In Progress` ist.

### 9.4 Kontext-Übergabe (Handoffs)
- Für die Übergabe an andere Agenten ist ZWINGEND das `@ticket.md` (Inbox-Prinzip) zu nutzen. Kein "Zuruf" über Chat. Der Kontext muss deterministisch in Form einer `.md` Datei im entsprechenden Agent-Inbox-Ordner liegen.

### 9.5 Auto-Review Modus
- Bevor ein komplexer Task auf "Done" (`[x]`) gesetzt wird, triggert der Agent bei sich selbst einen logischen Review (`@evaluate.md`). Nur bei grüner Ampel wird in die State-Dateien gepusht.

========================================
FILE: TEST-LAB-LOG.md
========================================
# Test-Lab Log

> Chronologische Learnings aus der Test-Lab Evaluationsphase.
> Wird automatisch befüllt bei Score ≤ 2 in einer Dimension.
> Wird zu Beginn jeder Session gelesen.

---

<!-- Einträge ab hier -->

## 2026-04-06 | Multi-Agent Koordination | Fehler | R: 1

- **Aufgabe:** Multi-Agent State Sync
- **Problem:** `CHAPTER-STATUS.md` wurde korrumpiert (Format / Inhalte zerstört).
- **Ursache:** "Task-Agenten" (oder untergeordnete Prozesse) griffen gleichzeitig auf Core-State-Dateien zu und überschrieben sich gegenseitig.
- **Korrektur:** `CLINE.md` um Abschnitt 9 erweitert. Klare Trennung: Nur der Meta-/Supervisor-Agent darf State-Dateien modifizieren.
- **Regel-Vorschlag:** 9.1 State-Dateien nur vom Supervisor schreiben lassen.


========================================
FILE: docs/00-MOC-Trading-System.md
========================================
---
aliases: [MOC, Map of Content, Übersicht]
tags: [moc, index]
trust: canonical
last_reviewed: 2026-04-19
---
# 🗺️ Map of Content — Hybrid AI-Trading System

*Zentrales Inhaltsverzeichnis für die kanonische Architekturdokumentation des 3+1 Blackbox Systems.*

---

## Architektur & Design

| Nr | Kapitel | Fokus |
|---|---|---|
| **01** | [[01-system-architektur\|System-Architektur & 3+1 Blackbox Design]] | Physischer Split (Brain vs. Muscle), Kommunikationstabelle, Validation Layer, Verworfene Konzepte |
| **10** | [[10-configuration\|Konfigurationsmanagement & Split-Brain Protection]] | SSOT: Config-Hash, Pydantic Schemas, Payload Hash-Locking |

## Die Blackboxen (Box 1–4)

| Nr | Kapitel | Box | Fokus |
|---|---|---|---|
| **02** | [[02-blackbox-data\|Blackbox 1: Data Engine]] | Box 1 (Win) | Asset Universe, Timeframes, Normalisierung, OpenBB Context Layer |
| **03** | [[03-blackbox-agents\|Blackbox 2: The Scientist]] | Box 2 (Linux) | Gatekeeper, Agenten-Orchestrierung, Scout/Manager, Fusion, Decision Matrix |
| **04** | [[04-blackbox-mt5\|Blackbox 3: MT5 Execution Bridge]] | Box 3 (Win) | Trade Lifecycle, Risk-Diktator, Prop-Firm Compliance, Graceful Degradation |
| **08** | [[08-backtesting-lab\|The Improvement Lab]] | Box 4 (Linux) | Backtesting (ffn + QuantStats), MLflow, Model Promotion, RL/Graph Training |

## Schnittstellen & Kommunikation

| Nr | Kapitel | Fokus |
|---|---|---|
| **05** | [[05-schnittstellen\|API & Schnittstellen-Spezifikation]] | SSOT: ZMQ Pipeline, REST Handshake, Heartbeat/IPC, Parquet Ferry, Error Handling |

## Infrastructure & Operations

| Nr | Kapitel | Fokus |
|---|---|---|
| **07** | [[07-memory-and-infra\|The OS: Memory & Infrastructure]] | Git-Memory, OpenClaw, VPS Hardening, Tailscale VPN, Deployment Pipeline, Observability, Secrets, Projektmanagement |
| **09** | [[09-testing-strategie\|V1 Testing-Strategie]] | Test-Pyramide, Unit/Integration/System Tests, Paper Trading, CI/CD Runner |
| **98** | [[98-implementation-guide\|Umsetzungsleitfaden — Von Architektur zu Code]] | Human Prerequisites, Mock-Architektur, Coding-Konventionen, Interface Contracts, Phasenplan |
| **99** | [[99-deploy-runbook\|Deploy & Ops Runbook]] | Copy-Paste Runbook, Rollback-Mechanismus, Log-Rotation, Disaster Recovery |

---

## Single Sources of Truth (SSOT) Verzeichnis

| Konzept | Kanonische Stelle | Andere Kapitel verweisen nur |
|---------|-------------------|------------------------------|
| `config_hash` & Split-Brain Protection | **Kap. 10** | 01, 04, 05, 07 |
| `SUSPEND` & Graceful Degradation (IPC) | **Kap. 05 §3** | 01, 04, 99 |
| Double-Dip Prevention | **Kap. 03 §3** | 04, 05 |
| Parquet Ferry (Technik) | **Kap. 05 §4** | 02, 08 |
| Parquet Ferry (Lab-Verarbeitung) | **Kap. 08 §2** | — |

---

*Zuletzt aktualisiert: 2026-04-19 — Docs Audit Refactoring*


========================================
FILE: docs/01-system-architektur.md
========================================
---
aliases: []
tags: []
related: [[00-MOC-Trading-System]]
trust: canonical
last_reviewed: 2026-04-19
---
# 01. System-Architektur & 3+1 Blackbox Design

*[Diese Architekturübersicht skizziert das grundlegende 3+1 Blackbox-Paradigma des Hybrid AI-Trading Systems. Sie dokumentiert die strikte physische und logische Isolation der Module zur Wahrung von Systemstabilität, Latenz-Optimierung und Risikominimierung.]*

## 1. Das 3+1 Blackbox Paradigma

Die Architektur des Systems verabschiedet sich von monolithischen Trading-Ansätzen, bei denen Datenabruf, Strategieauswertung und Order-Exekution im selben Skript passieren. Stattdessen wird eine strikte Trennung in drei Live-Pipeline-Boxen vollzogen. Eine 4. Box ("The Improvement Lab", rein offline) ergänzt das System für Backtesting und RL-Training.

**Physischer Split ("Brain vs. Muscle"):** 
- **Box 1 (Data) & Box 3 (MT5 Bridge)** laufen nativ auf einem **Windows Server**, da die essentielle MetaTrader5-Python-Bibliothek zwingend ein Windows-Betriebssystem erfordert.
- **Box 2 (Agents) & Box 4 (Lab)** laufen vollständig separiert auf einem **Hetzner Linux VPS**. Das System ist in V1 streng auf CPU-Berechnungen (via NumPy, paralleles Processing) ausgelegt, da Serverseitig keine Beschleunigung durch eine dedizierte GPU vorgesehen ist.
- Die Kommunikation zwischen den physisch getrennten Maschinen erfolgt sicher verschlüsselt über einen **Tailscale VPN-Tunnel**.

## 2. Die Blackboxen im Detail

### Blackbox 1: Data Engine (Input-Schicht)
Dieses Modul agiert autonom auf dem Windows-Server und dient einzig als Gateway für verlässliche Inputs: Es zieht, normalisiert und persistiert Marktdaten.
- Nutzt die direkte MT5-Verbindung für Live-Ticks und pollt weitere externe Marktdaten (Fundamental, News) über Schnittstellen wie OpenBB.
- Liefert saubere, vorverarbeitete Zeitreihen und Features an das Agenten-Netzwerk.
- Für historische Daten greift die **Parquet Ferry**-Logik: Box 1 pusht gesammelte Datensätze asynchron via Parquet-Speicherauszug an Box 4 auf das Linux-System, da dieses sonst keinen MetaTrader-Backendzugriff hat.
- → Ref: [[02-blackbox-data|Kapitel 02: Blackbox 1 Data Engine]]

### Blackbox 2: The Scientist (Agenten-Orchestrierung)
Das reine "Gehirn" des Systems, beheimatet auf dem Linux VPS. Diese Box weiß absolut nichts von APIs, Order-Typen oder Brokern. Sie liest ausschließlich Daten, interpretiert, und generiert System-Zustände.
- Sie empfängt vorverarbeitete Daten von Blackbox 1, bereitet Multi-Timeframe Arrays auf und filtert Markt-Rauschen – klassischerweise über Mechanismen wie die Entropie-Berechnung (vgl. Arella's *Entropy Inversion Hypothesis*). → Ref: [[market-folding|Market Folding]]
- Ein Agent Composition Model (Regime-Klassifizierer) verarbeitet Informationen auf CPU-Basis und generiert strenge, diskrete Target-States: `0` (Neutral/Exit) oder `1` (Long). **Short-Positionen (`-1`) sind in V1 des Systems architektonisch ausgeschlossen**.
- Integriert deterministische Workflows über *OpenClaw* als zentrale "Control Plane", verzichtet auf undefinierte Vektor-Caches (Context Poisoning Schutz).
- → Ref: [[03-blackbox-agents|Kapitel 03: Blackbox 2 Agents]]

### Blackbox 3: MT5 Execution Bridge (Ausführung)
Die ausführende "Muskel"-Schicht. Wiederum lokalisiert auf dem Windows-Server direkt am MT5 Terminal.
- Empfängt die hoch-abstrakten States (0/1) via REST-API (`POST /api/v1/signal`) und übersetzt sie in tatsächliche MetaTrader-Kommandos inklusive der dynamischen Positionsgrößen-Skalierung durch den **Capital Allocator** (basierend auf der Confidence der Agenten).
- Beinhaltet das **harte Risikomanagement**: Überwacht Prop-Firm Compliance-Limits (Equity Kills), verantwortet initiale Stop-Losses, Break-Even Schubsereien (`1R`) und Partial Closes.
- **Graceful Degradation:** Fällt das Linux-Hirn ab oder aus, gerät das Windows-Terminal nicht in Panik. Das Sicherheitskonzept basiert auf dem Heartbeat-Protokoll und dem `SUSPEND`-Modus. → Ref: [[05-schnittstellen|Kap. 05 §3: Watchdog & Graceful Degradation (SSOT)]]
- → Ref: [[04-blackbox-mt5|Kapitel 04: Blackbox 3 MT5 Bridge]]

### Box 4: The Improvement Lab (Offline)
Die vollständig vom Live-Betrieb isolierte Sandbox auf dem Linux-System (siehe dediziertes Kapitel).
- Dient exklusiv dem RL-Training und Graph Network Trainingsablauf, Backtesting auf den per *Parquet Ferry* importierten Dumps, und der Optimierung vor Überführung in den Live-Hotpath.
- → Ref: [[08-backtesting-lab|Kapitel 08: The Improvement Lab]]

## 3. Kommunikation & Schnittstellen

Die physisch getrennten Boxen kommunizieren über definierte Protokolle:

| Verbindung | Protokoll | Richtung | Zweck |
|---|---|---|---|
| Box 1 → Box 2 | ZMQ (msgpack_numpy) | Win → Linux | Live-Feature-Stream |
| Box 2 → Box 3 | REST (FastAPI, JSON) | Linux → Win | State-Signal + config_hash |
| Box 2 ↔ Box 4 | Dateisystem (Linux) | Lokal | Model-Loader, Staging |
| Box 1 → Box 4 | Rsync (Parquet Ferry) | Win → Linux | Historische Daten |
| Supervisor → Alle | Tailscale VPN | Bidirektional | SSH, RDP, Monitoring |

→ Ref: [[05-schnittstellen|Kapitel 05: API & Schnittstellen-Spezifikation]]

## 4. Validation Layer

Bevor ein Signal (`0` oder `1`) überhaupt physisch von Blackbox 2 zur MT5 Bridge gefunkt wird, muss es einen Gateway-Server passieren:
- **Compliance-Check:** Zeigt die Marktentropie noch gesunde Faltungen (Go)? Drohen Black-Swan-News in x Minuten? Sind die Drawdown-Limit-Protokolle sicher?
- **Config-Hash Validation:** Box 3 prüft den `config_hash` im REST-Payload gegen die lokale Config. Bei Mismatch: `SUSPEND`. → Ref: [[10-configuration|Kap. 10: Split-Brain Protection (SSOT)]]
- Nur einwandfrei verifizierte, allen strengen Regime-Regeln (Static DD, Trailing DD Limit) entsprechende Signale werden überhaupt erst zur Ausführung übergeben. Schlägt der Check fehl, ist das endgültige Signal der Blackbox 2 automatisch `0` und das System exekutiert rein sein passives Trailing-Risikomanagement in Box 3.

## 5. Verworfene Konzepte (Phantom-Tools)

*Diese Tools/Ansätze wurden explizit erwogen, aber per DECISION.md verworfen. Sie dürfen NICHT in Architektur-Überlegungen einfließen.*

| Konzept | Status | Grund | Entscheidung |
|---|---|---|---|
| **CUDA Streams / Pinned Memory** | ❌ VERWORFEN | Keine GPU auf Hetzner VPS vorhanden. CPU-only Architektur. | 2026-04-05 `FIX` |
| **QuantConnect / VectorBT Live** | ❌ VERWORFEN | Latenz- und Kontroll-Priorität. Direkte Python↔MT5 Bridge gesetzt. | 2026-04-05 `SCOPE` |
| **Vektor-Datenbanken (OpenFang, SQLite)** | ❌ VERWORFEN | Context Poisoning Risiko. Deterministisches Git-Memory bevorzugt. | 2026-04-05 `RICHTUNG` |
| **CUA (Computer Use Agent / Maus-Klick)** | ❌ VERWORFEN | MT5 API als einziger Execution-Tunnel ausreichend. | 2026-04-05 `SCOPE` |
| **State `-1` (Short-Positionen in V1)** | ❌ VERWORFEN | V1 handelt ausschließlich Long. Reduziert Komplexität. | 2026-04-05 `SCOPE` |
| **Firebase / React-Web (Kiebitz Stack)** | ❌ VERWORFEN | Web-Overhead würde OpenClaw-Setup destabilisieren. | 2026-04-05 `RICHTUNG` |
| **Dead Man's Switch (Kill All bei Ping-Loss)** | ❌ VERWORFEN | Graceful Degradation ersetzt. Broker-Side SL schützt Positionen. | 2026-04-05 `RICHTUNG` |

---
→ Verwandte Kapitel: [[02-blackbox-data|Kapitel 02: Blackbox 1 Data Engine]] | [[03-blackbox-agents|Kapitel 03: Blackbox 2 Agents]]


========================================
FILE: docs/02-blackbox-data.md
========================================
---
aliases: []
tags: []
related: [[00-MOC-Trading-System]]
trust: canonical
last_reviewed: 2026-04-19
---
# 02. Blackbox 1: Data Engine

*Die isolierte Input-Schicht ist verantwortlich für die lückenlose Beschaffung, Normalisierung und das asynchrone Routing von Marktdaten.*

---

## §1 Asset Universe & Timeframe Definition

### Explizite Asset-Klassen

| Asset-Klasse | Kategorie | Ziel-Produkt | Architektur-Status |
|--------------|-----------|--------------|--------------------|
| **Krypto (Spot/CFD)** | `crypto` | **Bitcoin (BTC)** | **MVP (Priorität 1)** |
| **Aktien (CFD)** | `stocks` | z.B. AAPL, TSLA | Pilot-Phase |
| **FOREX Majors** | `fx_major` | EURUSD, GBPUSD | Skalierbar (V2) |
| **Indices / Commodities**| `idx/comm` | SPX, XAUUSD | Skalierbar (V2) |

> **Architektur-Entscheidung (E-03):** Das initiale **MVP Asset-Universum** fokussiert sich exklusiv auf **Bitcoin** (und ggf. eine strukturierte Aktie). Die Daten-Pipeline ist jedoch generisch gebaut und für das gesamte MT5/FTMO-Universum voll skalierbar.

### Primary Timeframe

| Parameter | Wert | Begründung |
|-----------|------|------------|
| **Primary TF** | `M5` | Balance zwischen Signal-Frequenz und Noise-Filterung |
| **Übergeordneter TF (Context)** | `H1` | Trendausrichtung und Divergenz-Erkennung |
| **Historisches Fenster** | `H4` | Mean-Reversion-Zonen und S/R-Level |

### Volume-Indikator Limitations

| Indikator | Status | Begründung |
|-----------|--------|------------|
| **Tick Volume** | ✅ Aktiv | Primäre Volumen-Metrik aus MT5 |
| **Real Volume** | ⚠️ Limitiert | Nur für Assets mit echter Börsenanbindung |
| **OBV** | ✅ Aktiv | Berechnung auf Basis verfügbarer Tick-Daten |
| **VWAP** | ✅ Aktiv | Intra-Bar-VWAP für M5-Kerzen |
| **Volume Profile** | ❌ Deaktiviert | Requiriert Tick-Level-Daten >10Hz |

> **Hinweis:** Volume-Signale werden nur als Bestätigung (Confirmation), nicht als primärer Trigger eingesetzt.

---

## §2 Datenfenster Spezifikation (N=50)

### Window-Konfiguration

| Parameter | Kerzen-Fenster (N) | Logischer Timeframe-Bezug (M5 Base) |
|-----------|--------------------|---------------------------------|
| **Primary Rolling Window** | `N=50` | `M5` (250 Minuten = ca. 4 Stunden Live-Aktion) |
| **Context Window (Trend)** | `N=8` | `H1` (8 Stunden = Repräsentiert MTF-Trendrichtung) |
| **Historic Window (S/R)** | `N=30` | `H4` (120 Stunden = Wöchentliche Support/Resistance-Zonen) |

**Feature-Matrix (pro M5-Kerze):** OHLCV (5), Returns (4), Volatility (3), Momentum (3) = **15 Features × 50 = 750 Inputs** pro Inferenz-Schritt auf dem primären Timeframe.

### Window-Management

| Modus | Beschreibung | Anwendungsfall |
|-------|--------------|----------------|
| **Sliding Window** | Kontinuierliches Shifting um 1 Kerze | Live-Inferenz |
| **Snapshot Window** | Fixes Window bei Signal-Generierung | Backtesting |

---

## §3 Normalisierungs-Pipeline

Die rohen Datenströme werden in Blackbox 1 vorverarbeitet, um Blackbox 2 (The Scientist) optimal aufbereitete Machine-Learning-Features für die schnelle Inferenz durch prä-trainierte Modelle zu liefern:

- **Feature Engineering:** Berechnung fundamentaler ML-Inputs wie Log-Returns oder Downside Deviation anstelle von nicht-stationären Rohpreisen.
- **Array-Konditionierung:** Aufbereitung statischer Datenfenster (N=50) für die Korrelationsmatrix der Entropie-Berechnung.
- **Z-Score Normalisierung:** Pro Feature über das aktive Window mit rolling mean/std.
---

## §4 CPU-Only Optimierung

> **Architektur-Entscheidung (E-04):** Das System läuft **ausschließlich auf CPU**. Da auf dem Hetzner Linux VPS faktisch keine dedizierte GPU vorhanden ist, entfällt auch GPU-gestütztes Training im Improvement Lab. Frühere Konzepte wie *CUDA Streams*, *Pinned Memory* oder asynchrone VRAM-Transfers sind hiermit strikt aus der gesamten Architektur verbannt.

### NumPy-basierte Berechnungen

| Komponente | Implementierung | Begründung |
|------------|-----------------|------------|
| **Array-Operationen** | `numpy.ndarray` | Vektorisierte Berechnungen ohne Python-Loops |
| **Rolling Windows** | `numpy.lib.stride_tricks.sliding_window_view` | Memory-effiziente Window-Generierung |
| **Statistik** | `numpy.typing.ArrayLike` + `scipy.stats` | Parallele Verteilung auf CPU-Cores |
| **Matrizen-Multiplikation** | `numpy.dot` / `@` Operator | Optimiert für CPU-Cache-Lines |

### Parallel Processing (NumPy-basiert)

```python
import numpy as np
from concurrent.futures import ThreadPoolExecutor

def process_symbol_data(symbol: str, timeframe: str, n: int = 50) -> np.ndarray:
    rates = mt5_copy_rates(symbol, timeframe, n)
    closes = rates['close']
    log_returns = np.diff(np.log(closes))
    volatility = np.array([np.std(log_returns[max(0,i-14):i+1]) for i in range(14, len(log_returns))])
    return np.column_stack([closes[-n:], log_returns[-n:], volatility[-n:]])

symbols = ['EURUSD', 'GBPUSD', 'USDJPY']
with ThreadPoolExecutor(max_workers=3) as executor:
    results = list(executor.map(lambda s: process_symbol_data(s, 'M5'), symbols))
```

### Performance-Budget

| Operation | Max. Latenz | Budget |
|-----------|-------------|--------|
| MT5 Data Fetch | 50ms | Echtzeit |
| N=50 Window Generierung | 10ms | Echtzeit |
| Feature-Berechnung (N=50) | 5ms | Echtzeit |
| **Total Round-Trip** | 65ms | < 100ms Ziel |

---

## §5 External Data Layer (OpenBB Integration)

Die External Data Layer liefert **kontextuelle Zusatzdaten** für Meta-Filter und Regime-Erkennung. Sie ist **nicht** Teil des Execution-Data-Pfads.

### Box-Zugehörigkeit & Infrastruktur

> **Architektur-Entscheidung (External Data):** Das OpenBB SDK wird aus Gründen der Lastenverteilung und OS-Abhängigkeit auf **Box 2 (Linux VPS)** gehostet. Box 1 (Windows) widmet sich zu 100% dem latenzkritischen MT5-Tick-Stream. Box 2 pollt OpenBB autonom und injiziert die Meta-Daten direkt in die Inference-Pipeline der Agenten.

```text
┌─────────────────────────────────────────────────────────────────┐
│              EXTERNAL DATA LAYER (BOX 2 - LINUX VPS)            │
├─────────────────────────────────────────────────────────────────┤
│  OpenBB SDK ──► Context Provider ──► Filter-Logic ──► Blackbox 2│
│                                                                 │
│  Endpoints:                                                      │
│  ├── /economy/macro              → Regime-Indikatoren          │
│  ├── /options/volatility_surface → VIX-Analyse                  │
│  ├── /forex/quote                → Cross-Rates Context          │
│  └── /news                       → Sentiment (Backup)           │
└─────────────────────────────────────────────────────────────────┘
```

### OpenBB Endpoints & Mapping

| Endpoint | Datenpunkt | Verwendung | Refresh |
|----------|------------|------------|---------|
| `obb.economy.macro()` | GDP, CPI, PMI | Trendumgebung-Klassifikation | 15 Min |
| `obb.options.volatility_surface()` | VIX, IV-Rank | Volatilitäts-Regime | 5 Min |
| `obb.forex.quote()` | Cross-Rates | Korrelations-Matrix | 1 Min |
| `obb.news.search()` | Breaking News, NFP | Event-Risk-Filter | On-Demand |

### Poll-Frequenz & Caching

| Datenklasse | Poll-Frequenz | Cache-Dauer | Begründung |
|-------------|---------------|-------------|------------|
| **VIX/Volatilität** | 5 Min | 5 Min | Langsam variierend |
| **Macro-Indikatoren** | 15 Min | 30 Min | Tagesdaten-basiert |
| **Cross-Rates** | 1 Min | 1 Min | Kurzfristige Divergenz |
| **News** | On-Demand | 10 Min | Event-Risk-Modus |

### Freshness-Handling

```
if (cached_data_age > max_staleness):
    trigger_background_refresh()
    return stale_data_with_warning()
elif (api_available == False):
    return last_known_good()
else:
    return fresh_data()
```

| Staleness-Level | Zeit | Verhalten |
|-----------------|------|-----------|
| **Fresh** | 0-1 Min | Normale Verwendung |
| **Acceptable** | 1-5 Min | Warning-Log, Weiterverwendung |
| **Stale** | 5-15 Min | Error-Log, Fallback auf Primary TF |
| **Expired** | > 15 Min | **Graceful Degradation (Blind-Flight Context):** Inferenz fällt komplett auf MT5-Ticks zurück. **Kein Pipeline-Freeze!** Confidence-Score wird mit Penalty (`× 0.8`) abgewertet. Alert. |

> **Architektur-Entscheidung (A-3, OpenBB SPOF):** Fällt das OpenBB SDK komplett aus (z.B. Breaking Changes, Deprecation, API-Downtime), entfällt der gesamte Context Layer (VIX, Macro, Sentiment). Das System operiert dann **ausschließlich auf dem MT5-Tick-Stream** (Internal Data). Die Entropie-Berechnung in Box 2 fällt auf die 5-Feature-Matrix aus reinen Tick-Daten zurück. **Es wird in V1 bewusst kein alternativer Datenanbieter (FRED, Yahoo Finance) als Fallback integriert** — das wäre Over-Engineering. Der Confidence-Score wird stattdessen dauerhaft mit dem Penalty-Faktor belegt, bis OpenBB wieder verfügbar ist.

---

## §6 Data Health & Quality Layer

Um "Garbage In, Garbage Out" zu verhindern, implementiert Blackbox 1 automatisierte Integritätsprüfungen:

- **Lücken-Detektion:** Datenfenster (N=50) wird verworfen, falls >0,5% Ticks fehlen.
- **Volatilitäts-Anomalie-Check:** Extremwerte ohne News-Begründung werden isoliert.
- **Symbol-Konsistenz:** Abgleich Broker-Ticks vs. berechnete OHLC-Kerzen.
- **Timeframe-Continuität:** Prüfung auf Lücken im M5-Stream (>5 Min = Fehler).

---

## §7 Internal vs. External Data

- **Internal Data (Execution Critical):** Zeitreihen/Ticks für Order-Berechnung. **MÜSSEN** direkt via `mt5.copy_rates_from` vom Broker-Terminal generiert werden. **Box 1 läuft als lokaler Daemon auf demselben Windows Server wie MT5.**
- **External Data (Context Layer):** Zusatzdaten für Meta-Filter via OpenBB SDK (VIX, Macro-News, On-Chain-Daten).

---

*Weiterführend:* Wie diese sauberen Daten konkret gewichtet und für die State-Generierung genutzt werden, beschreibt [[03-blackbox-agents|Blackbox 2: The Scientist]].

========================================
FILE: docs/03-blackbox-agents.md
========================================
---
aliases: []
tags: []
related: [[00-MOC-Trading-System]]
trust: canonical
last_reviewed: 2026-04-19
---
# 03. Blackbox 2: The Scientist (Agenten-Orchestrierung)

*Dieses Modul fungiert als das abstrakte analytische Gehirn des Systems. Es integriert State-of-the-Art quant-mathematische Modelle und autonome KI-Agenten, um systematische States (0, 1) strikt abseits des "Market Noises" zu generieren. Alle Operationen sind vollständig auf CPU-Processing (NumPy, Multiprocessing) optimiert, da das Linux-VPS auf GPU-Beschleunigung verzichtet.*

## 1. Der Smarte Gatekeeper (Das 2-Stufen Wake-Up Modell)

Um Rechenkapazität (und LLM-Token) zu sparen, wachen die Agenten nicht zeitgesteuert (z.B. alle 5 Minuten) auf. Das System unterliegt stattdessen einem ereignisgesteuerten **Ressourcen-schonenden 2-Stufen-Modell**:

**Stufe 1 (Der smarte Gatekeeper):**
Ein leichtgewichtiges, CPU-optimiertes und non-agentic Python-Skript evaluiert zyklisch den Markt abseits der Agenten. Agenten (Stufe 2) erhalten erst Rechenleistung (`is_awake`), wenn **zwei strikte Trigger** gleichzeitig feuern:

- **Trigger A (Entropie-Freigabe):** Grundvoraussetzung. Der Markt muss strukturell gesund sein (hohe Entropie, Meinungsvielfalt). Bei einem Entropie-Kollaps (Panik/Herdenverhalten) bleiben Agenten im Schlafmodus.
- **Trigger B (POI & Volatilitäts-Ausbruch):** Agenten wachen erst auf, wenn der Preis eine vorab berechnete, historische "Point of Interest"-Zone (Support/Resistance aus dem H4-TF) erreicht **UND** gleichzeitig ein Volatilitäts-Spike (z.B. ein Anstieg in der Bollinger Band Width / NATR) messbar ist.

Sind beide Trigger erfüllt, generiert der Gatekeeper ein `ENTROPY_FACTOR` Flag für die Agenten.
*(Ausnahme: Existiert bereits ein aktiver Trade auf diesem Asset, greift ein Risk-Management-Override und die Manager-Agenten wecken sich selbständig).*

Der Output ist ein `ENTROPY_FACTOR` (Float-Wert zwischen 0.0 und 1.0, z.B. >0.8 = Go), berechnet über Von-Neumann-Entropie auf einer **5-Feature-Korrelationsmatrix**:

| Feature | Kürzel | Beschreibung |
|---|---|---|
| RSI | Relative Strength Index | Momentum-Oszillator (Überkauft/Überverkauft) |
| BBW | Bollinger Band Width | Volatilitätsmaß (Bandbreite) |
| NATR | Normalized Average True Range | Normalisierte Volatilität |
| VolOsc | Volume Oscillator | Volumen-Kraft (Akkumulation/Distribution) |
| CMF | Chaikin Money Flow | Geldfluss-Weighted Average |

→ Ref: [[market-folding|Market Folding (Detail)]]


## 2. Der 4-stufige Orchestrierungs-Loop

Ist das Asset durch den Entropie-Check freigegeben, feuern die orchestrierten Metriken und Agenten (unter Berücksichtigung von Multi-Timeframes) exakt in dieser Reihenfolge:

1. **Tradability-Prüfung:**
   Der Choppiness Index (CHOP) oder Vertical Horizontal Filter (VHF) trennen zähe Seitwärtsmärkte (die fälschlicherweise stabil wirken könnten) von echten ausbruchsfähigen Strukturen.
2. **Direction-Check (Trend & Regime):**
   Ermittlung des Regimes, im Idealfall über ein **Sparse Jump Model (SJM)**, um "Lagging" zu vermeiden. Ergänzend klassische Bestätigungen über ADX/DMI zur Messung der direkten Trendstärke oder Aroon für frische Trendstarts. → Ref: [[jump-models|Jump Models (Detail)]]
3. **Entry-Validierung:**
   (sofern Volumendaten für das jeweilige Asset sinnvoll verfügbar sind): Überprüfung des Ausbruchs durch das On-Balance Volume (OBV). OpenBB dient als Knotenpunkt für zusätzliche fundamentale Metadaten-Pulls.
4. **Agentic State Generation & Orchestration:**
   Autonome KI-Agenten konsolidieren Phase 1-3. Das System nutzt **Dynamic Phases** und ein **Agent Composition Model**. Diese orchestrieren die Metriken in modular zusammengesetzten Schritten. Das System bewertet exklusiv Long-Bewegungen (V1 MVP). Der finale konsolidierte Zustand wird in einen strikten und neutralen Array-Wert überführt:
   - `0` (Neutral / Risikoausstieg — Löst in Box 3 einen "Tight Trailing Mode" aus)
   - `1` (Long Markt)

## 3. Dynamische Agenten-Rollen & Composition (Scout vs. Manager)

Agenten in Box 2 agieren strikt kontextbezogen und passen ihr Verhalten an den IPC-Feedback-Loop (Laufende Trades aus Box 3) an. Das System kennt drei fundamentale Zustände:

- **Der `COLD_START`-Modus (Boot / Restart):**
  Box 2 startet nach einem Crash oder Neustart zwingend im `COLD_START`-Zustand. In diesem Modus gilt:
  - **Keine** Entropie-Berechnung, **keine** Agenten werden geweckt.
  - Box 2 wartet passiv auf den ersten Heartbeat-Ping-Response von Box 3 (inkl. `active_trades` Array). → Ref: [[05-schnittstellen|Kap. 05 §3: Heartbeat & Position-Report]]
  - Enthält das Array laufende Trades → Box 2 bootet direkt in den **Manager**-Modus.
  - Ist das Array leer → Box 2 wechselt in den **Scout**-Modus.
  - **Deadlock-Prävention:** Um ein "Wait-for-Sync" Deadlock zu vermeiden (Box 3 wartet nach einem Restart auf Box 2, Box 2 auf Box 3), muss Box 2 im `COLD_START` zwingend aktiv einen "Identity-Request" an den `/health` Endpoint von Box 3 feuern, um den initialen Sync zu erzwingen, anstatt nur passiv auf den Ping-Cycle zu warten.
  - **Empty-Array-Paradoxon (Double-Dip Schutz):** Erst nach erfolgreichem Empfang des ersten Heartbeats darf die reguläre Inference-Pipeline starten. Zusätzlich MUSS im Heartbeat das Flag `mt5_connected: true` stehen. Antwortet Box 3 zwar auf Netzwerkbasis, hat aber lokal die Verbindung zum Broker verloren (`mt5_connected: false`), schickt sie ein leeres `active_trades`-Array (weil sie die Orders gerade nicht sieht). In diesem Fall darf Box 2 den `COLD_START` nicht in den Scout-Modus verlassen, da sonst fälschlicherweise ein erneuter Einstieg (Double-Dip) getriggert werden könnte.

- **Der "Scout"-Modus (Kein aktiver Trade):**
  Der Agent sucht aggressiv nach Einstiegen. Er evaluiert die Signal-Matrix (Entropie + SJM Trend) auf Basis der initialen Setup-Kriterien. *Ziel:* Generierung von State 1 (Market Entry / Long).
- **Der "Manager"-Modus (Aktiver Trade läuft):**
  Der Agent sucht *nicht* nach neuen Entries (**Double-Dip Prevention**, SSOT in diesem Kapitel). Er verifiziert lediglich, ob die Ursprungs-These des laufenden Trades noch intakt ist (z.B. "Ist das Volumen noch da?", "Hält der Trend auf H1?"). *Ziel:* Aufrechterhaltung von State 1 (Hold) oder Downgrade auf State 0 (Tight Trailing Exit).
  → Die Double-Dip-Sperre basiert auf dem **Position-Report** im Heartbeat-Response von Box 3. Liest Box 2 für ein Asset einen laufenden Trade, ist Box 2 serverseitig hart gesperrt, neue Entry-Signale (State 1) für dieses Asset zu senden.

**Agent Composition Framework:**
Innerhalb der beiden aktiven Modi (Scout/Manager) wird die Entscheidungsfindung über ein **Agent Composition Framework** orchestriert:
- **Modulare Sub-Agenten:** Spezifische Agenten ("Macro Analyzer", "Sentiment Analyzer") evaluieren den Market Context innerhalb des aktuellen Modus und antworten über einen **strukturierten I/O-Vertrag** (`[Decision, Confidence, Reasoning]`). Jeder Sub-Agent hat ein striktes Timeout (z.B. 5 Sekunden). Antwortet ein Agent nicht rechtzeitig, wird sein Beitrag übersprungen und als `abstain` (Enthaltung) gewertet.
- **Dynamic Phases:** Phasen (z.B. Discovery im Scout-Modus → Validation → Monitoring im Manager-Modus) sind konfigurationsgesteuert. Hysterese-Filter (→ Ref: [[10-configuration|Kap. 10]]) regeln die Übergänge und verhindern Ping-Pong-Effekte.
- **Die Orchestrierung & Fallback-Kaskade (2-Level Fusion):** Die Zusammenführung divergierender Signale erfolgt über eine gehärtete **2-Level-Architektur**, um im Live-Betrieb (Hot-Path) API-Latenzen und LLM-Halluzinationen abzuwehren:
  - *Level 1 (Deterministischer Konsens):* Die Konfidenz-Werte der Sub-Agenten werden mathematisch mit ihrem historischen *Reliability Weight* (Zuverlässigkeitsgewicht, trainiert im Lab) multipliziert und über IF/THEN Logik (Veto-Rechte) zu einem Basis-State aggregiert.
  - *Level 2 (Asynchrones LLM Fallback):* Das Gemini Action Model wird *nur* in "Grauzonen" (z.B. konsolidierter Signal-Score liegt bei unklaren ~50%) zur Schlichtung von Narrativ-Divergenzen aufgerufen.
  - *Hard Timeout (Fail-Safe):* Antwortet das LLM auf Level 2 nicht innerhalb eines strikten Zeitfensters (z.B. 10 Sekunden), greift das sofortige Fail-Safe. Der Target-State wird zum globalen Kapitalerhalt defensiv auf 0 (Neutral / Exit) gesetzt.

## 4. Deep Reasoning & Event Sourced Persistence

Um komplexe Marktregime sicher zu identifizieren, nutzt das System die nativen **Thinking Models** (Gemini 3 Action Model):
- **Event-Sourced Audit Trail:** Jede Zwischenentscheidung (Output eines Sub-Agenten, Fusion durch Orchestrator) wird als unveränderliches Event im System via Git dokumentiert. Dies ermöglicht eine asynchrone Fehleranalyse, Replays und Absicherung, falls ein Signal im Nachhinein als "Phantom" identifiziert wird. Historische Backtesting-Analysen sind in Box 2 verboten und fest an The Improvement Lab (Box 4) delegiert.

## 5. Decision Matrix (Signal Matrix)

Die finale Entscheidungslogik kombiniert **SJM-State** und **Entropy-Factor** zu einem eindeutigen **System-State**:

```
System-State = f(SJM-State, ENTROPY_FACTOR)
```

### Eingangs-Parameter

| Quelle | Parameter | Wertebereich | Bedeutung |
|---|---|---|---|
| Sparse Jump Model | `SJM_State` | `{0=Bull, 1=Bear, 2=Neutral}` | Marktregime (Richtung) |
| Market Folding | `ENTROPY_FACTOR` | `[0.0, 1.0]` (>0.8 = Go) | Strukturelle Gesundheit |

### Entscheidungs-Matrix

| SJM-State | Entropy-Faktor | System-State | Interpretation |
|---|---|---|---|
| **Bear (1)** | Egal | `0` (Flat) | SJM erkennt Abwärtstrend → Kein Long |
| **Neutral (2)** | Egal | `0` (Flat) | Kein klares Edge → Kein Trade |
| **Bull (0)** | H↓ (< 0.8) | `0` (Flat) | ⚠️ **CRITICAL:** Struktur kollabiert trotz Aufwärtstrend |
| **Bull (0)** | H↑ (> 0.8) | `1` (Long) | ✅ **SAFE ZONE:** Trend + gesunde Struktur |

### Vereinfachte Boolesche Logik

```
LONG_SIGNAL = (SJM_State == BULL) AND (ENTROPY_FACTOR > THRESHOLD)
SYSTEM_STATE = 1 if LONG_SIGNAL else 0
```

**Begründung:** Selbst ein bullischer Trend ist wertlos (und gefährlich), wenn die Marktstruktur kollabiert. Die Kombination beider Signale eliminiert False Positives in Crash-Szenarien.

→ Ref: [[jump-models|Jump Models (Detail)]]
→ Ref: [[market-folding|Market Folding (Detail)]]

## 6. Autonomie vs. Live-Sicherheit

Die Agenten aus Blackbox 2 haben **keinerlei direkten Zugriff auf das Order-Buch**. Sie publizieren ihre Findings (den System-State) via REST/FastAPI über das Tailscale VPN in Richtung Windows-Server. Das physische Ausführen der Trades bleibt das exklusive Recht von Blackbox 3.

### 6.1 Rate-Limit Cooldown (429 Too Many Requests)
Sollte die Signalgenerierung in Box 2 aufgrund eines Bugs eskalieren, greift der Circuit Breaker von Box 3 (max. 12 Requests / Minute) und blockt ab (`HTTP 429`).
- **State-Freeze (Linux Cooldown):** Empfängt Box 2 einen `429 Too Many Requests` Code, loggt es lokal einen Critical Error und friert die Agenten-Generierung für **5 Minuten hart ein** (Cooldown-Stasis).
- **Silent Alerting (Linux):** Box 2 operiert dabei "silent" und feuert *keine* Mails ab. Der externe SMTP-Alert ("Circuit Breaker ausgelöst") wird exklusiv und zentral von Box 3 (Windows Alert-Hub) initiiert, da Box 2 bei einem Amoklauf als kompromittiert gilt.

---
→ Verwandte Kapitel: [[02-blackbox-data|02. Blackbox 1: Data Engine]] | [[04-blackbox-mt5|04. Blackbox 3: MT5 Execution Bridge]]


========================================
FILE: docs/04-blackbox-mt5.md
========================================
---
aliases: []
tags: []
related: [[00-MOC-Trading-System]]
trust: canonical
last_reviewed: 2026-04-12
---
# 04. Blackbox 3: MT5 Execution Bridge

*Diese isolierte Schicht ist der finale Vollstrecker. Sie schützt das Kapital vor algorithmischen Fehlern, Verbindungs-Ausfällen und Black-Swan-Ereignissen, indem sie von Agenten berechnete abstrakte States in granulare MetaTrader 5 Orders translatiert – unter Anwendung extremer Sicherheitsroutinen.*

## 1. Validation & Bridge-Architektur

Die tatsächliche Order-Ausführung im MT5 ist erst der letzte Schritt einer strengen Validierungskette:

1. **Python Validation Server & Capital Allocator:** 
   Bevor ein Signal der KI-Agenten (Blackbox 2) zum Terminal durchdringt, muss es einen Meta-Check im Validation Server bestehen. **Dieser Server läuft zwingend als physischer Host-Prozess auf dem MT5 Windows Server (neben dem Terminal)**, um die Latenz bei einem Not-Aus auf ~0ms zu minimieren:
   - *Ist die Entropie noch im Tradeable-Bereich, oder hat sich der Markt gecrasht/verformt?*
   - *Korrelations-Check & Exposure:* Liegen korrelierende "Trade-Bewerbungen" vor, wertet der **Capital Allocator** die von den Agenten mitgelieferten *Confidence Scores* aus. Schwächere Signale werden aussortiert, um Exposure-Limits nicht zu brechen.
   - *Ist der Trade Prop-Firm-compliant (z.B. News-Filter via OpenBB gecheckt, Max-Drawdown-Grenzen intakt)?*
2. **FastAPI Bridge:** 
   Gibt die Validation / der Allocator "grünes Licht", empfängt ein schlanker On-Server-FastAPI Daemon das Signal als sauberen JSON-Payload (z.B. `{"symbol": "EURUSD", "state": 1, "confidence": 0.85, "strategy_id": "SQ_Jump_v2", "entropy_factor": 0.95}`). Es werden ausschließlich Long-Signale (State `1`) oder Neutral-Signale (State `0`) verarbeitet.
3. **Execution Library:** 
   Dieser FastAPI Daemon interagiert direkt über die offizielle `MetaTrader5` Python Library mit dem gebundenen Terminal, um Latenzen zu minimieren (~5ms Ziel). Das reine Trading läuft chartless.

## 2. Asynchrone Ausführungslogik & Master Watchdog EA

Das System lehnt MQL5 `OnTick()` Iterationen für das Portfolio-Risikomanagement prinzipiell ab, da sie durch irregulären Tick-Fluss bei Multisimultan-Analysen zu asynchronem Thread-Blocking führen können. Verwendet wird ein asynchroner **Multi-Symbol Timer Loop** (via MQL5 `OnTimer()`). 

- **Ein einziger Master Watchdog EA:** Anstatt für jedes Asset einen eigenen EA auf einen Chart zu ziehen, überwacht ein einziger, chart-unabhängiger "Master Watchdog EA" das globale Portfolio-Risiko. Er pollt zyklisch den von Python diktierten globalen Risiko-Status und den Asset-Status (`0` oder `1`).
- **Thread-Safety & IPC:** Sämtliche `mt5.*` Aufrufe innerhalb der Python-Bridge werden durch ein `threading.Lock()` serialisiert, um Race Conditions zu vermeiden. Die Kommunikation via `GlobalVariableSet()` unterliegt der MQL5-Limitation (nur Double-Werte, max. 64KB Speicher, Datenverlust bei Terminal-Neustart), was durch das Heartbeat-Protokoll sicher abgefangen wird.
- **Konto-Modus:** Das Konto muss den Typ **Hedging** aufweisen, wird jedoch durch die Logik **zwingend uni-direktional** geführt (kein gleichzeitiges Long und Short im V1-Limit).
- **Die 3-Step Graceful Shutdown Sequenz (G-10):** Um "Terminal-Zombie"-States und COM-Lecks bei automatischen Rollbacks oder Service-Restarts zu vermeiden, **MUSS** der Python-Daemon Windows-Signale (`SIGINT`/`SIGTERM` via NSSM) abfangen und **strikt in dieser Reihenfolge** runterfahren:
  1. **Stop Ingress:** FastAPI/Uvicorn anweisen, keine neuen Requests (`POST /api/v1/signal`) mehr anzunehmen (Uvicorns standard Graceful-Shutdown Verhalten nutzen).
  2. **Stop Threads:** Den internen asynchronen MT5-Watchdog-Loop über ein `asyncio.Event()` (Cancellation-Token) sanft beenden.
  3. **Lock & Shutdown:** Erst wenn alle Threads ruhen, das globale MT5-Threading-Lock akquirieren und final `mt5.shutdown()` aufrufen.

## 3. Trade Lifecycle & State Handling

Die Bridge übersetzt die States in einen hybriden Lebenszyklus (Trade Lifecycle):

- **State 1 (Long Markt):** Trigger für einen Market-Entry. Initial wird serverseitig ein harter **ATR-Kaskaden-Stop-Loss** gesetzt. Bei Erreichen von `1R` Profit (Risk-to-Reward) erfolgt ein Partial Close (z.B. 50% der Position) und der SL wird auf Break-Even (Risk-Free) gezogen. Für den restlichen Pfad schützt ein breiter Trailing SL. 
- **State 0 (Neutral / Risikoausstieg):** Das Signal führt **nicht** zum sofortigen Market Close. Stattdessen wird die Position in einen **"Tight Trailing Mode"** versetzt. Der Trade wird demnach bei einer geringeren Gegenbewegung per Stop-Loss aus dem Markt gedrängt (Graceful Exit). Dies minimiert Spread-Verschleiß und Slippage bei flackernden KI-Signalen.

## 4. IPC, Watchdog Protocol & Graceful Degradation

Latenz-Schluckauf oder Verbindungsabbrüche auf dem VPN (Tunnel zuckt) sind normal. Das System nutzt **Graceful Degradation** in einem Suspend-Modell, anstatt das Portfolio bei jedem Ausfall der "Brain"-Blackbox panisch – mit teuren Spread-Verlusten – zu liquidieren.

- **Python↔MQL5 IPC (Heartbeat & Wake-Up):** Die Kommunikation kommt ohne DLLs aus und nutzt `GlobalVariableSet()` im MT5-Speicher. **Besonderer Sicherheitsaspekt:** Ein Terminal-Crash löscht den Heartbeat-Speicher. Um den Freeze zu durchbrechen, initialisiert sich der Terminal-EA beim Boot im `WAITING_FOR_SYNC` Modus und setzt `INIT_SYNC_REQUEST = 1`. Die on-Server FastAPI-Bridge (Box 3) pollt diesen Wert zyklisch. Parst sie die `1`, re-injiziert sie den gecachten `config_hash` (→ Ref: [[10-configuration|Kap. 10]]) und den letzten State direkt ins Terminal. Das System heilt sich autonom.
  → Für die vollständige Heartbeat-Spezifikation (Ping-Payload, Position-Report, Double-Dip Prevention): [[05-schnittstellen|Kap. 05 §3 (SSOT)]] und [[03-blackbox-agents|Kap. 03 §3 (SSOT Double-Dip)]].
- **Der Suspend-Modus:** Erkennt MQL5, dass der Ping ausfällt oder der Tick-Lag divergiert (Threshold: 30s relative Latenz), verfällt das Terminal in den "Pause"-Code (`SUSPEND`). → Details: [[05-schnittstellen|Kap. 05 §3 (SSOT)]]
- **Autonomous Safe Mode (Panic Liquidation):** Initial storniert MT5 ausnahmslos alle schwebenden Befehle. Laufende Trades werden gehalten und nur durch serverseitige Stop-Losses geschützt. Hält der `SUSPEND`-Status ungebrochen länger an, als in `config.yaml` (`suspend_panic_close_minutes`) deklariert ist, feuert der Risk-Diktator unweigerlich ein "Hard Close" auf alle Trades. Dies verhindert Overnight- und Weekend-Risk durch endgültig havarierte Agents.

## 5. Hard Stops & Der "Risk-Diktator"

Letzte Absicherung am Execution Layer, über generische Konfigurationsdateien definierbar:
- **Volume & Stop Validation:** Vor jedem `order_send()` prüft der Diktator die `volume_step` Konformität (Lot-Size Normalisierung) und stellt sicher, dass der gewünschte SL den `SYMBOL_TRADE_STOPS_LEVEL` Mindestabstand zum aktuellen Preis einhält.
- **Slippage-Prävention (Max-Spread Validation):** Das System führt im letzten Moment absolut zwingend eine Spread-Level-Validierung durch. Wenn `(ask - bid) > max_allowed_spread` (Parameter aus `compliance.yaml` aufgrund von z.B. flüssigkeitsarmen Phasen oder News-Events), muss Box 3 das Signal 1 kompromisslos ablehnen/pausieren, selbst wenn Box 2 ein klares "Go" sendet. Dies verhindert sofortige CRV-Zerstörung durch asymmetrische Ausführungspreise.
- **Post-Send Reconciliation:** Nach jedem Trade-Aufruf wird der Status über `mt5.history_deals_get()` oder `mt5.positions_get()` verifiziert, um Fehl-Exekutionen (Ghost Trades) sofort zu erkennen.
- **Floating Drawdown Killswitch:** Da Prop-Firms Drawdowns am "Floating Equity" messen, rechnet das Skript Tick-für-Tick das aktuelle Floating Equity ab. Basiert auf der Daily-Loss Berechnung gegen die Midnight-Balance des Brokers. **Harte Regel (G-03):** Der Daily-Loss-Reset orientiert sich *strikt an der Broker-Server-Time* (über `mt5.symbol_info_tick().time` oder das erste Broker-Tick des neuen Tages), niemals an der lokalen Systemzeit von Windows oder dem Linux-VPS. Dies schützt vor fatalen Pönalen durch Zeitzonen-Desyncs. Bricht dieses das definierte Limit (z.B. -4.5%), agiert das System als "Diktator": Es feuert sofort kompromisslos `CloseAllPositions()` und legt alle Agenten-Aktivitäten lahm.
- **Cool-Down (Anti-Revenge):** War der vorherige Abschluss des Symbols ein Verlusttrade, setzt das System einen Zwangspausen-Timer von X Stunden.
- **News-Auto-Close:** Der Risk-Diktator kann so konfiguriert werden, dass er Positionen X Minuten vor High-Impact News (via OpenBB Daten aus Box 2) automatisch schließt, um Slippage zu vermeiden.

→ Ref: [[prop-firm-allocator|Prop-Firm Allocator & Risk-Diktator]]

## 6. Trade Lifecycle Matrix

Diese Matrix definiert das exakte Verhalten bei Zustandsänderungen durch Box 2:

| Von | Nach | Aktion | Begründung |
|---|---|---|---|
| `-` | `1` (Long) | **Buy Market** | Initialer Eintritt mit ATR-SL. |
| `1` | `1` (Long) | **Hold** | Maintenance Modus (Trailing SL). |
| `1` | `0` (Neutral) | **Tighten SL** | Wechsel in "Tight Trailing Mode" (Graceful Exit). |
| `0` | `1` (Long) | **Buy Market** | Erneuter Einstieg nach Exit-Phase. |
| `1` | `SUSPEND` | **No Action** | Laufende Trades werden durch Broker-SL geschützt. |
| `-` | `SUSPEND` | **Cancel Pendings** | Keine neuen Entries erlaubt. |

---

## 7. Prop-Firm Compliance Module

Das System ist über eine `compliance.yaml` vollständig konfigurierbar für verschiedene Geldgeber:

- **Static vs. Trailing DD:** Konfigurierbar, ob der Max-Drawdown fix gegen die Initial Balance oder trailing gegen das High-Water-Mark Equity berechnet wird.
- **Consistency Rules:** Überwachung der Best-Day-Limits (z.B. kein einzelner Tag darf >40% des Gesamtziels ausmachen).
- **News-Blackout:** Definition von Sperrzeiten (z.B. ±2 Minuten) um High-Impact Events.
- **Minimum Trading Days Counter (PF-04):** Prop-Firms verlangen eine Mindestanzahl an Handelstagen (z.B. 4 Tage bei FTMO, 7 Tage bei Apex). Das System trackt automatisch die Anzahl der tatsächlich gehandelten Tage und blockiert eine vorzeitige Account-Phase-Aktivierung (Challenge → Verification), bis das Minimum erreicht ist. Verhindert Disqualifikation durch zu schnelles Abschließen.
- **Weekend Holding Rules (PF-06):** Konfigurierbare Regel, ob Positionen über das Wochenende gehalten werden dürfen. Wenn deaktiviert (Standard: restriktiv), schließt der Risk-Diktator am Freitag automatisch alle offenen Positionen X Minuten vor Marktchluss (z.B. 30 Min. vor Forex Close). Verhindert Weekend-Gap-Risiko und Prop-Firm-Pönalen bei Firmen, die Weekend-Holding explizit verbieten (z.B. TFT).
- **Account State Machine:** Automatisiertes Tracking der Phasen (Challenge → Verification → Funded/Live), um Risikoparameter dynamisch anzupassen.
- **Broker-Kontowechsel (A-6):** Bei einem Wechsel des MT5-Kontos (z.B. von FTMO-Demo auf FTMO-Live, oder zu einem anderen Broker) **muss** ein manueller Re-Kalibrierungs-Prozess durchlaufen werden:
  1. `compliance.yaml` aktualisieren (neue Prop-Firm Limits, `volume_step`, `trade_stops_level`).
  2. `config_hash` wird automatisch neu generiert (→ Ref: [[10-configuration|Kap. 10]]), wodurch Box 3 einen `ConfigDesyncPanic` auslöst, bis beide Seiten synchron sind.
  3. Der Risk-Diktator validiert die neuen Symbol-Infos (`mt5.symbol_info()`) beim nächsten Start und loggt Abweichungen (Spread, Lot-Size, Stop-Level).
  4. **Pflicht:** Mindestens 24h Paper-Trading auf dem neuen Konto vor Live-Einsatz (→ Ref: [[09-testing-strategie|Kap. 09 §5]]).

---
→ Verwandte Kapitel: [[03-blackbox-agents|03. Blackbox 2: The Scientist (Agenten)]] | [[05-schnittstellen|05. API & Schnittstellen-Spezifikation]]


========================================
FILE: docs/05-schnittstellen.md
========================================
---
aliases: []
tags: []
related: [[00-MOC-Trading-System]]
trust: canonical
last_reviewed: 2026-04-19
---
# 05. API & Schnittstellen-Spezifikation

*Dieses Modul definiert, wie die einzelnen Blackboxen reibungslos und Latenz-optimiert miteinander kommunizieren, ohne versehentliche Kopplung ("lose Fäden") zu erzeugen oder einander bei Ausfällen mitzureißen.*

## 1. Interface: Blackbox 1 (Data) ↔ Blackbox 2 (Agents)
- **Umgebung:** Physischer Split. Box 1 (Data Engine) läuft auf dem Windows Server zusammen mit dem MT5 Terminal. Box 2 (Agents) agiert auf dem Hetzner Linux VPS.
- **Übertragung:** Box 1 und Box 2 kommunizieren netzwerkübergreifend durch das **Tailscale VPN**. Das System nutzt **ZeroMQ (ZMQ)** als asynchrone Pub/Sub-Pipeline. Blackbox 1 publiziert Datenpakete, Blackbox 2 hat Subscriber-Sockets. Der minimale Latenz-Jitter des VPNs ist bei Swing Trades (SLA 3-5 Minuten) vernachlässigbar.
  - **Pipeline Hardening:** Um Peak-Lasten und Verbindungsabbrüche abzufangen, wird ZMQ durch strikte High-Water-Marks (z.B. `SNDHWM=100000`) abgesichert. Ein Reconnection-Handling mit Exponential Backoff fängt temporäre VPN-Drops ab. Optional dient CURVE Encryption als Defense-in-Depth Layer.
  - **ZMQ-Flaschenhals Prävention:** Obwohl ZMQ durch HWM geschützt ist, besteht bei der Deserialisierung eine Schwachstelle, wenn Box 1 Ticks schneller publiziert als Box 2 sie verarbeiten kann (Paket Drops). **Regel:** Box 2 nutzt zwingend einen asynchronen Buffer-Reader, der den ZMQ-Socket blockierungsfrei leert und die Daten in eine interne `asyncio.Queue` (Memory) schiebt, damit die Inferenz den Empfang niemals blockiert.
- **Payload-Struktur & Serialisierung:** CPU-optimierte NumPy-Arrays in definierten Rolling-Windows (z.B. Shape `[N, 5]` für die 5 Feature-Inputs der Entropie-Matrix), da der Linux-VPS auf GPU-Beschleunigung verzichtet. Die binäre Serialisierung erfolgt zwingend über **msgpack_numpy** (oder alternativ Apache Arrow) anstelle des unsicheren `pickle` (Schutz vor Remote Code Execution). Um Observability und Tracing (Structured Logging) zu garantieren, wird der Data-Payload in ein Dictionary gewrappt: `{"trace_id": "tick-77a1-8b21", "seq_id": 10453, "payload": <numpy_array>}`.
- **Sequencing (A-2, `seq_id`):** Jedes ZMQ-Paket enthält eine **monoton steigende Sequence Number** (`seq_id`, uint64). Box 2 prüft bei Empfang, ob `seq_id == last_seq_id + 1`. Bei einer Lücke oder Reihenfolge-Verletzung (Out-of-Order, typisch nach VPN-Reconnect) wird das Paket **verworfen** und ein Warning geloggt. Box 2 wartet auf die nächste korrekte Sequenz, um Inferenz auf falscher Datenbasis auszuschließen.
- **ZMQ Staleness-Monitor (Box 2):** Da das ZMQ PUB/SUB-Pattern bei leisen Abbrüchen oft blockiert ("hängt"), darf Box 2 nicht blind auf Basis veralteter Daten weiter inferieren. Ein aktiver *Time-Since-Last-Message Monitor* überwacht den Stream. Bleibt ein Paket über einen definierten Threshold aus, friert Box 2 die KI-Inferenz ein, um irrelevante Signale oder einen verdeckten "Blind Flight" an Box 3 kategorisch auszuschließen.

## 2. Interface: Blackbox 2 (Agents) ↔ Blackbox 3 (MT5 Bridge)
Hier liegt der architektonische Kern der Remote-Trennung. Die Python-Agenten-Welt (Linux) kommuniziert mit der MT5-Ausführungswelt (Windows) ausschließlich über eine strikte REST-Schnittstelle durch FastAPI über das VPN.

### 2.1 Readiness-Probe (`GET /health`)
Um persistente MT5-Verbindungsprobleme frühzeitig vor der echten Signal-Übertragung abzufangen, ist ein Deep-Check Readiness-Endpoint Pflicht:
- **Tiefenprüfung:** Der Aufruf retouniert nicht nur eine FastAPI-Vitalität, sondern testet zwingend die darunterliegende Execution-Bridge:
  - Läuft das Terminal? (`mt5.terminal_info() != None`)
  - Sind automatische Orders freigeschaltet? (`terminal_info.trade_allowed == True` / `algo_trades_allowed`)
- **Thread-Safety (WICHTIG):** Alle internen MetaTrader5-Abfragen in der Python-Bridge (inkl. des Status-Checks in `/health`) **müssen zwingend** durch ein globales `threading.Lock()` serialisiert werden, um Race-Conditions mit asynchronen Watchdogs oder Execution-Schleifen zu vermeiden.
- **Split-Brain Protection:**
  - `200 OK`: `{"status": "ready", "mt5_connected": true, "algo_allowed": true, "config_hash": "a1b2c3d"}` (Garantie der Hash-Synchronizität).
  - `503 Service Unavailable`: Bei MT5-Verbindungsabbruch, gesperrten Algos oder Hash-Mismatches.

### 2.2 Der Execution-Handshake (`POST /api/v1/signal`)
- **Rate-Limiting (Circuit Breaker):** Um ein "Pounding" von der Linux-Seite (z.B. amoklaufende Agenten-Loops) abzuwehren, implementiert FastAPI auf Box 3 zwingend ein Rate-Limiting (z.B. per `slowapi` Token-Bucket). Das Limit ist hart auf **12 Requests / Minute** (entspricht 1 Trade-Request alle 5 Sekunden) eingestellt.
- **Ablauf:**
  1. Box 2 (Linux) löst einen Webhook an die Tailscale-IP des Servers von Box 3 aus.
  2. JSON-Payload beinhaltet zwingend: `{ "symbol": "EURUSD", "state": 1, "confidence": 0.85, "strategy_id": "SQ_Jump_v2", "entropy_factor": 0.95, "config_hash": "a1b2c3d", "trace_id": "req-9f8e-11e2" }`. *Hysterese-Bedingung:* Box 2 sendet State 1 nur bei Überschreiten von `entry_confidence_min`. Fällt die Konfidenz unter `exit_confidence_max`, sendet Box 2 State 0 für einen Tight Trailing Graceful Exit.
  3. Der Validation Server auf Box 3 prüft Parameter auf Prop-Firm Setup, Hash-Locking und Rate-Limit (Box 3 rechnet Entropie *nicht* selbst, nutzt `entropy_factor` als Sanity-Check).
  4. Quittierung an Box 2 mit `200 OK` (Trade approved) oder `403 Forbidden` (Risk Limit).
  5. **HTTP 429 Too Many Requests:** Überschreitet Box 2 das Limit, blockt Box 3 sofort ab und **triggert zeitgleich einen SMTP-Alert auf dem Windows-Host** an den Supervisor ("Circuit Breaker ausgelöst: Box 2 flutet Bridge").
- **MT5 Internal Bridge:** Akzeptiert der FastAPI-Layer den Payload, nutzt er im gesicherten internen Threading-Lock die offizielle `MetaTrader5` Python Library für Order-Executions.

## 3. Watchdog & Graceful Degradation (Pulse-Check)
Das Heartbeat-System läuft parallel zur State-Übermittlung und verhindert blinde Panik-Liquidationen ("Tradekills").

- **Idempotenter Ping-Check & Position-Report (Box 3 → Box 2):** 
  Box 2 feuert alle 5 Sekunden einen Heartbeat (`POST /api/v1/ping`) an Box 3. Um die MT5 Wake-Up Lücke nach einem Server-Reboot zu schließen, arbeitet der Ping als **Idempotent State Broadcast**. Neben der Sequence-Number überträgt er zwingend den aktuellen System-Zustand: `{ "status": "alive", "last_received_tick_id": 10452, "current_state": 1, "config_hash": "a1b2c3", "trace_id": "ping-4b2a-99f1" }`. 
  **Position-Report:** Box 3 antwortet nicht nur mit `200 OK`, sondern retourniert im Ping-Response ein Array aller laufenden Trades (`[{"symbol": "EURUSD", "entry": 1.105, "sl": 1.100, "status": "active"}]`) sowie ein Pflicht-Flag `mt5_connected: true/false`. Letzteres zeigt an, ob MT5 aktuell Verbindung zum Broker-Server hat. → Double-Dip Prevention: SSOT in [[03-blackbox-agents|Kap. 03 §3]].
  **COLD_START Bootstrapping:** Dieser Heartbeat-Response ist zugleich der Trigger für Box 2, um nach einem Restart (→ [[03-blackbox-agents|Kap. 03 §3: COLD_START]]) den korrekten Boot-Modus (Scout vs. Manager) abzuleiten.
  - **Freshness-Threshold (Relative Latenz):** Für Swing-Trading wird eine Obergrenze des "Tick-Lags" von z.B. **30 Sekunden** definiert (gemessen rein auf Windows-Seite zwischen Eintreffen des MT5-Ticks und FastAPI-Ping). Veraltete Daten greifen analog zum Ping-Mangel.
  - **Clock-Sync:** *Ausgemustert.* Absolute UNIX-Timestamps für systemübergreifende Caching-Validierungen sind strikt untersagt, um VPN-Zeitdrifts zu neutralisieren.
- **Der `SUSPEND`-Mode:** 
  Bleibt der Ping aus oder veraltet der Data-Tick (z.B. VPN-Zucken), wechselt MT5 in den Suspend-Modus: Alle schwebenden Limit-Orders werden gelöscht. Laufende Live-Positionen **bleiben unangetastet**, gesichert durch ihren serverseitigen ATR-Stop-Loss (Graceful Degradation).
  - **Eskalation:** Bei längerem `SUSPEND` triggert System 3 vollautomatisch eine einfache Alert-Benachrichtigung via **E-Mail (SMTP MVP)** an den Supervisor.
- **Risk-Kill-Poll & Alerting:** 
  Hat Box 3 den separaten "Risk-Diktator" (z.B. Floating Drawdown überschritten) aktiviert, returniert es auf den Ping ein `423 Locked`. Box 2 erkennt das und friert die Agenten ein. Parallel hat Box 3 zumeist ohnehin selbst alarmiert.

## 4. Internal Data Sync: Blackbox 1 ↔ Blackbox 4 (The Parquet Ferry)
Diese Schnittstelle verknüpft die Windows-Datenerfassung mit der isolierten Linux-Backtesting-Welt:
- **Übertragung (Bidirectional Atomic Staging):** Um File-Locks und asynchrone Lesefehler beim Transfer über das VPN abzuwehren, gilt das atomare Konzept beidseitig. Auf der Windows-Seite schreibt Box 1 live in temporäre `staging_stream.parquet` Dateien und benennt diese bei Fertigstellung atomar in `ready_<timestamp>.parquet` um.
- **Prozess:** Der Parquet Ferry Daemon (Box 1) streamt exklusiv `ready_`-Dateien an Box 4 (Linux). **Wichtig:** Box 4 (The Improvement Lab) speichert den eintreffenden TCP-Stream strikt unter `incoming_temp.parquet`. Erst nach finaler Datei-Bestätigung triggert Box 4 ein lokales Umbenennen in verarbeitbare `.parquet`-Container. Dies verhindert zu 100%, dass Box-4-Analysen mit EOF-Fehlern crashen, weil sie korrupte Download-Reste lesen.
- **File-Locking (Race-Condition Prävention):** Da das atomare Umbenennen (`Rename`) der Ferry genau in dem Sekundenbruchteil crashen kann, in dem das Lab einen massiven Backtest iteriert, ist ein expliziter File-Locking-Mechanismus vorgeschrieben. Während des Transfers und Renames der Datei existiert eine `.lock` Datei. Das Lab respektiert diese und öffnet Dateien erst, wenn das Lock entfernt wurde.

## 5. Interface: Blackbox 4 (Lab) → Blackbox 2/3 (Model Promotion)
Definiert den Rückweg: Wie gelangen fertig trainierte Modelle in die Live-Pipeline?
- **Box 4 → Box 2 (Lokaler Transfer, Hetzner VPS):**
  Trainierte Weights (Temporal Graphs, Agent-Configs) werden über ein Git-basiertes **Model Registry** (`/models/staging/` → `/models/production/`) versioniert. Ein Commit löst den Rollout aus.
- **Box 4 → Box 3 (Cross-Machine Transfer):**
  PPO-Weights für den Allocator oder Risk-Configs (JSON/YAML) wandern per `rsync`/`scp` durch den Tunnel auf den Windows Server.
- **Evidence Gate (Pflicht):**
  Kein Modell darf ohne signierten Backtest-Nachweis promoted werden (gs-quant oder QuantStats Stresstests laufen exklusiv in Box 4). Der Report wird im Git-Audit-Log persistiert und der menschliche Supervisor gibt das finale Veto oder Go.

## 6. Error Handling & Retry-Policy
Eine konsistente Taxonomie für Netzwerk- oder Systemfehler sichert die funktionale Integrität auf allen Schnittstellen:
- **Error Taxonomy:** Transiente Verbindungsfehler münden in Retries (Fail-Safe), während logische Code-Ausnahmefehler oder korrupte Pakete einen direkten Abort (Fail-Fast) inklusive Alert auslösen.
- **ZMQ Message Corruption (Box 1 → Box 2):** Fehlerhaft serialisierte Numpy-Arrays (z.B. durch Checksummen-Mismatches auf der Leitung) werden strikt verworfen (Discard) und geloggt. Veraltete Daten fallen dann ins Watchdog-Zeitlimit.
- **FastAPI Requests (Box 2 → Box 3):** Serverfehler vom Typ `500 Internal Server Error` führen zu Retries mit Exponential Backoff. Bei permanentem Scheitern greift der reguläre `SUSPEND`.
- **MT5 Execution (`mt5.order_send`):** Broker-Rückgabewerte (Retcodes) werden präzise klassifiziert: Permanente Fehler (Invalid Stops, Market Closed, Invalid Params) lösen einen Alert aus und das Setup wird als "Invalid" verworfen. Requotes bewirken gezielte Retries.
- **Parquet Ferry (Box 1 → Box 4):** Fehlschläge beim Transfer werden mehrfach per Exponential-Backoff versucht. Falls atomare Drops final fehlschlagen, verbleiben sie im lokalen Windows-Safe-State für einen späteren Bulk-Transfer, ohne die Box-1 Live-Pipeline zu gefährden. Einen Alert generiert Super Productivity aggregiert nach 24h.

---
→ Verwandte Kapitel: [[04-blackbox-mt5|04. Blackbox 3: MT5 Execution Bridge]] | [[07-memory-and-infra|07. The OS: Memory & Infrastructure]]


========================================
FILE: docs/06-projekt-management.md
========================================
---
aliases: []
tags: []
related: [[00-MOC-Trading-System]]
trust: deprecated
last_reviewed: 2026-04-19
---
# 06. Meta-Ebene: Projektmanagement (Super Productivity)

> **⚠️ DEPRECATED:** Dieses Kapitel wurde am 2026-04-19 in [[07-memory-and-infra|Kap. 07 §12]] integriert.
> Der Inhalt befindet sich nun unter **"12. Projektmanagement & Shadow-CTO Console"** in Kap. 07.


========================================
FILE: docs/07-memory-and-infra.md
========================================
---
aliases: []
tags: []
related: [[00-MOC-Trading-System]]
trust: canonical
last_reviewed: 2026-04-19
---
# 07. The Operating System: Memory & Infrastructure

*Dieses Modul beschreibt die Dual-Server-Architektur des Systems. Das "Brain" (Blackbox 2 & 4, OpenClaw) läuft auf einem dedizierten Hetzner Linux VPS. Die "Muscle" (MT5 Terminal, Box 1 Data-Pull, Box 3 Validation Middleware) operiert physisch getrennt auf einem Windows Server aufgrund von Abhängigkeitszwängen der MT5-API. Beide Instanzen sind exklusiv über ein sicheres Tailscale VPN miteinander verbunden. Zudem definiert dieses Kapitel das deterministische Git-Memory-System zur Vermeidung von "Context Poisoning".*

## 1. OpenClaw & GitHub Stack (Das Zwei-Repos Konzept)

Anstelle von Vektor-Datenbanken (wie SQLite oder OpenFang), die anfällig für "Context Poisoning" sind, verlässt sich das System auf deterministische, Git-basierte Repositories als primäres Langzeitgedächtnis. Um "Context Poisoning" über Maschinengrenzen hinweg zu stoppen, gibt es **zwei isolierte Git-Repositories**:
- `trading-brain-linux`: Beinhaltet Box 2 und Box 4 auf dem Hetzner VPS. Hier operiert OpenClaw aktiv als Architekturentwickler.
- `execution-mt5-windows`: Beinhaltet das reine Execution und Data Pulling Framework auf dem Windows-Server. Dieser Code wird separat verwaltet, um zu verhindern, dass experimenteller AI-Code das Execution-System (Risk-Diktator) zerstört.
Das OpenClaw-Betriebssystem läuft auf dem Hetzner VPS.

### Orchestrator vs. Executor (Think vs. Do)
Die Architektur erzwingt eine strikte Rollentrennung, um Kontext-Verlust zu verhindern:
- **OpenClaw (Orchestrator):** Fungiert als Tech-Lead. Es schreibt nicht zwingend den Code, sondern hält den *Full Project Context*, analysiert Probleme, zerlegt sie in Tasks und verfasst präzise, zielgerichtete Prompts.
- **Agent (Executor/Claude Code):** Erhält nie den gesamten Kontext-Blob, sondern nur isolierte, spezifische Tasks mit harten "Acceptance Criteria". Dies schützt vor *Agent Drift*.

### Die Verzeichnis-Struktur
```text
/open-claw-workspace (Git Repo auf Hetzner VPS)
├── /agents               # Die Agenten-Konfiguration
│   ├── SOUL.md           # Globale Werte (C-Level Identität)
│   └── AGENTS.md         # Die strikte Befehlskette
├── /memory               # Transparenter Zustand
│   └── decisions.md      # Das permanente Logbuch für Korrekturen
├── /scripts              # Python "Gates" (Mechanische Veto-Scripts)
└── /projects             # Workspace für isolierte Agenten
```

## 2. Deterministisches Gedächtnis (`decisions.md`)

Die wichtigste Datei für das langfristige Alignment des Systems ist `decisions.md`. Sie verhindert "Agenten-Amnesie".
- Reagiert der menschliche Supervisor auf einen Fehltritt der KI ("Beachte ab sofort den VIX!") oder lehnt er einen Trade ab, wird die Vorgabe sofort mit Datum in die `decisions.md` geschrieben.
- Grundsatz: **Write First, Speak Second**. Ein Agent darf nicht bloß verbal zustimmen. Er muss die Änderung persistieren, sonst ist sie für das System (beim nächsten Neustart) nie passiert.

### Coding-Agent Disziplin & Auto-Memory
Wenn dedizierte CLI-Agenten (z. B. Claude Code oder Antigravity) Tasks abarbeiten, unterliegen sie einem methodischen Framework:
1. **Auto-Memory / Self-Learning:** Jeder Agent muss über ein projektisoliertes Lern-Gedächtnis (z.B. `autoMemoryEnabled`) verfügen, um Build-Gotchas, TypeScript-Regeln und Quirks im Dateisystem sitzungsübergreifend zu behalten, anstatt sie jedes Mal neu "ausprobieren" zu müssen.
2. **Superpowers Discipline:** Agenten agieren nicht als "Chat-Assistenten", sondern TDD-gesteuert. Ein defektes Modul wird nicht erraten, sondern über ein strukturiertes Debugging gelöst: Test schreiben → Fehlschlag provozieren → Code fixen → Test passieren lassen. Das verhindert blinde Code-Zerstörung.

## 3. The Scripts: Mechanische Sicherheits-Gates

Reines Prompting (wie "Bitte lies vorher die Regeln") ist statistisch ineffizient und bricht in komplexen Deep-Search-Trees oft ab. Das Setup nutzt stattdessen harte Python-Skripte, um Agenten-Korrektheit zu erzwingen:

- **The Context Gate (`context_gate.py`):** Bevor der Lead-Agent eine Entscheidung trifft oder einen Task anspannt, zwingt ihn das Python-Gate auf OS-Ebene, die aktuellen Regeln aus der `decisions.md` zu laden (Mechanische Absicherung der Workspace-Regeln).
- **The Evidence Gate (`evidence_gate.py`):** Ein Task (z.B. "Code-Optimierung für die MT5-Verbindung" in der Sandbox) wird erst dann vom System auf "Done" (oder als freigegeben für Box 3) gesetzt, wenn der Agent einen Commit-Hash und konkreten Beweis (z.B. Test-Logs) mitliefert. Dies tilgt Phantom-Arbeit.

## 4. Antigravity Deployment Hierarchie

Das System nutzt die native Hierarchie der Antigravity-Plattform zur Steuerung der Agenten-Intelligenz ("Progressive Disclosure"), um "Context Rot" und Latenz zu minimieren:

1. **Global Rules (`~/.agent/rules/`):** Permanent aktive Verhaltens-Leitplanken (z.B. "Handel nur während der Session-Zeiten", "Keine gefährlichen Terminal-Befehle").
2. **Workspace Skills (`.agent/skills/`):** On-Demand Kapazitätserweiterungen. Ein Agent lädt spezialisiertes Wissen (z.B. `sjm-training-skill` oder `mt5-bridge-deploy`) nur dann, wenn der Task es erfordert. Dies hält das aktive Gedächtnis schlank.
3. **Workflows (`.agent/workflows/`):** Vordefinierte Makros für den menschlichen Supervisor (z.B. `/doc-integrity`), die komplexe Abläufe deterministisch steuern.

## 5. The Reasoning Chain (Thought Signatures)

In agentenbasierten Multi-Agent Trading-Systemen ist die Nachvollziehbarkeit entscheidend. Das System nutzt die **Thought Signature** Technologie des Gemini 3 Action Models:
- Jede Entscheidung (Logik-Kette) erzeugt eine verschlüsselte Signatur des internen Denkprozesses.
- Diese Signatur wird in der `decisions.md` mitgeführt. Dies stellt sicher, dass der Agent über mehrere asynchrone API-Calls hinweg seine "Reasoning Line" behält, ohne den gesamten Chat-Verlauf (und damit Tokens) mitschleifen zu müssen.

## 6. Asynchroner Archivar (Latenz-Schutz)

Da Git-Push-Zyklen oder Dateilesezugriffe systembedingt Millisekunden bis Sekunden dauern, existiert eine strenge Blockade zwischen der Memory-Engine auf Linux (Box 2) und der Trading-Execution auf Windows (Box 3):
- Das Commit-Handling und Log-Pushing zu GitHub übernimmt ein isolierter, asynchroner Cronjob ("Der Archivar-Agent").
- Signal-Emissionen innerhalb von Box 2 laufen vollständig asynchron zum physischen Git-Log-Prozess. Der *Hot-Path* (das Senden vom State an die FastAPI Bridge in Box 3) wird niemals durch blockierende Festplatten-I/O-Locks der Memory-Engine verlangsamt. Alle ausführenden Systeme arbeiten strikt entkoppelt.

## 7. Tailscale VPN — Setup & Absicherung

*Die Tailscale VPN-Verbindung ist das Rückgrat der Dual-Server-Architektur. Sie verbindet Hetzner VPS (Brain) mit dem Windows Server (Muscle) und ersetzt unsichere Public-Exposes.*

### 7.1 Installation & Initialisierung

| Komponente | Befehl | Zweck |
|---|---|---|
| Hetzner VPS (Ubuntu/Debian) | `curl -fsSL https://tailscale.com/install.sh \| sh` | Tailscale Daemon installieren |
| Windows Server | MSI-Installer von tailscale.com | GUI-Client + Service |
| Auth | `tailscale up --auth-key <key>` | Einmal-Auth gegen Tailscale ACL |

### 7.2 ACL-Konfiguration (Tailnet Policy)

Die `acl.json` im Tailscale Admin-Panel regelt wer mit wem sprechen darf. Für das Trading-System gilt **Zero-Trust, Least-Privilege**:

```json
{
  "acls": [
    {
      "action": "accept",
      "src": ["tag:brain"],
      "dst": ["tag:muscle:3389", "tag:muscle:5555", "tag:muscle:8080"]
    },
    {
      "action": "accept",
      "src": ["autogroup:admin"],
      "dst": ["tag:brain:*", "tag:muscle:*"]
    }
  ],
  "tagOwners": {
    "tag:brain": ["autogroup:admin"],
    "tag:muscle": ["autogroup:admin"]
  }
}
```

- **Brain → Muscle:** Nur Port 3389 (RDP für Wartung), 5555 (ZMQ Data SUB) und 8080 (FastAPI Signal-Endpoint).
- **Muscle → Brain:** Keine direkte Verbindung erlaubt (Uni-direktionaler Signal-Flow).
- **Admin:** Vollzugriff für den menschlichen Supervisor.

### 7.3 Netzwerktopologie & IP-Plan

| Node | Tailscale IP (Beispiel) | Rolle |
|---|---|---|
| `brain-vps` | 100.64.0.10 | Hetzner VPS — Box 2 + Box 4 |
| `muscle-win` | 100.64.0.20 | Windows Server — Box 1 + Box 3 |
| `supervisor-laptop` | 100.64.0.50 | Admin-Zugriff |

→ Alle Kommunikation zwischen Brain und Muscle erfolgt **ausschließlich** über diese Tailscale-IPs. Kein Port-Forwarding, kein offener Port im Hetzner-Firewall-Panel.

### 7.4 Fallback & Heartbeat-Monitoring

| Szenario | Reaktion |
|---|---|
| Tailscale-Daemon abstürzt (Eine Seite) | `watchdog_freshness` erkennt Ping-Ausfall → SUSPEND (Graceful Degradation, s. DECISIONS.md 2026-04-05) |
| Beide Seiten verlieren VPN | Broker-Side SLs schützen offene Positionen. Keine neuen Trades bis Reconnect. |
| Auto-Reconnect | `systemctl enable --now tailscaled` + `tailscale up --operator=$USER` starten Daemon nach Reboot automatisch |

---

## 8. Hetzner VPS Hardening

*Der Hetzner VPS trägt das gesamte "Brain"-System. Er muss gegen Angriffe von außen und unbeabsichtigte Selbstzerstörung geschützt werden.*

### 8.1 Basis-Konfiguration (Post-Install)

```bash
# 1. Root-Login via Password deaktivieren, nur SSH-Key
sed -i 's/^#\(PermitRootLogin\).*/\1 prohibit-password/' /etc/ssh/sshd_config
sed -i 's/^#\(PasswordAuthentication\).*/\1 no/' /etc/ssh/sshd_config
systemctl restart sshd

# 2. UFW Firewall — Nur Essentials
ufw default deny incoming
ufw default allow outgoing
ufw allow 22/tcp    # SSH (nur von Supervisor-IP)
ufw allow from 100.64.0.0/10  # Tailscale-Subnetz erlauben
ufw enable

# 3. Fail2ban — SSH Bruteforce-Schutz
apt install -y fail2ban
# /etc/fail2ban/jail.local:
# [sshd]
# enabled = true
# maxretry = 3
# bantime = 3600
systemctl enable --now fail2ban
```

### 8.2 Unattended Upgrades

```bash
apt install -y unattended-upgrades
dpkg-reconfigure --priority=low unattended-upgrades
```

Automatische Sicherheitsupdates werden installiert, ohne dass der Supervisor eingreifen muss. Kernel-Updates erfordern einen manuellen Reboot.

### 8.3 Benutzer & Berechtigungen

| Benutzer | Rolle | Home | Shell |
|---|---|---|---|
| `supervisor` | Admin, sudo | /home/supervisor | /bin/bash |
| `openclaw` | Service-Account | /opt/openclaw | /usr/sbin/nologin |
| `trading-bot` | Python-Runner | /opt/trading | /usr/sbin/nologin |

- **Kein** Shared Account. Jeder Prozess läuft unter eigenem User.
- `openclaw` und `trading-bot` haben **kein** sudo, **kein** Login.

### 8.4 Backup-Strategie

| Typ | Frequenz | Ziel | Aufbewahrung |
|---|---|---|---|
| Voll-Backup (Snapshots) | Wöchentlich | Hetzner Image-Backup | 4 Wochen |
| Inkrementell (Config) | Täglich (Cron) | S3-kompatibler Storage (z.B. Backblaze B2) | 30 Tage |
| `decisions.md` & `.git` | Jeder Commit | GitHub Remote | Permanent |

---

## 9. OpenClaw Config-Skelett

*OpenClaw ist der Orchestrator (Tech-Lead). Diese Sektion definiert die konkrete YAML-Struktur, nicht nur das Konzept.*

### 9.1 Grundstruktur (`openclaw.yaml`)

```yaml
openclaw:
  version: "1.0.0"
  workspace: "/opt/openclaw-workspace"
  memory:
    decisions_log: "./memory/decisions.md"
    auto_sync: true
    sync_interval_minutes: 5

  agents:
    - name: "architect"
      role: "lead"
      skills:
        - "system-design"
        - "security-review"
      max_context_tokens: 32000
      context_gate: true

    - name: "coder"
      role: "executor"
      skills:
        - "python"
        - "fastapi"
        - "mt5-bridge"
      max_context_tokens: 8000
      context_gate: true
      evidence_gate: true

  routing:
    default: "architect"
    tasks:
      pattern: "\.(py|json|yaml|md)$"
      assign_to: "coder"
    infra:
      pattern: "(firewall|tailscale|backup)"
      assign_to: "architect"
```

### 9.2 Skill-Definition (`skills/mt5-bridge-deploy/skill.yaml`)

```yaml
skill:
  name: "mt5-bridge-deploy"
  version: "1.0"
  description: "Deploy und Update der FastAPI MT5 Bridge"
  triggers:
    - "deploy bridge"
    - "restart mt5"
  steps:
    - action: "context_gate"
    - action: "exec"
      command: "cd /opt/trading && git pull origin main"
    - action: "exec"
      command: "systemctl restart mt5-bridge"
    - action: "evidence_gate"
      check: "systemctl is-active mt5-bridge"
```

---

## 10. Context Gate & Evidence Gate — Implementierung

*Mechanische Veto-Skripte, die Agenten-Korrektheit erzwingen. Keine Prompt-Hoffnungen, harte Python-Logik.*

### 10.1 Context Gate (`scripts/context_gate.py`)

```python
#!/usr/bin/env python3
"""
Context Gate — Zwingt Agenten, decisions.md zu lesen bevor sie handeln.
Exit-Code 0 = Pass. Exit-Code 1 = Block + Error-Nachricht.
"""
import sys
import os
from pathlib import Path

DECISIONS_PATH = Path(__file__).parent.parent / "memory" / "decisions.md"
STALE_THRESHOLD_HOURS = 48

def check_decisions_exists() -> bool:
    if not DECISIONS_PATH.exists():
        return False
    return True

def check_decisions_fresh() -> bool:
    import time
    mtime = DECISIONS_PATH.stat().st_mtime
    age_hours = (time.time() - mtime) / 3600
    return age_hours < STALE_THRESHOLD_HOURS

def check_critical_vetos() -> list[str]:
    """Prüft auf aktive VETOs in decisions.md"""
    vetos = []
    with open(DECISIONS_PATH, "r") as f:
        for line in f:
            if "`VETO`" in line or "| `VETO`" in line:
                vetos.append(line.strip())
    return vetos

def main():
    errors = []

    if not check_decisions_exists():
        errors.append(f"DECISIONS.md nicht gefunden unter {DECISIONS_PATH}")
    elif not check_decisions_fresh():
        errors.append(f"DECISIONS.md ist älter als {STALE_THRESHOLD_HOURS}h — Supervisor-Review erforderlich")

    vetos = check_critical_vetos()
    if vetos:
        errors.append(f"AKTIVE VETOS gefunden: {vetos}")

    if errors:
        print("CONTEXT GATE: BLOCKED", file=sys.stderr)
        for e in errors:
            print(f"  REASON: {e}", file=sys.stderr)
        sys.exit(1)

    print("CONTEXT GATE: PASSED")
    sys.exit(0)

if __name__ == "__main__":
    main()
```

### 10.2 Evidence Gate (`scripts/evidence_gate.py`)

```python
#!/usr/bin/env python3
"""
Evidence Gate — Verlangt Commit-Hash und Test-Log bevor ein Task als "Done" gilt.
"""
import sys
import subprocess
import json
from pathlib import Path

EVIDENCE_PATH = Path(__file__).parent.parent / "memory" / "evidence_log.json"

def validate_commit_hash(commit_hash: str) -> bool:
    try:
        result = subprocess.run(
            ["git", "cat-file", "-t", commit_hash],
            capture_output=True, text=True, timeout=5
        )
        return result.returncode == 0 and "commit" in result.stdout
    except Exception:
        return False

def validate_log_exists(task_id: str) -> bool:
    """Prüft ob ein Test-Log für die Task-ID existiert"""
    log_path = Path(__file__).parent.parent / "logs" / f"{task_id}.log"
    return log_path.exists()

def main():
    if len(sys.argv) < 3:
        print("USAGE: evidence_gate.py <commit_hash> <task_id>", file=sys.stderr)
        sys.exit(1)

    commit_hash = sys.argv[1]
    task_id = sys.argv[2]

    errors = []

    if not validate_commit_hash(commit_hash):
        errors.append(f"Ungültiger Commit-Hash: {commit_hash}")

    if not validate_log_exists(task_id):
        errors.append(f"Kein Test-Log gefunden für Task: {task_id}")

    if errors:
        print("EVIDENCE GATE: BLOCKED", file=sys.stderr)
        for e in errors:
            print(f"  REASON: {e}", file=sys.stderr)
        sys.exit(1)

    # Evidence loggen
    evidence = {"commit": commit_hash, "task_id": task_id}
    with open(EVIDENCE_PATH, "a") as f:
        f.write(json.dumps(evidence) + "\n")

    print("EVIDENCE GATE: PASSED")
    sys.exit(0)

if __name__ == "__main__":
    main()
```

---

## 11. Two-Repo Deployment Pipeline

*Die strikte Trennung von Brain-Code und Muscle-Code verhindert, dass experimentelle AI-Änderungen das Live-Trading-System beschädigen.*

### 11.1 Repository-Struktur

| Repo | Plattform | Inhalt | Branch-Strategie |
|---|---|---|---|
| `trading-brain-linux` | Hetzner VPS → GitHub (privat) | Box 2 (Agents), Box 4 (Lab), OpenClaw Config | `main` = Stable, `develop` = WIP, `feature/*` |
| `execution-mt5-windows` | Windows Server → GitHub (privat) | Box 1 (Data-Pull), Box 3 (MT5 Bridge), Validation | `main` = Stable, `hotfix/*` |

### 11.2 Deploy-Prozess (Brain → Muscle Signal-Flow)

```
┌─────────────────────────────────────────────┐
│ 1. Agent pusht Feature-Branch an Brain-Repo │
│ 2. Context Gate läuft lokal (pre-push hook) │
│ 3. Pull-Request → Supervisor Review         │
│ 4. Merge nach `main`                        │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│ 5. VPS: `git pull origin main` (Cron, 5min) │
│ 6. Systemd: Service-Reload (wenn nötig)     │
│ 7. Config-Hash wird neu generiert            │
│ 8. FastAPI POST /api/v1/config_sync → Muscle│
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│ 9. Muscle: Empfängt config_hash             │
│ 10. Muscle: Prüft Hash gegen lokale Config  │
│ 11. Bei Match: Config aktualisiert           │
│ 12. Bei Mismatch: SUSPEND + Alert per SMTP  │
└─────────────────────────────────────────────┘
```

### 11.3 Git-Hook: Pre-Push Context Gate

```bash
#!/bin/bash
# .git/hooks/pre-push
# Wird vor jedem Push ausgeführt. Bricht ab wenn Context Gate blockiert.

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
GATE="$SCRIPT_DIR/../../scripts/context_gate.py"

if [ -f "$GATE" ]; then
    python3 "$GATE"
    if [ $? -ne 0 ]; then
        echo "PRE-PUSH GATE: Context Gate blockiert Push. decisions.md prüfen!"
        exit 1
    fi
fi

exit 0
```

### 11.4 Config-Hash Generierung

→ Die kanonische `config_hash`-Berechnung (SHA-256 über `compliance.yaml` + `thresholds.json`) sowie der vollständige Split-Brain Protection Workflow sind in [[10-configuration|Kap. 10 §10.3 und §10.5.3 (SSOT)]] definiert.

---

## 12. Observability & Structured Logging (Box-übergreifend)

*Um "Silent Failures" über die Maschinengrenzen hinweg debuggen zu können, ist ein rein textbasiertes Logging (`print("Fehler")`) unzureichend. Das System erzwingt ein strukturiertes Logging-Konzept.*

### 12.1 structlog + JSON Format
Alle Python-Dienste (Box 1, Box 2, Box 3 FastAPI und Parquet Ferry) nutzen zwingend das `structlog` Paket anstelle der Standard-`logging` Bibliothek.
- **Produktion:** Logs werden strikt als **JSON lines** formatiert.
- **Felder:** Jeder Log-Eintrag enthält zwingend: `timestamp` (ISO8601 UTC), `level`, `logger_name`, `event` und `trace_id`.

### 12.2 Correlation IDs (trace_id)
Jeder initial generierte Data-Tick von Box 1 erhält eine eindeutige UUID (`trace_id`).
- Diese `trace_id` wird als Feld in den ZMQ-Payload injiziert.
- Box 2 liest den Tick, führt die Inferenz aus und nutzt bei ihrem anschließenden POST-Request in Box 3 (`/api/v1/signal`) exakt dieselbe `trace_id` im JSON-Body.
- Box 3 loggt die Annahme oder Ablehnung des Trades unter Nennung dieser `trace_id`.
- Dadurch kann ein kompletter Event-Loop (Tick → Agent → Execution) fehlerfrei nachvollzogen werden.

### 12.3 Monitoring & Dashboards (Loki & Promtail)

Um dem System in der V1-Phase keinen DevOps-Bloat (wie Prometheus-Middleware oder ständiges Metric-Scraping) aufzubürden, verfolgt die Architektur das Prinzip **"Log-Aggregation statt Metric-Scraping"**. Die strukturierten JSON-Logs (aus §12.1) fungieren durch nativen Log-Parser de facto gratis als Metriken.

1. **Promtail (The Shipper):** Ein extrem leichtgewichtiger Service, der auf Windows (Box 1/3) und dem Linux VPS (Box 2) installiert wird. Er tailed die von NSSM/logrotate geschriebenen `.log` Dateien rein passiv und pusht sie über das VPN.
2. **Grafana & Loki (The Observer auf Box 4):**
   - **Isolierung:** Loki (Datenbank) und Grafana (UI) laufen als Docker-Container isoliert auf **Box 4 (The Lab)**. Sollte eine komplexe Dashboard-Abfrage (OOM Memory-Spike) zu einem Crash führen, bleiben die Live-Hotpaths der Systeme (Box 2 und Box 3) völlig unberührt.
   - **Sicherheitsvorgabe (Tailscale-only):** Grafana und Loki **dürfen niemals** an 0.0.0.0 (Hetzner Public IP) gebunden werden. Sie lauschen zwingend **nur auf der Tailscale-IP**, sodass das Dashboard unsichtbar fürs öffentliche Internet bleibt.
3. **Der Datenfluss:**
   `App (JSON stdout) → logrotate/NSSM → Promtail → Tailscale VPN → Loki (Box 4) → Grafana`

**V1 Dashboard Use-Cases (via LogQL `| json` Parser):**
- **VPN/Handshake Latenz:** Zeitdifferenz zwischen Tick-Erzeugung (Box 1) und Signal-Eingang (Box 3) im MT5-Execution Log, verkoppelt durch die exakt selbe `trace_id`.
- **Signal Distribution:** Wie oft feuert Box 2 pro Stunde das Signal `state: 1` im Verhältnis zu `state: 0`?
- **Error Rates:** Zählen und Visualisieren von HTTP 429 Rate Limits, `SUSPEND` Events und ausgelösten SMTP-Alerts für den Supervisor.

---

## 13. Secrets Management (SOPS & age)

*Zur Vermeidung von Plaintext-Secrets in Config-Dateien oder unverschlüsselten Environment-Variablen (`.env`) setzt das System auf Mozilla SOPS in Kombination mit `age`.*

### 13.1 Prinzip der Entschlüsselung
- **Keine `.env`-Dateien** mit Klartext-Keys (Broker-Logins, SMTP-Passwörter) auf dem Datenträger.
- Dateien wie `secrets.enc.env` werden verschlüsselt in das Git-Repo (`trading-config`) committed.
- Die Maschinen (Brain-VPS und Muscle-Win) besitzen jeweils einen asymmetrischen `age`-Private-Key (Out-of-Band provisioniert).
- Jeder Systemd-Service oder NSSM-Eintrag entschlüsselt die Datei beim Start *on-the-fly* direkt in den flüchtigen Speicher (RAM).

---

## 12. Projektmanagement & Shadow-CTO Console (ehem. Kap. 06)

*Die operative Steuerung des menschlichen Supervisors über das System.*

### 12.1 Super Productivity als Execution Console
"Super Productivity 18.0" fungiert als persönliches, lokales "Shadow-CTO" Dashboard. Es ersetzt kein schwerfälliges Multi-User Projekt Management (wie Jira), sondern steuert die operative Arbeit des Solo-Entwicklers.

- **Strikter Kontext-Fokus:** Die Architektur ist in autonome Blackboxen getrennt (Kap. 01). Entsprechend strikt ist das Timeboxing: Eine 45-minütige Entwicklungs-Session darf **niemals** den Kontext zwischen Box 1 (Data) und Box 3 (Execution) mischen. Kontext-Switches sind verboten.
- **Overengineering-Schutz:** Der integrierte Pomodoro-Timer (mit blockierenden Desktop-Overlays) erzwingt harte Pausen. Essenziell, um das Abdriften in endlose KI-Agenten "Rabbit-Holes" zu verhindern.
- **Execution Tracking:** Klare Trennung zwischen "Build" (KI generiert Code) und "Review" (Mensch prüft Code). Aufgaben werden als granulare Sub-Tasks getrackt.

### 12.2 REST-API Automatisierung (Post-MVP)
Super Productivity 18.0 bietet eine lokale REST-API (`http://localhost:5000`). Post-MVP können KI-Agenten über ein Python-Relayskript eigenständig Tickets aus Fehlerlogs des Labs in die Supervisor-Inbox pushen (`POST /api/v1/tasks`).

### 12.3 Alerting-Minimalismus (V1)
- **Keine Abhängigkeiten:** V1 verzichtet bewusst auf fragile Konstrukte wie n8n-Workflows oder komplexe Telegram-Bots.
- Fehler-Alerts werden ausfallsicher als simple **SMTP E-Mails** übermittelt (→ Ref: [[99-deploy-runbook|Kap. 99]]).
- Die Priorisierung und Einplanung geschieht bewusst **manuell** durch den menschlichen "Shadow-CTO" (Evidence Gate).

---

*Weiterführend:* Die High-Level-Architektur inkl. aller Blackbox-Rollen definiert [[01-system-architektur|System-Architektur & 3-Blackbox Design]].



========================================
FILE: docs/08-backtesting-lab.md
========================================
---
aliases: []
tags: []
related: [[00-MOC-Trading-System]]
trust: canonical
last_reviewed: 2026-04-19
---
# 08. The Improvement Lab: Backtesting & Metriken (Box 4)

*Dieses Modul beschreibt die "Offline"-Umgebung des Systems. Um die Live-Execution in Box 2 (Hot-Path) innerhalb der 3-5 Minuten SLA zu halten, werden schwere historische Analysen, Backtests und Stresstests in eine vollständig isolierte 4. Blackbox ausgelagert.*

## 1. Die strikte Trennung: Live vs. Lab

In frühen Entwürfen wurde erwogen, Tools wie `ffn` oder `QuantStats` direkt im Scientist-Agenten (Box 2) laufen zu lassen. Dies wurde **strikt abgelehnt (Veto)** aus folgenden Gründen:
- **Time-to-Decision:** Auch im Swing-Trading (Hold-Time: 2h - 2w) muss die "Data-to-Decision" Pipeline SLA (3-5 Minuten) eingehalten werden. Iterative Backtests oder Monte-Carlo-Simulationen auf dem Live-Tick durchzuführen, sprengt dieses Fenster.
- **Daten-Sourcing:** Box 1 liefert nur Live-Streaming-Daten zur reinen State-Generierung. Für historische Benchmarks ("wie hat sich dieses Setup vor 3 Jahren verhalten") werden lokale Parquet-Datenbanken von jahrelangen Ticks benötigt.

**Die Lösung:** Box 2 (The Scientist) feuert *nur* auf Basis vortrainierter Modelle (die aus dem Lab stammen) und verarbeitet aktuelle Ticks + Kontext. Das "Erlernen" und Validieren der Signale geschieht Offline im Lab.

## 2. Daten-Architektur des Labs

Woher kommen die Daten für das Backtesting? Es gibt keine API-Abfragen im Hot-Path des Labs, da dies bei Millionen von Datenpunkten zu Rate-Limits oder extremen Verzögerungen führt.

- **Die Local Vault (Parquet):** Das Lab baut auf einer physisch getrennten, lokalen Datei-Schicht aus **Parquet-Dateien** auf. Parquet bietet effizientes Columnar-Storage ohne den Overhead eines separaten Datenbankservers.
- **Data-Ingestion:** Die Daten gelangen über den *Parquet Ferry* Daemon von Box 1 (Windows) ins Lab. Um Race-Conditions bei Backtests während aktiver Übertragungen zu vermeiden, respektiert das Lab zwingend den File-Locking-Mechanismus (`.lock`-Dateien) der Ferry beim atomaren Rename. → Ref: [[05-schnittstellen|Schnittstellen §4: The Parquet Ferry]] für die technische Transferspezifikation (Atomic Staging, Bidirectional Rename).
- **Vorteil:** Backtests laufen auf Linux-SSDs/NVMe mit maximaler I/O-Geschwindigkeit ohne jeglichen Netzwerk- oder Live-API-Overhead.

### 2.1 Parquet Schema-Validation (A-4)

> **Architektur-Entscheidung:** Um "Garbage In, Garbage Out" beim Training zu verhindern, validiert Box 4 jede eingehende Parquet-Datei **nach** dem atomaren Rename und **vor** der Freigabe für Backtests.

| Prüfung | Methode | Verhalten bei Fehler |
|---------|---------|---------------------|
| **Schema-Konformität** | Pandera / manueller `assert` auf erwartete Spalten + Datentypen | Datei in `/quarantine/` verschieben, Alert loggen |
| **Min-Row-Count** | `len(df) >= MIN_ROWS` (z.B. 100 für OHLCV) | Datei verwerfen (vermutlich unvollständiger Transfer) |
| **Timestamp-Kontinuität** | Gap-Check: Max. erlaubte Lücke zwischen Timestamps (z.B. 2× Timeframe) | Warning-Log, Datei nutzbar aber mit Qualitäts-Flag |
| **NaN/Inf-Anteil** | `df.isna().sum() / len(df) < 0.01` | Datei in `/quarantine/` bei > 1% NaN |

## 3. Die Toolbox des Labs

Im Improvement Lab kommen die folgenden Werkzeuge zum Einsatz, die den Agenten in isolierten Tasks zur Verfügung stehen:

### A. Der "Lügendetektor" (`ffn`)
- **Einsatz:** Wenn ein Agent im Lab eine neue Strategie-Variante des Entropie-Filters entwickelt hat, jagt er die theoretischen Resultate durch `ffn` (Financial Functions for Python).
- **Metriken:** Fokus auf *Risk-Adjusted Returns* wie Information Ratio, Calmar Ratio und Max Drawdown Dauer.
- **Ziel:** Verhindern von Overfitting.

### B. Stresstest & Tail-Risk (`QuantStats`)
`QuantStats` ist das offizielle Stresstest-Tool für Box 4. Es liefert Drawdown-Tearsheets und Tail-Risk-Metriken für die Bewertung durch den Evidence Gate.
- **Evidence:** Der Agent muss einen von `QuantStats` generierten Report als Beweis im Git-Log (`decisions.md` oder in einem Audit-Log) hinterlegen, bevor der System-Administrator den Rollout absegnet.

### C. Experiment Tracking (`MLflow`)
- **Einsatz:** Da Data-Versioning asynchron und verlässlich durch die Parquet Ferry reguliert wird (Box 1 → Box 4), fokussiert sich Box 4 rein auf das Tracking von Parametern und Leistungskennzahlen. DVC wäre hier Overhead.
- **Integrität:** MLflow läuft als lokaler Tracking-Server (`sqlite:///mlruns.db`) exklusiv auf dem Hetzner-Server im Lab.
- **Evidence:** Jeder Backtest-Run sendet seine ermittelten Metriken (ausnahmslos evaluiert durch `ffn` und `QuantStats`), Thresholds und **zwingend** seinen `config_hash` an diese lokale SQLite-Datenbank, um deterministische Git-Zustände mit Metriken zu verknüpfen. → Ref: [[10-configuration|Kap. 10: Config-Hash Berechnung]]

## 4. Lab-Toolbox — Konkrete Projektstruktur

*Das Improvement Lab braucht eine klare Verzeichnisstruktur, damit Agenten isoliert arbeiten können.*

```
/opt/improvement-lab/
├── /data                      # Parquet-Daten (via Ferry synchronisiert)
│   ├── /ticks                 # Rohe Tick-Daten (symbol, timestamp, bid, ask)
│   ├── /ohlcv                 # Aggregierte OHLCV-Daten (1m, 5m, 1h, 1d)
│   ├── /metadata              # OpenBB News, Sentiment-Scores
│   └── /quarantine            # Fehlgeschlagene Schema-Validierungen (A-4)
├── /strategies                # Strategie-Sandbox (jedes subdir = ein Experiment)
│   ├── /entropy_filter_v1
│   │   ├── config.json        # Parameter (Thresholds, Timeframes)
│   │   ├── backtest.py        # NumPy/Pandas Backtest-Skript
│   │   ├── results/           # Ausgabe-Reports
│   │   │   ├── metrics.json   # ffn-Metriken
│   │   │   ├── trades.csv     # Einzel-Trades
│   │   │   └── equity_curve.png
│   │   └── stress_report.md   # QuantStats Tail-Event Report
│   └── /multi_tf_agent_v2
├── /models                    # Vortrainierte Modelle (für Box 2 Promotion)
│   ├── /production            # Aktuell aktive Modelle (symlink zu Box 2)
│   └── /staging               # Neue Kandidaten (warten auf Supervisor-Freigabe)
├── /mlruns                    # MLflow SQLite DB & Local Artifacts (Tracking-Historie)
├── /training                  # RL & Graph Network Pipelines
│   ├── /ppo                   # Proximal Policy Optimization Meta-Allocator
│   ├── /gat                   # Graph Attention Networks — Entropie
│   └── notebooks/             # Explorative Jupyter-Notebooks
├── /scripts                   # Helfer-Skripte
│   ├── compare_runs.py        # Skript zum Metriken-Vergleich
│   ├── data_download.py       # Trigger Box 1 Parquet Ferry Pull
│   ├── run_backtest.py        # CLI Entrypoint (aus Kap. 06 / Super Prod)
│   ├── train_ppo.py           # RL Training Loop Start
│   └── report_gen.py          # Automatischer Metriken-Report (ffn / quantstats)
└── README.md
```

### 4.1 Parquet-Format-Spezifikation

| Datei | Spalten | Frequenz | Größe (1 Jahr BTC) |
|---|---|---|---|
| `ticks_{symbol}_{date}.parquet` | timestamp, bid, ask, volume | Raw | ~2 GB |
| `ohlcv_{symbol}_{tf}.parquet` | timestamp, open, high, low, close, volume | 1m/5m/1h/1d | ~20 MB |
| `metadata_{symbol}_{date}.parquet` | timestamp, sentiment, news_score, vix | On-Event | ~5 MB |

→ Alle Timestamps: **UTC**. Keine Zeitzonenverwirrung.

---

## 5. Backtesting-Framework — V1 Architektur

### 5.1 Vermeidung von Tool-Bloat
Gemäß Architektur-Entscheidung (DECISIONS.md) verzichten wir im Rahmen des V1-Scopes auf externe Backtesting-Suites wie VectorBT, Backtrader oder Lean, um den Architektur-Bloat gering zu halten. Ein holistisches Backtesting-Modul wird erst in einem späteren Ausbaustadium integriert. 

Stattdessen basiert das V1-Design auf **CPU-optimierter, puristischer `numpy`/`pandas`-Logik**:
1. Vektorielle `numpy`-Operationen simulieren auf den Parquet-Series das Equity Curing.
2. Das resultierende PnL-Series-Objekt wird ohne Umwege in `ffn` (für klassische Metriken wie Sharpe und Drawdown) und `QuantStats` (für den Stresstest) gespeist.
3. Sämtliche dieser Berechnungen werden in MLflow festgehalten.

### 5.2 Walk-Forward-Validation Pipeline

```text
┌─────────────────────────────────────────────────┐
│ Walk-Forward-Validation (Train → Test → Slide)  │
├─────────────────────────────────────────────────┤
│                                                 │
│  ┃━━Train━━┃Test┃                               │
│           ┃━━Train━━┃Test┃                      │
│                    ┃━━Train━━┃Test┃             │
│                             ┃━━Train━━┃Test┃    │
│                                                 │
│  Out-of-Sample (OOS) Performance aggregieren    │
│  → Nur Modelle mit konsistentem OOS > IS * 0.8  │
│    werden für Promotion kandidieren              │
└─────────────────────────────────────────────────┘
```

### 5.3 Backtest-Runner CLI mit MLflow-Tracking (`scripts/run_backtest.py`)

```python
#!/usr/bin/env python3
"""
Backtest-Runner — CLI-Interface für V1 NumPy/ffn Pipeline.
Usage: python run_backtest.py --strategy entropy_filter_v1 --symbol BTCUSD
"""
import argparse
import json
import hashlib
from pathlib import Path
import mlflow
import pandas as pd
import numpy as np
import ffn

def load_strategy_config(strategy_name: str):
    config_path = Path(__file__).parent.parent / "strategies" / strategy_name / "config.json"
    if not config_path.exists():
        raise FileNotFoundError(f"Strategy config not found: {config_path}")
    with open(config_path, "rb") as f:
        config_hash = hashlib.sha256(f.read()).hexdigest()
    with open(config_path, "r") as f:
        config = json.load(f)
    return config, config_hash

def run_numpy_backtest(df: pd.DataFrame, config: dict) -> dict:
    """CPU-optimierte Equity-Curve Simulation und ffn Auswertung."""
    # Vektor-Auswertung analog zum Numpy-Speed in V1 (Placeholder)
    dates = df["timestamp"]
    equity = np.linspace(100, 150, len(dates))  # Dummy Equity Curve
    
    # Ausnahmslos ffn (Lügendetektor) zur Metriken-Erhebung
    perf = ffn.calc_stats(pd.Series(equity, index=dates))
    stats = perf.stats
    
    return {
        "total_return": stats.get("total_return", 0),
        "sharpe_ratio": stats.get("daily_sharpe", 0),
        "max_drawdown": stats.get("max_drawdown", 0)
    }

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--strategy", required=True)
    parser.add_argument("--symbol", required=True)
    args = parser.parse_args()

    # Config und deterministischen Hash laden
    config, config_hash = load_strategy_config(args.strategy)
    df = pd.DataFrame({"timestamp": pd.date_range("2023-01-01", periods=1000)}) # Dummy-Lader
    
    # MLflow Setup (Lokale DB)
    mlflow.set_tracking_uri("sqlite:///../mlruns.db")
    mlflow.set_experiment(args.strategy)

    with mlflow.start_run() as run:
        # PFLICHT: Config-Hash loggen (deterministisches Tracking)
        mlflow.log_params(config)
        mlflow.log_param("config_hash", config_hash)
        mlflow.log_param("symbol", args.symbol)
        
        # CPU-Logik / ffn Execution
        results = run_numpy_backtest(df, config)
        
        # Performance Metriken
        mlflow.log_metrics({
            "sharpe_ratio": float(results["sharpe_ratio"]),
            "max_drawdown": float(results["max_drawdown"])
        })
        
        print(f"✅ Run abgeschlossen. MLflow Run-ID: {run.info.run_id}")
        print(f"🔒 Config-Hash: {config_hash}")

if __name__ == "__main__":
    main()
```

---

## 6. Model Promotion Pipeline (Lab → Live)

*Ein Modell, das im Lab trainiert wurde, darf nicht direkt in den Live-Betrieb übernommen werden. Es durchläuft einen strikten Promotion-Prozess.*

```text
┌─────────────┐     ┌─────────────┐     ┌──────────────┐     ┌──────────────┐
│ 1. Training │ ──▶ │ 2. Backtest │ ──▶ │ 3. Staging   │ ──▶ │ 4. Production│
│   (Box 4)   │     │  (Box 4)    │     │  (Box 2 read)│     │  (Box 2 use) │
└─────────────┘     └─────────────┘     └──────────────┘     └──────────────┘
     │                    │                    │                    │
     ▼                    ▼                    ▼                    ▼
  Config             metrics.json        Supervisor           Live Trading
  parametrisiert     + stress_report     Approval via
                     + OOS > 0.8*IS      Git-Merge +
                     + MLflow Run-ID     Config-Hash Sync
                                          (Evidence Gate)
```

**Zusatz zum Evidence Gate:** Ein von `ffn` und `QuantStats` abgesegneter Run in MLflow liefert eine eindeutige `run_id`. Diese `run_id` muss als hieb- und stichfester Beweis (z.B. im Commit Log oder in einem Ticket) im Pull-Request zwingend eingebettet werden. Ohne nachweisbare `run_id` mit verifiziertem Hash verweigert der Supervisor-Gatekeeper den Push zu Box 2.

### 6.2 Promotion-Skript (`scripts/promote_model.py`)

```python
#!/usr/bin/env python3
"""
Model Promotion — Verschiebt ein Modell von /staging nach /production
mit Validation und Config-Hash Update.
"""
import hashlib
import json
import shutil
import sys
from pathlib import Path

LAB_ROOT = Path(__file__).parent.parent
STAGING_DIR = LAB_ROOT / "models" / "staging"
PRODUCTION_DIR = LAB_ROOT / "models" / "production"
CONFIG_PATH = LAB_ROOT.parent / "config" / "trading_config.json"

MIN_SHARPE = 1.0
MAX_DRAWDOWN = -0.15

def validate_metrics(metrics_path: Path) -> bool:
    with open(metrics_path) as f:
        metrics = json.load(f)
    sharpe = metrics.get("sharpe_ratio", 0)
    dd = metrics.get("max_drawdown", 0)
    if sharpe < MIN_SHARPE:
        print(f"BLOCKED: Sharpe {sharpe} < {MIN_SHARPE}", file=sys.stderr)
        return False
    if dd < MAX_DRAWDOWN:
        print(f"BLOCKED: Max DD {dd} < {MAX_DRAWDOWN}", file=sys.stderr)
        return False
    print(f"Metrics OK: Sharpe={sharpe}, DD={dd}")
    return True

def update_config_hash():
    with open(CONFIG_PATH, "rb") as f:
        config_hash = hashlib.sha256(f.read()).hexdigest()
    with open(CONFIG_PATH, "r+") as f:
        config = json.load(f)
        config["model_config_hash"] = config_hash
        f.seek(0)
        json.dump(config, f, indent=2)
        f.truncate()
    print(f"Config-Hash aktualisiert: {config_hash}")

def promote(model_name: str):
    staging_model = STAGING_DIR / model_name
    prod_model = PRODUCTION_DIR / model_name
    metrics_path = staging_model / "results" / "metrics.json"

    if not staging_model.exists():
        print(f"BLOCKED: Modell '{model_name}' nicht in Staging gefunden", file=sys.stderr)
        sys.exit(1)

    if not metrics_path.exists():
        print(f"BLOCKED: Keine metrics.json für '{model_name}'", file=sys.stderr)
        sys.exit(1)

    if not validate_metrics(metrics_path):
        sys.exit(1)

    # Verschieben (staging → production)
    if prod_model.exists():
        shutil.rmtree(prod_model)
    shutil.move(str(staging_model), str(prod_model))

    update_config_hash()
    print(f"✅ Modell '{model_name}' nach Production promoted")

def main():
    if len(sys.argv) < 2:
        print("USAGE: promote_model.py <model_name>")
        sys.exit(1)
    promote(sys.argv[1])

if __name__ == "__main__":
    main()
```

---

## 7. Machine Learning Sandbox (RL & Graph Networks)

Das Lab ist exklusiver Gastgeber für rechnerisch intensives Machine Learning. Da das Linux VPS **CPU-only** operiert (keine dedizierte GPU vorhanden), sind die Trainingspipelines strikt auf Multiprocessing und vektorisierte Batch-Verarbeitung ausgelegt. Da Box 4 komplett offline operiert, sind verlängerte Trainingszeiten ("Overnight-Runs") architektonisch unproblematisch:
- **Temporal Graph Encoders:** Statt starrer Filter berechnen Agenten historische Verteilungen als Graph-Strukturen, um "Market Folding" / Entropie-Bridges für den **Box 2 Gatekeeper** auf CPU-Basis robuster zu kalibrieren.
- **Proximal Policy Optimization (PPO):** Der "Risk-Diktator" und Capital Allocator in Box 3 funktionieren konzeptionell wie ein **Meta-Agent**. Im Lab wird dieser Meta-Agent (rein auf historischen Daten) mittels Reinforcement Learning darauf trainiert, wie Kapital am besten dynamisch zwischen korrelierenden Sub-Agenten umgeschichtet wird. Die fertig trainierten Gewichte *(Weights)* werden dann als "Production Config" in den Live-Systemen gestaged.

---

*Zusammenfassung:* Das System bleibt im Kern (Box 1-3) auf Latenz und Ausführung optimiert. Intelligenz, RL-Training (PPO) und das Offline-Staging der State-Generierung finden exklusiv in der isolierten Box 4 (The Improvement Lab) auf Basis lokaler, historischer Daten statt.

---

*Weiterführend:* Wie die trainierten Modelle aus dem Lab in die Live-Pipeline gelangen (Model Promotion), spezifiziert [[05-schnittstellen|API & Schnittstellen-Spezifikation §5]]. Die Live-Agenten, die diese Modelle konsumieren, beschreibt [[03-blackbox-agents|Blackbox 2: The Scientist]]. Die Gesamtarchitektur zeigt [[01-system-architektur|System-Architektur & 3-Blackbox Design]].


========================================
FILE: docs/09-testing-strategie.md
========================================
---
aliases: []
tags: []
related: [[00-MOC-Trading-System]]
trust: canonical
last_reviewed: 2026-04-19
---
# 09. Testing-Strategie

*[Dieses Kapitel definiert die Test-Pyramide für das Hybrid AI-Trading System — von isolierten Unit-Tests über Integrations-Tests der Schnittstellen bis zum Paper-Trading Dry-Run. Der Fokus liegt auf reproduzierbaren, deterministischen Tests, die keine Live-Marktverbindung benötigen.]*

## 1. Test-Philosophie & Scope

Das Trading-System verarbeitet echtes Kapital und darf nicht "im Live-Betrieb debuggt" werden. Jede kritische Komponente muss vor der Inbetriebnahme automatisiert prüfbar sein.

### Test-Pyramide

| Ebene | Scope | Werkzeug | Häufigkeit |
|---|---|---|---|
| **Unit Tests** | Einzelne Funktionen (Entropie-Berechnung, SL/TP, Volume) | `pytest` | Bei jedem Commit |
| **Integration Tests** | Schnittstellen (FastAPI, ZMQ, Heartbeat-IPC) | `pytest` + Mocks | Bei jedem Commit |
| **System Tests** | End-to-End Pipeline (Data → Agent → State) | Python-Scripts | Nightly |
| **Paper Trading** | Dry-Run gegen MT5 Demo | MT5 Demo-Konto | Vor jedem Live-Deploy |

### Ausschlüsse
- **Keine GPU-Tests im CI:** Da das System CPU-only läuft, entfallen CUDA-spezifische Tests.
- **Keine Live-Broker-Tests im CI:** Order-Tests laufen ausschließlich lokal gegen ein MT5-Demo-Konto.

## 2. Unit Tests

Unit-Tests sind die Basis. Sie müssen **schnell** (< 1 Sekunde pro Test), **deterministisch** und **unabhängig** von externer Infrastruktur sein.

### 2.1 Kritische Berechnungen

Folgende Funktionen MÜSSEN Unit-Tests mit 100% Branch-Coverage haben:

| Funktion | Test-Fokus | Prop-Firm-Relevanz |
|---|---|---|
| `calculate_entropy()` | Korrekte Inversion: H↑ = Go, H↓ = No-Go. Edge-Cases: leeres Array, NaN | Signal-Qualität |
| `calculate_stop_loss()` | ATR-basierter SL, Mindestabstand (`trade_stops_level`) | MT-02, PF-02 |
| `calculate_position_size()` | Risk-% vom Equity, Lot-Step Normalisierung (`volume_step`) | MT-01, PF-01 |
| `check_drawdown()` | Static vs. Trailing DD, Midnight-CEST Reset | PF-01, PF-02 |
| `signal_matrix()` | Regime × Entropie → State {0, 1}. Kein `-1` in V1 | Kap. 03 |
| `normalize_volume()` | Round-to-Step, Min/Max-Volume-Clamps | MT-01 |

### 2.2 Test-Struktur

```
tests/
├── unit/
│   ├── test_entropy.py
│   ├── test_risk_management.py      # SL, TP, DD
│   ├── test_position_sizing.py      # Lot-Berechnung
│   └── test_signal_matrix.py        # State-Machine {0, 1}
├── integration/
│   ├── test_fastapi_bridge.py       # /api/v1/signal Endpoint
│   ├── test_zmq_pipeline.py         # Box 1 → Box 2
│   └── test_heartbeat_ipc.py        # GlobalVariableSet Simulation
├── fixtures/
│   ├── sample_ticks.json            # Mock-Tick-Daten
│   ├── mock_mt5_responses.py        # MT5 API Mocks
│   └── config_test.yaml             # Test-Konfiguration
└── conftest.py                      # Shared Fixtures
```

### 2.3 Fixture-Pattern

Alle Tests arbeiten mit **Mock-Daten**, nie mit Live-Verbindungen:

```python
# tests/fixtures/mock_mt5_responses.py
@pytest.fixture
def mock_mt5_symbol_info():
    return {
        "symbol": "BTCUSD",
        "volume_min": 0.01,
        "volume_max": 100.0,
        "volume_step": 0.01,
        "trade_stops_level": 150,  # Points
        "digits": 2
    }

@pytest.fixture
def sample_tick_data():
    return [
        {"time": "2026-04-01T10:00:00", "bid": 85000.00, "ask": 85001.50, "volume": 120},
        {"time": "2026-04-01T10:00:01", "bid": 85002.00, "ask": 85003.50, "volume": 95},
        # ... 50+ Ticks für Rolling Window
    ]
```

### 2.4 Property-Based Testing

Für numerische Berechnungen (Entropie, ATR-SL) kommt **Hypothesis** zum Einsatz — generiert automatisch Edge-Cases:

```python
from hypothesis import given, strategies as st
import numpy as np

@given(st.arrays(st.floats(min_value=0, max_value=100000), 
               shape=(50,)))
def test_entropy_never_crashes(tick_prices):
    """Entropie-Berechnung darf bei keinem Input abstürzen."""
    result = calculate_entropy(tick_prices)
    assert isinstance(result, float)
    assert not np.isnan(result)
    assert not np.isinf(result)
```

## 3. Integration Tests

Integration-Tests prüfen die **Kommunikation zwischen den Blackboxen**. Sie starten die beteiligten Komponenten in isolierten Prozessen.

### 3.1 FastAPI Bridge (Box 2 → Box 3)

```python
# tests/integration/test_fastapi_bridge.py
from fastapi.testclient import TestClient
from box3.bridge.app import app

client = TestClient(app)

def test_signal_endpoint_valid_long():
    """State 1 mit korrekter Payload verarbeitet."""
    response = client.post("/signal", json={
        "state": 1,
        "confidence": 0.85,
        "symbol": "BTCUSD",
        "timestamp": "2026-04-05T14:00:00Z"
    })
    assert response.status_code == 200
    assert response.json()["status"] == "accepted"

def test_signal_endpoint_short_rejected():
    """State -1 wird in V1 abgelehnt."""
    response = client.post("/signal", json={
        "state": -1,
        "confidence": 0.90,
        "symbol": "BTCUSD"
    })
    assert response.status_code == 400
    assert "short_not_supported" in response.json()["detail"]

def test_signal_endpoint_missing_field():
    """Unvollständige Payload gibt klaren Fehler."""
    response = client.post("/signal", json={"state": 1})
    assert response.status_code == 422
```

### 3.2 ZMQ Pipeline (Box 1 → Box 2)

ZMQ-Tests mocken die Publisher/Subscriber-Logik ohne echte Netzwerkverbindung:

```python
# tests/integration/test_zmq_pipeline.py
import zmq
from unittest.mock import patch, MagicMock

def test_zmq_serialization_numpy_array():
    """NumPy Arrays werden korrekt serialisiert (msgpack)."""
    data = {"features": np.random.rand(50, 10).astype(np.float32)}
    serialized = serialize_payload(data)
    deserialized = deserialize_payload(serialized)
    np.testing.assert_array_almost_equal(
        deserialized["features"], data["features"]
    )

def test_zmq_high_water_mark():
    """Bei Volllauf des Buffers werden alte Nachrichten verworfen."""
    # Simuliert SNDHWM=100000 Verhalten
    ...
```

### 3.3 Heartbeat IPC (Box 2 ↔ Box 3 via MT5)

```python
# tests/integration/test_heartbeat_ipc.py
from unittest.mock import patch

class MockMT5:
    """Simuliert GlobalVariableSet/Get ohne MT5 Terminal."""
    def __init__(self):
        self._vars = {}
    
    def GlobalVariableSet(self, name, value):
        self._vars[name] = value
        return True
    
    def GlobalVariableGet(self, name):
        return self._vars.get(name, 0.0)

def test_heartbeat_timeout_triggers_suspend():
    """Wenn Heartbeat ausbleibt, geht Box 3 in SUSPEND."""
    mt5 = MockMT5()
    watchdog = Watchdog(mt5, heartbeat_timeout=5.0)
    
    # Heartbeat setzen
    mt5.GlobalVariableSet("CLINE_HEARTBEAT", time.time())
    assert watchdog.state != "SUSPEND"
    
    # Timeout simulieren (Zeit vorspulen)
    watchdog._last_heartbeat = time.time() - 10.0
    watchdog.check()
    assert watchdog.state == "SUSPEND"
    # Pending Orders storniert, laufende Trades behalten SL
```

## 4. System Tests (End-to-End)

System-Tests führen die gesamte Pipeline einmal durch — mit Mock-Daten anstatt Live-Markt.

### 4.1 Dry-Run Modus

Das System kennt einen `DRY_RUN=true` Modus, der:

| Komponente | Verhalten in Dry-Run |
|---|---|
| **Box 1** | Liest historische Parquet-Files statt Live-Ticks |
| **Box 2** | Berechnet States normal, loggt statt zu senden |
| **Box 3** | Simuliert Orders, sendet keine an MT5 |
| **Alerting** | Logs statt E-Mail/SMTP |

### 4.2 Chaos Engineering (Resilience Testing)

Das System muss im Dry-Run physisch beweisen, dass es auf Systemausfälle nicht mit "Happy Path"-Crashes reagiert (The Evidence Gate). Testszenarien:
1. **Network Jitter:** Box 2 fügt zufällige Latenzen in den ZMQ- und REST-Stream ein → Validierung der Sequence-Number/Relative-Tick-Lag Überwachung.
2. **Parquet Locks:** Ein Chaos-Skript lockt die temporäre Parquet-Datei auf Windows exklusiv → Beweis, dass der Ferry-Daemon atomare Drops hält und nicht crasht.
3. **MQL5 Amnesia:** Neustart des MT5-Terminals während eines Live-States → Beweis, dass FastAPI das `INIT_SYNC_REQUEST` Flag empfängt und den Wake-Up vollzieht.
4. **Panic Timeout:** Unterbrechung des VPN-Heartbeats für die in `config.yaml` definierte Zeit → Beweis, dass Box 3 in den *Autonomous Safe Mode* iteriert und offene Trades schließt.

### 4.3 Test-Szenarien

Jedes Szenario wird mit festen Input-Daten ausgeführt und das erwartete Output-State wird verglichen:

| Szenario | Input | Erwartetes State |
|---|---|---|
| **Bull + H↑** | Bullish SJM, Entropie > Threshold | `1` (Long) |
| **Bear + H↑** | Bearish SJM, Entropie > Threshold | `0` (Neutral, V1 kein Short) |
| **Bull + H↓** | Bullish SJM, Entropie < Threshold (Panik) | `0` (Neutral, No-Go) |
| **News-Event** | High-Impact News in < 15min | `0` (Neutral, Blackout) |
| **DD-Limit** | Equity nahe Max-Trailing-DD | `0` + Killswitch-Block |

## 5. Paper Trading (Demo-Phase)

Vor dem Live-Gang muss das System eine **Paper-Trading-Phase** auf einem MT5-Demo-Konto durchlaufen.

### 5.1 Voraussetzungen

- [ ] Alle Unit- und Integration-Tests bestanden (100%)
- [ ] System-Test Dry-Run mit ≥ 50 Trades ohne Error
- [ ] SMTP-Alerting konfiguriert und getestet

### 5.2 Paper-Trading Kriterien

| Kriterium | Schwellwert | Konsequenz bei Verfehlung |
|---|---|---|
| **Mindestdauer** | 30 Kalendertage | Verlängerung um 14 Tage |
| **Max Trailing DD** | < Prop-Firm Limit (z.B. 5%) | Abort, Root-Cause-Analyse |
| **Daily Loss Hits** | 0 (kein einziger) | Abort, Risk-Parameter-Review |
| **False Signal Rate** | < 40% (Graceful Exit via Trailing) | Signal-Matrix Tuning |
| **Heartbeat Dropped** | 0 | IPC-Stabilität prüfen |

### 5.3 Promotion Lab → Live

Ein Modell wird erst dann live geschaltet, wenn es **alle** Akzeptanzkriterien erfüllt:

1. Sharpe Ratio (Paper) ≥ 1.0
2. Max Drawdown ≤ 50% des Prop-Firm Limits (Safety Margin)
3. Consistency: Kein einzelner Trade > 5% des Gesamtgewinns
4. ≥ 100 Trades in Paper-Phase
5. Supervisor-Freigabe (manuell)

## 6. CI/CD Pipeline & Runner-Infrastruktur

Das System erzwingt eine physische Trennung der Test-Umgebungen aus Gründen der OS-Kompatibilität und extrem hoher Sicherheitsstandards.

### 6.1 Infrastruktur-Trennung (Sicherheit & OS-Scope)
- **OS-Limitierung:** Die offizielle `MetaTrader5` Python-Bibliothek existiert **ausschließlich für Windows**. Standard `ubuntu-latest` GitHub Runner würden beim Versuch, MT5-Bridges zu testen, sofort fehlschlagen. Tests in der Linux-Stage erfordern deshalb zwingend ein 100%iges Mocking des MT5-Clients.
- **Isolierter Staging-Server:** **CRITICAL VETO!** Ein CI/CD-Runner darf niemals auf der Produktionsmaschine (Box 3 - Hot-Path) betrieben werden. Ein fehlgeschlagener Testlauf (Endlosschleife, Memory-Leak, blockierte Threads) könnte das Live-Terminal im schlimmsten Fall crashen und den Risk-Diktator offline setzen. Für die reale Prüfung ist zwingend ein physisch oder virtuell isolierter **Windows Staging Server** (oder Hyper-V VM) bereitzustellen. Dieser hostet das dedizierte MT5-Demo-Terminal mitsamt dem Self-Hosted GitHub Runner und teilt **absolut keine** Ressourcen mit Box 3.

### 6.2 Pipeline-Flow

Die Pipeline gliedert sich in zwei streng getrennte Ablaufebenen:

**1. PR-Stage (Fast Feedback):**
Triggert bei Pull Requests auf Standard GitHub-Runnern (`ubuntu-latest`). Da auf Linux kein MT5-Terminal lauffähig ist, prüfen Unit-Tests und Integrations-Scripte ausschließlich die FastAPI-Schnittstellen und Logik-Module in einem 100% Dry-Run Modus (vollständige Mocks der MT5-API).

```yaml
# .github/workflows/pr-tests.yml
jobs:
  pr-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install -r requirements-test.txt
      - run: pytest tests/unit/ tests/integration/ --mock-mt5 -v
```

**2. Pre-Merge / Nightly-Stage (Real MT5 Integration):**
Läuft exklusiv vor dem finalen Merge nach `main` oder als Nightly-Job direkt auf dem isolierten Windows Staging Server. Führt End-to-End System Tests gegen das reale MT5 Demo-Terminal aus (Pipeline-Beweis).

```yaml
# .github/workflows/staging-tests.yml
jobs:
  staging-e2e-tests:
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: [self-hosted, Windows, staging]
    steps:
      - uses: actions/checkout@v4
      - run: pip install -r requirements.txt
      - run: pytest tests/system/ --real-mt5 -v
```

## 7. Regression Testing

Nach jedem Modell-Update (neue Entropie-Gewichte, angepasste SJM-Parameter):

| Test | Auslöser | Prüft |
|---|---|---|
| **Backtest Replay** | Neues Modell in Box 4 | Performance auf historischen Daten ≥ Vorgänger |
| **Signal-Diff** | Signal-Matrix Änderung | ≥ 90% Overlap mit vorherigen Signalen |
| **Risk-Parameter-Scan** | Risk-Config Änderung | Keine DD-Verletzung in allen Szenarien |

---

→ Verwandte Kapitel: [[03-blackbox-agents|Kapitel 03: Blackbox 2 Agents]] | [[04-blackbox-mt5|Kapitel 04: Blackbox 3 MT5 Bridge]] | [[05-schnittstellen|Kapitel 05: Schnittstellen]] | [[08-backtesting-lab|Kapitel 08: Improvement Lab]]

========================================
FILE: docs/10-configuration.md
========================================
---
aliases: [Kapitel 10, Konfigurationsmanagement, Config, Split-Brain Protection]
tags: [architecture, config, infrastructure, ops]
related: [[01-system-architektur]], [[04-blackbox-mt5]], [[05-schnittstellen]]
---
# Kapitel 10: Konfigurationsmanagement & Split-Brain Protection

*Dieses Kapitel definiert das verlässliche Konfigurationsmanagement für das verteilte 3-Blackbox-System. Es etabliert einen deterministischen, Git-basierten Workflow als "Single Source of Truth" und löst das asynchrone "Split-Brain"-Problem zwischen Servern durch einen strikten Hash-Lock innerhalb des REST-Payloads.*

## 10.1 Architectural Need: Das "Split-Brain"-Risiko

Das Hybrid AI-Trading System operiert über eine VPN-Brücke (Tailscale) zwischen zwei getrennten Systemen:
- **Box 2 (Agents):** Läuft auf einem Linux VPS. Hier liegen die Thresholds für die Entropie-Berechnung (`H↑` Go / `H↓` No-Go).
- **Box 3 (MT5 Bridge):** Läuft auf einem Windows Server. Hier liegen die exakten harten Prop-Firm-Risikolimits (Trailing Drawdown, Exposure, Hold-Times).

### Die asynchrone Gefahr
Wenn Konfigurationen (z. B. aggressivere Risk-Limits) geändert werden, gibt es zwangsläufig einen Zeitversatz im Deployment zwischen dem Linux-VPS und dem Windows-Server. 
Sendet Box 2 bereits States aus einer "neuen Realität", während Box 3 noch mit dem alten Regelwerk arbeitet, würde der Risk-Diktator in Box 3 die States als illegal klassifizieren, in Panik verfallen und Orders fälschlicherweise liquidieren oder in ein hartes SUSPEND fallen.

## 10.2 Der Single Source of Truth (GitOps)

Wir verzichten auf Tool-Bloat wie etcd oder HashiCorp Consul. Die Architektur orientiert sich voll an deterministischen Git-Pipelines.

1. **Zentrales Config-Repo:** Alle Schwellenwerte (`thresholds.json`) und Box-spezifischen Regeln (`prop_firm_rules.json`) liegen in einem isolierten Git-Repository.
2. **Versionierung (`config_hash`):** Die aktiven Konfigurationsdateien werden zur Laufzeit über einen SHA-256 Hash versioniert (File-Hashing). Dieser Hash repräsentiert die aktuell gültige globale Wahrheit des gesamten Systems.
3. **Pull-Mechanismus:** Beide Server besitzen einen Cronjob/Daemon, der das Config-Repository regelmäßig pulled bzw. auf Webhooks für einen sofortigen Pull reagiert.

## 10.3 Die Lösung: Payload Hash-Locking

Um absolute Konsistenz zu garantieren, wird die REST-Schnittstelle (FastAPI, siehe [[05-schnittstellen|Kapitel 05]]) um einen Hash-Abgleich erweitert.

### Workflow:
1. Box 2 liest seine Konfiguration und merkt sich den dazu passenden Git `config_hash`.
2. Box 2 berechnet den State, packt ihn als JSON-Payload und injiziert den Hash in jeden ausgehenden State-Payload via `POST /api/v1/signal`:
   ```json
   {
     "timestamp": 1682348110,
     "system_state": 1,
     "entropy_factor": 0.85,
     "config_hash": "a1b2c3d"
   }
   ```
3. Box 3 (MT5 Bridge) empfängt den Payload. Bevor der Risk-Diktator aktiv wird, erfolgt ein Intercept im Watchdog:
   - Ist `payload.config_hash == local.config_hash`?
   - **JA:** Der State ist valide für das aktuell geladene Risikomodell. Order wird an MT5 weitergegeben.
   - **NEIN:** Box 3 wirft sofort eine `ConfigDesyncPanic`. Der empfangene State wird **verworfen**. Box 3 blockiert so lange neue Trades, bis Box 3 intern sein Git-Repository aktualisiert hat und sein eigener `local.config_hash` wieder mit Box 2 übereinstimmt. Laufende Trades werden währenddessen durch den lokalen SL geschützt.

## 10.4 Variablen-Kategorien

Konfigurationsvariablen müssen zwingend isoliert und kategorisiert abgelegt werden, um Laufzeitfehler zu minimieren:

- **1. Prop-Firm Limits (Box 3):** `max_daily_loss`, `max_overall_drawdown`, `allowed_trading_hours`. Streng fixiert. Eine Änderung bedingt einen harten Neustart der Bridge. Der *Daily-Loss-Reset* greift hierbei zwingend `mt5.symbol_info_tick().time` (Broker-Server-Time) ab, um Zeitzonen-Konflikte (Local vs. Broker) zu vermeiden (G-03).
- **2. Agent Thresholds (Box 2):** Hysterese-Limits, `entropy_min_fold`, Timeframe-Kombinationen.
- **3. Infra-Configs:** Tailscale-IPs, ZMQ TCP-Ports, API-Keys für OpenBB. Werden aus Sicherheitsgründen per `.env` außerhalb des Git bereitgestellt.

## 10.5 Pydantic BaseSettings Schema (G-04)

> *Ziel: Keine Box startet mit einer invaliden oder fehlenden Konfiguration. Fail-Fast at Startup statt Silent-Misconfig im Live-Betrieb.*

### Prinzip

Alle Konfigurationsdateien (`compliance.yaml`, `thresholds.json`) werden beim Start der jeweiligen Box durch ein **Pydantic v2 `BaseSettings`-Modell** validiert. Ungültige Werte führen zu einem sofortigen `SystemExit` mit klarer Fehlermeldung, bevor eine Verbindung zur Börse oder zum VPN aufgebaut wird.

### 10.5.1 Box 3 — `compliance.yaml` Schema (Prop-Firm Limits)

```python
# box3/config/compliance_schema.py
from pydantic import BaseModel, Field, field_validator
from pydantic_settings import BaseSettings, SettingsConfigDict
from typing import Literal
import yaml, hashlib, json

class PropFirmRules(BaseModel):
    """Validiert compliance.yaml — Prop-Firm Risikolimits für Box 3."""

    # PF-01: Daily Loss Limit
    max_daily_loss_pct: float = Field(..., gt=0.0, lt=1.0,
        description="Max. täglicher Verlust als Bruchteil des Kontos (z.B. 0.05 = 5%)")

    # PF-02: Drawdown-Typ (Static = FTMO, Trailing = Apex)
    drawdown_type: Literal["static", "trailing"] = Field(...,
        description="Art des Drawdown-Limits des Geldgebers")
    max_overall_drawdown_pct: float = Field(..., gt=0.0, lt=1.0,
        description="Maximaler Gesamt-DD (z.B. 0.10 = 10%)")

    # PF-03: Consistency (Best-Day-Limit)
    best_day_profit_cap_pct: float = Field(default=0.30, gt=0.0, lt=1.0,
        description="Kein Tag darf > X% des Gesamtprofits ausmachen (z.B. 0.30)")

    # PF-04: Minimum Trading Days Counter
    min_trading_days: int = Field(default=0, ge=0,
        description="Mindestanzahl Handelstage für die Challenge (0 = deaktiviert)")

    # PF-05: News-Blackout Fenster in Minuten
    news_blackout_before_min: int = Field(default=15, ge=0)
    news_blackout_after_min: int = Field(default=15, ge=0)

    # PF-06: Weekend-Holding Flag
    close_on_friday_eod: bool = Field(default=False,
        description="Alle Positionen werden freitags zum EOD automatisch geschlossen")
    friday_close_time_utc: str = Field(default="20:55",
        description="UTC-Zeit für den automatischen Friday-Close (Format: HH:MM)")

    # Erlaubte Handelszeiten (UTC)
    allowed_trading_hours_utc: list[str] = Field(
        default=["00:00-23:59"],
        description="Liste von erlaubten Handelszeitfenstern im Format HH:MM-HH:MM (UTC)"
    )

    @field_validator("friday_close_time_utc")
    @classmethod
    def validate_time_format(cls, v: str) -> str:
        import re
        if not re.match(r"^\d{2}:\d{2}$", v):
            raise ValueError(f"Ungültiges Zeitformat: '{v}'. Erwartet HH:MM.")
        return v


class ComplianceConfig(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env",
        env_prefix="BOX3_",
        extra="forbid"    # Keine undokumentierten Felder erlaubt
    )
    rules: PropFirmRules

    @classmethod
    def from_yaml(cls, path: str) -> "ComplianceConfig":
        with open(path, "r") as f:
            raw = yaml.safe_load(f)
        return cls(rules=PropFirmRules(**raw))
```

### 10.5.2 Box 2 — `thresholds.json` Schema (Agent Thresholds)

```python
# box2/config/thresholds_schema.py
from pydantic import BaseModel, Field, model_validator
from pydantic_settings import BaseSettings, SettingsConfigDict
from typing import Literal
import json

class EntropyThresholds(BaseModel):
    """Validiert den Entropy-Gate Abschnitt."""
    entropy_min_fold: float = Field(..., gt=0.0, le=1.0,
        description="Minimaler Entropie-Wert für 'gefaltet/stabil' (H↑ Go-Bedingung)")
    entropy_collapse_threshold: float = Field(..., gt=0.0, le=1.0,
        description="Entropie-Obergrenze für 'kollabiert/Panik' (H↓ No-Go-Bedingung)")

    @model_validator(mode="after")
    def fold_gt_collapse(self) -> "EntropyThresholds":
        if self.entropy_min_fold <= self.entropy_collapse_threshold:
            raise ValueError(
                f"entropy_min_fold ({self.entropy_min_fold}) muss größer als "
                f"entropy_collapse_threshold ({self.entropy_collapse_threshold}) sein."
            )
        return self


class HysteresisConfig(BaseModel):
    """Verhindert zu schnelles Signal-Flipping (Hysterese) und implementiert Panik-Prävention."""
    state_change_cooldown_bars: int = Field(..., ge=1,
        description="Mindestanzahl Bars, bevor ein State-Wechsel erlaubt ist")
    confirmation_bars_required: int = Field(..., ge=1,
        description="Bars, die ein neues Signal bestätigen müssen")
    # Asymmetrische Hysterese für Exits:
    entry_confidence_min: float = Field(default=0.80, gt=0.0, le=1.0,
        description="Minimale Konfidenz für Entry (Scout-Modus)")
    exit_confidence_max: float = Field(default=0.40, gt=0.0, le=1.0,
        description="Konfidenz, ab der ein bestehender Trade als gebrochen gilt (Fällt auf State 0 / Tight Trailing)")

    @model_validator(mode="after")
    def entry_gt_exit(self) -> "HysteresisConfig":
        if self.entry_confidence_min <= self.exit_confidence_max:
            raise ValueError("entry_confidence_min muss strikt größer sein als exit_confidence_max (Asymmetrische Hysterese)")
        return self


class TimeframeConfig(BaseModel):
    primary: str = Field(..., description="Primärer Timeframe (z.B. 'M5')")
    secondary: list[str] = Field(..., min_length=1, max_length=2,
        description="Sekundäre Timeframes für Multi-TF-Konfirmation (z.B. ['D1', 'H1'])")


class AgentThresholds(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env",
        env_prefix="BOX2_",
        extra="forbid"
    )
    entropy: EntropyThresholds
    hysteresis: HysteresisConfig
    timeframes: TimeframeConfig

    @classmethod
    def from_json(cls, path: str) -> "AgentThresholds":
        with open(path, "r") as f:
            raw = json.load(f)
        return cls(**raw)
```

### 10.5.3 Config-Hash Berechnung (SHA-256)

Der `config_hash` im REST-Payload wird deterministisch aus beiden Konfigurationsdateien gemeinsam berechnet. Beide Seiten müssen dieselbe Logik implementieren:

```python
# shared/config_hash.py
import hashlib, json, yaml
from pathlib import Path

def compute_config_hash(compliance_path: str, thresholds_path: str) -> str:
    """
    Berechnet einen deterministischen SHA-256 Hash über beide Config-Dateien.
    Reihenfolge ist fix: compliance zuerst, dann thresholds.
    Gibt den ersten 12 Zeichen des Hex-Digests zurück (ausreichend für Split-Brain Detection).
    """
    h = hashlib.sha256()
    for path in [compliance_path, thresholds_path]:
        content = Path(path).read_bytes()
        h.update(content)
    return h.hexdigest()[:12]
```

> **Deployment-Regel:** Beide Boxes führen `compute_config_hash()` beim Start aus und speichern das Ergebnis als `LOCAL_CONFIG_HASH`. Box 2 injiziert diesen Wert in jeden `POST /api/v1/signal` Payload. Box 3 vergleicht ihn mit seinem eigenen `LOCAL_CONFIG_HASH` (§10.3).

### 10.5.4 Referenz-Beispiel Config-Dateien

**`compliance.yaml` (Box 3 — Windows Server):**
```yaml
# SOPS-verschlüsselt im Deployment — nur entschlüsselt im RAM verfügbar (G-02)
max_daily_loss_pct: 0.05
drawdown_type: trailing
max_overall_drawdown_pct: 0.10
best_day_profit_cap_pct: 0.30
min_trading_days: 10
news_blackout_before_min: 15
news_blackout_after_min: 15
close_on_friday_eod: false
friday_close_time_utc: "20:55"
allowed_trading_hours_utc:
  - "00:00-23:59"
```

**`thresholds.json` (Box 2 — Linux VPS):**
```json
{
  "entropy": {
    "entropy_min_fold": 0.65,
    "entropy_collapse_threshold": 0.35
  },
  "hysteresis": {
    "state_change_cooldown_bars": 3,
    "confirmation_bars_required": 2,
    "entry_confidence_min": 0.80,
    "exit_confidence_max": 0.40
  },
  "timeframes": {
    "primary": "M5",
    "secondary": ["H1", "H4"]
  }
}
```

### 10.5.5 Startup-Validation Sequenz

```
Box startet
    │
    ├─ [1] Lade Config-Datei (YAML/JSON)
    │
    ├─ [2] Pydantic Validation
    │        │
    │        ├─ FAIL → stderr + SystemExit(1)  [kein VPN/MT5 Kontakt]
    │        └─ PASS → Config-Objekt im RAM
    │
    ├─ [3] compute_config_hash() → speichere LOCAL_CONFIG_HASH
    │
    └─ [4] Normal Startup (ZMQ / FastAPI / MT5 Connect)
```

---

## Schnittstellendefinitionen & Querverweise

- **REST Payload Definition ergänzt:** Box 2 muss ab sofort den `config_hash` als mandatory String im JSON-Payload (`POST /api/v1/signal`) anhängen. Box 3 erzwingt diesen Key vor der Validierung ans MT5.
- **MT5 Watchdog (Box 3):** Die Fehler-Taxonomie aus Kap. 05 wird um `E-CONFIG-DESYNC` erweitert.
- **VPN Infra:** Die Pings via Tailscale müssen ungestört bleiben. Config-Pulls haben Vorrang vor anderen Internet-Aktivitäten der Box 3.

→ Ref: ZMQ Serialization (Box 1↔Box 2) in [[05-schnittstellen|Schnittstellen härten (Kap. 05) §1]].
→ Ref: REST-Schnittstelle (Box 2↔Box 3, inkl. Signal-Payload) in [[05-schnittstellen|Schnittstellen härten (Kap. 05) §2]].
→ Ref: Risk-Diktator Verhalten in [[04-blackbox-mt5|Execution Layer (Kap. 04)]].


========================================
FILE: docs/98-implementation-guide.md
========================================
---
aliases: [Implementation Guide, Umsetzungsleitfaden, Coding Guide]
tags: [implementation, guide, onboarding]
related: [[00-MOC-Trading-System]], [[99-deploy-runbook]]
trust: canonical
last_reviewed: 2026-04-26
---
# 98. Umsetzungsleitfaden — Von Architektur zu Code

*Dieses Kapitel ist der zentrale Onboarding-Leitfaden für **Coding-Agenten** (Cline, Claude Code, Antigravity, GPT, etc.), die das 3-Blackbox Trading System implementieren. Es definiert Voraussetzungen, Repository-Struktur, Mock-Architektur, Coding-Konventionen und die phasenweise Abarbeitung aller Tasks. Lies dieses Dokument **vor** dem ersten Commit.*

---

## 1. Pflicht-Lektüre vor dem Coding

Bevor du Code schreibst, MUSST du diese Dateien gelesen haben:

| Prio | Datei | Warum |
|------|-------|-------|
| 1 | `docs/00-MOC-Trading-System.md` | Gesamtübersicht, SSOT-Verzeichnis |
| 2 | `docs/01-system-architektur.md` | 3+1 Blackbox Design, Phantom-Tools |
| 3 | Das Kapitel der Box, an der du arbeitest | Detailspezifikation |
| 4 | `docs/05-schnittstellen.md` | API-Verträge zwischen den Boxen |
| 5 | `docs/10-configuration.md` | Config-Schemas, Split-Brain Protection |
| 6 | `DECISIONS.md` | Veto-Log — was ist VERBOTEN |

> **CRITICAL:** Lies `DECISIONS.md` KOMPLETT. Dort stehen architektonische Vetos (z.B. kein CUDA, kein Short, kein CUA, kein QuantConnect). Ein Verstoß macht deinen gesamten Code wertlos.

---

## 2. Human Prerequisites — Was der Mensch VOR dem Agent-Start bereitstellt

### 2.1 Einmalige Infrastruktur (durch den Supervisor)

Der menschliche Supervisor richtet folgendes ein, BEVOR ein Coding-Agent startet:

| # | Task | Ergebnis | Doku-Ref |
|---|------|----------|----------|
| H-1 | Hetzner VPS bestellen (Ubuntu 24.04) | SSH-Zugang, IP-Adresse | Kap. 99 §2 |
| H-2 | Tailscale auf beiden Servern installieren + Auth | Tailscale-IPs notiert | Kap. 99 §3 |
| H-3 | MT5 Terminal installieren + FTMO Demo Login | MT5 läuft, Hedging-Modus aktiv | Kap. 99 §1.2 |
| H-4 | MT5 Expert Advisors erlauben | Checkbox aktiv in Tools → Options | Kap. 99 §1.2 |
| H-5 | 3 GitHub Repos erstellen (privat) | URLs + Deploy-Keys | Kap. 07 §11 |
| H-6 | `age` Key-Paar generieren, Private Keys verteilen | Keys auf beiden Servern | Kap. 07 §13 |
| H-7 | UFW/Fail2ban (Linux), Windows Firewall Rules | Firewall aktiv | Kap. 99 §1.4/§2 |
| H-8 | Python 3.12 auf beiden Servern | `python --version` → 3.12.x | Kap. 99 §1.1/§2.1 |
| H-9 | NSSM auf Windows installieren | `choco install nssm` | Kap. 99 §1.5 |

### 2.2 Repository-Namen (fix)

| Repo | Plattform | Inhalt |
|------|-----------|--------|
| `trading-brain-linux` | Hetzner VPS | Box 2 (Agents) + Box 4 (Lab) |
| `execution-mt5-windows` | Windows Server | Box 1 (Data) + Box 3 (MT5 Bridge) |
| `trading-config` | Beide (shared) | `compliance.yaml`, `thresholds.json` |

### 2.3 IDE / Workspace-Konfiguration

Der Coding-Agent arbeitet lokal auf dem **Windows-Rechner des Supervisors**. Die Repos werden lokal geklont und via Git auf die Server deployed.

**Empfohlenes Setup:**

```
C:\trading\                          ← Workspace-Root
├── execution-mt5-windows\           ← Git Repo (Box 1 + Box 3)
│   ├── box1\                        ← Data Engine Code
│   ├── box3\                        ← MT5 Bridge Code
│   ├── shared\                      ← Gemeinsame Utilities
│   ├── tests\                       ← Alle Tests
│   ├── requirements.txt
│   ├── requirements-test.txt
│   └── pyproject.toml
├── trading-brain-linux\             ← Git Repo (Box 2 + Box 4)
│   ├── box2\                        ← Agents Code
│   ├── box4\                        ← Lab Code
│   ├── shared\                      ← Gemeinsame Utilities
│   ├── tests\
│   ├── requirements.txt
│   ├── requirements-test.txt
│   └── pyproject.toml
└── trading-config\                  ← Git Repo (Shared Config)
    ├── compliance.yaml
    ├── thresholds.json
    └── shared\
        └── config_hash.py
```

**IDE-Einstellungen:**
- Python 3.12 Interpreter
- `pytest` als Test-Runner
- Linter: `ruff` (schnell, Python-native)
- Formatter: `ruff format` (Black-kompatibel)
- Type-Checker: `mypy --strict` (optional aber empfohlen)

**`requirements-test.txt` (beide Repos):**
```
pytest>=8.0
pytest-asyncio>=0.23
pytest-cov>=5.0
hypothesis>=6.0
httpx>=0.27
aiosmtpd>=1.4
```

---

## 3. Mock-Architektur — Autonomes Entwickeln ohne MT5/VPN

> **Prinzip:** ~80% des Codes ist autonom testbar. Der Agent baut zuerst die Mock-Schicht, dann den Production-Code dagegen.

### 3.1 Die 3 Mock-Interfaces

Jedes Repo enthält unter `tests/mocks/` drei zentrale Mock-Module:

| Mock | Ersetzt | Nutzer |
|------|---------|--------|
| `MockMT5` | `import MetaTrader5 as mt5` | Box 1, Box 3 |
| `MockZMQ` | ZMQ PUB/SUB Sockets | Box 1 ↔ Box 2 |
| `MockSMTP` | `smtplib.SMTP` | Box 3 Alerting |

### 3.2 MockMT5 — Kernstruktur

Der MockMT5Client simuliert die gesamte MetaTrader5 Python Library:

```python
# tests/mocks/mock_mt5.py
class MockMT5:
    """Drop-in Replacement für MetaTrader5 Library.
    
    Simuliert: initialize, shutdown, terminal_info, symbol_info,
    symbol_info_tick, copy_rates_from_pos, order_send, positions_get,
    history_deals_get, GlobalVariableSet, GlobalVariableGet.
    
    Usage in Tests:
        from tests.mocks.mock_mt5 import MockMT5
        mt5 = MockMT5()
        mt5.initialize()
        info = mt5.symbol_info("BTCUSD")
    
    Usage in Production (Dependency Injection):
        # box3/bridge/app.py
        def create_app(mt5_client=None):
            if mt5_client is None:
                import MetaTrader5 as mt5_client
            app.state.mt5 = mt5_client
    """
```

**Pflicht-Features des Mocks:**
- `symbol_info()` → Liefert `volume_step`, `trade_stops_level`, `spread`, `digits`
- `order_send()` → Simuliert Retcodes (10009=OK, 10016=Invalid Stops, 10006=Requote)
- `positions_get()` → Liefert Liste aktiver Mock-Positionen
- `copy_rates_from_pos()` → Liefert numpy structured array mit OHLCV-Daten
- `GlobalVariableSet/Get()` → Dict-basierter IPC-Speicher

### 3.3 Dependency Injection Pattern

**ALLE** externen Abhängigkeiten (MT5, ZMQ, SMTP, OpenBB) werden via **Dependency Injection** übergeben, NIE als globaler Import:

```python
# ❌ FALSCH — nicht testbar
import MetaTrader5 as mt5

def check_position():
    return mt5.positions_get()

# ✅ RICHTIG — testbar mit Mock
def check_position(mt5_client):
    return mt5_client.positions_get()
```

Für FastAPI nutze `app.state` oder Depends():
```python
from fastapi import FastAPI, Depends

def get_mt5(request):
    return request.app.state.mt5

@app.post("/api/v1/signal")
async def receive_signal(payload: SignalPayload, mt5=Depends(get_mt5)):
    # mt5 ist in Tests ein MockMT5, in Produktion das echte MT5
    ...
```

---

## 4. Coding-Konventionen

### 4.1 Python-Standards

| Regel | Wert |
|-------|------|
| Python Version | 3.12+ |
| Type Hints | **Pflicht** auf allen public Functions |
| Docstrings | Google-Style, Deutsch oder Englisch |
| Max Line Length | 100 Zeichen |
| Import-Sortierung | `ruff` / isort Standard |

### 4.2 Logging (structlog)

**Kein `print()`. Kein `logging.info()`. Nur `structlog`.**

```python
import structlog
logger = structlog.get_logger()

# Jeder Log-Eintrag MUSS trace_id enthalten
logger.info("signal_received", 
    trace_id="req-9f8e-11e2",
    state=1, 
    symbol="BTCUSD",
    config_hash="a1b2c3d"
)
```

→ Ref: Kap. 07 §12.1

### 4.3 Testing

| Regel | Begründung |
|-------|------------|
| Jede Public Function → min. 1 Unit-Test | Evidence Gate |
| Tests nutzen **nur** Mock-Daten | Kein MT5, kein Netzwerk |
| `hypothesis` für numerische Funktionen | Edge-Case Abdeckung |
| Test-Dateien spiegeln Source-Struktur | `box3/risk/dd.py` → `tests/unit/test_dd.py` |
| Integration-Tests nutzen FastAPI `TestClient` | Kein laufender Server nötig |

### 4.4 Error Handling

```python
# Fehlertaxonomie aus Kap. 05 §6:
# Transient → Retry mit Backoff
# Permanent → Abort + Alert
# Corrupt  → Discard + Log

class TransientError(Exception): pass  # Retry
class PermanentError(Exception): pass  # Abort + SMTP
class CorruptDataError(Exception): pass  # Discard + Log
```

### 4.5 Config-Zugriff

**Niemals** Magic Numbers im Code. Alles kommt aus Pydantic-Schemas:

```python
# ❌ FALSCH
if drawdown > 0.05:
    kill_all()

# ✅ RICHTIG
if drawdown > config.rules.max_daily_loss_pct:
    kill_all()
```

→ Ref: Kap. 10 §10.5

---

## 5. Implementation-Phasen (Reihenfolge bindend)

### Phase 0: Foundation (Agent + Mensch)

**Agent baut:**
1. `shared/config_hash.py` — SHA-256 Berechnung (Kap. 10 §10.5.3)
2. `shared/logging_setup.py` — structlog JSON-Konfiguration (Kap. 07 §12.1)
3. `compliance.yaml` + `thresholds.json` mit Referenzwerten (Kap. 10 §10.5.4)
4. Pydantic Schemas: `ComplianceConfig`, `AgentThresholds` (Kap. 10 §10.5.1/2)
5. `tests/mocks/mock_mt5.py` — MockMT5 Client
6. `tests/mocks/mock_zmq.py` — MockZMQ PUB/SUB
7. `tests/mocks/mock_smtp.py` — MockSMTP
8. `pyproject.toml` + `requirements.txt` für beide Repos

**Evidence Gate Phase 0:**
- `pytest tests/` → alle grün
- `compute_config_hash()` produziert deterministischen Hash
- Pydantic validiert Referenz-Configs fehlerfrei

### Phase 1: Box 3 — MT5 Execution Bridge

**Repo:** `execution-mt5-windows`

```
box3/
├── __init__.py
├── bridge/
│   ├── app.py              ← FastAPI App (uvicorn entry)
│   ├── models.py           ← Pydantic Request/Response Models
│   ├── dependencies.py     ← get_mt5(), get_config()
│   └── middleware.py        ← Rate-Limit, Config-Hash Check
├── execution/
│   ├── mt5_wrapper.py      ← Thread-safe MT5 Wrapper (Lock)
│   ├── order_manager.py    ← order_send + Reconciliation
│   └── trade_lifecycle.py  ← State Machine (0/1 → SL/Entry)
├── risk/
│   ├── risk_dictator.py    ← Volume, Spread, Stop-Level Checks
│   ├── floating_dd.py      ← Floating Drawdown Killswitch
│   ├── compliance.py       ← PF-01 bis PF-06 Enforcement
│   └── cooldown.py         ← Anti-Revenge Timer
├── watchdog/
│   ├── heartbeat.py        ← Ping-Handler + Position-Report
│   ├── suspend.py          ← SUSPEND Mode Logic
│   ├── safe_mode.py        ← Autonomous Panic Liquidation
│   └── shutdown.py         ← 3-Step Graceful Shutdown (G-10)
├── alerting/
│   └── smtp_alerts.py      ← SMTP E-Mail Versand
└── ipc/
    └── global_vars.py      ← GlobalVariableSet/Get Wrapper
```

**Reihenfolge innerhalb Phase 1:**
1. `bridge/models.py` + `bridge/app.py` (FastAPI Skeleton)
2. `bridge/middleware.py` (Rate-Limit + Config-Hash)
3. `execution/mt5_wrapper.py` (Thread-safe Lock Wrapper)
4. `risk/risk_dictator.py` (Volume, Spread, Stop-Level)
5. `risk/floating_dd.py` (Floating DD Killswitch)
6. `risk/compliance.py` (Prop-Firm Regeln)
7. `execution/trade_lifecycle.py` (State Machine)
8. `execution/order_manager.py` (order_send + Reconciliation)
9. `watchdog/heartbeat.py` + `watchdog/suspend.py`
10. `watchdog/safe_mode.py` (Panic Timer)
11. `watchdog/shutdown.py` (Graceful Shutdown)
12. `alerting/smtp_alerts.py`

**Evidence Gate Phase 1:**
- `pytest tests/unit/ tests/integration/ -v --cov=box3 --cov-report=term` → Coverage ≥ 80%
- `GET /health` → 200 OK mit MockMT5
- `POST /api/v1/signal` State 1 → Mock-Order erstellt
- State 0 → Trailing SL tightened (kein Close)
- Config-Hash Mismatch → 409 ConfigDesyncPanic
- 13 Requests/Minute → 429 + MockSMTP Alert captured
- Floating DD über Limit → `CloseAllPositions()` gefeuert

### Phase 2: Box 1 — Data Engine

**Repo:** `execution-mt5-windows`

```
box1/
├── __init__.py
├── data_pull/
│   ├── mt5_fetcher.py      ← copy_rates_from, Multi-TF
│   └── health_checks.py    ← Lücken, Anomalien, Konsistenz
├── features/
│   ├── engineering.py      ← 15 Features (OHLCV, Returns, Vol, Mom)
│   └── normalization.py    ← Z-Score (rolling mean/std)
├── streaming/
│   ├── zmq_publisher.py    ← ZMQ PUB (msgpack_numpy, seq_id, trace_id)
│   └── payload.py          ← Payload-Wrapping Logik
└── ferry/
    ├── parquet_writer.py   ← Atomic Staging (→ ready_*.parquet)
    └── ferry_daemon.py     ← rsync an Box 4
```

### Phase 3: Box 2 — The Scientist

**Repo:** `trading-brain-linux`

```
box2/
├── __init__.py
├── receiver/
│   ├── zmq_subscriber.py   ← ZMQ SUB, asyncio.Queue Buffer
│   ├── seq_validator.py    ← seq_id Prüfung, Out-of-Order Discard
│   └── staleness.py        ← Time-Since-Last-Message Monitor
├── analysis/
│   ├── entropy.py          ← Von-Neumann Entropie (5-Feature Matrix)
│   ├── gatekeeper.py       ← 2-Trigger Wake-Up (Entropie + POI)
│   ├── regime.py           ← SJM / HMM Regime Detection (V1: vereinfacht)
│   └── decision_matrix.py  ← SJM × Entropy → State {0, 1}
├── orchestration/
│   ├── agent_modes.py      ← COLD_START, Scout, Manager
│   ├── composition.py      ← Sub-Agent Framework (I/O-Vertrag)
│   ├── fusion.py           ← 2-Level Fusion (Deterministisch + LLM)
│   └── double_dip.py       ← Double-Dip Prevention
├── output/
│   ├── signal_client.py    ← REST POST /api/v1/signal (httpx)
│   ├── heartbeat_client.py ← REST POST /api/v1/ping (5s Loop)
│   └── cooldown.py         ← 429 Handling (5 Min Freeze)
└── context/
    ├── openbb_provider.py  ← OpenBB SDK Polling (VIX, Macro, News)
    └── degradation.py      ← Graceful Degradation bei Ausfall
```

### Phase 4: Integration & E2E

- DRY_RUN Modus aktivieren
- End-to-End Pipeline testen (Tick → Agent → Signal → Mock-MT5)
- Config-Hash Sync validieren
- Chaos-Tests schreiben (VPN-Drop, MT5-Restart, Panic Timeout)

### Phase 5: Paper Trading

- Mensch deployt Code auf echte Server
- 30 Tage MT5 Demo (Akzeptanzkriterien: Kap. 09 §5)

### Phase 6: Box 4 — Lab (parallel ab Phase 2)

**Repo:** `trading-brain-linux`

```
box4/
├── ingestion/
│   ├── parquet_receiver.py  ← Empfang + Atomic Rename
│   └── schema_validator.py  ← Pandera Validation (A-4)
├── backtesting/
│   ├── runner.py            ← numpy/ffn Pipeline
│   └── walk_forward.py      ← Walk-Forward-Validation
├── tracking/
│   └── mlflow_setup.py      ← MLflow SQLite Tracking
└── promotion/
    └── promote_model.py     ← Staging → Production Pipeline
```

---

## 6. Autonomie-Matrix — Was braucht den Menschen?

### 🟢 Agent arbeitet KOMPLETT AUTONOM (Mock-basiert)

- Gesamte FastAPI App (alle Endpoints via TestClient)
- Risk-Diktator (reine Mathematik auf Mock-Symbol-Info)
- Compliance Module (Pydantic-Logik)
- Entropie-Berechnung (NumPy auf Mock-Arrays)
- Decision Matrix, Scout/Manager, COLD_START (Zustandsautomaten)
- Feature Engineering (NumPy auf Mock-OHLCV)
- ZMQ Serialisierung (lokal über `inproc://` oder asyncio.Queue)
- Config-Hash, structlog, Pydantic Schemas
- Trade Lifecycle State Machine
- Alle Unit + Integration Tests
- Lab: Backtest Runner, MLflow, Schema Validation

### 🔴 Mensch MUSS ran (einmalig, ~1 Stunde)

- VPS bestellen + SSH-Key
- Tailscale installieren + Auth
- MT5 installieren + Broker-Login
- MT5 Expert Advisors erlauben (GUI Checkbox)
- GitHub Repos + Deploy Keys
- `age` Keys generieren + verteilen
- NSSM auf Windows installieren

### 🟡 Agent baut Code, Mensch führt aus

- NSSM Service-Registrierung (Agent schreibt Script → Mensch führt als Admin aus)
- Systemd Service-Files (Agent schreibt → Mensch aktiviert)
- MQL5 EA Kompilierung (Agent schreibt `.mq5` → Mensch kompiliert im MetaEditor)
- E2E Tests auf echter Infra
- Deploy-Scripts ausführen

---

## 7. Checkliste: Ist mein Workspace bereit?

Bevor ein Coding-Agent den ersten Commit macht, müssen folgende Punkte erfüllt sein:

```
□ Python 3.12 installiert
□ Git installiert und konfiguriert
□ Repos geklont (alle 3)
□ Virtual Environment erstellt: python -m venv .venv
□ Dependencies installiert: pip install -r requirements.txt -r requirements-test.txt
□ pytest läuft: pytest --version
□ ruff läuft: ruff check .
□ Die 4 Pflicht-Dateien gelesen:
  □ docs/00-MOC-Trading-System.md
  □ docs/01-system-architektur.md
  □ docs/10-configuration.md
  □ DECISIONS.md
□ Dieses Kapitel (98) gelesen
```

---

## 8. Häufige Agent-Fehler (Anti-Patterns)

| Anti-Pattern | Warum falsch | Richtig |
|-------------|-------------|---------|
| `import MetaTrader5 as mt5` als globaler Import | Nicht testbar, Windows-only | Dependency Injection |
| `print("Error")` | Nicht strukturiert, kein trace_id | `structlog` mit JSON |
| Magic Numbers (`if dd > 0.05`) | Nicht konfigurierbar | Pydantic Config lesen |
| Tests gegen echtes MT5 | Nicht reproduzierbar, braucht Terminal | MockMT5 nutzen |
| `pickle` für Serialisierung | Security: Remote Code Execution | `msgpack_numpy` |
| Short-Positionen (State -1) | In V1 architektonisch verboten | Nur States {0, 1} |
| GPU/CUDA Code | Kein GPU auf dem VPS | CPU-only (NumPy) |
| Direkte Datei-Schreiber ohne Lock | Race Conditions mit Ferry | Atomic Rename + .lock |
| `time.time()` für Cross-Machine Sync | VPN-Zeitdrift | Relative Latenzen, seq_id |
| ClickHouse / Vektor-DB | Explizit gestrichen (DECISIONS.md) | Parquet + Git |

---

## 9. Kapitelreferenz für Coding-Tasks

| Wenn du baust... | Lies zuerst... |
|-------------------|----------------|
| FastAPI Endpoints | Kap. 05 §2 |
| Risk-Diktator | Kap. 04 §5 |
| Trade Lifecycle | Kap. 04 §3 |
| Compliance Module | Kap. 04 §7 |
| ZMQ Pipeline | Kap. 05 §1 |
| Heartbeat/IPC | Kap. 05 §3 |
| Entropie-Berechnung | Kap. 03 §1 + refs/papers/market-folding.md |
| Decision Matrix | Kap. 03 §5 |
| Scout/Manager | Kap. 03 §3 |
| Parquet Ferry | Kap. 05 §4 |
| Config Schemas | Kap. 10 §10.5 |
| Deployment | Kap. 99 (Runbook) |
| Testing | Kap. 09 |
| Lab/Backtesting | Kap. 08 |

---

## 10. Schnittstellenverträge (Interface Contracts)

> **Regel:** Jede Modul-Grenze hat einen formalen I/O-Vertrag als Pydantic-Model. Ein Agent, der ein Modul implementiert, darf die Signatur **nicht** ändern — nur das Innere. Änderungen am Vertrag erfordern ein DECISIONS.md Update.

### 10.1 Box 1 → Box 2: ZMQ Data Payload

```python
# shared/contracts/data_payload.py
from pydantic import BaseModel, Field
import numpy as np
from numpy.typing import NDArray

class DataPayload(BaseModel):
    """Wird von Box 1 (ZMQ PUB) gesendet, von Box 2 (ZMQ SUB) empfangen.
    Serialisiert via msgpack_numpy. Ref: Kap. 05 §1"""
    
    class Config:
        arbitrary_types_allowed = True
    
    trace_id: str = Field(..., description="UUID4 pro Nachricht")
    seq_id: int = Field(..., ge=0, description="Monoton steigend, kein Reset")
    timestamp_utc: float = Field(..., description="time.time() des Senders")
    symbol: str = Field(..., pattern=r"^[A-Z]{6}$", description="z.B. BTCUSD")
    timeframe: str = Field(..., description="M5, H1, oder H4")
    features: list[list[float]] = Field(
        ..., description="Shape [N, 15]: N=50 Bars, 15 Features (Z-normalisiert)"
    )
    raw_close: list[float] = Field(
        ..., description="Unnormalisierte Close-Preise für ATR-Berechnung"
    )
    data_quality: str = Field(
        default="OK", description="OK | GAP_DETECTED | STALE"
    )
```

### 10.2 Box 2 → Box 3: REST Signal Request

```python
# shared/contracts/signal_contract.py
from pydantic import BaseModel, Field, field_validator
from enum import IntEnum

class TradeState(IntEnum):
    HOLD_TIGHTEN = 0  # Kein neuer Trade, Trailing SL tightenen
    ENTRY_BUY = 1     # Neuer Long-Entry (Short verboten in V1)

class SignalRequest(BaseModel):
    """POST /api/v1/signal — Ref: Kap. 05 §2.2"""
    
    state: TradeState
    symbol: str = Field(..., pattern=r"^[A-Z]{6}$")
    confidence: float = Field(..., ge=0.0, le=1.0, description="Agent-Konfidenz")
    config_hash: str = Field(..., min_length=8, description="SHA-256 Prefix")
    trace_id: str = Field(..., description="Durchgereicht von DataPayload")
    entropy: float = Field(..., description="Aktuelle Entropie H")
    regime: str = Field(..., description="BULL | BEAR | UNCERTAIN")
    fusion_method: str = Field(
        ..., description="DETERMINISTIC | LLM_FALLBACK"
    )
    
    @field_validator("state")
    @classmethod
    def no_short_in_v1(cls, v):
        if v not in (0, 1):
            raise ValueError("V1: Nur States {0, 1} erlaubt (DECISIONS.md)")
        return v

class SignalResponse(BaseModel):
    """Response von Box 3 nach Signal-Verarbeitung."""
    
    accepted: bool
    action_taken: str = Field(
        ..., description="ORDER_SENT | SL_TIGHTENED | REJECTED | SUSPENDED"
    )
    order_ticket: int | None = Field(default=None, description="MT5 Ticket")
    rejection_reason: str | None = Field(
        default=None, 
        description="z.B. SPREAD_TOO_HIGH, DD_LIMIT, RATE_LIMITED"
    )
    config_hash: str = Field(..., description="Hash von Box 3 (Sync-Check)")
```

### 10.3 Box 3 Heartbeat Contract

```python
# shared/contracts/heartbeat_contract.py
from pydantic import BaseModel, Field

class PingRequest(BaseModel):
    """POST /api/v1/ping — alle 5s von Box 2. Ref: Kap. 05 §3"""
    
    sender: str = Field(default="box2", description="Absender-Kennung")
    config_hash: str
    timestamp_utc: float

class PingResponse(BaseModel):
    """Antwort mit aktuellem Position-Report."""
    
    status: str = Field(..., description="ALIVE | SUSPENDED | SHUTTING_DOWN")
    has_open_position: bool
    position_symbol: str | None = None
    position_side: str | None = Field(
        default=None, description="BUY (kein SELL in V1)"
    )
    position_profit: float | None = None
    position_sl: float | None = None
    mt5_connected: bool
    algo_trading_allowed: bool
    config_hash: str
```

### 10.4 Health-Check Contract

```python
# shared/contracts/health_contract.py
from pydantic import BaseModel, Field

class HealthResponse(BaseModel):
    """GET /health — Deep-Check. Ref: Kap. 05 §2.1, G-07"""
    
    status: str = Field(..., description="healthy | degraded | critical")
    mt5_connected: bool
    algo_trading_allowed: bool
    config_hash: str
    uptime_seconds: float
    open_positions: int
    last_signal_age_seconds: float | None = Field(
        default=None, description="Sekunden seit letztem Signal"
    )
    suspend_active: bool
    version: str = Field(default="1.0.0")
```

### 10.5 Interne Modul-Verträge (Function Signatures)

Diese Signaturen definieren die Grenzen **innerhalb** einer Box. Jedes Modul exportiert genau diese Funktionen:

```python
# === Box 1: Data Engine ===

# box1/features/engineering.py
def compute_features(
    rates: np.ndarray,  # MT5 structured array [N, OHLCV]
    window: int = 50
) -> np.ndarray:
    """Returns: np.ndarray shape [window, 15]"""
    ...

# box1/features/normalization.py
def z_normalize(
    features: np.ndarray,   # [N, 15]
    lookback: int = 200
) -> np.ndarray:
    """Returns: Z-normalisiertes Array, gleiche Shape"""
    ...

# box1/streaming/zmq_publisher.py
def create_publisher(
    address: str = "tcp://0.0.0.0:5555",
    sndhwm: int = 100_000
) -> zmq.Socket:
    ...

async def publish_payload(
    socket: zmq.Socket,
    payload: DataPayload
) -> None:
    ...

# === Box 2: The Scientist ===

# box2/analysis/entropy.py
def calculate_entropy(
    features: np.ndarray,  # [N, 5] (die 5 Korrelationsfeatures)
    method: str = "von_neumann"
) -> float:
    """Returns: Entropie H ∈ [0, 1]. H↑ = mehr Information."""
    ...

# box2/analysis/gatekeeper.py
def should_wake(
    entropy: float,
    entropy_threshold: float,  # aus config
    poi_triggered: bool,
    volatility_spike: bool
) -> bool:
    """Trigger A (Entropie) UND Trigger B (POI oder Volatilität)."""
    ...

# box2/analysis/decision_matrix.py
def resolve_state(
    regime: str,        # "BULL" | "BEAR" | "UNCERTAIN"
    entropy: float,
    has_open_position: bool,
    config: AgentThresholds
) -> TradeState:
    """Returns: TradeState.HOLD_TIGHTEN (0) oder ENTRY_BUY (1)"""
    ...

# box2/orchestration/fusion.py
async def fuse_signals(
    sub_agent_outputs: list[dict],
    weights: list[float],
    veto_threshold: float,
    llm_client: object | None = None,  # None = kein Fallback
    timeout: float = 10.0
) -> tuple[TradeState, str]:
    """Returns: (state, fusion_method)"""
    ...

# === Box 3: MT5 Bridge ===

# box3/execution/mt5_wrapper.py
def execute_order(
    mt5_client: object,
    symbol: str,
    order_type: int,    # 0=BUY
    volume: float,
    sl: float,
    tp: float | None,
    trace_id: str
) -> tuple[bool, int | None, str]:
    """Returns: (success, ticket, message)"""
    ...

# box3/risk/risk_dictator.py
def validate_trade(
    symbol_info: object,   # mt5.symbol_info() oder MockSymbolInfo
    volume: float,
    sl_distance: float,
    config: ComplianceConfig
) -> tuple[bool, str]:
    """Returns: (allowed, reason). Pre-Trade Gate."""
    ...

# box3/risk/floating_dd.py
def check_drawdown(
    current_equity: float,
    midnight_balance: float,
    config: ComplianceConfig
) -> tuple[bool, float]:
    """Returns: (kill_required, current_dd_pct)"""
    ...
```

### 10.6 Erweiterungs-Regeln

| Regel | Beschreibung |
|-------|-------------|
| **Contract-First** | Änderungen an Contracts → DECISIONS.md Eintrag + alle Consumer updaten |
| **Additive Only** | Neue Felder dürfen hinzugefügt werden (mit `default`), bestehende nie entfernt |
| **Version im Header** | Zukünftig: `api_version` Feld in Payloads für Backward-Compat |
| **Type Hints = Pflicht** | Jede Public Function muss vollständig typisiert sein |
| **Docstring = Vertrag** | Was im Docstring steht, ist bindend. Keine stille Verhaltensänderung. |

---

→ Verwandte Kapitel: [[99-deploy-runbook|99. Deploy Runbook]] | [[09-testing-strategie|09. Testing-Strategie]] | [[10-configuration|10. Konfigurationsmanagement]] | [[05-schnittstellen|05. Schnittstellen]]


========================================
FILE: docs/99-deploy-runbook.md
========================================
# 99. Deploy & Ops Runbook — Hybrid AI-Trading System

*COPY-PASTE-fähiges Runbook für Linux-Sysadmins (Ubuntu 24.04) ohne Trading-Wissen. Physischer Split: Linux VPS (Brain: Box2/4) + Windows Server (Muscle: Box1/3). Tailscale VPN essenziell. Repos: `trading-brain-linux` (Brain), `execution-mt5-windows` (Muscle), `trading-config` (shared Config-Repo).*

## 1. Windows Server Setup (Muscle: Box1 Data + Box3 MT5 Bridge)

**Voraussetzungen:** Windows Server 2022/2019, Admin-Rechte, MT5 Account (FTMO Demo), GitHub SSH deploy-keys.

### 1.1 Packages & Python
```powershell
# Chocolatey install (Admin PowerShell)
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

choco install -y python git openssh vscode sops age
python -m pip install --upgrade pip
pip install MetaTrader5 fastapi uvicorn numpy pandas msgpack-numpy pyzmq requests python-dotenv cryptography
```

**Python Version:** 3.12.x (pip check `python --version`)

### 1.2 MT5 Setup
1. Download MT5: https://www.metatrader5.com/en/download → Install `mt5.exe`.
2. Login: FTMO Demo Account (Hedging Mode).
3. Expert Advisors erlauben: Tools → Options → Expert Advisors → Allow DLL/Automation.
4. Terminal-Pfad notieren: `%APPDATA%\MetaQuotes\Terminal\<hash>\terminal64.exe`

### 1.3 Tailscale
1. Download MSI: https://tailscale.com/download → Install.
2. PowerShell (Admin): `tailscale up --authkey=<one-time-key> --advertise-tags=tag:muscle --hostname=muscle-win`
3. IP notieren: `tailscale ip -4` (z.B. 100.64.0.20)

### 1.4 Windows Firewall (UFW-Äquivalent)
```powershell
# Inbound Rules (PowerShell Admin)
New-NetFirewallRule -DisplayName "Tailscale" -Direction Inbound -Protocol UDP -LocalPort 41641 -Action Allow
New-NetFirewallRule -DisplayName "FastAPI MT5 Bridge" -Direction Inbound -LocalPort 8080 -Action Allow -RemoteAddress 100.64.0.0/10
New-NetFirewallRule -DisplayName "RDP" -Direction Inbound -Protocol TCP -LocalPort 3389 -Action Allow -RemoteAddress 100.64.0.0/10
New-NetFirewallRule -DisplayName "ZMQ Data (Box1 PUB)" -Direction Inbound -Protocol TCP -LocalPort 5555 -Action Allow -RemoteAddress 100.64.0.0/10
Set-NetFirewallProfile -Profile Domain,Public,Private -DefaultInboundAction Block -DefaultOutboundAction Allow
```

### 1.5 Services (NSSM als systemd)
```powershell
# NSSM install (für FastAPI + Data Engine)
choco install nssm
nssm install MT5-Bridge "C:\Python\Python312\python.exe" "C:\trading\execution-mt5-windows\main.py"
nssm set MT5-Bridge AppDirectory "C:\trading"
nssm set MT5-Bridge AppStdout "C:\trading\logs\bridge.log"
nssm set MT5-Bridge AppStderr "C:\trading\logs\bridge.err"
# Graceful Shutdown Konfiguration (G-10) - Erlaubt Python Signal-Handling
nssm set MT5-Bridge AppStopMethodSkip 6
nssm set MT5-Bridge AppStopMethodConsole 15000

nssm start MT5-Bridge

nssm install Data-Engine "C:\Python\Python312\python.exe" "C:\trading\execution-mt5-windows\data_pull.py"
nssm set Data-Engine AppStopMethodSkip 6
nssm set Data-Engine AppStopMethodConsole 15000
nssm start Data-Engine
```

## 2. Linux VPS Setup (Hetzner Ubuntu 24.04 | Brain: Box2 Agents + Box4 Lab)

**Voraussetzungen:** Frischer Ubuntu 24.04 Droplet, root-SSH.

```bash
# 2.1 Update & Essentials
apt update && apt upgrade -y
apt install -y ufw fail2ban git python3.12 python3.12-venv python3-pip tmux htop unattended-upgrades curl rsync age
# SOPS manuell installieren (da nicht im Std-Repo in aktuellen Versionen)
curl -LO https://github.com/getsops/sops/releases/download/v3.8.1/sops-v3.8.1.linux.amd64
mv sops-v3.8.1.linux.amd64 /usr/local/bin/sops
chmod +x /usr/local/bin/sops

# 2.2 Python Env
python3.12 -m venv /opt/trading/venv
source /opt/trading/venv/bin/activate
pip install --upgrade pip
pip install numpy pandas fastapi uvicorn pyzmq msgpack-numpy openbb scikit-learn requests python-dotenv cryptography

# 2.3 Tailscale
curl -fsSL https://tailscale.com/install.sh | sh
tailscale up --authkey=<one-time-key> --advertise-tags=tag:brain --hostname=brain-vps
tailscale ip -4  # Notiere IP (z.B. 100.64.0.10)

# 2.4 UFW
ufw default deny incoming
ufw default allow outgoing
ufw allow 22/tcp from <Leon-IP>
ufw allow 41641/udp  # Tailscale
ufw allow from 100.64.0.0/10  # Tailscale Subnet
ufw --force enable

# 2.5 Fail2ban
systemctl enable --now fail2ban
cat > /etc/fail2ban/jail.local << 'EOF'
[sshd]
enabled = true
maxretry = 3
bantime = 3600
EOF

# 2.6 Users & Dirs
useradd -m -s /bin/bash trading-bot
chown -R trading-bot:trading-bot /opt/trading
su - trading-bot -c "mkdir -p /opt/trading/{logs,models,config,data}"

# 2.7 Repos Clone (SSH deploy-keys in GitHub)
su - trading-bot
cd /opt/trading
git clone git@github.com:<user>/trading-brain-linux.git .
git clone git@github.com:<user>/trading-config.git config
deactivate
```

### 2.8 Systemd Services
```bash
# Box2 Agents (ZMQ Sub + FastAPI Signal)
cat > /etc/systemd/system/trading-agents.service << 'EOF'
[Unit]
Description=Trading Agents (Box2)
After=network.target

[Service]
User=trading-bot
WorkingDirectory=/opt/trading
Environment=PATH=/opt/trading/venv/bin
ExecStart=/opt/trading/venv/bin/python box2_agents.py
# Graceful Shutdown: ZMQ-Sockets abbauen (G-10)
KillSignal=SIGTERM
TimeoutStopSec=15
Restart=always
StandardOutput=append:/opt/trading/logs/agents.log
StandardError=append:/opt/trading/logs/agents.err

[Install]
WantedBy=multi-user.target
EOF

# Box4 Lab (Backtest/RL, on-demand)
cat > /etc/systemd/system/trading-lab.service << 'EOF'
[Unit]
Description=Trading Lab (Box4)
After=network.target trading-agents.service

[Service]
User=trading-bot
WorkingDirectory=/opt/trading
Environment=PATH=/opt/trading/venv/bin
ExecStart=/opt/trading/venv/bin/python lab_runner.py
KillSignal=SIGTERM
TimeoutStopSec=15
Restart=always
StandardOutput=append:/opt/trading/logs/lab.log
StandardError=append:/opt/trading/logs/lab.err

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now trading-agents trading-lab
```

## 3. Tailscale Konfiguration

**Tailscale Admin Console (tailscale.com):**
```json
{
  "acls": [
    {"action": "accept", "src": ["tag:brain"], "dst": ["tag:muscle:5555,8080,3389"]},
    {"action": "accept", "src": ["autogroup:admin"], "dst": ["*:*"]}
  ],
  "tagOwners": {
    "tag:brain": ["autogroup:admin"],
    "tag:muscle": ["autogroup:admin"]
  }
}
```
- Test: `tailscale ping muscle-win` (von brain-vps)

## 4. Two-Repo Deployment + Config Sync

**Repos:** 
- Brain: `trading-brain-linux` (Box2/4 code)
- Muscle: `execution-mt5-windows` (Box1/3 code)
- Shared: `trading-config` (compliance.yaml, thresholds.json)

**Sync (Cron auf beiden):**
```bash
# Linux VPS (/etc/cron.d/trading-sync)
*/5 * * * * trading-bot cd /opt/trading && git -C . pull origin main && git -C config pull origin main && systemctl restart trading-agents

# Windows (Task Scheduler): git pull every 5min → Restart NSSM services
```

**Config-Hash:** Automatisch in box2_agents.py: `config_hash = hashlib.sha256(open('config/compliance.yaml').read().encode()).hexdigest()[:8]` → In REST /api/v1/signal Payload.

## 5. First-Run Checklist

| Schritt | Check | Command |
|---------|-------|---------|
| 1 | Tailscale connected | `tailscale status` |
| 2 | Repos up-to-date | `git status` (clean) |
| 3 | Services running | `systemctl status trading-*` / `nssm status MT5-Bridge` |
| 4 | ZMQ Test (Win→Linux) | Python ZMQ pub/sub test script |
| 5 | REST Readiness-Check | `curl http://100.64.0.20:8080/health` (erwartet 200 OK + algo_allowed) |
| 6 | REST Signal Test | `curl -X POST http://100.64.0.20:8080/api/v1/signal -d '{"state":0}'` |
| 7 | Heartbeat OK | Logs: "alive" every 5s |
| 8 | Config Hash Match | Payload hash == local hash |

**Reihenfolge:** Tailscale → Firewall → Repos → Services → Test End-to-End.

## 6. Troubleshooting (Top 5 aus Gap-Analysen)

1. **ZMQ Reconnect Fail (Phase B):** Exp-Backoff fehlt → Add `context.setsockopt(zmq.RECONNECT_IVL, 500); context.setsockopt(zmq.RECONNECT_IVL_MAX, 30000)`
2. **Config Desync (Phase D/10):** Hash mismatch → `SUSPEND` → Manual `git pull` on both + restart.
3. **Tailscale Down:** Ping fail → `ufw status`; `tailscale up --reset`
4. **MT5 Requotes (Phase B):** Retry=2, delay=100ms in order_send.
5. **UFW Blocks Tailscale (Phase D):** `ufw allow from 100.64.0.0/10`; `tailscale ping <peer>`

## 7. Monitoring & Alerts

### 7.1 Linux-Side Health Checks (Box 2)
**Täglich checken (Cron `/etc/cron.daily/trading-health`):**
```bash
#!/bin/bash
systemctl is-active --quiet trading-agents || echo "Agents down" | mail -s "Trading Alert" leon@example.com
tailscale status | grep -q muscle-win || echo "VPN down" | mail -s "VPN Alert" leon@example.com
df -h /opt | awk '$5>90 {print "Disk full"}' | mail -s "Disk Alert" leon@example.com
```
**Alerts:** SMTP (Postfix minimal: `apt install mailutils`), Logs: `journalctl -u trading-agents -f`

### 7.2 Windows-Side System Alerts (Box 3)
Die FastAPI Bridge sendet bei kritischen Events (z.B. `SUSPEND`, `Risk-Kill`, `Heartbeat-Timeout` oder fehlgeschlagenen Order-Ausführungen) direkt systemimmanente Sofort-Alarme per SMTP. 

**Voraussetzungen (mit SOPS verschlüsselt):**
Die Ablage einer Plaintext `.env` ist auf dem Server strikt verboten. Nutze SOPS, um eine `secrets.enc.env` zu generieren:
```ini
# secrets.enc.env (entschlüsselt im RAM)
SMTP_SERVER=smtp.example.com
SMTP_PORT=587
SMTP_USER=alert@example.com
SMTP_PASS=DeinSicheresPasswort
ALERT_EMAIL_RECIPIENT=supervisor@example.com
```
*Vorteil:* Python (bzw. ein `dotenv-loader` Wrapper) entschlüsselt die Datei via SOPS beim Start on-the-fly (`sops -d secrets.enc.env`). Python verarbeitet die Alerts aus dem Hot-Path selbstständig per `smtplib`.

## 8. Rollback-Mechanismus (G-05)

> *Ziel: Jedes Deployment auf Brain und Muscle, das eine definierte Health-Check-Sequenz nicht besteht, wird automatisch auf den letzten stabilen Git-Commit zurückgerollt — ohne manuellen Eingriff.*

### 8.1 Prinzip: Deploy → Health-Check → Rollback-Guard

```
git pull / Task Scheduler pull
         │
         ▼
  service restart (systemd / NSSM)
         │
         ▼
  health_check.py  ──── PASS ──→  Normal Operation
         │
        FAIL
         │
         ▼
  git revert HEAD (non-interactive)
         │
         ▼
  service restart mit bekannt-gutem Commit
         │
         ▼
  SMTP Alert: "ROLLBACK executed on <Brain|Muscle>"
```

**Cooldown-Guard:** Rollback darf maximal **1x pro 15 Minuten** ausgeführt werden (Lockfile-Mechanismus). Verhindert Rollback-Loops bei dauerhaft defekten Commits auf `main`.

---

### 8.2 Health-Check Script (Brain — Linux VPS)

```python
#!/usr/bin/env python3
# /opt/trading/scripts/health_check.py
# Wird nach jedem git pull + service restart aufgerufen.
# Exit 0 = Gesund. Exit 1 = Rollback auslösen.

import subprocess, sys, time, socket, os, smtplib
from pathlib import Path
from email.mime.text import MIMEText

FASTAPI_HOST = "127.0.0.1"       # Box 2 REST intern
FASTAPI_PORT = 8080
SIGNAL_ENDPOINT = "/api/v1/signal"
ZMQ_CHECK_TIMEOUT_S = 5
LOCKFILE = Path("/tmp/trading_rollback.lock")
COOLDOWN_SECONDS = 900            # 15 Minuten

def check_tcp_port(host: str, port: int, timeout: int = 3) -> bool:
    """Prüft ob ein TCP-Port erreichbar ist (Service gestartet)."""
    try:
        with socket.create_connection((host, port), timeout=timeout):
            return True
    except OSError:
        return False

def check_systemd_service(name: str) -> bool:
    """Prüft ob ein systemd-Service aktiv ist."""
    result = subprocess.run(
        ["systemctl", "is-active", "--quiet", name],
        capture_output=True
    )
    return result.returncode == 0

def check_fastapi_health() -> bool:
    """Prüft /health Endpoint der FastAPI (G-07)."""
    import urllib.request
    try:
        url = f"http://{FASTAPI_HOST}:{FASTAPI_PORT}/health"
        with urllib.request.urlopen(url, timeout=3) as resp:
            return resp.status == 200
    except Exception:
        return False

def is_cooldown_active() -> bool:
    """Verhindert Rollback-Loops: max 1x pro COOLDOWN_SECONDS."""
    if LOCKFILE.exists():
        age = time.time() - LOCKFILE.stat().st_mtime
        if age < COOLDOWN_SECONDS:
            return True
        LOCKFILE.unlink()   # Abgelaufenes Lock entfernen
    return False

def send_alert(subject: str, body: str):
    """SMTP Alert an Supervisor (Credentials aus SOPS .env)."""
    smtp_server  = os.environ.get("SMTP_SERVER", "")
    smtp_port    = int(os.environ.get("SMTP_PORT", "587"))
    smtp_user    = os.environ.get("SMTP_USER", "")
    smtp_pass    = os.environ.get("SMTP_PASS", "")
    recipient    = os.environ.get("ALERT_EMAIL_RECIPIENT", "")
    if not all([smtp_server, smtp_user, smtp_pass, recipient]):
        print(f"[ALERT] {subject}: {body}")  # Fallback: structlog
        return
    msg = MIMEText(body)
    msg["Subject"] = subject
    msg["From"]    = smtp_user
    msg["To"]      = recipient
    with smtplib.SMTP(smtp_server, smtp_port) as s:
        s.starttls()
        s.login(smtp_user, smtp_pass)
        s.send_message(msg)

def main():
    errors = []

    # 1. systemd Services prüfen
    for svc in ["trading-agents", "trading-lab"]:
        if not check_systemd_service(svc):
            errors.append(f"systemd service '{svc}' ist NICHT aktiv")

    # 2. FastAPI erreichbar?
    if not check_tcp_port(FASTAPI_HOST, FASTAPI_PORT):
        errors.append(f"FastAPI Port {FASTAPI_PORT} nicht erreichbar")
    elif not check_fastapi_health():
        errors.append(f"FastAPI /health returned non-200")

    if not errors:
        print("HEALTH CHECK: PASSED")
        sys.exit(0)

    # --- Health-Check fehlgeschlagen ---
    print(f"HEALTH CHECK: FAILED — {errors}", file=sys.stderr)

    if is_cooldown_active():
        print("ROLLBACK: Cooldown aktiv — kein weiterer Rollback", file=sys.stderr)
        send_alert("[TRADING] ⛔ Health Check FAIL (Cooldown aktiv)",
                   f"Fehler: {errors}\n\nRollback-Cooldown aktiv. Manueller Eingriff nötig.")
        sys.exit(2)

    # Rollback ausführen
    LOCKFILE.touch()
    repo = Path("/opt/trading")
    bad_commit  = subprocess.check_output(["git", "-C", str(repo), "rev-parse", "HEAD"],
                                           text=True).strip()
    subprocess.run(["git", "-C", str(repo), "revert", "--no-edit", "HEAD"], check=True)
    subprocess.run(["systemctl", "restart", "trading-agents"], check=True)
    subprocess.run(["systemctl", "restart", "trading-lab"],    check=True)

    good_commit = subprocess.check_output(["git", "-C", str(repo), "rev-parse", "HEAD"],
                                           text=True).strip()
    send_alert(
        "[TRADING] ⚠️ ROLLBACK ausgeführt (Brain VPS)",
        f"Rollback von {bad_commit[:8]} → {good_commit[:8]}\n\nFehler: {errors}"
    )
    print(f"ROLLBACK: Reverted to {good_commit[:8]}")
    sys.exit(1)

if __name__ == "__main__":
    main()
```

---

### 8.3 Deployment-Trigger Script (Brain — Linux VPS)

Ersetzt den simplen `git pull`-Cron aus §4. Health-Check wird **nach jedem Pull** automatisch aufgerufen:

```bash
#!/bin/bash
# /opt/trading/scripts/deploy_brain.sh
# Cron: */5 * * * * trading-bot /opt/trading/scripts/deploy_brain.sh >> /opt/trading/logs/deploy.log 2>&1

set -e
REPO="/opt/trading"
CFG_REPO="/opt/trading/config"

# SOPS Secrets laden (G-02)
eval $(sops -d $REPO/.env.enc | sed 's/^/export /')

# 1. Code + Config pullen
git -C "$REPO"     pull --ff-only origin main
git -C "$CFG_REPO" pull --ff-only origin main

# 2. Services neu starten
systemctl restart trading-agents trading-lab

# 3. Kurzes Startup-Delay, dann Health-Check
sleep 10
python3 "$REPO/scripts/health_check.py"
```

> **`--ff-only`:** Verhindert ungewollte Merge-Commits auf dem Server. Pull schlägt fehl statt zu mergen.

---

### 8.4 Health-Check & Rollback (Muscle — Windows Server)

```powershell
# C:\trading\scripts\Deploy-Muscle.ps1
# Task Scheduler: alle 5 Minuten, User: SYSTEM

param(
    [string]$Repo    = "C:\trading\execution-mt5-windows",
    [string]$CfgRepo = "C:\trading\trading-config",
    [string]$LockFile = "$env:TEMP\trading_rollback.lock"
)

$ErrorActionPreference = "Stop"
$COOLDOWN_MINUTES = 15

function Test-ServiceRunning($ServiceName) {
    $svc = Get-Service -Name $ServiceName -ErrorAction SilentlyContinue
    return ($svc -and $svc.Status -eq "Running")
}

function Test-FastAPI {
    try {
        $r = Invoke-WebRequest -Uri "http://127.0.0.1:8080/health" -TimeoutSec 3 -UseBasicParsing
        return $r.StatusCode -eq 200
    } catch { return $false }
}

function Send-Alert($Subject, $Body) {
    # Credentials aus Env (via SOPS secrets, G-02)
    $s = New-Object Net.Mail.SmtpClient($env:SMTP_SERVER, $env:SMTP_PORT)
    $s.EnableSsl = $true
    $s.Credentials = New-Object Net.NetworkCredential($env:SMTP_USER, $env:SMTP_PASS)
    $msg = New-Object Net.Mail.MailMessage($env:SMTP_USER, $env:ALERT_EMAIL_RECIPIENT, $Subject, $Body)
    $s.Send($msg)
}

function Test-CooldownActive {
    if (Test-Path $LockFile) {
        $age = (Get-Date) - (Get-Item $LockFile).LastWriteTime
        if ($age.TotalMinutes -lt $COOLDOWN_MINUTES) { return $true }
        Remove-Item $LockFile -Force
    }
    return $false
}

# --- Deploy ---
Set-Location $Repo
git pull --ff-only origin main
Set-Location $CfgRepo
git pull --ff-only origin main

# Services neu starten
Restart-Service -Name "MT5-Bridge"  -Force
Restart-Service -Name "Data-Engine" -Force
Start-Sleep -Seconds 10

# --- Health Check ---
$Errors = @()
foreach ($svc in @("MT5-Bridge", "Data-Engine")) {
    if (-not (Test-ServiceRunning $svc)) { $Errors += "Service $svc läuft nicht" }
}
if (-not (Test-FastAPI)) { $Errors += "FastAPI /health nicht erreichbar" }

if ($Errors.Count -eq 0) {
    Write-Host "HEALTH CHECK: PASSED"
    exit 0
}

# --- Rollback ---
Write-Warning "HEALTH CHECK FAILED: $($Errors -join ', ')"

if (Test-CooldownActive) {
    Send-Alert "[TRADING] ⛔ Health FAIL (Cooldown)" "Fehler: $Errors`n`nManueller Eingriff nötig."
    exit 2
}

New-Item -Path $LockFile -ItemType File -Force | Out-Null
$BadCommit  = git -C $Repo rev-parse HEAD
git -C $Repo revert --no-edit HEAD
$GoodCommit = git -C $Repo rev-parse HEAD

Restart-Service -Name "MT5-Bridge"  -Force
Restart-Service -Name "Data-Engine" -Force

Send-Alert "[TRADING] ⚠️ ROLLBACK (Muscle WIN)" `
    "Rollback $($BadCommit.Substring(0,8)) → $($GoodCommit.Substring(0,8))`n`nFehler: $Errors"

Write-Host "ROLLBACK: Reverted to $($GoodCommit.Substring(0,8))"
exit 1
```

**Task Scheduler Einrichtung (Muscle):**
```powershell
# Admin PowerShell — einmalig ausführen
$action  = New-ScheduledTaskAction -Execute "powershell.exe" `
             -Argument "-NonInteractive -File C:\trading\scripts\Deploy-Muscle.ps1"
$trigger = New-ScheduledTaskTrigger -RepetitionInterval (New-TimeSpan -Minutes 5) -Once -At "00:00"
Register-ScheduledTask -TaskName "TradingDeploy" -Action $action -Trigger $trigger `
  -RunLevel Highest -User "SYSTEM" -Force
```

---

### 8.5 Rollback-Entscheidungsmatrix

| Szenario | Reaktion | Manueller Eingriff? |
|---|---|---|
| Neuer Commit deployt, Service startet nicht | Automatischer Rollback + SMTP Alert | Nein (bis Cooldown) |
| Rollback fehlgeschlagen (Git-Konflikt) | SMTP Alert, Services bleiben im alten State | **Ja** |
| Cooldown aktiv, nächster bad Pull | SMTP Alert, kein weiterer Rollback | **Ja** |
| Config-Hash nach Rollback immer noch falsch | `ConfigDesyncPanic` in Box 3 → SUSPEND | **Ja** |
| `--ff-only` Pull schlägt fehl (diverged branch) | Git-Error, kein Restart, kein Rollback | **Ja** |

> **Eskalation:** Drei aufeinanderfolgende Rollbacks (erkennbar an Commit-History) signalisieren ein strukturelles Problem im `main`-Branch → Supervisor muss den Branch manuell reparieren und `git push --force-with-lease` nach Hotfix.

---

## 9. Observability & Log-Management (Rotation)

Um "Disk Full" Ausfälle (Silent Deaths) durch wachsende JSON-Log-Streams zu verhindern, lagern wir die Log-Rotation exklusiv auf Betriebssystem-Ebene aus (12-Factor App Prinzip).

### 9.1 Windows (NSSM Log-Rotation auf Box 1 & 3)

NSSM bietet native, hochperformante Log-Rotation. Es blockiert Python nicht und umgeht Windows "File-in-use"-Sperren (`AppRotateOnline 1`).

```powershell
# Admin PowerShell: Setup NSSM Log-Rotation
nssm set MT5-Bridge AppRotateFiles 1
nssm set MT5-Bridge AppRotateOnline 1
nssm set MT5-Bridge AppRotateBytes 52428800  # 50 MB
nssm set MT5-Bridge AppRotateBytesHigh 0

nssm set Data-Engine AppRotateFiles 1
nssm set Data-Engine AppRotateOnline 1
nssm set Data-Engine AppRotateBytes 52428800 # 50 MB
nssm set Data-Engine AppRotateBytesHigh 0
```
*Wichtig:* Die Flag `AppRotateFiles 1` garantiert, dass NSSM auch beim Start/Restart des Services die Logdatei umbenennt und wegrotiert, falls das 50MB-Limit überschritten ist.

### 9.2 Linux (Logrotate auf Box 2 & 4)

Da die Linux-Services jetzt via `StandardOutput=append:/opt/trading/logs/...` direkt in Dateien schreiben, konfigurieren wir das Standardwerkzeug `logrotate`. **Die `copytruncate`-Direktive ist hierbei Pflicht**, damit der Python-Prozess nicht per `kill -s USR1` neugestartet werden muss, um Datei-Handles zu lösen.

```bash
# Auf dem Linux VPS ausführen:
cat > /etc/logrotate.d/trading << 'EOF'
/opt/trading/logs/*.log /opt/trading/logs/*.err {
    su root root
    daily
    rotate 14
    size 50M
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
}
EOF

# Syntax-Test
logrotate -d /etc/logrotate.d/trading
```

---

## 10. Disaster Recovery Playbook (A-5)

> *Definiert RPO, RTO und die sequenzielle Wiederherstellung beider Maschinen nach einem Totalausfall.*

### 10.1 Recovery-Ziele

| Parameter | Wert | Begründung |
|---|---|---|
| **RPO** (Recovery Point Objective) | **< 5 Minuten** | Git-Commits (Brain-Repo + Config-Repo) alle 5 Min via Cron gesynct. Datenverlust beschränkt sich auf den letzten uncommitted State. |
| **RTO** (Recovery Time Objective) | **< 2 Stunden** | Hetzner-Snapshot Restore (~10 Min) + Tailscale Re-Auth (~5 Min) + Service-Start + Health-Check. |

### 10.2 Szenario: Linux VPS Totalausfall (Brain)

| Schritt | Aktion | Erwartete Dauer |
|---|---|---|
| 1 | Hetzner-Snapshot wiederherstellen (letztes Wochen-Backup) | 10 Min |
| 2 | `apt update && apt upgrade -y` | 5 Min |
| 3 | Tailscale re-authentifizieren: `tailscale up --authkey=<new-key> --advertise-tags=tag:brain` | 2 Min |
| 4 | Git-Repos pullen: `git -C /opt/trading pull origin main && git -C /opt/trading/config pull origin main` | 2 Min |
| 5 | SOPS age-Key provisionieren (Out-of-Band, vom Supervisor-Laptop) | 5 Min |
| 6 | Services starten: `systemctl restart trading-agents trading-lab` | 1 Min |
| 7 | Health-Check: `python3 /opt/trading/scripts/health_check.py` | 1 Min |
| 8 | Tailscale Ping von Muscle prüfen: `tailscale ping brain-vps` | 1 Min |

**Während des Ausfalls:** Box 3 (Muscle) geht in `SUSPEND` (Heartbeat fehlt). Laufende Trades werden durch Broker-Side SL geschützt. Keine neuen Trades.

### 10.3 Szenario: Windows Server Totalausfall (Muscle)

| Schritt | Aktion | Erwartete Dauer |
|---|---|---|
| 1 | Windows Server neu aufsetzen oder Backup einspielen | 30-60 Min |
| 2 | MT5 installieren, FTMO-Konto re-authentifizieren | 10 Min |
| 3 | Tailscale MSI installieren + Auth | 5 Min |
| 4 | Git-Repos klonen, NSSM Services einrichten (siehe §1) | 15 Min |
| 5 | SOPS age-Key provisionieren | 5 Min |
| 6 | Services starten: `nssm start MT5-Bridge && nssm start Data-Engine` | 2 Min |
| 7 | Health-Check: `/health` Endpoint + ZMQ Test | 5 Min |

**Während des Ausfalls:** Box 2 (Brain) erkennt via Heartbeat-Timeout, dass Muscle offline ist. Agenten werden eingefroren (kein Signal-Senden möglich).

### 10.4 Recovery-Reihenfolge (Beide ausfallen)

1. **Muscle (Windows) zuerst** — MT5-Terminal muss laufen, bevor Box 2 Signale senden kann.
2. **Brain (Linux) danach** — Box 2 bootet im `COLD_START` (→ [[03-blackbox-agents|Kap. 03 §3]]) und wartet auf Heartbeat.

---

*Last Updated: 2026-04-19. Questions? Ping Supervisor.*


========================================
FILE: 10-MOC-Blackboxen.md
========================================
---
aliases: [Blackboxen, 3+1 Blackbox Design]
tags: [moc, blackbox, architecture]
related: [[00-MOC-Trading-System]], [[13-MOC-Agenten]], [[15-MOC-Lab]]
trust: canonical
last_reviewed: 2026-04-11
---
# 10. Map of Content: Blackboxen

Übersicht über die 3 Live-Boxen und die Lab-Box.

## Box 1: Data Engine
- [[02-blackbox-data|Doku: Blackbox 1 (Data Engine)]]
- [[parquet-ferry|Konzept: Parquet Ferry]]

## Box 2: The Scientist (Agenten)
- [[03-blackbox-agents|Doku: Blackbox 2 (Agents)]]
- [[13-MOC-Agenten|MOC: Agenten & Orchestrierung]]
- [[decision-matrix|Konzept: Decision Matrix]]

## Box 3: MT5 Execution Bridge
- [[04-blackbox-mt5|Doku: Blackbox 3 (MT5 Execution)]]
- [[11-MOC-Schnittstellen|MOC: Schnittstellen]]
- [[heartbeat-protocol|Konzept: Heartbeat-Protokoll]]

## Box 4: The Improvement Lab
- [[08-backtesting-lab|Doku: The Improvement Lab]]
- [[15-MOC-Lab|MOC: Lab & Backtesting]]


========================================
FILE: 11-MOC-Schnittstellen.md
========================================
---
aliases: [Schnittstellen, APIs, IPC]
tags: [moc, api, interfaces, ipc]
related: [[00-MOC-Trading-System]], [[10-MOC-Blackboxen]]
trust: canonical
last_reviewed: 2026-04-11
---
# 11. Map of Content: Schnittstellen

Hub für alle Inter-Process und System-Schnittstellen.

## Kern-Doku
- [[05-schnittstellen|Schnittstellen-Spezifikation (IPC, API, Tailscale)]]

## Protokolle & Technologiefokus
- [[heartbeat-protocol|Konzept: Heartbeat Protocol (Python↔MQL5 IPC)]]
- [[parquet-ferry|Konzept: Parquet Ferry (Data Sync Historic)]]
- VPN: Tailscale (siehe [[07-memory-and-infra]])
- Notification: SMTP Alerting (Suspends & Killswitches)


========================================
FILE: 12-MOC-Risikomanagement.md
========================================
---
aliases: [Risikomanagement, Risk, Drawdown]
tags: [moc, risk, compliance, execution]
related: [[00-MOC-Trading-System]], [[04-blackbox-mt5]]
trust: canonical
last_reviewed: 2026-04-11
---
# 12. Map of Content: Risikomanagement

Dieser Hub konsolidiert alles zum Thema Kapitalerhalt und Regeltreue.

## Konzepte & Logik
- [[prop-firm-compliance|Konzept: Prop-Firm Compliance (DD, News, Consistency)]]
- [[capital-allocator|Konzept: Capital Allocator (Positionsgrößen)]]
- [[trade-lifecycle|Konzept: Trade Lifecycle (Trailing SL, Partial Close)]]
- [[graceful-degradation|Konzept: Graceful Degradation (SUSPEND-Modus)]]

## Implementierung
- Wird in Box 3 exekutiert: [[04-blackbox-mt5|MT5 Execution Bridge]]


========================================
FILE: 13-MOC-Agenten.md
========================================
---
aliases: [Agenten, Orchestrierung, The Scientist]
tags: [moc, agents, ai, composition]
related: [[00-MOC-Trading-System]], [[10-MOC-Blackboxen]]
trust: canonical
last_reviewed: 2026-04-11
---
# 13. Map of Content: Agenten & Orchestrierung

Hub für die AI-Logik und Agenten-Steuerung (Blackbox 2).

## Kern-Architektur
- [[03-blackbox-agents|Doku: Blackbox 2 (Agents)]]

## Markt-Analyse & Signale
- [[entropy-inversion|Konzept: Entropy Inversion Hypothesis]]
- [[decision-matrix|Konzept: Decision Matrix (SJM x Entropy)]]

## System-Design Prinzipien
- [[evidence-gate|Konzept: Evidence Gate (Beweispflicht)]]
- [[context-gate|Konzept: Context Gate (Poisoning-Schutz)]]
- OpenClaw Integration (Deterministische Workflows)
- Keine Short-Positionen in V1 (States strikt 0 oder 1)


========================================
FILE: 15-MOC-Lab.md
========================================
---
aliases: [Improvement Lab, Backtesting, Lab, Box 4]
tags: [moc, lab, backtesting, analytics]
related: [[00-MOC-Trading-System]], [[10-MOC-Blackboxen]]
trust: canonical
last_reviewed: 2026-04-11
---
# 15. Map of Content: The Improvement Lab

Zentraler Hub für das historische Training, Backtesting und Re-Inforcement-Learning (Box 4).

## Kern-Doku
- [[08-backtesting-lab|Doku: The Improvement Lab]]

## Konzepte & Prozesse
- [[parquet-ferry|Konzept: Parquet Ferry]] (Wie historische Daten ins Lab kommen)
- Model Promotion Pipeline (Integration nach Blackbox 2)


========================================
FILE: refs/concepts/trade-lifecycle.md
========================================
---
aliases: [Trade Lifecycle, Trailing SL, Partial Close]
tags: [concept, risk, execution, trade-management]
related: [[12-MOC-Risikomanagement]], [[04-blackbox-mt5]]
trust: canonical
last_reviewed: 2026-04-11
---
# Trade Lifecycle

Der geregelte Ablauf eines Trades von der Platzierung bis zum finalen Exit. Durch die Limitierung auf Long-Only (`1` oder `0`), agiert Box 3 asymmetrisch in ihrem Management:

## Phasen
1. **Entry:** Auslösung des Trades auf ein State-`1`-Signal. Setzen eines initialen, absoluten Hard-Stop-Loss.
2. **First Milestone (`1R`):** Erreicht der Trade das erste Ziel (1 Risk Bracket Profit), greift der **Partial Close** (z.B. 50% Schließung zur Gewinnsicherung) und der SL rückt auf Break-Even.
3. **Trailing Mode:** Darüber hinaus greift ein weiterer Trailing-SL, der dem Preis mit einem gewissen Abstand folgt.
4. **State `0` (Neutral):** Empfängt Box 3 ein `0` Signal, wird der Trade explizit *nicht* wild sofort als Market-Order geschlossen. Stattdessen wird der Trailing-SL "festgezogen" (Tight Trailing Mode), um den Trade organisch bei einer Gegenbewegung hinauszu-stoppen (Graceful Exit) und Spreadkosten vorzubeugen.


========================================
FILE: refs/concepts/prop-firm-compliance.md
========================================
---
aliases: [Prop-Firm Compliance, FTMO Rules, Drawdown Limits]
tags: [concept, risk, compliance]
related: [[12-MOC-Risikomanagement]], [[04-blackbox-mt5]]
trust: canonical
last_reviewed: 2026-04-11
---
# Prop-Firm Compliance

Dieses System ist explizit darauf ausgelegt, die harten Vorgaben von Fremdkapital-Firmen (Proprietary Trading Firms wie FTMO) einzuhalten.

## Zentrale Guardrails
Die Überwachung erfolgt vollständig in Box 3 (MT5 Bridge):
- **Static Drawdown Limit (Daily Loss):** Das System muss bei z.B. 5% Tagesverlust hart blockieren. Signale von Box 2 werden ab diesem Soft-Stop nicht mehr als Market Orders exekutiert.
- **Trailing Drawdown Limit:** Max Drawdown über den gesamten Account-Lebenszyklus.
- **News Trading Restriction:** Reduktion oder Suspendierung der Trading-Aktivität x Minuten vor und nach roten High-Impact News Events (gefeedet über OpenBB aus Box 1).
- **Consistency Rules:** Gewährleistung, dass Trades und Lot-Sizes nicht erratisch oder inkonsistent skaliert werden ([[capital-allocator]]).

Das harte Risikomanagement der Exekutionsbrücke schützt das Konto somit davor, wegen Metrik-Verstößen geschlossen zu werden.


========================================
FILE: refs/concepts/entropy-inversion.md
========================================
---
aliases: [Entropy Inversion Hypothese, Entropy Inversion, Market Folding, Entropie]
tags: [concept, data, agents, marktstruktur]
related: [[13-MOC-Agenten]], [[03-blackbox-agents]], [[decision-matrix]]
trust: canonical
source: Arella Market Folding Paper
last_reviewed: 2026-04-11
---
# Entropy Inversion Hypothesis

Die *Entropy Inversion Hypothesis* beschreibt den Kern des Marktanalyse-Modells in Blackbox 2. Sie nutzt das Konzept des "Market Foldings" nach Arella.

## Kern-Definition
- **Hohe Entropie (H↑):** Signalisiert einen gesunden, stabilen Markt (Faltung / "Folding"). Die Marktkräfte verteilen sich organisch. Dies ist die **Go-Bedingung** für das System.
- **Niedrige Entropie (H↓):** Signalisiert eine einseitige Dominanz, Kollaps oder Panik (z.B. Flash Crash, News-Event). Dies ist eine strikte **No-Go-Bedingung**.

In der [[decision-matrix]] wird die berechnete Entropie mit der diskreten Output-Matrix kombiniert. 

Eine Position (Long = 1) darf nur dann eingenommen oder gehalten werden, wenn der Markt sich im Zustand gesunder Entropie befindet.


========================================
FILE: refs/concepts/decision-matrix.md
========================================
---
aliases: [Decision Matrix, Signal Matrix]
tags: [concept, agents, logic, signal]
related: [[13-MOC-Agenten]], [[entropy-inversion]]
trust: canonical
last_reviewed: 2026-04-11
---
# Decision Matrix

Die finale Signal Matrix in Blackbox 2, welche Agenten-Konfidenz und System-Gesundheit kombiniert.

## Formel
`SJM-State × Entropy Factor = System-State`

- **SJM-State (Sub-Jealousy Model / Agent State):** Das Signal der klasifizierenden AI-Modelle (bullish/bearish Regime etc.). Für V1 gilt: `1` (Long) oder `0` (Neutral/Exit).
- **Entropy Factor:** Resultiert aus der [[entropy-inversion]]. Gesunder Markt = `1`, Gestörter/Unklarer Markt = `0`.

## Matrix
| SJM-State | Entropy | Output State | Aktion |
|---|---|---|---|
| 0 | 0 | **0** | Passiv (bzw. Tight Trailing) |
| 0 | 1 | **0** | Passiv (bzw. Tight Trailing) |
| 1 | 0 | **0** | Blockiert (Kein Go wegen Panik-Risiko) |
| 1 | 1 | **1** | **Go (Long)** |

Somit fungiert die Entropie als binärer Multiplikator und hartes Filter-Kriterium der Signale.


========================================
FILE: refs/concepts/context-gate.md
========================================
---
aliases: [Context Gate, Poisoning Protection]
tags: [concept, agents, security, design]
related: [[13-MOC-Agenten]], [[03-blackbox-agents]]
trust: canonical
last_reviewed: 2026-04-11
---
# Context Gate

Ein präventives Design-Pattern, das "Context Poisoning" (Fehlinformationen oder Halluzinationen durch irrelevante Daten) im KI-Modell der Agenten verhindert.

## Funktionsweise
Anstatt das Modell (z.B. OpenRouter / Gemini) einfach unstrukturiert an eine riesige Vektor-Datenbank (Vector DB) oder ein endlos wachsendes Memory-Log anzubinden, wird das Context Gate als mechanische Filter-Vorschubschaltung eingebaut. 

- Der System-Zustand muss explizit abgefragt und verifiziert werden.
- Dem Agenten (Box 2 / The Scientist) wird ausschließlich der aktuell notwendige Kontext (Ticks, ausgewählte Meta-Events aus OpenBB) in einem eng definierten JSON/Text-Format übergeben.
- Verhindert das "Ausufern" und unberechenbare Verzweigen von Argumentationsketten während des Hot-Path Timeframes (Tick-Evaluation).


========================================
FILE: refs/concepts/evidence-gate.md
========================================
---
aliases: [Evidence Gate, Beweispflicht, Receipt]
tags: [concept, system, workflow]
related: [[13-MOC-Agenten]], [[trust-levels]]
trust: canonical
last_reviewed: 2026-04-11
---
# Evidence Gate

Die strikte Vorschrift, dass Aufgaben oder recherchiertes Wissen von Agenten nicht einfach behauptet, sondern strukturiert belegt werden müssen ("Receipt-Pflicht").

## Mechanik
- **Research:** Wenn Rick (VPS-Agent) eine Web-Recherche durchführt, ist das Ergebnis nur gültig, wenn es mit einem Quellen-Link im `10-Knowledge/` Ordner landet. Keine Quelle = Kein Fact.
- **Handoffs:** Tickets ("Done") gelten nur als erfüllt, wenn physische Veränderungen (Code-Commits, State-Updates) oder Verweise protokolliert wurden.

Dieses Pattern zwingt LLMs (Large Language Models) in eine Nachweispflicht und eliminiert blinden Glauben in autonome Output-Schleifen.


========================================
FILE: refs/concepts/trust-levels.md
========================================
---
aliases: [Trust Levels, Knowledge Trust, TTL]
tags: [concept, knowledge, system]
related: [[13-MOC-Agenten]], [[evidence-gate]]
trust: canonical
last_reviewed: 2026-04-11
---
# Trust Levels

Ein Bewertungsmaßstab ('TTL' und 'Trust') für Dateien in der Knowledge-Base und im Projekt, um den Agenten kontextuellen Vorrang zu signalisieren.

## Level-Definitionen
- **canonical:** Absolut verifiziertes Kernwissen. Die Single Source of Truth.
- **working:** Aktuelles, verwendetes Arbeitswissen, das sich jedoch ändern kann.
- **stale:** Veraltetes Wissen, dessen Lebenszeit (TTL) abgelaufen ist. Darf nicht mehr als Fakten-Basis für Architektur-Entscheidungen herangezogen werden.
- **contested:** Widersprüchliches oder durch Veto angefochtenes Wissen.

Jede neue Konzeptdatei und Dokumentation muss im YAML Frontmatter das `trust` Attribut spezifizieren, damit Agenten Signale bezüglich der Verlässlichkeit erhalten.


========================================
FILE: refs/concepts/graceful-degradation.md
========================================
---
aliases: [Graceful Degradation, SUSPEND_MODE, SUSPEND]
tags: [concept, risk, execution, architecture]
related: [[04-blackbox-mt5]], [[12-MOC-Risikomanagement]], [[heartbeat-protocol]]
trust: canonical
last_reviewed: 2026-04-11
---
# Graceful Degradation

Der Architektur-Mechanismus, der Systempanik bei einem Verbindungsabriss (z.B. VPN Disconnect, Linux-Absturz) verhindert. Beheimatet in der Exekutions-Logik (Box 3).

## Die Mechanik
Statt eines harschen "Dead Man's Switch", welcher bei Verbindungsabbruch unverzüglich alle Trades schließt und Spread-Verluste verursacht, nutzt das System einen abgestuften Rückzug:

1. **Auslöser:** Das [[heartbeat-protocol]] am MT5 schlägt fehl (kein Ping von Box 2 für X Millisekunden).
2. **Reaktion:** Zustand wechselt automatisch in den `SUSPEND`-Mode.
3. **Konsequenzen:**
   - Keine neuen Trades werden platziert.
   - Alle unberührten *Pending Orders* werden sofort storniert.
   - *Aktive Swing-Trades* bleiben offen! Ihr [[trade-lifecycle]] ist durch broker- bzw. in-memory-basierte Stop-Loss und Take-Profit Grenzen bereits technisch abgesichert.

Durch dieses Design minimiert das System unnötige Transaktionskosten während flackernder Kommunikationsleitungen.


========================================
FILE: refs/concepts/heartbeat-protocol.md
========================================
---
aliases: [Heartbeat Protocol, Heartbeat, IPC Ping]
tags: [concept, execution, infra]
related: [[11-MOC-Schnittstellen]], [[graceful-degradation]], [[04-blackbox-mt5]]
trust: canonical
last_reviewed: 2026-04-11
---
# Heartbeat Protocol

Das reduzierte, extrem schnelle IPC (Inter-Process Communication) Protokoll zwischen der Python-Bridge und dem internen MQL5 Expert Advisor im Ausführungs-Terminal (Box 3).

## Funktionsweise
Anstelle von langsamen File-I/O oder WebSockets verwendet das System das native `GlobalVariableSet()` des MetaTraders als gemeinsamen Speicher ('Shared Memory'). 
- Die Python-App aktualisiert zyklisch (z.B. jede Sekunde) einen Timestamp im Global Variable Set (der "Ping").
- Ein sehr kompakter MQL5-EA (Expert Advisor), der in einer Endlosschleife bzw. auf jedem Tick triggert, überwacht diese Variable.
- Bleibt die Differenz zur aktuellen Zeit über der definierten Toleranz (Pong verfehlt), löst der Terminal-EA lokal die [[graceful-degradation]] Maßnahmen (SUSPEND) aus.

Vorteile: Keine DLLs, extrem geringe Latenz, und beim Terminal-Crash wird der Speicher automatisch gelöscht, was ein sicheres Default-Off erzwingt.


========================================
FILE: refs/concepts/mql5-ipc-protocol.md
========================================
---
aliases: [MQL5 IPC, Heartbeat Protocol, GlobalVariableSet]
tags: [concept, architecture, networking]
related: [[04-blackbox-mt5]], [[05-schnittstellen]]
trust: canonical
last_reviewed: 2026-04-11
---
# MQL5 IPC-Protokoll (Heartbeat)

Dieses Dokument spezifiziert das proprietäre Inter-Prozess-Kommunikations-Protokoll (IPC) zwischen der Blackbox 2 (Linux/Python) und der Blackbox 3 (Windows/MT5).

## Mechanismus: MQL5 Global Variables

Aufgrund der Latenz-Anforderungen und der Vermeidung von instabilen DLLs nutzt das System den internen Speicher von MetaTrader 5 über die Funktionen `GlobalVariableSet()` und `GlobalVariableGet()`.

### Vorteile
- **Geschwindigkeit:** Zugriff erfolgt direkt im RAM des Terminals.
- **Sicherheit:** Keine externen Abhängigkeiten oder offene Ports am Terminal-Prozess.
- **Persistenz-Limit:** Variablen werden im Falle eines Terminal-Crashes gelöscht (bei `GlobalVariableSet` ohne `persist` Flag), was einen automatischen Sicherheits-SUSPEND auslöst.

## Datendefinition

Da MT5-Global-Variables ausschließlich den Datentyp `double` (64-bit float) unterstützen, wird der Kommunikations-Payload wie folgt strukturiert:

| Variable Name | Typ | Bedeutung |
|---|---|---|
| `AG_HB_[SYMBOL]` | double | Datetime-Stamp der letzten Signalübermittlung. |
| `AG_ST_[SYMBOL]` | double | Aktueller Ziel-State (`0.0` für Flat, `1.0` für Long). |
| `AG_CF_[SYMBOL]` | double | Confidence Score (`0.0` bis `1.0`). |
| `AG_RISK_SUSPEND` | double | Globaler Killswitch-Status (`1.0` = Ausführung gestoppt). |

## Flussdiagramm (Heartbeat Logic)

```mermaid
sequenceDiagram
    participant B2 as Box 2 (Python)
    participant B3 as Box 3 (Python Bridge)
    participant MT5 as MT5 Terminal (EA)

    B2->>B3: Send State Array (ZMQ/FastAPI)
    B3->>MT5: mt5.global_variable_set("AG_HB_BTCUSD", time.now())
    B3->>MT5: mt5.global_variable_set("AG_ST_BTCUSD", 1.0)
    
    Loop Every 1s (MQL5 Timer)
        MT5->>MT5: Check AG_HB_BTCUSD age
        alt Age < 30s
            MT5->>MT5: Execute/Maintain AG_ST_BTCUSD
        else Age >= 30s
            MT5->>MT5: Trigger SUSPEND (Cancel Pendings)
        end
    end
```

## Relevanz für das System
Dieser Mechanismus stellt sicher, dass die "Muskel"-Schicht (Box 3) niemals auf veralteten Informationen ("Stale Data") der "Brain"-Schicht (Box 2) exekutiert. Er formt das fundamentale Rückgrat der **Graceful Degradation**.


========================================
FILE: refs/concepts/two-repo-pattern.md
========================================
---
aliases: [Two-Repo Pattern, Repo Split, Brain vs Muscle]
tags: [concept, architecture, devops]
related: [[01-system-architektur]], [[10-MOC-Blackboxen]]
trust: canonical
last_reviewed: 2026-04-11
---
# Two-Repo Pattern

Das Architektur-Paradigma, welches die strikte Trennung von Intelligenz (Brain) und Ausführung (Muscle) in zwei isolierten Codestämmen (Repositories) erzwingt.

## Brain-Repo (Linux, Box 2 & 4)
Hier lebt die gesamte Analyse-Logik, Datenaufbereitung und das KI-Routing. Dieses Repo hat weder Kenntnisse über den Broker, noch über MT5 APIs. Es spricht in States (`0` oder `1`).

## Execution-Repo (Windows, Box 1 & 3)
Dies ist die physische Hülle um das MT5 Terminal. Es beschäftigt sich ausschließlich mit den APIs, den [[prop-firm-compliance]] Limits, Spread und Orderverarbeitung. Es ist ignorant gegenüber den Gründen für ein Signal und führt stur die übersetzten States aus.

Die Kommunikation zwischen beiden erfolgt via geschützten REST/FastAPI Endpunkten. Dieses Setup verhindert versehentliche Side-Effects (wie z.B., dass ein defektes KI-Modell versehentlich Market-Buy Loops generiert).


========================================
FILE: refs/concepts/capital-allocator.md
========================================
---
aliases: [Capital Allocator, Positionsgrößen, Sizing]
tags: [concept, risk, execution]
related: [[12-MOC-Risikomanagement]], [[04-blackbox-mt5]]
trust: canonical
last_reviewed: 2026-04-11
---
# Capital Allocator

Die Komponente in Box 3 (Execution), die für das dynamische Position-Sizing verantwortlich ist.

## Logik
Statt starrer Lot-Sizes skaliert das System die Einsätze dynamisch:
1. **Basis-Risiko:** Prozentsatz des Kapitals (z.B. 1% Risk pro Trade) basierend auf dem ATR (Average True Range) / Stop-Loss Abstand.
2. **Confidence-Modifikator:** Der empfangene Status (`1` oder `0`) von Box 2 kann perspektivisch noch mit einem Konfidenzwert versehen werden. Der Allocator entscheidet final, ob das Risiko basierend auf der Marktkonfidenz runterskaliert wird (z.B. nur 0.5% statt 1%).

Die Einhaltung der [[prop-firm-compliance]] (Max Lot pro Tag, Max Risk Limit) hat jedoch immer letzte Hebel-Gewalt und überschreibt den Allocator if needed.


========================================
FILE: refs/concepts/parquet-ferry.md
========================================
---
aliases: [Parquet Ferry, Data Sync Ferry, Speicherauszug]
tags: [concept, data, infra, schnittstellen]
related: [[11-MOC-Schnittstellen]], [[02-blackbox-data]], [[08-backtesting-lab]]
trust: canonical
last_reviewed: 2026-04-11
---
# Parquet Ferry

Ein Architektur-Pattern zur Bewältigung der asynchronen Massendatenübertragung zwischen dem Windows Server (Box 1) und dem Linux Server (Box 4).

## Die Notwendigkeit
Die MetaTrader 5 Python-Bibliothek kann ausschließlich unter Windows laufen. Wenn *The Improvement Lab* (Box 4) auf dem Linux VPS historisches Backtesting oder Reinforcement Learning durchführen soll, hat es keinen direkten API-Zugang zur MT5 Infrastruktur.

## Die Lösung
Box 1 fungiert als lokaler Scraper, der die Ticks/Bars aus dem MT5 aggregiert, komprimiert (als Parquet-Datei) und via **Parquet Ferry**-Dienst (z.B. sFTP, Rsync via VPN) regelmäßig an `10-Knowledge/` oder einen dedizierten Storage-Folder auf der Linux-Maschine schiebt.

Vorteile:
- Komprimierung verringert Datengröße massiv.
- Parquet bewahrt strukturierte Datentypen (Pandas/Polars kompatibel).
- Null Latenz-Einfluss auf die Live-Tick-Pipes.


========================================
FILE: refs/INDEX.md
========================================
# Referenz-Index — Hybrid AI-Trading System

*Dieses Verzeichnis enthält kondensiertes Hintergrundwissen, das aus den Kerndokumenten (`docs/`) ausgelagert wurde, um die Kapitel schlank und fokussiert zu halten. Kapitel referenzieren hierhin mit `→ Ref: refs/...`.*

## 📄 Papers (Akademische Grundlagen)

| Datei | Thema | Referenziert in |
|---|---|---|
| [market-folding.md](papers/market-folding.md) | Entropy Inversion Hypothesis, Von-Neumann-Entropie, Feature Matrix | Kap. 03 §1 |
| [jump-models.md](papers/jump-models.md) | Sparse Jump Model (SJM), Regime Detection | Kap. 03 §2 |

## 🏗️ Patterns (Architektur-Konzepte)

| Datei | Thema | Referenziert in |
|---|---|---|
| [context-gate.md](patterns/context-gate.md) | Mechanisches Gate für Agenten-Kontextladung | Kap. 07 §3 |
| [evidence-gate.md](patterns/evidence-gate.md) | Beweispflicht vor "Done"-Status | Kap. 07 §3 |
| [performance-profiling.md](patterns/performance-profiling.md) | **[DEPRECATED]** Nsight Systems & PyTorch Profiler | - |
| [agent-composition.md](patterns/agent-composition.md) | Modularer Agenten-Baukasten, Event-Sourcing & Orchestration | Kap. 03 |
| [prop-firm-allocator.md](patterns/prop-firm-allocator.md) | Floating Drawdown Killswitch & Capital Allocation | Kap. 04 |
| [prop-firm-compliance.md](patterns/prop-firm-compliance.md) | Prop-Firm Compliance & Gatekeeper Rules (PF-01 bis PF-06) | Kap. 04 |

## 🛠️ Tools (Evaluierungen & Steckbriefe)

| Datei | Thema | Referenziert in |
|---|---|---|
| [qlib-evaluation.md](tools/qlib-evaluation.md) | Microsoft Qlib Quantitative Platform | Kap. 02, 03 |
| [agent-orchestration.md](tools/agent-orchestration.md) | **[DEPRECATED]** CrewAI vs. AutoGen vs. LangChain | Kap. 03, 07 |
| [openbb-evaluation.md](tools/openbb-evaluation.md) | OpenBB Integration (External Data Layer) | Kap. 02 |

## 📦 Quellmaterial (Archiv)

*Original-Dokumente, Paper und PDF-Exporte (nur für Supervisor / Nachschlage-Zwecke).*
- [Source PDFs](sources/) — Das physische Archiv in `refs/sources/`.

## Konvention

- Jede Referenz-Datei beginnt mit einer `## Quelle`-Sektion (Original-Paper/Repo/Chat)
- Jede Referenz-Datei endet mit `## Relevanz für das System` (konkreter Bezug zum 3-Blackbox Design)
- Kapitel verweisen per Inline-Link: `→ Ref: [Titel](../refs/path/file.md)`


========================================
FILE: refs/patterns/agent-composition.md
========================================
# Agent Composition & Orchestration Framework

## Quelle
Extrahiert aus Konzept-Dokumenten (Kiebitz Vision & Architecture), Tech-Stack (Firebase) wurde vollständig entfernt zugunsten von OpenClaw/Hetzner.

## Relevanz für das System
Definiert, wie Agenten strukturiert, kombiniert und orchestriert werden, um starre Hardcode-Phasen zu ersetzen.

---

## 1. Das Agent Composition Model
Agenten im System ("Blackbox 2") generieren **keine direkten Trade-Signale**, sondern fungieren als **Regime-Klassifizierer**. Ihr Output muss stets in einem klar definierten Contract-Format (z. B. strukturiertes JSON: `[Decision, Confidence, Reasoning]`) vorliegen.

Agenten sind als wiederverwendbare, modulare Bausteine (global definiert) konzipiert. Anstatt Agenten fest in den Code einer Strategie zu integrieren ("hardcoded"), werden sie pro Strategie dynamisch über Konfigurationen / State-Metadaten zusammengestellt ("Composition").

## 2. Flexible Phasen (Dynamic Phases)
Das bisherige starre "Scout → Sniper → Bodyguard" Muster wird durch frei definierbare Phasen abgelöst. Eine Strategie definiert ihre eigenen Phasen, je nach Asset und Timeframe (z.B. Discovery → Validation → Monitoring → Cooldown).

In jeder Phase:
- Laufen spezifische Agenten (Parallel oder Sequenziell)
- Mit phasen-spezifischem "Weighting" (Gewichtung) und "Prompt Overrides"

### Threshold-Logik & Hysterese
Übergänge zwischen Phasen (Transitions) erfolgen nicht sofort. Um "Signal-Rauschen" zu vermeiden, greift ein mechanisches System:
- **Lookback Samples:** Eine Threshold muss über $N$ aufeinanderfolgende Läufe (Cycles) erfüllt sein, nicht nur ein einzelnes Mal.
- **Hysterese:** Eintritts- und Austritts-Thresholds unterscheiden sich (z. B. Entry ab 80% Confidence, Exit erst, wenn sie wieder auf unter 60% fällt), um "Ping-Pong-Effekte" an der Kante zu vermeiden.

## 3. Orchestration Levels (Die Fusion)
Wenn eine Phase mehrere Agenten-Outputs erhält, entscheidet die Orchestrierung, wie diese Daten fusioniert werden. Es gibt drei Evolutionsstufen:

1. **Level 1 (Mechanic):** Einfache Mathematik (z.B. Weighted Average). Deterministisch, schnell, aber kann Divergenzen nicht tiefer interpretieren.
2. **Level 2 (Logic):** Programmlogik mit IF/THEN-Regeln (z.B. Diskrepanz-Checker, Macro-Veto-Regeln). Intelligent, fängt Logik-Fehler und fehlenden Consensus ab.
3. **Level 3 (Semantic):** Ein eigenständiger Orchestrator-Agent (LLM) erhält die Outputs der Worker-Agenten. Das LLM sucht nach Mustern in Divergenzen (z.B. "Macro ist Long, Sentiment noch neutral → Dies ist eine Accumulation-Phase, wir passen das Confidence-Level entsprechend an").

## 4. Event-Sourced Persistence (Audit Trail)
Jede Sub-Aktion — ob Worker-Agent Output oder Orchestrations-Fusion — wird als unveränderliches Event (Log) persistent gemacht. Dieser 100%-ige Audit-Trail erlaubt es, Asynchrones Debugging durchzuführen und alte Strategien mit historischen Snapshots wieder abzuspielen (Replay-Funktion). In der OpenClaw Architektur wird dies über Graphen, Filesystem-Dumps und Git-Commits realisiert.


========================================
FILE: refs/patterns/prop-firm-compliance.md
========================================
# Prop-Firm Compliance Model

## Quelle
- OPEN_TASKS.md (Sprint 2, PF-01 bis PF-06)
- DECISIONS.md (E-08)

## Details
Dieses Modell definiert das generische, konfigurierbare Regelwerk zur Einhaltung strikter Prop-Firm Anforderungen (z.B. FTMO, Apex, TFT).

- **PF-01 (Daily Loss):** Berechnung gegen Midnight-Balance. Zwingend Timezone-aware (z.B. CE(S)T vs. Broker-Server-Time).
- **PF-02 (Drawdown):** Umschaltbar zwischen Static Drawdown (z.B. FTMO) und Trailing Drawdown (z.B. Apex).
- **PF-03 (Consistency):** Implementierung der Best-Day-Limit Regel (z.B. kein Tag darf >30% des Gesamtprofits ausmachen).
- **PF-04 (Trading Days):** Ein globaler Counter zur Durchsetzung von Minimum Trading Days Challenges.
- **PF-05 (News-Blackout):** Config-definiertes Zeitfenster vor/nach High-Impact News, in welchem Trading aussetzt (SUSPEND Pending Orders). News-Bezug über OpenBB.
- **PF-06 (Weekend-Holding):** Flag-basierte Regelung zum harten Liquidieren oder Halten übers Wochenende (Friday EOD Auto-Close).

## Relevanz für das System
Wird als Compliance-Schicht im Risk-Diktator von Box 3 (MT5 Execution Bridge) eingebettet und via JSON/YAML Config gesteuert. Garantiert, dass Accounts nicht aufgrund formaler Regelverstöße von Fremdkapitalgebern gebannt werden.


========================================
FILE: refs/patterns/prop-firm-allocator.md
========================================
# Prop-Firm Allocator & Risk-Diktator

## Quelle
Extrahiert aus Chat-Transkripten ("Neuer buildup03"), Fokus auf extreme Risikokontrolle für Prop-Firm-Trading (FTMO, Apex, etc.).

## Relevanz für das System
Definiert die logische Brücke und Kapitalverteilung zwischen den Agenten (Box 2) und der finalen Ausführung (Box 3/MT5), um "Drawdown-Rules" garantiert nicht zu reißen.

---

## 1. Trade-Bewerbungen & Confidence Score
Agenten aus Box 2 (The Scientist) haben **keine direkte Ordergewaltübernahme**. Sobald ein Agent einen Trade aufbaut (Adversarial Debate, Phasenerfüllung), generiert er eine *Trade-Bewerbung* (z. B. via JSON/API). 
Eine solche Bewerbung enthält zwingend einen intern berechneten **Confidence Score** (z. B. 1–100), der sich primär aus mathematischen Metriken (niedrige Entropie, R:R) und sekundär aus der analytischen Bewertung zusammensetzt.

## 2. Der "Capital Allocator" (Exposure Management)
Nicht jede Trade-Bewerbung wird ausgeführt. Ein zentrales System in der MT5 Bridge (Box 3) validiert die Bewerbungen:
- **Correlation Checks:** Korrelierende Trade-Ideen (z. B. Short EURUSD und Short GBPUSD) werden erkannt. Um Max-Exposure-Limits nicht zu überschreiten, wird das Signal mit dem schwächeren Confidence Score blockiert.
- **Dynamisches Sizing:** Das Kapital wird proportional zur Konfidenz verteilt (z.B. mittels Kelly-Kriterium).

## 3. Der "Floating Drawdown" Killswitch (Risk-Diktator)
Prop-Firms messen Gewinn und Verlust oftmals "Floating" (inklusive nicht-realisierter Trades). 
Da Agenten relativ asynchron arbeiten und ihre eigenen Phasen verwalten, muss auf der untersten Execution-Ebene (direkt in MQL5 oder in einem Tick-für-Tick laufenden Python-Script) ein **harter Diktator-Loop** installiert sein:
- **Tick-Überwachung:** Das Floating-Equity wird kontinuierlich überwacht.
- **Guillotine-Drop:** Bricht das Floating-Equity das Tages- oder Max-Limit (z. B. -4.5% bei einem 5% Limit als Puffer), feuert das System kompromisslos `CloseAllPositions()` und blockiert alle neuen Orders für den Rest des Tages — völlig unabhängig vom Willen oder den laufenden Analysen der Agenten.
- **News-Gaps & Over-Weekend:** Der Diktator schließt Trades automatisch Minuten vor "High-Impact" Makro-Events (NFP, CPI), sofern Prop-Firm-Regeln das Halten von Trades zu diesen Zeiten verbieten.