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`

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