shinkan-jinkendo/.claude/docs/working/PROGRESSION_GRAPH_SLOT_EDITOR_SPEC.md

# Progressionsgraph — Slot-Editor (Phase B)

**Stand:** 2026-06-10 · **Status:** In Umsetzung

## Ziel

Ein Progressionsgraph = **ein linearer Hauptpfad** (Roadmap = strukturgebend). Jeder **Major Step** ist ein **Slot** mit:

- **primary** — Hauptübung des Slots (Pfadknoten)
- **siblings** — 0..n Schwestern (gleiche Stufe, `edge_type: sibling`)

KI-Entwürfe und Bibliotheksübungen leben **im selben Slot-Modell**, ohne sofortige Übungsanlage.

## Slot-Zustände (`kind`)

| kind | Bedeutung |
|------|-----------|
| `empty` | Noch keine Übung |
| `library` | `exercise_id` (+ optional `variant_id`) |
| `proposal` | KI-Entwurf (`ai_suggestion`, kein `exercise_id`) |

## Kanten

- `primary(n) → primary(n+1)` — `next_exercise` (nur befüllte Primärkette, lückenlos verbunden)
- `primary ↔ sibling` — `sibling` (pro Slot)

Leere Slots in der Roadmap sind erlaubt; Kanten nur zwischen aufeinanderfolgenden befüllten Primär-Slots.

## Editor-Zustand (`ProgressionGraphDraft`)

```ts
{
  goalQuery, startSituation, targetState, roadmapNotes, maxSteps,
  majorSteps: MajorStep[],
  slots: Slot[],           // index = major_step_index
  pathSkillExpectations?,
  lastFindings?,           // path_qa-Snapshot
  dirty: boolean,
}
```

**Hydration:** `planning_roadmap` + Kanten → Slots; `slot_contents[]` für Entwürfe; Primärkette aus `next_exercise`.

**Speichern:** Batch-Delete bestehender Pfad-/Schwester-Kanten → `edges/sequence` (Primärkette) → einzelne `sibling`-Kanten → `PUT`/`sequence` mit Artefakt inkl. `slot_contents`, optional `last_findings`.

## Findings-Panel

Nutzt `path_qa` (`overall_ok`, `quality_score`, `issues`, `recommendations`, `gap_fill_offers`, …).

**API:** `POST /api/planning/progression-path-suggest` mit `evaluate_only: true` und `evaluate_steps[]` — QA ohne Re-Match.

Persistenz: `planning_roadmap.last_findings`.

## Artefakt-Erweiterung (`GraphPlanningRoadmapArtifact`)

Zusätzlich optional:

- `slot_contents[]` — `{ major_step_index, primary, siblings[] }`
- `last_findings` — letzter `path_qa`-Snapshot

## UI (konsolidiert)

- **Eine Oberfläche:** `ExerciseProgressionGraphPanel` embeddet `ProgressionGraphEditor` (Slots + Findings)
- Kein separater Slot-Editor, kein 4-Schritt-KI-Wizard, kein `ProgressionChainEditor` im Panel
- Route `/progression-graphs/:id` → Redirect nach `/exercises` (Deep-Link wählt Graph)
- **Phase C:** Übersicht mit Kacheln (Name, Start, Ziel)

## Ersetzt (Legacy, nicht mehr im Panel)

- `ExerciseProgressionPathBuilder` · `ProgressionChainEditor` — Code bleibt vorerst, nicht eingebunden

## Implementierungsreihenfolge

| ID | Inhalt |
|----|--------|
| B.0 | Draft + Laden/Speichern Slots ↔ Kanten |
| B.1 | Slot-Karten, Bibliothek + Entwurf |
| B.2 | Findings-Panel + `evaluate_only` |
| B.3 | Entwürfe im Artefakt + „Übung anlegen“ |
| B.4 | Route + Panel vereinfachen |
| B.5 | `last_findings` + Phase-C-Vorbereitung |