feat: initial agent-swarm-repo template

Generelles Git-Repo-Template fuer KI-Agenten-Arbeit (multi-agent swarm pattern). Enthaelt: - Rollen-System (Leader, Worker, Reviewer) mit Model-Routing-Matrix (Tier-basiert) - Zwei komplementaere Loops: Feature-Loop (vorwaerts) + Audit-Loop (rueckwaerts) - Spike-Gate fuer Research-Items (GO/NO-GO vor Produktionscode) - Obligatorische Opus-Review-Gate nach jeder Implement-Session - Drei ausfuehrbare Gates: session-hygiene, ownership (Cross-Edit-Schutz), doc-drift -- alle dormant bis zur ersten Initialisierung, dann automatisch aktiv - Bootstrap: scripts/init.sh + session-prompts/BOOTSTRAP.md - Worked Example (URL-Shortener-Domaene): Board, Session-Log, Audit-Finding, ADR - Token-Hygiene (3-Tier: Session-Schnitt / Command-Disziplin / Cache-Disziplin) - GitHub Actions CI (gates.yml) laeuft auf jedem Push/PR Muster destilliert aus produktiv-bewaehrten Patterns des ConformalLabpp-Projekts.
2026-06-03 06:35:06 +02:00
commit 696eddb5ef
40 changed files with 1310 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,10 @@
 __pycache__/
 *.py[cod]
 .venv/
 .env
 *.log
 logs/
 .DS_Store
 .idea/
 .vscode/
 # metrics/*.csv wird bewusst getrackt — die Observability-Story braucht den Trend.
--- 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,39 @@
 # 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`.
--- a/README.md
+++ b/README.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/ROADMAP.md
+++ b/ROADMAP.md
@@ -0,0 +1,37 @@
 # ROADMAP — Board & Ready-Set
 Eingang des Feature-Loops **und** der Abhängigkeits-DAG: jedes Item kennt seine
 Prerequisites. Der Leader berechnet jeden Zyklus das **Ready-Set** und dispatcht
 nur daraus.
 > **ROADMAP vs. STATE:** ROADMAP = der ganze geplante Graph (Planungsebene).
 > `STATE.md` = was *gerade jetzt* läuft (Live-Ebene: Now / In Progress / Blocked).
 > Ein Item wandert: ROADMAP-`🔲` → beim Dispatch in `STATE.md` „In Progress" →
 > bei Merge zurück als ROADMAP-`✅` in „Done".
 ## Legende
 - **Typ:** 🔌 port (Referenz-Impl/golden oracle) · 🔬 research (nur Paper-Formeln) · 🧱 infra
 - **Status:** ✅ done · 🔲 ready · ⏸ blocked-by-prereq · ⛔ blocked-extern (Lizenz/Mensch-Entscheid)
 ## Ready-Set-Regel (so dispatcht der Leader)
 ```
 Ready-Set = { Items mit Status 🔲, deren Prereqs ALLE ✅ sind }
 ```
 1. Ready-Set bilden (Board unten lesen).
 2. Ein Item ziehen; Modell aus `docs/roles/model-routing.md` setzen.
 3. Session-Prompt aus `session-prompts/` ausfüllen (Template: `session-prompts/TEMPLATE.md`).
 4. **🔌/🧱** → direkt Worker. **🔬** → erst durch das Spike-Gate (`docs/loops/spike-gate.md`).
 5. Nach Implement: Review-Gate (Opus) → Merge → Item hier auf ✅, Dependents werden frei.
 ## Board
 | ID | Item | Typ | Status | Prereqs | Rolle · Modell | Aufwand |
 |----|------|-----|--------|---------|----------------|---------|
 | _F-01_ | _<Feature/Paket>_ | 🔌 | 🔲 | — | Porter · Sonnet | _…_ |
 | _F-02_ | _<Feature/Paket>_ | 🔬 | ⏸ | F-01 | Theorist · Opus | _…_ |
 > Ein durchgespieltes, befülltes Board: `examples/walkthrough/ROADMAP.md`.
 ## Done
 | ID | Item | Session | Commit |
 |----|------|---------|--------|
 | _…_ | _…_ | _…_ | _…_ |
--- a/STATE.md
+++ b/STATE.md
@@ -0,0 +1,25 @@
 # STATE — aktueller Stand
 > Einzige Quelle für "wo stehen wir". Jede Session aktualisiert dies am Ende.
 **Letzte Session:** _<id / datum>_ · **Aktive Rolle:** _<leader/worker/reviewer>_
 ## Now (in dieser Session im Fokus)
 - _…_
 ## In Progress (begonnen, nicht fertig)
 - _… (Paket, Owner, Branch)_
 ## Blocked
 - _… (Grund, wartet worauf)_
 ## Next (priorisiert)
 - _…_
 ## Offene Audit-Findings
 - _… (Verweis auf audits/<datei>, Severity)_
 ## Datei-Ownership (aktiv)
 | Paket | Dateien/Pfade | Owner |
 |---|---|---|
 | _…_ | _…_ | _…_ |
--- 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/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/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/examples/walkthrough/README.md
+++ b/examples/walkthrough/README.md
@@ -0,0 +1,30 @@
 # Worked Example — „DemoLinks" (ein URL-Shortener)
 Eine **befüllte Momentaufnahme** des Betriebsmodells, damit man sieht wie der
 ausgefüllte Zustand aussieht — nicht nur die Platzhalter. Erfundene, generische
 Domäne; nichts davon muss man bauen.
 ## Was hier passiert ist (Story)
 1. **Bootstrap:** Leader hat aus dem Brief „kleiner URL-Shortener" das Board
   ([`ROADMAP.md`](ROADMAP.md)) mit vier Items + Abhängigkeits-DAG erzeugt.
 2. **Feature-Loop, Zyklus 1:** Ready-Set war `{F-01}`. Worker (Sonnet) hat die
   Storage-Schicht gebaut → Review-Gate (Opus) APPROVE → gemerged.
   Belegt im Session-Log ([`sessions/2026-06-03-S1.md`](sessions/2026-06-03-S1.md))
   und als Entscheidung im ADR ([`docs/adr/0002-storage-keyvalue.md`](docs/adr/0002-storage-keyvalue.md)).
 3. **Jetzt:** Ready-Set ist `{F-02, F-03}`. Für F-02 (🔌 Port) liegt ein fertiger
   Session-Prompt bereit ([`session-prompts/F-02.md`](session-prompts/F-02.md)).
   F-03 (🔬 Research) muss zuerst durch das Spike-Gate. Live-Stand:
   [`STATE.md`](STATE.md).
 4. **Audit-Loop, parallel:** Ein kalter Auditor hat an F-01 ein „untested claim"
   gefunden ([`audits/2026-06-04-storage.md`](audits/2026-06-04-storage.md)) und
   eine Korrektur-Task mit Model-Zuweisung eingestellt.
 ## Worauf man achten sollte
 - **Board als DAG:** F-04 ist `⏸` weil sein Prereq F-02 noch nicht `✅` ist — der
  Leader dispatcht es gar nicht erst. F-03 zeigt die `🔬`-Spur (Spike vor Code).
 - **Port vs. Research:** F-02 hat eine Referenz-Impl (golden oracle) → Worker direkt.
  F-03 hat keine → Theorist → Spike → GO/NO-GO.
 - **Ownership-Tabelle** in `STATE.md`: jedes Paket hat disjunkte Pfade (mit Slash) —
  genau das prüft `scripts/gate-ownership.sh`.
 - **Spuren-Vollständigkeit:** ROADMAP (Plan) ↔ STATE (Live) ↔ Session-Log (was lief)
  ↔ ADR (warum) ↔ Audit (was driftet). Ein kalter Agent rekonstruiert daraus alles.
--- a/examples/walkthrough/ROADMAP.md
+++ b/examples/walkthrough/ROADMAP.md
@@ -0,0 +1,27 @@
 # ROADMAP — Board & Ready-Set  (Beispiel: DemoLinks)
 > Befülltes Beispiel-Board. Format-Referenz für das echte `ROADMAP.md` im Root.
 ## Legende
 - **Typ:** 🔌 port · 🔬 research · 🧱 infra
 - **Status:** ✅ done · 🔲 ready · ⏸ blocked-by-prereq · ⛔ blocked-extern
 ## Ready-Set-Regel
 `Ready-Set = { Items mit 🔲, deren Prereqs ALLE ✅ }` → aktuell: **{ F-02, F-03 }**.
 ## Board
 | ID | Item | Typ | Status | Prereqs | Rolle · Modell | Aufwand |
 |----|------|-----|--------|---------|----------------|---------|
 | F-01 | Storage-Schicht (Key-Value Store + TTL) | 🧱 | ✅ | — | Worker · Sonnet | ~0.5 d |
 | F-02 | `POST /shorten` Endpoint | 🔌 | 🔲 | F-01 | Porter · Sonnet | ~0.5 d |
 | F-03 | Klick-Dedup-Analytik (neuartige Heuristik) | 🔬 | 🔲 | F-01 | Theorist · Opus → Spike | ~3 d |
 | F-04 | Rate-Limiter pro Client | 🧱 | ⏸ | F-02 | Worker · Sonnet | ~0.5 d |
 > F-03 ist `🔬`: vor Produktionscode erst **Spike** (`docs/loops/spike-gate.md`) —
 > numerischer Nachweis, dass die Dedup-Heuristik keine echten Klicks verwirft.
 > F-04 bleibt `⏸`, bis F-02 `✅` ist; der Leader dispatcht es nicht früher.
 ## Done
 | ID | Item | Session | Commit |
 |----|------|---------|--------|
 | F-01 | Storage-Schicht | S1 (2026-06-03) | `a1b2c3d` |
--- a/examples/walkthrough/STATE.md
+++ b/examples/walkthrough/STATE.md
@@ -0,0 +1,29 @@
 # STATE — aktueller Stand  (Beispiel: DemoLinks)
 > Live-Ebene. Was *jetzt* läuft. Der Plan steht im Board (`ROADMAP.md`).
 **Letzte Session:** S1 / 2026-06-03 · **Aktive Rolle:** worker
 ## Now (in dieser Session im Fokus)
 - F-02 `POST /shorten` vorbereiten (Session-Prompt liegt bereit).
 ## In Progress (begonnen, nicht fertig)
 - _(keine — F-01 ist gemerged)_
 ## Blocked
 - F-04 Rate-Limiter — wartet auf F-02 (`⏸` im Board).
 ## Next (priorisiert)
 - F-02 dispatchen (Porter · Sonnet).
 - F-03 Spike anstoßen (Theorist · Opus) — Research, nicht direkt bauen.
 ## Offene Audit-Findings
 - A-01 (`audits/2026-06-04-storage.md`, 🟡) — F-01 behauptet TTL-Eviction ohne
  Test. Korrektur-Task: Haiku, Session S2.
 ## Datei-Ownership (aktiv)
 | Paket | Dateien/Pfade | Owner |
 |---|---|---|
 | storage | `src/storage/` | worker-a |
 | api | `src/api/` | worker-b |
 | analytics | `src/analytics/` | theorist |
--- a/examples/walkthrough/audits/2026-06-04-storage.md
+++ b/examples/walkthrough/audits/2026-06-04-storage.md
@@ -0,0 +1,19 @@
 # Audit storage — 2026-06-04
 - **Reviewer-Session:** kalt (kein Vorkontext), Modell Opus
 - **Orientierung allein aus AGENTS/STATE/CONVENTIONS gelungen?** Ja
 ## Befunde
 | # | Typ | Beschreibung | Severity | Model | Korrektur-Task |
 |---|-----|--------------|----------|-------|----------------|
 | A-01 | untested | `store.py` dokumentiert TTL-Eviction, aber kein Test deckt das Ablaufen ab. Behauptung ohne Beleg. | 🟡 | Haiku | S2: Eviction-Test ergänzen, dann R-0001 bleibt `done` mit Beleg. |
 | A-02 | hygiene | `manifests/requirements.md` referenziert `tests/test_store.py` — existiert ✅. Keine tote Referenz. | 🔵 | — | keine (nur Notiz). |
 ## Verifikation
 - Manifest geprüft: R-0001 Datei + Test existieren. ✅
 - Tests ausgeführt: `pytest tests/test_store.py` → 4 passed (Eviction-Pfad aber
  nicht unter den 4).
 ## Empfehlung
 - Audit-Loop nicht eskalieren (nur 1× 🟡). A-01 als Korrektur-Task in `STATE.md`
  und ins Board (Wave „quick wins", Haiku). Feature-Loop bleibt freigegeben.
--- a/examples/walkthrough/docs/adr/0002-storage-keyvalue.md
+++ b/examples/walkthrough/docs/adr/0002-storage-keyvalue.md
@@ -0,0 +1,12 @@
 # 0002 — Storage zunächst In-Memory Key-Value, nicht SQLite
 - **Status:** accepted
 - **Kontext:** F-01 braucht einen Speicher für (Code → URL). Optionen: In-Memory
  Dict mit TTL, oder SQLite. Der Shortener soll erst die API-Form (F-02) und die
  Analytik (F-03) validieren; Persistenz ist noch nicht gefordert.
 - **Entscheidung:** In-Memory Key-Value Store mit optionaler TTL. SQLite wird
  erst eingeführt, wenn ein Item Persistenz über Neustarts verlangt.
 - **Konsequenz:** Schnelle Iteration, keine Schema-Migration jetzt. Preis: Daten
  überleben keinen Neustart — explizit als Nicht-Ziel der ersten Iteration
  vermerkt. Re-Litigation vermieden, weil das *Warum* hier festgehalten ist.
 - **Superseded by:** _(noch keins)_
--- a/examples/walkthrough/session-prompts/F-02.md
+++ b/examples/walkthrough/session-prompts/F-02.md
@@ -0,0 +1,40 @@
 # Session-Prompt — F-02 `POST /shorten`  (befülltes Beispiel)
 ```
 Modell: Sonnet
 Du arbeitest in /pfad/zu/DemoLinks auf einem neuen Branch `feat/api` (von `main`).
 ## Aufgabe
 Implementiere den Endpoint `POST /shorten`: nimmt `{ "url": "<lang>" }`, erzeugt
 einen kurzen Code, speichert (Code → URL) über die Storage-Schicht (F-01) und gibt
 `{ "code": "<kurz>" }` zurück. AUSSERHALB des Scopes: Rate-Limiting (das ist F-04),
 Analytik (F-03), Auth.
 ## Details
 Referenz-Implementierung (Port): `reference/flask_shortener.py` Zeilen 20–58
 (golden oracle — gleiche Code-Erzeugung, gleiche Kollisionsbehandlung).
 Storage-API: `src/storage/store.py` (`put(key, value)` / `get(key)`).
 ## Akzeptanzkriterien
 - [ ] Gleiche Eingabe → gleicher Code wie die Referenz (golden-value-Test).
 - [ ] Kollision wird erkannt und neu gewürfelt (Test mit erzwungener Kollision).
 - [ ] Ungültige URL → 400 mit klarer Meldung.
 - [ ] Tests grün: `pytest tests/test_api.py`
 ## Nicht anfassen
 `src/storage/` (Owner: worker-a) und `src/analytics/` (Owner: theorist).
 Nur `src/api/` + `tests/test_api.py`.
 ## Commit & Push
 - `feat(api): add POST /shorten endpoint`
 - Trailer: `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`
 - Push nach `origin`, PR öffnen (Base `main`).
 ## Abschluss
 1. `manifests/requirements.md` R-0002 → `done`.
 2. `STATE.md`: F-02 nach „In Progress", dann Handoff für Review.
 3. Session-Log aus `sessions/TEMPLATE.md`.
 4. `bash scripts/gate-session-hygiene.sh` und `bash scripts/gate-ownership.sh`.
 5. PR-URL + Testzahl reporten. Danach: Review-Gate (Opus).
 ```
--- a/examples/walkthrough/sessions/2026-06-03-S1.md
+++ b/examples/walkthrough/sessions/2026-06-03-S1.md
@@ -0,0 +1,34 @@
 # Session S1 — 2026-06-03
 - **Rolle:** worker
 - **Modell:** Sonnet
 - **Ziel:** F-01 Storage-Schicht (Key-Value Store mit TTL) bauen.
 ## Geändert (Dateien)
 - `src/storage/store.py` — In-Memory KV-Store, `put/get/expire`.
 - `src/storage/__init__.py`
 - `tests/test_store.py` — put/get-Roundtrip, Overwrite, Miss.
 - `manifests/requirements.md` — R-0001 → `done`.
 ## Entscheidungen
 - In-Memory-Dict statt SQLite für die erste Iteration → ADR 0002 (accepted).
 ## Tests
 - `pytest tests/test_store.py` → 4 passed.
 ## Token-Verbrauch
 - input: 41k · output: 6k · total: 47k · tokens/Task: 47k
 - Auffälligkeiten: keine (kein Re-Reading, kein Schleifen).
 ## Gates
 - Hygiene: PASS · Kontext: PASS · Token: PASS
 - Review-Gate: APPROVE (Opus-Session S1-review) — „TTL-Pfad korrekt, aber
  Eviction ist ungetestet" → als Audit-Finding A-01 notiert, nicht blockierend.
 ## Handoff / Next
 - F-02 ist jetzt ready (Prereq F-01 ✅). Prompt unter `session-prompts/F-02.md`.
 - F-03 ready, aber Research → erst Spike.
 - Review-Gate nötig? erledigt (APPROVE).
 ## Clean-Start-Check
 - [x] Orientierung allein aus AGENTS/STATE/CONVENTIONS möglich.
--- a/manifests/requirements.md
+++ b/manifests/requirements.md
@@ -0,0 +1,9 @@
 # Requirements-Manifest (kalt verifizierbar)
 Eine Zeile je Erfolgskriterium. Der Reviewer prüft Spalte für Spalte.
 | ID | Anforderung | Datei(en) | Test/Prüfbefehl | Status |
 |----|-------------|-----------|------------------|--------|
 | R-0001 | _Beispiel: …_ | `path/to/file` | `pytest tests/test_x.py` | 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,47 @@
 #!/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..."
 # Loop laeuft im Haupt-Shell (Process Substitution), damit fail=1 wirkt.
 if [ -f "$man" ]; then
  while read -r p; do
    # Platzhalter und Nicht-Pfade ueberspringen.
    case "$p" in
      *" "*|*…*|_*|*path/to*) continue ;;
    esac
    case "$p" in
      */*|*.py|*.md|*.sh|*.js|*.ts|*.yml|*.yaml|*.json)
        [ -e "$p" ] || { echo "  - fehlende Referenz: $p"; fail=1; } ;;
    esac
  done < <(grep -oE '`[^`]+`' "$man" | tr -d '`')
 fi
 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,80 @@
 #!/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; next}
  f && /^[[:space:]]*$/{f=0}
  f && /^\|/{
    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,38 @@
 #!/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 || git rev-parse HEAD~1 2>/dev/null || true)
 if [ -n "$base" ]; then
  git diff --name-only "$base"...HEAD | grep -q '^STATE.md$' || \
    note "STATE.md im aktuellen Branch nicht aktualisiert."
 else
  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/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.
		`@@ -0,0 +1,2 @@`
							`date,sessions,rework_commits,total_commits`
							`2026-06-03,0,0,0`