feat: bootstrap jetson-ai-ollama from agent-swarm template

Leader-Bootstrap (Planung) aus Template + Jetson-Meta-Prompt:
- ROADMAP-Board W1-W6 als Abhaengigkeits-DAG (Ready-Set = {W1})
- STATE mit disjunkter Datei-Ownership W2-W6
- CONVENTIONS Projekt-Vertrag (Profile, Pfade, Ports, Daemon-Env, num_ctx, DVC, Scope)
- manifests/requirements.md = kalt verifizierbares Review-Manifest (R-01..R-10)
- REVIEW.md Kalt-Review-Einstieg; ADR 0002 (Ollama-nativ, kein Swapper/Gateway)
- session-prompts/W1..W6 dispatch-fertig; .gitignore um Jetson-Ignores erweitert
- examples/walkthrough entfernt (Projekt hat eigenes gefuelltes Board)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/about-template.md

@@ -0,0 +1,58 @@
+# agent-swarm-repo
+
+Ein **generelles Git-Repo-Template für KI-Agenten-Arbeit**. Das Repo ist die
+*dauerhafte gemeinsame Erinnerung* — Sessions sind flüchtig, der Stand lebt in den
+Dateien. Agenten koordinieren über Dateien, nicht über den Chat.
+
+## Aktoren & Modelle
+
+| Rolle | Modell | Aufgabe |
+|---|---|---|
+| Leader | Sonnet | Orchestrierung, Klassifikation, Integration |
+| Worker / Porter | Sonnet | Implementierung mit klarer Spec, faithful Ports |
+| Theorist | Opus | Formeln ableiten, Validation entwerfen |
+| Prototyper (Spike) | Opus→Sonnet | Wegwerf Proof-of-Correctness vor Produktion |
+| Reviewer (Gate) | **Opus, immer** | unabhängiger Review-Pass nach jedem Implement |
+| Scholar / Doc | Haiku | Docs, Citations, CLI-Glue |
+| Human | — | Richtung, Lizenz, Precision-Substrat, Freigabe |
+
+Vollständige Matrix + Entscheidungsregel: `docs/roles/model-routing.md`.
+
+## Zwei Loops (komposit)
+
+- **Feature-Loop (vorwärts):** Roadmap → Port/Research-Klassifikation →
+  [Research: Theorist → Spike → GO/NO-GO] → Worker parallel → Review-Gate (Opus) →
+  Integration → Tests + Doku + Manifest → Quality-Gate.
+- **Audit-Loop (rückwärts):** kalter Auditor (Opus) → Findings mit Model-Zuweisung →
+  Implement-Sessions → Review-Gate (Opus, kalt) → Korrektur-Tasks → Observability-Gate.
+
+Die Loops komplementieren sich: Feature-Dev produziert, Audit härtet ab.
+Jedes Merge triggert einen Audit-Backlog-Eintrag (expliziter Handoff).
+
+## Drei Schlüsselprinzipien
+
+1. **Review-Gate nach jeder Implement-Session** — immer Opus, immer kalt (eigene
+   Session). Implement-Modell ≠ Review-Modell ist eine Korrektheitseigenschaft.
+2. **Spike vor Research-Code** — throwaway Proof-of-Correctness auf einem Wegwerf-Branch.
+   NO-GO ist ein valides Ergebnis, kein Versagen. Schützt vor wochen-langen falschen Implementierungen.
+3. **Session-Prompts kaltstartfähig** — jede Session hat einen vollständigen Prompt
+   unter `session-prompts/` (Modell, Branch, Scope, Befehle, Akzeptanzkriterien).
+
+## Clean-Start-Invariante
+Am Ende **jeder** Session muss gelten: ein neuer Agent kann sich allein über
+`AGENTS.md → STATE.md → CONVENTIONS.md` orientieren. Das erzwingt das
+Session-Hygiene-Gate.
+
+## Loslegen (neues Projekt)
+1. `bash scripts/init.sh "Projektname"` — macht den Klon zu deinem Projekt
+   (Template-Overview wandert nach `docs/about-template.md`).
+2. `session-prompts/BOOTSTRAP.md` in eine frische Leader-Session geben, Projekt-Brief
+   anhängen → der Leader füllt Board (`ROADMAP.md`), `STATE.md`, `CONVENTIONS.md`
+   und erzeugt die ersten Session-Prompts.
+3. Die Gates sind **dormant**, bis die erste Session `STATE.md` befüllt — danach greifen sie automatisch.
+
+> **Erst verstehen?** `examples/walkthrough/` zeigt ein komplett befülltes Beispiel
+> (Board, Session-Log, Audit-Finding, ADR) an einer generischen Domäne.
+
+## Einstieg (jede Session)
+Jeder Agent liest zuerst **`AGENTS.md`**. Methodik im Detail: `docs/methodology.md`.

docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,9 @@
+# 0001 — Entscheidungen als ADR festhalten
+
+- **Status:** accepted
+- **Kontext:** Agenten-Sessions sind flüchtig; ohne festgehaltenes *Warum*
+  entstehen Drift und Wiederholungsfehler.
+- **Entscheidung:** Tragende Entscheidungen werden als ADR unter `docs/adr/`
+  dokumentiert und in `CONVENTIONS.md` als verbindlich referenziert.
+- **Konsequenz:** Minimaler Schreibaufwand pro Entscheidung; dafür kalt lesbare
+  Begründungen und weniger Re-Litigation.

docs/adr/0002-ollama-native.md

@@ -0,0 +1,18 @@
+# 0002 — Ollama-natives Modell-Management, kein eigener Swapper/Gateway
+
+- **Status:** accepted
+- **Kontext:** Jetson Orin Nano Super 8 GB (~7,4 GB nutzbar), Single-User,
+  latenzgebunden. Drei Profile (light/gemma/heavy) nötig, aber nie zwei gleichzeitig
+  resident. Frühere Ansätze hätten einen eigenen Modell-Swapper oder ein API-Gateway
+  vor Ollama gesetzt.
+- **Entscheidung:** Der **Ollama-Daemon serviert die Modelle nativ** (Wechsel per
+  Modellname über die OpenAI-kompatible API). `OLLAMA_MAX_LOADED_MODELS=1` hält genau
+  ein Modell resident (8-GB-Schutz); ein weiteres Profil belegt erst bei Anfrage
+  Speicher. **Kein eigener Swapper, kein Gateway.** **DVC bleibt Modell-Source-of-
+  Truth**, Ollamas Blob-Store ist nur Laufzeit-Cache.
+- **Konsequenz:** Drei Profile quasi gratis (laden on-demand), kein Custom-Code für
+  Modellwechsel, kleinere Angriffsfläche. Preis: kurzer `OLLAMA_KEEP_ALIVE=30s` →
+  Ladezeit beim Profilwechsel — bei Single-User akzeptabel (keine fremde Session wird
+  unterbrochen). Externer Zugriff/Auth/Metrik-Aggregation liegen bewusst off-box
+  (nginx-Proxy, Prometheus) — siehe `CONVENTIONS.md` Scope-Grenze.
+- **Superseded by:** _(noch keins)_

docs/adr/README.md

@@ -0,0 +1,5 @@
+# Architecture Decision Records (ADR)
+
+Jede tragende Entscheidung wird als kurzes, nummeriertes ADR festgehalten —
+so weiß jede künftige Session das *Warum*. Format: `NNNN-kurz-titel.md`.
+Status: proposed / accepted / superseded. Neues ADR statt altes umschreiben.

docs/gates/observability-gates.md

@@ -0,0 +1,20 @@
+# Observability-Gates
+
+Überwachen das **System**, nicht ein einzelnes Feature. Speisen den Audit-Loop.
+
+## 1. System-Effizienz (Metriken über Zeit)
+- Features pro Session · **Rework-Rate** (Commits, die frühere Arbeit korrigieren)
+- Test-Pass-Rate · **Tokens pro Feature** · Zykluszeit · Gate-Fehlerquote
+- Quelle: Session-Logs + Git-Log, aggregiert von `scripts/metrics.sh` nach
+  `metrics/`.
+
+## 2. Doku-Drift (automatisch erkennbar)
+- Jeder Manifest-Eintrag: referenzierte Datei existiert **und** Test grün?
+- `STATE.md` "Now" nicht älter als N Sessions (Stale-Signal).
+- Code ohne Doc-Änderung / Doc ohne Code-Änderung -> Drift-Verdacht (Heuristik
+  aus `git diff --name-only`).
+- Tote Links / referenzierte, aber fehlende ADRs.
+- Quelle: `scripts/gate-doc-drift.sh`. Befund -> sofortiger Audit-Trigger.
+
+## Schwellen (anpassbar)
+Rework-Rate > 20 %, Stale-State > 3 Sessions oder Drift-Treffer > 0 ⇒ Audit-Loop.

docs/gates/quality-gates.md

@@ -0,0 +1,26 @@
+# Quality-Gates
+
+Laufen am Session-Ende und in CI. Jedes Gate: **PASS/FAIL** + Checkliste.
+`FAIL` blockt den Merge bzw. erzeugt einen Korrektur-Task.
+
+## 1. Session-Hygiene
+- [ ] `STATE.md` in dieser Session aktualisiert.
+- [ ] Session-Log unter `sessions/` angelegt (mit Token-Verbrauch).
+- [ ] Working Tree sauber, Commits konventionskonform.
+- [ ] **Clean-Start-Invariante** erfüllt (Orientierung allein aus
+      AGENTS/STATE/CONVENTIONS).
+- Automatisierung: `scripts/gate-session-hygiene.sh`.
+
+## 2. Kontext-Pflege
+- [ ] Doku ist Single Source of Truth, keine Duplikate.
+- [ ] Doc-Größenbudget eingehalten (Drift-Risiko bei überlangen Docs).
+- [ ] Manifest deckt sich mit der Realität (Dateien/Tests existieren).
+- [ ] Keine toten Verweise.
+
+## 3. Token-Verbrauch
+- [ ] Session-Log enthält input/output/total Tokens und Tokens-pro-Task.
+- [ ] Budget nicht überschritten; auffälliges Re-Reading vermerkt.
+- [ ] Trend über Sessions in `metrics/` fortgeschrieben.
+
+→ Vollständige Tier-1/2/3-Anleitung (Session-Schnitt, Command-Disziplin,
+  Cache-Disziplin): **`docs/token-hygiene.md`** (Single Source of Truth).

docs/loops/audit-loop.md

@@ -0,0 +1,54 @@
+# Audit-Loop (rückwärts)
+
+Ziel: Korrektheit & Hygiene erhalten, Drift früh fangen.
+
+```
+Kalter Auditor (Opus, neue Session)
+  -> Orientierung allein aus AGENTS/STATE/CONVENTIONS pruefen
+    -> Manifest verifizieren + Tests ausfuehren
+      -> Drift & Hygiene-Befunde sammeln
+        -> audits/<datum>.md: Finding-Tabelle mit Severity + Model-Zuweisung
+          -> Korrektur-Tasks in ROADMAP/STATE einstellen
+            -> Observability-Gate (Effizienz + Doku-Drift) aktualisieren
+```
+
+## Trigger
+Nach N Feature-Zyklen, oder sofort bei Drift-Signal aus den Observability-Gates.
+
+## Finding-Orchestration
+
+Findings werden in `audits/<datum>.md` **mit Model-Zuweisung** erfasst:
+
+| ID | Typ | Sev | Status | Model | Session |
+|----|-----|-----|--------|-------|---------|
+| F-01 | drift | 🔴 | ⬜ | Sonnet | S1 |
+| F-02 | hygiene | 🟡 | ✅ abc123 | Haiku | S1 |
+
+Severity: 🔴 hoch · 🟡 mittel · 🔵 niedrig
+
+Model-Routing (s. `docs/roles/model-routing.md`):
+- **Haiku** — mechanisch, lokal, kein Risiko (Docs, Umbenennen, Konstanten)
+- **Sonnet** — klare Akzeptanzkriterien (Tests, Error-Handling, kleine API-Änderungen)
+- **Opus** — Numerik, Architektur, irreversible Entscheidungen + **jede Review-Gate-Session**
+
+Entscheidungs-Regel: nicht "wie schwer", sondern "wie viel muss **verstanden** werden,
+um es richtig zu machen."
+
+## Session-Sequenz
+
+Findings werden in Sessions gebündelt (ähnliche Model-Zuweisung, ähnlicher Scope).
+Nach jeder Implement-Session kommt eine **Opus-Review-Session** (kalt, unabhängig):
+
+```
+Implement-Session (Sonnet/Haiku)
+  -> dedizierten Review-Gate-Session (Opus, kalt)
+    APPROVE → Finding ✅ + Commit-Ref eintragen
+    CHANGES-REQUESTED → zurück zu Implement
+```
+
+Kaltstartfähige Prompts für jede Session: `session-prompts/`.
+
+## Ergebnis
+Priorisierte Korrektur-Tasks mit Model-Zuweisung, die der nächste Feature-Loop
+abräumt. Handoff zu Feature-Dev: jedes bereinigte Finding bestätigt, dass das
+Repo wieder der Clean-Start-Invariante genügt.

docs/loops/feature-loop.md

@@ -0,0 +1,62 @@
+# Feature-Loop (vorwärts)
+
+Ziel: neue Fähigkeit, sauber dokumentiert und belegt.
+
+## Kern-Pipeline
+
+```
+Roadmap-Item
+  -> Leader klassifiziert (port / research / infra)
+  -> Leader zerlegt in disjunkte Pakete (+ STATE-Ownership)
+
+  ┌── PORT ────────────────────────────────────────────┐
+  │  Worker (Sonnet): golden-oracle Implementierung    │
+  │  Validation (Sonnet): Parität-Tests                │
+  └────────────────────────────────────────────────────┘
+
+  ┌── RESEARCH ─────────────────────────────────────────────────────────┐
+  │  Theorist (Opus): Formeln aus Papers ableiten, Validation entwerfen │
+  │  Spike (Prototyper): Wegwerf-Implementierung auf scratch/**-Branch  │
+  │  GO/NO-GO-Gate: math korrekt? → GO: weiter; NO-GO: → Roadmap       │
+  │  Research-Implementer (Opus→Sonnet): produktiv umsetzen             │
+  └─────────────────────────────────────────────────────────────────────┘
+
+  -> Validation Engineer: Test-Batterie je Item-Typ bauen
+  -> Review-Gate (Opus, kalt): math korrekt? Parität? Public-API ok?
+       APPROVE → weiter | CHANGES-REQUESTED → zurück zu Implement
+  -> Leader integriert & löst Konflikte
+  -> Manifest + Docs + STATE aktualisiert
+  -> Quality-Gate (Hygiene/Kontext/Token)
+       PASS: Item nach "Done" | FAIL: Korrektur-Task
+```
+
+## Klassifikation Port vs. Research
+
+| Typ | Kriterium | Oracle | Validation-Pflicht |
+|---|---|---|---|
+| **Port** | hat Referenz-Implementierung (Java, Python, Pseudo-Code) | golden values bit-for-bit | FD-Gradient + Parität |
+| **Research** | kein direkter Vorläufer, nur Paper-Formeln | keine extern | Invarianten + analyt. Grenzfälle + Konvergenz |
+| **Infra** | kein fachlicher Inhalt (CLI, CI, Docs) | trivial | Smoke-Test |
+
+Regel: Research-Items **müssen** durch das Spike-Gate, bevor Produktions-Code
+geschrieben wird. Näheres: `docs/loops/spike-gate.md`.
+
+## Model-Routing (grobe Heuristik)
+
+Vollständige Matrix: `docs/roles/model-routing.md`. Kurzform:
+- Mechanische Arbeit (Umbenennen, Docs, CLI-Glue) → **Haiku**
+- Implementierung mit klarer Spec → **Sonnet**
+- Mathe, Architektur, jede Review-Gate-Session → **Opus**
+
+## Session-Prompts
+
+Kaltstartfähige Prompts je Phase/Paket unter `session-prompts/`.
+Template: `session-prompts/TEMPLATE.md`.
+
+## Eintrittskriterien
+Roadmap-Item priorisiert; Klassifikation (Port/Research/Infra) klar;
+betroffene Konventionen geklärt.
+
+## Austrittskriterien (Definition of Done, s. CONVENTIONS.md)
+Tests grün · Manifest `done` · Docs/STATE aktuell · Session-Log ·
+Review-Gate `APPROVE` · Hygiene-Gate `PASS`.

docs/loops/spike-gate.md

@@ -0,0 +1,55 @@
+# Spike-Gate (nur Research-Items)
+
+Bevor Research-Mathe produktivsiert wird: numerischer Proof-of-Correctness
+auf einem **Wegwerf-Branch**. Der Spike schützt davor, Wochen in eine
+mathematisch falsche Implementierung zu investieren.
+
+## Warum
+
+Research-Items haben keinen goldenen Oracle (keine Referenz-Implementierung).
+Eine Implementierung kann kompilieren, konvergieren und trotzdem **geometrisch
+falsch** sein. Invarianten-Checks und Konvergenz-Studien fangen das nur, wenn
+die zu prüfenden Invarianten vorab klar spezifiziert wurden.
+
+## Ablauf
+
+```
+Theorist (Opus):
+  Formeln aus Papers/Dissertation ableiten
+  Validation-Strategie entwerfen (Invarianten, analyt. Grenzfälle, Kreuzcheck)
+  LaTeX-Notiz / Spec-Dokument erstellen
+        ↓
+Prototyper (Opus → Sonnet):
+  Throwaway-Implementierung auf Branch `spike/<thema>`
+  Numerischen Korrektheitsnachweis führen (die vom Theorist entworfene Validation)
+        ↓
+GO/NO-GO-Gate:
+  GO  → Spike-Branch wird verworfen; Research-Implementer baut produktiv
+  NO-GO → Spike-Branch bleibt als Dokumentation des negativen Ergebnisses
+          → Eintrag in ROADMAP: "Spike <thema> FAILED — Grund: …"
+          → Zurück zum Theorist oder Human-Entscheidung
+```
+
+## NO-GO ist kein Versagen
+
+Ein NO-GO ist ein valides, wertvolles Ergebnis. Es dokumentiert, dass ein
+Ansatz numerisch nicht funktioniert, bevor Produktionscode und Tests dafür
+investiert wurden. **Negative Spikes müssen genauso sorgfältig dokumentiert
+werden wie erfolgreiche.**
+
+## Validation-Typen (gewählt vom Theorist)
+
+| Situation | Validation |
+|---|---|
+| Cross-Implementierung verfügbar (andere Bibliothek) | Übereinstimmung nach Normalisierung |
+| Analytische Grenzfälle bekannt (z. B. κ=0 ↔ Euklidisch) | Bit-for-bit-Übereinstimmung am Grenzfall |
+| Erhaltungsgrößen bekannt (Gauss-Bonnet, Holonomie-Closure) | Invarianten-Check unter Perturbation |
+| Analytisch vs. numerisch (FD vs. exakte Hessematrix) | Wert-Identität + Speed-Messung |
+| Kein direkter Check möglich | Konvergenz-unter-Verfeinerung-Studie |
+
+## Aufwand-Faustregel
+
+Ein Spike sollte **höchstens 20 % des Aufwands** einer vollständigen
+Implementierung kosten. Wenn er mehr braucht, ist das Scope entweder falsch
+klassifiziert (→ kleineres Research-Item) oder der Theorist hat die Spec
+nicht ausreichend präzisiert (→ zurück zum Theorist).

docs/methodology.md

@@ -0,0 +1,48 @@
+# Methodik — Betriebsmodell
+
+## Grundprinzip
+Das Repo ist die dauerhafte Erinnerung; Sessions sind flüchtig. Alles
+Entscheidungsrelevante liegt **auf Disk**, nie nur im Chat. So kann jede neue
+Session kalt starten.
+
+## Rollen
+- **Leader** (`docs/roles/leader.md`) — Orchestrierung & Integration.
+- **Worker** (`docs/roles/worker.md`) — disjunkte parallele Umsetzung.
+- **Reviewer** (`docs/roles/reviewer.md`) — kalter Audit in neuer Session; immer Opus.
+- **Model-Routing** (`docs/roles/model-routing.md`) — welches Modell für welche Arbeit.
+
+## Zwei Loops (Feature-Dev und Audit)
+
+- **Feature-Loop / vorwärts** (`docs/loops/feature-loop.md`): erzeugt Fähigkeit.
+  Enthält eine **Port/Research-Klassifikation** und (für Research) ein
+  **Spike-Gate** (`docs/loops/spike-gate.md`) bevor Produktionscode entsteht.
+- **Audit-Loop / rückwärts** (`docs/loops/audit-loop.md`): erhält Korrektheit &
+  Hygiene, speist Korrekturen mit Model-Zuweisung zurück in Roadmap/State.
+
+Die Loops **komplementieren sich**: Feature-Dev produziert Module; Audit härtet
+sie ab. Jedes Merge im Feature-Loop triggert einen Audit-Backlog-Eintrag.
+Die Loops wechseln sich ab: nach N Feature-Zyklen ein Audit-Zyklus (oder sofort
+bei Drift-Signal aus den Observability-Gates).
+
+## Review-Gate (eingebaut in beide Loops)
+
+Nach **jeder** Implement-Session kommt eine separate Opus-Session (kalt,
+unabhängig), die den Diff reviewt. Kein Merge ohne Review-Gate `APPROVE`.
+Details: `docs/roles/reviewer.md`.
+
+## Session-Prompts
+
+Für jede Session existiert ein kaltstartfähiger Prompt unter `session-prompts/`.
+Template: `session-prompts/TEMPLATE.md`. Der Prompt enthält: Modell, Branch,
+Scope, Befehle, Akzeptanzkriterien — alles was die Session ohne Vorkontext braucht.
+
+## Gates
+- **Quality-Gates** (`docs/gates/quality-gates.md`): Session-Hygiene,
+  Kontext-Pflege, Token-Verbrauch.
+- **Observability-Gates** (`docs/gates/observability-gates.md`): System-Effizienz
+  und Doku-Drift.
+- **Token-Hygiene** (`docs/token-hygiene.md`): 3-Tier-System zur Kostensteuerung.
+
+## Clean-Start-Invariante
+Session-Ende ⇒ neuer Agent orientiert sich allein über
+`AGENTS.md → STATE.md → CONVENTIONS.md`. Verletzung = Hygiene-Gate `FAIL`.

docs/roles/leader.md

@@ -0,0 +1,17 @@
+# Rolle: Leader
+
+## Auftrag
+Arbeit zerlegen, zuweisen, integrieren — nicht selbst alle Pakete bauen.
+
+## Ablauf (Feature-Loop)
+1. Oberstes Roadmap-Item ziehen, in **disjunkte Worker-Pakete** zerlegen
+   (klare Datei-Ownership, minimale Kopplung).
+2. Ownership-Tabelle in `STATE.md` eintragen; offene Fragen vorab in
+   `CONVENTIONS.md`/ADR klären, damit Worker nicht divergieren.
+3. Worker parallel dispatchen. Während sie laufen: nichts in ihren Dateien ändern.
+4. **Integrieren:** zusammenführen, Konflikte lösen, Schnittstellen prüfen.
+5. Manifest + Docs + `STATE.md` aktualisieren, Quality-Gate ausführen.
+
+## Regeln
+- Konflikte gehören dir, nicht den Workern.
+- Wenn ein Paket > 1 Worker-Session braucht: weiter zerlegen.

docs/roles/model-routing.md

@@ -0,0 +1,58 @@
+# Model-Routing — Zuweisung nach Aufgabentyp
+
+Vollständige Entscheidungsmatrix. Kurzform in `docs/loops/feature-loop.md`.
+
+> **Tier-Sprache statt feste Modellnamen:** Modellnamen veralten; die Tier-Logik
+> (klein/mittel/hoch) bleibt. Konkrete Modell-IDs (z. B. Haiku 4.5, Sonnet 4.6,
+> Opus 4.8) sind aktuelle Beispiele — beim Provider nachschlagen, wenn neue
+> Versionen verfügbar sind.
+
+## Tiers
+
+| Tier | Eigenschaft | Aktuelle Beispiele (Anthropic Claude) |
+|------|-------------|---------------------------------------|
+| **klein** | schnell, günstig, ausreichend für klar spezifizierte, mechanische Arbeit | Haiku |
+| **mittel** | ausgewogen; guter Coder bei klarer Spec | Sonnet |
+| **hoch** | höchste Reasoning-Kapazität; für Unklarheiten, Mathe, Review | Opus |
+
+## Routing-Matrix
+
+| Aufgabe | Rolle · Tier |
+|---|---|
+| Mechanisch, lokal, kein Risiko: Docs, Umbenennen, Konstanten, CLI-Glue | klein |
+| Faithful Translation von bekannter Referenz (Port, golden oracle) | Porter · mittel |
+| Implementierung mit klarer Spec + Akzeptanzkriterien: Tests, Error-Handling | mittel |
+| Numerik, Architektur, Mathe von Grund auf, irreversible Public-API-Entscheidungen | hoch |
+| Formeln aus Papers ableiten, Validation-Strategie entwerfen | Theorist · hoch |
+| Throwaway Proof-of-Correctness (Spike), bevor Produktionscode entsteht | Prototyper · hoch → mittel |
+| Test-Batterie für abgeschlossene Implementierung | Validation · mittel |
+| **Jede Review-Gate-Session** (unabhängig, kalt) | **Reviewer · hoch** |
+| Docs polieren, Referenz-Listen, Tutorials | Scholar · klein |
+| Branch/PR/CI/Rebase/Merge | Integrator · mittel |
+| Fachliche Richtungsentscheidungen, Lizenz, Precision-Substrat | Human |
+
+## Entscheidungsregel
+
+**Nicht** „wie schwer ist das Finding/Feature", sondern:
+**„Wie viel muss *verstanden* werden, um es richtig zu machen?"**
+
+- Eine 1-Zeilen-Korrektur mit klarer Spec → mittel (auch wenn 🔴 Severity).
+- Eine numerische Umformulierung mit Auswirkung auf Korrektheit → hoch
+  (auch wenn 🔵 Severity).
+
+## Review-Gate-Regel
+
+Die Review-Gate-Session ist **immer höchste Kapazitätsstufe und immer kalt**
+(eigene Session, kein Vorkontext aus der Implement-Session). Implement-Tier ≠
+Review-Tier ist keine Effizienzfrage, sondern eine Korrektheitseigenschaft.
+
+## Routing Port vs. Research
+
+```
+Gibt es eine Referenz-Implementierung / goldene Werte?
+  JA  → Port   → Porter (Sonnet), golden-oracle parity-Tests Pflicht
+  NEIN → Research → Theorist (Opus) ableiten → Spike → GO/NO-GO
+                    → Research-Implementer (Opus→Sonnet) produktivisieren
+```
+
+Details zum Spike-Gate: `docs/loops/spike-gate.md`.

docs/roles/reviewer.md

@@ -0,0 +1,41 @@
+# Rolle: Externer Reviewer (kalt)
+
+## Auftrag
+In einer **frischen Session ohne Vorkontext** verifizieren, ob das Repo stimmt
+und ob ein Neuling sich orientieren kann.
+
+**Modell: immer Opus.** Rationale: ein unabhängiger, kapazitätsstarker Pass
+nach jedem Implement findet systematisch andere Fehler als das implementierende
+Modell. Der Reviewer darf niemals dasselbe Modell in derselben Session gewesen sein.
+
+## Zwei Reviewer-Rollen
+
+### 1. Review-Gate (nach jeder Implement-Session, Feature- wie Audit-Loop)
+Geht den Diff durch — nicht das ganze Repo. Prüft:
+
+- [ ] Build sauber; Test-Suite grün (keine Regressions im Zählstand).
+- [ ] Keine golden-vector / Parität-Tests verändert, sofern nicht explizit begründet.
+- [ ] Numerische Änderungen sind wert-identisch wo behauptet, oder getestet.
+- [ ] Neue Public-Surface (Typen, Enums, API) ist absichtlich und dokumentiert.
+- [ ] Commit-Message enthält Model-Attribution des Implementers.
+- [ ] Finding / Phase als ✅ in der Orchestration-Tabelle mit Commit-Ref eingetragen.
+
+Ergebnis: **APPROVE** oder **CHANGES-REQUESTED** (mit konkreter Liste).
+
+### 2. Audit-Reviewer (periodisch, Audit-Loop)
+Startet komplett kalt — kein Vorkontext aus vorherigen Sessions.
+
+1. **Nur** `AGENTS.md → STATE.md → CONVENTIONS.md` lesen. Orientierung gelungen?
+   (Ja/Nein → erstes Finding.)
+2. `manifests/requirements.md` durchgehen: Dateien vorhanden? Tests lauffähig?
+3. **Drift suchen:** Docs vs. Code, ADRs vs. Realität, `STATE.md`-Aktualität,
+   tote Verweise, ungetestete Behauptungen.
+4. **Hygiene prüfen:** Ownership-Verstöße, Doppel-Dokumentation, Doc-Budget.
+5. Findings nach `audits/<datum>.md` (Template) mit Severity + Model-Zuweisung.
+   Korrektur-Tasks in `ROADMAP.md` / `STATE.md` einstellen.
+   Observability-Gate aktualisieren.
+
+## Prinzip
+Der Reviewer baut keine Features — er deckt Lücken zwischen *behauptet* und
+*belegt* auf. Er nimmt an, dass alle Aussagen im Repo falsch sind, bis er sie
+selbst verifiziert hat.

docs/roles/worker.md

@@ -0,0 +1,14 @@
+# Rolle: Worker
+
+## Auftrag
+Genau **ein** zugewiesenes Paket umsetzen — innerhalb der eigenen Dateigrenzen.
+
+## Ablauf
+1. `AGENTS.md`-Reihenfolge lesen, dann nur die für dein Paket relevanten Dateien.
+2. Gegen den Vertrag in `CONVENTIONS.md` bauen (Naming/Pfade/Schnittstellen).
+3. Tests für dein Paket schreiben; Manifest-Einträge auf `in_progress`/`done` setzen.
+4. **Niemals** Dateien außerhalb deines Pakets anfassen — sonst Notiz an den Leader.
+5. Session-Log schreiben (inkl. Token-Verbrauch), Hygiene-Gate ausführen.
+
+## Anti-Pattern
+- Scope-Creep, "mal eben" fremde Dateien anpassen, Doku "später".

docs/token-hygiene.md

@@ -0,0 +1,50 @@
+# Token-Hygiene — 3 Ebenen
+
+Jeder Turn schickt die ganze Konversations-History erneut. Kontextakkumulation
+ist der größte vermeidbare Kostenfaktor in Multi-Agenten-Setups.
+
+---
+
+## Tier 1 — Session-Schnitt (höchste Wirkung)
+
+- **Eine Session pro Aufgabe.** Nach einer abgeschlossenen Aufgabe `/clear` starten
+  statt zum nächsten Thema im selben Thread zu wechseln. Alter Kontext ist totes
+  Gewicht in jedem weiteren Turn.
+- **Proaktiv kompaktieren** an sauberen Übergabepunkten. `/compact <was wichtig ist>`
+  bevor die nächste Aufgabe startet — nicht warten bis auto-compaction einsetzt
+  (Zeitpunkt ist nicht kontrollierbar).
+- **Lese-intensive Sweeps delegieren.** Ein Explore/Plan-Subagent liest in seinem
+  eigenen Kontext und gibt eine kurze Zusammenfassung zurück — das Bulk landet nie
+  im Hauptkontext. Nur bei bekannten Pfaden direkt `Read` nutzen.
+
+## Tier 2 — Command-Disziplin (mittlere Wirkung)
+
+- **Scope + Filter gemeinsam.** Pfad-scopede Suchen (`grep -rn "symbol" src/`, nicht
+  Repo-weit). Test-Output filtern (`--filter "SuiteX"`, nicht alle Ergebnisse dumpen).
+- **Logs nie roh in Kontext.** In Datei umleiten, dann `grep`/`tail`. Bei
+  Hintergrund-Jobs Output-Datei selektiv lesen, nicht pauschal.
+- **Nicht zurück-lesen nach Edit.** `Edit` schlägt fehl bei inkonsistentem State —
+  ein erfolgreicher Edit braucht kein `Read` zur Verifikation.
+- **Referenz per Zeilennummer** (`datei.py:147`) statt Code-Blöcke neu einzufügen.
+
+## Tier 3 — Cache-Disziplin (Prompt-Cache, TTL 5 min)
+
+Der stabile Präfix jeder Anfrage (System-Prompt + CLAUDE.md / AGENTS.md) wird
+gecacht. Cache-Miss = der ganze Kontext wird uncached neu gelesen.
+
+- **Stabilen Präfix stabil halten.** `AGENTS.md`, `CLAUDE.md` und Projekt-Config
+  **nicht mitten in einer Arbeitssession editieren**. Änderungen sammeln und in
+  einem eigenen Durchgang machen.
+- **Keine Ketten kurzer Pausen.** Einzelne lange Pause (> 5 min) = ein Cache-Miss.
+  Viele kurze „warte-mal-kurz"-Turns mit Lücken > 5 min = jedes Mal ein neuer Miss.
+  Bei externem Warten (CI, Deploy): **einmal** lang warten statt mehrfach pollen.
+- **Eine Session pro Thema** (interagiert direkt mit Cache): frischer Thread = kleiner,
+  vollständig gecachter Präfix.
+
+---
+
+## Schnell-Check vor einer langen Session
+
+- [ ] Einzelnes Thema? Wenn nein → splitten.
+- [ ] AGENTS.md-Änderungen anstehend? → **vorher** erledigen, dann stabil lassen.
+- [ ] Lange Wartezeiten erwartet (CI/Build)? → Hintergrund-Job + **einmal** warten.