Initial public upload from Projekte/megaHarness

Browse files

Files changed (6) hide show

.codex/config.toml +31 -0
ARCHITECTURE.md +335 -0
Artefakt_USP.md +154 -0
BRIEFING_LUIS.md +260 -0
Höhlengleichnis.md +221 -0
idea +23 -0

.codex/config.toml ADDED Viewed

	@@ -0,0 +1,31 @@

+# Coding MCPs: project-local registration (2026-09-07).
+[mcp_servers.serena]
+command = "/home/smlflg/.local/share/coding-mcp/serena/.venv/bin/serena"
+args = ["start-mcp-server", "--context=codex", "--project", "/home/smlflg/Projekte/megaHarness", "--enable-web-dashboard", "false", "--open-web-dashboard", "false", "--enable-gui-log-window", "false"]
+cwd = "/home/smlflg/Projekte/megaHarness"
+enabled = true
+startup_timeout_sec = 120
+tool_timeout_sec = 180
+[mcp_servers.serena.env]
+"SERENA_HOME" = "/home/smlflg/.local/share/coding-mcp/serena/state"
+[mcp_servers.gitnexus]
+command = "/home/smlflg/.nvm/versions/node/v24.13.0/bin/node"
+args = ["/home/smlflg/.local/share/coding-mcp/gitnexus/node_modules/gitnexus/dist/cli/index.js", "mcp"]
+cwd = "/home/smlflg/Projekte/megaHarness"
+enabled = true
+startup_timeout_sec = 120
+tool_timeout_sec = 180
+[mcp_servers.gitnexus.env]
+"GITNEXUS_HOME" = "/home/smlflg/.local/share/coding-mcp/gitnexus/runtime"
+[mcp_servers.context7]
+command = "/home/smlflg/.nvm/versions/node/v24.13.0/bin/node"
+args = ["/home/smlflg/.local/share/coding-mcp/context7/node_modules/@upstash/context7-mcp/dist/index.js"]
+cwd = "/home/smlflg/Projekte/megaHarness"
+enabled = true
+startup_timeout_sec = 120
+tool_timeout_sec = 180

ARCHITECTURE.md ADDED Viewed

	@@ -0,0 +1,335 @@

+# megaHarness — Architektur-Plan
+**Status:** Architektur-Lock für 5-Tage-MVP (2026-04-23 → 2026-04-28)
+**Autor:** Samuel (Vision) + Claude/Opus 4.7 (Architektur-Synthese)
+**Basis-Dokumente:** `idea` (Vision), `HarnessEcosystem/docs/gpt5-4-shift-report.md` (empirische Rechtfertigung)
+---
+## 0. North Star
+megaHarness ist Samuels persönliches **Meta-Harness**: eine Schicht **über** existierenden Agent-Harnesses (Claude Code, OpenClaude, Codex, OpenHands, Cursor, …), die sie als austauschbare Execution-Engines orchestriert. Der Wert liegt nicht in einem neuen Agent, sondern in **Komposition**: gleiche Task läuft auf anderem Harness + anderem Modell, ohne Re-Konfiguration.
+Die acht Prinzipien aus `idea` sind nicht verhandelbar. Alles andere ist Implementierungsdetail.
+---
+## 1. Architektur in Schichten
+```
+┌─────────────────────────────────────────────────────────────┐
+│  L4 — UI-Layer                                              │
+│  Dashboard · Track-Viewer · MD-DB-Browser · Eval-Viewer     │
+├─────────────────────────────────────────────────────────────┤
+│  L3 — Kernel (megaHarness-Core)                             │
+│  Task-Router · Parallel-Orchestrator · Sidecar-Engine       │
+│  Eval-Engine · MD-Resolver · Harness-Swap                   │
+├─────────────────────────────────────────────────────────────┤
+│  L2 — MD-Datenbank (Source of Truth)                        │
+│  projects/ · instructions/ · skills/ · tracks/ · evals/     │
+├─────────────────────────────────────────────────────────────┤
+│  L1 — Harness-Adapter-Layer                                 │
+│  Claude-Code · OpenClaude · Codex · OpenHands · Hermes      │
+├─────────────────────────────────────────────────────────────┤
+│  L0 — Provider-Layer (extern, nicht megaHarness)            │
+│  Anthropic · OpenAI · Google · MiniMax · lokale Modelle     │
+└─────────────────────────────────────────────────────────────┘
+```
+**Kern-Invariante:** L3 kennt L1 nur durch Adapter-Interface, L2 nur durch Resolver-Interface, L0 nie direkt. So wird Modell-Swap und Harness-Swap zur Config-Änderung, nicht zum Refactor.
+---
+## 2. Kern-Komponenten
+### 2.1 MD-Datenbank (L2)
+**Rolle:** Einzige Quelle der Wahrheit für alle adaptiven Verträge.
+**Entitäten:**
+- `projects/*.md` — Projekt-Briefs, Done-Kriterien, Scope-Locks
+- `instructions/*.md` — CLAUDE.md-Äquivalente, per Harness + Modell versioniert
+- `skills/*.md` — wiederverwendbare Skill-Definitionen
+- `sidecar/*.md` — Regelwerke (ADHS-Hooks, Scope-Guards, Commit-Gates)
+- `tracks/*.md` — Live-Track-Definitionen (Task, Harness, Modell, Budget, Done)
+- `evals/*.jsonl` — Eval-Läufe, append-only
+**Adaptivität:** jedes MD-File hat Frontmatter mit `applies_when:`-Clauses (Harness-ID, Modell-ID, Projekt-ID, Session-Phase). Der **MD-Resolver** (L3) wählt zur Laufzeit das relevante Subset. Nicht-adaptive .md-Files sind Legacy-Schicht.
+**Warum Markdown + Frontmatter, nicht SQLite/Postgres:**
+- Menschenlesbar, Git-diffbar
+- LLM-nativ (kein Query-Layer nötig für Konsumption)
+- Versionierbar mit dem Repo
+- Zero Infrastruktur, keine Migrations-Drama
+**Trade-off:** keine komplexen Joins, keine Transaktionen. Für diesen Use-Case egal.
+### 2.2 Harness-Adapter-Protokoll (L1↔L3-Vertrag)
+Jeder Harness-Adapter implementiert ein minimales Interface:
+| Method | Zweck |
+|---|---|
+| `spawn(track_md)` | Starte Session aus Track-MD |
+| `status(session_id)` | Lebens-Check, Tokens, Turn-Count |
+| `interrupt(session_id)` | Hartes Stop |
+| `collect(session_id)` | Transcript + Metriken holen |
+| `capabilities()` | Was kann der Harness (Tools, Background, Worktrees) |
+**Completion-Contract:** jeder Spawn bekommt aus der MD-DB eine explizite `done_when:`-Clause injiziert. Harnesses ohne native Contract-Unterstützung (GPT-5.4 im Claude-Code-Harness: siehe Shift-Report) kriegen einen Wrapper-Prompt, der die Clause als System-Message voranstellt.
+**Der Harness-Swap-Moment:** Swap = Track-MD unverändert lassen, nur `harness_id:` im Frontmatter ändern. Re-Spawn. Der Kernel liefert dieselben Inputs.
+### 2.3 Task-Router (L3)
+**Input:** Task-Request (aus UI, CLI, Cron oder Eval-Trigger)
+**Output:** Track-MD + Harness-Auswahl
+**Routing-Logik:**
+1. Matching: welche Harnesses + Modelle sind kompatibel mit Task-Typ
+2. Policy: Default-Modell pro Task-Typ aus `instructions/router-policy.md`
+3. Override: explizite User-Wahl schlägt Policy
+4. Fallback: wenn Primär-Harness unavailable, Sekundär aus Policy
+**Empirisch kalibriert:** Shift-Report zeigt, dass GPT-5.4 im Claude-Code-Harness 2–8M Input-Tokens pro Session verbrennt. Router-Policy verhindert diese Kombination by default, es sei denn explizit als Experiment deklariert.
+### 2.4 Parallel-Orchestrator (L3)
+**Rolle:** N Tracks gleichzeitig, keine Race Conditions im Dateisystem, Checkpoint-fähig.
+**Mechanismen:**
+- Git-Worktree pro Track (Isolation auf Repo-Ebene)
+- tmux/supervisord für Prozess-Leben (keine eigene Prozess-Verwaltung bauen)
+- MD-Queue für Track-Slots (`tracks/active/`, `tracks/queued/`, `tracks/done/`, `tracks/failed/`)
+- Heartbeat-File pro Track für Status-Polling
+**Kapazität:** 3–5 Tracks parallel. Mehr ist Token-Verbrennung ohne Kognitions-Nutzen (Samuel kann nicht 8 parallel reviewen).
+### 2.5 Sidecar-Engine (L3)
+**Rolle:** Samuel-spezifische Kalibrierung — ADHS-Guards, Scope-Warnungen, Commit-Gates.
+**Baut auf:** existierendem `Sidecar-ng`-Projekt (bereits produktiv, liefert die Hook-Payloads die dieser Dialog durchgehend zeigt).
+**Integration:** Sidecar-Engine ist **kein neuer Code**, sondern ein Adapter der existierende Sidecar-NG-Events an die MD-DB und den Orchestrator sendet. Regeln kommen aus `sidecar/*.md`.
+**Kernfunktion für megaHarness:** Cross-Track-Scope-Guard. Wenn Track A in `home/` arbeitet und Track B plötzlich auch: Flag.
+### 2.6 Eval-Engine (L3)
+**Rolle:** jeder Track misst sich selbst.
+**Baut auf:** existierendem `HarnessEcosystem/sidebyside` (liefert bereits snapshot-basierte Vergleiche, siehe Shift-Report).
+**Metriken pro Track:**
+- Token-Effizienz (in/out, pro Turn)
+- Tool-Burst-Dichte (Tool-Calls pro Turn)
+- Contract-Adhärenz (Done-Clause erreicht?)
+- Termination-Typ (clean / limit / interrupt / crash)
+- Outcome-Label (manuell oder durch Review-Track)
+**Feedback-Loop:** Eval-Ergebnisse schreiben zurück nach `evals/*.jsonl`. Router-Policy konsumiert aggregierte Evals → empirische Modell-Auswahl.
+### 2.7 UI-Layer (L4)
+**Kern-Views:**
+1. Track-Dashboard (welche Tracks laufen, Status, ETA, Tokens)
+2. MD-DB-Browser (Navigation + Diff)
+3. Eval-Viewer (Baut auf `frontier-llm-harness`-Ästhetik auf)
+4. Spawn-Composer (Track-MD erstellen → Router → Adapter)
+**Technologie-Entscheidung:** statische SPA + lokaler HTTP-Server, liest direkt aus `tracks/` + `evals/`. Kein Backend. Grund: `sidebyside` + `frontier-llm-harness` haben das Pattern bereits bewiesen, keine neue Infrastruktur.
+**Live-Updates:** Polling (nicht WebSocket). KISS.
+---
+## 3. Bausteine-Map (Was existiert, was fehlt)
+| Schicht / Komponente | Existierend (✓) / Fehlt (✗) | Quelle |
+|---|---|---|
+| L2 MD-DB Schema | ✗ | — |
+| L2 MD-Resolver | ✗ | — |
+| L2 Adaptive Regeln existierend | (✓) teilweise | PromptGarage, Skills |
+| L1 Claude Code Adapter | (✓) implizit (JSONL-Logs) | `~/.claude/projects/` |
+| L1 Codex/GPT-5.4 Adapter | (✓) implizit | `extract_codex.py` |
+| L1 OpenClaude Adapter | ✗ | Fork existiert, kein Adapter |
+| L1 Hermes Adapter | (✓) teilweise | `extract_hermes.py` |
+| L1 OpenHands Adapter | ✗ | — |
+| L3 Harness-Swap Mechanik | (in Arbeit) | `derWolfimSchafspelz/openclaude` |
+| L3 Task-Router | ✗ | — |
+| L3 Parallel-Orchestrator | ✗ | — |
+| L3 Sidecar-Engine | ✓ | `Sidecar-ng` |
+| L3 Eval-Engine | ✓ | `HarnessEcosystem/sidebyside` |
+| L4 Dashboard | (✓) Aesthetik + Pattern | `SidecarDashboard`, `KomandoZentral`, `frontier-llm-harness` |
+**Schlüssel-Erkenntnis:** L2 (MD-DB) ist der kritische neue Baustein. L3-Kernel ist dünne Integration existierender Teile. L1-Adapter sind jeweils 1–2 Tage Arbeit, wir brauchen in 5 Tagen nur 2–3.
+---
+## 4. Harness-Swap — der aktuelle Build
+**Definition:** Harness-Swap ist der Mechanismus, der denselben Task auf einem anderen Harness re-exekutiert, ohne Task-Definition zu ändern.
+**Architekturrolle:** Harness-Swap ist **nicht** ein L1-Adapter. Es ist ein L3-Kernel-Feature, das L1-Adapter koordiniert.
+**Interface:**
+```
+swap(track_id, from_harness, to_harness) →
+  1. collect(from_harness.session) → transcript + state
+  2. translate(state, to_harness.capabilities) → new_state
+  3. track_md.harness_id = to_harness
+  4. spawn(to_harness, track_md, continuation=new_state)
+```
+**State-Translation-Regeln** sind in `instructions/harness-translation-*.md` abgelegt (eine Datei pro Harness-Paar). Diese Regeln sind **adaptiv** — sie werden basierend auf Eval-Daten (was hat funktioniert beim letzten Swap?) fortgeschrieben.
+**MVP-Umfang:** Claude Code ↔ OpenClaude Swap. Alles andere Post-MVP.
+---
+## 5. Datenfluss — der eine zentrale Loop
+```
+User-Intent
+   ↓
+MD-Resolver liest projects/ + instructions/
+   ↓
+Task-Router wählt Harness + Modell (Policy + Eval-History)
+   ↓
+Track-MD geschrieben in tracks/active/
+   ↓
+Parallel-Orchestrator spawnt via L1-Adapter
+   ↓
+Harness läuft (mit Completion-Contract injiziert)
+   ↓
+Sidecar-Engine beobachtet, flagt bei Regel-Verletzung
+   ↓
+Abschluss: Eval-Engine schreibt nach evals/*.jsonl
+   ↓
+Track-MD nach tracks/done/ verschoben
+   ↓
+UI reflektiert neuen Zustand
+   ↓
+Router-Policy lernt aus evals/ für nächsten Spawn
+```
+Dieser Loop ist das System. Alles andere ist Verzierung.
+---
+## 6. 5-Tage-Meilensteine (architektonisch)
+Jeder Meilenstein hat **eine binäre Done-Frage**, nicht eine Feature-Liste.
+### Tag 1 — Fundament (2026-04-23)
+**Done-Frage:** Existiert `md-db/` mit Schema-definierten Frontmatter-Keys, und kann der MD-Resolver aus einer `tracks/example.md` eine zusammengesetzte Instruction produzieren?
+- MD-DB-Schema finalisiert (Frontmatter-Felder, Ordner-Layout)
+- MD-Resolver als dünner Layer
+- Ein Beispiel-Track in der DB abgelegt
+- **Non-Goal Tag 1:** kein Spawn, keine UI, kein Router
+### Tag 2 — Execution (2026-04-24)
+**Done-Frage:** Kann ein Track-MD via Adapter einen Claude-Code-Subprozess spawnen, laufen lassen, und das Transcript ingesten?
+- L1-Adapter: Claude Code (via CLI-Spawn)
+- L1-Adapter: OpenClaude (via Fork-CLI)
+- L3 Spawn-Funktion im Kernel
+- **Non-Goal:** kein Parallelismus, kein Swap, kein Router
+### Tag 3 — Parallelität + Router (2026-04-25)
+**Done-Frage:** Laufen 3 Tracks gleichzeitig in Worktrees, ohne dass sie sich im Dateisystem zerstören, und wählt der Router automatisch Harness+Modell aus der Policy?
+- Parallel-Orchestrator mit Worktree-Isolation
+- Task-Router mit statischer Policy (Eval-Feedback Post-MVP)
+- Heartbeat + Status-Polling
+- **Non-Goal:** UI, Swap
+### Tag 4 — Swap + Eval-Integration (2026-04-26)
+**Done-Frage:** Kann ein laufender Track von Claude Code nach OpenClaude geswapt werden, und schreibt der Eval-Hook nach Abschluss saubere Metriken in `evals/`?
+- Harness-Swap (MVP: Claude Code ↔ OpenClaude)
+- Eval-Engine-Hook an Adapter-Collection angebunden
+- `sidebyside`-Scripts als Eval-Konsumenten integriert
+- **Non-Goal:** UI, Router-Lernen aus Evals
+### Tag 5 — UI + E2E (2026-04-27, Puffer 2026-04-28)
+**Done-Frage:** Sieht Samuel im Browser ein Track-Dashboard, kann er einen neuen Track spawnen und das Ergebnis inklusive Evals einsehen?
+- Statische SPA mit Track-Dashboard + MD-DB-Browser + Eval-Viewer
+- Spawn-Composer (einfache Form, kein Advanced)
+- Ein echter E2E-Run: Spawn → Parallel → Swap → Eval → UI
+- Puffer-Tag (28.04) für Polish und unerwartete Blocker
+---
+## 7. Risiken & Mitigationen
+| Risiko | Wahrscheinlichkeit | Impact | Mitigation |
+|---|---|---|---|
+| Scope-Creep über MVP hinaus | Hoch | Hoch | Jeder Tag hat eine binäre Done-Frage, nicht Feature-Liste. Post-MVP-Liste explizit in §9. |
+| GPT-5.4 im Claude-Code-Harness verbrennt Token-Budget | Hoch | Mittel | Router-Policy verhindert Kombination by default. Nur als explizites Experiment. Empirisch belegt durch Shift-Report. |
+| UI-Tag-5 wird zum Zeitfresser | Hoch | Hoch | Statische SPA, keine neue Infrastruktur. `frontier-llm-harness` als Muster. Kein Framework-Neuwahl. |
+| MD-DB-Schema wird zu komplex | Mittel | Hoch | Schema ≤ 10 Frontmatter-Keys im MVP. Erweiterung nur mit belegtem Use-Case. |
+| Parallelismus zerstört Dateisystem | Mittel | Hoch | Git-Worktree pro Track. Kein Shared-State außerhalb `md-db/`. |
+| Bestehende Projekte nicht sauber integrierbar | Mittel | Mittel | MVP nutzt nur `Sidecar-ng` und `sidebyside` als Integration. Rest Post-MVP. |
+| 5-Tage-Schätzung zu optimistisch | Hoch | Hoch | Tag 5 hat Puffer 28.04. MVP-Scope bewusst klein. Wenn Tag 3 nicht done: Swap+Eval gehen Post-MVP. |
+| ADHS-Fokus-Kollaps | Mittel | Hoch | Sidecar-NG aktiv, tägliche Done-Frage als Anker, keine Parallelarbeit an mehr als EINEM Kernel-Teil gleichzeitig. |
+---
+## 8. Done-Kriterien (Tag 5)
+Der MVP ist fertig, wenn **alle** folgenden Bedingungen wahr sind:
+1. `md-db/` existiert mit den definierten Ordnern
+2. Mindestens 2 Harness-Adapter funktionieren (Claude Code, OpenClaude)
+3. 3 Tracks sind parallel gelaufen ohne gegenseitige Blockade
+4. Ein Harness-Swap wurde erfolgreich durchgeführt (Claude Code → OpenClaude)
+5. Mindestens ein Eval-Lauf ist in `evals/` persistent
+6. UI zeigt aktuelle Tracks + Evals korrekt
+7. Ein Ende-zu-Ende-Flow (Spawn → Parallel → Swap → Eval → UI) lief ohne manuelle Eingriffe durch
+Wenn 5 von 7 erreicht: **MVP accepted**. Wenn weniger: MVP-Scope reevaluieren, nicht verlängern.
+---
+## 9. Non-Goals (Post-MVP, bewusst ausgeschlossen)
+- Cursor-Adapter
+- OpenHands-Adapter
+- Hermes-Adapter (Collect-Script reicht)
+- Router-Policy-Lernen aus Eval-History
+- Advanced Spawn-Composer in UI (Form-only reicht)
+- Fremde Repos als Tracks (nur eigene im MVP)
+- Cloud-Deployment
+- Multi-User
+- Auth
+- Mobile-UI
+- Persistente DB (MD-Files reichen)
+- Config-Hot-Reload
+- Skill-Marketplace
+- Eval-Auto-Labeling durch Review-Track
+Jeder dieser Punkte ist ein legitimes Feature — aber nicht in 5 Tagen.
+---
+## 10. Glossar
+- **Harness**: Ausführungsumgebung für einen Agent (Claude Code, Codex, OpenHands …)
+- **Modell**: LLM-Endpoint (Opus, GPT-5.4, …)
+- **Track**: Eine konkrete Task-Instanz mit Harness + Modell + Projekt-Kontext
+- **Spawn**: Track in einem Harness starten
+- **Swap**: Track mitten im Leben auf anderen Harness übertragen
+- **MD-DB**: Markdown-basierte Datenbank (L2)
+- **Completion-Contract**: Explizites `done_when:` in Track-MD
+- **Adaptiv**: .md-File gilt nur wenn Frontmatter-`applies_when:` zur Laufzeit matcht
+---
+## 11. Offene Architektur-Fragen (vor Tag 1 zu entscheiden)
+1. **Kernel-Sprache:** Python (ökosystemnah zu Claude Code + Codex) vs TypeScript (näher an UI). **Empfehlung: Python**, Grund: alle existierenden Scripts (`extract_*.py`, `build_snapshot.py`) sind Python. Kein Sprach-Bruch.
+2. **Prozess-Modell:** tmux vs supervisord vs systemd-user. **Empfehlung: tmux**, Grund: Samuel nutzt es bereits, minimal neues Setup.
+3. **UI-Framework:** vanilla JS (wie `sidebyside`) vs Preact vs Svelte. **Empfehlung: vanilla**, Grund: `sidebyside` + `frontier-llm-harness` sind vanilla und lesbar.
+4. **MD-DB-Location:** `~/.megaharness/md-db/` vs im Repo. **Empfehlung: im Repo** (`megaHarness/md-db/`), Grund: Git-versioniert, portabel, diffbar.
+---
+**Dieser Plan ist ein Vertrag zwischen Samuel und dem 5-Tage-Ich. Jede Abweichung muss als ADR (Architecture Decision Record) in `docs/adr/` dokumentiert werden — oder explizit abgelehnt und hier gestrichen. Keine stille Scope-Drift.**

Artefakt_USP.md ADDED Viewed

	@@ -0,0 +1,154 @@

+# Artefakt-USP-Doktrin
+**Zweck:** Leitlinie für die Entscheidung „eigen bauen vs. fremdes Repo integrieren" über die gesamte Lebenszeit von megaHarness.
+**Gilt neben:** `ARCHITECTURE.md`
+**Adressat:** Samuel (und zukünftige Claude/Opus-Sessions, die Architektur-Entscheidungen treffen)
+---
+## 0. Kernsatz
+> **Samuels USP ist nicht Code. Der USP ist die Sammlung der Artefakte: MD-Datenbank-Inhalte, Sidecar-Regeln, Router-Policies, Track-Done-Definitionen, Eval-Interpretationen.**
+> **Code ist die dünne Schicht, die diese Artefakte zum Leben bringt. Nicht umgekehrt.**
+Jede Entscheidung „selbst bauen vs. fremd integrieren" wird gegen diesen Satz gehalten. Wenn der Beitrag eines Code-Stücks austauschbar ist durch ein fremdes Repo, das dieselbe Funktion erfüllt: integrieren. Wenn der Beitrag Samuels spezifische Arbeitsweise, Denkmuster oder Qualitätsurteile kodiert: selbst bauen, selbst pflegen.
+---
+## 1. Warum das die richtige Trennung ist
+Samuels knappste Ressource ist **nicht** Code-Lines und **nicht** Tokens. Sie ist **Fokus-Zeit**. Jede Stunde, die in selbstgebaute Commodity-Layer fließt (HTTP-Server, Markdown-Parser, Prozess-Orchestrierung, Model-Routing), ist eine Stunde, die nicht in den USP-Artefakten steckt — dort wo der tatsächliche Wert erzeugt wird.
+Die Gegenrichtung ist gleichermaßen falsch: wer fremde Repos verwendet, um seinen USP zu definieren, baut fremde Ideologie in sein System ein und wird dauerhaft gegen Upstream-Entscheidungen kämpfen.
+**Die Doktrin ist also:** fremde Substanz für fremdes Problem (Plumbing), eigene Substanz für eigenes Problem (Arbeitsweise).
+---
+## 2. Ratio nach Schicht (Referenz-Tabelle)
+| Schicht | Eigen / Fremd | Begründung |
+|---|---|---|
+| **MD-DB-Schema + Inhalte** (L2) | **100% eigen** | Das IST die Personalisierung. Unersetzlich. |
+| **Sidecar-Engine** (L3) | **100% eigen**, existiert als `Sidecar-ng` | ADHS-Kalibrierung und Regelwerk sind unique zu Samuel |
+| **Router-Policy** (L3) | **100% eigen** | Policy ist empirisches Lernen, nicht Standard |
+| **Track-MD-Format / Done-Sprache** (L2) | **100% eigen** | Samuels Definition von „fertig" |
+| **Eval-Interpretationen** (L3) | **100% eigen** | Baut auf `sidebyside`, Wertung bleibt Samuels |
+| **UI-Komposition** (L4) | ~80% eigen, ~20% Komponenten | Scan-Ästhetik ist persönlich, Buttons sind commodity |
+| **Kernel-Glue** (L3: Spawn, Collect, Swap) | ~60% eigen, ~40% Libraries | Dünn halten; Pydantic / subprocess / GitPython nutzen |
+| **Parallel-Orchestrator** (L3) | ~30% eigen, ~70% tmux/supervisord | Unix löst Prozess-Management seit Jahrzehnten |
+| **Harness-Adapter** (L1) | ~90% fremd (via CLI-Spawn), ~10% Mapping-Code | Wrapper, nie Fork |
+| **Model-Routing** (L0-nah) | ~5% eigen, ~95% LiteLLM / aisuite | Gelöstes Problem, nicht nachbauen |
+| **Basis-Rendering / MD-Parser** (L4/L2-Infra) | 0% eigen | `markdown-it`, `python-frontmatter` — fertig |
+---
+## 3. Faustzahlen
+- **Code-Volumen:** ~25% eigen, ~75% Libraries/Adapter-Shims
+- **Architektur-Entscheidungen:** ~80% eigen, ~20% übernommen
+- **Artefakt-Inhalte** (MDs, Regeln, Policies): **100% eigen**
+- **Token-Investment-Verteilung** (über 5-Tage-MVP und darüber hinaus):
+  - ~60% in Artefakt-Erzeugung (MDs schreiben, Regeln kalibrieren, Evals lesen und umsetzen)
+  - ~30% in Kernel-Glue-Code
+  - ~10% in Integration fremder Bibliotheken und Adapter
+Wenn das Verhältnis kippt (mehr Glue-Code als Artefakte), ist das ein Alarmsignal — nicht ein Feature-Fortschritt.
+---
+## 4. Anti-Patterns (Muster die Samuel dokumentiert bisher daran hindern, Projekte abzuschließen)
+### A1 — Fork-als-Maintenance
+Fremdes Repo forken und selbst pflegen. Upstream bewegt sich, der Fork bleibt stehen, Merge-Schulden wachsen exponentiell. **Beispiel:** `derWolfimSchafspelz/openclaude`.
+**Gegenmittel:** Adapter statt Fork. Fork nur wenn Adapter nachweislich nicht möglich. Wenn Fork, dann Upstream-Tracking dokumentieren.
+### A2 — Eigenbau-aus-Prinzip
+Alles selbst bauen, weil „fremdes Tool nicht gut genug" oder „passt nicht zu meiner Arbeitsweise".
+**Gegenmittel:** Unterscheide „passt nicht zu meiner Arbeitsweise" (→ Adapter + eigene Konfiguration reicht) von „löst das falsche Problem" (→ selbst bauen). In 90% der Fälle ist es Ersteres.
+### A3 — Framework-Shopping
+Diese Woche LangGraph, nächste Woche Goose, übernächste OpenHands. Jede Woche Setup, nie Nutzung.
+**Gegenmittel:** Pro Schicht genau **ein** Execution-Target im MVP. Wechsel erst nach dokumentiertem Fail-Criterium.
+### A4 — Perfektionismus auf Glue
+Viele Stunden in Refactoring von Code, der nur existiert, um Artefakte zu laden und an Harnesses zu schicken.
+**Gegenmittel:** Glue darf hässlich sein. Artefakte müssen gut sein. Review-Zeit entsprechend verteilen.
+### A5 — Ideologie-Import
+Fremdes Repo so tief integrieren, dass sein Abstraktions-Modell (z.B. „Agent", „Chain", „Flow") das eigene Modell überschreibt.
+**Gegenmittel:** Integration über dünne Adapter, die fremde Terminologie an megaHarness-Terminologie übersetzen. MD-DB kennt nur megaHarness-Begriffe.
+### A6 — Verbose Migration statt Import
+Existierende eigene Projekte (Sidecar-ng, sidebyside, PromptGarage) Stück für Stück in megaHarness kopieren.
+**Gegenmittel:** **Importieren statt portieren.** Die Projekte bleiben wo sie sind. megaHarness ruft sie auf. Wenn eine echte API-Harmonisierung nötig ist: dünner Wrapper, kein Umzug.
+---
+## 5. Konkrete Anwendung für megaHarness (MVP und Post-MVP)
+### 5.1 Eigene Projekte → importieren, nicht portieren
+| Projekt | Rolle in megaHarness | Art der Integration |
+|---|---|---|
+| `Sidecar-ng` | Sidecar-Engine (L3) | Import als Library oder Subprocess-Call |
+| `HarnessEcosystem/sidebyside` | Eval-Engine (L3) | Datenaustausch über `evals/*.jsonl` |
+| `frontier-llm-harness` | UI-Pattern für L4 | Muster übernehmen, nicht Code kopieren |
+| `SidecarDashboard` | UI-Komponenten-Quelle | Selektive Wiederverwendung |
+| `KomandoZentral` | UI-Layout-Referenz | Layout-Ideen übernehmen |
+| `PromptGarage` | MD-DB-Inhalt-Quelle | Datei-Import, kein Code-Import |
+| `Hermes` | Notification-Sink | Message-Send via existierende Hermes-API |
+| `openclaude` Fork | Adapter-Target | Nur als CLI-Spawn-Ziel nutzen, keine Code-Integration |
+### 5.2 Fremde Repos → als Library oder Adapter-Target, nie als Fork
+| Tool | Rolle | Integrations-Stil |
+|---|---|---|
+| **LiteLLM** | Model-Routing (L0-nah) | Library-Import, keine Modifikation |
+| **OpenHands** | Adapter-Target (L1, Post-MVP) | CLI-Spawn über Adapter, kein Code-Import |
+| **Goose** | Adapter-Target (L1, optional) | Dito |
+| **tmux / supervisord** | Parallel-Orchestrator (L3) | System-Binary, Config-Files |
+| **Pydantic / python-frontmatter / markdown-it** | MD-DB-Plumbing | Standard-Libraries |
+### 5.3 USP-Artefakte → selbst, konstant pflegen
+- Alle `md-db/**/*.md`-Inhalte
+- Alle Router-Policy-Dateien
+- Alle Sidecar-Regel-Dateien
+- Alle Eval-Interpretations-Dokumente
+- Alle Track-Templates
+- Jede Erweiterung des MD-DB-Schemas
+**Diese Kategorie darf nie an ein fremdes Repo outgesourced werden, auch wenn es vermeintlich ähnliche Lösungen gibt.** Sie ist der einzige Grund, warum megaHarness existiert.
+---
+## 6. Entscheidungs-Heuristik (für jede neue Komponente)
+Folgende drei Fragen in Reihenfolge:
+1. **Ist das ein gelöstes Commodity-Problem?** (HTTP, Parsing, Prozess-Start, Model-Aufruf)
+   → Ja: Library importieren. Keine Diskussion.
+2. **Ist das Verhalten an Samuels Arbeitsweise gebunden?** (Done-Kriterien, Regel-Interaktionen, UI-Scan-Patterns)
+   → Ja: selbst bauen. Keine Diskussion.
+3. **Wenn weder eindeutig ja: existiert ein fremdes Repo, das dasselbe Problem löst und dessen Abstraktionen zu megaHarness-Denken passen?**
+   → Ja: Adapter schreiben, nicht forken.
+   → Nein: selbst bauen, aber minimal.
+Wenn die Antwort auf alle drei Fragen unklar ist: die Komponente ist wahrscheinlich nicht MVP-relevant.
+---
+## 7. Review-Trigger
+Diese Doktrin wird geprüft und ggf. angepasst:
+- Am Ende des 5-Tage-MVP (2026-04-28)
+- Bei jeder Entscheidung, einen neuen Fork anzulegen
+- Bei jeder Entscheidung, mehr als 500 Zeilen eigenen Glue-Code zu schreiben
+- Wenn die Faustzahlen in §3 merklich kippen (weniger als 50% Token-Investment in Artefakte)
+Die Doktrin selbst ist nicht dogmatisch — aber Abweichungen werden dokumentiert, als ADR in `docs/adr/`, bevor sie implementiert werden.
+---
+**Dieser Artefakt ist ein Vertrag zwischen Samuel und seinem zukünftigen Ich, das in Versuchung kommen wird, entweder alles neu zu bauen oder alles zuzukaufen. Beides wäre ein Fehler. Das Produkt ist die Komposition.**

BRIEFING_LUIS.md ADDED Viewed

	@@ -0,0 +1,260 @@

+# Briefing für Luis — Architektur-Konsolidierung Agent Control Tower
+> Hi Luis, danke nochmal fürs Telefonat. Dieses Dokument fasst zusammen, was ich erzählt habe, plus den Stand des Codes, den du brauchst, um den Konsolidierungs-Plan ohne Rückfragen schreiben zu können. Wenn etwas widerspricht, gilt unser Telefonat — schreib mir, ich klär das.
+>
+> **Was du am Ende lieferst:** eine Markdown-Datei `KONSOLIDIERUNG_LUIS.md` neben diesem Briefing. Details siehe §8.
+---
+## 0. Lese-Reihenfolge und Auftrag
+Bitte geh in dieser Reihenfolge vor:
+1. **Zuerst die Website**: [`index.html`](./index.html)
+2. **Dann dieses Briefing**: [`BRIEFING_LUIS.md`](./BRIEFING_LUIS.md)
+3. **Dann, nur falls du tiefer reinschauen willst**:
+   - [`AGENT_CONTROL_TOWER_PROJECT_AUDIT.md`](./AGENT_CONTROL_TOWER_PROJECT_AUDIT.md)
+   - [`agent-control-tower-steckbriefe.md`](./agent-control-tower-steckbriefe.md)
+Wichtig: Ich brauche von dir **erstmal keine Implementierung**. Kein Code schreiben, nichts refactoren, kein Repo neu aufsetzen. Ich brauche eine **technische Konsolidierungsentscheidung**:
+- Welches Projekt wird der **Anker**?
+- Was wird **übernommen**?
+- Was wird **archiviert**?
+- Wie sieht die **minimale Repo-/Architektur-Topologie** aus?
+Das Ziel ist **nicht**, alle bisherigen Projekte zusammenzukippen, sondern daraus einen realistischen **Agent Control Tower** zu machen.
+---
+## 1. Die Vision in einem Satz
+**Agent Control Tower** ist ein Cockpit, das alle meine agentischen Aktivitäten und Projekte greifbar und übersichtlich macht, einen strikten Fokus-Modus erzwingt und Tasks in **megaHarness** als Orchestrator funnelt.
+Endzustand, an dem ich es als „fertig" erkenne: ich kann am Computer sitzen, Dinge umsetzen, die Idee verkaufen und anderen beibringen.
+### 1.1 Realistischer Core Scope / Definition of Done
+Das Ziel ist ein **end-to-end lauffähiger Flow mit minimalen, aber echten Komponenten**. Nicht alles auf einmal, sondern ein glaubwürdiger Kern für ca. **300 € Budget**.
+**Gewünschter User Flow:**
+1. Ich öffne das **UI** lokal.
+2. Ich gebe einen Task per **Text** oder **Speech-to-Text** ein.
+3. Ein **Router-Agent** schlägt das passende Harness vor (z. B. Claude Code / Codex / Gemini CLI / OpenCode) — mit kurzer Begründung.
+4. Ein **Prompt-Booster** reichert den Prompt an (Kontext, Modus, Rolle).
+5. Ich starte das gewählte Harness zunächst **manuell im Terminal** über einen vom Tower erzeugten Copy-Paste-Befehl.
+6. Im UI sehe ich ein **Kanban-Board** meiner Projekt-Tasks, gespeist aus **GitHub Issues**.
+**Akzeptanzkriterien für diesen Core:**
+- UI startbar mit einem Befehl (`pnpm dev`, `make run` o. ä.)
+- Speech-to-Text funktioniert lokal oder per API
+- Router klassifiziert mindestens 3 Harness-Typen nachvollziehbar
+- Prompt-Booster produziert bei gleichem Input reproduzierbaren Output
+- Kanban-Board zeigt Issues aus mindestens 3 Repos, gruppiert nach Projekt
+- README erklärt Clone → Setup → Run so, dass wir beide es durchspielen können
+**Explizit out of scope im Core:**
+- Kein Auto-Start der Harnesses aus dem UI
+- Keine eigene DB
+- Keine Auth / kein Multi-User
+- Keine Session-Persistenz außer dem, was GitHub ohnehin speichert
+**Bekannte Stolperfallen:**
+- **V7-Pattern / Scope-Eskalation**: Neue Ideen landen in `STRETCH.md`, nicht im Sprint.
+- **Harness-Lifecycle**: sauberes Starten/Stoppen war historisch Pain Point — deshalb im Core bewusst manuell.
+- **GitHub Rate Limits**: `gh issue list` projektübergreifend braucht wahrscheinlich simplen Cache.
+---
+## 2. Schichtenbild
+```
+L4   Agent Control Tower (Cockpit)        →  Übersicht, Greifbarkeit
+L4′  Focus-Mode-Taskbar (Filter)          →  strikter Fokus-Erzwinger
+L3   megaHarness (Orchestrator)           →  Multi-Harness, Multi-Modell
+L1   Harness-Adapter                      →  Claude Code, OpenClaude, Codex, OpenHands, Hermes
+L0   LLM-Provider (extern, nicht Eigen-Code)
+```
+Stand pro Schicht:
+| Schicht | Stand |
+|---|---|
+| L4 Cockpit | existiert in drei Reifegraden parallel (siehe §3) |
+| L4′ Focus-Mode | konzeptionell in der Vision, **nicht implementiert** |
+| L3 megaHarness | Architektur-Doktrin gelockt (4 MD-Files), **MVP-Implementierung steckengeblieben** |
+| L1 Adapter | deployment-fertig in `Zentrale`, fragmentiert in den anderen Versuchen |
+| L0 | durch externe Provider abgedeckt |
+---
+## 3. Was schon existiert — sechs Ordner unter `/home/smlflg/Projekte/`
+| Ordner | Was es ist | Stand |
+|---|---|---|
+| `KomandoZentral/` | Deterministische, regelbasierte Routing-Engine. CLI + FastAPI Web-UI. Python. | Deployed, Tests grün |
+| `Zentrale/` | Multi-Agent-Supervisor (Textual TUI + FastAPI Web + CLI). Wave 1–5 gebaut, KomandoZentral-Routing eingewoben (`--use-kz`-Flag). | **Stabilstes Asset** |
+| `FusionKomandoZentraleZentrale/` | Vier-Schritt-Minimal-Fusion (Intent → Route → Execute → Result). FastAPI Backend lokal. | MVP-fertig, 14 Tests grün, **integriert NICHT mit den anderen** |
+| `megaHarness/` | Architektur-Doktrin in 4 Markdown-Files (siehe §6). | Doktrin gelockt, MVP-Implementierung nicht abgeschlossen |
+| `ACT-agentcommandotower/` | Bewusst minimaler Operator-Stub: `tower.py` + `tower.yaml`. | Stub, kein Git, kein Build |
+| `derWolfimSchafspelz/` | OpenClaude-Fork (Multi-Provider Coding-Agent CLI). | Anti-Pattern laut eigener Doktrin — gehört durch CLI-Adapter ersetzt |
+Detailansicht je Ordner siehe §12 (Anhang).
+---
+## 4. Drei Fusionsphilosophien — warum sie nicht harmonieren
+| Versuch | Philosophie | Kern-Mechanismus |
+|---|---|---|
+| `FusionKomandoZentraleZentrale` | Minimalistisch, intent-zentriert | Vier Schritte als Vertrag, keine Policy-Evolution, keine Swarm-Logik |
+| `Zentrale` | Praktisch-deployed, Supervisor-Pattern, profile-basiert | Profile + Context-Packs + Phase-Routing über mehrere Harnesses |
+| `megaHarness` | Meta-Harness über Harnesses | Schichtenmodell, Harness-Swap, adaptive .md-Datenbank als Source of Truth |
+Jeder Versuch ist **intern kohärent**. Sie wurden in unterschiedlichen Phasen geboren, ohne aufeinander designt zu sein — deshalb integrieren sie nicht.
+Eine deiner Kernentscheidungen wird sein: **welcher der drei Versuche wird Anker, was wird abgewickelt?** Mein Bauchgefühl sagt `Zentrale` (deploybar), aber ich will dein Urteil.
+---
+## 5. Doppelungen, die du kennen musst
+- **Intent-Klassifizierung 3×**: in `FusionKomandoZentraleZentrale`, in `KomandoZentral/src/kz/classify.py`, und im megaHarness-Task-Router (geplant).
+- **Harness-Routing 3×**: KomandoZentral-Confidence-Logik, Zentrale-Static-Routing, megaHarness-Policy.
+- **Context-Pack-Generierung 1×**: nur in `Zentrale`, funktional — der einzigartige Wert dieses Projekts.
+Drei verschiedene Lösungen für dasselbe Problem (Routing) sind die direkte Ursache der Integrations-Blockade.
+---
+## 6. Architektur-Doktrin — bitte vor dem Konsolidierungs-Plan lesen
+Diese vier Dateien beschreiben, **wie ich denke**, nicht **was du tun musst**. Lies sie kursorisch. Weiche von ihnen ab, wo nötig — aber begründe Abweichungen explizit:
+| Datei | Zweck |
+|---|---|
+| [`ARCHITECTURE.md`](./ARCHITECTURE.md) | L0–L4 Schichtenmodell, 5-Tage-MVP-Plan, Risiken & Done-Kriterien |
+| [`Artefakt_USP.md`](./Artefakt_USP.md) | Build-vs-Integrate-Heuristik: was selbst bauen, was fremd integrieren |
+| [`Höhlengleichnis.md`](./Höhlengleichnis.md) | Projekt-Destillation, Kategorien A/B/C/D/E/F |
+| [`idea`](./idea) | 8-Punkt-Vision (Stichpunkte, kein Prosa) |
+---
+## 7. Empirische Kalibrierung — ein Datenpunkt, der Routing-Entscheidungen beeinflusst
+GPT-5.4 verbrennt im Claude-Code-Harness **2–8 Millionen Input-Tokens pro Session**, bei Opus 4.7 sind es **< 20 k**. Der Output-Anteil kollabiert dabei. Empirisch belegt: [`HarnessEcosystem/docs/gpt5-4-shift-report.md`](../HarnessEcosystem/docs/gpt5-4-shift-report.md).
+**Konsequenz für deinen Plan:** Der Router darf GPT-5.4 nicht standardmäßig in einen Claude-nativen Harness schicken. Diese Constraint sollte in der Topologie sichtbar sein.
+---
+## 8. Was du liefern sollst — explizit
+**Format:** eine einzige Markdown-Datei `KONSOLIDIERUNG_LUIS.md`, abgelegt unter `/home/smlflg/Projekte/megaHarness/` (neben diesem Briefing).
+**Format-Constraint:** max. 6–10 Druckseiten, scannbar, kein Code-Snippet > 10 Zeilen.
+**Inhalt** — diese fünf Sektionen, in dieser Reihenfolge:
+| § | Titel | Was hineingehört |
+|---|---|---|
+| **a** | **Anker-Empfehlung** | Welcher der drei Versuche (Zentrale / FusionKZZ / megaHarness) wird Fundament des Agent Control Tower? Mit Begründung. |
+| **b** | **Höhlengleichnis-Verdict pro Projekt** | Für die 6 Ordner aus §3 jeweils Kategorie A/B/C/D/E/F (siehe `Höhlengleichnis.md`) zuordnen, mit 1–2 Sätzen Begründung. |
+| **c** | **Konsolidierungs-Sequenz** | In welcher Reihenfolge wird zusammengeführt? Welche Schritte sind Voraussetzung füreinander? |
+| **d** | **Risiken** | Was geht in der Konsolidierung verloren? Was bricht? Welche Schritte sind nicht mehr rückholbar? |
+| **e** | **Repository-Topologie** | Wie sollte das Layout des konsolidierten Agent Control Tower aussehen? (Struktur, nicht Code.) |
+---
+## 9. Was du NICHT entscheiden musst
+- Die megaHarness-Architektur-Doktrin (Schichtenmodell, MD-DB als Source of Truth, Build-vs-Integrate, Höhlengleichnis-Kategorien) ist mein Anker. Du darfst davon abweichen, aber bitte begründe.
+- **Kein Code schreiben. Kein Refactor. Kein Repo neu anlegen. Nur der schriftliche Plan.**
+- Nicht die ~80 Projekte in meinem Workspace — nur die 6 Ordner aus §3.
+---
+## 10. Rahmen
+- **Budget:** 300 €.
+- **N=1-Realität:** Ich bin Solo. Keine Eval-Suite mit statistischer Signifikanz. Empfehlungen sollen das berücksichtigen — keine Frontier-Lab-Annahmen.
+- **Persönliche Schicht:** Sidecar-NG (ADHS-kompatible Hooks/Regeln) und meine Arbeitsweise sollen erhalten bleiben. Kein Wegrationalisieren der personalisierten Layer — das ist mein USP.
+- **Endziel:** am Computer sitzen, Dinge umsetzen, die Idee verkaufen und anderen beibringen.
+---
+## 11. Folgeprozess
+1. Du liest dieses Briefing + überfliegst die Doktrin-Files (§6).
+2. Du sammelst offene Fragen — wenn nötig, kurzes Klär-Telefonat.
+3. Du schreibst `KONSOLIDIERUNG_LUIS.md` gemäß §8.
+4. Ich reviewe. Bei Iteration: annotierte Version oder Folge-Dokument.
+---
+## 12. Anhang — Detailansicht je Ordner
+### 12.1 `KomandoZentral/`
+- **Was es ist:** Deterministische, regelbasierte Routing-Engine für AI-Harnesses mit CLI und lokaler Web-UI.
+- **Stack:** Python (uv), FastAPI, regelbasiert (kein LLM in der Routing-Logik selbst).
+- **Top-Level-Module unter `src/kz/`:** `classify.py` (Task-Klassifizierung), `cli.py`, `service.py` (Routing-Pipeline), `web.py` (FastAPI + Web-UI, ~34 KB), `models.py`, `rules.py`, `confidence.py`, `persist.py`, `registry.py`.
+- **Operator-State-Flags** (im CLI sichtbar): `--focus`, `--adhd-risk`, `--drift-risk`, `--energy`, `--mode`, `--cost-tolerance`. **Wichtig:** das ist die personalisierte Schicht, die erhalten bleiben muss.
+- **DECISIONS/:** drei YAML-Dateien mit konkreten Routing-Entscheidungen — Beispiele für die Output-Form der Engine.
+- **Beta-Doku:** [`KomandoZentral/BETA_SCOPE.md`](../KomandoZentral/BETA_SCOPE.md), [`OPENCODE_HANDOFF.md`](../KomandoZentral/OPENCODE_HANDOFF.md).
+- **Schlüssel-Files für dich:** [`KomandoZentral/README.md`](../KomandoZentral/README.md), [`KomandoZentral/SOFTWARE_ARCHITEKTUR.md`](../KomandoZentral/SOFTWARE_ARCHITEKTUR.md), [`KomandoZentral/ECOSYSTEM_MAP.md`](../KomandoZentral/ECOSYSTEM_MAP.md).
+### 12.2 `Zentrale/`
+- **Was es ist:** Multi-Agent-Orchestrator im Supervisor-Pattern. Sitzt über Claude Code, Codex, OpenCode, Hermes und Gemini, routet Tasks auf den passenden Harness, injiziert projekt-/phasenspezifischen Markdown-Context.
+- **Stack:** Python + Textual (TUI) + FastAPI (Web). JSON-Registries für Phasen/Harnesses/Profile.
+- **Reife:** Wave 1–5 gebaut (LiveDashboard, TaskQueue, PhaseSwitcher, CostTracker, QuickRun). End-to-End `run`-Befehl orchestriert: route → context-pack → create-run → opencode → log → status. Tests grün, `validate` + `doctor` Commands existieren.
+- **Integration mit KomandoZentral:** `--use-kz`-Flag bereits implementiert — nutzt KomandoZentrals Routing-Engine.
+- **Stärke:** einziger Ort, an dem Context-Pack-Generierung funktional läuft.
+### 12.3 `FusionKomandoZentraleZentrale/`
+- **Was es ist:** Mein Versuch, die Konzepte aus KomandoZentral + Zentrale + megaHarness-Executor in eine minimale Vier-Schritt-Architektur zu fusionieren: Intent → Route → Execute → Result.
+- **Stack:** Python, FastAPI Backend, lokale DB für Run-Records.
+- **Komponenten:** `IntentClassifier` (nur Modus/Task-Typ), `KomandoRouter` (Intent → Phase/Harness), `FusionSystem` (Orchestrator), `Executor` (Ausführung).
+- **Stand:** MVP-fertig, **14 Tests grün**. API-Grundgerüst (Health, Runs anlegen/abrufen, projektbezogene Runs listen).
+- **Wo es scheiterte:** keine Erweiterung über MVP hinaus, **integriert nicht** mit KomandoZentral / Zentrale / megaHarness. CLI-Wrapper, JSON-Export, Eval-Modus geplant aber nicht implementiert.
+- **Schlüssel-Files:** [`FusionKomandoZentraleZentrale/README.md`](../FusionKomandoZentraleZentrale/README.md), [`FusionKomandoZentraleZentrale/src/fusion_kzz/orchestrator.py`](../FusionKomandoZentraleZentrale/src/fusion_kzz/orchestrator.py).
+### 12.4 `megaHarness/`
+- **Was es ist:** Mein persönliches Meta-Harness als Architektur-Konzept — eine Schicht über existierenden Harnesses, die sie als austauschbare Execution-Engines orchestriert.
+- **Inhalt:** vier Markdown-Files (siehe §6). **Keine Implementierung über die Doktrin hinaus.**
+- **Kern-Idee:** L3 kennt L1 nur über Adapter-Interface, L2 über Resolver. Modell-Swap und Harness-Swap werden zur Config-Änderung statt Refactor.
+- **5-Tage-MVP-Plan** liegt in `ARCHITECTURE.md` §6 — nicht abgearbeitet.
+- **Bausteine-Status laut eigener Map:** L2 (MD-DB-Schema) ✗, L1-Adapter (Claude Code/OpenClaude) ~50 %, L3-Kernel in Arbeit, L3 (Eval-Engine, Sidecar) ✓ existiert via `HarnessEcosystem/sidebyside` und `Sidecar-ng`, L4 (UI-Ästhetik) ✓ aus `frontier-llm-harness`.
+### 12.5 `ACT-agentcommandotower/`
+- **Was es ist:** Minimaler lokaler Operator-Stub für agentic Projects.
+- **Stack:** Python-Script (`tower.py`, ca. 3,5 KB, 4 Commands: `status`, `focus`, `add-decision`, `add-run`, `pause`), YAML für State (`tower.yaml`), Markdown für Docs (`focus.md`, `decisions.md`).
+- **Bewusste Non-Goals:** keine DB, keine Web-UI, keine Hintergrundprozesse, keine autonome Orchestrierung.
+- **Stand:** Stub, kein .git, nicht über MVP hinaus entwickelt.
+- **Mögliche Rolle:** Inspiration für minimalen Cockpit-Layer, nicht als Code-Basis.
+### 12.6 `derWolfimSchafspelz/`
+- **Was es ist:** Fork-Wrapper um OpenClaude (offene Multi-Provider Coding-Agent CLI, Node.js/Bun, MIT-Lizenz). Unterstützt OpenAI-kompatible APIs, Gemini, GitHub Models, Codex, Ollama.
+- **Anti-Pattern (laut [`Artefakt_USP.md`](./Artefakt_USP.md), Pattern A1):** Fork-als-Maintenance — Upstream bewegt sich, Fork bleibt stehen, Merge-Schulden wachsen.
+- **Empfohlene Auflösung:** OpenClaude **nicht** forken, sondern als CLI-Spawn-Adapter aus dem Agent Control Tower nutzen. Der Fork kann dann archiviert werden.
+---
+## Schlusswort
+Falls etwas in diesem Briefing nicht zum Telefonat passt: ruf an oder schreib. Das Telefonat war reicher als dieser Text — er ist ein Anker, kein Ersatz.
+Wenn dir beim Lesen klar wird, dass du noch eine Information aus einem der Repos brauchst, die hier nicht steht: sag's, ich liefere nach. Lieber ein Klär-Round als Plan auf Annahmen.
+Wenn Rückfragen offen bleiben, können wir auch kurz telefonieren.
+— Samuel Fleig

Höhlengleichnis.md ADDED Viewed

	@@ -0,0 +1,221 @@

+# Höhlengleichnis — Projekt-Destillation und GH-Gegenstück-Mapping
+**Zweck:** Systematisches Vorgehen, um aus Samuels ~80 Projekten (10% done, 50% 0,9-done, 40% unklar) das zu extrahieren, was echter USP ist — und das zu integrieren, was von anderen besser gebaut wurde.
+**Gilt neben:** `ARCHITECTURE.md`, `Artefakt_USP.md`
+**Metapher:** Platons Höhlengleichnis. Unfertige Projekte = Schatten an der Wand. Die saubere Umsetzung des gleichen Gedankens im GH-Ökosystem = die Idee außerhalb der Höhle. Die Aufgabe: erkennen, was Schatten ist, was eigene Idee, und welche Ideen jemand anderes schon sauberer aus der Höhle rausgetragen hat.
+---
+## 0. Kernsatz
+> **Nicht jeder unfertige Gedanke muss selbst zu Ende gebaut werden. Die meisten deiner Projekte sind Beweise, dass du einen bestimmten Bedarf erkannt hast. In einigen Fällen hat jemand diesen Bedarf sauberer gelöst, als du es je würdest. Deine Arbeit ist dann: den Bedarf klar benennen, das fremde Repo integrieren, und deine Personalisierung darüberlegen.**
+Die Voraussetzung für diese Entscheidung ist der **destillierte Seed** — der eine Satz, der den Kern deines Projekts beschreibt, losgelöst von Code und Projektnamen.
+---
+## 1. Der Prozess in vier Phasen
+```
+Phase 1: Destillation       →  Seed (1–2 Sätze pro Projekt)
+Phase 2: Gegenstück-Suche   →  0–N GH-Repos mit ähnlichem Seed
+Phase 3: Matching-Urteil    →  Entscheidungs-Kategorie (siehe §5)
+Phase 4: Aktions-Routing    →  Finishen / Integrieren / Streichen / Kombinieren
+```
+Jede Phase hat ein eigenes Artefakt in der MD-DB unter `md-db/projects/<slug>/`:
+- `seed.md` — das Destillat
+- `gh-matches.md` — Kandidaten aus der Gegenstück-Suche
+- `verdict.md` — das Matching-Urteil mit Begründung
+- `action.md` — was konkret getan wird
+---
+## 2. Phase 1 — Destillations-Template
+Für jedes Projekt wird **ein einziger Satz** produziert, nach folgendem Template:
+> **„[Projektname] existiert, weil es [Bedarf] löst, indem es [Kern-Mechanismus] tut — und zwar speziell für [Nutzer / Kontext]."**
+Beispiele (konstruiert):
+- „`PromptGarage` existiert, weil fragmentierte Prompts unauffindbar werden, indem es Prompts als versionierte MD-Files mit Frontmatter organisiert — speziell für Solo-Developer mit vielen Modellen."
+- „`SidecarDashboard` existiert, weil Sidecar-Events nicht sichtbar sind, indem es Hook-Payloads live rendert — speziell für ADHS-kompatibles Arbeiten."
+**Regeln für den Satz:**
+1. Maximal 30 Wörter.
+2. Keine Feature-Aufzählung.
+3. Kein „etc.".
+4. Wenn du den Satz nicht schreiben kannst: das Projekt ist entweder noch nicht existent (bloß ein Ordner) **oder** gehört in die Strich-Liste (§5 Kategorie D).
+**Output:** `md-db/projects/<slug>/seed.md` mit Frontmatter `status: draft | confirmed | stale`.
+---
+## 3. Phase 2 — Gegenstück-Suche
+**Ziel:** Finde 0–N GH-Repos, deren `seed` semantisch deinem `seed` entspricht.
+### 3.1 Such-Heuristiken
+1. **Keywords aus dem Seed** in GH-Search: Bedarf + Mechanismus, nicht Projektname.
+2. **Awesome-Listen** der nächstliegenden Domäne durchgehen (z.B. `awesome-llm-agents`, `awesome-markdown-tools`).
+3. **Hacker-News-Suche** auf den Bedarf (nicht auf Lösungen) — News hat oft Diskussionen über ähnliche Probleme.
+4. **Papers-with-Code** für Repos mit Forschungshintergrund.
+5. **Cross-Reference:** wenn du bereits ein Repo kennst, das nah ist, schau dessen „Similar Repos" und Stargazer-Empfehlungen an.
+### 3.2 Qualitäts-Filter für Kandidaten
+Ein Repo ist ein relevanter Kandidat, wenn mindestens **drei** der folgenden Kriterien erfüllt sind:
+- Aktiv maintained (Commit in den letzten 6 Monaten)
+- Mehr als 100 Stars **oder** klar publiziert mit Dokumentation
+- Installierbar/lauffähig ohne Spezial-Setup
+- Abstraktions-Modell passt zu deinem Denken (keine Ideologie-Kollision — siehe Anti-Pattern A5 in Artefakt_USP)
+- Lizenz kompatibel (MIT / Apache-2 / BSD — nicht AGPL ohne Prüfung)
+### 3.3 Anti-Kriterien (disqualifizieren sofort)
+- Enterprise-SaaS ohne Self-Host-Option
+- Abhängig von proprietärem Stack, den du nicht nutzt
+- Tote Repos (letzter Commit > 2 Jahre)
+- Wrappers um andere Tools, die selbst die bessere Wahl wären
+**Output:** `md-db/projects/<slug>/gh-matches.md` mit Tabelle: Repo-URL, Stars, Last-Commit, Seed-Match-Bewertung (1–5), Lizenz, Notiz.
+---
+## 4. Phase 3 — Matching-Urteil
+Für jedes Projekt wird **genau eine** Kategorie vergeben:
+| Kategorie | Definition | Aktion |
+|---|---|---|
+| **A — Original** | Kein adäquates GH-Gegenstück existiert; dein Seed ist genuin | Selbst finishen, zu megaHarness integrieren |
+| **B — Schlechter Schatten** | GH-Gegenstück existiert, aber schlechter als deins | Selbst finishen, optional später als eigenes Repo publizieren |
+| **C — Besserer Schatten** | GH-Gegenstück existiert, ist deutlich sauberer | Eigenes Projekt archivieren; GH-Repo als Adapter-Target integrieren |
+| **D — Schatten ohne Idee** | Seed lässt sich nicht destillieren, Projekt war nie klar | Streichen, Lernen notieren, zur Ruhe kommen lassen |
+| **E — Komplementär** | GH-Gegenstück existiert, aber du deckst andere Axe ab | Beide behalten, Verbindung skizzieren |
+| **F — Vor-Entscheidung nötig** | Seed klar, GH-Kandidat klar, aber Entscheidung hängt an nicht-getesteten Annahmen | Annahme als Mini-Experiment validieren, dann erneut entscheiden |
+### Begründungs-Pflicht
+Jedes Urteil braucht eine Begründung in `verdict.md`, die auf folgende drei Fragen antwortet:
+1. Was genau macht das GH-Repo besser/schlechter/anders?
+2. Welche Personalisierungs-Schicht (Samuel-spezifisch) wäre bei Kategorie C noch nötig?
+3. Welche Annahme könnte dieses Urteil kippen, wenn sie falsch ist?
+---
+## 5. Phase 4 — Aktions-Routing
+| Kategorie | Token-Budget-Anteil | Zeit-Horizont |
+|---|---|---|
+| A — Original | Hoch — hier steckt USP | MVP-relevante zuerst, Rest Post-MVP |
+| B — Schlechter Schatten | Mittel — nur finishen was du auch nutzt | Post-MVP |
+| C — Besserer Schatten | **Niedrig** — nur Adapter-Aufwand | MVP-relevante wenn Baustein, sonst später |
+| D — Schatten ohne Idee | **Null** — aktives Loslassen | Sofort streichen (`archived/`-Ordner, nicht löschen) |
+| E — Komplementär | Mittel — Verbindung dokumentieren | Post-MVP |
+| F — Vor-Entscheidung | Klein — nur Experiment, keine Implementierung | Vor jedem größeren Commit |
+**Wichtig:** Kategorie D ist nicht Scheitern. Das sind Erkenntnis-Artefakte. Jeder Ordner, der dort landet, bekommt vorher eine kurze `lesson.md`: was war der Reiz, was war der Hinderungsgrund, was würdest du heute anders wissen. Das ist das eigentliche Ergebnis solcher Projekte.
+---
+## 6. Anwendungsplan für 80 Projekte
+Die Bearbeitung aller 80 Projekte manuell ist 80 × (Destillation + Suche + Urteil) ≈ 80 × 30min = 40h. Das ist ein eigenes Projekt.
+### 6.1 Priorisierungs-Heuristik
+Nicht alle 80 gleich behandeln. Sortiere vor der Destillation in drei Schichten:
+| Schicht | Kriterium | Zuerst destillieren? |
+|---|---|---|
+| **S1 — Aktiv** | Hast du in den letzten 4 Wochen daran gearbeitet? | Ja, zuerst |
+| **S2 — Fast-fertig** | Der 50%-0,9-done-Block | Ja, als zweites |
+| **S3 — Schlafend** | Alles andere | Batch-Destillation via Agent-Team, später |
+### 6.2 Parallelisierung
+S3 (wahrscheinlich 30–40 Projekte) ist prädestiniert für einen **Sonnet-Background-Agent pro Projekt-Cluster**, der die Destillation automatisiert vorschlägt. Samuel reviewt Seeds, nicht schreibt sie.
+Pro Agent: 3–5 Projekte, Input = README + Ordner-Listing, Output = `seed.md` im Draft-Status. Samuel confirmed/edited.
+**Das ist die richtige Stelle für den „Unleash the Beast"-Modus**, wenn Samuel ihn nutzen will: S3 in 10–15 Parallel-Agenten destillieren, in einem halben Tag fertig.
+### 6.3 Integration in 5-Tage-MVP
+**Nicht** alle 80 Projekte gehören in den MVP. Der MVP braucht nur:
+- Die Destillations-Pipeline als Prozess-Dokument (existiert jetzt)
+- Eine MD-DB-Struktur, die die 4 Artefakte pro Projekt aufnehmen kann (ist in §1 definiert)
+- 3–5 Beispiel-Destillationen als Proof
+Die Batch-Destillation der restlichen ~75 Projekte ist Post-MVP-Arbeit.
+---
+## 7. Anti-Patterns (wo die Metapher schiefläuft)
+### H1 — Höhlen-Romantik
+Die Metapher „draußen ist die Idee, drinnen der Schatten" suggeriert, dass fremd automatisch besser ist. Falsch. Viele GH-Repos sind selbst Schatten anderer Ideen — nur lauter publiziert.
+**Gegenmittel:** Qualitäts-Filter §3.2 ist Pflicht, nicht Kür.
+### H2 — Destillations-Perfektionismus
+Stunden für den „perfekten Seed-Satz" eines Projekts, das ohnehin in Kategorie D gehört.
+**Gegenmittel:** 10-Minuten-Timer pro Projekt. Wenn nach 10 Minuten kein Seed-Satz existiert: Projekt ist Kategorie D.
+### H3 — Falsche Originalität
+Behauptung „meins ist anders", obwohl GH-Repo denselben Bedarf sauberer löst, nur weil das fremde Repo eine andere Oberflächen-Terminologie nutzt.
+**Gegenmittel:** Seed vergleichen, nicht UI. Wenn Seeds ≈ gleich sind, dann ist es Kategorie C, egal wie die Oberflächen aussehen.
+### H4 — Sunk-Cost-Blockade
+Widerwillen, ein 90%-done-Projekt nach Kategorie C/D zu schicken, weil „ich habe schon so viel investiert".
+**Gegenmittel:** Die investierte Zeit ist der Preis der Erkenntnis. Sie ist bereits bezahlt. Die Frage ist nur, ob die nächsten 10% sich lohnen. Meistens: nein, wenn C/D zutrifft.
+### H5 — Schnelle Integration ohne Personalisierung
+Ein besseres GH-Repo gefunden → einfach installieren und benutzen, ohne die Samuel-spezifische Schicht darüberzulegen.
+**Gegenmittel:** Kategorie C braucht zwingend einen Eintrag „Personalisierungs-Schicht" in `verdict.md`. Ohne den Schritt verlierst du den Grund, warum du es überhaupt gebaut hättest.
+---
+## 8. Beispiel (exemplarisch durchgespielt)
+### Projekt: `PromptGarage`
+**Phase 1 — Destillation:**
+> PromptGarage existiert, weil fragmentierte Prompts über Modelle und Sessions unauffindbar werden, indem es Prompts als versionierte MD-Files mit Frontmatter-Metadaten organisiert — speziell für Solo-Developer, die mehrere Modelle und Harnesses bedienen.
+**Phase 2 — Gegenstück-Suche (Kandidaten):**
+- `promptfoo/promptfoo` — Eval + Versioning, nicht pures Storage
+- `langfuse/langfuse` — SaaS-fokussiert, zu schwer für Solo
+- `humanloop/humanloop` — kommerzielle Plattform
+- `OpenPromptbook` (diverse Forks) — statische Sammlungen, nicht versioniert
+- Eigene Ordner-Struktur `~/prompts/*.md` — genau das, was du baust
+**Phase 3 — Matching-Urteil:** Kategorie **A (Original)** oder **E (Komplementär)** — keine der gefundenen Lösungen tut genau „versionierte MD-Files mit Frontmatter für Solo-Dev". Am nächsten: promptfoo, aber mit anderem Fokus (Eval).
+**Phase 4 — Aktions-Routing:** Als MD-DB-Kern-Komponente in megaHarness integrieren. PromptGarage wird nicht „fertig gemacht", sondern **wird** die MD-DB. Der Name kann bleiben oder fallen.
+*(Dieses Beispiel ist Illustration, kein endgültiges Urteil. Die echte Destillation macht Samuel.)*
+---
+## 9. Integration mit Artefakt_USP-Doktrin
+Das Höhlengleichnis ist der **Prozess**, der die Doktrin umsetzt:
+- Artefakt_USP sagt: *„Baue eigen nur was USP ist, importiere fremd wo commodity."*
+- Höhlengleichnis sagt: *„Für jedes Projekt finde heraus, welche Kategorie gilt, systematisch."*
+Jedes `verdict.md` ist ein Anwendungs-Fall der Doktrin. Sammeln sich viele Kategorie-C-Urteile in einer Domäne, ist das ein Signal, dass dort das Ökosystem reif ist und Selbstbau generell verschwendete Zeit wäre. Umgekehrt: viele Kategorie-A in einer Domäne heißt, da ist echter Nischen-Wert.
+---
+## 10. Review-Trigger
+Diese Methode wird geprüft, wenn:
+- Nach 10 durchlaufenen Projekten: stimmt die Kategorie-Verteilung mit dem Gefühl überein?
+- Ein Kategorie-D-Projekt erneut auftaucht (gleicher Seed, neuer Anlauf) — dann ist entweder das D-Urteil falsch oder der Seed falsch destilliert.
+- Ein Kategorie-C-GH-Repo verschwindet oder unmaintained wird — dann wird es zu F oder kippt in A.
+---
+**Dieses Artefakt ist dein Weg aus der Höhle. Nicht jede Idee muss dein Code sein. Nicht jedes fremde Repo muss deine Idee ersetzen. Die Kunst ist die Unterscheidung, und die Unterscheidung ist hier operationalisiert.**

idea ADDED Viewed

	@@ -0,0 +1,23 @@

+1. Harness-agnostisch — kann Claude Code, OpenClaude, Codex, Cursor, OpenHands etc. als Execution-Layer orchestrieren
+    2. Modell-agnostisch — Opus, GPT‑5.4, Sonnet, Gemini, Minimax austauschbar pro Track
+    3. .md-Datenbank als Source-of-Truth — alle Instructions, CLAUDE.md, Skills, Sidecar-Regeln, Projekt-Briefs als versioniertes Markdown, adaptiv (kontextabhängig geladen)
+    4. Parallel-native — mehrere Tracks gleichzeitig, nicht sequenziell
+    5. Eval-integriert — jeder Track misst sich selbst (Token/Turn, Completion, Quality-Labels), Ergebnisse fließen zurück in die .md-DB
+    6. Integriert eigene + fremde Projekte — also Adapter-Layer für externe Repos, nicht nur für Samuels Code
+    7. Samuel-optimiert — ADHS-kompatibel, Sidecar-logik-native, kurze Feedback-Loops
+    8. UI — sichtbar, nicht nur CLI. Dashboard für Tracks, Status, Metriken
+    Das ist keine Kleinigkeit — das ist im Grunde ein Produkt, nicht ein Config-Job. Was du beschreibst überlappt stark mit Devin + LangSmith + ein Eval-Framework + ein
+    Markdown-CMS — alles in einem.
+    Was das für den 5-Tage-Plan heißt
+    Dein „fertig" ist nicht in 5 Tagen erreichbar aus dem Stand. Aber ein lauffähiger Kern, auf dem du weiterbaust, ist drin:
+    - Tag 1: OpenHands als Execution-Engine läuft (dein „Motor"). Gleichzeitig: .md-DB-Struktur definiert (einfach: ~/.harness/md-db/ mit projects/, instructions/, evals/,
+    tracks/).
+    - Tag 2: Adapter-Layer: dünne Python-Shell die aus .md-Einträgen Track-Configs generiert und an OpenHands/Claude Code/Codex weiterreicht. Das ist dein
+    „harness-agnostisch".
+    - Tag 3: Parallel-Queue (Temporal/Dagger oder simpler: tmux + Prefect). 3 Tracks gleichzeitig.
+    - Tag 4: Eval-Hooks — pro Track werden Metriken nach Abschluss in die .md-DB zurückgeschrieben.
+    - Tag 5: UI — einfachster Weg: statische HTML-SPA die die .md-DB rendert (dein frontier-llm-harness und sidebyside sind genau das Muster). Oder: Streamlit/Gradio.