planer/docs/format.md

.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

# 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

# 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

# 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

# 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

# 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

# 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

# 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).