Update documentation and enhance planning features in Progression Graph

- Updated the `CLAUDE.md` to reflect changes in the Progression Graph, including the new Ist-Stand and roadmap specifications. - Enhanced `PLANNING_EXERCISE_SUGGEST_CONTEXT.md` with detailed descriptions of the current state and features of the planning exercise. - Revised `PLANNING_PROGRESSION_ROADMAP_SPEC.md` to document the implementation status of various phases and their corresponding migrations. - Incremented application version to 0.8.217 to incorporate recent updates and improvements in the planning context and roadmap functionalities.
2026-06-10 07:50:29 +02:00 · 2026-06-10 07:50:29 +02:00 · 3be7606d90
commit 3be7606d90
parent ca3a9c6fa4
8 changed files with 462 additions and 43 deletions
--- a/.claude/docs/working/PLANNING_EXERCISE_SUGGEST_CONTEXT.md
+++ b/.claude/docs/working/PLANNING_EXERCISE_SUGGEST_CONTEXT.md
@ -493,23 +493,37 @@ Nach Pfad-Bildung:

 ---

-## 24. Phase F — Roadmap-first Progressionsgraph (0.8.204+) 🔄
+## 24. Phase F — Roadmap-first Progressionsgraph (0.8.204–217) ✅

 **Entscheidung:** Progressionsgraph plant **vom Ziel rückwärts** (Roadmap → Stufenspezifikation → Bibliothek/KI). **Keine Gruppenanalyse** — die gehört zur Trainingsplanung.

+**Ist-Stand (vollständig):** `docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md`  
 **Spec:** `working/PLANNING_PROGRESSION_ROADMAP_SPEC.md` · **Roadmap:** `docs/architecture/PLANNING_KI_ROADMAP.md`

 | Teil | Modul / API |
 |------|-------------|
 | Pipeline | `planning_progression_roadmap.py` (Workflow-lite) |
-| API | `include_roadmap_preview`, `include_llm_roadmap`, `roadmap_first` auf `progression-path-suggest` |
-| Prompts | Migration **078/079** — Slugs in `ai_prompts` (Admin), **kein** Template im Python-Code |
-| UI | `ExerciseProgressionPathBuilder` — Roadmap-Box (Major Steps) |
+| Match | `planning_exercise_path_builder.py` — `roadmap_first`, `roadmap_override` |
+| Skills | `planning_skill_expectations.py` — pro Stufe + Pfad |
+| Gap-KI | `planning_exercise_form_context.py`, `planning_exercise_path_ai_fill.py` |
+| Persistenz | `planning_roadmap` JSONB (Migration **088**) |
+| API | `progression-path-suggest`, `PUT` Graph, `POST …/edges/sequence` |
+| Prompts | **078/079/087** — Slugs nur in `ai_prompts` |
+| UI | `ExerciseProgressionPathBuilder`, `ExerciseGapFillPrepModal` |

-**F3 (0.8.206):** `roadmap_first=true` (Default im UI) — Retrieval pro `stage_spec`/Major Step; `roadmap_unfilled` Gap-Angebote. Ohne Flag: retrieval-first wie bisher, Roadmap nur Preview.
+**Graph-Bias:** `progression_graph_id` bevorzugt **bestehende Nachfolger** ab Schritt 2 (Gewicht ~4–10 %), baut aber **keinen** Pfad aus vorhandenen Knoten — siehe Ist-Doku §5.

 **Mitai Workflow-Engine:** bewusst **nicht** jetzt — Pipeline workflow-ready für spätere Anbindung.

 ---

 ## 25. Backlog (offen)
+
+Siehe priorisierte Liste in **`docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md`** §10:
+
+1. UI-Wizard (Progressionsgraph) — separater Chat  
+2. Graph-Erweiterungsmodus (Start ab Knoten)  
+3. Trainingsplanung Phase G (Gruppenkontext, `planning_skill_expectations`)  
+4. Kontext auf allen Pfad-Schritten in der UI  
+5. Enrichment / Prompt-Feintuning  
+6. Mitai Workflow-Engine (langfristig)
--- a/.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md
+++ b/.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md
@ -2,9 +2,11 @@

 **Version:** 0.1  
 **Datum:** 2026-06-07  
-**Status:** VERBINDLICHE ZIELARCHITEKTUR — Umsetzung gestartet (0.8.204+)  
+**Status:** VERBINDLICHE ZIELARCHITEKTUR — **F0–F9 umgesetzt** (0.8.217)  
 **Geltungsbereich:** **Progressionsgraph** (`exercise_progression_graphs`) — **ohne** Gruppenanalyse

+**Ist-Stand (Module, API, Graph-Verhalten, Persistenz):** `docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md`
+
 **Bezüge:**  
 `working/PLANNING_EXERCISE_SUGGEST_CONTEXT.md` · `working/AI_PLANNING_KI_MULTISTAGE_FORECAST.md` · `technical/AI_TRAINING_PLANNING_CONCEPT.md` · `technical/AI_PROMPT_TARGET_ARCHITECTURE.md` · `docs/architecture/PLANNING_KI_ROADMAP.md` · `docs/HANDOVER.md`

@ -152,6 +154,7 @@ Jede Phase: `(ctx) → ctx`, Zwischenergebnisse in API-Response für **Human-in-

 | Slug | Phase | Migration |
 |------|-------|-----------|
+| `planning_progression_start_target` | Start/Ziel | **087** |
 | `planning_progression_goal_analysis` | A | **078** |
 | `planning_progression_roadmap` | B | **078** |
 | `planning_progression_stage_spec` | C | **079** |
@ -184,15 +187,23 @@ Jede Phase: `(ctx) → ctx`, Zwischenergebnisse in API-Response für **Human-in-

 | ID | Inhalt | Status |
 |----|--------|--------|
-| **F0** | Spec + Doku + `planning_progression_roadmap.py` Scaffold | 🔄 0.8.204 |
-| **F1** | `include_roadmap_preview` in API + deterministische A/B | 🔄 0.8.204 |
-| **F2** | LLM Phase A/B/C über `ai_prompts` (078/079), `include_llm_roadmap` | 🔄 0.8.205 |
-| **F3** | Retrieval aus `stage_specs` (roadmap_first) | ✅ 0.8.206 |
-| **F4** | UI Roadmap-Review | ✅ 0.8.207 |
-| **F5** | Trainingsplanung: eigene Pipeline + ggf. Workflow-Engine | 🔲 |
+| **F0** | Spec + Doku + `planning_progression_roadmap.py` Scaffold | ✅ 0.8.204 |
+| **F1** | `include_roadmap_preview` in API + deterministische A/B | ✅ 0.8.204 |
+| **F2** | LLM Phase A/B/C über `ai_prompts` (078/079), `include_llm_roadmap` | ✅ 0.8.205 |
+| **F3** | Retrieval aus `stage_specs` (roadmap_first) | ✅ 0.8.206–209 |
+| **F4** | UI Roadmap-Review + `roadmap_override` | ✅ 0.8.207 |
+| **F5** | Start/Ziel strukturiert + Prompt **087** + Zwei-Schritt-UI | ✅ 0.8.210–214 |
+| **F6** | Gap-Prep + `planning_context` an Übungs-KI | ✅ 0.8.212–214 |
+| **F7** | `planning_skill_expectations` | ✅ 0.8.215–216 |
+| **F8** | Editierbare `stage_specs` in UI | ✅ 0.8.216 |
+| **F9** | `planning_roadmap` JSONB (Migration **088**) | ✅ 0.8.217 |
+| **G** | Trainingsplanung: eigene Pipeline + Workflow-Engine | 🔲 |
+
+Details: `docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md`

 ---

 ## 9. Changelog

+- **2026-05-22:** Ist-Stand F5–F9 dokumentiert; Verweis auf `PLANNING_PROGRESSION_GRAPH_KI.md`.
 - **2026-06-07:** Erstfassung — Roadmap-first Entscheidung, Abgrenzung Graphen vs. Planung, Workflow-lite.
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -18,7 +18,7 @@
 > | Architektur-Zielbild, Refaktor-Roadmap, verbindliche Shinkan-Regeln | **`docs/architecture/README.md`** |
 > | Performance-Baseline (Phase 0) | **`docs/architecture/BASELINE_SNAPSHOT.md`** |
 > | KI-Prompt-System — Zielarchitektur | `.claude/docs/technical/AI_PROMPT_TARGET_ARCHITECTURE.md` |
-> | Planungs-KI Progressions-Roadmap (Phase F) | **`.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md`** · **`docs/architecture/PLANNING_KI_ROADMAP.md`** |
+> | Planungs-KI Progressionsgraph (Ist-Stand) | **`docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md`** · Spec **`.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md`** · Roadmap **`docs/architecture/PLANNING_KI_ROADMAP.md`** |

 ## Projekt-Übersicht

--- a/backend/version.py
+++ b/backend/version.py
@ -38,7 +38,7 @@ MODULE_VERSIONS = {
    "skill_profiles": "1.0.0",  # Phase 3: gewichtetes Fähigkeiten-Profil + skill-discovery/suggestions
    "methods": "0.1.0",
    "exercises": "2.37.1",  # KI-Endpoints: feature_usage nach ai_calls consume
-    "planning_exercise_suggest": "0.21.1",  # start_target_only + reicher gap-fill planning_context
+    "planning_exercise_suggest": "0.22.0",  # skill_expectations, planning_roadmap persist (088), stage_specs override
    "training_units": "0.4.0",  # POST .../publish-to-framework: Ablauf aus geplanter Einheit → Rahmen-Slot-Blueprint
    "training_programs": "0.1.0",
    "planning": "0.15.0",  # Vorlagen: Strukturvorschau, Bearbeiten inkl. Split-Sessions + Beschreibung
@ -53,6 +53,48 @@ MODULE_VERSIONS = {
 }

 CHANGELOG = [
+    {
+        "version": "0.8.217",
+        "date": "2026-06-07",
+        "changes": [
+            "F9: planning_roadmap JSONB am Progressionsgraph (Migration 088).",
+            "PUT Graph + POST edges/sequence speichern Planungs-Artefakt; Laden beim Graph-Wechsel.",
+            "Roadmap-Vorschlag: include_llm_intent=true für reicheren Semantic Brief.",
+            "Doku: docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md als zentrale Ist-Referenz.",
+        ],
+    },
+    {
+        "version": "0.8.216",
+        "date": "2026-06-07",
+        "changes": [
+            "F8: Editierbare stage_specs in UI (Belastung, Erfolgskriterien) → roadmap_override.",
+            "Erwartete Fähigkeiten als Tags pro Pfadschritt und auf Pfad-Ebene.",
+        ],
+    },
+    {
+        "version": "0.8.215",
+        "date": "2026-06-07",
+        "changes": [
+            "F7: planning_skill_expectations — pro Stufe Retrieval, path_skill_expectations, Gap-Kontext.",
+            "Wiederverwendbare Scopes für spätere Trainingsplanung (training_section, framework_slot).",
+        ],
+    },
+    {
+        "version": "0.8.214",
+        "date": "2026-06-07",
+        "changes": [
+            "F6: ExerciseGapFillPrepModal — Trainer-Ergänzungen vor KI-Entwurf.",
+            "context_preview und reicher goal_for_ai aus Roadmap-Snapshot.",
+        ],
+    },
+    {
+        "version": "0.8.210",
+        "date": "2026-06-07",
+        "changes": [
+            "F5: Strukturierte Start/Ziel-Felder, Prompt 087, Zwei-Schritt-UI (start_target_only).",
+            "Priorität Trainer-Eingabe > KI > Regex; heuristische Start→Ziel-Roadmap.",
+        ],
+    },
    {
        "version": "0.8.209",
        "date": "2026-06-07",
--- a/docs/HANDOVER.md
+++ b/docs/HANDOVER.md
@ -89,38 +89,39 @@ Das Schema ist gegenüber dem Code zurück: Migration **`022_skills_schema_compl
 - **Varianten:** Speichern in der **Aktionsleiste** persistiert zuerst geänderte Varianten (`persistPendingVariantChanges`), dann Übungs-Stammdaten; „Variante anlegen“ als `type="button"` ohne verschachteltes Formular (`createVariantFromDraft`)
 - **Governance (Übungen):** Owner = `created_by`; Bearbeiten = Ersteller, Plattform-Admin oder `can_plan_in_club` bei `visibility=club`; Löschen `club` = nur `club_admin`; Details **`FEATURES_DELIVERED_2026-Q2.md`** §16, **`EXERCISES_API_SPEC.md`** Permissions

-### 2.8 KI Assistenz Übungen & Planungs-KI Übungssuche (Stand **0.8.183**)
+### 2.8 KI Assistenz Übungen & Planungs-KI (Stand **0.8.217**)

-**Spec / Pipeline:** `.claude/docs/working/PLANNING_EXERCISE_SUGGEST_CONTEXT.md`
+**Zentrale Ist-Doku (Progressionsgraph-KI):** **`docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md`** — bei Drift zuerst dort pflegen.
+
+**Retrieval / Scoring:** `.claude/docs/working/PLANNING_EXERCISE_SUGGEST_CONTEXT.md`  
+**Zielarchitektur Roadmap:** `.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md`  
+**Produkt-Roadmap Phase G+:** `docs/architecture/PLANNING_KI_ROADMAP.md`

 | Phase | Inhalt | Status |
 |-------|--------|--------|
-| **P0** | Kontext-Pack, Hybrid-Score, Planungs-Picker | ✅ |
-| **P0.1** | `ExerciseMatchProfile` / `PlanningTargetProfile`, `profile_v1` | ✅ |
-| **P1** | Szenario-Pipeline + LLM Intent (`073`) + Erwartungsprofil (`074`) | ✅ |
-| **P2 / B2** | LLM-Rerank (`072`) bei engem Top-Feld, max. 2 LLM-Calls | ✅ **0.8.182** |
-| **A** | Voll-Library deterministisch ranken (kein OR-Profil-Pool) | ✅ **0.8.177** |
-| **B** | Text-Signale aus guidance/Rahmen-Zielen (`planning_text_signals`) | ✅ **0.8.181** |
-| **C1** | Progressionsgraph auto-match + variantenbewusste Nachfolger | ✅ **0.8.183** |
-| **C2** | Varianten in Trefferliste / Picker-Auswahl | ✅ **0.8.184** |
-| **C3** | Graph-Builder: Ziel → Pfad vorschlagen → in Graph speichern | ✅ **0.8.185** |
-| **E** | Semantik-Schicht (Brief, Phrasen-Score) + Pfad-QA (Lücken, Brücken, LLM-QS) | ✅ **0.8.186** |
-| **E2** | Pfad-Neuordnung (LLM) + KI-Neuanlage bei unüberbrückbaren Lücken | ✅ **0.8.187** |
-| **E3** | `gap_fill_offers`, Off-Topic-Strip, voller KI-Call bei Lücken | ✅ **0.8.203** |
-| **F0–F2** | Roadmap-Pipeline + LLM-Prompts (078/079) | ✅ **0.8.205** |
-| **F3** | `roadmap_first` — Retrieval + QA lite (keine Brücken/Reorder) | ✅ **0.8.209** |
-| **F4** | Roadmap-Review UI + `roadmap_override` | ✅ **0.8.207** |
-| **D** | `planning_context` an `suggestExerciseAi` (Neu-Anlage) | ✅ **0.8.208** |
+| **P0–P2, A–C2** | Übungssuche, Voll-Library, Graph-Bias, Varianten | ✅ bis **0.8.184** |
+| **C3, E–E3** | Pfad-Builder, Semantik, QA, Gap-Offers | ✅ bis **0.8.203** |
+| **D** | `planning_context` an `suggestExerciseAi` | ✅ **0.8.208** |
+| **F0–F4** | Roadmap-Pipeline, LLM 078/079, `roadmap_first`, UI-Review | ✅ **0.8.205–209** |
+| **F5** | Start/Ziel strukturiert, LLM **087**, Zwei-Schritt-UI | ✅ **0.8.210–214** |
+| **F6** | Gap-Prep-Modal, reicher KI-Kontext (`planning_exercise_form_context`) | ✅ **0.8.212–214** |
+| **F7** | `planning_skill_expectations` — Retrieval + UI + Gap | ✅ **0.8.215–216** |
+| **F8** | Editierbare `stage_specs` (Belastung, Erfolgskriterien) | ✅ **0.8.216** |
+| **F9** | `planning_roadmap` JSONB am Graph (Migration **088**) | ✅ **0.8.217** |

-**Architektur-Entscheidung (2026-06-07):** Progressionsgraph = **Roadmap-first** (Ziel → Major Steps → Übungs-Match). **Keine Gruppenanalyse** im Graphen. Mitai Workflow-Engine **später** — jetzt `planning_progression_roadmap.py`. Spec: **`.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md`** · Roadmap: **`docs/architecture/PLANNING_KI_ROADMAP.md`**
+**Architektur (verbindlich):** Progressionsgraph = **Roadmap-first**, **keine Gruppenanalyse**. Bestehender Graph = **leichter Nachfolger-Bias** ab Schritt 2, **kein** automatisches Erweitern ab letztem Knoten (siehe Ist-Doku §5). Trainingsplanung = **eigene Pipeline** (Phase G), wiederverwendet `planning_skill_expectations`.

-**Backend:** `planning_exercise_suggest.py`, `planning_exercise_retrieval.py`, `planning_exercise_path_builder.py`, **`planning_progression_roadmap.py`** · Router `POST /api/planning/exercise-suggest`, `POST /api/planning/progression-path-suggest` (`roadmap_first`, `include_roadmap_preview`)
+**Backend-Kern:** `planning_progression_roadmap.py`, `planning_exercise_path_builder.py`, `planning_skill_expectations.py`, `planning_exercise_form_context.py`, `planning_exercise_path_ai_fill.py`, `progression_graph_planning_artifact.py`

-**Frontend:** `ExerciseProgressionPathBuilder` — Roadmap-Box + Pfad je Major Step (`roadmap_first`) · `ExercisePickerModal` (Planung)
+**API:** `POST /api/planning/progression-path-suggest` · `PUT /api/exercise-progression-graphs/:id` (`planning_roadmap`) · `POST …/edges/sequence`

-**Superadmin:** Übungs-Anreicherung (Skills) — `exercise_enrichment_admin` (**0.8.178+**), separater Admin-Flow
+**Frontend:** `ExerciseProgressionPathBuilder`, `ExerciseGapFillPrepModal`, `planningContextForExerciseAi.js`

-**Offen (F4+):** Roadmap-UI editierbar; Trainingsplanung eigene Pipeline (Gruppenkontext); Enrichment
+**Offen (priorisiert):**
+1. UI-Wizard (Scroll-Monolith → 4 Schritte) — **separater UI-Chat**
+2. Graph-Erweiterungsmodus (Start ab Knoten)
+3. Trainingsplanung Phase G (Gruppenkontext)
+4. Kontext-Anzeige auf allen Pfad-Schritten

 #### Übungs-KI Formular / Schnellanlage (Stand **0.8.171**)

--- a/docs/architecture/PLANNING_KI_ROADMAP.md
+++ b/docs/architecture/PLANNING_KI_ROADMAP.md
@ -1,10 +1,11 @@
 # Planungs-KI — Produkt-Roadmap

-**Stand:** 2026-06-07  
-**App-Version:** ab **0.8.204** — maßgeblich `backend/version.py`
+**Stand:** 2026-05-22  
+**App-Version:** **0.8.217** — maßgeblich `backend/version.py`

 Diese Roadmap ergänzt die **Architektur-Refaktor-Roadmap** (`UMSETZUNGSPLAN_ROADMAP.md`) und gilt **nur für KI-gestützte Trainingsplanungsunterstützung**.

+**Ist-Stand Progressionsgraph (detailliert):** `PLANNING_PROGRESSION_GRAPH_KI.md`  
 **Leit-Spec:** `.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md`

 ---
@ -26,9 +27,10 @@ Diese Roadmap ergänzt die **Architektur-Refaktor-Roadmap** (`UMSETZUNGSPLAN_ROA
 | A–C2 | Übungssuche | Voll-Library, Graph, Varianten | ✅ |
 | C3 | Progressionsgraph | Pfad-Builder (retrieval-first) | ✅ |
 | E–E3 | Progressionsgraph | Semantik, QA, Lücken-Angebote | ✅ |
-| **F0–F1** | Progressionsgraph | Roadmap-Pipeline Scaffold + API-Preview | 🔄 **0.8.204** |
-| **F2–F4** | Progressionsgraph | LLM Roadmap, roadmap-first Retrieval, UI Review | 🔲 |
+| **F0–F4** | Progressionsgraph | Roadmap-Pipeline, LLM, roadmap-first, UI Review | ✅ **0.8.204–209** |
+| **F5–F9** | Progressionsgraph | Start/Ziel, Gap-Prep, Skill-Expectations, Persistenz | ✅ **0.8.210–217** |
 | D | Übungs-Neuanlage | `planning_context` an `suggestExerciseAi` | ✅ **0.8.208** |
+| **UX** | Progressionsgraph | Wizard/Stepper statt Scroll-UI | 🔲 |
 | G | Trainingsplanung | Kontext-Pack Gruppe/Historie, S0–S4 | 🔲 |
 | H | Plattform | Mitai-Workflow-Engine (optional) | 🔲 Backlog |

@ -70,6 +72,40 @@ Diese Roadmap ergänzt die **Architektur-Refaktor-Roadmap** (`UMSETZUNGSPLAN_ROA
 - [x] Major Steps editierbar (Phase, Lernziel, Reihenfolge) vor Übungs-Match
 - [x] API `roadmap_only` + `roadmap_override`

+### F5 — Start/Ziel (0.8.210–214)
+
+- [x] Strukturierte Felder `start_situation`, `target_state`, `roadmap_notes`
+- [x] Prompt **087** `planning_progression_start_target`
+- [x] Priorität: Trainer > KI > Regex (`resolve_roadmap_structured_input`)
+- [x] Zwei-Schritt-UI: „Start/Ziel analysieren“ / „Roadmap vorschlagen“
+
+### F6 — Gap-KI-Kontext (0.8.212–214)
+
+- [x] `ExerciseGapFillPrepModal` vor KI-Call
+- [x] `planning_exercise_form_context.py` — Gap-Snapshot, `context_preview`
+- [x] Migration **085** — `planning_context` in Übungs-Prompts
+
+### F7 — Fähigkeiten-Scoring (0.8.215–216)
+
+- [x] `planning_skill_expectations.py` (Scopes: `progression_stage`, `progression_path`)
+- [x] Pro-Stufe-Retrieval + `path_skill_expectations` + UI-Tags
+- [x] `expected_skills` in Gap-Fill
+
+### F8 — Stufen-Details UI (0.8.216)
+
+- [x] Editierbare `stage_specs` in `roadmap_override` (Belastung, Erfolgskriterien, Vermeiden)
+
+### F9 — Persistenz (0.8.217)
+
+- [x] Migration **088** — `planning_roadmap` JSONB am Graph
+- [x] Laden/Speichern über `GET/PUT` Graph + Sequenz-Endpoint
+
+### UX — UI-Überarbeitung (offen)
+
+- [ ] Wizard mit 4 Schritten (Ziel → Roadmap → Match → Lücken)
+- [ ] Progressive disclosure — Details in Panels, nicht alles gleichzeitig
+- [ ] Briefing: `PLANNING_PROGRESSION_GRAPH_KI.md` §10
+
 ---

 ## Abhängigkeiten
@ -85,4 +121,4 @@ Diese Roadmap ergänzt die **Architektur-Refaktor-Roadmap** (`UMSETZUNGSPLAN_ROA

 ## Pflege

-Bei Abschluss einer Teilphase: diese Datei, `HANDOVER.md` §2.8, `PLANNING_EXERCISE_SUGGEST_CONTEXT.md` §24, Changelog in `version.py`.
+Bei Abschluss einer Teilphase: **`PLANNING_PROGRESSION_GRAPH_KI.md`** (Ist-Stand), diese Datei, `HANDOVER.md` §2.8, `PLANNING_EXERCISE_SUGGEST_CONTEXT.md` §24, Changelog in `version.py`.
--- a/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md
+++ b/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md
@ -0,0 +1,314 @@
+# Progressionsgraph — KI-Planung (Ist-Stand)
+
+**Stand:** 2026-05-22 (Dokumentation) · **App-Version:** **0.8.217** · **DB:** Migration **088**  
+**Maßgeblich für Code:** `backend/version.py` (`APP_VERSION`, `DB_SCHEMA_VERSION`)
+
+> **Diese Datei ist die zentrale Referenz** für die KI-gestützte Planung im Progressionsgraph.  
+> Ältere Abschnitte in `HANDOVER.md` §2.8 und `PLANNING_KI_ROADMAP.md` verweisen hierher.
+
+**Bezüge:**  
+`.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md` (Zielarchitektur) ·  
+`.claude/docs/working/PLANNING_EXERCISE_SUGGEST_CONTEXT.md` (Retrieval/Scoring) ·  
+`.claude/docs/technical/SKILL_SCORING_SPEC.md` (Fähigkeiten-Scoring) ·  
+`docs/architecture/PLANNING_KI_ROADMAP.md` (Produkt-Roadmap Phase G+)
+
+---
+
+## 1. Fachliche Abgrenzung
+
+| Thema | Progressionsgraph (dieses Feature) | Trainingsplanung (Phase G, später) |
+|--------|-------------------------------------|-------------------------------------|
+| Ziel | Curriculum / Technikpfad über Übungen | Konkrete Trainingseinheit für Gruppe |
+| Kontext | Zieltext, Start/Ziel, Roadmap, optional Graph-Kanten | Gruppe, Historie, Termin, Rahmen |
+| Pipeline | `planning_progression_roadmap.py` → Path-Builder | Eigene Pipeline (noch offen) |
+| Gruppenanalyse | **Nein** | **Ja** |
+| Wiederverwendung | `planning_skill_expectations.py`, `planning_exercise_form_context.py` | Gleiche Bausteine, andere Scopes |
+
+**Shinkan-Regel:** Der Progressionsgraph ist **keine** persönliche Tracking-App und plant **nicht** für einzelne Sportler.
+
+---
+
+## 2. Trainer-Workflow (UI)
+
+Aktuell in `ExerciseProgressionPathBuilder.jsx` (eingebettet in `ExerciseProgressionGraphPanel.jsx`):
+
+```
+① Ziel eingeben (+ optional Start/Ziel-Felder manuell)
+② „Start/Ziel analysieren“ (optional, start_target_only)
+③ „Roadmap vorschlagen“ (roadmap_only, LLM-Roadmap)
+④ Roadmap bearbeiten (Major Steps + Stufen-Details)
+⑤ „Übungen matchen“ (roadmap_first + roadmap_override)
+⑥ Lücken mit KI schließen (gap_fill_offers + Vorbereitungs-Dialog)
+⑦ „Pfad in Graph speichern“ (Sequenz-Kanten)
+```
+
+**Bekannte UX-Schuld:** Alle Schritte liegen auf **einer langen Scroll-Seite** — Überarbeitung als Wizard/Stepper ist geplant (separater UI-Chat). Briefing-Vorlage siehe unten §10.
+
+---
+
+## 3. Architektur (Module)
+
+```mermaid
+flowchart TB
+    subgraph ui [Frontend]
+        EPB[ExerciseProgressionPathBuilder]
+        GFM[ExerciseGapFillPrepModal]
+        PCtx[planningContextForExerciseAi.js]
+    end
+
+    subgraph api [API]
+        PPS[POST /api/planning/progression-path-suggest]
+        EAI[POST /api/exercises/ai/suggest]
+        SEQ[POST /api/exercise-progression-graphs/:id/edges/sequence]
+        PUT[PUT /api/exercise-progression-graphs/:id]
+    end
+
+    subgraph roadmap [Roadmap-Pipeline]
+        PR[planning_progression_roadmap.py]
+        ST087[Prompt 087 start_target]
+        ST078[Prompts 078/079 roadmap + stage_spec]
+    end
+
+    subgraph match [Match + QA]
+        PB[planning_exercise_path_builder.py]
+        RET[planning_exercise_retrieval.py]
+        PG[planning_exercise_progression.py]
+        SEM[planning_exercise_semantics.py]
+    end
+
+    subgraph skills [Fähigkeiten — wiederverwendbar]
+        PSE[planning_skill_expectations.py]
+        PEFC[planning_exercise_form_context.py]
+        AIF[planning_exercise_path_ai_fill.py]
+    end
+
+    subgraph persist [Persistenz Graph]
+        G088[(planning_roadmap JSONB — Migration 088)]
+        EDGES[(exercise_progression_edges)]
+    end
+
+    EPB --> PPS
+    EPB --> SEQ
+    EPB --> PUT
+    GFM --> EAI
+    PPS --> PR
+    PPS --> PB
+    PB --> RET
+    PB --> PG
+    PB --> PSE
+    AIF --> PEFC
+    PSE --> RET
+    SEQ --> EDGES
+    PUT --> G088
+    SEQ --> G088
+```
+
+### 3.1 Verantwortlichkeiten
+
+| Modul | Aufgabe |
+|--------|---------|
+| `planning_progression_roadmap.py` | Phasen A–C: Zielanalyse, Roadmap, `stage_specs`; Start/Ziel-Auflösung (Trainer > KI > Regex) |
+| `planning_exercise_path_builder.py` | `suggest_progression_path`: roadmap_first Match, QA, Gap-Offers |
+| `planning_exercise_progression.py` | Graph auflösen, Nachfolger-Kanten für Retrieval-Bias |
+| `planning_skill_expectations.py` | Skill-Erwartungen pro Scope (`progression_stage`, `progression_path`, später `training_section`) |
+| `planning_exercise_form_context.py` | `planning_context` / Gap-Snapshot für Übungs-KI |
+| `planning_exercise_path_ai_fill.py` | Gap-Fill-Angebote, `goal_for_ai`, `context_preview` |
+| `progression_graph_planning_artifact.py` | Validierung `planning_roadmap` JSON (Schema v1, max. 64 KB) |
+
+---
+
+## 4. API — `POST /api/planning/progression-path-suggest`
+
+### 4.1 Wichtige Request-Flags
+
+| Feld | Typ | Bedeutung |
+|------|-----|-----------|
+| `query` | string | Ziel / Entwicklungsrichtung (min. 3 Zeichen) |
+| `max_steps` | int | Anzahl Major Steps (2–10) |
+| `progression_graph_id` | int? | Gewählter Graph — siehe §5 |
+| `roadmap_first` | bool | Match pro `stage_spec` statt iterativem Pfad |
+| `roadmap_only` | bool | Nur Roadmap, keine Übungen |
+| `start_target_only` | bool | Nur Start/Ziel-Analyse |
+| `roadmap_override` | object | Trainer-bearbeitete `major_steps` + `stage_specs` |
+| `start_situation`, `target_state`, `roadmap_notes` | string? | Strukturierte Eingabe (Priorität vor KI) |
+| `include_llm_start_target` | bool | LLM-Extraktion Start/Ziel (Prompt **087**) |
+| `include_llm_roadmap` | bool | LLM Roadmap (Prompts **078/079**) |
+| `include_llm_intent` | bool | LLM Intent für Semantic Brief (Roadmap-Vorschlag: **true** seit 0.8.217) |
+| `include_path_qa`, `include_ai_gap_fill` | bool | QS, Lücken-Angebote |
+
+### 4.2 Wichtige Response-Felder
+
+| Feld | Bedeutung |
+|------|-----------|
+| `progression_roadmap` | Artefakte A/B/C inkl. `resolved_structured`, `stage_specs`, `prompt_slugs` |
+| `steps[]` | Gematchte Übungen; pro Schritt u. a. `roadmap_*`, `skill_expectations` |
+| `path_skill_expectations` | Pfadweite Skill-Erwartungen |
+| `gap_fill_offers[]` | Lücken mit `context_preview`, `goal_for_ai` |
+| `path_qa` | QS inkl. `roadmap_qa_mode: roadmap_first_lite` |
+
+### 4.3 Prompt-Slugs (nur in `ai_prompts`, nie Hardcoding)
+
+| Slug | Migration | Phase |
+|------|-----------|-------|
+| `planning_progression_start_target` | **087** | Start/Ziel-Extraktion |
+| `planning_progression_goal_analysis` | **078** | Zielanalyse |
+| `planning_progression_roadmap` | **078** | Roadmap (micro → major) |
+| `planning_progression_stage_spec` | **079** | Stufenspezifikation |
+
+---
+
+## 5. Rolle des bestehenden Graphs
+
+**Wichtig — häufiges Missverständnis:**
+
+| Aspekt | Verhalten |
+|--------|-----------|
+| **KI-Pfadvorschlag** | Baut einen **neuen** Übungspfad aus der **Bibliothek** (Roadmap-first), nicht aus vorhandenen Graph-Knoten als Start |
+| **Schritt 1** | Kein Anker → **kein** Graph-Bias |
+| **Ab Schritt 2** | Anker = vorherige Übung im Vorschlag → ausgehende Kanten im Graph werden geladen |
+| **Scoring** | Nachfolger im Graph: Bonus `progression` (ca. **4–10 %** Gewicht, Semantik/Profil dominieren) |
+| **Speichern** | `POST …/edges/sequence` **fügt Kanten hinzu** — ersetzt den Graph nicht |
+| **Nicht implementiert** | „Ab letztem Graph-Knoten erweitern“, bestehende Sequenz als Pfad-Start |
+
+Code: `planning_exercise_progression.py` → `apply_progression_context_to_pack` → `planning_exercise_retrieval.py` (`prog_hit`).
+
+---
+
+## 6. Persistenz
+
+### 6.1 Kanten (`exercise_progression_edges`)
+
+- Übungsfolge als gerichtete Kanten `next_exercise`
+- Varianten-aware (Migration **034**)
+- Kanten-Notizen aus Pfad-Begründungen oder Fallback-`segment_notes`
+
+### 6.2 Planungs-Artefakt (`planning_roadmap` JSONB, Migration **088**)
+
+Gespeichert am **Graph-Container** (`exercise_progression_graphs`), Schema v1:
+
+```json
+{
+  "schema_version": 1,
+  "goal_query": "…",
+  "start_situation": "…",
+  "target_state": "…",
+  "roadmap_notes": "…",
+  "max_steps": 5,
+  "progression_roadmap": { },
+  "path_skill_expectations": { }
+}
+```
+
+| Aktion | API |
+|--------|-----|
+| Speichern (Roadmap/Match) | `PUT /api/exercise-progression-graphs/:id` |
+| Speichern (mit Pfad) | `POST …/edges/sequence` (optional `planning_roadmap` im Body) |
+| Laden | `GET /api/exercise-progression-graphs/:id` → Frontend stellt Workflow-Felder wieder her |
+
+Validierung: `progression_graph_planning_artifact.py` · Tests: `test_progression_graph_planning_artifact.py`
+
+**`planning_roadmap` ≠ Graph-Kanten:** Metadaten für Wiederaufnahme der KI-Planung, nicht der Übungsgraph selbst.
+
+---
+
+## 7. Fähigkeiten-Scoring-Anbindung
+
+Modul: `planning_skill_expectations.py`
+
+| Scope | Verwendung heute | Phase G (vorbereitet) |
+|-------|------------------|------------------------|
+| `progression_path` | Einmaliges Pfad-Profil (`path_skill_expectations`) | — |
+| `progression_stage` | Pro Roadmap-Stufe vor Retrieval + in Gap-Kontext | — |
+| `training_section` | — | Trainingsabschnitt |
+| `framework_slot` | — | Rahmen-Slot |
+
+Quellen: `semantic_topic`, `text_match`, `load_profile` (aus `stage_spec`).
+
+Integration:
+- Retrieval: `apply_expectations_to_target` → Hybrid-Score
+- UI: Tags pro Pfadschritt + Pfad-Header; Gap-Kontext „Erwartete Fähigkeiten“
+- KI-Neuanlage: `expected_skills` in `context_preview` / `goal_for_ai`
+
+---
+
+## 8. KI-Lücken (Gap-Fill)
+
+Flow:
+1. `roadmap_unfilled` / QA-Lücken → `gap_fill_offers`
+2. Trainer: **„Vorbereiten & KI anlegen“** → `ExerciseGapFillPrepModal` (Titel, Stufen-Lernziel, Ergänzungen)
+3. `POST /api/exercises/ai/suggest` mit `planning_context`
+4. Vorschau → Übung anlegen → in Pfad einfügen
+
+Kontext-Helfer: `frontend/src/utils/planningContextForExerciseAi.js`
+
+---
+
+## 9. Implementierungsstände (Phasen)
+
+| Phase | Inhalt | Status | Version |
+|-------|--------|--------|---------|
+| F0–F2 | Roadmap-Pipeline + LLM-Prompts 078/079 | ✅ | 0.8.204–205 |
+| F3 | `roadmap_first` Match pro Stufe | ✅ | 0.8.206–209 |
+| F4 | Roadmap-Review UI + `roadmap_override` | ✅ | 0.8.207 |
+| F5 | Start/Ziel strukturiert + LLM **087** + Zwei-Schritt-UI | ✅ | 0.8.210–214 |
+| F6 | Gap-Prep-Modal + reicher `planning_context` | ✅ | 0.8.212–214 |
+| F7 | `planning_skill_expectations` (Retrieval + UI + Gap) | ✅ | 0.8.215–216 |
+| F8 | Editierbare `stage_specs` in UI | ✅ | 0.8.216 |
+| F9 | `planning_roadmap` Persistenz (Migration **088**) | ✅ | 0.8.217 |
+| **G** | Trainingsplanung eigene Pipeline + Graph-Referenz | 🔲 | — |
+| **UX** | Wizard/Stepper statt Scroll-Monolith | 🔲 | separater Chat |
+
+---
+
+## 10. Offenes Backlog (priorisiert)
+
+1. **UI-Überarbeitung** — Wizard mit 4 Schritten, progressive disclosure (Briefing unten)
+2. **Graph-Erweiterungsmodus** — Start ab gewähltem Knoten / letzter Sequenz
+3. **Kontext auf allen Pfad-Schritten** in UI (nicht nur Lücken)
+4. **Trainingsplanung Phase G** — Pipeline mit Gruppenkontext, Wiederverwendung `planning_skill_expectations`
+5. Enrichment / Prompt-Feintuning
+6. Mitai Workflow-Engine (langfristig)
+
+### Briefing-Vorlage UI-Chat (Copy-Paste)
+
+Siehe Nutzer-Chat 2026-05-22 oder `HANDOVER.md` §2.8 — Abschnitt „UI-Überarbeitung“.
+
+Kern: Wizard ① Ziel & Start/Ziel → ② Roadmap → ③ Match → ④ Lücken & Speichern; Backend-Pipeline unverändert lassen.
+
+---
+
+## 11. Tests
+
+| Datei | Abdeckung |
+|-------|-----------|
+| `test_planning_progression_roadmap.py` | Roadmap-Pipeline, Override, Start/Ziel |
+| `test_planning_exercise_path_builder.py` | Pfad-Annotierung, Skill-Expectations auf Steps |
+| `test_planning_skill_expectations.py` | Skill-Erwartungen, Scopes |
+| `test_planning_exercise_path_ai_fill.py` | Gap-Fill, `expected_skills` in goal text |
+| `test_planning_exercise_form_context.py` | `planning_context`, Gap-Snapshot |
+| `test_progression_graph_planning_artifact.py` | JSONB-Artefakt-Validierung |
+| `test_planning_exercise_progression.py` | Graph-Auflösung, Nachfolger |
+
+---
+
+## 12. Dokumenten-Index (Drift vermeiden)
+
+| Frage | Primäre Quelle |
+|-------|----------------|
+| Was ist der aktuelle Ist-Stand? | **Diese Datei** |
+| Zielarchitektur / JSON-Artefakte | `PLANNING_PROGRESSION_ROADMAP_SPEC.md` |
+| Retrieval, Hybrid-Score, Intents | `PLANNING_EXERCISE_SUGGEST_CONTEXT.md` |
+| Produkt-Roadmap Phase G+ | `PLANNING_KI_ROADMAP.md` |
+| Session-Handover / nächste Schritte | `docs/HANDOVER.md` §2.8 |
+| Fähigkeiten-Scoring allgemein | `SKILL_SCORING_SPEC.md` |
+| Versionen / Changelog | `backend/version.py` |
+
+**Pflege-Regel:** Bei jeder abgeschlossenen Teilphase diese Datei + `HANDOVER.md` §2.8 + `version.py` CHANGELOG aktualisieren.
+
+---
+
+## 13. Changelog (Dokument)
+
+| Datum | Änderung |
+|-------|----------|
+| 2026-05-22 | Erstfassung Ist-Stand 0.8.217 — zentrale Referenz nach F5–F9 |
--- a/docs/architecture/README.md
+++ b/docs/architecture/README.md
@ -14,7 +14,8 @@ Dieses Bündel ist die **Leitlinie für die große Refaktorierung** nach dem MVP
 | [`frontend/src/api/planning.js`](../../frontend/src/api/planning.js) | Phase 4: Trainingsplanung (Einheiten, Vorlagen, Module, Rahmen, KPIs) |
 | [BASELINE_SNAPSHOT.md](./BASELINE_SNAPSHOT.md) | Phase 0: Bundle-, API- und Last-Baseline (Messvorlagen, Vergleich nach Phase 2) |
 | [KI-Prompt-Zielarchitektur](../../.claude/docs/technical/AI_PROMPT_TARGET_ARCHITECTURE.md) | Roadmap: Kontext-Arten, Composition, Planung/Rahmen, Phasenplan (verbindliche Zielrichtung) |
-| [PLANNING_KI_ROADMAP.md](./PLANNING_KI_ROADMAP.md) | **Planungs-KI Produkt-Roadmap** (Phase F Roadmap-first, Abgrenzung Trainingsplanung) |
+| [PLANNING_PROGRESSION_GRAPH_KI.md](./PLANNING_PROGRESSION_GRAPH_KI.md) | **Progressionsgraph-KI Ist-Stand** (Module, API, Graph-Verhalten, Persistenz — zentrale Referenz) |
+| [PLANNING_KI_ROADMAP.md](./PLANNING_KI_ROADMAP.md) | **Planungs-KI Produkt-Roadmap** (Phase F–G, Abgrenzung Trainingsplanung) |
 | [Progressions-Roadmap Spec](../../.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md) | Phase F: Artefakte A→B→C, API, Workflow-lite |

 ## Tests (E2E / Refaktor-Budget)