init

docs/format.md

@@ -0,0 +1,184 @@
+# `.planer/`-Dateiformat (Spezifikation, Phase 0)
+
+Format der Wissensschichten im Projekt-Repo. Entwurf — wird in Phase 0 gegen echte
+Scan-Ergebnisse am Creator validiert und nachgeschärft.
+
+## Design-Entscheidungen
+
+- **Markdown mit einfachen `schlüssel: wert`-Zeilen**, kein reines YAML/JSON: Menschen
+  lesen und editieren die Dateien direkt (Soll-Änderungen!), Agenten schreiben sie,
+  Skripte parsen sie mit simplen Regeln (Überschriften-Ebenen + Schlüsselzeilen).
+- **Einheiten-ID = `pfad::symbol`** (z. B. `backend/kanban.py::_worker`) — stabil,
+  ableitbar, ohne separate ID-Verwaltung. Bei Datei-Ebene ohne Symbol: nur `pfad`.
+- **Belege = wörtliche Kurzzitate** aus dem Code (nicht Zeilennummern — die verschieben
+  sich bei jedem Diff). Mechanisch prüfbar per Substring-Suche in der Anker-Datei.
+  Ein Beleg ist ein Ausschnitt aus GENAU EINER Quellzeile (Phase-0-Erkenntnis:
+  Modelle ziehen sonst mehrzeilige Statements zusammen — nicht prüfbar).
+- **Eine Einheiten-Datei pro Quelldatei** (nicht pro Einheit — sonst hunderte Dateien;
+  nicht eine große — sonst Merge-Hölle). Diff-Lokalität: Quelldatei ändert sich →
+  genau eine Einheiten-Datei ändert sich.
+- **Sichten referenzieren Einheiten nur per ID**, kopieren nie Fakten (Single Source).
+
+## Verzeichnis-Layout
+
+```
+<projekt>/.planer/
+  kern.md                  Kern des Projekts + tragende Einheiten
+  architektur.md           Komponenten + Beziehungen
+  flows.md                 Abläufe als Schrittfolgen
+  features/<bereich>.md    eine Datei je Funktionsbereich
+  einheiten/<quelle>.md    eine Datei je Quelldatei (Pfad, `/` → `__`)
+  pruefung.md              Build-/Test-/Start-Kommandos, Eigenheiten
+  entscheidungen/*.md      Decision Records
+  strategie/*.md           benannte Soll-Entwürfe
+  ideen.md                 Ideen-Backlog
+  jourfixe/*.md            Sitzungsprotokolle
+```
+
+## Einheiten: `einheiten/backend__kanban.py.md`
+
+````markdown
+# Einheiten: backend/kanban.py
+stand: 3f2a91c        ← Commit-Hash des letzten Scans dieser Datei (der Anker-Stand)
+
+## backend/kanban.py::_worker
+beschreibung: Zieht Karten aus der Stufe der Spalte und arbeitet sie nebenläufig ab.
+input: Flow, Stage-Spezifikation, Inflight-Limit, Liste aller Stage-Namen
+output: kehrt erst zurück, wenn flowweit nichts mehr zu tun ist; Karten sind advanced,
+  im Backoff oder dead
+entscheidungen:
+- Exit erst nach doppelter Leerlauf-Prüfung mit Karenz-Schlaf.
+  beleg: "if await _idle_exit():"
+- Ein Barriere-Worker zieht nur bei Quieszenz aller Upstream-Stufen.
+  beleg: "return await quiescent(flow, spec.upstream)"
+kanten:
+- ruft-auf: backend/kanban.py::quiescent
+- nutzt: backend/database.py::kanban_pull
+- wird-genutzt-von: backend/kanban.py::run_flow
+````
+
+Regeln:
+- `## `-Überschrift = Einheiten-ID. Freitext darunter bis zur nächsten Schlüsselzeile
+  ist verboten — nur `beschreibung:`, `input:`, `output:`, `entscheidungen:`, `kanten:`
+  (feste Reihenfolge).
+- `beschreibung:` genau ein Satz (die Verantwortung), Umbruch mit Einrückung erlaubt.
+- `input:` was die Einheit entgegennimmt, `output:` was sie liefert bzw. bewirkt —
+  je eine knappe Zeile, keine Prosa.
+- Jede Entscheidung: kurzer Satz (`- `-Zeile) — eine im Code getroffene Design-
+  Entscheidung oder Garantie, kein Implementierungs-Nacherzählen — gefolgt von
+  `beleg: "<wörtliches Kurzzitat aus der Anker-Datei>"`.
+- **Der konkrete Code wird nie in Artefakte kopiert** — die UI zieht ihn live über den
+  Anker (Pfad + Symbol) aus der Quelle. Single Source, kein Drift.
+- `kanten:`-Typen: `ruft-auf`, `nutzt`, `wird-genutzt-von`, `löst-aus`, `wird-ausgelöst-von`.
+  Ziel ist immer eine Einheiten-ID.
+- MECE-Anspruch v1: Symbol-Ebene; Kleinkram (Imports, Konstanten) darf unzugeordnet
+  bleiben. Jede Funktion/Klasse der Quelldatei gehört zu genau einer Einheit (eine
+  Einheit darf mehrere kleine, zusammengehörige Symbole bündeln — dann mehrere
+  `anker:`-Zeilen unter der Überschrift, ID ist der Hauptanker).
+
+## Feature-Sicht: `features/<bereich>.md`
+
+````markdown
+# Bereich: Generierungs-Pipeline
+beschreibung: Erzeugt aus einer Quelle die Lerninhalte in drei Board-Stufen.
+
+## Feature: Resümierbare Kanban-Boards [kern]
+beschreibung: Generierung läuft als Karten durch Spalten und übersteht Abbrüche.
+
+### Kann nach Abbruch fortsetzen
+einheiten: backend/kanban.py::run_flow, backend/database.py::kanban_pull
+
+### Fehlerhafte Karten landen sichtbar im Dead-Letter
+einheiten: backend/kanban.py::_worker
+````
+
+Regeln:
+- `# Bereich` → `## Feature` → `### Teilfeature`; Flag `[kern]` oder `[rand]` am Feature.
+- **Titel kurz, ohne Klammern, ohne „und"** — ein Bereich/Feature erfüllt genau EINE
+  Aufgabe; wer „und" braucht, muss splitten. Beschreibungen: ein kurzer Satz, der den
+  Kern trifft, ebenfalls ohne „und"-Aufzählung.
+- Teilfeatures tragen NUR `einheiten:`-Referenzen (+ optional `beschreibung:`).
+  Alles Weitere zieht die UI live aus den Einheiten: die Entscheidungs-Liste
+  (aggregiert über die referenzierten Einheiten), je Methode Input/Output und den
+  konkreten Code aus dem Anker.
+- MECE je Ebene: Bereiche zerlegen das Projekt, Features ihren Bereich, Teilfeatures
+  ihr Feature — vollständig, überschneidungsfrei. Richtwert 6–10 Bereiche, 5–15
+  Features je Bereich.
+
+## Kern: `kern.md`
+
+````markdown
+# Kern: creator
+Aus einem Thema/Skript/Ordner/Link entsteht ein vollständiger, belegter Lernguide
+mit Übungssystem — zerlegt nach MECE, jede Aussage mit Beleg.
+
+tragende-einheiten: backend/kanban.py::run_flow, backend/board_inventory.py, …
+````
+
+Wenige Sätze; `tragende-einheiten:` verweist auf das, was das Projekt trägt.
+
+## Architektur: `architektur.md`
+
+````markdown
+# Architektur: creator
+
+## Komponente: Kanban-Engine
+beschreibung: Generischer Streaming-Motor; Boards definieren die Stufen.
+einheiten: backend/kanban.py::Flow, backend/kanban.py::_worker, …
+beziehungen:
+- nutzt: Komponente: Datenbank
+- wird-genutzt-von: Komponente: Boards
+````
+
+Komponenten-Beziehungen werden aus den Einheiten-Kanten aggregiert und beim Scan
+gegen sie geprüft (keine Beziehung ohne mindestens eine tragende Kante).
+
+## Flows: `flows.md`
+
+````markdown
+# Flows: creator
+
+## Flow: Thema → fertiger Guide
+1. Research-Agenten sammeln Quellen — backend/board_inventory.py::research
+2. Titel werden geclustert und benannt — backend/board_inventory.py::cluster
+3. …
+````
+
+Nummerierte Schritte, jeder Schritt endet mit ` — <einheiten-id>[, <einheiten-id>]`.
+
+## Prüfung: `pruefung.md`
+
+````markdown
+# Prüfung: creator
+tests: make test
+lint: (keins vorhanden)
+start: make dev
+hinweise:
+- Backend-Edits bei laufendem Flow triggern uvicorn-Reload und killen Läufe.
+````
+
+Feste Schlüssel `tests:`, `lint:`, `start:`; fehlt etwas, steht dort explizit
+`(keins vorhanden)` — Gates degradieren sichtbar, nie still.
+
+## Decision Record: `entscheidungen/<datum>-<slug>.md`
+
+````markdown
+# Entscheidung: Belege als Kurzzitate statt Zeilennummern
+datum: 2026-07-09
+status: aktiv
+betrifft: einheiten-format
+frage: Wie referenzieren Fakten die Code-Stelle?
+optionen: Zeilennummern (präzise, aber driften) | Kurzzitate (robust, substring-prüfbar)
+entscheidung: Kurzzitate.
+begründung: Zeilennummern veralten bei jedem Diff; Zitate sind mechanisch prüfbar.
+````
+
+## Mechanische Prüfungen (Skripte, tokenfrei)
+
+1. **Anker-Existenz**: jede Einheiten-ID zeigt auf existierende Datei + Symbol darin.
+2. **Zitat-Treue**: jeder `beleg:`-String kommt wörtlich in der Anker-Datei vor.
+3. **Referenz-Integrität**: jede `einheiten:`-Referenz in Sichten existiert; jedes
+   Kanten-Ziel existiert.
+4. **Abdeckung**: jedes Symbol der Quelldatei ist einer Einheit zugeordnet (Report,
+   v1 kein harter Fehler).
+5. **Struktur**: Dateien folgen der Grammatik (Schlüssel, Reihenfolge, Flags).