# `.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 ``` /.planer/ kern.md Kern des Projekts + tragende Einheiten architektur.md Komponenten + Beziehungen flows.md Abläufe als Schrittfolgen features/.md eine Datei je Funktionsbereich einheiten/.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: ""`. - **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/.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 ` — [, ]`. ## 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/-.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).