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>
2026-06-03 06:55:39 +02:00
commit efee259d01
43 changed files with 1563 additions and 0 deletions
--- a/.github/workflows/gates.yml
+++ b/.github/workflows/gates.yml
@@ -0,0 +1,16 @@
+name: gates
+on: [push, pull_request]
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - name: Session-Hygiene-Gate
+        run: bash scripts/gate-session-hygiene.sh
+      - name: Ownership-Gate
+        run: bash scripts/gate-ownership.sh
+      - name: Doku-Drift-Gate
+        run: bash scripts/gate-doc-drift.sh
+      - name: Metriken sammeln
+        run: bash scripts/metrics.sh
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+.env
+*.log
+logs/
+.DS_Store
+.idea/
+.vscode/
+# metrics/*.csv wird bewusst getrackt — die Observability-Story braucht den Trend.
+
+# --- Jetson AI / Ollama spezifisch ---
+*.gguf
+models/
+.dvc/cache/
+.dvc/tmp/
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,38 @@
+# AGENTS.md — Einstiegspunkt für jede Session
+
+> **Lies dies zuerst. Lies NICHT das ganze Repo.** Orientiere dich in dieser
+> Reihenfolge und höre auf, sobald du genug Kontext für deine Aufgabe hast.
+
+## Lese-Reihenfolge (klarer Start)
+1. **Dieses Dokument** — wer macht was, wo steht was.
+2. **`STATE.md`** — *wo wir gerade stehen* (Now / In Progress / Blocked / Next /
+   offene Audit-Findings). Die einzige Quelle für den aktuellen Stand.
+3. **`CONVENTIONS.md`** — verbindliche Regeln (Naming, Pfade, Commits, Ownership,
+   Model-Attribution, Review-Gate).
+4. **Deine Rollen-Datei** — `docs/roles/{leader,worker,reviewer}.md`.
+   Welches Modell für welche Arbeit: `docs/roles/model-routing.md`.
+5. **Die relevante Loop-Datei** — `docs/loops/{feature,audit}-loop.md`.
+   Bei Research-Items: `docs/loops/spike-gate.md`.
+6. **Dein Session-Prompt** — `session-prompts/` (fertig ausgefüllter Prompt für
+   diese Session — kein Lesen des ganzen Repos nötig).
+7. Nur bei Bedarf: `manifests/requirements.md`, betroffene ADRs, Code.
+
+## Wo finde ich was?
+| Frage | Datei |
+|---|---|
+| Aktueller Stand / nächster Schritt | `STATE.md` |
+| Regeln & gemeinsamer Vertrag | `CONVENTIONS.md` |
+| Plan / Board / Ready-Set (DAG) | `ROADMAP.md` |
+| Befülltes Beispiel zum Lernen | `examples/walkthrough/` |
+| Warum wurde X so entschieden | `docs/adr/` |
+| Anforderung → Datei → Test → Status | `manifests/requirements.md` |
+| Was hat die letzte Session getan | `sessions/` (neuester Eintrag) |
+| Offene Prüf-Befunde + Model-Zuweisung | `audits/` |
+| Welches Modell für welche Arbeit | `docs/roles/model-routing.md` |
+| Kaltstartfähige Session-Prompts | `session-prompts/` |
+| Token-Kosten kontrollieren | `docs/token-hygiene.md` |
+
+## Pflicht am Session-Ende
+- `STATE.md` aktualisieren · Session-Log aus `sessions/TEMPLATE.md` anlegen
+  (inkl. **Token-Verbrauch** + Model-Attribution) · betroffene Manifeste/Docs anpassen ·
+  Quality-Gate ausführen (`scripts/gate-session-hygiene.sh`).
--- a/CONVENTIONS.md
+++ b/CONVENTIONS.md
@@ -0,0 +1,64 @@
+# CONVENTIONS.md — gemeinsamer Vertrag
+
+Verbindlich für **alle** Aktoren. Änderungen nur per ADR.
+
+## Ownership
+- **Kein Paket editiert Dateien eines anderen.** Integration & Konfliktlösung
+  ausschließlich durch den Leader.
+- Jede Datei hat genau ein zuständiges Worker-Paket (siehe `STATE.md`).
+
+## Git & Commits
+- Branch je Paket: `feat/<paket>`, `audit/<scope>`, `fix/<scope>`.
+- **Conventional Commits:** `feat:`, `fix:`, `docs:`, `test:`, `refactor:`,
+  `chore:`. Der Git-Log ist Teil der Dokumentation.
+- **Model-Attribution:** jeder Commit eines Agenten enthält einen Trailer:
+  `Co-Authored-By: Claude <Tier> <noreply@anthropic.com>`
+  Tier = Capability-Bezeichnung des eingesetzten Modells, z. B. „Sonnet 4.6"
+  für mittlere Kapazität oder „Opus 4.8" für maximale — nicht der interne
+  Modell-Name. Gilt für das zum Commit-Zeitpunkt eingesetzte Modell.
+  Ermöglicht nachträgliche Rückverfolgung welche Kapazitätsstufe was entschieden hat.
+
+## Review-Gate
+- **Jede Implement-Session wird von einer separaten high-capacity-Session reviewed**
+  (aktuell: Opus-Tier). Der Review läuft kalt (eigene Session, kein Vorkontext),
+  prüft den Diff, und gibt APPROVE oder CHANGES-REQUESTED zurück.
+- Implement-Kapazitätsstufe ≠ Review-Kapazitätsstufe: ein Modell, das sich selbst
+  reviewed, findet systematisch weniger als ein unabhängiger Pass auf höchster Stufe.
+- Konkrete Tier-Zuordnungen: `docs/roles/model-routing.md`.
+- Review-Gate-Checkliste: `docs/roles/reviewer.md`.
+
+## Dokumentation
+- **Single Source of Truth** je Information — keine Duplikate über Docs hinweg.
+- Doku ist knapp: ein Dokument, das man nicht mehr liest, driftet. Größenbudget
+  pro Doc beachten (Faustregel < 200 Zeilen).
+- Jede Code-Änderung passt das passende Doc + Manifest **in derselben Session** an.
+
+## Definition of Done
+1. Manifest-Eintrag (`manifests/requirements.md`) mit Test + Status `done`.
+2. Tests grün. 3. Docs aktuell. 4. `STATE.md` aktualisiert.
+5. Session-Log geschrieben. 6. Quality-Gate `PASS`.
+
+## Projekt-Vertrag: Jetson AI / Ollama
+Verbindlich für alle Worker — Single Source of Truth dieser Werte. Änderungen nur per ADR.
+
+- **Hardware:** Jetson Orin Nano Super 8 GB (~7,4 GB nutzbar). Single-User → latenz-,
+  nicht durchsatzgebunden. Kein Batching, keine Inferenz-Skalierung.
+- **Profilnamen (Ollama-Modellnamen):** `qwen-light`, `gemma`, `qwen-heavy`.
+- **Pfade:** GGUF unter `/opt/jetson-ai/models/<name>.gguf`; Ollama-Store
+  `/opt/ollama/models` (nur Laufzeit-Cache).
+- **Ports / Endpoints:** Ollama `11434` (OpenAI `/v1/chat/completions`, Status
+  `/api/ps`); Exporter `/metrics` auf Port `8000`.
+- **Daemon-Env (in `ollama/systemd/ollama.service.d/override.conf`):**
+  `OLLAMA_FLASH_ATTENTION=1`, `OLLAMA_KV_CACHE_TYPE=q8_0`,
+  `OLLAMA_MAX_LOADED_MODELS=1` (genau ein Modell resident, 8-GB-Schutz),
+  `OLLAMA_KEEP_ALIVE=30s`, `OLLAMA_MODELS=/opt/ollama/models`,
+  `OLLAMA_HOST=0.0.0.0:11434` (nur LAN, Firewall auf den Proxy beschränken).
+- **`num_ctx` je Modelfile explizit** (Ollama kürzt sonst still): light/gemma 16384,
+  heavy 8192.
+- **Env-Variablen Single Source:** `.env.example` — nur Platzhalter, **nie Secrets**.
+- **DVC = Modell-Source-of-Truth.** `build-models.sh` baut alle drei Profile
+  reproduzierbar aus den DVC-getrackten GGUFs.
+- **Scope-Grenze (out of repo):** nginx-Reverse-Proxy (TLS + OAuth) und
+  Prometheus/Grafana laufen **off-box**. Ollama hat **keine eigene Auth** → nie
+  direkt ins Internet binden.
+- **Code:** Type Hints, Docstrings.
--- a/README.md
+++ b/README.md
@@ -0,0 +1,46 @@
+# Jetson AI / Ollama (MLOps)
+
+Lokal laufendes **Single-User-AI-System** auf einem **Jetson Orin Nano Super (8 GB)**:
+Ollama-Daemon serviert drei Modell-Profile (OpenAI-kompatibel), ein schlanker
+Exporter-Sidecar exponiert `/metrics`. Modellwechsel passiert **nativ über den
+Modellnamen** — kein eigener Swapper, kein Gateway (siehe `docs/adr/0002-ollama-native.md`).
+
+- **Profile:** `qwen-light` (Daily-Driver) · `gemma` (Creative/Chat, multimodal) ·
+  `qwen-heavy` (harte Reasoning-Fälle). `OLLAMA_MAX_LOADED_MODELS=1` hält genau ein
+  Modell resident → drei Profile sind quasi gratis.
+- **Optimierung:** `q8_0`-KV-Cache + Flash Attention, `num_ctx` je Profil explizit.
+- **Daten:** DVC ist Modell-Source-of-Truth; Ollamas Blob-Store nur Laufzeit-Cache.
+
+> **Scope:** Dieses Repo deckt **nur den Jetson** ab. nginx (TLS + OAuth) und
+> Prometheus/Grafana laufen off-box. Ollama hat keine eigene Auth → nur ans LAN
+> binden, Firewall auf den Proxy. Voller Vertrag: [`CONVENTIONS.md`](CONVENTIONS.md).
+
+---
+
+## Arbeitsmodell (agent-swarm)
+Dieses Repo wurde aus dem **agent-swarm-Template** gebootstrapt: ein Leader/Worker-
+Agentensystem, dessen Stand komplett auf Disk lebt — kalt lesbar ohne Vorkontext.
+Methodik: [`docs/methodology.md`](docs/methodology.md) · Herkunft:
+[`docs/about-template.md`](docs/about-template.md).
+
+| Wo | Datei |
+|---|---|
+| Stand & nächster Schritt | [`STATE.md`](STATE.md) |
+| Plan / Board / Ready-Set (DAG) | [`ROADMAP.md`](ROADMAP.md) |
+| Gemeinsamer Vertrag | [`CONVENTIONS.md`](CONVENTIONS.md) |
+| Kalt-Review-Einstieg | [`REVIEW.md`](REVIEW.md) |
+| Dispatch-fertige Worker-Prompts | [`session-prompts/`](session-prompts/) |
+
+## Sofort bauen
+Die Planung ist fertig (W1–W6 im Board). So baust du es:
+
+1. **W1 zuerst** — frische Session öffnen, Modell **Sonnet**, Inhalt von
+   [`session-prompts/W1.md`](session-prompts/W1.md) einfügen → legt das Grundgerüst an.
+2. **Review-Gate** (Opus, kalt) → mergen → W1 im Board auf `✅`.
+3. **W2–W5 parallel** — je eigene Session (`session-prompts/W2.md` … `W5.md`),
+   disjunkte Datei-Ownership, laufen unabhängig.
+4. **W6 zuletzt** — Docs, integriert die Realität der anderen Pakete.
+
+Jeder Worker-Prompt ist self-contained (Modell, Branch, Dateien, Akzeptanzkriterien,
+Abschluss-Gates). Die Gates (`scripts/gate-*.sh`) sind aktiv und prüfen Ownership,
+Hygiene und Doku-Drift bei jedem Schritt.
--- a/REVIEW.md
+++ b/REVIEW.md
@@ -0,0 +1,29 @@
+# REVIEW — Kalt-Review-Einstieg
+
+Dieses Repo ist so gebaut, dass ein Reviewer **ohne jeden Vorkontext** in einer
+frischen Session verifizieren kann, ob alles stimmt. Du musst nichts glauben —
+führe die Prüfbefehle aus.
+
+## In dieser Reihenfolge
+1. **`AGENTS.md` → `STATE.md` → `CONVENTIONS.md`** lesen. Kannst du dich allein
+   damit orientieren? (Wenn nein → erstes Finding.)
+2. **`manifests/requirements.md`** ist das Verifikations-Manifest: je Erfolgs-
+   kriterium eine Zeile *Anforderung → Datei(en) → Prüfbefehl → Status*. Gehe es
+   Zeile für Zeile durch und führe den Prüfbefehl jeder `done`-Zeile aus.
+3. **Tests kodieren die Kriterien** (Modelfile-Build, Endpoint-Smoke) — ausführen
+   statt glauben: `pytest tests/ -q`.
+4. **Git-Log** (Conventional Commits + Model-Attribution) erzählt die Reihenfolge.
+
+## Automatische Gates (lokal lauffähig)
+```bash
+bash scripts/gate-session-hygiene.sh   # STATE/Session-Log/Commits sauber?
+bash scripts/gate-ownership.sh         # kein Cross-Editing über Paket-Grenzen?
+bash scripts/gate-doc-drift.sh         # done-Zeilen belegen ihre Dateien?
+```
+
+## Was „fertig" heißt
+Alle Zeilen in `manifests/requirements.md` auf `done`, ihre Prüfbefehle grün,
+`tests/` grün, die drei Gates `PASS`. Die Erfolgskriterien selbst stehen — Single
+Source of Truth — im Manifest und in `CONVENTIONS.md` (Projekt-Vertrag), nicht hier.
+
+> Reviewer-Rolle und Checkliste im Detail: `docs/roles/reviewer.md`.
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -0,0 +1,41 @@
+# ROADMAP — Board & Ready-Set  (Jetson AI / Ollama)
+
+Eingang des Feature-Loops **und** der Abhängigkeits-DAG. Der Leader berechnet jeden
+Zyklus das **Ready-Set** und dispatcht nur daraus.
+
+> **ROADMAP vs. STATE:** ROADMAP = der ganze geplante Graph. `STATE.md` = was
+> *gerade jetzt* läuft. Item wandert: `🔲` → beim Dispatch in STATE „In Progress" →
+> bei Merge zurück als `✅` in „Done".
+
+## Legende
+- **Typ:** 🔌 port · 🔬 research · 🧱 infra
+- **Status:** ✅ done · 🔲 ready · ⏸ blocked-by-prereq · ⛔ blocked-extern
+
+## Ready-Set-Regel
+```
+Ready-Set = { Items mit 🔲, deren Prereqs ALLE ✅ }   →   aktuell: { W1 }
+```
+1. Ready-Set bilden. 2. Modell aus `docs/roles/model-routing.md`. 3. Prompt aus
+`session-prompts/<ID>.md`. 4. Worker bauen. 5. Review-Gate (hoch) → Merge → ✅.
+
+> **Dieses Projekt ist rein 🧱 infra/config** — kein 🔬-Item, daher kein Spike-Gate.
+> Die Kopplung der Pakete läuft ausschließlich über `CONVENTIONS.md`.
+
+## Board
+| ID | Item | Typ | Status | Prereqs | Rolle · Tier | Aufwand |
+|----|------|-----|--------|---------|--------------|---------|
+| W1 | Grundgerüst: Struktur, README-Skelett, LICENSE, `.gitignore`, `.env.example` | 🧱 | 🔲 | — | Worker · mittel | ~0.5 d |
+| W2 | Ollama-Profile: Modelfiles light/gemma/heavy, systemd-override, `build-models.sh`, DVC | 🧱 | ⏸ | W1 | Worker · mittel | ~1 d |
+| W3 | Exporter-Sidecar: `/metrics`:8000 + systemd-Service | 🧱 | ⏸ | W1 | Worker · mittel | ~0.5 d |
+| W4 | Setup & CI/CD: `setup-jetson.sh`, `benchmark.sh`, Workflows | 🧱 | ⏸ | W1 | Worker · mittel | ~1 d |
+| W5 | Client & Tests: `client/`, `tests/`, Requirements | 🧱 | ⏸ | W1 | Worker · mittel | ~1 d |
+| W6 | Docs: architecture/api/deployment/troubleshooting + README-Finalisierung | 🧱 | ⏸ | W2,W3,W4,W5 | Scholar · klein | ~0.5 d |
+
+**Wellen:** W1 zuerst (alleine) → dann **W2–W5 parallel** (disjunkte Ownership,
+nur über `CONVENTIONS.md` gekoppelt) → W6 zuletzt (integriert die Realität der
+anderen). Session-Prompts liegen fertig unter `session-prompts/W1…W6.md`.
+
+## Done
+| ID | Item | Session | Commit |
+|----|------|---------|--------|
+| — | _(noch nichts gemerged — W1 ist als nächstes dran)_ | — | — |
--- a/STATE.md
+++ b/STATE.md
@@ -0,0 +1,35 @@
+# STATE — aktueller Stand  (Jetson AI / Ollama)
+
+> Live-Ebene. Was *jetzt* läuft. Plan steht im Board (`ROADMAP.md`).
+
+**Letzte Session:** bootstrap / 2026-06-03 · **Aktive Rolle:** leader
+
+## Now (in dieser Session im Fokus)
+- Bootstrap fertig (Planung). Nächster Dispatch: **W1 Grundgerüst** (`session-prompts/W1.md`).
+
+## In Progress (begonnen, nicht fertig)
+- _(keine — alles geplant, noch nichts gebaut)_
+
+## Blocked
+- W2–W5 — warten auf W1 (Grundgerüst). `⏸`
+- W6 (Docs) — wartet auf W2–W5. `⏸`
+
+## Next (priorisiert)
+1. W1 dispatchen (Worker · mittel).
+2. Nach W1-Merge: W2, W3, W4, W5 **parallel** dispatchen (disjunkte Ownership).
+3. Zuletzt W6 (Scholar · klein).
+
+## Offene Audit-Findings
+- _(keine — Projekt frisch gebootstrapt)_
+
+## Datei-Ownership (aktiv)
+> Verzeichnis-Pfade mit Slash beenden (das prüft `scripts/gate-ownership.sh`).
+> W1 läuft sequentiell zuerst und legt das Grundgerüst an; ab dann gilt:
+
+| Paket | Dateien/Pfade | Owner |
+|---|---|---|
+| W2 | `ollama/`, `scripts/build-models.sh`, `.dvc/` | worker-w2 |
+| W3 | `exporter/`, `requirements/exporter.txt` | worker-w3 |
+| W4 | `scripts/setup-jetson.sh`, `scripts/benchmark.sh`, `.github/workflows/` | worker-w4 |
+| W5 | `client/`, `tests/`, `requirements/client.txt`, `requirements/dev.txt` | worker-w5 |
+| W6 | `docs/architecture.md`, `docs/api.md`, `docs/deployment.md`, `docs/troubleshooting.md` | worker-w6 |
--- a/audits/README.md
+++ b/audits/README.md
@@ -0,0 +1,4 @@
+# audits/
+
+Befunde des externen Reviewers: `YYYY-MM-DD-<scope>.md` aus `TEMPLATE.md`.
+Jeder Befund mit Severity; Korrektur-Tasks wandern nach `ROADMAP.md`/`STATE.md`.
--- a/audits/TEMPLATE.md
+++ b/audits/TEMPLATE.md
@@ -0,0 +1,15 @@
+# Audit <scope> — <YYYY-MM-DD>
+
+- **Reviewer-Session:** kalt (kein Vorkontext)
+- **Orientierung allein aus AGENTS/STATE/CONVENTIONS gelungen?** Ja/Nein
+
+## Befunde
+| # | Typ (drift/hygiene/untested) | Beschreibung | Severity | Korrektur-Task |
+|---|------------------------------|--------------|----------|----------------|
+| 1 | _…_ | _…_ | low/med/high | _Roadmap-/STATE-Eintrag_ |
+
+## Verifikation
+- Manifest geprüft: _…_ · Tests ausgeführt: _… -> Ergebnis_
+
+## Empfehlung
+- _Audit-Loop weiter / Feature-Loop freigegeben._
--- a/docs/about-template.md
+++ b/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`.
--- a/docs/adr/0001-record-architecture-decisions.md
+++ b/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.
--- a/docs/adr/0002-ollama-native.md
+++ b/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)_
--- a/docs/adr/README.md
+++ b/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.
--- a/docs/gates/observability-gates.md
+++ b/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.
--- a/docs/gates/quality-gates.md
+++ b/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).
--- a/docs/loops/audit-loop.md
+++ b/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.
--- a/docs/loops/feature-loop.md
+++ b/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`.
--- a/docs/loops/spike-gate.md
+++ b/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).
--- a/docs/methodology.md
+++ b/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`.
--- a/docs/roles/leader.md
+++ b/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.
--- a/docs/roles/model-routing.md
+++ b/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`.
--- a/docs/roles/reviewer.md
+++ b/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.
--- a/docs/roles/worker.md
+++ b/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".
--- a/docs/token-hygiene.md
+++ b/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.
--- a/manifests/requirements.md
+++ b/manifests/requirements.md
@@ -0,0 +1,20 @@
+# Requirements-Manifest (kalt verifizierbar)
+
+Eine Zeile je Erfolgskriterium — der **kalt lesbare Review** (siehe `REVIEW.md`).
+Der Reviewer prüft Spalte für Spalte; `done`-Zeilen müssen ihren Prüfbefehl bestehen.
+`scripts/gate-doc-drift.sh` erzwingt die Existenz der Pfade in `done`/`in_progress`-Zeilen.
+
+| ID | Anforderung | Datei(en) | Test/Prüfbefehl | Status |
+|----|-------------|-----------|------------------|--------|
+| R-01 | Vertrag zuerst: CONVENTIONS + disjunkte Ownership | `CONVENTIONS.md`, `STATE.md` | `grep -q qwen-light CONVENTIONS.md` | done |
+| R-02 | Drei Profile über Modelfiles (light/gemma/heavy) | `ollama/Modelfile.light`, `ollama/Modelfile.gemma`, `ollama/Modelfile.heavy` | `pytest tests/test_modelfiles.py` | todo |
+| R-03 | q8_0-KV + Flash Attention + MAX_LOADED_MODELS=1 | `ollama/systemd/ollama.service.d/override.conf` | `grep -Eq 'q8_0' ollama/systemd/ollama.service.d/override.conf` | todo |
+| R-04 | num_ctx je Profil explizit (light/gemma 16384, heavy 8192) | `ollama/Modelfile.light`, `ollama/Modelfile.heavy` | `grep -q 'num_ctx' ollama/Modelfile.light` | todo |
+| R-05 | GPU-Nutzung verifiziert; Ollama nur LAN + Firewall | `scripts/setup-jetson.sh` | `bash -n scripts/setup-jetson.sh` | todo |
+| R-06 | Metrik-Endpoint über Exporter (`:8000/metrics`) | `exporter/systemd/ollama-exporter.service` | `pytest tests/test_endpoints.py` | todo |
+| R-07 | Keine Secrets; `.env.example` nur Platzhalter | `.env.example` | `grep -q 'JETSON_LAN_IP=' .env.example` | todo |
+| R-08 | DVC = Modell-Source-of-Truth; build reproduzierbar | `scripts/build-models.sh`, `.dvc/config` | `bash -n scripts/build-models.sh` | todo |
+| R-09 | Client + CLI funktionsfähig (OpenAI-kompatibel) | `client/python/jetson_ai/client.py`, `client/cli/ai.py` | `pytest tests/` | todo |
+| R-10 | Kalt verifizierbar; Tests kodieren Kriterien | `REVIEW.md`, `tests/test_endpoints.py` | `pytest tests/ -q` | todo |
+
+Status: `todo` · `in_progress` · `done` · `drift` (vom Audit markiert).
--- a/metrics/efficiency.csv
+++ b/metrics/efficiency.csv
@@ -0,0 +1,2 @@
+date,sessions,rework_commits,total_commits
+2026-06-03,0,0,0
--- a/scripts/gate-doc-drift.sh
+++ b/scripts/gate-doc-drift.sh
@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Doku-Drift-Gate: prueft Manifest-Referenzen + STATE-Aktualitaet + Doc-Budget.
+set -uo pipefail
+fail=0; man="manifests/requirements.md"
+
+# Dormant solange das Template nicht initialisiert ist (scripts/init.sh).
+if grep -q '<id / datum>' STATE.md 2>/dev/null; then
+  echo "[drift] Template noch nicht initialisiert (scripts/init.sh) — uebersprungen."
+  echo "GATE: PASS"; exit 0
+fi
+
+echo "[drift] pruefe im Manifest referenzierte Pfade (nur done/in_progress/drift)..."
+# Nur Pfade aus ERLEDIGTEN Zeilen muessen existieren — 'todo'-Zeilen sind Plan,
+# ihre Dateien gibt es absichtlich noch nicht. Treffer in eine Datei sammeln,
+# damit fail=1 nicht in einer Pipe-Subshell verloren geht.
+miss=$(mktemp)
+if [ -f "$man" ]; then
+  while IFS= read -r line; do
+    case "$line" in \|*) : ;; *) continue ;; esac   # nur Tabellenzeilen
+    status=$(printf '%s' "$line" | sed 's/^|//; s/|[[:space:]]*$//' \
+             | awk -F'|' '{print $NF}' | tr -d ' ' | tr 'A-Z' 'a-z')
+    case "$status" in done|in_progress|drift) : ;; *) continue ;; esac
+    while IFS= read -r tok; do
+      case "$tok" in *" "*|*…*|_*|*path/to*) continue ;; esac
+      case "$tok" in
+        */*|*.py|*.md|*.sh|*.js|*.ts|*.yml|*.yaml|*.json|*.conf|*.ini|*.txt)
+          [ -e "$tok" ] || echo "$status	$tok" >> "$miss" ;;
+      esac
+    done < <(printf '%s\n' "$line" | grep -oE '`[^`]+`' | tr -d '`')
+  done < "$man"
+fi
+if [ -s "$miss" ]; then
+  while IFS="	" read -r st p; do echo "  - fehlende Referenz (Status $st): $p"; done < "$miss"
+  fail=1
+fi
+rm -f "$miss"
+
+echo "[drift] STATE.md Stale-Check (Commits seit letzter Aenderung)..."
+last_state=$(git log -1 --format=%H -- STATE.md 2>/dev/null || true)
+if [ -n "$last_state" ]; then
+  since=$(git rev-list --count "${last_state}..HEAD" 2>/dev/null || echo 0)
+  [ "${since:-0}" -le 3 ] || { echo "  - STATE.md seit $since Commits unveraendert"; fail=1; }
+fi
+
+echo "[drift] Doc-Groessenbudget (Faustregel < 200 Zeilen)..."
+while read -r f; do
+  case "$f" in examples/*) continue ;; esac   # Beispiele duerfen laenger sein
+  n=$(wc -l < "$f" 2>/dev/null || echo 0)
+  [ "$n" -le 200 ] || echo "  - Hinweis: $f hat $n Zeilen (> 200, Drift-Risiko)."
+done < <(git ls-files 2>/dev/null | grep '\.md$' || true)
+
+echo "[drift] Code ohne Doc-Aenderung im letzten Commit?"
+files=$(git show --name-only --pretty= HEAD 2>/dev/null || true)
+if echo "$files" | grep -qE '\.(py|sh|js|ts)$' && ! echo "$files" | grep -qE '\.md$'; then
+  echo "  - Hinweis: Code geaendert, keine Doku angepasst (Drift-Verdacht)."
+fi
+
+[ "$fail" -eq 0 ] && echo "GATE: PASS" || { echo "GATE: FAIL"; exit 1; }
--- a/scripts/gate-ownership.sh
+++ b/scripts/gate-ownership.sh
@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Ownership-Gate: kein Paket editiert Dateien eines anderen.
+# Liest die Ownership-Tabelle aus STATE.md, mappt geaenderte Dateien (Branch vs.
+# Basis) auf Pakete und FAILt bei Cross-Editing ueber >1 Paket-Grenze hinweg.
+# Integration (Leader) ist ausgenommen: Branch main/master/integrate/*.
+# Konvention: Verzeichnis-Pfade in der Tabelle mit Slash beenden (src/api/).
+# Portabel gehalten (kein mapfile / keine assoziativen Arrays, laeuft auf bash 3.2).
+set -uo pipefail
+
+# Dormant solange das Template nicht initialisiert ist.
+if grep -q '<id / datum>' STATE.md 2>/dev/null; then
+  echo "[ownership] Template noch nicht initialisiert — uebersprungen."
+  echo "GATE: PASS"; exit 0
+fi
+
+branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+case "$branch" in
+  main|master|integrate/*)
+    echo "[ownership] '$branch' ist Integrations-Branch — uebersprungen."
+    echo "GATE: PASS"; exit 0 ;;
+esac
+
+# (pkg<TAB>prefix)-Zeilen aus der STATE.md-Ownership-Tabelle ziehen.
+pairs=$(awk -F'|' '
+  /Datei-Ownership/{f=1; started=0; next}
+  f && started && $0 !~ /^\|/ {f=0}            # erst NACH Tabellenbeginn abbrechen
+  f && /^\|/{
+    started=1;
+    pkg=$2; paths=$3;
+    gsub(/^[ \t]+|[ \t]+$/,"",pkg);
+    if(pkg=="" || pkg=="Paket" || pkg ~ /---/ || pkg ~ /…/ || pkg ~ /^_/) next;
+    n=split(paths, a, ",");
+    for(i=1;i<=n;i++){ p=a[i]; gsub(/^[ \t]+|[ \t]+$/,"",p); gsub(/`/,"",p);
+      if(p=="" || p ~ /…/ || p ~ /^_/) continue;
+      print pkg "\t" p }
+  }' STATE.md 2>/dev/null)
+
+if [ -z "$pairs" ]; then
+  echo "[ownership] keine befuellte Ownership-Tabelle in STATE.md — uebersprungen."
+  echo "GATE: PASS"; exit 0
+fi
+
+base=$(git merge-base HEAD main 2>/dev/null || git rev-parse HEAD~1 2>/dev/null || true)
+[ -n "$base" ] || { echo "[ownership] keine Diff-Basis — uebersprungen."; echo "GATE: PASS"; exit 0; }
+changed=$(git diff --name-only "$base"...HEAD 2>/dev/null)
+[ -n "$changed" ] || { echo "[ownership] keine Aenderungen — uebersprungen."; echo "GATE: PASS"; exit 0; }
+
+hit=""; unowned=""
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  bestpre=""; bestpkg=""
+  while IFS="	" read -r pkg pre; do
+    [ -n "$pre" ] || continue
+    case "$f" in
+      "$pre"|"$pre"*)
+        if [ "${#pre}" -gt "${#bestpre}" ]; then bestpre="$pre"; bestpkg="$pkg"; fi ;;
+    esac
+  done <<EOF
+$pairs
+EOF
+  if [ -n "$bestpkg" ]; then
+    hit="$hit$bestpkg
+"
+  else
+    unowned="$unowned $f"
+  fi
+done <<EOF
+$changed
+EOF
+
+distinct=$(printf '%s' "$hit" | sed '/^$/d' | sort -u)
+n=$(printf '%s' "$distinct" | sed '/^$/d' | grep -c . || true)
+echo "[ownership] Branch '$branch' beruehrt $n Paket(e): $(printf '%s ' $distinct)"
+[ -n "$unowned" ] && echo "[ownership] Hinweis: ohne Owner in STATE.md:$unowned"
+
+if [ "${n:-0}" -gt 1 ]; then
+  echo "  - FAIL: Aenderungen ueber mehrere Ownership-Grenzen (Cross-Editing)."
+  echo "    Worker editieren nur ihr Paket; Integration macht der Leader (Branch integrate/*)."
+  echo "GATE: FAIL"; exit 1
+fi
+echo "GATE: PASS"
--- a/scripts/gate-session-hygiene.sh
+++ b/scripts/gate-session-hygiene.sh
@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Session-Hygiene-Gate (Starter — an Repo anpassen).
+set -uo pipefail
+fail=0
+note(){ echo "  - $1"; fail=1; }
+
+# Dormant solange das Template nicht initialisiert ist (scripts/init.sh).
+if grep -q '<id / datum>' STATE.md 2>/dev/null; then
+  echo "[hygiene] Template noch nicht initialisiert (scripts/init.sh) — uebersprungen."
+  echo "GATE: PASS"; exit 0
+fi
+
+echo "[hygiene] pruefe Working Tree..."
+[ -z "$(git status --porcelain)" ] || note "Working Tree nicht sauber."
+
+echo "[hygiene] STATE.md im aktuellen Branch aktualisiert?"
+base=$(git merge-base HEAD main 2>/dev/null || true)
+head=$(git rev-parse HEAD 2>/dev/null || true)
+if [ -n "$base" ] && [ "$base" != "$head" ]; then
+  # echte Divergenz (Feature-Branch): Diff gegen Abzweigpunkt
+  git diff --name-only "$base"...HEAD | grep -q '^STATE.md$' || \
+    note "STATE.md im aktuellen Branch nicht aktualisiert."
+else
+  # auf main/Integration oder Root-Commit: letzten Commit pruefen
+  git log -1 --name-only --pretty= | grep -q '^STATE.md$' || \
+    note "STATE.md im letzten Commit nicht angefasst."
+fi
+
+echo "[hygiene] Session-Log vorhanden?"
+ls sessions/[0-9]*.md >/dev/null 2>&1 || note "Kein Session-Log unter sessions/."
+
+echo "[hygiene] Conventional Commits?"
+git log -1 --pretty=%s | grep -Eq '^(feat|fix|docs|test|refactor|chore)(\(.+\))?: ' || \
+  note "Letzter Commit nicht conventional."
+
+echo "[hygiene] Model-Attribution im letzten Commit?"
+git log -1 --pretty=%B | grep -q 'Co-Authored-By: Claude' || \
+  echo "  - Hinweis: letzter Commit ohne 'Co-Authored-By: Claude <Modell>' (Pflicht nur fuer Agenten-Commits)."
+
+if [ "$fail" -ne 0 ]; then echo "GATE: FAIL"; exit 1; fi
+echo "GATE: PASS"
--- a/scripts/init.sh
+++ b/scripts/init.sh
@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# init.sh — ein Template-Klon zu einem konkreten Projekt machen.
+# Nutzung:  bash scripts/init.sh "Mein Projektname"
+#
+# Was passiert:
+#   - die Template-README wandert nach docs/about-template.md (Methodik bleibt erhalten)
+#   - eine frische, projektbezogene README.md wird geschrieben
+#   - falls noch kein Git-Repo: git init
+#   - die Gates bleiben DORMANT, bis die erste echte Session STATE.md befuellt
+#     (die Zeile mit '<id / datum>' ersetzt) — danach greifen sie automatisch.
+#
+# Naechster Schritt nach init: session-prompts/BOOTSTRAP.md in eine frische
+# Leader-Session geben, zusammen mit deinem Projekt-Brief.
+set -euo pipefail
+
+name="${1:-}"
+if [ -z "$name" ]; then
+  echo "Nutzung: bash scripts/init.sh \"Projektname\"" >&2
+  exit 2
+fi
+
+[ -f AGENTS.md ] || { echo "Bitte aus dem Repo-Root ausfuehren (AGENTS.md nicht gefunden)." >&2; exit 1; }
+
+if [ -f docs/about-template.md ]; then
+  echo "Bereits initialisiert (docs/about-template.md existiert). Abbruch." >&2
+  exit 1
+fi
+
+# 1) Template-README bewahren, frische Projekt-README schreiben.
+git mv README.md docs/about-template.md 2>/dev/null || mv README.md docs/about-template.md
+cat > README.md <<EOF
+# ${name}
+
+> Arbeitet nach dem **agent-swarm**-Betriebsmodell. Jeder Agent (Mensch wie KI)
+> liest zuerst [\`AGENTS.md\`](AGENTS.md). Methodik im Detail:
+> [\`docs/methodology.md\`](docs/methodology.md). Herkunft des Modells:
+> [\`docs/about-template.md\`](docs/about-template.md).
+
+## Schnellstart
+- **Stand & nächster Schritt:** [\`STATE.md\`](STATE.md)
+- **Plan / Ready-Set:** [\`ROADMAP.md\`](ROADMAP.md)
+- **Regeln:** [\`CONVENTIONS.md\`](CONVENTIONS.md)
+- **Neues Feature anstoßen:** [\`session-prompts/BOOTSTRAP.md\`](session-prompts/BOOTSTRAP.md)
+EOF
+
+# 2) Git initialisieren, falls noetig.
+if ! git rev-parse --git-dir >/dev/null 2>&1; then
+  git init -q
+  echo "[init] leeres Git-Repo angelegt."
+fi
+
+echo "[init] '${name}' initialisiert."
+echo "[init] Template-Overview liegt jetzt unter docs/about-template.md."
+echo
+echo "Naechster Schritt:"
+echo "  1) Projekt-Brief bereithalten (Ziel, Stack, Constraints)."
+echo "  2) session-prompts/BOOTSTRAP.md in eine frische Session geben (Modell: Sonnet)."
+echo "  3) Der Leader fuellt ROADMAP/STATE/CONVENTIONS und erzeugt die ersten Session-Prompts."
+echo
+echo "Die Gates sind dormant, bis die erste Session STATE.md befuellt."
--- a/scripts/metrics.sh
+++ b/scripts/metrics.sh
@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# Observability: aggregiert Session-Logs + Git zu metrics/efficiency.csv
+set -uo pipefail
+mkdir -p metrics; out="metrics/efficiency.csv"
+echo "date,sessions,rework_commits,total_commits" > "$out"
+total=$(git rev-list --count HEAD 2>/dev/null || echo 0)
+rework=$(git log --pretty=%s | grep -Ec '^(fix|refactor)(\(.+\))?: ' || true)
+sess=$(ls sessions/[0-9]*.md 2>/dev/null | wc -l | tr -d ' ')
+echo "$(date +%F),$sess,$rework,$total" >> "$out"
+echo "[metrics] geschrieben nach $out"
+echo "  Rework-Rate: $rework/$total Commits"
--- a/session-prompts/BOOTSTRAP.md
+++ b/session-prompts/BOOTSTRAP.md
@@ -0,0 +1,61 @@
+# BOOTSTRAP — neues Projekt aufsetzen (Leader-Session)
+
+Kopiere den Block unten in eine **frische Session** (Modell: **Sonnet**) und hänge
+deinen Projekt-Brief an. Der Leader füllt das Repo aus dem Brief — du musst keine
+Datei von Hand anlegen.
+
+> Voraussetzung: einmalig `bash scripts/init.sh "Projektname"` gelaufen.
+
+---
+
+```
+Du bist der LEADER eines agent-swarm-Repos. Arbeite in _<absoluter Repo-Pfad>_.
+
+Lies in dieser Reihenfolge und höre auf, sobald du genug Kontext hast:
+AGENTS.md → STATE.md → CONVENTIONS.md → docs/methodology.md →
+docs/roles/{leader,model-routing}.md → docs/loops/feature-loop.md →
+ROADMAP.md (Board-Format) → examples/walkthrough/ (ein befülltes Beispiel).
+
+## Mein Projekt-Brief
+<<< HIER deinen Brief einfügen: Ziel, Tech-Stack, harte Constraints,
+    erste gewünschte Fähigkeit. 3–15 Zeilen reichen. >>>
+
+## Deine Aufgabe (nur Planung, noch kein Feature-Code)
+1. ROADMAP.md als Board befüllen: den Brief in Items zerlegen, jedes mit
+   Typ (🔌 port / 🔬 research / 🧱 infra), Status, Prereqs, Rolle·Modell, Aufwand.
+   Den Abhängigkeits-DAG explizit machen (was blockiert was).
+2. CONVENTIONS.md projektspezifisch ergänzen, falls nötig: Build-/Test-Befehl,
+   Branch-/Remote-Konventionen, Sprache. Bestehende Regeln NICHT verwässern.
+   Tragende Entscheidungen als ADR unter docs/adr/ festhalten.
+3. STATE.md auf den echten Startzustand setzen: die Header-Zeile mit einer echten
+   Session-ID/Datum füllen (ersetzt den '<id / datum>'-Platzhalter — DAS aktiviert
+   die Gates), Now/Next füllen, die Ownership-Tabelle für die ersten Pakete anlegen
+   (Verzeichnis-Pfade mit Slash beenden, z. B. `src/api/`).
+4. Für jedes Item aus dem aktuellen READY-SET (Status 🔲, alle Prereqs ✅) einen
+   kaltstartfähigen Prompt unter session-prompts/<ID>.md aus
+   session-prompts/TEMPLATE.md erzeugen — Modell gemäß docs/roles/model-routing.md.
+5. Ein Session-Log unter sessions/<datum>-bootstrap.md aus sessions/TEMPLATE.md
+   schreiben. Hygiene-Gate ausführen: bash scripts/gate-session-hygiene.sh.
+
+## Wichtig
+- Du PLANST und dispatcht — du baust die Features nicht selbst.
+- Research-Items (🔬) müssen vor Produktionscode durch das Spike-Gate
+  (docs/loops/spike-gate.md). Markiere sie entsprechend im Board.
+- Halte die Single-Source-of-Truth-Regel: keine Information doppelt ablegen.
+- Conventional Commit + Trailer
+  `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`.
+
+Am Ende: zeig mir das befüllte Board (ROADMAP.md) und das Ready-Set, und sag mir,
+welche Session-Prompts du erzeugt hast und in welcher Reihenfolge ich sie dispatchen
+sollte.
+```
+
+---
+
+## Danach (laufender Betrieb)
+
+1. Ready-Set aus `ROADMAP.md` lesen → einen Prompt aus `session-prompts/` nehmen.
+2. Frische Session, Modell setzen, dispatchen (Worker bzw. Theorist→Spike).
+3. Nach Implement: **Review-Gate** (Opus, kalt) — Prompt-Block in
+   `session-prompts/TEMPLATE.md`.
+4. Merge → Item im Board auf ✅ → Dependents werden frei. Nach N Zyklen: Audit-Loop.
--- a/session-prompts/TEMPLATE.md
+++ b/session-prompts/TEMPLATE.md
@@ -0,0 +1,77 @@
+# Session-Prompt-Template
+
+Kopiere diesen Block in eine frische Session. Fülle alle `_…_`-Platzhalter aus.
+Jeder Prompt ist **kaltstartfähig** — die neue Session braucht kein Vorwissen.
+
+---
+
+```
+Modell: _Haiku | Sonnet | Opus_
+
+Du arbeitest in _<absoluter Pfad zum Repo>_ auf einem neuen Branch
+`_feat|fix|docs|audit/<name>_` (von `main`).
+
+## Aufgabe
+_Kurze Beschreibung (1–3 Sätze) was implementiert, geprüft oder dokumentiert
+werden soll. Scope klar abgrenzen — was liegt AUSSERHALB dieser Session?_
+
+## Details
+Vollständige Spezifikation in: `_<Pfad zum Detail-Dokument>_`
+Betroffene Dateien: `_<Pfad(e)>_`
+
+## Akzeptanzkriterien
+- [ ] _Kriterium 1 (messbar, konkret)_
+- [ ] _Kriterium 2_
+- [ ] Tests grün: `_<Test-Befehl>_`
+
+## Nicht anfassen
+_Dateien / Pakete ausserhalb des Scopes. Kein Cross-Editing._
+
+## Commit & Push
+- Conventional Commit: `_feat|fix|docs|test|chore_: …`
+- Trailer: `Co-Authored-By: Claude _<Modell>_ <noreply@anthropic.com>`
+- Push nach `origin`, PR öffnen (Base: `main`).
+
+## Abschluss
+1. Manifest-Eintrag updaten (`manifests/requirements.md` → Status `done`).
+2. `STATE.md` aktualisieren (Now / In Progress / Next).
+3. Session-Log schreiben (`sessions/TEMPLATE.md` → `sessions/<id>-<datum>.md`).
+4. Hygiene-Gate ausführen: `bash scripts/gate-session-hygiene.sh`.
+5. PR-URL + Test-Zählstand reporten.
+```
+
+---
+
+## Review-Gate-Prompt (Opus, kalt, nach jeder Implement-Session)
+
+```
+Modell: Opus
+
+Du bist ein externer Reviewer ohne Vorkontext aus der Implement-Session.
+Lies NUR den Diff von Branch `_<branch>_` gegen `main`.
+
+Repo: _<absoluter Pfad>_
+Diff: `git diff main..._<branch>_`
+
+## Prüf-Checkliste
+- [ ] Build sauber; Test-Suite grün (kein Regressions-Zählstand).
+- [ ] Keine bestehenden Tests verändert (außer 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 — alles ok.
+CHANGES-REQUESTED — konkrete Liste der notwendigen Korrekturen.
+```
+
+---
+
+## Hinweise zum Befüllen
+
+- **Scope zuerst** — was liegt AUSSERHALB? Das verhindert Scope-Creep.
+- **Test-Befehl ist Pflicht** — kein "irgendwie testen", sondern der exakte Aufruf.
+- **Model-Routing prüfen** — falsches Modell ist teuer; s. `docs/roles/model-routing.md`.
+- **Kein Vorkontext annehmen** — der Prompt landet in einer frischen Session ohne
+  History. Alle nötigen Pfade, Befehle und Entscheidungen müssen im Prompt stehen.
--- a/session-prompts/W1.md
+++ b/session-prompts/W1.md
@@ -0,0 +1,41 @@
+# Session-Prompt — W1 Grundgerüst  (zuerst, alleine)
+
+```
+Modell: Sonnet
+
+Du bist WORKER für Paket W1 in /pfad/zu/jetson-ai-ollama, Branch `feat/w1-scaffold`
+(von `main`). Lies zuerst AGENTS.md → STATE.md → CONVENTIONS.md (Projekt-Vertrag).
+
+## Aufgabe
+Das Grundgerüst anlegen, auf das W2–W5 parallel aufsetzen. NUR Struktur + Basis-
+Dateien, KEINE Profil-/Exporter-/Client-Logik (das sind W2/W3/W5).
+
+## Deliverables (deine Dateien)
+- `LICENSE` — MIT, auf den Repo-Eigentümer.
+- `.env.example` — nur Platzhalter (keine Secrets):
+  `JETSON_LAN_IP=`, `OLLAMA_MODELS=/opt/ollama/models`, `PROMETHEUS_SCRAPE_TARGET=`.
+- Verzeichnis-Skelett mit `.gitkeep`, damit die Parallel-Worker andocken können:
+  `ollama/systemd/ollama.service.d/`, `exporter/systemd/`, `client/python/jetson_ai/`,
+  `client/cli/`, `scripts/`, `tests/`, `requirements/`, `docs/`, `models/`.
+- `.dvc/config` — leeres DVC-Remote-Skelett mit Kommentar, welches Remote (S3/MinIO/
+  SSH/NAS) einzutragen ist. (DVC-Init-Details gehören W2 — hier nur die Datei.)
+
+## Akzeptanzkriterien
+- [ ] `test -f LICENSE && test -f .env.example`
+- [ ] `grep -q 'JETSON_LAN_IP=' .env.example` (R-07)
+- [ ] Keine echten Werte/Secrets in `.env.example`.
+- [ ] Alle Skelett-Verzeichnisse existieren (mit `.gitkeep`).
+
+## Nicht anfassen
+README.md, CONVENTIONS.md, STATE.md, ROADMAP.md, docs/ (außer .gitkeep), und alle
+Dateien anderer Pakete. Keine Modelfiles, kein Exporter-Code, kein Client-Code.
+
+## Abschluss
+1. `manifests/requirements.md`: R-07 → `done`.
+2. `STATE.md`: W1 nach „In Progress" → nach Merge in „Done"; W2–W5 werden ready.
+3. Session-Log aus `sessions/TEMPLATE.md`.
+4. Commit `feat(w1): scaffold structure, LICENSE, .env.example` + Trailer
+   `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`.
+5. `bash scripts/gate-session-hygiene.sh && bash scripts/gate-ownership.sh`.
+6. PR (Base `main`) via Gitea-API. Dann Review-Gate (Opus).
+```
--- a/session-prompts/W2.md
+++ b/session-prompts/W2.md
@@ -0,0 +1,44 @@
+# Session-Prompt — W2 Ollama-Profile  (parallel, nach W1)
+
+```
+Modell: Sonnet
+
+Du bist WORKER für Paket W2 in /pfad/zu/jetson-ai-ollama, Branch `feat/w2-profiles`
+(von `main`, nach W1-Merge). Lies AGENTS.md → STATE.md → CONVENTIONS.md (Projekt-
+Vertrag = Single Source of Truth für Profilnamen, Pfade, Env, num_ctx).
+
+## Aufgabe
+Die drei Ollama-Profile reproduzierbar bauen lassen — über Modelfiles, systemd-
+Daemon-Env und ein Build-Skript, mit DVC als Modell-Source-of-Truth.
+
+## Deliverables (deine Dateien — Ownership: `ollama/`, `scripts/build-models.sh`, `.dvc/`)
+- `ollama/Modelfile.light` — `FROM /opt/jetson-ai/models/qwen3.5-4b-q4_k_m.gguf`,
+  `PARAMETER num_ctx 16384`, `PARAMETER temperature 0.7`.
+- `ollama/Modelfile.gemma` — Gemma-4-E4B GGUF, `num_ctx 16384`.
+- `ollama/Modelfile.heavy` — Qwen3.5-9B GGUF, `num_ctx 8192`.
+- `ollama/systemd/ollama.service.d/override.conf` — exakt die Env aus CONVENTIONS
+  (FLASH_ATTENTION=1, KV_CACHE_TYPE=q8_0, MAX_LOADED_MODELS=1, KEEP_ALIVE=30s,
+  MODELS=/opt/ollama/models, HOST=0.0.0.0:11434).
+- `scripts/build-models.sh` — `dvc pull` → `ollama create qwen-light -f …light`,
+  `ollama create gemma -f …gemma`, `ollama create qwen-heavy -f …heavy`. Idempotent.
+- `.dvc/config` finalisieren (Remote bleibt env-/platzhaltergesteuert).
+
+## Akzeptanzkriterien
+- [ ] `pytest tests/test_modelfiles.py` grün (W5 liefert den Test; bis dahin lokal:
+      `grep -q 'num_ctx 16384' ollama/Modelfile.light`). (R-02, R-04)
+- [ ] `grep -Eq 'q8_0' ollama/systemd/ollama.service.d/override.conf` und
+      `grep -q 'MAX_LOADED_MODELS=1'` (R-03).
+- [ ] `bash -n scripts/build-models.sh` ok; baut alle drei Profile (R-08).
+- [ ] num_ctx in JEDEM Modelfile explizit gesetzt.
+
+## Nicht anfassen
+`exporter/`, `client/`, `tests/`, `scripts/setup-jetson.sh`, `scripts/benchmark.sh`,
+`.github/`, `docs/`. Nur deine Ownership-Pfade.
+
+## Abschluss
+1. `manifests/requirements.md`: R-02, R-03, R-04, R-08 → `done`.
+2. `STATE.md` + Session-Log aktualisieren.
+3. Commit(s) `feat(w2): …` + Trailer `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`.
+4. `bash scripts/gate-session-hygiene.sh && bash scripts/gate-ownership.sh`.
+5. PR (Base `main`). Dann Review-Gate (Opus).
+```
--- a/session-prompts/W3.md
+++ b/session-prompts/W3.md
@@ -0,0 +1,39 @@
+# Session-Prompt — W3 Exporter-Sidecar  (parallel, nach W1)
+
+```
+Modell: Sonnet
+
+Du bist WORKER für Paket W3 in /pfad/zu/jetson-ai-ollama, Branch `feat/w3-exporter`
+(von `main`, nach W1-Merge). Lies AGENTS.md → STATE.md → CONVENTIONS.md.
+
+## Aufgabe
+Ollama hat keinen Prometheus-Endpoint. Bau einen schlanken Exporter-Sidecar, der die
+Ollama-API anzapft und `/metrics` auf Port 8000 exponiert — als systemd-Service.
+
+## Deliverables (Ownership: `exporter/`, `requirements/exporter.txt`)
+- `exporter/` — Exporter (Python). Quellen: Timing-Felder jeder Ollama-Antwort
+  (`eval_count`, `eval_duration`, `prompt_eval_duration`, `total_duration`) und
+  `/api/ps` (Modell, VRAM, Keep-Alive); optional `tegrastats`. Endpoint `:8000/metrics`.
+  Alternativ einen fertigen Exporter (z. B. `ghcr.io/norskhelsenett/ollama-metrics`)
+  als systemd-Unit verdrahten — dann ist `exporter/` dünn.
+- `exporter/systemd/ollama-exporter.service` — systemd-Unit (After=ollama.service).
+- `requirements/exporter.txt` — Laufzeit-Deps des Exporters.
+
+## Akzeptanzkriterien
+- [ ] `pytest tests/test_endpoints.py` deckt den `/metrics`-Smoke ab (W5 liefert den
+      Test; bis dahin lokal: Exporter startet, `curl :8000/metrics` liefert Prom-Format). (R-06)
+- [ ] systemd-Unit ist syntaktisch valide und referenziert Port 8000.
+- [ ] Liest NUR die Ollama-API/`/api/ps` — keine Modell-/Profil-Logik (das ist W2).
+
+## Nicht anfassen
+`ollama/`, `client/`, `scripts/`, `.github/`, `docs/`, `tests/`. Nur deine Pfade.
+(Den `tests/test_endpoints.py` schreibt W5 — koordiniere die Endpoint-Form über CONVENTIONS.)
+
+## Abschluss
+1. `manifests/requirements.md`: R-06 → `done`.
+2. `STATE.md` + Session-Log.
+3. Commit `feat(w3): ollama metrics exporter sidecar` + Trailer
+   `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`.
+4. `bash scripts/gate-session-hygiene.sh && bash scripts/gate-ownership.sh`.
+5. PR (Base `main`). Dann Review-Gate (Opus).
+```
--- a/session-prompts/W4.md
+++ b/session-prompts/W4.md
@@ -0,0 +1,39 @@
+# Session-Prompt — W4 Setup & CI/CD  (parallel, nach W1)
+
+```
+Modell: Sonnet
+
+Du bist WORKER für Paket W4 in /pfad/zu/jetson-ai-ollama, Branch `feat/w4-setup-cicd`
+(von `main`, nach W1-Merge). Lies AGENTS.md → STATE.md → CONVENTIONS.md.
+
+## Aufgabe
+Den Jetson reproduzierbar aufsetzen und CI/CD bereitstellen.
+
+## Deliverables (Ownership: `scripts/setup-jetson.sh`, `scripts/benchmark.sh`, `.github/workflows/`)
+- `scripts/setup-jetson.sh` — Ollama installieren und **GPU-Nutzung verifizieren**
+  (`ollama ps` + Logs, kein CPU-Fallback); Drop-in-Env aus
+  `ollama/systemd/ollama.service.d/override.conf` aktivieren (`daemon-reload`,
+  `restart ollama`); NVMe-SSD + Swap; Desktop-GUI/unnötige Dienste aus; MAXN-SUPER;
+  Exporter als systemd-Service aktivieren; **Firewall: nur Proxy → 11434**.
+- `scripts/benchmark.sh` — Latenz/Token-Durchsatz je Profil (Single-User), `--smoke`-Modus.
+- `.github/workflows/ci.yml` — lint + `bash -n` der Skripte + pytest (ohne Jetson-Hardware).
+- `.github/workflows/cd-jetson.yml` — Deploy auf den Jetson (self-hosted Runner/SSH).
+
+## Akzeptanzkriterien
+- [ ] `bash -n scripts/setup-jetson.sh` und `bash -n scripts/benchmark.sh` ok (R-05).
+- [ ] setup-jetson verifiziert GPU explizit und bindet Ollama nur ans LAN + Firewall.
+- [ ] Keine Secrets in den Workflows (nur Repo/Org-Secrets referenzieren).
+- [ ] CI läuft ohne Jetson-Hardware grün (Hardware-Schritte als no-op/guarded).
+
+## Nicht anfassen
+`ollama/`, `exporter/`, `client/`, `tests/`, `scripts/build-models.sh`, `docs/`.
+Die bereits vorhandene `.github/workflows/gates.yml` (Agent-System-Gates) NICHT ändern.
+
+## Abschluss
+1. `manifests/requirements.md`: R-05 → `done`.
+2. `STATE.md` + Session-Log.
+3. Commit `feat(w4): jetson setup + ci/cd` + Trailer
+   `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`.
+4. `bash scripts/gate-session-hygiene.sh && bash scripts/gate-ownership.sh`.
+5. PR (Base `main`). Dann Review-Gate (Opus).
+```
--- a/session-prompts/W5.md
+++ b/session-prompts/W5.md
@@ -0,0 +1,39 @@
+# Session-Prompt — W5 Client & Tests  (parallel, nach W1)
+
+```
+Modell: Sonnet
+
+Du bist WORKER für Paket W5 in /pfad/zu/jetson-ai-ollama, Branch `feat/w5-client-tests`
+(von `main`, nach W1-Merge). Lies AGENTS.md → STATE.md → CONVENTIONS.md.
+
+## Aufgabe
+Einen schlanken OpenAI-kompatiblen Client + CLI, und die Tests, die die
+Erfolgskriterien KODIEREN (damit der Review sie ausführen statt glauben muss).
+
+## Deliverables (Ownership: `client/`, `tests/`, `requirements/client.txt`, `requirements/dev.txt`)
+- `client/python/jetson_ai/client.py` — dünner Wrapper um `/v1/chat/completions`
+  (Profil per Modellname `qwen-light`/`gemma`/`qwen-heavy`), Type Hints + Docstrings.
+- `client/cli/ai.py` — CLI: `ai -m qwen-light "..."`.
+- `tests/test_modelfiles.py` — prüft alle drei Modelfiles: `num_ctx` explizit,
+  korrekte FROM-Pfade, Profilnamen (R-02/R-04-Oracle).
+- `tests/test_endpoints.py` — Smoke gegen Ollama `:11434` + Exporter `:8000/metrics`
+  (gegen laufende Dienste oder gemockt). (R-06/R-10)
+- `requirements/client.txt`, `requirements/dev.txt`.
+
+## Akzeptanzkriterien
+- [ ] `pytest tests/ -q` grün (R-09, R-10).
+- [ ] `tests/test_modelfiles.py` schlägt fehl, wenn ein `num_ctx` fehlt (negativer Fall).
+- [ ] Client spricht die OpenAI-Route, NICHT Ollamas natives `/api/generate`.
+
+## Nicht anfassen
+`ollama/`, `exporter/`, `scripts/`, `.github/`, `docs/`. Nur deine Pfade. Form der
+Modelfiles/Endpoints kommt aus CONVENTIONS — bei Unklarheit dort nachsehen, nicht raten.
+
+## Abschluss
+1. `manifests/requirements.md`: R-09, R-10 → `done`.
+2. `STATE.md` + Session-Log.
+3. Commit `feat(w5): openai client, cli, tests` + Trailer
+   `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`.
+4. `bash scripts/gate-session-hygiene.sh && bash scripts/gate-ownership.sh`.
+5. PR (Base `main`). Dann Review-Gate (Opus).
+```
--- a/session-prompts/W6.md
+++ b/session-prompts/W6.md
@@ -0,0 +1,37 @@
+# Session-Prompt — W6 Docs  (zuletzt, integriert die Realität der anderen)
+
+```
+Modell: Haiku
+
+Du bist WORKER für Paket W6 in /pfad/zu/jetson-ai-ollama, Branch `docs/w6`
+(von `main`, NACHDEM W2–W5 gemerged sind). Lies AGENTS.md → STATE.md → CONVENTIONS.md
+und die nun real existierenden Dateien aus W2–W5.
+
+## Aufgabe
+Die Doku schreiben, die den TATSÄCHLICHEN Stand beschreibt (nicht den geplanten),
+und README + REVIEW finalisieren.
+
+## Deliverables (Ownership: `docs/`)
+- `docs/architecture.md` — Daemon + Exporter-Sidecar, drei Profile, MAX_LOADED_MODELS=1,
+  Datenfluss DVC → Ollama. Scope-Grenze (nginx/Prometheus off-box).
+- `docs/api.md` — OpenAI-Endpoint, Profilnamen, `/api/ps`, `/metrics`.
+- `docs/deployment.md` — `setup-jetson.sh`, `build-models.sh`, Firewall, systemd.
+- `docs/troubleshooting.md` — GPU-Fallback erkennen, OOM, Profil lädt nicht, Keep-Alive.
+- README-Feinschliff + Verweis aus `REVIEW.md` prüfen (keine toten Links).
+
+## Akzeptanzkriterien
+- [ ] Jede Doku-Aussage deckt sich mit dem realen Code (keine Drift).
+- [ ] Alle internen Links lösen auf; `bash scripts/gate-doc-drift.sh` → PASS.
+- [ ] Doc-Größenbudget beachtet (< 200 Zeilen je Doc).
+
+## Nicht anfassen
+Code-Pakete (`ollama/`, `exporter/`, `client/`, `scripts/`, `.github/`, `tests/`).
+Nur `docs/` + README-Feinschliff.
+
+## Abschluss
+1. Alle verbleibenden `manifests/requirements.md`-Zeilen auf `done` prüfen.
+2. `STATE.md`: alles in „Done"; Projekt review-ready.
+3. Commit `docs(w6): architecture/api/deployment/troubleshooting` + Trailer
+   `Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>`.
+4. Alle drei Gates grün. PR (Base `main`). Dann Review-Gate (Opus) gegen REVIEW.md.
+```
--- a/sessions/2026-06-03-bootstrap.md
+++ b/sessions/2026-06-03-bootstrap.md
@@ -0,0 +1,41 @@
+# Session bootstrap — 2026-06-03
+
+- **Rolle:** leader
+- **Modell:** Opus
+- **Ziel:** Projekt aus dem agent-swarm-Template + Jetson-Meta-Prompt bootstrappen
+  (nur Planung, kein Feature-Code).
+
+## Geändert (Dateien)
+- `ROADMAP.md` — Board W1–W6 als DAG (alle 🧱 infra, kein 🔬 → kein Spike).
+- `STATE.md` — Now=Dispatch W1; Ownership-Tabelle W2–W6 (disjunkte Pfade).
+- `CONVENTIONS.md` — Projekt-Vertrag (Profilnamen, Pfade, Ports, Daemon-Env, num_ctx,
+  DVC-SoT, Scope-Grenze).
+- `manifests/requirements.md` — R-01…R-10 als kalt verifizierbares Review-Manifest.
+- `REVIEW.md` — Kalt-Review-Einstieg (zeigt auf Manifest + Reviewer-Rolle).
+- `docs/adr/0002-ollama-native.md` — Architektur-Lock (Ollama-nativ, kein Swapper/Gateway).
+- `README.md` — Projekt-Front-Door + „Sofort bauen".
+- `session-prompts/W1.md … W6.md` — dispatch-fertige Worker-Prompts.
+- `.gitignore` — Jetson-Ignores (`*.gguf`, `models/`, `.dvc/cache/`).
+- entfernt: `examples/walkthrough/` (Template-Lernbeispiel; Projekt hat eigenes Board).
+
+## Entscheidungen
+- Ollama-natives Modell-Management statt eigenem Swapper → ADR 0002.
+- REVIEW.md (aus Meta-Prompt) = dünner Einstieg; die Kriterien leben im Manifest
+  (Single Source of Truth, keine Duplikation).
+
+## Tests
+- Gates lokal: hygiene / ownership / doc-drift → PASS (siehe Gates unten).
+
+## Token-Verbrauch
+- (Bootstrap-Session; Planung) — keine Auffälligkeiten.
+
+## Gates
+- Hygiene: PASS · Kontext: PASS · Token: PASS
+- Review-Gate: n/a (reine Planung; erste Implement-Session W1 wird gereviewed)
+
+## Handoff / Next
+- **W1 dispatchen** (`session-prompts/W1.md`, Sonnet). Nach Merge: W2–W5 parallel,
+  dann W6. Ready-Set jetzt = { W1 }.
+
+## Clean-Start-Check
+- [x] Orientierung allein aus AGENTS/STATE/CONVENTIONS möglich.
--- a/sessions/README.md
+++ b/sessions/README.md
@@ -0,0 +1,4 @@
+# sessions/
+
+Pro Session ein Log aus `TEMPLATE.md`: `YYYY-MM-DD-<id>.md`. Erzählt zusammen mit
+dem Git-Log, was passiert ist — inkl. Token-Verbrauch (Eingang fürs Token-Gate).
--- a/sessions/TEMPLATE.md
+++ b/sessions/TEMPLATE.md
@@ -0,0 +1,29 @@
+# Session <id> — <YYYY-MM-DD>
+
+- **Rolle:** leader | worker | reviewer | theorist | porter | prototyper | integrator
+- **Modell:** Haiku | Sonnet | Opus
+- **Ziel:** _…_
+
+## Geändert (Dateien)
+- _…_
+
+## Entscheidungen
+- _… (Verweis auf ADR, falls tragend)_
+
+## Tests
+- _Befehl -> Ergebnis_
+
+## Token-Verbrauch
+- input: _…_ · output: _…_ · total: _…_ · tokens/Task: _…_
+- Auffälligkeiten (Re-Reading, Schleifen): _…_
+
+## Gates
+- Hygiene: PASS/FAIL · Kontext: PASS/FAIL · Token: PASS/FAIL
+- Review-Gate: APPROVE / CHANGES-REQUESTED (Opus-Session-ID: _…_)
+
+## Handoff / Next
+- _Was die nächste Session zuerst tun sollte._
+- Review-Gate nötig? Ja/Nein
+
+## Clean-Start-Check
+- [ ] Orientierung allein aus AGENTS/STATE/CONVENTIONS möglich.