ARCHITECTURE.md

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