From 0adf20c9e10e3fadb2082289c0e7749f84b84996 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Wed, 10 Jun 2026 06:54:49 +0200
Subject: [PATCH 01/33] Enhance Gap Planning Context with Stage Overrides and
 Trainer Supplements

- Added `stage_learning_goal_override` and `gap_trainer_supplements` parameters to `build_progression_path_gap_planning_context`, allowing for customized learning goals and additional trainer notes.
- Updated `gapOfferContextDisplayLines` to include trainer supplements in the context display.
- Enhanced `ExerciseProgressionPathBuilder` to utilize new parameters for improved gap fill offer handling.
- Incremented application version to 0.8.214 to reflect these changes.
---
 backend/planning_exercise_form_context.py     |   7 +
 .../test_planning_exercise_form_context.py    |  11 ++
 backend/version.py                            |   2 +-
 .../ExerciseProgressionPathBuilder.jsx        | 134 ++++++++++---
 .../exercises/ExerciseGapFillPrepModal.jsx    | 186 ++++++++++++++++++
 .../src/utils/planningContextForExerciseAi.js |  13 +-
 6 files changed, 323 insertions(+), 30 deletions(-)
 create mode 100644 frontend/src/components/exercises/ExerciseGapFillPrepModal.jsx

diff --git a/backend/planning_exercise_form_context.py b/backend/planning_exercise_form_context.py
index 3394261..6972c93 100644
--- a/backend/planning_exercise_form_context.py
+++ b/backend/planning_exercise_form_context.py
@@ -168,6 +168,8 @@ def build_progression_path_gap_planning_context(
     resolved_structured: Optional[Mapping[str, Any]] = None,
     stage_spec: Optional[Mapping[str, Any]] = None,
     semantic_brief: Optional[Mapping[str, Any]] = None,
+    stage_learning_goal_override: Optional[str] = None,
+    gap_trainer_supplements: Optional[str] = None,
 ) -> Dict[str, Any]:
     """Kontext für KI-Neuanlage aus Progressionsgraph-Pfad-Lücke."""
     offer = offer or {}
@@ -205,6 +207,11 @@ def build_progression_path_gap_planning_context(
         semantic_brief=semantic_brief,
     )
     ctx.update(snap)
+    if stage_learning_goal_override and stage_learning_goal_override.strip():
+        ctx["stage_learning_goal"] = _trim_str(stage_learning_goal_override, limit=1200)
+        ctx["roadmap_learning_goal"] = ctx["stage_learning_goal"]
+    if gap_trainer_supplements and gap_trainer_supplements.strip():
+        ctx["gap_trainer_supplements"] = _trim_str(gap_trainer_supplements, limit=2000)
     return sanitize_planning_context_for_ai(ctx)
 
 
diff --git a/backend/tests/test_planning_exercise_form_context.py b/backend/tests/test_planning_exercise_form_context.py
index 772e2ff..3079065 100644
--- a/backend/tests/test_planning_exercise_form_context.py
+++ b/backend/tests/test_planning_exercise_form_context.py
@@ -78,3 +78,14 @@ def test_gap_planning_context_carries_snapshot_fields():
     )
     assert ctx["start_situation"] == "Start"
     assert ctx["stage_learning_goal"] == "Stufenziel"
+
+
+def test_gap_planning_context_trainer_supplements_and_stage_override():
+    ctx = build_progression_path_gap_planning_context(
+        goal_query="Kumite",
+        stage_spec={"learning_goal": "Original"},
+        stage_learning_goal_override="Angepasstes Stufenziel",
+        gap_trainer_supplements="Nur Partnerübung, Kindergruppe",
+    )
+    assert ctx["stage_learning_goal"] == "Angepasstes Stufenziel"
+    assert ctx["gap_trainer_supplements"] == "Nur Partnerübung, Kindergruppe"
diff --git a/backend/version.py b/backend/version.py
index f3eec53..e55663f 100644
--- a/backend/version.py
+++ b/backend/version.py
@@ -1,6 +1,6 @@
 # Shinkan Jinkendo Version Information
 
-APP_VERSION = "0.8.213"
+APP_VERSION = "0.8.214"
 BUILD_DATE = "2026-06-07"
 DB_SCHEMA_VERSION = "20260607087"
 
diff --git a/frontend/src/components/ExerciseProgressionPathBuilder.jsx b/frontend/src/components/ExerciseProgressionPathBuilder.jsx
index 6b3f535..7288ec8 100644
--- a/frontend/src/components/ExerciseProgressionPathBuilder.jsx
+++ b/frontend/src/components/ExerciseProgressionPathBuilder.jsx
@@ -4,6 +4,7 @@
 import React, { useCallback, useEffect, useState } from 'react'
 import api from '../utils/api'
 import ExerciseAiQuickCreateModal from './exercises/ExerciseAiQuickCreateModal'
+import ExerciseGapFillPrepModal from './exercises/ExerciseGapFillPrepModal'
 import ExerciseAiSuggestPreviewModal from './ExerciseAiSuggestPreviewModal'
 import {
   aiPreviewToQuickCreateDraft,
@@ -13,6 +14,7 @@ import {
 import {
   buildPathGapPlanningContextForAi,
   gapOfferContextDisplayLines,
+  initialStageLearningGoalFromOffer,
 } from '../utils/planningContextForExerciseAi'
 
 function applyResolvedStructuredFromRoadmap(progressionRoadmap, setters) {
@@ -252,6 +254,12 @@ export default function ExerciseProgressionPathBuilder({
   const [quickSaving, setQuickSaving] = useState(false)
   const [quickAiError, setQuickAiError] = useState('')
   const [activePlanningContextLines, setActivePlanningContextLines] = useState([])
+  const [gapPrepOpen, setGapPrepOpen] = useState(false)
+  const [gapPrepTitle, setGapPrepTitle] = useState('')
+  const [gapPrepStageGoal, setGapPrepStageGoal] = useState('')
+  const [gapPrepSupplements, setGapPrepSupplements] = useState('')
+  const [gapPrepFocusAreaId, setGapPrepFocusAreaId] = useState('')
+  const [gapPrepError, setGapPrepError] = useState('')
 
   useEffect(() => {
     let cancelled = false
@@ -391,13 +399,6 @@ export default function ExerciseProgressionPathBuilder({
     setQuickAiError('')
   }
 
-  const handleGapFillClick = async (offer) => {
-    if (!confirmPathExpansionIfNeeded(offer, pathSteps.length, maxSteps, setMaxSteps)) {
-      return
-    }
-    await runGapFillAiSuggest(offer)
-  }
-
   const gapContextFallbackParams = {
     goalQuery,
     semanticBrief,
@@ -410,21 +411,70 @@ export default function ExerciseProgressionPathBuilder({
     roadmapNotes,
   }
 
-  const runGapFillAiSuggest = async (offer) => {
-    const title = (offer?.title_hint || '').trim()
-    if (title.length < 3) {
-      alert('Titel-Hinweis fehlt — bitte Pfad erneut vorschlagen.')
+  const closeGapFillPrep = () => {
+    if (quickSaving) return
+    setGapPrepOpen(false)
+    setGapPrepError('')
+  }
+
+  const openGapFillPrep = (offer) => {
+    const defaultFocus = resolveDefaultFocusAreaId(targetSummary, focusAreas)
+    setActiveOffer(offer)
+    setGapPrepTitle((offer?.title_hint || '').trim())
+    setGapPrepStageGoal(initialStageLearningGoalFromOffer(offer, gapContextFallbackParams))
+    setGapPrepSupplements('')
+    setGapPrepFocusAreaId(defaultFocus ? String(defaultFocus) : '')
+    setActivePlanningContextLines(gapOfferContextDisplayLines(offer, gapContextFallbackParams))
+    setGapPrepError('')
+    setGapPrepOpen(true)
+  }
+
+  const handleGapFillClick = (offer) => {
+    if (!confirmPathExpansionIfNeeded(offer, pathSteps.length, maxSteps, setMaxSteps)) {
       return
     }
-    const goalText = (offer?.goal_for_ai || offer?.sketch || '').trim()
-    const focusId = resolveDefaultFocusAreaId(targetSummary, focusAreas)
+    openGapFillPrep(offer)
+  }
+
+  const submitGapFillPrep = async () => {
+    const title = (gapPrepTitle || '').trim()
+    if (title.length < 3) {
+      alert('Titel: mindestens 3 Zeichen.')
+      return
+    }
+    const focusId = parseInt(String(gapPrepFocusAreaId).trim(), 10)
+    if (!Number.isFinite(focusId) || focusId < 1) {
+      alert('Bitte einen Fokusbereich wählen.')
+      return
+    }
+    if (!activeOffer) return
+    setGapPrepError('')
+    await runGapFillAiSuggest(activeOffer, {
+      title,
+      stageLearningGoal: (gapPrepStageGoal || '').trim(),
+      supplements: (gapPrepSupplements || '').trim(),
+      focusAreaId: focusId,
+    })
+  }
+
+  const runGapFillAiSuggest = async (offer, prep = null) => {
+    const title = (prep?.title || offer?.title_hint || '').trim()
+    if (title.length < 3) {
+      alert('Titel: mindestens 3 Zeichen.')
+      return
+    }
+    const supplements = (prep?.supplements || '').trim()
+    const stageGoal = (prep?.stageLearningGoal || '').trim()
+    let goalText = (offer?.goal_for_ai || offer?.sketch || '').trim()
+    if (supplements) {
+      goalText = `${goalText}\n\nTrainer-Ergänzungen für diese Übung:\n${supplements}`.trim()
+    }
+    const focusId =
+      prep?.focusAreaId != null && Number.isFinite(Number(prep.focusAreaId))
+        ? Number(prep.focusAreaId)
+        : resolveDefaultFocusAreaId(targetSummary, focusAreas)
     if (!focusId) {
-      alert('Kein Fokusbereich verfügbar — bitte Kataloge laden oder manuell wählen.')
-      setQuickTitle(title)
-      setQuickSketch(goalText)
-      setQuickFocusAreaId('')
-      setActiveOffer(offer)
-      setQuickCreateOpen(true)
+      alert('Kein Fokusbereich verfügbar — bitte im Vorbereitungsdialog wählen.')
       return
     }
     const focusRow = (focusAreas || []).find((x) => Number(x.id) === focusId)
@@ -438,11 +488,16 @@ export default function ExerciseProgressionPathBuilder({
     setQuickCreateDraft(null)
     setQuickSaving(true)
     setGeneratingOfferId(offer?.offer_id || null)
-    const contextLines = gapOfferContextDisplayLines(offer, gapContextFallbackParams)
+    const contextParams = {
+      ...gapContextFallbackParams,
+      stageLearningGoalOverride: stageGoal,
+      gapTrainerSupplements: supplements,
+    }
+    const contextLines = gapOfferContextDisplayLines(offer, contextParams)
     setActivePlanningContextLines(contextLines)
     const planningContext = buildPathGapPlanningContextForAi({
       offer,
-      ...gapContextFallbackParams,
+      ...contextParams,
     })
     try {
       const aiRes = await api.suggestExerciseAi({
@@ -450,7 +505,7 @@ export default function ExerciseProgressionPathBuilder({
         goal: goalText || undefined,
         execution: '',
         preparation: '',
-        trainer_notes: '',
+        trainer_notes: supplements || '',
         focus_area_hint: focusHint || undefined,
         focus_areas_context: [{ focus_area_id: focusId, is_primary: true }],
         planning_context: planningContext || undefined,
@@ -469,12 +524,13 @@ export default function ExerciseProgressionPathBuilder({
           sketchPlain: goalText,
         }),
       )
+      setGapPrepOpen(false)
       setQuickCreateOpen(false)
     } catch (e) {
       console.error(e)
       const msg = e?.message || String(e)
+      setGapPrepError(msg)
       setQuickAiError(msg)
-      setQuickCreateOpen(true)
     } finally {
       setQuickSaving(false)
       setGeneratingOfferId(null)
@@ -1205,7 +1261,7 @@ export default function ExerciseProgressionPathBuilder({
             Fehlende oder zu ersetzende Schritte ({pathSteps.length}/{maxSteps} im Pfad).
             {pathSteps.length >= maxSteps
               ? ' Der Pfad ist voll — beim Einfügen können Sie die Pfadlänge dynamisch vergrößern (ohne neuen Vorschlag); Ersatz-Angebote ersetzen einen Schritt.'
-              : ' „Mit KI anlegen“ erzeugt einen vollständigen Entwurf und fügt die Übung ein.'}
+              : ' Zuerst Kontext prüfen und ergänzen, dann KI-Entwurf erstellen und einfügen.'}
           </p>
           <div style={{ display: 'flex', flexDirection: 'column', gap: '10px' }}>
             {gapFillOffers.map((offer) => (
@@ -1255,12 +1311,12 @@ export default function ExerciseProgressionPathBuilder({
                           : 'Pfad voll — Klick fragt, ob die Pfadlänge vergrößert werden soll'
                         : offer.replace_step_index != null
                           ? 'Ersetzt den themenfremden Schritt im Pfad'
-                          : 'KI-Entwurf mit Pfad-Kontext generieren'
+                          : 'Kontext prüfen, Ergänzungen mitgeben, dann KI-Entwurf'
                     }
                   >
                     {generatingOfferId === offer.offer_id
                       ? 'KI erstellt Entwurf …'
-                      : 'Mit KI anlegen'}
+                      : 'Vorbereiten & KI anlegen'}
                   </button>
                 </div>
               </div>
@@ -1406,6 +1462,25 @@ export default function ExerciseProgressionPathBuilder({
         </>
       ) : null}
 
+      <ExerciseGapFillPrepModal
+        open={gapPrepOpen}
+        onClose={closeGapFillPrep}
+        offer={activeOffer}
+        contextLines={activePlanningContextLines}
+        title={gapPrepTitle}
+        onTitleChange={setGapPrepTitle}
+        stageLearningGoal={gapPrepStageGoal}
+        onStageLearningGoalChange={setGapPrepStageGoal}
+        supplements={gapPrepSupplements}
+        onSupplementsChange={setGapPrepSupplements}
+        focusAreaId={gapPrepFocusAreaId}
+        onFocusAreaChange={setGapPrepFocusAreaId}
+        focusAreas={focusAreas}
+        busy={quickSaving}
+        error={gapPrepError}
+        onSubmit={submitGapFillPrep}
+      />
+
       <ExerciseAiQuickCreateModal
         open={quickCreateOpen}
         onClose={closeQuickCreate}
@@ -1428,8 +1503,11 @@ export default function ExerciseProgressionPathBuilder({
         onDraftChange={setQuickCreateDraft}
         onDiscard={() => {
           setQuickCreateDraft(null)
-          setActivePlanningContextLines([])
-          if (activeOffer) setQuickCreateOpen(true)
+          if (activeOffer) {
+            setGapPrepOpen(true)
+          } else {
+            setActivePlanningContextLines([])
+          }
         }}
         planningContextLines={activePlanningContextLines}
         onApply={applyQuickCreateDraft}
diff --git a/frontend/src/components/exercises/ExerciseGapFillPrepModal.jsx b/frontend/src/components/exercises/ExerciseGapFillPrepModal.jsx
new file mode 100644
index 0000000..196982a
--- /dev/null
+++ b/frontend/src/components/exercises/ExerciseGapFillPrepModal.jsx
@@ -0,0 +1,186 @@
+import React, { useEffect } from 'react'
+
+/**
+ * Vorbereitung vor KI-Übungsanlage aus Pfad-Lücke: Kontext prüfen, Ergänzungen mitgeben.
+ */
+export default function ExerciseGapFillPrepModal({
+  open,
+  onClose,
+  offer = null,
+  contextLines = [],
+  title = '',
+  onTitleChange,
+  stageLearningGoal = '',
+  onStageLearningGoalChange,
+  supplements = '',
+  onSupplementsChange,
+  focusAreaId = '',
+  onFocusAreaChange,
+  focusAreas = [],
+  busy = false,
+  error = '',
+  onSubmit,
+}) {
+  useEffect(() => {
+    if (!open) return undefined
+    const onKey = (e) => {
+      if (e.key === 'Escape' && !busy) {
+        e.preventDefault()
+        onClose()
+      }
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [open, busy, onClose])
+
+  if (!open || !offer) return null
+
+  const readOnlyLines = (contextLines || []).filter(
+    (line) => line.label !== 'Stufen-Lernziel',
+  )
+
+  return (
+    <div
+      className="admin-modal-backdrop"
+      role="presentation"
+      onClick={(e) => {
+        if (e.target === e.currentTarget && !busy) onClose()
+      }}
+    >
+      <div
+        className="admin-modal-sheet"
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="gap-fill-prep-title"
+        onClick={(e) => e.stopPropagation()}
+        style={{ maxWidth: '680px' }}
+      >
+        <div className="admin-modal-sheet__header">
+          <h3 id="gap-fill-prep-title" className="admin-modal-sheet__title">
+            Übung mit KI vorbereiten
+          </h3>
+          <button
+            type="button"
+            className="btn btn-secondary admin-modal-sheet__close"
+            disabled={busy}
+            onClick={onClose}
+          >
+            Schließen
+          </button>
+        </div>
+        <div className="admin-modal-sheet__body">
+          <p className="muted" style={{ marginTop: 0, marginBottom: '12px', lineHeight: 1.45 }}>
+            Prüfen und anpassen, was an die KI geht. Ergänzungen fließen in Ziel, Trainerhinweise und
+            Planungskontext ein — erst danach wird der Entwurf erzeugt.
+          </p>
+
+          {readOnlyLines.length > 0 ? (
+            <div
+              style={{
+                marginBottom: '14px',
+                padding: '10px 12px',
+                borderRadius: '8px',
+                border: '1px solid var(--border)',
+                background: 'var(--surface2)',
+                fontSize: '12px',
+              }}
+            >
+              <strong style={{ display: 'block', marginBottom: '6px' }}>Pfad-Kontext (aus Roadmap)</strong>
+              <dl style={{ margin: 0, display: 'grid', gap: '6px' }}>
+                {readOnlyLines.map(({ label, value }) => (
+                  <div key={label}>
+                    <dt style={{ margin: 0, fontSize: '11px', color: 'var(--text3)' }}>{label}</dt>
+                    <dd style={{ margin: '2px 0 0', lineHeight: 1.45, color: 'var(--text2)' }}>{value}</dd>
+                  </div>
+                ))}
+              </dl>
+            </div>
+          ) : null}
+
+          <div style={{ display: 'grid', gap: '12px' }}>
+            <div>
+              <label className="form-label" htmlFor="gap-prep-title">
+                Titel-Vorschlag *
+              </label>
+              <input
+                id="gap-prep-title"
+                className="form-input"
+                value={title}
+                onChange={(e) => onTitleChange(e.target.value)}
+                disabled={busy}
+                maxLength={280}
+              />
+            </div>
+            <div>
+              <label className="form-label" htmlFor="gap-prep-stage-goal">
+                Stufen-Lernziel (anpassbar)
+              </label>
+              <textarea
+                id="gap-prep-stage-goal"
+                className="form-input"
+                rows={2}
+                value={stageLearningGoal}
+                onChange={(e) => onStageLearningGoalChange(e.target.value)}
+                disabled={busy}
+                placeholder="Was soll diese Übung in der Roadmap-Stufe leisten?"
+              />
+            </div>
+            <div>
+              <label className="form-label" htmlFor="gap-prep-supplements">
+                Ergänzungen / Anpassungen für die KI
+              </label>
+              <textarea
+                id="gap-prep-supplements"
+                className="form-input"
+                rows={3}
+                value={supplements}
+                onChange={(e) => onSupplementsChange(e.target.value)}
+                disabled={busy}
+                placeholder="z. B. nur Partnerübung, 10–12 Jahre, Fokus auf Reaktion unter Druck, keine Sprünge …"
+              />
+            </div>
+            <div>
+              <label className="form-label" htmlFor="gap-prep-focus">
+                Fokusbereich *
+              </label>
+              <select
+                id="gap-prep-focus"
+                className="form-input"
+                value={focusAreaId}
+                onChange={(e) => onFocusAreaChange(e.target.value)}
+                disabled={busy}
+              >
+                <option value="">Bitte wählen …</option>
+                {(focusAreas || []).map((fa) => (
+                  <option key={fa.id} value={fa.id}>
+                    {fa.name}
+                  </option>
+                ))}
+              </select>
+            </div>
+          </div>
+
+          {offer.from_title && offer.to_title ? (
+            <p style={{ fontSize: '11px', color: 'var(--text3)', margin: '12px 0 0' }}>
+              Einordnung: zwischen „{offer.from_title}“ und „{offer.to_title}“
+            </p>
+          ) : null}
+
+          {error ? (
+            <p className="form-error" style={{ marginTop: '12px' }}>
+              {error}
+            </p>
+          ) : null}
+        </div>
+        <div className="admin-modal-sheet__footer" style={{ display: 'flex', gap: '8px', flexWrap: 'wrap' }}>
+          <button type="button" className="btn btn-secondary" disabled={busy} onClick={onClose}>
+            Abbrechen
+          </button>
+          <button type="button" className="btn btn-primary" disabled={busy} onClick={onSubmit}>
+            {busy ? 'KI erstellt Entwurf …' : 'KI-Entwurf erstellen'}
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/frontend/src/utils/planningContextForExerciseAi.js b/frontend/src/utils/planningContextForExerciseAi.js
index 3896470..345859b 100644
--- a/frontend/src/utils/planningContextForExerciseAi.js
+++ b/frontend/src/utils/planningContextForExerciseAi.js
@@ -53,6 +53,8 @@ export function buildPathGapPlanningContextForAi({
   startSituation = '',
   targetState = '',
   roadmapNotes = '',
+  stageLearningGoalOverride = '',
+  gapTrainerSupplements = '',
 } = {}) {
   const afterIdx = Number(offer?.insert_after_index)
   const stepA = Number.isFinite(afterIdx) && afterIdx >= 0 ? pathSteps[afterIdx] : null
@@ -105,7 +107,9 @@ export function buildPathGapPlanningContextForAi({
     start_situation: start,
     target_state: target,
     roadmap_notes: notes,
-    stage_learning_goal: stageSpec?.learning_goal || null,
+    stage_learning_goal:
+      (stageLearningGoalOverride || '').trim() || stageSpec?.learning_goal || null,
+    gap_trainer_supplements: (gapTrainerSupplements || '').trim() || null,
     stage_phase: stageSpec?.phase || majorStep?.phase || null,
     stage_exercise_type: stageSpec?.exercise_type || null,
     stage_load_profile: Array.isArray(stageSpec?.load_profile)
@@ -158,5 +162,12 @@ export function gapOfferContextDisplayLines(offer, fallbackParams = null) {
   if (Array.isArray(raw.skill_hints) && raw.skill_hints.length) {
     push('Fähigkeiten-Fokus', raw.skill_hints.slice(0, 3).join(' · '))
   }
+  push('Trainer-Ergänzungen', raw.gap_trainer_supplements)
   return lines
 }
+
+export function initialStageLearningGoalFromOffer(offer, fallbackParams = null) {
+  const lines = gapOfferContextDisplayLines(offer, fallbackParams)
+  const hit = lines.find((l) => l.label === 'Stufen-Lernziel')
+  return hit?.value || (offer?.title_hint || '').trim()
+}

From 1e7941f57baabcf398f50b372a2b69ff2a8c221d Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Wed, 10 Jun 2026 07:09:46 +0200
Subject: [PATCH 02/33] Enhance Gap Fill Goal Text and Skill Expectations
 Integration

- Updated `build_gap_fill_goal_text` to include expected skills in the generated text, improving clarity for users.
- Enhanced `_roadmap_gap_snapshot_for_spec` to incorporate skill expectations from the progression stage, enriching the roadmap context.
- Modified `_annotate_roadmap_step` to append skill expectations to the step reasons, providing additional insights.
- Updated tests to verify the inclusion of expected skills in the gap fill goal text.
- Incremented application version to 0.8.215 to reflect these changes.
---
 backend/planning_exercise_path_ai_fill.py     |  11 +
 backend/planning_exercise_path_builder.py     | 106 +++++-
 backend/planning_skill_expectations.py        | 334 ++++++++++++++++++
 .../test_planning_exercise_path_ai_fill.py    |  17 +
 .../tests/test_planning_skill_expectations.py | 121 +++++++
 backend/version.py                            |   2 +-
 .../src/utils/planningContextForExerciseAi.js |   7 +
 7 files changed, 593 insertions(+), 5 deletions(-)
 create mode 100644 backend/planning_skill_expectations.py
 create mode 100644 backend/tests/test_planning_skill_expectations.py

diff --git a/backend/planning_exercise_path_ai_fill.py b/backend/planning_exercise_path_ai_fill.py
index 25e28da..1018b59 100644
--- a/backend/planning_exercise_path_ai_fill.py
+++ b/backend/planning_exercise_path_ai_fill.py
@@ -314,6 +314,17 @@ def build_gap_fill_goal_text(
             "Fähigkeiten-/Fokus-Hinweise: "
             + "; ".join(str(x) for x in snap["skill_hints"][:4])
         )
+    expected = snap.get("expected_skills") or []
+    if expected:
+        names = [
+            str(s.get("skill_name") or "").strip()
+            for s in expected[:5]
+            if str(s.get("skill_name") or "").strip()
+        ]
+        if names:
+            parts.append(
+                "Erwartete Fähigkeiten (Scoring): " + ", ".join(names)
+            )
     if spec.get("rationale"):
         parts.append(f"Qualitätsprüfung: {spec['rationale']}")
     if spec.get("sketch"):
diff --git a/backend/planning_exercise_path_builder.py b/backend/planning_exercise_path_builder.py
index efef5cf..2184805 100644
--- a/backend/planning_exercise_path_builder.py
+++ b/backend/planning_exercise_path_builder.py
@@ -51,6 +51,12 @@ from planning_exercise_suggest import (
     resolve_planning_exercise_intent,
 )
 from planning_exercise_form_context import build_progression_gap_snapshot
+from planning_skill_expectations import (
+    apply_expectations_to_target,
+    build_planning_skill_expectations,
+    expectation_input_from_progression_path,
+    expectation_input_from_progression_stage,
+)
 from planning_progression_roadmap import (
     MajorStep,
     ProgressionRoadmapContext,
@@ -91,14 +97,17 @@ class ProgressionPathSuggestRequest(BaseModel):
 
 
 def _roadmap_gap_snapshot_for_spec(
+    cur,
     roadmap_ctx: Optional[ProgressionRoadmapContext],
     spec: Mapping[str, Any],
     *,
+    goal_query: str,
     semantic_brief: PlanningSemanticBrief,
 ) -> Dict[str, Any]:
-    """Roadmap-Kontext für KI-Lücken-Übung (Start, Ziel, Stufenspec)."""
+    """Roadmap-Kontext für KI-Lücken-Übung (Start, Ziel, Stufenspec, Fähigkeiten)."""
     major_idx = spec.get("roadmap_major_step_index")
     stage_spec_dict: Optional[Dict[str, Any]] = None
+    major_dict: Optional[Dict[str, Any]] = None
     if roadmap_ctx and major_idx is not None:
         for s in roadmap_ctx.stage_specs or []:
             if int(s.major_step_index) == int(major_idx):
@@ -107,6 +116,7 @@ def _roadmap_gap_snapshot_for_spec(
                     for m in roadmap_ctx.roadmap.major_steps:
                         if m.index == int(major_idx):
                             stage_spec_dict["phase"] = m.phase
+                            major_dict = m.model_dump()
                             break
                 break
     ga = roadmap_ctx.goal_analysis.model_dump() if roadmap_ctx and roadmap_ctx.goal_analysis else None
@@ -120,12 +130,25 @@ def _roadmap_gap_snapshot_for_spec(
         if roadmap_ctx and roadmap_ctx.semantic_brief
         else brief_to_summary_dict(semantic_brief)
     )
-    return build_progression_gap_snapshot(
+    snap = build_progression_gap_snapshot(
         goal_analysis=ga,
         resolved_structured=rs,
         stage_spec=stage_spec_dict,
         semantic_brief=brief_summary,
     )
+    inp = expectation_input_from_progression_stage(
+        goal_query=goal_query,
+        goal_analysis=ga,
+        resolved_structured=rs,
+        stage_spec=stage_spec_dict,
+        semantic_brief_summary=brief_summary,
+        major_step=major_dict,
+    )
+    exp = build_planning_skill_expectations(cur, inp, semantic_brief=semantic_brief)
+    if exp.items:
+        snap["expected_skills"] = exp.to_api_dict()["expected_skills"]
+        snap["skill_expectation_sources"] = exp.sources
+    return snap
 
 
 def _roadmap_structured_from_body(body: ProgressionPathSuggestRequest) -> Optional[RoadmapStructuredInput]:
@@ -244,6 +267,7 @@ def _run_path_step_retrieval(
     path_intent: Optional[str] = None,
     step_query_override: Optional[str] = None,
     step_phase_override: Optional[str] = None,
+    step_target_profile_override: Optional[PlanningTargetProfile] = None,
 ) -> Tuple[List[Dict[str, Any]], PlanningTargetProfile, Dict[str, Any], str]:
     step_query = step_query_override or step_retrieval_query(
         semantic_brief, goal_query, step_index, max_steps
@@ -311,7 +335,11 @@ def _run_path_step_retrieval(
         "expectation_mode": "query_only" if step_index == 0 and not planned_ids else "planning_hybrid",
     }
 
-    if path_target_profile is not None:
+    if step_target_profile_override is not None:
+        target_profile = step_target_profile_override
+        intent = path_intent or resolve_planning_exercise_intent(goal_query, "free_search")
+        query_intent_summary = {}
+    elif path_target_profile is not None:
         target_profile = path_target_profile
         intent = path_intent or resolve_planning_exercise_intent(goal_query, "free_search")
         query_intent_summary = {}
@@ -414,6 +442,7 @@ def _annotate_roadmap_step(
     *,
     stage_spec: StageSpecArtifact,
     major_step: Optional[MajorStep],
+    skill_expectations: Optional[Dict[str, Any]] = None,
 ) -> Dict[str, Any]:
     reasons = list(step.get("reasons") or [])
     learning_goal = (stage_spec.learning_goal or "").strip()
@@ -421,11 +450,23 @@ def _annotate_roadmap_step(
         roadmap_reason = f"Roadmap: {learning_goal[:120]}"
         if roadmap_reason not in reasons:
             reasons.insert(0, roadmap_reason)
+    if skill_expectations and skill_expectations.get("expected_skills"):
+        names = [
+            str(s.get("skill_name") or "").strip()
+            for s in skill_expectations["expected_skills"][:3]
+            if str(s.get("skill_name") or "").strip()
+        ]
+        if names:
+            skill_reason = f"Fähigkeiten: {', '.join(names)}"
+            if skill_reason not in reasons:
+                reasons.append(skill_reason)
     step["reasons"] = reasons[:4]
     step["roadmap_major_step_index"] = stage_spec.major_step_index
     step["roadmap_phase"] = major_step.phase if major_step else None
     step["roadmap_learning_goal"] = learning_goal or None
     step["roadmap_match_source"] = "stage_spec"
+    if skill_expectations:
+        step["skill_expectations"] = skill_expectations
     return step
 
 
@@ -463,8 +504,37 @@ def _build_steps_roadmap_first(
     anchor_variant_id: Optional[int] = None
     unfilled: List[Tuple[int, StageSpecArtifact]] = []
 
+    ga_dump = (
+        roadmap_ctx.goal_analysis.model_dump() if roadmap_ctx.goal_analysis else None
+    )
+    rs_dump = (
+        roadmap_ctx.resolved_structured.model_dump()
+        if roadmap_ctx.resolved_structured
+        else None
+    )
+    brief_summary = (
+        roadmap_ctx.semantic_brief
+        if roadmap_ctx.semantic_brief
+        else brief_to_summary_dict(semantic_brief)
+    )
+
     for step_index, stage_spec in enumerate(stage_specs):
         major = major_by_index.get(stage_spec.major_step_index)
+        stage_spec_dict = stage_spec.model_dump()
+        if major:
+            stage_spec_dict["phase"] = major.phase
+        stage_inp = expectation_input_from_progression_stage(
+            goal_query=goal_query,
+            goal_analysis=ga_dump,
+            resolved_structured=rs_dump,
+            stage_spec=stage_spec_dict,
+            semantic_brief_summary=brief_summary,
+            major_step=major.model_dump() if major else None,
+        )
+        stage_exp = build_planning_skill_expectations(cur, stage_inp, semantic_brief=semantic_brief)
+        step_target = apply_expectations_to_target(path_target_profile, stage_exp)
+        skill_exp_api = stage_exp.to_api_dict() if stage_exp.items else None
+
         step_query = stage_spec_retrieval_query(
             semantic_brief=semantic_brief,
             goal_query=goal_query,
@@ -490,6 +560,7 @@ def _build_steps_roadmap_first(
             path_intent=path_intent,
             step_query_override=step_query,
             step_phase_override=major.phase if major else None,
+            step_target_profile_override=step_target,
         )
 
         hit = _pick_best_path_hit(hits, used, semantic_brief=semantic_brief)
@@ -511,6 +582,7 @@ def _build_steps_roadmap_first(
                 path_intent=path_intent,
                 step_query_override=goal_query,
                 step_phase_override=major.phase if major else None,
+                step_target_profile_override=step_target,
             )
             hit = _pick_best_path_hit(hits, used, semantic_brief=semantic_brief)
 
@@ -522,6 +594,7 @@ def _build_steps_roadmap_first(
             _hit_to_path_step(hit),
             stage_spec=stage_spec,
             major_step=major,
+            skill_expectations=skill_exp_api,
         )
         steps.append(step)
         eid = int(step["exercise_id"])
@@ -652,6 +725,26 @@ def suggest_progression_path(
         semantic_brief=semantic_brief,
         include_llm_intent=body.include_llm_intent,
     )
+    path_skill_expectations: Optional[Dict[str, Any]] = None
+    if roadmap_ctx and roadmap_ctx.goal_analysis:
+        path_inp = expectation_input_from_progression_path(
+            goal_query=goal_query,
+            goal_analysis=roadmap_ctx.goal_analysis.model_dump(),
+            resolved_structured=(
+                roadmap_ctx.resolved_structured.model_dump()
+                if roadmap_ctx.resolved_structured
+                else None
+            ),
+            semantic_brief_summary=(
+                roadmap_ctx.semantic_brief
+                if roadmap_ctx.semantic_brief
+                else brief_to_summary_dict(semantic_brief)
+            ),
+        )
+        path_exp = build_planning_skill_expectations(cur, path_inp, semantic_brief=semantic_brief)
+        if path_exp.items:
+            path_target_profile = apply_expectations_to_target(path_target_profile, path_exp)
+            path_skill_expectations = path_exp.to_api_dict()
 
     roadmap_unfilled: List[Tuple[int, StageSpecArtifact]] = []
     roadmap_gap_offers: List[Dict[str, Any]] = []
@@ -702,7 +795,11 @@ def suggest_progression_path(
                         brief=semantic_brief,
                         proposal=None,
                         roadmap_snapshot=_roadmap_gap_snapshot_for_spec(
-                            roadmap_ctx, spec, semantic_brief=semantic_brief
+                            cur,
+                            roadmap_ctx,
+                            spec,
+                            goal_query=goal_query,
+                            semantic_brief=semantic_brief,
                         ),
                     )
                 )
@@ -927,6 +1024,7 @@ def suggest_progression_path(
         "roadmap_only": False,
         "roadmap_edited": roadmap_edited,
         "roadmap_unfilled_count": len(roadmap_unfilled),
+        "path_skill_expectations": path_skill_expectations,
         "retrieval_phase": "+".join(retrieval_parts),
     }
 
diff --git a/backend/planning_skill_expectations.py b/backend/planning_skill_expectations.py
new file mode 100644
index 0000000..e996349
--- /dev/null
+++ b/backend/planning_skill_expectations.py
@@ -0,0 +1,334 @@
+"""
+Wiederverwendbare Fähigkeiten-Erwartungen für Planungs-KI.
+
+Domänen-Scopes (gleiches Input-/Output-Modell):
+- ``progression_stage`` — ein Major Step / stage_spec im Progressionsgraphen
+- ``progression_path`` — gesamter Pfad (Ziel + Start/Ziel)
+- ``training_section`` — Abschnitt einer Trainingseinheit (Phase G, später)
+- ``framework_slot`` — Rahmen-Session-Slot (Phase G, später)
+
+Konsumenten mergen ``skill_weights`` in ``PlanningTargetProfile`` (Retrieval)
+oder liefern ``expected_skills`` an Übungs-KI (planning_context).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple
+
+from planning_exercise_profiles import _merge_weight_maps, _normalize_weight_map
+from planning_exercise_semantics import PlanningSemanticBrief, resolve_semantic_skill_weights
+from planning_exercise_text_signals import _load_skills_for_text_match, _match_skills_in_text
+
+# Scope-Strings — stabil für API/UI und spätere Trainingsplanung
+SCOPE_PROGRESSION_STAGE = "progression_stage"
+SCOPE_PROGRESSION_PATH = "progression_path"
+SCOPE_TRAINING_SECTION = "training_section"
+SCOPE_FRAMEWORK_SLOT = "framework_slot"
+
+_LOAD_PROFILE_SKILL_TERMS: Dict[str, Tuple[str, ...]] = {
+    "koordination": ("Koordination",),
+    "präzision": ("Präzision",),
+    "praezision": ("Präzision",),
+    "kraft": ("Kraft", "Kime"),
+    "geschwindigkeit": ("Geschwindigkeit", "Schnelligkeit"),
+    "schnelligkeit": ("Schnelligkeit", "Geschwindigkeit"),
+    "timing": ("Timing", "Reaktion"),
+    "reaktion": ("Reaktion", "Timing"),
+    "distanz": ("Distanz",),
+    "raum": ("Raum", "Distanz"),
+    "gleichgewicht": ("Gleichgewicht",),
+    "kime": ("Kime",),
+    "ausdauer": ("Ausdauer",),
+    "beweglichkeit": ("Beweglichkeit",),
+}
+
+
+@dataclass
+class PlanningSkillExpectationInput:
+    scope: str = SCOPE_PROGRESSION_STAGE
+    primary_topic: str = ""
+    goal_query: str = ""
+    start_situation: str = ""
+    target_state: str = ""
+    stage_learning_goal: str = ""
+    roadmap_notes: str = ""
+    load_profile: List[str] = field(default_factory=list)
+    phase: str = ""
+    skill_hints: List[str] = field(default_factory=list)
+
+
+@dataclass
+class PlanningSkillExpectationItem:
+    skill_id: int
+    skill_name: str
+    weight: float
+    source: str
+
+
+@dataclass
+class PlanningSkillExpectations:
+    scope: str
+    skill_weights: Dict[int, float]
+    items: List[PlanningSkillExpectationItem]
+    sources: List[str]
+
+    def to_api_dict(self) -> Dict[str, Any]:
+        return {
+            "scope": self.scope,
+            "sources": list(self.sources),
+            "expected_skills": [
+                {
+                    "skill_id": it.skill_id,
+                    "skill_name": it.skill_name,
+                    "weight": round(it.weight, 4),
+                    "source": it.source,
+                }
+                for it in self.items
+            ],
+        }
+
+
+def _norm_load_key(s: str) -> str:
+    return (s or "").strip().lower().replace("ä", "ae").replace("ö", "oe").replace("ü", "ue")
+
+
+def _text_blob(inp: PlanningSkillExpectationInput) -> str:
+    parts = [
+        inp.primary_topic,
+        inp.goal_query,
+        inp.start_situation,
+        inp.target_state,
+        inp.stage_learning_goal,
+        inp.roadmap_notes,
+        inp.phase,
+        " ".join(inp.load_profile or []),
+        " ".join(inp.skill_hints or []),
+    ]
+    return "\n".join(p for p in parts if (p or "").strip()).lower()
+
+
+def _resolve_skills_by_name_terms(
+    cur,
+    terms: Sequence[str],
+    *,
+    weight: float = 0.9,
+    source: str,
+    weights: Dict[int, float],
+    items: Dict[int, PlanningSkillExpectationItem],
+) -> bool:
+    found = False
+    for name in terms:
+        if not name:
+            continue
+        cur.execute(
+            """
+            SELECT id, name FROM skills
+            WHERE (status IS NULL OR status = 'active')
+              AND LOWER(name) LIKE %s
+            ORDER BY CASE WHEN LOWER(name) = %s THEN 0 WHEN LOWER(name) LIKE %s THEN 1 ELSE 2 END,
+                     LENGTH(name) ASC
+            LIMIT 1
+            """,
+            (f"%{name.lower()}%", name.lower(), f"{name.lower()}%"),
+        )
+        row = cur.fetchone()
+        if not row:
+            continue
+        sid = int(row["id"])
+        w = max(weights.get(sid, 0.0), weight)
+        weights[sid] = w
+        items[sid] = PlanningSkillExpectationItem(
+            skill_id=sid,
+            skill_name=str(row.get("name") or "").strip(),
+            weight=w,
+            source=source,
+        )
+        found = True
+    return found
+
+
+def _merge_weights_into(
+    weights: Dict[int, float],
+    items: Dict[int, PlanningSkillExpectationItem],
+    incoming: Dict[int, float],
+    *,
+    source: str,
+    skill_rows: Sequence[Tuple[int, str, int]],
+) -> None:
+    name_by_id = {sid: name for sid, name, _ in skill_rows}
+    for sid, w in incoming.items():
+        if w <= 0:
+            continue
+        merged = max(weights.get(sid, 0.0), float(w))
+        weights[sid] = merged
+        items[sid] = PlanningSkillExpectationItem(
+            skill_id=sid,
+            skill_name=name_by_id.get(sid, f"Skill #{sid}"),
+            weight=merged,
+            source=source,
+        )
+
+
+def build_planning_skill_expectations(
+    cur,
+    inp: PlanningSkillExpectationInput,
+    *,
+    semantic_brief: Optional[PlanningSemanticBrief] = None,
+) -> PlanningSkillExpectations:
+    """Deterministisch: Thema + Text + load_profile → skill_weights."""
+    weights: Dict[int, float] = {}
+    items: Dict[int, PlanningSkillExpectationItem] = {}
+    sources: List[str] = []
+
+    skill_rows = _load_skills_for_text_match(cur)
+
+    if semantic_brief is not None:
+        topic_weights = resolve_semantic_skill_weights(cur, semantic_brief)
+        if topic_weights:
+            sources.append("semantic_topic")
+            _merge_weights_into(
+                weights, items, topic_weights, source="semantic_topic", skill_rows=skill_rows
+            )
+
+    blob = _text_blob(inp)
+    if blob:
+        text_weights = _match_skills_in_text(blob, skill_rows)
+        if text_weights:
+            sources.append("text_match")
+            _merge_weights_into(
+                weights, items, text_weights, source="text_match", skill_rows=skill_rows
+            )
+
+    load_found = False
+    for raw in inp.load_profile or []:
+        key = _norm_load_key(str(raw))
+        terms = _LOAD_PROFILE_SKILL_TERMS.get(key, (str(raw).strip(),) if key else ())
+        if _resolve_skills_by_name_terms(
+            cur, terms, weight=0.88, source="load_profile", weights=weights, items=items
+        ):
+            load_found = True
+    if load_found and "load_profile" not in sources:
+        sources.append("load_profile")
+
+    normalized = _normalize_weight_map(weights)
+    out_items = sorted(
+        [
+            PlanningSkillExpectationItem(
+                skill_id=sid,
+                skill_name=items[sid].skill_name,
+                weight=normalized[sid],
+                source=items[sid].source,
+            )
+            for sid in normalized
+        ],
+        key=lambda x: (-x.weight, x.skill_name.lower()),
+    )[:8]
+
+    return PlanningSkillExpectations(
+        scope=inp.scope or SCOPE_PROGRESSION_STAGE,
+        skill_weights=normalized,
+        items=out_items,
+        sources=sources,
+    )
+
+
+def expectation_input_from_progression_stage(
+    *,
+    goal_query: str,
+    goal_analysis: Optional[Mapping[str, Any]] = None,
+    resolved_structured: Optional[Mapping[str, Any]] = None,
+    stage_spec: Optional[Mapping[str, Any]] = None,
+    semantic_brief_summary: Optional[Mapping[str, Any]] = None,
+    major_step: Optional[Mapping[str, Any]] = None,
+) -> PlanningSkillExpectationInput:
+    """Roadmap-Stufe → PlanningSkillExpectationInput (Progressionsgraph)."""
+    ga = dict(goal_analysis or {})
+    rs = dict(resolved_structured or {})
+    spec = dict(stage_spec or {})
+    brief = dict(semantic_brief_summary or {})
+    major = dict(major_step or {})
+
+    skill_hints: List[str] = []
+    for item in (brief.get("must_phrases") or [])[:4]:
+        s = str(item or "").strip()
+        if s:
+            skill_hints.append(s)
+
+    return PlanningSkillExpectationInput(
+        scope=SCOPE_PROGRESSION_STAGE,
+        primary_topic=str(ga.get("primary_topic") or brief.get("primary_topic") or "").strip(),
+        goal_query=(goal_query or "").strip(),
+        start_situation=str(rs.get("start_situation") or ga.get("start_assumption") or "").strip(),
+        target_state=str(rs.get("target_state") or ga.get("target_state") or "").strip(),
+        stage_learning_goal=str(
+            spec.get("learning_goal") or major.get("learning_goal") or ""
+        ).strip(),
+        roadmap_notes=str(rs.get("roadmap_notes") or "").strip(),
+        load_profile=[str(x).strip() for x in (spec.get("load_profile") or []) if str(x).strip()],
+        phase=str(spec.get("phase") or major.get("phase") or "").strip(),
+        skill_hints=skill_hints,
+    )
+
+
+def expectation_input_from_progression_path(
+    *,
+    goal_query: str,
+    goal_analysis: Optional[Mapping[str, Any]] = None,
+    resolved_structured: Optional[Mapping[str, Any]] = None,
+    semantic_brief_summary: Optional[Mapping[str, Any]] = None,
+) -> PlanningSkillExpectationInput:
+    """Gesamtpfad-Kontext (z. B. einmaliges Pfad-Profil)."""
+    ga = dict(goal_analysis or {})
+    rs = dict(resolved_structured or {})
+    brief = dict(semantic_brief_summary or {})
+    skill_hints: List[str] = []
+    for item in (brief.get("must_phrases") or [])[:4]:
+        s = str(item or "").strip()
+        if s:
+            skill_hints.append(s)
+    return PlanningSkillExpectationInput(
+        scope=SCOPE_PROGRESSION_PATH,
+        primary_topic=str(ga.get("primary_topic") or brief.get("primary_topic") or "").strip(),
+        goal_query=(goal_query or "").strip(),
+        start_situation=str(rs.get("start_situation") or ga.get("start_assumption") or "").strip(),
+        target_state=str(rs.get("target_state") or ga.get("target_state") or "").strip(),
+        roadmap_notes=str(rs.get("roadmap_notes") or "").strip(),
+        skill_hints=skill_hints,
+    )
+
+
+def apply_expectations_to_target(target, expectations: PlanningSkillExpectations):
+    """Merge Erwartungs-Skills in PlanningTargetProfile (Retrieval)."""
+    from planning_exercise_semantics import enrich_target_with_semantic_expectations
+
+    if not expectations.skill_weights:
+        return target
+    return enrich_target_with_semantic_expectations(
+        target, skill_weights=dict(expectations.skill_weights)
+    )
+
+
+def merge_expectation_skill_weights(
+    base: Dict[int, float],
+    extra: Dict[int, float],
+    *,
+    extra_scale: float = 1.0,
+) -> Dict[int, float]:
+    merged = _merge_weight_maps(base, extra, scale=extra_scale)
+    return _normalize_weight_map(merged)
+
+
+__all__ = [
+    "SCOPE_FRAMEWORK_SLOT",
+    "SCOPE_PROGRESSION_PATH",
+    "SCOPE_PROGRESSION_STAGE",
+    "SCOPE_TRAINING_SECTION",
+    "PlanningSkillExpectationInput",
+    "PlanningSkillExpectationItem",
+    "PlanningSkillExpectations",
+    "apply_expectations_to_target",
+    "build_planning_skill_expectations",
+    "expectation_input_from_progression_path",
+    "expectation_input_from_progression_stage",
+    "merge_expectation_skill_weights",
+]
diff --git a/backend/tests/test_planning_exercise_path_ai_fill.py b/backend/tests/test_planning_exercise_path_ai_fill.py
index 54b317a..98cb393 100644
--- a/backend/tests/test_planning_exercise_path_ai_fill.py
+++ b/backend/tests/test_planning_exercise_path_ai_fill.py
@@ -119,6 +119,23 @@ def test_build_gap_fill_goal_text_includes_roadmap_snapshot():
     assert "timing" in text
 
 
+def test_build_gap_fill_goal_text_includes_expected_skills():
+    brief = build_semantic_brief("Kumite Beinarbeit")
+    text = build_gap_fill_goal_text(
+        goal_query="Kumite Beinarbeit",
+        brief=brief,
+        spec={"phase": "vertiefung", "title_hint": "Rhythmen"},
+        roadmap_snapshot={
+            "expected_skills": [
+                {"skill_name": "Timing", "weight": 0.9},
+                {"skill_name": "Distanz", "weight": 0.8},
+            ],
+        },
+    )
+    assert "Erwartete Fähigkeiten" in text
+    assert "Timing" in text
+
+
 def test_build_gap_fill_offer_exposes_context_preview():
     brief = build_semantic_brief("Kumite Beinarbeit")
     offer = build_gap_fill_offer(
diff --git a/backend/tests/test_planning_skill_expectations.py b/backend/tests/test_planning_skill_expectations.py
new file mode 100644
index 0000000..f35be9a
--- /dev/null
+++ b/backend/tests/test_planning_skill_expectations.py
@@ -0,0 +1,121 @@
+"""Tests wiederverwendbare Fähigkeiten-Erwartungen (Progressionsgraph + später Planung)."""
+from unittest.mock import MagicMock
+
+from planning_skill_expectations import (
+    SCOPE_PROGRESSION_PATH,
+    SCOPE_PROGRESSION_STAGE,
+    PlanningSkillExpectationInput,
+    apply_expectations_to_target,
+    build_planning_skill_expectations,
+    expectation_input_from_progression_path,
+    expectation_input_from_progression_stage,
+)
+
+
+class _FakeCursor:
+    def __init__(self, skills):
+        self._skills = skills
+
+    def execute(self, query, params=None):
+        del query
+        if params and len(params) >= 2:
+            needle = str(params[0]).strip("%").lower()
+            exact = str(params[1]).lower()
+            matches = [
+                s
+                for s in self._skills
+                if needle in s["name"].lower() or s["name"].lower() == exact
+            ]
+            self._row = matches[0] if matches else None
+        else:
+            self._row = None
+
+    def fetchone(self):
+        return self._row
+
+
+def _fake_skill_rows():
+    return [
+        (1, "Koordination", 0),
+        (2, "Timing", 0),
+        (3, "Distanz", 0),
+        (4, "Kime", 0),
+    ]
+
+
+def test_expectation_input_from_progression_stage_merges_sources(monkeypatch):
+    monkeypatch.setattr(
+        "planning_skill_expectations._load_skills_for_text_match",
+        lambda cur: _fake_skill_rows(),
+    )
+    inp = expectation_input_from_progression_stage(
+        goal_query="Kumite Beinarbeit",
+        goal_analysis={
+            "primary_topic": "Kumite",
+            "start_assumption": "gleichförmige Steppbewegung",
+            "target_state": "explosiver Angriff",
+        },
+        resolved_structured={"roadmap_notes": "Kindergruppe"},
+        stage_spec={
+            "learning_goal": "variable Rhythmen",
+            "load_profile": ["timing", "distanz"],
+            "phase": "vertiefung",
+        },
+        semantic_brief_summary={"must_phrases": ["Beinarbeit"], "primary_topic": "Kumite"},
+        major_step={"phase": "vertiefung", "learning_goal": "Major-Ziel"},
+    )
+    assert inp.scope == SCOPE_PROGRESSION_STAGE
+    assert inp.primary_topic == "Kumite"
+    assert inp.start_situation == "gleichförmige Steppbewegung"
+    assert inp.load_profile == ["timing", "distanz"]
+    assert "Beinarbeit" in inp.skill_hints
+
+
+def test_build_planning_skill_expectations_load_profile_and_text(monkeypatch):
+    monkeypatch.setattr(
+        "planning_skill_expectations._load_skills_for_text_match",
+        lambda cur: _fake_skill_rows(),
+    )
+    cur = _FakeCursor(
+        [
+            {"id": 2, "name": "Timing"},
+            {"id": 3, "name": "Distanz"},
+        ]
+    )
+    inp = PlanningSkillExpectationInput(
+        scope=SCOPE_PROGRESSION_STAGE,
+        primary_topic="Kumite",
+        goal_query="Kumite Beinarbeit mit Timing",
+        load_profile=["timing", "distanz"],
+    )
+    exp = build_planning_skill_expectations(cur, inp)
+    assert exp.scope == SCOPE_PROGRESSION_STAGE
+    assert "load_profile" in exp.sources or "text_match" in exp.sources
+    names = {it.skill_name for it in exp.items}
+    assert "Timing" in names or "Distanz" in names
+    assert exp.skill_weights
+
+
+def test_expectation_input_from_progression_path_scope():
+    inp = expectation_input_from_progression_path(
+        goal_query="Mae Geri Perfektion",
+        goal_analysis={"primary_topic": "Mae Geri"},
+        resolved_structured={"start_situation": "Grundstellung", "target_state": "freier Kick"},
+    )
+    assert inp.scope == SCOPE_PROGRESSION_PATH
+    assert inp.start_situation == "Grundstellung"
+    assert inp.target_state == "freier Kick"
+
+
+def test_apply_expectations_to_target_noop_without_weights():
+    class _Target:
+        skill_weights = {}
+
+        def to_summary_dict(self, cur):
+            return {}
+
+    target = _Target()
+    from planning_skill_expectations import PlanningSkillExpectations
+
+    empty = PlanningSkillExpectations(scope=SCOPE_PROGRESSION_STAGE, skill_weights={}, items=[], sources=[])
+    assert apply_expectations_to_target(target, empty) is target
diff --git a/backend/version.py b/backend/version.py
index e55663f..f266fd2 100644
--- a/backend/version.py
+++ b/backend/version.py
@@ -1,6 +1,6 @@
 # Shinkan Jinkendo Version Information
 
-APP_VERSION = "0.8.214"
+APP_VERSION = "0.8.215"
 BUILD_DATE = "2026-06-07"
 DB_SCHEMA_VERSION = "20260607087"
 
diff --git a/frontend/src/utils/planningContextForExerciseAi.js b/frontend/src/utils/planningContextForExerciseAi.js
index 345859b..bc77f9e 100644
--- a/frontend/src/utils/planningContextForExerciseAi.js
+++ b/frontend/src/utils/planningContextForExerciseAi.js
@@ -162,6 +162,13 @@ export function gapOfferContextDisplayLines(offer, fallbackParams = null) {
   if (Array.isArray(raw.skill_hints) && raw.skill_hints.length) {
     push('Fähigkeiten-Fokus', raw.skill_hints.slice(0, 3).join(' · '))
   }
+  if (Array.isArray(raw.expected_skills) && raw.expected_skills.length) {
+    const names = raw.expected_skills
+      .map((s) => String(s?.skill_name || '').trim())
+      .filter(Boolean)
+      .slice(0, 5)
+    if (names.length) push('Erwartete Fähigkeiten', names.join(' · '))
+  }
   push('Trainer-Ergänzungen', raw.gap_trainer_supplements)
   return lines
 }

From 98b279fa89f0781c246787b22d48bb258a131ba5 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Wed, 10 Jun 2026 07:14:18 +0200
Subject: [PATCH 03/33] Update version to 0.8.216 and enhance Exercise
 Progression Path Builder

- Incremented application version to 0.8.216 to reflect recent changes.
- Added skill expectations handling in the Exercise Progression Path Builder, improving the integration of expected skills into the roadmap steps.
- Enhanced the mapping of major steps to include load profiles, success criteria, anti-patterns, and exercise types, enriching the user experience and functionality.
---
 .../test_planning_exercise_path_builder.py    |  18 +
 backend/version.py                            |   2 +-
 .../ExerciseProgressionPathBuilder.jsx        | 314 ++++++++++++++----
 3 files changed, 272 insertions(+), 62 deletions(-)

diff --git a/backend/tests/test_planning_exercise_path_builder.py b/backend/tests/test_planning_exercise_path_builder.py
index dc9d598..84547f6 100644
--- a/backend/tests/test_planning_exercise_path_builder.py
+++ b/backend/tests/test_planning_exercise_path_builder.py
@@ -42,3 +42,21 @@ def test_annotate_roadmap_step_adds_metadata():
     assert step["roadmap_phase"] == "grundlage"
     assert step["roadmap_match_source"] == "stage_spec"
     assert any("Roadmap:" in r for r in step["reasons"])
+
+
+def test_annotate_roadmap_step_adds_skill_expectations():
+    spec = StageSpecArtifact(major_step_index=0, learning_goal="Timing und Distanz")
+    step = _annotate_roadmap_step(
+        {"exercise_id": 5, "title": "Test", "reasons": []},
+        stage_spec=spec,
+        major_step=None,
+        skill_expectations={
+            "scope": "progression_stage",
+            "expected_skills": [
+                {"skill_id": 2, "skill_name": "Timing", "weight": 0.9},
+                {"skill_id": 3, "skill_name": "Distanz", "weight": 0.8},
+            ],
+        },
+    )
+    assert step["skill_expectations"]["expected_skills"][0]["skill_name"] == "Timing"
+    assert any("Fähigkeiten:" in r for r in step["reasons"])
diff --git a/backend/version.py b/backend/version.py
index f266fd2..f33ed91 100644
--- a/backend/version.py
+++ b/backend/version.py
@@ -1,6 +1,6 @@
 # Shinkan Jinkendo Version Information
 
-APP_VERSION = "0.8.215"
+APP_VERSION = "0.8.216"
 BUILD_DATE = "2026-06-07"
 DB_SCHEMA_VERSION = "20260607087"
 
diff --git a/frontend/src/components/ExerciseProgressionPathBuilder.jsx b/frontend/src/components/ExerciseProgressionPathBuilder.jsx
index 7288ec8..52734f8 100644
--- a/frontend/src/components/ExerciseProgressionPathBuilder.jsx
+++ b/frontend/src/components/ExerciseProgressionPathBuilder.jsx
@@ -107,6 +107,7 @@ function mapApiStepToRow(step) {
       step?.roadmap_major_step_index != null ? Number(step.roadmap_major_step_index) : null,
     roadmapPhase: step?.roadmap_phase || null,
     roadmapLearningGoal: step?.roadmap_learning_goal || null,
+    skillExpectations: step?.skill_expectations || null,
   }
 }
 
@@ -137,16 +138,65 @@ const PATH_STEPS_HARD_MAX = 10
 
 const ROADMAP_PHASES = ['einstieg', 'grundlage', 'vertiefung', 'anwendung', 'perfektion']
 
+const LOAD_PROFILE_OPTIONS = [
+  'koordination',
+  'präzision',
+  'kraft',
+  'geschwindigkeit',
+  'timing',
+  'reaktion',
+  'distanz',
+  'gleichgewicht',
+  'kime',
+  'ausdauer',
+  'beweglichkeit',
+]
+
 function mapMajorStepsFromApi(apiRoadmap) {
   const raw = apiRoadmap?.roadmap?.major_steps
   if (!Array.isArray(raw)) return []
-  return raw.map((s, i) => ({
+  const rows = raw.map((s, i) => ({
     index: i,
     phase: s.phase || 'vertiefung',
     learning_goal: (s.learning_goal || '').trim(),
     consolidates: Array.isArray(s.consolidates) ? s.consolidates : [],
     rationale: s.rationale || '',
+    load_profile: [],
+    success_criteria: [],
+    anti_patterns: [],
+    exercise_type: '',
   }))
+  return mergeStageSpecsIntoMajorSteps(rows, apiRoadmap)
+}
+
+function mergeStageSpecsIntoMajorSteps(rows, apiRoadmap) {
+  const specs = apiRoadmap?.stage_specs
+  if (!Array.isArray(specs) || !rows.length) return rows
+  return rows.map((row, i) => {
+    const spec =
+      specs.find((s) => Number(s.major_step_index) === i) ||
+      specs.find((s) => Number(s.major_step_index) === row.index) ||
+      specs[i]
+    if (!spec) return row
+    return {
+      ...row,
+      load_profile: Array.isArray(spec.load_profile) ? [...spec.load_profile] : [],
+      success_criteria: Array.isArray(spec.success_criteria) ? [...spec.success_criteria] : [],
+      anti_patterns: Array.isArray(spec.anti_patterns) ? [...spec.anti_patterns] : [],
+      exercise_type: (spec.exercise_type || '').trim(),
+    }
+  })
+}
+
+function linesToStringList(text) {
+  return String(text || '')
+    .split('\n')
+    .map((s) => s.trim())
+    .filter(Boolean)
+}
+
+function listToMultiline(arr) {
+  return Array.isArray(arr) ? arr.join('\n') : ''
 }
 
 function reindexMajorSteps(rows) {
@@ -154,17 +204,35 @@ function reindexMajorSteps(rows) {
 }
 
 function majorStepsToOverridePayload(rows) {
+  const indexed = reindexMajorSteps(rows)
   return {
-    major_steps: reindexMajorSteps(rows).map((row) => ({
+    major_steps: indexed.map((row) => ({
       index: row.index,
       phase: row.phase || 'vertiefung',
       learning_goal: row.learning_goal.trim(),
       consolidates: row.consolidates || [],
       rationale: row.rationale || '',
     })),
+    stage_specs: indexed.map((row, i) => ({
+      major_step_index: i,
+      learning_goal: row.learning_goal.trim(),
+      load_profile: Array.isArray(row.load_profile) ? row.load_profile : [],
+      exercise_type: (row.exercise_type || '').trim(),
+      success_criteria: Array.isArray(row.success_criteria) ? row.success_criteria : [],
+      anti_patterns: Array.isArray(row.anti_patterns) ? row.anti_patterns : [],
+    })),
   }
 }
 
+function formatExpectedSkillNames(skillExpectations, limit = 4) {
+  const items = skillExpectations?.expected_skills
+  if (!Array.isArray(items)) return []
+  return items
+    .map((s) => String(s?.skill_name || '').trim())
+    .filter(Boolean)
+    .slice(0, limit)
+}
+
 /** Einfügen wächst den Pfad; Ersetzen (replace_step_index) nicht. */
 function offerGrowsPath(offer) {
   const replaceIdx = offer?.replace_step_index
@@ -234,6 +302,7 @@ export default function ExerciseProgressionPathBuilder({
   const [pathSteps, setPathSteps] = useState([])
   const [gapFillOffers, setGapFillOffers] = useState([])
   const [progressionRoadmap, setProgressionRoadmap] = useState(null)
+  const [pathSkillExpectations, setPathSkillExpectations] = useState(null)
   const [editableMajorSteps, setEditableMajorSteps] = useState([])
   const [roadmapDirty, setRoadmapDirty] = useState(false)
   const [loadingRoadmap, setLoadingRoadmap] = useState(false)
@@ -331,6 +400,10 @@ export default function ExerciseProgressionPathBuilder({
           learning_goal: '',
           consolidates: [],
           rationale: '',
+          load_profile: [],
+          success_criteria: [],
+          anti_patterns: [],
+          exercise_type: '',
         },
       ])
     })
@@ -629,8 +702,14 @@ export default function ExerciseProgressionPathBuilder({
           : [],
     )
     setProgressionRoadmap(res?.progression_roadmap || null)
+    setPathSkillExpectations(res?.path_skill_expectations || null)
     setRoadmapDirty(false)
     if (!segmentNotes.trim() && q) setSegmentNotes(q.slice(0, 400))
+    if (res?.progression_roadmap?.stage_specs?.length) {
+      setEditableMajorSteps((prev) =>
+        prev.length ? mergeStageSpecsIntoMajorSteps(prev, res.progression_roadmap) : prev,
+      )
+    }
   }
 
   const applyStartTargetResponse = (res) => {
@@ -737,12 +816,14 @@ export default function ExerciseProgressionPathBuilder({
       setTargetSummary(null)
       setPathQa(null)
       setGapFillOffers([])
+      setPathSkillExpectations(null)
       setRoadmapDirty(false)
     } catch (e) {
       console.error(e)
       setError(e.message || 'Roadmap-Vorschlag fehlgeschlagen')
       setEditableMajorSteps([])
       setProgressionRoadmap(null)
+      setPathSkillExpectations(null)
     } finally {
       setLoadingRoadmap(false)
     }
@@ -831,6 +912,7 @@ export default function ExerciseProgressionPathBuilder({
       setPathQa(null)
       setGapFillOffers([])
       setProgressionRoadmap(null)
+      setPathSkillExpectations(null)
       setEditableMajorSteps([])
       setRoadmapDirty(false)
       if (typeof onSaved === 'function') await onSaved()
@@ -1048,7 +1130,7 @@ export default function ExerciseProgressionPathBuilder({
         </div>
       ) : null}
 
-      {(semanticBrief || targetSummary) && pathSteps.length > 0 ? (
+      {(semanticBrief || targetSummary || pathSkillExpectations) && pathSteps.length > 0 ? (
         <div style={{ marginTop: '10px', display: 'flex', flexWrap: 'wrap', gap: '6px' }}>
           {semanticBrief?.primary_topic ? (
             <span className="exercise-tag" style={{ borderColor: 'var(--accent)' }}>
@@ -1067,6 +1149,16 @@ export default function ExerciseProgressionPathBuilder({
                 Fokus: {fa}
               </span>
             ))}
+          {formatExpectedSkillNames(pathSkillExpectations, 5).map((name) => (
+            <span
+              key={`path-skill-${name}`}
+              className="exercise-tag"
+              style={{ borderColor: 'color-mix(in srgb, var(--accent) 55%, var(--border))' }}
+              title="Pfadweite Fähigkeiten-Erwartung (Scoring)"
+            >
+              {name}
+            </span>
+          ))}
         </div>
       ) : null}
 
@@ -1102,7 +1194,7 @@ export default function ExerciseProgressionPathBuilder({
               : progressionRoadmap
                 ? ' (heuristisch/KI)'
                 : ''}
-            . Phasen und Lernziele anpassen, dann „Übungen matchen“.
+            . Phasen und Lernziele anpassen; optional Stufen-Details für Match und KI-Lücken, dann „Übungen matchen“.
           </p>
           <div style={{ display: 'flex', flexDirection: 'column', gap: '10px' }}>
             {editableMajorSteps.map((step, idx) => (
@@ -1113,66 +1205,141 @@ export default function ExerciseProgressionPathBuilder({
                   borderRadius: '8px',
                   background: 'var(--surface2)',
                   border: '1px solid var(--border)',
-                  display: 'grid',
-                  gridTemplateColumns: 'repeat(auto-fit, minmax(160px, 1fr))',
-                  gap: '10px',
-                  alignItems: 'end',
                 }}
               >
-                <div className="form-row" style={{ marginBottom: 0, flex: '0 0 120px' }}>
-                  <label className="form-label">Stufe {idx + 1} · Phase</label>
-                  <select
-                    className="form-input"
-                    value={step.phase}
-                    onChange={(e) => patchMajorStep(idx, { phase: e.target.value })}
-                    disabled={disabled || loading || saving}
-                  >
-                    {ROADMAP_PHASES.map((p) => (
-                      <option key={p} value={p}>
-                        {p}
-                      </option>
-                    ))}
-                  </select>
-                </div>
-                <div className="form-row" style={{ marginBottom: 0, flex: '2 1 240px' }}>
-                  <label className="form-label">Lernziel</label>
-                  <input
-                    className="form-input"
-                    value={step.learning_goal}
-                    onChange={(e) => patchMajorStep(idx, { learning_goal: e.target.value })}
-                    placeholder="z. B. Grundstellung und Hüftmobilität für Mae Geri"
-                    disabled={disabled || loading || saving}
-                  />
-                </div>
-                <div style={{ display: 'flex', gap: '6px', flexWrap: 'wrap' }}>
-                  <button
-                    type="button"
-                    className="btn"
-                    style={{ fontSize: '12px', padding: '4px 8px' }}
-                    onClick={() => moveMajorStep(idx, -1)}
-                    disabled={disabled || loading || saving || idx === 0}
-                  >
-                    ↑
-                  </button>
-                  <button
-                    type="button"
-                    className="btn"
-                    style={{ fontSize: '12px', padding: '4px 8px' }}
-                    onClick={() => moveMajorStep(idx, 1)}
-                    disabled={disabled || loading || saving || idx >= editableMajorSteps.length - 1}
-                  >
-                    ↓
-                  </button>
-                  <button
-                    type="button"
-                    className="btn"
-                    style={{ fontSize: '12px', padding: '4px 8px' }}
-                    onClick={() => removeMajorStep(idx)}
-                    disabled={disabled || loading || saving || editableMajorSteps.length <= 2}
-                  >
-                    Entfernen
-                  </button>
+                <div
+                  style={{
+                    display: 'grid',
+                    gridTemplateColumns: 'repeat(auto-fit, minmax(160px, 1fr))',
+                    gap: '10px',
+                    alignItems: 'end',
+                  }}
+                >
+                  <div className="form-row" style={{ marginBottom: 0, flex: '0 0 120px' }}>
+                    <label className="form-label">Stufe {idx + 1} · Phase</label>
+                    <select
+                      className="form-input"
+                      value={step.phase}
+                      onChange={(e) => patchMajorStep(idx, { phase: e.target.value })}
+                      disabled={disabled || loading || saving}
+                    >
+                      {ROADMAP_PHASES.map((p) => (
+                        <option key={p} value={p}>
+                          {p}
+                        </option>
+                      ))}
+                    </select>
+                  </div>
+                  <div className="form-row" style={{ marginBottom: 0, flex: '2 1 240px' }}>
+                    <label className="form-label">Lernziel (Major Step)</label>
+                    <input
+                      className="form-input"
+                      value={step.learning_goal}
+                      onChange={(e) => patchMajorStep(idx, { learning_goal: e.target.value })}
+                      placeholder="z. B. Grundstellung und Hüftmobilität für Mae Geri"
+                      disabled={disabled || loading || saving}
+                    />
+                  </div>
+                  <div style={{ display: 'flex', gap: '6px', flexWrap: 'wrap' }}>
+                    <button
+                      type="button"
+                      className="btn"
+                      style={{ fontSize: '12px', padding: '4px 8px' }}
+                      onClick={() => moveMajorStep(idx, -1)}
+                      disabled={disabled || loading || saving || idx === 0}
+                    >
+                      ↑
+                    </button>
+                    <button
+                      type="button"
+                      className="btn"
+                      style={{ fontSize: '12px', padding: '4px 8px' }}
+                      onClick={() => moveMajorStep(idx, 1)}
+                      disabled={disabled || loading || saving || idx >= editableMajorSteps.length - 1}
+                    >
+                      ↓
+                    </button>
+                    <button
+                      type="button"
+                      className="btn"
+                      style={{ fontSize: '12px', padding: '4px 8px' }}
+                      onClick={() => removeMajorStep(idx)}
+                      disabled={disabled || loading || saving || editableMajorSteps.length <= 2}
+                    >
+                      Entfernen
+                    </button>
+                  </div>
                 </div>
+                <details style={{ marginTop: '10px', fontSize: '12px' }}>
+                  <summary style={{ cursor: 'pointer', color: 'var(--accent-dark)', fontWeight: 600 }}>
+                    Stufen-Details (Match & KI)
+                    {step.load_profile?.length
+                      ? ` · ${step.load_profile.slice(0, 2).join(', ')}`
+                      : ''}
+                  </summary>
+                  <div style={{ marginTop: '10px', display: 'grid', gap: '10px' }}>
+                    <div>
+                      <label className="form-label">Belastungsschwerpunkte</label>
+                      <div style={{ display: 'flex', flexWrap: 'wrap', gap: '6px' }}>
+                        {LOAD_PROFILE_OPTIONS.map((opt) => {
+                          const active = (step.load_profile || []).includes(opt)
+                          return (
+                            <label
+                              key={opt}
+                              className="exercise-tag"
+                              style={{
+                                cursor: disabled || loading || saving ? 'default' : 'pointer',
+                                borderColor: active ? 'var(--accent)' : 'var(--border)',
+                                opacity: disabled || loading || saving ? 0.6 : 1,
+                              }}
+                            >
+                              <input
+                                type="checkbox"
+                                checked={active}
+                                disabled={disabled || loading || saving}
+                                style={{ marginRight: '4px' }}
+                                onChange={() => {
+                                  const current = step.load_profile || []
+                                  const next = active
+                                    ? current.filter((x) => x !== opt)
+                                    : [...current, opt]
+                                  patchMajorStep(idx, { load_profile: next })
+                                }}
+                              />
+                              {opt}
+                            </label>
+                          )
+                        })}
+                      </div>
+                    </div>
+                    <div className="form-row" style={{ marginBottom: 0 }}>
+                      <label className="form-label">Erfolgskriterien (je Zeile)</label>
+                      <textarea
+                        className="form-input"
+                        rows={2}
+                        value={listToMultiline(step.success_criteria)}
+                        onChange={(e) =>
+                          patchMajorStep(idx, { success_criteria: linesToStringList(e.target.value) })
+                        }
+                        placeholder={'z. B. Bezug zur Technik erkennbar\nPhase vertiefung im Übungsziel'}
+                        disabled={disabled || loading || saving}
+                      />
+                    </div>
+                    <div className="form-row" style={{ marginBottom: 0 }}>
+                      <label className="form-label">Vermeiden (optional, je Zeile)</label>
+                      <textarea
+                        className="form-input"
+                        rows={2}
+                        value={listToMultiline(step.anti_patterns)}
+                        onChange={(e) =>
+                          patchMajorStep(idx, { anti_patterns: linesToStringList(e.target.value) })
+                        }
+                        placeholder="z. B. reine Kraftübung ohne Technikbezug"
+                        disabled={disabled || loading || saving}
+                      />
+                    </div>
+                  </div>
+                </details>
               </div>
             ))}
           </div>
@@ -1361,6 +1528,30 @@ export default function ExerciseProgressionPathBuilder({
                       Ziel: {step.roadmapLearningGoal}
                     </p>
                   ) : null}
+                  {formatExpectedSkillNames(step.skillExpectations).length ? (
+                    <div
+                      style={{
+                        display: 'flex',
+                        flexWrap: 'wrap',
+                        gap: '4px',
+                        marginTop: '6px',
+                      }}
+                    >
+                      {formatExpectedSkillNames(step.skillExpectations).map((name) => (
+                        <span
+                          key={`${idx}-${name}`}
+                          className="exercise-tag"
+                          style={{
+                            fontSize: '10px',
+                            borderColor: 'color-mix(in srgb, var(--accent) 50%, var(--border))',
+                          }}
+                          title="Erwartete Fähigkeiten dieser Roadmap-Stufe"
+                        >
+                          {name}
+                        </span>
+                      ))}
+                    </div>
+                  ) : null}
                   <div style={{ fontSize: '13px' }}>
                     <strong>{step.exerciseTitle}</strong>
                     {step.exerciseId ? (
@@ -1454,6 +1645,7 @@ export default function ExerciseProgressionPathBuilder({
                 setPathQa(null)
                 setGapFillOffers([])
                 setProgressionRoadmap(null)
+                setPathSkillExpectations(null)
               }}
             >
               Vorschlag verwerfen

From 5692931d07ee8540dcd8ea7f4a4d2c52c2ad0c18 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Wed, 10 Jun 2026 07:25:57 +0200
Subject: [PATCH 04/33] Update version to 0.8.217 and enhance Exercise
 Progression Path Builder with planning roadmap features

- Incremented application version to 0.8.217 to reflect recent changes.
- Added support for a planning roadmap in the Exercise Progression Path Builder, allowing users to save and load structured planning artifacts.
- Enhanced the persistence logic for the planning roadmap, ensuring updates are correctly handled during graph modifications.
- Improved the user interface to display saved planning hints, enriching the user experience and interaction with the progression graphs.
---
 ...ise_progression_graph_planning_roadmap.sql |   8 ++
 .../progression_graph_planning_artifact.py    |  49 +++++++
 .../routers/exercise_progression_graphs.py    |  46 ++++--
 ...est_progression_graph_planning_artifact.py |  36 +++++
 backend/version.py                            |   4 +-
 .../ExerciseProgressionPathBuilder.jsx        | 136 +++++++++++++++++-
 6 files changed, 268 insertions(+), 11 deletions(-)
 create mode 100644 backend/migrations/088_exercise_progression_graph_planning_roadmap.sql
 create mode 100644 backend/progression_graph_planning_artifact.py
 create mode 100644 backend/tests/test_progression_graph_planning_artifact.py

diff --git a/backend/migrations/088_exercise_progression_graph_planning_roadmap.sql b/backend/migrations/088_exercise_progression_graph_planning_roadmap.sql
new file mode 100644
index 0000000..12eb27a
--- /dev/null
+++ b/backend/migrations/088_exercise_progression_graph_planning_roadmap.sql
@@ -0,0 +1,8 @@
+-- Migration 088: Planungs-Roadmap-Artefakt am Progressionsgraph (JSONB, optional).
+-- Speichert Ziel, Start/Ziel, progression_roadmap + stage_specs für Wiederaufnahme der KI-Planung.
+
+ALTER TABLE exercise_progression_graphs
+    ADD COLUMN IF NOT EXISTS planning_roadmap JSONB;
+
+COMMENT ON COLUMN exercise_progression_graphs.planning_roadmap IS
+    'Optionales Planungs-Artefakt (goal_query, resolved_structured, progression_roadmap, stage_specs) — Schema v1 im App-Code.';
diff --git a/backend/progression_graph_planning_artifact.py b/backend/progression_graph_planning_artifact.py
new file mode 100644
index 0000000..64020d4
--- /dev/null
+++ b/backend/progression_graph_planning_artifact.py
@@ -0,0 +1,49 @@
+"""Validierung und Normalisierung des Planungs-Artefakts am Progressionsgraph."""
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+ARTIFACT_SCHEMA_VERSION = 1
+_MAX_JSON_BYTES = 64_000
+
+
+class GraphPlanningRoadmapArtifact(BaseModel):
+    schema_version: int = Field(default=ARTIFACT_SCHEMA_VERSION, ge=1, le=1)
+    goal_query: str = Field(default="", max_length=2000)
+    start_situation: Optional[str] = Field(default=None, max_length=2000)
+    target_state: Optional[str] = Field(default=None, max_length=2000)
+    roadmap_notes: Optional[str] = Field(default=None, max_length=2000)
+    max_steps: int = Field(default=5, ge=2, le=10)
+    progression_roadmap: Optional[Dict[str, Any]] = None
+    path_skill_expectations: Optional[Dict[str, Any]] = None
+
+    @field_validator("progression_roadmap", "path_skill_expectations", mode="before")
+    @classmethod
+    def _empty_dict_to_none(cls, v):
+        if v == {}:
+            return None
+        return v
+
+
+def normalize_planning_roadmap_payload(raw: Any) -> Optional[Dict[str, Any]]:
+    """None erlaubt (löschen); sonst validiertes Dict."""
+    if raw is None:
+        return None
+    if not isinstance(raw, dict):
+        raise ValueError("planning_roadmap muss ein JSON-Objekt sein")
+    artifact = GraphPlanningRoadmapArtifact.model_validate(raw)
+    out = artifact.model_dump(exclude_none=True)
+    blob = json.dumps(out, ensure_ascii=False)
+    if len(blob.encode("utf-8")) > _MAX_JSON_BYTES:
+        raise ValueError("planning_roadmap ist zu groß (max. 64 KB)")
+    return out
+
+
+__all__ = [
+    "ARTIFACT_SCHEMA_VERSION",
+    "GraphPlanningRoadmapArtifact",
+    "normalize_planning_roadmap_payload",
+]
diff --git a/backend/routers/exercise_progression_graphs.py b/backend/routers/exercise_progression_graphs.py
index 212359f..16c1380 100644
--- a/backend/routers/exercise_progression_graphs.py
+++ b/backend/routers/exercise_progression_graphs.py
@@ -3,13 +3,15 @@ Progressionsgraph zwischen Übungen (Übung → Übung), Migration 032–034.
 Optional Übungsvarianten als Knoten-Endpunkte; Sequenz-Bulk-Anlage.
 AuthZ analog training_plan_templates: Bearbeiten/Löschen wie Übungen; Governance-Übergänge zentral.
 """
-from typing import Any, List, Optional
+from typing import Any, Dict, List, Optional
 
 from fastapi import APIRouter, Depends, HTTPException, Query
 from pydantic import BaseModel, Field, model_validator
 from psycopg2 import IntegrityError
+from psycopg2.extras import Json
 
 from db import get_db, get_cursor, r2d
+from progression_graph_planning_artifact import normalize_planning_roadmap_payload
 from tenant_context import TenantContext, get_tenant_context, library_content_visibility_sql
 from club_tenancy import (
     assert_library_content_deletable,
@@ -36,6 +38,7 @@ class ProgressionGraphUpdate(BaseModel):
     description: Optional[str] = None
     visibility: Optional[str] = Field(None, pattern="^(private|club|official)$")
     club_id: Optional[int] = None
+    planning_roadmap: Optional[Dict[str, Any]] = None
 
 
 class ProgressionEdgeCreate(BaseModel):
@@ -59,6 +62,7 @@ class SequenceStep(BaseModel):
 class ProgressionSequenceCreate(BaseModel):
     steps: List[SequenceStep] = Field(..., min_length=2)
     segment_notes: Optional[List[Optional[str]]] = None
+    planning_roadmap: Optional[Dict[str, Any]] = None
     """Länge muss len(steps)-1 sein, wenn gesetzt; Notiz pro Kante Zwischen je zwei Schritten."""
 
     @model_validator(mode="after")
@@ -116,6 +120,17 @@ def _assert_graph_writable(cur, row: dict, profile_id: int, role: str) -> None:
     assert_library_content_editable(cur, profile_id, role, row)
 
 
+def _persist_graph_planning_roadmap(cur, graph_id: int, raw: Optional[Dict[str, Any]]) -> None:
+    try:
+        normalized = normalize_planning_roadmap_payload(raw)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    cur.execute(
+        "UPDATE exercise_progression_graphs SET planning_roadmap = %s WHERE id = %s",
+        (Json(normalized) if normalized is not None else None, graph_id),
+    )
+
+
 def _require_graph_read(cur, graph_id: int, profile_id: int, role: str) -> dict:
     row = _graph_row(cur, graph_id)
     _assert_graph_readable(cur, row, profile_id, role)
@@ -353,15 +368,24 @@ def update_progression_graph(
             fields.append("club_id = %s")
             params.append(next_club if next_vis == "club" else None)
 
-        if not fields:
+        if "planning_roadmap" in original:
+            _persist_graph_planning_roadmap(cur, graph_id, original.get("planning_roadmap"))
+
+        if not fields and "planning_roadmap" not in original:
             return get_progression_graph(graph_id, include_edges=False, tenant=tenant)
 
-        fields.append("updated_at = NOW()")
-        params.append(graph_id)
-        cur.execute(
-            f"UPDATE exercise_progression_graphs SET {', '.join(fields)} WHERE id = %s",
-            tuple(params),
-        )
+        if fields:
+            fields.append("updated_at = NOW()")
+            params.append(graph_id)
+            cur.execute(
+                f"UPDATE exercise_progression_graphs SET {', '.join(fields)} WHERE id = %s",
+                tuple(params),
+            )
+        elif "planning_roadmap" in original:
+            cur.execute(
+                "UPDATE exercise_progression_graphs SET updated_at = NOW() WHERE id = %s",
+                (graph_id,),
+            )
         conn.commit()
 
     return get_progression_graph(graph_id, include_edges=False, tenant=tenant)
@@ -488,6 +512,12 @@ def create_progression_sequence(
                     note,
                 )
                 created.append(row)
+            if body.planning_roadmap is not None:
+                _persist_graph_planning_roadmap(cur, graph_id, body.planning_roadmap)
+                cur.execute(
+                    "UPDATE exercise_progression_graphs SET updated_at = NOW() WHERE id = %s",
+                    (graph_id,),
+                )
             conn.commit()
         except IntegrityError as e:
             conn.rollback()
diff --git a/backend/tests/test_progression_graph_planning_artifact.py b/backend/tests/test_progression_graph_planning_artifact.py
new file mode 100644
index 0000000..523e6ea
--- /dev/null
+++ b/backend/tests/test_progression_graph_planning_artifact.py
@@ -0,0 +1,36 @@
+"""Tests Planungs-Artefakt am Progressionsgraph."""
+import pytest
+
+from progression_graph_planning_artifact import (
+    ARTIFACT_SCHEMA_VERSION,
+    normalize_planning_roadmap_payload,
+)
+
+
+def test_normalize_planning_roadmap_minimal():
+    out = normalize_planning_roadmap_payload(
+        {
+            "schema_version": ARTIFACT_SCHEMA_VERSION,
+            "goal_query": "Mae Geri Perfektion",
+            "max_steps": 5,
+        }
+    )
+    assert out["goal_query"] == "Mae Geri Perfektion"
+    assert out["max_steps"] == 5
+
+
+def test_normalize_planning_roadmap_with_progression_roadmap():
+    out = normalize_planning_roadmap_payload(
+        {
+            "goal_query": "Kumite Beinarbeit",
+            "progression_roadmap": {
+                "stage_specs": [{"major_step_index": 0, "learning_goal": "Grundstellung"}],
+            },
+        }
+    )
+    assert out["progression_roadmap"]["stage_specs"][0]["learning_goal"] == "Grundstellung"
+
+
+def test_normalize_rejects_invalid_type():
+    with pytest.raises(ValueError, match="JSON-Objekt"):
+        normalize_planning_roadmap_payload("not-json")
diff --git a/backend/version.py b/backend/version.py
index f33ed91..742ae6b 100644
--- a/backend/version.py
+++ b/backend/version.py
@@ -1,8 +1,8 @@
 # Shinkan Jinkendo Version Information
 
-APP_VERSION = "0.8.216"
+APP_VERSION = "0.8.217"
 BUILD_DATE = "2026-06-07"
-DB_SCHEMA_VERSION = "20260607087"
+DB_SCHEMA_VERSION = "20260607088"
 
 MODULE_VERSIONS = {
     "legal_documents": "1.4.0",  # Admin: Live-Vorschau pro Abschnitt + modale Vollvorschau (Editor + Dokumentenliste)
diff --git a/frontend/src/components/ExerciseProgressionPathBuilder.jsx b/frontend/src/components/ExerciseProgressionPathBuilder.jsx
index 52734f8..5784f75 100644
--- a/frontend/src/components/ExerciseProgressionPathBuilder.jsx
+++ b/frontend/src/components/ExerciseProgressionPathBuilder.jsx
@@ -233,6 +233,31 @@ function formatExpectedSkillNames(skillExpectations, limit = 4) {
     .slice(0, limit)
 }
 
+const PLANNING_ARTIFACT_SCHEMA = 1
+
+function buildPlanningRoadmapArtifactSnapshot({
+  goalQuery,
+  startSituation,
+  targetState,
+  roadmapNotes,
+  maxSteps,
+  progressionRoadmap,
+  pathSkillExpectations,
+}) {
+  const q = (goalQuery || '').trim()
+  if (!q && !progressionRoadmap) return null
+  return {
+    schema_version: PLANNING_ARTIFACT_SCHEMA,
+    goal_query: q,
+    start_situation: (startSituation || '').trim() || null,
+    target_state: (targetState || '').trim() || null,
+    roadmap_notes: (roadmapNotes || '').trim() || null,
+    max_steps: Number(maxSteps) || 5,
+    progression_roadmap: progressionRoadmap || null,
+    path_skill_expectations: pathSkillExpectations || null,
+  }
+}
+
 /** Einfügen wächst den Pfad; Ersetzen (replace_step_index) nicht. */
 function offerGrowsPath(offer) {
   const replaceIdx = offer?.replace_step_index
@@ -329,6 +354,93 @@ export default function ExerciseProgressionPathBuilder({
   const [gapPrepSupplements, setGapPrepSupplements] = useState('')
   const [gapPrepFocusAreaId, setGapPrepFocusAreaId] = useState('')
   const [gapPrepError, setGapPrepError] = useState('')
+  const [loadedPlanningHint, setLoadedPlanningHint] = useState(false)
+
+  const buildPlanningArtifact = useCallback(
+    () =>
+      buildPlanningRoadmapArtifactSnapshot({
+        goalQuery,
+        startSituation,
+        targetState,
+        roadmapNotes,
+        maxSteps,
+        progressionRoadmap,
+        pathSkillExpectations,
+      }),
+    [
+      goalQuery,
+      startSituation,
+      targetState,
+      roadmapNotes,
+      maxSteps,
+      progressionRoadmap,
+      pathSkillExpectations,
+    ],
+  )
+
+  const persistPlanningRoadmapToGraph = useCallback(async () => {
+    if (!graphId) return
+    const artifact = buildPlanningArtifact()
+    if (!artifact?.goal_query && !artifact?.progression_roadmap) return
+    try {
+      await api.updateExerciseProgressionGraph(Number(graphId), { planning_roadmap: artifact })
+    } catch (e) {
+      console.warn('Planungs-Artefakt konnte nicht gespeichert werden', e)
+    }
+  }, [graphId, buildPlanningArtifact])
+
+  useEffect(() => {
+    if (!graphId) return
+    let cancelled = false
+    setLoadedPlanningHint(false)
+    setPathSteps([])
+    setTargetSummary(null)
+    setSemanticBrief(null)
+    setPathQa(null)
+    setGapFillOffers([])
+    setPathSkillExpectations(null)
+    setEditableMajorSteps([])
+    setProgressionRoadmap(null)
+    setRoadmapDirty(false)
+    setStartTargetAnalyzed(false)
+    setError('')
+
+    api
+      .getExerciseProgressionGraph(Number(graphId))
+      .then((g) => {
+        if (cancelled) return
+        const art = g?.planning_roadmap
+        if (!art) return
+        if (art.goal_query) setGoalQuery(String(art.goal_query))
+        if (art.start_situation) setStartSituation(String(art.start_situation))
+        if (art.target_state) setTargetState(String(art.target_state))
+        if (art.roadmap_notes) setRoadmapNotes(String(art.roadmap_notes))
+        if (art.max_steps) setMaxSteps(Number(art.max_steps))
+        if (art.path_skill_expectations) setPathSkillExpectations(art.path_skill_expectations)
+        if (art.progression_roadmap) {
+          setProgressionRoadmap(art.progression_roadmap)
+          const majors = mapMajorStepsFromApi(art.progression_roadmap)
+          if (majors.length >= 2) {
+            setEditableMajorSteps(majors)
+          }
+        }
+        if (
+          art.start_situation ||
+          art.target_state ||
+          art.progression_roadmap?.resolved_structured
+        ) {
+          setStartTargetAnalyzed(true)
+        }
+        setLoadedPlanningHint(true)
+      })
+      .catch((e) => {
+        console.warn(e)
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [graphId])
 
   useEffect(() => {
     let cancelled = false
@@ -783,7 +895,7 @@ export default function ExerciseProgressionPathBuilder({
       const res = await api.suggestProgressionPath({
         query: q,
         max_steps: Number(maxSteps),
-        include_llm_intent: false,
+        include_llm_intent: true,
         include_path_qa: false,
         include_llm_path_qa: false,
         include_path_reorder: false,
@@ -818,6 +930,8 @@ export default function ExerciseProgressionPathBuilder({
       setGapFillOffers([])
       setPathSkillExpectations(null)
       setRoadmapDirty(false)
+      setLoadedPlanningHint(false)
+      await persistPlanningRoadmapToGraph()
     } catch (e) {
       console.error(e)
       setError(e.message || 'Roadmap-Vorschlag fehlgeschlagen')
@@ -865,6 +979,8 @@ export default function ExerciseProgressionPathBuilder({
       })
       applyPathMatchResponse(res, q)
       setMaxSteps(validSteps.length)
+      setLoadedPlanningHint(false)
+      await persistPlanningRoadmapToGraph()
     } catch (e) {
       console.error(e)
       setError(e.message || 'Übungs-Match fehlgeschlagen')
@@ -899,12 +1015,14 @@ export default function ExerciseProgressionPathBuilder({
     setSaving(true)
     setError('')
     try {
+      const planningArtifact = buildPlanningArtifact()
       await api.createExerciseProgressionSequence(Number(graphId), {
         steps: steps.map((s) => ({
           exercise_id: s.exerciseId,
           variant_id: s.variantId || null,
         })),
         segment_notes,
+        ...(planningArtifact ? { planning_roadmap: planningArtifact } : {}),
       })
       setPathSteps([])
       setTargetSummary(null)
@@ -942,6 +1060,22 @@ export default function ExerciseProgressionPathBuilder({
         Zuerst didaktische Roadmap vorschlagen und anpassen, dann Übungen je Major Step aus der Bibliothek matchen.
         Lücken können mit KI als Übung angelegt werden.
       </p>
+      {loadedPlanningHint && editableMajorSteps.length > 0 && pathSteps.length === 0 ? (
+        <p
+          style={{
+            fontSize: '12px',
+            color: 'var(--accent-dark)',
+            margin: '0 0 10px',
+            padding: '8px 10px',
+            borderRadius: '8px',
+            background: 'color-mix(in srgb, var(--accent) 8%, var(--surface))',
+            lineHeight: 1.45,
+          }}
+        >
+          Gespeicherte Planung für diesen Graph geladen — Roadmap anpassen und erneut matchen, oder neuen Vorschlag
+          starten.
+        </p>
+      ) : null}
       <div style={{ display: 'flex', flexWrap: 'wrap', gap: '10px', alignItems: 'flex-end' }}>
         <div className="form-row" style={{ flex: '2 1 240px', marginBottom: 0 }}>
           <label className="form-label">Ziel / Entwicklungsrichtung</label>

From ca3a9c6fa4f000f43ae63117020f1c02946b8ca1 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Wed, 10 Jun 2026 07:30:01 +0200
Subject: [PATCH 05/33] Enhance Exercise Progression Path Builder with Planning
 Wizard Stepper

- Introduced a new Planning Wizard Stepper component to guide users through the exercise planning process in four steps.
- Implemented logic to compute the maximum reachable step based on user input and current progress.
- Updated state management to track the current wizard step and ensure it aligns with user interactions.
- Enhanced the user interface to improve clarity and navigation through the planning stages.
- Incremented application version to reflect these changes.
---
 .../ExerciseProgressionPathBuilder.jsx        | 704 ++++++++++++------
 1 file changed, 487 insertions(+), 217 deletions(-)

diff --git a/frontend/src/components/ExerciseProgressionPathBuilder.jsx b/frontend/src/components/ExerciseProgressionPathBuilder.jsx
index 5784f75..b6a2deb 100644
--- a/frontend/src/components/ExerciseProgressionPathBuilder.jsx
+++ b/frontend/src/components/ExerciseProgressionPathBuilder.jsx
@@ -1,7 +1,7 @@
 /**
  * Planungs-KI Phase C3/E3: Ziel → Übungspfad vorschlagen → Lücken mit KI anlegen → in Graph speichern.
  */
-import React, { useCallback, useEffect, useState } from 'react'
+import React, { useCallback, useEffect, useMemo, useState } from 'react'
 import api from '../utils/api'
 import ExerciseAiQuickCreateModal from './exercises/ExerciseAiQuickCreateModal'
 import ExerciseGapFillPrepModal from './exercises/ExerciseGapFillPrepModal'
@@ -136,6 +136,93 @@ const OFFER_SOURCE_LABELS = {
 
 const PATH_STEPS_HARD_MAX = 10
 
+const WIZARD_STEPS = [
+  { id: 1, label: 'Ziel & Start/Ziel', short: 'Ziel' },
+  { id: 2, label: 'Roadmap', short: 'Roadmap' },
+  { id: 3, label: 'Match', short: 'Match' },
+  { id: 4, label: 'Lücken & Speichern', short: 'Speichern' },
+]
+
+function computeMaxReachableStep(editableMajorSteps, pathSteps) {
+  if (pathSteps.length > 0) return 4
+  if (editableMajorSteps.length >= 2) return 2
+  return 1
+}
+
+function PlanningWizardStepper({ currentStep, maxReachable, onStepChange, disabled }) {
+  return (
+    <nav
+      aria-label="Planungsfortschritt"
+      style={{
+        display: 'flex',
+        flexWrap: 'wrap',
+        gap: '4px',
+        marginBottom: '16px',
+        padding: '10px 12px',
+        borderRadius: '10px',
+        background: 'var(--surface2)',
+        border: '1px solid var(--border)',
+      }}
+    >
+      {WIZARD_STEPS.map((step, idx) => {
+        const reachable = step.id <= maxReachable
+        const active = currentStep === step.id
+        const done = step.id < currentStep && reachable
+        const canClick = reachable && !disabled && step.id <= maxReachable
+        return (
+          <React.Fragment key={step.id}>
+            {idx > 0 ? (
+              <span
+                aria-hidden
+                style={{
+                  alignSelf: 'center',
+                  color: done || active ? 'var(--accent)' : 'var(--text3)',
+                  fontSize: '12px',
+                  padding: '0 2px',
+                }}
+              >
+                →
+              </span>
+            ) : null}
+            <button
+              type="button"
+              className={active ? 'btn btn-primary' : 'btn btn-secondary'}
+              disabled={!canClick}
+              onClick={() => canClick && onStepChange(step.id)}
+              style={{
+                flex: '1 1 120px',
+                minWidth: '100px',
+                fontSize: '12px',
+                padding: '8px 10px',
+                opacity: reachable ? 1 : 0.45,
+                borderColor: active
+                  ? 'var(--accent)'
+                  : done
+                    ? 'color-mix(in srgb, var(--accent) 40%, var(--border))'
+                    : undefined,
+              }}
+              title={step.label}
+              aria-current={active ? 'step' : undefined}
+            >
+              <span style={{ marginRight: '6px', fontWeight: 700 }}>{step.id}</span>
+              <span className="planning-step-label-full">{step.label}</span>
+              <span className="planning-step-label-short" style={{ display: 'none' }}>
+                {step.short}
+              </span>
+            </button>
+          </React.Fragment>
+        )
+      })}
+      <style>{`
+        @media (max-width: 520px) {
+          .planning-step-label-full { display: none !important; }
+          .planning-step-label-short { display: inline !important; }
+        }
+      `}</style>
+    </nav>
+  )
+}
+
 const ROADMAP_PHASES = ['einstieg', 'grundlage', 'vertiefung', 'anwendung', 'perfektion']
 
 const LOAD_PROFILE_OPTIONS = [
@@ -355,6 +442,12 @@ export default function ExerciseProgressionPathBuilder({
   const [gapPrepFocusAreaId, setGapPrepFocusAreaId] = useState('')
   const [gapPrepError, setGapPrepError] = useState('')
   const [loadedPlanningHint, setLoadedPlanningHint] = useState(false)
+  const [wizardStep, setWizardStep] = useState(1)
+
+  const maxReachableStep = useMemo(
+    () => computeMaxReachableStep(editableMajorSteps, pathSteps),
+    [editableMajorSteps, pathSteps],
+  )
 
   const buildPlanningArtifact = useCallback(
     () =>
@@ -404,6 +497,7 @@ export default function ExerciseProgressionPathBuilder({
     setRoadmapDirty(false)
     setStartTargetAnalyzed(false)
     setError('')
+    setWizardStep(1)
 
     api
       .getExerciseProgressionGraph(Number(graphId))
@@ -422,6 +516,7 @@ export default function ExerciseProgressionPathBuilder({
           const majors = mapMajorStepsFromApi(art.progression_roadmap)
           if (majors.length >= 2) {
             setEditableMajorSteps(majors)
+            setWizardStep(2)
           }
         }
         if (
@@ -442,6 +537,12 @@ export default function ExerciseProgressionPathBuilder({
     }
   }, [graphId])
 
+  useEffect(() => {
+    if (wizardStep > maxReachableStep) {
+      setWizardStep(maxReachableStep)
+    }
+  }, [wizardStep, maxReachableStep])
+
   useEffect(() => {
     let cancelled = false
     Promise.all([
@@ -931,6 +1032,7 @@ export default function ExerciseProgressionPathBuilder({
       setPathSkillExpectations(null)
       setRoadmapDirty(false)
       setLoadedPlanningHint(false)
+      setWizardStep(2)
       await persistPlanningRoadmapToGraph()
     } catch (e) {
       console.error(e)
@@ -980,6 +1082,7 @@ export default function ExerciseProgressionPathBuilder({
       applyPathMatchResponse(res, q)
       setMaxSteps(validSteps.length)
       setLoadedPlanningHint(false)
+      setWizardStep(3)
       await persistPlanningRoadmapToGraph()
     } catch (e) {
       console.error(e)
@@ -1033,6 +1136,7 @@ export default function ExerciseProgressionPathBuilder({
       setPathSkillExpectations(null)
       setEditableMajorSteps([])
       setRoadmapDirty(false)
+      setWizardStep(1)
       if (typeof onSaved === 'function') await onSaved()
       const msg =
         skippedAi > 0
@@ -1057,26 +1161,43 @@ export default function ExerciseProgressionPathBuilder({
     >
       <h3 style={{ marginTop: 0, fontSize: '1rem' }}>KI: Pfad zum Ziel</h3>
       <p style={{ fontSize: '12px', color: 'var(--text3)', marginTop: 0, lineHeight: 1.45 }}>
-        Zuerst didaktische Roadmap vorschlagen und anpassen, dann Übungen je Major Step aus der Bibliothek matchen.
-        Lücken können mit KI als Übung angelegt werden.
+        In vier Schritten: Ziel festlegen → Roadmap bearbeiten → Übungen matchen → Lücken schließen und speichern.
       </p>
-      {loadedPlanningHint && editableMajorSteps.length > 0 && pathSteps.length === 0 ? (
-        <p
-          style={{
-            fontSize: '12px',
-            color: 'var(--accent-dark)',
-            margin: '0 0 10px',
-            padding: '8px 10px',
-            borderRadius: '8px',
-            background: 'color-mix(in srgb, var(--accent) 8%, var(--surface))',
-            lineHeight: 1.45,
-          }}
-        >
-          Gespeicherte Planung für diesen Graph geladen — Roadmap anpassen und erneut matchen, oder neuen Vorschlag
-          starten.
+
+      <PlanningWizardStepper
+        currentStep={wizardStep}
+        maxReachable={maxReachableStep}
+        onStepChange={setWizardStep}
+        disabled={disabled || loading || saving}
+      />
+
+      {error ? (
+        <p className="form-error" style={{ marginTop: 0, marginBottom: '12px' }}>
+          {error}
         </p>
       ) : null}
-      <div style={{ display: 'flex', flexWrap: 'wrap', gap: '10px', alignItems: 'flex-end' }}>
+
+      {wizardStep === 1 ? (
+        <section aria-labelledby="planning-step-1-heading">
+          <h4 id="planning-step-1-heading" style={{ margin: '0 0 10px', fontSize: '0.95rem' }}>
+            Schritt 1 — Ziel & Start/Ziel
+          </h4>
+          {loadedPlanningHint && editableMajorSteps.length > 0 && pathSteps.length === 0 ? (
+            <p
+              style={{
+                fontSize: '12px',
+                color: 'var(--accent-dark)',
+                margin: '0 0 10px',
+                padding: '8px 10px',
+                borderRadius: '8px',
+                background: 'color-mix(in srgb, var(--accent) 8%, var(--surface))',
+                lineHeight: 1.45,
+              }}
+            >
+              Gespeicherte Planung geladen — Sie können bei Schritt 2 weitermachen oder hier neu starten.
+            </p>
+          ) : null}
+          <div style={{ display: 'flex', flexWrap: 'wrap', gap: '10px', alignItems: 'flex-end' }}>
         <div className="form-row" style={{ flex: '2 1 240px', marginBottom: 0 }}>
           <label className="form-label">Ziel / Entwicklungsrichtung</label>
           <input
@@ -1142,78 +1263,56 @@ export default function ExerciseProgressionPathBuilder({
           />
         </div>
       </div>
-      <p style={{ fontSize: '11px', color: 'var(--text3)', margin: '6px 0 0', lineHeight: 1.4 }}>
-        Optional zuerst „Start/Ziel analysieren“, anpassen, dann Roadmap-Stufen. Sind Start und Ziel leer,
-        geschieht die Analyse beim Roadmap-Vorschlag automatisch mit. Manuelle Eingaben haben immer Vorrang.
-      </p>
-      <div style={{ display: 'flex', flexWrap: 'wrap', gap: '10px', alignItems: 'flex-end', marginTop: '10px' }}>
-        <button
-          type="button"
-          className="btn btn-secondary"
-          disabled={disabled || loading || saving || !graphId}
-          onClick={analyzeStartTarget}
-          title="Nur Ausgangslage, Zielzustand und Ergänzungen per KI — ohne Roadmap-Stufen"
-        >
-          {loadingStartTarget ? 'Analyse …' : 'Start/Ziel analysieren'}
-        </button>
-        <button
-          type="button"
-          className="btn btn-primary"
-          disabled={disabled || loading || saving || !graphId}
-          onClick={suggestRoadmap}
-          title={
-            startSituation.trim() && targetState.trim()
-              ? 'Roadmap-Stufen aus den gesetzten Start/Ziel-Feldern'
-              : 'Start/Ziel-Analyse und Roadmap-Stufen in einem Schritt'
-          }
-        >
-          {loadingRoadmap ? 'Roadmap …' : 'Roadmap vorschlagen'}
-        </button>
-        {startTargetAnalyzed && !editableMajorSteps.length ? (
-          <span className="exercise-tag" style={{ borderColor: 'var(--accent)' }}>
-            Start/Ziel bereit — Roadmap als Nächstes
-          </span>
-        ) : null}
-        <button
-          type="button"
-          className="btn btn-secondary"
-          disabled={
-            disabled ||
-            loading ||
-            saving ||
-            !graphId ||
-            editableMajorSteps.length < 2
-          }
-          onClick={matchExercisesFromRoadmap}
-          title={
-            editableMajorSteps.length < 2
-              ? 'Zuerst Roadmap vorschlagen'
-              : roadmapDirty
-                ? 'Roadmap wurde bearbeitet — erneut matchen'
-                : 'Bibliothek je Major Step durchsuchen'
-          }
-        >
-          {loadingMatch ? 'Match …' : roadmapDirty ? 'Übungen neu matchen' : 'Übungen matchen'}
-        </button>
-      </div>
+          <p style={{ fontSize: '11px', color: 'var(--text3)', margin: '6px 0 0', lineHeight: 1.4 }}>
+            Optional zuerst „Start/Ziel analysieren“, anpassen, dann Roadmap-Stufen. Sind Start und Ziel leer,
+            geschieht die Analyse beim Roadmap-Vorschlag automatisch mit. Manuelle Eingaben haben immer Vorrang.
+          </p>
+          <div style={{ display: 'flex', flexWrap: 'wrap', gap: '10px', alignItems: 'center', marginTop: '12px' }}>
+            <button
+              type="button"
+              className="btn btn-secondary"
+              disabled={disabled || loading || saving || !graphId}
+              onClick={analyzeStartTarget}
+              title="Nur Ausgangslage, Zielzustand und Ergänzungen per KI — ohne Roadmap-Stufen"
+            >
+              {loadingStartTarget ? 'Analyse …' : 'Start/Ziel analysieren'}
+            </button>
+            <button
+              type="button"
+              className="btn btn-primary"
+              disabled={disabled || loading || saving || !graphId}
+              onClick={suggestRoadmap}
+              title={
+                startSituation.trim() && targetState.trim()
+                  ? 'Roadmap-Stufen aus den gesetzten Start/Ziel-Feldern'
+                  : 'Start/Ziel-Analyse und Roadmap-Stufen in einem Schritt'
+              }
+            >
+              {loadingRoadmap ? 'Roadmap …' : 'Roadmap vorschlagen →'}
+            </button>
+            {startTargetAnalyzed && !editableMajorSteps.length ? (
+              <span className="exercise-tag" style={{ borderColor: 'var(--accent)' }}>
+                Start/Ziel bereit
+              </span>
+            ) : null}
+          </div>
 
-      {error ? (
-        <p className="form-error" style={{ marginTop: '10px' }}>
-          {error}
-        </p>
-      ) : null}
-
-      {(progressionRoadmap?.goal_analysis ||
-        progressionRoadmap?.pipeline_phase === 'start_target_only') ? (
-        <div
-          style={{
-            marginTop: '12px',
-            padding: '12px',
-            borderRadius: '8px',
-            border: '1px solid var(--border)',
-            background: 'var(--surface2)',
-          }}
-        >
+          {(progressionRoadmap?.goal_analysis ||
+            progressionRoadmap?.pipeline_phase === 'start_target_only') ? (
+            <details
+              style={{
+                marginTop: '12px',
+                padding: '10px 12px',
+                borderRadius: '8px',
+                border: '1px solid var(--border)',
+                background: 'var(--surface2)',
+                fontSize: '12px',
+              }}
+            >
+              <summary style={{ cursor: 'pointer', fontWeight: 600, color: 'var(--accent-dark)' }}>
+                KI-Zielanalyse (Details)
+              </summary>
+              <div style={{ marginTop: '10px' }}>
           <div style={{ display: 'flex', flexWrap: 'wrap', gap: '8px', alignItems: 'center', marginBottom: '8px' }}>
             <strong style={{ fontSize: '13px' }}>Zielanalyse</strong>
             {progressionRoadmap.llm_start_target_applied ? (
@@ -1261,45 +1360,32 @@ export default function ExerciseProgressionPathBuilder({
               </p>
             ) : null}
           </div>
-        </div>
-      ) : null}
-
-      {(semanticBrief || targetSummary || pathSkillExpectations) && pathSteps.length > 0 ? (
-        <div style={{ marginTop: '10px', display: 'flex', flexWrap: 'wrap', gap: '6px' }}>
-          {semanticBrief?.primary_topic ? (
-            <span className="exercise-tag" style={{ borderColor: 'var(--accent)' }}>
-              Thema: {semanticBrief.primary_topic}
-            </span>
+              </div>
+            </details>
           ) : null}
-          {Array.isArray(semanticBrief?.development_arc) &&
-            semanticBrief.development_arc.slice(0, 3).map((phase) => (
-              <span key={phase} className="exercise-tag">
-                {phase}
-              </span>
-            ))}
-          {Array.isArray(targetSummary?.focus_areas) &&
-            targetSummary.focus_areas.slice(0, 1).map((fa) => (
-              <span key={fa} className="exercise-tag">
-                Fokus: {fa}
-              </span>
-            ))}
-          {formatExpectedSkillNames(pathSkillExpectations, 5).map((name) => (
-            <span
-              key={`path-skill-${name}`}
-              className="exercise-tag"
-              style={{ borderColor: 'color-mix(in srgb, var(--accent) 55%, var(--border))' }}
-              title="Pfadweite Fähigkeiten-Erwartung (Scoring)"
-            >
-              {name}
-            </span>
-          ))}
-        </div>
+        </section>
       ) : null}
 
-      {editableMajorSteps.length > 0 ? (
+      {wizardStep === 2 ? (
+        <section aria-labelledby="planning-step-2-heading">
+          <h4 id="planning-step-2-heading" style={{ margin: '0 0 10px', fontSize: '0.95rem' }}>
+            Schritt 2 — Didaktische Roadmap
+          </h4>
+          {editableMajorSteps.length === 0 ? (
+            <p style={{ fontSize: '13px', color: 'var(--text2)', margin: 0 }}>
+              Noch keine Roadmap — zuerst in Schritt 1 „Roadmap vorschlagen“.
+              <button
+                type="button"
+                className="btn btn-secondary"
+                style={{ marginLeft: '10px', fontSize: '12px' }}
+                onClick={() => setWizardStep(1)}
+              >
+                Zu Schritt 1
+              </button>
+            </p>
+          ) : (
         <div
           style={{
-            marginTop: '12px',
             padding: '12px',
             borderRadius: '8px',
             border: '1px solid color-mix(in srgb, var(--accent) 45%, var(--border))',
@@ -1307,7 +1393,7 @@ export default function ExerciseProgressionPathBuilder({
           }}
         >
           <div style={{ display: 'flex', flexWrap: 'wrap', gap: '8px', alignItems: 'center', marginBottom: '8px' }}>
-            <strong style={{ fontSize: '13px' }}>Didaktische Roadmap — bearbeiten</strong>
+            <strong style={{ fontSize: '13px' }}>Major Steps bearbeiten</strong>
             {roadmapDirty ? (
               <span className="exercise-tag" style={{ borderColor: 'var(--danger)' }}>
                 Geändert — bitte erneut matchen
@@ -1489,9 +1575,102 @@ export default function ExerciseProgressionPathBuilder({
             </button>
           ) : null}
         </div>
+          )}
+          {editableMajorSteps.length >= 2 ? (
+            <div
+              style={{
+                display: 'flex',
+                flexWrap: 'wrap',
+                gap: '10px',
+                alignItems: 'center',
+                marginTop: '14px',
+                paddingTop: '14px',
+                borderTop: '1px solid var(--border)',
+              }}
+            >
+              <button
+                type="button"
+                className="btn btn-secondary"
+                onClick={() => setWizardStep(1)}
+                disabled={disabled || loading || saving}
+              >
+                ← Zurück
+              </button>
+              <button
+                type="button"
+                className="btn btn-primary"
+                disabled={disabled || loading || saving || !graphId}
+                onClick={matchExercisesFromRoadmap}
+                title={
+                  roadmapDirty
+                    ? 'Roadmap wurde bearbeitet — erneut matchen'
+                    : 'Bibliothek je Major Step durchsuchen'
+                }
+              >
+                {loadingMatch ? 'Match …' : roadmapDirty ? 'Übungen neu matchen →' : 'Übungen matchen →'}
+              </button>
+            </div>
+          ) : null}
+        </section>
       ) : null}
 
-      {pathQa && pathSteps.length > 0 ? (
+      {wizardStep === 3 ? (
+        <section aria-labelledby="planning-step-3-heading">
+          <h4 id="planning-step-3-heading" style={{ margin: '0 0 10px', fontSize: '0.95rem' }}>
+            Schritt 3 — Übungen & Qualität
+          </h4>
+          {pathSteps.length === 0 ? (
+            <p style={{ fontSize: '13px', color: 'var(--text2)', margin: 0 }}>
+              Noch kein Match — zuerst in Schritt 2 „Übungen matchen“.
+              <button
+                type="button"
+                className="btn btn-secondary"
+                style={{ marginLeft: '10px', fontSize: '12px' }}
+                onClick={() => setWizardStep(editableMajorSteps.length >= 2 ? 2 : 1)}
+              >
+                Zurück
+              </button>
+            </p>
+          ) : (
+            <>
+          {(semanticBrief || targetSummary || pathSkillExpectations) ? (
+            <details style={{ marginBottom: '10px', fontSize: '12px' }}>
+              <summary style={{ cursor: 'pointer', color: 'var(--accent-dark)', fontWeight: 600 }}>
+                Pfad-Kontext (Thema, Fokus, Fähigkeiten)
+              </summary>
+              <div style={{ marginTop: '8px', display: 'flex', flexWrap: 'wrap', gap: '6px' }}>
+          {semanticBrief?.primary_topic ? (
+            <span className="exercise-tag" style={{ borderColor: 'var(--accent)' }}>
+              Thema: {semanticBrief.primary_topic}
+            </span>
+          ) : null}
+          {Array.isArray(semanticBrief?.development_arc) &&
+            semanticBrief.development_arc.slice(0, 3).map((phase) => (
+              <span key={phase} className="exercise-tag">
+                {phase}
+              </span>
+            ))}
+          {Array.isArray(targetSummary?.focus_areas) &&
+            targetSummary.focus_areas.slice(0, 1).map((fa) => (
+              <span key={fa} className="exercise-tag">
+                Fokus: {fa}
+              </span>
+            ))}
+          {formatExpectedSkillNames(pathSkillExpectations, 5).map((name) => (
+            <span
+              key={`path-skill-${name}`}
+              className="exercise-tag"
+              style={{ borderColor: 'color-mix(in srgb, var(--accent) 55%, var(--border))' }}
+              title="Pfadweite Fähigkeiten-Erwartung (Scoring)"
+            >
+              {name}
+            </span>
+          ))}
+              </div>
+            </details>
+          ) : null}
+
+      {pathQa ? (
         <div
           style={{
             marginTop: '10px',
@@ -1528,7 +1707,7 @@ export default function ExerciseProgressionPathBuilder({
             </p>
           ) : Number(pathQa.off_topic_count) > 0 ? (
             <p style={{ margin: '6px 0 0', color: 'var(--danger)' }}>
-              {pathQa.off_topic_count} Schritt(e) ohne Bezug zum Pfad-Thema — siehe Lücken-Angebote unten.
+              {pathQa.off_topic_count} Schritt(e) ohne Bezug zum Pfad-Thema — Lücken in Schritt 4 schließen.
             </p>
           ) : null}
           {pathQa.reorder_applied ? (
@@ -1547,88 +1726,7 @@ export default function ExerciseProgressionPathBuilder({
         </div>
       ) : null}
 
-      {gapFillOffers.length > 0 ? (
-        <div
-          style={{
-            marginTop: '12px',
-            padding: '12px',
-            borderRadius: '8px',
-            border: '1px solid color-mix(in srgb, var(--accent) 40%, var(--border))',
-            background: 'color-mix(in srgb, var(--accent) 5%, var(--surface))',
-          }}
-        >
-          <strong style={{ fontSize: '13px' }}>Fehlende Schritte — mit KI anlegen</strong>
-          <p style={{ fontSize: '12px', color: 'var(--text3)', margin: '6px 0 10px', lineHeight: 1.45 }}>
-            Fehlende oder zu ersetzende Schritte ({pathSteps.length}/{maxSteps} im Pfad).
-            {pathSteps.length >= maxSteps
-              ? ' Der Pfad ist voll — beim Einfügen können Sie die Pfadlänge dynamisch vergrößern (ohne neuen Vorschlag); Ersatz-Angebote ersetzen einen Schritt.'
-              : ' Zuerst Kontext prüfen und ergänzen, dann KI-Entwurf erstellen und einfügen.'}
-          </p>
           <div style={{ display: 'flex', flexDirection: 'column', gap: '10px' }}>
-            {gapFillOffers.map((offer) => (
-              <div
-                key={offer.offer_id}
-                style={{
-                  padding: '10px 12px',
-                  borderRadius: '8px',
-                  background: 'var(--surface2)',
-                  border: '1px solid var(--border)',
-                }}
-              >
-                <div style={{ display: 'flex', flexWrap: 'wrap', gap: '8px', alignItems: 'flex-start' }}>
-                  <div style={{ flex: '1 1 200px' }}>
-                    <span className="exercise-tag" style={{ marginBottom: '6px', display: 'inline-block' }}>
-                      {OFFER_SOURCE_LABELS[offer.source] || offer.source || 'Lücke'}
-                      {offer.phase ? ` · ${offer.phase}` : ''}
-                    </span>
-                    <div style={{ fontSize: '13px', fontWeight: 600 }}>{offer.title_hint}</div>
-                    {offer.rationale ? (
-                      <p style={{ fontSize: '12px', color: 'var(--text2)', margin: '4px 0 0' }}>{offer.rationale}</p>
-                    ) : null}
-                    {offer.from_title && offer.to_title ? (
-                      <p style={{ fontSize: '11px', color: 'var(--text3)', margin: '4px 0 0' }}>
-                        Zwischen „{offer.from_title}“ und „{offer.to_title}“
-                        {offer.replace_step_index != null ? ' (ersetzt themenfremden Schritt)' : ''}
-                      </p>
-                    ) : null}
-                    <GapOfferContextPreview
-                      lines={gapOfferContextDisplayLines(offer, gapContextFallbackParams)}
-                    />
-                  </div>
-                  <button
-                    type="button"
-                    className="btn btn-primary"
-                    style={{ fontSize: '12px', flexShrink: 0 }}
-                    disabled={
-                      quickSaving ||
-                      (isGapOfferBlockedByPathCapacity(offer, pathSteps.length, maxSteps) &&
-                        maxSteps >= PATH_STEPS_HARD_MAX)
-                    }
-                    onClick={() => handleGapFillClick(offer)}
-                    title={
-                      isGapOfferBlockedByPathCapacity(offer, pathSteps.length, maxSteps)
-                        ? maxSteps >= PATH_STEPS_HARD_MAX
-                          ? `Maximal ${PATH_STEPS_HARD_MAX} Schritte — zuerst einen Schritt entfernen.`
-                          : 'Pfad voll — Klick fragt, ob die Pfadlänge vergrößert werden soll'
-                        : offer.replace_step_index != null
-                          ? 'Ersetzt den themenfremden Schritt im Pfad'
-                          : 'Kontext prüfen, Ergänzungen mitgeben, dann KI-Entwurf'
-                    }
-                  >
-                    {generatingOfferId === offer.offer_id
-                      ? 'KI erstellt Entwurf …'
-                      : 'Vorbereiten & KI anlegen'}
-                  </button>
-                </div>
-              </div>
-            ))}
-          </div>
-        </div>
-      ) : null}
-
-      {pathSteps.length > 0 ? (
-        <>
-          <div style={{ marginTop: '14px' }}>
             {pathSteps.map((step, idx) => (
               <div
                 key={`${step.exerciseId}-${step.proposalKey || ''}-${idx}`}
@@ -1637,14 +1735,12 @@ export default function ExerciseProgressionPathBuilder({
                   gridTemplateColumns: 'repeat(auto-fit, minmax(200px, 1fr))',
                   gap: '10px',
                   alignItems: 'end',
-                  marginBottom: '12px',
-                  paddingBottom: '12px',
-                  borderBottom: idx < pathSteps.length - 1 ? '1px dashed var(--border)' : 'none',
+                  padding: step.isOffTopic ? '8px' : '10px 12px',
+                  borderRadius: '8px',
+                  border: '1px solid var(--border)',
                   background: step.isOffTopic
-                    ? 'color-mix(in srgb, var(--danger) 6%, transparent)'
-                    : undefined,
-                  borderRadius: step.isOffTopic ? '8px' : undefined,
-                  padding: step.isOffTopic ? '8px' : undefined,
+                    ? 'color-mix(in srgb, var(--danger) 6%, var(--surface2))'
+                    : 'var(--surface2)',
                 }}
               >
                 <div className="form-row" style={{ marginBottom: 0 }}>
@@ -1749,6 +1845,170 @@ export default function ExerciseProgressionPathBuilder({
               </div>
             ))}
           </div>
+          <div
+            style={{
+              display: 'flex',
+              flexWrap: 'wrap',
+              gap: '10px',
+              alignItems: 'center',
+              marginTop: '14px',
+              paddingTop: '14px',
+              borderTop: '1px solid var(--border)',
+            }}
+          >
+            <button
+              type="button"
+              className="btn btn-secondary"
+              onClick={() => setWizardStep(2)}
+              disabled={disabled || loading || saving}
+            >
+              ← Roadmap
+            </button>
+            <button
+              type="button"
+              className="btn btn-primary"
+              onClick={() => setWizardStep(4)}
+              disabled={disabled || loading || saving}
+            >
+              Weiter zu Lücken & Speichern →
+            </button>
+            {gapFillOffers.length > 0 ? (
+              <span className="exercise-tag" style={{ borderColor: 'var(--danger)' }}>
+                {gapFillOffers.length} Lücke(n) offen
+              </span>
+            ) : null}
+          </div>
+            </>
+          )}
+        </section>
+      ) : null}
+
+      {wizardStep === 4 ? (
+        <section aria-labelledby="planning-step-4-heading">
+          <h4 id="planning-step-4-heading" style={{ margin: '0 0 10px', fontSize: '0.95rem' }}>
+            Schritt 4 — Lücken schließen & Pfad speichern
+          </h4>
+          {pathSteps.length === 0 ? (
+            <p style={{ fontSize: '13px', color: 'var(--text2)', margin: 0 }}>
+              Noch kein Pfad — zuerst Schritt 3 abschließen.
+              <button
+                type="button"
+                className="btn btn-secondary"
+                style={{ marginLeft: '10px', fontSize: '12px' }}
+                onClick={() => setWizardStep(3)}
+              >
+                Zu Schritt 3
+              </button>
+            </p>
+          ) : (
+            <>
+          {gapFillOffers.length > 0 ? (
+        <div
+          style={{
+            marginBottom: '14px',
+            padding: '12px',
+            borderRadius: '8px',
+            border: '1px solid color-mix(in srgb, var(--accent) 40%, var(--border))',
+            background: 'color-mix(in srgb, var(--accent) 5%, var(--surface))',
+          }}
+        >
+          <strong style={{ fontSize: '13px' }}>Fehlende Schritte — mit KI anlegen</strong>
+          <p style={{ fontSize: '12px', color: 'var(--text3)', margin: '6px 0 10px', lineHeight: 1.45 }}>
+            Fehlende oder zu ersetzende Schritte ({pathSteps.length}/{maxSteps} im Pfad).
+            {pathSteps.length >= maxSteps
+              ? ' Der Pfad ist voll — beim Einfügen können Sie die Pfadlänge dynamisch vergrößern (ohne neuen Vorschlag); Ersatz-Angebote ersetzen einen Schritt.'
+              : ' Zuerst Kontext prüfen und ergänzen, dann KI-Entwurf erstellen und einfügen.'}
+          </p>
+          <div style={{ display: 'flex', flexDirection: 'column', gap: '10px' }}>
+            {gapFillOffers.map((offer) => (
+              <div
+                key={offer.offer_id}
+                style={{
+                  padding: '10px 12px',
+                  borderRadius: '8px',
+                  background: 'var(--surface2)',
+                  border: '1px solid var(--border)',
+                }}
+              >
+                <div style={{ display: 'flex', flexWrap: 'wrap', gap: '8px', alignItems: 'flex-start' }}>
+                  <div style={{ flex: '1 1 200px' }}>
+                    <span className="exercise-tag" style={{ marginBottom: '6px', display: 'inline-block' }}>
+                      {OFFER_SOURCE_LABELS[offer.source] || offer.source || 'Lücke'}
+                      {offer.phase ? ` · ${offer.phase}` : ''}
+                    </span>
+                    <div style={{ fontSize: '13px', fontWeight: 600 }}>{offer.title_hint}</div>
+                    {offer.rationale ? (
+                      <p style={{ fontSize: '12px', color: 'var(--text2)', margin: '4px 0 0' }}>{offer.rationale}</p>
+                    ) : null}
+                    {offer.from_title && offer.to_title ? (
+                      <p style={{ fontSize: '11px', color: 'var(--text3)', margin: '4px 0 0' }}>
+                        Zwischen „{offer.from_title}“ und „{offer.to_title}“
+                        {offer.replace_step_index != null ? ' (ersetzt themenfremden Schritt)' : ''}
+                      </p>
+                    ) : null}
+                    <GapOfferContextPreview
+                      lines={gapOfferContextDisplayLines(offer, gapContextFallbackParams)}
+                    />
+                  </div>
+                  <button
+                    type="button"
+                    className="btn btn-primary"
+                    style={{ fontSize: '12px', flexShrink: 0 }}
+                    disabled={
+                      quickSaving ||
+                      (isGapOfferBlockedByPathCapacity(offer, pathSteps.length, maxSteps) &&
+                        maxSteps >= PATH_STEPS_HARD_MAX)
+                    }
+                    onClick={() => handleGapFillClick(offer)}
+                    title={
+                      isGapOfferBlockedByPathCapacity(offer, pathSteps.length, maxSteps)
+                        ? maxSteps >= PATH_STEPS_HARD_MAX
+                          ? `Maximal ${PATH_STEPS_HARD_MAX} Schritte — zuerst einen Schritt entfernen.`
+                          : 'Pfad voll — Klick fragt, ob die Pfadlänge vergrößert werden soll'
+                        : offer.replace_step_index != null
+                          ? 'Ersetzt den themenfremden Schritt im Pfad'
+                          : 'Kontext prüfen, Ergänzungen mitgeben, dann KI-Entwurf'
+                    }
+                  >
+                    {generatingOfferId === offer.offer_id
+                      ? 'KI erstellt Entwurf …'
+                      : 'Vorbereiten & KI anlegen'}
+                  </button>
+                </div>
+              </div>
+            ))}
+          </div>
+        </div>
+          ) : (
+            <p
+              style={{
+                fontSize: '12px',
+                color: 'var(--accent-dark)',
+                margin: '0 0 14px',
+                padding: '8px 10px',
+                borderRadius: '8px',
+                background: 'color-mix(in srgb, var(--accent) 8%, var(--surface))',
+              }}
+            >
+              Keine offenen Lücken — Pfad kann direkt gespeichert werden.
+            </p>
+          )}
+
+          <details style={{ marginBottom: '12px', fontSize: '12px' }}>
+            <summary style={{ cursor: 'pointer', fontWeight: 600, color: 'var(--accent-dark)' }}>
+              Pfad-Übersicht ({pathSteps.length} Schritte)
+            </summary>
+            <ol style={{ margin: '10px 0 0', paddingLeft: '20px', lineHeight: 1.5 }}>
+              {pathSteps.map((step, idx) => (
+                <li key={`summary-${idx}`} style={{ marginBottom: '4px' }}>
+                  <strong>{step.exerciseTitle}</strong>
+                  {step.roadmapPhase ? ` (${step.roadmapPhase})` : ''}
+                  {step.isAiProposal ? ' — KI-Vorschlag, noch anlegen' : ''}
+                </li>
+              ))}
+            </ol>
+          </details>
+
           <div className="form-row">
             <label className="form-label">Notiz für Kanten (Fallback, optional)</label>
             <textarea
@@ -1759,7 +2019,15 @@ export default function ExerciseProgressionPathBuilder({
               placeholder="Wird pro Kante genutzt, wenn keine KI-Begründung vorliegt."
             />
           </div>
-          <div style={{ display: 'flex', flexWrap: 'wrap', gap: '8px' }}>
+          <div style={{ display: 'flex', flexWrap: 'wrap', gap: '8px', marginTop: '10px' }}>
+            <button
+              type="button"
+              className="btn btn-secondary"
+              onClick={() => setWizardStep(3)}
+              disabled={disabled || loading || saving}
+            >
+              ← Match anpassen
+            </button>
             <button
               type="button"
               className="btn btn-primary"
@@ -1778,14 +2046,16 @@ export default function ExerciseProgressionPathBuilder({
                 setSemanticBrief(null)
                 setPathQa(null)
                 setGapFillOffers([])
-                setProgressionRoadmap(null)
                 setPathSkillExpectations(null)
+                setWizardStep(editableMajorSteps.length >= 2 ? 2 : 1)
               }}
             >
               Vorschlag verwerfen
             </button>
           </div>
-        </>
+            </>
+          )}
+        </section>
       ) : null}
 
       <ExerciseGapFillPrepModal

From 3be7606d90d3f0af80e95fa16a1e1dca3446694f Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Wed, 10 Jun 2026 07:50:29 +0200
Subject: [PATCH 06/33] 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.
---
 .../PLANNING_EXERCISE_SUGGEST_CONTEXT.md      |  24 +-
 .../PLANNING_PROGRESSION_ROADMAP_SPEC.md      |  25 +-
 CLAUDE.md                                     |   2 +-
 backend/version.py                            |  44 ++-
 docs/HANDOVER.md                              |  47 +--
 docs/architecture/PLANNING_KI_ROADMAP.md      |  46 ++-
 .../PLANNING_PROGRESSION_GRAPH_KI.md          | 314 ++++++++++++++++++
 docs/architecture/README.md                   |   3 +-
 8 files changed, 462 insertions(+), 43 deletions(-)
 create mode 100644 docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md

diff --git a/.claude/docs/working/PLANNING_EXERCISE_SUGGEST_CONTEXT.md b/.claude/docs/working/PLANNING_EXERCISE_SUGGEST_CONTEXT.md
index bbce56c..a8c1ccd 100644
--- 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)
diff --git a/.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md b/.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md
index 6e0eadb..b6d7307 100644
--- 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.
diff --git a/CLAUDE.md b/CLAUDE.md
index f8d36f2..03e9f8a 100644
--- 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
 
diff --git a/backend/version.py b/backend/version.py
index 742ae6b..d3ab790 100644
--- 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",
diff --git a/docs/HANDOVER.md b/docs/HANDOVER.md
index 869ba42..06e5daf 100644
--- 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**)
 
diff --git a/docs/architecture/PLANNING_KI_ROADMAP.md b/docs/architecture/PLANNING_KI_ROADMAP.md
index 8f0cda3..ee16d23 100644
--- 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`.
diff --git a/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md b/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md
new file mode 100644
index 0000000..246493a
--- /dev/null
+++ 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 |
diff --git a/docs/architecture/README.md b/docs/architecture/README.md
index 40061f6..a3a4c40 100644
--- 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)

From 800189ff8f614135e95ac8b11153a5375c9ccc6e Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Wed, 10 Jun 2026 07:55:51 +0200
Subject: [PATCH 07/33] Enhance Exercise Progression Graph Panel and Path
 Builder with New Features

- Added `ProgressionChainEditor` to the Exercise Progression Graph Panel for improved management of exercise chains.
- Refactored state management to utilize `useRef` for chain editor references and removed unused sequence step logic.
- Introduced a path insert notice in the Exercise Progression Path Builder to inform users about unsaved changes.
- Updated UI elements to enhance clarity regarding the status of paths before saving.
- Incremented application version to reflect these updates.
---
 .../ExerciseProgressionGraphPanel.jsx         | 440 ++++-----------
 .../ExerciseProgressionPathBuilder.jsx        |  55 +-
 .../src/components/ProgressionChainEditor.jsx | 508 ++++++++++++++++++
 3 files changed, 657 insertions(+), 346 deletions(-)
 create mode 100644 frontend/src/components/ProgressionChainEditor.jsx

diff --git a/frontend/src/components/ExerciseProgressionGraphPanel.jsx b/frontend/src/components/ExerciseProgressionGraphPanel.jsx
index cd92620..a124300 100644
--- a/frontend/src/components/ExerciseProgressionGraphPanel.jsx
+++ b/frontend/src/components/ExerciseProgressionGraphPanel.jsx
@@ -2,7 +2,7 @@
  * Progressionsgraphen: Sequenz-Editor (mehrere Nachfolger auf einmal), Ketten-Ansicht,
  * Varianten als eigene Knoten-Endpunkte, Schwester-Kanten gesondert, Tabelle als Fallback.
  */
-import React, { useCallback, useEffect, useMemo, useState } from 'react'
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { Link } from 'react-router-dom'
 import api from '../utils/api'
 import SkillProfilePanel from './skills/SkillProfilePanel'
@@ -10,6 +10,7 @@ import { useAuth } from '../context/AuthContext'
 import { getTenantClubDependencyKey } from '../utils/activeClub'
 import ExercisePickerModal from './ExercisePickerModal'
 import ExerciseProgressionPathBuilder from './ExerciseProgressionPathBuilder'
+import ProgressionChainEditor from './ProgressionChainEditor'
 import { EXERCISE_VISIBILITY_FIELD_LABEL } from '../constants/exerciseGovernanceLabels'
 
 const VIS_OPTIONS = [
@@ -92,10 +93,6 @@ function maximalLinearChains(nextEdges) {
   return chains
 }
 
-function emptySeqStep() {
-  return { exerciseId: null, exerciseTitle: '', variantId: null, variants: [] }
-}
-
 function emptyEndpoint() {
   return { exerciseId: null, exerciseTitle: '', variantId: null, variants: [] }
 }
@@ -126,9 +123,8 @@ export default function ExerciseProgressionGraphPanel({
   const [metaDescription, setMetaDescription] = useState('')
   const [metaVisibility, setMetaVisibility] = useState('private')
 
-  const [sequenceSteps, setSequenceSteps] = useState([emptySeqStep(), emptySeqStep()])
-  const [sequenceBulkNotes, setSequenceBulkNotes] = useState('')
   const [pickContext, setPickContext] = useState(null)
+  const chainEditorRef = useRef(null)
 
   const [relationKind, setRelationKind] = useState('progression')
   const [firstEp, setFirstEp] = useState(emptyEndpoint)
@@ -138,7 +134,6 @@ export default function ExerciseProgressionGraphPanel({
   const [filterAnchorOnly, setFilterAnchorOnly] = useState(!!anchorExerciseId)
   const [editingEdgeNotes, setEditingEdgeNotes] = useState(null)
   const [notesDraft, setNotesDraft] = useState('')
-  const [uiTab, setUiTab] = useState('overview')
   const [skillProfileData, setSkillProfileData] = useState(null)
   const [skillProfileLoading, setSkillProfileLoading] = useState(false)
   const [skillProfileError, setSkillProfileError] = useState('')
@@ -343,81 +338,6 @@ export default function ExerciseProgressionGraphPanel({
     }
   }
 
-  const patchSeqStep = (idx, patch) => {
-    setSequenceSteps((prev) => prev.map((s, i) => (i === idx ? { ...s, ...patch } : s)))
-  }
-
-  const addSeqStep = () => setSequenceSteps((prev) => [...prev, emptySeqStep()])
-
-  const removeSeqStep = (idx) => {
-    setSequenceSteps((prev) => {
-      if (prev.length <= 2) return prev
-      return prev.filter((_, i) => i !== idx)
-    })
-  }
-
-  const moveSeqStep = (idx, dir) => {
-    setSequenceSteps((prev) => {
-      const j = idx + dir
-      if (j < 0 || j >= prev.length) return prev
-      const next = [...prev]
-      const t = next[idx]
-      next[idx] = next[j]
-      next[j] = t
-      return next
-    })
-  }
-
-  const submitSequence = async () => {
-    if (!selectedGraphId) {
-      alert('Zuerst einen Graphen wählen.')
-      return
-    }
-    const steps = sequenceSteps.filter((s) => s.exerciseId != null)
-    if (steps.length < 2) {
-      alert('Mindestens zwei Schritte mit gewählter Übung.')
-      return
-    }
-    const n = steps.length - 1
-    const noteRaw = sequenceBulkNotes.trim()
-    const segment_notes = Array.from({ length: n }, () => (noteRaw ? noteRaw : null))
-
-    setBusy(true)
-    try {
-      await api.createExerciseProgressionSequence(selectedGraphId, {
-        steps: steps.map((s) => ({
-          exercise_id: s.exerciseId,
-          variant_id: s.variantId || null,
-        })),
-        segment_notes,
-      })
-      setSequenceBulkNotes('')
-      await refreshEdges(selectedGraphId)
-      alert(`${n} Nachfolger-Kante(n) angelegt.`)
-    } catch (err) {
-      alert(err.message || String(err))
-    } finally {
-      setBusy(false)
-    }
-  }
-
-  const deleteChain = async (edgeObjs) => {
-    if (!selectedGraphId || !edgeObjs?.length) return
-    if (!confirm(`${edgeObjs.length} Kante(n) dieser Reihe löschen?`)) return
-    setBusy(true)
-    try {
-      await api.deleteExerciseProgressionEdgesBatch(
-        selectedGraphId,
-        edgeObjs.map((e) => e.id),
-      )
-      await refreshEdges(selectedGraphId)
-    } catch (err) {
-      alert(err.message || String(err))
-    } finally {
-      setBusy(false)
-    }
-  }
-
   const handleAddEdge = async () => {
     if (!selectedGraphId) {
       alert('Zuerst einen Graphen wählen.')
@@ -507,13 +427,16 @@ export default function ExerciseProgressionGraphPanel({
     const variantId =
       ex.exercise_variant_id ?? ex.suggested_variant_id ?? null
 
-    if (pickContext?.kind === 'sequence') {
-      patchSeqStep(pickContext.index, {
-        exerciseId: ex.id,
-        exerciseTitle: title,
-        variantId: variantId != null ? Number(variantId) : null,
-        variants,
-      })
+    if (pickContext?.kind === 'chain') {
+      await chainEditorRef.current?.applyExercise(
+        pickContext.draftKey,
+        pickContext.nodeIndex,
+        {
+          ...ex,
+          variants,
+          exercise_variant_id: variantId,
+        },
+      )
       setPickContext(null)
       return
     }
@@ -555,10 +478,9 @@ export default function ExerciseProgressionGraphPanel({
       )}
 
       <p style={{ fontSize: '13px', color: 'var(--text2)', marginBottom: '16px' }}>
-        Pro Graph mehrere <strong>Reihen</strong> und <strong>Alternativen</strong>: eine{' '}
-        <strong>Sequenz</strong> legt automatisch alle Schritte Übung1 → Übung2 → … als Nachfolger-Kanten an.
-        Optional pro Schritt eine <strong>Variante</strong> — sie wirkt wie ein eigener Knoten. Verzweigungen und
-        Schwestern trennst du weiterhin mit Einzelkanten oder mehreren Sequenzen aus dem gleichen Knoten.
+        Ein Graph enthält eine oder mehrere <strong>Reihen</strong> (lineare Pfade Übung → Übung) sowie optional{' '}
+        <strong>Schwester-Alternativen</strong>. Reihen bearbeiten Sie direkt in der Liste; mit dem KI-Planer legen
+        Sie neue Pfade in vier Schritten an.
       </p>
 
       {loadErr && (
@@ -631,236 +553,30 @@ export default function ExerciseProgressionGraphPanel({
         </form>
       </div>
 
-      {selectedGraphId && (
-        <div className="card" style={{ marginBottom: '12px' }}>
-          <h3 style={{ marginTop: 0, fontSize: '1rem' }}>Graph bearbeiten</h3>
-          <div className="form-row">
-            <label className="form-label">Name</label>
-            <input className="form-input" value={metaName} onChange={(e) => setMetaName(e.target.value)} />
-          </div>
-          <div className="form-row">
-            <label className="form-label">Beschreibung</label>
-            <textarea
-              className="form-input"
-              rows={2}
-              value={metaDescription}
-              onChange={(e) => setMetaDescription(e.target.value)}
-            />
-          </div>
-          <div className="form-row">
-            <label className="form-label">{EXERCISE_VISIBILITY_FIELD_LABEL}</label>
-            <select className="form-input" value={metaVisibility} onChange={(e) => setMetaVisibility(e.target.value)}>
-              {filteredGraphVisOptions.map((o) => (
-                <option key={o.value} value={o.value}>
-                  {o.label}
-                </option>
-              ))}
-            </select>
-          </div>
-          <button type="button" className="btn btn-secondary" disabled={busy} onClick={handleSaveMeta}>
-            Metadaten speichern
-          </button>
-        </div>
+      {selectedGraphId && anchorExerciseId != null && (
+        <label style={{ display: 'flex', alignItems: 'center', gap: '8px', marginBottom: '12px', fontSize: '13px' }}>
+          <input
+            type="checkbox"
+            checked={filterAnchorOnly}
+            onChange={(e) => setFilterAnchorOnly(e.target.checked)}
+          />
+          Nur Reihen und Kanten, die diese Übung betreffen
+        </label>
       )}
 
       {selectedGraphId && (
-        <div
-          role="tablist"
-          style={{ display: 'flex', gap: '8px', marginBottom: '12px', flexWrap: 'wrap' }}
-          aria-label="Darstellung"
-        >
-          <button
-            type="button"
-            className={uiTab === 'overview' ? 'btn btn-primary' : 'btn btn-secondary'}
-            onClick={() => setUiTab('overview')}
-          >
-            Übersicht & Sequenz
-          </button>
-          <button
-            type="button"
-            className={uiTab === 'table' ? 'btn btn-primary' : 'btn btn-secondary'}
-            onClick={() => setUiTab('table')}
-          >
-            Alle Kanten (Tabelle)
-          </button>
-        </div>
-      )}
-
-      {selectedGraphId && uiTab === 'overview' && (
         <>
-          <SkillProfilePanel
-            title="Fähigkeiten entlang des Pfads"
-            hint="Alle Übungen als Knoten im Graph (Standardgewicht pro Übung; Intensität und Stufen aus der Übungsverknüpfung)."
-            profile={skillProfileData?.overall}
-            loading={skillProfileLoading}
-            error={skillProfileError}
-            defaultExpanded
-            artifactType="progression_graph"
-          />
-          <ExerciseProgressionPathBuilder
+          <ProgressionChainEditor
+            ref={chainEditorRef}
             graphId={selectedGraphId}
-            disabled={busy}
-            onSaved={async () => {
-              await refreshEdges(selectedGraphId)
-            }}
+            chains={flowChains}
+            busy={busy}
+            anchorExerciseId={anchorExerciseId}
+            anchorTitle={anchorTitle}
+            onRefresh={async () => refreshEdges(selectedGraphId)}
+            onPickExercise={setPickContext}
+            loadVariantsForExercise={loadVariantsForExercise}
           />
-          <div className="card" style={{ marginBottom: '12px' }}>
-            <h3 style={{ marginTop: 0, fontSize: '1rem' }}>Sequenz / Reihe anlegen</h3>
-            <p style={{ fontSize: '12px', color: 'var(--text3)', marginTop: 0 }}>
-              Reihenfolge von links nach rechts: jede Zeile ein Schritt. Es werden automatisch alle Nachfolger-Kanten
-              zwischen benachbarten Schritten erzeugt (ein API-Vorgang).
-            </p>
-            {sequenceSteps.map((step, idx) => (
-              <div
-                key={idx}
-                style={{
-                  display: 'grid',
-                  gridTemplateColumns: 'repeat(auto-fit, minmax(200px, 1fr))',
-                  gap: '10px',
-                  alignItems: 'end',
-                  marginBottom: '12px',
-                  paddingBottom: '12px',
-                  borderBottom: idx < sequenceSteps.length - 1 ? '1px dashed var(--border)' : 'none',
-                }}
-              >
-                <div className="form-row" style={{ marginBottom: 0 }}>
-                  <label className="form-label">Schritt {idx + 1}</label>
-                  <div style={{ display: 'flex', flexWrap: 'wrap', gap: '8px', alignItems: 'center' }}>
-                    <span style={{ fontSize: '13px', flex: '1 1 140px' }}>
-                      {step.exerciseId ? (
-                        <>
-                          <strong>{step.exerciseTitle}</strong>
-                          <span style={{ color: 'var(--text3)' }}> (#{step.exerciseId})</span>
-                        </>
-                      ) : (
-                        <span style={{ color: 'var(--text3)' }}>Übung wählen</span>
-                      )}
-                    </span>
-                    <button
-                      type="button"
-                      className="btn btn-secondary"
-                      style={{ fontSize: '12px', padding: '4px 10px' }}
-                      onClick={() => setPickContext({ kind: 'sequence', index: idx })}
-                    >
-                      Übung…
-                    </button>
-                    {anchorExerciseId != null && (
-                      <button
-                        type="button"
-                        className="btn"
-                        style={{ fontSize: '12px', padding: '4px 10px' }}
-                        onClick={async () => {
-                          const variants = await loadVariantsForExercise(anchorExerciseId)
-                          patchSeqStep(idx, {
-                            exerciseId: anchorExerciseId,
-                            exerciseTitle: anchorTitle?.trim() || `Übung #${anchorExerciseId}`,
-                            variantId: null,
-                            variants,
-                          })
-                        }}
-                      >
-                        Diese Übung
-                      </button>
-                    )}
-                  </div>
-                </div>
-                <div className="form-row" style={{ marginBottom: 0 }}>
-                  <label className="form-label">Variante (optional)</label>
-                  <select
-                    className="form-input"
-                    disabled={!step.exerciseId}
-                    value={step.variantId ?? ''}
-                    onChange={(e) =>
-                      patchSeqStep(idx, {
-                        variantId: e.target.value === '' ? null : parseInt(e.target.value, 10),
-                      })
-                    }
-                  >
-                    <option value="">Gesamte Übung (ohne feste Variante)</option>
-                    {(step.variants || []).map((v) => (
-                      <option key={v.id} value={v.id}>
-                        {v.variant_name || `Variante #${v.id}`}
-                      </option>
-                    ))}
-                  </select>
-                </div>
-                <div style={{ display: 'flex', gap: '6px', flexWrap: 'wrap' }}>
-                  <button type="button" className="btn" style={{ fontSize: '12px', padding: '4px 8px' }} onClick={() => moveSeqStep(idx, -1)}>
-                    ↑
-                  </button>
-                  <button type="button" className="btn" style={{ fontSize: '12px', padding: '4px 8px' }} onClick={() => moveSeqStep(idx, 1)}>
-                    ↓
-                  </button>
-                  <button type="button" className="btn" style={{ fontSize: '12px', padding: '4px 8px' }} onClick={() => removeSeqStep(idx)}>
-                    Zeile entfernen
-                  </button>
-                </div>
-              </div>
-            ))}
-            <button type="button" className="btn btn-secondary" style={{ marginBottom: '12px' }} onClick={addSeqStep}>
-              + Schritt
-            </button>
-            <div className="form-row">
-              <label className="form-label">Entwicklungsziel für alle neuen Zwischen-Kanten (optional)</label>
-              <textarea
-                className="form-input"
-                rows={2}
-                value={sequenceBulkNotes}
-                onChange={(e) => setSequenceBulkNotes(e.target.value)}
-                placeholder="wird auf jedes neue Segment der Sequenz kopiert"
-              />
-            </div>
-            <button type="button" className="btn btn-primary" disabled={busy} onClick={submitSequence}>
-              Sequenz als Nachfolger-Kanten speichern
-            </button>
-          </div>
-
-          <div className="card" style={{ marginBottom: '12px' }}>
-            <h3 style={{ marginTop: 0, fontSize: '1rem' }}>Nachfolger als Reihen (Lesart)</h3>
-            {flowChains.length === 0 ? (
-              <p style={{ color: 'var(--text2)', margin: 0 }}>Keine Nachfolger-Kanten im aktuellen Filter.</p>
-            ) : (
-              flowChains.map((chain, ci) => (
-                <div
-                  key={ci}
-                  style={{
-                    marginBottom: '14px',
-                    padding: '12px',
-                    borderRadius: '10px',
-                    border: '1px solid var(--border)',
-                    background: 'var(--surface2)',
-                  }}
-                >
-                  <div
-                    style={{
-                      display: 'flex',
-                      flexWrap: 'wrap',
-                      alignItems: 'center',
-                      gap: '6px 10px',
-                      fontSize: '13px',
-                      lineHeight: 1.5,
-                    }}
-                  >
-                    {chain.nodes.map((n, ni) => (
-                      <React.Fragment key={`${n.exercise_id}-${n.variant_id}-${ni}`}>
-                        {ni > 0 && (
-                          <span style={{ color: 'var(--accent)', fontWeight: 700 }} aria-hidden>
-                            →
-                          </span>
-                        )}
-                        <span style={{ fontWeight: 600 }}>{formatNodeLine(n)}</span>
-                      </React.Fragment>
-                    ))}
-                  </div>
-                  <div style={{ marginTop: '10px', display: 'flex', gap: '8px', flexWrap: 'wrap' }}>
-                    <button type="button" className="btn btn-secondary" disabled={busy} onClick={() => deleteChain(chain.edges)}>
-                      Diese Reihe löschen ({chain.edges.length} Kante(n))
-                    </button>
-                  </div>
-                </div>
-              ))
-            )}
-          </div>
 
           <div className="card" style={{ marginBottom: '12px' }}>
             <h3 style={{ marginTop: 0, fontSize: '1rem' }}>Schwestern & Alternativen</h3>
@@ -919,6 +635,65 @@ export default function ExerciseProgressionGraphPanel({
             )}
           </div>
 
+          <details className="card" style={{ marginBottom: '12px' }}>
+            <summary style={{ cursor: 'pointer', fontWeight: 600 }}>Graph-Einstellungen (Name, Sichtbarkeit)</summary>
+            <div style={{ marginTop: '14px' }}>
+              <div className="form-row">
+                <label className="form-label">Name</label>
+                <input className="form-input" value={metaName} onChange={(e) => setMetaName(e.target.value)} />
+              </div>
+              <div className="form-row">
+                <label className="form-label">Beschreibung</label>
+                <textarea
+                  className="form-input"
+                  rows={2}
+                  value={metaDescription}
+                  onChange={(e) => setMetaDescription(e.target.value)}
+                />
+              </div>
+              <div className="form-row">
+                <label className="form-label">{EXERCISE_VISIBILITY_FIELD_LABEL}</label>
+                <select
+                  className="form-input"
+                  value={metaVisibility}
+                  onChange={(e) => setMetaVisibility(e.target.value)}
+                >
+                  {filteredGraphVisOptions.map((o) => (
+                    <option key={o.value} value={o.value}>
+                      {o.label}
+                    </option>
+                  ))}
+                </select>
+              </div>
+              <button type="button" className="btn btn-secondary" disabled={busy} onClick={handleSaveMeta}>
+                Metadaten speichern
+              </button>
+            </div>
+          </details>
+
+          <details className="card" style={{ marginBottom: '12px' }}>
+            <summary style={{ cursor: 'pointer', fontWeight: 600 }}>KI: Neuen Pfad planen (4 Schritte)</summary>
+            <div style={{ marginTop: '14px' }}>
+              <ExerciseProgressionPathBuilder
+                graphId={selectedGraphId}
+                disabled={busy}
+                onSaved={async () => {
+                  await refreshEdges(selectedGraphId)
+                }}
+              />
+            </div>
+          </details>
+
+          <SkillProfilePanel
+            title="Fähigkeiten entlang des Pfads"
+            hint="Alle Übungen als Knoten im Graph (Standardgewicht pro Übung; Intensität und Stufen aus der Übungsverknüpfung)."
+            profile={skillProfileData?.overall}
+            loading={skillProfileLoading}
+            error={skillProfileError}
+            defaultExpanded={false}
+            artifactType="progression_graph"
+          />
+
           <details className="card" style={{ marginBottom: '12px' }}>
             <summary style={{ cursor: 'pointer', fontWeight: 600 }}>Einzelkante (Nachfolger oder Schwester)</summary>
             <div style={{ marginTop: '14px' }}>
@@ -1010,26 +785,13 @@ export default function ExerciseProgressionGraphPanel({
               </button>
             </div>
           </details>
-        </>
-      )}
 
-      {selectedGraphId && anchorExerciseId != null && (
-        <label style={{ display: 'flex', alignItems: 'center', gap: '8px', marginBottom: '12px', fontSize: '13px' }}>
-          <input
-            type="checkbox"
-            checked={filterAnchorOnly}
-            onChange={(e) => setFilterAnchorOnly(e.target.checked)}
-          />
-          Nur Kanten, die diese Übung betreffen (Übersicht &amp; Tabelle)
-        </label>
-      )}
-
-      {selectedGraphId && uiTab === 'table' && (
-        <div className="card">
-          <h3 style={{ marginTop: 0, fontSize: '1rem' }}>
-            Alle Kanten ({filteredEdges.length}
-            {edges.length !== filteredEdges.length ? ` von ${edges.length}` : ''})
-          </h3>
+          <details className="card" style={{ marginBottom: '12px' }}>
+            <summary style={{ cursor: 'pointer', fontWeight: 600 }}>
+              Technische Kantenliste ({filteredEdges.length}
+              {edges.length !== filteredEdges.length ? ` von ${edges.length}` : ''})
+            </summary>
+            <div style={{ marginTop: '14px' }}>
           {filteredEdges.length === 0 ? (
             <p style={{ color: 'var(--text2)', margin: 0 }}>Keine Kanten.</p>
           ) : (
@@ -1111,7 +873,9 @@ export default function ExerciseProgressionGraphPanel({
               </table>
             </div>
           )}
-        </div>
+            </div>
+          </details>
+        </>
       )}
 
       <ExercisePickerModal
diff --git a/frontend/src/components/ExerciseProgressionPathBuilder.jsx b/frontend/src/components/ExerciseProgressionPathBuilder.jsx
index b6a2deb..23e6982 100644
--- a/frontend/src/components/ExerciseProgressionPathBuilder.jsx
+++ b/frontend/src/components/ExerciseProgressionPathBuilder.jsx
@@ -443,6 +443,7 @@ export default function ExerciseProgressionPathBuilder({
   const [gapPrepError, setGapPrepError] = useState('')
   const [loadedPlanningHint, setLoadedPlanningHint] = useState(false)
   const [wizardStep, setWizardStep] = useState(1)
+  const [pathInsertNotice, setPathInsertNotice] = useState('')
 
   const maxReachableStep = useMemo(
     () => computeMaxReachableStep(editableMajorSteps, pathSteps),
@@ -498,6 +499,7 @@ export default function ExerciseProgressionPathBuilder({
     setStartTargetAnalyzed(false)
     setError('')
     setWizardStep(1)
+    setPathInsertNotice('')
 
     api
       .getExerciseProgressionGraph(Number(graphId))
@@ -883,6 +885,11 @@ export default function ExerciseProgressionPathBuilder({
       insertExerciseFromOffer(created, activeOffer)
       setQuickCreateDraft(null)
       setActiveOffer(null)
+      const title = (created.title || quickTitle || 'Übung').trim()
+      setPathInsertNotice(
+        `„${title}" wurde in den KI-Pfad eingefügt. Speichern Sie jetzt mit «Pfad in Graph speichern» — die Reihe erscheint dann oben unter «Reihen im Graph».`,
+      )
+      setWizardStep(4)
     } catch (e) {
       console.error(e)
       const msg = e?.message || String(e)
@@ -1137,6 +1144,7 @@ export default function ExerciseProgressionPathBuilder({
       setEditableMajorSteps([])
       setRoadmapDirty(false)
       setWizardStep(1)
+      setPathInsertNotice('')
       if (typeof onSaved === 'function') await onSaved()
       const msg =
         skippedAi > 0
@@ -1902,6 +1910,23 @@ export default function ExerciseProgressionPathBuilder({
             </p>
           ) : (
             <>
+          <div
+            style={{
+              marginBottom: '14px',
+              padding: '10px 12px',
+              borderRadius: '8px',
+              border: '1px solid color-mix(in srgb, var(--accent) 45%, var(--border))',
+              background: 'color-mix(in srgb, var(--accent) 10%, var(--surface))',
+              fontSize: '12px',
+              lineHeight: 1.5,
+              color: 'var(--accent-dark)',
+            }}
+          >
+            <strong>Wichtig:</strong> Der KI-Pfad ist noch nicht im Graph gespeichert. KI-Übungen werden erst nach
+            «Pfad in Graph speichern» als neue Reihe oben sichtbar.
+            {pathInsertNotice ? <p style={{ margin: '8px 0 0' }}>{pathInsertNotice}</p> : null}
+          </div>
+
           {gapFillOffers.length > 0 ? (
         <div
           style={{
@@ -1994,20 +2019,33 @@ export default function ExerciseProgressionPathBuilder({
             </p>
           )}
 
-          <details style={{ marginBottom: '12px', fontSize: '12px' }}>
-            <summary style={{ cursor: 'pointer', fontWeight: 600, color: 'var(--accent-dark)' }}>
-              Pfad-Übersicht ({pathSteps.length} Schritte)
-            </summary>
-            <ol style={{ margin: '10px 0 0', paddingLeft: '20px', lineHeight: 1.5 }}>
+          <div
+            style={{
+              marginBottom: '12px',
+              padding: '10px 12px',
+              borderRadius: '8px',
+              border: '1px solid var(--border)',
+              background: 'var(--surface2)',
+              fontSize: '12px',
+            }}
+          >
+            <strong style={{ display: 'block', marginBottom: '8px' }}>
+              Pfad vor dem Speichern ({pathSteps.length} Schritte)
+            </strong>
+            <ol style={{ margin: 0, paddingLeft: '20px', lineHeight: 1.55 }}>
               {pathSteps.map((step, idx) => (
                 <li key={`summary-${idx}`} style={{ marginBottom: '4px' }}>
                   <strong>{step.exerciseTitle}</strong>
-                  {step.roadmapPhase ? ` (${step.roadmapPhase})` : ''}
-                  {step.isAiProposal ? ' — KI-Vorschlag, noch anlegen' : ''}
+                  {step.exerciseId ? (
+                    <span style={{ color: 'var(--text3)' }}> (#{step.exerciseId})</span>
+                  ) : (
+                    <span style={{ color: 'var(--danger)' }}> — noch nicht angelegt</span>
+                  )}
+                  {step.roadmapPhase ? ` · ${step.roadmapPhase}` : ''}
                 </li>
               ))}
             </ol>
-          </details>
+          </div>
 
           <div className="form-row">
             <label className="form-label">Notiz für Kanten (Fallback, optional)</label>
@@ -2047,6 +2085,7 @@ export default function ExerciseProgressionPathBuilder({
                 setPathQa(null)
                 setGapFillOffers([])
                 setPathSkillExpectations(null)
+                setPathInsertNotice('')
                 setWizardStep(editableMajorSteps.length >= 2 ? 2 : 1)
               }}
             >
diff --git a/frontend/src/components/ProgressionChainEditor.jsx b/frontend/src/components/ProgressionChainEditor.jsx
new file mode 100644
index 0000000..21fc0a3
--- /dev/null
+++ b/frontend/src/components/ProgressionChainEditor.jsx
@@ -0,0 +1,508 @@
+/**
+ * Bearbeitbare Darstellung linearer Progressions-Reihen im Graphen.
+ */
+import React, { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useState } from 'react'
+import { Link } from 'react-router-dom'
+import api from '../utils/api'
+
+function emptyNode() {
+  return {
+    exerciseId: null,
+    exerciseTitle: '',
+    variantId: null,
+    variantName: null,
+    variants: [],
+  }
+}
+
+function chainToDraft(chain) {
+  return {
+    key: `chain-${chain.edges[0]?.id ?? 'x'}`,
+    edgeIds: chain.edges.map((e) => e.id),
+    segmentNotes: chain.edges.map((e) => e.notes || ''),
+    nodes: chain.nodes.map((n) => ({
+      exerciseId: n.exercise_id,
+      exerciseTitle: n.title || `Übung #${n.exercise_id}`,
+      variantId: n.variant_id ?? null,
+      variantName: n.variant_name ?? null,
+      variants: [],
+    })),
+    dirty: false,
+    isNew: false,
+  }
+}
+
+function newChainDraft() {
+  const key = `new-${Date.now()}`
+  return {
+    key,
+    edgeIds: [],
+    segmentNotes: [],
+    nodes: [emptyNode(), emptyNode()],
+    dirty: true,
+    isNew: true,
+  }
+}
+
+function formatNodeLabel(node) {
+  if (!node.exerciseId) return '— Übung wählen —'
+  return (
+    <>
+      <Link to={`/exercises/${node.exerciseId}`}>{node.exerciseTitle}</Link>
+      {node.variantName ? (
+        <span style={{ color: 'var(--text3)', fontWeight: 400 }}>{` · ${node.variantName}`}</span>
+      ) : null}
+    </>
+  )
+}
+
+const ProgressionChainEditor = forwardRef(function ProgressionChainEditor(
+  {
+    graphId,
+    chains = [],
+    busy = false,
+    anchorExerciseId = null,
+    anchorTitle = null,
+    onRefresh,
+    onPickExercise,
+    loadVariantsForExercise,
+  },
+  ref,
+) {
+  const [drafts, setDrafts] = useState([])
+  const [savingKey, setSavingKey] = useState(null)
+
+  const chainSignature = useMemo(
+    () =>
+      chains
+        .map((c) => c.edges.map((e) => e.id).join(','))
+        .join('|'),
+    [chains],
+  )
+
+  useEffect(() => {
+    setDrafts(chains.map(chainToDraft))
+  }, [chainSignature, chains])
+
+  const patchDraft = useCallback((key, patchFn) => {
+    setDrafts((prev) =>
+      prev.map((d) => {
+        if (d.key !== key) return d
+        const next = patchFn(d)
+        return { ...next, dirty: true }
+      }),
+    )
+  }, [])
+
+  const moveNode = (key, idx, dir) => {
+    patchDraft(key, (d) => {
+      const j = idx + dir
+      if (j < 0 || j >= d.nodes.length) return d
+      const nodes = [...d.nodes]
+      const t = nodes[idx]
+      nodes[idx] = nodes[j]
+      nodes[j] = t
+      return { ...d, nodes }
+    })
+  }
+
+  const removeNode = (key, idx) => {
+    patchDraft(key, (d) => {
+      if (d.nodes.length <= 2) return d
+      const nodes = d.nodes.filter((_, i) => i !== idx)
+      const segmentNotes = d.segmentNotes.slice(0, Math.max(0, nodes.length - 1))
+      return { ...d, nodes, segmentNotes }
+    })
+  }
+
+  const setVariant = (key, idx, variantId) => {
+    patchDraft(key, (d) => ({
+      ...d,
+      nodes: d.nodes.map((n, i) => {
+        if (i !== idx) return n
+        const v = (n.variants || []).find((x) => Number(x.id) === Number(variantId))
+        return {
+          ...n,
+          variantId: variantId === '' || variantId == null ? null : Number(variantId),
+          variantName: v?.variant_name || null,
+        }
+      }),
+    }))
+  }
+
+  const applyExerciseToNode = useCallback(async (key, idx, ex) => {
+    const title = ex.title || `Übung #${ex.id}`
+    const variants =
+      Array.isArray(ex.variants) && ex.variants.length
+        ? ex.variants
+        : await loadVariantsForExercise(ex.id)
+    const variantId = ex.exercise_variant_id ?? ex.suggested_variant_id ?? null
+    patchDraft(key, (d) => ({
+      ...d,
+      nodes: d.nodes.map((n, i) =>
+        i === idx
+          ? {
+              exerciseId: ex.id,
+              exerciseTitle: title,
+              variantId: variantId != null ? Number(variantId) : null,
+              variantName:
+                variantId != null
+                  ? variants.find((v) => Number(v.id) === Number(variantId))?.variant_name || null
+                  : null,
+              variants,
+            }
+          : n,
+      ),
+    }))
+  }, [patchDraft, loadVariantsForExercise])
+
+  const insertNodeAfter = (key, idx) => {
+    patchDraft(key, (d) => {
+      const nodes = [...d.nodes]
+      nodes.splice(idx + 1, 0, emptyNode())
+      return { ...d, nodes }
+    })
+    onPickExercise({ kind: 'chain', draftKey: key, nodeIndex: idx + 1 })
+  }
+
+  const addNewChain = () => {
+    setDrafts((prev) => [...prev, newChainDraft()])
+  }
+
+  const discardDraft = (key) => {
+    setDrafts((prev) => {
+      const draft = prev.find((d) => d.key === key)
+      if (!draft) return prev
+      if (draft.isNew) return prev.filter((d) => d.key !== key)
+      const original = chains.find((c) => `chain-${c.edges[0]?.id}` === key)
+      if (!original) return prev.filter((d) => d.key !== key)
+      return prev.map((d) => (d.key === key ? chainToDraft(original) : d))
+    })
+  }
+
+  const deleteChain = async (draft) => {
+    if (!graphId) return
+    if (draft.isNew) {
+      setDrafts((prev) => prev.filter((d) => d.key !== draft.key))
+      return
+    }
+    if (!draft.edgeIds.length) return
+    if (!window.confirm(`Reihe mit ${draft.nodes.length} Schritten löschen?`)) return
+    setSavingKey(draft.key)
+    try {
+      await api.deleteExerciseProgressionEdgesBatch(graphId, draft.edgeIds)
+      await onRefresh()
+    } catch (e) {
+      alert(e.message || String(e))
+    } finally {
+      setSavingKey(null)
+    }
+  }
+
+  const saveDraft = async (draft) => {
+    if (!graphId) return
+    const steps = draft.nodes.filter((n) => n.exerciseId != null)
+    if (steps.length < 2) {
+      alert('Mindestens zwei Schritte mit gewählter Übung.')
+      return
+    }
+    const n = steps.length - 1
+    let segment_notes = draft.segmentNotes.slice(0, n)
+    while (segment_notes.length < n) segment_notes.push(null)
+    segment_notes = segment_notes.slice(0, n)
+
+    setSavingKey(draft.key)
+    try {
+      if (!draft.isNew && draft.edgeIds.length) {
+        await api.deleteExerciseProgressionEdgesBatch(graphId, draft.edgeIds)
+      }
+      await api.createExerciseProgressionSequence(graphId, {
+        steps: steps.map((s) => ({
+          exercise_id: s.exerciseId,
+          variant_id: s.variantId || null,
+        })),
+        segment_notes,
+      })
+      await onRefresh()
+    } catch (e) {
+      alert(e.message || String(e))
+    } finally {
+      setSavingKey(null)
+    }
+  }
+
+  const ensureVariantsLoaded = async (key, idx) => {
+    const draft = drafts.find((d) => d.key === key)
+    const node = draft?.nodes[idx]
+    if (!node?.exerciseId || (node.variants || []).length) return
+    const variants = await loadVariantsForExercise(node.exerciseId)
+    setDrafts((prev) =>
+      prev.map((d) => {
+        if (d.key !== key) return d
+        return {
+          ...d,
+          nodes: d.nodes.map((n, i) => (i === idx ? { ...n, variants } : n)),
+        }
+      }),
+    )
+  }
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      applyExercise: applyExerciseToNode,
+    }),
+    [applyExerciseToNode],
+  )
+
+  if (!graphId) return null
+
+  return (
+    <div className="card" style={{ marginBottom: '12px' }}>
+      <div
+        style={{
+          display: 'flex',
+          flexWrap: 'wrap',
+          gap: '10px',
+          alignItems: 'center',
+          justifyContent: 'space-between',
+          marginBottom: '12px',
+        }}
+      >
+        <div>
+          <h3 style={{ margin: 0, fontSize: '1rem' }}>Reihen im Graph</h3>
+          <p style={{ fontSize: '12px', color: 'var(--text3)', margin: '4px 0 0', lineHeight: 1.45 }}>
+            Jede Reihe ist ein linearer Pfad: Schritt 1 → 2 → … Reihenfolge ändern, Übungen tauschen oder
+            dazwischen einfügen, dann speichern.
+          </p>
+        </div>
+        <button type="button" className="btn btn-primary" disabled={busy} onClick={addNewChain}>
+          + Neue Reihe
+        </button>
+      </div>
+
+      {drafts.length === 0 ? (
+        <p style={{ color: 'var(--text2)', margin: 0, fontSize: '13px' }}>
+          Noch keine Reihen in diesem Graph. Legen Sie eine neue Reihe an oder nutzen Sie den KI-Planer unten.
+        </p>
+      ) : (
+        drafts.map((draft, chainIdx) => (
+          <div
+            key={draft.key}
+            style={{
+              marginBottom: '16px',
+              padding: '14px',
+              borderRadius: '10px',
+              border: `1px solid ${
+                draft.dirty
+                  ? 'color-mix(in srgb, var(--accent) 50%, var(--border))'
+                  : 'var(--border)'
+              }`,
+              background: 'var(--surface2)',
+            }}
+          >
+            <div
+              style={{
+                display: 'flex',
+                flexWrap: 'wrap',
+                gap: '8px',
+                alignItems: 'center',
+                marginBottom: '12px',
+              }}
+            >
+              <strong style={{ fontSize: '13px' }}>Reihe {chainIdx + 1}</strong>
+              {draft.dirty ? (
+                <span className="exercise-tag" style={{ borderColor: 'var(--accent)' }}>
+                  Ungespeichert
+                </span>
+              ) : null}
+              {draft.isNew ? (
+                <span className="exercise-tag">Neu</span>
+              ) : (
+                <span className="exercise-tag">{draft.nodes.length} Schritte</span>
+              )}
+            </div>
+
+            <div style={{ display: 'flex', flexDirection: 'column', gap: '0' }}>
+              {draft.nodes.map((node, idx) => (
+                <React.Fragment key={`${draft.key}-node-${idx}`}>
+                  {idx > 0 ? (
+                    <div
+                      style={{
+                        display: 'flex',
+                        alignItems: 'center',
+                        gap: '8px',
+                        padding: '4px 0 4px 12px',
+                        color: 'var(--accent)',
+                        fontSize: '12px',
+                        fontWeight: 700,
+                      }}
+                      aria-hidden
+                    >
+                      ↓ Nachfolger
+                    </div>
+                  ) : null}
+                  <div
+                    style={{
+                      display: 'grid',
+                      gridTemplateColumns: 'repeat(auto-fit, minmax(180px, 1fr))',
+                      gap: '10px',
+                      alignItems: 'end',
+                      padding: '10px 12px',
+                      borderRadius: '8px',
+                      border: '1px solid var(--border)',
+                      background: 'var(--surface)',
+                    }}
+                  >
+                    <div className="form-row" style={{ marginBottom: 0 }}>
+                      <label className="form-label">Schritt {idx + 1}</label>
+                      <div
+                        style={{
+                          display: 'flex',
+                          flexWrap: 'wrap',
+                          gap: '8px',
+                          alignItems: 'center',
+                        }}
+                      >
+                        <span style={{ fontSize: '13px', flex: '1 1 140px' }}>
+                          {formatNodeLabel(node)}
+                        </span>
+                        <button
+                          type="button"
+                          className="btn btn-secondary"
+                          style={{ fontSize: '12px', padding: '4px 10px' }}
+                          disabled={busy || savingKey === draft.key}
+                          onClick={() =>
+                            onPickExercise({ kind: 'chain', draftKey: draft.key, nodeIndex: idx })
+                          }
+                        >
+                          {node.exerciseId ? 'Tauschen…' : 'Übung…'}
+                        </button>
+                        {anchorExerciseId != null ? (
+                          <button
+                            type="button"
+                            className="btn"
+                            style={{ fontSize: '12px', padding: '4px 10px' }}
+                            disabled={busy || savingKey === draft.key}
+                            onClick={async () => {
+                              const variants = await loadVariantsForExercise(anchorExerciseId)
+                              await applyExerciseToNode(draft.key, idx, {
+                                id: anchorExerciseId,
+                                title: anchorTitle?.trim() || `Übung #${anchorExerciseId}`,
+                                variants,
+                              })
+                            }}
+                          >
+                            Kontext-Übung
+                          </button>
+                        ) : null}
+                      </div>
+                    </div>
+                    <div className="form-row" style={{ marginBottom: 0 }}>
+                      <label className="form-label">Variante</label>
+                      <select
+                        className="form-input"
+                        disabled={!node.exerciseId || busy || savingKey === draft.key}
+                        value={node.variantId ?? ''}
+                        onFocus={() => ensureVariantsLoaded(draft.key, idx)}
+                        onChange={(e) =>
+                          setVariant(
+                            draft.key,
+                            idx,
+                            e.target.value === '' ? null : parseInt(e.target.value, 10),
+                          )
+                        }
+                      >
+                        <option value="">Gesamte Übung</option>
+                        {(node.variants || []).map((v) => (
+                          <option key={v.id} value={v.id}>
+                            {v.variant_name || `Variante #${v.id}`}
+                          </option>
+                        ))}
+                      </select>
+                    </div>
+                    <div style={{ display: 'flex', gap: '6px', flexWrap: 'wrap' }}>
+                      <button
+                        type="button"
+                        className="btn"
+                        style={{ fontSize: '12px', padding: '4px 8px' }}
+                        disabled={busy || savingKey === draft.key || idx === 0}
+                        onClick={() => moveNode(draft.key, idx, -1)}
+                      >
+                        ↑
+                      </button>
+                      <button
+                        type="button"
+                        className="btn"
+                        style={{ fontSize: '12px', padding: '4px 8px' }}
+                        disabled={busy || savingKey === draft.key || idx >= draft.nodes.length - 1}
+                        onClick={() => moveNode(draft.key, idx, 1)}
+                      >
+                        ↓
+                      </button>
+                      <button
+                        type="button"
+                        className="btn"
+                        style={{ fontSize: '12px', padding: '4px 8px' }}
+                        disabled={busy || savingKey === draft.key}
+                        onClick={() => insertNodeAfter(draft.key, idx)}
+                      >
+                        + Einfügen
+                      </button>
+                      <button
+                        type="button"
+                        className="btn"
+                        style={{ fontSize: '12px', padding: '4px 8px' }}
+                        disabled={busy || savingKey === draft.key || draft.nodes.length <= 2}
+                        onClick={() => removeNode(draft.key, idx)}
+                      >
+                        Entfernen
+                      </button>
+                    </div>
+                  </div>
+                </React.Fragment>
+              ))}
+            </div>
+
+            <div style={{ display: 'flex', flexWrap: 'wrap', gap: '8px', marginTop: '12px' }}>
+              <button
+                type="button"
+                className="btn btn-primary"
+                disabled={busy || savingKey === draft.key || !draft.dirty}
+                onClick={() => saveDraft(draft)}
+              >
+                {savingKey === draft.key ? 'Speichern …' : 'Reihe speichern'}
+              </button>
+              {draft.dirty ? (
+                <button
+                  type="button"
+                  className="btn btn-secondary"
+                  disabled={busy || savingKey === draft.key}
+                  onClick={() => discardDraft(draft.key)}
+                >
+                  Verwerfen
+                </button>
+              ) : null}
+              <button
+                type="button"
+                className="btn"
+                style={{
+                  fontSize: '12px',
+                  background: 'var(--danger)',
+                  color: '#fff',
+                  border: 'none',
+                }}
+                disabled={busy || savingKey === draft.key}
+                onClick={() => deleteChain(draft)}
+              >
+                Reihe löschen
+              </button>
+            </div>
+          </div>
+        ))
+      )}
+    </div>
+  )
+})
+
+export default ProgressionChainEditor

From 8d5f0b533c6d43eaa58bdeb75236c774b74855cc Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Wed, 10 Jun 2026 11:17:05 +0200
Subject: [PATCH 08/33] Enhance Exercise Progression Graph Panel and Path
 Builder with New Features

- Introduced a primary chain selection in the Exercise Progression Graph Panel to streamline exercise path management.
- Updated the ProgressionChainEditor to support single path mode, allowing users to manage a single progression path more effectively.
- Enhanced the ExerciseProgressionPathBuilder with improved logic for merging graph nodes into path steps and filtering gap offers.
- Updated UI elements for better clarity and user experience, including new notifications and styling adjustments.
- Incremented application version to reflect these updates.
---
 .../ExerciseProgressionGraphPanel.jsx         |  67 ++++---
 .../ExerciseProgressionPathBuilder.jsx        | 182 ++++++++++++++++--
 .../src/components/ProgressionChainEditor.jsx |  30 +--
 3 files changed, 224 insertions(+), 55 deletions(-)

diff --git a/frontend/src/components/ExerciseProgressionGraphPanel.jsx b/frontend/src/components/ExerciseProgressionGraphPanel.jsx
index a124300..e62a75f 100644
--- a/frontend/src/components/ExerciseProgressionGraphPanel.jsx
+++ b/frontend/src/components/ExerciseProgressionGraphPanel.jsx
@@ -277,6 +277,13 @@ export default function ExerciseProgressionGraphPanel({
 
   const flowChains = useMemo(() => maximalLinearChains(nextEdgesFiltered), [nextEdgesFiltered])
 
+  const primaryChain = useMemo(() => {
+    if (!flowChains.length) return null
+    return flowChains.reduce((best, chain) =>
+      chain.nodes.length >= best.nodes.length ? chain : best,
+    )
+  }, [flowChains])
+
   const handleCreateGraph = async (e) => {
     e.preventDefault()
     const name = newGraphName.trim()
@@ -566,17 +573,42 @@ export default function ExerciseProgressionGraphPanel({
 
       {selectedGraphId && (
         <>
-          <ProgressionChainEditor
-            ref={chainEditorRef}
-            graphId={selectedGraphId}
-            chains={flowChains}
-            busy={busy}
-            anchorExerciseId={anchorExerciseId}
-            anchorTitle={anchorTitle}
-            onRefresh={async () => refreshEdges(selectedGraphId)}
-            onPickExercise={setPickContext}
-            loadVariantsForExercise={loadVariantsForExercise}
-          />
+          <div
+            className="card"
+            style={{
+              marginBottom: '12px',
+              borderColor: 'color-mix(in srgb, var(--accent) 30%, var(--border))',
+            }}
+          >
+            <h3 style={{ marginTop: 0, fontSize: '1rem' }}>Progressionspfad</h3>
+            <p style={{ fontSize: '12px', color: 'var(--text3)', marginTop: 0, lineHeight: 1.45 }}>
+              Der Graph enthält typischerweise <strong>einen linearen Pfad</strong> (Übung → Übung). Unten
+              manuell bearbeiten oder mit dem KI-Planer erweitern — Speichern im KI-Wizard ersetzt den Pfad.
+            </p>
+
+            <ProgressionChainEditor
+              ref={chainEditorRef}
+              graphId={selectedGraphId}
+              chains={primaryChain ? [primaryChain] : []}
+              busy={busy}
+              anchorExerciseId={anchorExerciseId}
+              anchorTitle={anchorTitle}
+              onRefresh={async () => refreshEdges(selectedGraphId)}
+              onPickExercise={setPickContext}
+              loadVariantsForExercise={loadVariantsForExercise}
+              singlePathMode
+            />
+
+            <ExerciseProgressionPathBuilder
+              graphId={selectedGraphId}
+              disabled={busy}
+              graphChainNodes={primaryChain?.nodes ?? null}
+              graphChainEdgeIds={primaryChain?.edges?.map((e) => e.id) ?? null}
+              onSaved={async () => {
+                await refreshEdges(selectedGraphId)
+              }}
+            />
+          </div>
 
           <div className="card" style={{ marginBottom: '12px' }}>
             <h3 style={{ marginTop: 0, fontSize: '1rem' }}>Schwestern & Alternativen</h3>
@@ -671,19 +703,6 @@ export default function ExerciseProgressionGraphPanel({
             </div>
           </details>
 
-          <details className="card" style={{ marginBottom: '12px' }}>
-            <summary style={{ cursor: 'pointer', fontWeight: 600 }}>KI: Neuen Pfad planen (4 Schritte)</summary>
-            <div style={{ marginTop: '14px' }}>
-              <ExerciseProgressionPathBuilder
-                graphId={selectedGraphId}
-                disabled={busy}
-                onSaved={async () => {
-                  await refreshEdges(selectedGraphId)
-                }}
-              />
-            </div>
-          </details>
-
           <SkillProfilePanel
             title="Fähigkeiten entlang des Pfads"
             hint="Alle Übungen als Knoten im Graph (Standardgewicht pro Übung; Intensität und Stufen aus der Übungsverknüpfung)."
diff --git a/frontend/src/components/ExerciseProgressionPathBuilder.jsx b/frontend/src/components/ExerciseProgressionPathBuilder.jsx
index 23e6982..a80812d 100644
--- a/frontend/src/components/ExerciseProgressionPathBuilder.jsx
+++ b/frontend/src/components/ExerciseProgressionPathBuilder.jsx
@@ -2,6 +2,7 @@
  * Planungs-KI Phase C3/E3: Ziel → Übungspfad vorschlagen → Lücken mit KI anlegen → in Graph speichern.
  */
 import React, { useCallback, useEffect, useMemo, useState } from 'react'
+import { Link } from 'react-router-dom'
 import api from '../utils/api'
 import ExerciseAiQuickCreateModal from './exercises/ExerciseAiQuickCreateModal'
 import ExerciseGapFillPrepModal from './exercises/ExerciseGapFillPrepModal'
@@ -134,6 +135,122 @@ const OFFER_SOURCE_LABELS = {
   roadmap_unfilled: 'Roadmap-Stufe',
 }
 
+function normalizeTitleKey(text) {
+  return String(text || '')
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, ' ')
+}
+
+function mergeGraphIntoPathSteps(pathRows, graphNodes) {
+  if (!Array.isArray(graphNodes) || !graphNodes.length || !pathRows.length) return pathRows
+  return pathRows.map((row, i) => {
+    const node = graphNodes[i]
+    if (!node?.exercise_id) return row
+    if (row.exerciseId != null) return row
+    return {
+      ...row,
+      exerciseId: Number(node.exercise_id),
+      exerciseTitle: node.title || `Übung #${node.exercise_id}`,
+      variantId: node.variant_id != null ? Number(node.variant_id) : null,
+      variants: row.variants || [],
+      isFromGraph: true,
+      reasons: [...(row.reasons || []), 'Aus bestehendem Graph übernommen'],
+    }
+  })
+}
+
+function filterGapOffersForGraph(offers, pathRows, graphNodes) {
+  if (!Array.isArray(offers) || !offers.length) return offers
+  const graphIds = new Set(
+    (graphNodes || []).map((n) => Number(n.exercise_id)).filter(Number.isFinite),
+  )
+  const graphTitles = new Set(
+    (graphNodes || []).map((n) => normalizeTitleKey(n.title)).filter(Boolean),
+  )
+  const pathIds = new Set(
+    (pathRows || []).map((r) => r.exerciseId).filter((id) => id != null),
+  )
+
+  return offers.filter((offer) => {
+    const hint = normalizeTitleKey(offer?.title_hint)
+    const majorIdx =
+      offer?.roadmap_major_step_index != null ? Number(offer.roadmap_major_step_index) : null
+
+    if (majorIdx != null && Number.isFinite(majorIdx) && graphNodes?.[majorIdx]) {
+      const gid = Number(graphNodes[majorIdx].exercise_id)
+      if (graphIds.has(gid) && pathIds.has(gid)) return false
+    }
+
+    for (const gid of graphIds) {
+      if (pathIds.has(gid) && hint) {
+        const node = graphNodes.find((n) => Number(n.exercise_id) === gid)
+        const nodeTitle = normalizeTitleKey(node?.title)
+        if (nodeTitle && (nodeTitle === hint || nodeTitle.includes(hint) || hint.includes(nodeTitle))) {
+          return false
+        }
+      }
+    }
+
+    for (const t of graphTitles) {
+      if (hint && (t === hint || t.includes(hint) || hint.includes(t))) return false
+    }
+    return true
+  })
+}
+
+function SavedGraphPathStrip({ nodes, hasDraft }) {
+  if (!Array.isArray(nodes) || nodes.length === 0) {
+    return (
+      <div
+        style={{
+          marginBottom: '14px',
+          padding: '10px 12px',
+          borderRadius: '8px',
+          border: '1px dashed var(--border)',
+          background: 'var(--surface2)',
+          fontSize: '12px',
+          color: 'var(--text2)',
+        }}
+      >
+        <strong style={{ color: 'var(--text1)' }}>Im Graph gespeichert:</strong> noch kein Pfad — der erste
+        Speichervorgang legt die Übungsfolge an.
+      </div>
+    )
+  }
+  return (
+    <div
+      style={{
+        marginBottom: '14px',
+        padding: '10px 12px',
+        borderRadius: '8px',
+        border: '1px solid var(--border)',
+        background: 'var(--surface2)',
+        fontSize: '12px',
+      }}
+    >
+      <strong style={{ display: 'block', marginBottom: '8px', color: 'var(--accent-dark)' }}>
+        Im Graph gespeichert ({nodes.length} Schritte)
+        {hasDraft ? (
+          <span style={{ fontWeight: 400, color: 'var(--text3)', marginLeft: '8px' }}>
+            — KI-Entwurf unten; Speichern ersetzt diesen Pfad
+          </span>
+        ) : null}
+      </strong>
+      <ol style={{ margin: 0, paddingLeft: '20px', lineHeight: 1.55 }}>
+        {nodes.map((node, idx) => (
+          <li key={`saved-${node.exercise_id}-${node.variant_id}-${idx}`}>
+            <Link to={`/exercises/${node.exercise_id}`}>{node.title || `Übung #${node.exercise_id}`}</Link>
+            {node.variant_name ? (
+              <span style={{ color: 'var(--text3)' }}>{` · ${node.variant_name}`}</span>
+            ) : null}
+          </li>
+        ))}
+      </ol>
+    </div>
+  )
+}
+
 const PATH_STEPS_HARD_MAX = 10
 
 const WIZARD_STEPS = [
@@ -399,6 +516,8 @@ export default function ExerciseProgressionPathBuilder({
   graphId,
   disabled = false,
   onSaved,
+  graphChainNodes = null,
+  graphChainEdgeIds = null,
 }) {
   const [goalQuery, setGoalQuery] = useState('')
   const [startSituation, setStartSituation] = useState('')
@@ -887,7 +1006,7 @@ export default function ExerciseProgressionPathBuilder({
       setActiveOffer(null)
       const title = (created.title || quickTitle || 'Übung').trim()
       setPathInsertNotice(
-        `„${title}" wurde in den KI-Pfad eingefügt. Speichern Sie jetzt mit «Pfad in Graph speichern» — die Reihe erscheint dann oben unter «Reihen im Graph».`,
+        `„${title}" wurde in den KI-Entwurf eingefügt. Mit «Pfad im Graph speichern» wird der gesamte Pfad übernommen.`,
       )
       setWizardStep(4)
     } catch (e) {
@@ -910,17 +1029,18 @@ export default function ExerciseProgressionPathBuilder({
     if (rows.length < 2) {
       throw new Error('Zu wenig Schritte im Vorschlag.')
     }
-    setPathSteps(rows)
+    const mergedRows = mergeGraphIntoPathSteps(rows, graphChainNodes)
+    const rawGaps = Array.isArray(res?.gap_fill_offers)
+      ? res.gap_fill_offers
+      : Array.isArray(qa?.gap_fill_offers)
+        ? qa.gap_fill_offers
+        : []
+    const gaps = filterGapOffersForGraph(rawGaps, mergedRows, graphChainNodes)
+    setPathSteps(mergedRows)
     setTargetSummary(res?.target_profile_summary || null)
     setSemanticBrief(res?.semantic_brief_summary || null)
     setPathQa(qa)
-    setGapFillOffers(
-      Array.isArray(res?.gap_fill_offers)
-        ? res.gap_fill_offers
-        : Array.isArray(qa?.gap_fill_offers)
-          ? qa.gap_fill_offers
-          : [],
-    )
+    setGapFillOffers(gaps)
     setProgressionRoadmap(res?.progression_roadmap || null)
     setPathSkillExpectations(res?.path_skill_expectations || null)
     setRoadmapDirty(false)
@@ -1125,6 +1245,12 @@ export default function ExerciseProgressionPathBuilder({
     setSaving(true)
     setError('')
     try {
+      const edgeIds = Array.isArray(graphChainEdgeIds)
+        ? graphChainEdgeIds.filter((id) => Number.isFinite(Number(id)))
+        : []
+      if (edgeIds.length > 0) {
+        await api.deleteExerciseProgressionEdgesBatch(Number(graphId), edgeIds)
+      }
       const planningArtifact = buildPlanningArtifact()
       await api.createExerciseProgressionSequence(Number(graphId), {
         steps: steps.map((s) => ({
@@ -1148,12 +1274,19 @@ export default function ExerciseProgressionPathBuilder({
       if (typeof onSaved === 'function') await onSaved()
       const msg =
         skippedAi > 0
-          ? `${n} Kante(n) gespeichert. ${skippedAi} KI-Vorschlag/Vorschläge nicht im Graph (noch nicht angelegt).`
-          : `${n} Nachfolger-Kante(n) aus KI-Pfad gespeichert.`
+          ? `Pfad gespeichert (${n} Kante(n)). ${skippedAi} KI-Vorschlag/Vorschläge noch nicht angelegt.`
+          : edgeIds.length > 0
+            ? `Progressionspfad aktualisiert (${n} Kante(n)).`
+            : `Progressionspfad angelegt (${n} Kante(n)).`
       alert(msg)
     } catch (e) {
       console.error(e)
-      setError(e.message || 'Speichern fehlgeschlagen')
+      const detail = e?.message || String(e)
+      setError(
+        detail.includes('409') || detail.toLowerCase().includes('duplikat')
+          ? 'Speichern fehlgeschlagen: Pfad-Konflikt. Bitte erneut versuchen — bestehende Kanten werden beim Speichern ersetzt.'
+          : detail || 'Speichern fehlgeschlagen',
+      )
     } finally {
       setSaving(false)
     }
@@ -1161,17 +1294,20 @@ export default function ExerciseProgressionPathBuilder({
 
   return (
     <div
-      className="card"
       style={{
-        marginBottom: '12px',
-        borderColor: 'color-mix(in srgb, var(--accent) 35%, var(--border))',
+        marginTop: '16px',
+        paddingTop: '16px',
+        borderTop: '1px solid var(--border)',
       }}
     >
-      <h3 style={{ marginTop: 0, fontSize: '1rem' }}>KI: Pfad zum Ziel</h3>
+      <h3 style={{ marginTop: 0, fontSize: '1rem' }}>Progressionspfad planen (KI)</h3>
       <p style={{ fontSize: '12px', color: 'var(--text3)', marginTop: 0, lineHeight: 1.45 }}>
-        In vier Schritten: Ziel festlegen → Roadmap bearbeiten → Übungen matchen → Lücken schließen und speichern.
+        Ein Graph hat einen linearen Pfad. Oben der gespeicherte Stand, darunter der KI-Entwurf in vier Schritten.
+        Speichern übernimmt den Entwurf und ersetzt den bisherigen Pfad.
       </p>
 
+      <SavedGraphPathStrip nodes={graphChainNodes} hasDraft={pathSteps.length > 0} />
+
       <PlanningWizardStepper
         currentStep={wizardStep}
         maxReachable={maxReachableStep}
@@ -1759,6 +1895,7 @@ export default function ExerciseProgressionPathBuilder({
                       : ''}
                     {step.roadmapPhase ? ` (${step.roadmapPhase})` : ''}
                     {step.isOffTopic ? ' (themenfremd)' : ''}
+                    {step.isFromGraph ? ' (im Graph)' : ''}
                     {step.isAiProposal ? ' (KI-Neu)' : step.isBridge ? ' (Brücke)' : ''}
                   </label>
                   {step.roadmapLearningGoal ? (
@@ -1922,8 +2059,8 @@ export default function ExerciseProgressionPathBuilder({
               color: 'var(--accent-dark)',
             }}
           >
-            <strong>Wichtig:</strong> Der KI-Pfad ist noch nicht im Graph gespeichert. KI-Übungen werden erst nach
-            «Pfad in Graph speichern» als neue Reihe oben sichtbar.
+            <strong>Wichtig:</strong> Der KI-Entwurf ist noch nicht gespeichert. «Pfad im Graph speichern» übernimmt
+            ihn und ersetzt den oben gezeigten Pfad.
             {pathInsertNotice ? <p style={{ margin: '8px 0 0' }}>{pathInsertNotice}</p> : null}
           </div>
 
@@ -2042,6 +2179,7 @@ export default function ExerciseProgressionPathBuilder({
                     <span style={{ color: 'var(--danger)' }}> — noch nicht angelegt</span>
                   )}
                   {step.roadmapPhase ? ` · ${step.roadmapPhase}` : ''}
+                  {step.isFromGraph ? ' · bereits im Graph' : ''}
                 </li>
               ))}
             </ol>
@@ -2072,7 +2210,11 @@ export default function ExerciseProgressionPathBuilder({
               disabled={disabled || saving || pathSteps.filter((s) => s.exerciseId).length < 2}
               onClick={savePathToGraph}
             >
-              {saving ? 'Speichern …' : 'Pfad in Graph speichern'}
+              {saving
+                ? 'Speichern …'
+                : graphChainEdgeIds?.length
+                  ? 'Pfad im Graph speichern (ersetzen)'
+                  : 'Pfad im Graph speichern'}
             </button>
             <button
               type="button"
diff --git a/frontend/src/components/ProgressionChainEditor.jsx b/frontend/src/components/ProgressionChainEditor.jsx
index 21fc0a3..5ab21e0 100644
--- a/frontend/src/components/ProgressionChainEditor.jsx
+++ b/frontend/src/components/ProgressionChainEditor.jsx
@@ -66,6 +66,7 @@ const ProgressionChainEditor = forwardRef(function ProgressionChainEditor(
     onRefresh,
     onPickExercise,
     loadVariantsForExercise,
+    singlePathMode = false,
   },
   ref,
 ) {
@@ -258,7 +259,7 @@ const ProgressionChainEditor = forwardRef(function ProgressionChainEditor(
   if (!graphId) return null
 
   return (
-    <div className="card" style={{ marginBottom: '12px' }}>
+    <div style={{ marginBottom: '16px' }}>
       <div
         style={{
           display: 'flex',
@@ -270,20 +271,25 @@ const ProgressionChainEditor = forwardRef(function ProgressionChainEditor(
         }}
       >
         <div>
-          <h3 style={{ margin: 0, fontSize: '1rem' }}>Reihen im Graph</h3>
+          <h4 style={{ margin: 0, fontSize: '0.95rem' }}>
+            {singlePathMode ? 'Manuell bearbeiten' : 'Reihen im Graph'}
+          </h4>
           <p style={{ fontSize: '12px', color: 'var(--text3)', margin: '4px 0 0', lineHeight: 1.45 }}>
-            Jede Reihe ist ein linearer Pfad: Schritt 1 → 2 → … Reihenfolge ändern, Übungen tauschen oder
-            dazwischen einfügen, dann speichern.
+            Schritt 1 → 2 → …: Reihenfolge ändern, Übungen tauschen oder dazwischen einfügen, dann speichern.
           </p>
         </div>
-        <button type="button" className="btn btn-primary" disabled={busy} onClick={addNewChain}>
-          + Neue Reihe
-        </button>
+        {!singlePathMode || drafts.length === 0 ? (
+          <button type="button" className="btn btn-secondary" disabled={busy} onClick={addNewChain}>
+            {singlePathMode ? '+ Pfad anlegen' : '+ Neue Reihe'}
+          </button>
+        ) : null}
       </div>
 
       {drafts.length === 0 ? (
         <p style={{ color: 'var(--text2)', margin: 0, fontSize: '13px' }}>
-          Noch keine Reihen in diesem Graph. Legen Sie eine neue Reihe an oder nutzen Sie den KI-Planer unten.
+          {singlePathMode
+            ? 'Noch kein gespeicherter Pfad — manuell anlegen oder mit dem KI-Planer unten.'
+            : 'Noch keine Reihen in diesem Graph.'}
         </p>
       ) : (
         drafts.map((draft, chainIdx) => (
@@ -310,7 +316,9 @@ const ProgressionChainEditor = forwardRef(function ProgressionChainEditor(
                 marginBottom: '12px',
               }}
             >
-              <strong style={{ fontSize: '13px' }}>Reihe {chainIdx + 1}</strong>
+              <strong style={{ fontSize: '13px' }}>
+                {singlePathMode ? 'Gespeicherter Pfad' : `Reihe ${chainIdx + 1}`}
+              </strong>
               {draft.dirty ? (
                 <span className="exercise-tag" style={{ borderColor: 'var(--accent)' }}>
                   Ungespeichert
@@ -471,7 +479,7 @@ const ProgressionChainEditor = forwardRef(function ProgressionChainEditor(
                 disabled={busy || savingKey === draft.key || !draft.dirty}
                 onClick={() => saveDraft(draft)}
               >
-                {savingKey === draft.key ? 'Speichern …' : 'Reihe speichern'}
+                {savingKey === draft.key ? 'Speichern …' : singlePathMode ? 'Pfad speichern' : 'Reihe speichern'}
               </button>
               {draft.dirty ? (
                 <button
@@ -495,7 +503,7 @@ const ProgressionChainEditor = forwardRef(function ProgressionChainEditor(
                 disabled={busy || savingKey === draft.key}
                 onClick={() => deleteChain(draft)}
               >
-                Reihe löschen
+                {singlePathMode ? 'Pfad löschen' : 'Reihe löschen'}
               </button>
             </div>
           </div>

From 97efe66306c5f8f6e13c8da41f773680dc7cfcdb Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Wed, 10 Jun 2026 13:05:49 +0200
Subject: [PATCH 09/33] Implement EvaluateStepPayload and SlotContentEntry for
 Enhanced Planning Features

- Introduced EvaluateStepPayload class to facilitate evaluation of exercise steps with optional attributes for AI proposals and roadmap details.
- Added SlotContentEntry and SlotExerciseContent classes to manage exercise content within the progression graph planning artifact.
- Updated GraphPlanningRoadmapArtifact to include new slot contents and last findings attributes for improved data handling.
- Enhanced Exercise Progression Graph Panel with links to the new Slot Editor for streamlined editing of progression graphs.
- Incremented application version to reflect these updates.
---
 .../PROGRESSION_GRAPH_SLOT_EDITOR_SPEC.md     |  79 +++
 backend/planning_exercise_path_builder.py     | 208 +++++++
 .../progression_graph_planning_artifact.py    |  29 +-
 frontend/src/App.jsx                          |   2 +
 .../ExerciseProgressionGraphPanel.jsx         |  15 +-
 .../components/ProgressionFindingsPanel.jsx   | 141 +++++
 .../src/components/ProgressionGraphEditor.jsx | 523 +++++++++++++++++
 .../src/components/ProgressionSlotCard.jsx    | 160 ++++++
 .../src/pages/ProgressionGraphEditPage.jsx    |  25 +
 frontend/src/utils/progressionGraphDraft.js   | 541 ++++++++++++++++++
 10 files changed, 1719 insertions(+), 4 deletions(-)
 create mode 100644 .claude/docs/working/PROGRESSION_GRAPH_SLOT_EDITOR_SPEC.md
 create mode 100644 frontend/src/components/ProgressionFindingsPanel.jsx
 create mode 100644 frontend/src/components/ProgressionGraphEditor.jsx
 create mode 100644 frontend/src/components/ProgressionSlotCard.jsx
 create mode 100644 frontend/src/pages/ProgressionGraphEditPage.jsx
 create mode 100644 frontend/src/utils/progressionGraphDraft.js

diff --git a/.claude/docs/working/PROGRESSION_GRAPH_SLOT_EDITOR_SPEC.md b/.claude/docs/working/PROGRESSION_GRAPH_SLOT_EDITOR_SPEC.md
new file mode 100644
index 0000000..2a59513
--- /dev/null
+++ b/.claude/docs/working/PROGRESSION_GRAPH_SLOT_EDITOR_SPEC.md
@@ -0,0 +1,79 @@
+# 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 & Routing
+
+- **B.4:** Route `/progression-graphs/:id` — Slots links, Findings rechts
+- **Phase C:** Übersicht mit Kacheln (Name, Start, Ziel)
+
+## Ersetzt schrittweise
+
+- Getrennte `ExerciseProgressionPathBuilder`-Wizard-UI + `ProgressionChainEditor` → integrierter `ProgressionGraphEditor`
+
+## 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 |
diff --git a/backend/planning_exercise_path_builder.py b/backend/planning_exercise_path_builder.py
index 2184805..f910df4 100644
--- a/backend/planning_exercise_path_builder.py
+++ b/backend/planning_exercise_path_builder.py
@@ -74,6 +74,18 @@ from planning_progression_roadmap import (
 from routers.training_planning import _has_planning_role
 
 
+class EvaluateStepPayload(BaseModel):
+    exercise_id: Optional[int] = Field(default=None, ge=1)
+    variant_id: Optional[int] = Field(default=None, ge=1)
+    title: Optional[str] = Field(default=None, max_length=500)
+    is_ai_proposal: bool = False
+    ai_suggestion: Optional[Dict[str, Any]] = None
+    proposal_key: Optional[str] = Field(default=None, max_length=120)
+    roadmap_major_step_index: Optional[int] = Field(default=None, ge=0, le=20)
+    roadmap_phase: Optional[str] = Field(default=None, max_length=80)
+    roadmap_learning_goal: Optional[str] = Field(default=None, max_length=2000)
+
+
 class ProgressionPathSuggestRequest(BaseModel):
     query: str = Field(..., min_length=3, max_length=2000)
     max_steps: int = Field(default=5, ge=2, le=10)
@@ -88,6 +100,8 @@ class ProgressionPathSuggestRequest(BaseModel):
     roadmap_first: bool = False
     roadmap_only: bool = False
     start_target_only: bool = False
+    evaluate_only: bool = False
+    evaluate_steps: Optional[List[EvaluateStepPayload]] = None
     roadmap_override: Optional[RoadmapOverridePayload] = None
     start_situation: Optional[str] = Field(default=None, max_length=2000)
     target_state: Optional[str] = Field(default=None, max_length=2000)
@@ -606,6 +620,162 @@ def _build_steps_roadmap_first(
     return steps, unfilled
 
 
+def _evaluate_steps_from_payload(
+    cur,
+    payloads: List[EvaluateStepPayload],
+) -> List[Dict[str, Any]]:
+    steps: List[Dict[str, Any]] = []
+    for raw in payloads:
+        is_proposal = bool(raw.is_ai_proposal) or raw.exercise_id is None
+        title = (raw.title or "").strip() or None
+        if is_proposal:
+            steps.append(
+                {
+                    "exercise_id": None,
+                    "variant_id": None,
+                    "title": title or "KI-Vorschlag",
+                    "is_ai_proposal": True,
+                    "ai_suggestion": raw.ai_suggestion,
+                    "proposal_key": raw.proposal_key,
+                    "roadmap_major_step_index": raw.roadmap_major_step_index,
+                    "roadmap_phase": raw.roadmap_phase,
+                    "roadmap_learning_goal": raw.roadmap_learning_goal,
+                    "reasons": [],
+                }
+            )
+            continue
+        eid = int(raw.exercise_id)
+        cur.execute(
+            "SELECT id, title, summary FROM exercises WHERE id = %s",
+            (eid,),
+        )
+        row = cur.fetchone()
+        if not row:
+            raise HTTPException(status_code=400, detail=f"Übung {eid} nicht gefunden")
+        steps.append(
+            {
+                "exercise_id": eid,
+                "variant_id": raw.variant_id,
+                "title": title or row.get("title"),
+                "summary": row.get("summary"),
+                "is_ai_proposal": False,
+                "roadmap_major_step_index": raw.roadmap_major_step_index,
+                "roadmap_phase": raw.roadmap_phase,
+                "roadmap_learning_goal": raw.roadmap_learning_goal,
+                "reasons": [],
+            }
+        )
+    return steps
+
+
+def _run_evaluate_only_path_qa(
+    cur,
+    *,
+    body: ProgressionPathSuggestRequest,
+    goal_query: str,
+    semantic_brief: PlanningSemanticBrief,
+    steps: List[Dict[str, Any]],
+    roadmap_ctx: Optional[ProgressionRoadmapContext],
+) -> Dict[str, Any]:
+    roadmap_first = roadmap_ctx is not None
+    gaps: List[Dict[str, Any]] = []
+    bridge_inserts: List[Dict[str, Any]] = []
+    unfilled_gaps: List[Dict[str, Any]] = []
+    llm_qa: Optional[Dict[str, Any]] = None
+    llm_qa_applied = False
+    off_topic_steps: List[Dict[str, Any]] = []
+    stripped_off_topic: List[Dict[str, Any]] = []
+    ai_proposals: List[Dict[str, Any]] = []
+    gap_fill_offers: List[Dict[str, Any]] = []
+    roadmap_qa_mode: Optional[str] = None
+
+    if body.include_path_qa:
+        if roadmap_first:
+            roadmap_qa_mode = "roadmap_first_lite"
+        gaps = detect_path_gaps(
+            cur,
+            steps,
+            brief=semantic_brief,
+            roadmap_first=roadmap_first,
+        )
+        if gaps and roadmap_first:
+            unfilled_gaps = list(gaps)
+
+        if body.include_llm_path_qa:
+            llm_qa, llm_qa_applied = try_llm_qa_progression_path(
+                cur,
+                goal_query=goal_query,
+                brief=semantic_brief,
+                steps=steps,
+                gaps=gaps,
+                bridge_inserts=bridge_inserts,
+            )
+
+        off_topic_steps = detect_off_topic_steps(cur, steps, brief=semantic_brief)
+        llm_gap_specs = parse_llm_suggested_new_exercises(
+            llm_qa,
+            brief=semantic_brief,
+            step_count=len(steps),
+        )
+
+        if body.include_ai_gap_fill:
+            fresh_large_gaps = [g for g in gaps if g.get("is_large_gap")]
+            gap_specs = collect_gap_fill_specs(
+                steps=steps,
+                unfilled_gaps=fresh_large_gaps or unfilled_gaps,
+                off_topic_steps=off_topic_steps,
+                llm_specs=llm_gap_specs,
+                brief=semantic_brief,
+                goal_query=goal_query,
+            )
+            path_roadmap_snapshot = None
+            if roadmap_ctx:
+                path_roadmap_snapshot = build_progression_gap_snapshot(
+                    goal_analysis=(
+                        roadmap_ctx.goal_analysis.model_dump()
+                        if roadmap_ctx.goal_analysis
+                        else None
+                    ),
+                    resolved_structured=(
+                        roadmap_ctx.resolved_structured.model_dump()
+                        if roadmap_ctx.resolved_structured
+                        else None
+                    ),
+                    semantic_brief=roadmap_ctx.semantic_brief
+                    or brief_to_summary_dict(semantic_brief),
+                )
+            _, ai_proposals, gap_fill_offers = apply_gap_fill_after_qa(
+                cur,
+                steps,
+                gap_specs,
+                goal_query=goal_query,
+                brief=semantic_brief,
+                include_ai_calls=False,
+                max_ai_proposals=0,
+                auto_insert_proposals=False,
+                roadmap_snapshot=path_roadmap_snapshot,
+            )
+
+    path_qa = build_path_qa_summary(
+        gaps=gaps,
+        bridge_inserts=bridge_inserts,
+        ai_proposals=ai_proposals,
+        gap_fill_offers=gap_fill_offers,
+        off_topic_steps=off_topic_steps,
+        stripped_off_topic=stripped_off_topic,
+        llm_qa=llm_qa,
+        llm_applied=llm_qa_applied,
+        reorder_applied=False,
+        reorder_notes=[],
+        roadmap_qa_mode=roadmap_qa_mode,
+    )
+    return {
+        "path_qa": path_qa,
+        "gap_fill_offers": gap_fill_offers,
+        "steps": steps,
+    }
+
+
 def suggest_progression_path(
     cur,
     *,
@@ -631,6 +801,7 @@ def suggest_progression_path(
     roadmap_first = bool(body.roadmap_first)
     roadmap_only = bool(body.roadmap_only)
     start_target_only = bool(body.start_target_only)
+    evaluate_only = bool(body.evaluate_only)
     include_roadmap = (
         roadmap_first or body.include_roadmap_preview or roadmap_only or start_target_only
     )
@@ -719,6 +890,42 @@ def suggest_progression_path(
             "retrieval_phase": "roadmap_only",
         }
 
+    if evaluate_only:
+        if not body.evaluate_steps:
+            raise HTTPException(
+                status_code=400,
+                detail="evaluate_only erfordert evaluate_steps",
+            )
+        eval_steps = _evaluate_steps_from_payload(cur, body.evaluate_steps)
+        qa_pack = _run_evaluate_only_path_qa(
+            cur,
+            body=body,
+            goal_query=goal_query,
+            semantic_brief=semantic_brief,
+            steps=eval_steps,
+            roadmap_ctx=roadmap_ctx,
+        )
+        return {
+            "goal_query": goal_query,
+            "max_steps_requested": max_steps,
+            "steps": qa_pack["steps"],
+            "step_count": len(qa_pack["steps"]),
+            "target_profile_summary": None,
+            "semantic_brief_summary": brief_to_summary_dict(semantic_brief),
+            "semantic_llm_applied": semantic_llm_applied,
+            "query_intent_summary": {},
+            "progression_graph_id": body.progression_graph_id,
+            "path_qa": qa_pack["path_qa"],
+            "gap_fill_offers": qa_pack["gap_fill_offers"],
+            "progression_roadmap": progression_roadmap,
+            "roadmap_first": bool(roadmap_ctx),
+            "roadmap_only": False,
+            "roadmap_edited": roadmap_edited,
+            "roadmap_unfilled_count": 0,
+            "path_skill_expectations": None,
+            "retrieval_phase": "evaluate_only",
+        }
+
     path_target_profile, first_intent_summary, path_intent = _build_path_target_profile(
         cur,
         goal_query=goal_query,
@@ -1030,6 +1237,7 @@ def suggest_progression_path(
 
 
 __all__ = [
+    "EvaluateStepPayload",
     "ProgressionPathSuggestRequest",
     "suggest_progression_path",
     "_pick_best_path_hit",
diff --git a/backend/progression_graph_planning_artifact.py b/backend/progression_graph_planning_artifact.py
index 64020d4..42988ad 100644
--- a/backend/progression_graph_planning_artifact.py
+++ b/backend/progression_graph_planning_artifact.py
@@ -10,6 +10,22 @@ ARTIFACT_SCHEMA_VERSION = 1
 _MAX_JSON_BYTES = 64_000
 
 
+class SlotExerciseContent(BaseModel):
+    kind: str = Field(default="empty", pattern=r"^(empty|library|proposal)$")
+    exercise_id: Optional[int] = Field(default=None, ge=1)
+    variant_id: Optional[int] = Field(default=None, ge=1)
+    title: Optional[str] = Field(default=None, max_length=500)
+    variant_name: Optional[str] = Field(default=None, max_length=200)
+    proposal_key: Optional[str] = Field(default=None, max_length=120)
+    ai_suggestion: Optional[Dict[str, Any]] = None
+
+
+class SlotContentEntry(BaseModel):
+    major_step_index: int = Field(ge=0, le=20)
+    primary: SlotExerciseContent = Field(default_factory=SlotExerciseContent)
+    siblings: List[SlotExerciseContent] = Field(default_factory=list)
+
+
 class GraphPlanningRoadmapArtifact(BaseModel):
     schema_version: int = Field(default=ARTIFACT_SCHEMA_VERSION, ge=1, le=1)
     goal_query: str = Field(default="", max_length=2000)
@@ -19,14 +35,23 @@ class GraphPlanningRoadmapArtifact(BaseModel):
     max_steps: int = Field(default=5, ge=2, le=10)
     progression_roadmap: Optional[Dict[str, Any]] = None
     path_skill_expectations: Optional[Dict[str, Any]] = None
+    slot_contents: Optional[List[SlotContentEntry]] = None
+    last_findings: Optional[Dict[str, Any]] = None
 
-    @field_validator("progression_roadmap", "path_skill_expectations", mode="before")
+    @field_validator("progression_roadmap", "path_skill_expectations", "last_findings", mode="before")
     @classmethod
     def _empty_dict_to_none(cls, v):
         if v == {}:
             return None
         return v
 
+    @field_validator("slot_contents", mode="before")
+    @classmethod
+    def _empty_slot_list_to_none(cls, v):
+        if v == []:
+            return None
+        return v
+
 
 def normalize_planning_roadmap_payload(raw: Any) -> Optional[Dict[str, Any]]:
     """None erlaubt (löschen); sonst validiertes Dict."""
@@ -45,5 +70,7 @@ def normalize_planning_roadmap_payload(raw: Any) -> Optional[Dict[str, Any]]:
 __all__ = [
     "ARTIFACT_SCHEMA_VERSION",
     "GraphPlanningRoadmapArtifact",
+    "SlotContentEntry",
+    "SlotExerciseContent",
     "normalize_planning_roadmap_payload",
 ]
diff --git a/frontend/src/App.jsx b/frontend/src/App.jsx
index acb42d4..1f695a6 100644
--- a/frontend/src/App.jsx
+++ b/frontend/src/App.jsx
@@ -31,6 +31,7 @@ const SettingsSystemInfoPage = lazy(() => import('./pages/SettingsSystemInfoPage
 const ExercisesListPage = lazy(() => import('./pages/ExercisesListPage'))
 const ExerciseDetailPage = lazy(() => import('./pages/ExerciseDetailPage'))
 const ExerciseFormPage = lazy(() => import('./pages/ExerciseFormPage'))
+const ProgressionGraphEditPage = lazy(() => import('./pages/ProgressionGraphEditPage'))
 const ClubsPage = lazy(() => import('./pages/ClubsPage'))
 const InboxPage = lazy(() => import('./pages/InboxPage'))
 const SkillsPage = lazy(() => import('./pages/SkillsPage'))
@@ -244,6 +245,7 @@ const appRouter = createBrowserRouter([
       { path: 'settings/system', element: <SettingsSystemInfoPage /> },
       { path: 'settings/legal', element: <SettingsLegalPage /> },
       { path: 'media', element: <MediaLibraryPage /> },
+      { path: 'progression-graphs/:id', element: <ProgressionGraphEditPage /> },
       {
         path: 'exercises',
         children: [
diff --git a/frontend/src/components/ExerciseProgressionGraphPanel.jsx b/frontend/src/components/ExerciseProgressionGraphPanel.jsx
index e62a75f..330c80a 100644
--- a/frontend/src/components/ExerciseProgressionGraphPanel.jsx
+++ b/frontend/src/components/ExerciseProgressionGraphPanel.jsx
@@ -485,9 +485,9 @@ export default function ExerciseProgressionGraphPanel({
       )}
 
       <p style={{ fontSize: '13px', color: 'var(--text2)', marginBottom: '16px' }}>
-        Ein Graph enthält eine oder mehrere <strong>Reihen</strong> (lineare Pfade Übung → Übung) sowie optional{' '}
-        <strong>Schwester-Alternativen</strong>. Reihen bearbeiten Sie direkt in der Liste; mit dem KI-Planer legen
-        Sie neue Pfade in vier Schritten an.
+        Ein Graph = ein linearer <strong>Primärpfad</strong> (Roadmap-Slots) plus optionale{' '}
+        <strong>Schwestern</strong>. Für die integrierte Bearbeitung (Slots, KI-Entwürfe, Graph-Bewertung){' '}
+        <strong>Slot-Editor öffnen</strong> — unten weiterhin Kurzansicht und KI-Wizard.
       </p>
 
       {loadErr && (
@@ -525,6 +525,15 @@ export default function ExerciseProgressionGraphPanel({
           <button type="button" className="btn" disabled={busy || !selectedGraphId} onClick={handleDeleteGraph}>
             Graph löschen
           </button>
+          {selectedGraphId ? (
+            <Link
+              to={`/progression-graphs/${selectedGraphId}`}
+              className="btn btn-primary"
+              style={{ textDecoration: 'none' }}
+            >
+              Slot-Editor öffnen
+            </Link>
+          ) : null}
         </div>
 
         <form onSubmit={handleCreateGraph} style={{ marginTop: '16px', paddingTop: '16px', borderTop: '1px solid var(--border)' }}>
diff --git a/frontend/src/components/ProgressionFindingsPanel.jsx b/frontend/src/components/ProgressionFindingsPanel.jsx
new file mode 100644
index 0000000..af70fa5
--- /dev/null
+++ b/frontend/src/components/ProgressionFindingsPanel.jsx
@@ -0,0 +1,141 @@
+/**
+ * Zentrales Findings-Panel für Progressionsgraph-QA (Phase B.2).
+ */
+import React from 'react'
+
+function severityStyle(pathQa) {
+  if (!pathQa) return {}
+  return {
+    background: pathQa.overall_ok
+      ? 'color-mix(in srgb, var(--accent) 8%, var(--surface2))'
+      : 'color-mix(in srgb, var(--danger) 8%, var(--surface2))',
+  }
+}
+
+export default function ProgressionFindingsPanel({
+  pathQa = null,
+  gapFillOffers = [],
+  loading = false,
+  error = '',
+  onEvaluate,
+  onApplyGapOffer,
+  evaluateDisabled = false,
+}) {
+  return (
+    <div className="card" style={{ position: 'sticky', top: '12px' }}>
+      <h3 style={{ marginTop: 0, fontSize: '1rem' }}>Graph-Bewertung</h3>
+      <p style={{ fontSize: '12px', color: 'var(--text3)', marginTop: 0, lineHeight: 1.45 }}>
+        Prüft den aktuellen Slot-Stand (inkl. KI-Entwürfe) ohne erneutes Übungs-Matching.
+      </p>
+
+      <button
+        type="button"
+        className="btn btn-primary btn-full"
+        disabled={loading || evaluateDisabled}
+        onClick={onEvaluate}
+        style={{ marginBottom: '12px' }}
+      >
+        {loading ? 'Bewertung läuft…' : 'Graph bewerten'}
+      </button>
+
+      {error ? (
+        <p className="form-error" style={{ marginTop: 0 }}>
+          {error}
+        </p>
+      ) : null}
+
+      {pathQa ? (
+        <div
+          style={{
+            padding: '10px 12px',
+            borderRadius: '8px',
+            fontSize: '12px',
+            lineHeight: 1.45,
+            ...severityStyle(pathQa),
+          }}
+        >
+          <strong>
+            Pfad-QS: {pathQa.overall_ok ? 'OK' : 'Hinweise'}
+            {pathQa.quality_score != null
+              ? ` (${Math.round(Number(pathQa.quality_score) * 100)} %)`
+              : ''}
+          </strong>
+          {pathQa.topic_coverage ? (
+            <p style={{ margin: '6px 0 0', color: 'var(--text2)' }}>{pathQa.topic_coverage}</p>
+          ) : null}
+          {Array.isArray(pathQa.issues) && pathQa.issues.length > 0 ? (
+            <ul style={{ margin: '6px 0 0', paddingLeft: '16px', color: 'var(--text2)' }}>
+              {pathQa.issues.map((issue) => (
+                <li key={issue}>{issue}</li>
+              ))}
+            </ul>
+          ) : null}
+          {Array.isArray(pathQa.recommendations) && pathQa.recommendations.length > 0 ? (
+            <>
+              <p style={{ margin: '8px 0 4px', fontWeight: 600, color: 'var(--text2)' }}>Empfehlungen</p>
+              <ul style={{ margin: 0, paddingLeft: '16px', color: 'var(--text2)' }}>
+                {pathQa.recommendations.map((rec) => (
+                  <li key={rec}>{rec}</li>
+                ))}
+              </ul>
+            </>
+          ) : null}
+          {Number(pathQa.off_topic_count) > 0 ? (
+            <p style={{ margin: '6px 0 0', color: 'var(--danger)' }}>
+              {pathQa.off_topic_count} Schritt(e) ohne Bezug zum Pfad-Thema.
+            </p>
+          ) : null}
+          {pathQa.roadmap_qa_mode === 'roadmap_first_lite' ? (
+            <p style={{ margin: '6px 0 0', color: 'var(--text2)' }}>
+              QS an Roadmap gekoppelt (keine Brücken zwischen Major Steps).
+            </p>
+          ) : null}
+        </div>
+      ) : (
+        <p style={{ fontSize: '12px', color: 'var(--text3)', margin: 0 }}>
+          Noch keine Bewertung. Slots befüllen und „Graph bewerten“ ausführen.
+        </p>
+      )}
+
+      {Array.isArray(gapFillOffers) && gapFillOffers.length > 0 ? (
+        <div style={{ marginTop: '14px' }}>
+          <h4 style={{ margin: '0 0 8px', fontSize: '0.9rem' }}>Lücken-Angebote</h4>
+          <ul style={{ listStyle: 'none', padding: 0, margin: 0, display: 'flex', flexDirection: 'column', gap: '8px' }}>
+            {gapFillOffers.slice(0, 6).map((offer) => (
+              <li
+                key={offer.offer_id || offer.title_hint}
+                style={{
+                  padding: '8px 10px',
+                  borderRadius: '8px',
+                  border: '1px solid var(--border)',
+                  background: 'var(--surface2)',
+                  fontSize: '12px',
+                }}
+              >
+                <div style={{ fontWeight: 600 }}>
+                  {offer.title_hint || 'Übungsvorschlag'}
+                  {offer.roadmap_major_step_index != null
+                    ? ` · Slot ${Number(offer.roadmap_major_step_index) + 1}`
+                    : ''}
+                </div>
+                {offer.rationale ? (
+                  <p style={{ margin: '4px 0 0', color: 'var(--text2)' }}>{offer.rationale}</p>
+                ) : null}
+                {typeof onApplyGapOffer === 'function' ? (
+                  <button
+                    type="button"
+                    className="btn btn-secondary"
+                    style={{ marginTop: '6px', fontSize: '11px', padding: '4px 8px' }}
+                    onClick={() => onApplyGapOffer(offer)}
+                  >
+                    Als Entwurf in Slot
+                  </button>
+                ) : null}
+              </li>
+            ))}
+          </ul>
+        </div>
+      ) : null}
+    </div>
+  )
+}
diff --git a/frontend/src/components/ProgressionGraphEditor.jsx b/frontend/src/components/ProgressionGraphEditor.jsx
new file mode 100644
index 0000000..4c1bedc
--- /dev/null
+++ b/frontend/src/components/ProgressionGraphEditor.jsx
@@ -0,0 +1,523 @@
+/**
+ * Integrierter Slot-Editor für Progressionsgraphen (Phase B).
+ */
+import React, { useCallback, useEffect, useMemo, useState } from 'react'
+import { Link } from 'react-router-dom'
+import api from '../utils/api'
+import ExercisePickerModal from './ExercisePickerModal'
+import ProgressionSlotCard from './ProgressionSlotCard'
+import ProgressionFindingsPanel from './ProgressionFindingsPanel'
+import {
+  applyGapOfferToSlot,
+  applyMatchStepsToSlots,
+  buildPlanningArtifactFromDraft,
+  hydrateProgressionGraphDraft,
+  librarySlotExercise,
+  majorStepsToOverridePayload,
+  reindexMajorSteps,
+  saveProgressionGraphDraft,
+  slotsToEvaluateSteps,
+} from '../utils/progressionGraphDraft'
+
+const ROADMAP_PHASES = ['einstieg', 'grundlage', 'vertiefung', 'anwendung', 'perfektion']
+
+function roadmapStructuredPayload(startSituation, targetState, roadmapNotes) {
+  const body = {}
+  const start = (startSituation || '').trim()
+  const target = (targetState || '').trim()
+  const notes = (roadmapNotes || '').trim()
+  if (start) body.start_situation = start
+  if (target) body.target_state = target
+  if (notes) body.roadmap_notes = notes
+  return body
+}
+
+export default function ProgressionGraphEditor({ graphId }) {
+  const [graphMeta, setGraphMeta] = useState(null)
+  const [draft, setDraft] = useState(null)
+  const [busy, setBusy] = useState(false)
+  const [loadErr, setLoadErr] = useState('')
+  const [actionErr, setActionErr] = useState('')
+  const [pickContext, setPickContext] = useState(null)
+  const [pathQa, setPathQa] = useState(null)
+  const [gapFillOffers, setGapFillOffers] = useState([])
+  const [evaluating, setEvaluating] = useState(false)
+  const [matching, setMatching] = useState(false)
+  const [roadmapLoading, setRoadmapLoading] = useState(false)
+
+  const loadGraph = useCallback(async () => {
+    if (!graphId) return
+    setBusy(true)
+    setLoadErr('')
+    try {
+      const [graph, edges] = await Promise.all([
+        api.getExerciseProgressionGraph(Number(graphId)),
+        api.listExerciseProgressionEdges(Number(graphId)),
+      ])
+      setGraphMeta(graph)
+      setDraft(
+        hydrateProgressionGraphDraft({
+          artifact: graph?.planning_roadmap,
+          edges: Array.isArray(edges) ? edges : [],
+          graphName: graph?.name,
+        }),
+      )
+      const findings = graph?.planning_roadmap?.last_findings
+      if (findings) setPathQa(findings)
+    } catch (e) {
+      setLoadErr(e.message || 'Graph konnte nicht geladen werden')
+      setDraft(null)
+    } finally {
+      setBusy(false)
+    }
+  }, [graphId])
+
+  useEffect(() => {
+    loadGraph()
+  }, [loadGraph])
+
+  const patchDraft = useCallback((patchFn) => {
+    setDraft((prev) => {
+      if (!prev) return prev
+      const next = patchFn(prev)
+      return { ...next, dirty: true }
+    })
+  }, [])
+
+  const handlePickExercise = async (exercise) => {
+    if (!pickContext || !exercise?.id) return
+    const { slotIndex, role } = pickContext
+    const entry = librarySlotExercise({
+      exerciseId: exercise.id,
+      exerciseTitle: exercise.title || `Übung #${exercise.id}`,
+    })
+    patchDraft((d) => {
+      const slots = d.slots.map((s, i) => {
+        if (i !== slotIndex) return s
+        if (role === 'primary') return { ...s, primary: entry }
+        const siblings = [...(s.siblings || [])]
+        if (!siblings.some((x) => x.exerciseId === entry.exerciseId)) siblings.push(entry)
+        return { ...s, siblings }
+      })
+      return { ...d, slots }
+    })
+    setPickContext(null)
+  }
+
+  const handlePatchLearningGoal = (slotIndex, value) => {
+    patchDraft((d) => {
+      const slots = d.slots.map((s, i) => (i === slotIndex ? { ...s, learning_goal: value } : s))
+      const majorSteps = reindexMajorSteps(
+        (d.majorSteps || []).map((m, i) => (i === slotIndex ? { ...m, learning_goal: value } : m)),
+      )
+      return { ...d, slots, majorSteps }
+    })
+  }
+
+  const handleClearPrimary = (slotIndex) => {
+    patchDraft((d) => {
+      const slots = d.slots.map((s, i) =>
+        i === slotIndex ? { ...s, primary: { kind: 'empty', exerciseId: null, variantId: null, exerciseTitle: '', variantName: null, proposalKey: null, aiSuggestion: null }, siblings: [] } : s,
+      )
+      return { ...d, slots }
+    })
+  }
+
+  const handleRemoveSibling = (slotIndex, sibIdx) => {
+    patchDraft((d) => {
+      const slots = d.slots.map((s, i) => {
+        if (i !== slotIndex) return s
+        return { ...s, siblings: s.siblings.filter((_, j) => j !== sibIdx) }
+      })
+      return { ...d, slots }
+    })
+  }
+
+  const handleAddSlot = () => {
+    patchDraft((d) => {
+      const idx = d.slots.length
+      const phase = ROADMAP_PHASES[Math.min(idx, ROADMAP_PHASES.length - 1)]
+      const slot = {
+        majorStepIndex: idx,
+        phase,
+        learning_goal: '',
+        consolidates: [],
+        rationale: '',
+        load_profile: [],
+        success_criteria: [],
+        anti_patterns: [],
+        exercise_type: '',
+        primary: { kind: 'empty', exerciseId: null, variantId: null, exerciseTitle: '', variantName: null, proposalKey: null, aiSuggestion: null },
+        siblings: [],
+      }
+      const major = {
+        index: idx,
+        phase,
+        learning_goal: '',
+        consolidates: [],
+        rationale: '',
+        load_profile: [],
+        success_criteria: [],
+        anti_patterns: [],
+        exercise_type: '',
+      }
+      return {
+        ...d,
+        slots: [...d.slots, slot],
+        majorSteps: [...(d.majorSteps || []), major],
+        maxSteps: Math.max(d.maxSteps, idx + 1),
+      }
+    })
+  }
+
+  const validMajorSteps = useMemo(() => {
+    if (!draft?.slots) return []
+    return draft.slots.filter((s) => (s.learning_goal || '').trim().length >= 3)
+  }, [draft?.slots])
+
+  const runRoadmapGenerate = async () => {
+    const q = (draft?.goalQuery || '').trim()
+    if (q.length < 3) {
+      alert('Ziel-Anfrage: mindestens 3 Zeichen.')
+      return
+    }
+    setRoadmapLoading(true)
+    setActionErr('')
+    try {
+      const res = await api.suggestProgressionPath({
+        query: q,
+        max_steps: draft.maxSteps || 5,
+        include_llm_intent: true,
+        include_path_qa: false,
+        include_llm_path_qa: false,
+        include_path_reorder: false,
+        include_ai_gap_fill: false,
+        include_roadmap_preview: true,
+        include_llm_roadmap: true,
+        roadmap_only: true,
+        progression_graph_id: Number(graphId),
+        ...roadmapStructuredPayload(draft.startSituation, draft.targetState, draft.roadmapNotes),
+      })
+      const roadmap = res?.progression_roadmap
+      if (!roadmap) throw new Error('Keine Roadmap in der Antwort')
+      const majors = (roadmap?.roadmap?.major_steps || []).map((s, i) => ({
+        index: i,
+        phase: s.phase || ROADMAP_PHASES[Math.min(i, ROADMAP_PHASES.length - 1)],
+        learning_goal: (s.learning_goal || '').trim(),
+        consolidates: Array.isArray(s.consolidates) ? s.consolidates : [],
+        rationale: s.rationale || '',
+        load_profile: [],
+        success_criteria: [],
+        anti_patterns: [],
+        exercise_type: '',
+      }))
+      const hydrated = hydrateProgressionGraphDraft({
+        artifact: {
+          ...buildPlanningArtifactFromDraft({ ...draft, progressionRoadmap: roadmap }),
+          progression_roadmap: roadmap,
+        },
+        edges: [],
+        graphName: draft.graphName,
+      })
+      setDraft({ ...hydrated, goalQuery: q, dirty: true })
+    } catch (e) {
+      setActionErr(e.message || 'Roadmap-Generierung fehlgeschlagen')
+    } finally {
+      setRoadmapLoading(false)
+    }
+  }
+
+  const runMatch = async () => {
+    const q = (draft?.goalQuery || '').trim()
+    if (q.length < 3) {
+      alert('Ziel-Anfrage: mindestens 3 Zeichen.')
+      return
+    }
+    if (validMajorSteps.length < 2) {
+      alert('Mindestens zwei Slots mit Lernziel (je 3+ Zeichen) nötig.')
+      return
+    }
+    setMatching(true)
+    setActionErr('')
+    try {
+      const override = majorStepsToOverridePayload(draft.slots.map((s) => ({
+        index: s.majorStepIndex,
+        phase: s.phase,
+        learning_goal: s.learning_goal,
+        consolidates: s.consolidates,
+        rationale: s.rationale,
+        load_profile: s.load_profile,
+        success_criteria: s.success_criteria,
+        anti_patterns: s.anti_patterns,
+        exercise_type: s.exercise_type,
+      })))
+      const res = await api.suggestProgressionPath({
+        query: q,
+        max_steps: validMajorSteps.length,
+        include_llm_intent: true,
+        include_path_qa: true,
+        include_llm_path_qa: true,
+        include_path_reorder: false,
+        include_ai_gap_fill: true,
+        include_roadmap_preview: true,
+        include_llm_roadmap: false,
+        roadmap_first: true,
+        roadmap_override: override,
+        progression_graph_id: Number(graphId),
+        ...roadmapStructuredPayload(draft.startSituation, draft.targetState, draft.roadmapNotes),
+      })
+      const next = applyMatchStepsToSlots(
+        {
+          ...draft,
+          progressionRoadmap: res?.progression_roadmap || draft.progressionRoadmap,
+          pathSkillExpectations: res?.path_skill_expectations || draft.pathSkillExpectations,
+        },
+        res?.steps,
+      )
+      setDraft(next)
+      setPathQa(res?.path_qa || null)
+      setGapFillOffers(Array.isArray(res?.gap_fill_offers) ? res.gap_fill_offers : [])
+    } catch (e) {
+      setActionErr(e.message || 'Übungs-Match fehlgeschlagen')
+    } finally {
+      setMatching(false)
+    }
+  }
+
+  const runEvaluate = async () => {
+    const q = (draft?.goalQuery || '').trim()
+    if (q.length < 3) {
+      alert('Ziel-Anfrage: mindestens 3 Zeichen.')
+      return
+    }
+    setEvaluating(true)
+    setActionErr('')
+    try {
+      const override =
+        validMajorSteps.length >= 2
+          ? majorStepsToOverridePayload(
+              draft.slots.map((s) => ({
+                index: s.majorStepIndex,
+                phase: s.phase,
+                learning_goal: s.learning_goal,
+                consolidates: s.consolidates,
+                rationale: s.rationale,
+                load_profile: s.load_profile,
+                success_criteria: s.success_criteria,
+                anti_patterns: s.anti_patterns,
+                exercise_type: s.exercise_type,
+              })),
+            )
+          : undefined
+      const res = await api.suggestProgressionPath({
+        query: q,
+        max_steps: draft.slots.length || draft.maxSteps || 5,
+        include_path_qa: true,
+        include_llm_path_qa: true,
+        include_ai_gap_fill: true,
+        include_path_reorder: false,
+        include_llm_intent: false,
+        evaluate_only: true,
+        evaluate_steps: slotsToEvaluateSteps(draft),
+        roadmap_override: override,
+        progression_graph_id: Number(graphId),
+        ...roadmapStructuredPayload(draft.startSituation, draft.targetState, draft.roadmapNotes),
+      })
+      setPathQa(res?.path_qa || null)
+      setGapFillOffers(Array.isArray(res?.gap_fill_offers) ? res.gap_fill_offers : [])
+      setDraft((prev) => (prev ? { ...prev, lastFindings: res?.path_qa || null } : prev))
+    } catch (e) {
+      setActionErr(e.message || 'Bewertung fehlgeschlagen')
+    } finally {
+      setEvaluating(false)
+    }
+  }
+
+  const handleSave = async () => {
+    if (!draft || !graphId) return
+    setBusy(true)
+    setActionErr('')
+    try {
+      await saveProgressionGraphDraft(api, graphId, { ...draft, lastFindings: pathQa })
+      await loadGraph()
+      alert('Progressionsgraph gespeichert.')
+    } catch (e) {
+      setActionErr(e.message || 'Speichern fehlgeschlagen')
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const handleApplyGapOffer = (offer) => {
+    const idx =
+      offer?.roadmap_major_step_index != null ? Number(offer.roadmap_major_step_index) : null
+    if (idx == null || !Number.isFinite(idx)) {
+      alert('Angebot ohne Slot-Zuordnung — bitte manuell zuweisen.')
+      return
+    }
+    setDraft((prev) => applyGapOfferToSlot(prev, idx, offer))
+  }
+
+  if (loadErr) {
+    return (
+      <div className="card">
+        <p className="form-error">{loadErr}</p>
+        <Link to="/exercises" className="btn btn-secondary">
+          Zurück
+        </Link>
+      </div>
+    )
+  }
+
+  if (!draft) {
+    return (
+      <div style={{ display: 'flex', justifyContent: 'center', padding: '40px' }}>
+        <div className="spinner" />
+      </div>
+    )
+  }
+
+  return (
+    <div>
+      <div style={{ marginBottom: '12px', display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start', flexWrap: 'wrap', gap: '8px' }}>
+        <div>
+          <h2 style={{ margin: 0, fontSize: '1.15rem' }}>
+            {graphMeta?.name || draft.graphName || `Graph #${graphId}`}
+          </h2>
+          <p style={{ margin: '4px 0 0', fontSize: '12px', color: 'var(--text3)' }}>
+            Slot-Editor · Roadmap = Struktur · ein Primärpfad + Schwestern
+          </p>
+        </div>
+        <Link to="/exercises" className="btn btn-secondary" style={{ fontSize: '12px' }}>
+          Zur Übersicht
+        </Link>
+      </div>
+
+      {actionErr ? (
+        <p className="form-error" style={{ marginTop: 0 }}>
+          {actionErr}
+        </p>
+      ) : null}
+
+      <div
+        className="progression-graph-editor-grid"
+        style={{
+          display: 'grid',
+          gridTemplateColumns: 'minmax(0, 1fr) minmax(260px, 320px)',
+          gap: '14px',
+          alignItems: 'start',
+        }}
+      >
+        <div>
+          <div className="card" style={{ marginBottom: '12px' }}>
+            <h3 style={{ marginTop: 0, fontSize: '1rem' }}>Ziel & Roadmap</h3>
+            <div className="form-row">
+              <label className="form-label">Ziel-Anfrage</label>
+              <textarea
+                className="form-input"
+                rows={2}
+                value={draft.goalQuery}
+                disabled={busy}
+                onChange={(e) => patchDraft((d) => ({ ...d, goalQuery: e.target.value }))}
+                placeholder="z. B. Vom Anfänger zum sauberen Gerade-Tritt"
+              />
+            </div>
+            <div className="form-row" style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '10px' }}>
+              <div>
+                <label className="form-label">Start-Situation</label>
+                <input
+                  className="form-input"
+                  value={draft.startSituation}
+                  disabled={busy}
+                  onChange={(e) => patchDraft((d) => ({ ...d, startSituation: e.target.value }))}
+                />
+              </div>
+              <div>
+                <label className="form-label">Ziel-Zustand</label>
+                <input
+                  className="form-input"
+                  value={draft.targetState}
+                  disabled={busy}
+                  onChange={(e) => patchDraft((d) => ({ ...d, targetState: e.target.value }))}
+                />
+              </div>
+            </div>
+            <div style={{ display: 'flex', flexWrap: 'wrap', gap: '8px', marginTop: '8px' }}>
+              <button
+                type="button"
+                className="btn btn-secondary"
+                disabled={busy || roadmapLoading}
+                onClick={runRoadmapGenerate}
+              >
+                {roadmapLoading ? 'Roadmap…' : 'Roadmap generieren'}
+              </button>
+              <button
+                type="button"
+                className="btn btn-secondary"
+                disabled={busy || matching}
+                onClick={runMatch}
+              >
+                {matching ? 'Match…' : 'Übungen matchen'}
+              </button>
+              <button type="button" className="btn btn-primary" disabled={busy} onClick={handleSave}>
+                {busy ? 'Speichern…' : 'Graph speichern'}
+              </button>
+            </div>
+            {draft.dirty ? (
+              <p style={{ margin: '8px 0 0', fontSize: '11px', color: 'var(--accent-dark)' }}>
+                Ungespeicherte Änderungen
+              </p>
+            ) : null}
+          </div>
+
+          <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: '8px' }}>
+            <h3 style={{ margin: 0, fontSize: '1rem' }}>Slots ({draft.slots.length})</h3>
+            <button type="button" className="btn btn-secondary" style={{ fontSize: '12px' }} disabled={busy || draft.slots.length >= 10} onClick={handleAddSlot}>
+              Slot hinzufügen
+            </button>
+          </div>
+
+          {draft.slots.map((slot, idx) => (
+            <ProgressionSlotCard
+              key={`slot-${slot.majorStepIndex}-${idx}`}
+              slot={slot}
+              slotIndex={idx}
+              disabled={busy}
+              onPickPrimary={(i) => setPickContext({ slotIndex: i, role: 'primary' })}
+              onPickSibling={(i) => setPickContext({ slotIndex: i, role: 'sibling' })}
+              onClearPrimary={handleClearPrimary}
+              onRemoveSibling={handleRemoveSibling}
+              onPatchLearningGoal={handlePatchLearningGoal}
+            />
+          ))}
+        </div>
+
+        <ProgressionFindingsPanel
+          pathQa={pathQa}
+          gapFillOffers={gapFillOffers}
+          loading={evaluating}
+          error={evaluating ? '' : ''}
+          onEvaluate={runEvaluate}
+          onApplyGapOffer={handleApplyGapOffer}
+          evaluateDisabled={busy || !draft.goalQuery?.trim()}
+        />
+      </div>
+
+      {pickContext ? (
+        <ExercisePickerModal
+          open
+          onClose={() => setPickContext(null)}
+          onSelectExercise={handlePickExercise}
+        />
+      ) : null}
+
+      <style>{`
+        @media (max-width: 900px) {
+          .progression-graph-editor-grid {
+            grid-template-columns: 1fr !important;
+          }
+        }
+      `}</style>
+    </div>
+  )
+}
diff --git a/frontend/src/components/ProgressionSlotCard.jsx b/frontend/src/components/ProgressionSlotCard.jsx
new file mode 100644
index 0000000..51fcaf0
--- /dev/null
+++ b/frontend/src/components/ProgressionSlotCard.jsx
@@ -0,0 +1,160 @@
+/**
+ * Einzelner Roadmap-Slot im Progressionsgraph-Editor.
+ */
+import React from 'react'
+import { Link } from 'react-router-dom'
+
+function exerciseLabel(entry) {
+  if (!entry || entry.kind === 'empty') return '— noch leer —'
+  if (entry.kind === 'proposal') return entry.exerciseTitle || 'KI-Entwurf'
+  return entry.exerciseTitle || `Übung #${entry.exerciseId}`
+}
+
+export default function ProgressionSlotCard({
+  slot,
+  slotIndex,
+  onPickPrimary,
+  onPickSibling,
+  onClearPrimary,
+  onRemoveSibling,
+  onPatchLearningGoal,
+  disabled = false,
+}) {
+  const { primary, siblings = [], phase, learning_goal: learningGoal } = slot
+
+  return (
+    <div
+      className="card"
+      style={{
+        marginBottom: '10px',
+        borderColor: primary.kind === 'empty'
+          ? 'var(--border)'
+          : 'color-mix(in srgb, var(--accent) 25%, var(--border))',
+      }}
+    >
+      <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start', gap: '8px', flexWrap: 'wrap' }}>
+        <div>
+          <h4 style={{ margin: 0, fontSize: '0.95rem' }}>
+            Slot {slotIndex + 1}
+            {phase ? <span style={{ color: 'var(--text3)', fontWeight: 400 }}>{` · ${phase}`}</span> : null}
+          </h4>
+        </div>
+        <span
+          className="exercise-tag"
+          style={{
+            fontSize: '11px',
+            borderColor: primary.kind === 'proposal' ? 'var(--danger)' : undefined,
+          }}
+        >
+          {primary.kind === 'empty' ? 'leer' : primary.kind === 'proposal' ? 'KI-Entwurf' : 'Bibliothek'}
+        </span>
+      </div>
+
+      <div className="form-row" style={{ marginTop: '10px', marginBottom: '8px' }}>
+        <label className="form-label">Lernziel (Major Step)</label>
+        <input
+          className="form-input"
+          value={learningGoal || ''}
+          disabled={disabled}
+          onChange={(e) => onPatchLearningGoal(slotIndex, e.target.value)}
+          placeholder="Was soll in dieser Stufe erreicht werden?"
+        />
+      </div>
+
+      <div
+        style={{
+          padding: '10px 12px',
+          borderRadius: '8px',
+          background: 'var(--surface2)',
+          border: '1px solid var(--border)',
+        }}
+      >
+        <div style={{ fontSize: '11px', color: 'var(--text3)', marginBottom: '4px' }}>Hauptpfad (primary)</div>
+        <div style={{ fontSize: '13px', fontWeight: 600 }}>
+          {primary.kind === 'library' && primary.exerciseId ? (
+            <Link to={`/exercises/${primary.exerciseId}`}>{exerciseLabel(primary)}</Link>
+          ) : (
+            exerciseLabel(primary)
+          )}
+          {primary.variantName ? (
+            <span style={{ color: 'var(--text3)', fontWeight: 400 }}>{` · ${primary.variantName}`}</span>
+          ) : null}
+        </div>
+        <div style={{ display: 'flex', gap: '6px', flexWrap: 'wrap', marginTop: '8px' }}>
+          <button
+            type="button"
+            className="btn btn-secondary"
+            style={{ fontSize: '12px', padding: '4px 10px' }}
+            disabled={disabled}
+            onClick={() => onPickPrimary(slotIndex)}
+          >
+            {primary.kind === 'empty' ? 'Übung wählen' : 'Übung ändern'}
+          </button>
+          {primary.kind !== 'empty' ? (
+            <button
+              type="button"
+              className="btn"
+              style={{ fontSize: '12px', padding: '4px 10px' }}
+              disabled={disabled}
+              onClick={() => onClearPrimary(slotIndex)}
+            >
+              Leeren
+            </button>
+          ) : null}
+        </div>
+      </div>
+
+      <div style={{ marginTop: '10px' }}>
+        <div style={{ fontSize: '11px', color: 'var(--text3)', marginBottom: '6px' }}>Schwestern (Alternativen)</div>
+        {siblings.length === 0 ? (
+          <p style={{ margin: 0, fontSize: '12px', color: 'var(--text2)' }}>Keine Schwestern.</p>
+        ) : (
+          <ul style={{ listStyle: 'none', padding: 0, margin: '0 0 8px', display: 'flex', flexDirection: 'column', gap: '6px' }}>
+            {siblings.map((sib, sibIdx) => (
+              <li
+                key={`${sib.exerciseId || sib.proposalKey}-${sibIdx}`}
+                style={{
+                  display: 'flex',
+                  justifyContent: 'space-between',
+                  alignItems: 'center',
+                  gap: '8px',
+                  padding: '6px 8px',
+                  borderRadius: '6px',
+                  background: 'var(--surface2)',
+                  fontSize: '12px',
+                }}
+              >
+                <span>
+                  {sib.kind === 'library' && sib.exerciseId ? (
+                    <Link to={`/exercises/${sib.exerciseId}`}>{exerciseLabel(sib)}</Link>
+                  ) : (
+                    exerciseLabel(sib)
+                  )}
+                </span>
+                <button
+                  type="button"
+                  className="btn"
+                  style={{ fontSize: '11px', padding: '2px 8px' }}
+                  disabled={disabled}
+                  onClick={() => onRemoveSibling(slotIndex, sibIdx)}
+                >
+                  Entfernen
+                </button>
+              </li>
+            ))}
+          </ul>
+        )}
+        <button
+          type="button"
+          className="btn btn-secondary"
+          style={{ fontSize: '12px', padding: '4px 10px' }}
+          disabled={disabled || primary.kind !== 'library'}
+          onClick={() => onPickSibling(slotIndex)}
+          title={primary.kind !== 'library' ? 'Zuerst eine Hauptübung wählen' : undefined}
+        >
+          Schwester hinzufügen
+        </button>
+      </div>
+    </div>
+  )
+}
diff --git a/frontend/src/pages/ProgressionGraphEditPage.jsx b/frontend/src/pages/ProgressionGraphEditPage.jsx
new file mode 100644
index 0000000..ccf392d
--- /dev/null
+++ b/frontend/src/pages/ProgressionGraphEditPage.jsx
@@ -0,0 +1,25 @@
+import React from 'react'
+import { Link, useParams } from 'react-router-dom'
+import ProgressionGraphEditor from '../components/ProgressionGraphEditor'
+
+export default function ProgressionGraphEditPage() {
+  const { id } = useParams()
+  const graphId = Number(id)
+
+  if (!Number.isFinite(graphId) || graphId < 1) {
+    return (
+      <div className="page" style={{ padding: '16px' }}>
+        <p className="form-error">Ungültige Graph-ID.</p>
+        <Link to="/exercises" className="btn btn-secondary">
+          Zurück
+        </Link>
+      </div>
+    )
+  }
+
+  return (
+    <div className="page" style={{ padding: '16px', paddingBottom: '80px' }}>
+      <ProgressionGraphEditor graphId={graphId} />
+    </div>
+  )
+}
diff --git a/frontend/src/utils/progressionGraphDraft.js b/frontend/src/utils/progressionGraphDraft.js
new file mode 100644
index 0000000..8470ec6
--- /dev/null
+++ b/frontend/src/utils/progressionGraphDraft.js
@@ -0,0 +1,541 @@
+/**
+ * Progressionsgraph Slot-Editor — Draft-Hydration und Speichern (Phase B).
+ */
+
+const ROADMAP_PHASES = ['einstieg', 'grundlage', 'vertiefung', 'anwendung', 'perfektion']
+export const PLANNING_ARTIFACT_SCHEMA = 1
+
+export function emptySlotExercise() {
+  return {
+    kind: 'empty',
+    exerciseId: null,
+    variantId: null,
+    exerciseTitle: '',
+    variantName: null,
+    proposalKey: null,
+    aiSuggestion: null,
+  }
+}
+
+export function librarySlotExercise({ exerciseId, exerciseTitle, variantId = null, variantName = null }) {
+  return {
+    kind: 'library',
+    exerciseId: Number(exerciseId),
+    variantId: variantId != null ? Number(variantId) : null,
+    exerciseTitle: exerciseTitle || `Übung #${exerciseId}`,
+    variantName: variantName || null,
+    proposalKey: null,
+    aiSuggestion: null,
+  }
+}
+
+export function proposalSlotExercise({ title, proposalKey = null, aiSuggestion = null }) {
+  return {
+    kind: 'proposal',
+    exerciseId: null,
+    variantId: null,
+    exerciseTitle: (title || 'KI-Vorschlag').trim(),
+    variantName: null,
+    proposalKey: proposalKey || `proposal-${Date.now()}`,
+    aiSuggestion: aiSuggestion || null,
+  }
+}
+
+export function slotExerciseFromApi(raw) {
+  if (!raw || typeof raw !== 'object') return emptySlotExercise()
+  const kind = raw.kind || (raw.exercise_id != null ? 'library' : raw.ai_suggestion ? 'proposal' : 'empty')
+  if (kind === 'proposal' || raw.ai_suggestion) {
+    return proposalSlotExercise({
+      title: raw.title || raw.exercise_title,
+      proposalKey: raw.proposal_key,
+      aiSuggestion: raw.ai_suggestion,
+    })
+  }
+  if (kind === 'library' && raw.exercise_id != null) {
+    return librarySlotExercise({
+      exerciseId: raw.exercise_id,
+      exerciseTitle: raw.title || raw.exercise_title,
+      variantId: raw.variant_id,
+      variantName: raw.variant_name,
+    })
+  }
+  return emptySlotExercise()
+}
+
+export function slotExerciseToApi(entry) {
+  if (!entry || entry.kind === 'empty') {
+    return { kind: 'empty' }
+  }
+  if (entry.kind === 'proposal') {
+    return {
+      kind: 'proposal',
+      title: entry.exerciseTitle || 'KI-Vorschlag',
+      proposal_key: entry.proposalKey || null,
+      ai_suggestion: entry.aiSuggestion || null,
+    }
+  }
+  return {
+    kind: 'library',
+    exercise_id: entry.exerciseId,
+    variant_id: entry.variantId || null,
+    title: entry.exerciseTitle || null,
+    variant_name: entry.variantName || null,
+  }
+}
+
+export function mapMajorStepsFromApi(apiRoadmap) {
+  const raw = apiRoadmap?.roadmap?.major_steps
+  if (!Array.isArray(raw)) return []
+  const rows = raw.map((s, i) => ({
+    index: i,
+    phase: s.phase || 'vertiefung',
+    learning_goal: (s.learning_goal || '').trim(),
+    consolidates: Array.isArray(s.consolidates) ? s.consolidates : [],
+    rationale: s.rationale || '',
+    load_profile: [],
+    success_criteria: [],
+    anti_patterns: [],
+    exercise_type: '',
+  }))
+  const specs = apiRoadmap?.stage_specs
+  if (!Array.isArray(specs) || !rows.length) return rows
+  return rows.map((row, i) => {
+    const spec =
+      specs.find((s) => Number(s.major_step_index) === i) ||
+      specs.find((s) => Number(s.major_step_index) === row.index) ||
+      specs[i]
+    if (!spec) return row
+    return {
+      ...row,
+      load_profile: Array.isArray(spec.load_profile) ? [...spec.load_profile] : [],
+      success_criteria: Array.isArray(spec.success_criteria) ? [...spec.success_criteria] : [],
+      anti_patterns: Array.isArray(spec.anti_patterns) ? [...spec.anti_patterns] : [],
+      exercise_type: (spec.exercise_type || '').trim(),
+    }
+  })
+}
+
+export function reindexMajorSteps(rows) {
+  return rows.map((row, i) => ({ ...row, index: i }))
+}
+
+export function majorStepsToOverridePayload(rows) {
+  const indexed = reindexMajorSteps(rows)
+  return {
+    major_steps: indexed.map((row) => ({
+      index: row.index,
+      phase: row.phase || 'vertiefung',
+      learning_goal: row.learning_goal.trim(),
+      consolidates: row.consolidates || [],
+      rationale: row.rationale || '',
+    })),
+    stage_specs: indexed.map((row, i) => ({
+      major_step_index: i,
+      learning_goal: row.learning_goal.trim(),
+      load_profile: Array.isArray(row.load_profile) ? row.load_profile : [],
+      exercise_type: (row.exercise_type || '').trim(),
+      success_criteria: Array.isArray(row.success_criteria) ? row.success_criteria : [],
+      anti_patterns: Array.isArray(row.anti_patterns) ? row.anti_patterns : [],
+    })),
+  }
+}
+
+function nodeKey(exerciseId, variantId) {
+  return `${exerciseId}:${variantId ?? ''}`
+}
+
+/** Maximale lineare Segmente aus next_exercise-Kanten. */
+export function maximalLinearChains(nextEdges) {
+  if (!nextEdges?.length) return []
+  const outMap = new Map()
+  const inMap = new Map()
+
+  for (const e of nextEdges) {
+    const f = nodeKey(e.from_exercise_id, e.from_exercise_variant_id)
+    const t = nodeKey(e.to_exercise_id, e.to_exercise_variant_id)
+    if (!outMap.has(f)) outMap.set(f, [])
+    outMap.get(f).push(e)
+    if (!inMap.has(t)) inMap.set(t, [])
+    inMap.get(t).push(e)
+  }
+
+  const used = new Set()
+  const chains = []
+
+  for (const startEdge of nextEdges) {
+    if (used.has(startEdge.id)) continue
+    const edgesSeq = [startEdge]
+
+    let fk = nodeKey(startEdge.from_exercise_id, startEdge.from_exercise_variant_id)
+    while (true) {
+      const preds = inMap.get(fk)
+      if (!preds || preds.length !== 1) break
+      const pred = preds[0]
+      if (used.has(pred.id)) break
+      edgesSeq.unshift(pred)
+      fk = nodeKey(pred.from_exercise_id, pred.from_exercise_variant_id)
+    }
+
+    let tk = nodeKey(startEdge.to_exercise_id, startEdge.to_exercise_variant_id)
+    while (true) {
+      const outs = outMap.get(tk)
+      if (!outs || outs.length !== 1) break
+      const nx = outs[0]
+      if (used.has(nx.id)) break
+      edgesSeq.push(nx)
+      tk = nodeKey(nx.to_exercise_id, nx.to_exercise_variant_id)
+    }
+
+    edgesSeq.forEach((ed) => used.add(ed.id))
+    const first = edgesSeq[0]
+    const nodes = [
+      {
+        exercise_id: first.from_exercise_id,
+        variant_id: first.from_exercise_variant_id ?? null,
+        title: first.from_exercise_title,
+        variant_name: first.from_variant_name ?? null,
+      },
+    ]
+    for (const ed of edgesSeq) {
+      nodes.push({
+        exercise_id: ed.to_exercise_id,
+        variant_id: ed.to_exercise_variant_id ?? null,
+        title: ed.to_exercise_title,
+        variant_name: ed.to_variant_name ?? null,
+      })
+    }
+    chains.push({ nodes, edges: edgesSeq })
+  }
+  return chains
+}
+
+function chainNodeToLibrary(node) {
+  if (!node?.exercise_id) return emptySlotExercise()
+  return librarySlotExercise({
+    exerciseId: node.exercise_id,
+    exerciseTitle: node.title || `Übung #${node.exercise_id}`,
+    variantId: node.variant_id,
+    variantName: node.variant_name,
+  })
+}
+
+function buildSlotsFromSources({ majorSteps, slotContents, primaryChain, siblingEdges }) {
+  const slotCount = Math.max(majorSteps.length, primaryChain?.nodes?.length || 0, 2)
+  const slots = []
+
+  for (let i = 0; i < slotCount; i += 1) {
+    const major = majorSteps[i] || {
+      index: i,
+      phase: ROADMAP_PHASES[Math.min(i, ROADMAP_PHASES.length - 1)],
+      learning_goal: '',
+      consolidates: [],
+      rationale: '',
+      load_profile: [],
+      success_criteria: [],
+      anti_patterns: [],
+      exercise_type: '',
+    }
+    const saved = Array.isArray(slotContents)
+      ? slotContents.find((s) => Number(s.major_step_index) === i)
+      : null
+
+    let primary = saved?.primary
+      ? slotExerciseFromApi(saved.primary)
+      : chainNodeToLibrary(primaryChain?.nodes?.[i])
+
+    if (primary.kind === 'empty' && saved?.primary) {
+      primary = slotExerciseFromApi(saved.primary)
+    }
+
+    const siblings = []
+    const seenSiblingKeys = new Set()
+
+    if (Array.isArray(saved?.siblings)) {
+      for (const sib of saved.siblings) {
+        const entry = slotExerciseFromApi(sib)
+        if (entry.kind !== 'empty') {
+          const key = entry.kind === 'library' ? `lib-${entry.exerciseId}` : `prop-${entry.proposalKey}`
+          if (!seenSiblingKeys.has(key)) {
+            seenSiblingKeys.add(key)
+            siblings.push(entry)
+          }
+        }
+      }
+    }
+
+    if (primary.kind === 'library' && Array.isArray(siblingEdges)) {
+      const pid = primary.exerciseId
+      for (const edge of siblingEdges) {
+        let other = null
+        if (Number(edge.from_exercise_id) === pid) {
+          other = librarySlotExercise({
+            exerciseId: edge.to_exercise_id,
+            exerciseTitle: edge.to_exercise_title,
+            variantId: edge.to_exercise_variant_id,
+            variantName: edge.to_variant_name,
+          })
+        } else if (Number(edge.to_exercise_id) === pid) {
+          other = librarySlotExercise({
+            exerciseId: edge.from_exercise_id,
+            exerciseTitle: edge.from_exercise_title,
+            variantId: edge.from_exercise_variant_id,
+            variantName: edge.from_variant_name,
+          })
+        }
+        if (other) {
+          const key = `lib-${other.exerciseId}`
+          if (!seenSiblingKeys.has(key)) {
+            seenSiblingKeys.add(key)
+            siblings.push(other)
+          }
+        }
+      }
+    }
+
+    slots.push({
+      majorStepIndex: i,
+      phase: major.phase,
+      learning_goal: major.learning_goal,
+      consolidates: major.consolidates,
+      rationale: major.rationale,
+      load_profile: major.load_profile,
+      success_criteria: major.success_criteria,
+      anti_patterns: major.anti_patterns,
+      exercise_type: major.exercise_type,
+      primary,
+      siblings,
+    })
+  }
+
+  return slots
+}
+
+export function hydrateProgressionGraphDraft({
+  artifact = null,
+  edges = [],
+  graphName = '',
+}) {
+  const nextEdges = (edges || []).filter((e) => (e.edge_type || 'next_exercise') === 'next_exercise')
+  const siblingEdges = (edges || []).filter((e) => e.edge_type === 'sibling')
+  const chains = maximalLinearChains(nextEdges)
+  const primaryChain = chains.sort((a, b) => b.nodes.length - a.nodes.length)[0] || null
+
+  const majorSteps = artifact?.progression_roadmap
+    ? mapMajorStepsFromApi(artifact.progression_roadmap)
+    : []
+
+  const slots = buildSlotsFromSources({
+    majorSteps,
+    slotContents: artifact?.slot_contents,
+    primaryChain,
+    siblingEdges,
+  })
+
+  return {
+    graphName: graphName || '',
+    goalQuery: artifact?.goal_query || '',
+    startSituation: artifact?.start_situation || '',
+    targetState: artifact?.target_state || '',
+    roadmapNotes: artifact?.roadmap_notes || '',
+    maxSteps: Number(artifact?.max_steps) || Math.max(slots.length, 5),
+    majorSteps: majorSteps.length ? majorSteps : slots.map((s, i) => ({
+      index: i,
+      phase: s.phase,
+      learning_goal: s.learning_goal,
+      consolidates: s.consolidates,
+      rationale: s.rationale,
+      load_profile: s.load_profile,
+      success_criteria: s.success_criteria,
+      anti_patterns: s.anti_patterns,
+      exercise_type: s.exercise_type,
+    })),
+    slots,
+    pathSkillExpectations: artifact?.path_skill_expectations || null,
+    progressionRoadmap: artifact?.progression_roadmap || null,
+    lastFindings: artifact?.last_findings || null,
+    primaryChainEdgeIds: primaryChain?.edges?.map((e) => e.id) || [],
+    siblingEdgeIds: siblingEdges.map((e) => e.id),
+    dirty: false,
+  }
+}
+
+export function buildPlanningArtifactFromDraft(draft, { lastFindings = undefined } = {}) {
+  const q = (draft.goalQuery || '').trim()
+  const progressionRoadmap = draft.progressionRoadmap || null
+  if (!q && !progressionRoadmap && !draft.slots?.length) return null
+
+  const slot_contents = (draft.slots || []).map((slot) => ({
+    major_step_index: slot.majorStepIndex,
+    primary: slotExerciseToApi(slot.primary),
+    siblings: (slot.siblings || []).map(slotExerciseToApi).filter((s) => s.kind !== 'empty'),
+  }))
+
+  const artifact = {
+    schema_version: PLANNING_ARTIFACT_SCHEMA,
+    goal_query: q,
+    start_situation: (draft.startSituation || '').trim() || null,
+    target_state: (draft.targetState || '').trim() || null,
+    roadmap_notes: (draft.roadmapNotes || '').trim() || null,
+    max_steps: Number(draft.maxSteps) || draft.slots?.length || 5,
+    progression_roadmap: progressionRoadmap,
+    path_skill_expectations: draft.pathSkillExpectations || null,
+    slot_contents,
+  }
+
+  const findings = lastFindings !== undefined ? lastFindings : draft.lastFindings
+  if (findings) artifact.last_findings = findings
+
+  return artifact
+}
+
+/** Befüllte Primärkette (nur library) für edges/sequence. */
+export function draftPrimaryChainSteps(draft) {
+  const steps = []
+  for (const slot of draft.slots || []) {
+    if (slot.primary?.kind === 'library' && slot.primary.exerciseId != null) {
+      steps.push({
+        exerciseId: slot.primary.exerciseId,
+        variantId: slot.primary.variantId,
+        exerciseTitle: slot.primary.exerciseTitle,
+        majorStepIndex: slot.majorStepIndex,
+        phase: slot.phase,
+        learningGoal: slot.learning_goal,
+      })
+    }
+  }
+  return steps
+}
+
+export function draftSiblingEdgePairs(draft) {
+  const pairs = []
+  for (const slot of draft.slots || []) {
+    if (slot.primary?.kind !== 'library' || slot.primary.exerciseId == null) continue
+    for (const sib of slot.siblings || []) {
+      if (sib.kind !== 'library' || sib.exerciseId == null) continue
+      pairs.push({
+        from: { exerciseId: slot.primary.exerciseId, variantId: slot.primary.variantId },
+        to: { exerciseId: sib.exerciseId, variantId: sib.variantId },
+      })
+    }
+  }
+  return pairs
+}
+
+export function slotsToEvaluateSteps(draft) {
+  return (draft.slots || []).map((slot) => {
+    const p = slot.primary
+    if (p.kind === 'proposal') {
+      return {
+        exercise_id: null,
+        variant_id: null,
+        title: p.exerciseTitle,
+        is_ai_proposal: true,
+        ai_suggestion: p.aiSuggestion,
+        proposal_key: p.proposalKey,
+        roadmap_major_step_index: slot.majorStepIndex,
+        roadmap_phase: slot.phase,
+        roadmap_learning_goal: slot.learning_goal,
+      }
+    }
+    if (p.kind === 'library' && p.exerciseId != null) {
+      return {
+        exercise_id: p.exerciseId,
+        variant_id: p.variantId || null,
+        title: p.exerciseTitle,
+        is_ai_proposal: false,
+        roadmap_major_step_index: slot.majorStepIndex,
+        roadmap_phase: slot.phase,
+        roadmap_learning_goal: slot.learning_goal,
+      }
+    }
+    return {
+      exercise_id: null,
+      variant_id: null,
+      title: `(leer: ${slot.learning_goal || `Slot ${slot.majorStepIndex + 1}`})`,
+      is_ai_proposal: true,
+      roadmap_major_step_index: slot.majorStepIndex,
+      roadmap_phase: slot.phase,
+      roadmap_learning_goal: slot.learning_goal,
+    }
+  })
+}
+
+export function applyMatchStepsToSlots(draft, apiSteps) {
+  const steps = Array.isArray(apiSteps) ? apiSteps : []
+  const nextSlots = (draft.slots || []).map((slot) => ({ ...slot, primary: { ...slot.primary }, siblings: [...(slot.siblings || [])] }))
+
+  for (const step of steps) {
+    const idx =
+      step.roadmap_major_step_index != null
+        ? Number(step.roadmap_major_step_index)
+        : steps.indexOf(step)
+    if (!Number.isFinite(idx) || idx < 0 || idx >= nextSlots.length) continue
+
+    const isProposal = Boolean(step.is_ai_proposal) || step.exercise_id == null
+    if (isProposal) {
+      nextSlots[idx].primary = proposalSlotExercise({
+        title: step.title,
+        proposalKey: step.proposal_key,
+        aiSuggestion: step.ai_suggestion,
+      })
+    } else {
+      nextSlots[idx].primary = librarySlotExercise({
+        exerciseId: step.exercise_id,
+        exerciseTitle: step.title || `Übung #${step.exercise_id}`,
+        variantId: step.variant_id,
+      })
+    }
+  }
+
+  return { ...draft, slots: nextSlots, dirty: true }
+}
+
+export function applyGapOfferToSlot(draft, slotIndex, offer, aiSuggestion = null) {
+  const nextSlots = (draft.slots || []).map((s) => ({ ...s, primary: { ...s.primary }, siblings: [...(s.siblings || [])] }))
+  if (slotIndex < 0 || slotIndex >= nextSlots.length) return draft
+  nextSlots[slotIndex].primary = proposalSlotExercise({
+    title: offer?.title_hint || offer?.title || 'KI-Vorschlag',
+    proposalKey: offer?.offer_id || offer?.proposal_key,
+    aiSuggestion: aiSuggestion || offer?.ai_suggestion || null,
+  })
+  return { ...draft, slots: nextSlots, dirty: true }
+}
+
+export async function saveProgressionGraphDraft(api, graphId, draft) {
+  const primarySteps = draftPrimaryChainSteps(draft)
+  const siblingPairs = draftSiblingEdgePairs(draft)
+  const artifact = buildPlanningArtifactFromDraft(draft)
+  const edgeIds = [
+    ...(draft.primaryChainEdgeIds || []),
+    ...(draft.siblingEdgeIds || []),
+  ].filter((id) => Number.isFinite(Number(id)))
+
+  if (edgeIds.length > 0) {
+    await api.deleteExerciseProgressionEdgesBatch(Number(graphId), edgeIds)
+  }
+
+  if (primarySteps.length >= 2) {
+    await api.createExerciseProgressionSequence(Number(graphId), {
+      steps: primarySteps.map((s) => ({
+        exercise_id: s.exerciseId,
+        variant_id: s.variantId || null,
+      })),
+      segment_notes: primarySteps.slice(1).map(() => null),
+      ...(artifact ? { planning_roadmap: artifact } : {}),
+    })
+  } else if (artifact) {
+    await api.updateExerciseProgressionGraph(Number(graphId), { planning_roadmap: artifact })
+  }
+
+  for (const pair of siblingPairs) {
+    await api.createExerciseProgressionEdge(Number(graphId), {
+      from_exercise_id: pair.from.exerciseId,
+      from_exercise_variant_id: pair.from.variantId,
+      to_exercise_id: pair.to.exerciseId,
+      to_exercise_variant_id: pair.to.variantId,
+      edge_type: 'sibling',
+    })
+  }
+
+  return { primaryCount: primarySteps.length, siblingCount: siblingPairs.length }
+}

From c1bf9279ad0d59a0f1d34d6db0c09725acbf3831 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Wed, 10 Jun 2026 15:34:37 +0200
Subject: [PATCH 10/33] Add Gap Offer Handling and UI Enhancements in
 Progression Graph Components

- Implemented `_build_evaluate_empty_slot_gap_specs` function to generate gap offer specifications for unfilled roadmap slots in evaluate-only mode.
- Enhanced `ProgressionFindingsPanel` to display AI offers for empty slots and gaps, improving user interaction and clarity.
- Updated `ProgressionGraphEditor` and `ProgressionSlotCard` components to support new functionalities for managing slots and offers.
- Refactored utility functions in `progressionGraphDraft.js` to streamline slot management and offer handling.
- Incremented application version to reflect these updates.
---
 backend/planning_exercise_path_builder.py     |  62 +++
 .../progression_graph_planning_artifact.py    |   2 +-
 ...est_progression_graph_planning_artifact.py |  23 +
 .../components/ProgressionFindingsPanel.jsx   | 206 +++++++--
 .../src/components/ProgressionGraphEditor.jsx | 437 +++++++++++++-----
 .../src/components/ProgressionSlotCard.jsx    | 128 +++--
 frontend/src/utils/progressionGraphDraft.js   | 262 ++++++++++-
 7 files changed, 914 insertions(+), 206 deletions(-)

diff --git a/backend/planning_exercise_path_builder.py b/backend/planning_exercise_path_builder.py
index f910df4..364448a 100644
--- a/backend/planning_exercise_path_builder.py
+++ b/backend/planning_exercise_path_builder.py
@@ -668,6 +668,47 @@ def _evaluate_steps_from_payload(
     return steps
 
 
+def _build_evaluate_empty_slot_gap_specs(
+    steps: List[Dict[str, Any]],
+    *,
+    goal_query: str,
+) -> List[Dict[str, Any]]:
+    """Gap-Angebote für leere Roadmap-Slots im evaluate_only-Modus."""
+    specs: List[Dict[str, Any]] = []
+    for step in steps:
+        if step.get("exercise_id") is not None:
+            continue
+        major_idx = step.get("roadmap_major_step_index")
+        if major_idx is None:
+            continue
+        try:
+            roadmap_idx = int(major_idx)
+        except (TypeError, ValueError):
+            continue
+        phase = (step.get("roadmap_phase") or "vertiefung").strip().lower()
+        learning_goal = (step.get("roadmap_learning_goal") or step.get("title") or "").strip()
+        title_hint = learning_goal[:120] if learning_goal else f"Slot {roadmap_idx + 1}"
+        specs.append(
+            {
+                "source": "roadmap_unfilled",
+                "insert_after_index": max(roadmap_idx - 1, -1),
+                "gap": {
+                    "expected_phase": phase,
+                    "roadmap_major_step_index": roadmap_idx,
+                    "learning_goal": learning_goal,
+                },
+                "phase": phase,
+                "title_hint": title_hint,
+                "sketch": learning_goal or title_hint,
+                "rationale": (
+                    f"Slot {roadmap_idx + 1} ohne Übung — KI-Entwurf für diese Roadmap-Stufe."
+                ),
+                "roadmap_major_step_index": roadmap_idx,
+            }
+        )
+    return specs[:8]
+
+
 def _run_evaluate_only_path_qa(
     cur,
     *,
@@ -728,6 +769,27 @@ def _run_evaluate_only_path_qa(
                 brief=semantic_brief,
                 goal_query=goal_query,
             )
+            empty_slot_specs = _build_evaluate_empty_slot_gap_specs(
+                steps,
+                goal_query=goal_query,
+            )
+            seen_spec_keys = {
+                (
+                    s.get("source"),
+                    s.get("roadmap_major_step_index"),
+                    s.get("insert_after_index"),
+                )
+                for s in gap_specs
+            }
+            for spec in empty_slot_specs:
+                key = (
+                    spec.get("source"),
+                    spec.get("roadmap_major_step_index"),
+                    spec.get("insert_after_index"),
+                )
+                if key not in seen_spec_keys:
+                    gap_specs.append(spec)
+                    seen_spec_keys.add(key)
             path_roadmap_snapshot = None
             if roadmap_ctx:
                 path_roadmap_snapshot = build_progression_gap_snapshot(
diff --git a/backend/progression_graph_planning_artifact.py b/backend/progression_graph_planning_artifact.py
index 42988ad..0a75480 100644
--- a/backend/progression_graph_planning_artifact.py
+++ b/backend/progression_graph_planning_artifact.py
@@ -2,7 +2,7 @@
 from __future__ import annotations
 
 import json
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional
 
 from pydantic import BaseModel, Field, field_validator
 
diff --git a/backend/tests/test_progression_graph_planning_artifact.py b/backend/tests/test_progression_graph_planning_artifact.py
index 523e6ea..1ae1932 100644
--- a/backend/tests/test_progression_graph_planning_artifact.py
+++ b/backend/tests/test_progression_graph_planning_artifact.py
@@ -34,3 +34,26 @@ def test_normalize_planning_roadmap_with_progression_roadmap():
 def test_normalize_rejects_invalid_type():
     with pytest.raises(ValueError, match="JSON-Objekt"):
         normalize_planning_roadmap_payload("not-json")
+
+
+def test_normalize_slot_contents():
+    out = normalize_planning_roadmap_payload(
+        {
+            "goal_query": "Gerade-Tritt",
+            "max_steps": 3,
+            "slot_contents": [
+                {
+                    "major_step_index": 0,
+                    "primary": {"kind": "library", "exercise_id": 12, "title": "Grundstellung"},
+                    "siblings": [],
+                },
+                {
+                    "major_step_index": 1,
+                    "primary": {"kind": "proposal", "title": "KI-Entwurf", "proposal_key": "p1"},
+                    "siblings": [],
+                },
+            ],
+        }
+    )
+    assert len(out["slot_contents"]) == 2
+    assert out["slot_contents"][1]["primary"]["kind"] == "proposal"
diff --git a/frontend/src/components/ProgressionFindingsPanel.jsx b/frontend/src/components/ProgressionFindingsPanel.jsx
index af70fa5..ebfc1cb 100644
--- a/frontend/src/components/ProgressionFindingsPanel.jsx
+++ b/frontend/src/components/ProgressionFindingsPanel.jsx
@@ -1,7 +1,13 @@
 /**
  * Zentrales Findings-Panel für Progressionsgraph-QA (Phase B.2).
  */
-import React from 'react'
+import React, { useMemo, useState } from 'react'
+import {
+  offerCanExpandSlots,
+  offerNeedsNewSlot,
+  offerSourceLabel,
+  resolveOfferSlotIndex,
+} from '../utils/progressionGraphDraft'
 
 function severityStyle(pathQa) {
   if (!pathQa) return {}
@@ -12,20 +18,150 @@ function severityStyle(pathQa) {
   }
 }
 
+function GapOfferCard({
+  offer,
+  slotCount,
+  draft,
+  onApplyDraft,
+  onInsertSlot,
+  onGenerateAi,
+  generatingOfferId,
+  aiBusy,
+}) {
+  const defaultSlot = resolveOfferSlotIndex(draft, offer)
+  const [slotPick, setSlotPick] = useState(
+    defaultSlot != null && Number.isFinite(defaultSlot) ? String(defaultSlot) : '',
+  )
+  const needsInsert = offerNeedsNewSlot(offer)
+  const canInsert = offerCanExpandSlots(draft, offer)
+
+  const slotOptions = useMemo(() => {
+    const rows = []
+    for (let i = 0; i < slotCount; i += 1) {
+      rows.push({ value: String(i), label: `Slot ${i + 1}` })
+    }
+    return rows
+  }, [slotCount])
+
+  const applyToSlot = () => {
+    const idx = slotPick !== '' ? Number(slotPick) : defaultSlot
+    if (!Number.isFinite(idx)) {
+      alert('Bitte einen Slot wählen.')
+      return
+    }
+    onApplyDraft(offer, idx)
+  }
+
+  return (
+    <li
+      style={{
+        padding: '10px 12px',
+        borderRadius: '8px',
+        border: '1px solid var(--border)',
+        background: 'var(--surface2)',
+        fontSize: '12px',
+      }}
+    >
+      <span className="exercise-tag" style={{ marginBottom: '6px', display: 'inline-block' }}>
+        {offerSourceLabel(offer.source)}
+        {offer.phase ? ` · ${offer.phase}` : ''}
+        {offer.has_ai_payload ? ' · KI-Entwurf bereit' : ''}
+      </span>
+      <div style={{ fontWeight: 600 }}>{offer.title_hint || offer.proposal_title || 'Übungsvorschlag'}</div>
+      {offer.rationale ? (
+        <p style={{ margin: '4px 0 0', color: 'var(--text2)' }}>{offer.rationale}</p>
+      ) : null}
+      {offer.from_title && offer.to_title ? (
+        <p style={{ margin: '4px 0 0', color: 'var(--text3)', fontSize: '11px' }}>
+          Zwischen „{offer.from_title}“ und „{offer.to_title}“
+        </p>
+      ) : null}
+
+      <div style={{ marginTop: '8px', display: 'flex', flexWrap: 'wrap', gap: '6px', alignItems: 'center' }}>
+        <label style={{ fontSize: '11px', color: 'var(--text3)' }}>
+          Ziel-Slot
+          <select
+            className="form-input"
+            style={{ marginLeft: '6px', padding: '4px 8px', fontSize: '12px', minWidth: '100px' }}
+            value={slotPick}
+            onChange={(e) => setSlotPick(e.target.value)}
+          >
+            <option value="">— wählen —</option>
+            {slotOptions.map((o) => (
+              <option key={o.value} value={o.value}>
+                {o.label}
+              </option>
+            ))}
+          </select>
+        </label>
+      </div>
+
+      <div style={{ marginTop: '8px', display: 'flex', flexWrap: 'wrap', gap: '6px' }}>
+        {offer.has_ai_payload ? (
+          <button
+            type="button"
+            className="btn btn-primary"
+            style={{ fontSize: '11px', padding: '4px 8px' }}
+            onClick={() => applyToSlot()}
+          >
+            Entwurf in Slot
+          </button>
+        ) : (
+          <button
+            type="button"
+            className="btn btn-primary"
+            style={{ fontSize: '11px', padding: '4px 8px' }}
+            disabled={aiBusy}
+            onClick={() => onGenerateAi(offer, slotPick !== '' ? Number(slotPick) : defaultSlot)}
+          >
+            {generatingOfferId === offer.offer_id ? 'KI erstellt…' : 'KI anlegen'}
+          </button>
+        )}
+        <button
+          type="button"
+          className="btn btn-secondary"
+          style={{ fontSize: '11px', padding: '4px 8px' }}
+          onClick={() => applyToSlot()}
+        >
+          Platzhalter in Slot
+        </button>
+        {needsInsert ? (
+          <button
+            type="button"
+            className="btn btn-secondary"
+            style={{ fontSize: '11px', padding: '4px 8px' }}
+            disabled={!canInsert}
+            title={!canInsert ? `Maximal ${slotCount} Slots` : 'Neuen Slot zwischen zwei Stufen einfügen'}
+            onClick={() => onInsertSlot(offer)}
+          >
+            Neuen Slot einfügen
+          </button>
+        ) : null}
+      </div>
+    </li>
+  )
+}
+
 export default function ProgressionFindingsPanel({
   pathQa = null,
   gapFillOffers = [],
+  draft = null,
+  slotCount = 0,
   loading = false,
   error = '',
   onEvaluate,
   onApplyGapOffer,
+  onInsertGapSlot,
+  onGenerateGapAi,
+  generatingOfferId = null,
+  aiBusy = false,
   evaluateDisabled = false,
 }) {
   return (
     <div className="card" style={{ position: 'sticky', top: '12px' }}>
       <h3 style={{ marginTop: 0, fontSize: '1rem' }}>Graph-Bewertung</h3>
       <p style={{ fontSize: '12px', color: 'var(--text3)', marginTop: 0, lineHeight: 1.45 }}>
-        Prüft den aktuellen Slot-Stand (inkl. KI-Entwürfe) ohne erneutes Übungs-Matching.
+        Prüft den Slot-Stand und listet KI-Angebote für leere Stufen und Lücken.
       </p>
 
       <button
@@ -85,57 +221,39 @@ export default function ProgressionFindingsPanel({
               {pathQa.off_topic_count} Schritt(e) ohne Bezug zum Pfad-Thema.
             </p>
           ) : null}
-          {pathQa.roadmap_qa_mode === 'roadmap_first_lite' ? (
-            <p style={{ margin: '6px 0 0', color: 'var(--text2)' }}>
-              QS an Roadmap gekoppelt (keine Brücken zwischen Major Steps).
-            </p>
-          ) : null}
         </div>
       ) : (
         <p style={{ fontSize: '12px', color: 'var(--text3)', margin: 0 }}>
-          Noch keine Bewertung. Slots befüllen und „Graph bewerten“ ausführen.
+          Noch keine Bewertung. Roadmap anlegen, dann „Graph bewerten“ oder „Übungen matchen“.
         </p>
       )}
 
-      {Array.isArray(gapFillOffers) && gapFillOffers.length > 0 ? (
-        <div style={{ marginTop: '14px' }}>
-          <h4 style={{ margin: '0 0 8px', fontSize: '0.9rem' }}>Lücken-Angebote</h4>
+      <div style={{ marginTop: '14px' }}>
+        <h4 style={{ margin: '0 0 8px', fontSize: '0.9rem' }}>
+          KI-Angebote {gapFillOffers.length > 0 ? `(${gapFillOffers.length})` : ''}
+        </h4>
+        {gapFillOffers.length === 0 ? (
+          <p style={{ fontSize: '12px', color: 'var(--text3)', margin: 0 }}>
+            Keine offenen Angebote. Nach Match oder Bewertung erscheinen Vorschläge für leere Slots und Lücken.
+          </p>
+        ) : (
           <ul style={{ listStyle: 'none', padding: 0, margin: 0, display: 'flex', flexDirection: 'column', gap: '8px' }}>
-            {gapFillOffers.slice(0, 6).map((offer) => (
-              <li
-                key={offer.offer_id || offer.title_hint}
-                style={{
-                  padding: '8px 10px',
-                  borderRadius: '8px',
-                  border: '1px solid var(--border)',
-                  background: 'var(--surface2)',
-                  fontSize: '12px',
-                }}
-              >
-                <div style={{ fontWeight: 600 }}>
-                  {offer.title_hint || 'Übungsvorschlag'}
-                  {offer.roadmap_major_step_index != null
-                    ? ` · Slot ${Number(offer.roadmap_major_step_index) + 1}`
-                    : ''}
-                </div>
-                {offer.rationale ? (
-                  <p style={{ margin: '4px 0 0', color: 'var(--text2)' }}>{offer.rationale}</p>
-                ) : null}
-                {typeof onApplyGapOffer === 'function' ? (
-                  <button
-                    type="button"
-                    className="btn btn-secondary"
-                    style={{ marginTop: '6px', fontSize: '11px', padding: '4px 8px' }}
-                    onClick={() => onApplyGapOffer(offer)}
-                  >
-                    Als Entwurf in Slot
-                  </button>
-                ) : null}
-              </li>
+            {gapFillOffers.map((offer) => (
+              <GapOfferCard
+                key={offer.offer_id || `${offer.source}-${offer.title_hint}`}
+                offer={offer}
+                slotCount={slotCount}
+                draft={draft}
+                generatingOfferId={generatingOfferId}
+                aiBusy={aiBusy}
+                onApplyDraft={(o, idx) => onApplyGapOffer(o, idx)}
+                onInsertSlot={onInsertGapSlot}
+                onGenerateAi={onGenerateGapAi}
+              />
             ))}
           </ul>
-        </div>
-      ) : null}
+        )}
+      </div>
     </div>
   )
 }
diff --git a/frontend/src/components/ProgressionGraphEditor.jsx b/frontend/src/components/ProgressionGraphEditor.jsx
index 4c1bedc..1c71a24 100644
--- a/frontend/src/components/ProgressionGraphEditor.jsx
+++ b/frontend/src/components/ProgressionGraphEditor.jsx
@@ -5,22 +5,37 @@ import React, { useCallback, useEffect, useMemo, useState } from 'react'
 import { Link } from 'react-router-dom'
 import api from '../utils/api'
 import ExercisePickerModal from './ExercisePickerModal'
+import ExerciseGapFillPrepModal from './exercises/ExerciseGapFillPrepModal'
 import ProgressionSlotCard from './ProgressionSlotCard'
 import ProgressionFindingsPanel from './ProgressionFindingsPanel'
 import {
-  applyGapOfferToSlot,
+  aiPreviewToQuickCreateDraft,
+  buildQuickCreateAiPreview,
+} from '../utils/exerciseAiQuickCreate'
+import {
+  buildPathGapPlanningContextForAi,
+  gapOfferContextDisplayLines,
+  initialStageLearningGoalFromOffer,
+} from '../utils/planningContextForExerciseAi'
+import {
+  addSlotToDraft,
+  applyGapOfferToDraft,
   applyMatchStepsToSlots,
-  buildPlanningArtifactFromDraft,
+  collectGapOffersFromApiResponse,
   hydrateProgressionGraphDraft,
+  insertSlotInDraft,
   librarySlotExercise,
   majorStepsToOverridePayload,
-  reindexMajorSteps,
+  moveSlotInDraft,
+  patchSlotInDraft,
+  removeSlotFromDraft,
   saveProgressionGraphDraft,
+  SLOT_MAX,
+  slotsAsPathStepRows,
   slotsToEvaluateSteps,
+  syncProgressionRoadmapFromSlots,
 } from '../utils/progressionGraphDraft'
 
-const ROADMAP_PHASES = ['einstieg', 'grundlage', 'vertiefung', 'anwendung', 'perfektion']
-
 function roadmapStructuredPayload(startSituation, targetState, roadmapNotes) {
   const body = {}
   const start = (startSituation || '').trim()
@@ -32,6 +47,16 @@ function roadmapStructuredPayload(startSituation, targetState, roadmapNotes) {
   return body
 }
 
+function resolveDefaultFocusAreaId(targetSummary, focusAreas) {
+  const targetName = targetSummary?.focus_areas?.[0]
+  if (targetName && Array.isArray(focusAreas) && focusAreas.length) {
+    const norm = String(targetName).trim().toLowerCase()
+    const hit = focusAreas.find((fa) => String(fa.name || '').trim().toLowerCase() === norm)
+    if (hit?.id) return Number(hit.id)
+  }
+  return focusAreas?.[0]?.id ? Number(focusAreas[0].id) : null
+}
+
 export default function ProgressionGraphEditor({ graphId }) {
   const [graphMeta, setGraphMeta] = useState(null)
   const [draft, setDraft] = useState(null)
@@ -44,6 +69,20 @@ export default function ProgressionGraphEditor({ graphId }) {
   const [evaluating, setEvaluating] = useState(false)
   const [matching, setMatching] = useState(false)
   const [roadmapLoading, setRoadmapLoading] = useState(false)
+  const [semanticBrief, setSemanticBrief] = useState(null)
+  const [targetSummary, setTargetSummary] = useState(null)
+  const [focusAreas, setFocusAreas] = useState([])
+
+  const [activeOffer, setActiveOffer] = useState(null)
+  const [activeOfferSlotIndex, setActiveOfferSlotIndex] = useState(null)
+  const [gapPrepOpen, setGapPrepOpen] = useState(false)
+  const [gapPrepTitle, setGapPrepTitle] = useState('')
+  const [gapPrepStageGoal, setGapPrepStageGoal] = useState('')
+  const [gapPrepSupplements, setGapPrepSupplements] = useState('')
+  const [gapPrepFocusAreaId, setGapPrepFocusAreaId] = useState('')
+  const [gapPrepError, setGapPrepError] = useState('')
+  const [generatingOfferId, setGeneratingOfferId] = useState(null)
+  const [gapAiBusy, setGapAiBusy] = useState(false)
 
   const loadGraph = useCallback(async () => {
     if (!graphId) return
@@ -76,6 +115,21 @@ export default function ProgressionGraphEditor({ graphId }) {
     loadGraph()
   }, [loadGraph])
 
+  useEffect(() => {
+    let cancelled = false
+    api
+      .listFocusAreas({ status: 'active' })
+      .then((fa) => {
+        if (!cancelled) setFocusAreas(Array.isArray(fa) ? fa : [])
+      })
+      .catch(() => {
+        if (!cancelled) setFocusAreas([])
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [])
+
   const patchDraft = useCallback((patchFn) => {
     setDraft((prev) => {
       if (!prev) return prev
@@ -84,6 +138,21 @@ export default function ProgressionGraphEditor({ graphId }) {
     })
   }, [])
 
+  const gapContextParams = useMemo(() => {
+    if (!draft) return {}
+    return {
+      goalQuery: draft.goalQuery,
+      semanticBrief,
+      graphId,
+      pathSteps: slotsAsPathStepRows(draft),
+      editableMajorSteps: draft.majorSteps,
+      progressionRoadmap: draft.progressionRoadmap,
+      startSituation: draft.startSituation,
+      targetState: draft.targetState,
+      roadmapNotes: draft.roadmapNotes,
+    }
+  }, [draft, semanticBrief, graphId])
+
   const handlePickExercise = async (exercise) => {
     if (!pickContext || !exercise?.id) return
     const { slotIndex, role } = pickContext
@@ -99,27 +168,68 @@ export default function ProgressionGraphEditor({ graphId }) {
         if (!siblings.some((x) => x.exerciseId === entry.exerciseId)) siblings.push(entry)
         return { ...s, siblings }
       })
-      return { ...d, slots }
+      return syncProgressionRoadmapFromSlots({ ...d, slots })
     })
     setPickContext(null)
   }
 
   const handlePatchLearningGoal = (slotIndex, value) => {
-    patchDraft((d) => {
-      const slots = d.slots.map((s, i) => (i === slotIndex ? { ...s, learning_goal: value } : s))
-      const majorSteps = reindexMajorSteps(
-        (d.majorSteps || []).map((m, i) => (i === slotIndex ? { ...m, learning_goal: value } : m)),
-      )
-      return { ...d, slots, majorSteps }
-    })
+    patchDraft((d) => patchSlotInDraft(d, slotIndex, { learning_goal: value }))
+  }
+
+  const handlePatchPhase = (slotIndex, value) => {
+    patchDraft((d) => patchSlotInDraft(d, slotIndex, { phase: value }))
+  }
+
+  const handleMoveSlot = (slotIndex, dir) => {
+    patchDraft((d) => moveSlotInDraft(d, slotIndex, dir))
+  }
+
+  const handleRemoveSlot = (slotIndex) => {
+    if ((draft?.slots?.length || 0) <= 2) {
+      alert('Mindestens zwei Slots müssen bleiben.')
+      return
+    }
+    if (!window.confirm(`Slot ${slotIndex + 1} wirklich entfernen?`)) return
+    patchDraft((d) => removeSlotFromDraft(d, slotIndex))
+  }
+
+  const handleInsertAfter = (slotIndex) => {
+    if ((draft?.slots?.length || 0) >= SLOT_MAX) {
+      alert(`Maximal ${SLOT_MAX} Slots.`)
+      return
+    }
+    patchDraft((d) => insertSlotInDraft(d, slotIndex))
+  }
+
+  const handleAddSlot = () => {
+    if ((draft?.slots?.length || 0) >= SLOT_MAX) {
+      alert(`Maximal ${SLOT_MAX} Slots.`)
+      return
+    }
+    patchDraft((d) => addSlotToDraft(d))
   }
 
   const handleClearPrimary = (slotIndex) => {
     patchDraft((d) => {
       const slots = d.slots.map((s, i) =>
-        i === slotIndex ? { ...s, primary: { kind: 'empty', exerciseId: null, variantId: null, exerciseTitle: '', variantName: null, proposalKey: null, aiSuggestion: null }, siblings: [] } : s,
+        i === slotIndex
+          ? {
+              ...s,
+              primary: {
+                kind: 'empty',
+                exerciseId: null,
+                variantId: null,
+                exerciseTitle: '',
+                variantName: null,
+                proposalKey: null,
+                aiSuggestion: null,
+              },
+              siblings: [],
+            }
+          : s,
       )
-      return { ...d, slots }
+      return syncProgressionRoadmapFromSlots({ ...d, slots })
     })
   }
 
@@ -133,48 +243,18 @@ export default function ProgressionGraphEditor({ graphId }) {
     })
   }
 
-  const handleAddSlot = () => {
-    patchDraft((d) => {
-      const idx = d.slots.length
-      const phase = ROADMAP_PHASES[Math.min(idx, ROADMAP_PHASES.length - 1)]
-      const slot = {
-        majorStepIndex: idx,
-        phase,
-        learning_goal: '',
-        consolidates: [],
-        rationale: '',
-        load_profile: [],
-        success_criteria: [],
-        anti_patterns: [],
-        exercise_type: '',
-        primary: { kind: 'empty', exerciseId: null, variantId: null, exerciseTitle: '', variantName: null, proposalKey: null, aiSuggestion: null },
-        siblings: [],
-      }
-      const major = {
-        index: idx,
-        phase,
-        learning_goal: '',
-        consolidates: [],
-        rationale: '',
-        load_profile: [],
-        success_criteria: [],
-        anti_patterns: [],
-        exercise_type: '',
-      }
-      return {
-        ...d,
-        slots: [...d.slots, slot],
-        majorSteps: [...(d.majorSteps || []), major],
-        maxSteps: Math.max(d.maxSteps, idx + 1),
-      }
-    })
-  }
-
   const validMajorSteps = useMemo(() => {
     if (!draft?.slots) return []
     return draft.slots.filter((s) => (s.learning_goal || '').trim().length >= 3)
   }, [draft?.slots])
 
+  const applyApiResponse = (res) => {
+    setSemanticBrief(res?.semantic_brief_summary || null)
+    setTargetSummary(res?.target_profile_summary || null)
+    setPathQa(res?.path_qa || null)
+    setGapFillOffers(collectGapOffersFromApiResponse(res))
+  }
+
   const runRoadmapGenerate = async () => {
     const q = (draft?.goalQuery || '').trim()
     if (q.length < 3) {
@@ -200,26 +280,20 @@ export default function ProgressionGraphEditor({ graphId }) {
       })
       const roadmap = res?.progression_roadmap
       if (!roadmap) throw new Error('Keine Roadmap in der Antwort')
-      const majors = (roadmap?.roadmap?.major_steps || []).map((s, i) => ({
-        index: i,
-        phase: s.phase || ROADMAP_PHASES[Math.min(i, ROADMAP_PHASES.length - 1)],
-        learning_goal: (s.learning_goal || '').trim(),
-        consolidates: Array.isArray(s.consolidates) ? s.consolidates : [],
-        rationale: s.rationale || '',
-        load_profile: [],
-        success_criteria: [],
-        anti_patterns: [],
-        exercise_type: '',
-      }))
       const hydrated = hydrateProgressionGraphDraft({
         artifact: {
-          ...buildPlanningArtifactFromDraft({ ...draft, progressionRoadmap: roadmap }),
+          goal_query: q,
           progression_roadmap: roadmap,
+          start_situation: draft.startSituation,
+          target_state: draft.targetState,
+          roadmap_notes: draft.roadmapNotes,
+          max_steps: (roadmap?.roadmap?.major_steps || []).length || draft.maxSteps,
         },
         edges: [],
         graphName: draft.graphName,
       })
       setDraft({ ...hydrated, goalQuery: q, dirty: true })
+      setSemanticBrief(res?.semantic_brief_summary || null)
     } catch (e) {
       setActionErr(e.message || 'Roadmap-Generierung fehlgeschlagen')
     } finally {
@@ -240,20 +314,11 @@ export default function ProgressionGraphEditor({ graphId }) {
     setMatching(true)
     setActionErr('')
     try {
-      const override = majorStepsToOverridePayload(draft.slots.map((s) => ({
-        index: s.majorStepIndex,
-        phase: s.phase,
-        learning_goal: s.learning_goal,
-        consolidates: s.consolidates,
-        rationale: s.rationale,
-        load_profile: s.load_profile,
-        success_criteria: s.success_criteria,
-        anti_patterns: s.anti_patterns,
-        exercise_type: s.exercise_type,
-      })))
+      const synced = syncProgressionRoadmapFromSlots(draft)
+      const override = majorStepsToOverridePayload(synced.slots)
       const res = await api.suggestProgressionPath({
         query: q,
-        max_steps: validMajorSteps.length,
+        max_steps: synced.slots.length,
         include_llm_intent: true,
         include_path_qa: true,
         include_llm_path_qa: true,
@@ -268,15 +333,14 @@ export default function ProgressionGraphEditor({ graphId }) {
       })
       const next = applyMatchStepsToSlots(
         {
-          ...draft,
-          progressionRoadmap: res?.progression_roadmap || draft.progressionRoadmap,
-          pathSkillExpectations: res?.path_skill_expectations || draft.pathSkillExpectations,
+          ...synced,
+          progressionRoadmap: res?.progression_roadmap || synced.progressionRoadmap,
+          pathSkillExpectations: res?.path_skill_expectations || synced.pathSkillExpectations,
         },
         res?.steps,
       )
       setDraft(next)
-      setPathQa(res?.path_qa || null)
-      setGapFillOffers(Array.isArray(res?.gap_fill_offers) ? res.gap_fill_offers : [])
+      applyApiResponse(res)
     } catch (e) {
       setActionErr(e.message || 'Übungs-Match fehlgeschlagen')
     } finally {
@@ -293,38 +357,24 @@ export default function ProgressionGraphEditor({ graphId }) {
     setEvaluating(true)
     setActionErr('')
     try {
+      const synced = syncProgressionRoadmapFromSlots(draft)
       const override =
-        validMajorSteps.length >= 2
-          ? majorStepsToOverridePayload(
-              draft.slots.map((s) => ({
-                index: s.majorStepIndex,
-                phase: s.phase,
-                learning_goal: s.learning_goal,
-                consolidates: s.consolidates,
-                rationale: s.rationale,
-                load_profile: s.load_profile,
-                success_criteria: s.success_criteria,
-                anti_patterns: s.anti_patterns,
-                exercise_type: s.exercise_type,
-              })),
-            )
-          : undefined
+        validMajorSteps.length >= 2 ? majorStepsToOverridePayload(synced.slots) : undefined
       const res = await api.suggestProgressionPath({
         query: q,
-        max_steps: draft.slots.length || draft.maxSteps || 5,
+        max_steps: synced.slots.length || draft.maxSteps || 5,
         include_path_qa: true,
         include_llm_path_qa: true,
         include_ai_gap_fill: true,
         include_path_reorder: false,
         include_llm_intent: false,
         evaluate_only: true,
-        evaluate_steps: slotsToEvaluateSteps(draft),
+        evaluate_steps: slotsToEvaluateSteps(synced),
         roadmap_override: override,
         progression_graph_id: Number(graphId),
         ...roadmapStructuredPayload(draft.startSituation, draft.targetState, draft.roadmapNotes),
       })
-      setPathQa(res?.path_qa || null)
-      setGapFillOffers(Array.isArray(res?.gap_fill_offers) ? res.gap_fill_offers : [])
+      applyApiResponse(res)
       setDraft((prev) => (prev ? { ...prev, lastFindings: res?.path_qa || null } : prev))
     } catch (e) {
       setActionErr(e.message || 'Bewertung fehlgeschlagen')
@@ -348,14 +398,136 @@ export default function ProgressionGraphEditor({ graphId }) {
     }
   }
 
-  const handleApplyGapOffer = (offer) => {
-    const idx =
-      offer?.roadmap_major_step_index != null ? Number(offer.roadmap_major_step_index) : null
-    if (idx == null || !Number.isFinite(idx)) {
-      alert('Angebot ohne Slot-Zuordnung — bitte manuell zuweisen.')
+  const handleApplyGapOffer = (offer, slotIndex) => {
+    setDraft((prev) => {
+      const next = applyGapOfferToDraft(prev, offer, { slotIndex })
+      return { ...next, dirty: true }
+    })
+    setGapFillOffers((prev) => prev.filter((o) => o.offer_id !== offer?.offer_id))
+  }
+
+  const handleInsertGapSlot = (offer) => {
+    if ((draft?.slots?.length || 0) >= SLOT_MAX) {
+      alert(`Maximal ${SLOT_MAX} Slots — zuerst einen Slot entfernen.`)
       return
     }
-    setDraft((prev) => applyGapOfferToSlot(prev, idx, offer))
+    setDraft((prev) => {
+      const next = applyGapOfferToDraft(prev, offer, { insertNewSlot: true })
+      return { ...next, dirty: true }
+    })
+    setGapFillOffers((prev) => prev.filter((o) => o.offer_id !== offer?.offer_id))
+  }
+
+  const openGapFillPrep = (offer, slotIndex = null) => {
+    const defaultFocus = resolveDefaultFocusAreaId(targetSummary, focusAreas)
+    setActiveOffer(offer)
+    setActiveOfferSlotIndex(slotIndex)
+    setGapPrepTitle((offer?.title_hint || '').trim())
+    setGapPrepStageGoal(initialStageLearningGoalFromOffer(offer, gapContextParams))
+    setGapPrepSupplements('')
+    setGapPrepFocusAreaId(defaultFocus ? String(defaultFocus) : '')
+    setGapPrepError('')
+    setGapPrepOpen(true)
+  }
+
+  const runGapFillAiSuggest = async (offer, prep, slotIndex) => {
+    const title = (prep?.title || offer?.title_hint || '').trim()
+    if (title.length < 3) {
+      alert('Titel: mindestens 3 Zeichen.')
+      return
+    }
+    const supplements = (prep?.supplements || '').trim()
+    const stageGoal = (prep?.stageLearningGoal || '').trim()
+    let goalText = (offer?.goal_for_ai || offer?.sketch || '').trim()
+    if (supplements) {
+      goalText = `${goalText}\n\nTrainer-Ergänzungen:\n${supplements}`.trim()
+    }
+    const focusId =
+      prep?.focusAreaId != null && Number.isFinite(Number(prep.focusAreaId))
+        ? Number(prep.focusAreaId)
+        : resolveDefaultFocusAreaId(targetSummary, focusAreas)
+    if (!focusId) {
+      alert('Bitte einen Fokusbereich wählen.')
+      return
+    }
+    const focusRow = (focusAreas || []).find((x) => Number(x.id) === focusId)
+    const focusHint = (focusRow?.name || offer?.primary_topic || '').trim()
+
+    setGapAiBusy(true)
+    setGeneratingOfferId(offer?.offer_id || null)
+    setGapPrepError('')
+    try {
+      const planningContext = buildPathGapPlanningContextForAi({
+        offer,
+        ...gapContextParams,
+        stageLearningGoalOverride: stageGoal,
+        gapTrainerSupplements: supplements,
+      })
+      const aiRes = await api.suggestExerciseAi({
+        title,
+        goal: goalText || undefined,
+        execution: '',
+        preparation: '',
+        trainer_notes: supplements || '',
+        focus_area_hint: focusHint || undefined,
+        focus_areas_context: [{ focus_area_id: focusId, is_primary: true }],
+        planning_context: planningContext || undefined,
+        include_summary: true,
+        include_skills: true,
+        include_instructions: true,
+      })
+      const preview = buildQuickCreateAiPreview(aiRes, { sketchPlain: goalText })
+      if (!preview.hasSummaryProposal && !preview.hasInstructionChoices && !preview.hasSkillChoices) {
+        throw new Error('Die KI lieferte keinen verwertbaren Vorschlag.')
+      }
+      const aiDraft = aiPreviewToQuickCreateDraft(preview, {
+        title,
+        focusAreaId: focusId,
+        sketchPlain: goalText,
+      })
+      const enrichedOffer = {
+        ...offer,
+        proposal_title: title,
+        ai_suggestion: aiDraft,
+        has_ai_payload: true,
+      }
+      setDraft((prev) => {
+        const next = applyGapOfferToDraft(prev, enrichedOffer, { slotIndex })
+        return { ...next, dirty: true }
+      })
+      setGapFillOffers((prev) => prev.filter((o) => o.offer_id !== offer?.offer_id))
+      setGapPrepOpen(false)
+      setActiveOffer(null)
+    } catch (e) {
+      setGapPrepError(e.message || 'KI-Anlage fehlgeschlagen')
+    } finally {
+      setGapAiBusy(false)
+      setGeneratingOfferId(null)
+    }
+  }
+
+  const submitGapFillPrep = async () => {
+    const title = (gapPrepTitle || '').trim()
+    if (title.length < 3) {
+      alert('Titel: mindestens 3 Zeichen.')
+      return
+    }
+    const focusId = parseInt(String(gapPrepFocusAreaId).trim(), 10)
+    if (!Number.isFinite(focusId) || focusId < 1) {
+      alert('Bitte einen Fokusbereich wählen.')
+      return
+    }
+    if (!activeOffer) return
+    await runGapFillAiSuggest(
+      activeOffer,
+      {
+        title,
+        stageLearningGoal: (gapPrepStageGoal || '').trim(),
+        supplements: (gapPrepSupplements || '').trim(),
+        focusAreaId: focusId,
+      },
+      activeOfferSlotIndex,
+    )
   }
 
   if (loadErr) {
@@ -385,7 +557,7 @@ export default function ProgressionGraphEditor({ graphId }) {
             {graphMeta?.name || draft.graphName || `Graph #${graphId}`}
           </h2>
           <p style={{ margin: '4px 0 0', fontSize: '12px', color: 'var(--text3)' }}>
-            Slot-Editor · Roadmap = Struktur · ein Primärpfad + Schwestern
+            Slots verschieben, ergänzen · KI-Angebote zuordnen · dynamisch erweitern (max. {SLOT_MAX})
           </p>
         </div>
         <Link to="/exercises" className="btn btn-secondary" style={{ fontSize: '12px' }}>
@@ -403,7 +575,7 @@ export default function ProgressionGraphEditor({ graphId }) {
         className="progression-graph-editor-grid"
         style={{
           display: 'grid',
-          gridTemplateColumns: 'minmax(0, 1fr) minmax(260px, 320px)',
+          gridTemplateColumns: 'minmax(0, 1fr) minmax(280px, 340px)',
           gap: '14px',
           alignItems: 'start',
         }}
@@ -472,22 +644,34 @@ export default function ProgressionGraphEditor({ graphId }) {
 
           <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: '8px' }}>
             <h3 style={{ margin: 0, fontSize: '1rem' }}>Slots ({draft.slots.length})</h3>
-            <button type="button" className="btn btn-secondary" style={{ fontSize: '12px' }} disabled={busy || draft.slots.length >= 10} onClick={handleAddSlot}>
-              Slot hinzufügen
+            <button
+              type="button"
+              className="btn btn-secondary"
+              style={{ fontSize: '12px' }}
+              disabled={busy || draft.slots.length >= SLOT_MAX}
+              onClick={handleAddSlot}
+            >
+              Slot am Ende
             </button>
           </div>
 
           {draft.slots.map((slot, idx) => (
             <ProgressionSlotCard
-              key={`slot-${slot.majorStepIndex}-${idx}`}
+              key={`slot-${idx}-${slot.learning_goal?.slice(0, 12) || 'x'}`}
               slot={slot}
               slotIndex={idx}
+              slotCount={draft.slots.length}
               disabled={busy}
               onPickPrimary={(i) => setPickContext({ slotIndex: i, role: 'primary' })}
               onPickSibling={(i) => setPickContext({ slotIndex: i, role: 'sibling' })}
               onClearPrimary={handleClearPrimary}
               onRemoveSibling={handleRemoveSibling}
               onPatchLearningGoal={handlePatchLearningGoal}
+              onPatchPhase={handlePatchPhase}
+              onMoveUp={(i) => handleMoveSlot(i, -1)}
+              onMoveDown={(i) => handleMoveSlot(i, 1)}
+              onRemoveSlot={handleRemoveSlot}
+              onInsertAfter={handleInsertAfter}
             />
           ))}
         </div>
@@ -495,10 +679,16 @@ export default function ProgressionGraphEditor({ graphId }) {
         <ProgressionFindingsPanel
           pathQa={pathQa}
           gapFillOffers={gapFillOffers}
+          draft={draft}
+          slotCount={draft.slots.length}
           loading={evaluating}
-          error={evaluating ? '' : ''}
+          error=""
           onEvaluate={runEvaluate}
           onApplyGapOffer={handleApplyGapOffer}
+          onInsertGapSlot={handleInsertGapSlot}
+          onGenerateGapAi={openGapFillPrep}
+          generatingOfferId={generatingOfferId}
+          aiBusy={gapAiBusy}
           evaluateDisabled={busy || !draft.goalQuery?.trim()}
         />
       </div>
@@ -511,6 +701,29 @@ export default function ProgressionGraphEditor({ graphId }) {
         />
       ) : null}
 
+      <ExerciseGapFillPrepModal
+        open={gapPrepOpen}
+        offer={activeOffer}
+        onClose={() => {
+          if (gapAiBusy) return
+          setGapPrepOpen(false)
+          setGapPrepError('')
+        }}
+        title={gapPrepTitle}
+        onTitleChange={setGapPrepTitle}
+        stageLearningGoal={gapPrepStageGoal}
+        onStageLearningGoalChange={setGapPrepStageGoal}
+        supplements={gapPrepSupplements}
+        onSupplementsChange={setGapPrepSupplements}
+        focusAreaId={gapPrepFocusAreaId}
+        onFocusAreaChange={setGapPrepFocusAreaId}
+        focusAreas={focusAreas}
+        contextLines={gapOfferContextDisplayLines(activeOffer, gapContextParams)}
+        error={gapPrepError}
+        busy={gapAiBusy}
+        onSubmit={submitGapFillPrep}
+      />
+
       <style>{`
         @media (max-width: 900px) {
           .progression-graph-editor-grid {
diff --git a/frontend/src/components/ProgressionSlotCard.jsx b/frontend/src/components/ProgressionSlotCard.jsx
index 51fcaf0..3f02399 100644
--- a/frontend/src/components/ProgressionSlotCard.jsx
+++ b/frontend/src/components/ProgressionSlotCard.jsx
@@ -3,6 +3,7 @@
  */
 import React from 'react'
 import { Link } from 'react-router-dom'
+import { ROADMAP_PHASES } from '../utils/progressionGraphDraft'
 
 function exerciseLabel(entry) {
   if (!entry || entry.kind === 'empty') return '— noch leer —'
@@ -13,11 +14,17 @@ function exerciseLabel(entry) {
 export default function ProgressionSlotCard({
   slot,
   slotIndex,
+  slotCount = 1,
   onPickPrimary,
   onPickSibling,
   onClearPrimary,
   onRemoveSibling,
   onPatchLearningGoal,
+  onPatchPhase,
+  onMoveUp,
+  onMoveDown,
+  onRemoveSlot,
+  onInsertAfter,
   disabled = false,
 }) {
   const { primary, siblings = [], phase, learning_goal: learningGoal } = slot
@@ -34,31 +41,77 @@ export default function ProgressionSlotCard({
     >
       <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start', gap: '8px', flexWrap: 'wrap' }}>
         <div>
-          <h4 style={{ margin: 0, fontSize: '0.95rem' }}>
-            Slot {slotIndex + 1}
-            {phase ? <span style={{ color: 'var(--text3)', fontWeight: 400 }}>{` · ${phase}`}</span> : null}
-          </h4>
+          <h4 style={{ margin: 0, fontSize: '0.95rem' }}>Slot {slotIndex + 1}</h4>
+        </div>
+        <div style={{ display: 'flex', gap: '4px', flexWrap: 'wrap', alignItems: 'center' }}>
+          <span
+            className="exercise-tag"
+            style={{
+              fontSize: '11px',
+              borderColor: primary.kind === 'proposal' ? 'var(--danger)' : undefined,
+            }}
+          >
+            {primary.kind === 'empty' ? 'leer' : primary.kind === 'proposal' ? 'KI-Entwurf' : 'Bibliothek'}
+          </span>
+          <button
+            type="button"
+            className="btn"
+            style={{ fontSize: '11px', padding: '2px 6px' }}
+            disabled={disabled || slotIndex === 0}
+            onClick={() => onMoveUp(slotIndex)}
+            title="Nach oben"
+          >
+            ↑
+          </button>
+          <button
+            type="button"
+            className="btn"
+            style={{ fontSize: '11px', padding: '2px 6px' }}
+            disabled={disabled || slotIndex >= slotCount - 1}
+            onClick={() => onMoveDown(slotIndex)}
+            title="Nach unten"
+          >
+            ↓
+          </button>
+          <button
+            type="button"
+            className="btn"
+            style={{ fontSize: '11px', padding: '2px 6px' }}
+            disabled={disabled || slotCount <= 2}
+            onClick={() => onRemoveSlot(slotIndex)}
+            title="Slot entfernen"
+          >
+            ✕
+          </button>
         </div>
-        <span
-          className="exercise-tag"
-          style={{
-            fontSize: '11px',
-            borderColor: primary.kind === 'proposal' ? 'var(--danger)' : undefined,
-          }}
-        >
-          {primary.kind === 'empty' ? 'leer' : primary.kind === 'proposal' ? 'KI-Entwurf' : 'Bibliothek'}
-        </span>
       </div>
 
-      <div className="form-row" style={{ marginTop: '10px', marginBottom: '8px' }}>
-        <label className="form-label">Lernziel (Major Step)</label>
-        <input
-          className="form-input"
-          value={learningGoal || ''}
-          disabled={disabled}
-          onChange={(e) => onPatchLearningGoal(slotIndex, e.target.value)}
-          placeholder="Was soll in dieser Stufe erreicht werden?"
-        />
+      <div className="form-row" style={{ marginTop: '10px', marginBottom: '8px', display: 'grid', gridTemplateColumns: '1fr 140px', gap: '8px' }}>
+        <div>
+          <label className="form-label">Lernziel (Major Step)</label>
+          <input
+            className="form-input"
+            value={learningGoal || ''}
+            disabled={disabled}
+            onChange={(e) => onPatchLearningGoal(slotIndex, e.target.value)}
+            placeholder="Was soll in dieser Stufe erreicht werden?"
+          />
+        </div>
+        <div>
+          <label className="form-label">Phase</label>
+          <select
+            className="form-input"
+            value={phase || 'vertiefung'}
+            disabled={disabled}
+            onChange={(e) => onPatchPhase(slotIndex, e.target.value)}
+          >
+            {ROADMAP_PHASES.map((p) => (
+              <option key={p} value={p}>
+                {p}
+              </option>
+            ))}
+          </select>
+        </div>
       </div>
 
       <div
@@ -144,16 +197,27 @@ export default function ProgressionSlotCard({
             ))}
           </ul>
         )}
-        <button
-          type="button"
-          className="btn btn-secondary"
-          style={{ fontSize: '12px', padding: '4px 10px' }}
-          disabled={disabled || primary.kind !== 'library'}
-          onClick={() => onPickSibling(slotIndex)}
-          title={primary.kind !== 'library' ? 'Zuerst eine Hauptübung wählen' : undefined}
-        >
-          Schwester hinzufügen
-        </button>
+        <div style={{ display: 'flex', gap: '6px', flexWrap: 'wrap' }}>
+          <button
+            type="button"
+            className="btn btn-secondary"
+            style={{ fontSize: '12px', padding: '4px 10px' }}
+            disabled={disabled || primary.kind !== 'library'}
+            onClick={() => onPickSibling(slotIndex)}
+            title={primary.kind !== 'library' ? 'Zuerst eine Hauptübung wählen' : undefined}
+          >
+            Schwester hinzufügen
+          </button>
+          <button
+            type="button"
+            className="btn"
+            style={{ fontSize: '12px', padding: '4px 10px' }}
+            disabled={disabled || slotCount >= 10}
+            onClick={() => onInsertAfter(slotIndex)}
+          >
+            Slot darunter einfügen
+          </button>
+        </div>
       </div>
     </div>
   )
diff --git a/frontend/src/utils/progressionGraphDraft.js b/frontend/src/utils/progressionGraphDraft.js
index 8470ec6..af43fc9 100644
--- a/frontend/src/utils/progressionGraphDraft.js
+++ b/frontend/src/utils/progressionGraphDraft.js
@@ -2,9 +2,191 @@
  * Progressionsgraph Slot-Editor — Draft-Hydration und Speichern (Phase B).
  */
 
-const ROADMAP_PHASES = ['einstieg', 'grundlage', 'vertiefung', 'anwendung', 'perfektion']
+export const ROADMAP_PHASES = ['einstieg', 'grundlage', 'vertiefung', 'anwendung', 'perfektion']
+export const SLOT_MAX = 10
 export const PLANNING_ARTIFACT_SCHEMA = 1
 
+const OFFER_SOURCE_LABELS = {
+  unfilled_gap: 'Lücke',
+  off_topic: 'Themenfremd',
+  llm_suggested: 'QS-Empfehlung',
+  roadmap_unfilled: 'Roadmap-Stufe',
+}
+
+export function offerSourceLabel(source) {
+  return OFFER_SOURCE_LABELS[source] || source || 'Angebot'
+}
+
+function createEmptySlot(index) {
+  const phase = ROADMAP_PHASES[Math.min(index, ROADMAP_PHASES.length - 1)]
+  return {
+    majorStepIndex: index,
+    phase,
+    learning_goal: '',
+    consolidates: [],
+    rationale: '',
+    load_profile: [],
+    success_criteria: [],
+    anti_patterns: [],
+    exercise_type: '',
+    primary: emptySlotExercise(),
+    siblings: [],
+  }
+}
+
+function majorStepFromSlot(slot, index) {
+  return {
+    index,
+    phase: slot.phase || ROADMAP_PHASES[Math.min(index, ROADMAP_PHASES.length - 1)],
+    learning_goal: slot.learning_goal || '',
+    consolidates: slot.consolidates || [],
+    rationale: slot.rationale || '',
+    load_profile: slot.load_profile || [],
+    success_criteria: slot.success_criteria || [],
+    anti_patterns: slot.anti_patterns || [],
+    exercise_type: slot.exercise_type || '',
+  }
+}
+
+export function reindexSlots(slots) {
+  return (slots || []).map((slot, i) => ({
+    ...slot,
+    majorStepIndex: i,
+    primary: { ...slot.primary },
+    siblings: [...(slot.siblings || [])],
+  }))
+}
+
+/** progression_roadmap aus aktuellen Slots ableiten (nach Verschieben/Hinzufügen). */
+export function syncProgressionRoadmapFromSlots(draft) {
+  const slots = reindexSlots(draft.slots || [])
+  const existing = draft.progressionRoadmap || {}
+  const major_steps = slots.map((s, i) => ({
+    index: i,
+    phase: s.phase || 'vertiefung',
+    learning_goal: (s.learning_goal || '').trim(),
+    consolidates: s.consolidates || [],
+    rationale: s.rationale || '',
+  }))
+  const stage_specs = slots.map((s, i) => ({
+    major_step_index: i,
+    learning_goal: (s.learning_goal || '').trim(),
+    load_profile: Array.isArray(s.load_profile) ? s.load_profile : [],
+    exercise_type: (s.exercise_type || '').trim(),
+    success_criteria: Array.isArray(s.success_criteria) ? s.success_criteria : [],
+    anti_patterns: Array.isArray(s.anti_patterns) ? s.anti_patterns : [],
+  }))
+  return {
+    ...draft,
+    slots,
+    majorSteps: slots.map(majorStepFromSlot),
+    maxSteps: slots.length,
+    progressionRoadmap: {
+      ...existing,
+      major_step_count: slots.length,
+      max_steps: slots.length,
+      roadmap: { ...(existing.roadmap || {}), major_steps },
+      stage_specs,
+    },
+  }
+}
+
+export function moveSlotInDraft(draft, slotIndex, direction) {
+  const slots = [...(draft.slots || [])]
+  const j = slotIndex + direction
+  if (j < 0 || j >= slots.length) return draft
+  const tmp = slots[slotIndex]
+  slots[slotIndex] = slots[j]
+  slots[j] = tmp
+  return syncProgressionRoadmapFromSlots({ ...draft, slots, dirty: true })
+}
+
+export function removeSlotFromDraft(draft, slotIndex) {
+  const slots = draft.slots || []
+  if (slots.length <= 2) return draft
+  const next = slots.filter((_, i) => i !== slotIndex)
+  return syncProgressionRoadmapFromSlots({ ...draft, slots: next, dirty: true })
+}
+
+export function insertSlotInDraft(draft, afterIndex, partial = {}) {
+  const slots = [...(draft.slots || [])]
+  if (slots.length >= SLOT_MAX) return draft
+  const insertAt = afterIndex < 0 ? 0 : Math.min(afterIndex + 1, slots.length)
+  const newSlot = {
+    ...createEmptySlot(insertAt),
+    ...partial,
+    primary: partial.primary || emptySlotExercise(),
+    siblings: partial.siblings || [],
+  }
+  slots.splice(insertAt, 0, newSlot)
+  return syncProgressionRoadmapFromSlots({ ...draft, slots, dirty: true })
+}
+
+export function addSlotToDraft(draft) {
+  const slots = draft.slots || []
+  if (slots.length >= SLOT_MAX) return draft
+  return syncProgressionRoadmapFromSlots({
+    ...draft,
+    slots: [...slots, createEmptySlot(slots.length)],
+    dirty: true,
+  })
+}
+
+export function patchSlotInDraft(draft, slotIndex, patch) {
+  const slots = (draft.slots || []).map((s, i) => (i === slotIndex ? { ...s, ...patch } : s))
+  return syncProgressionRoadmapFromSlots({ ...draft, slots, dirty: true })
+}
+
+export function resolveOfferSlotIndex(draft, offer) {
+  if (offer?.roadmap_major_step_index != null && Number.isFinite(Number(offer.roadmap_major_step_index))) {
+    return Number(offer.roadmap_major_step_index)
+  }
+  if (offer?.replace_step_index != null && Number.isFinite(Number(offer.replace_step_index))) {
+    return Number(offer.replace_step_index)
+  }
+  if (offer?.insert_after_index != null && Number.isFinite(Number(offer.insert_after_index))) {
+    const after = Number(offer.insert_after_index)
+    if (offer.source === 'roadmap_unfilled') return after + 1
+    return Math.min(after + 1, (draft.slots?.length || 1) - 1)
+  }
+  return null
+}
+
+export function offerNeedsNewSlot(offer) {
+  return offer?.source === 'unfilled_gap' || offer?.source === 'llm_suggested'
+}
+
+export function offerCanExpandSlots(draft, offer) {
+  if (!offerNeedsNewSlot(offer)) return false
+  return (draft.slots?.length || 0) < SLOT_MAX
+}
+
+export function collectGapOffersFromApiResponse(res) {
+  const qa = res?.path_qa || {}
+  const merged = [
+    ...(Array.isArray(res?.gap_fill_offers) ? res.gap_fill_offers : []),
+    ...(Array.isArray(qa?.gap_fill_offers) ? qa.gap_fill_offers : []),
+  ]
+  const seen = new Set()
+  return merged.filter((offer) => {
+    const key = offer?.offer_id || `${offer?.source}-${offer?.title_hint}`
+    if (!key || seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+}
+
+export function slotsAsPathStepRows(draft) {
+  return (draft.slots || []).map((slot) => ({
+    exerciseId: slot.primary?.exerciseId ?? null,
+    exerciseTitle: slot.primary?.exerciseTitle || '',
+    roadmapMajorStepIndex: slot.majorStepIndex,
+    roadmapPhase: slot.phase,
+    roadmapLearningGoal: slot.learning_goal,
+    isAiProposal: slot.primary?.kind === 'proposal',
+  }))
+}
+
 export function emptySlotExercise() {
   return {
     kind: 'empty',
@@ -487,34 +669,74 @@ export function applyMatchStepsToSlots(draft, apiSteps) {
     }
   }
 
-  return { ...draft, slots: nextSlots, dirty: true }
+  return syncProgressionRoadmapFromSlots({ ...draft, slots: nextSlots, dirty: true })
 }
 
 export function applyGapOfferToSlot(draft, slotIndex, offer, aiSuggestion = null) {
   const nextSlots = (draft.slots || []).map((s) => ({ ...s, primary: { ...s.primary }, siblings: [...(s.siblings || [])] }))
   if (slotIndex < 0 || slotIndex >= nextSlots.length) return draft
+  const title =
+    offer?.proposal_title ||
+    offer?.title_hint ||
+    offer?.title ||
+    nextSlots[slotIndex].learning_goal ||
+    'KI-Vorschlag'
   nextSlots[slotIndex].primary = proposalSlotExercise({
-    title: offer?.title_hint || offer?.title || 'KI-Vorschlag',
-    proposalKey: offer?.offer_id || offer?.proposal_key,
+    title,
+    proposalKey: offer?.proposal_key || offer?.offer_id || null,
     aiSuggestion: aiSuggestion || offer?.ai_suggestion || null,
   })
-  return { ...draft, slots: nextSlots, dirty: true }
+  return syncProgressionRoadmapFromSlots({ ...draft, slots: nextSlots, dirty: true })
+}
+
+/**
+ * Angebot einem Slot zuordnen — optional neuen Slot einfügen (Brücke / QS-Neuanlage).
+ */
+export function applyGapOfferToDraft(draft, offer, { slotIndex = null, insertNewSlot = false } = {}) {
+  let next = { ...draft }
+  if (insertNewSlot && offerNeedsNewSlot(offer)) {
+    const afterIdx = Number(offer?.insert_after_index)
+    if (Number.isFinite(afterIdx)) {
+      if ((next.slots?.length || 0) >= SLOT_MAX) return next
+      next = insertSlotInDraft(next, afterIdx, {
+        learning_goal: (offer?.title_hint || offer?.sketch || '').trim().split('\n')[0] || '',
+        phase: offer?.phase || offer?.gap?.expected_phase || 'vertiefung',
+      })
+      slotIndex = afterIdx + 1
+    }
+  }
+  const idx = slotIndex != null ? slotIndex : resolveOfferSlotIndex(next, offer)
+  if (idx == null || !Number.isFinite(idx) || idx < 0 || idx >= (next.slots?.length || 0)) {
+    return next
+  }
+  return applyGapOfferToSlot(next, idx, offer)
 }
 
 export async function saveProgressionGraphDraft(api, graphId, draft) {
-  const primarySteps = draftPrimaryChainSteps(draft)
-  const siblingPairs = draftSiblingEdgePairs(draft)
-  const artifact = buildPlanningArtifactFromDraft(draft)
-  const edgeIds = [
-    ...(draft.primaryChainEdgeIds || []),
-    ...(draft.siblingEdgeIds || []),
-  ].filter((id) => Number.isFinite(Number(id)))
+  const synced = syncProgressionRoadmapFromSlots(draft)
+  const primarySteps = draftPrimaryChainSteps(synced)
+  const siblingPairs = draftSiblingEdgePairs(synced)
+  const artifact = buildPlanningArtifactFromDraft(synced)
 
-  if (edgeIds.length > 0) {
-    await api.deleteExerciseProgressionEdgesBatch(Number(graphId), edgeIds)
-  }
+  // Kanten frisch laden — hydrate-Arrays können nach Zwischen-Speichern veraltet sein.
+  const currentEdges = await api.listExerciseProgressionEdges(Number(graphId))
+  const nextEdgeIds = (currentEdges || [])
+    .filter((e) => (e.edge_type || 'next_exercise') === 'next_exercise')
+    .map((e) => e.id)
+    .filter((id) => Number.isFinite(Number(id)))
+  const siblingEdgeIds = (currentEdges || [])
+    .filter((e) => e.edge_type === 'sibling')
+    .map((e) => e.id)
+    .filter((id) => Number.isFinite(Number(id)))
 
+  let artifactPersisted = false
+
+  // Primärkette nur ersetzen, wenn mindestens zwei Bibliotheks-Übungen im Pfad sind.
+  // Sonst bestehende next_exercise-Kanten erhalten (nur Artefakt/Slots speichern).
   if (primarySteps.length >= 2) {
+    if (nextEdgeIds.length > 0) {
+      await api.deleteExerciseProgressionEdgesBatch(Number(graphId), nextEdgeIds)
+    }
     await api.createExerciseProgressionSequence(Number(graphId), {
       steps: primarySteps.map((s) => ({
         exercise_id: s.exerciseId,
@@ -523,10 +745,12 @@ export async function saveProgressionGraphDraft(api, graphId, draft) {
       segment_notes: primarySteps.slice(1).map(() => null),
       ...(artifact ? { planning_roadmap: artifact } : {}),
     })
-  } else if (artifact) {
-    await api.updateExerciseProgressionGraph(Number(graphId), { planning_roadmap: artifact })
+    artifactPersisted = Boolean(artifact)
   }
 
+  if (siblingEdgeIds.length > 0) {
+    await api.deleteExerciseProgressionEdgesBatch(Number(graphId), siblingEdgeIds)
+  }
   for (const pair of siblingPairs) {
     await api.createExerciseProgressionEdge(Number(graphId), {
       from_exercise_id: pair.from.exerciseId,
@@ -537,5 +761,9 @@ export async function saveProgressionGraphDraft(api, graphId, draft) {
     })
   }
 
+  if (artifact && !artifactPersisted) {
+    await api.updateExerciseProgressionGraph(Number(graphId), { planning_roadmap: artifact })
+  }
+
   return { primaryCount: primarySteps.length, siblingCount: siblingPairs.length }
 }

From ee22b229705966c5aafcfc9470d288f0c652af14 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Wed, 10 Jun 2026 15:42:29 +0200
Subject: [PATCH 11/33] Refactor Progression Graph Components and Consolidate
 UI

- Updated the `ProgressionGraphSlotEditorSpec.md` to reflect UI consolidation, removing separate editors and integrating functionalities into `ExerciseProgressionGraphPanel`.
- Refactored `ExerciseProgressionGraphPanel` to streamline the editing experience, removing unused state and logic for better performance.
- Enhanced `ProgressionGraphEditor` to support embedded usage and trigger callbacks on save, improving integration with other components.
- Simplified `ProgressionGraphEditPage` to redirect users to the exercises list with deep-linking support for selected graphs.
- Incremented application version to reflect these updates.
---
 .../PROGRESSION_GRAPH_SLOT_EDITOR_SPEC.md     |  10 +-
 .../ExerciseProgressionGraphPanel.jsx         | 632 ++++--------------
 .../src/components/ProgressionGraphEditor.jsx |  29 +-
 .../src/pages/ProgressionGraphEditPage.jsx    |  24 +-
 4 files changed, 145 insertions(+), 550 deletions(-)

diff --git a/.claude/docs/working/PROGRESSION_GRAPH_SLOT_EDITOR_SPEC.md b/.claude/docs/working/PROGRESSION_GRAPH_SLOT_EDITOR_SPEC.md
index 2a59513..3f5d0cf 100644
--- a/.claude/docs/working/PROGRESSION_GRAPH_SLOT_EDITOR_SPEC.md
+++ b/.claude/docs/working/PROGRESSION_GRAPH_SLOT_EDITOR_SPEC.md
@@ -58,14 +58,16 @@ Zusätzlich optional:
 - `slot_contents[]` — `{ major_step_index, primary, siblings[] }`
 - `last_findings` — letzter `path_qa`-Snapshot
 
-## UI & Routing
+## UI (konsolidiert)
 
-- **B.4:** Route `/progression-graphs/:id` — Slots links, Findings rechts
+- **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 schrittweise
+## Ersetzt (Legacy, nicht mehr im Panel)
 
-- Getrennte `ExerciseProgressionPathBuilder`-Wizard-UI + `ProgressionChainEditor` → integrierter `ProgressionGraphEditor`
+- `ExerciseProgressionPathBuilder` · `ProgressionChainEditor` — Code bleibt vorerst, nicht eingebunden
 
 ## Implementierungsreihenfolge
 
diff --git a/frontend/src/components/ExerciseProgressionGraphPanel.jsx b/frontend/src/components/ExerciseProgressionGraphPanel.jsx
index 330c80a..a8be046 100644
--- a/frontend/src/components/ExerciseProgressionGraphPanel.jsx
+++ b/frontend/src/components/ExerciseProgressionGraphPanel.jsx
@@ -1,16 +1,13 @@
 /**
- * Progressionsgraphen: Sequenz-Editor (mehrere Nachfolger auf einmal), Ketten-Ansicht,
- * Varianten als eigene Knoten-Endpunkte, Schwester-Kanten gesondert, Tabelle als Fallback.
+ * Progressionsgraphen — eine Oberfläche: Graph wählen, Roadmap-Slots bearbeiten, KI & Speichern.
  */
-import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
-import { Link } from 'react-router-dom'
+import React, { useCallback, useEffect, useMemo, useState } from 'react'
+import { Link, useLocation } from 'react-router-dom'
 import api from '../utils/api'
 import SkillProfilePanel from './skills/SkillProfilePanel'
 import { useAuth } from '../context/AuthContext'
 import { getTenantClubDependencyKey } from '../utils/activeClub'
-import ExercisePickerModal from './ExercisePickerModal'
-import ExerciseProgressionPathBuilder from './ExerciseProgressionPathBuilder'
-import ProgressionChainEditor from './ProgressionChainEditor'
+import ProgressionGraphEditor from './ProgressionGraphEditor'
 import { EXERCISE_VISIBILITY_FIELD_LABEL } from '../constants/exerciseGovernanceLabels'
 
 const VIS_OPTIONS = [
@@ -25,83 +22,12 @@ function edgeTypeLabel(type) {
   return type || '—'
 }
 
-/** Maximale lineare Segmente aus next_exercise-Kanten (jedes Segment deckt zusammenhängende „Pfade“ ab). */
-function maximalLinearChains(nextEdges) {
-  if (!nextEdges?.length) return []
-  const outMap = new Map()
-  const inMap = new Map()
-  const nodeKey = (ex, v) => `${ex}:${v ?? ''}`
-
-  for (const e of nextEdges) {
-    const f = nodeKey(e.from_exercise_id, e.from_exercise_variant_id)
-    const t = nodeKey(e.to_exercise_id, e.to_exercise_variant_id)
-    if (!outMap.has(f)) outMap.set(f, [])
-    outMap.get(f).push(e)
-    if (!inMap.has(t)) inMap.set(t, [])
-    inMap.get(t).push(e)
-  }
-
-  const used = new Set()
-  const chains = []
-
-  for (const startEdge of nextEdges) {
-    if (used.has(startEdge.id)) continue
-
-    const edgesSeq = [startEdge]
-
-    let fk = nodeKey(startEdge.from_exercise_id, startEdge.from_exercise_variant_id)
-    while (true) {
-      const preds = inMap.get(fk)
-      if (!preds || preds.length !== 1) break
-      const pred = preds[0]
-      if (used.has(pred.id)) break
-      edgesSeq.unshift(pred)
-      fk = nodeKey(pred.from_exercise_id, pred.from_exercise_variant_id)
-    }
-
-    let tk = nodeKey(startEdge.to_exercise_id, startEdge.to_exercise_variant_id)
-    while (true) {
-      const outs = outMap.get(tk)
-      if (!outs || outs.length !== 1) break
-      const nx = outs[0]
-      if (used.has(nx.id)) break
-      edgesSeq.push(nx)
-      tk = nodeKey(nx.to_exercise_id, nx.to_exercise_variant_id)
-    }
-
-    edgesSeq.forEach((ed) => used.add(ed.id))
-
-    const first = edgesSeq[0]
-    const nodes = [
-      {
-        exercise_id: first.from_exercise_id,
-        variant_id: first.from_exercise_variant_id ?? null,
-        title: first.from_exercise_title,
-        variant_name: first.from_variant_name ?? null,
-      },
-    ]
-    for (const ed of edgesSeq) {
-      nodes.push({
-        exercise_id: ed.to_exercise_id,
-        variant_id: ed.to_exercise_variant_id ?? null,
-        title: ed.to_exercise_title,
-        variant_name: ed.to_variant_name ?? null,
-      })
-    }
-    chains.push({ nodes, edges: edgesSeq })
-  }
-  return chains
-}
-
-function emptyEndpoint() {
-  return { exerciseId: null, exerciseTitle: '', variantId: null, variants: [] }
-}
-
 export default function ExerciseProgressionGraphPanel({
   anchorExerciseId = null,
   anchorTitle = null,
 }) {
   const { user } = useAuth()
+  const location = useLocation()
   const isSuperadmin = user?.role === 'superadmin'
   const tenantClubDepKey = useMemo(() => getTenantClubDependencyKey(user), [user])
 
@@ -123,14 +49,6 @@ export default function ExerciseProgressionGraphPanel({
   const [metaDescription, setMetaDescription] = useState('')
   const [metaVisibility, setMetaVisibility] = useState('private')
 
-  const [pickContext, setPickContext] = useState(null)
-  const chainEditorRef = useRef(null)
-
-  const [relationKind, setRelationKind] = useState('progression')
-  const [firstEp, setFirstEp] = useState(emptyEndpoint)
-  const [secondEp, setSecondEp] = useState(emptyEndpoint)
-  const [edgeNotes, setEdgeNotes] = useState('')
-
   const [filterAnchorOnly, setFilterAnchorOnly] = useState(!!anchorExerciseId)
   const [editingEdgeNotes, setEditingEdgeNotes] = useState(null)
   const [notesDraft, setNotesDraft] = useState('')
@@ -138,6 +56,13 @@ export default function ExerciseProgressionGraphPanel({
   const [skillProfileLoading, setSkillProfileLoading] = useState(false)
   const [skillProfileError, setSkillProfileError] = useState('')
 
+  useEffect(() => {
+    const gid = location.state?.progressionGraphId
+    if (gid != null && Number.isFinite(Number(gid))) {
+      setSelectedGraphId(Number(gid))
+    }
+  }, [location.state?.progressionGraphId])
+
   useEffect(() => {
     setSelectedGraphId(null)
   }, [tenantClubDepKey])
@@ -157,12 +82,6 @@ export default function ExerciseProgressionGraphPanel({
     setEdges(Array.isArray(list) ? list : [])
   }, [])
 
-  const loadVariantsForExercise = useCallback(async (exerciseId) => {
-    if (!exerciseId) return []
-    const ex = await api.getExercise(exerciseId)
-    return Array.isArray(ex?.variants) ? ex.variants : []
-  }, [])
-
   useEffect(() => {
     let cancelled = false
     ;(async () => {
@@ -234,30 +153,6 @@ export default function ExerciseProgressionGraphPanel({
     }
   }, [selectedGraphId, graphs, refreshEdges])
 
-  useEffect(() => {
-    let cancelled = false
-    ;(async () => {
-      if (!firstEp.exerciseId) return
-      const vars = await loadVariantsForExercise(firstEp.exerciseId)
-      if (!cancelled) setFirstEp((p) => ({ ...p, variants: vars }))
-    })()
-    return () => {
-      cancelled = true
-    }
-  }, [firstEp.exerciseId, loadVariantsForExercise])
-
-  useEffect(() => {
-    let cancelled = false
-    ;(async () => {
-      if (!secondEp.exerciseId) return
-      const vars = await loadVariantsForExercise(secondEp.exerciseId)
-      if (!cancelled) setSecondEp((p) => ({ ...p, variants: vars }))
-    })()
-    return () => {
-      cancelled = true
-    }
-  }, [secondEp.exerciseId, loadVariantsForExercise])
-
   const filteredEdges = useMemo(() => {
     if (!filterAnchorOnly || anchorExerciseId == null) return edges
     return edges.filter(
@@ -266,24 +161,6 @@ export default function ExerciseProgressionGraphPanel({
     )
   }, [edges, filterAnchorOnly, anchorExerciseId])
 
-  const nextEdgesFiltered = useMemo(
-    () => filteredEdges.filter((e) => e.edge_type === 'next_exercise'),
-    [filteredEdges],
-  )
-  const siblingEdgesFiltered = useMemo(
-    () => filteredEdges.filter((e) => e.edge_type === 'sibling'),
-    [filteredEdges],
-  )
-
-  const flowChains = useMemo(() => maximalLinearChains(nextEdgesFiltered), [nextEdgesFiltered])
-
-  const primaryChain = useMemo(() => {
-    if (!flowChains.length) return null
-    return flowChains.reduce((best, chain) =>
-      chain.nodes.length >= best.nodes.length ? chain : best,
-    )
-  }, [flowChains])
-
   const handleCreateGraph = async (e) => {
     e.preventDefault()
     const name = newGraphName.trim()
@@ -322,7 +199,7 @@ export default function ExerciseProgressionGraphPanel({
         visibility: metaVisibility,
       })
       await refreshGraphs()
-      alert('Graph gespeichert.')
+      alert('Graph-Metadaten gespeichert.')
     } catch (err) {
       alert(err.message || String(err))
     } finally {
@@ -332,7 +209,7 @@ export default function ExerciseProgressionGraphPanel({
 
   const handleDeleteGraph = async () => {
     if (!selectedGraphId) return
-    if (!confirm('Diesen Progressionsgraphen und alle Kanten wirklich löschen?')) return
+    if (!window.confirm('Diesen Progressionsgraph wirklich löschen?')) return
     setBusy(true)
     try {
       await api.deleteExerciseProgressionGraph(selectedGraphId)
@@ -345,49 +222,8 @@ export default function ExerciseProgressionGraphPanel({
     }
   }
 
-  const handleAddEdge = async () => {
-    if (!selectedGraphId) {
-      alert('Zuerst einen Graphen wählen.')
-      return
-    }
-    if (!firstEp.exerciseId || !secondEp.exerciseId) {
-      alert('Beide Enden müssen eine Übung haben.')
-      return
-    }
-    if (
-      firstEp.exerciseId === secondEp.exerciseId &&
-      (firstEp.variantId == null ||
-        secondEp.variantId == null ||
-        firstEp.variantId === secondEp.variantId)
-    ) {
-      alert('Bei derselben Übung bitte zwei verschiedene Varianten wählen (oder unterschiedliche Übungen).')
-      return
-    }
-    const edge_type = relationKind === 'sibling' ? 'sibling' : 'next_exercise'
-    const notes = edgeNotes.trim() || null
-    const body = {
-      from_exercise_id: firstEp.exerciseId,
-      to_exercise_id: secondEp.exerciseId,
-      from_exercise_variant_id: firstEp.variantId || null,
-      to_exercise_variant_id: secondEp.variantId || null,
-      edge_type,
-      notes,
-    }
-    setBusy(true)
-    try {
-      await api.createExerciseProgressionEdge(selectedGraphId, body)
-      setEdgeNotes('')
-      await refreshEdges(selectedGraphId)
-    } catch (err) {
-      alert(err.message || String(err))
-    } finally {
-      setBusy(false)
-    }
-  }
-
   const handleDeleteEdge = async (edgeId) => {
     if (!selectedGraphId) return
-    if (!confirm('Kante löschen?')) return
     setBusy(true)
     try {
       await api.deleteExerciseProgressionEdge(selectedGraphId, edgeId)
@@ -420,58 +256,10 @@ export default function ExerciseProgressionGraphPanel({
     }
   }
 
-  const swapEnds = () => {
-    const a = firstEp
-    setFirstEp(secondEp)
-    setSecondEp(a)
-  }
-
-  const applyPickedExercise = async (ex) => {
-    const title = ex.title || `Übung #${ex.id}`
-    const variants = Array.isArray(ex.variants) && ex.variants.length
-      ? ex.variants
-      : await loadVariantsForExercise(ex.id)
-    const variantId =
-      ex.exercise_variant_id ?? ex.suggested_variant_id ?? null
-
-    if (pickContext?.kind === 'chain') {
-      await chainEditorRef.current?.applyExercise(
-        pickContext.draftKey,
-        pickContext.nodeIndex,
-        {
-          ...ex,
-          variants,
-          exercise_variant_id: variantId,
-        },
-      )
-      setPickContext(null)
-      return
-    }
-    if (pickContext?.kind === 'single') {
-      const patch = {
-        exerciseId: ex.id,
-        exerciseTitle: title,
-        variantId: variantId != null ? Number(variantId) : null,
-        variants,
-      }
-      if (pickContext.slot === 'first') setFirstEp(patch)
-      else setSecondEp(patch)
-      setPickContext(null)
-    }
-  }
-
-  function formatNodeLine(n) {
-    return (
-      <>
-        <Link to={`/exercises/${n.exercise_id}`}>{n.title}</Link>
-        {n.variant_name ? (
-          <span style={{ color: 'var(--text3)', fontWeight: 400 }}>{` · ${n.variant_name}`}</span>
-        ) : null}
-      </>
-    )
-  }
-
-  const pickerOpen = pickContext != null
+  const handleEditorSaved = useCallback(async () => {
+    if (!selectedGraphId) return
+    await Promise.all([refreshEdges(selectedGraphId), refreshGraphs()])
+  }, [selectedGraphId, refreshEdges, refreshGraphs])
 
   return (
     <div className="exercise-progression-panel">
@@ -485,9 +273,8 @@ export default function ExerciseProgressionGraphPanel({
       )}
 
       <p style={{ fontSize: '13px', color: 'var(--text2)', marginBottom: '16px' }}>
-        Ein Graph = ein linearer <strong>Primärpfad</strong> (Roadmap-Slots) plus optionale{' '}
-        <strong>Schwestern</strong>. Für die integrierte Bearbeitung (Slots, KI-Entwürfe, Graph-Bewertung){' '}
-        <strong>Slot-Editor öffnen</strong> — unten weiterhin Kurzansicht und KI-Wizard.
+        Ein Progressionsgraph = <strong>Roadmap mit Slots</strong> (Lernziel + Hauptübung + Schwestern).
+        Roadmap, KI-Match und Bewertung sind in einer Ansicht — kein separater Wizard.
       </p>
 
       {loadErr && (
@@ -525,18 +312,12 @@ export default function ExerciseProgressionGraphPanel({
           <button type="button" className="btn" disabled={busy || !selectedGraphId} onClick={handleDeleteGraph}>
             Graph löschen
           </button>
-          {selectedGraphId ? (
-            <Link
-              to={`/progression-graphs/${selectedGraphId}`}
-              className="btn btn-primary"
-              style={{ textDecoration: 'none' }}
-            >
-              Slot-Editor öffnen
-            </Link>
-          ) : null}
         </div>
 
-        <form onSubmit={handleCreateGraph} style={{ marginTop: '16px', paddingTop: '16px', borderTop: '1px solid var(--border)' }}>
+        <form
+          onSubmit={handleCreateGraph}
+          style={{ marginTop: '16px', paddingTop: '16px', borderTop: '1px solid var(--border)' }}
+        >
           <h4 style={{ margin: '0 0 8px', fontSize: '0.95rem' }}>Neuen Graphen anlegen</h4>
           <div style={{ display: 'flex', flexWrap: 'wrap', gap: '10px', alignItems: 'flex-end' }}>
             <div className="form-row" style={{ flex: '2 1 200px', marginBottom: 0 }}>
@@ -576,107 +357,20 @@ export default function ExerciseProgressionGraphPanel({
             checked={filterAnchorOnly}
             onChange={(e) => setFilterAnchorOnly(e.target.checked)}
           />
-          Nur Reihen und Kanten, die diese Übung betreffen
+          Technische Kantenliste: nur Kanten mit dieser Übung
         </label>
       )}
 
-      {selectedGraphId && (
+      {selectedGraphId ? (
         <>
-          <div
-            className="card"
-            style={{
-              marginBottom: '12px',
-              borderColor: 'color-mix(in srgb, var(--accent) 30%, var(--border))',
-            }}
-          >
-            <h3 style={{ marginTop: 0, fontSize: '1rem' }}>Progressionspfad</h3>
-            <p style={{ fontSize: '12px', color: 'var(--text3)', marginTop: 0, lineHeight: 1.45 }}>
-              Der Graph enthält typischerweise <strong>einen linearen Pfad</strong> (Übung → Übung). Unten
-              manuell bearbeiten oder mit dem KI-Planer erweitern — Speichern im KI-Wizard ersetzt den Pfad.
-            </p>
+          <ProgressionGraphEditor
+            key={selectedGraphId}
+            graphId={selectedGraphId}
+            embedded
+            onSaved={handleEditorSaved}
+          />
 
-            <ProgressionChainEditor
-              ref={chainEditorRef}
-              graphId={selectedGraphId}
-              chains={primaryChain ? [primaryChain] : []}
-              busy={busy}
-              anchorExerciseId={anchorExerciseId}
-              anchorTitle={anchorTitle}
-              onRefresh={async () => refreshEdges(selectedGraphId)}
-              onPickExercise={setPickContext}
-              loadVariantsForExercise={loadVariantsForExercise}
-              singlePathMode
-            />
-
-            <ExerciseProgressionPathBuilder
-              graphId={selectedGraphId}
-              disabled={busy}
-              graphChainNodes={primaryChain?.nodes ?? null}
-              graphChainEdgeIds={primaryChain?.edges?.map((e) => e.id) ?? null}
-              onSaved={async () => {
-                await refreshEdges(selectedGraphId)
-              }}
-            />
-          </div>
-
-          <div className="card" style={{ marginBottom: '12px' }}>
-            <h3 style={{ marginTop: 0, fontSize: '1rem' }}>Schwestern & Alternativen</h3>
-            {siblingEdgesFiltered.length === 0 ? (
-              <p style={{ color: 'var(--text2)', margin: 0 }}>Keine Schwester-Kanten im aktuellen Filter.</p>
-            ) : (
-              <ul style={{ listStyle: 'none', padding: 0, margin: 0 }}>
-                {siblingEdgesFiltered.map((row) => (
-                  <li
-                    key={row.id}
-                    style={{
-                      padding: '10px 12px',
-                      marginBottom: '8px',
-                      borderRadius: '8px',
-                      border: '1px solid var(--border)',
-                      background: 'var(--surface2)',
-                      display: 'flex',
-                      justifyContent: 'space-between',
-                      flexWrap: 'wrap',
-                      gap: '8px',
-                      alignItems: 'center',
-                      fontSize: '13px',
-                    }}
-                  >
-                    <span>
-                      <strong>{formatNodeLine({
-                        exercise_id: row.from_exercise_id,
-                        variant_id: row.from_exercise_variant_id,
-                        title: row.from_exercise_title,
-                        variant_name: row.from_variant_name,
-                      })}</strong>
-                      <span style={{ color: 'var(--text3)', margin: '0 8px' }}>· Schwester ·</span>
-                      <strong>{formatNodeLine({
-                        exercise_id: row.to_exercise_id,
-                        variant_id: row.to_exercise_variant_id,
-                        title: row.to_exercise_title,
-                        variant_name: row.to_variant_name,
-                      })}</strong>
-                      {row.notes ? (
-                        <span style={{ display: 'block', marginTop: '6px', color: 'var(--text2)', fontWeight: 400 }}>
-                          {row.notes}
-                        </span>
-                      ) : null}
-                    </span>
-                    <button
-                      type="button"
-                      className="btn"
-                      style={{ fontSize: '12px', padding: '4px 10px', background: 'var(--danger)', color: '#fff', border: 'none' }}
-                      onClick={() => handleDeleteEdge(row.id)}
-                    >
-                      Löschen
-                    </button>
-                  </li>
-                ))}
-              </ul>
-            )}
-          </div>
-
-          <details className="card" style={{ marginBottom: '12px' }}>
+          <details className="card" style={{ marginBottom: '12px', marginTop: '12px' }}>
             <summary style={{ cursor: 'pointer', fontWeight: 600 }}>Graph-Einstellungen (Name, Sichtbarkeit)</summary>
             <div style={{ marginTop: '14px' }}>
               <div className="form-row">
@@ -714,7 +408,7 @@ export default function ExerciseProgressionGraphPanel({
 
           <SkillProfilePanel
             title="Fähigkeiten entlang des Pfads"
-            hint="Alle Übungen als Knoten im Graph (Standardgewicht pro Übung; Intensität und Stufen aus der Übungsverknüpfung)."
+            hint="Alle Übungen als Knoten im Graph."
             profile={skillProfileData?.overall}
             loading={skillProfileLoading}
             error={skillProfileError}
@@ -722,196 +416,102 @@ export default function ExerciseProgressionGraphPanel({
             artifactType="progression_graph"
           />
 
-          <details className="card" style={{ marginBottom: '12px' }}>
-            <summary style={{ cursor: 'pointer', fontWeight: 600 }}>Einzelkante (Nachfolger oder Schwester)</summary>
-            <div style={{ marginTop: '14px' }}>
-              <div className="form-row">
-                <label className="form-label">Beziehung</label>
-                <select className="form-input" value={relationKind} onChange={(e) => setRelationKind(e.target.value)}>
-                  <option value="progression">Nachfolger</option>
-                  <option value="sibling">Schwester</option>
-                </select>
-              </div>
-
-              {['first', 'second'].map((slot) => {
-                const ep = slot === 'first' ? firstEp : secondEp
-                const setEp = slot === 'first' ? setFirstEp : setSecondEp
-                return (
-                  <div key={slot} style={{ marginBottom: '12px' }}>
-                    <label className="form-label">{slot === 'first' ? 'Von (Quelle)' : 'Nach (Ziel)'}</label>
-                    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '8px', alignItems: 'center', marginBottom: '8px' }}>
-                      <span style={{ fontSize: '13px', flex: '1 1 160px' }}>
-                        {ep.exerciseId ? (
-                          <>
-                            <strong>{ep.exerciseTitle}</strong>
-                            <span style={{ color: 'var(--text3)' }}> (#{ep.exerciseId})</span>
-                          </>
-                        ) : (
-                          <span style={{ color: 'var(--text3)' }}>— Übung wählen —</span>
-                        )}
-                      </span>
-                      <button
-                        type="button"
-                        className="btn btn-secondary"
-                        onClick={() => setPickContext({ kind: 'single', slot })}
-                      >
-                        Übung…
-                      </button>
-                      {anchorExerciseId != null && (
-                        <button
-                          type="button"
-                          className="btn"
-                          style={{ fontSize: '12px', padding: '4px 10px' }}
-                          onClick={async () => {
-                            const variants = await loadVariantsForExercise(anchorExerciseId)
-                            setEp({
-                              exerciseId: anchorExerciseId,
-                              exerciseTitle: anchorTitle?.trim() || `Übung #${anchorExerciseId}`,
-                              variantId: null,
-                              variants,
-                            })
-                          }}
-                        >
-                          Diese Übung
-                        </button>
-                      )}
-                    </div>
-                    <select
-                      className="form-input"
-                      disabled={!ep.exerciseId}
-                      value={ep.variantId ?? ''}
-                      onChange={(e) =>
-                        setEp((p) => ({
-                          ...p,
-                          variantId: e.target.value === '' ? null : parseInt(e.target.value, 10),
-                        }))
-                      }
-                    >
-                      <option value="">Gesamte Übung</option>
-                      {(ep.variants || []).map((v) => (
-                        <option key={v.id} value={v.id}>
-                          {v.variant_name || `Variante #${v.id}`}
-                        </option>
-                      ))}
-                    </select>
-                  </div>
-                )
-              })}
-
-              {relationKind === 'progression' && (
-                <button type="button" className="btn" style={{ marginBottom: '10px' }} onClick={swapEnds}>
-                  Reihenfolge tauschen
-                </button>
-              )}
-
-              <div className="form-row">
-                <label className="form-label">Notiz</label>
-                <textarea className="form-input" rows={2} value={edgeNotes} onChange={(e) => setEdgeNotes(e.target.value)} />
-              </div>
-              <button type="button" className="btn btn-primary" disabled={busy} onClick={handleAddEdge}>
-                Kante speichern
-              </button>
-            </div>
-          </details>
-
           <details className="card" style={{ marginBottom: '12px' }}>
             <summary style={{ cursor: 'pointer', fontWeight: 600 }}>
               Technische Kantenliste ({filteredEdges.length}
               {edges.length !== filteredEdges.length ? ` von ${edges.length}` : ''})
             </summary>
             <div style={{ marginTop: '14px' }}>
-          {filteredEdges.length === 0 ? (
-            <p style={{ color: 'var(--text2)', margin: 0 }}>Keine Kanten.</p>
-          ) : (
-            <div style={{ overflowX: 'auto' }}>
-              <table style={{ width: '100%', borderCollapse: 'collapse', fontSize: '13px' }}>
-                <thead>
-                  <tr style={{ textAlign: 'left', borderBottom: '1px solid var(--border)' }}>
-                    <th style={{ padding: '8px 6px' }}>Von</th>
-                    <th style={{ padding: '8px 6px' }} />
-                    <th style={{ padding: '8px 6px' }}>Nach</th>
-                    <th style={{ padding: '8px 6px' }}>Art</th>
-                    <th style={{ padding: '8px 6px' }}>Notiz</th>
-                    <th style={{ padding: '8px 6px' }} />
-                  </tr>
-                </thead>
-                <tbody>
-                  {filteredEdges.map((row) => (
-                    <tr key={row.id} style={{ borderBottom: '1px solid var(--border)' }}>
-                      <td style={{ padding: '8px 6px', verticalAlign: 'top' }}>
-                        <Link to={`/exercises/${row.from_exercise_id}`}>{row.from_exercise_title || `#${row.from_exercise_id}`}</Link>
-                        {row.from_variant_name ? (
-                          <div style={{ color: 'var(--text3)', fontSize: '12px' }}>{row.from_variant_name}</div>
-                        ) : null}
-                      </td>
-                      <td style={{ padding: '8px 6px', color: 'var(--text3)', verticalAlign: 'top' }}>
-                        {row.edge_type === 'sibling' ? '·' : '→'}
-                      </td>
-                      <td style={{ padding: '8px 6px', verticalAlign: 'top' }}>
-                        <Link to={`/exercises/${row.to_exercise_id}`}>{row.to_exercise_title || `#${row.to_exercise_id}`}</Link>
-                        {row.to_variant_name ? (
-                          <div style={{ color: 'var(--text3)', fontSize: '12px' }}>{row.to_variant_name}</div>
-                        ) : null}
-                      </td>
-                      <td style={{ padding: '8px 6px', verticalAlign: 'top' }}>{edgeTypeLabel(row.edge_type)}</td>
-                      <td style={{ padding: '8px 6px', verticalAlign: 'top', maxWidth: '280px' }}>
-                        {editingEdgeNotes === row.id ? (
-                          <>
-                            <textarea
-                              className="form-input"
-                              rows={2}
-                              value={notesDraft}
-                              onChange={(e) => setNotesDraft(e.target.value)}
-                              style={{ marginBottom: '6px' }}
-                            />
-                            <button type="button" className="btn btn-secondary" disabled={busy} onClick={() => saveNotes(row.id)}>
-                              Speichern
-                            </button>
-                            <button type="button" className="btn" disabled={busy} onClick={() => setEditingEdgeNotes(null)}>
-                              Abbrechen
-                            </button>
-                          </>
-                        ) : (
-                          <>
-                            <span style={{ whiteSpace: 'pre-wrap' }}>{row.notes || '—'}</span>
+              {filteredEdges.length === 0 ? (
+                <p style={{ color: 'var(--text2)', margin: 0 }}>Keine Kanten.</p>
+              ) : (
+                <div style={{ overflowX: 'auto' }}>
+                  <table style={{ width: '100%', borderCollapse: 'collapse', fontSize: '13px' }}>
+                    <thead>
+                      <tr style={{ textAlign: 'left', borderBottom: '1px solid var(--border)' }}>
+                        <th style={{ padding: '8px 6px' }}>Von</th>
+                        <th style={{ padding: '8px 6px' }} />
+                        <th style={{ padding: '8px 6px' }}>Nach</th>
+                        <th style={{ padding: '8px 6px' }}>Art</th>
+                        <th style={{ padding: '8px 6px' }}>Notiz</th>
+                        <th style={{ padding: '8px 6px' }} />
+                      </tr>
+                    </thead>
+                    <tbody>
+                      {filteredEdges.map((row) => (
+                        <tr key={row.id} style={{ borderBottom: '1px solid var(--border)' }}>
+                          <td style={{ padding: '8px 6px', verticalAlign: 'top' }}>
+                            <Link to={`/exercises/${row.from_exercise_id}`}>
+                              {row.from_exercise_title || `#${row.from_exercise_id}`}
+                            </Link>
+                          </td>
+                          <td style={{ padding: '8px 6px', color: 'var(--text3)', verticalAlign: 'top' }}>
+                            {row.edge_type === 'sibling' ? '·' : '→'}
+                          </td>
+                          <td style={{ padding: '8px 6px', verticalAlign: 'top' }}>
+                            <Link to={`/exercises/${row.to_exercise_id}`}>
+                              {row.to_exercise_title || `#${row.to_exercise_id}`}
+                            </Link>
+                          </td>
+                          <td style={{ padding: '8px 6px', verticalAlign: 'top' }}>{edgeTypeLabel(row.edge_type)}</td>
+                          <td style={{ padding: '8px 6px', verticalAlign: 'top', maxWidth: '280px' }}>
+                            {editingEdgeNotes === row.id ? (
+                              <>
+                                <textarea
+                                  className="form-input"
+                                  rows={2}
+                                  value={notesDraft}
+                                  onChange={(e) => setNotesDraft(e.target.value)}
+                                />
+                                <button
+                                  type="button"
+                                  className="btn btn-primary"
+                                  style={{ marginTop: '6px', fontSize: '12px', padding: '4px 8px' }}
+                                  onClick={() => saveNotes(row.id)}
+                                >
+                                  Speichern
+                                </button>
+                              </>
+                            ) : (
+                              <>
+                                {row.notes || '—'}
+                                <button
+                                  type="button"
+                                  className="btn"
+                                  style={{ marginLeft: '8px', fontSize: '12px', padding: '4px 8px' }}
+                                  onClick={() => startEditNotes(row)}
+                                >
+                                  Bearbeiten
+                                </button>
+                              </>
+                            )}
+                          </td>
+                          <td style={{ padding: '8px 6px', verticalAlign: 'top' }}>
                             <button
                               type="button"
                               className="btn"
-                              style={{ marginLeft: '8px', fontSize: '12px', padding: '4px 8px' }}
-                              onClick={() => startEditNotes(row)}
+                              style={{
+                                fontSize: '12px',
+                                padding: '4px 8px',
+                                background: 'var(--danger)',
+                                color: '#fff',
+                                border: 'none',
+                              }}
+                              onClick={() => handleDeleteEdge(row.id)}
                             >
-                              Bearbeiten
+                              Löschen
                             </button>
-                          </>
-                        )}
-                      </td>
-                      <td style={{ padding: '8px 6px', verticalAlign: 'top' }}>
-                        <button
-                          type="button"
-                          className="btn"
-                          style={{ fontSize: '12px', padding: '4px 8px', background: 'var(--danger)', color: '#fff', border: 'none' }}
-                          onClick={() => handleDeleteEdge(row.id)}
-                        >
-                          Löschen
-                        </button>
-                      </td>
-                    </tr>
-                  ))}
-                </tbody>
-              </table>
-            </div>
-          )}
+                          </td>
+                        </tr>
+                      ))}
+                    </tbody>
+                  </table>
+                </div>
+              )}
             </div>
           </details>
         </>
-      )}
-
-      <ExercisePickerModal
-        open={pickerOpen}
-        onClose={() => setPickContext(null)}
-        onSelectExercise={applyPickedExercise}
-        exerciseKindAny={['simple']}
-      />
+      ) : null}
     </div>
   )
 }
diff --git a/frontend/src/components/ProgressionGraphEditor.jsx b/frontend/src/components/ProgressionGraphEditor.jsx
index 1c71a24..5985de1 100644
--- a/frontend/src/components/ProgressionGraphEditor.jsx
+++ b/frontend/src/components/ProgressionGraphEditor.jsx
@@ -57,7 +57,7 @@ function resolveDefaultFocusAreaId(targetSummary, focusAreas) {
   return focusAreas?.[0]?.id ? Number(focusAreas[0].id) : null
 }
 
-export default function ProgressionGraphEditor({ graphId }) {
+export default function ProgressionGraphEditor({ graphId, embedded = false, onSaved }) {
   const [graphMeta, setGraphMeta] = useState(null)
   const [draft, setDraft] = useState(null)
   const [busy, setBusy] = useState(false)
@@ -390,6 +390,7 @@ export default function ProgressionGraphEditor({ graphId }) {
     try {
       await saveProgressionGraphDraft(api, graphId, { ...draft, lastFindings: pathQa })
       await loadGraph()
+      if (typeof onSaved === 'function') await onSaved()
       alert('Progressionsgraph gespeichert.')
     } catch (e) {
       setActionErr(e.message || 'Speichern fehlgeschlagen')
@@ -551,19 +552,21 @@ export default function ProgressionGraphEditor({ graphId }) {
 
   return (
     <div>
-      <div style={{ marginBottom: '12px', display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start', flexWrap: 'wrap', gap: '8px' }}>
-        <div>
-          <h2 style={{ margin: 0, fontSize: '1.15rem' }}>
-            {graphMeta?.name || draft.graphName || `Graph #${graphId}`}
-          </h2>
-          <p style={{ margin: '4px 0 0', fontSize: '12px', color: 'var(--text3)' }}>
-            Slots verschieben, ergänzen · KI-Angebote zuordnen · dynamisch erweitern (max. {SLOT_MAX})
-          </p>
+      {!embedded ? (
+        <div style={{ marginBottom: '12px', display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start', flexWrap: 'wrap', gap: '8px' }}>
+          <div>
+            <h2 style={{ margin: 0, fontSize: '1.15rem' }}>
+              {graphMeta?.name || draft.graphName || `Graph #${graphId}`}
+            </h2>
+            <p style={{ margin: '4px 0 0', fontSize: '12px', color: 'var(--text3)' }}>
+              Roadmap-Slots · KI-Match · Graph-Bewertung (max. {SLOT_MAX} Slots)
+            </p>
+          </div>
+          <Link to="/exercises" className="btn btn-secondary" style={{ fontSize: '12px' }}>
+            Zur Übersicht
+          </Link>
         </div>
-        <Link to="/exercises" className="btn btn-secondary" style={{ fontSize: '12px' }}>
-          Zur Übersicht
-        </Link>
-      </div>
+      ) : null}
 
       {actionErr ? (
         <p className="form-error" style={{ marginTop: 0 }}>
diff --git a/frontend/src/pages/ProgressionGraphEditPage.jsx b/frontend/src/pages/ProgressionGraphEditPage.jsx
index ccf392d..d2a1e7d 100644
--- a/frontend/src/pages/ProgressionGraphEditPage.jsx
+++ b/frontend/src/pages/ProgressionGraphEditPage.jsx
@@ -1,25 +1,15 @@
 import React from 'react'
-import { Link, useParams } from 'react-router-dom'
-import ProgressionGraphEditor from '../components/ProgressionGraphEditor'
+import { Navigate, useParams } from 'react-router-dom'
 
+/** Alte Deep-Links → Übungen-Liste mit Graph-Auswahl. */
 export default function ProgressionGraphEditPage() {
   const { id } = useParams()
   const graphId = Number(id)
-
-  if (!Number.isFinite(graphId) || graphId < 1) {
-    return (
-      <div className="page" style={{ padding: '16px' }}>
-        <p className="form-error">Ungültige Graph-ID.</p>
-        <Link to="/exercises" className="btn btn-secondary">
-          Zurück
-        </Link>
-      </div>
-    )
-  }
-
   return (
-    <div className="page" style={{ padding: '16px', paddingBottom: '80px' }}>
-      <ProgressionGraphEditor graphId={graphId} />
-    </div>
+    <Navigate
+      to="/exercises"
+      replace
+      state={Number.isFinite(graphId) && graphId > 0 ? { progressionGraphId: graphId } : undefined}
+    />
   )
 }

From e0ddfa6ce591ee68d7af234905d41c2dd5ed5cdf Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Wed, 10 Jun 2026 15:56:30 +0200
Subject: [PATCH 12/33] Add AI Suggestion Handling for Roadmap Gaps and Enhance
 Progression Graph Components

- Implemented functions to resolve neighboring steps based on major indices and build AI context for unfilled roadmap stages.
- Enhanced `try_suggest_ai_stage_step` to generate AI proposals for empty roadmap stages, improving user experience in gap filling.
- Updated `build_gap_fill_offer` to utilize major step neighbors for better context in offers related to unfilled slots.
- Added tests to ensure correct functionality of AI suggestion handling in the context of roadmap gaps.
- Incremented application version to reflect these updates.
---
 backend/planning_exercise_path_ai_fill.py     | 208 +++++++++++++++++-
 .../test_planning_exercise_path_ai_fill.py    |  33 +++
 .../src/components/ProgressionGraphEditor.jsx | 122 ++++++++--
 .../src/components/ProgressionSlotCard.jsx    |  18 ++
 frontend/src/utils/progressionGraphDraft.js   | 157 +++++++++++--
 5 files changed, 490 insertions(+), 48 deletions(-)

diff --git a/backend/planning_exercise_path_ai_fill.py b/backend/planning_exercise_path_ai_fill.py
index 1018b59..ef1f5bf 100644
--- a/backend/planning_exercise_path_ai_fill.py
+++ b/backend/planning_exercise_path_ai_fill.py
@@ -18,6 +18,144 @@ from planning_exercise_semantics import PlanningSemanticBrief, brief_to_summary_
 _logger = logging.getLogger("shinkan.planning_exercise_path_ai_fill")
 
 
+def _resolve_neighbor_steps_by_major_index(
+    steps: Sequence[Mapping[str, Any]],
+    major_idx: int,
+) -> Tuple[Optional[Mapping[str, Any]], Optional[Mapping[str, Any]]]:
+    """Nachbarn im Pfad anhand roadmap_major_step_index (nicht Array-Position)."""
+    step_before: Optional[Mapping[str, Any]] = None
+    step_after: Optional[Mapping[str, Any]] = None
+    for step in steps:
+        raw = step.get("roadmap_major_step_index")
+        if raw is None:
+            continue
+        try:
+            mi = int(raw)
+        except (TypeError, ValueError):
+            continue
+        if mi < major_idx:
+            step_before = step
+        elif mi > major_idx and step_after is None:
+            step_after = step
+    return step_before, step_after
+
+
+def _build_stage_ai_context(
+    *,
+    goal_query: str,
+    brief: PlanningSemanticBrief,
+    spec: Mapping[str, Any],
+    step_before: Optional[Mapping[str, Any]] = None,
+    step_after: Optional[Mapping[str, Any]] = None,
+) -> ExerciseFormAiPromptContext:
+    """KI-Kontext für unbesetzte Roadmap-Stufe (keine Brücke zwischen falschen Array-Indizes)."""
+    gap = dict(spec.get("gap") or {})
+    phase = spec.get("phase") or gap.get("expected_phase") or "vertiefung"
+    topic = (brief.primary_topic or "Technik").strip()
+    learning_goal = (
+        gap.get("learning_goal")
+        or spec.get("title_hint")
+        or spec.get("sketch")
+        or ""
+    ).strip()
+    title = (spec.get("title_hint") or f"{topic} — {phase}").strip()[:280]
+    goal_parts = [
+        f"Planungsziel: {goal_query}",
+        f"Roadmap-Stufe ({phase}): {learning_goal}",
+        "Erstelle eine Übung, die dieses Stufen-Lernziel erfüllt — keine generische Brücken-Übung.",
+    ]
+    if step_before:
+        goal_parts.append(
+            f"Vorherige Stufe im Pfad: „{(step_before.get('title') or '').strip()}“"
+        )
+    if step_after:
+        goal_parts.append(
+            f"Nächste Stufe im Pfad: „{(step_after.get('title') or '').strip()}“"
+        )
+    sketch = (spec.get("sketch") or "").strip()
+    if sketch and sketch != learning_goal:
+        goal_parts.extend(["", f"Kontext: {sketch}"])
+    goal = "\n".join(goal_parts)
+
+    focus_hint = topic if brief.topic_type == "technique" else None
+    if brief.must_phrases:
+        focus_hint = ", ".join(brief.must_phrases[:2])
+
+    return ExerciseFormAiPromptContext(
+        title=title[:280],
+        goal=goal[:8000],
+        execution=None,
+        focus_hint=focus_hint,
+    )
+
+
+def try_suggest_ai_stage_step(
+    cur,
+    *,
+    goal_query: str,
+    brief: PlanningSemanticBrief,
+    spec: Mapping[str, Any],
+    steps: Sequence[Mapping[str, Any]],
+) -> Optional[Dict[str, Any]]:
+    """KI-Vorschlag für leere Roadmap-Stufe."""
+    major_idx = spec.get("roadmap_major_step_index")
+    if major_idx is None:
+        return None
+    try:
+        mi = int(major_idx)
+    except (TypeError, ValueError):
+        return None
+    step_before, step_after = _resolve_neighbor_steps_by_major_index(steps, mi)
+    gap = dict(spec.get("gap") or {})
+    if not gap.get("expected_phase"):
+        gap["expected_phase"] = spec.get("phase") or "vertiefung"
+    gap["roadmap_major_step_index"] = mi
+    if not gap.get("learning_goal"):
+        gap["learning_goal"] = spec.get("title_hint") or spec.get("sketch")
+
+    ctx = _build_stage_ai_context(
+        goal_query=goal_query,
+        brief=brief,
+        spec=spec,
+        step_before=step_before,
+        step_after=step_after,
+    )
+    try:
+        ai_payload = run_exercise_form_ai_suggestion(cur, ctx=ctx)
+    except Exception:
+        _logger.exception("roadmap_unfilled AI suggest failed")
+        return None
+    if not ai_payload:
+        return None
+
+    summary_text = ""
+    summary_obj = ai_payload.get("summary")
+    if isinstance(summary_obj, dict):
+        summary_text = str(summary_obj.get("text") or "").strip()
+    elif isinstance(summary_obj, str):
+        summary_text = summary_obj.strip()
+
+    proposal_key = f"ai-{uuid.uuid4().hex[:10]}"
+    title = (ctx.title or spec.get("title_hint") or "KI-Vorschlag").strip()
+    return {
+        "exercise_id": None,
+        "proposal_key": proposal_key,
+        "variant_id": None,
+        "title": title,
+        "summary": summary_text or None,
+        "score": None,
+        "semantic_score": None,
+        "reasons": ["KI-Neuanlage für Roadmap-Stufe ohne Bibliothekstreffer"],
+        "variants": [],
+        "is_bridge": False,
+        "is_ai_proposal": True,
+        "ai_suggestion": dict(ai_payload),
+        "roadmap_major_step_index": mi,
+        "roadmap_phase": gap.get("expected_phase"),
+        "roadmap_learning_goal": gap.get("learning_goal"),
+    }
+
+
 def _build_gap_ai_context(
     *,
     goal_query: str,
@@ -291,13 +429,20 @@ def build_gap_fill_goal_text(
     stage_goal = snap.get("stage_learning_goal") or spec.get("title_hint")
     if stage_goal:
         parts.append(f"Lernziel dieser Roadmap-Stufe: {stage_goal}")
-    parts.extend(
-        [
-            f"Entwicklungsphase dieser Übung: {snap.get('stage_phase') or phase}",
-            f"Erwarteter Entwicklungsbogen: {arc}",
-            f"Einordnung: didaktische Zwischenstufe zwischen „{from_title}“ und „{to_title}“.",
-        ]
-    )
+    parts.append(f"Entwicklungsphase dieser Übung: {snap.get('stage_phase') or phase}")
+    parts.append(f"Erwarteter Entwicklungsbogen: {arc}")
+    if spec.get("source") == "roadmap_unfilled":
+        parts.append(
+            "Einordnung: Übung für diese Roadmap-Stufe — das Stufen-Lernziel steht im Vordergrund."
+        )
+        if step_a:
+            parts.append(f"Vorherige Stufe: „{from_title}“")
+        if step_b:
+            parts.append(f"Nächste Stufe: „{to_title}“")
+    else:
+        parts.append(
+            f"Einordnung: didaktische Zwischenstufe zwischen „{from_title}“ und „{to_title}“."
+        )
     if snap.get("stage_load_profile"):
         parts.append(f"Belastungsschwerpunkte: {', '.join(snap['stage_load_profile'])}")
     if snap.get("stage_success_criteria"):
@@ -346,10 +491,20 @@ def build_gap_fill_offer(
     proposal: Optional[Mapping[str, Any]] = None,
     roadmap_snapshot: Optional[Mapping[str, Any]] = None,
 ) -> Dict[str, Any]:
+    source = spec.get("source")
     idx = int(spec.get("insert_after_index") or 0)
+    major_idx = spec.get("roadmap_major_step_index")
+    if source == "roadmap_unfilled" and major_idx is not None:
+        try:
+            mi = int(major_idx)
+        except (TypeError, ValueError):
+            mi = idx
+        step_a, step_b = _resolve_neighbor_steps_by_major_index(steps, mi)
+        idx = mi
+    else:
+        step_a = steps[idx] if idx < len(steps) else None
+        step_b = steps[idx + 1] if idx + 1 < len(steps) else None
     offer_id = f"{spec.get('source')}-{idx}-{uuid.uuid4().hex[:8]}"
-    step_a = steps[idx] if idx < len(steps) else None
-    step_b = steps[idx + 1] if idx + 1 < len(steps) else None
     goal_for_ai = ""
     if brief and goal_query:
         goal_for_ai = build_gap_fill_goal_text(
@@ -411,6 +566,38 @@ def apply_gap_fill_after_qa(
     offers: List[Dict[str, Any]] = []
 
     for spec in specs:
+        source = spec.get("source")
+
+        if source == "roadmap_unfilled":
+            proposal: Optional[Dict[str, Any]] = None
+            if include_ai_calls and len(proposals) < max_ai_proposals:
+                proposal = try_suggest_ai_stage_step(
+                    cur,
+                    goal_query=goal_query,
+                    brief=brief,
+                    spec=spec,
+                    steps=out,
+                )
+            offer = build_gap_fill_offer(
+                spec=spec,
+                steps=out,
+                goal_query=goal_query,
+                brief=brief,
+                proposal=proposal,
+                roadmap_snapshot=roadmap_snapshot,
+            )
+            offers.append(offer)
+            if proposal and auto_insert_proposals:
+                proposals.append(
+                    {
+                        "roadmap_major_step_index": spec.get("roadmap_major_step_index"),
+                        "proposal_key": proposal.get("proposal_key"),
+                        "proposal_title": proposal.get("title"),
+                        "offer_id": offer.get("offer_id"),
+                    }
+                )
+            continue
+
         idx = int(spec.get("insert_after_index") or 0)
         if idx < 0 or idx >= len(out) - 1:
             continue
@@ -432,7 +619,7 @@ def apply_gap_fill_after_qa(
         if not gap.get("expected_phase"):
             gap["expected_phase"] = spec.get("phase") or "vertiefung"
 
-        proposal: Optional[Dict[str, Any]] = None
+        proposal = None
         if include_ai_calls and len(proposals) < max_ai_proposals:
             proposal = try_suggest_ai_bridge_step(
                 cur,
@@ -508,4 +695,5 @@ __all__ = [
     "collect_gap_fill_specs",
     "insert_ai_proposals_for_gaps",
     "try_suggest_ai_bridge_step",
+    "try_suggest_ai_stage_step",
 ]
diff --git a/backend/tests/test_planning_exercise_path_ai_fill.py b/backend/tests/test_planning_exercise_path_ai_fill.py
index 98cb393..15016a9 100644
--- a/backend/tests/test_planning_exercise_path_ai_fill.py
+++ b/backend/tests/test_planning_exercise_path_ai_fill.py
@@ -136,6 +136,39 @@ def test_build_gap_fill_goal_text_includes_expected_skills():
     assert "Timing" in text
 
 
+def test_build_gap_fill_offer_roadmap_unfilled_uses_major_step_neighbors():
+    """Leere Stufe 2 zwischen Stufe 1 und 3 — Nachbarn per roadmap_major_step_index."""
+    brief = build_semantic_brief("Kumite Beinarbeit")
+    steps = [
+        {
+            "title": "Explosive Angriffe",
+            "exercise_id": 10,
+            "roadmap_major_step_index": 0,
+        },
+        {
+            "title": "Kumite-Anwendung",
+            "exercise_id": 30,
+            "roadmap_major_step_index": 2,
+        },
+    ]
+    offer = build_gap_fill_offer(
+        spec={
+            "source": "roadmap_unfilled",
+            "roadmap_major_step_index": 1,
+            "phase": "grundlage",
+            "title_hint": "Grundlegende Kumite-Steppbewegungen",
+            "gap": {"learning_goal": "Grundlegende Kumite-Steppbewegungen", "expected_phase": "grundlage"},
+        },
+        steps=steps,
+        goal_query="Kumite Beinarbeit",
+        brief=brief,
+    )
+    assert offer["roadmap_major_step_index"] == 1
+    assert "Explosive Angriffe" in offer["from_title"]
+    assert "Kumite-Anwendung" in offer["to_title"]
+    assert "Stufen-Lernziel" in offer["goal_for_ai"] or "Roadmap-Stufe" in offer["goal_for_ai"]
+
+
 def test_build_gap_fill_offer_exposes_context_preview():
     brief = build_semantic_brief("Kumite Beinarbeit")
     offer = build_gap_fill_offer(
diff --git a/frontend/src/components/ProgressionGraphEditor.jsx b/frontend/src/components/ProgressionGraphEditor.jsx
index 5985de1..0bfbc57 100644
--- a/frontend/src/components/ProgressionGraphEditor.jsx
+++ b/frontend/src/components/ProgressionGraphEditor.jsx
@@ -11,17 +11,20 @@ import ProgressionFindingsPanel from './ProgressionFindingsPanel'
 import {
   aiPreviewToQuickCreateDraft,
   buildQuickCreateAiPreview,
+  buildQuickCreateExercisePayloadFromDraft,
 } from '../utils/exerciseAiQuickCreate'
 import {
   buildPathGapPlanningContextForAi,
   gapOfferContextDisplayLines,
   initialStageLearningGoalFromOffer,
 } from '../utils/planningContextForExerciseAi'
+import ExerciseAiQuickCreateModal from './exercises/ExerciseAiQuickCreateModal'
 import {
   addSlotToDraft,
+  applyEvaluateResponseToDraft,
   applyGapOfferToDraft,
-  applyMatchStepsToSlots,
-  collectGapOffersFromApiResponse,
+  applyMatchResponseToDraft,
+  buildPlanningArtifactFromDraft,
   hydrateProgressionGraphDraft,
   insertSlotInDraft,
   librarySlotExercise,
@@ -30,10 +33,12 @@ import {
   patchSlotInDraft,
   removeSlotFromDraft,
   saveProgressionGraphDraft,
+  setSlotPrimaryLibrary,
   SLOT_MAX,
   slotsAsPathStepRows,
   slotsToEvaluateSteps,
   syncProgressionRoadmapFromSlots,
+  syncSlotPhasesFromRoadmap,
 } from '../utils/progressionGraphDraft'
 
 function roadmapStructuredPayload(startSituation, targetState, roadmapNotes) {
@@ -83,6 +88,12 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
   const [gapPrepError, setGapPrepError] = useState('')
   const [generatingOfferId, setGeneratingOfferId] = useState(null)
   const [gapAiBusy, setGapAiBusy] = useState(false)
+  const [currentEdges, setCurrentEdges] = useState([])
+  const [slotQuickCreateOpen, setSlotQuickCreateOpen] = useState(false)
+  const [slotQuickCreateIndex, setSlotQuickCreateIndex] = useState(null)
+  const [slotQuickCreateDraft, setSlotQuickCreateDraft] = useState(null)
+  const [slotQuickSaving, setSlotQuickSaving] = useState(false)
+  const [slotQuickError, setSlotQuickError] = useState('')
 
   const loadGraph = useCallback(async () => {
     if (!graphId) return
@@ -93,11 +104,13 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
         api.getExerciseProgressionGraph(Number(graphId)),
         api.listExerciseProgressionEdges(Number(graphId)),
       ])
+      const edgeList = Array.isArray(edges) ? edges : []
+      setCurrentEdges(edgeList)
       setGraphMeta(graph)
       setDraft(
         hydrateProgressionGraphDraft({
           artifact: graph?.planning_roadmap,
-          edges: Array.isArray(edges) ? edges : [],
+          edges: edgeList,
           graphName: graph?.name,
         }),
       )
@@ -248,13 +261,6 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
     return draft.slots.filter((s) => (s.learning_goal || '').trim().length >= 3)
   }, [draft?.slots])
 
-  const applyApiResponse = (res) => {
-    setSemanticBrief(res?.semantic_brief_summary || null)
-    setTargetSummary(res?.target_profile_summary || null)
-    setPathQa(res?.path_qa || null)
-    setGapFillOffers(collectGapOffersFromApiResponse(res))
-  }
-
   const runRoadmapGenerate = async () => {
     const q = (draft?.goalQuery || '').trim()
     if (q.length < 3) {
@@ -280,8 +286,10 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
       })
       const roadmap = res?.progression_roadmap
       if (!roadmap) throw new Error('Keine Roadmap in der Antwort')
+      const preservedArtifact = buildPlanningArtifactFromDraft(draft) || {}
       const hydrated = hydrateProgressionGraphDraft({
         artifact: {
+          ...preservedArtifact,
           goal_query: q,
           progression_roadmap: roadmap,
           start_situation: draft.startSituation,
@@ -289,10 +297,11 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
           roadmap_notes: draft.roadmapNotes,
           max_steps: (roadmap?.roadmap?.major_steps || []).length || draft.maxSteps,
         },
-        edges: [],
+        edges: currentEdges,
         graphName: draft.graphName,
       })
-      setDraft({ ...hydrated, goalQuery: q, dirty: true })
+      const withPhases = syncSlotPhasesFromRoadmap(hydrated, roadmap)
+      setDraft({ ...withPhases, goalQuery: q, dirty: true })
       setSemanticBrief(res?.semantic_brief_summary || null)
     } catch (e) {
       setActionErr(e.message || 'Roadmap-Generierung fehlgeschlagen')
@@ -331,16 +340,19 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
         progression_graph_id: Number(graphId),
         ...roadmapStructuredPayload(draft.startSituation, draft.targetState, draft.roadmapNotes),
       })
-      const next = applyMatchStepsToSlots(
+      const { draft: matched, remainingOffers } = applyMatchResponseToDraft(
         {
           ...synced,
           progressionRoadmap: res?.progression_roadmap || synced.progressionRoadmap,
           pathSkillExpectations: res?.path_skill_expectations || synced.pathSkillExpectations,
         },
-        res?.steps,
+        res,
       )
-      setDraft(next)
-      applyApiResponse(res)
+      setDraft(matched)
+      setSemanticBrief(res?.semantic_brief_summary || null)
+      setTargetSummary(res?.target_profile_summary || null)
+      setPathQa(res?.path_qa || null)
+      setGapFillOffers(remainingOffers)
     } catch (e) {
       setActionErr(e.message || 'Übungs-Match fehlgeschlagen')
     } finally {
@@ -374,8 +386,11 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
         progression_graph_id: Number(graphId),
         ...roadmapStructuredPayload(draft.startSituation, draft.targetState, draft.roadmapNotes),
       })
-      applyApiResponse(res)
-      setDraft((prev) => (prev ? { ...prev, lastFindings: res?.path_qa || null } : prev))
+      setSemanticBrief(res?.semantic_brief_summary || null)
+      setPathQa(res?.path_qa || null)
+      const { draft: evaluated, remainingOffers } = applyEvaluateResponseToDraft(synced, res)
+      setDraft({ ...evaluated, lastFindings: res?.path_qa || null })
+      setGapFillOffers(remainingOffers)
     } catch (e) {
       setActionErr(e.message || 'Bewertung fehlgeschlagen')
     } finally {
@@ -492,10 +507,12 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
         ai_suggestion: aiDraft,
         has_ai_payload: true,
       }
-      setDraft((prev) => {
-        const next = applyGapOfferToDraft(prev, enrichedOffer, { slotIndex })
-        return { ...next, dirty: true }
-      })
+      setDraft((prev) => applyGapOfferToDraft(prev, enrichedOffer, { slotIndex }))
+      if (slotIndex != null && Number.isFinite(slotIndex)) {
+        setSlotQuickCreateIndex(slotIndex)
+        setSlotQuickCreateDraft(aiDraft)
+        setSlotQuickCreateOpen(true)
+      }
       setGapFillOffers((prev) => prev.filter((o) => o.offer_id !== offer?.offer_id))
       setGapPrepOpen(false)
       setActiveOffer(null)
@@ -507,6 +524,50 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
     }
   }
 
+  const openSlotQuickCreate = (slotIndex) => {
+    const slot = draft?.slots?.[slotIndex]
+    if (!slot) return
+    const primary = slot.primary
+    setSlotQuickCreateIndex(slotIndex)
+    setSlotQuickError('')
+    if (primary?.kind === 'proposal' && primary.aiSuggestion) {
+      setSlotQuickCreateDraft(primary.aiSuggestion)
+      setSlotQuickCreateOpen(true)
+      return
+    }
+    setActiveOfferSlotIndex(slotIndex)
+    openGapFillPrep(
+      {
+        offer_id: `slot-${slotIndex}`,
+        title_hint: primary?.exerciseTitle || slot.learning_goal,
+        roadmap_major_step_index: slot.majorStepIndex,
+        phase: slot.phase,
+        source: 'roadmap_unfilled',
+        goal_for_ai: slot.learning_goal,
+      },
+      slotIndex,
+    )
+  }
+
+  const applySlotQuickCreate = async () => {
+    if (slotQuickCreateIndex == null || !slotQuickCreateDraft) return
+    setSlotQuickSaving(true)
+    setSlotQuickError('')
+    try {
+      const payload = buildQuickCreateExercisePayloadFromDraft(slotQuickCreateDraft)
+      const created = await api.createExercise(payload)
+      if (!created?.id) throw new Error('Anlegen fehlgeschlagen')
+      setDraft((prev) => setSlotPrimaryLibrary(prev, slotQuickCreateIndex, created))
+      setSlotQuickCreateOpen(false)
+      setSlotQuickCreateDraft(null)
+      setSlotQuickCreateIndex(null)
+    } catch (e) {
+      setSlotQuickError(e.message || 'Übung konnte nicht angelegt werden')
+    } finally {
+      setSlotQuickSaving(false)
+    }
+  }
+
   const submitGapFillPrep = async () => {
     const title = (gapPrepTitle || '').trim()
     if (title.length < 3) {
@@ -675,6 +736,7 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
               onMoveDown={(i) => handleMoveSlot(i, 1)}
               onRemoveSlot={handleRemoveSlot}
               onInsertAfter={handleInsertAfter}
+              onCreateFromProposal={openSlotQuickCreate}
             />
           ))}
         </div>
@@ -704,6 +766,22 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
         />
       ) : null}
 
+      <ExerciseAiQuickCreateModal
+        open={slotQuickCreateOpen}
+        onClose={() => {
+          if (slotQuickSaving) return
+          setSlotQuickCreateOpen(false)
+          setSlotQuickCreateDraft(null)
+          setSlotQuickError('')
+        }}
+        title={draft?.slots?.[slotQuickCreateIndex]?.primary?.exerciseTitle || ''}
+        draft={slotQuickCreateDraft}
+        onDraftChange={setSlotQuickCreateDraft}
+        busy={slotQuickSaving}
+        error={slotQuickError}
+        onSubmit={applySlotQuickCreate}
+      />
+
       <ExerciseGapFillPrepModal
         open={gapPrepOpen}
         offer={activeOffer}
diff --git a/frontend/src/components/ProgressionSlotCard.jsx b/frontend/src/components/ProgressionSlotCard.jsx
index 3f02399..c0017c0 100644
--- a/frontend/src/components/ProgressionSlotCard.jsx
+++ b/frontend/src/components/ProgressionSlotCard.jsx
@@ -25,6 +25,7 @@ export default function ProgressionSlotCard({
   onMoveDown,
   onRemoveSlot,
   onInsertAfter,
+  onCreateFromProposal,
   disabled = false,
 }) {
   const { primary, siblings = [], phase, learning_goal: learningGoal } = slot
@@ -133,6 +134,12 @@ export default function ProgressionSlotCard({
             <span style={{ color: 'var(--text3)', fontWeight: 400 }}>{` · ${primary.variantName}`}</span>
           ) : null}
         </div>
+        {primary.kind === 'proposal' && primary.aiSuggestion?.summary?.text ? (
+          <p style={{ margin: '6px 0 0', fontSize: '12px', color: 'var(--text2)', lineHeight: 1.4 }}>
+            {primary.aiSuggestion.summary.text.slice(0, 220)}
+            {primary.aiSuggestion.summary.text.length > 220 ? '…' : ''}
+          </p>
+        ) : null}
         <div style={{ display: 'flex', gap: '6px', flexWrap: 'wrap', marginTop: '8px' }}>
           <button
             type="button"
@@ -143,6 +150,17 @@ export default function ProgressionSlotCard({
           >
             {primary.kind === 'empty' ? 'Übung wählen' : 'Übung ändern'}
           </button>
+          {primary.kind === 'proposal' && typeof onCreateFromProposal === 'function' ? (
+            <button
+              type="button"
+              className="btn btn-primary"
+              style={{ fontSize: '12px', padding: '4px 10px' }}
+              disabled={disabled}
+              onClick={() => onCreateFromProposal(slotIndex)}
+            >
+              {primary.aiSuggestion ? 'Als Übung anlegen' : 'Mit KI anlegen'}
+            </button>
+          ) : null}
           {primary.kind !== 'empty' ? (
             <button
               type="button"
diff --git a/frontend/src/utils/progressionGraphDraft.js b/frontend/src/utils/progressionGraphDraft.js
index af43fc9..2718e63 100644
--- a/frontend/src/utils/progressionGraphDraft.js
+++ b/frontend/src/utils/progressionGraphDraft.js
@@ -161,21 +161,76 @@ export function offerCanExpandSlots(draft, offer) {
   return (draft.slots?.length || 0) < SLOT_MAX
 }
 
+const GAP_OFFER_SOURCE_PRIORITY = {
+  roadmap_unfilled: 0,
+  unfilled_gap: 1,
+  llm_suggested: 2,
+  off_topic: 3,
+}
+
 export function collectGapOffersFromApiResponse(res) {
+  const top = Array.isArray(res?.gap_fill_offers) ? res.gap_fill_offers : []
+  if (top.length) return top
   const qa = res?.path_qa || {}
-  const merged = [
-    ...(Array.isArray(res?.gap_fill_offers) ? res.gap_fill_offers : []),
-    ...(Array.isArray(qa?.gap_fill_offers) ? qa.gap_fill_offers : []),
-  ]
-  const seen = new Set()
-  return merged.filter((offer) => {
-    const key = offer?.offer_id || `${offer?.source}-${offer?.title_hint}`
-    if (!key || seen.has(key)) return false
-    seen.add(key)
+  return Array.isArray(qa?.gap_fill_offers) ? qa.gap_fill_offers : []
+}
+
+/** Maximal ein Angebot pro Slot — Roadmap-Lücken vor Brücken/QS. */
+export function dedupeGapOffersBySlot(offers, draft) {
+  const bySlot = new Map()
+  for (const offer of offers || []) {
+    const idx = resolveOfferSlotIndex(draft, offer)
+    if (idx == null || !Number.isFinite(idx) || idx < 0) continue
+    const existing = bySlot.get(idx)
+    const prio = GAP_OFFER_SOURCE_PRIORITY[offer?.source] ?? 9
+    const existingPrio = existing ? (GAP_OFFER_SOURCE_PRIORITY[existing?.source] ?? 9) : 99
+    if (!existing || prio < existingPrio) {
+      bySlot.set(idx, offer)
+    }
+  }
+  return Array.from(bySlot.entries())
+    .sort(([a], [b]) => a - b)
+    .map(([, offer]) => offer)
+}
+
+/** Angebote nur für Slots ohne belegte Primary (Bibliothek oder KI-Entwurf). */
+export function filterGapOffersForUnfilledSlots(draft, offers) {
+  return (offers || []).filter((offer) => {
+    const idx = resolveOfferSlotIndex(draft, offer)
+    if (idx == null || idx < 0 || idx >= (draft?.slots?.length || 0)) return true
+    const p = draft.slots[idx]?.primary
+    if (p?.kind === 'library' && p.exerciseId != null) return false
+    if (p?.kind === 'proposal') return false
     return true
   })
 }
 
+export function syncSlotPhasesFromRoadmap(draft, progressionRoadmap) {
+  if (!progressionRoadmap) return draft
+  const majors = mapMajorStepsFromApi(progressionRoadmap)
+  if (!majors.length) return draft
+  const slots = (draft.slots || []).map((slot, i) => {
+    const m = majors[i]
+    if (!m) return slot
+    return {
+      ...slot,
+      phase: m.phase || slot.phase,
+      learning_goal: m.learning_goal || slot.learning_goal,
+      load_profile: m.load_profile?.length ? m.load_profile : slot.load_profile,
+      success_criteria: m.success_criteria?.length ? m.success_criteria : slot.success_criteria,
+      anti_patterns: m.anti_patterns?.length ? m.anti_patterns : slot.anti_patterns,
+      exercise_type: m.exercise_type || slot.exercise_type,
+    }
+  })
+  return syncProgressionRoadmapFromSlots({
+    ...draft,
+    slots,
+    progressionRoadmap,
+    majorSteps: majors,
+    maxSteps: Math.max(slots.length, majors.length),
+  })
+}
+
 export function slotsAsPathStepRows(draft) {
   return (draft.slots || []).map((slot) => ({
     exerciseId: slot.primary?.exerciseId ?? null,
@@ -644,19 +699,23 @@ export function slotsToEvaluateSteps(draft) {
 
 export function applyMatchStepsToSlots(draft, apiSteps) {
   const steps = Array.isArray(apiSteps) ? apiSteps : []
-  const nextSlots = (draft.slots || []).map((slot) => ({ ...slot, primary: { ...slot.primary }, siblings: [...(slot.siblings || [])] }))
+  const nextSlots = (draft.slots || []).map((slot) => ({
+    ...slot,
+    primary: { ...slot.primary },
+    siblings: [...(slot.siblings || [])],
+  }))
 
   for (const step of steps) {
-    const idx =
-      step.roadmap_major_step_index != null
-        ? Number(step.roadmap_major_step_index)
-        : steps.indexOf(step)
-    if (!Number.isFinite(idx) || idx < 0 || idx >= nextSlots.length) continue
+    if (step.roadmap_major_step_index == null || !Number.isFinite(Number(step.roadmap_major_step_index))) {
+      continue
+    }
+    const idx = Number(step.roadmap_major_step_index)
+    if (idx < 0 || idx >= nextSlots.length) continue
 
     const isProposal = Boolean(step.is_ai_proposal) || step.exercise_id == null
     if (isProposal) {
       nextSlots[idx].primary = proposalSlotExercise({
-        title: step.title,
+        title: step.title || nextSlots[idx].learning_goal,
         proposalKey: step.proposal_key,
         aiSuggestion: step.ai_suggestion,
       })
@@ -672,6 +731,72 @@ export function applyMatchStepsToSlots(draft, apiSteps) {
   return syncProgressionRoadmapFromSlots({ ...draft, slots: nextSlots, dirty: true })
 }
 
+/** Lücken-Angebote in leere Slots legen; Panel nur für verbleibende Lücken. */
+export function applyGapOffersFromResponse(draft, res) {
+  let next = draft
+  if (res?.progression_roadmap) {
+    next = syncSlotPhasesFromRoadmap(next, res.progression_roadmap)
+  }
+
+  const offers = dedupeGapOffersBySlot(collectGapOffersFromApiResponse(res), next)
+  const placedIds = new Set()
+
+  for (const offer of offers) {
+    const idx = resolveOfferSlotIndex(next, offer)
+    if (idx == null || idx < 0 || idx >= (next.slots?.length || 0)) continue
+    const primary = next.slots[idx]?.primary
+    if (primary?.kind === 'library' && primary.exerciseId != null) continue
+    if (primary?.kind === 'proposal') continue
+
+    next = applyGapOfferToSlot(next, idx, offer)
+    if (offer?.offer_id) placedIds.add(offer.offer_id)
+  }
+
+  const remainingOffers = filterGapOffersForUnfilledSlots(
+    next,
+    dedupeGapOffersBySlot(
+      collectGapOffersFromApiResponse(res).filter((o) => !placedIds.has(o?.offer_id)),
+      next,
+    ),
+  )
+
+  return { draft: { ...next, dirty: true }, remainingOffers }
+}
+
+/** Match-Antwort: Schritte + Lücken-Angebote direkt in Slots (wie früher im Pfad-Wizard sichtbar). */
+export function applyMatchResponseToDraft(draft, res) {
+  let next = applyMatchStepsToSlots(draft, res?.steps)
+  if (res?.progression_roadmap) {
+    next = {
+      ...syncSlotPhasesFromRoadmap(next, res.progression_roadmap),
+      pathSkillExpectations: res?.path_skill_expectations || next.pathSkillExpectations,
+    }
+  }
+  const { draft: withOffers, remainingOffers } = applyGapOffersFromResponse(next, res)
+  return { draft: withOffers, remainingOffers }
+}
+
+/** Evaluate-Antwort: KI-Angebote in leere Slots (ohne Schritte neu zu matchen). */
+export function applyEvaluateResponseToDraft(draft, res) {
+  return applyGapOffersFromResponse(draft, res)
+}
+
+export function setSlotPrimaryLibrary(draft, slotIndex, exercise) {
+  if (!exercise?.id) return draft
+  const slots = (draft.slots || []).map((s, i) =>
+    i === slotIndex
+      ? {
+          ...s,
+          primary: librarySlotExercise({
+            exerciseId: exercise.id,
+            exerciseTitle: exercise.title || `Übung #${exercise.id}`,
+          }),
+        }
+      : s,
+  )
+  return syncProgressionRoadmapFromSlots({ ...draft, slots, dirty: true })
+}
+
 export function applyGapOfferToSlot(draft, slotIndex, offer, aiSuggestion = null) {
   const nextSlots = (draft.slots || []).map((s) => ({ ...s, primary: { ...s.primary }, siblings: [...(s.siblings || [])] }))
   if (slotIndex < 0 || slotIndex >= nextSlots.length) return draft

From 3b483346defe0eb1af2f3f9665a9e1d2ea038df2 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Wed, 10 Jun 2026 16:04:15 +0200
Subject: [PATCH 13/33] Enhance Progression Graph Editor with Skills Catalog
 and AI Draft Handling

- Introduced skills catalog management in the `ProgressionGraphEditor`, allowing for improved context in AI suggestions.
- Updated the loading mechanism to fetch both focus areas and skills catalog concurrently, enhancing performance.
- Implemented `ensureQuickCreateDraftFromAiSuggestion` utility to streamline the creation of drafts from AI suggestions.
- Enhanced slot management by integrating AI context into the gap fill preparation process, improving user experience.
- Incremented application version to reflect these updates.
---
 .../src/components/ProgressionGraphEditor.jsx | 139 ++++++++++++------
 frontend/src/utils/exerciseAiQuickCreate.js   |  18 +++
 2 files changed, 111 insertions(+), 46 deletions(-)

diff --git a/frontend/src/components/ProgressionGraphEditor.jsx b/frontend/src/components/ProgressionGraphEditor.jsx
index 0bfbc57..04c0ae4 100644
--- a/frontend/src/components/ProgressionGraphEditor.jsx
+++ b/frontend/src/components/ProgressionGraphEditor.jsx
@@ -12,13 +12,14 @@ import {
   aiPreviewToQuickCreateDraft,
   buildQuickCreateAiPreview,
   buildQuickCreateExercisePayloadFromDraft,
+  ensureQuickCreateDraftFromAiSuggestion,
 } from '../utils/exerciseAiQuickCreate'
 import {
   buildPathGapPlanningContextForAi,
   gapOfferContextDisplayLines,
   initialStageLearningGoalFromOffer,
 } from '../utils/planningContextForExerciseAi'
-import ExerciseAiQuickCreateModal from './exercises/ExerciseAiQuickCreateModal'
+import ExerciseAiSuggestPreviewModal from './ExerciseAiSuggestPreviewModal'
 import {
   addSlotToDraft,
   applyEvaluateResponseToDraft,
@@ -77,6 +78,7 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
   const [semanticBrief, setSemanticBrief] = useState(null)
   const [targetSummary, setTargetSummary] = useState(null)
   const [focusAreas, setFocusAreas] = useState([])
+  const [skillsCatalog, setSkillsCatalog] = useState([])
 
   const [activeOffer, setActiveOffer] = useState(null)
   const [activeOfferSlotIndex, setActiveOfferSlotIndex] = useState(null)
@@ -89,11 +91,11 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
   const [generatingOfferId, setGeneratingOfferId] = useState(null)
   const [gapAiBusy, setGapAiBusy] = useState(false)
   const [currentEdges, setCurrentEdges] = useState([])
-  const [slotQuickCreateOpen, setSlotQuickCreateOpen] = useState(false)
   const [slotQuickCreateIndex, setSlotQuickCreateIndex] = useState(null)
   const [slotQuickCreateDraft, setSlotQuickCreateDraft] = useState(null)
   const [slotQuickSaving, setSlotQuickSaving] = useState(false)
   const [slotQuickError, setSlotQuickError] = useState('')
+  const [activePlanningContextLines, setActivePlanningContextLines] = useState([])
 
   const loadGraph = useCallback(async () => {
     if (!graphId) return
@@ -130,13 +132,20 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
 
   useEffect(() => {
     let cancelled = false
-    api
-      .listFocusAreas({ status: 'active' })
-      .then((fa) => {
-        if (!cancelled) setFocusAreas(Array.isArray(fa) ? fa : [])
+    Promise.all([
+      api.listFocusAreas({ status: 'active' }),
+      api.listSkillsCatalog({ status: 'active' }),
+    ])
+      .then(([fa, sk]) => {
+        if (cancelled) return
+        setFocusAreas(Array.isArray(fa) ? fa : [])
+        setSkillsCatalog(Array.isArray(sk) ? sk : [])
       })
       .catch(() => {
-        if (!cancelled) setFocusAreas([])
+        if (!cancelled) {
+          setFocusAreas([])
+          setSkillsCatalog([])
+        }
       })
     return () => {
       cancelled = true
@@ -434,6 +443,20 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
     setGapFillOffers((prev) => prev.filter((o) => o.offer_id !== offer?.offer_id))
   }
 
+  const slotOfferContext = (slotIndex) => {
+    const slot = draft?.slots?.[slotIndex]
+    if (!slot) return null
+    return {
+      offer_id: `slot-${slotIndex}`,
+      title_hint: slot.primary?.exerciseTitle || slot.learning_goal,
+      roadmap_major_step_index: slot.majorStepIndex,
+      phase: slot.phase,
+      source: 'roadmap_unfilled',
+      goal_for_ai: slot.learning_goal,
+      sketch: slot.learning_goal,
+    }
+  }
+
   const openGapFillPrep = (offer, slotIndex = null) => {
     const defaultFocus = resolveDefaultFocusAreaId(targetSummary, focusAreas)
     setActiveOffer(offer)
@@ -442,6 +465,7 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
     setGapPrepStageGoal(initialStageLearningGoalFromOffer(offer, gapContextParams))
     setGapPrepSupplements('')
     setGapPrepFocusAreaId(defaultFocus ? String(defaultFocus) : '')
+    setActivePlanningContextLines(gapOfferContextDisplayLines(offer, gapContextParams))
     setGapPrepError('')
     setGapPrepOpen(true)
   }
@@ -472,12 +496,17 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
     setGapAiBusy(true)
     setGeneratingOfferId(offer?.offer_id || null)
     setGapPrepError('')
+    setSlotQuickError('')
+    const contextParams = {
+      ...gapContextParams,
+      stageLearningGoalOverride: stageGoal,
+      gapTrainerSupplements: supplements,
+    }
+    setActivePlanningContextLines(gapOfferContextDisplayLines(offer, contextParams))
     try {
       const planningContext = buildPathGapPlanningContextForAi({
         offer,
-        ...gapContextParams,
-        stageLearningGoalOverride: stageGoal,
-        gapTrainerSupplements: supplements,
+        ...contextParams,
       })
       const aiRes = await api.suggestExerciseAi({
         title,
@@ -507,15 +536,19 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
         ai_suggestion: aiDraft,
         has_ai_payload: true,
       }
-      setDraft((prev) => applyGapOfferToDraft(prev, enrichedOffer, { slotIndex }))
-      if (slotIndex != null && Number.isFinite(slotIndex)) {
-        setSlotQuickCreateIndex(slotIndex)
-        setSlotQuickCreateDraft(aiDraft)
-        setSlotQuickCreateOpen(true)
+      const resolvedSlot =
+        slotIndex != null && Number.isFinite(slotIndex)
+          ? slotIndex
+          : activeOfferSlotIndex != null && Number.isFinite(activeOfferSlotIndex)
+            ? activeOfferSlotIndex
+            : null
+      if (resolvedSlot != null) {
+        setSlotQuickCreateIndex(resolvedSlot)
+        setDraft((prev) => applyGapOfferToDraft(prev, enrichedOffer, { slotIndex: resolvedSlot }))
       }
+      setSlotQuickCreateDraft(aiDraft)
       setGapFillOffers((prev) => prev.filter((o) => o.offer_id !== offer?.offer_id))
       setGapPrepOpen(false)
-      setActiveOffer(null)
     } catch (e) {
       setGapPrepError(e.message || 'KI-Anlage fehlgeschlagen')
     } finally {
@@ -528,25 +561,27 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
     const slot = draft?.slots?.[slotIndex]
     if (!slot) return
     const primary = slot.primary
+    const offer = slotOfferContext(slotIndex)
     setSlotQuickCreateIndex(slotIndex)
     setSlotQuickError('')
-    if (primary?.kind === 'proposal' && primary.aiSuggestion) {
-      setSlotQuickCreateDraft(primary.aiSuggestion)
-      setSlotQuickCreateOpen(true)
-      return
-    }
+    setActiveOffer(offer)
     setActiveOfferSlotIndex(slotIndex)
-    openGapFillPrep(
-      {
-        offer_id: `slot-${slotIndex}`,
-        title_hint: primary?.exerciseTitle || slot.learning_goal,
-        roadmap_major_step_index: slot.majorStepIndex,
-        phase: slot.phase,
-        source: 'roadmap_unfilled',
-        goal_for_ai: slot.learning_goal,
-      },
-      slotIndex,
-    )
+    setActivePlanningContextLines(gapOfferContextDisplayLines(offer, gapContextParams))
+
+    if (primary?.kind === 'proposal' && primary.aiSuggestion) {
+      const focusId = resolveDefaultFocusAreaId(targetSummary, focusAreas)
+      const draftReady = ensureQuickCreateDraftFromAiSuggestion(primary.aiSuggestion, {
+        title: primary.exerciseTitle || slot.learning_goal,
+        focusAreaId: focusId,
+        sketchPlain: (offer?.goal_for_ai || slot.learning_goal || '').trim(),
+      })
+      if (draftReady) {
+        setSlotQuickCreateDraft(draftReady)
+        return
+      }
+    }
+
+    openGapFillPrep(offer, slotIndex)
   }
 
   const applySlotQuickCreate = async () => {
@@ -558,11 +593,15 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
       const created = await api.createExercise(payload)
       if (!created?.id) throw new Error('Anlegen fehlgeschlagen')
       setDraft((prev) => setSlotPrimaryLibrary(prev, slotQuickCreateIndex, created))
-      setSlotQuickCreateOpen(false)
       setSlotQuickCreateDraft(null)
       setSlotQuickCreateIndex(null)
+      setActiveOffer(null)
+      setActiveOfferSlotIndex(null)
+      setActivePlanningContextLines([])
     } catch (e) {
-      setSlotQuickError(e.message || 'Übung konnte nicht angelegt werden')
+      const msg = e.message || 'Übung konnte nicht angelegt werden'
+      setSlotQuickError(msg)
+      alert(msg)
     } finally {
       setSlotQuickSaving(false)
     }
@@ -766,20 +805,28 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
         />
       ) : null}
 
-      <ExerciseAiQuickCreateModal
-        open={slotQuickCreateOpen}
-        onClose={() => {
-          if (slotQuickSaving) return
-          setSlotQuickCreateOpen(false)
-          setSlotQuickCreateDraft(null)
-          setSlotQuickError('')
-        }}
-        title={draft?.slots?.[slotQuickCreateIndex]?.primary?.exerciseTitle || ''}
+      <ExerciseAiSuggestPreviewModal
         draft={slotQuickCreateDraft}
         onDraftChange={setSlotQuickCreateDraft}
-        busy={slotQuickSaving}
-        error={slotQuickError}
-        onSubmit={applySlotQuickCreate}
+        onDiscard={() => {
+          if (slotQuickSaving) return
+          setSlotQuickCreateDraft(null)
+          setSlotQuickError('')
+          if (activeOffer) {
+            setGapPrepOpen(true)
+          } else {
+            setActivePlanningContextLines([])
+          }
+        }}
+        planningContextLines={activePlanningContextLines}
+        onApply={applySlotQuickCreate}
+        focusAreas={focusAreas}
+        skillsCatalog={skillsCatalog}
+        dialogTitle="Progressions-Slot — KI-Entwurf bearbeiten"
+        hint="Texte prüfen und anpassen, dann als Übung speichern — sie wird dem Slot zugeordnet."
+        applyLabel={slotQuickSaving ? 'Wird angelegt …' : 'Anlegen und Slot zuweisen'}
+        applyDisabled={slotQuickSaving}
+        zIndex={2100}
       />
 
       <ExerciseGapFillPrepModal
diff --git a/frontend/src/utils/exerciseAiQuickCreate.js b/frontend/src/utils/exerciseAiQuickCreate.js
index 46f9b89..298a364 100644
--- a/frontend/src/utils/exerciseAiQuickCreate.js
+++ b/frontend/src/utils/exerciseAiQuickCreate.js
@@ -166,6 +166,24 @@ export function describeAiSkillRowForPreview(row, skillsCatalog) {
 }
 
 /** KI-Vorschau → bearbeitbarer Entwurf (Rich-Text-Felder). */
+/** Rohes API-ai_suggestion oder bereits bearbeiteter Entwurf → Preview-Entwurf. */
+export function ensureQuickCreateDraftFromAiSuggestion(
+  aiSuggestion,
+  { title = '', focusAreaId = '', sketchPlain = '' } = {},
+) {
+  if (!aiSuggestion || typeof aiSuggestion !== 'object') return null
+  if (aiSuggestion.instructionFields) return aiSuggestion
+  const preview = buildQuickCreateAiPreview(aiSuggestion, { sketchPlain })
+  if (
+    !preview.hasSummaryProposal &&
+    !preview.hasInstructionChoices &&
+    !preview.hasSkillChoices
+  ) {
+    return null
+  }
+  return aiPreviewToQuickCreateDraft(preview, { title, focusAreaId, sketchPlain })
+}
+
 export function aiPreviewToQuickCreateDraft(preview, { title, focusAreaId, sketchPlain }) {
   const sketchHtml = aiPlainTextToMinimalHtml(sketchPlain)
   const instructionFields = {

From 48d51c07c569c603baa4a4ab992a0f898d46bce1 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Wed, 10 Jun 2026 16:17:40 +0200
Subject: [PATCH 14/33] Enhance Exercise Progression Graph Panel and Editor
 with New Features

- Refactored `ExerciseProgressionGraphPanel` to support a create dialog for new progression graphs, improving user experience.
- Integrated `ProgressionGraphListCard` for better visualization of existing graphs and streamlined management.
- Updated `ProgressionGraphEditor` to handle start/target analysis and improved draft hydration with AI suggestions.
- Added utility functions for managing structured responses from AI, enhancing the planning process.
- Incremented application version to reflect these updates.
---
 .../ExerciseProgressionGraphPanel.jsx         | 593 ++++++++++--------
 .../src/components/ProgressionGraphEditor.jsx | 188 +++++-
 .../components/ProgressionGraphListCard.jsx   | 126 ++++
 .../exercises/ExercisesListPageRoot.jsx       |  11 +-
 frontend/src/utils/progressionGraphDraft.js   |  45 ++
 5 files changed, 687 insertions(+), 276 deletions(-)
 create mode 100644 frontend/src/components/ProgressionGraphListCard.jsx

diff --git a/frontend/src/components/ExerciseProgressionGraphPanel.jsx b/frontend/src/components/ExerciseProgressionGraphPanel.jsx
index a8be046..a0a2988 100644
--- a/frontend/src/components/ExerciseProgressionGraphPanel.jsx
+++ b/frontend/src/components/ExerciseProgressionGraphPanel.jsx
@@ -1,13 +1,21 @@
 /**
- * Progressionsgraphen — eine Oberfläche: Graph wählen, Roadmap-Slots bearbeiten, KI & Speichern.
+ * Progressionsgraphen — Kachel-Übersicht (wie Übungen) + Editor-Detailansicht.
  */
-import React, { useCallback, useEffect, useMemo, useState } from 'react'
+import React, {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useState,
+} from 'react'
 import { Link, useLocation } from 'react-router-dom'
 import api from '../utils/api'
 import SkillProfilePanel from './skills/SkillProfilePanel'
 import { useAuth } from '../context/AuthContext'
 import { getTenantClubDependencyKey } from '../utils/activeClub'
 import ProgressionGraphEditor from './ProgressionGraphEditor'
+import ProgressionGraphListCard from './ProgressionGraphListCard'
 import { EXERCISE_VISIBILITY_FIELD_LABEL } from '../constants/exerciseGovernanceLabels'
 
 const VIS_OPTIONS = [
@@ -22,10 +30,14 @@ function edgeTypeLabel(type) {
   return type || '—'
 }
 
-export default function ExerciseProgressionGraphPanel({
-  anchorExerciseId = null,
-  anchorTitle = null,
-}) {
+function ExerciseProgressionGraphPanel(
+  {
+    anchorExerciseId = null,
+    anchorTitle = null,
+    initialGraphId = null,
+  },
+  ref,
+) {
   const { user } = useAuth()
   const location = useLocation()
   const isSuperadmin = user?.role === 'superadmin'
@@ -42,6 +54,7 @@ export default function ExerciseProgressionGraphPanel({
   const [busy, setBusy] = useState(false)
   const [loadErr, setLoadErr] = useState(null)
 
+  const [createModalOpen, setCreateModalOpen] = useState(false)
   const [newGraphName, setNewGraphName] = useState('')
   const [newGraphVisibility, setNewGraphVisibility] = useState('private')
 
@@ -56,16 +69,28 @@ export default function ExerciseProgressionGraphPanel({
   const [skillProfileLoading, setSkillProfileLoading] = useState(false)
   const [skillProfileError, setSkillProfileError] = useState('')
 
+  useImperativeHandle(ref, () => ({
+    openCreateDialog: () => {
+      setNewGraphName('')
+      setNewGraphVisibility('private')
+      setCreateModalOpen(true)
+    },
+  }))
+
   useEffect(() => {
-    const gid = location.state?.progressionGraphId
+    const gid =
+      initialGraphId ??
+      location.state?.progressionGraphId
     if (gid != null && Number.isFinite(Number(gid))) {
       setSelectedGraphId(Number(gid))
     }
-  }, [location.state?.progressionGraphId])
+  }, [location.state?.progressionGraphId, initialGraphId])
 
   useEffect(() => {
-    setSelectedGraphId(null)
-  }, [tenantClubDepKey])
+    if (!initialGraphId && !location.state?.progressionGraphId) {
+      setSelectedGraphId(null)
+    }
+  }, [tenantClubDepKey, initialGraphId, location.state?.progressionGraphId])
 
   const refreshGraphs = useCallback(async () => {
     const list = await api.listExerciseProgressionGraphs()
@@ -174,6 +199,7 @@ export default function ExerciseProgressionGraphPanel({
         name,
         visibility: newGraphVisibility,
       })
+      setCreateModalOpen(false)
       setNewGraphName('')
       await refreshGraphs()
       if (created?.id != null) setSelectedGraphId(created.id)
@@ -184,6 +210,22 @@ export default function ExerciseProgressionGraphPanel({
     }
   }
 
+  const handleDeleteGraph = async (graph) => {
+    const gid = graph?.id ?? selectedGraphId
+    if (!gid) return
+    if (!window.confirm(`Progressionsgraph „${graph?.name || gid}" wirklich löschen?`)) return
+    setBusy(true)
+    try {
+      await api.deleteExerciseProgressionGraph(gid)
+      if (selectedGraphId === gid) setSelectedGraphId(null)
+      await refreshGraphs()
+    } catch (err) {
+      alert(err.message || String(err))
+    } finally {
+      setBusy(false)
+    }
+  }
+
   const handleSaveMeta = async () => {
     if (!selectedGraphId) return
     const name = metaName.trim()
@@ -207,21 +249,6 @@ export default function ExerciseProgressionGraphPanel({
     }
   }
 
-  const handleDeleteGraph = async () => {
-    if (!selectedGraphId) return
-    if (!window.confirm('Diesen Progressionsgraph wirklich löschen?')) return
-    setBusy(true)
-    try {
-      await api.deleteExerciseProgressionGraph(selectedGraphId)
-      setSelectedGraphId(null)
-      await refreshGraphs()
-    } catch (err) {
-      alert(err.message || String(err))
-    } finally {
-      setBusy(false)
-    }
-  }
-
   const handleDeleteEdge = async (edgeId) => {
     if (!selectedGraphId) return
     setBusy(true)
@@ -261,8 +288,159 @@ export default function ExerciseProgressionGraphPanel({
     await Promise.all([refreshEdges(selectedGraphId), refreshGraphs()])
   }, [selectedGraphId, refreshEdges, refreshGraphs])
 
+  const selectedGraph = graphs.find((g) => g.id === selectedGraphId)
+
+  if (loadErr) {
+    return (
+      <div className="card" style={{ borderColor: 'var(--danger)' }}>
+        <p style={{ margin: 0, color: 'var(--danger)' }}>{loadErr}</p>
+      </div>
+    )
+  }
+
+  if (!selectedGraphId) {
+    return (
+      <div className="exercise-progression-panel">
+        {anchorExerciseId != null && (
+          <p style={{ fontSize: '13px', color: 'var(--text2)', marginBottom: '12px' }}>
+            Kontext:{' '}
+            <strong>{anchorTitle?.trim() || `Übung #${anchorExerciseId}`}</strong>
+            {' · '}
+            <Link to={`/exercises/${anchorExerciseId}`}>Ansehen</Link>
+          </p>
+        )}
+
+        <p style={{ fontSize: '13px', color: 'var(--text2)', marginBottom: '16px' }}>
+          Progressionsgraphen planen didaktische Entwicklungspfade mit Roadmap-Slots, KI-Match und
+          Bewertung — analog zur Übungsbibliothek als eigene Sammlung.
+        </p>
+
+        {busy && graphs.length === 0 ? (
+          <div className="empty-state card" style={{ padding: '2rem 1rem' }}>
+            <div className="spinner" />
+            <p className="muted" style={{ marginTop: '12px' }}>
+              Lade Progressionsgraphen…
+            </p>
+          </div>
+        ) : graphs.length === 0 ? (
+          <div className="card empty-state" style={{ padding: '2rem 1rem', textAlign: 'center' }}>
+            <p style={{ margin: '0 0 12px', color: 'var(--text2)' }}>
+              Noch keine Progressionsgraphen — lege den ersten an.
+            </p>
+            <button
+              type="button"
+              className="btn btn-primary"
+              onClick={() => {
+                setCreateModalOpen(true)
+              }}
+            >
+              + Neu
+            </button>
+          </div>
+        ) : (
+          <div className="exercises-list-grid">
+            {graphs.map((g) => (
+              <ProgressionGraphListCard
+                key={g.id}
+                graph={g}
+                userId={user?.id}
+                disabled={busy}
+                onOpen={(row) => setSelectedGraphId(row.id)}
+                onDelete={handleDeleteGraph}
+              />
+            ))}
+          </div>
+        )}
+
+        {createModalOpen ? (
+          <div
+            className="admin-modal-backdrop"
+            role="presentation"
+            onClick={(e) => {
+              if (e.target === e.currentTarget && !busy) setCreateModalOpen(false)
+            }}
+          >
+            <div
+              className="admin-modal-sheet"
+              role="dialog"
+              aria-modal="true"
+              aria-labelledby="new-progression-graph-title"
+              onClick={(e) => e.stopPropagation()}
+              style={{ maxWidth: '480px' }}
+            >
+              <div className="admin-modal-sheet__header">
+                <h3 id="new-progression-graph-title" className="admin-modal-sheet__title">
+                  Neuer Progressionsgraph
+                </h3>
+                <button
+                  type="button"
+                  className="btn btn-secondary admin-modal-sheet__close"
+                  disabled={busy}
+                  onClick={() => setCreateModalOpen(false)}
+                >
+                  Schließen
+                </button>
+              </div>
+              <form onSubmit={handleCreateGraph}>
+                <div className="admin-modal-sheet__body">
+                  <div className="form-row">
+                    <label className="form-label">Name *</label>
+                    <input
+                      className="form-input"
+                      value={newGraphName}
+                      onChange={(e) => setNewGraphName(e.target.value)}
+                      placeholder="z. B. Kumite-Einstieg Verein Nord"
+                      autoFocus
+                    />
+                  </div>
+                  <div className="form-row">
+                    <label className="form-label">{EXERCISE_VISIBILITY_FIELD_LABEL}</label>
+                    <select
+                      className="form-input"
+                      value={newGraphVisibility}
+                      onChange={(e) => setNewGraphVisibility(e.target.value)}
+                    >
+                      {filteredGraphVisOptions.map((o) => (
+                        <option key={o.value} value={o.value}>
+                          {o.label}
+                        </option>
+                      ))}
+                    </select>
+                  </div>
+                </div>
+                <div className="admin-modal-sheet__footer">
+                  <button type="button" className="btn btn-secondary" disabled={busy} onClick={() => setCreateModalOpen(false)}>
+                    Abbrechen
+                  </button>
+                  <button type="submit" className="btn btn-primary" disabled={busy}>
+                    Anlegen
+                  </button>
+                </div>
+              </form>
+            </div>
+          </div>
+        ) : null}
+      </div>
+    )
+  }
+
   return (
     <div className="exercise-progression-panel">
+      <div style={{ marginBottom: '12px', display: 'flex', flexWrap: 'wrap', gap: '8px', alignItems: 'center' }}>
+        <button
+          type="button"
+          className="btn btn-secondary"
+          style={{ fontSize: '12px' }}
+          disabled={busy}
+          onClick={() => setSelectedGraphId(null)}
+        >
+          ← Zur Übersicht
+        </button>
+        <h2 style={{ margin: 0, fontSize: '1.1rem', flex: '1 1 auto' }}>
+          {selectedGraph?.name || `Graph #${selectedGraphId}`}
+        </h2>
+      </div>
+
       {anchorExerciseId != null && (
         <p style={{ fontSize: '13px', color: 'var(--text2)', marginBottom: '12px' }}>
           Kontext:{' '}
@@ -272,84 +450,6 @@ export default function ExerciseProgressionGraphPanel({
         </p>
       )}
 
-      <p style={{ fontSize: '13px', color: 'var(--text2)', marginBottom: '16px' }}>
-        Ein Progressionsgraph = <strong>Roadmap mit Slots</strong> (Lernziel + Hauptübung + Schwestern).
-        Roadmap, KI-Match und Bewertung sind in einer Ansicht — kein separater Wizard.
-      </p>
-
-      {loadErr && (
-        <div className="card" style={{ borderColor: 'var(--danger)', marginBottom: '12px' }}>
-          <p style={{ margin: 0, color: 'var(--danger)' }}>{loadErr}</p>
-        </div>
-      )}
-
-      <div className="card" style={{ marginBottom: '12px' }}>
-        <h3 style={{ marginTop: 0, fontSize: '1rem' }}>Graph auswählen</h3>
-        <div style={{ display: 'flex', flexWrap: 'wrap', gap: '10px', alignItems: 'flex-end' }}>
-          <div className="form-row" style={{ flex: '1 1 220px', marginBottom: 0 }}>
-            <label className="form-label">Aktiver Graph</label>
-            <select
-              className="form-input"
-              value={selectedGraphId ?? ''}
-              onChange={(e) => setSelectedGraphId(e.target.value ? parseInt(e.target.value, 10) : null)}
-            >
-              <option value="">— wählen —</option>
-              {graphs.map((g) => (
-                <option key={g.id} value={g.id}>
-                  {g.name} ({g.edges_count ?? 0} Kanten)
-                </option>
-              ))}
-            </select>
-          </div>
-          <button
-            type="button"
-            className="btn"
-            disabled={busy || !selectedGraphId}
-            onClick={() => refreshEdges(selectedGraphId)}
-          >
-            Aktualisieren
-          </button>
-          <button type="button" className="btn" disabled={busy || !selectedGraphId} onClick={handleDeleteGraph}>
-            Graph löschen
-          </button>
-        </div>
-
-        <form
-          onSubmit={handleCreateGraph}
-          style={{ marginTop: '16px', paddingTop: '16px', borderTop: '1px solid var(--border)' }}
-        >
-          <h4 style={{ margin: '0 0 8px', fontSize: '0.95rem' }}>Neuen Graphen anlegen</h4>
-          <div style={{ display: 'flex', flexWrap: 'wrap', gap: '10px', alignItems: 'flex-end' }}>
-            <div className="form-row" style={{ flex: '2 1 200px', marginBottom: 0 }}>
-              <label className="form-label">Name</label>
-              <input
-                className="form-input"
-                value={newGraphName}
-                onChange={(e) => setNewGraphName(e.target.value)}
-                placeholder="z. B. Kumite-Einstieg Verein Nord"
-              />
-            </div>
-            <div className="form-row" style={{ flex: '1 1 140px', marginBottom: 0 }}>
-              <label className="form-label">{EXERCISE_VISIBILITY_FIELD_LABEL}</label>
-              <select
-                className="form-input"
-                value={newGraphVisibility}
-                onChange={(e) => setNewGraphVisibility(e.target.value)}
-              >
-                {filteredGraphVisOptions.map((o) => (
-                  <option key={o.value} value={o.value}>
-                    {o.label}
-                  </option>
-                ))}
-              </select>
-            </div>
-            <button type="submit" className="btn btn-primary" disabled={busy}>
-              Graph erstellen
-            </button>
-          </div>
-        </form>
-      </div>
-
       {selectedGraphId && anchorExerciseId != null && (
         <label style={{ display: 'flex', alignItems: 'center', gap: '8px', marginBottom: '12px', fontSize: '13px' }}>
           <input
@@ -361,157 +461,160 @@ export default function ExerciseProgressionGraphPanel({
         </label>
       )}
 
-      {selectedGraphId ? (
-        <>
-          <ProgressionGraphEditor
-            key={selectedGraphId}
-            graphId={selectedGraphId}
-            embedded
-            onSaved={handleEditorSaved}
-          />
+      <ProgressionGraphEditor
+        key={selectedGraphId}
+        graphId={selectedGraphId}
+        embedded
+        onSaved={handleEditorSaved}
+      />
 
-          <details className="card" style={{ marginBottom: '12px', marginTop: '12px' }}>
-            <summary style={{ cursor: 'pointer', fontWeight: 600 }}>Graph-Einstellungen (Name, Sichtbarkeit)</summary>
-            <div style={{ marginTop: '14px' }}>
-              <div className="form-row">
-                <label className="form-label">Name</label>
-                <input className="form-input" value={metaName} onChange={(e) => setMetaName(e.target.value)} />
-              </div>
-              <div className="form-row">
-                <label className="form-label">Beschreibung</label>
-                <textarea
-                  className="form-input"
-                  rows={2}
-                  value={metaDescription}
-                  onChange={(e) => setMetaDescription(e.target.value)}
-                />
-              </div>
-              <div className="form-row">
-                <label className="form-label">{EXERCISE_VISIBILITY_FIELD_LABEL}</label>
-                <select
-                  className="form-input"
-                  value={metaVisibility}
-                  onChange={(e) => setMetaVisibility(e.target.value)}
-                >
-                  {filteredGraphVisOptions.map((o) => (
-                    <option key={o.value} value={o.value}>
-                      {o.label}
-                    </option>
-                  ))}
-                </select>
-              </div>
-              <button type="button" className="btn btn-secondary" disabled={busy} onClick={handleSaveMeta}>
-                Metadaten speichern
-              </button>
-            </div>
-          </details>
+      <details className="card" style={{ marginBottom: '12px', marginTop: '12px' }}>
+        <summary style={{ cursor: 'pointer', fontWeight: 600 }}>Graph-Einstellungen (Name, Sichtbarkeit)</summary>
+        <div style={{ marginTop: '14px' }}>
+          <div className="form-row">
+            <label className="form-label">Name</label>
+            <input className="form-input" value={metaName} onChange={(e) => setMetaName(e.target.value)} />
+          </div>
+          <div className="form-row">
+            <label className="form-label">Beschreibung</label>
+            <textarea
+              className="form-input"
+              rows={2}
+              value={metaDescription}
+              onChange={(e) => setMetaDescription(e.target.value)}
+            />
+          </div>
+          <div className="form-row">
+            <label className="form-label">{EXERCISE_VISIBILITY_FIELD_LABEL}</label>
+            <select
+              className="form-input"
+              value={metaVisibility}
+              onChange={(e) => setMetaVisibility(e.target.value)}
+            >
+              {filteredGraphVisOptions.map((o) => (
+                <option key={o.value} value={o.value}>
+                  {o.label}
+                </option>
+              ))}
+            </select>
+          </div>
+          <div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap' }}>
+            <button type="button" className="btn btn-secondary" disabled={busy} onClick={handleSaveMeta}>
+              Metadaten speichern
+            </button>
+            <button type="button" className="btn" disabled={busy} onClick={() => handleDeleteGraph(selectedGraph)}>
+              Graph löschen
+            </button>
+          </div>
+        </div>
+      </details>
 
-          <SkillProfilePanel
-            title="Fähigkeiten entlang des Pfads"
-            hint="Alle Übungen als Knoten im Graph."
-            profile={skillProfileData?.overall}
-            loading={skillProfileLoading}
-            error={skillProfileError}
-            defaultExpanded={false}
-            artifactType="progression_graph"
-          />
+      <SkillProfilePanel
+        title="Fähigkeiten entlang des Pfads"
+        hint="Alle Übungen als Knoten im Graph."
+        profile={skillProfileData?.overall}
+        loading={skillProfileLoading}
+        error={skillProfileError}
+        defaultExpanded={false}
+        artifactType="progression_graph"
+      />
 
-          <details className="card" style={{ marginBottom: '12px' }}>
-            <summary style={{ cursor: 'pointer', fontWeight: 600 }}>
-              Technische Kantenliste ({filteredEdges.length}
-              {edges.length !== filteredEdges.length ? ` von ${edges.length}` : ''})
-            </summary>
-            <div style={{ marginTop: '14px' }}>
-              {filteredEdges.length === 0 ? (
-                <p style={{ color: 'var(--text2)', margin: 0 }}>Keine Kanten.</p>
-              ) : (
-                <div style={{ overflowX: 'auto' }}>
-                  <table style={{ width: '100%', borderCollapse: 'collapse', fontSize: '13px' }}>
-                    <thead>
-                      <tr style={{ textAlign: 'left', borderBottom: '1px solid var(--border)' }}>
-                        <th style={{ padding: '8px 6px' }}>Von</th>
-                        <th style={{ padding: '8px 6px' }} />
-                        <th style={{ padding: '8px 6px' }}>Nach</th>
-                        <th style={{ padding: '8px 6px' }}>Art</th>
-                        <th style={{ padding: '8px 6px' }}>Notiz</th>
-                        <th style={{ padding: '8px 6px' }} />
-                      </tr>
-                    </thead>
-                    <tbody>
-                      {filteredEdges.map((row) => (
-                        <tr key={row.id} style={{ borderBottom: '1px solid var(--border)' }}>
-                          <td style={{ padding: '8px 6px', verticalAlign: 'top' }}>
-                            <Link to={`/exercises/${row.from_exercise_id}`}>
-                              {row.from_exercise_title || `#${row.from_exercise_id}`}
-                            </Link>
-                          </td>
-                          <td style={{ padding: '8px 6px', color: 'var(--text3)', verticalAlign: 'top' }}>
-                            {row.edge_type === 'sibling' ? '·' : '→'}
-                          </td>
-                          <td style={{ padding: '8px 6px', verticalAlign: 'top' }}>
-                            <Link to={`/exercises/${row.to_exercise_id}`}>
-                              {row.to_exercise_title || `#${row.to_exercise_id}`}
-                            </Link>
-                          </td>
-                          <td style={{ padding: '8px 6px', verticalAlign: 'top' }}>{edgeTypeLabel(row.edge_type)}</td>
-                          <td style={{ padding: '8px 6px', verticalAlign: 'top', maxWidth: '280px' }}>
-                            {editingEdgeNotes === row.id ? (
-                              <>
-                                <textarea
-                                  className="form-input"
-                                  rows={2}
-                                  value={notesDraft}
-                                  onChange={(e) => setNotesDraft(e.target.value)}
-                                />
-                                <button
-                                  type="button"
-                                  className="btn btn-primary"
-                                  style={{ marginTop: '6px', fontSize: '12px', padding: '4px 8px' }}
-                                  onClick={() => saveNotes(row.id)}
-                                >
-                                  Speichern
-                                </button>
-                              </>
-                            ) : (
-                              <>
-                                {row.notes || '—'}
-                                <button
-                                  type="button"
-                                  className="btn"
-                                  style={{ marginLeft: '8px', fontSize: '12px', padding: '4px 8px' }}
-                                  onClick={() => startEditNotes(row)}
-                                >
-                                  Bearbeiten
-                                </button>
-                              </>
-                            )}
-                          </td>
-                          <td style={{ padding: '8px 6px', verticalAlign: 'top' }}>
+      <details className="card" style={{ marginBottom: '12px' }}>
+        <summary style={{ cursor: 'pointer', fontWeight: 600 }}>
+          Technische Kantenliste ({filteredEdges.length}
+          {edges.length !== filteredEdges.length ? ` von ${edges.length}` : ''})
+        </summary>
+        <div style={{ marginTop: '14px' }}>
+          {filteredEdges.length === 0 ? (
+            <p style={{ color: 'var(--text2)', margin: 0 }}>Keine Kanten.</p>
+          ) : (
+            <div style={{ overflowX: 'auto' }}>
+              <table style={{ width: '100%', borderCollapse: 'collapse', fontSize: '13px' }}>
+                <thead>
+                  <tr style={{ textAlign: 'left', borderBottom: '1px solid var(--border)' }}>
+                    <th style={{ padding: '8px 6px' }}>Von</th>
+                    <th style={{ padding: '8px 6px' }} />
+                    <th style={{ padding: '8px 6px' }}>Nach</th>
+                    <th style={{ padding: '8px 6px' }}>Art</th>
+                    <th style={{ padding: '8px 6px' }}>Notiz</th>
+                    <th style={{ padding: '8px 6px' }} />
+                  </tr>
+                </thead>
+                <tbody>
+                  {filteredEdges.map((row) => (
+                    <tr key={row.id} style={{ borderBottom: '1px solid var(--border)' }}>
+                      <td style={{ padding: '8px 6px', verticalAlign: 'top' }}>
+                        <Link to={`/exercises/${row.from_exercise_id}`}>
+                          {row.from_exercise_title || `#${row.from_exercise_id}`}
+                        </Link>
+                      </td>
+                      <td style={{ padding: '8px 6px', color: 'var(--text3)', verticalAlign: 'top' }}>
+                        {row.edge_type === 'sibling' ? '·' : '→'}
+                      </td>
+                      <td style={{ padding: '8px 6px', verticalAlign: 'top' }}>
+                        <Link to={`/exercises/${row.to_exercise_id}`}>
+                          {row.to_exercise_title || `#${row.to_exercise_id}`}
+                        </Link>
+                      </td>
+                      <td style={{ padding: '8px 6px', verticalAlign: 'top' }}>{edgeTypeLabel(row.edge_type)}</td>
+                      <td style={{ padding: '8px 6px', verticalAlign: 'top', maxWidth: '280px' }}>
+                        {editingEdgeNotes === row.id ? (
+                          <>
+                            <textarea
+                              className="form-input"
+                              rows={2}
+                              value={notesDraft}
+                              onChange={(e) => setNotesDraft(e.target.value)}
+                            />
+                            <button
+                              type="button"
+                              className="btn btn-primary"
+                              style={{ marginTop: '6px', fontSize: '12px', padding: '4px 8px' }}
+                              onClick={() => saveNotes(row.id)}
+                            >
+                              Speichern
+                            </button>
+                          </>
+                        ) : (
+                          <>
+                            {row.notes || '—'}
                             <button
                               type="button"
                               className="btn"
-                              style={{
-                                fontSize: '12px',
-                                padding: '4px 8px',
-                                background: 'var(--danger)',
-                                color: '#fff',
-                                border: 'none',
-                              }}
-                              onClick={() => handleDeleteEdge(row.id)}
+                              style={{ marginLeft: '8px', fontSize: '12px', padding: '4px 8px' }}
+                              onClick={() => startEditNotes(row)}
                             >
-                              Löschen
+                              Bearbeiten
                             </button>
-                          </td>
-                        </tr>
-                      ))}
-                    </tbody>
-                  </table>
-                </div>
-              )}
+                          </>
+                        )}
+                      </td>
+                      <td style={{ padding: '8px 6px', verticalAlign: 'top' }}>
+                        <button
+                          type="button"
+                          className="btn"
+                          style={{
+                            fontSize: '12px',
+                            padding: '4px 8px',
+                            background: 'var(--danger)',
+                            color: '#fff',
+                            border: 'none',
+                          }}
+                          onClick={() => handleDeleteEdge(row.id)}
+                        >
+                          Löschen
+                        </button>
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
             </div>
-          </details>
-        </>
-      ) : null}
+          )}
+        </div>
+      </details>
     </div>
   )
 }
+
+export default forwardRef(ExerciseProgressionGraphPanel)
diff --git a/frontend/src/components/ProgressionGraphEditor.jsx b/frontend/src/components/ProgressionGraphEditor.jsx
index 04c0ae4..3a02888 100644
--- a/frontend/src/components/ProgressionGraphEditor.jsx
+++ b/frontend/src/components/ProgressionGraphEditor.jsx
@@ -25,8 +25,10 @@ import {
   applyEvaluateResponseToDraft,
   applyGapOfferToDraft,
   applyMatchResponseToDraft,
+  applyResolvedStructuredToDraft,
   buildPlanningArtifactFromDraft,
   hydrateProgressionGraphDraft,
+  SLOT_MIN,
   insertSlotInDraft,
   librarySlotExercise,
   majorStepsToOverridePayload,
@@ -75,6 +77,8 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
   const [evaluating, setEvaluating] = useState(false)
   const [matching, setMatching] = useState(false)
   const [roadmapLoading, setRoadmapLoading] = useState(false)
+  const [startTargetLoading, setStartTargetLoading] = useState(false)
+  const [startTargetReady, setStartTargetReady] = useState(false)
   const [semanticBrief, setSemanticBrief] = useState(null)
   const [targetSummary, setTargetSummary] = useState(null)
   const [focusAreas, setFocusAreas] = useState([])
@@ -109,12 +113,14 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
       const edgeList = Array.isArray(edges) ? edges : []
       setCurrentEdges(edgeList)
       setGraphMeta(graph)
-      setDraft(
-        hydrateProgressionGraphDraft({
-          artifact: graph?.planning_roadmap,
-          edges: edgeList,
-          graphName: graph?.name,
-        }),
+      const hydrated = hydrateProgressionGraphDraft({
+        artifact: graph?.planning_roadmap,
+        edges: edgeList,
+        graphName: graph?.name,
+      })
+      setDraft(hydrated)
+      setStartTargetReady(
+        Boolean((hydrated.startSituation || '').trim() && (hydrated.targetState || '').trim()),
       )
       const findings = graph?.planning_roadmap?.last_findings
       if (findings) setPathQa(findings)
@@ -270,12 +276,55 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
     return draft.slots.filter((s) => (s.learning_goal || '').trim().length >= 3)
   }, [draft?.slots])
 
+  const runAnalyzeStartTarget = async () => {
+    const q = (draft?.goalQuery || '').trim()
+    if (q.length < 3) {
+      alert('Ziel-Anfrage: mindestens 3 Zeichen.')
+      return
+    }
+    setStartTargetLoading(true)
+    setActionErr('')
+    try {
+      const res = await api.suggestProgressionPath({
+        query: q,
+        max_steps: draft.maxSteps || 5,
+        include_llm_intent: false,
+        include_path_qa: false,
+        include_llm_path_qa: false,
+        include_path_reorder: false,
+        include_ai_gap_fill: false,
+        include_roadmap_preview: false,
+        include_llm_roadmap: false,
+        include_llm_start_target: true,
+        start_target_only: true,
+        progression_graph_id: Number(graphId),
+        ...roadmapStructuredPayload(draft.startSituation, draft.targetState, draft.roadmapNotes),
+      })
+      const roadmap = res?.progression_roadmap
+      if (!roadmap) throw new Error('Keine Start/Ziel-Analyse in der Antwort')
+      setDraft((prev) => {
+        const structured = applyResolvedStructuredToDraft(
+          { ...prev, progressionRoadmap: roadmap },
+          roadmap,
+        )
+        return { ...structured, dirty: true }
+      })
+      setStartTargetReady(true)
+      setSemanticBrief(res?.semantic_brief_summary || null)
+    } catch (e) {
+      setActionErr(e.message || 'Start/Ziel-Analyse fehlgeschlagen')
+    } finally {
+      setStartTargetLoading(false)
+    }
+  }
+
   const runRoadmapGenerate = async () => {
     const q = (draft?.goalQuery || '').trim()
     if (q.length < 3) {
       alert('Ziel-Anfrage: mindestens 3 Zeichen.')
       return
     }
+    const fieldsEmpty = !(draft.startSituation || '').trim() && !(draft.targetState || '').trim()
     setRoadmapLoading(true)
     setActionErr('')
     try {
@@ -289,28 +338,44 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
         include_ai_gap_fill: false,
         include_roadmap_preview: true,
         include_llm_roadmap: true,
+        include_llm_start_target: fieldsEmpty,
         roadmap_only: true,
         progression_graph_id: Number(graphId),
         ...roadmapStructuredPayload(draft.startSituation, draft.targetState, draft.roadmapNotes),
       })
       const roadmap = res?.progression_roadmap
       if (!roadmap) throw new Error('Keine Roadmap in der Antwort')
+      const majorCount = (roadmap?.roadmap?.major_steps || []).length
+      if (majorCount < SLOT_MIN) throw new Error('Roadmap hat zu wenig Stufen.')
       const preservedArtifact = buildPlanningArtifactFromDraft(draft) || {}
+      let startSituation = draft.startSituation
+      let targetState = draft.targetState
+      let roadmapNotes = draft.roadmapNotes
+      if (fieldsEmpty) {
+        const patch = applyResolvedStructuredToDraft(
+          { startSituation, targetState, roadmapNotes },
+          roadmap,
+        )
+        startSituation = patch.startSituation
+        targetState = patch.targetState
+        roadmapNotes = patch.roadmapNotes
+        setStartTargetReady(true)
+      }
       const hydrated = hydrateProgressionGraphDraft({
         artifact: {
           ...preservedArtifact,
           goal_query: q,
           progression_roadmap: roadmap,
-          start_situation: draft.startSituation,
-          target_state: draft.targetState,
-          roadmap_notes: draft.roadmapNotes,
-          max_steps: (roadmap?.roadmap?.major_steps || []).length || draft.maxSteps,
+          start_situation: startSituation,
+          target_state: targetState,
+          roadmap_notes: roadmapNotes,
+          max_steps: majorCount || draft.maxSteps,
         },
         edges: currentEdges,
         graphName: draft.graphName,
       })
       const withPhases = syncSlotPhasesFromRoadmap(hydrated, roadmap)
-      setDraft({ ...withPhases, goalQuery: q, dirty: true })
+      setDraft({ ...withPhases, goalQuery: q, maxSteps: majorCount || withPhases.maxSteps, dirty: true })
       setSemanticBrief(res?.semantic_brief_summary || null)
     } catch (e) {
       setActionErr(e.message || 'Roadmap-Generierung fehlgeschlagen')
@@ -686,38 +751,98 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
         <div>
           <div className="card" style={{ marginBottom: '12px' }}>
             <h3 style={{ marginTop: 0, fontSize: '1rem' }}>Ziel & Roadmap</h3>
-            <div className="form-row">
-              <label className="form-label">Ziel-Anfrage</label>
-              <textarea
-                className="form-input"
-                rows={2}
-                value={draft.goalQuery}
-                disabled={busy}
-                onChange={(e) => patchDraft((d) => ({ ...d, goalQuery: e.target.value }))}
-                placeholder="z. B. Vom Anfänger zum sauberen Gerade-Tritt"
-              />
-            </div>
-            <div className="form-row" style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '10px' }}>
-              <div>
-                <label className="form-label">Start-Situation</label>
+            <div
+              style={{
+                display: 'flex',
+                flexWrap: 'wrap',
+                gap: '10px',
+                alignItems: 'flex-end',
+                marginBottom: '10px',
+              }}
+            >
+              <div className="form-row" style={{ flex: '2 1 240px', marginBottom: 0 }}>
+                <label className="form-label">Ziel / Entwicklungsrichtung</label>
                 <input
                   className="form-input"
+                  value={draft.goalQuery}
+                  disabled={busy}
+                  onChange={(e) => patchDraft((d) => ({ ...d, goalQuery: e.target.value }))}
+                  placeholder="z. B. Von Erlernen bis zur Perfektion des Fußtritts Mae Geri …"
+                />
+              </div>
+              <div className="form-row" style={{ flex: '0 1 100px', marginBottom: 0 }}>
+                <label className="form-label">Stufen (Slots)</label>
+                <input
+                  type="number"
+                  min={SLOT_MIN}
+                  max={SLOT_MAX}
+                  className="form-input"
+                  value={draft.maxSteps}
+                  disabled={busy}
+                  onChange={(e) =>
+                    patchDraft((d) => ({
+                      ...d,
+                      maxSteps: Math.max(SLOT_MIN, Math.min(SLOT_MAX, Number(e.target.value) || 5)),
+                    }))
+                  }
+                />
+              </div>
+            </div>
+            <div
+              style={{
+                display: 'grid',
+                gridTemplateColumns: 'repeat(auto-fit, minmax(220px, 1fr))',
+                gap: '10px',
+              }}
+            >
+              <div className="form-row" style={{ marginBottom: 0 }}>
+                <label className="form-label">Startpunkt / Ausgangslage</label>
+                <textarea
+                  className="form-input"
+                  rows={2}
                   value={draft.startSituation}
                   disabled={busy}
                   onChange={(e) => patchDraft((d) => ({ ...d, startSituation: e.target.value }))}
+                  placeholder="z. B. gleichartige Steppbewegung, vorhersehbar"
                 />
               </div>
-              <div>
-                <label className="form-label">Ziel-Zustand</label>
-                <input
+              <div className="form-row" style={{ marginBottom: 0 }}>
+                <label className="form-label">Zielzustand</label>
+                <textarea
                   className="form-input"
+                  rows={2}
                   value={draft.targetState}
                   disabled={busy}
                   onChange={(e) => patchDraft((d) => ({ ...d, targetState: e.target.value }))}
+                  placeholder="z. B. dynamische Bewegung mit explosivem Angriff und Ausweichen"
+                />
+              </div>
+              <div className="form-row" style={{ marginBottom: 0 }}>
+                <label className="form-label">Ergänzungen (Fokus, Gruppe, Besonderheiten)</label>
+                <textarea
+                  className="form-input"
+                  rows={2}
+                  value={draft.roadmapNotes}
+                  disabled={busy}
+                  onChange={(e) => patchDraft((d) => ({ ...d, roadmapNotes: e.target.value }))}
+                  placeholder="optional: Altersgruppe, Kumite-Kontext, Trainingsfokus …"
                 />
               </div>
             </div>
-            <div style={{ display: 'flex', flexWrap: 'wrap', gap: '8px', marginTop: '8px' }}>
+            <p style={{ fontSize: '11px', color: 'var(--text3)', margin: '8px 0 0', lineHeight: 1.4 }}>
+              Optional zuerst „Start/Ziel analysieren“, anpassen, dann Roadmap-Stufen. Sind Start und Ziel leer,
+              geschieht die Analyse beim Roadmap-Vorschlag automatisch. Manuelle Eingaben haben Vorrang.
+            </p>
+            <div style={{ display: 'flex', flexWrap: 'wrap', gap: '8px', marginTop: '10px', alignItems: 'center' }}>
+              <button
+                type="button"
+                className="btn btn-secondary"
+                disabled={busy || startTargetLoading}
+                onClick={runAnalyzeStartTarget}
+                title="Nur Ausgangslage, Zielzustand und Ergänzungen per KI — ohne Roadmap-Stufen"
+              >
+                {startTargetLoading ? 'Analyse…' : 'Start/Ziel analysieren'}
+              </button>
               <button
                 type="button"
                 className="btn btn-secondary"
@@ -726,6 +851,11 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
               >
                 {roadmapLoading ? 'Roadmap…' : 'Roadmap generieren'}
               </button>
+              {startTargetReady ? (
+                <span className="exercise-tag" style={{ borderColor: 'var(--accent)' }}>
+                  Start/Ziel bereit
+                </span>
+              ) : null}
               <button
                 type="button"
                 className="btn btn-secondary"
diff --git a/frontend/src/components/ProgressionGraphListCard.jsx b/frontend/src/components/ProgressionGraphListCard.jsx
new file mode 100644
index 0000000..fb63381
--- /dev/null
+++ b/frontend/src/components/ProgressionGraphListCard.jsx
@@ -0,0 +1,126 @@
+import React from 'react'
+import { GitBranch, Lock, Users, Globe, Pencil, Trash2 } from 'lucide-react'
+import { graphGoalQueryFromRow, graphSlotCountFromRow } from '../utils/progressionGraphDraft'
+import { EXERCISE_VISIBILITY_FIELD_LABEL } from '../constants/exerciseGovernanceLabels'
+
+const VIS_LABELS = { official: 'Global', club: 'Verein', private: 'Privat' }
+
+function visibilityLabel(v) {
+  return VIS_LABELS[v] || v || '—'
+}
+
+function cardClassName(graph, userId) {
+  const vis = graph.visibility || 'private'
+  const visKey = vis === 'official' || vis === 'club' || vis === 'private' ? vis : 'private'
+  const mine = userId != null && Number(graph.created_by) === Number(userId)
+  return ['card', 'exercise-card', 'progression-graph-card', `exercise-card--scope-${visKey}`, mine ? 'exercise-card--mine' : '']
+    .filter(Boolean)
+    .join(' ')
+}
+
+function VisIcon({ visibility }) {
+  if (visibility === 'official') return <Globe size={14} aria-hidden="true" />
+  if (visibility === 'club') return <Users size={14} aria-hidden="true" />
+  return <Lock size={14} aria-hidden="true" />
+}
+
+export default function ProgressionGraphListCard({
+  graph,
+  userId = null,
+  onOpen,
+  onDelete,
+  disabled = false,
+}) {
+  const goalQuery = graphGoalQueryFromRow(graph)
+  const slotCount = graphSlotCountFromRow(graph)
+  const edgesCount = Number(graph.edges_count) || 0
+  const description = (graph.description || '').trim()
+
+  return (
+    <article className={cardClassName(graph, userId)}>
+      <div className="exercise-card__body">
+        <div className="exercise-card-title" style={{ display: 'flex', alignItems: 'flex-start', gap: '8px' }}>
+          <GitBranch size={18} style={{ flexShrink: 0, marginTop: '2px', color: 'var(--accent)' }} aria-hidden="true" />
+          <button
+            type="button"
+            className="exercise-card__body--clickable"
+            style={{
+              border: 'none',
+              background: 'none',
+              padding: 0,
+              textAlign: 'left',
+              font: 'inherit',
+              color: 'inherit',
+              cursor: disabled ? 'default' : 'pointer',
+              width: '100%',
+            }}
+            disabled={disabled}
+            onClick={() => onOpen?.(graph)}
+          >
+            {graph.name || `Graph #${graph.id}`}
+          </button>
+        </div>
+
+        <div className="exercise-card-tags" style={{ marginTop: '8px' }}>
+          <span className="exercise-tag" title={EXERCISE_VISIBILITY_FIELD_LABEL}>
+            <VisIcon visibility={graph.visibility} />
+            {visibilityLabel(graph.visibility)}
+          </span>
+          {slotCount != null ? (
+            <span className="exercise-tag">{slotCount} Stufen</span>
+          ) : null}
+          <span className="exercise-tag">
+            {edgesCount === 1 ? '1 Kante' : `${edgesCount} Kanten`}
+          </span>
+        </div>
+
+        {goalQuery ? (
+          <p className="exercise-card-summary" style={{ marginTop: '10px' }}>
+            <strong style={{ fontWeight: 600, color: 'var(--text2)' }}>Ziel: </strong>
+            {goalQuery.length > 160 ? `${goalQuery.slice(0, 160)}…` : goalQuery}
+          </p>
+        ) : description ? (
+          <p className="exercise-card-summary" style={{ marginTop: '10px' }}>
+            {description.length > 160 ? `${description.slice(0, 160)}…` : description}
+          </p>
+        ) : (
+          <p className="exercise-card-summary muted" style={{ marginTop: '10px' }}>
+            Noch kein Planungsziel hinterlegt — öffnen und Roadmap anlegen.
+          </p>
+        )}
+      </div>
+
+      <div
+        className="exercise-card-layout"
+        style={{
+          padding: '10px 14px 14px',
+          borderTop: '1px solid var(--border)',
+          display: 'flex',
+          gap: '8px',
+          flexWrap: 'wrap',
+        }}
+      >
+        <button
+          type="button"
+          className="btn btn-primary"
+          style={{ fontSize: '12px', padding: '6px 12px' }}
+          disabled={disabled}
+          onClick={() => onOpen?.(graph)}
+        >
+          <Pencil size={14} style={{ marginRight: '4px', verticalAlign: '-2px' }} aria-hidden="true" />
+          Bearbeiten
+        </button>
+        <button
+          type="button"
+          className="btn"
+          style={{ fontSize: '12px', padding: '6px 12px' }}
+          disabled={disabled}
+          onClick={() => onDelete?.(graph)}
+        >
+          <Trash2 size={14} style={{ marginRight: '4px', verticalAlign: '-2px' }} aria-hidden="true" />
+          Löschen
+        </button>
+      </div>
+    </article>
+  )
+}
diff --git a/frontend/src/components/exercises/ExercisesListPageRoot.jsx b/frontend/src/components/exercises/ExercisesListPageRoot.jsx
index 361a38a..ea03bee 100644
--- a/frontend/src/components/exercises/ExercisesListPageRoot.jsx
+++ b/frontend/src/components/exercises/ExercisesListPageRoot.jsx
@@ -95,6 +95,7 @@ function ExercisesListPageRoot() {
   const [quickSaving, setQuickSaving] = useState(false)
   const [quickAiError, setQuickAiError] = useState('')
   const [quickCreateDraft, setQuickCreateDraft] = useState(null)
+  const progressionPanelRef = useRef(null)
 
   const planningKi = usePlanningExerciseSuggestSearch({
     enabled: pageTab === 'list' && aiQuickCreateEnabled,
@@ -653,7 +654,13 @@ function ExercisesListPageRoot() {
             )}
           </div>
         ) : (
-          <span aria-hidden="true" />
+          <button
+            type="button"
+            className="btn btn-primary"
+            onClick={() => progressionPanelRef.current?.openCreateDialog?.()}
+          >
+            + Neu
+          </button>
         )}
       </div>
 
@@ -676,7 +683,7 @@ function ExercisesListPageRoot() {
             </div>
           }
         >
-          <ExerciseProgressionGraphPanel />
+          <ExerciseProgressionGraphPanel ref={progressionPanelRef} />
         </Suspense>
       ) : (
         <>
diff --git a/frontend/src/utils/progressionGraphDraft.js b/frontend/src/utils/progressionGraphDraft.js
index 2718e63..18ee771 100644
--- a/frontend/src/utils/progressionGraphDraft.js
+++ b/frontend/src/utils/progressionGraphDraft.js
@@ -4,8 +4,53 @@
 
 export const ROADMAP_PHASES = ['einstieg', 'grundlage', 'vertiefung', 'anwendung', 'perfektion']
 export const SLOT_MAX = 10
+export const SLOT_MIN = 2
 export const PLANNING_ARTIFACT_SCHEMA = 1
 
+/** Start/Ziel/Ergänzungen aus KI-Roadmap-Antwort (resolved_structured). */
+export function resolvedStructuredFromRoadmap(progressionRoadmap) {
+  const rs = progressionRoadmap?.resolved_structured
+  if (!rs) return null
+  const patch = {}
+  if (rs.start_situation) patch.startSituation = String(rs.start_situation)
+  if (rs.target_state) patch.targetState = String(rs.target_state)
+  if (rs.roadmap_notes) patch.roadmapNotes = String(rs.roadmap_notes)
+  return Object.keys(patch).length ? patch : null
+}
+
+export function applyResolvedStructuredToDraft(draft, progressionRoadmap, { onlyIfEmpty = false } = {}) {
+  const patch = resolvedStructuredFromRoadmap(progressionRoadmap)
+  if (!patch) return draft
+  const next = { ...draft }
+  if (patch.startSituation && (!onlyIfEmpty || !(draft.startSituation || '').trim())) {
+    next.startSituation = patch.startSituation
+  }
+  if (patch.targetState && (!onlyIfEmpty || !(draft.targetState || '').trim())) {
+    next.targetState = patch.targetState
+  }
+  if (patch.roadmapNotes && (!onlyIfEmpty || !(draft.roadmapNotes || '').trim())) {
+    next.roadmapNotes = patch.roadmapNotes
+  }
+  return { ...next, dirty: true }
+}
+
+export function graphGoalQueryFromRow(graph) {
+  const art = graph?.planning_roadmap
+  if (!art || typeof art !== 'object') return ''
+  return (art.goal_query || '').trim()
+}
+
+export function graphSlotCountFromRow(graph) {
+  const art = graph?.planning_roadmap
+  if (!art || typeof art !== 'object') return null
+  const slots = art.slot_contents
+  if (Array.isArray(slots) && slots.length) return slots.length
+  const majors = art.progression_roadmap?.roadmap?.major_steps
+  if (Array.isArray(majors) && majors.length) return majors.length
+  const ms = Number(art.max_steps)
+  return Number.isFinite(ms) && ms > 0 ? ms : null
+}
+
 const OFFER_SOURCE_LABELS = {
   unfilled_gap: 'Lücke',
   off_topic: 'Themenfremd',

From 18547613ead964b7cf21bd6a2250d3bd6c77aaf4 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Wed, 10 Jun 2026 16:39:17 +0200
Subject: [PATCH 15/33] Implement Stage Learning Goal Features in Planning
 Exercise

- Added `semantic_brief_for_stage` function to enhance semantic briefs with stage learning goals for improved roadmap matching.
- Introduced `exercise_passes_stage_learning_goal_gate` to validate exercises against stage learning goals, enhancing relevance checks.
- Updated path retrieval and scoring logic to incorporate stage learning goals, allowing for more nuanced exercise selection.
- Enhanced UI to indicate weak matches with stage learning goals, improving user feedback on exercise relevance.
- Incremented application version to reflect these updates.
---
 backend/planning_exercise_path_builder.py     |  52 ++++----
 backend/planning_exercise_path_qa.py          |  36 ++++-
 backend/planning_exercise_retrieval.py        |  24 +++-
 backend/planning_exercise_semantics.py        | 124 +++++++++++++++++-
 .../test_planning_roadmap_stage_match.py      |  96 ++++++++++++++
 backend/version.py                            |  11 +-
 .../PLANNING_PROGRESSION_GRAPH_KI.md          |  35 +++--
 .../ExerciseProgressionPathBuilder.jsx        |   5 +
 8 files changed, 339 insertions(+), 44 deletions(-)
 create mode 100644 backend/tests/test_planning_roadmap_stage_match.py

diff --git a/backend/planning_exercise_path_builder.py b/backend/planning_exercise_path_builder.py
index 364448a..7dc0b4c 100644
--- a/backend/planning_exercise_path_builder.py
+++ b/backend/planning_exercise_path_builder.py
@@ -38,6 +38,7 @@ from planning_exercise_semantics import (
     exercise_passes_path_semantic_gate,
     pick_best_path_hit,
     resolve_semantic_skill_weights,
+    semantic_brief_for_stage,
     step_phase_for_index,
     step_retrieval_query,
     try_enrich_semantic_brief_with_llm,
@@ -183,8 +184,16 @@ def _pick_best_path_hit(
     used_exercise_ids: Set[int],
     *,
     semantic_brief: Optional[PlanningSemanticBrief] = None,
+    stage_learning_goal: Optional[str] = None,
+    roadmap_stage_match: bool = False,
 ) -> Optional[Dict[str, Any]]:
-    return pick_best_path_hit(hits, used_exercise_ids, semantic_brief=semantic_brief)
+    return pick_best_path_hit(
+        hits,
+        used_exercise_ids,
+        semantic_brief=semantic_brief,
+        stage_learning_goal=stage_learning_goal,
+        roadmap_stage_match=roadmap_stage_match,
+    )
 
 
 def _build_path_target_profile(
@@ -282,6 +291,7 @@ def _run_path_step_retrieval(
     step_query_override: Optional[str] = None,
     step_phase_override: Optional[str] = None,
     step_target_profile_override: Optional[PlanningTargetProfile] = None,
+    stage_learning_goal: Optional[str] = None,
 ) -> Tuple[List[Dict[str, Any]], PlanningTargetProfile, Dict[str, Any], str]:
     step_query = step_query_override or step_retrieval_query(
         semantic_brief, goal_query, step_index, max_steps
@@ -317,6 +327,8 @@ def _run_path_step_retrieval(
         "retrieval_query": step_query,
         "path_step_phase": step_phase_override
         or step_phase_for_index(semantic_brief, step_index, max_steps),
+        "stage_learning_goal": (stage_learning_goal or "").strip() or None,
+        "roadmap_stage_match": bool((stage_learning_goal or "").strip()),
     }
     pack = apply_progression_context_to_pack(
         cur,
@@ -556,6 +568,12 @@ def _build_steps_roadmap_first(
             major_step=major,
         )
         step_kind = resolve_step_exercise_kind_filter(stage_spec, body.exercise_kind_any)
+        stage_goal = (stage_spec.learning_goal or "").strip()
+        stage_brief = semantic_brief_for_stage(
+            semantic_brief,
+            learning_goal=stage_goal,
+            phase=major.phase if major else None,
+        )
 
         hits, _, _, _ = _run_path_step_retrieval(
             cur,
@@ -569,36 +587,22 @@ def _build_steps_roadmap_first(
             progression_graph_id=body.progression_graph_id,
             include_llm_intent=body.include_llm_intent and step_index == 0,
             exercise_kind_any=step_kind,
-            semantic_brief=semantic_brief,
+            semantic_brief=stage_brief,
             path_target_profile=path_target_profile,
             path_intent=path_intent,
             step_query_override=step_query,
             step_phase_override=major.phase if major else None,
             step_target_profile_override=step_target,
+            stage_learning_goal=stage_goal or None,
         )
 
-        hit = _pick_best_path_hit(hits, used, semantic_brief=semantic_brief)
-        if not hit and step_query != goal_query:
-            hits, _, _, _ = _run_path_step_retrieval(
-                cur,
-                tenant=tenant,
-                goal_query=goal_query,
-                step_index=step_index,
-                max_steps=max_steps,
-                planned_ids=planned_ids,
-                anchor_id=anchor_id,
-                anchor_variant_id=anchor_variant_id,
-                progression_graph_id=body.progression_graph_id,
-                include_llm_intent=False,
-                exercise_kind_any=step_kind,
-                semantic_brief=semantic_brief,
-                path_target_profile=path_target_profile,
-                path_intent=path_intent,
-                step_query_override=goal_query,
-                step_phase_override=major.phase if major else None,
-                step_target_profile_override=step_target,
-            )
-            hit = _pick_best_path_hit(hits, used, semantic_brief=semantic_brief)
+        hit = _pick_best_path_hit(
+            hits,
+            used,
+            semantic_brief=stage_brief,
+            stage_learning_goal=stage_goal or None,
+            roadmap_stage_match=True,
+        )
 
         if not hit:
             unfilled.append((step_index, stage_spec))
diff --git a/backend/planning_exercise_path_qa.py b/backend/planning_exercise_path_qa.py
index 2f41247..2fdf291 100644
--- a/backend/planning_exercise_path_qa.py
+++ b/backend/planning_exercise_path_qa.py
@@ -20,7 +20,9 @@ from planning_exercise_semantics import (
     PlanningSemanticBrief,
     brief_to_summary_dict,
     exercise_passes_path_semantic_gate,
+    exercise_passes_stage_learning_goal_gate,
     score_exercise_semantic_relevance,
+    semantic_brief_for_stage,
     step_phase_for_index,
 )
 
@@ -407,21 +409,49 @@ def detect_off_topic_steps(
         if step.get("is_ai_proposal") or step.get("exercise_id") is None:
             continue
         bundle = _load_exercise_text_bundle(cur, int(step["exercise_id"]))
-        phase = step_phase_for_index(brief, idx, total)
+        stage_goal = (step.get("roadmap_learning_goal") or "").strip()
+        phase = (step.get("roadmap_phase") or "").strip().lower() or step_phase_for_index(
+            brief, idx, total
+        )
+        step_brief = (
+            semantic_brief_for_stage(brief, learning_goal=stage_goal, phase=phase or None)
+            if stage_goal
+            else brief
+        )
         sem, sem_reasons = score_exercise_semantic_relevance(
             title=bundle["title"],
             summary=bundle["summary"],
             goal=bundle["goal"],
             variant_names=bundle["variant_names"],
-            brief=brief,
+            brief=step_brief,
             step_phase=phase,
         )
+        if stage_goal and not exercise_passes_stage_learning_goal_gate(
+            learning_goal=stage_goal,
+            title=bundle["title"],
+            summary=bundle["summary"],
+            goal=bundle["goal"],
+            semantic_score=sem,
+        ):
+            off_topic.append(
+                {
+                    "step_index": idx,
+                    "exercise_id": int(step["exercise_id"]),
+                    "title": step.get("title") or bundle["title"],
+                    "semantic_score": round(sem, 4),
+                    "expected_phase": phase,
+                    "issue": "stage_mismatch",
+                    "roadmap_learning_goal": stage_goal,
+                    "reasons": sem_reasons[:3],
+                }
+            )
+            continue
         if exercise_passes_path_semantic_gate(
             semantic_score=sem,
             title=bundle["title"],
             summary=bundle["summary"],
             goal=bundle["goal"],
-            brief=brief,
+            brief=step_brief,
             strict=True,
         ):
             continue
diff --git a/backend/planning_exercise_retrieval.py b/backend/planning_exercise_retrieval.py
index dcb928e..42af3e8 100644
--- a/backend/planning_exercise_retrieval.py
+++ b/backend/planning_exercise_retrieval.py
@@ -17,6 +17,7 @@ from planning_exercise_profiles import (
 from planning_exercise_semantics import (
     PlanningSemanticBrief,
     exercise_passes_path_semantic_gate,
+    exercise_passes_stage_learning_goal_gate,
     score_exercise_semantic_relevance,
 )
 
@@ -200,6 +201,8 @@ def rank_visible_library_hits(
         semantic_brief = semantic_brief_raw
     step_phase = pack.get("path_step_phase")
     path_mode = pack.get("context_mode") == "progression_path"
+    stage_learning_goal = (pack.get("stage_learning_goal") or "").strip()
+    roadmap_stage_match = bool(pack.get("roadmap_stage_match"))
 
     last_planned_skills: Set[int] = set()
     planned_ids = pack.get("planned_exercise_ids") or []
@@ -279,6 +282,8 @@ def rank_visible_library_hits(
                 step_phase=step_phase,
             )
 
+        score_penalty = 0.0
+        stage_match_reason: Optional[str] = None
         if (
             path_mode
             and semantic_brief
@@ -293,8 +298,21 @@ def rank_visible_library_hits(
             )
         ):
             score_penalty = 0.42
-        else:
-            score_penalty = 0.0
+        if roadmap_stage_match and stage_learning_goal:
+            title_s = str(row.get("title") or "")
+            summary_s = str(row.get("summary") or "")
+            goal_s = goals_by_ex.get(eid, "")
+            if exercise_passes_stage_learning_goal_gate(
+                learning_goal=stage_learning_goal,
+                title=title_s,
+                summary=summary_s,
+                goal=goal_s,
+                semantic_score=semantic_score,
+            ):
+                score_penalty = max(0.0, score_penalty - 0.08)
+                stage_match_reason = "Passt zum Stufen-Lernziel"
+            else:
+                score_penalty += 0.35
 
         score = (
             weights.get("semantic", 0.0) * semantic_score
@@ -309,6 +327,8 @@ def rank_visible_library_hits(
         )
 
         reasons: List[str] = []
+        if stage_match_reason:
+            reasons.append(stage_match_reason)
         if semantic_score >= 0.35 and semantic_reasons:
             for sr in semantic_reasons:
                 if sr not in reasons:
diff --git a/backend/planning_exercise_semantics.py b/backend/planning_exercise_semantics.py
index 7571233..e91a6a0 100644
--- a/backend/planning_exercise_semantics.py
+++ b/backend/planning_exercise_semantics.py
@@ -604,6 +604,103 @@ def apply_path_retrieval_weights(brief: PlanningSemanticBrief) -> Dict[str, floa
     }
 
 
+_STAGE_GOAL_STOPWORDS = _QUERY_STOPWORDS | frozenset(
+    {
+        "stufe",
+        "phase",
+        "lernziel",
+        "grundlage",
+        "vertiefung",
+        "anwendung",
+        "perfektion",
+        "einstieg",
+        "sicher",
+        "sauber",
+        "korrekt",
+        "technik",
+        "training",
+    }
+)
+
+
+def _significant_stage_tokens(learning_goal: str) -> List[str]:
+    """Wörter aus Stufen-Lernziel für Text-Match (ohne Füllwörter)."""
+    raw = re.findall(r"[a-zäöüß]{4,}", _normalize_phrase(learning_goal), flags=re.IGNORECASE)
+    out: List[str] = []
+    for w in raw:
+        low = w.lower().replace("ä", "ae").replace("ö", "oe").replace("ü", "ue")
+        if low in _STAGE_GOAL_STOPWORDS:
+            continue
+        if low not in out:
+            out.append(low)
+    return out[:10]
+
+
+def semantic_brief_for_stage(
+    brief: PlanningSemanticBrief,
+    *,
+    learning_goal: str,
+    phase: Optional[str] = None,
+) -> PlanningSemanticBrief:
+    """Brief um Stufen-Lernziel erweitern — für Roadmap-Match pro Major Step."""
+    lg = _normalize_phrase(learning_goal)
+    if not lg:
+        return brief
+    must = list(brief.must_phrases or [])
+    if lg not in must:
+        must.insert(0, lg[:120])
+    arc = list(brief.development_arc or [])
+    ph = (phase or "").strip().lower()
+    if ph and ph not in arc:
+        arc = [ph, *arc]
+    strength = max(float(brief.semantic_strength or 0.0), 0.58)
+    return brief.model_copy(
+        update={
+            "must_phrases": must[:12],
+            "development_arc": arc[:8],
+            "semantic_strength": min(1.0, strength),
+        }
+    )
+
+
+def exercise_passes_stage_learning_goal_gate(
+    *,
+    learning_goal: str,
+    title: str,
+    summary: str = "",
+    goal: str = "",
+    semantic_score: float = 0.0,
+    min_semantic: float = 0.20,
+    relaxed: bool = False,
+) -> bool:
+    """Roadmap-Stufe: Übung muss zum Stufen-Lernziel passen, nicht nur zum Gesamtthema."""
+    lg = (learning_goal or "").strip()
+    if len(lg) < 3:
+        return True
+
+    blob = _blob_from_fields(title, summary, goal, [])
+    norm_lg = _normalize_phrase(lg)
+    if _phrase_in_blob(norm_lg, blob):
+        return True
+
+    tokens = _significant_stage_tokens(lg)
+    if not tokens:
+        threshold = 0.12 if relaxed else min_semantic
+        return semantic_score >= threshold
+
+    hits = sum(1 for t in tokens if _phrase_in_blob(t, blob))
+    if len(tokens) <= 2:
+        required = 1
+    else:
+        required = max(2, (len(tokens) + 1) // 2)
+
+    if hits >= required:
+        return True
+
+    threshold = 0.14 if relaxed else min_semantic
+    return semantic_score >= threshold
+
+
 def exercise_passes_path_semantic_gate(
     *,
     semantic_score: float,
@@ -641,11 +738,15 @@ def pick_best_path_hit(
     used_exercise_ids: Set[int],
     *,
     semantic_brief: Optional[PlanningSemanticBrief] = None,
+    stage_learning_goal: Optional[str] = None,
+    roadmap_stage_match: bool = False,
 ) -> Optional[Dict[str, Any]]:
-    """Gestufte Auswahl: strikt → relaxed → bester Semantik-Score."""
+    """Gestufte Auswahl: strikt → relaxed → optional Notfall-Fallback."""
     if not hits:
         return None
 
+    stage_goal = (stage_learning_goal or "").strip()
+
     def _scan(*, strict: bool) -> Optional[Dict[str, Any]]:
         best: Optional[Dict[str, Any]] = None
         best_key: Tuple[float, float] = (-1.0, -1.0)
@@ -654,15 +755,25 @@ def pick_best_path_hit(
             if eid in used_exercise_ids:
                 continue
             sem = float(hit.get("semantic_score") or 0.0)
+            title = str(hit.get("title") or "")
+            summary = str(hit.get("summary") or "")
             if semantic_brief and not exercise_passes_path_semantic_gate(
                 semantic_score=sem,
-                title=str(hit.get("title") or ""),
-                summary=str(hit.get("summary") or ""),
+                title=title,
+                summary=summary,
                 goal="",
                 brief=semantic_brief,
                 strict=strict,
             ):
                 continue
+            if stage_goal and not exercise_passes_stage_learning_goal_gate(
+                learning_goal=stage_goal,
+                title=title,
+                summary=summary,
+                semantic_score=sem,
+                relaxed=not strict,
+            ):
+                continue
             score = float(hit.get("score") or 0.0)
             key = (sem, score)
             if key > best_key:
@@ -677,7 +788,10 @@ def pick_best_path_hit(
     if chosen:
         return chosen
 
-    # Notfall: bester verbleibender Treffer mit Semantik > 0 (Thema trotzdem priorisieren)
+    if roadmap_stage_match:
+        return None
+
+    # Notfall (nur retrieval-first / Brücken): bester verbleibender Treffer
     fallback: Optional[Dict[str, Any]] = None
     fallback_key: Tuple[float, float] = (-1.0, -1.0)
     for hit in hits:
@@ -706,8 +820,10 @@ __all__ = [
     "build_semantic_brief",
     "enrich_target_with_semantic_expectations",
     "exercise_passes_path_semantic_gate",
+    "exercise_passes_stage_learning_goal_gate",
     "merge_semantic_brief_llm",
     "pick_best_path_hit",
+    "semantic_brief_for_stage",
     "resolve_semantic_skill_weights",
     "score_exercise_semantic_relevance",
     "semantic_core_phrases",
diff --git a/backend/tests/test_planning_roadmap_stage_match.py b/backend/tests/test_planning_roadmap_stage_match.py
new file mode 100644
index 0000000..6fc529a
--- /dev/null
+++ b/backend/tests/test_planning_roadmap_stage_match.py
@@ -0,0 +1,96 @@
+"""Tests Roadmap-Stufen-Match — Gate gegen themenfremde Übungen."""
+from planning_exercise_semantics import (
+    exercise_passes_stage_learning_goal_gate,
+    pick_best_path_hit,
+    semantic_brief_for_stage,
+    build_semantic_brief,
+)
+
+
+def test_stage_gate_accepts_learning_goal_in_title():
+    assert exercise_passes_stage_learning_goal_gate(
+        learning_goal="variable Rhythmen und Hüftmobilität für Mae Geri",
+        title="Mae Geri — variable Rhythmen",
+        summary="",
+        semantic_score=0.1,
+    )
+
+
+def test_stage_gate_rejects_unrelated_kumite():
+    assert not exercise_passes_stage_learning_goal_gate(
+        learning_goal="variable Rhythmen und Hüftmobilität für Mae Geri",
+        title="Kumite Grundstellungen",
+        summary="Partnerarbeit Distanz",
+        semantic_score=0.05,
+    )
+
+
+def test_semantic_brief_for_stage_adds_learning_goal():
+    brief = build_semantic_brief("Mae Geri Perfektion")
+    stage = semantic_brief_for_stage(
+        brief,
+        learning_goal="Hüftmobilität und Kammerhaltung",
+        phase="grundlage",
+    )
+    assert "hüftmobilität und kammerhaltung" in stage.must_phrases[0]
+
+
+def test_pick_best_path_hit_roadmap_stage_no_weak_fallback():
+    brief = build_semantic_brief("Mae Geri Perfektion")
+    stage_brief = semantic_brief_for_stage(
+        brief,
+        learning_goal="Hüftmobilität für Mae Geri",
+        phase="grundlage",
+    )
+    hits = [
+        {
+            "id": 1,
+            "title": "Kumite Stellungen",
+            "summary": "Partner Distanz",
+            "score": 0.92,
+            "semantic_score": 0.08,
+        },
+        {
+            "id": 2,
+            "title": "Kraft-Ausdauer Zirkel",
+            "summary": "allgemeine Fitness",
+            "score": 0.88,
+            "semantic_score": 0.02,
+        },
+    ]
+    chosen = pick_best_path_hit(
+        hits,
+        set(),
+        semantic_brief=stage_brief,
+        stage_learning_goal="Hüftmobilität für Mae Geri",
+        roadmap_stage_match=True,
+    )
+    assert chosen is None
+
+
+def test_pick_best_path_hit_roadmap_stage_picks_relevant():
+    brief = build_semantic_brief("Mae Geri Perfektion")
+    stage_brief = semantic_brief_for_stage(
+        brief,
+        learning_goal="Hüftmobilität für Mae Geri",
+        phase="grundlage",
+    )
+    hits = [
+        {"id": 1, "title": "Kumite", "score": 0.9, "semantic_score": 0.1},
+        {
+            "id": 2,
+            "title": "Mae Geri Hüftmobilität",
+            "summary": "Kammerhaltung und Hüfte",
+            "score": 0.7,
+            "semantic_score": 0.55,
+        },
+    ]
+    chosen = pick_best_path_hit(
+        hits,
+        set(),
+        semantic_brief=stage_brief,
+        stage_learning_goal="Hüftmobilität für Mae Geri",
+        roadmap_stage_match=True,
+    )
+    assert chosen is not None
+    assert int(chosen["id"]) == 2
diff --git a/backend/version.py b/backend/version.py
index d3ab790..00dacd4 100644
--- a/backend/version.py
+++ b/backend/version.py
@@ -1,6 +1,6 @@
 # Shinkan Jinkendo Version Information
 
-APP_VERSION = "0.8.217"
+APP_VERSION = "0.8.218"
 BUILD_DATE = "2026-06-07"
 DB_SCHEMA_VERSION = "20260607088"
 
@@ -53,6 +53,15 @@ MODULE_VERSIONS = {
 }
 
 CHANGELOG = [
+    {
+        "version": "0.8.218",
+        "date": "2026-06-07",
+        "changes": [
+            "Roadmap-Match: Stufen-Lernziel-Gate (semantic_brief_for_stage, stage_learning_goal).",
+            "Kein Fallback auf globale goal_query bei roadmap_first — Lücke statt falscher Übung.",
+            "Retrieval-Strafe/Bonus für Stufen-Passung; QS erkennt stage_mismatch.",
+        ],
+    },
     {
         "version": "0.8.217",
         "date": "2026-06-07",
diff --git a/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md b/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md
index 246493a..bacadd1 100644
--- a/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md
+++ b/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md
@@ -1,6 +1,6 @@
 # Progressionsgraph — KI-Planung (Ist-Stand)
 
-**Stand:** 2026-05-22 (Dokumentation) · **App-Version:** **0.8.217** · **DB:** Migration **088**  
+**Stand:** 2026-05-22 (Dokumentation) · **App-Version:** **0.8.218** · **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.  
@@ -157,7 +157,21 @@ flowchart TB
 
 ---
 
-## 5. Rolle des bestehenden Graphs
+## 5. Roadmap-Match — Stufen-Qualität (0.8.218)
+
+Pro Major Step gilt:
+
+1. **Stufen-Brief** — `semantic_brief_for_stage()` ergänzt `must_phrases` um das Stufen-Lernziel.
+2. **Stufen-Gate** — `exercise_passes_stage_learning_goal_gate()` prüft Lernziel-Text in Titel/Summary/Ziel oder Mindest-`semantic_score`.
+3. **Kein Fallback** — Bei `roadmap_first` wird **nicht** auf die globale `goal_query` zurückgefallen; passt keine Übung → **Lücke** (`roadmap_unfilled`) statt themenfremder Übung.
+4. **Retrieval** — Bonus/Strafe im Hybrid-Score je nach Stufen-Passung.
+5. **QS** — `detect_off_topic_steps` erkennt `stage_mismatch` anhand `roadmap_learning_goal`.
+
+Tests: `test_planning_roadmap_stage_match.py`
+
+---
+
+## 6. Rolle des bestehenden Graphs
 
 **Wichtig — häufiges Missverständnis:**
 
@@ -174,7 +188,7 @@ Code: `planning_exercise_progression.py` → `apply_progression_context_to_pack`
 
 ---
 
-## 6. Persistenz
+## 7. Persistenz
 
 ### 6.1 Kanten (`exercise_progression_edges`)
 
@@ -211,7 +225,7 @@ Validierung: `progression_graph_planning_artifact.py` · Tests: `test_progressio
 
 ---
 
-## 7. Fähigkeiten-Scoring-Anbindung
+## 8. Fähigkeiten-Scoring-Anbindung
 
 Modul: `planning_skill_expectations.py`
 
@@ -231,7 +245,7 @@ Integration:
 
 ---
 
-## 8. KI-Lücken (Gap-Fill)
+## 9. KI-Lücken (Gap-Fill)
 
 Flow:
 1. `roadmap_unfilled` / QA-Lücken → `gap_fill_offers`
@@ -243,7 +257,7 @@ Kontext-Helfer: `frontend/src/utils/planningContextForExerciseAi.js`
 
 ---
 
-## 9. Implementierungsstände (Phasen)
+## 10. Implementierungsstände (Phasen)
 
 | Phase | Inhalt | Status | Version |
 |-------|--------|--------|---------|
@@ -255,12 +269,13 @@ Kontext-Helfer: `frontend/src/utils/planningContextForExerciseAi.js`
 | 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 |
+| F10 | Stufen-Lernziel-Gate beim Match (kein goal_query-Fallback) | ✅ | 0.8.218 |
 | **G** | Trainingsplanung eigene Pipeline + Graph-Referenz | 🔲 | — |
 | **UX** | Wizard/Stepper statt Scroll-Monolith | 🔲 | separater Chat |
 
 ---
 
-## 10. Offenes Backlog (priorisiert)
+## 11. Offenes Backlog (priorisiert)
 
 1. **UI-Überarbeitung** — Wizard mit 4 Schritten, progressive disclosure (Briefing unten)
 2. **Graph-Erweiterungsmodus** — Start ab gewähltem Knoten / letzter Sequenz
@@ -277,7 +292,7 @@ Kern: Wizard ① Ziel & Start/Ziel → ② Roadmap → ③ Match → ④ Lücken
 
 ---
 
-## 11. Tests
+## 12. Tests
 
 | Datei | Abdeckung |
 |-------|-----------|
@@ -291,7 +306,7 @@ Kern: Wizard ① Ziel & Start/Ziel → ② Roadmap → ③ Match → ④ Lücken
 
 ---
 
-## 12. Dokumenten-Index (Drift vermeiden)
+## 13. Dokumenten-Index (Drift vermeiden)
 
 | Frage | Primäre Quelle |
 |-------|----------------|
@@ -307,7 +322,7 @@ Kern: Wizard ① Ziel & Start/Ziel → ② Roadmap → ③ Match → ④ Lücken
 
 ---
 
-## 13. Changelog (Dokument)
+## 14. Changelog (Dokument)
 
 | Datum | Änderung |
 |-------|----------|
diff --git a/frontend/src/components/ExerciseProgressionPathBuilder.jsx b/frontend/src/components/ExerciseProgressionPathBuilder.jsx
index a80812d..598a620 100644
--- a/frontend/src/components/ExerciseProgressionPathBuilder.jsx
+++ b/frontend/src/components/ExerciseProgressionPathBuilder.jsx
@@ -1895,6 +1895,11 @@ export default function ExerciseProgressionPathBuilder({
                       : ''}
                     {step.roadmapPhase ? ` (${step.roadmapPhase})` : ''}
                     {step.isOffTopic ? ' (themenfremd)' : ''}
+                    {step.semanticScore != null &&
+                    Number(step.semanticScore) < 0.22 &&
+                    step.roadmapLearningGoal ? (
+                      <span style={{ color: 'var(--danger)' }}> (schwaches Stufen-Match)</span>
+                    ) : null}
                     {step.isFromGraph ? ' (im Graph)' : ''}
                     {step.isAiProposal ? ' (KI-Neu)' : step.isBridge ? ' (Brücke)' : ''}
                   </label>

From 07e147bc767c751060fbede402446580da96c91d Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Wed, 10 Jun 2026 17:02:21 +0200
Subject: [PATCH 16/33] Enhance Stage Matching and Retrieval Logic in Planning
 Exercise

- Introduced `build_stage_match_brief` to create stage-specific semantic briefs, improving roadmap matching accuracy.
- Updated path retrieval logic to differentiate between general and stage-specific semantic weights, enhancing exercise relevance.
- Added support for anti-patterns and success criteria in stage matching, allowing for more nuanced exercise selection.
- Enhanced tests to validate new stage matching features and ensure correct functionality against learning goals.
- Incremented application version to reflect these updates.
---
 backend/planning_exercise_path_builder.py     |  51 ++-
 backend/planning_exercise_path_qa.py          |   2 +
 backend/planning_exercise_retrieval.py        |  85 +++-
 backend/planning_exercise_semantics.py        | 417 +++++++++++++++---
 .../test_planning_roadmap_stage_match.py      |  99 ++++-
 backend/version.py                            |  18 +-
 6 files changed, 591 insertions(+), 81 deletions(-)

diff --git a/backend/planning_exercise_path_builder.py b/backend/planning_exercise_path_builder.py
index 7dc0b4c..473c228 100644
--- a/backend/planning_exercise_path_builder.py
+++ b/backend/planning_exercise_path_builder.py
@@ -32,13 +32,14 @@ from planning_exercise_retrieval import run_multistage_planning_retrieval
 from planning_exercise_semantics import (
     PlanningSemanticBrief,
     apply_path_retrieval_weights,
+    apply_stage_match_retrieval_weights,
     brief_to_summary_dict,
     build_semantic_brief,
+    build_stage_match_brief,
     enrich_target_with_semantic_expectations,
     exercise_passes_path_semantic_gate,
     pick_best_path_hit,
     resolve_semantic_skill_weights,
-    semantic_brief_for_stage,
     step_phase_for_index,
     step_retrieval_query,
     try_enrich_semantic_brief_with_llm,
@@ -185,14 +186,18 @@ def _pick_best_path_hit(
     *,
     semantic_brief: Optional[PlanningSemanticBrief] = None,
     stage_learning_goal: Optional[str] = None,
+    stage_anti_patterns: Optional[List[str]] = None,
     roadmap_stage_match: bool = False,
+    stage_match_brief: Optional[PlanningSemanticBrief] = None,
 ) -> Optional[Dict[str, Any]]:
     return pick_best_path_hit(
         hits,
         used_exercise_ids,
         semantic_brief=semantic_brief,
         stage_learning_goal=stage_learning_goal,
+        stage_anti_patterns=stage_anti_patterns,
         roadmap_stage_match=roadmap_stage_match,
+        stage_match_brief=stage_match_brief,
     )
 
 
@@ -292,6 +297,11 @@ def _run_path_step_retrieval(
     step_phase_override: Optional[str] = None,
     step_target_profile_override: Optional[PlanningTargetProfile] = None,
     stage_learning_goal: Optional[str] = None,
+    stage_anti_patterns: Optional[List[str]] = None,
+    stage_match_brief: Optional[PlanningSemanticBrief] = None,
+    stage_success_criteria: Optional[List[str]] = None,
+    stage_load_profile: Optional[List[str]] = None,
+    path_context_note: Optional[str] = None,
 ) -> Tuple[List[Dict[str, Any]], PlanningTargetProfile, Dict[str, Any], str]:
     step_query = step_query_override or step_retrieval_query(
         semantic_brief, goal_query, step_index, max_steps
@@ -328,7 +338,12 @@ def _run_path_step_retrieval(
         "path_step_phase": step_phase_override
         or step_phase_for_index(semantic_brief, step_index, max_steps),
         "stage_learning_goal": (stage_learning_goal or "").strip() or None,
+        "stage_anti_patterns": list(stage_anti_patterns or []),
         "roadmap_stage_match": bool((stage_learning_goal or "").strip()),
+        "stage_match_brief": stage_match_brief,
+        "stage_success_criteria": list(stage_success_criteria or []),
+        "stage_load_profile": list(stage_load_profile or []),
+        "path_context_note": (path_context_note or "").strip() or None,
     }
     pack = apply_progression_context_to_pack(
         cur,
@@ -383,7 +398,10 @@ def _run_path_step_retrieval(
             has_planning_reference=has_plan_ref,
         )
 
-    weights = apply_path_retrieval_weights(semantic_brief)
+    if pack.get("roadmap_stage_match"):
+        weights = apply_stage_match_retrieval_weights(semantic_brief)
+    else:
+        weights = apply_path_retrieval_weights(semantic_brief)
 
     profile_id = tenant.profile_id
     role = tenant.global_role
@@ -490,6 +508,8 @@ def _annotate_roadmap_step(
     step["roadmap_major_step_index"] = stage_spec.major_step_index
     step["roadmap_phase"] = major_step.phase if major_step else None
     step["roadmap_learning_goal"] = learning_goal or None
+    if stage_spec.anti_patterns:
+        step["roadmap_anti_patterns"] = list(stage_spec.anti_patterns)
     step["roadmap_match_source"] = "stage_spec"
     if skill_expectations:
         step["skill_expectations"] = skill_expectations
@@ -569,10 +589,22 @@ def _build_steps_roadmap_first(
         )
         step_kind = resolve_step_exercise_kind_filter(stage_spec, body.exercise_kind_any)
         stage_goal = (stage_spec.learning_goal or "").strip()
-        stage_brief = semantic_brief_for_stage(
-            semantic_brief,
+        stage_anti = list(stage_spec.anti_patterns or [])
+        path_context_note = None
+        if rs_dump:
+            ctx_parts = [
+                str(rs_dump.get("start_situation") or "").strip()[:120],
+                str(rs_dump.get("target_state") or "").strip()[:120],
+                str(rs_dump.get("roadmap_notes") or "").strip()[:120],
+            ]
+            path_context_note = " ".join(p for p in ctx_parts if p)[:240] or None
+        stage_match_brief = build_stage_match_brief(
             learning_goal=stage_goal,
+            anti_patterns=stage_anti,
+            success_criteria=list(stage_spec.success_criteria or []),
+            load_profile=list(stage_spec.load_profile or []),
             phase=major.phase if major else None,
+            path_context_note=path_context_note,
         )
 
         hits, _, _, _ = _run_path_step_retrieval(
@@ -587,21 +619,28 @@ def _build_steps_roadmap_first(
             progression_graph_id=body.progression_graph_id,
             include_llm_intent=body.include_llm_intent and step_index == 0,
             exercise_kind_any=step_kind,
-            semantic_brief=stage_brief,
+            semantic_brief=stage_match_brief,
             path_target_profile=path_target_profile,
             path_intent=path_intent,
             step_query_override=step_query,
             step_phase_override=major.phase if major else None,
             step_target_profile_override=step_target,
             stage_learning_goal=stage_goal or None,
+            stage_anti_patterns=stage_anti or None,
+            stage_match_brief=stage_match_brief,
+            stage_success_criteria=list(stage_spec.success_criteria or []),
+            stage_load_profile=list(stage_spec.load_profile or []),
+            path_context_note=path_context_note,
         )
 
         hit = _pick_best_path_hit(
             hits,
             used,
-            semantic_brief=stage_brief,
+            semantic_brief=stage_match_brief,
             stage_learning_goal=stage_goal or None,
+            stage_anti_patterns=stage_anti or None,
             roadmap_stage_match=True,
+            stage_match_brief=stage_match_brief,
         )
 
         if not hit:
diff --git a/backend/planning_exercise_path_qa.py b/backend/planning_exercise_path_qa.py
index 2fdf291..d8880bc 100644
--- a/backend/planning_exercise_path_qa.py
+++ b/backend/planning_exercise_path_qa.py
@@ -426,12 +426,14 @@ def detect_off_topic_steps(
             brief=step_brief,
             step_phase=phase,
         )
+        stage_anti = list(step.get("roadmap_anti_patterns") or [])
         if stage_goal and not exercise_passes_stage_learning_goal_gate(
             learning_goal=stage_goal,
             title=bundle["title"],
             summary=bundle["summary"],
             goal=bundle["goal"],
             semantic_score=sem,
+            anti_patterns=stage_anti or None,
         ):
             off_topic.append(
                 {
diff --git a/backend/planning_exercise_retrieval.py b/backend/planning_exercise_retrieval.py
index 42af3e8..3051518 100644
--- a/backend/planning_exercise_retrieval.py
+++ b/backend/planning_exercise_retrieval.py
@@ -14,11 +14,14 @@ from planning_exercise_profiles import (
     load_exercise_match_profiles_bulk,
     score_exercise_against_target,
 )
+from exercise_ai import strip_html_to_plain
 from planning_exercise_semantics import (
     PlanningSemanticBrief,
+    build_stage_match_brief,
     exercise_passes_path_semantic_gate,
-    exercise_passes_stage_learning_goal_gate,
+    exercise_passes_stage_fit,
     score_exercise_semantic_relevance,
+    score_exercise_stage_fit,
 )
 
 _MAX_LIBRARY_ROWS = 8000
@@ -149,7 +152,7 @@ def _load_exercise_goals_chunked(cur, exercise_ids: Sequence[int], *, batch: int
         ph = ",".join(["%s"] * len(chunk))
         cur.execute(f"SELECT id, goal FROM exercises WHERE id IN ({ph})", chunk)
         for row in cur.fetchall():
-            out[int(row["id"])] = str(row.get("goal") or "")
+            out[int(row["id"])] = strip_html_to_plain(row.get("goal"), max_len=1200)
     return out
 
 
@@ -203,6 +206,19 @@ def rank_visible_library_hits(
     path_mode = pack.get("context_mode") == "progression_path"
     stage_learning_goal = (pack.get("stage_learning_goal") or "").strip()
     roadmap_stage_match = bool(pack.get("roadmap_stage_match"))
+    stage_match_brief_raw = pack.get("stage_match_brief")
+    stage_match_brief: Optional[PlanningSemanticBrief] = None
+    if isinstance(stage_match_brief_raw, PlanningSemanticBrief):
+        stage_match_brief = stage_match_brief_raw
+    elif roadmap_stage_match and stage_learning_goal:
+        stage_match_brief = build_stage_match_brief(
+            learning_goal=stage_learning_goal,
+            anti_patterns=pack.get("stage_anti_patterns"),
+            success_criteria=pack.get("stage_success_criteria"),
+            load_profile=pack.get("stage_load_profile"),
+            phase=step_phase,
+            path_context_note=pack.get("path_context_note"),
+        )
 
     last_planned_skills: Set[int] = set()
     planned_ids = pack.get("planned_exercise_ids") or []
@@ -229,7 +245,11 @@ def rank_visible_library_hits(
     skills_by_ex = _load_skill_sets_chunked(cur, cand_ids)
     goals_by_ex: Dict[int, str] = {}
     variants_by_ex: Dict[int, List[str]] = {}
-    if semantic_brief and semantic_brief.semantic_strength > 0.05:
+    need_exercise_semantic_text = (
+        (semantic_brief and semantic_brief.semantic_strength > 0.05)
+        or (stage_match_brief and stage_match_brief.semantic_strength > 0.05)
+    )
+    if need_exercise_semantic_text:
         goals_by_ex = _load_exercise_goals_chunked(cur, cand_ids)
         variants_by_ex = _load_variant_names_chunked(cur, cand_ids)
 
@@ -270,52 +290,75 @@ def rank_visible_library_hits(
                 emp, target, intent=intent
             )
 
+        title_s = str(row.get("title") or "")
+        summary_s = str(row.get("summary") or "")
+        goal_s = goals_by_ex.get(eid, "")
+
         semantic_score = 0.0
         semantic_reasons: List[str] = []
         if semantic_brief and semantic_brief.semantic_strength > 0.05:
             semantic_score, semantic_reasons = score_exercise_semantic_relevance(
-                title=str(row.get("title") or ""),
-                summary=str(row.get("summary") or ""),
-                goal=goals_by_ex.get(eid, ""),
+                title=title_s,
+                summary=summary_s,
+                goal=goal_s,
                 variant_names=variants_by_ex.get(eid, []),
                 brief=semantic_brief,
                 step_phase=step_phase,
             )
 
+        stage_semantic_score = 0.0
+        stage_semantic_reasons: List[str] = []
+        if stage_match_brief and stage_match_brief.semantic_strength > 0.05:
+            stage_semantic_score, stage_semantic_reasons = score_exercise_stage_fit(
+                title=title_s,
+                summary=summary_s,
+                goal=goal_s,
+                variant_names=variants_by_ex.get(eid, []),
+                stage_brief=stage_match_brief,
+                step_phase=step_phase,
+            )
+
+        effective_semantic = (
+            stage_semantic_score
+            if roadmap_stage_match and stage_match_brief
+            else semantic_score
+        )
+
         score_penalty = 0.0
         stage_match_reason: Optional[str] = None
         if (
             path_mode
+            and not roadmap_stage_match
             and semantic_brief
             and semantic_brief.semantic_strength >= 0.55
             and not exercise_passes_path_semantic_gate(
                 semantic_score=semantic_score,
-                title=str(row.get("title") or ""),
-                summary=str(row.get("summary") or ""),
-                goal=goals_by_ex.get(eid, ""),
+                title=title_s,
+                summary=summary_s,
+                goal=goal_s,
                 brief=semantic_brief,
                 strict=True,
             )
         ):
             score_penalty = 0.42
         if roadmap_stage_match and stage_learning_goal:
-            title_s = str(row.get("title") or "")
-            summary_s = str(row.get("summary") or "")
-            goal_s = goals_by_ex.get(eid, "")
-            if exercise_passes_stage_learning_goal_gate(
+            if exercise_passes_stage_fit(
                 learning_goal=stage_learning_goal,
                 title=title_s,
                 summary=summary_s,
                 goal=goal_s,
-                semantic_score=semantic_score,
+                stage_brief=stage_match_brief,
+                stage_semantic_score=stage_semantic_score,
+                anti_patterns=pack.get("stage_anti_patterns"),
+                step_phase=step_phase,
             ):
-                score_penalty = max(0.0, score_penalty - 0.08)
+                score_penalty = max(0.0, score_penalty - 0.10)
                 stage_match_reason = "Passt zum Stufen-Lernziel"
             else:
-                score_penalty += 0.35
+                score_penalty += 0.48
 
         score = (
-            weights.get("semantic", 0.0) * semantic_score
+            weights.get("semantic", 0.0) * effective_semantic
             + weights["fulltext"] * ft_norm
             + weights["progression"] * prog_hit
             + weights["skill"] * skill_sim
@@ -329,7 +372,11 @@ def rank_visible_library_hits(
         reasons: List[str] = []
         if stage_match_reason:
             reasons.append(stage_match_reason)
-        if semantic_score >= 0.35 and semantic_reasons:
+        if roadmap_stage_match and stage_semantic_score >= 0.30 and stage_semantic_reasons:
+            for sr in stage_semantic_reasons:
+                if sr not in reasons:
+                    reasons.append(sr)
+        elif semantic_score >= 0.35 and semantic_reasons:
             for sr in semantic_reasons:
                 if sr not in reasons:
                     reasons.append(sr)
@@ -365,6 +412,8 @@ def rank_visible_library_hits(
                 "score": round(max(0.0, min(1.0, score)), 4),
                 "reasons": reasons,
                 "semantic_score": round(semantic_score, 4),
+                "stage_semantic_score": round(stage_semantic_score, 4),
+                "goal": goal_s,
             }
         )
         succ_variants = pack.get("progression_successor_variants") or {}
diff --git a/backend/planning_exercise_semantics.py b/backend/planning_exercise_semantics.py
index e91a6a0..45a1adc 100644
--- a/backend/planning_exercise_semantics.py
+++ b/backend/planning_exercise_semantics.py
@@ -9,6 +9,7 @@ from __future__ import annotations
 import json
 import logging
 import re
+from dataclasses import dataclass, field
 from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple
 
 from pydantic import BaseModel, Field, field_validator
@@ -462,7 +463,7 @@ def score_exercise_semantic_relevance(
 
     core_hits = sum(1 for ph in core if _phrase_in_blob(ph, blob))
     must_hits = sum(1 for ph in must if _phrase_in_blob(ph, blob))
-    exclude_hits = sum(1 for ph in exclude if _phrase_in_blob(ph, blob))
+    exclude_hits = sum(1 for ph in exclude if _phrase_excluded_in_blob(ph, blob))
 
     score = 0.0
     if core:
@@ -623,9 +624,82 @@ _STAGE_GOAL_STOPWORDS = _QUERY_STOPWORDS | frozenset(
 )
 
 
-def _significant_stage_tokens(learning_goal: str) -> List[str]:
-    """Wörter aus Stufen-Lernziel für Text-Match (ohne Füllwörter)."""
-    raw = re.findall(r"[a-zäöüß]{4,}", _normalize_phrase(learning_goal), flags=re.IGNORECASE)
+_STAGE_NEGATION_PATTERNS = (
+    r"\bohne\s+([^,.;]+)",
+    r"\bkein(?:e|en|er|em)?\s+([^,.;]+)",
+    r"\bnicht\s+([^,.;]+)",
+)
+
+# Aus „ohne Tritttechnik“ etc. — erweiterte Treffer im Übungstext
+_STAGE_EXCLUDE_ALIASES: Dict[str, Tuple[str, ...]] = {
+    "tritttechnik": (
+        "tritttechnik",
+        "trittpraezision",
+        "trittpräzision",
+        "tritt praesision",
+        "tritt-präzision",
+        "kicktechnik",
+        "tritt ausführung",
+        "tritt ausfuehrung",
+    ),
+    "kumite": ("kumite", "partnerkampf", "freikampf", "jiyu kumite"),
+    "kraftuebung": ("kraftuebung", "kraftübung", "krafttraining", "kraftübungen"),
+    "anwendung": ("kumite anwendung", "kampfanwendung"),
+}
+
+_STAGE_FOCUS_TOKENS = frozenset(
+    {
+        "koordination",
+        "absprung",
+        "beinhebung",
+        "landung",
+        "sprung",
+        "sprungphase",
+        "balance",
+        "gleichgewicht",
+        "timing",
+        "vorbereitung",
+        "athletik",
+        "mobilitaet",
+        "mobilität",
+        "stabilisation",
+        "stabilisierung",
+    }
+)
+
+
+@dataclass
+class StageGoalConstraints:
+    positive_tokens: List[str] = field(default_factory=list)
+    exclude_phrases: List[str] = field(default_factory=list)
+    has_negation: bool = False
+    strict_positive: bool = False
+
+
+def _expand_stage_exclude_phrase(phrase: str) -> List[str]:
+    norm = _normalize_phrase(phrase)
+    if not norm:
+        return []
+    out: List[str] = [norm]
+    compact = norm.replace(" ", "")
+    if compact and compact not in out:
+        out.append(compact)
+    for key, aliases in _STAGE_EXCLUDE_ALIASES.items():
+        if key in norm or norm in key:
+            for alias in aliases:
+                a = _normalize_phrase(alias)
+                if a and a not in out:
+                    out.append(a)
+    return out[:12]
+
+
+def _significant_stage_tokens(learning_goal: str, *, strip_negated: bool = True) -> List[str]:
+    """Wörter aus Stufen-Lernziel für Text-Match (ohne Füllwörter, ohne Negationssegmente)."""
+    text = _normalize_phrase(learning_goal)
+    if strip_negated:
+        for pat in _STAGE_NEGATION_PATTERNS:
+            text = re.sub(pat, " ", text)
+    raw = re.findall(r"[a-zäöüß]{4,}", text, flags=re.IGNORECASE)
     out: List[str] = []
     for w in raw:
         low = w.lower().replace("ä", "ae").replace("ö", "oe").replace("ü", "ue")
@@ -636,19 +710,245 @@ def _significant_stage_tokens(learning_goal: str) -> List[str]:
     return out[:10]
 
 
+def parse_stage_goal_constraints(
+    learning_goal: str,
+    anti_patterns: Optional[Sequence[str]] = None,
+) -> StageGoalConstraints:
+    """Positiv/Negativ aus Stufen-Lernziel + anti_patterns (Roadmap-Stufe)."""
+    lg = (learning_goal or "").strip()
+    if len(lg) < 3:
+        return StageGoalConstraints()
+
+    norm = _normalize_phrase(lg)
+    exclude: List[str] = []
+    has_negation = False
+    for pat in _STAGE_NEGATION_PATTERNS:
+        for m in re.finditer(pat, norm):
+            has_negation = True
+            chunk = (m.group(1) or "").strip()
+            if chunk:
+                exclude.extend(_expand_stage_exclude_phrase(chunk))
+
+    for raw in anti_patterns or []:
+        s = _normalize_phrase(str(raw or ""))
+        if s:
+            exclude.extend(_expand_stage_exclude_phrase(s))
+
+    positive = _significant_stage_tokens(lg, strip_negated=True)
+    focus_hits = [t for t in positive if t in _STAGE_FOCUS_TOKENS]
+    strict_positive = bool(focus_hits) or has_negation
+
+    dedup_exclude: List[str] = []
+    for item in exclude:
+        if item and item not in dedup_exclude:
+            dedup_exclude.append(item)
+
+    return StageGoalConstraints(
+        positive_tokens=positive,
+        exclude_phrases=dedup_exclude[:16],
+        has_negation=has_negation,
+        strict_positive=strict_positive,
+    )
+
+
+def _phrase_excluded_in_blob(phrase: str, blob: str) -> bool:
+    """Treffer nur wenn das Ausschluss-Thema nicht selbst negiert beschrieben ist."""
+    if not phrase or not blob:
+        return False
+    if not _phrase_in_blob(phrase, blob):
+        return False
+    norm = _normalize_phrase(phrase)
+    for pat in _STAGE_NEGATION_PATTERNS:
+        for m in re.finditer(pat, blob):
+            chunk = _normalize_phrase(m.group(1) or "")
+            if not chunk:
+                continue
+            if norm in chunk or chunk in norm or _phrase_in_blob(norm, chunk):
+                return False
+    return True
+
+
+def _blob_matches_stage_excludes(blob: str, exclude_phrases: Sequence[str]) -> bool:
+    for phrase in exclude_phrases:
+        if _phrase_excluded_in_blob(phrase, blob):
+            return True
+    return False
+
+
+_MIN_STAGE_FIT_SEMANTIC = 0.30
+_MIN_STAGE_FIT_RELAXED = 0.20
+
+
+def build_stage_match_brief(
+    *,
+    learning_goal: str,
+    anti_patterns: Optional[Sequence[str]] = None,
+    success_criteria: Optional[Sequence[str]] = None,
+    load_profile: Optional[Sequence[str]] = None,
+    phase: Optional[str] = None,
+    path_context_note: Optional[str] = None,
+) -> PlanningSemanticBrief:
+    """
+    Stufen-zentrierter Semantik-Brief — unabhängig vom Gesamt-Pfad-Thema.
+
+    Primär für Roadmap-Match: Bewertung gegen Titel + Kurzbeschreibung + Übungsziel.
+    """
+    lg = (learning_goal or "").strip()
+    if len(lg) < 3:
+        return PlanningSemanticBrief(semantic_strength=0.0)
+
+    constraints = parse_stage_goal_constraints(lg, anti_patterns)
+    must: List[str] = []
+    norm_lg = _normalize_phrase(lg)
+    for token in constraints.positive_tokens:
+        if token not in must:
+            must.append(token)
+    if norm_lg and norm_lg not in must:
+        must.append(norm_lg[:120])
+    for raw in success_criteria or []:
+        s = _normalize_phrase(str(raw or ""))
+        if s and s not in must:
+            must.append(s[:100])
+    for raw in load_profile or []:
+        s = _normalize_phrase(str(raw or ""))
+        if s and s not in must:
+            must.append(s[:60])
+
+    retrieval_parts = [norm_lg]
+    if path_context_note:
+        note = _normalize_phrase(path_context_note)[:200]
+        if note:
+            retrieval_parts.append(note)
+
+    arc: List[str] = []
+    ph = (phase or "").strip().lower()
+    if ph:
+        arc.append(ph)
+
+    return PlanningSemanticBrief(
+        primary_topic="",
+        topic_type="focus",
+        must_phrases=must[:12],
+        exclude_phrases=list(constraints.exclude_phrases)[:12],
+        development_arc=arc[:4],
+        retrieval_query=" ".join(p for p in retrieval_parts if p)[:500],
+        semantic_strength=0.78,
+        rationale="stage_match_brief",
+    )
+
+
+def score_exercise_stage_fit(
+    *,
+    title: str,
+    summary: str,
+    goal: str,
+    stage_brief: PlanningSemanticBrief,
+    variant_names: Optional[Sequence[str]] = None,
+    step_phase: Optional[str] = None,
+) -> Tuple[float, List[str]]:
+    """Semantik-Score Übung ↔ Stufen-Lernziel (Titel + Summary + Goal)."""
+    score, reasons = score_exercise_semantic_relevance(
+        title=title,
+        summary=summary,
+        goal=goal,
+        variant_names=variant_names or [],
+        brief=stage_brief,
+        step_phase=step_phase,
+    )
+    blob = _blob_from_fields(title, summary, goal, variant_names or [])
+    focus_tokens = [
+        t
+        for t in (stage_brief.must_phrases or [])
+        if t and " " not in t and len(t) >= 4
+    ][:6]
+    if focus_tokens:
+        hits = sum(1 for t in focus_tokens if _phrase_in_blob(t, blob))
+        ratio = hits / len(focus_tokens)
+        bonus = 0.28 * ratio
+        if bonus > 0:
+            score = min(1.0, score + bonus)
+            if hits >= max(1, len(focus_tokens) // 2):
+                reasons = ["Stufen-Schwerpunkte im Übungstext", *reasons]
+    return max(0.0, min(1.0, round(score, 4))), reasons[:4]
+
+
+def exercise_passes_stage_fit(
+    *,
+    learning_goal: str,
+    title: str,
+    summary: str = "",
+    goal: str = "",
+    stage_brief: Optional[PlanningSemanticBrief] = None,
+    stage_semantic_score: Optional[float] = None,
+    anti_patterns: Optional[Sequence[str]] = None,
+    step_phase: Optional[str] = None,
+    min_stage_semantic: float = _MIN_STAGE_FIT_SEMANTIC,
+    relaxed: bool = False,
+) -> bool:
+    """Allgemeines Stufen-Fit-Gate: voller Übungstext vs. Stufen-Brief."""
+    lg = (learning_goal or "").strip()
+    if len(lg) < 3:
+        return True
+
+    blob = _blob_from_fields(title, summary, goal, [])
+    constraints = parse_stage_goal_constraints(lg, anti_patterns)
+    if constraints.exclude_phrases and _blob_matches_stage_excludes(blob, constraints.exclude_phrases):
+        return False
+
+    brief = stage_brief or build_stage_match_brief(
+        learning_goal=lg,
+        anti_patterns=anti_patterns,
+    )
+    stage_sem = stage_semantic_score
+    if stage_sem is None:
+        stage_sem, _ = score_exercise_stage_fit(
+            title=title,
+            summary=summary,
+            goal=goal,
+            stage_brief=brief,
+            step_phase=step_phase,
+        )
+
+    threshold = _MIN_STAGE_FIT_RELAXED if relaxed else min_stage_semantic
+    return float(stage_sem or 0.0) >= threshold
+
+
+def apply_stage_match_retrieval_weights(brief: PlanningSemanticBrief) -> Dict[str, float]:
+    """Roadmap-Stufe: Stufen-Semantik (Ziel/Summary/Goal) dominiert."""
+    return {
+        "semantic": 0.58,
+        "fulltext": 0.14,
+        "profile": 0.18,
+        "progression": 0.04,
+        "skill": 0.04,
+        "plan": 0.02,
+        "repeat_unit": -0.40,
+        "repeat_group": -0.15,
+    }
+
+
 def semantic_brief_for_stage(
     brief: PlanningSemanticBrief,
     *,
     learning_goal: str,
     phase: Optional[str] = None,
+    anti_patterns: Optional[Sequence[str]] = None,
 ) -> PlanningSemanticBrief:
-    """Brief um Stufen-Lernziel erweitern — für Roadmap-Match pro Major Step."""
+    """Legacy: globalen Brief anreichern — bevorzugt build_stage_match_brief für Roadmap-Match."""
     lg = _normalize_phrase(learning_goal)
     if not lg:
         return brief
+    constraints = parse_stage_goal_constraints(learning_goal, anti_patterns)
     must = list(brief.must_phrases or [])
+    for token in constraints.positive_tokens[:4]:
+        if token not in must:
+            must.append(token)
     if lg not in must:
         must.insert(0, lg[:120])
+    exclude = list(brief.exclude_phrases or [])
+    for item in constraints.exclude_phrases:
+        if item not in exclude:
+            exclude.append(item)
     arc = list(brief.development_arc or [])
     ph = (phase or "").strip().lower()
     if ph and ph not in arc:
@@ -657,6 +957,7 @@ def semantic_brief_for_stage(
     return brief.model_copy(
         update={
             "must_phrases": must[:12],
+            "exclude_phrases": exclude[:12],
             "development_arc": arc[:8],
             "semantic_strength": min(1.0, strength),
         }
@@ -672,33 +973,24 @@ def exercise_passes_stage_learning_goal_gate(
     semantic_score: float = 0.0,
     min_semantic: float = 0.20,
     relaxed: bool = False,
+    anti_patterns: Optional[Sequence[str]] = None,
+    stage_brief: Optional[PlanningSemanticBrief] = None,
+    stage_semantic_score: Optional[float] = None,
+    step_phase: Optional[str] = None,
 ) -> bool:
-    """Roadmap-Stufe: Übung muss zum Stufen-Lernziel passen, nicht nur zum Gesamtthema."""
-    lg = (learning_goal or "").strip()
-    if len(lg) < 3:
-        return True
-
-    blob = _blob_from_fields(title, summary, goal, [])
-    norm_lg = _normalize_phrase(lg)
-    if _phrase_in_blob(norm_lg, blob):
-        return True
-
-    tokens = _significant_stage_tokens(lg)
-    if not tokens:
-        threshold = 0.12 if relaxed else min_semantic
-        return semantic_score >= threshold
-
-    hits = sum(1 for t in tokens if _phrase_in_blob(t, blob))
-    if len(tokens) <= 2:
-        required = 1
-    else:
-        required = max(2, (len(tokens) + 1) // 2)
-
-    if hits >= required:
-        return True
-
-    threshold = 0.14 if relaxed else min_semantic
-    return semantic_score >= threshold
+    """Roadmap-Stufe: delegiert an exercise_passes_stage_fit (Titel + Summary + Goal)."""
+    del semantic_score, min_semantic
+    return exercise_passes_stage_fit(
+        learning_goal=learning_goal,
+        title=title,
+        summary=summary,
+        goal=goal,
+        stage_brief=stage_brief,
+        stage_semantic_score=stage_semantic_score,
+        anti_patterns=anti_patterns,
+        step_phase=step_phase,
+        relaxed=relaxed,
+    )
 
 
 def exercise_passes_path_semantic_gate(
@@ -739,7 +1031,9 @@ def pick_best_path_hit(
     *,
     semantic_brief: Optional[PlanningSemanticBrief] = None,
     stage_learning_goal: Optional[str] = None,
+    stage_anti_patterns: Optional[Sequence[str]] = None,
     roadmap_stage_match: bool = False,
+    stage_match_brief: Optional[PlanningSemanticBrief] = None,
 ) -> Optional[Dict[str, Any]]:
     """Gestufte Auswahl: strikt → relaxed → optional Notfall-Fallback."""
     if not hits:
@@ -747,6 +1041,13 @@ def pick_best_path_hit(
 
     stage_goal = (stage_learning_goal or "").strip()
 
+    stage_brief: Optional[PlanningSemanticBrief] = stage_match_brief
+    if roadmap_stage_match and stage_goal and stage_brief is None:
+        stage_brief = build_stage_match_brief(
+            learning_goal=stage_goal,
+            anti_patterns=stage_anti_patterns,
+        )
+
     def _scan(*, strict: bool) -> Optional[Dict[str, Any]]:
         best: Optional[Dict[str, Any]] = None
         best_key: Tuple[float, float] = (-1.0, -1.0)
@@ -754,28 +1055,38 @@ def pick_best_path_hit(
             eid = int(hit["id"])
             if eid in used_exercise_ids:
                 continue
-            sem = float(hit.get("semantic_score") or 0.0)
             title = str(hit.get("title") or "")
             summary = str(hit.get("summary") or "")
-            if semantic_brief and not exercise_passes_path_semantic_gate(
-                semantic_score=sem,
-                title=title,
-                summary=summary,
-                goal="",
-                brief=semantic_brief,
-                strict=strict,
-            ):
-                continue
-            if stage_goal and not exercise_passes_stage_learning_goal_gate(
-                learning_goal=stage_goal,
-                title=title,
-                summary=summary,
-                semantic_score=sem,
-                relaxed=not strict,
-            ):
-                continue
+            goal_text = str(hit.get("goal") or hit.get("exercise_goal") or "")
+            sem = float(hit.get("semantic_score") or 0.0)
+            stage_sem = float(hit.get("stage_semantic_score") or sem)
+
+            if roadmap_stage_match and stage_goal:
+                if not exercise_passes_stage_fit(
+                    learning_goal=stage_goal,
+                    title=title,
+                    summary=summary,
+                    goal=goal_text,
+                    stage_brief=stage_brief,
+                    stage_semantic_score=stage_sem,
+                    anti_patterns=stage_anti_patterns,
+                    relaxed=not strict,
+                ):
+                    continue
+            else:
+                if semantic_brief and not exercise_passes_path_semantic_gate(
+                    semantic_score=sem,
+                    title=title,
+                    summary=summary,
+                    goal=goal_text,
+                    brief=semantic_brief,
+                    strict=strict,
+                ):
+                    continue
+
             score = float(hit.get("score") or 0.0)
-            key = (sem, score)
+            rank_sem = stage_sem if roadmap_stage_match and stage_goal else sem
+            key = (rank_sem, score)
             if key > best_key:
                 best_key = key
                 best = hit
@@ -820,9 +1131,15 @@ __all__ = [
     "build_semantic_brief",
     "enrich_target_with_semantic_expectations",
     "exercise_passes_path_semantic_gate",
+    "StageGoalConstraints",
+    "apply_stage_match_retrieval_weights",
+    "build_stage_match_brief",
+    "exercise_passes_stage_fit",
     "exercise_passes_stage_learning_goal_gate",
     "merge_semantic_brief_llm",
+    "parse_stage_goal_constraints",
     "pick_best_path_hit",
+    "score_exercise_stage_fit",
     "semantic_brief_for_stage",
     "resolve_semantic_skill_weights",
     "score_exercise_semantic_relevance",
diff --git a/backend/tests/test_planning_roadmap_stage_match.py b/backend/tests/test_planning_roadmap_stage_match.py
index 6fc529a..ce8a572 100644
--- a/backend/tests/test_planning_roadmap_stage_match.py
+++ b/backend/tests/test_planning_roadmap_stage_match.py
@@ -1,7 +1,9 @@
 """Tests Roadmap-Stufen-Match — Gate gegen themenfremde Übungen."""
 from planning_exercise_semantics import (
+    build_stage_match_brief,
     exercise_passes_stage_learning_goal_gate,
     pick_best_path_hit,
+    score_exercise_stage_fit,
     semantic_brief_for_stage,
     build_semantic_brief,
 )
@@ -35,10 +37,37 @@ def test_semantic_brief_for_stage_adds_learning_goal():
     assert "hüftmobilität und kammerhaltung" in stage.must_phrases[0]
 
 
+def test_build_stage_match_brief_uses_stage_tokens_not_global_topic():
+    brief = build_stage_match_brief(
+        learning_goal="Koordination von Absprung und Beinhebung ohne Tritttechnik",
+        phase="vertiefung",
+    )
+    must_blob = " ".join(brief.must_phrases or []).lower()
+    assert "mawashi" not in must_blob
+    assert "absprung" in must_blob
+    assert not (brief.primary_topic or "").strip()
+
+
+def test_stage_fit_prefers_goal_over_misleading_title():
+    stage_goal = "Koordination von Absprung und Beinhebung ohne Tritttechnik"
+    stage_brief = build_stage_match_brief(learning_goal=stage_goal)
+    kick_score, _ = score_exercise_stage_fit(
+        title="Mawashi Geri Trittpräzision",
+        summary="Kicktechnik",
+        goal="Präzision im Tritt und Hüftarbeit",
+        stage_brief=stage_brief,
+    )
+    coord_score, _ = score_exercise_stage_fit(
+        title="Allgemeines Sprungtraining",
+        summary="Athletik",
+        goal="Absprung, Beinhebung und Landung koordinieren — ohne Trittausführung",
+        stage_brief=stage_brief,
+    )
+    assert coord_score > kick_score
+
+
 def test_pick_best_path_hit_roadmap_stage_no_weak_fallback():
-    brief = build_semantic_brief("Mae Geri Perfektion")
-    stage_brief = semantic_brief_for_stage(
-        brief,
+    stage_brief = build_stage_match_brief(
         learning_goal="Hüftmobilität für Mae Geri",
         phase="grundlage",
     )
@@ -69,9 +98,7 @@ def test_pick_best_path_hit_roadmap_stage_no_weak_fallback():
 
 
 def test_pick_best_path_hit_roadmap_stage_picks_relevant():
-    brief = build_semantic_brief("Mae Geri Perfektion")
-    stage_brief = semantic_brief_for_stage(
-        brief,
+    stage_brief = build_stage_match_brief(
         learning_goal="Hüftmobilität für Mae Geri",
         phase="grundlage",
     )
@@ -94,3 +121,63 @@ def test_pick_best_path_hit_roadmap_stage_picks_relevant():
     )
     assert chosen is not None
     assert int(chosen["id"]) == 2
+
+
+def test_stage_gate_rejects_tritt_when_goal_says_ohne_tritttechnik():
+    """Regression: gesprungener Mawashi — Slot Koordination ohne Tritttechnik."""
+    goal = "Koordination von Absprung und Beinhebung ohne Tritttechnik"
+    assert not exercise_passes_stage_learning_goal_gate(
+        learning_goal=goal,
+        title="Verbesserung der Trittpräzision des Mawashi Geri und der Hüftbewegung",
+        summary="Präzision und Hüftarbeit im Stand",
+        semantic_score=0.72,
+    )
+
+
+def test_stage_gate_accepts_absprung_drill_not_kick_focus():
+    goal = "Koordination von Absprung und Beinhebung ohne Tritttechnik"
+    assert exercise_passes_stage_learning_goal_gate(
+        learning_goal=goal,
+        title="Sprungkoordination — Absprung und Beinhebung",
+        summary="Ohne Trittausführung, Fokus Gleichgewicht und Timing",
+        semantic_score=0.35,
+    )
+
+
+def test_pick_best_rejects_mawashi_tritt_precision_for_coordination_slot():
+    stage_goal = "Koordination von Absprung und Beinhebung ohne Tritttechnik"
+    stage_brief = build_stage_match_brief(learning_goal=stage_goal, phase="vertiefung")
+    hits = [
+        {
+            "id": 99,
+            "title": "Verbesserung der Trittpräzision des Mawashi Geri und der Hüftbewegung",
+            "summary": "Tritttechnik und Hüfte im Stand",
+            "score": 0.91,
+            "semantic_score": 0.68,
+        },
+        {
+            "id": 100,
+            "title": "Absprung und Beinhebung — Koordination ohne Kick",
+            "summary": "Sprungvorbereitung, kein Tritt",
+            "score": 0.62,
+            "semantic_score": 0.41,
+        },
+    ]
+    chosen = pick_best_path_hit(
+        hits,
+        set(),
+        semantic_brief=stage_brief,
+        stage_learning_goal=stage_goal,
+        roadmap_stage_match=True,
+    )
+    assert chosen is not None
+    assert int(chosen["id"]) == 100
+
+
+def test_parse_stage_goal_constraints_extracts_ohne_tritttechnik():
+    from planning_exercise_semantics import parse_stage_goal_constraints
+
+    c = parse_stage_goal_constraints("Koordination von Absprung und Beinhebung ohne Tritttechnik")
+    assert c.has_negation
+    assert "absprung" in c.positive_tokens
+    assert any("tritt" in ex for ex in c.exclude_phrases)
diff --git a/backend/version.py b/backend/version.py
index 00dacd4..9469e76 100644
--- a/backend/version.py
+++ b/backend/version.py
@@ -1,6 +1,6 @@
 # Shinkan Jinkendo Version Information
 
-APP_VERSION = "0.8.218"
+APP_VERSION = "0.8.220"
 BUILD_DATE = "2026-06-07"
 DB_SCHEMA_VERSION = "20260607088"
 
@@ -53,6 +53,22 @@ MODULE_VERSIONS = {
 }
 
 CHANGELOG = [
+    {
+        "version": "0.8.220",
+        "date": "2026-06-07",
+        "changes": [
+            "Roadmap-Stufen-Match: build_stage_match_brief + stage_semantic_score über Titel, Summary und Goal.",
+            "Retriever lädt Übungsziele immer bei Stufen-Match; Ranking nach Stufen-Fit statt Gesamtthema.",
+        ],
+    },
+    {
+        "version": "0.8.219",
+        "date": "2026-06-07",
+        "changes": [
+            "Roadmap-Stufen-Gate: Negationen (ohne Tritttechnik) + Pflicht-Treffer Absprung/Beinhebung.",
+            "anti_patterns in Stufen-Match; Gesamt-Thema allein reicht bei strict_positive nicht mehr.",
+        ],
+    },
     {
         "version": "0.8.218",
         "date": "2026-06-07",

From 3c12363b8f7ea40984ed731678a6032505ea3fc0 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Thu, 11 Jun 2026 08:43:59 +0200
Subject: [PATCH 17/33] Enhance Path Exclusion Logic and Semantic Brief
 Enrichment

- Introduced `resolve_path_anti_patterns` to improve handling of path exclusions based on explicit negations and semantic briefs.
- Updated `enrich_brief_with_path_constraints` to incorporate path-specific exclusions into semantic briefs, enhancing exercise relevance.
- Modified roadmap step annotation to allow for anti-pattern overrides, improving flexibility in exercise selection.
- Enhanced tests to validate new path exclusion features and ensure correct functionality against learning goals.
- Incremented application version to reflect these updates.
---
 backend/planning_exercise_path_builder.py     | 48 +++++++++--
 backend/planning_exercise_path_qa.py          | 30 ++++++-
 backend/planning_exercise_semantics.py        | 72 +++++++++++++++-
 backend/planning_progression_roadmap.py       | 38 +++++++--
 .../test_planning_roadmap_stage_match.py      | 83 ++++++++++++++++++-
 backend/version.py                            | 17 +++-
 6 files changed, 270 insertions(+), 18 deletions(-)

diff --git a/backend/planning_exercise_path_builder.py b/backend/planning_exercise_path_builder.py
index 473c228..44a1228 100644
--- a/backend/planning_exercise_path_builder.py
+++ b/backend/planning_exercise_path_builder.py
@@ -36,7 +36,9 @@ from planning_exercise_semantics import (
     brief_to_summary_dict,
     build_semantic_brief,
     build_stage_match_brief,
+    enrich_brief_with_path_constraints,
     enrich_target_with_semantic_expectations,
+    resolve_path_anti_patterns,
     exercise_passes_path_semantic_gate,
     pick_best_path_hit,
     resolve_semantic_skill_weights,
@@ -487,6 +489,7 @@ def _annotate_roadmap_step(
     stage_spec: StageSpecArtifact,
     major_step: Optional[MajorStep],
     skill_expectations: Optional[Dict[str, Any]] = None,
+    anti_patterns_override: Optional[List[str]] = None,
 ) -> Dict[str, Any]:
     reasons = list(step.get("reasons") or [])
     learning_goal = (stage_spec.learning_goal or "").strip()
@@ -508,8 +511,9 @@ def _annotate_roadmap_step(
     step["roadmap_major_step_index"] = stage_spec.major_step_index
     step["roadmap_phase"] = major_step.phase if major_step else None
     step["roadmap_learning_goal"] = learning_goal or None
-    if stage_spec.anti_patterns:
-        step["roadmap_anti_patterns"] = list(stage_spec.anti_patterns)
+    anti = list(anti_patterns_override or stage_spec.anti_patterns or [])
+    if anti:
+        step["roadmap_anti_patterns"] = anti
     step["roadmap_match_source"] = "stage_spec"
     if skill_expectations:
         step["skill_expectations"] = skill_expectations
@@ -589,7 +593,6 @@ def _build_steps_roadmap_first(
         )
         step_kind = resolve_step_exercise_kind_filter(stage_spec, body.exercise_kind_any)
         stage_goal = (stage_spec.learning_goal or "").strip()
-        stage_anti = list(stage_spec.anti_patterns or [])
         path_context_note = None
         if rs_dump:
             ctx_parts = [
@@ -598,6 +601,12 @@ def _build_steps_roadmap_first(
                 str(rs_dump.get("roadmap_notes") or "").strip()[:120],
             ]
             path_context_note = " ".join(p for p in ctx_parts if p)[:240] or None
+        path_anti = resolve_path_anti_patterns(
+            goal_query,
+            semantic_brief=semantic_brief,
+            extra_context=path_context_note,
+        )
+        stage_anti = list(dict.fromkeys([*(stage_spec.anti_patterns or []), *path_anti]))
         stage_match_brief = build_stage_match_brief(
             learning_goal=stage_goal,
             anti_patterns=stage_anti,
@@ -605,6 +614,7 @@ def _build_steps_roadmap_first(
             load_profile=list(stage_spec.load_profile or []),
             phase=major.phase if major else None,
             path_context_note=path_context_note,
+            path_anti_patterns=path_anti,
         )
 
         hits, _, _, _ = _run_path_step_retrieval(
@@ -652,6 +662,7 @@ def _build_steps_roadmap_first(
             stage_spec=stage_spec,
             major_step=major,
             skill_expectations=skill_exp_api,
+            anti_patterns_override=stage_anti,
         )
         steps.append(step)
         eid = int(step["exercise_id"])
@@ -795,7 +806,13 @@ def _run_evaluate_only_path_qa(
                 bridge_inserts=bridge_inserts,
             )
 
-        off_topic_steps = detect_off_topic_steps(cur, steps, brief=semantic_brief)
+        off_topic_steps = detect_off_topic_steps(
+            cur,
+            steps,
+            brief=semantic_brief,
+            goal_query=goal_query,
+        )
+        steps, stripped_off_topic = strip_off_topic_steps_from_path(steps, off_topic_steps)
         llm_gap_specs = parse_llm_suggested_new_exercises(
             llm_qa,
             brief=semantic_brief,
@@ -807,7 +824,7 @@ def _run_evaluate_only_path_qa(
             gap_specs = collect_gap_fill_specs(
                 steps=steps,
                 unfilled_gaps=fresh_large_gaps or unfilled_gaps,
-                off_topic_steps=off_topic_steps,
+                off_topic_steps=off_topic_steps if not stripped_off_topic else [],
                 llm_specs=llm_gap_specs,
                 brief=semantic_brief,
                 goal_query=goal_query,
@@ -902,6 +919,20 @@ def suggest_progression_path(
         semantic_brief, semantic_llm_applied = try_enrich_semantic_brief_with_llm(
             cur, goal_query, semantic_brief
         )
+    extra_path_ctx = " ".join(
+        p
+        for p in (
+            (body.start_situation or "").strip(),
+            (body.target_state or "").strip(),
+            (body.roadmap_notes or "").strip(),
+        )
+        if p
+    )
+    semantic_brief = enrich_brief_with_path_constraints(
+        semantic_brief,
+        goal_query,
+        extra_context=extra_path_ctx or None,
+    )
 
     roadmap_first = bool(body.roadmap_first)
     roadmap_only = bool(body.roadmap_only)
@@ -1222,7 +1253,12 @@ def suggest_progression_path(
             if llm_qa.get("overall_ok") or (q_val is not None and q_val >= 0.45):
                 steps, reorder_applied, reorder_notes = apply_llm_path_reorder(steps, llm_qa)
 
-        off_topic_steps = detect_off_topic_steps(cur, steps, brief=semantic_brief)
+        off_topic_steps = detect_off_topic_steps(
+            cur,
+            steps,
+            brief=semantic_brief,
+            goal_query=goal_query,
+        )
         steps, stripped_off_topic = strip_off_topic_steps_from_path(steps, off_topic_steps)
         if stripped_off_topic:
             off_topic_steps = []
diff --git a/backend/planning_exercise_path_qa.py b/backend/planning_exercise_path_qa.py
index d8880bc..de7a896 100644
--- a/backend/planning_exercise_path_qa.py
+++ b/backend/planning_exercise_path_qa.py
@@ -18,9 +18,12 @@ from openrouter_chat import (
 
 from planning_exercise_semantics import (
     PlanningSemanticBrief,
+    _blob_from_fields,
+    _blob_matches_stage_excludes,
     brief_to_summary_dict,
     exercise_passes_path_semantic_gate,
     exercise_passes_stage_learning_goal_gate,
+    resolve_path_anti_patterns,
     score_exercise_semantic_relevance,
     semantic_brief_for_stage,
     step_phase_for_index,
@@ -398,17 +401,39 @@ def detect_off_topic_steps(
     steps: Sequence[Mapping[str, Any]],
     *,
     brief: PlanningSemanticBrief,
+    goal_query: Optional[str] = None,
 ) -> List[Dict[str, Any]]:
     """Schritte ohne Bezug zum Pfad-Thema (z. B. reine Kraftübungen bei Mae Geri)."""
     if brief.semantic_strength < 0.55 or len(steps) < 2:
         return []
 
+    path_anti = resolve_path_anti_patterns(goal_query or "", semantic_brief=brief)
     off_topic: List[Dict[str, Any]] = []
     total = len(steps)
     for idx, step in enumerate(steps):
         if step.get("is_ai_proposal") or step.get("exercise_id") is None:
             continue
         bundle = _load_exercise_text_bundle(cur, int(step["exercise_id"]))
+        blob = _blob_from_fields(
+            bundle["title"],
+            bundle["summary"],
+            bundle["goal"],
+            bundle["variant_names"],
+        )
+        step_anti = list(step.get("roadmap_anti_patterns") or []) + path_anti
+        if step_anti and _blob_matches_stage_excludes(blob, step_anti):
+            off_topic.append(
+                {
+                    "step_index": idx,
+                    "exercise_id": int(step["exercise_id"]),
+                    "title": step.get("title") or bundle["title"],
+                    "semantic_score": 0.0,
+                    "expected_phase": (step.get("roadmap_phase") or "").strip().lower() or None,
+                    "issue": "path_exclude",
+                    "reasons": ["Widerspricht Pfad-Ausschlüssen (z. B. Kumite)"],
+                }
+            )
+            continue
         stage_goal = (step.get("roadmap_learning_goal") or "").strip()
         phase = (step.get("roadmap_phase") or "").strip().lower() or step_phase_for_index(
             brief, idx, total
@@ -529,9 +554,10 @@ def strip_off_topic_steps_from_path(
         return steps, []
 
     by_index = {int(o["step_index"]): dict(o) for o in off_topic_steps if o.get("step_index") is not None}
-    indices = sorted(by_index.keys(), reverse=True)
-    if len(steps) - len(indices) < min_remaining:
+    max_remove = max(0, len(steps) - min_remaining)
+    if max_remove <= 0:
         return steps, []
+    indices = sorted(by_index.keys(), reverse=True)[:max_remove]
 
     out = list(steps)
     removed: List[Dict[str, Any]] = []
diff --git a/backend/planning_exercise_semantics.py b/backend/planning_exercise_semantics.py
index 45a1adc..8c29c06 100644
--- a/backend/planning_exercise_semantics.py
+++ b/backend/planning_exercise_semantics.py
@@ -246,6 +246,11 @@ def build_semantic_brief(query: Optional[str]) -> PlanningSemanticBrief:
     if len(q) >= 24 and not technique:
         strength = max(strength, 0.4)
 
+    path_constraints = parse_stage_goal_constraints(q)
+    for item in path_constraints.exclude_phrases:
+        if item not in exclude:
+            exclude.append(item)
+
     return PlanningSemanticBrief(
         primary_topic=primary,
         topic_type=topic_type,
@@ -775,6 +780,63 @@ def _blob_matches_stage_excludes(blob: str, exclude_phrases: Sequence[str]) -> b
     return False
 
 
+def resolve_path_anti_patterns(
+    goal_query: str,
+    *,
+    semantic_brief: Optional[PlanningSemanticBrief] = None,
+    extra_context: Optional[str] = None,
+) -> List[str]:
+    """
+    Pfadweite Ausschlüsse — nur aus expliziten Quellen, kein Themen-Raten.
+
+    Quellen (in dieser Reihenfolge):
+      1. Negationen in Anfrage/Kontext (ohne/kein/nicht …) via parse_stage_goal_constraints
+      2. exclude_phrases im Semantic Brief (inkl. LLM/Technik-Regeln)
+      3. stage_specs.anti_patterns (Roadmap-Stufe, vom Trainer oder LLM)
+
+    Keine stillen Ausschlüsse aus dem Hauptthema (z. B. „Mawashi“ → kein Kumite).
+    """
+    parts = [str(goal_query or "").strip(), str(extra_context or "").strip()]
+    combined = " ".join(p for p in parts if p)
+    if not combined and not semantic_brief:
+        return []
+
+    constraints = parse_stage_goal_constraints(combined) if combined else StageGoalConstraints()
+    out: List[str] = []
+    for item in constraints.exclude_phrases:
+        if item and item not in out:
+            out.append(item)
+
+    if semantic_brief:
+        for raw in semantic_brief.exclude_phrases or []:
+            for expanded in _expand_stage_exclude_phrase(str(raw or "")):
+                if expanded and expanded not in out:
+                    out.append(expanded)
+
+    return out[:24]
+
+
+def enrich_brief_with_path_constraints(
+    brief: PlanningSemanticBrief,
+    goal_query: str,
+    *,
+    extra_context: Optional[str] = None,
+) -> PlanningSemanticBrief:
+    """Negationen/Ausschlüsse aus der Gesamtanfrage in den Semantic Brief übernehmen."""
+    anti = resolve_path_anti_patterns(
+        goal_query,
+        semantic_brief=brief,
+        extra_context=extra_context,
+    )
+    if not anti:
+        return brief
+    exclude = list(brief.exclude_phrases or [])
+    for item in anti:
+        if item not in exclude:
+            exclude.append(item)
+    return brief.model_copy(update={"exclude_phrases": exclude[:16]})
+
+
 _MIN_STAGE_FIT_SEMANTIC = 0.30
 _MIN_STAGE_FIT_RELAXED = 0.20
 
@@ -787,6 +849,7 @@ def build_stage_match_brief(
     load_profile: Optional[Sequence[str]] = None,
     phase: Optional[str] = None,
     path_context_note: Optional[str] = None,
+    path_anti_patterns: Optional[Sequence[str]] = None,
 ) -> PlanningSemanticBrief:
     """
     Stufen-zentrierter Semantik-Brief — unabhängig vom Gesamt-Pfad-Thema.
@@ -797,7 +860,12 @@ def build_stage_match_brief(
     if len(lg) < 3:
         return PlanningSemanticBrief(semantic_strength=0.0)
 
-    constraints = parse_stage_goal_constraints(lg, anti_patterns)
+    merged_anti: List[str] = []
+    for raw in list(anti_patterns or []) + list(path_anti_patterns or []):
+        s = str(raw or "").strip()
+        if s and s not in merged_anti:
+            merged_anti.append(s)
+    constraints = parse_stage_goal_constraints(lg, merged_anti)
     must: List[str] = []
     norm_lg = _normalize_phrase(lg)
     for token in constraints.positive_tokens:
@@ -1134,7 +1202,9 @@ __all__ = [
     "StageGoalConstraints",
     "apply_stage_match_retrieval_weights",
     "build_stage_match_brief",
+    "enrich_brief_with_path_constraints",
     "exercise_passes_stage_fit",
+    "resolve_path_anti_patterns",
     "exercise_passes_stage_learning_goal_gate",
     "merge_semantic_brief_llm",
     "parse_stage_goal_constraints",
diff --git a/backend/planning_progression_roadmap.py b/backend/planning_progression_roadmap.py
index e1e0a6c..725296a 100644
--- a/backend/planning_progression_roadmap.py
+++ b/backend/planning_progression_roadmap.py
@@ -847,12 +847,24 @@ def build_stage_specs(
     major_steps: Sequence[MajorStep],
     *,
     goal_analysis: GoalAnalysisArtifact,
+    goal_query: str = "",
+    semantic_brief: Optional[PlanningSemanticBrief] = None,
 ) -> List[StageSpecArtifact]:
     """Phase C — Stufenspezifikation je Major Step (heuristisch)."""
+    from planning_exercise_semantics import resolve_path_anti_patterns
+
     topic = goal_analysis.primary_topic or "Technik"
+    path_anti = resolve_path_anti_patterns(goal_query, semantic_brief=semantic_brief)
     specs: List[StageSpecArtifact] = []
     for step in major_steps:
         phase = (step.phase or "vertiefung").lower()
+        anti = [
+            "reine Kraftübung ohne Technikbezug",
+            f"andere Technik als {topic}" if topic else "themenfremde Übung",
+        ]
+        for item in path_anti:
+            if item not in anti:
+                anti.append(item)
         specs.append(
             StageSpecArtifact(
                 major_step_index=step.index,
@@ -863,10 +875,7 @@ def build_stage_specs(
                     f"Bezug zu {topic}",
                     f"Phase {phase} erkennbar im Übungsziel",
                 ],
-                anti_patterns=[
-                    "reine Kraftübung ohne Technikbezug",
-                    f"andere Technik als {topic}" if topic else "themenfremde Übung",
-                ],
+                anti_patterns=anti[:14],
             )
         )
     return specs
@@ -927,14 +936,24 @@ def roadmap_context_from_override(
                 )
             )
         if not all(s.exercise_type for s in stage_specs):
-            rebuilt = build_stage_specs(majors, goal_analysis=goal_analysis)
+            rebuilt = build_stage_specs(
+                majors,
+                goal_analysis=goal_analysis,
+                goal_query=goal_query.strip(),
+                semantic_brief=semantic_brief,
+            )
             for i, spec in enumerate(stage_specs):
                 if not spec.exercise_type:
                     spec.exercise_type = rebuilt[i].exercise_type
                 if not spec.load_profile:
                     spec.load_profile = list(rebuilt[i].load_profile)
     else:
-        stage_specs = build_stage_specs(majors, goal_analysis=goal_analysis)
+        stage_specs = build_stage_specs(
+            majors,
+            goal_analysis=goal_analysis,
+            goal_query=goal_query.strip(),
+            semantic_brief=semantic_brief,
+        )
 
     return ProgressionRoadmapContext(
         goal_query=goal_query.strip(),
@@ -1103,7 +1122,12 @@ def run_progression_roadmap_pipeline(
         )
     ctx.roadmap = roadmap
 
-    stage_specs = build_stage_specs(roadmap.major_steps, goal_analysis=goal_analysis)
+    stage_specs = build_stage_specs(
+        roadmap.major_steps,
+        goal_analysis=goal_analysis,
+        goal_query=goal_query,
+        semantic_brief=brief,
+    )
     if include_llm_roadmap and cur is not None:
         llm_specs, spec_ok = try_llm_stage_specs(
             cur,
diff --git a/backend/tests/test_planning_roadmap_stage_match.py b/backend/tests/test_planning_roadmap_stage_match.py
index ce8a572..9077640 100644
--- a/backend/tests/test_planning_roadmap_stage_match.py
+++ b/backend/tests/test_planning_roadmap_stage_match.py
@@ -1,12 +1,16 @@
 """Tests Roadmap-Stufen-Match — Gate gegen themenfremde Übungen."""
 from planning_exercise_semantics import (
+    build_semantic_brief,
     build_stage_match_brief,
+    enrich_brief_with_path_constraints,
     exercise_passes_stage_learning_goal_gate,
+    exercise_passes_stage_fit,
     pick_best_path_hit,
+    resolve_path_anti_patterns,
     score_exercise_stage_fit,
     semantic_brief_for_stage,
-    build_semantic_brief,
 )
+from planning_exercise_path_qa import strip_off_topic_steps_from_path
 
 
 def test_stage_gate_accepts_learning_goal_in_title():
@@ -174,6 +178,83 @@ def test_pick_best_rejects_mawashi_tritt_precision_for_coordination_slot():
     assert int(chosen["id"]) == 100
 
 
+def test_path_anti_patterns_from_keine_kumite_anwendung():
+    q = "gesprungener Mawashi Geri Sprungphase, keine Kumite-Anwendung gewünscht"
+    brief = enrich_brief_with_path_constraints(build_semantic_brief(q), q)
+    anti = resolve_path_anti_patterns(q, semantic_brief=brief)
+    assert any("kumite" in a for a in anti)
+
+
+def test_stage_fit_rejects_kumite_when_path_excludes_kumite():
+    q = "gesprungener Mawashi Geri, keine Kumite-Anwendung"
+    brief = enrich_brief_with_path_constraints(build_semantic_brief(q), q)
+    path_anti = resolve_path_anti_patterns(q, semantic_brief=brief)
+    stage_goal = "Sprungkraft und Koordination für gesprungenen Mawashi Geri"
+    stage_brief = build_stage_match_brief(
+        learning_goal=stage_goal,
+        anti_patterns=path_anti,
+        path_anti_patterns=path_anti,
+    )
+    assert not exercise_passes_stage_fit(
+        learning_goal=stage_goal,
+        title="Kumite Distanztraining Mawashi",
+        summary="Partner-Kumite mit Trittanwendung",
+        goal="Anwendung im freien Kampf",
+        stage_brief=stage_brief,
+        anti_patterns=path_anti,
+    )
+
+
+def test_pick_best_skips_kumite_for_mawashi_athletic_path():
+    q = "gesprungener Mawashi Geri Sprungkraft, keine Kumite-Anwendung"
+    brief = enrich_brief_with_path_constraints(build_semantic_brief(q), q)
+    path_anti = resolve_path_anti_patterns(q, semantic_brief=brief)
+    stage_goal = "Athletisches Sprungtraining für Mawashi Geri"
+    stage_brief = build_stage_match_brief(
+        learning_goal=stage_goal,
+        anti_patterns=path_anti,
+        path_anti_patterns=path_anti,
+    )
+    hits = [
+        {
+            "id": 1,
+            "title": "Kumite Mawashi Anwendung",
+            "summary": "Partner Kumite",
+            "goal": "Kampfanwendung",
+            "score": 0.95,
+            "semantic_score": 0.55,
+            "stage_semantic_score": 0.55,
+        },
+        {
+            "id": 2,
+            "title": "Sprungkraft Plyometrie",
+            "summary": "Absprung und Landung",
+            "goal": "Sprungkraft für Tritttechnik",
+            "score": 0.62,
+            "semantic_score": 0.38,
+            "stage_semantic_score": 0.38,
+        },
+    ]
+    chosen = pick_best_path_hit(
+        hits,
+        set(),
+        stage_learning_goal=stage_goal,
+        stage_anti_patterns=path_anti,
+        roadmap_stage_match=True,
+        stage_match_brief=stage_brief,
+    )
+    assert chosen is not None
+    assert int(chosen["id"]) == 2
+
+
+def test_strip_off_topic_removes_partial_when_most_steps_bad():
+    steps = [{"exercise_id": i, "title": f"E{i}"} for i in range(1, 8)]
+    off_topic = [{"step_index": i, "issue": "path_exclude"} for i in range(5)]
+    out, removed = strip_off_topic_steps_from_path(steps, off_topic, min_remaining=2)
+    assert len(out) == 2
+    assert len(removed) == 5
+
+
 def test_parse_stage_goal_constraints_extracts_ohne_tritttechnik():
     from planning_exercise_semantics import parse_stage_goal_constraints
 
diff --git a/backend/version.py b/backend/version.py
index 9469e76..8fc2b84 100644
--- a/backend/version.py
+++ b/backend/version.py
@@ -1,6 +1,6 @@
 # Shinkan Jinkendo Version Information
 
-APP_VERSION = "0.8.220"
+APP_VERSION = "0.8.222"
 BUILD_DATE = "2026-06-07"
 DB_SCHEMA_VERSION = "20260607088"
 
@@ -53,6 +53,21 @@ MODULE_VERSIONS = {
 }
 
 CHANGELOG = [
+    {
+        "version": "0.8.222",
+        "date": "2026-06-07",
+        "changes": [
+            "Pfad-Ausschlüsse: athletic→Kumite-Heuristik entfernt — nur explizite Negationen und anti_patterns.",
+        ],
+    },
+    {
+        "version": "0.8.221",
+        "date": "2026-06-07",
+        "changes": [
+            "Pfad-Ausschlüsse (keine Kumite etc.) aus Anfrage in Brief, stage_specs und Matching-Gates.",
+            "QS entfernt path_exclude-Schritte; partielles Strippen wenn die meisten Slots falsch sind.",
+        ],
+    },
     {
         "version": "0.8.220",
         "date": "2026-06-07",

From 4ef3f00e6b60caa3cb00e05b5caf3623eb79ad51 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Thu, 11 Jun 2026 08:47:26 +0200
Subject: [PATCH 18/33] Enhance Planning Intent Context and Stage Specification
 Finalization

- Introduced `intent_context` and `semantic_brief` parameters in `try_llm_stage_specs` to improve context handling for stage specifications.
- Updated `build_goal_analysis` to extract explicit exclusions from goal queries, enhancing constraint management.
- Enhanced `roadmap_context_from_override` to enrich semantic briefs with path constraints and finalize stage specifications with intent context.
- Incremented application version to reflect these updates.
---
 ...9_ai_prompt_planning_intent_enrichment.sql |  67 ++++++
 backend/planning_intent_context.py            | 216 ++++++++++++++++++
 backend/planning_progression_roadmap.py       |  91 +++++++-
 backend/tests/test_planning_intent_context.py |  58 +++++
 backend/version.py                            |  14 +-
 .../PLANNING_PROGRESSION_GRAPH_KI.md          |  31 ++-
 6 files changed, 464 insertions(+), 13 deletions(-)
 create mode 100644 backend/migrations/089_ai_prompt_planning_intent_enrichment.sql
 create mode 100644 backend/planning_intent_context.py
 create mode 100644 backend/tests/test_planning_intent_context.py

diff --git a/backend/migrations/089_ai_prompt_planning_intent_enrichment.sql b/backend/migrations/089_ai_prompt_planning_intent_enrichment.sql
new file mode 100644
index 0000000..7ebcff7
--- /dev/null
+++ b/backend/migrations/089_ai_prompt_planning_intent_enrichment.sql
@@ -0,0 +1,67 @@
+-- Migration 089: Planungs-Intent — Zielanalyse + Stufenspecs (anti_patterns, success_criteria)
+
+UPDATE ai_prompts SET
+    description = 'Phase A: Ist-/Soll, Erfolgskriterien und explizite Ausschlüsse (ohne Gruppenkontext).',
+    template = $t$Du bist Assistent für Kampfsport-Trainer und analysierst eine Anfrage für einen Progressionsgraphen.
+
+Anfrage: {{goal_query}}
+Semantic Brief: {{semantic_brief_json}}
+
+Wichtig:
+- Keine Gruppenanalyse — nur didaktischer Pfad für die Technik/das Thema.
+- Explizite Negationen aus der Anfrage (ohne/kein/nicht …) in constraints.excluded_themes übernehmen — nicht raten.
+- success_criteria: messbar, für späteres Übungs-Matching (Titel + Kurzbeschreibung + Übungsziel).
+
+Antworte NUR mit JSON:
+{
+  "primary_topic": "Hauptthema",
+  "start_assumption": "Voraussetzungen für den Einstieg",
+  "target_state": "Konkreter Zielzustand der Progression",
+  "success_criteria": ["messbare Kriterien entlang des Pfads"],
+  "constraints": {
+    "partner_required": false,
+    "excluded_themes": ["wörtliche Negationen, z. B. keine Kumite-Anwendung"],
+    "trainer_notes": "optional: Fokus aus Ergänzungen"
+  }
+}$t$,
+    default_template = template
+WHERE slug = 'planning_progression_goal_analysis';
+
+UPDATE ai_prompts SET
+    description = 'Phase C: Belastung, Übungstyp, Erfolgskriterien und anti_patterns je Major Step — für Retrieval-Matching.',
+    template = $t$Du bist Assistent für Kampfsport-Trainer und spezifizierst didaktische Stufen eines Progressionsgraphen.
+
+Anfrage: {{goal_query}}
+Zielanalyse: {{goal_analysis_json}}
+Major Steps: {{major_steps_json}}
+Planungs-Intent (Pfadweite Regeln): {{intent_context_json}}
+Semantic Brief: {{semantic_brief_json}}
+
+Aufgabe je Major Step — Felder für automatisches Übungs-Matching (nicht nur Titel):
+- learning_goal: messbares Stufen-Lernziel (was die Übung bringen soll)
+- load_profile: z. B. koordination, präzision, kraft, athletik
+- exercise_type: kihon_einzel | partner_drill | kombination | kraft_auxiliary
+- success_criteria: 2–4 prüfbare Kriterien an Kurzbeschreibung + Übungsziel (nicht nur Technikname im Titel)
+- anti_patterns: 2–5 Dinge, die für diese Stufe unpassend sind
+
+Regeln:
+1. Jede explicit_exclusions / excluded_themes aus intent_context und Zielanalyse MUSS in anti_patterns jeder Stufe vorkommen (umformuliert ok).
+2. Keine neuen Ausschlüsse erfinden, die nicht in Anfrage/Intent/Zielanalyse stehen.
+3. success_criteria Pfad-weit + stufenspezifisch kombinieren.
+4. partner_drill nur wenn Partner/Kumite nicht ausgeschlossen ist.
+
+Antworte NUR mit JSON:
+{
+  "stage_specs": [
+    {
+      "major_step_index": 0,
+      "learning_goal": "…",
+      "load_profile": ["koordination"],
+      "exercise_type": "kihon_einzel",
+      "success_criteria": ["…"],
+      "anti_patterns": ["…"]
+    }
+  ]
+}$t$,
+    default_template = template
+WHERE slug = 'planning_progression_stage_spec';
diff --git a/backend/planning_intent_context.py b/backend/planning_intent_context.py
new file mode 100644
index 0000000..89dd5e2
--- /dev/null
+++ b/backend/planning_intent_context.py
@@ -0,0 +1,216 @@
+"""
+Gemeinsame Intent-Anreicherung für Planungs-Retrieval.
+
+Progressionsgraph (Roadmap stage_specs) und später Trainingsplanung
+(Abschnitt/Slot) nutzen dieselben Bausteine:
+  Intent-Kontext bauen → Specs finalisieren → Matching-Gates.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Mapping, Optional, Sequence
+
+from planning_exercise_semantics import (
+    PlanningSemanticBrief,
+    resolve_path_anti_patterns,
+)
+
+_NEGATION_CLAUSE_RE = re.compile(
+    r"\b(?:ohne|kein(?:e|en|er|em)?|nicht)\s+[^,.;\n]+",
+    flags=re.IGNORECASE,
+)
+
+
+def extract_explicit_exclusions(*texts: Optional[str]) -> List[str]:
+    """Lesbare Negationsklauseln aus Freitext (ohne Themen-Raten)."""
+    out: List[str] = []
+    for raw in texts:
+        s = (raw or "").strip()
+        if not s:
+            continue
+        for m in _NEGATION_CLAUSE_RE.finditer(s):
+            clause = m.group(0).strip().rstrip(".,;")
+            if clause and clause.lower() not in {x.lower() for x in out}:
+                out.append(clause[:220])
+    return out[:12]
+
+
+@dataclass
+class PlanningIntentContext:
+    """Pfad-/Abschnittsweiter Planungs-Intent — domänenneutral."""
+
+    source_query: str = ""
+    primary_topic: str = ""
+    path_anti_patterns: List[str] = field(default_factory=list)
+    path_success_criteria: List[str] = field(default_factory=list)
+    explicit_exclusions: List[str] = field(default_factory=list)
+    context_notes: str = ""
+
+    def to_api_dict(self) -> Dict[str, Any]:
+        return {
+            "source_query": self.source_query,
+            "primary_topic": self.primary_topic,
+            "path_anti_patterns": self.path_anti_patterns[:16],
+            "path_success_criteria": self.path_success_criteria[:10],
+            "explicit_exclusions": self.explicit_exclusions[:10],
+            "context_notes": self.context_notes[:1200] or None,
+        }
+
+
+def build_planning_intent_context(
+    goal_query: str,
+    *,
+    semantic_brief: Optional[PlanningSemanticBrief] = None,
+    goal_analysis: Optional[Mapping[str, Any]] = None,
+    extra_context: Optional[str] = None,
+    primary_topic: Optional[str] = None,
+) -> PlanningIntentContext:
+    """Intent aus Anfrage, Zielanalyse und optionalem Kontext — ohne Sonderregeln pro Thema."""
+    ga = dict(goal_analysis or {})
+    notes_parts = [extra_context or ""]
+    constraints = ga.get("constraints") if isinstance(ga.get("constraints"), dict) else {}
+    if isinstance(constraints, dict):
+        trainer_notes = str(constraints.get("trainer_notes") or "").strip()
+        if trainer_notes:
+            notes_parts.append(trainer_notes)
+
+    combined_notes = " ".join(p.strip() for p in notes_parts if p and p.strip())
+    explicit = extract_explicit_exclusions(goal_query, combined_notes or None)
+    ga_excluded = constraints.get("excluded_themes") if isinstance(constraints, dict) else None
+    if isinstance(ga_excluded, list):
+        for item in ga_excluded:
+            s = str(item or "").strip()
+            if s and s.lower() not in {x.lower() for x in explicit}:
+                explicit.append(s[:220])
+
+    path_anti = resolve_path_anti_patterns(
+        goal_query,
+        semantic_brief=semantic_brief,
+        extra_context=combined_notes or None,
+    )
+    path_success: List[str] = []
+    for item in ga.get("success_criteria") or []:
+        s = str(item or "").strip()
+        if s and s not in path_success:
+            path_success.append(s[:240])
+    target = str(ga.get("target_state") or "").strip()
+    if target and len(target) >= 8:
+        line = f"Zielzustand erreichbar: {target[:200]}"
+        if line not in path_success:
+            path_success.append(line)
+
+    topic = (primary_topic or ga.get("primary_topic") or "").strip()
+    if semantic_brief and not topic:
+        topic = (semantic_brief.primary_topic or "").strip()
+
+    return PlanningIntentContext(
+        source_query=(goal_query or "").strip(),
+        primary_topic=topic,
+        path_anti_patterns=path_anti,
+        path_success_criteria=path_success,
+        explicit_exclusions=explicit,
+        context_notes=combined_notes[:1200],
+    )
+
+
+def _dedupe_preserve(items: Sequence[str], *, limit: int = 14) -> List[str]:
+    out: List[str] = []
+    seen: set[str] = set()
+    for raw in items:
+        s = str(raw or "").strip()
+        if not s:
+            continue
+        key = s.lower()
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(s[:240])
+        if len(out) >= limit:
+            break
+    return out
+
+
+def finalize_stage_spec_artifact(
+    spec: "StageSpecArtifact",
+    *,
+    major_step: Optional["MajorStep"] = None,
+    intent: PlanningIntentContext,
+) -> "StageSpecArtifact":
+    """Pfad-Intent in eine Stufenspezifikation mergen (LLM oder heuristisch)."""
+    from planning_progression_roadmap import MajorStep, StageSpecArtifact
+
+    learning_goal = (spec.learning_goal or (major_step.learning_goal if major_step else "")).strip()
+    phase = (major_step.phase if major_step else "").strip().lower()
+
+    anti = _dedupe_preserve(
+        [
+            *(spec.anti_patterns or []),
+            *intent.explicit_exclusions,
+            *intent.path_anti_patterns,
+        ],
+        limit=14,
+    )
+    success = _dedupe_preserve(
+        [
+            *(spec.success_criteria or []),
+            *intent.path_success_criteria,
+            (
+                f"Übung liefert messbar: {learning_goal[:160]}"
+                if learning_goal
+                else ""
+            ),
+            (
+                f"Kurzbeschreibung und Übungsziel passen zur Phase {phase}"
+                if phase
+                else "Kurzbeschreibung und Übungsziel passen zum Stufen-Lernziel"
+            ),
+        ],
+        limit=8,
+    )
+
+    idx = spec.major_step_index
+    if major_step is not None:
+        idx = major_step.index
+
+    return StageSpecArtifact(
+        major_step_index=idx,
+        learning_goal=learning_goal,
+        load_profile=list(spec.load_profile or []),
+        exercise_type=(spec.exercise_type or "").strip(),
+        success_criteria=success,
+        anti_patterns=anti,
+    )
+
+
+def finalize_stage_specs_with_intent(
+    specs: Sequence["StageSpecArtifact"],
+    major_steps: Sequence["MajorStep"],
+    *,
+    intent: PlanningIntentContext,
+    fallback_specs: Optional[Sequence["StageSpecArtifact"]] = None,
+) -> List["StageSpecArtifact"]:
+    """Alle Stufen mit gleichem Pfad-Intent anreichern; fehlende Indizes aus Fallback."""
+    from planning_progression_roadmap import MajorStep, StageSpecArtifact
+
+    by_idx = {int(s.major_step_index): s for s in specs}
+    fallback_by_idx = {int(s.major_step_index): s for s in (fallback_specs or [])}
+    out: List[StageSpecArtifact] = []
+    for major in major_steps:
+        raw = by_idx.get(major.index) or fallback_by_idx.get(major.index)
+        if raw is None:
+            raw = StageSpecArtifact(
+                major_step_index=major.index,
+                learning_goal=major.learning_goal,
+            )
+        out.append(finalize_stage_spec_artifact(raw, major_step=major, intent=intent))
+    return out
+
+
+__all__ = [
+    "PlanningIntentContext",
+    "build_planning_intent_context",
+    "extract_explicit_exclusions",
+    "finalize_stage_spec_artifact",
+    "finalize_stage_specs_with_intent",
+]
diff --git a/backend/planning_progression_roadmap.py b/backend/planning_progression_roadmap.py
index 725296a..7881b55 100644
--- a/backend/planning_progression_roadmap.py
+++ b/backend/planning_progression_roadmap.py
@@ -298,6 +298,8 @@ def try_llm_stage_specs(
     goal_query: str,
     goal_analysis: GoalAnalysisArtifact,
     major_steps: Sequence[MajorStep],
+    intent_context: Optional[Mapping[str, Any]] = None,
+    semantic_brief: Optional[PlanningSemanticBrief] = None,
 ) -> Tuple[Optional[List[StageSpecArtifact]], bool]:
     obj = _run_prompt_json(
         cur,
@@ -306,6 +308,11 @@ def try_llm_stage_specs(
             "goal_query": goal_query or "",
             "goal_analysis_json": json.dumps(goal_analysis.model_dump(), ensure_ascii=False),
             "major_steps_json": json.dumps([m.model_dump() for m in major_steps], ensure_ascii=False),
+            "intent_context_json": json.dumps(dict(intent_context or {}), ensure_ascii=False),
+            "semantic_brief_json": json.dumps(
+                brief_to_summary_dict(semantic_brief) if semantic_brief else {},
+                ensure_ascii=False,
+            ),
         },
     )
     if not obj:
@@ -522,9 +529,14 @@ def build_goal_analysis(
     if notes.strip():
         criteria.append(f"Berücksichtigung: {notes.strip()[:200]}")
 
+    from planning_intent_context import extract_explicit_exclusions
+
     constraints: Dict[str, Any] = {"partner_required": False, "group_analysis": False}
     if notes.strip():
         constraints["trainer_notes"] = notes.strip()[:500]
+    excluded = extract_explicit_exclusions(goal_query, notes or None)
+    if excluded:
+        constraints["excluded_themes"] = excluded
 
     return GoalAnalysisArtifact(
         primary_topic=topic,
@@ -955,6 +967,44 @@ def roadmap_context_from_override(
             semantic_brief=semantic_brief,
         )
 
+    from planning_exercise_semantics import enrich_brief_with_path_constraints
+    from planning_intent_context import (
+        build_planning_intent_context,
+        finalize_stage_specs_with_intent,
+    )
+
+    enriched_brief = enrich_brief_with_path_constraints(
+        semantic_brief,
+        goal_query.strip(),
+        extra_context=_merge_roadmap_notes(
+            structured.roadmap_notes if structured else None,
+            structured.start_situation if structured else None,
+            structured.target_state if structured else None,
+        ),
+    )
+    intent = build_planning_intent_context(
+        goal_query.strip(),
+        semantic_brief=enriched_brief,
+        goal_analysis=goal_analysis.model_dump(),
+        extra_context=_merge_roadmap_notes(
+            structured.roadmap_notes if structured else None,
+            structured.start_situation if structured else None,
+            structured.target_state if structured else None,
+        ),
+        primary_topic=goal_analysis.primary_topic,
+    )
+    stage_specs = finalize_stage_specs_with_intent(
+        stage_specs,
+        majors,
+        intent=intent,
+        fallback_specs=build_stage_specs(
+            majors,
+            goal_analysis=goal_analysis,
+            goal_query=goal_query.strip(),
+            semantic_brief=enriched_brief,
+        ),
+    )
+
     return ProgressionRoadmapContext(
         goal_query=goal_query.strip(),
         max_steps=effective_max,
@@ -1122,24 +1172,59 @@ def run_progression_roadmap_pipeline(
         )
     ctx.roadmap = roadmap
 
-    stage_specs = build_stage_specs(
+    from planning_exercise_semantics import enrich_brief_with_path_constraints
+    from planning_intent_context import (
+        build_planning_intent_context,
+        finalize_stage_specs_with_intent,
+    )
+
+    brief = enrich_brief_with_path_constraints(
+        brief,
+        goal_query,
+        extra_context=_merge_roadmap_notes(
+            resolved.roadmap_notes,
+            resolved.start_situation,
+            resolved.target_state,
+        ),
+    )
+    intent = build_planning_intent_context(
+        goal_query,
+        semantic_brief=brief,
+        goal_analysis=goal_analysis.model_dump(),
+        extra_context=_merge_roadmap_notes(
+            resolved.roadmap_notes,
+            resolved.start_situation,
+            resolved.target_state,
+        ),
+        primary_topic=goal_analysis.primary_topic,
+    )
+
+    heuristic_specs = build_stage_specs(
         roadmap.major_steps,
         goal_analysis=goal_analysis,
         goal_query=goal_query,
         semantic_brief=brief,
     )
+    stage_specs = list(heuristic_specs)
     if include_llm_roadmap and cur is not None:
         llm_specs, spec_ok = try_llm_stage_specs(
             cur,
             goal_query=llm_goal_query,
             goal_analysis=goal_analysis,
             major_steps=roadmap.major_steps,
+            intent_context=intent.to_api_dict(),
+            semantic_brief=brief,
         )
         if spec_ok and llm_specs:
-            stage_specs = llm_specs
+            stage_specs = list(llm_specs)
             ctx.llm_stage_spec_applied = True
             ctx.prompt_slugs.append(PROMPT_SLUG_STAGE_SPEC)
-    ctx.stage_specs = stage_specs
+    ctx.stage_specs = finalize_stage_specs_with_intent(
+        stage_specs,
+        roadmap.major_steps,
+        intent=intent,
+        fallback_specs=heuristic_specs,
+    )
 
     if ctx.llm_goal_analysis_applied or ctx.llm_roadmap_applied or ctx.llm_stage_spec_applied:
         ctx.pipeline_phase = "roadmap_v1_llm"
diff --git a/backend/tests/test_planning_intent_context.py b/backend/tests/test_planning_intent_context.py
new file mode 100644
index 0000000..e85d5a8
--- /dev/null
+++ b/backend/tests/test_planning_intent_context.py
@@ -0,0 +1,58 @@
+"""Tests gemeinsames Planungs-Intent-Modul (Progressionsgraph → Trainingsplanung)."""
+from planning_intent_context import (
+    build_planning_intent_context,
+    extract_explicit_exclusions,
+    finalize_stage_specs_with_intent,
+)
+from planning_progression_roadmap import (
+    MajorStep,
+    StageSpecArtifact,
+    build_goal_analysis,
+    build_stage_specs,
+    run_progression_roadmap_pipeline,
+)
+from planning_exercise_semantics import build_semantic_brief, enrich_brief_with_path_constraints
+
+
+def test_extract_explicit_exclusions_parses_negations():
+    q = "gesprungener Mawashi Geri, keine Kumite-Anwendung gewünscht"
+    out = extract_explicit_exclusions(q)
+    assert any("kumite" in x.lower() for x in out)
+
+
+def test_build_planning_intent_context_includes_path_anti():
+    q = "Mawashi Geri Sprungkraft, keine Kumite-Anwendung"
+    brief = enrich_brief_with_path_constraints(build_semantic_brief(q), q)
+    ga = build_goal_analysis(q, brief)
+    intent = build_planning_intent_context(q, semantic_brief=brief, goal_analysis=ga.model_dump())
+    assert intent.explicit_exclusions
+    assert any("kumite" in a for a in intent.path_anti_patterns)
+
+
+def test_finalize_stage_specs_merges_intent_into_each_stage():
+    q = "gesprungener Mawashi Geri, keine Kumite-Anwendung"
+    brief = enrich_brief_with_path_constraints(build_semantic_brief(q), q)
+    ga = build_goal_analysis(q, brief)
+    intent = build_planning_intent_context(q, semantic_brief=brief, goal_analysis=ga.model_dump())
+    majors = [
+        MajorStep(index=0, phase="grundlage", learning_goal="Grundtechnik Mawashi", consolidates=["m1"]),
+        MajorStep(index=1, phase="vertiefung", learning_goal="Sprungkoordination", consolidates=["m2"]),
+    ]
+    raw_specs = [
+        StageSpecArtifact(major_step_index=0, learning_goal=majors[0].learning_goal),
+        StageSpecArtifact(major_step_index=1, learning_goal=majors[1].learning_goal),
+    ]
+    finalized = finalize_stage_specs_with_intent(raw_specs, majors, intent=intent)
+    assert len(finalized) == 2
+    for spec in finalized:
+        assert spec.success_criteria
+        assert any("kumite" in a.lower() for a in spec.anti_patterns)
+        assert any("messbar" in c.lower() or "übungsziel" in c.lower() for c in spec.success_criteria)
+
+
+def test_pipeline_stage_specs_carry_exclusions_without_llm():
+    q = "gesprungener Mawashi Geri Sprungphase, keine Kumite-Anwendung"
+    ctx = run_progression_roadmap_pipeline(q, max_steps=3, include_llm_roadmap=False)
+    assert len(ctx.stage_specs) == 3
+    for spec in ctx.stage_specs:
+        assert any("kumite" in a.lower() for a in (spec.anti_patterns or []))
diff --git a/backend/version.py b/backend/version.py
index 8fc2b84..7d5fe5e 100644
--- a/backend/version.py
+++ b/backend/version.py
@@ -1,8 +1,8 @@
 # Shinkan Jinkendo Version Information
 
-APP_VERSION = "0.8.222"
+APP_VERSION = "0.8.223"
 BUILD_DATE = "2026-06-07"
-DB_SCHEMA_VERSION = "20260607088"
+DB_SCHEMA_VERSION = "20260607089"
 
 MODULE_VERSIONS = {
     "legal_documents": "1.4.0",  # Admin: Live-Vorschau pro Abschnitt + modale Vollvorschau (Editor + Dokumentenliste)
@@ -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.22.0",  # skill_expectations, planning_roadmap persist (088), stage_specs override
+    "planning_exercise_suggest": "0.23.0",  # planning_intent_context, finalize stage_specs, Prompt 089
     "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,14 @@ MODULE_VERSIONS = {
 }
 
 CHANGELOG = [
+    {
+        "version": "0.8.223",
+        "date": "2026-06-07",
+        "changes": [
+            "planning_intent_context: gemeinsamer Intent für anti_patterns/success_criteria (Phase G-ready).",
+            "Migration 089: LLM-Prompts Zielanalyse + stage_spec mit Intent-Kontext; finalize nach Pipeline.",
+        ],
+    },
     {
         "version": "0.8.222",
         "date": "2026-06-07",
diff --git a/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md b/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md
index bacadd1..f456456 100644
--- a/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md
+++ b/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md
@@ -225,7 +225,23 @@ Validierung: `progression_graph_planning_artifact.py` · Tests: `test_progressio
 
 ---
 
-## 8. Fähigkeiten-Scoring-Anbindung
+## 8. Planungs-Intent (gemeinsam mit Trainingsplanung)
+
+Modul: **`planning_intent_context.py`** — domänenneutral, wiederverwendbar in Phase G.
+
+| Baustein | Progressionsgraph heute | Trainingsplanung (Phase G) |
+|----------|-------------------------|----------------------------|
+| `build_planning_intent_context` | Aus `goal_query`, Zielanalyse, Notizen | Aus `section_guidance`, Slot, Einheit |
+| `explicit_exclusions` | Negationen (`ohne/kein/nicht …`) | gleich |
+| `path_anti_patterns` | → jede `stage_spec.anti_patterns` | → Abschnitts-/Slot-Brief |
+| `path_success_criteria` | → `success_criteria` + Matching | → Slot-Erwartung |
+| `finalize_stage_specs_with_intent` | Nach heuristischer/LLM-Roadmap | Analog für Sektionen |
+
+LLM: Migration **089** — Prompts `planning_progression_goal_analysis` + `planning_progression_stage_spec` erhalten `intent_context_json`; Ausschlüsse nicht erfinden, nur aus Anfrage übernehmen.
+
+Matching: `anti_patterns` + `success_criteria` → `build_stage_match_brief` → Retrieval-Gate (Titel + Summary + Goal).
+
+## 9. Fähigkeiten-Scoring-Anbindung
 
 Modul: `planning_skill_expectations.py`
 
@@ -245,7 +261,7 @@ Integration:
 
 ---
 
-## 9. KI-Lücken (Gap-Fill)
+## 10. KI-Lücken (Gap-Fill)
 
 Flow:
 1. `roadmap_unfilled` / QA-Lücken → `gap_fill_offers`
@@ -257,7 +273,7 @@ Kontext-Helfer: `frontend/src/utils/planningContextForExerciseAi.js`
 
 ---
 
-## 10. Implementierungsstände (Phasen)
+## 11. Implementierungsstände (Phasen)
 
 | Phase | Inhalt | Status | Version |
 |-------|--------|--------|---------|
@@ -275,7 +291,7 @@ Kontext-Helfer: `frontend/src/utils/planningContextForExerciseAi.js`
 
 ---
 
-## 11. Offenes Backlog (priorisiert)
+## 12. Offenes Backlog (priorisiert)
 
 1. **UI-Überarbeitung** — Wizard mit 4 Schritten, progressive disclosure (Briefing unten)
 2. **Graph-Erweiterungsmodus** — Start ab gewähltem Knoten / letzter Sequenz
@@ -292,13 +308,14 @@ Kern: Wizard ① Ziel & Start/Ziel → ② Roadmap → ③ Match → ④ Lücken
 
 ---
 
-## 12. Tests
+## 13. 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_intent_context.py` | Intent-Kontext, finalize stage_specs |
 | `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 |
@@ -306,7 +323,7 @@ Kern: Wizard ① Ziel & Start/Ziel → ② Roadmap → ③ Match → ④ Lücken
 
 ---
 
-## 13. Dokumenten-Index (Drift vermeiden)
+## 14. Dokumenten-Index (Drift vermeiden)
 
 | Frage | Primäre Quelle |
 |-------|----------------|
@@ -322,7 +339,7 @@ Kern: Wizard ① Ziel & Start/Ziel → ② Roadmap → ③ Match → ④ Lücken
 
 ---
 
-## 14. Changelog (Dokument)
+## 15. Changelog (Dokument)
 
 | Datum | Änderung |
 |-------|----------|

From a152218c45248974aa892b095256389ce1608c77 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Thu, 11 Jun 2026 10:19:58 +0200
Subject: [PATCH 19/33] Enhance Path QA and Stage Matching Logic

- Introduced multistage path quality assurance (QA) functionality to improve exercise relevance and feedback through structured tiers and optimization hints.
- Updated stage specifications to include `start_state` and `target_state` for better contextualization in roadmap matching.
- Enhanced semantic brief construction with technique sibling exclusions to refine exercise selection based on primary topics.
- Improved path retrieval logic to incorporate new parameters for nuanced matching against learning goals.
- Incremented application version to reflect these updates.
---
 .../090_ai_prompt_stage_transition_states.sql |  43 +++++
 backend/planning_exercise_path_builder.py     |  65 +++++++
 backend/planning_exercise_path_qa.py          |  32 ++++
 backend/planning_exercise_retrieval.py        |   2 +
 backend/planning_exercise_semantics.py        |  90 ++++++++-
 backend/planning_intent_context.py            |  36 +++-
 backend/planning_path_qa_pipeline.py          | 176 ++++++++++++++++++
 backend/planning_progression_roadmap.py       |  32 ++++
 backend/planning_stage_context.py             | 140 ++++++++++++++
 .../test_planning_roadmap_stage_match.py      |  43 +++++
 backend/tests/test_planning_stage_context.py  |  65 +++++++
 backend/version.py                            |  20 +-
 .../PLANNING_PROGRESSION_GRAPH_KI.md          |  22 +++
 13 files changed, 760 insertions(+), 6 deletions(-)
 create mode 100644 backend/migrations/090_ai_prompt_stage_transition_states.sql
 create mode 100644 backend/planning_path_qa_pipeline.py
 create mode 100644 backend/planning_stage_context.py
 create mode 100644 backend/tests/test_planning_stage_context.py

diff --git a/backend/migrations/090_ai_prompt_stage_transition_states.sql b/backend/migrations/090_ai_prompt_stage_transition_states.sql
new file mode 100644
index 0000000..1a04b80
--- /dev/null
+++ b/backend/migrations/090_ai_prompt_stage_transition_states.sql
@@ -0,0 +1,43 @@
+-- Migration 090: Stufenspecs — start_state / target_state pro Major Step (Soll-Verkettung)
+
+UPDATE ai_prompts SET
+    description = 'Phase C: Stufenspezifikation inkl. Soll-Start und Stufen-Ziel je Major Step.',
+    template = $t$Du bist Assistent für Kampfsport-Trainer und spezifizierst didaktische Stufen eines Progressionsgraphen.
+
+Anfrage: {{goal_query}}
+Zielanalyse: {{goal_analysis_json}}
+Major Steps: {{major_steps_json}}
+Planungs-Intent (Pfadweite Regeln): {{intent_context_json}}
+Semantic Brief: {{semantic_brief_json}}
+
+Jede Stufe ist ein Übergang im Gesamtpfad:
+- start_state: Soll-Zustand zu Beginn (= Ziel der vorherigen Stufe; Stufe 0 = Pfad-Start)
+- target_state: Zielzustand nach dieser Stufe (= Soll für die nächste Stufe)
+- learning_goal: messbares Lernziel der Übungssuche (was die Übung bringen soll)
+
+Felder je Major Step:
+- load_profile, exercise_type, success_criteria, anti_patterns (wie bisher)
+
+Regeln:
+1. start_state/target_state aus Zielanalyse und Major Steps ableiten — konsistente Kette.
+2. explicit_exclusions aus intent_context in anti_patterns jeder Stufe.
+3. success_criteria: prüfbar an Kurzbeschreibung + Übungsziel.
+4. Keine erfundenen Ausschlüsse.
+
+Antworte NUR mit JSON:
+{
+  "stage_specs": [
+    {
+      "major_step_index": 0,
+      "start_state": "…",
+      "target_state": "…",
+      "learning_goal": "…",
+      "load_profile": ["koordination"],
+      "exercise_type": "kihon_einzel",
+      "success_criteria": ["…"],
+      "anti_patterns": ["…"]
+    }
+  ]
+}$t$,
+    default_template = template
+WHERE slug = 'planning_progression_stage_spec';
diff --git a/backend/planning_exercise_path_builder.py b/backend/planning_exercise_path_builder.py
index 44a1228..9a56cf5 100644
--- a/backend/planning_exercise_path_builder.py
+++ b/backend/planning_exercise_path_builder.py
@@ -13,6 +13,8 @@ from pydantic import BaseModel, Field
 
 from tenant_context import TenantContext, library_content_visibility_sql
 from planning_exercise_profiles import PlanningTargetProfile
+from planning_path_qa_pipeline import run_multistage_path_qa
+from planning_stage_context import build_contextualized_stage_goal, resolve_path_start_target
 from planning_exercise_path_qa import (
     apply_llm_path_reorder,
     build_path_qa_summary,
@@ -191,6 +193,8 @@ def _pick_best_path_hit(
     stage_anti_patterns: Optional[List[str]] = None,
     roadmap_stage_match: bool = False,
     stage_match_brief: Optional[PlanningSemanticBrief] = None,
+    path_primary_topic: Optional[str] = None,
+    path_technique_excludes: Optional[List[str]] = None,
 ) -> Optional[Dict[str, Any]]:
     return pick_best_path_hit(
         hits,
@@ -200,6 +204,8 @@ def _pick_best_path_hit(
         stage_anti_patterns=stage_anti_patterns,
         roadmap_stage_match=roadmap_stage_match,
         stage_match_brief=stage_match_brief,
+        path_primary_topic=path_primary_topic,
+        path_technique_excludes=path_technique_excludes,
     )
 
 
@@ -304,6 +310,8 @@ def _run_path_step_retrieval(
     stage_success_criteria: Optional[List[str]] = None,
     stage_load_profile: Optional[List[str]] = None,
     path_context_note: Optional[str] = None,
+    path_primary_topic: Optional[str] = None,
+    path_technique_excludes: Optional[List[str]] = None,
 ) -> Tuple[List[Dict[str, Any]], PlanningTargetProfile, Dict[str, Any], str]:
     step_query = step_query_override or step_retrieval_query(
         semantic_brief, goal_query, step_index, max_steps
@@ -346,6 +354,8 @@ def _run_path_step_retrieval(
         "stage_success_criteria": list(stage_success_criteria or []),
         "stage_load_profile": list(stage_load_profile or []),
         "path_context_note": (path_context_note or "").strip() or None,
+        "path_primary_topic": (path_primary_topic or "").strip() or None,
+        "path_technique_excludes": list(path_technique_excludes or []),
     }
     pack = apply_progression_context_to_pack(
         cur,
@@ -514,6 +524,10 @@ def _annotate_roadmap_step(
     anti = list(anti_patterns_override or stage_spec.anti_patterns or [])
     if anti:
         step["roadmap_anti_patterns"] = anti
+    if (stage_spec.start_state or "").strip():
+        step["roadmap_start_state"] = stage_spec.start_state.strip()
+    if (stage_spec.target_state or "").strip():
+        step["roadmap_target_state"] = stage_spec.target_state.strip()
     step["roadmap_match_source"] = "stage_spec"
     if skill_expectations:
         step["skill_expectations"] = skill_expectations
@@ -562,6 +576,11 @@ def _build_steps_roadmap_first(
         if roadmap_ctx.resolved_structured
         else None
     )
+    path_start, path_target = resolve_path_start_target(
+        structured=roadmap_ctx.resolved_structured,
+        goal_analysis=roadmap_ctx.goal_analysis,
+    )
+    stage_count = len(stage_specs)
     brief_summary = (
         roadmap_ctx.semantic_brief
         if roadmap_ctx.semantic_brief
@@ -593,6 +612,17 @@ def _build_steps_roadmap_first(
         )
         step_kind = resolve_step_exercise_kind_filter(stage_spec, body.exercise_kind_any)
         stage_goal = (stage_spec.learning_goal or "").strip()
+        stage_start = (stage_spec.start_state or "").strip()
+        stage_target = (stage_spec.target_state or "").strip()
+        contextual_goal = build_contextualized_stage_goal(
+            learning_goal=stage_goal,
+            start_state=stage_start,
+            target_state=stage_target,
+            path_target_state=path_target,
+            path_start_state=path_start,
+            stage_index=step_index,
+            stage_count=stage_count,
+        )
         path_context_note = None
         if rs_dump:
             ctx_parts = [
@@ -607,6 +637,14 @@ def _build_steps_roadmap_first(
             extra_context=path_context_note,
         )
         stage_anti = list(dict.fromkeys([*(stage_spec.anti_patterns or []), *path_anti]))
+        path_primary = (semantic_brief.primary_topic or "").strip()
+        path_tech_excludes = list(semantic_brief.exclude_phrases or [])
+        if semantic_brief.topic_type == "technique" and path_primary:
+            from planning_exercise_semantics import technique_sibling_excludes
+
+            for item in technique_sibling_excludes(path_primary):
+                if item not in path_tech_excludes:
+                    path_tech_excludes.append(item)
         stage_match_brief = build_stage_match_brief(
             learning_goal=stage_goal,
             anti_patterns=stage_anti,
@@ -615,6 +653,12 @@ def _build_steps_roadmap_first(
             phase=major.phase if major else None,
             path_context_note=path_context_note,
             path_anti_patterns=path_anti,
+            path_primary_topic=path_primary or None,
+            path_technique_excludes=path_tech_excludes or None,
+            stage_start_state=stage_start or None,
+            stage_target_state=stage_target or None,
+            path_target_state=path_target or None,
+            contextualized_learning_goal=contextual_goal or None,
         )
 
         hits, _, _, _ = _run_path_step_retrieval(
@@ -641,6 +685,8 @@ def _build_steps_roadmap_first(
             stage_success_criteria=list(stage_spec.success_criteria or []),
             stage_load_profile=list(stage_spec.load_profile or []),
             path_context_note=path_context_note,
+            path_primary_topic=path_primary or None,
+            path_technique_excludes=path_tech_excludes or None,
         )
 
         hit = _pick_best_path_hit(
@@ -651,6 +697,8 @@ def _build_steps_roadmap_first(
             stage_anti_patterns=stage_anti or None,
             roadmap_stage_match=True,
             stage_match_brief=stage_match_brief,
+            path_primary_topic=path_primary or None,
+            path_technique_excludes=path_tech_excludes or None,
         )
 
         if not hit:
@@ -878,6 +926,13 @@ def _run_evaluate_only_path_qa(
                 roadmap_snapshot=path_roadmap_snapshot,
             )
 
+    multistage_qa = run_multistage_path_qa(
+        off_topic_steps=off_topic_steps,
+        stripped_off_topic=stripped_off_topic,
+        gaps=gaps,
+        llm_qa=llm_qa,
+        llm_applied=llm_qa_applied,
+    )
     path_qa = build_path_qa_summary(
         gaps=gaps,
         bridge_inserts=bridge_inserts,
@@ -890,6 +945,7 @@ def _run_evaluate_only_path_qa(
         reorder_applied=False,
         reorder_notes=[],
         roadmap_qa_mode=roadmap_qa_mode,
+        multistage_qa=multistage_qa,
     )
     return {
         "path_qa": path_qa,
@@ -1318,6 +1374,14 @@ def suggest_progression_path(
             if offer.get("offer_id") not in seen_offer_ids:
                 gap_fill_offers.append(offer)
 
+    multistage_qa = run_multistage_path_qa(
+        off_topic_steps=off_topic_steps,
+        stripped_off_topic=stripped_off_topic,
+        gaps=gaps,
+        llm_qa=llm_qa,
+        llm_applied=llm_qa_applied,
+        roadmap_unfilled=roadmap_unfilled if roadmap_first else None,
+    )
     path_qa = build_path_qa_summary(
         gaps=gaps,
         bridge_inserts=bridge_inserts,
@@ -1330,6 +1394,7 @@ def suggest_progression_path(
         reorder_applied=reorder_applied,
         reorder_notes=reorder_notes,
         roadmap_qa_mode=roadmap_qa_mode,
+        multistage_qa=multistage_qa,
     )
 
     target_profile_summary = path_target_profile.to_summary_dict(cur)
diff --git a/backend/planning_exercise_path_qa.py b/backend/planning_exercise_path_qa.py
index de7a896..4ce77ba 100644
--- a/backend/planning_exercise_path_qa.py
+++ b/backend/planning_exercise_path_qa.py
@@ -23,10 +23,12 @@ from planning_exercise_semantics import (
     brief_to_summary_dict,
     exercise_passes_path_semantic_gate,
     exercise_passes_stage_learning_goal_gate,
+    exercise_passes_technique_path_scope,
     resolve_path_anti_patterns,
     score_exercise_semantic_relevance,
     semantic_brief_for_stage,
     step_phase_for_index,
+    technique_sibling_excludes,
 )
 
 _logger = logging.getLogger("shinkan.planning_exercise_path_qa")
@@ -434,6 +436,31 @@ def detect_off_topic_steps(
                 }
             )
             continue
+        primary = (brief.primary_topic or "").strip()
+        if brief.topic_type == "technique" and primary:
+            siblings = technique_sibling_excludes(primary)
+            stage_goal_pre = (step.get("roadmap_learning_goal") or "").strip()
+            if not exercise_passes_technique_path_scope(
+                primary_topic=primary,
+                title=bundle["title"],
+                summary=bundle["summary"],
+                goal=bundle["goal"],
+                learning_goal=stage_goal_pre,
+                sibling_excludes=siblings,
+                relaxed=False,
+            ):
+                off_topic.append(
+                    {
+                        "step_index": idx,
+                        "exercise_id": int(step["exercise_id"]),
+                        "title": step.get("title") or bundle["title"],
+                        "semantic_score": 0.0,
+                        "expected_phase": (step.get("roadmap_phase") or "").strip().lower() or None,
+                        "issue": "technique_scope",
+                        "reasons": [f"Passt nicht zur Haupttechnik „{primary}“"],
+                    }
+                )
+                continue
         stage_goal = (step.get("roadmap_learning_goal") or "").strip()
         phase = (step.get("roadmap_phase") or "").strip().lower() or step_phase_for_index(
             brief, idx, total
@@ -599,6 +626,7 @@ def build_path_qa_summary(
     reorder_applied: bool = False,
     reorder_notes: Optional[Sequence[str]] = None,
     roadmap_qa_mode: Optional[str] = None,
+    multistage_qa: Optional[Mapping[str, Any]] = None,
 ) -> Dict[str, Any]:
     offers = list(gap_fill_offers or [])
     off_topic = list(off_topic_steps or [])
@@ -619,6 +647,10 @@ def build_path_qa_summary(
         "reorder_notes": list(reorder_notes or []),
         "roadmap_qa_mode": roadmap_qa_mode,
     }
+    if multistage_qa:
+        summary["qa_tiers"] = list(multistage_qa.get("qa_tiers") or [])
+        summary["optimization_hints"] = list(multistage_qa.get("optimization_hints") or [])
+        summary["optimization_hint_count"] = int(multistage_qa.get("optimization_hint_count") or 0)
     if llm_qa:
         summary["overall_ok"] = bool(llm_qa.get("overall_ok", True))
         summary["quality_score"] = llm_qa.get("quality_score")
diff --git a/backend/planning_exercise_retrieval.py b/backend/planning_exercise_retrieval.py
index 3051518..6b748b1 100644
--- a/backend/planning_exercise_retrieval.py
+++ b/backend/planning_exercise_retrieval.py
@@ -351,6 +351,8 @@ def rank_visible_library_hits(
                 stage_semantic_score=stage_semantic_score,
                 anti_patterns=pack.get("stage_anti_patterns"),
                 step_phase=step_phase,
+                path_primary_topic=pack.get("path_primary_topic"),
+                path_technique_excludes=pack.get("path_technique_excludes"),
             ):
                 score_penalty = max(0.0, score_penalty - 0.10)
                 stage_match_reason = "Passt zum Stufen-Lernziel"
diff --git a/backend/planning_exercise_semantics.py b/backend/planning_exercise_semantics.py
index 8c29c06..38798e2 100644
--- a/backend/planning_exercise_semantics.py
+++ b/backend/planning_exercise_semantics.py
@@ -180,6 +180,51 @@ def _find_technique_in_text(q_lower: str) -> Optional[Tuple[str, Tuple[str, ...]
     return None
 
 
+def technique_sibling_excludes(primary_topic: str) -> List[str]:
+    """Andere Techniken derselben Familie (z. B. Mae/Yoko bei Mawashi) — aus Katalog."""
+    topic = _normalize_phrase(primary_topic)
+    if not topic:
+        return []
+    hit = _find_technique_in_text(topic)
+    if not hit:
+        return []
+    out: List[str] = []
+    for raw in hit[1]:
+        for expanded in _expand_stage_exclude_phrase(raw):
+            if expanded and expanded not in out:
+                out.append(expanded)
+    return out[:16]
+
+
+def exercise_passes_technique_path_scope(
+    *,
+    primary_topic: str,
+    title: str,
+    summary: str = "",
+    goal: str = "",
+    learning_goal: str = "",
+    sibling_excludes: Optional[Sequence[str]] = None,
+    relaxed: bool = False,
+) -> bool:
+    """
+    Technik-Pfad: keine Geschwister-Technik; Haupttechnik im Übungstext oder Stufen-Lernziel.
+    """
+    primary = _normalize_phrase(primary_topic)
+    if not primary:
+        return True
+
+    blob = _blob_from_fields(title, summary, goal, [])
+    excludes = list(sibling_excludes or technique_sibling_excludes(primary))
+    if excludes and _blob_matches_stage_excludes(blob, excludes):
+        return False
+
+    in_exercise = _phrase_in_blob(primary, blob)
+    in_stage = _phrase_in_blob(primary, _blob_from_fields("", "", learning_goal, []))
+    if in_exercise or in_stage:
+        return True
+    return relaxed
+
+
 def _detect_development_arc(q_lower: str) -> List[str]:
     found: List[str] = []
     for phase, markers in _ARC_PHASES:
@@ -850,13 +895,19 @@ def build_stage_match_brief(
     phase: Optional[str] = None,
     path_context_note: Optional[str] = None,
     path_anti_patterns: Optional[Sequence[str]] = None,
+    path_primary_topic: Optional[str] = None,
+    path_technique_excludes: Optional[Sequence[str]] = None,
+    stage_start_state: Optional[str] = None,
+    stage_target_state: Optional[str] = None,
+    path_target_state: Optional[str] = None,
+    contextualized_learning_goal: Optional[str] = None,
 ) -> PlanningSemanticBrief:
     """
     Stufen-zentrierter Semantik-Brief — unabhängig vom Gesamt-Pfad-Thema.
 
     Primär für Roadmap-Match: Bewertung gegen Titel + Kurzbeschreibung + Übungsziel.
     """
-    lg = (learning_goal or "").strip()
+    lg = (contextualized_learning_goal or learning_goal or "").strip()
     if len(lg) < 3:
         return PlanningSemanticBrief(semantic_strength=0.0)
 
@@ -865,9 +916,20 @@ def build_stage_match_brief(
         s = str(raw or "").strip()
         if s and s not in merged_anti:
             merged_anti.append(s)
+    primary_path = _normalize_phrase(path_primary_topic or "")
+    if primary_path:
+        for item in technique_sibling_excludes(primary_path):
+            if item not in merged_anti:
+                merged_anti.append(item)
+    for raw in path_technique_excludes or []:
+        for expanded in _expand_stage_exclude_phrase(str(raw or "")):
+            if expanded and expanded not in merged_anti:
+                merged_anti.append(expanded)
     constraints = parse_stage_goal_constraints(lg, merged_anti)
     must: List[str] = []
     norm_lg = _normalize_phrase(lg)
+    if primary_path and primary_path not in must:
+        must.insert(0, primary_path[:120])
     for token in constraints.positive_tokens:
         if token not in must:
             must.append(token)
@@ -883,6 +945,10 @@ def build_stage_match_brief(
             must.append(s[:60])
 
     retrieval_parts = [norm_lg]
+    for raw in (stage_start_state, stage_target_state, path_target_state):
+        s = _normalize_phrase(str(raw or ""))[:200]
+        if s and s not in retrieval_parts:
+            retrieval_parts.append(s)
     if path_context_note:
         note = _normalize_phrase(path_context_note)[:200]
         if note:
@@ -950,12 +1016,14 @@ def exercise_passes_stage_fit(
     stage_semantic_score: Optional[float] = None,
     anti_patterns: Optional[Sequence[str]] = None,
     step_phase: Optional[str] = None,
+    path_primary_topic: Optional[str] = None,
+    path_technique_excludes: Optional[Sequence[str]] = None,
     min_stage_semantic: float = _MIN_STAGE_FIT_SEMANTIC,
     relaxed: bool = False,
 ) -> bool:
     """Allgemeines Stufen-Fit-Gate: voller Übungstext vs. Stufen-Brief."""
     lg = (learning_goal or "").strip()
-    if len(lg) < 3:
+    if len(lg) < 3 and not (path_primary_topic or "").strip():
         return True
 
     blob = _blob_from_fields(title, summary, goal, [])
@@ -963,6 +1031,18 @@ def exercise_passes_stage_fit(
     if constraints.exclude_phrases and _blob_matches_stage_excludes(blob, constraints.exclude_phrases):
         return False
 
+    primary_path = (path_primary_topic or "").strip()
+    if primary_path and not exercise_passes_technique_path_scope(
+        primary_topic=primary_path,
+        title=title,
+        summary=summary,
+        goal=goal,
+        learning_goal=lg,
+        sibling_excludes=path_technique_excludes,
+        relaxed=relaxed,
+    ):
+        return False
+
     brief = stage_brief or build_stage_match_brief(
         learning_goal=lg,
         anti_patterns=anti_patterns,
@@ -1102,6 +1182,8 @@ def pick_best_path_hit(
     stage_anti_patterns: Optional[Sequence[str]] = None,
     roadmap_stage_match: bool = False,
     stage_match_brief: Optional[PlanningSemanticBrief] = None,
+    path_primary_topic: Optional[str] = None,
+    path_technique_excludes: Optional[Sequence[str]] = None,
 ) -> Optional[Dict[str, Any]]:
     """Gestufte Auswahl: strikt → relaxed → optional Notfall-Fallback."""
     if not hits:
@@ -1138,6 +1220,8 @@ def pick_best_path_hit(
                     stage_brief=stage_brief,
                     stage_semantic_score=stage_sem,
                     anti_patterns=stage_anti_patterns,
+                    path_primary_topic=path_primary_topic,
+                    path_technique_excludes=path_technique_excludes,
                     relaxed=not strict,
                 ):
                     continue
@@ -1209,8 +1293,10 @@ __all__ = [
     "merge_semantic_brief_llm",
     "parse_stage_goal_constraints",
     "pick_best_path_hit",
+    "exercise_passes_technique_path_scope",
     "score_exercise_stage_fit",
     "semantic_brief_for_stage",
+    "technique_sibling_excludes",
     "resolve_semantic_skill_weights",
     "score_exercise_semantic_relevance",
     "semantic_core_phrases",
diff --git a/backend/planning_intent_context.py b/backend/planning_intent_context.py
index 89dd5e2..ce6e774 100644
--- a/backend/planning_intent_context.py
+++ b/backend/planning_intent_context.py
@@ -14,6 +14,7 @@ from typing import Any, Dict, List, Mapping, Optional, Sequence
 from planning_exercise_semantics import (
     PlanningSemanticBrief,
     resolve_path_anti_patterns,
+    technique_sibling_excludes,
 )
 
 _NEGATION_CLAUSE_RE = re.compile(
@@ -46,14 +47,18 @@ class PlanningIntentContext:
     path_success_criteria: List[str] = field(default_factory=list)
     explicit_exclusions: List[str] = field(default_factory=list)
     context_notes: str = ""
+    topic_type: str = "general"
+    technique_sibling_excludes: List[str] = field(default_factory=list)
 
     def to_api_dict(self) -> Dict[str, Any]:
         return {
             "source_query": self.source_query,
             "primary_topic": self.primary_topic,
+            "topic_type": self.topic_type,
             "path_anti_patterns": self.path_anti_patterns[:16],
             "path_success_criteria": self.path_success_criteria[:10],
             "explicit_exclusions": self.explicit_exclusions[:10],
+            "technique_sibling_excludes": self.technique_sibling_excludes[:16],
             "context_notes": self.context_notes[:1200] or None,
         }
 
@@ -101,15 +106,32 @@ def build_planning_intent_context(
             path_success.append(line)
 
     topic = (primary_topic or ga.get("primary_topic") or "").strip()
-    if semantic_brief and not topic:
-        topic = (semantic_brief.primary_topic or "").strip()
+    topic_type = "general"
+    siblings: List[str] = []
+    if semantic_brief:
+        if not topic:
+            topic = (semantic_brief.primary_topic or "").strip()
+        topic_type = (semantic_brief.topic_type or "general").strip().lower()
+        if topic_type == "technique" and topic:
+            siblings = technique_sibling_excludes(topic)
+            for raw in semantic_brief.exclude_phrases or []:
+                s = str(raw or "").strip()
+                if s and s.lower() not in {x.lower() for x in siblings}:
+                    siblings.append(s[:120])
+
+    if topic_type == "technique" and topic:
+        line = f"Haupttechnik {topic} in Kurzbeschreibung oder Übungsziel erkennbar"
+        if line not in path_success:
+            path_success.insert(0, line)
 
     return PlanningIntentContext(
         source_query=(goal_query or "").strip(),
         primary_topic=topic,
+        topic_type=topic_type,
         path_anti_patterns=path_anti,
         path_success_criteria=path_success,
         explicit_exclusions=explicit,
+        technique_sibling_excludes=siblings[:16],
         context_notes=combined_notes[:1200],
     )
 
@@ -148,13 +170,23 @@ def finalize_stage_spec_artifact(
             *(spec.anti_patterns or []),
             *intent.explicit_exclusions,
             *intent.path_anti_patterns,
+            *intent.technique_sibling_excludes,
+            (
+                f"andere Technik als {intent.primary_topic}"
+                if intent.topic_type == "technique" and intent.primary_topic
+                else ""
+            ),
         ],
         limit=14,
     )
+    stage_start = (spec.start_state or "").strip()
+    stage_target = (spec.target_state or "").strip()
     success = _dedupe_preserve(
         [
             *(spec.success_criteria or []),
             *intent.path_success_criteria,
+            (f"Soll-Start der Stufe erreichbar: {stage_start[:180]}" if stage_start else ""),
+            (f"Stufen-Ziel erreichbar: {stage_target[:180]}" if stage_target else ""),
             (
                 f"Übung liefert messbar: {learning_goal[:160]}"
                 if learning_goal
diff --git a/backend/planning_path_qa_pipeline.py b/backend/planning_path_qa_pipeline.py
new file mode 100644
index 0000000..2073880
--- /dev/null
+++ b/backend/planning_path_qa_pipeline.py
@@ -0,0 +1,176 @@
+"""
+Mehrstufige Pfad-QS — Findings pro Stufe, daraus Optimierungspotenziale ableiten.
+
+Stufen (allgemein, domänenneutral):
+  1. deterministische Gates (Technik-Scope, Ausschlüsse, Stufen-Fit)
+  2. Übergangs-Kohärenz (Lücken zwischen Schritten)
+  3. LLM-Ganzpfad-Bewertung (Empfehlungen, keine Auto-Patches)
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Mapping, Optional, Sequence
+
+
+_ACTION_BY_ISSUE: Dict[str, str] = {
+    "technique_scope": "rematch_slot",
+    "path_exclude": "rematch_slot",
+    "stage_mismatch": "refine_stage_spec",
+    "off_topic": "rematch_slot",
+    "gap": "bridge_or_gap_fill",
+    "large_gap": "bridge_or_gap_fill",
+    "roadmap_unfilled": "rematch_slot",
+}
+
+
+def _action_for_finding(finding: Mapping[str, Any]) -> str:
+    issue = str(finding.get("issue") or finding.get("type") or "").strip().lower()
+    if finding.get("is_large_gap"):
+        return "bridge_or_gap_fill"
+    return _ACTION_BY_ISSUE.get(issue, "review")
+
+
+def _hint_from_finding(finding: Mapping[str, Any], *, tier: str) -> Dict[str, Any]:
+    step_index = finding.get("step_index")
+    if step_index is None:
+        step_index = finding.get("major_step_index")
+    issue = str(finding.get("issue") or finding.get("type") or tier)
+    action = _action_for_finding(finding)
+    title = str(finding.get("title") or finding.get("removed_title") or "").strip()
+    reasons = finding.get("reasons") or []
+    reason = reasons[0] if reasons else str(finding.get("rationale") or finding.get("detail") or "")
+
+    hint: Dict[str, Any] = {
+        "tier": tier,
+        "action": action,
+        "issue": issue,
+        "step_index": step_index,
+        "title": title or None,
+        "reason": (reason or "")[:400] or None,
+    }
+    if finding.get("roadmap_learning_goal"):
+        hint["roadmap_learning_goal"] = finding.get("roadmap_learning_goal")
+    if finding.get("roadmap_major_step_index") is not None:
+        hint["roadmap_major_step_index"] = finding.get("roadmap_major_step_index")
+    return {k: v for k, v in hint.items() if v is not None and v != ""}
+
+
+def derive_optimization_hints(
+    tiers: Sequence[Mapping[str, Any]],
+) -> List[Dict[str, Any]]:
+    """Aus QS-Stufen konkrete Optimierungsaktionen (ohne anfrage-spezifische Heuristiken)."""
+    hints: List[Dict[str, Any]] = []
+    seen: set[tuple] = set()
+    for tier in tiers:
+        tier_id = str(tier.get("id") or "")
+        for finding in tier.get("findings") or []:
+            if not isinstance(finding, dict):
+                continue
+            hint = _hint_from_finding(finding, tier=tier_id)
+            key = (
+                hint.get("tier"),
+                hint.get("action"),
+                hint.get("step_index"),
+                hint.get("issue"),
+            )
+            if key in seen:
+                continue
+            seen.add(key)
+            hints.append(hint)
+    return hints[:24]
+
+
+def run_multistage_path_qa(
+    *,
+    off_topic_steps: Sequence[Mapping[str, Any]],
+    stripped_off_topic: Sequence[Mapping[str, Any]],
+    gaps: Sequence[Mapping[str, Any]],
+    llm_qa: Optional[Mapping[str, Any]] = None,
+    llm_applied: bool = False,
+    roadmap_unfilled: Optional[Sequence[Mapping[str, Any]]] = None,
+) -> Dict[str, Any]:
+    """Orchestriert QS-Stufen und leitet Optimierungspotenziale ab."""
+    tier1_findings: List[Dict[str, Any]] = []
+    for item in stripped_off_topic or off_topic_steps or []:
+        if isinstance(item, dict):
+            tier1_findings.append(dict(item))
+
+    tier2_findings: List[Dict[str, Any]] = [dict(g) for g in gaps if isinstance(g, dict)]
+
+    tier3_findings: List[Dict[str, Any]] = []
+    llm_recommendations: List[str] = []
+    if llm_applied and llm_qa:
+        q_score = llm_qa.get("quality_score")
+        tier3_findings.append(
+            {
+                "issue": "llm_assessment",
+                "quality_score": q_score,
+                "overall_ok": llm_qa.get("overall_ok"),
+                "detail": llm_qa.get("summary") or llm_qa.get("assessment"),
+            }
+        )
+        for raw in llm_qa.get("recommendations") or llm_qa.get("suggestions") or []:
+            s = str(raw or "").strip()
+            if s:
+                llm_recommendations.append(s[:500])
+
+    unfilled = list(roadmap_unfilled or [])
+    if unfilled:
+        for item in unfilled:
+            if isinstance(item, (list, tuple)) and len(item) >= 2:
+                idx, spec = item[0], item[1]
+                tier1_findings.append(
+                    {
+                        "issue": "roadmap_unfilled",
+                        "step_index": int(idx),
+                        "roadmap_major_step_index": getattr(spec, "major_step_index", idx),
+                        "roadmap_learning_goal": getattr(spec, "learning_goal", None),
+                        "reasons": ["Keine passende Übung für Roadmap-Stufe"],
+                    }
+                )
+            elif isinstance(item, dict):
+                tier1_findings.append({**item, "issue": item.get("issue") or "roadmap_unfilled"})
+
+    tiers: List[Dict[str, Any]] = [
+        {
+            "id": "tier1_deterministic",
+            "label": "Deterministische Gates",
+            "finding_count": len(tier1_findings),
+            "findings": tier1_findings[:16],
+        },
+        {
+            "id": "tier2_transitions",
+            "label": "Übergangs-Kohärenz",
+            "finding_count": len(tier2_findings),
+            "findings": tier2_findings[:12],
+        },
+        {
+            "id": "tier3_llm_holistic",
+            "label": "LLM-Ganzpfad",
+            "finding_count": len(tier3_findings),
+            "findings": tier3_findings,
+            "recommendations": llm_recommendations[:8],
+            "applied": bool(llm_applied),
+        },
+    ]
+    optimization_hints = derive_optimization_hints(tiers)
+    for rec in llm_recommendations[:5]:
+        optimization_hints.append(
+            {
+                "tier": "tier3_llm_holistic",
+                "action": "review_roadmap",
+                "issue": "llm_recommendation",
+                "reason": rec,
+            }
+        )
+
+    return {
+        "qa_tiers": tiers,
+        "optimization_hints": optimization_hints[:28],
+        "optimization_hint_count": len(optimization_hints),
+    }
+
+
+__all__ = [
+    "derive_optimization_hints",
+    "run_multistage_path_qa",
+]
diff --git a/backend/planning_progression_roadmap.py b/backend/planning_progression_roadmap.py
index 7881b55..5d95e7f 100644
--- a/backend/planning_progression_roadmap.py
+++ b/backend/planning_progression_roadmap.py
@@ -104,6 +104,10 @@ class RoadmapArtifact(BaseModel):
 class StageSpecArtifact(BaseModel):
     major_step_index: int = Field(ge=0)
     learning_goal: str = ""
+    """Soll-Start dieser Stufe (= Zielzustand der vorherigen Stufe / Pfad-Start)."""
+    start_state: str = ""
+    """Zielzustand dieser Stufe (= Soll für den nächsten Schritt)."""
+    target_state: str = ""
     load_profile: List[str] = Field(default_factory=list)
     exercise_type: str = ""
     success_criteria: List[str] = Field(default_factory=list)
@@ -941,6 +945,8 @@ def roadmap_context_from_override(
                 StageSpecArtifact(
                     major_step_index=i,
                     learning_goal=(spec.learning_goal or majors[i].learning_goal).strip(),
+                    start_state=(spec.start_state or "").strip(),
+                    target_state=(spec.target_state or "").strip(),
                     load_profile=list(spec.load_profile or []),
                     exercise_type=(spec.exercise_type or "").strip(),
                     success_criteria=list(spec.success_criteria or []),
@@ -1004,6 +1010,19 @@ def roadmap_context_from_override(
             semantic_brief=enriched_brief,
         ),
     )
+    from planning_stage_context import derive_stage_specs_transition_states, resolve_path_start_target
+
+    path_start, path_target = resolve_path_start_target(
+        structured=structured,
+        goal_analysis=goal_analysis,
+    )
+    stage_specs = derive_stage_specs_transition_states(
+        stage_specs,
+        majors,
+        path_start=path_start,
+        path_target=path_target,
+        goal_analysis=goal_analysis,
+    )
 
     return ProgressionRoadmapContext(
         goal_query=goal_query.strip(),
@@ -1225,6 +1244,19 @@ def run_progression_roadmap_pipeline(
         intent=intent,
         fallback_specs=heuristic_specs,
     )
+    from planning_stage_context import derive_stage_specs_transition_states, resolve_path_start_target
+
+    path_start, path_target = resolve_path_start_target(
+        structured=resolved,
+        goal_analysis=goal_analysis,
+    )
+    ctx.stage_specs = derive_stage_specs_transition_states(
+        ctx.stage_specs,
+        roadmap.major_steps,
+        path_start=path_start,
+        path_target=path_target,
+        goal_analysis=goal_analysis,
+    )
 
     if ctx.llm_goal_analysis_applied or ctx.llm_roadmap_applied or ctx.llm_stage_spec_applied:
         ctx.pipeline_phase = "roadmap_v1_llm"
diff --git a/backend/planning_stage_context.py b/backend/planning_stage_context.py
new file mode 100644
index 0000000..0ed2aa8
--- /dev/null
+++ b/backend/planning_stage_context.py
@@ -0,0 +1,140 @@
+"""
+Stufen-Kontext im Gesamtziel — Start/Ziel pro Roadmap-Stufe für Matching und QS.
+
+Übertragbar auf Trainingsplanung: Abschnitt-Soll (= Ende Vorabschnitt), Abschnitt-Ziel.
+"""
+from __future__ import annotations
+
+from typing import List, Optional, Sequence
+
+from planning_progression_roadmap import (
+    GoalAnalysisArtifact,
+    MajorStep,
+    RoadmapStructuredInput,
+    StageSpecArtifact,
+)
+
+
+def build_contextualized_stage_goal(
+    *,
+    learning_goal: str,
+    start_state: str = "",
+    target_state: str = "",
+    path_target_state: str = "",
+    path_start_state: str = "",
+    stage_index: int = 0,
+    stage_count: int = 1,
+) -> str:
+    """Stufen-Lernziel eingebettet in Übergang und Gesamtziel (für Brief/Retrieval)."""
+    lg = (learning_goal or "").strip()
+    if not lg:
+        return ""
+
+    parts: List[str] = []
+    start = (start_state or "").strip()
+    target = (target_state or "").strip()
+    path_end = (path_target_state or "").strip()
+    path_begin = (path_start_state or "").strip()
+
+    if start:
+        parts.append(f"Soll-Start: {start[:220]}")
+    elif path_begin and stage_index == 0:
+        parts.append(f"Pfad-Start: {path_begin[:220]}")
+    if target:
+        parts.append(f"Stufen-Ziel: {target[:220]}")
+    parts.append(f"Lernziel: {lg[:280]}")
+    if path_end:
+        if stage_index >= max(0, stage_count - 1):
+            parts.append(f"Gesamtziel: {path_end[:220]}")
+        else:
+            parts.append(f"Gesamtziel (Kontext): {path_end[:180]}")
+
+    return " | ".join(parts)[:900]
+
+
+def derive_stage_specs_transition_states(
+    stage_specs: Sequence[StageSpecArtifact],
+    major_steps: Sequence[MajorStep],
+    *,
+    path_start: str = "",
+    path_target: str = "",
+    goal_analysis: Optional[GoalAnalysisArtifact] = None,
+) -> List[StageSpecArtifact]:
+    """
+    Verkettete Soll-/Zielzustände je Stufe.
+
+    - Stufe 0 start = Pfad-Start
+    - Stufe n start = Zielzustand Stufe n-1 (Ziel des vorherigen Schritts)
+    - Letzte Stufe target = Pfad-Gesamtziel (falls gesetzt)
+    """
+    start_path = (path_start or "").strip()
+    end_path = (path_target or "").strip()
+    if goal_analysis:
+        if not start_path:
+            start_path = (goal_analysis.start_assumption or "").strip()
+        if not end_path:
+            end_path = (goal_analysis.target_state or "").strip()
+
+    by_idx = {int(s.major_step_index): s for s in stage_specs}
+    majors = sorted(major_steps, key=lambda m: m.index)
+    if not majors:
+        return list(stage_specs)
+
+    out: List[StageSpecArtifact] = []
+    prev_target = start_path
+    last_idx = majors[-1].index
+
+    for major in majors:
+        spec = by_idx.get(major.index)
+        if spec is None:
+            spec = StageSpecArtifact(
+                major_step_index=major.index,
+                learning_goal=major.learning_goal,
+            )
+
+        explicit_start = (spec.start_state or "").strip()
+        explicit_target = (spec.target_state or "").strip()
+        stage_start = explicit_start or prev_target or start_path
+        if explicit_target:
+            stage_target = explicit_target
+        elif major.index == last_idx and end_path:
+            stage_target = end_path
+        else:
+            stage_target = (major.learning_goal or spec.learning_goal or "").strip()
+
+        prev_target = stage_target
+        out.append(
+            spec.model_copy(
+                update={
+                    "start_state": (stage_start or "")[:500],
+                    "target_state": (stage_target or "")[:500],
+                }
+            )
+        )
+    return out
+
+
+def resolve_path_start_target(
+    *,
+    structured: Optional[RoadmapStructuredInput] = None,
+    goal_analysis: Optional[GoalAnalysisArtifact] = None,
+) -> tuple[str, str]:
+    """Pfadweiter Start- und Zielzustand für Stufen-Verkettung."""
+    start = ""
+    target = ""
+    if structured:
+        start = (structured.start_situation or "").strip()
+        target = (structured.target_state or "").strip()
+    if goal_analysis:
+        if not start:
+            start = (goal_analysis.start_assumption or "").strip()
+        if not target:
+            target = (goal_analysis.target_state or "").strip()
+    return start, target
+
+
+__all__ = [
+    "build_contextualized_stage_goal",
+    "derive_stage_specs_transition_states",
+    "resolve_path_start_target",
+]
diff --git a/backend/tests/test_planning_roadmap_stage_match.py b/backend/tests/test_planning_roadmap_stage_match.py
index 9077640..0a9f97d 100644
--- a/backend/tests/test_planning_roadmap_stage_match.py
+++ b/backend/tests/test_planning_roadmap_stage_match.py
@@ -5,10 +5,12 @@ from planning_exercise_semantics import (
     enrich_brief_with_path_constraints,
     exercise_passes_stage_learning_goal_gate,
     exercise_passes_stage_fit,
+    exercise_passes_technique_path_scope,
     pick_best_path_hit,
     resolve_path_anti_patterns,
     score_exercise_stage_fit,
     semantic_brief_for_stage,
+    technique_sibling_excludes,
 )
 from planning_exercise_path_qa import strip_off_topic_steps_from_path
 
@@ -247,6 +249,47 @@ def test_pick_best_skips_kumite_for_mawashi_athletic_path():
     assert int(chosen["id"]) == 2
 
 
+def test_technique_scope_rejects_sibling_geri_for_mawashi_path():
+    siblings = technique_sibling_excludes("mawashi geri")
+    assert any("mae" in s for s in siblings)
+    assert not exercise_passes_technique_path_scope(
+        primary_topic="mawashi geri",
+        title="Mae Geri Grundtechnik",
+        summary="Front kick",
+        goal="Präzision Mae Geri",
+        learning_goal="Sprungvorbereitung für Mawashi Geri",
+        sibling_excludes=siblings,
+    )
+    assert exercise_passes_technique_path_scope(
+        primary_topic="mawashi geri",
+        title="Sprungkraft Plyometrie",
+        summary="Absprung",
+        goal="Vorbereitung gesprungener Mawashi Geri",
+        learning_goal="Sprungvorbereitung für Mawashi Geri",
+        sibling_excludes=siblings,
+    )
+
+
+def test_stage_fit_rejects_yoko_geri_on_mawashi_roadmap_stage():
+    brief = build_semantic_brief("gesprungener Mawashi Geri Sprungphase")
+    primary = brief.primary_topic or "mawashi geri"
+    stage_goal = "Koordination Sprungphase Mawashi Geri"
+    stage_brief = build_stage_match_brief(
+        learning_goal=stage_goal,
+        path_primary_topic=primary,
+        path_technique_excludes=technique_sibling_excludes(primary),
+    )
+    assert not exercise_passes_stage_fit(
+        learning_goal=stage_goal,
+        title="Yoko Geri seitlicher Tritt",
+        summary="Seitwärtskick",
+        goal="Yoko Geri Technik",
+        stage_brief=stage_brief,
+        path_primary_topic=primary,
+        path_technique_excludes=technique_sibling_excludes(primary),
+    )
+
+
 def test_strip_off_topic_removes_partial_when_most_steps_bad():
     steps = [{"exercise_id": i, "title": f"E{i}"} for i in range(1, 8)]
     off_topic = [{"step_index": i, "issue": "path_exclude"} for i in range(5)]
diff --git a/backend/tests/test_planning_stage_context.py b/backend/tests/test_planning_stage_context.py
new file mode 100644
index 0000000..dae3fa7
--- /dev/null
+++ b/backend/tests/test_planning_stage_context.py
@@ -0,0 +1,65 @@
+"""Tests Stufen-Kontext (Start/Ziel-Verkettung) und mehrstufige QS."""
+from planning_path_qa_pipeline import derive_optimization_hints, run_multistage_path_qa
+from planning_progression_roadmap import MajorStep, StageSpecArtifact
+from planning_stage_context import (
+    build_contextualized_stage_goal,
+    derive_stage_specs_transition_states,
+)
+
+
+def test_derive_stage_transition_chain():
+    majors = [
+        MajorStep(index=0, phase="grundlage", learning_goal="Stand-Mawashi", consolidates=["m1"]),
+        MajorStep(index=1, phase="vertiefung", learning_goal="Sprungvorbereitung", consolidates=["m2"]),
+        MajorStep(index=2, phase="perfektion", learning_goal="Gesprungener Mawashi", consolidates=["m3"]),
+    ]
+    specs = [
+        StageSpecArtifact(major_step_index=0, learning_goal=majors[0].learning_goal),
+        StageSpecArtifact(major_step_index=1, learning_goal=majors[1].learning_goal),
+        StageSpecArtifact(major_step_index=2, learning_goal=majors[2].learning_goal),
+    ]
+    out = derive_stage_specs_transition_states(
+        specs,
+        majors,
+        path_start="Anfänger mit Grundstellung",
+        path_target="Sauberer gesprungener Mawashi Geri",
+    )
+    assert out[0].start_state == "Anfänger mit Grundstellung"
+    assert out[1].start_state == out[0].target_state
+    assert out[2].target_state == "Sauberer gesprungener Mawashi Geri"
+
+
+def test_contextualized_stage_goal_includes_path_target():
+    text = build_contextualized_stage_goal(
+        learning_goal="Sprungkoordination",
+        start_state="Stand-Mawashi sicher",
+        target_state="Explosiver Absprung",
+        path_target_state="Gesprungener Mawashi Geri",
+        stage_index=1,
+        stage_count=3,
+    )
+    assert "Sprungkoordination" in text
+    assert "Gesamtziel" in text
+    assert "Soll-Start" in text
+
+
+def test_multistage_qa_emits_optimization_hints():
+    result = run_multistage_path_qa(
+        off_topic_steps=[],
+        stripped_off_topic=[
+            {
+                "step_index": 2,
+                "issue": "technique_scope",
+                "title": "Yoko Geri",
+                "reasons": ["Passt nicht zur Haupttechnik"],
+            }
+        ],
+        gaps=[{"from_title": "A", "to_title": "B", "gap_score": 0.6, "is_large_gap": True}],
+        llm_qa={"quality_score": 0.25, "recommendations": ["Athletisches Training ergänzen"]},
+        llm_applied=True,
+    )
+    assert len(result["qa_tiers"]) == 3
+    hints = result["optimization_hints"]
+    assert any(h.get("action") == "rematch_slot" for h in hints)
+    assert any(h.get("action") == "bridge_or_gap_fill" for h in hints)
+    assert derive_optimization_hints(result["qa_tiers"])
diff --git a/backend/version.py b/backend/version.py
index 7d5fe5e..8ec0719 100644
--- a/backend/version.py
+++ b/backend/version.py
@@ -1,8 +1,8 @@
 # Shinkan Jinkendo Version Information
 
-APP_VERSION = "0.8.223"
+APP_VERSION = "0.8.225"
 BUILD_DATE = "2026-06-07"
-DB_SCHEMA_VERSION = "20260607089"
+DB_SCHEMA_VERSION = "20260607090"
 
 MODULE_VERSIONS = {
     "legal_documents": "1.4.0",  # Admin: Live-Vorschau pro Abschnitt + modale Vollvorschau (Editor + Dokumentenliste)
@@ -53,6 +53,22 @@ MODULE_VERSIONS = {
 }
 
 CHANGELOG = [
+    {
+        "version": "0.8.225",
+        "date": "2026-06-07",
+        "changes": [
+            "Stufen start_state/target_state (Soll-Verkettung) + kontextualisiertes Matching.",
+            "Mehrstufige Pfad-QS (tier1–3) mit optimization_hints; Migration 090 Prompt.",
+        ],
+    },
+    {
+        "version": "0.8.224",
+        "date": "2026-06-07",
+        "changes": [
+            "Technik-Pfad-Scope: Geschwister-Techniken (Mae/Yoko bei Mawashi) als hartes Gate in Match/QS.",
+            "path_primary_topic in build_stage_match_brief; Intent technique_sibling_excludes.",
+        ],
+    },
     {
         "version": "0.8.223",
         "date": "2026-06-07",
diff --git a/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md b/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md
index f456456..5b2df2d 100644
--- a/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md
+++ b/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md
@@ -241,6 +241,28 @@ LLM: Migration **089** — Prompts `planning_progression_goal_analysis` + `plann
 
 Matching: `anti_patterns` + `success_criteria` → `build_stage_match_brief` → Retrieval-Gate (Titel + Summary + Goal).
 
+### Stufen im Gesamtziel (`planning_stage_context.py`)
+
+| Feld | Bedeutung |
+|------|-----------|
+| `start_state` | Soll-Start der Stufe (= `target_state` der Vorstufe / Pfad-Start) |
+| `target_state` | Ziel nach dieser Stufe (= Soll für den nächsten Schritt) |
+| `build_contextualized_stage_goal()` | Lernziel + Start + Stufen-Ziel + Gesamtziel → Brief/Retrieval |
+
+Deterministisch: `derive_stage_specs_transition_states()` nach Roadmap-Pipeline; LLM kann Felder überschreiben (Prompt **090**).
+
+### Mehrstufige Pfad-QS (`planning_path_qa_pipeline.py`)
+
+| Stufe | Inhalt | Ableitung |
+|-------|--------|-----------|
+| **tier1** | Deterministische Gates (Technik-Scope, Ausschlüsse, unfilled) | `optimization_hints` → `rematch_slot`, `refine_stage_spec` |
+| **tier2** | Übergangs-Lücken zwischen Schritten | `bridge_or_gap_fill` |
+| **tier3** | LLM-Ganzpfad + Empfehlungen | `review_roadmap` |
+
+API: `path_qa.qa_tiers`, `path_qa.optimization_hints` — **kein** anfrage-spezifischer Patch, sondern strukturierte Rückkopplung. Auto-Rematch-Schleife: Backlog (QS → Aktion → erneutes Match).
+
+Phase G: gleiche Tiers für Abschnitts-QS nach Einheits-Match.
+
 ## 9. Fähigkeiten-Scoring-Anbindung
 
 Modul: `planning_skill_expectations.py`

From 1d94c2ebf136859d1c6e2ce723b02f32b2ef104a Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Thu, 11 Jun 2026 10:30:48 +0200
Subject: [PATCH 20/33] Enhance Roadmap Slot Matching and Off-Topic Detection

- Introduced `auto_rematch_after_qa` parameter in `ProgressionPathSuggestRequest` to enable automatic rematching after quality assurance checks.
- Refactored roadmap slot matching logic to improve clarity and functionality, renaming `_build_steps_roadmap_first` to `_match_roadmap_slot`.
- Added `_with_roadmap_major_index` utility to streamline off-topic step detection by incorporating roadmap major step indices.
- Enhanced off-topic detection logic to utilize the new utility for improved clarity in identifying mismatches and exclusions.
- Incremented application version to reflect these updates.
---
 backend/planning_exercise_path_builder.py   | 377 +++++++++++++-------
 backend/planning_exercise_path_qa.py        |  96 +++--
 backend/planning_path_rematch.py            | 202 +++++++++++
 backend/tests/test_planning_path_rematch.py | 133 +++++++
 4 files changed, 635 insertions(+), 173 deletions(-)
 create mode 100644 backend/planning_path_rematch.py
 create mode 100644 backend/tests/test_planning_path_rematch.py

diff --git a/backend/planning_exercise_path_builder.py b/backend/planning_exercise_path_builder.py
index 9a56cf5..7a9b4c7 100644
--- a/backend/planning_exercise_path_builder.py
+++ b/backend/planning_exercise_path_builder.py
@@ -14,6 +14,7 @@ from pydantic import BaseModel, Field
 from tenant_context import TenantContext, library_content_visibility_sql
 from planning_exercise_profiles import PlanningTargetProfile
 from planning_path_qa_pipeline import run_multistage_path_qa
+from planning_path_rematch import collect_rematch_slot_indices, rematch_roadmap_slots
 from planning_stage_context import build_contextualized_stage_goal, resolve_path_start_target
 from planning_exercise_path_qa import (
     apply_llm_path_reorder,
@@ -97,6 +98,7 @@ class ProgressionPathSuggestRequest(BaseModel):
     max_steps: int = Field(default=5, ge=2, le=10)
     include_llm_intent: bool = True
     include_path_qa: bool = True
+    auto_rematch_after_qa: bool = True
     include_llm_path_qa: bool = True
     include_path_reorder: bool = True
     include_ai_gap_fill: bool = True
@@ -534,6 +536,174 @@ def _annotate_roadmap_step(
     return step
 
 
+def _match_roadmap_slot(
+    cur,
+    *,
+    tenant: TenantContext,
+    body: ProgressionPathSuggestRequest,
+    goal_query: str,
+    max_steps: int,
+    semantic_brief: PlanningSemanticBrief,
+    path_target_profile: PlanningTargetProfile,
+    path_intent: str,
+    roadmap_ctx: ProgressionRoadmapContext,
+    stage_spec: StageSpecArtifact,
+    step_index: int,
+    stage_count: int,
+    planned_ids: List[int],
+    anchor_id: Optional[int],
+    anchor_variant_id: Optional[int],
+    used: Set[int],
+) -> Tuple[Optional[Dict[str, Any]], Optional[StageSpecArtifact]]:
+    """Einzelnen Roadmap-Slot matchen (Initial-Build und Auto-Rematch)."""
+    major_by_index: Dict[int, MajorStep] = {}
+    if roadmap_ctx.roadmap:
+        major_by_index = {m.index: m for m in roadmap_ctx.roadmap.major_steps}
+    major = major_by_index.get(stage_spec.major_step_index)
+
+    ga_dump = (
+        roadmap_ctx.goal_analysis.model_dump() if roadmap_ctx.goal_analysis else None
+    )
+    rs_dump = (
+        roadmap_ctx.resolved_structured.model_dump()
+        if roadmap_ctx.resolved_structured
+        else None
+    )
+    path_start, path_target = resolve_path_start_target(
+        structured=roadmap_ctx.resolved_structured,
+        goal_analysis=roadmap_ctx.goal_analysis,
+    )
+    brief_summary = (
+        roadmap_ctx.semantic_brief
+        if roadmap_ctx.semantic_brief
+        else brief_to_summary_dict(semantic_brief)
+    )
+
+    stage_spec_dict = stage_spec.model_dump()
+    if major:
+        stage_spec_dict["phase"] = major.phase
+    stage_inp = expectation_input_from_progression_stage(
+        goal_query=goal_query,
+        goal_analysis=ga_dump,
+        resolved_structured=rs_dump,
+        stage_spec=stage_spec_dict,
+        semantic_brief_summary=brief_summary,
+        major_step=major.model_dump() if major else None,
+    )
+    stage_exp = build_planning_skill_expectations(cur, stage_inp, semantic_brief=semantic_brief)
+    step_target = apply_expectations_to_target(path_target_profile, stage_exp)
+    skill_exp_api = stage_exp.to_api_dict() if stage_exp.items else None
+
+    step_query = stage_spec_retrieval_query(
+        semantic_brief=semantic_brief,
+        goal_query=goal_query,
+        stage_spec=stage_spec,
+        major_step=major,
+    )
+    step_kind = resolve_step_exercise_kind_filter(stage_spec, body.exercise_kind_any)
+    stage_goal = (stage_spec.learning_goal or "").strip()
+    stage_start = (stage_spec.start_state or "").strip()
+    stage_target = (stage_spec.target_state or "").strip()
+    contextual_goal = build_contextualized_stage_goal(
+        learning_goal=stage_goal,
+        start_state=stage_start,
+        target_state=stage_target,
+        path_target_state=path_target,
+        path_start_state=path_start,
+        stage_index=step_index,
+        stage_count=stage_count,
+    )
+    path_context_note = None
+    if rs_dump:
+        ctx_parts = [
+            str(rs_dump.get("start_situation") or "").strip()[:120],
+            str(rs_dump.get("target_state") or "").strip()[:120],
+            str(rs_dump.get("roadmap_notes") or "").strip()[:120],
+        ]
+        path_context_note = " ".join(p for p in ctx_parts if p)[:240] or None
+    path_anti = resolve_path_anti_patterns(
+        goal_query,
+        semantic_brief=semantic_brief,
+        extra_context=path_context_note,
+    )
+    stage_anti = list(dict.fromkeys([*(stage_spec.anti_patterns or []), *path_anti]))
+    path_primary = (semantic_brief.primary_topic or "").strip()
+    path_tech_excludes = list(semantic_brief.exclude_phrases or [])
+    if semantic_brief.topic_type == "technique" and path_primary:
+        from planning_exercise_semantics import technique_sibling_excludes
+
+        for item in technique_sibling_excludes(path_primary):
+            if item not in path_tech_excludes:
+                path_tech_excludes.append(item)
+    stage_match_brief = build_stage_match_brief(
+        learning_goal=stage_goal,
+        anti_patterns=stage_anti,
+        success_criteria=list(stage_spec.success_criteria or []),
+        load_profile=list(stage_spec.load_profile or []),
+        phase=major.phase if major else None,
+        path_context_note=path_context_note,
+        path_anti_patterns=path_anti,
+        path_primary_topic=path_primary or None,
+        path_technique_excludes=path_tech_excludes or None,
+        stage_start_state=stage_start or None,
+        stage_target_state=stage_target or None,
+        path_target_state=path_target or None,
+        contextualized_learning_goal=contextual_goal or None,
+    )
+
+    hits, _, _, _ = _run_path_step_retrieval(
+        cur,
+        tenant=tenant,
+        goal_query=goal_query,
+        step_index=step_index,
+        max_steps=max_steps,
+        planned_ids=planned_ids,
+        anchor_id=anchor_id,
+        anchor_variant_id=anchor_variant_id,
+        progression_graph_id=body.progression_graph_id,
+        include_llm_intent=body.include_llm_intent and step_index == 0,
+        exercise_kind_any=step_kind,
+        semantic_brief=stage_match_brief,
+        path_target_profile=path_target_profile,
+        path_intent=path_intent,
+        step_query_override=step_query,
+        step_phase_override=major.phase if major else None,
+        step_target_profile_override=step_target,
+        stage_learning_goal=stage_goal or None,
+        stage_anti_patterns=stage_anti or None,
+        stage_match_brief=stage_match_brief,
+        stage_success_criteria=list(stage_spec.success_criteria or []),
+        stage_load_profile=list(stage_spec.load_profile or []),
+        path_context_note=path_context_note,
+        path_primary_topic=path_primary or None,
+        path_technique_excludes=path_tech_excludes or None,
+    )
+
+    hit = _pick_best_path_hit(
+        hits,
+        used,
+        semantic_brief=stage_match_brief,
+        stage_learning_goal=stage_goal or None,
+        stage_anti_patterns=stage_anti or None,
+        roadmap_stage_match=True,
+        stage_match_brief=stage_match_brief,
+        path_primary_topic=path_primary or None,
+        path_technique_excludes=path_tech_excludes or None,
+    )
+
+    if not hit:
+        return None, stage_spec
+
+    step = _annotate_roadmap_step(
+        _hit_to_path_step(hit),
+        stage_spec=stage_spec,
+        major_step=major,
+        skill_expectations=skill_exp_api,
+        anti_patterns_override=stage_anti,
+    )
+    return step, None
+
+
 def _build_steps_roadmap_first(
     cur,
     *,
@@ -557,161 +727,37 @@ def _build_steps_roadmap_first(
             for m in roadmap_ctx.roadmap.major_steps[:max_steps]
         ]
 
-    major_by_index: Dict[int, MajorStep] = {}
-    if roadmap_ctx.roadmap:
-        major_by_index = {m.index: m for m in roadmap_ctx.roadmap.major_steps}
-
     used: Set[int] = set()
     steps: List[Dict[str, Any]] = []
     planned_ids: List[int] = []
     anchor_id: Optional[int] = None
     anchor_variant_id: Optional[int] = None
     unfilled: List[Tuple[int, StageSpecArtifact]] = []
-
-    ga_dump = (
-        roadmap_ctx.goal_analysis.model_dump() if roadmap_ctx.goal_analysis else None
-    )
-    rs_dump = (
-        roadmap_ctx.resolved_structured.model_dump()
-        if roadmap_ctx.resolved_structured
-        else None
-    )
-    path_start, path_target = resolve_path_start_target(
-        structured=roadmap_ctx.resolved_structured,
-        goal_analysis=roadmap_ctx.goal_analysis,
-    )
     stage_count = len(stage_specs)
-    brief_summary = (
-        roadmap_ctx.semantic_brief
-        if roadmap_ctx.semantic_brief
-        else brief_to_summary_dict(semantic_brief)
-    )
 
     for step_index, stage_spec in enumerate(stage_specs):
-        major = major_by_index.get(stage_spec.major_step_index)
-        stage_spec_dict = stage_spec.model_dump()
-        if major:
-            stage_spec_dict["phase"] = major.phase
-        stage_inp = expectation_input_from_progression_stage(
-            goal_query=goal_query,
-            goal_analysis=ga_dump,
-            resolved_structured=rs_dump,
-            stage_spec=stage_spec_dict,
-            semantic_brief_summary=brief_summary,
-            major_step=major.model_dump() if major else None,
-        )
-        stage_exp = build_planning_skill_expectations(cur, stage_inp, semantic_brief=semantic_brief)
-        step_target = apply_expectations_to_target(path_target_profile, stage_exp)
-        skill_exp_api = stage_exp.to_api_dict() if stage_exp.items else None
-
-        step_query = stage_spec_retrieval_query(
-            semantic_brief=semantic_brief,
-            goal_query=goal_query,
-            stage_spec=stage_spec,
-            major_step=major,
-        )
-        step_kind = resolve_step_exercise_kind_filter(stage_spec, body.exercise_kind_any)
-        stage_goal = (stage_spec.learning_goal or "").strip()
-        stage_start = (stage_spec.start_state or "").strip()
-        stage_target = (stage_spec.target_state or "").strip()
-        contextual_goal = build_contextualized_stage_goal(
-            learning_goal=stage_goal,
-            start_state=stage_start,
-            target_state=stage_target,
-            path_target_state=path_target,
-            path_start_state=path_start,
-            stage_index=step_index,
-            stage_count=stage_count,
-        )
-        path_context_note = None
-        if rs_dump:
-            ctx_parts = [
-                str(rs_dump.get("start_situation") or "").strip()[:120],
-                str(rs_dump.get("target_state") or "").strip()[:120],
-                str(rs_dump.get("roadmap_notes") or "").strip()[:120],
-            ]
-            path_context_note = " ".join(p for p in ctx_parts if p)[:240] or None
-        path_anti = resolve_path_anti_patterns(
-            goal_query,
-            semantic_brief=semantic_brief,
-            extra_context=path_context_note,
-        )
-        stage_anti = list(dict.fromkeys([*(stage_spec.anti_patterns or []), *path_anti]))
-        path_primary = (semantic_brief.primary_topic or "").strip()
-        path_tech_excludes = list(semantic_brief.exclude_phrases or [])
-        if semantic_brief.topic_type == "technique" and path_primary:
-            from planning_exercise_semantics import technique_sibling_excludes
-
-            for item in technique_sibling_excludes(path_primary):
-                if item not in path_tech_excludes:
-                    path_tech_excludes.append(item)
-        stage_match_brief = build_stage_match_brief(
-            learning_goal=stage_goal,
-            anti_patterns=stage_anti,
-            success_criteria=list(stage_spec.success_criteria or []),
-            load_profile=list(stage_spec.load_profile or []),
-            phase=major.phase if major else None,
-            path_context_note=path_context_note,
-            path_anti_patterns=path_anti,
-            path_primary_topic=path_primary or None,
-            path_technique_excludes=path_tech_excludes or None,
-            stage_start_state=stage_start or None,
-            stage_target_state=stage_target or None,
-            path_target_state=path_target or None,
-            contextualized_learning_goal=contextual_goal or None,
-        )
-
-        hits, _, _, _ = _run_path_step_retrieval(
+        step, unfilled_spec = _match_roadmap_slot(
             cur,
             tenant=tenant,
+            body=body,
             goal_query=goal_query,
-            step_index=step_index,
             max_steps=max_steps,
+            semantic_brief=semantic_brief,
+            path_target_profile=path_target_profile,
+            path_intent=path_intent,
+            roadmap_ctx=roadmap_ctx,
+            stage_spec=stage_spec,
+            step_index=step_index,
+            stage_count=stage_count,
             planned_ids=planned_ids,
             anchor_id=anchor_id,
             anchor_variant_id=anchor_variant_id,
-            progression_graph_id=body.progression_graph_id,
-            include_llm_intent=body.include_llm_intent and step_index == 0,
-            exercise_kind_any=step_kind,
-            semantic_brief=stage_match_brief,
-            path_target_profile=path_target_profile,
-            path_intent=path_intent,
-            step_query_override=step_query,
-            step_phase_override=major.phase if major else None,
-            step_target_profile_override=step_target,
-            stage_learning_goal=stage_goal or None,
-            stage_anti_patterns=stage_anti or None,
-            stage_match_brief=stage_match_brief,
-            stage_success_criteria=list(stage_spec.success_criteria or []),
-            stage_load_profile=list(stage_spec.load_profile or []),
-            path_context_note=path_context_note,
-            path_primary_topic=path_primary or None,
-            path_technique_excludes=path_tech_excludes or None,
+            used=used,
         )
-
-        hit = _pick_best_path_hit(
-            hits,
-            used,
-            semantic_brief=stage_match_brief,
-            stage_learning_goal=stage_goal or None,
-            stage_anti_patterns=stage_anti or None,
-            roadmap_stage_match=True,
-            stage_match_brief=stage_match_brief,
-            path_primary_topic=path_primary or None,
-            path_technique_excludes=path_tech_excludes or None,
-        )
-
-        if not hit:
-            unfilled.append((step_index, stage_spec))
+        if not step:
+            unfilled.append((step_index, unfilled_spec or stage_spec))
             continue
 
-        step = _annotate_roadmap_step(
-            _hit_to_path_step(hit),
-            stage_spec=stage_spec,
-            major_step=major,
-            skill_expectations=skill_exp_api,
-            anti_patterns_override=stage_anti,
-        )
         steps.append(step)
         eid = int(step["exercise_id"])
         used.add(eid)
@@ -1245,6 +1291,8 @@ def suggest_progression_path(
     gap_fill_offers: List[Dict[str, Any]] = []
     off_topic_steps: List[Dict[str, Any]] = []
     stripped_off_topic: List[Dict[str, Any]] = []
+    rematch_log: List[Dict[str, Any]] = []
+    rematch_rounds = 0
     llm_qa: Optional[Dict[str, Any]] = None
     llm_qa_applied = False
     reorder_applied = False
@@ -1315,6 +1363,7 @@ def suggest_progression_path(
             brief=semantic_brief,
             goal_query=goal_query,
         )
+        off_topic_before_strip = list(off_topic_steps)
         steps, stripped_off_topic = strip_off_topic_steps_from_path(steps, off_topic_steps)
         if stripped_off_topic:
             off_topic_steps = []
@@ -1325,6 +1374,56 @@ def suggest_progression_path(
                 roadmap_first=roadmap_first,
             )
 
+        if (
+            roadmap_first
+            and body.auto_rematch_after_qa
+            and roadmap_ctx is not None
+            and roadmap_ctx.stage_specs
+        ):
+            slot_indices, rematch_reasons = collect_rematch_slot_indices(
+                stripped_off_topic=stripped_off_topic,
+                off_topic_steps=off_topic_before_strip if not stripped_off_topic else [],
+                optimization_hints=[],
+                stage_specs=roadmap_ctx.stage_specs,
+            )
+            if slot_indices:
+                steps, rematch_log, rematch_new_unfilled = rematch_roadmap_slots(
+                    cur,
+                    tenant=tenant,
+                    body=body,
+                    goal_query=goal_query,
+                    max_steps=max_steps,
+                    semantic_brief=semantic_brief,
+                    path_target_profile=path_target_profile,
+                    path_intent=path_intent,
+                    roadmap_ctx=roadmap_ctx,
+                    steps=steps,
+                    slot_indices=slot_indices,
+                    rematch_reasons=rematch_reasons,
+                    match_slot_fn=_match_roadmap_slot,
+                )
+                rematch_rounds = 1
+                if rematch_new_unfilled:
+                    remapped = {sp.major_step_index for _, sp in rematch_new_unfilled}
+                    roadmap_unfilled = [
+                        item
+                        for item in roadmap_unfilled
+                        if item[1].major_step_index not in remapped
+                    ]
+                    roadmap_unfilled.extend(rematch_new_unfilled)
+                off_topic_steps = detect_off_topic_steps(
+                    cur,
+                    steps,
+                    brief=semantic_brief,
+                    goal_query=goal_query,
+                )
+                gaps = detect_path_gaps(
+                    cur,
+                    steps,
+                    brief=semantic_brief,
+                    roadmap_first=roadmap_first,
+                )
+
         llm_gap_specs = parse_llm_suggested_new_exercises(
             llm_qa,
             brief=semantic_brief,
@@ -1396,6 +1495,10 @@ def suggest_progression_path(
         roadmap_qa_mode=roadmap_qa_mode,
         multistage_qa=multistage_qa,
     )
+    if rematch_log:
+        path_qa["rematch_applied"] = True
+        path_qa["rematch_log"] = rematch_log
+        path_qa["rematch_rounds"] = rematch_rounds
 
     target_profile_summary = path_target_profile.to_summary_dict(cur)
     retrieval_parts = ["profile_v1", "full_library", "path_builder", "semantics"]
@@ -1419,6 +1522,8 @@ def suggest_progression_path(
         retrieval_parts.append("roadmap_edited")
     if roadmap_unfilled:
         retrieval_parts.append("roadmap_unfilled")
+    if rematch_log:
+        retrieval_parts.append("path_rematch")
 
     return {
         "goal_query": goal_query,
diff --git a/backend/planning_exercise_path_qa.py b/backend/planning_exercise_path_qa.py
index 4ce77ba..8b833a4 100644
--- a/backend/planning_exercise_path_qa.py
+++ b/backend/planning_exercise_path_qa.py
@@ -398,6 +398,16 @@ def apply_llm_path_reorder(
 _OFF_TOPIC_SEMANTIC_MAX = 0.10
 
 
+def _with_roadmap_major_index(
+    step: Mapping[str, Any],
+    entry: Dict[str, Any],
+) -> Dict[str, Any]:
+    midx = step.get("roadmap_major_step_index")
+    if midx is not None:
+        entry["roadmap_major_step_index"] = int(midx)
+    return entry
+
+
 def detect_off_topic_steps(
     cur,
     steps: Sequence[Mapping[str, Any]],
@@ -425,15 +435,18 @@ def detect_off_topic_steps(
         step_anti = list(step.get("roadmap_anti_patterns") or []) + path_anti
         if step_anti and _blob_matches_stage_excludes(blob, step_anti):
             off_topic.append(
-                {
-                    "step_index": idx,
-                    "exercise_id": int(step["exercise_id"]),
-                    "title": step.get("title") or bundle["title"],
-                    "semantic_score": 0.0,
-                    "expected_phase": (step.get("roadmap_phase") or "").strip().lower() or None,
-                    "issue": "path_exclude",
-                    "reasons": ["Widerspricht Pfad-Ausschlüssen (z. B. Kumite)"],
-                }
+                _with_roadmap_major_index(
+                    step,
+                    {
+                        "step_index": idx,
+                        "exercise_id": int(step["exercise_id"]),
+                        "title": step.get("title") or bundle["title"],
+                        "semantic_score": 0.0,
+                        "expected_phase": (step.get("roadmap_phase") or "").strip().lower() or None,
+                        "issue": "path_exclude",
+                        "reasons": ["Widerspricht Pfad-Ausschlüssen (z. B. Kumite)"],
+                    },
+                )
             )
             continue
         primary = (brief.primary_topic or "").strip()
@@ -450,15 +463,18 @@ def detect_off_topic_steps(
                 relaxed=False,
             ):
                 off_topic.append(
-                    {
-                        "step_index": idx,
-                        "exercise_id": int(step["exercise_id"]),
-                        "title": step.get("title") or bundle["title"],
-                        "semantic_score": 0.0,
-                        "expected_phase": (step.get("roadmap_phase") or "").strip().lower() or None,
-                        "issue": "technique_scope",
-                        "reasons": [f"Passt nicht zur Haupttechnik „{primary}“"],
-                    }
+                    _with_roadmap_major_index(
+                        step,
+                        {
+                            "step_index": idx,
+                            "exercise_id": int(step["exercise_id"]),
+                            "title": step.get("title") or bundle["title"],
+                            "semantic_score": 0.0,
+                            "expected_phase": (step.get("roadmap_phase") or "").strip().lower() or None,
+                            "issue": "technique_scope",
+                            "reasons": [f"Passt nicht zur Haupttechnik „{primary}“"],
+                        },
+                    )
                 )
                 continue
         stage_goal = (step.get("roadmap_learning_goal") or "").strip()
@@ -488,16 +504,19 @@ def detect_off_topic_steps(
             anti_patterns=stage_anti or None,
         ):
             off_topic.append(
-                {
-                    "step_index": idx,
-                    "exercise_id": int(step["exercise_id"]),
-                    "title": step.get("title") or bundle["title"],
-                    "semantic_score": round(sem, 4),
-                    "expected_phase": phase,
-                    "issue": "stage_mismatch",
-                    "roadmap_learning_goal": stage_goal,
-                    "reasons": sem_reasons[:3],
-                }
+                _with_roadmap_major_index(
+                    step,
+                    {
+                        "step_index": idx,
+                        "exercise_id": int(step["exercise_id"]),
+                        "title": step.get("title") or bundle["title"],
+                        "semantic_score": round(sem, 4),
+                        "expected_phase": phase,
+                        "issue": "stage_mismatch",
+                        "roadmap_learning_goal": stage_goal,
+                        "reasons": sem_reasons[:3],
+                    },
+                )
             )
             continue
         if exercise_passes_path_semantic_gate(
@@ -512,15 +531,18 @@ def detect_off_topic_steps(
         if sem > _OFF_TOPIC_SEMANTIC_MAX:
             continue
         off_topic.append(
-            {
-                "step_index": idx,
-                "exercise_id": int(step["exercise_id"]),
-                "title": step.get("title") or bundle["title"],
-                "semantic_score": round(sem, 4),
-                "expected_phase": phase,
-                "issue": "off_topic",
-                "reasons": sem_reasons[:3],
-            }
+            _with_roadmap_major_index(
+                step,
+                {
+                    "step_index": idx,
+                    "exercise_id": int(step["exercise_id"]),
+                    "title": step.get("title") or bundle["title"],
+                    "semantic_score": round(sem, 4),
+                    "expected_phase": phase,
+                    "issue": "off_topic",
+                    "reasons": sem_reasons[:3],
+                },
+            )
         )
     return off_topic
 
diff --git a/backend/planning_path_rematch.py b/backend/planning_path_rematch.py
new file mode 100644
index 0000000..1faeba8
--- /dev/null
+++ b/backend/planning_path_rematch.py
@@ -0,0 +1,202 @@
+"""
+Auto-Rematch nach Pfad-QS — betroffene Roadmap-Slots erneut matchen (Phase A).
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Set, Tuple
+
+from planning_progression_roadmap import ProgressionRoadmapContext, StageSpecArtifact
+
+
+def collect_rematch_slot_indices(
+    *,
+    stripped_off_topic: Sequence[Mapping[str, Any]],
+    off_topic_steps: Sequence[Mapping[str, Any]],
+    optimization_hints: Sequence[Mapping[str, Any]],
+    stage_specs: Sequence[StageSpecArtifact],
+) -> Tuple[Set[int], Dict[int, str]]:
+    """Major-Step-Indizes für rematch_slot + Begründung pro Slot."""
+    spec_by_pos = list(stage_specs)
+    indices: Set[int] = set()
+    reasons: Dict[int, str] = {}
+
+    def _register(midx: int, reason: str) -> None:
+        indices.add(int(midx))
+        if midx not in reasons and reason:
+            reasons[int(midx)] = reason[:400]
+
+    def _resolve_major(item: Mapping[str, Any]) -> Optional[int]:
+        raw = item.get("roadmap_major_step_index")
+        if raw is not None:
+            return int(raw)
+        si = item.get("step_index")
+        if si is not None:
+            pos = int(si)
+            if 0 <= pos < len(spec_by_pos):
+                return int(spec_by_pos[pos].major_step_index)
+        return None
+
+    for item in stripped_off_topic or []:
+        if not isinstance(item, dict):
+            continue
+        midx = _resolve_major(item)
+        if midx is not None:
+            issue = str(item.get("issue") or "stripped_off_topic")
+            r = (item.get("reasons") or [issue])[0] if item.get("reasons") else issue
+            _register(midx, str(r))
+
+    for item in off_topic_steps or []:
+        if not isinstance(item, dict):
+            continue
+        midx = _resolve_major(item)
+        if midx is None:
+            continue
+        issue = str(item.get("issue") or "off_topic")
+        r = (item.get("reasons") or [issue])[0] if item.get("reasons") else issue
+        _register(midx, str(r))
+
+    for hint in optimization_hints or []:
+        if not isinstance(hint, dict):
+            continue
+        if str(hint.get("action") or "") != "rematch_slot":
+            continue
+        midx = _resolve_major(hint)
+        if midx is not None:
+            _register(midx, str(hint.get("reason") or hint.get("issue") or "rematch_slot"))
+
+    return indices, reasons
+
+
+def _context_before_major(
+    steps_by_major: Mapping[int, Mapping[str, Any]],
+    target_major: int,
+) -> Tuple[List[int], Optional[int], Optional[int]]:
+    planned: List[int] = []
+    anchor: Optional[int] = None
+    anchor_vid: Optional[int] = None
+    for midx in sorted(steps_by_major):
+        if midx >= target_major:
+            break
+        step = steps_by_major[midx]
+        eid = step.get("exercise_id")
+        if eid is not None:
+            planned.append(int(eid))
+            anchor = int(eid)
+            vid = step.get("variant_id")
+            anchor_vid = int(vid) if vid is not None else None
+    return planned, anchor, anchor_vid
+
+
+def rematch_roadmap_slots(
+    cur,
+    *,
+    tenant,
+    body,
+    goal_query: str,
+    max_steps: int,
+    semantic_brief,
+    path_target_profile,
+    path_intent: str,
+    roadmap_ctx: ProgressionRoadmapContext,
+    steps: Sequence[Mapping[str, Any]],
+    slot_indices: Set[int],
+    rematch_reasons: Mapping[int, str],
+    match_slot_fn,
+) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]], List[Tuple[int, StageSpecArtifact]]]:
+    """
+    Ersetzt nur betroffene Slots; andere Schritte und used-Set bleiben konsistent.
+
+    match_slot_fn: _match_roadmap_slot aus path_builder (Injection gegen Zirkularität).
+    """
+    stage_specs = list(roadmap_ctx.stage_specs or [])[:max_steps]
+    if not stage_specs or not slot_indices:
+        return list(steps), [], []
+
+    spec_by_major = {int(s.major_step_index): s for s in stage_specs}
+    steps_by_major: Dict[int, Dict[str, Any]] = {}
+    for raw in steps:
+        step = dict(raw)
+        midx = step.get("roadmap_major_step_index")
+        if midx is not None:
+            steps_by_major[int(midx)] = step
+
+    rematch_log: List[Dict[str, Any]] = []
+    new_unfilled: List[Tuple[int, StageSpecArtifact]] = []
+
+    for major_idx in sorted(slot_indices):
+        stage_spec = spec_by_major.get(int(major_idx))
+        if stage_spec is None:
+            continue
+        step_index = next(
+            (i for i, sp in enumerate(stage_specs) if int(sp.major_step_index) == int(major_idx)),
+            major_idx,
+        )
+        old = steps_by_major.pop(int(major_idx), None)
+        used = {
+            int(s["exercise_id"])
+            for m, s in steps_by_major.items()
+            if s.get("exercise_id") is not None
+        }
+        planned_ids, anchor_id, anchor_variant_id = _context_before_major(
+            steps_by_major, int(major_idx)
+        )
+
+        new_step, unfilled_spec = match_slot_fn(
+            cur,
+            tenant=tenant,
+            body=body,
+            goal_query=goal_query,
+            max_steps=max_steps,
+            semantic_brief=semantic_brief,
+            path_target_profile=path_target_profile,
+            path_intent=path_intent,
+            roadmap_ctx=roadmap_ctx,
+            stage_spec=stage_spec,
+            step_index=step_index,
+            stage_count=len(stage_specs),
+            planned_ids=planned_ids,
+            anchor_id=anchor_id,
+            anchor_variant_id=anchor_variant_id,
+            used=used,
+        )
+
+        reason = str(rematch_reasons.get(int(major_idx)) or "rematch_slot")
+        if new_step:
+            steps_by_major[int(major_idx)] = new_step
+            rematch_log.append(
+                {
+                    "roadmap_major_step_index": int(major_idx),
+                    "action": "replaced",
+                    "reason": reason,
+                    "replaced_exercise_id": old.get("exercise_id") if old else None,
+                    "replaced_title": old.get("title") if old else None,
+                    "new_exercise_id": new_step.get("exercise_id"),
+                    "new_title": new_step.get("title"),
+                }
+            )
+        else:
+            if unfilled_spec is not None:
+                new_unfilled.append((step_index, unfilled_spec))
+            rematch_log.append(
+                {
+                    "roadmap_major_step_index": int(major_idx),
+                    "action": "rematch_unfilled",
+                    "reason": reason,
+                    "replaced_exercise_id": old.get("exercise_id") if old else None,
+                    "replaced_title": old.get("title") if old else None,
+                }
+            )
+
+    ordered: List[Dict[str, Any]] = []
+    for spec in sorted(stage_specs, key=lambda s: s.major_step_index):
+        midx = int(spec.major_step_index)
+        if midx in steps_by_major:
+            ordered.append(steps_by_major[midx])
+
+    return ordered, rematch_log, new_unfilled
+
+
+__all__ = [
+    "collect_rematch_slot_indices",
+    "rematch_roadmap_slots",
+]
diff --git a/backend/tests/test_planning_path_rematch.py b/backend/tests/test_planning_path_rematch.py
new file mode 100644
index 0000000..fbacba9
--- /dev/null
+++ b/backend/tests/test_planning_path_rematch.py
@@ -0,0 +1,133 @@
+"""Tests Auto-Rematch nach Pfad-QS (Phase A)."""
+from planning_path_rematch import collect_rematch_slot_indices, rematch_roadmap_slots
+from planning_progression_roadmap import ProgressionRoadmapContext, StageSpecArtifact
+
+
+def _stage_specs():
+    return [
+        StageSpecArtifact(major_step_index=0, learning_goal="Grundlage"),
+        StageSpecArtifact(major_step_index=1, learning_goal="Vertiefung"),
+        StageSpecArtifact(major_step_index=2, learning_goal="Anwendung"),
+    ]
+
+
+def test_collect_rematch_slot_indices_from_stripped_with_major_index():
+    specs = _stage_specs()
+    stripped = [
+        {
+            "step_index": 1,
+            "roadmap_major_step_index": 1,
+            "issue": "technique_scope",
+            "reasons": ["Passt nicht zur Haupttechnik"],
+        }
+    ]
+    indices, reasons = collect_rematch_slot_indices(
+        stripped_off_topic=stripped,
+        off_topic_steps=[],
+        optimization_hints=[],
+        stage_specs=specs,
+    )
+    assert indices == {1}
+    assert "Haupttechnik" in reasons[1]
+
+
+def test_collect_rematch_slot_indices_resolves_step_index_to_major():
+    specs = _stage_specs()
+    off_topic = [
+        {
+            "step_index": 2,
+            "issue": "stage_mismatch",
+            "reasons": ["Ziel passt nicht"],
+        }
+    ]
+    indices, reasons = collect_rematch_slot_indices(
+        stripped_off_topic=[],
+        off_topic_steps=off_topic,
+        optimization_hints=[],
+        stage_specs=specs,
+    )
+    assert indices == {2}
+    assert reasons[2] == "Ziel passt nicht"
+
+
+def test_collect_rematch_slot_indices_from_optimization_hints():
+    specs = _stage_specs()
+    hints = [
+        {
+            "action": "rematch_slot",
+            "roadmap_major_step_index": 0,
+            "reason": "QS-Tier-1",
+        }
+    ]
+    indices, _ = collect_rematch_slot_indices(
+        stripped_off_topic=[],
+        off_topic_steps=[],
+        optimization_hints=hints,
+        stage_specs=specs,
+    )
+    assert indices == {0}
+
+
+def test_rematch_roadmap_slots_replaces_only_target_slot():
+    specs = _stage_specs()
+    ctx = ProgressionRoadmapContext(
+        goal_query="Mawashi Geri",
+        max_steps=3,
+        stage_specs=specs,
+    )
+    steps = [
+        {
+            "exercise_id": 10,
+            "title": "Slot 0 OK",
+            "roadmap_major_step_index": 0,
+        },
+        {
+            "exercise_id": 20,
+            "title": "Mae Geri falsch",
+            "roadmap_major_step_index": 1,
+        },
+        {
+            "exercise_id": 30,
+            "title": "Slot 2 OK",
+            "roadmap_major_step_index": 2,
+        },
+    ]
+
+    def _fake_match(cur, *, stage_spec, used, **kwargs):
+        assert stage_spec.major_step_index == 1
+        assert 20 not in used
+        assert 10 in used
+        return (
+            {
+                "exercise_id": 21,
+                "title": "Sprungkraft Mawashi",
+                "roadmap_major_step_index": 1,
+            },
+            None,
+        )
+
+    ordered, log, unfilled = rematch_roadmap_slots(
+        None,
+        tenant=None,
+        body=None,
+        goal_query="Mawashi Geri",
+        max_steps=3,
+        semantic_brief=None,
+        path_target_profile=None,
+        path_intent="",
+        roadmap_ctx=ctx,
+        steps=steps,
+        slot_indices={1},
+        rematch_reasons={1: "technique_scope"},
+        match_slot_fn=_fake_match,
+    )
+
+    assert len(ordered) == 3
+    assert ordered[0]["exercise_id"] == 10
+    assert ordered[1]["exercise_id"] == 21
+    assert ordered[2]["exercise_id"] == 30
+    assert len(log) == 1
+    assert log[0]["action"] == "replaced"
+    assert log[0]["replaced_exercise_id"] == 20
+    assert log[0]["new_exercise_id"] == 21
+    assert not unfilled

From 713a344d170f309bfd8083f9843a9cf908e76da2 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Thu, 11 Jun 2026 10:40:25 +0200
Subject: [PATCH 21/33] Enhance Roadmap Step Handling and Off-Topic Logic

- Improved off-topic step handling by incorporating roadmap major step indices for better indexing and detection.
- Refactored `collect_gap_fill_specs` to streamline the insertion logic for off-topic steps, ensuring correct placement based on major step indices.
- Introduced `_normalize_roadmap_steps_coverage` function to standardize roadmap steps coverage, enhancing the handling of missing slots.
- Added `prune_stripped_after_rematch` function to clean up stripped off-topic steps after rematching, improving the overall rematching process.
- Updated tests to validate new rematching and off-topic handling features, ensuring robustness against edge cases.
- Incremented application version to reflect these updates.
---
 backend/planning_exercise_path_ai_fill.py     |  26 ++-
 backend/planning_exercise_path_builder.py     | 203 ++++++++++++++----
 backend/planning_exercise_path_qa.py          |   9 +-
 backend/planning_path_rematch.py              |  30 +++
 backend/tests/test_planning_path_rematch.py   |  41 +++-
 .../ExerciseProgressionPathBuilder.jsx        |   5 +-
 frontend/src/utils/progressionGraphDraft.js   |   8 +
 7 files changed, 269 insertions(+), 53 deletions(-)

diff --git a/backend/planning_exercise_path_ai_fill.py b/backend/planning_exercise_path_ai_fill.py
index ef1f5bf..c33a5bc 100644
--- a/backend/planning_exercise_path_ai_fill.py
+++ b/backend/planning_exercise_path_ai_fill.py
@@ -363,15 +363,35 @@ def collect_gap_fill_specs(
         )
 
     for ot in off_topic_steps:
-        idx = int(ot.get("step_index") or 0)
-        if idx <= 0 or idx >= len(steps) - 1:
+        major_idx = ot.get("roadmap_major_step_index")
+        idx: Optional[int] = None
+        if major_idx is not None:
+            try:
+                mi = int(major_idx)
+            except (TypeError, ValueError):
+                mi = None
+            if mi is not None:
+                idx = next(
+                    (
+                        i
+                        for i, s in enumerate(steps)
+                        if s.get("roadmap_major_step_index") is not None
+                        and int(s["roadmap_major_step_index"]) == mi
+                    ),
+                    None,
+                )
+        if idx is None:
+            idx = int(ot.get("step_index") or 0)
+        if idx < 0 or idx >= len(steps):
             continue
         phase = ot.get("expected_phase") or "vertiefung"
+        insert_after = max(idx - 1, -1)
         add(
             {
                 "source": "off_topic",
-                "insert_after_index": idx - 1,
+                "insert_after_index": insert_after,
                 "replace_step_index": idx,
+                "roadmap_major_step_index": major_idx,
                 "gap": {
                     "expected_phase": phase,
                     "off_topic_title": ot.get("title"),
diff --git a/backend/planning_exercise_path_builder.py b/backend/planning_exercise_path_builder.py
index 7a9b4c7..7973571 100644
--- a/backend/planning_exercise_path_builder.py
+++ b/backend/planning_exercise_path_builder.py
@@ -14,7 +14,11 @@ from pydantic import BaseModel, Field
 from tenant_context import TenantContext, library_content_visibility_sql
 from planning_exercise_profiles import PlanningTargetProfile
 from planning_path_qa_pipeline import run_multistage_path_qa
-from planning_path_rematch import collect_rematch_slot_indices, rematch_roadmap_slots
+from planning_path_rematch import (
+    collect_rematch_slot_indices,
+    prune_stripped_after_rematch,
+    rematch_roadmap_slots,
+)
 from planning_stage_context import build_contextualized_stage_goal, resolve_path_start_target
 from planning_exercise_path_qa import (
     apply_llm_path_reorder,
@@ -704,6 +708,129 @@ def _match_roadmap_slot(
     return step, None
 
 
+def _normalize_roadmap_steps_coverage(
+    steps: List[Dict[str, Any]],
+    *,
+    roadmap_ctx: ProgressionRoadmapContext,
+    max_steps: int,
+) -> List[Dict[str, Any]]:
+    """Ein Eintrag pro Roadmap-Major-Step — fehlende Slots als leere Platzhalter."""
+    stage_specs = list(roadmap_ctx.stage_specs or [])[:max_steps]
+    if not stage_specs:
+        return steps
+
+    major_by_index: Dict[int, MajorStep] = {}
+    if roadmap_ctx.roadmap:
+        major_by_index = {m.index: m for m in roadmap_ctx.roadmap.major_steps}
+
+    by_major: Dict[int, Dict[str, Any]] = {}
+    for raw in steps:
+        step = dict(raw)
+        midx = step.get("roadmap_major_step_index")
+        if midx is not None:
+            by_major[int(midx)] = step
+
+    out: List[Dict[str, Any]] = []
+    for spec in sorted(stage_specs, key=lambda s: s.major_step_index):
+        midx = int(spec.major_step_index)
+        if midx in by_major:
+            out.append(by_major[midx])
+            continue
+        major = major_by_index.get(midx)
+        goal = (spec.learning_goal or "").strip()
+        out.append(
+            {
+                "exercise_id": None,
+                "variant_id": None,
+                "title": goal or f"Slot {midx + 1}",
+                "is_ai_proposal": False,
+                "roadmap_major_step_index": midx,
+                "roadmap_phase": major.phase if major else None,
+                "roadmap_learning_goal": goal or None,
+                "roadmap_match_source": "stage_spec",
+                "reasons": [],
+            }
+        )
+    return out
+
+
+def _maybe_rematch_roadmap_after_strip(
+    cur,
+    *,
+    tenant: TenantContext,
+    body: ProgressionPathSuggestRequest,
+    goal_query: str,
+    max_steps: int,
+    semantic_brief: PlanningSemanticBrief,
+    path_target_profile: PlanningTargetProfile,
+    path_intent: str,
+    roadmap_ctx: ProgressionRoadmapContext,
+    steps: List[Dict[str, Any]],
+    stripped_off_topic: List[Dict[str, Any]],
+    off_topic_before_strip: List[Dict[str, Any]],
+    roadmap_unfilled: List[Tuple[int, StageSpecArtifact]],
+) -> Tuple[
+    List[Dict[str, Any]],
+    List[Dict[str, Any]],
+    List[Dict[str, Any]],
+    List[Dict[str, Any]],
+    int,
+    List[Tuple[int, StageSpecArtifact]],
+]:
+    rematch_log: List[Dict[str, Any]] = []
+    rematch_rounds = 0
+    if not body.auto_rematch_after_qa or not roadmap_ctx.stage_specs:
+        return steps, rematch_log, stripped_off_topic, [], rematch_rounds, roadmap_unfilled
+
+    slot_indices, rematch_reasons = collect_rematch_slot_indices(
+        stripped_off_topic=stripped_off_topic,
+        off_topic_steps=off_topic_before_strip if not stripped_off_topic else [],
+        optimization_hints=[],
+        stage_specs=roadmap_ctx.stage_specs,
+    )
+    if not slot_indices:
+        return steps, rematch_log, stripped_off_topic, [], rematch_rounds, roadmap_unfilled
+
+    steps, rematch_log, rematch_new_unfilled = rematch_roadmap_slots(
+        cur,
+        tenant=tenant,
+        body=body,
+        goal_query=goal_query,
+        max_steps=max_steps,
+        semantic_brief=semantic_brief,
+        path_target_profile=path_target_profile,
+        path_intent=path_intent,
+        roadmap_ctx=roadmap_ctx,
+        steps=steps,
+        slot_indices=slot_indices,
+        rematch_reasons=rematch_reasons,
+        match_slot_fn=_match_roadmap_slot,
+    )
+    rematch_rounds = 1
+    stripped_off_topic = prune_stripped_after_rematch(stripped_off_topic, rematch_log)
+    if rematch_new_unfilled:
+        remapped = {sp.major_step_index for _, sp in rematch_new_unfilled}
+        roadmap_unfilled = [
+            item for item in roadmap_unfilled if item[1].major_step_index not in remapped
+        ]
+        roadmap_unfilled.extend(rematch_new_unfilled)
+
+    off_topic_steps = detect_off_topic_steps(
+        cur,
+        steps,
+        brief=semantic_brief,
+        goal_query=goal_query,
+    )
+    return (
+        steps,
+        rematch_log,
+        stripped_off_topic,
+        off_topic_steps,
+        rematch_rounds,
+        roadmap_unfilled,
+    )
+
+
 def _build_steps_roadmap_first(
     cur,
     *,
@@ -906,7 +1033,6 @@ def _run_evaluate_only_path_qa(
             brief=semantic_brief,
             goal_query=goal_query,
         )
-        steps, stripped_off_topic = strip_off_topic_steps_from_path(steps, off_topic_steps)
         llm_gap_specs = parse_llm_suggested_new_exercises(
             llm_qa,
             brief=semantic_brief,
@@ -918,7 +1044,7 @@ def _run_evaluate_only_path_qa(
             gap_specs = collect_gap_fill_specs(
                 steps=steps,
                 unfilled_gaps=fresh_large_gaps or unfilled_gaps,
-                off_topic_steps=off_topic_steps if not stripped_off_topic else [],
+                off_topic_steps=off_topic_steps,
                 llm_specs=llm_gap_specs,
                 brief=semantic_brief,
                 goal_query=goal_query,
@@ -1374,49 +1500,31 @@ def suggest_progression_path(
                 roadmap_first=roadmap_first,
             )
 
-        if (
-            roadmap_first
-            and body.auto_rematch_after_qa
-            and roadmap_ctx is not None
-            and roadmap_ctx.stage_specs
-        ):
-            slot_indices, rematch_reasons = collect_rematch_slot_indices(
+        if roadmap_first and roadmap_ctx is not None:
+            (
+                steps,
+                rematch_log,
+                stripped_off_topic,
+                rematch_off_topic,
+                rematch_rounds,
+                roadmap_unfilled,
+            ) = _maybe_rematch_roadmap_after_strip(
+                cur,
+                tenant=tenant,
+                body=body,
+                goal_query=goal_query,
+                max_steps=max_steps,
+                semantic_brief=semantic_brief,
+                path_target_profile=path_target_profile,
+                path_intent=path_intent,
+                roadmap_ctx=roadmap_ctx,
+                steps=steps,
                 stripped_off_topic=stripped_off_topic,
-                off_topic_steps=off_topic_before_strip if not stripped_off_topic else [],
-                optimization_hints=[],
-                stage_specs=roadmap_ctx.stage_specs,
+                off_topic_before_strip=off_topic_before_strip,
+                roadmap_unfilled=roadmap_unfilled,
             )
-            if slot_indices:
-                steps, rematch_log, rematch_new_unfilled = rematch_roadmap_slots(
-                    cur,
-                    tenant=tenant,
-                    body=body,
-                    goal_query=goal_query,
-                    max_steps=max_steps,
-                    semantic_brief=semantic_brief,
-                    path_target_profile=path_target_profile,
-                    path_intent=path_intent,
-                    roadmap_ctx=roadmap_ctx,
-                    steps=steps,
-                    slot_indices=slot_indices,
-                    rematch_reasons=rematch_reasons,
-                    match_slot_fn=_match_roadmap_slot,
-                )
-                rematch_rounds = 1
-                if rematch_new_unfilled:
-                    remapped = {sp.major_step_index for _, sp in rematch_new_unfilled}
-                    roadmap_unfilled = [
-                        item
-                        for item in roadmap_unfilled
-                        if item[1].major_step_index not in remapped
-                    ]
-                    roadmap_unfilled.extend(rematch_new_unfilled)
-                off_topic_steps = detect_off_topic_steps(
-                    cur,
-                    steps,
-                    brief=semantic_brief,
-                    goal_query=goal_query,
-                )
+            if rematch_off_topic:
+                off_topic_steps = rematch_off_topic
                 gaps = detect_path_gaps(
                     cur,
                     steps,
@@ -1500,6 +1608,13 @@ def suggest_progression_path(
         path_qa["rematch_log"] = rematch_log
         path_qa["rematch_rounds"] = rematch_rounds
 
+    if roadmap_first and roadmap_ctx is not None:
+        steps = _normalize_roadmap_steps_coverage(
+            steps,
+            roadmap_ctx=roadmap_ctx,
+            max_steps=max_steps,
+        )
+
     target_profile_summary = path_target_profile.to_summary_dict(cur)
     retrieval_parts = ["profile_v1", "full_library", "path_builder", "semantics"]
     if roadmap_first:
diff --git a/backend/planning_exercise_path_qa.py b/backend/planning_exercise_path_qa.py
index 8b833a4..82b5847 100644
--- a/backend/planning_exercise_path_qa.py
+++ b/backend/planning_exercise_path_qa.py
@@ -416,7 +416,14 @@ def detect_off_topic_steps(
     goal_query: Optional[str] = None,
 ) -> List[Dict[str, Any]]:
     """Schritte ohne Bezug zum Pfad-Thema (z. B. reine Kraftübungen bei Mae Geri)."""
-    if brief.semantic_strength < 0.55 or len(steps) < 2:
+    if len(steps) < 2:
+        return []
+    roadmap_stage_steps = any(
+        (step.get("roadmap_match_source") == "stage_spec")
+        or (step.get("roadmap_learning_goal") or "").strip()
+        for step in steps
+    )
+    if brief.semantic_strength < 0.55 and not roadmap_stage_steps:
         return []
 
     path_anti = resolve_path_anti_patterns(goal_query or "", semantic_brief=brief)
diff --git a/backend/planning_path_rematch.py b/backend/planning_path_rematch.py
index 1faeba8..d86f5b9 100644
--- a/backend/planning_path_rematch.py
+++ b/backend/planning_path_rematch.py
@@ -137,6 +137,8 @@ def rematch_roadmap_slots(
             for m, s in steps_by_major.items()
             if s.get("exercise_id") is not None
         }
+        if old and old.get("exercise_id") is not None:
+            used.add(int(old["exercise_id"]))
         planned_ids, anchor_id, anchor_variant_id = _context_before_major(
             steps_by_major, int(major_idx)
         )
@@ -196,7 +198,35 @@ def rematch_roadmap_slots(
     return ordered, rematch_log, new_unfilled
 
 
+def prune_stripped_after_rematch(
+    stripped_off_topic: Sequence[Mapping[str, Any]],
+    rematch_log: Sequence[Mapping[str, Any]],
+) -> List[Dict[str, Any]]:
+    """Entfernt aus stripped_off_topic Slots, die per Rematch ersetzt wurden."""
+    replaced: Set[int] = set()
+    for entry in rematch_log or []:
+        if not isinstance(entry, dict):
+            continue
+        if str(entry.get("action") or "") != "replaced":
+            continue
+        midx = entry.get("roadmap_major_step_index")
+        if midx is not None:
+            replaced.add(int(midx))
+    if not replaced:
+        return list(stripped_off_topic or [])
+    out: List[Dict[str, Any]] = []
+    for item in stripped_off_topic or []:
+        if not isinstance(item, dict):
+            continue
+        midx = item.get("roadmap_major_step_index")
+        if midx is not None and int(midx) in replaced:
+            continue
+        out.append(dict(item))
+    return out
+
+
 __all__ = [
     "collect_rematch_slot_indices",
+    "prune_stripped_after_rematch",
     "rematch_roadmap_slots",
 ]
diff --git a/backend/tests/test_planning_path_rematch.py b/backend/tests/test_planning_path_rematch.py
index fbacba9..46e4b02 100644
--- a/backend/tests/test_planning_path_rematch.py
+++ b/backend/tests/test_planning_path_rematch.py
@@ -95,8 +95,9 @@ def test_rematch_roadmap_slots_replaces_only_target_slot():
 
     def _fake_match(cur, *, stage_spec, used, **kwargs):
         assert stage_spec.major_step_index == 1
-        assert 20 not in used
+        assert 20 in used
         assert 10 in used
+        assert 30 in used
         return (
             {
                 "exercise_id": 21,
@@ -131,3 +132,41 @@ def test_rematch_roadmap_slots_replaces_only_target_slot():
     assert log[0]["replaced_exercise_id"] == 20
     assert log[0]["new_exercise_id"] == 21
     assert not unfilled
+
+
+def test_rematch_excludes_replaced_exercise_from_used():
+    specs = _stage_specs()
+    ctx = ProgressionRoadmapContext(
+        goal_query="Mawashi Geri",
+        max_steps=3,
+        stage_specs=specs,
+    )
+    steps = [
+        {"exercise_id": 10, "title": "OK", "roadmap_major_step_index": 0},
+        {"exercise_id": 99, "title": "Mae Geri", "roadmap_major_step_index": 1},
+    ]
+    seen_used = []
+
+    def _fake_match(cur, *, used, stage_spec, **kwargs):
+        seen_used.append(set(used))
+        return (
+            {"exercise_id": 42, "title": "Neu", "roadmap_major_step_index": stage_spec.major_step_index},
+            None,
+        )
+
+    rematch_roadmap_slots(
+        None,
+        tenant=None,
+        body=None,
+        goal_query="Mawashi",
+        max_steps=3,
+        semantic_brief=None,
+        path_target_profile=None,
+        path_intent="",
+        roadmap_ctx=ctx,
+        steps=steps,
+        slot_indices={1},
+        rematch_reasons={1: "technique_scope"},
+        match_slot_fn=_fake_match,
+    )
+    assert 99 in seen_used[0]
diff --git a/frontend/src/components/ExerciseProgressionPathBuilder.jsx b/frontend/src/components/ExerciseProgressionPathBuilder.jsx
index 598a620..327a0a9 100644
--- a/frontend/src/components/ExerciseProgressionPathBuilder.jsx
+++ b/frontend/src/components/ExerciseProgressionPathBuilder.jsx
@@ -1022,10 +1022,7 @@ export default function ExerciseProgressionPathBuilder({
   const applyPathMatchResponse = (res, q) => {
     const qa = res?.path_qa || null
     const rawRows = (Array.isArray(res?.steps) ? res.steps : []).map(mapApiStepToRow)
-    const rows =
-      Array.isArray(qa?.stripped_off_topic_steps) && qa.stripped_off_topic_steps.length > 0
-        ? rawRows
-        : applyOffTopicFlags(rawRows, qa)
+    const rows = applyOffTopicFlags(rawRows, qa)
     if (rows.length < 2) {
       throw new Error('Zu wenig Schritte im Vorschlag.')
     }
diff --git a/frontend/src/utils/progressionGraphDraft.js b/frontend/src/utils/progressionGraphDraft.js
index 18ee771..119494b 100644
--- a/frontend/src/utils/progressionGraphDraft.js
+++ b/frontend/src/utils/progressionGraphDraft.js
@@ -750,12 +750,14 @@ export function applyMatchStepsToSlots(draft, apiSteps) {
     siblings: [...(slot.siblings || [])],
   }))
 
+  const touchedMajors = new Set()
   for (const step of steps) {
     if (step.roadmap_major_step_index == null || !Number.isFinite(Number(step.roadmap_major_step_index))) {
       continue
     }
     const idx = Number(step.roadmap_major_step_index)
     if (idx < 0 || idx >= nextSlots.length) continue
+    touchedMajors.add(idx)
 
     const isProposal = Boolean(step.is_ai_proposal) || step.exercise_id == null
     if (isProposal) {
@@ -773,6 +775,12 @@ export function applyMatchStepsToSlots(draft, apiSteps) {
     }
   }
 
+  for (let i = 0; i < nextSlots.length; i += 1) {
+    if (!touchedMajors.has(i)) {
+      nextSlots[i].primary = emptySlotExercise()
+    }
+  }
+
   return syncProgressionRoadmapFromSlots({ ...draft, slots: nextSlots, dirty: true })
 }
 

From f63b09fc9c3bcb90f1a2a2e83bc5f62d7c5dc425 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Thu, 11 Jun 2026 10:48:36 +0200
Subject: [PATCH 22/33] Refine Technique Path Scope Logic and Enhance Test
 Coverage

- Updated the `exercise_passes_technique_path_scope` function to clarify the requirements for technique inclusion, ensuring that the primary technique must appear in the exercise text.
- Enhanced the logic to allow for relaxed matching based on parts of the primary topic, improving flexibility in exercise validation.
- Added new tests to validate the rejection of off-topic exercises, specifically addressing cases where only stage goals mention the primary technique.
- Improved the selection logic in `pick_best_path_hit` to ensure proper handling of roadmap stage matches.
---
 backend/planning_exercise_semantics.py        | 23 +++++---
 .../test_planning_roadmap_stage_match.py      | 56 +++++++++++++++++++
 2 files changed, 71 insertions(+), 8 deletions(-)

diff --git a/backend/planning_exercise_semantics.py b/backend/planning_exercise_semantics.py
index 38798e2..c7b0d77 100644
--- a/backend/planning_exercise_semantics.py
+++ b/backend/planning_exercise_semantics.py
@@ -207,7 +207,10 @@ def exercise_passes_technique_path_scope(
     relaxed: bool = False,
 ) -> bool:
     """
-    Technik-Pfad: keine Geschwister-Technik; Haupttechnik im Übungstext oder Stufen-Lernziel.
+    Technik-Pfad: keine Geschwister-Technik; Haupttechnik muss im Übungstext vorkommen.
+
+    Das Stufen-Lernziel allein reicht nicht — sonst würden themenfremde Übungen (z. B. Kumite)
+    nur wegen „Mawashi Geri“ im Lernziel durch das Gate rutschen.
     """
     primary = _normalize_phrase(primary_topic)
     if not primary:
@@ -218,11 +221,14 @@ def exercise_passes_technique_path_scope(
     if excludes and _blob_matches_stage_excludes(blob, excludes):
         return False
 
-    in_exercise = _phrase_in_blob(primary, blob)
-    in_stage = _phrase_in_blob(primary, _blob_from_fields("", "", learning_goal, []))
-    if in_exercise or in_stage:
+    if _phrase_in_blob(primary, blob):
         return True
-    return relaxed
+
+    if relaxed:
+        parts = [p for p in primary.split() if len(p) >= 4]
+        if parts and any(_phrase_in_blob(part, blob) for part in parts):
+            return True
+    return False
 
 
 def _detect_development_arc(q_lower: str) -> List[str]:
@@ -1245,15 +1251,16 @@ def pick_best_path_hit(
         return best
 
     chosen = _scan(strict=True)
-    if chosen:
-        return chosen
-    chosen = _scan(strict=False)
     if chosen:
         return chosen
 
     if roadmap_stage_match:
         return None
 
+    chosen = _scan(strict=False)
+    if chosen:
+        return chosen
+
     # Notfall (nur retrieval-first / Brücken): bester verbleibender Treffer
     fallback: Optional[Dict[str, Any]] = None
     fallback_key: Tuple[float, float] = (-1.0, -1.0)
diff --git a/backend/tests/test_planning_roadmap_stage_match.py b/backend/tests/test_planning_roadmap_stage_match.py
index 0a9f97d..56d768b 100644
--- a/backend/tests/test_planning_roadmap_stage_match.py
+++ b/backend/tests/test_planning_roadmap_stage_match.py
@@ -249,6 +249,62 @@ def test_pick_best_skips_kumite_for_mawashi_athletic_path():
     assert int(chosen["id"]) == 2
 
 
+def test_technique_scope_rejects_kumite_when_only_stage_goal_mentions_mawashi():
+    siblings = technique_sibling_excludes("mawashi geri")
+    assert not exercise_passes_technique_path_scope(
+        primary_topic="mawashi geri",
+        title="Kumite Grundstellungen",
+        summary="Partner-Distanz und freier Kampf",
+        goal="Kumite-Technik",
+        learning_goal="Sprungkraft und Koordination für Mawashi Geri",
+        sibling_excludes=siblings,
+        relaxed=True,
+    )
+
+
+def test_pick_best_roadmap_rejects_kumite_with_path_primary_topic():
+    q = "gesprungener Mawashi Geri Sprungphase"
+    brief = enrich_brief_with_path_constraints(build_semantic_brief(q), q)
+    primary = (brief.primary_topic or "mawashi geri").strip()
+    stage_goal = "Sprungvorbereitung für Mawashi Geri"
+    stage_brief = build_stage_match_brief(
+        learning_goal=stage_goal,
+        path_primary_topic=primary,
+        path_technique_excludes=technique_sibling_excludes(primary),
+    )
+    hits = [
+        {
+            "id": 1,
+            "title": "Kumite Distanztraining",
+            "summary": "Partnerarbeit",
+            "goal": "Kampfvorbereitung",
+            "score": 0.95,
+            "semantic_score": 0.4,
+            "stage_semantic_score": 0.35,
+        },
+        {
+            "id": 2,
+            "title": "Sprungkraft Plyometrie",
+            "summary": "Absprung für Tritttechnik",
+            "goal": "Sprungkraft Mawashi Geri Vorbereitung",
+            "score": 0.7,
+            "semantic_score": 0.45,
+            "stage_semantic_score": 0.42,
+        },
+    ]
+    chosen = pick_best_path_hit(
+        hits,
+        set(),
+        stage_learning_goal=stage_goal,
+        roadmap_stage_match=True,
+        stage_match_brief=stage_brief,
+        path_primary_topic=primary,
+        path_technique_excludes=technique_sibling_excludes(primary),
+    )
+    assert chosen is not None
+    assert int(chosen["id"]) == 2
+
+
 def test_technique_scope_rejects_sibling_geri_for_mawashi_path():
     siblings = technique_sibling_excludes("mawashi geri")
     assert any("mae" in s for s in siblings)

From 044ce2ee60247230be3464d162005dfa3f205b43 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Thu, 11 Jun 2026 11:06:38 +0200
Subject: [PATCH 23/33] Implement Primary Topic Resolution in Path Logic

- Introduced `resolve_path_primary_topic` function to enhance the determination of primary topics from goal queries and semantic briefs, improving exercise relevance.
- Updated `_match_roadmap_slot` and `detect_off_topic_steps` functions to utilize the new primary topic resolution logic, ensuring accurate topic identification.
- Enhanced tests to validate the functionality of primary topic resolution and its impact on exercise selection and off-topic detection.
- Improved handling of primary topics in the `ExerciseProgressionPathBuilder` and related components for better integration with the overall path-building process.
---
 backend/planning_exercise_path_builder.py     | 13 ++++-
 backend/planning_exercise_path_qa.py          | 14 +++--
 backend/planning_exercise_semantics.py        | 34 +++++++++++-
 backend/planning_progression_roadmap.py       |  1 +
 .../test_planning_roadmap_stage_match.py      | 54 ++++++++++++++++++-
 .../ExerciseProgressionPathBuilder.jsx        | 10 ++--
 frontend/src/utils/progressionGraphDraft.js   | 18 +++++--
 7 files changed, 128 insertions(+), 16 deletions(-)

diff --git a/backend/planning_exercise_path_builder.py b/backend/planning_exercise_path_builder.py
index 7973571..d017fc0 100644
--- a/backend/planning_exercise_path_builder.py
+++ b/backend/planning_exercise_path_builder.py
@@ -46,6 +46,7 @@ from planning_exercise_semantics import (
     enrich_brief_with_path_constraints,
     enrich_target_with_semantic_expectations,
     resolve_path_anti_patterns,
+    resolve_path_primary_topic,
     exercise_passes_path_semantic_gate,
     pick_best_path_hit,
     resolve_semantic_skill_weights,
@@ -631,9 +632,17 @@ def _match_roadmap_slot(
         extra_context=path_context_note,
     )
     stage_anti = list(dict.fromkeys([*(stage_spec.anti_patterns or []), *path_anti]))
-    path_primary = (semantic_brief.primary_topic or "").strip()
+    path_primary = (
+        resolve_path_primary_topic(
+            goal_query,
+            semantic_brief,
+            stage_learning_goal=stage_goal,
+            extra_context=path_context_note,
+        )
+        or ""
+    ).strip()
     path_tech_excludes = list(semantic_brief.exclude_phrases or [])
-    if semantic_brief.topic_type == "technique" and path_primary:
+    if path_primary:
         from planning_exercise_semantics import technique_sibling_excludes
 
         for item in technique_sibling_excludes(path_primary):
diff --git a/backend/planning_exercise_path_qa.py b/backend/planning_exercise_path_qa.py
index 82b5847..f0cb034 100644
--- a/backend/planning_exercise_path_qa.py
+++ b/backend/planning_exercise_path_qa.py
@@ -25,6 +25,7 @@ from planning_exercise_semantics import (
     exercise_passes_stage_learning_goal_gate,
     exercise_passes_technique_path_scope,
     resolve_path_anti_patterns,
+    resolve_path_primary_topic,
     score_exercise_semantic_relevance,
     semantic_brief_for_stage,
     step_phase_for_index,
@@ -456,10 +457,17 @@ def detect_off_topic_steps(
                 )
             )
             continue
-        primary = (brief.primary_topic or "").strip()
-        if brief.topic_type == "technique" and primary:
+        stage_goal_pre = (step.get("roadmap_learning_goal") or "").strip()
+        primary = (
+            resolve_path_primary_topic(
+                goal_query or "",
+                brief,
+                stage_learning_goal=stage_goal_pre or None,
+            )
+            or ""
+        ).strip()
+        if primary:
             siblings = technique_sibling_excludes(primary)
-            stage_goal_pre = (step.get("roadmap_learning_goal") or "").strip()
             if not exercise_passes_technique_path_scope(
                 primary_topic=primary,
                 title=bundle["title"],
diff --git a/backend/planning_exercise_semantics.py b/backend/planning_exercise_semantics.py
index c7b0d77..9d630bb 100644
--- a/backend/planning_exercise_semantics.py
+++ b/backend/planning_exercise_semantics.py
@@ -180,6 +180,28 @@ def _find_technique_in_text(q_lower: str) -> Optional[Tuple[str, Tuple[str, ...]
     return None
 
 
+def resolve_path_primary_topic(
+    goal_query: str,
+    semantic_brief: Optional[PlanningSemanticBrief] = None,
+    *,
+    stage_learning_goal: Optional[str] = None,
+    extra_context: Optional[str] = None,
+) -> Optional[str]:
+    """
+    Haupttechnik aus Anfrage, Kontext oder Stufen-Lernziel — nicht nur aus goal_query.
+    """
+    if semantic_brief:
+        primary = (semantic_brief.primary_topic or "").strip()
+        if primary:
+            return primary
+    parts = [goal_query or "", extra_context or "", stage_learning_goal or ""]
+    combined = _normalize_phrase(" ".join(p for p in parts if p))
+    if not combined:
+        return None
+    hit = _find_technique_in_text(combined.lower())
+    return hit[0] if hit else None
+
+
 def technique_sibling_excludes(primary_topic: str) -> List[str]:
     """Andere Techniken derselben Familie (z. B. Mae/Yoko bei Mawashi) — aus Katalog."""
     topic = _normalize_phrase(primary_topic)
@@ -1038,13 +1060,22 @@ def exercise_passes_stage_fit(
         return False
 
     primary_path = (path_primary_topic or "").strip()
+    if not primary_path and lg:
+        hit = _find_technique_in_text(_normalize_phrase(lg))
+        if hit:
+            primary_path = hit[0]
+    tech_excludes = list(path_technique_excludes or [])
+    if primary_path:
+        for item in technique_sibling_excludes(primary_path):
+            if item not in tech_excludes:
+                tech_excludes.append(item)
     if primary_path and not exercise_passes_technique_path_scope(
         primary_topic=primary_path,
         title=title,
         summary=summary,
         goal=goal,
         learning_goal=lg,
-        sibling_excludes=path_technique_excludes,
+        sibling_excludes=tech_excludes,
         relaxed=relaxed,
     ):
         return False
@@ -1295,6 +1326,7 @@ __all__ = [
     "build_stage_match_brief",
     "enrich_brief_with_path_constraints",
     "exercise_passes_stage_fit",
+    "resolve_path_primary_topic",
     "resolve_path_anti_patterns",
     "exercise_passes_stage_learning_goal_gate",
     "merge_semantic_brief_llm",
diff --git a/backend/planning_progression_roadmap.py b/backend/planning_progression_roadmap.py
index 5d95e7f..f772345 100644
--- a/backend/planning_progression_roadmap.py
+++ b/backend/planning_progression_roadmap.py
@@ -1028,6 +1028,7 @@ def roadmap_context_from_override(
         goal_query=goal_query.strip(),
         max_steps=effective_max,
         semantic_brief=brief_to_summary_dict(semantic_brief),
+        resolved_structured=structured,
         goal_analysis=goal_analysis,
         roadmap=RoadmapArtifact(major_steps=majors),
         stage_specs=stage_specs,
diff --git a/backend/tests/test_planning_roadmap_stage_match.py b/backend/tests/test_planning_roadmap_stage_match.py
index 56d768b..d7cc943 100644
--- a/backend/tests/test_planning_roadmap_stage_match.py
+++ b/backend/tests/test_planning_roadmap_stage_match.py
@@ -8,6 +8,7 @@ from planning_exercise_semantics import (
     exercise_passes_technique_path_scope,
     pick_best_path_hit,
     resolve_path_anti_patterns,
+    resolve_path_primary_topic,
     score_exercise_stage_fit,
     semantic_brief_for_stage,
     technique_sibling_excludes,
@@ -231,12 +232,13 @@ def test_pick_best_skips_kumite_for_mawashi_athletic_path():
             "id": 2,
             "title": "Sprungkraft Plyometrie",
             "summary": "Absprung und Landung",
-            "goal": "Sprungkraft für Tritttechnik",
+            "goal": "Sprungkraft für Mawashi Geri Vorbereitung",
             "score": 0.62,
             "semantic_score": 0.38,
             "stage_semantic_score": 0.38,
         },
     ]
+    primary = resolve_path_primary_topic(q, brief, stage_learning_goal=stage_goal)
     chosen = pick_best_path_hit(
         hits,
         set(),
@@ -244,6 +246,56 @@ def test_pick_best_skips_kumite_for_mawashi_athletic_path():
         stage_anti_patterns=path_anti,
         roadmap_stage_match=True,
         stage_match_brief=stage_brief,
+        path_primary_topic=primary,
+        path_technique_excludes=technique_sibling_excludes(primary or "mawashi geri"),
+    )
+    assert chosen is not None
+    assert int(chosen["id"]) == 2
+
+
+def test_resolve_path_primary_topic_from_stage_learning_goal():
+    brief = build_semantic_brief("Trainingsprogression gesprungener Tritt")
+    primary = resolve_path_primary_topic(
+        "Trainingsprogression gesprungener Tritt",
+        brief,
+        stage_learning_goal="Perfektionierung der statischen Mawashi Geri Technik",
+    )
+    assert primary and "mawashi" in primary
+
+
+def test_pick_rejects_kumite_when_primary_only_in_stage_goal():
+    brief = build_semantic_brief("Trainingsprogression")
+    stage_goal = "Perfektionierung der statischen Mawashi Geri Technik"
+    stage_brief = build_stage_match_brief(learning_goal=stage_goal)
+    primary = resolve_path_primary_topic("Trainingsprogression", brief, stage_learning_goal=stage_goal)
+    hits = [
+        {
+            "id": 4,
+            "title": "4 Kumite Reaktions Übungen",
+            "summary": "Partner",
+            "goal": "Kumite",
+            "score": 0.95,
+            "semantic_score": 0.4,
+            "stage_semantic_score": 0.35,
+        },
+        {
+            "id": 2,
+            "title": "Mawashi Geri Standtechnik",
+            "summary": "Rundtritt",
+            "goal": "Mawashi Geri Basis",
+            "score": 0.7,
+            "semantic_score": 0.5,
+            "stage_semantic_score": 0.48,
+        },
+    ]
+    chosen = pick_best_path_hit(
+        hits,
+        set(),
+        stage_learning_goal=stage_goal,
+        roadmap_stage_match=True,
+        stage_match_brief=stage_brief,
+        path_primary_topic=primary,
+        path_technique_excludes=technique_sibling_excludes(primary or "mawashi geri"),
     )
     assert chosen is not None
     assert int(chosen["id"]) == 2
diff --git a/frontend/src/components/ExerciseProgressionPathBuilder.jsx b/frontend/src/components/ExerciseProgressionPathBuilder.jsx
index 327a0a9..9c83c04 100644
--- a/frontend/src/components/ExerciseProgressionPathBuilder.jsx
+++ b/frontend/src/components/ExerciseProgressionPathBuilder.jsx
@@ -142,8 +142,10 @@ function normalizeTitleKey(text) {
     .replace(/\s+/g, ' ')
 }
 
-function mergeGraphIntoPathSteps(pathRows, graphNodes) {
-  if (!Array.isArray(graphNodes) || !graphNodes.length || !pathRows.length) return pathRows
+function mergeGraphIntoPathSteps(pathRows, graphNodes, { skipGraphMerge = false } = {}) {
+  if (skipGraphMerge || !Array.isArray(graphNodes) || !graphNodes.length || !pathRows.length) {
+    return pathRows
+  }
   return pathRows.map((row, i) => {
     const node = graphNodes[i]
     if (!node?.exercise_id) return row
@@ -1019,14 +1021,14 @@ export default function ExerciseProgressionPathBuilder({
     }
   }
 
-  const applyPathMatchResponse = (res, q) => {
+  const applyPathMatchResponse = (res, q, { skipGraphMerge = true } = {}) => {
     const qa = res?.path_qa || null
     const rawRows = (Array.isArray(res?.steps) ? res.steps : []).map(mapApiStepToRow)
     const rows = applyOffTopicFlags(rawRows, qa)
+    const mergedRows = mergeGraphIntoPathSteps(rows, graphChainNodes, { skipGraphMerge })
     if (rows.length < 2) {
       throw new Error('Zu wenig Schritte im Vorschlag.')
     }
-    const mergedRows = mergeGraphIntoPathSteps(rows, graphChainNodes)
     const rawGaps = Array.isArray(res?.gap_fill_offers)
       ? res.gap_fill_offers
       : Array.isArray(qa?.gap_fill_offers)
diff --git a/frontend/src/utils/progressionGraphDraft.js b/frontend/src/utils/progressionGraphDraft.js
index 119494b..62d8659 100644
--- a/frontend/src/utils/progressionGraphDraft.js
+++ b/frontend/src/utils/progressionGraphDraft.js
@@ -785,7 +785,7 @@ export function applyMatchStepsToSlots(draft, apiSteps) {
 }
 
 /** Lücken-Angebote in leere Slots legen; Panel nur für verbleibende Lücken. */
-export function applyGapOffersFromResponse(draft, res) {
+export function applyGapOffersFromResponse(draft, res, { replaceOffTopicSlots = false } = {}) {
   let next = draft
   if (res?.progression_roadmap) {
     next = syncSlotPhasesFromRoadmap(next, res.progression_roadmap)
@@ -798,8 +798,14 @@ export function applyGapOffersFromResponse(draft, res) {
     const idx = resolveOfferSlotIndex(next, offer)
     if (idx == null || idx < 0 || idx >= (next.slots?.length || 0)) continue
     const primary = next.slots[idx]?.primary
-    if (primary?.kind === 'library' && primary.exerciseId != null) continue
-    if (primary?.kind === 'proposal') continue
+    const isOffTopicReplace =
+      replaceOffTopicSlots &&
+      offer?.source === 'off_topic' &&
+      offer?.replace_step_index != null
+    if (!isOffTopicReplace) {
+      if (primary?.kind === 'library' && primary.exerciseId != null) continue
+      if (primary?.kind === 'proposal') continue
+    }
 
     next = applyGapOfferToSlot(next, idx, offer)
     if (offer?.offer_id) placedIds.add(offer.offer_id)
@@ -817,7 +823,7 @@ export function applyGapOffersFromResponse(draft, res) {
 }
 
 /** Match-Antwort: Schritte + Lücken-Angebote direkt in Slots (wie früher im Pfad-Wizard sichtbar). */
-export function applyMatchResponseToDraft(draft, res) {
+export function applyMatchResponseToDraft(draft, res, { replaceOffTopicSlots = true } = {}) {
   let next = applyMatchStepsToSlots(draft, res?.steps)
   if (res?.progression_roadmap) {
     next = {
@@ -825,7 +831,9 @@ export function applyMatchResponseToDraft(draft, res) {
       pathSkillExpectations: res?.path_skill_expectations || next.pathSkillExpectations,
     }
   }
-  const { draft: withOffers, remainingOffers } = applyGapOffersFromResponse(next, res)
+  const { draft: withOffers, remainingOffers } = applyGapOffersFromResponse(next, res, {
+    replaceOffTopicSlots,
+  })
   return { draft: withOffers, remainingOffers }
 }
 

From 8f1dad53ab3227cd0170cbda6ed01f32ff69ed0b Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Thu, 11 Jun 2026 11:17:53 +0200
Subject: [PATCH 24/33] Enhance Progression Path Suggestion Logic and UI
 Feedback

- Updated `suggest_progression_path` to include AI-generated gap fill offers when exercises are missing, improving the relevance of suggested paths.
- Introduced a match summary to provide insights on library matches and gap fill offers, enhancing user feedback in the `ProgressionGraphEditor`.
- Refined the `pick_best_path_hit` function to ensure proper handling of roadmap stage matches based on primary topics.
- Added tests to validate the new gap fill offer logic and match summary functionality, ensuring robustness in path suggestion features.
---
 backend/planning_exercise_path_builder.py     | 60 ++++++++++++++++++-
 backend/planning_exercise_semantics.py        |  5 +-
 .../test_planning_roadmap_stage_match.py      | 26 ++++++++
 .../src/components/ProgressionGraphEditor.jsx | 20 +++++++
 frontend/src/utils/progressionGraphDraft.js   | 18 ++++--
 5 files changed, 121 insertions(+), 8 deletions(-)

diff --git a/backend/planning_exercise_path_builder.py b/backend/planning_exercise_path_builder.py
index d017fc0..0855cf2 100644
--- a/backend/planning_exercise_path_builder.py
+++ b/backend/planning_exercise_path_builder.py
@@ -1414,7 +1414,10 @@ def suggest_progression_path(
             anchor_id = eid
             anchor_variant_id = step.get("variant_id")
 
-    if len(steps) < 2:
+    stage_spec_count = len(roadmap_ctx.stage_specs or []) if roadmap_ctx else 0
+    if roadmap_first and stage_spec_count >= 2:
+        pass
+    elif len(steps) < 2:
         raise HTTPException(
             status_code=422,
             detail="Zu wenig passende Übungen für einen Pfad (mindestens 2 Schritte). Ziel präzisieren oder max_steps senken.",
@@ -1623,6 +1626,60 @@ def suggest_progression_path(
             roadmap_ctx=roadmap_ctx,
             max_steps=max_steps,
         )
+        if body.include_ai_gap_fill:
+            seen_offer_ids = {o.get("offer_id") for o in gap_fill_offers}
+            for step in steps:
+                if step.get("exercise_id") is not None:
+                    continue
+                try:
+                    major_idx = int(step["roadmap_major_step_index"])
+                except (TypeError, ValueError, KeyError):
+                    continue
+                stage_spec = next(
+                    (
+                        s
+                        for s in (roadmap_ctx.stage_specs or [])
+                        if int(s.major_step_index) == major_idx
+                    ),
+                    None,
+                )
+                if stage_spec is None:
+                    continue
+                spec = {
+                    "source": "roadmap_unfilled",
+                    "insert_after_index": max(major_idx - 1, -1),
+                    "roadmap_major_step_index": major_idx,
+                    "phase": (step.get("roadmap_phase") or "vertiefung").strip().lower(),
+                    "title_hint": (stage_spec.learning_goal or step.get("title") or f"Slot {major_idx + 1}")[:120],
+                    "sketch": (stage_spec.learning_goal or "").strip(),
+                    "rationale": f"Slot {major_idx + 1} — keine passende Bibliotheks-Übung; KI-Entwurf für diese Stufe.",
+                }
+                offer = build_gap_fill_offer(
+                    spec=spec,
+                    steps=steps,
+                    goal_query=goal_query,
+                    brief=semantic_brief,
+                    proposal=None,
+                    roadmap_snapshot=_roadmap_gap_snapshot_for_spec(
+                        cur,
+                        roadmap_ctx,
+                        spec,
+                        goal_query=goal_query,
+                        semantic_brief=semantic_brief,
+                    ),
+                )
+                if offer.get("offer_id") not in seen_offer_ids:
+                    gap_fill_offers.append(offer)
+                    seen_offer_ids.add(offer.get("offer_id"))
+
+    filled_library_steps = sum(1 for s in steps if s.get("exercise_id") is not None)
+    match_summary = {
+        "roadmap_first": roadmap_first,
+        "library_matches": filled_library_steps,
+        "slot_count": len(steps),
+        "gap_fill_offer_count": len(gap_fill_offers),
+        "roadmap_unfilled_count": len(roadmap_unfilled),
+    }
 
     target_profile_summary = path_target_profile.to_summary_dict(cur)
     retrieval_parts = ["profile_v1", "full_library", "path_builder", "semantics"]
@@ -1667,6 +1724,7 @@ def suggest_progression_path(
         "roadmap_edited": roadmap_edited,
         "roadmap_unfilled_count": len(roadmap_unfilled),
         "path_skill_expectations": path_skill_expectations,
+        "match_summary": match_summary,
         "retrieval_phase": "+".join(retrieval_parts),
     }
 
diff --git a/backend/planning_exercise_semantics.py b/backend/planning_exercise_semantics.py
index 9d630bb..701e41c 100644
--- a/backend/planning_exercise_semantics.py
+++ b/backend/planning_exercise_semantics.py
@@ -1286,7 +1286,10 @@ def pick_best_path_hit(
         return chosen
 
     if roadmap_stage_match:
-        return None
+        if (path_primary_topic or "").strip():
+            return None
+        chosen = _scan(strict=False)
+        return chosen
 
     chosen = _scan(strict=False)
     if chosen:
diff --git a/backend/tests/test_planning_roadmap_stage_match.py b/backend/tests/test_planning_roadmap_stage_match.py
index d7cc943..9519c60 100644
--- a/backend/tests/test_planning_roadmap_stage_match.py
+++ b/backend/tests/test_planning_roadmap_stage_match.py
@@ -263,6 +263,32 @@ def test_resolve_path_primary_topic_from_stage_learning_goal():
     assert primary and "mawashi" in primary
 
 
+def test_pick_roadmap_relaxed_for_non_technique_stage():
+    stage_goal = "Progression Hüftflexibilität und Adduktoren dehnen"
+    stage_brief = build_stage_match_brief(learning_goal=stage_goal)
+    hits = [
+        {
+            "id": 11,
+            "title": "Adduktoren Dehnung am Boden",
+            "summary": "Flexibilität Hüfte",
+            "goal": "Mobilität",
+            "score": 0.68,
+            "semantic_score": 0.22,
+            "stage_semantic_score": 0.22,
+        },
+    ]
+    chosen = pick_best_path_hit(
+        hits,
+        set(),
+        stage_learning_goal=stage_goal,
+        roadmap_stage_match=True,
+        stage_match_brief=stage_brief,
+        path_primary_topic=None,
+    )
+    assert chosen is not None
+    assert int(chosen["id"]) == 11
+
+
 def test_pick_rejects_kumite_when_primary_only_in_stage_goal():
     brief = build_semantic_brief("Trainingsprogression")
     stage_goal = "Perfektionierung der statischen Mawashi Geri Technik"
diff --git a/frontend/src/components/ProgressionGraphEditor.jsx b/frontend/src/components/ProgressionGraphEditor.jsx
index 3a02888..78bee4c 100644
--- a/frontend/src/components/ProgressionGraphEditor.jsx
+++ b/frontend/src/components/ProgressionGraphEditor.jsx
@@ -71,6 +71,7 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
   const [busy, setBusy] = useState(false)
   const [loadErr, setLoadErr] = useState('')
   const [actionErr, setActionErr] = useState('')
+  const [matchNotice, setMatchNotice] = useState('')
   const [pickContext, setPickContext] = useState(null)
   const [pathQa, setPathQa] = useState(null)
   const [gapFillOffers, setGapFillOffers] = useState([])
@@ -396,6 +397,7 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
     }
     setMatching(true)
     setActionErr('')
+    setMatchNotice('')
     try {
       const synced = syncProgressionRoadmapFromSlots(draft)
       const override = majorStepsToOverridePayload(synced.slots)
@@ -427,6 +429,21 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
       setTargetSummary(res?.target_profile_summary || null)
       setPathQa(res?.path_qa || null)
       setGapFillOffers(remainingOffers)
+      const ms = res?.match_summary
+      if (ms) {
+        setMatchNotice(
+          `Match: ${ms.library_matches ?? 0}/${ms.slot_count ?? '?'} Slots aus Bibliothek, ${ms.gap_fill_offer_count ?? 0} KI-Angebote.`,
+        )
+      }
+      try {
+        await saveProgressionGraphDraft(api, graphId, {
+          ...matched,
+          lastFindings: res?.path_qa || null,
+        })
+        setDraft((prev) => (prev ? { ...prev, dirty: false } : prev))
+      } catch (saveErr) {
+        console.warn('Match-Artefakt konnte nicht gespeichert werden', saveErr)
+      }
     } catch (e) {
       setActionErr(e.message || 'Übungs-Match fehlgeschlagen')
     } finally {
@@ -868,6 +885,9 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
                 {busy ? 'Speichern…' : 'Graph speichern'}
               </button>
             </div>
+            {matchNotice ? (
+              <p style={{ margin: '8px 0 0', fontSize: '11px', color: 'var(--accent-dark)' }}>{matchNotice}</p>
+            ) : null}
             {draft.dirty ? (
               <p style={{ margin: '8px 0 0', fontSize: '11px', color: 'var(--accent-dark)' }}>
                 Ungespeicherte Änderungen
diff --git a/frontend/src/utils/progressionGraphDraft.js b/frontend/src/utils/progressionGraphDraft.js
index 62d8659..dd7bf38 100644
--- a/frontend/src/utils/progressionGraphDraft.js
+++ b/frontend/src/utils/progressionGraphDraft.js
@@ -245,7 +245,7 @@ export function filterGapOffersForUnfilledSlots(draft, offers) {
     if (idx == null || idx < 0 || idx >= (draft?.slots?.length || 0)) return true
     const p = draft.slots[idx]?.primary
     if (p?.kind === 'library' && p.exerciseId != null) return false
-    if (p?.kind === 'proposal') return false
+    if (p?.kind === 'proposal' && p.aiSuggestion) return false
     return true
   })
 }
@@ -407,13 +407,13 @@ export function majorStepsToOverridePayload(rows) {
     major_steps: indexed.map((row) => ({
       index: row.index,
       phase: row.phase || 'vertiefung',
-      learning_goal: row.learning_goal.trim(),
+      learning_goal: (row.learning_goal || '').trim(),
       consolidates: row.consolidates || [],
       rationale: row.rationale || '',
     })),
     stage_specs: indexed.map((row, i) => ({
       major_step_index: i,
-      learning_goal: row.learning_goal.trim(),
+      learning_goal: (row.learning_goal || '').trim(),
       load_profile: Array.isArray(row.load_profile) ? row.load_profile : [],
       exercise_type: (row.exercise_type || '').trim(),
       success_criteria: Array.isArray(row.success_criteria) ? row.success_criteria : [],
@@ -521,9 +521,12 @@ function buildSlotsFromSources({ majorSteps, slotContents, primaryChain, sibling
       ? slotContents.find((s) => Number(s.major_step_index) === i)
       : null
 
+    const hasSavedSlotContents = Array.isArray(slotContents) && slotContents.length > 0
     let primary = saved?.primary
       ? slotExerciseFromApi(saved.primary)
-      : chainNodeToLibrary(primaryChain?.nodes?.[i])
+      : hasSavedSlotContents
+        ? emptySlotExercise()
+        : chainNodeToLibrary(primaryChain?.nodes?.[i])
 
     if (primary.kind === 'empty' && saved?.primary) {
       primary = slotExerciseFromApi(saved.primary)
@@ -760,7 +763,10 @@ export function applyMatchStepsToSlots(draft, apiSteps) {
     touchedMajors.add(idx)
 
     const isProposal = Boolean(step.is_ai_proposal) || step.exercise_id == null
-    if (isProposal) {
+    const hasAiPayload = Boolean(step.ai_suggestion) || Boolean(step.proposal_key)
+    if (isProposal && !hasAiPayload) {
+      nextSlots[idx].primary = emptySlotExercise()
+    } else if (isProposal) {
       nextSlots[idx].primary = proposalSlotExercise({
         title: step.title || nextSlots[idx].learning_goal,
         proposalKey: step.proposal_key,
@@ -804,7 +810,7 @@ export function applyGapOffersFromResponse(draft, res, { replaceOffTopicSlots =
       offer?.replace_step_index != null
     if (!isOffTopicReplace) {
       if (primary?.kind === 'library' && primary.exerciseId != null) continue
-      if (primary?.kind === 'proposal') continue
+      if (primary?.kind === 'proposal' && primary.aiSuggestion) continue
     }
 
     next = applyGapOfferToSlot(next, idx, offer)

From 480890d0c6235ffb92d7e2272d31972b158c4242 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Thu, 11 Jun 2026 11:48:25 +0200
Subject: [PATCH 25/33] Update Dockerfile and requirements for improved
 dependency management

- Added `tzdata` installation in the Dockerfile to support time zone handling in Linux environments.
- Increased `PIP_DEFAULT_TIMEOUT` and added retry logic for pip installations to enhance reliability during dependency installation.
- Updated `requirements.txt` to conditionally include `tzdata` for Windows platforms, ensuring compatibility across different operating systems.
---
 backend/Dockerfile                            |   6 +-
 backend/planning_exercise_form_context.py     | 173 +++++++++++++++-
 backend/planning_exercise_path_ai_fill.py     |  48 ++++-
 backend/planning_exercise_path_builder.py     |   3 +
 backend/requirements.txt                      |   2 +-
 .../test_planning_exercise_form_context.py    |  43 ++++
 .../test_planning_exercise_path_ai_fill.py    |  30 +++
 .../src/components/ProgressionGraphEditor.jsx |  15 +-
 .../src/utils/planningContextForExerciseAi.js | 184 +++++++++++++++++-
 frontend/src/utils/progressionGraphDraft.js   |   6 +
 10 files changed, 492 insertions(+), 18 deletions(-)

diff --git a/backend/Dockerfile b/backend/Dockerfile
index 41de5da..eb64367 100644
--- a/backend/Dockerfile
+++ b/backend/Dockerfile
@@ -2,14 +2,16 @@ FROM python:3.12-slim
 
 WORKDIR /app
 
-# Install system dependencies
+# Install system dependencies (tzdata für zoneinfo/ZoneInfo unter Linux)
 RUN apt-get update && apt-get install -y \
     postgresql-client \
+    tzdata \
     && rm -rf /var/lib/apt/lists/*
 
 # Copy requirements and install dependencies
 COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
+ENV PIP_DEFAULT_TIMEOUT=120
+RUN pip install --no-cache-dir --retries 5 -r requirements.txt
 
 # Copy application code
 COPY . .
diff --git a/backend/planning_exercise_form_context.py b/backend/planning_exercise_form_context.py
index 6972c93..63c9d04 100644
--- a/backend/planning_exercise_form_context.py
+++ b/backend/planning_exercise_form_context.py
@@ -6,7 +6,7 @@ Wird als ``planning_context_json`` in Übungs-Prompts (summary, skills, instruct
 from __future__ import annotations
 
 import json
-from typing import Any, Dict, List, Mapping, Optional
+from typing import Any, Dict, List, Mapping, Optional, Sequence
 
 _MAX_JSON_CHARS = 6000
 _MAX_STRING = 800
@@ -85,6 +85,163 @@ def planning_context_prompt_variables(
     }
 
 
+def _major_index_from_step(step: Mapping[str, Any]) -> Optional[int]:
+    for key in ("roadmap_major_step_index", "major_step_index"):
+        raw = step.get(key)
+        if raw is None:
+            continue
+        try:
+            return int(raw)
+        except (TypeError, ValueError):
+            continue
+    return None
+
+
+def prior_path_steps_before_major(
+    steps: Sequence[Mapping[str, Any]],
+    major_idx: int,
+) -> List[Dict[str, Any]]:
+    """Pfadschritte mit kleinerem roadmap_major_step_index, sortiert."""
+    prior: List[Dict[str, Any]] = []
+    for step in steps:
+        mi = _major_index_from_step(step)
+        if mi is not None and mi < major_idx:
+            prior.append(dict(step))
+    prior.sort(key=lambda s: _major_index_from_step(s) or 0)
+    return prior
+
+
+def _step_display_fields(step: Mapping[str, Any]) -> Dict[str, Any]:
+    title = _trim_str(
+        step.get("title") or step.get("exercise_title"),
+        limit=200,
+    )
+    learning_goal = _trim_str(
+        step.get("roadmap_learning_goal") or step.get("learning_goal"),
+        limit=500,
+    )
+    summary = _trim_str(step.get("summary"), limit=400)
+    start_state = _trim_str(step.get("roadmap_start_state") or step.get("start_state"))
+    target_state = _trim_str(step.get("roadmap_target_state") or step.get("target_state"))
+    phase = _trim_str(step.get("roadmap_phase") or step.get("phase"))
+    criteria_raw = step.get("stage_success_criteria") or step.get("success_criteria") or []
+    criteria = [
+        t
+        for x in criteria_raw
+        if (t := _trim_str(x, limit=200))
+    ][:4]
+    out: Dict[str, Any] = {
+        "title": title,
+        "learning_goal": learning_goal,
+        "summary": summary,
+        "start_state": start_state,
+        "target_state": target_state,
+        "phase": phase,
+        "success_criteria": criteria or None,
+        "major_step_index": _major_index_from_step(step),
+    }
+    return {k: v for k, v in out.items() if v is not None and v != "" and v != []}
+
+
+def build_progression_entry_state(
+    *,
+    major_step_index: Optional[int] = None,
+    prior_steps: Sequence[Mapping[str, Any]] = (),
+    start_situation: Optional[str] = None,
+    current_stage_start: Optional[str] = None,
+) -> Dict[str, Any]:
+    """
+    Eingangszustand für eine Roadmap-Stufe: erreichte Voraussetzungen aus Vorstufen.
+    """
+    prior_compact = [_step_display_fields(s) for s in prior_steps]
+    prior_compact = [
+        p
+        for p in prior_compact
+        if any(p.get(k) for k in ("title", "learning_goal", "summary", "success_criteria"))
+    ]
+
+    achievements: List[str] = []
+    detail_lines: List[str] = []
+    for p in prior_compact:
+        if p.get("success_criteria"):
+            achievements.extend(p["success_criteria"])
+        elif p.get("learning_goal"):
+            achievements.append(p["learning_goal"])
+
+        label_parts: List[str] = []
+        if p.get("major_step_index") is not None:
+            label_parts.append(f"Stufe {int(p['major_step_index']) + 1}")
+        if p.get("phase"):
+            label_parts.append(f"({p['phase']})")
+        if p.get("title"):
+            label_parts.append(f"„{p['title']}\"")
+        prefix = " ".join(label_parts) if label_parts else "Vorstufe"
+        achieved = ""
+        if p.get("target_state"):
+            achieved = p["target_state"]
+        elif p.get("success_criteria"):
+            achieved = "; ".join(p["success_criteria"])
+        elif p.get("learning_goal"):
+            achieved = p["learning_goal"]
+        elif p.get("summary"):
+            achieved = p["summary"]
+        if achieved:
+            detail_lines.append(f"{prefix}: erreicht — {achieved}")
+
+    immediate_entry: Optional[str] = _trim_str(current_stage_start)
+    if not immediate_entry and prior_compact:
+        immediate = prior_compact[-1]
+        if immediate.get("target_state"):
+            immediate_entry = immediate["target_state"]
+        elif immediate.get("success_criteria"):
+            immediate_entry = "; ".join(immediate["success_criteria"])
+        elif immediate.get("learning_goal"):
+            immediate_entry = immediate["learning_goal"]
+        elif immediate.get("summary"):
+            immediate_entry = immediate["summary"]
+    elif not immediate_entry and start_situation:
+        immediate_entry = start_situation
+
+    entry_state = immediate_entry or start_situation
+    if prior_compact and start_situation and not immediate_entry:
+        detail_lines.insert(0, f"Ausgangsbasis Pfad: {start_situation}")
+
+    out: Dict[str, Any] = {}
+    if entry_state:
+        out["entry_state"] = _trim_str(entry_state, limit=1200)
+    if detail_lines:
+        out["entry_state_detail"] = _trim_str("\n".join(detail_lines), limit=2000)
+    if prior_compact:
+        out["prior_steps"] = prior_compact[:6]
+    if achievements:
+        out["prior_achievements"] = list(dict.fromkeys(achievements))[:8]
+    return out
+
+
+def enrich_gap_snapshot_with_entry_state(
+    snapshot: Mapping[str, Any],
+    *,
+    steps: Sequence[Mapping[str, Any]],
+    major_step_index: Optional[int],
+) -> Dict[str, Any]:
+    snap = dict(snapshot)
+    if major_step_index is None:
+        return snap
+    try:
+        mi = int(major_step_index)
+    except (TypeError, ValueError):
+        return snap
+    prior = prior_path_steps_before_major(steps, mi)
+    entry = build_progression_entry_state(
+        major_step_index=mi,
+        prior_steps=prior,
+        start_situation=snap.get("start_situation"),
+        current_stage_start=snap.get("stage_start_state"),
+    )
+    snap.update(entry)
+    return snap
+
+
 def build_progression_gap_snapshot(
     *,
     goal_analysis: Optional[Mapping[str, Any]] = None,
@@ -141,6 +298,8 @@ def build_progression_gap_snapshot(
         "stage_learning_goal": _trim_str(
             spec.get("learning_goal"), limit=1200
         ),
+        "stage_start_state": _trim_str(spec.get("start_state")),
+        "stage_target_state": _trim_str(spec.get("target_state")),
         "stage_phase": _trim_str(spec.get("phase")),
         "stage_exercise_type": _trim_str(spec.get("exercise_type")),
         "stage_load_profile": load_profile or None,
@@ -160,6 +319,7 @@ def build_progression_path_gap_planning_context(
     offer: Optional[Mapping[str, Any]] = None,
     neighbor_before: Optional[Mapping[str, Any]] = None,
     neighbor_after: Optional[Mapping[str, Any]] = None,
+    prior_path_steps: Optional[Sequence[Mapping[str, Any]]] = None,
     path_step_count: int = 0,
     major_step_count: Optional[int] = None,
     roadmap_phase: Optional[str] = None,
@@ -207,6 +367,14 @@ def build_progression_path_gap_planning_context(
         semantic_brief=semantic_brief,
     )
     ctx.update(snap)
+    if major_idx is not None and prior_path_steps:
+        ctx.update(
+            build_progression_entry_state(
+                major_step_index=major_idx,
+                prior_steps=list(prior_path_steps),
+                start_situation=ctx.get("start_situation"),
+            )
+        )
     if stage_learning_goal_override and stage_learning_goal_override.strip():
         ctx["stage_learning_goal"] = _trim_str(stage_learning_goal_override, limit=1200)
         ctx["roadmap_learning_goal"] = ctx["stage_learning_goal"]
@@ -216,8 +384,11 @@ def build_progression_path_gap_planning_context(
 
 
 __all__ = [
+    "build_progression_entry_state",
     "build_progression_gap_snapshot",
     "build_progression_path_gap_planning_context",
+    "enrich_gap_snapshot_with_entry_state",
+    "prior_path_steps_before_major",
     "compact_planning_context_json",
     "planning_context_prompt_variables",
     "sanitize_planning_context_for_ai",
diff --git a/backend/planning_exercise_path_ai_fill.py b/backend/planning_exercise_path_ai_fill.py
index c33a5bc..e798161 100644
--- a/backend/planning_exercise_path_ai_fill.py
+++ b/backend/planning_exercise_path_ai_fill.py
@@ -12,7 +12,12 @@ from ai_prompt_job import run_exercise_form_ai_suggestion
 from exercise_ai import strip_html_to_plain
 
 from planning_exercise_path_qa import find_step_pair_index
-from planning_exercise_form_context import build_progression_gap_snapshot
+from planning_exercise_form_context import (
+    build_progression_entry_state,
+    build_progression_gap_snapshot,
+    enrich_gap_snapshot_with_entry_state,
+    prior_path_steps_before_major,
+)
 from planning_exercise_semantics import PlanningSemanticBrief, brief_to_summary_dict
 
 _logger = logging.getLogger("shinkan.planning_exercise_path_ai_fill")
@@ -47,6 +52,8 @@ def _build_stage_ai_context(
     spec: Mapping[str, Any],
     step_before: Optional[Mapping[str, Any]] = None,
     step_after: Optional[Mapping[str, Any]] = None,
+    prior_steps: Optional[Sequence[Mapping[str, Any]]] = None,
+    start_situation: Optional[str] = None,
 ) -> ExerciseFormAiPromptContext:
     """KI-Kontext für unbesetzte Roadmap-Stufe (keine Brücke zwischen falschen Array-Indizes)."""
     gap = dict(spec.get("gap") or {})
@@ -59,11 +66,26 @@ def _build_stage_ai_context(
         or ""
     ).strip()
     title = (spec.get("title_hint") or f"{topic} — {phase}").strip()[:280]
+    major_idx = spec.get("roadmap_major_step_index")
+    entry: Dict[str, Any] = {}
+    if prior_steps is not None and major_idx is not None:
+        entry = build_progression_entry_state(
+            major_step_index=major_idx,
+            prior_steps=prior_steps,
+            start_situation=start_situation,
+        )
+
     goal_parts = [
         f"Planungsziel: {goal_query}",
         f"Roadmap-Stufe ({phase}): {learning_goal}",
         "Erstelle eine Übung, die dieses Stufen-Lernziel erfüllt — keine generische Brücken-Übung.",
     ]
+    if entry.get("entry_state"):
+        goal_parts.append(
+            f"Eingangszustand (erreichte Voraussetzungen): {entry['entry_state']}"
+        )
+    if entry.get("entry_state_detail") and entry.get("entry_state_detail") != entry.get("entry_state"):
+        goal_parts.append(f"Bisheriger Pfad:\n{entry['entry_state_detail']}")
     if step_before:
         goal_parts.append(
             f"Vorherige Stufe im Pfad: „{(step_before.get('title') or '').strip()}“"
@@ -106,6 +128,7 @@ def try_suggest_ai_stage_step(
     except (TypeError, ValueError):
         return None
     step_before, step_after = _resolve_neighbor_steps_by_major_index(steps, mi)
+    prior_steps = prior_path_steps_before_major(steps, mi)
     gap = dict(spec.get("gap") or {})
     if not gap.get("expected_phase"):
         gap["expected_phase"] = spec.get("phase") or "vertiefung"
@@ -119,6 +142,7 @@ def try_suggest_ai_stage_step(
         spec=spec,
         step_before=step_before,
         step_after=step_after,
+        prior_steps=prior_steps,
     )
     try:
         ai_payload = run_exercise_form_ai_suggestion(cur, ctx=ctx)
@@ -440,8 +464,16 @@ def build_gap_fill_goal_text(
         f"Planungsziel (gesamter Pfad): {goal_query}",
         f"Hauptthema: {snap.get('primary_topic') or topic}",
     ]
-    if snap.get("start_situation"):
+    if snap.get("entry_state"):
+        parts.append(
+            f"Eingangszustand (erreichte Voraussetzungen aus Vorstufen): {snap['entry_state']}"
+        )
+    if snap.get("entry_state_detail") and snap.get("entry_state_detail") != snap.get("entry_state"):
+        parts.append(f"Bisheriger Pfad:\n{snap['entry_state_detail']}")
+    if snap.get("start_situation") and not snap.get("entry_state"):
         parts.append(f"Voraussetzung / Ausgangslage (Progression): {snap['start_situation']}")
+    elif snap.get("start_situation") and snap.get("prior_steps"):
+        parts.append(f"Ausgangsbasis des gesamten Pfads: {snap['start_situation']}")
     if snap.get("target_state"):
         parts.append(f"Gesamtziel der Progression: {snap['target_state']}")
     if snap.get("roadmap_notes"):
@@ -525,6 +557,14 @@ def build_gap_fill_offer(
         step_a = steps[idx] if idx < len(steps) else None
         step_b = steps[idx + 1] if idx + 1 < len(steps) else None
     offer_id = f"{spec.get('source')}-{idx}-{uuid.uuid4().hex[:8]}"
+    enriched_snapshot = dict(roadmap_snapshot) if roadmap_snapshot else {}
+    major_raw = spec.get("roadmap_major_step_index")
+    if major_raw is not None:
+        enriched_snapshot = enrich_gap_snapshot_with_entry_state(
+            enriched_snapshot,
+            steps=steps,
+            major_step_index=major_raw,
+        )
     goal_for_ai = ""
     if brief and goal_query:
         goal_for_ai = build_gap_fill_goal_text(
@@ -533,9 +573,9 @@ def build_gap_fill_offer(
             spec=spec,
             step_a=step_a,
             step_b=step_b,
-            roadmap_snapshot=roadmap_snapshot,
+            roadmap_snapshot=enriched_snapshot or None,
         )
-    ctx_preview = dict(roadmap_snapshot) if roadmap_snapshot else None
+    ctx_preview = enriched_snapshot or None
     offer: Dict[str, Any] = {
         "offer_id": offer_id,
         "source": spec.get("source"),
diff --git a/backend/planning_exercise_path_builder.py b/backend/planning_exercise_path_builder.py
index 0855cf2..31d04f9 100644
--- a/backend/planning_exercise_path_builder.py
+++ b/backend/planning_exercise_path_builder.py
@@ -535,6 +535,9 @@ def _annotate_roadmap_step(
         step["roadmap_start_state"] = stage_spec.start_state.strip()
     if (stage_spec.target_state or "").strip():
         step["roadmap_target_state"] = stage_spec.target_state.strip()
+    if stage_spec.success_criteria:
+        step["success_criteria"] = list(stage_spec.success_criteria)
+        step["stage_success_criteria"] = list(stage_spec.success_criteria)
     step["roadmap_match_source"] = "stage_spec"
     if skill_expectations:
         step["skill_expectations"] = skill_expectations
diff --git a/backend/requirements.txt b/backend/requirements.txt
index ebc6416..a7f455a 100644
--- a/backend/requirements.txt
+++ b/backend/requirements.txt
@@ -10,5 +10,5 @@ bcrypt==4.1.3
 slowapi==0.1.9
 psycopg2-binary==2.9.9
 python-dateutil==2.9.0
-tzdata>=2024.1  # ZoneInfo (Europe/Berlin) auch unter Windows
+tzdata>=2024.1; sys_platform == "win32"  # ZoneInfo lokal; Linux/Docker: apt tzdata
 sqlparse>=0.5.0  # Migrationen: Statements splitten (Fallback ohne psql)
diff --git a/backend/tests/test_planning_exercise_form_context.py b/backend/tests/test_planning_exercise_form_context.py
index 3079065..5e0e2ba 100644
--- a/backend/tests/test_planning_exercise_form_context.py
+++ b/backend/tests/test_planning_exercise_form_context.py
@@ -1,7 +1,9 @@
 """Tests Planungs-KI Phase D — planning_context für suggestExerciseAi."""
 from planning_exercise_form_context import (
+    build_progression_entry_state,
     build_progression_gap_snapshot,
     build_progression_path_gap_planning_context,
+    enrich_gap_snapshot_with_entry_state,
     planning_context_prompt_variables,
     sanitize_planning_context_for_ai,
 )
@@ -80,6 +82,47 @@ def test_gap_planning_context_carries_snapshot_fields():
     assert ctx["stage_learning_goal"] == "Stufenziel"
 
 
+def test_build_progression_entry_state_from_prior_steps():
+    entry = build_progression_entry_state(
+        major_step_index=2,
+        prior_steps=[
+            {
+                "roadmap_major_step_index": 0,
+                "title": "Schritt-Stand",
+                "roadmap_phase": "einstieg",
+                "success_criteria": ["stabile Grundstellung"],
+            },
+            {
+                "roadmap_major_step_index": 1,
+                "title": "Mawashi Vorbereitung",
+                "roadmap_target_state": "Hüfte dreht vor dem Knie",
+                "roadmap_phase": "grundlage",
+            },
+        ],
+        start_situation="Anfänger ohne Kumite-Erfahrung",
+        current_stage_start="Hüfte dreht vor dem Knie, sicherer Stand",
+    )
+    assert entry["entry_state"] == "Hüfte dreht vor dem Knie, sicherer Stand"
+    assert "Mawashi Vorbereitung" in entry["entry_state_detail"]
+    assert "stabile Grundstellung" in entry["prior_achievements"][0]
+
+
+def test_enrich_gap_snapshot_with_entry_state():
+    snap = enrich_gap_snapshot_with_entry_state(
+        {"start_situation": "Basis", "stage_learning_goal": "Rhythmen"},
+        steps=[
+            {
+                "roadmap_major_step_index": 0,
+                "title": "A",
+                "success_criteria": ["Timing erkannt"],
+            }
+        ],
+        major_step_index=1,
+    )
+    assert snap["entry_state"] == "Timing erkannt"
+    assert snap["prior_steps"][0]["title"] == "A"
+
+
 def test_gap_planning_context_trainer_supplements_and_stage_override():
     ctx = build_progression_path_gap_planning_context(
         goal_query="Kumite",
diff --git a/backend/tests/test_planning_exercise_path_ai_fill.py b/backend/tests/test_planning_exercise_path_ai_fill.py
index 15016a9..8748b04 100644
--- a/backend/tests/test_planning_exercise_path_ai_fill.py
+++ b/backend/tests/test_planning_exercise_path_ai_fill.py
@@ -169,6 +169,36 @@ def test_build_gap_fill_offer_roadmap_unfilled_uses_major_step_neighbors():
     assert "Stufen-Lernziel" in offer["goal_for_ai"] or "Roadmap-Stufe" in offer["goal_for_ai"]
 
 
+def test_build_gap_fill_offer_includes_entry_state_from_prior_steps():
+    brief = build_semantic_brief("Kumite Beinarbeit")
+    steps = [
+        {
+            "roadmap_major_step_index": 0,
+            "title": "Schritt A",
+            "roadmap_target_state": "gleichmäßige Distanz",
+            "success_criteria": ["Partnerabstand stabil"],
+        },
+        {"roadmap_major_step_index": 2, "title": "Schritt C"},
+    ]
+    offer = build_gap_fill_offer(
+        spec={
+            "source": "roadmap_unfilled",
+            "phase": "vertiefung",
+            "title_hint": "Rhythmen",
+            "roadmap_major_step_index": 1,
+        },
+        steps=steps,
+        goal_query="Kumite Beinarbeit",
+        brief=brief,
+        roadmap_snapshot={
+            "start_situation": "Steppbewegung",
+            "stage_learning_goal": "variable Rhythmen",
+        },
+    )
+    assert offer["context_preview"]["entry_state"] == "gleichmäßige Distanz"
+    assert "Eingangszustand" in offer["goal_for_ai"]
+
+
 def test_build_gap_fill_offer_exposes_context_preview():
     brief = build_semantic_brief("Kumite Beinarbeit")
     offer = build_gap_fill_offer(
diff --git a/frontend/src/components/ProgressionGraphEditor.jsx b/frontend/src/components/ProgressionGraphEditor.jsx
index 78bee4c..7d5a20f 100644
--- a/frontend/src/components/ProgressionGraphEditor.jsx
+++ b/frontend/src/components/ProgressionGraphEditor.jsx
@@ -16,6 +16,7 @@ import {
 } from '../utils/exerciseAiQuickCreate'
 import {
   buildPathGapPlanningContextForAi,
+  buildSlotGapGoalForAi,
   gapOfferContextDisplayLines,
   initialStageLearningGoalFromOffer,
 } from '../utils/planningContextForExerciseAi'
@@ -527,15 +528,23 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
 
   const slotOfferContext = (slotIndex) => {
     const slot = draft?.slots?.[slotIndex]
-    if (!slot) return null
+    if (!draft || !slot) return null
+    const goalForAi =
+      buildSlotGapGoalForAi(draft, slotIndex, { goalQuery: draft.goalQuery }) ||
+      slot.learning_goal
+    const priorSlot =
+      slotIndex > 0 && draft.slots[slotIndex - 1]
+        ? draft.slots[slotIndex - 1]
+        : null
     return {
       offer_id: `slot-${slotIndex}`,
       title_hint: slot.primary?.exerciseTitle || slot.learning_goal,
       roadmap_major_step_index: slot.majorStepIndex,
       phase: slot.phase,
       source: 'roadmap_unfilled',
-      goal_for_ai: slot.learning_goal,
-      sketch: slot.learning_goal,
+      goal_for_ai: goalForAi,
+      sketch: goalForAi,
+      from_title: priorSlot?.primary?.exerciseTitle || null,
     }
   }
 
diff --git a/frontend/src/utils/planningContextForExerciseAi.js b/frontend/src/utils/planningContextForExerciseAi.js
index bc77f9e..1d1da9e 100644
--- a/frontend/src/utils/planningContextForExerciseAi.js
+++ b/frontend/src/utils/planningContextForExerciseAi.js
@@ -2,6 +2,8 @@
  * Planungs-KI Phase D: strukturierter Kontext für suggestExerciseAi.
  */
 
+import { slotsAsPathStepRows } from './progressionGraphDraft.js'
+
 export function buildPickerPlanningContextForAi({
   planningContextSummary = null,
   planningContext = null,
@@ -30,6 +32,109 @@ export function buildPickerPlanningContextForAi({
   return Object.fromEntries(Object.entries(ctx).filter(([, v]) => v != null && v !== ''))
 }
 
+function majorIndexFromStep(step) {
+  const raw = step?.roadmap_major_step_index ?? step?.roadmapMajorStepIndex
+  if (raw == null || !Number.isFinite(Number(raw))) return null
+  return Number(raw)
+}
+
+function priorPathStepsBeforeMajor(pathSteps, majorIdx) {
+  if (majorIdx == null || !Number.isFinite(Number(majorIdx))) return []
+  const mi = Number(majorIdx)
+  return (pathSteps || [])
+    .filter((s) => {
+      const idx = majorIndexFromStep(s)
+      return idx != null && idx < mi
+    })
+    .sort((a, b) => (majorIndexFromStep(a) || 0) - (majorIndexFromStep(b) || 0))
+}
+
+function stepDisplayFields(step) {
+  if (!step) return null
+  const title = String(step.title || step.exerciseTitle || '').trim()
+  const learningGoal = String(
+    step.roadmap_learning_goal || step.roadmapLearningGoal || step.learning_goal || '',
+  ).trim()
+  const phase = String(step.roadmap_phase || step.roadmapPhase || step.phase || '').trim()
+  const startState = String(step.roadmap_start_state || step.start_state || '').trim()
+  const targetState = String(step.roadmap_target_state || step.target_state || '').trim()
+  const criteria = Array.isArray(step.success_criteria)
+    ? step.success_criteria.map((x) => String(x || '').trim()).filter(Boolean).slice(0, 4)
+    : []
+  const majorStepIndex = majorIndexFromStep(step)
+  const out = {
+    title: title || null,
+    learning_goal: learningGoal || null,
+    start_state: startState || null,
+    target_state: targetState || null,
+    phase: phase || null,
+    success_criteria: criteria.length ? criteria : null,
+    major_step_index: majorStepIndex,
+  }
+  const hasData = Object.values(out).some((v) => v != null && v !== '')
+  return hasData ? out : null
+}
+
+export function buildProgressionEntryState({
+  majorStepIndex = null,
+  priorSteps = [],
+  startSituation = '',
+  currentStageStart = '',
+} = {}) {
+  const priorCompact = (priorSteps || [])
+    .map(stepDisplayFields)
+    .filter(Boolean)
+
+  const achievements = []
+  const detailLines = []
+  for (const p of priorCompact) {
+    if (Array.isArray(p.success_criteria) && p.success_criteria.length) {
+      achievements.push(...p.success_criteria)
+    } else if (p.learning_goal) {
+      achievements.push(p.learning_goal)
+    }
+
+    const labelParts = []
+    if (p.major_step_index != null) labelParts.push(`Stufe ${p.major_step_index + 1}`)
+    if (p.phase) labelParts.push(`(${p.phase})`)
+    if (p.title) labelParts.push(`„${p.title}"`)
+    const prefix = labelParts.length ? labelParts.join(' ') : 'Vorstufe'
+    const achieved =
+      p.target_state ||
+      (Array.isArray(p.success_criteria) && p.success_criteria.length
+        ? p.success_criteria.join('; ')
+        : '') ||
+      p.learning_goal ||
+      ''
+    if (achieved) detailLines.push(`${prefix}: erreicht — ${achieved}`)
+  }
+
+  let entryState = (currentStageStart || '').trim()
+  if (!entryState && priorCompact.length) {
+    const immediate = priorCompact[priorCompact.length - 1]
+    entryState =
+      immediate.target_state ||
+      (Array.isArray(immediate.success_criteria) && immediate.success_criteria.length
+        ? immediate.success_criteria.join('; ')
+        : '') ||
+      immediate.learning_goal ||
+      ''
+  } else if (!entryState && (startSituation || '').trim()) {
+    entryState = startSituation.trim()
+  }
+
+  if (priorCompact.length && (startSituation || '').trim() && !entryState) {
+    detailLines.unshift(`Ausgangsbasis Pfad: ${startSituation.trim()}`)
+  }
+
+  const out = {}
+  if (entryState) out.entry_state = entryState
+  if (detailLines.length) out.entry_state_detail = detailLines.join('\n')
+  if (priorCompact.length) out.prior_steps = priorCompact.slice(0, 6)
+  if (achievements.length) out.prior_achievements = [...new Set(achievements)].slice(0, 8)
+  return out
+}
+
 function stageSpecForMajorIndex(progressionRoadmap, majorIdx) {
   if (majorIdx == null || !progressionRoadmap) return null
   const specs = progressionRoadmap?.stage_specs
@@ -56,14 +161,25 @@ export function buildPathGapPlanningContextForAi({
   stageLearningGoalOverride = '',
   gapTrainerSupplements = '',
 } = {}) {
-  const afterIdx = Number(offer?.insert_after_index)
-  const stepA = Number.isFinite(afterIdx) && afterIdx >= 0 ? pathSteps[afterIdx] : null
-  const stepB =
-    Number.isFinite(afterIdx) && afterIdx >= 0 ? pathSteps[afterIdx + 1] : null
   const majorIdxRaw =
     offer?.roadmap_major_step_index ?? offer?.gap?.roadmap_major_step_index
   const majorIdx =
     majorIdxRaw != null && Number.isFinite(Number(majorIdxRaw)) ? Number(majorIdxRaw) : null
+  const priorSteps = majorIdx != null ? priorPathStepsBeforeMajor(pathSteps, majorIdx) : []
+  const afterIdx = Number(offer?.insert_after_index)
+  const stepA =
+    priorSteps.length > 0
+      ? priorSteps[priorSteps.length - 1]
+      : Number.isFinite(afterIdx) && afterIdx >= 0
+        ? pathSteps[afterIdx]
+        : null
+  const stepB =
+    majorIdx != null
+      ? (pathSteps || []).find((s) => majorIndexFromStep(s) === majorIdx + 1) ||
+        (Number.isFinite(afterIdx) && afterIdx >= 0 ? pathSteps[afterIdx + 1] : null)
+      : Number.isFinite(afterIdx) && afterIdx >= 0
+        ? pathSteps[afterIdx + 1]
+        : null
   const majorStep =
     majorIdx != null && editableMajorSteps[majorIdx] ? editableMajorSteps[majorIdx] : null
   const stageSpec = stageSpecForMajorIndex(progressionRoadmap, majorIdx)
@@ -92,6 +208,13 @@ export function buildPathGapPlanningContextForAi({
     )
   }
 
+  const entryState = buildProgressionEntryState({
+    majorStepIndex: majorIdx,
+    priorSteps,
+    startSituation: start,
+    currentStageStart: stageSpec?.start_state || '',
+  })
+
   const ctx = {
     source: 'progression_path_gap_fill',
     goal_query: (goalQuery || '').trim() || null,
@@ -109,6 +232,8 @@ export function buildPathGapPlanningContextForAi({
     roadmap_notes: notes,
     stage_learning_goal:
       (stageLearningGoalOverride || '').trim() || stageSpec?.learning_goal || null,
+    stage_start_state: stageSpec?.start_state || null,
+    stage_target_state: stageSpec?.target_state || null,
     gap_trainer_supplements: (gapTrainerSupplements || '').trim() || null,
     stage_phase: stageSpec?.phase || majorStep?.phase || null,
     stage_exercise_type: stageSpec?.exercise_type || null,
@@ -125,8 +250,9 @@ export function buildPathGapPlanningContextForAi({
       ? ga.success_criteria.slice(0, 4)
       : null,
     skill_hints: skillHints.length ? skillHints : null,
-    neighbor_before_title: stepA?.exerciseTitle || offer?.from_title || null,
-    neighbor_after_title: stepB?.exerciseTitle || offer?.to_title || null,
+    neighbor_before_title: stepA?.exerciseTitle || stepA?.title || offer?.from_title || null,
+    neighbor_after_title: stepB?.exerciseTitle || stepB?.title || offer?.to_title || null,
+    ...entryState,
     path_step_count: Array.isArray(pathSteps) ? pathSteps.length : 0,
     major_step_count:
       editableMajorSteps?.length ||
@@ -148,7 +274,14 @@ export function gapOfferContextDisplayLines(offer, fallbackParams = null) {
     const v = String(value || '').trim()
     if (v) lines.push({ label, value: v })
   }
-  push('Ausgangslage (Pfad)', raw.start_situation)
+  push('Eingangszustand (Vorstufen)', raw.entry_state)
+  if (raw.entry_state_detail && raw.entry_state_detail !== raw.entry_state) {
+    push('Bisheriger Pfad', raw.entry_state_detail)
+  }
+  if (Array.isArray(raw.prior_achievements) && raw.prior_achievements.length) {
+    push('Erreichte Voraussetzungen', raw.prior_achievements.slice(0, 6).join(' · '))
+  }
+  push('Ausgangslage (gesamter Pfad)', raw.start_situation)
   push('Gesamtziel (Pfad)', raw.target_state)
   push('Ergänzungen', raw.roadmap_notes)
   push('Stufen-Lernziel', raw.stage_learning_goal || raw.roadmap_learning_goal)
@@ -173,6 +306,43 @@ export function gapOfferContextDisplayLines(offer, fallbackParams = null) {
   return lines
 }
 
+/** Zieltext für KI aus Slot-Kontext (Graph-Editor ohne API-Offer). */
+export function buildSlotGapGoalForAi(draft, slotIndex, { goalQuery = '' } = {}) {
+  const slot = draft?.slots?.[slotIndex]
+  if (!slot) return ''
+  const pathSteps = slotsAsPathStepRows(draft)
+  const majorIdx = slot.majorStepIndex
+  const priorSteps = priorPathStepsBeforeMajor(pathSteps, majorIdx)
+  const start = (draft.startSituation || '').trim()
+  const stageSpec =
+    majorIdx != null && draft.progressionRoadmap
+      ? stageSpecForMajorIndex(draft.progressionRoadmap, majorIdx)
+      : null
+  const entry = buildProgressionEntryState({
+    majorStepIndex: majorIdx,
+    priorSteps,
+    startSituation: start,
+    currentStageStart: stageSpec?.start_state || '',
+  })
+  const parts = [
+    goalQuery ? `Planungsziel (gesamter Pfad): ${goalQuery}` : '',
+    entry.entry_state
+      ? `Eingangszustand (erreichte Voraussetzungen): ${entry.entry_state}`
+      : start
+        ? `Ausgangslage (Pfad): ${start}`
+        : '',
+    entry.entry_state_detail && entry.entry_state_detail !== entry.entry_state
+      ? `Bisheriger Pfad:\n${entry.entry_state_detail}`
+      : '',
+    (slot.learning_goal || '').trim()
+      ? `Lernziel dieser Roadmap-Stufe: ${(slot.learning_goal || '').trim()}`
+      : '',
+    (slot.phase || '').trim() ? `Entwicklungsphase: ${slot.phase}` : '',
+    'Die Übung baut didaktisch auf den Vorstufen auf — Voraussetzungen explizit benennen, messbares Stufenziel.',
+  ].filter(Boolean)
+  return parts.join('\n\n').trim()
+}
+
 export function initialStageLearningGoalFromOffer(offer, fallbackParams = null) {
   const lines = gapOfferContextDisplayLines(offer, fallbackParams)
   const hit = lines.find((l) => l.label === 'Stufen-Lernziel')
diff --git a/frontend/src/utils/progressionGraphDraft.js b/frontend/src/utils/progressionGraphDraft.js
index dd7bf38..3a2707a 100644
--- a/frontend/src/utils/progressionGraphDraft.js
+++ b/frontend/src/utils/progressionGraphDraft.js
@@ -280,9 +280,15 @@ export function slotsAsPathStepRows(draft) {
   return (draft.slots || []).map((slot) => ({
     exerciseId: slot.primary?.exerciseId ?? null,
     exerciseTitle: slot.primary?.exerciseTitle || '',
+    title: slot.primary?.exerciseTitle || '',
+    roadmap_major_step_index: slot.majorStepIndex,
     roadmapMajorStepIndex: slot.majorStepIndex,
+    roadmap_phase: slot.phase,
     roadmapPhase: slot.phase,
+    roadmap_learning_goal: slot.learning_goal,
     roadmapLearningGoal: slot.learning_goal,
+    learning_goal: slot.learning_goal,
+    success_criteria: Array.isArray(slot.success_criteria) ? slot.success_criteria : [],
     isAiProposal: slot.primary?.kind === 'proposal',
   }))
 }

From 7203c871fc12a1de386859c17f4057737604df77 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Thu, 11 Jun 2026 12:02:04 +0200
Subject: [PATCH 26/33] Add Slot Assignments and Enhance Path Handling Logic

- Introduced `slot_assignments` to `ProgressionPathSuggestRequest` for improved handling of existing slot assignments in path building.
- Implemented `_slot_assignments_by_major_index` and `_path_step_from_slot_assignment` functions to facilitate the integration of slot assignments into the path generation process.
- Updated `_build_steps_roadmap_first` to utilize slot assignments, enhancing the accuracy of path steps based on existing exercise slots.
- Enhanced `detect_path_gaps` to skip empty slots, preventing unnecessary errors during gap detection.
- Added tests to validate the new slot assignment handling and ensure robustness in path generation logic.
---
 backend/planning_exercise_path_builder.py     | 68 +++++++++++++++++++
 backend/planning_exercise_path_qa.py          |  2 +
 .../tests/test_planning_exercise_path_qa.py   | 36 ++++++++++
 .../src/components/ProgressionGraphEditor.jsx |  2 +
 frontend/src/utils/progressionGraphDraft.js   | 21 +++++-
 5 files changed, 128 insertions(+), 1 deletion(-)

diff --git a/backend/planning_exercise_path_builder.py b/backend/planning_exercise_path_builder.py
index 31d04f9..9316f41 100644
--- a/backend/planning_exercise_path_builder.py
+++ b/backend/planning_exercise_path_builder.py
@@ -115,6 +115,7 @@ class ProgressionPathSuggestRequest(BaseModel):
     start_target_only: bool = False
     evaluate_only: bool = False
     evaluate_steps: Optional[List[EvaluateStepPayload]] = None
+    slot_assignments: Optional[List[EvaluateStepPayload]] = None
     roadmap_override: Optional[RoadmapOverridePayload] = None
     start_situation: Optional[str] = Field(default=None, max_length=2000)
     target_state: Optional[str] = Field(default=None, max_length=2000)
@@ -262,6 +263,52 @@ def _build_path_target_profile(
     return target, query_intent_summary, intent
 
 
+def _slot_assignments_by_major_index(
+    assignments: Optional[List[EvaluateStepPayload]],
+) -> Dict[int, EvaluateStepPayload]:
+    out: Dict[int, EvaluateStepPayload] = {}
+    for raw in assignments or []:
+        if raw.exercise_id is None or raw.roadmap_major_step_index is None:
+            continue
+        out[int(raw.roadmap_major_step_index)] = raw
+    return out
+
+
+def _path_step_from_slot_assignment(
+    cur,
+    *,
+    assignment: EvaluateStepPayload,
+    stage_spec: StageSpecArtifact,
+    major_step: Optional[MajorStep],
+) -> Optional[Dict[str, Any]]:
+    """Bestehende Slot-Zuordnung aus dem Graph-Editor (nach KI-Anlage) übernehmen."""
+    eid = int(assignment.exercise_id)
+    cur.execute(
+        "SELECT id, title, summary FROM exercises WHERE id = %s",
+        (eid,),
+    )
+    row = cur.fetchone()
+    if not row:
+        return None
+    title = (assignment.title or row.get("title") or "").strip() or str(row.get("title") or "")
+    step = {
+        "exercise_id": eid,
+        "variant_id": assignment.variant_id,
+        "title": title,
+        "summary": row.get("summary"),
+        "score": None,
+        "semantic_score": None,
+        "reasons": ["Bestehende Slot-Zuordnung (Graph-Editor)"],
+        "variants": [],
+        "slot_assignment": True,
+    }
+    return _annotate_roadmap_step(
+        step,
+        stage_spec=stage_spec,
+        major_step=major_step,
+    )
+
+
 def _hit_to_path_step(hit: Dict[str, Any], *, is_bridge: bool = False) -> Dict[str, Any]:
     raw_vid = hit.get("suggested_variant_id")
     variant_id: Optional[int] = None
@@ -873,8 +920,29 @@ def _build_steps_roadmap_first(
     anchor_variant_id: Optional[int] = None
     unfilled: List[Tuple[int, StageSpecArtifact]] = []
     stage_count = len(stage_specs)
+    assignments = _slot_assignments_by_major_index(body.slot_assignments)
+    majors_by_index: Dict[int, MajorStep] = {}
+    if roadmap_ctx.roadmap:
+        majors_by_index = {m.index: m for m in roadmap_ctx.roadmap.major_steps}
 
     for step_index, stage_spec in enumerate(stage_specs):
+        major_idx = stage_spec.major_step_index
+        if major_idx in assignments:
+            pinned = _path_step_from_slot_assignment(
+                cur,
+                assignment=assignments[major_idx],
+                stage_spec=stage_spec,
+                major_step=majors_by_index.get(major_idx),
+            )
+            if pinned:
+                steps.append(pinned)
+                eid = int(pinned["exercise_id"])
+                used.add(eid)
+                planned_ids.append(eid)
+                anchor_id = eid
+                anchor_variant_id = pinned.get("variant_id")
+                continue
+
         step, unfilled_spec = _match_roadmap_slot(
             cur,
             tenant=tenant,
diff --git a/backend/planning_exercise_path_qa.py b/backend/planning_exercise_path_qa.py
index f0cb034..d3e50a7 100644
--- a/backend/planning_exercise_path_qa.py
+++ b/backend/planning_exercise_path_qa.py
@@ -182,6 +182,8 @@ def detect_path_gaps(
     for i in range(total_segments):
         step_a = steps[i]
         step_b = steps[i + 1]
+        if step_a.get("exercise_id") is None or step_b.get("exercise_id") is None:
+            continue
         if roadmap_first and is_roadmap_planned_neighbor_pair(step_a, step_b):
             continue
         gap = measure_step_transition_gap(
diff --git a/backend/tests/test_planning_exercise_path_qa.py b/backend/tests/test_planning_exercise_path_qa.py
index 929e187..f6a8d8a 100644
--- a/backend/tests/test_planning_exercise_path_qa.py
+++ b/backend/tests/test_planning_exercise_path_qa.py
@@ -106,6 +106,42 @@ def test_detect_path_gaps_skips_roadmap_neighbors():
     assert gaps == []
 
 
+def test_detect_path_gaps_skips_empty_slots():
+    """Graph-Bewertung: leere Slots dürfen keinen 500er durch Übergangs-Lücken auslösen."""
+    brief = build_semantic_brief("Mawashi Geri Kumite")
+    steps = [
+        {
+            "exercise_id": 10,
+            "title": "Stand",
+            "roadmap_major_step_index": 0,
+        },
+        {
+            "exercise_id": None,
+            "title": "(leer: Slot 2)",
+            "is_ai_proposal": True,
+            "roadmap_major_step_index": 1,
+        },
+        {
+            "exercise_id": 11,
+            "title": "Anwendung",
+            "roadmap_major_step_index": 2,
+        },
+    ]
+
+    class _FakeCur:
+        def execute(self, *args, **kwargs):
+            return None
+
+        def fetchall(self):
+            return []
+
+        def fetchone(self):
+            return {"title": "X", "summary": "", "goal": ""}
+
+    gaps = detect_path_gaps(_FakeCur(), steps, brief=brief, roadmap_first=True)
+    assert isinstance(gaps, list)
+
+
 def test_apply_llm_path_reorder_invalid_ignored():
     steps = [{"exercise_id": 1}, {"exercise_id": 2}]
     reordered, applied, _ = apply_llm_path_reorder(steps, {"ordered_step_indices": [0, 0]})
diff --git a/frontend/src/components/ProgressionGraphEditor.jsx b/frontend/src/components/ProgressionGraphEditor.jsx
index 7d5a20f..8687fd5 100644
--- a/frontend/src/components/ProgressionGraphEditor.jsx
+++ b/frontend/src/components/ProgressionGraphEditor.jsx
@@ -41,6 +41,7 @@ import {
   SLOT_MAX,
   slotsAsPathStepRows,
   slotsToEvaluateSteps,
+  slotsToSlotAssignments,
   syncProgressionRoadmapFromSlots,
   syncSlotPhasesFromRoadmap,
 } from '../utils/progressionGraphDraft'
@@ -414,6 +415,7 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
         include_llm_roadmap: false,
         roadmap_first: true,
         roadmap_override: override,
+        slot_assignments: slotsToSlotAssignments(synced),
         progression_graph_id: Number(graphId),
         ...roadmapStructuredPayload(draft.startSituation, draft.targetState, draft.roadmapNotes),
       })
diff --git a/frontend/src/utils/progressionGraphDraft.js b/frontend/src/utils/progressionGraphDraft.js
index 3a2707a..3cd9ab4 100644
--- a/frontend/src/utils/progressionGraphDraft.js
+++ b/frontend/src/utils/progressionGraphDraft.js
@@ -712,6 +712,21 @@ export function draftSiblingEdgePairs(draft) {
   return pairs
 }
 
+/** Bereits zugeordnete Bibliotheks-Übungen für Re-Match (Pins). */
+export function slotsToSlotAssignments(draft) {
+  return (draft.slots || [])
+    .filter((slot) => slot.primary?.kind === 'library' && slot.primary.exerciseId != null)
+    .map((slot) => ({
+      exercise_id: slot.primary.exerciseId,
+      variant_id: slot.primary.variantId || null,
+      title: slot.primary.exerciseTitle || null,
+      is_ai_proposal: false,
+      roadmap_major_step_index: slot.majorStepIndex,
+      roadmap_phase: slot.phase || null,
+      roadmap_learning_goal: slot.learning_goal || null,
+    }))
+}
+
 export function slotsToEvaluateSteps(draft) {
   return (draft.slots || []).map((slot) => {
     const p = slot.primary
@@ -789,7 +804,11 @@ export function applyMatchStepsToSlots(draft, apiSteps) {
 
   for (let i = 0; i < nextSlots.length; i += 1) {
     if (!touchedMajors.has(i)) {
-      nextSlots[i].primary = emptySlotExercise()
+      const keep =
+        nextSlots[i].primary?.kind === 'library' && nextSlots[i].primary.exerciseId != null
+      if (!keep) {
+        nextSlots[i].primary = emptySlotExercise()
+      }
     }
   }
 

From b464047c3aa3a7655758ae0503321425a9751db1 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Thu, 11 Jun 2026 12:10:46 +0200
Subject: [PATCH 27/33] Enhance Exercise Progression Graph Functionality and
 Visibility Logic

- Introduced new functions for handling exercise visibility in progression graphs, including `library_content_visibility_for_progression_graph_sql` to manage visibility based on graph context.
- Added `_supplemental_exercise_ids_from_body` to extract exercise IDs from request bodies, improving data handling in path suggestions.
- Implemented visibility promotion candidate retrieval in the API, allowing for the identification of private exercises that need visibility adjustments when promoting graph visibility.
- Enhanced existing SQL queries and retrieval functions to incorporate new visibility logic, ensuring accurate exercise visibility based on user roles and graph settings.
- Updated frontend components to support visibility promotion workflows, including user prompts for managing private exercises during graph visibility changes.
- Added tests to validate new visibility logic and ensure robustness in exercise retrieval and promotion processes.
---
 backend/planning_exercise_path_builder.py     | 128 ++++++++++++++++--
 backend/planning_exercise_retrieval.py        |  57 ++++++++
 .../routers/exercise_progression_graphs.py    | 122 +++++++++++++++++
 backend/tenant_context.py                     |  51 +++++++
 backend/tests/test_access_layer.py            |  38 +++++-
 frontend/src/api/exercises.js                 |  10 ++
 .../ExerciseProgressionGraphPanel.jsx         |  52 ++++++-
 7 files changed, 447 insertions(+), 11 deletions(-)

diff --git a/backend/planning_exercise_path_builder.py b/backend/planning_exercise_path_builder.py
index 9316f41..8b6157d 100644
--- a/backend/planning_exercise_path_builder.py
+++ b/backend/planning_exercise_path_builder.py
@@ -11,7 +11,11 @@ from typing import Any, Callable, Dict, List, Mapping, Optional, Set, Tuple
 from fastapi import HTTPException
 from pydantic import BaseModel, Field
 
-from tenant_context import TenantContext, library_content_visibility_sql
+from tenant_context import (
+    TenantContext,
+    library_content_visibility_for_progression_graph_sql,
+    library_content_visibility_sql,
+)
 from planning_exercise_profiles import PlanningTargetProfile
 from planning_path_qa_pipeline import run_multistage_path_qa
 from planning_path_rematch import (
@@ -263,6 +267,90 @@ def _build_path_target_profile(
     return target, query_intent_summary, intent
 
 
+def _supplemental_exercise_ids_from_body(body: ProgressionPathSuggestRequest) -> List[int]:
+    """Verankerte Graph-Slots immer im Retriever-Kandidatenpool halten."""
+    ids: List[int] = []
+    for coll in (body.slot_assignments, body.evaluate_steps):
+        for raw in coll or []:
+            if raw.exercise_id is not None:
+                try:
+                    eid = int(raw.exercise_id)
+                except (TypeError, ValueError):
+                    continue
+                if eid > 0:
+                    ids.append(eid)
+    return list(dict.fromkeys(ids))
+
+
+def _planning_visibility_sql(
+    cur,
+    tenant: TenantContext,
+    progression_graph_id: Optional[int],
+) -> Tuple[str, List[Any]]:
+    if progression_graph_id and int(progression_graph_id) > 0:
+        cur.execute(
+            "SELECT visibility, club_id FROM exercise_progression_graphs WHERE id = %s",
+            (int(progression_graph_id),),
+        )
+        grow = cur.fetchone()
+        if grow:
+            g_club = grow.get("club_id")
+            return library_content_visibility_for_progression_graph_sql(
+                alias="e",
+                profile_id=tenant.profile_id,
+                role=tenant.global_role,
+                effective_club_id=tenant.effective_club_id,
+                graph_visibility=str(grow.get("visibility") or "private"),
+                graph_club_id=int(g_club) if g_club is not None else None,
+            )
+    return library_content_visibility_sql(
+        alias="e",
+        profile_id=tenant.profile_id,
+        role=tenant.global_role,
+        effective_club_id=tenant.effective_club_id,
+    )
+
+
+def _exercise_allowed_in_progression_graph(
+    exercise_row: Mapping[str, Any],
+    *,
+    graph_visibility: str,
+    graph_club_id: Optional[int],
+    profile_id: int,
+    role: str,
+) -> bool:
+    """Prüft, ob eine Übung zur Sichtbarkeit des Progressionsgraphen passt."""
+    from club_tenancy import is_platform_admin
+
+    ex_vis = (exercise_row.get("visibility") or "private").strip().lower()
+    gvis = (graph_visibility or "private").strip().lower()
+    if gvis == "private":
+        if ex_vis == "official":
+            return True
+        if ex_vis == "club":
+            return True
+        if ex_vis == "private":
+            if is_platform_admin(role):
+                return True
+            try:
+                return int(exercise_row.get("created_by") or 0) == int(profile_id)
+            except (TypeError, ValueError):
+                return False
+        return False
+    if gvis == "club":
+        if ex_vis == "official":
+            return True
+        if ex_vis != "club":
+            return False
+        ex_club = exercise_row.get("club_id")
+        if ex_club is None:
+            return False
+        if graph_club_id is None:
+            return True
+        return int(ex_club) == int(graph_club_id)
+    return ex_vis == "official"
+
+
 def _slot_assignments_by_major_index(
     assignments: Optional[List[EvaluateStepPayload]],
 ) -> Dict[int, EvaluateStepPayload]:
@@ -280,16 +368,32 @@ def _path_step_from_slot_assignment(
     assignment: EvaluateStepPayload,
     stage_spec: StageSpecArtifact,
     major_step: Optional[MajorStep],
+    tenant: Optional[TenantContext] = None,
+    progression_graph_id: Optional[int] = None,
 ) -> Optional[Dict[str, Any]]:
     """Bestehende Slot-Zuordnung aus dem Graph-Editor (nach KI-Anlage) übernehmen."""
     eid = int(assignment.exercise_id)
     cur.execute(
-        "SELECT id, title, summary FROM exercises WHERE id = %s",
+        "SELECT id, title, summary, visibility, club_id, created_by FROM exercises WHERE id = %s",
         (eid,),
     )
     row = cur.fetchone()
     if not row:
         return None
+    if tenant and progression_graph_id:
+        cur.execute(
+            "SELECT visibility, club_id FROM exercise_progression_graphs WHERE id = %s",
+            (int(progression_graph_id),),
+        )
+        grow = cur.fetchone()
+        if grow and not _exercise_allowed_in_progression_graph(
+            row,
+            graph_visibility=str(grow.get("visibility") or "private"),
+            graph_club_id=int(grow["club_id"]) if grow.get("club_id") is not None else None,
+            profile_id=tenant.profile_id,
+            role=tenant.global_role,
+        ):
+            return None
     title = (assignment.title or row.get("title") or "").strip() or str(row.get("title") or "")
     step = {
         "exercise_id": eid,
@@ -366,6 +470,7 @@ def _run_path_step_retrieval(
     path_context_note: Optional[str] = None,
     path_primary_topic: Optional[str] = None,
     path_technique_excludes: Optional[List[str]] = None,
+    supplemental_exercise_ids: Optional[List[int]] = None,
 ) -> Tuple[List[Dict[str, Any]], PlanningTargetProfile, Dict[str, Any], str]:
     step_query = step_query_override or step_retrieval_query(
         semantic_brief, goal_query, step_index, max_steps
@@ -469,13 +574,10 @@ def _run_path_step_retrieval(
     else:
         weights = apply_path_retrieval_weights(semantic_brief)
 
-    profile_id = tenant.profile_id
-    role = tenant.global_role
-    vis_sql, vis_params = library_content_visibility_sql(
-        alias="e",
-        profile_id=profile_id,
-        role=role,
-        effective_club_id=tenant.effective_club_id,
+    vis_sql, vis_params = _planning_visibility_sql(
+        cur,
+        tenant,
+        progression_graph_id,
     )
 
     hits, _skills_by_ex, _full_lib = run_multistage_planning_retrieval(
@@ -488,6 +590,7 @@ def _run_path_step_retrieval(
         intent=intent,
         intent_weights=weights,
         pack=pack,
+        supplemental_exercise_ids=supplemental_exercise_ids,
     )
     hits = _enrich_planning_hits_with_variant_meta(cur, hits[:32])
     return hits, target_profile, query_intent_summary, intent
@@ -506,6 +609,7 @@ def _make_bridge_search_fn(
     planned_ids: List[int],
     path_target_profile: PlanningTargetProfile,
     path_intent: str,
+    supplemental_exercise_ids: Optional[List[int]] = None,
 ) -> Callable[..., List[Dict[str, Any]]]:
     def _bridge_search(
         step_a: Dict[str, Any],
@@ -529,6 +633,7 @@ def _make_bridge_search_fn(
             step_a=step_a,
             step_b=step_b,
             path_target_profile=path_target_profile,
+            supplemental_exercise_ids=supplemental_exercise_ids,
             path_intent=path_intent,
         )
         gated = [
@@ -740,6 +845,7 @@ def _match_roadmap_slot(
         path_context_note=path_context_note,
         path_primary_topic=path_primary or None,
         path_technique_excludes=path_tech_excludes or None,
+        supplemental_exercise_ids=_supplemental_exercise_ids_from_body(body),
     )
 
     hit = _pick_best_path_hit(
@@ -933,6 +1039,8 @@ def _build_steps_roadmap_first(
                 assignment=assignments[major_idx],
                 stage_spec=stage_spec,
                 major_step=majors_by_index.get(major_idx),
+                tenant=tenant,
+                progression_graph_id=body.progression_graph_id,
             )
             if pinned:
                 steps.append(pinned)
@@ -1471,6 +1579,7 @@ def suggest_progression_path(
                 semantic_brief=semantic_brief,
                 path_target_profile=path_target_profile,
                 path_intent=path_intent,
+                supplemental_exercise_ids=_supplemental_exercise_ids_from_body(body),
             )
 
             hit = _pick_best_path_hit(hits, used, semantic_brief=semantic_brief)
@@ -1531,6 +1640,7 @@ def suggest_progression_path(
                 planned_ids=planned_ids,
                 path_target_profile=path_target_profile,
                 path_intent=path_intent,
+                supplemental_exercise_ids=_supplemental_exercise_ids_from_body(body),
             )
             steps, bridge_inserts, unfilled_gaps = insert_bridge_exercises(
                 cur,
diff --git a/backend/planning_exercise_retrieval.py b/backend/planning_exercise_retrieval.py
index 6b748b1..da71d8a 100644
--- a/backend/planning_exercise_retrieval.py
+++ b/backend/planning_exercise_retrieval.py
@@ -58,6 +58,52 @@ def _normalize_exercise_kind_filter(exercise_kind_any: Optional[List[str]]) -> L
     return out
 
 
+def fetch_exercise_rows_by_ids(
+    cur,
+    exercise_ids: Sequence[int],
+    *,
+    vis_sql: str,
+    vis_params: Sequence[Any],
+) -> List[Dict[str, Any]]:
+    """Lädt konkrete Übungen nach, wenn sie im Graph/Slot verankert sind (Pin-Sicherheit)."""
+    ids = sorted({int(x) for x in exercise_ids if int(x) > 0})
+    if not ids:
+        return []
+    ph = ",".join(["%s"] * len(ids))
+    sql = f"""
+        SELECT e.id, e.title, e.summary, e.method_archetype,
+               (
+                 SELECT fa.name FROM exercise_focus_areas efa
+                 JOIN focus_areas fa ON fa.id = efa.focus_area_id
+                 WHERE efa.exercise_id = e.id
+                 ORDER BY efa.is_primary DESC NULLS LAST, fa.name ASC
+                 LIMIT 1
+               ) AS primary_focus_name,
+               0.0::float AS ft_rank
+        FROM exercises e
+        WHERE e.id IN ({ph})
+          AND ({vis_sql})
+          AND COALESCE(e.status, '') <> %s
+    """
+    params: List[Any] = list(ids) + list(vis_params) + ["archived"]
+    cur.execute(sql, params)
+    return [dict(r) for r in cur.fetchall()]
+
+
+def merge_supplemental_exercise_rows(
+    rows: Sequence[Dict[str, Any]],
+    supplemental: Sequence[Dict[str, Any]],
+) -> List[Dict[str, Any]]:
+    seen = {int(r["id"]) for r in rows if r.get("id") is not None}
+    out = list(rows)
+    for row in supplemental:
+        rid = int(row["id"])
+        if rid not in seen:
+            seen.add(rid)
+            out.append(dict(row))
+    return out
+
+
 def fetch_all_visible_exercise_rows(
     cur,
     *,
@@ -438,6 +484,7 @@ def run_multistage_planning_retrieval(
     intent: str,
     intent_weights: Mapping[str, float],
     pack: Mapping[str, Any],
+    supplemental_exercise_ids: Optional[Sequence[int]] = None,
 ) -> Tuple[List[Dict[str, Any]], Dict[int, Set[int]], bool]:
     """Orchestriert S1b-0 → S1b-1 (Voll-Library-Ranking)."""
     rows = fetch_all_visible_exercise_rows(
@@ -447,6 +494,14 @@ def run_multistage_planning_retrieval(
         query=pack.get("retrieval_query") or query,
         exercise_kind_any=exercise_kind_any,
     )
+    if supplemental_exercise_ids:
+        extra = fetch_exercise_rows_by_ids(
+            cur,
+            supplemental_exercise_ids,
+            vis_sql=vis_sql,
+            vis_params=vis_params,
+        )
+        rows = merge_supplemental_exercise_rows(rows, extra)
     hits, skills_by_ex = rank_visible_library_hits(
         cur,
         rows,
@@ -482,8 +537,10 @@ def profile_preselect_rows(
 
 __all__ = [
     "fetch_all_visible_exercise_rows",
+    "fetch_exercise_rows_by_ids",
     "fetch_retrieval_candidate_rows",
     "hybrid_score_planning_hits",
+    "merge_supplemental_exercise_rows",
     "profile_preselect_rows",
     "rank_visible_library_hits",
     "run_multistage_planning_retrieval",
diff --git a/backend/routers/exercise_progression_graphs.py b/backend/routers/exercise_progression_graphs.py
index 16c1380..9e4edaa 100644
--- a/backend/routers/exercise_progression_graphs.py
+++ b/backend/routers/exercise_progression_graphs.py
@@ -3,6 +3,7 @@ Progressionsgraph zwischen Übungen (Übung → Übung), Migration 032–034.
 Optional Übungsvarianten als Knoten-Endpunkte; Sequenz-Bulk-Anlage.
 AuthZ analog training_plan_templates: Bearbeiten/Löschen wie Übungen; Governance-Übergänge zentral.
 """
+import json
 from typing import Any, Dict, List, Optional
 
 from fastapi import APIRouter, Depends, HTTPException, Query
@@ -256,6 +257,127 @@ def get_progression_graph(
         return row
 
 
+def _exercise_ids_from_planning_roadmap(artifact: Optional[Dict[str, Any]]) -> set[int]:
+    ids: set[int] = set()
+    if not artifact or not isinstance(artifact, dict):
+        return ids
+    for slot in artifact.get("slot_contents") or []:
+        if not isinstance(slot, dict):
+            continue
+        primary = slot.get("primary") if isinstance(slot.get("primary"), dict) else {}
+        if primary.get("kind") == "library" and primary.get("exercise_id") is not None:
+            try:
+                ids.add(int(primary["exercise_id"]))
+            except (TypeError, ValueError):
+                pass
+        for sib in slot.get("siblings") or []:
+            if not isinstance(sib, dict):
+                continue
+            if sib.get("kind") == "library" and sib.get("exercise_id") is not None:
+                try:
+                    ids.add(int(sib["exercise_id"]))
+                except (TypeError, ValueError):
+                    pass
+    return ids
+
+
+def _collect_graph_referenced_exercise_ids(cur, graph_id: int) -> set[int]:
+    ids: set[int] = set()
+    cur.execute(
+        """
+        SELECT from_exercise_id, to_exercise_id
+        FROM exercise_progression_edges
+        WHERE graph_id = %s
+        """,
+        (graph_id,),
+    )
+    for row in cur.fetchall():
+        for key in ("from_exercise_id", "to_exercise_id"):
+            raw = row.get(key)
+            if raw is not None:
+                ids.add(int(raw))
+    cur.execute(
+        "SELECT planning_roadmap FROM exercise_progression_graphs WHERE id = %s",
+        (graph_id,),
+    )
+    prow = cur.fetchone()
+    if prow and prow.get("planning_roadmap"):
+        art = prow["planning_roadmap"]
+        if isinstance(art, str):
+            try:
+                art = json.loads(art)
+            except json.JSONDecodeError:
+                art = None
+        ids |= _exercise_ids_from_planning_roadmap(art if isinstance(art, dict) else None)
+    return ids
+
+
+@router.get("/exercise-progression-graphs/{graph_id}/visibility-promotion-candidates")
+def list_visibility_promotion_candidates(
+    graph_id: int,
+    target_visibility: str = Query(default="club", pattern="^(club|official)$"),
+    tenant: TenantContext = Depends(get_tenant_context),
+):
+    """
+    Private Übungen im Graph, die bei Promotion des Graphen mit angehoben werden müssten.
+    """
+    profile_id = tenant.profile_id
+    role = tenant.global_role
+    with get_db() as conn:
+        cur = get_cursor(conn)
+        row = _require_graph_read(cur, graph_id, profile_id, role)
+        graph_vis = (row.get("visibility") or "private").strip().lower()
+        if graph_vis != "private" or target_visibility != "club":
+            return {
+                "graph_id": graph_id,
+                "graph_visibility": graph_vis,
+                "target_visibility": target_visibility,
+                "exercises": [],
+            }
+        ref_ids = _collect_graph_referenced_exercise_ids(cur, graph_id)
+        if not ref_ids:
+            return {
+                "graph_id": graph_id,
+                "graph_visibility": graph_vis,
+                "target_visibility": target_visibility,
+                "exercises": [],
+            }
+        ph = ",".join(["%s"] * len(ref_ids))
+        cur.execute(
+            f"""
+            SELECT id, title, visibility, club_id, created_by
+            FROM exercises
+            WHERE id IN ({ph})
+              AND LOWER(TRIM(COALESCE(visibility, ''))) = 'private'
+            ORDER BY title
+            """,
+            list(ref_ids),
+        )
+        exercises = []
+        for ex in cur.fetchall():
+            exd = r2d(ex)
+            if not library_content_visible_to_profile(
+                cur,
+                profile_id,
+                role,
+                exd,
+            ):
+                continue
+            exercises.append(
+                {
+                    "id": exd["id"],
+                    "title": exd.get("title"),
+                    "visibility": exd.get("visibility"),
+                }
+            )
+    return {
+        "graph_id": graph_id,
+        "graph_visibility": graph_vis,
+        "target_visibility": target_visibility,
+        "exercises": exercises,
+    }
+
+
 @router.post("/exercise-progression-graphs", status_code=201)
 def create_progression_graph(
     body: ProgressionGraphCreate,
diff --git a/backend/tenant_context.py b/backend/tenant_context.py
index 175221e..d3ab1ae 100644
--- a/backend/tenant_context.py
+++ b/backend/tenant_context.py
@@ -108,6 +108,57 @@ def library_content_visibility_sql(
     return "(" + " OR ".join(parts) + ")", params
 
 
+def library_content_visibility_for_progression_graph_sql(
+    *,
+    alias: str,
+    profile_id: int,
+    role: str,
+    effective_club_id: Optional[int],
+    graph_visibility: str,
+    graph_club_id: Optional[int] = None,
+) -> tuple[str, List[Any]]:
+    """
+    Übungs-Sichtbarkeit für Progressionsgraph-Match/Planung.
+
+    - private Graph: private (eigene) + Verein + offiziell — volle Nutzer-Bibliothek
+    - club Graph: nur Verein (aktiver Graph-Verein) + offiziell
+    - official Graph: nur offiziell
+    """
+    gvis = (graph_visibility or "private").strip().lower()
+    if gvis == "private":
+        return library_content_visibility_sql(
+            alias=alias,
+            profile_id=profile_id,
+            role=role,
+            effective_club_id=effective_club_id,
+        )
+    if gvis == "club":
+        parts: List[str] = [f"{alias}.visibility = 'official'"]
+        params: List[Any] = []
+        club_id = graph_club_id if graph_club_id is not None else effective_club_id
+        if club_id is not None:
+            plat = is_platform_admin(role)
+            if plat:
+                parts.append(f"({alias}.visibility = 'club' AND {alias}.club_id = %s)")
+                params.append(int(club_id))
+            else:
+                parts.append(
+                    f"""(
+                        {alias}.visibility = 'club'
+                        AND {alias}.club_id = %s
+                        AND EXISTS (
+                            SELECT 1 FROM club_members cm
+                            WHERE cm.profile_id = %s
+                              AND cm.club_id = {alias}.club_id
+                              AND cm.status = 'active'
+                        )
+                    )"""
+                )
+                params.extend([int(club_id), profile_id])
+        return "(" + " OR ".join(parts) + ")", params
+    return f"({alias}.visibility = 'official')", []
+
+
 def club_library_visibility_sql(
     *,
     alias: str,
diff --git a/backend/tests/test_access_layer.py b/backend/tests/test_access_layer.py
index 915c0ee..8169dc7 100644
--- a/backend/tests/test_access_layer.py
+++ b/backend/tests/test_access_layer.py
@@ -2,7 +2,12 @@
 import pytest
 from fastapi import HTTPException
 
-from tenant_context import library_content_visibility_sql, parse_active_club_header, resolve_tenant_context
+from tenant_context import (
+    library_content_visibility_for_progression_graph_sql,
+    library_content_visibility_sql,
+    parse_active_club_header,
+    resolve_tenant_context,
+)
 
 
 def test_library_visibility_sql_platform_admin_restricts_club_by_membership():
@@ -41,6 +46,37 @@ def test_library_visibility_sql_trainer_without_active_club_no_shared_club_branc
     assert params == [42]
 
 
+def test_progression_graph_visibility_sql_private_matches_library():
+    base_sql, base_params = library_content_visibility_sql(
+        alias="e", profile_id=5, role="trainer", effective_club_id=12
+    )
+    graph_sql, graph_params = library_content_visibility_for_progression_graph_sql(
+        alias="e",
+        profile_id=5,
+        role="trainer",
+        effective_club_id=12,
+        graph_visibility="private",
+        graph_club_id=None,
+    )
+    assert graph_sql == base_sql
+    assert graph_params == base_params
+
+
+def test_progression_graph_visibility_sql_club_excludes_private():
+    sql, params = library_content_visibility_for_progression_graph_sql(
+        alias="e",
+        profile_id=5,
+        role="trainer",
+        effective_club_id=12,
+        graph_visibility="club",
+        graph_club_id=12,
+    )
+    assert "official" in sql
+    assert "visibility = 'club'" in sql
+    assert "visibility = 'private'" not in sql
+    assert 12 in params
+
+
 def test_library_visibility_sql_user_with_active_club_includes_club_branch():
     sql, params = library_content_visibility_sql(
         alias="t",
diff --git a/frontend/src/api/exercises.js b/frontend/src/api/exercises.js
index 4eee53d..4e72274 100644
--- a/frontend/src/api/exercises.js
+++ b/frontend/src/api/exercises.js
@@ -521,6 +521,16 @@ export async function getExerciseProgressionGraph(id, { includeEdges = false } =
   return request(`/api/exercise-progression-graphs/${id}${q}`)
 }
 
+export async function getProgressionGraphVisibilityPromotionCandidates(
+  graphId,
+  { targetVisibility = 'club' } = {},
+) {
+  const q = new URLSearchParams({ target_visibility: targetVisibility })
+  return request(
+    `/api/exercise-progression-graphs/${graphId}/visibility-promotion-candidates?${q}`,
+  )
+}
+
 export async function createExerciseProgressionGraph(data) {
   return request('/api/exercise-progression-graphs', {
     method: 'POST',
diff --git a/frontend/src/components/ExerciseProgressionGraphPanel.jsx b/frontend/src/components/ExerciseProgressionGraphPanel.jsx
index a0a2988..2d02149 100644
--- a/frontend/src/components/ExerciseProgressionGraphPanel.jsx
+++ b/frontend/src/components/ExerciseProgressionGraphPanel.jsx
@@ -13,7 +13,7 @@ import { Link, useLocation } from 'react-router-dom'
 import api from '../utils/api'
 import SkillProfilePanel from './skills/SkillProfilePanel'
 import { useAuth } from '../context/AuthContext'
-import { getTenantClubDependencyKey } from '../utils/activeClub'
+import { activeClubMemberships, getTenantClubDependencyKey } from '../utils/activeClub'
 import ProgressionGraphEditor from './ProgressionGraphEditor'
 import ProgressionGraphListCard from './ProgressionGraphListCard'
 import { EXERCISE_VISIBILITY_FIELD_LABEL } from '../constants/exerciseGovernanceLabels'
@@ -226,6 +226,14 @@ function ExerciseProgressionGraphPanel(
     }
   }
 
+  const resolvePromoteClubId = () => {
+    const g = graphs.find((x) => x.id === selectedGraphId)
+    if (g?.club_id != null) return Number(g.club_id)
+    const memberships = activeClubMemberships(user?.clubs)
+    const active = memberships.find((c) => c.is_active) || memberships[0]
+    return active?.club_id != null ? Number(active.club_id) : null
+  }
+
   const handleSaveMeta = async () => {
     if (!selectedGraphId) return
     const name = metaName.trim()
@@ -233,8 +241,50 @@ function ExerciseProgressionGraphPanel(
       alert('Name ist Pflicht')
       return
     }
+    const prevGraph = graphs.find((x) => x.id === selectedGraphId)
+    const prevVis = (prevGraph?.visibility || 'private').trim().toLowerCase()
+    const nextVis = (metaVisibility || 'private').trim().toLowerCase()
+
     setBusy(true)
     try {
+      if (prevVis === 'private' && nextVis === 'club') {
+        const preview = await api.getProgressionGraphVisibilityPromotionCandidates(
+          selectedGraphId,
+          { targetVisibility: 'club' },
+        )
+        const privateExercises = Array.isArray(preview?.exercises) ? preview.exercises : []
+        if (privateExercises.length > 0) {
+          const titles = privateExercises
+            .slice(0, 8)
+            .map((ex) => `• ${ex.title || `Übung #${ex.id}`}`)
+            .join('\n')
+          const more =
+            privateExercises.length > 8
+              ? `\n… und ${privateExercises.length - 8} weitere`
+              : ''
+          const promote = window.confirm(
+            `Der Graph wird auf „Verein“ gestellt. Im Graph sind noch ${privateExercises.length} private Übung(en):\n\n${titles}${more}\n\nDiese Übungen ebenfalls auf Vereins-Sichtbarkeit anheben?`,
+          )
+          if (promote) {
+            const clubId = resolvePromoteClubId()
+            if (!clubId) {
+              alert('Kein aktiver Verein — Übungen können nicht auf Verein promoted werden.')
+            } else {
+              const ids = privateExercises.map((ex) => ex.id).filter((id) => id != null)
+              const res = await api.bulkPatchExercisesMetadata({
+                exercise_ids: ids,
+                visibility: 'club',
+                club_id: clubId,
+              })
+              if ((res?.failed || []).length) {
+                const f = res.failed[0]
+                throw new Error(f?.detail || 'Übungs-Promotion fehlgeschlagen')
+              }
+            }
+          }
+        }
+      }
+
       await api.updateExerciseProgressionGraph(selectedGraphId, {
         name,
         description: metaDescription.trim() || null,

From ad051c015f267485c6d3ae8fb18aaad2796e56e9 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Thu, 11 Jun 2026 12:20:41 +0200
Subject: [PATCH 28/33] Enhance Progression Path Suggestion with Retrieval
 Boost and Slot Assignment Logic

- Added `preserve_slot_assignments` and `retrieval_boost_exercise_ids` to `ProgressionPathSuggestRequest` for improved handling of exercise suggestions.
- Refactored `_supplemental_exercise_ids_from_body` to incorporate retrieval boost exercise IDs, ensuring they are prioritized over slot assignments.
- Updated `_build_steps_roadmap_first` to conditionally preserve slot assignments based on the new flag.
- Enhanced tests to validate the new retrieval boost logic and its integration with existing slot assignment handling.
---
 backend/planning_exercise_path_builder.py     | 77 +++++++++++++++----
 backend/planning_exercise_semantics.py        |  2 -
 .../test_planning_exercise_path_builder.py    | 25 ++++++
 .../test_planning_roadmap_stage_match.py      | 33 ++++++++
 .../src/components/ProgressionGraphEditor.jsx |  4 +-
 frontend/src/utils/progressionGraphDraft.js   | 30 +++-----
 6 files changed, 133 insertions(+), 38 deletions(-)

diff --git a/backend/planning_exercise_path_builder.py b/backend/planning_exercise_path_builder.py
index 8b6157d..700272a 100644
--- a/backend/planning_exercise_path_builder.py
+++ b/backend/planning_exercise_path_builder.py
@@ -120,6 +120,8 @@ class ProgressionPathSuggestRequest(BaseModel):
     evaluate_only: bool = False
     evaluate_steps: Optional[List[EvaluateStepPayload]] = None
     slot_assignments: Optional[List[EvaluateStepPayload]] = None
+    preserve_slot_assignments: bool = False
+    retrieval_boost_exercise_ids: Optional[List[int]] = None
     roadmap_override: Optional[RoadmapOverridePayload] = None
     start_situation: Optional[str] = Field(default=None, max_length=2000)
     target_state: Optional[str] = Field(default=None, max_length=2000)
@@ -267,18 +269,53 @@ def _build_path_target_profile(
     return target, query_intent_summary, intent
 
 
-def _supplemental_exercise_ids_from_body(body: ProgressionPathSuggestRequest) -> List[int]:
-    """Verankerte Graph-Slots immer im Retriever-Kandidatenpool halten."""
+def _graph_edge_exercise_ids(cur, graph_id: Optional[int]) -> List[int]:
+    """Übungs-IDs aus gespeicherten Graph-Kanten (für Re-Match-Boost)."""
+    if not graph_id or int(graph_id) < 1:
+        return []
+    cur.execute(
+        """
+        SELECT from_exercise_id AS eid FROM exercise_progression_edges
+        WHERE graph_id = %s AND from_exercise_id IS NOT NULL
+        UNION
+        SELECT to_exercise_id AS eid FROM exercise_progression_edges
+        WHERE graph_id = %s AND to_exercise_id IS NOT NULL
+        """,
+        (int(graph_id), int(graph_id)),
+    )
+    out: List[int] = []
+    for row in cur.fetchall() or []:
+        try:
+            eid = int(row.get("eid") or 0)
+        except (TypeError, ValueError):
+            continue
+        if eid > 0:
+            out.append(eid)
+    return out
+
+
+def _supplemental_exercise_ids_from_body(
+    cur,
+    body: ProgressionPathSuggestRequest,
+) -> List[int]:
+    """Kandidatenpool erweitern — ohne automatisches Slot-Pinning."""
     ids: List[int] = []
-    for coll in (body.slot_assignments, body.evaluate_steps):
-        for raw in coll or []:
-            if raw.exercise_id is not None:
-                try:
-                    eid = int(raw.exercise_id)
-                except (TypeError, ValueError):
-                    continue
-                if eid > 0:
-                    ids.append(eid)
+    for raw in body.evaluate_steps or []:
+        if raw.exercise_id is not None:
+            try:
+                eid = int(raw.exercise_id)
+            except (TypeError, ValueError):
+                continue
+            if eid > 0:
+                ids.append(eid)
+    for eid in body.retrieval_boost_exercise_ids or []:
+        try:
+            val = int(eid)
+        except (TypeError, ValueError):
+            continue
+        if val > 0:
+            ids.append(val)
+    ids.extend(_graph_edge_exercise_ids(cur, body.progression_graph_id))
     return list(dict.fromkeys(ids))
 
 
@@ -845,7 +882,7 @@ def _match_roadmap_slot(
         path_context_note=path_context_note,
         path_primary_topic=path_primary or None,
         path_technique_excludes=path_tech_excludes or None,
-        supplemental_exercise_ids=_supplemental_exercise_ids_from_body(body),
+        supplemental_exercise_ids=_supplemental_exercise_ids_from_body(cur, body),
     )
 
     hit = _pick_best_path_hit(
@@ -1026,7 +1063,11 @@ def _build_steps_roadmap_first(
     anchor_variant_id: Optional[int] = None
     unfilled: List[Tuple[int, StageSpecArtifact]] = []
     stage_count = len(stage_specs)
-    assignments = _slot_assignments_by_major_index(body.slot_assignments)
+    assignments = (
+        _slot_assignments_by_major_index(body.slot_assignments)
+        if body.preserve_slot_assignments
+        else {}
+    )
     majors_by_index: Dict[int, MajorStep] = {}
     if roadmap_ctx.roadmap:
         majors_by_index = {m.index: m for m in roadmap_ctx.roadmap.major_steps}
@@ -1579,7 +1620,7 @@ def suggest_progression_path(
                 semantic_brief=semantic_brief,
                 path_target_profile=path_target_profile,
                 path_intent=path_intent,
-                supplemental_exercise_ids=_supplemental_exercise_ids_from_body(body),
+                supplemental_exercise_ids=_supplemental_exercise_ids_from_body(cur, body),
             )
 
             hit = _pick_best_path_hit(hits, used, semantic_brief=semantic_brief)
@@ -1640,7 +1681,7 @@ def suggest_progression_path(
                 planned_ids=planned_ids,
                 path_target_profile=path_target_profile,
                 path_intent=path_intent,
-                supplemental_exercise_ids=_supplemental_exercise_ids_from_body(body),
+                supplemental_exercise_ids=_supplemental_exercise_ids_from_body(cur, body),
             )
             steps, bridge_inserts, unfilled_gaps = insert_bridge_exercises(
                 cur,
@@ -1683,7 +1724,11 @@ def suggest_progression_path(
             goal_query=goal_query,
         )
         off_topic_before_strip = list(off_topic_steps)
-        steps, stripped_off_topic = strip_off_topic_steps_from_path(steps, off_topic_steps)
+        steps, stripped_off_topic = strip_off_topic_steps_from_path(
+            steps,
+            off_topic_steps,
+            min_remaining=0 if roadmap_first else 2,
+        )
         if stripped_off_topic:
             off_topic_steps = []
             gaps = detect_path_gaps(
diff --git a/backend/planning_exercise_semantics.py b/backend/planning_exercise_semantics.py
index 701e41c..1a378cd 100644
--- a/backend/planning_exercise_semantics.py
+++ b/backend/planning_exercise_semantics.py
@@ -1286,8 +1286,6 @@ def pick_best_path_hit(
         return chosen
 
     if roadmap_stage_match:
-        if (path_primary_topic or "").strip():
-            return None
         chosen = _scan(strict=False)
         return chosen
 
diff --git a/backend/tests/test_planning_exercise_path_builder.py b/backend/tests/test_planning_exercise_path_builder.py
index 84547f6..5c021b6 100644
--- a/backend/tests/test_planning_exercise_path_builder.py
+++ b/backend/tests/test_planning_exercise_path_builder.py
@@ -1,12 +1,37 @@
 """Tests Planungs-KI Phase C3/E/F — Pfad-Vorschläge."""
 from planning_exercise_path_builder import (
+    EvaluateStepPayload,
+    ProgressionPathSuggestRequest,
     _annotate_roadmap_step,
     _hit_to_path_step,
     _pick_best_path_hit,
+    _supplemental_exercise_ids_from_body,
 )
 from planning_progression_roadmap import MajorStep, StageSpecArtifact
 
 
+class _FakeCur:
+    def execute(self, *_args, **_kwargs):
+        return None
+
+    def fetchall(self):
+        return []
+
+
+def test_supplemental_boost_uses_retrieval_boost_not_slot_pins():
+    body = ProgressionPathSuggestRequest(
+        query="Mawashi Geri Progression",
+        slot_assignments=[
+            EvaluateStepPayload(exercise_id=99, roadmap_major_step_index=0),
+        ],
+        retrieval_boost_exercise_ids=[42, 7],
+    )
+    ids = _supplemental_exercise_ids_from_body(_FakeCur(), body)
+    assert 99 not in ids
+    assert 42 in ids
+    assert 7 in ids
+
+
 def test_pick_next_path_hit_skips_used():
     hits = [{"id": 1, "title": "A", "semantic_score": 0.2}, {"id": 2, "title": "B", "semantic_score": 0.2}, {"id": 3, "title": "C", "semantic_score": 0.2}]
     assert _pick_best_path_hit(hits, {1})["id"] == 2
diff --git a/backend/tests/test_planning_roadmap_stage_match.py b/backend/tests/test_planning_roadmap_stage_match.py
index 9519c60..0c9fdc9 100644
--- a/backend/tests/test_planning_roadmap_stage_match.py
+++ b/backend/tests/test_planning_roadmap_stage_match.py
@@ -340,6 +340,39 @@ def test_technique_scope_rejects_kumite_when_only_stage_goal_mentions_mawashi():
     )
 
 
+def test_pick_roadmap_relaxed_with_path_primary_when_strict_fails():
+    """Bestehende Graph-Übungen: relaxed Gate auch bei gesetztem path_primary_topic."""
+    stage_goal = "Hüftmobilität für Mawashi Geri"
+    primary = "mawashi geri"
+    stage_brief = build_stage_match_brief(
+        learning_goal=stage_goal,
+        path_primary_topic=primary,
+        path_technique_excludes=technique_sibling_excludes(primary),
+    )
+    hits = [
+        {
+            "id": 42,
+            "title": "Mawashi Geri Hüftmobilität — Vereinsübung",
+            "summary": "Dehnung und Hüfte für Rundtritt",
+            "goal": "Mobilität Mawashi Geri",
+            "score": 0.55,
+            "semantic_score": 0.25,
+            "stage_semantic_score": 0.25,
+        },
+    ]
+    chosen = pick_best_path_hit(
+        hits,
+        set(),
+        stage_learning_goal=stage_goal,
+        roadmap_stage_match=True,
+        stage_match_brief=stage_brief,
+        path_primary_topic=primary,
+        path_technique_excludes=technique_sibling_excludes(primary),
+    )
+    assert chosen is not None
+    assert int(chosen["id"]) == 42
+
+
 def test_pick_best_roadmap_rejects_kumite_with_path_primary_topic():
     q = "gesprungener Mawashi Geri Sprungphase"
     brief = enrich_brief_with_path_constraints(build_semantic_brief(q), q)
diff --git a/frontend/src/components/ProgressionGraphEditor.jsx b/frontend/src/components/ProgressionGraphEditor.jsx
index 8687fd5..042acfa 100644
--- a/frontend/src/components/ProgressionGraphEditor.jsx
+++ b/frontend/src/components/ProgressionGraphEditor.jsx
@@ -41,7 +41,7 @@ import {
   SLOT_MAX,
   slotsAsPathStepRows,
   slotsToEvaluateSteps,
-  slotsToSlotAssignments,
+  draftRetrievalBoostExerciseIds,
   syncProgressionRoadmapFromSlots,
   syncSlotPhasesFromRoadmap,
 } from '../utils/progressionGraphDraft'
@@ -415,7 +415,7 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
         include_llm_roadmap: false,
         roadmap_first: true,
         roadmap_override: override,
-        slot_assignments: slotsToSlotAssignments(synced),
+        retrieval_boost_exercise_ids: draftRetrievalBoostExerciseIds(synced),
         progression_graph_id: Number(graphId),
         ...roadmapStructuredPayload(draft.startSituation, draft.targetState, draft.roadmapNotes),
       })
diff --git a/frontend/src/utils/progressionGraphDraft.js b/frontend/src/utils/progressionGraphDraft.js
index 3cd9ab4..96e7632 100644
--- a/frontend/src/utils/progressionGraphDraft.js
+++ b/frontend/src/utils/progressionGraphDraft.js
@@ -712,19 +712,17 @@ export function draftSiblingEdgePairs(draft) {
   return pairs
 }
 
-/** Bereits zugeordnete Bibliotheks-Übungen für Re-Match (Pins). */
-export function slotsToSlotAssignments(draft) {
-  return (draft.slots || [])
-    .filter((slot) => slot.primary?.kind === 'library' && slot.primary.exerciseId != null)
-    .map((slot) => ({
-      exercise_id: slot.primary.exerciseId,
-      variant_id: slot.primary.variantId || null,
-      title: slot.primary.exerciseTitle || null,
-      is_ai_proposal: false,
-      roadmap_major_step_index: slot.majorStepIndex,
-      roadmap_phase: slot.phase || null,
-      roadmap_learning_goal: slot.learning_goal || null,
-    }))
+/** Bereits zugeordnete Bibliotheks-Übungen — nur Retriever-Boost, kein Pinning. */
+export function draftRetrievalBoostExerciseIds(draft) {
+  const ids = new Set()
+  for (const slot of draft.slots || []) {
+    const p = slot.primary
+    if (p?.kind === 'library' && p.exerciseId != null) ids.add(p.exerciseId)
+    for (const sib of slot.siblings || []) {
+      if (sib.kind === 'library' && sib.exerciseId != null) ids.add(sib.exerciseId)
+    }
+  }
+  return [...ids]
 }
 
 export function slotsToEvaluateSteps(draft) {
@@ -804,11 +802,7 @@ export function applyMatchStepsToSlots(draft, apiSteps) {
 
   for (let i = 0; i < nextSlots.length; i += 1) {
     if (!touchedMajors.has(i)) {
-      const keep =
-        nextSlots[i].primary?.kind === 'library' && nextSlots[i].primary.exerciseId != null
-      if (!keep) {
-        nextSlots[i].primary = emptySlotExercise()
-      }
+      nextSlots[i].primary = emptySlotExercise()
     }
   }
 

From ca2adbd55ec645621c9067157c6ac7e3541cb596 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Thu, 11 Jun 2026 12:33:02 +0200
Subject: [PATCH 29/33] Enhance Exercise Retrieval and Path Handling Logic

- Introduced new functions for handling exercise visibility and retrieval based on progression graph context, including `fetch_exercise_rows_by_ids_for_graph`.
- Updated `_load_supplemental_exercise_rows` to incorporate graph visibility rules, improving the accuracy of exercise retrieval.
- Enhanced `_run_path_step_retrieval` to utilize preloaded supplemental exercise rows, optimizing performance and clarity in path step processing.
- Added `exercise_title_equivalent_to_stage_goal` function to improve title matching against learning goals, enhancing exercise relevance.
- Updated tests to validate new retrieval logic and title equivalence functionality, ensuring robustness in exercise selection processes.
---
 backend/planning_exercise_path_builder.py     | 374 +++++++++++++++---
 backend/planning_exercise_path_qa.py          |   7 +
 backend/planning_exercise_retrieval.py        |  92 ++++-
 backend/planning_exercise_semantics.py        |  46 +++
 .../test_planning_exercise_path_builder.py    |   4 +-
 .../test_planning_roadmap_stage_match.py      |  26 ++
 .../src/components/ProgressionGraphEditor.jsx |   2 +
 frontend/src/utils/progressionGraphDraft.js   |  30 +-
 8 files changed, 500 insertions(+), 81 deletions(-)

diff --git a/backend/planning_exercise_path_builder.py b/backend/planning_exercise_path_builder.py
index 700272a..1783275 100644
--- a/backend/planning_exercise_path_builder.py
+++ b/backend/planning_exercise_path_builder.py
@@ -6,7 +6,7 @@ planning_progression_roadmap.py und PLANNING_PROGRESSION_ROADMAP_SPEC.md.
 """
 from __future__ import annotations
 
-from typing import Any, Callable, Dict, List, Mapping, Optional, Set, Tuple
+from typing import Any, Callable, Dict, List, Mapping, Optional, Sequence, Set, Tuple
 
 from fastapi import HTTPException
 from pydantic import BaseModel, Field
@@ -298,7 +298,7 @@ def _supplemental_exercise_ids_from_body(
     cur,
     body: ProgressionPathSuggestRequest,
 ) -> List[int]:
-    """Kandidatenpool erweitern — ohne automatisches Slot-Pinning."""
+    """Kandidatenpool erweitern (Graph-Kanten, Boost, Slot-Zuordnungen)."""
     ids: List[int] = []
     for raw in body.evaluate_steps or []:
         if raw.exercise_id is not None:
@@ -308,6 +308,14 @@ def _supplemental_exercise_ids_from_body(
                 continue
             if eid > 0:
                 ids.append(eid)
+    for raw in body.slot_assignments or []:
+        if raw.exercise_id is not None:
+            try:
+                eid = int(raw.exercise_id)
+            except (TypeError, ValueError):
+                continue
+            if eid > 0:
+                ids.append(eid)
     for eid in body.retrieval_boost_exercise_ids or []:
         try:
             val = int(eid)
@@ -319,6 +327,64 @@ def _supplemental_exercise_ids_from_body(
     return list(dict.fromkeys(ids))
 
 
+def _graph_visibility_context(
+    cur,
+    progression_graph_id: Optional[int],
+) -> Tuple[str, Optional[int]]:
+    if not progression_graph_id or int(progression_graph_id) < 1:
+        return "private", None
+    cur.execute(
+        "SELECT visibility, club_id FROM exercise_progression_graphs WHERE id = %s",
+        (int(progression_graph_id),),
+    )
+    row = cur.fetchone()
+    if not row:
+        return "private", None
+    g_club = row.get("club_id")
+    return (
+        str(row.get("visibility") or "private"),
+        int(g_club) if g_club is not None else None,
+    )
+
+
+def _load_supplemental_exercise_rows(
+    cur,
+    *,
+    tenant: TenantContext,
+    progression_graph_id: Optional[int],
+    exercise_ids: Optional[Sequence[int]],
+    vis_sql: str,
+    vis_params: Sequence[Any],
+) -> List[Dict[str, Any]]:
+    """Supplemental-Übungen mit Graph-Sichtbarkeit, Fallback Library-vis_sql."""
+    ids = list(dict.fromkeys(int(x) for x in (exercise_ids or []) if int(x) > 0))
+    if not ids:
+        return []
+    if progression_graph_id and int(progression_graph_id) > 0:
+        from planning_exercise_retrieval import fetch_exercise_rows_by_ids_for_graph
+
+        gvis, gclub = _graph_visibility_context(cur, progression_graph_id)
+        graph_rows = fetch_exercise_rows_by_ids_for_graph(
+            cur,
+            ids,
+            graph_visibility=gvis,
+            graph_club_id=gclub,
+            profile_id=tenant.profile_id,
+            role=tenant.global_role,
+            exercise_allowed_fn=_exercise_allowed_in_progression_graph,
+        )
+        if graph_rows:
+            return graph_rows
+    from planning_exercise_retrieval import fetch_exercise_rows_by_ids
+
+    return fetch_exercise_rows_by_ids(
+        cur,
+        ids,
+        vis_sql=vis_sql,
+        vis_params=vis_params,
+    )
+
+
 def _planning_visibility_sql(
     cur,
     tenant: TenantContext,
@@ -508,6 +574,7 @@ def _run_path_step_retrieval(
     path_primary_topic: Optional[str] = None,
     path_technique_excludes: Optional[List[str]] = None,
     supplemental_exercise_ids: Optional[List[int]] = None,
+    priority_exercise_ids: Optional[List[int]] = None,
 ) -> Tuple[List[Dict[str, Any]], PlanningTargetProfile, Dict[str, Any], str]:
     step_query = step_query_override or step_retrieval_query(
         semantic_brief, goal_query, step_index, max_steps
@@ -617,6 +684,14 @@ def _run_path_step_retrieval(
         progression_graph_id,
     )
 
+    supplemental_rows = _load_supplemental_exercise_rows(
+        cur,
+        tenant=tenant,
+        progression_graph_id=progression_graph_id,
+        exercise_ids=supplemental_exercise_ids,
+        vis_sql=vis_sql,
+        vis_params=vis_params,
+    )
     hits, _skills_by_ex, _full_lib = run_multistage_planning_retrieval(
         cur,
         vis_sql=vis_sql,
@@ -627,9 +702,19 @@ def _run_path_step_retrieval(
         intent=intent,
         intent_weights=weights,
         pack=pack,
-        supplemental_exercise_ids=supplemental_exercise_ids,
+        supplemental_rows_preloaded=supplemental_rows,
     )
-    hits = _enrich_planning_hits_with_variant_meta(cur, hits[:32])
+    from planning_exercise_retrieval import trim_hits_preserving_priority_ids
+
+    priority_ids = list(
+        dict.fromkeys(
+            int(x)
+            for x in (priority_exercise_ids or supplemental_exercise_ids or [])
+            if int(x) > 0
+        )
+    )
+    hits = trim_hits_preserving_priority_ids(hits, priority_ids, limit=48)
+    hits = _enrich_planning_hits_with_variant_meta(cur, hits)
     return hits, target_profile, query_intent_summary, intent
 
 
@@ -727,37 +812,111 @@ def _annotate_roadmap_step(
     if stage_spec.success_criteria:
         step["success_criteria"] = list(stage_spec.success_criteria)
         step["stage_success_criteria"] = list(stage_spec.success_criteria)
-    step["roadmap_match_source"] = "stage_spec"
+    if not step.get("roadmap_match_source"):
+        step["roadmap_match_source"] = "stage_spec"
+    if step.get("exercise_id") is not None:
+        step["slot_status"] = step.get("slot_status") or (
+            "preserved" if step.get("roadmap_match_source") == "slot_reconciled" else "matched"
+        )
+    else:
+        step["slot_status"] = step.get("slot_status") or "unfilled"
     if skill_expectations:
         step["skill_expectations"] = skill_expectations
     return step
 
 
-def _match_roadmap_slot(
+def _try_reconcile_slot_assignment(
     cur,
     *,
+    assignment: EvaluateStepPayload,
+    stage_spec: StageSpecArtifact,
+    major_step: Optional[MajorStep],
     tenant: TenantContext,
+    progression_graph_id: Optional[int],
+    stage_match_brief: Optional[PlanningSemanticBrief],
+    stage_goal: str,
+    stage_anti: Optional[List[str]],
+    path_primary: str,
+    path_tech_excludes: Optional[List[str]],
+) -> Optional[Dict[str, Any]]:
+    """
+    Bestehende Slot-Zuordnung behalten, wenn sie noch zum Stufen-Lernziel passt.
+
+    Validiert gegen dieselben Gates wie Match/QA (relaxed), inkl. Titel-Äquivalenz.
+    """
+    from planning_exercise_semantics import (
+        exercise_passes_stage_fit,
+        exercise_title_equivalent_to_stage_goal,
+    )
+
+    step = _path_step_from_slot_assignment(
+        cur,
+        assignment=assignment,
+        stage_spec=stage_spec,
+        major_step=major_step,
+        tenant=tenant,
+        progression_graph_id=progression_graph_id,
+    )
+    if not step:
+        return None
+
+    title = str(step.get("title") or "").strip()
+    summary = str(step.get("summary") or "").strip()
+    goal = ""
+    cur.execute("SELECT goal FROM exercises WHERE id = %s", (int(step["exercise_id"]),))
+    grow = cur.fetchone()
+    if grow:
+        goal = str(grow.get("goal") or "").strip()
+
+    lg = (stage_goal or stage_spec.learning_goal or "").strip()
+    if exercise_title_equivalent_to_stage_goal(title, lg):
+        step["roadmap_match_source"] = "slot_reconciled"
+        step["slot_status"] = "preserved"
+        step["reasons"] = ["Bestehende Zuordnung (Titel = Lernziel)"] + list(step.get("reasons") or [])[:2]
+        return _annotate_roadmap_step(
+            step,
+            stage_spec=stage_spec,
+            major_step=major_step,
+            anti_patterns_override=stage_anti,
+        )
+
+    if exercise_passes_stage_fit(
+        learning_goal=lg,
+        title=title,
+        summary=summary,
+        goal=goal,
+        stage_brief=stage_match_brief,
+        anti_patterns=stage_anti,
+        path_primary_topic=path_primary or None,
+        path_technique_excludes=path_tech_excludes,
+        relaxed=True,
+    ):
+        step["roadmap_match_source"] = "slot_reconciled"
+        step["slot_status"] = "preserved"
+        step["reasons"] = ["Bestehende Zuordnung (Stufen-Fit)"] + list(step.get("reasons") or [])[:2]
+        return _annotate_roadmap_step(
+            step,
+            stage_spec=stage_spec,
+            major_step=major_step,
+            anti_patterns_override=stage_anti,
+        )
+    return None
+
+
+def _stage_validation_context_for_spec(
+    cur,
+    *,
     body: ProgressionPathSuggestRequest,
     goal_query: str,
-    max_steps: int,
     semantic_brief: PlanningSemanticBrief,
     path_target_profile: PlanningTargetProfile,
-    path_intent: str,
     roadmap_ctx: ProgressionRoadmapContext,
     stage_spec: StageSpecArtifact,
     step_index: int,
     stage_count: int,
-    planned_ids: List[int],
-    anchor_id: Optional[int],
-    anchor_variant_id: Optional[int],
-    used: Set[int],
-) -> Tuple[Optional[Dict[str, Any]], Optional[StageSpecArtifact]]:
-    """Einzelnen Roadmap-Slot matchen (Initial-Build und Auto-Rematch)."""
-    major_by_index: Dict[int, MajorStep] = {}
-    if roadmap_ctx.roadmap:
-        major_by_index = {m.index: m for m in roadmap_ctx.roadmap.major_steps}
-    major = major_by_index.get(stage_spec.major_step_index)
-
+    major: Optional[MajorStep],
+) -> Dict[str, Any]:
+    """Gemeinsamer Kontext für Reconcile + Match eines Roadmap-Slots."""
     ga_dump = (
         roadmap_ctx.goal_analysis.model_dump() if roadmap_ctx.goal_analysis else None
     )
@@ -770,34 +929,6 @@ def _match_roadmap_slot(
         structured=roadmap_ctx.resolved_structured,
         goal_analysis=roadmap_ctx.goal_analysis,
     )
-    brief_summary = (
-        roadmap_ctx.semantic_brief
-        if roadmap_ctx.semantic_brief
-        else brief_to_summary_dict(semantic_brief)
-    )
-
-    stage_spec_dict = stage_spec.model_dump()
-    if major:
-        stage_spec_dict["phase"] = major.phase
-    stage_inp = expectation_input_from_progression_stage(
-        goal_query=goal_query,
-        goal_analysis=ga_dump,
-        resolved_structured=rs_dump,
-        stage_spec=stage_spec_dict,
-        semantic_brief_summary=brief_summary,
-        major_step=major.model_dump() if major else None,
-    )
-    stage_exp = build_planning_skill_expectations(cur, stage_inp, semantic_brief=semantic_brief)
-    step_target = apply_expectations_to_target(path_target_profile, stage_exp)
-    skill_exp_api = stage_exp.to_api_dict() if stage_exp.items else None
-
-    step_query = stage_spec_retrieval_query(
-        semantic_brief=semantic_brief,
-        goal_query=goal_query,
-        stage_spec=stage_spec,
-        major_step=major,
-    )
-    step_kind = resolve_step_exercise_kind_filter(stage_spec, body.exercise_kind_any)
     stage_goal = (stage_spec.learning_goal or "").strip()
     stage_start = (stage_spec.start_state or "").strip()
     stage_target = (stage_spec.target_state or "").strip()
@@ -855,6 +986,105 @@ def _match_roadmap_slot(
         path_target_state=path_target or None,
         contextualized_learning_goal=contextual_goal or None,
     )
+    return {
+        "stage_goal": stage_goal,
+        "stage_anti": stage_anti,
+        "path_primary": path_primary,
+        "path_tech_excludes": path_tech_excludes,
+        "stage_match_brief": stage_match_brief,
+        "path_context_note": path_context_note,
+        "path_anti": path_anti,
+        "path_start": path_start,
+        "path_target": path_target,
+        "ga_dump": ga_dump,
+        "rs_dump": rs_dump,
+    }
+
+
+def _match_roadmap_slot(
+    cur,
+    *,
+    tenant: TenantContext,
+    body: ProgressionPathSuggestRequest,
+    goal_query: str,
+    max_steps: int,
+    semantic_brief: PlanningSemanticBrief,
+    path_target_profile: PlanningTargetProfile,
+    path_intent: str,
+    roadmap_ctx: ProgressionRoadmapContext,
+    stage_spec: StageSpecArtifact,
+    step_index: int,
+    stage_count: int,
+    planned_ids: List[int],
+    anchor_id: Optional[int],
+    anchor_variant_id: Optional[int],
+    used: Set[int],
+    slot_priority_exercise_id: Optional[int] = None,
+) -> Tuple[Optional[Dict[str, Any]], Optional[StageSpecArtifact]]:
+    """Einzelnen Roadmap-Slot matchen (Initial-Build und Auto-Rematch)."""
+    major_by_index: Dict[int, MajorStep] = {}
+    if roadmap_ctx.roadmap:
+        major_by_index = {m.index: m for m in roadmap_ctx.roadmap.major_steps}
+    major = major_by_index.get(stage_spec.major_step_index)
+
+    ctx = _stage_validation_context_for_spec(
+        cur,
+        body=body,
+        goal_query=goal_query,
+        semantic_brief=semantic_brief,
+        path_target_profile=path_target_profile,
+        roadmap_ctx=roadmap_ctx,
+        stage_spec=stage_spec,
+        step_index=step_index,
+        stage_count=stage_count,
+        major=major,
+    )
+    stage_goal = ctx["stage_goal"]
+    stage_anti = ctx["stage_anti"]
+    path_primary = ctx["path_primary"]
+    path_tech_excludes = ctx["path_tech_excludes"]
+    stage_match_brief = ctx["stage_match_brief"]
+    path_context_note = ctx["path_context_note"]
+    ga_dump = ctx["ga_dump"]
+    rs_dump = ctx["rs_dump"]
+
+    brief_summary = (
+        roadmap_ctx.semantic_brief
+        if roadmap_ctx.semantic_brief
+        else brief_to_summary_dict(semantic_brief)
+    )
+
+    stage_spec_dict = stage_spec.model_dump()
+    if major:
+        stage_spec_dict["phase"] = major.phase
+    stage_inp = expectation_input_from_progression_stage(
+        goal_query=goal_query,
+        goal_analysis=ga_dump,
+        resolved_structured=rs_dump,
+        stage_spec=stage_spec_dict,
+        semantic_brief_summary=brief_summary,
+        major_step=major.model_dump() if major else None,
+    )
+    stage_exp = build_planning_skill_expectations(cur, stage_inp, semantic_brief=semantic_brief)
+    step_target = apply_expectations_to_target(path_target_profile, stage_exp)
+    skill_exp_api = stage_exp.to_api_dict() if stage_exp.items else None
+
+    step_query = stage_spec_retrieval_query(
+        semantic_brief=semantic_brief,
+        goal_query=goal_query,
+        stage_spec=stage_spec,
+        major_step=major,
+    )
+    step_kind = resolve_step_exercise_kind_filter(stage_spec, body.exercise_kind_any)
+
+    supplemental_ids = _supplemental_exercise_ids_from_body(cur, body)
+    priority_ids = list(
+        dict.fromkeys(
+            x
+            for x in [slot_priority_exercise_id, *(body.retrieval_boost_exercise_ids or [])]
+            if x is not None and int(x) > 0
+        )
+    )
 
     hits, _, _, _ = _run_path_step_retrieval(
         cur,
@@ -882,7 +1112,8 @@ def _match_roadmap_slot(
         path_context_note=path_context_note,
         path_primary_topic=path_primary or None,
         path_technique_excludes=path_tech_excludes or None,
-        supplemental_exercise_ids=_supplemental_exercise_ids_from_body(cur, body),
+        supplemental_exercise_ids=supplemental_ids,
+        priority_exercise_ids=priority_ids,
     )
 
     hit = _pick_best_path_hit(
@@ -907,6 +1138,7 @@ def _match_roadmap_slot(
         skill_expectations=skill_exp_api,
         anti_patterns_override=stage_anti,
     )
+    step["slot_status"] = "matched"
     return step, None
 
 
@@ -949,7 +1181,8 @@ def _normalize_roadmap_steps_coverage(
                 "roadmap_major_step_index": midx,
                 "roadmap_phase": major.phase if major else None,
                 "roadmap_learning_goal": goal or None,
-                "roadmap_match_source": "stage_spec",
+                "roadmap_match_source": "unfilled",
+                "slot_status": "unfilled",
                 "reasons": [],
             }
         )
@@ -1063,34 +1296,54 @@ def _build_steps_roadmap_first(
     anchor_variant_id: Optional[int] = None
     unfilled: List[Tuple[int, StageSpecArtifact]] = []
     stage_count = len(stage_specs)
-    assignments = (
-        _slot_assignments_by_major_index(body.slot_assignments)
-        if body.preserve_slot_assignments
-        else {}
-    )
+    assignments = _slot_assignments_by_major_index(body.slot_assignments)
     majors_by_index: Dict[int, MajorStep] = {}
     if roadmap_ctx.roadmap:
         majors_by_index = {m.index: m for m in roadmap_ctx.roadmap.major_steps}
 
     for step_index, stage_spec in enumerate(stage_specs):
         major_idx = stage_spec.major_step_index
+        major = majors_by_index.get(major_idx)
+        slot_priority_id: Optional[int] = None
+
         if major_idx in assignments:
-            pinned = _path_step_from_slot_assignment(
+            ctx = _stage_validation_context_for_spec(
+                cur,
+                body=body,
+                goal_query=goal_query,
+                semantic_brief=semantic_brief,
+                path_target_profile=path_target_profile,
+                roadmap_ctx=roadmap_ctx,
+                stage_spec=stage_spec,
+                step_index=step_index,
+                stage_count=stage_count,
+                major=major,
+            )
+            reconciled = _try_reconcile_slot_assignment(
                 cur,
                 assignment=assignments[major_idx],
                 stage_spec=stage_spec,
-                major_step=majors_by_index.get(major_idx),
+                major_step=major,
                 tenant=tenant,
                 progression_graph_id=body.progression_graph_id,
+                stage_match_brief=ctx["stage_match_brief"],
+                stage_goal=ctx["stage_goal"],
+                stage_anti=ctx["stage_anti"],
+                path_primary=ctx["path_primary"],
+                path_tech_excludes=ctx["path_tech_excludes"],
             )
-            if pinned:
-                steps.append(pinned)
-                eid = int(pinned["exercise_id"])
+            if reconciled:
+                steps.append(reconciled)
+                eid = int(reconciled["exercise_id"])
                 used.add(eid)
                 planned_ids.append(eid)
                 anchor_id = eid
-                anchor_variant_id = pinned.get("variant_id")
+                anchor_variant_id = reconciled.get("variant_id")
                 continue
+            try:
+                slot_priority_id = int(assignments[major_idx].exercise_id)
+            except (TypeError, ValueError):
+                slot_priority_id = None
 
         step, unfilled_spec = _match_roadmap_slot(
             cur,
@@ -1109,6 +1362,7 @@ def _build_steps_roadmap_first(
             anchor_id=anchor_id,
             anchor_variant_id=anchor_variant_id,
             used=used,
+            slot_priority_exercise_id=slot_priority_id,
         )
         if not step:
             unfilled.append((step_index, unfilled_spec or stage_spec))
diff --git a/backend/planning_exercise_path_qa.py b/backend/planning_exercise_path_qa.py
index d3e50a7..4cb3c85 100644
--- a/backend/planning_exercise_path_qa.py
+++ b/backend/planning_exercise_path_qa.py
@@ -435,7 +435,14 @@ def detect_off_topic_steps(
     for idx, step in enumerate(steps):
         if step.get("is_ai_proposal") or step.get("exercise_id") is None:
             continue
+        stage_goal_early = (step.get("roadmap_learning_goal") or "").strip()
         bundle = _load_exercise_text_bundle(cur, int(step["exercise_id"]))
+        from planning_exercise_semantics import exercise_title_equivalent_to_stage_goal
+
+        if stage_goal_early and exercise_title_equivalent_to_stage_goal(
+            bundle["title"], stage_goal_early
+        ):
+            continue
         blob = _blob_from_fields(
             bundle["title"],
             bundle["summary"],
diff --git a/backend/planning_exercise_retrieval.py b/backend/planning_exercise_retrieval.py
index da71d8a..deb0d13 100644
--- a/backend/planning_exercise_retrieval.py
+++ b/backend/planning_exercise_retrieval.py
@@ -58,6 +58,21 @@ def _normalize_exercise_kind_filter(exercise_kind_any: Optional[List[str]]) -> L
     return out
 
 
+_EXERCISE_ROW_SELECT = """
+        SELECT e.id, e.title, e.summary, e.method_archetype,
+               e.visibility, e.club_id, e.created_by,
+               (
+                 SELECT fa.name FROM exercise_focus_areas efa
+                 JOIN focus_areas fa ON fa.id = efa.focus_area_id
+                 WHERE efa.exercise_id = e.id
+                 ORDER BY efa.is_primary DESC NULLS LAST, fa.name ASC
+                 LIMIT 1
+               ) AS primary_focus_name,
+               0.0::float AS ft_rank
+        FROM exercises e
+"""
+
+
 def fetch_exercise_rows_by_ids(
     cur,
     exercise_ids: Sequence[int],
@@ -71,16 +86,7 @@ def fetch_exercise_rows_by_ids(
         return []
     ph = ",".join(["%s"] * len(ids))
     sql = f"""
-        SELECT e.id, e.title, e.summary, e.method_archetype,
-               (
-                 SELECT fa.name FROM exercise_focus_areas efa
-                 JOIN focus_areas fa ON fa.id = efa.focus_area_id
-                 WHERE efa.exercise_id = e.id
-                 ORDER BY efa.is_primary DESC NULLS LAST, fa.name ASC
-                 LIMIT 1
-               ) AS primary_focus_name,
-               0.0::float AS ft_rank
-        FROM exercises e
+        {_EXERCISE_ROW_SELECT.strip()}
         WHERE e.id IN ({ph})
           AND ({vis_sql})
           AND COALESCE(e.status, '') <> %s
@@ -90,6 +96,67 @@ def fetch_exercise_rows_by_ids(
     return [dict(r) for r in cur.fetchall()]
 
 
+def fetch_exercise_rows_by_ids_for_graph(
+    cur,
+    exercise_ids: Sequence[int],
+    *,
+    graph_visibility: str,
+    graph_club_id: Optional[int],
+    profile_id: int,
+    role: str,
+    exercise_allowed_fn,
+) -> List[Dict[str, Any]]:
+    """
+    Lädt Übungen nach ID mit Graph-Sichtbarkeitsregeln (nicht Library-vis_sql).
+
+    Ermöglicht Re-Match für im Graph verankerte private Übungen auf Club-Graphen
+    (eigene private) bzw. alle graph-konformen Übungen.
+    """
+    ids = sorted({int(x) for x in exercise_ids if int(x) > 0})
+    if not ids:
+        return []
+    ph = ",".join(["%s"] * len(ids))
+    sql = f"""
+        {_EXERCISE_ROW_SELECT.strip()}
+        WHERE e.id IN ({ph})
+          AND COALESCE(e.status, '') <> %s
+    """
+    cur.execute(sql, [*ids, "archived"])
+    out: List[Dict[str, Any]] = []
+    for row in cur.fetchall() or []:
+        if exercise_allowed_fn(
+            row,
+            graph_visibility=graph_visibility,
+            graph_club_id=graph_club_id,
+            profile_id=profile_id,
+            role=role,
+        ):
+            out.append(dict(row))
+    return out
+
+
+def trim_hits_preserving_priority_ids(
+    hits: Sequence[Mapping[str, Any]],
+    priority_ids: Optional[Sequence[int]],
+    *,
+    limit: int = 48,
+) -> List[Dict[str, Any]]:
+    """Behält priorisierte Graph-/Slot-Übungen im Kandidatenpool (vor pick_best_path_hit)."""
+    priority_set = {int(x) for x in (priority_ids or []) if int(x) > 0}
+    if not priority_set:
+        return list(hits)[:limit]
+    by_id: Dict[int, Dict[str, Any]] = {}
+    for hit in hits:
+        try:
+            by_id[int(hit["id"])] = dict(hit)
+        except (TypeError, ValueError, KeyError):
+            continue
+    priority_hits = [by_id[eid] for eid in sorted(priority_set) if eid in by_id]
+    rest = [dict(h) for h in hits if int(h.get("id") or 0) not in priority_set]
+    merged = priority_hits + rest
+    return merged[: max(limit, len(priority_hits))]
+
+
 def merge_supplemental_exercise_rows(
     rows: Sequence[Dict[str, Any]],
     supplemental: Sequence[Dict[str, Any]],
@@ -485,6 +552,7 @@ def run_multistage_planning_retrieval(
     intent_weights: Mapping[str, float],
     pack: Mapping[str, Any],
     supplemental_exercise_ids: Optional[Sequence[int]] = None,
+    supplemental_rows_preloaded: Optional[Sequence[Dict[str, Any]]] = None,
 ) -> Tuple[List[Dict[str, Any]], Dict[int, Set[int]], bool]:
     """Orchestriert S1b-0 → S1b-1 (Voll-Library-Ranking)."""
     rows = fetch_all_visible_exercise_rows(
@@ -494,7 +562,9 @@ def run_multistage_planning_retrieval(
         query=pack.get("retrieval_query") or query,
         exercise_kind_any=exercise_kind_any,
     )
-    if supplemental_exercise_ids:
+    if supplemental_rows_preloaded:
+        rows = merge_supplemental_exercise_rows(rows, supplemental_rows_preloaded)
+    elif supplemental_exercise_ids:
         extra = fetch_exercise_rows_by_ids(
             cur,
             supplemental_exercise_ids,
diff --git a/backend/planning_exercise_semantics.py b/backend/planning_exercise_semantics.py
index 1a378cd..ecb9ac9 100644
--- a/backend/planning_exercise_semantics.py
+++ b/backend/planning_exercise_semantics.py
@@ -153,6 +153,48 @@ def _normalize_phrase(text: str) -> str:
     return re.sub(r"\s+", " ", (text or "").strip().lower())
 
 
+_STAGE_TITLE_STOP = frozenset(
+    {"für", "fur", "und", "der", "die", "das", "mit", "im", "in", "am", "an", "zur", "zum", "den", "dem", "des"}
+)
+
+
+def _stage_title_tokens(text: str) -> List[str]:
+    return [
+        tok
+        for tok in _normalize_phrase(text).split()
+        if tok not in _STAGE_TITLE_STOP and len(tok) > 1
+    ]
+
+
+def exercise_title_equivalent_to_stage_goal(title: str, learning_goal: str) -> bool:
+    """
+    Titel entspricht dem Stufen-Lernziel (wortgleich oder nahezu identisch).
+
+    Deckt Graph-Slots ab, bei denen die Übung gezielt zum Lernziel angelegt wurde,
+    ohne dass die Pfad-Haupttechnik im Übungstext vorkommt.
+    """
+    t = _normalize_phrase(title)
+    lg = _normalize_phrase(learning_goal)
+    if len(t) < 3 or len(lg) < 3:
+        return False
+    if t == lg:
+        return True
+    shorter, longer = (t, lg) if len(t) <= len(lg) else (lg, t)
+    if shorter in longer and len(shorter) >= 8 and len(shorter) / max(len(longer), 1) >= 0.72:
+        return True
+    t_tok = _stage_title_tokens(title)
+    lg_tok = _stage_title_tokens(learning_goal)
+    if len(t_tok) >= 2 and t_tok == lg_tok:
+        return True
+    if len(t_tok) >= 2 and len(lg_tok) >= 2:
+        t_set = set(t_tok)
+        lg_set = set(lg_tok)
+        overlap = len(t_set & lg_set)
+        if overlap >= 2 and overlap / max(len(t_set), len(lg_set)) >= 0.85:
+            return True
+    return False
+
+
 def _normalize_query(text: str) -> str:
     return re.sub(r"\s+", " ", (text or "").strip())
 
@@ -1059,6 +1101,9 @@ def exercise_passes_stage_fit(
     if constraints.exclude_phrases and _blob_matches_stage_excludes(blob, constraints.exclude_phrases):
         return False
 
+    if exercise_title_equivalent_to_stage_goal(title, learning_goal or lg):
+        return True
+
     primary_path = (path_primary_topic or "").strip()
     if not primary_path and lg:
         hit = _find_technique_in_text(_normalize_phrase(lg))
@@ -1327,6 +1372,7 @@ __all__ = [
     "build_stage_match_brief",
     "enrich_brief_with_path_constraints",
     "exercise_passes_stage_fit",
+    "exercise_title_equivalent_to_stage_goal",
     "resolve_path_primary_topic",
     "resolve_path_anti_patterns",
     "exercise_passes_stage_learning_goal_gate",
diff --git a/backend/tests/test_planning_exercise_path_builder.py b/backend/tests/test_planning_exercise_path_builder.py
index 5c021b6..ef20664 100644
--- a/backend/tests/test_planning_exercise_path_builder.py
+++ b/backend/tests/test_planning_exercise_path_builder.py
@@ -18,7 +18,7 @@ class _FakeCur:
         return []
 
 
-def test_supplemental_boost_uses_retrieval_boost_not_slot_pins():
+def test_supplemental_boost_includes_slot_assignments_and_retrieval_boost():
     body = ProgressionPathSuggestRequest(
         query="Mawashi Geri Progression",
         slot_assignments=[
@@ -27,7 +27,7 @@ def test_supplemental_boost_uses_retrieval_boost_not_slot_pins():
         retrieval_boost_exercise_ids=[42, 7],
     )
     ids = _supplemental_exercise_ids_from_body(_FakeCur(), body)
-    assert 99 not in ids
+    assert 99 in ids
     assert 42 in ids
     assert 7 in ids
 
diff --git a/backend/tests/test_planning_roadmap_stage_match.py b/backend/tests/test_planning_roadmap_stage_match.py
index 0c9fdc9..e620c95 100644
--- a/backend/tests/test_planning_roadmap_stage_match.py
+++ b/backend/tests/test_planning_roadmap_stage_match.py
@@ -340,6 +340,32 @@ def test_technique_scope_rejects_kumite_when_only_stage_goal_mentions_mawashi():
     )
 
 
+def test_title_equivalent_to_stage_goal():
+    from planning_exercise_semantics import exercise_title_equivalent_to_stage_goal
+
+    assert exercise_title_equivalent_to_stage_goal(
+        "Hüftmobilität für Mae Geri",
+        "Hüftmobilität für Mae Geri",
+    )
+    assert exercise_title_equivalent_to_stage_goal(
+        "Hüftmobilität Mae Geri",
+        "Hüftmobilität für Mae Geri",
+    )
+    assert not exercise_title_equivalent_to_stage_goal("Kumite", "Hüftmobilität für Mae Geri")
+
+
+def test_stage_fit_passes_for_title_equivalent_despite_missing_path_technique():
+    stage_goal = "Koordination Absprung ohne Kick"
+    assert exercise_passes_stage_fit(
+        learning_goal=stage_goal,
+        title=stage_goal,
+        summary="",
+        goal="",
+        path_primary_topic="mawashi geri",
+        path_technique_excludes=["kumite"],
+    )
+
+
 def test_pick_roadmap_relaxed_with_path_primary_when_strict_fails():
     """Bestehende Graph-Übungen: relaxed Gate auch bei gesetztem path_primary_topic."""
     stage_goal = "Hüftmobilität für Mawashi Geri"
diff --git a/frontend/src/components/ProgressionGraphEditor.jsx b/frontend/src/components/ProgressionGraphEditor.jsx
index 042acfa..ecb7fd4 100644
--- a/frontend/src/components/ProgressionGraphEditor.jsx
+++ b/frontend/src/components/ProgressionGraphEditor.jsx
@@ -42,6 +42,7 @@ import {
   slotsAsPathStepRows,
   slotsToEvaluateSteps,
   draftRetrievalBoostExerciseIds,
+  slotsToSlotAssignments,
   syncProgressionRoadmapFromSlots,
   syncSlotPhasesFromRoadmap,
 } from '../utils/progressionGraphDraft'
@@ -415,6 +416,7 @@ export default function ProgressionGraphEditor({ graphId, embedded = false, onSa
         include_llm_roadmap: false,
         roadmap_first: true,
         roadmap_override: override,
+        slot_assignments: slotsToSlotAssignments(synced),
         retrieval_boost_exercise_ids: draftRetrievalBoostExerciseIds(synced),
         progression_graph_id: Number(graphId),
         ...roadmapStructuredPayload(draft.startSituation, draft.targetState, draft.roadmapNotes),
diff --git a/frontend/src/utils/progressionGraphDraft.js b/frontend/src/utils/progressionGraphDraft.js
index 96e7632..c3960e6 100644
--- a/frontend/src/utils/progressionGraphDraft.js
+++ b/frontend/src/utils/progressionGraphDraft.js
@@ -712,7 +712,22 @@ export function draftSiblingEdgePairs(draft) {
   return pairs
 }
 
-/** Bereits zugeordnete Bibliotheks-Übungen — nur Retriever-Boost, kein Pinning. */
+/** Slot-Zuordnungen für Backend-Reconciliation (validiert, nicht blind gepinnt). */
+export function slotsToSlotAssignments(draft) {
+  return (draft.slots || [])
+    .filter((slot) => slot.primary?.kind === 'library' && slot.primary.exerciseId != null)
+    .map((slot) => ({
+      exercise_id: slot.primary.exerciseId,
+      variant_id: slot.primary.variantId || null,
+      title: slot.primary.exerciseTitle || null,
+      is_ai_proposal: false,
+      roadmap_major_step_index: slot.majorStepIndex,
+      roadmap_phase: slot.phase || null,
+      roadmap_learning_goal: slot.learning_goal || null,
+    }))
+}
+
+/** Alle Graph-Übungs-IDs für Retriever-Boost (Slots + Geschwister). */
 export function draftRetrievalBoostExerciseIds(draft) {
   const ids = new Set()
   for (const slot of draft.slots || []) {
@@ -784,7 +799,12 @@ export function applyMatchStepsToSlots(draft, apiSteps) {
     const isProposal = Boolean(step.is_ai_proposal) || step.exercise_id == null
     const hasAiPayload = Boolean(step.ai_suggestion) || Boolean(step.proposal_key)
     if (isProposal && !hasAiPayload) {
-      nextSlots[idx].primary = emptySlotExercise()
+      const wasLibrary =
+        nextSlots[idx].primary?.kind === 'library' && nextSlots[idx].primary.exerciseId != null
+      const mustClear = step.slot_status === 'unfilled' || step.slot_status === 'stripped'
+      if (!wasLibrary || mustClear) {
+        nextSlots[idx].primary = emptySlotExercise()
+      }
     } else if (isProposal) {
       nextSlots[idx].primary = proposalSlotExercise({
         title: step.title || nextSlots[idx].learning_goal,
@@ -800,12 +820,6 @@ export function applyMatchStepsToSlots(draft, apiSteps) {
     }
   }
 
-  for (let i = 0; i < nextSlots.length; i += 1) {
-    if (!touchedMajors.has(i)) {
-      nextSlots[i].primary = emptySlotExercise()
-    }
-  }
-
   return syncProgressionRoadmapFromSlots({ ...draft, slots: nextSlots, dirty: true })
 }
 

From b2fbf6b4afba1d17b6d210babd16b38726a58871 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Thu, 11 Jun 2026 12:45:53 +0200
Subject: [PATCH 30/33] Refactor Roadmap Step Annotation and Slot Assignment
 Logic

- Updated `_annotate_roadmap_step` to change the condition for setting `slot_status` based on `roadmap_match_source`, improving clarity in slot assignment handling.
- Removed the `_try_reconcile_slot_assignment` function to streamline the slot assignment process, as its logic is now integrated into the main flow.
- Enhanced `_match_roadmap_slot` to conditionally preserve slot assignments based on exercise ID, ensuring better handling of existing assignments.
- Improved the handling of semantic scores in `rank_visible_library_hits` to prioritize the best semantic fit, enhancing exercise retrieval accuracy.
- Added tests to validate the new logic for title equivalence and semantic scoring, ensuring robustness in exercise selection processes.
---
 backend/planning_exercise_path_builder.py     | 124 ++----------------
 backend/planning_exercise_path_qa.py          |   7 -
 backend/planning_exercise_retrieval.py        |  27 +++-
 backend/planning_exercise_semantics.py        |  19 ++-
 .../test_planning_roadmap_stage_match.py      |  43 +++++-
 5 files changed, 91 insertions(+), 129 deletions(-)

diff --git a/backend/planning_exercise_path_builder.py b/backend/planning_exercise_path_builder.py
index 1783275..143c804 100644
--- a/backend/planning_exercise_path_builder.py
+++ b/backend/planning_exercise_path_builder.py
@@ -816,7 +816,7 @@ def _annotate_roadmap_step(
         step["roadmap_match_source"] = "stage_spec"
     if step.get("exercise_id") is not None:
         step["slot_status"] = step.get("slot_status") or (
-            "preserved" if step.get("roadmap_match_source") == "slot_reconciled" else "matched"
+            "preserved" if step.get("roadmap_match_source") == "slot_best_match" else "matched"
         )
     else:
         step["slot_status"] = step.get("slot_status") or "unfilled"
@@ -825,84 +825,6 @@ def _annotate_roadmap_step(
     return step
 
 
-def _try_reconcile_slot_assignment(
-    cur,
-    *,
-    assignment: EvaluateStepPayload,
-    stage_spec: StageSpecArtifact,
-    major_step: Optional[MajorStep],
-    tenant: TenantContext,
-    progression_graph_id: Optional[int],
-    stage_match_brief: Optional[PlanningSemanticBrief],
-    stage_goal: str,
-    stage_anti: Optional[List[str]],
-    path_primary: str,
-    path_tech_excludes: Optional[List[str]],
-) -> Optional[Dict[str, Any]]:
-    """
-    Bestehende Slot-Zuordnung behalten, wenn sie noch zum Stufen-Lernziel passt.
-
-    Validiert gegen dieselben Gates wie Match/QA (relaxed), inkl. Titel-Äquivalenz.
-    """
-    from planning_exercise_semantics import (
-        exercise_passes_stage_fit,
-        exercise_title_equivalent_to_stage_goal,
-    )
-
-    step = _path_step_from_slot_assignment(
-        cur,
-        assignment=assignment,
-        stage_spec=stage_spec,
-        major_step=major_step,
-        tenant=tenant,
-        progression_graph_id=progression_graph_id,
-    )
-    if not step:
-        return None
-
-    title = str(step.get("title") or "").strip()
-    summary = str(step.get("summary") or "").strip()
-    goal = ""
-    cur.execute("SELECT goal FROM exercises WHERE id = %s", (int(step["exercise_id"]),))
-    grow = cur.fetchone()
-    if grow:
-        goal = str(grow.get("goal") or "").strip()
-
-    lg = (stage_goal or stage_spec.learning_goal or "").strip()
-    if exercise_title_equivalent_to_stage_goal(title, lg):
-        step["roadmap_match_source"] = "slot_reconciled"
-        step["slot_status"] = "preserved"
-        step["reasons"] = ["Bestehende Zuordnung (Titel = Lernziel)"] + list(step.get("reasons") or [])[:2]
-        return _annotate_roadmap_step(
-            step,
-            stage_spec=stage_spec,
-            major_step=major_step,
-            anti_patterns_override=stage_anti,
-        )
-
-    if exercise_passes_stage_fit(
-        learning_goal=lg,
-        title=title,
-        summary=summary,
-        goal=goal,
-        stage_brief=stage_match_brief,
-        anti_patterns=stage_anti,
-        path_primary_topic=path_primary or None,
-        path_technique_excludes=path_tech_excludes,
-        relaxed=True,
-    ):
-        step["roadmap_match_source"] = "slot_reconciled"
-        step["slot_status"] = "preserved"
-        step["reasons"] = ["Bestehende Zuordnung (Stufen-Fit)"] + list(step.get("reasons") or [])[:2]
-        return _annotate_roadmap_step(
-            step,
-            stage_spec=stage_spec,
-            major_step=major_step,
-            anti_patterns_override=stage_anti,
-        )
-    return None
-
-
 def _stage_validation_context_for_spec(
     cur,
     *,
@@ -1138,7 +1060,16 @@ def _match_roadmap_slot(
         skill_expectations=skill_exp_api,
         anti_patterns_override=stage_anti,
     )
-    step["slot_status"] = "matched"
+    if (
+        slot_priority_exercise_id is not None
+        and int(step["exercise_id"]) == int(slot_priority_exercise_id)
+    ):
+        step["slot_status"] = "preserved"
+        step["roadmap_match_source"] = "slot_best_match"
+        step["reasons"] = ["Bester Treffer (bestehende Zuordnung)"] + list(step.get("reasons") or [])[:2]
+    else:
+        step["slot_status"] = "matched"
+        step["roadmap_match_source"] = "stage_spec"
     return step, None
 
 
@@ -1307,39 +1238,6 @@ def _build_steps_roadmap_first(
         slot_priority_id: Optional[int] = None
 
         if major_idx in assignments:
-            ctx = _stage_validation_context_for_spec(
-                cur,
-                body=body,
-                goal_query=goal_query,
-                semantic_brief=semantic_brief,
-                path_target_profile=path_target_profile,
-                roadmap_ctx=roadmap_ctx,
-                stage_spec=stage_spec,
-                step_index=step_index,
-                stage_count=stage_count,
-                major=major,
-            )
-            reconciled = _try_reconcile_slot_assignment(
-                cur,
-                assignment=assignments[major_idx],
-                stage_spec=stage_spec,
-                major_step=major,
-                tenant=tenant,
-                progression_graph_id=body.progression_graph_id,
-                stage_match_brief=ctx["stage_match_brief"],
-                stage_goal=ctx["stage_goal"],
-                stage_anti=ctx["stage_anti"],
-                path_primary=ctx["path_primary"],
-                path_tech_excludes=ctx["path_tech_excludes"],
-            )
-            if reconciled:
-                steps.append(reconciled)
-                eid = int(reconciled["exercise_id"])
-                used.add(eid)
-                planned_ids.append(eid)
-                anchor_id = eid
-                anchor_variant_id = reconciled.get("variant_id")
-                continue
             try:
                 slot_priority_id = int(assignments[major_idx].exercise_id)
             except (TypeError, ValueError):
diff --git a/backend/planning_exercise_path_qa.py b/backend/planning_exercise_path_qa.py
index 4cb3c85..d3e50a7 100644
--- a/backend/planning_exercise_path_qa.py
+++ b/backend/planning_exercise_path_qa.py
@@ -435,14 +435,7 @@ def detect_off_topic_steps(
     for idx, step in enumerate(steps):
         if step.get("is_ai_proposal") or step.get("exercise_id") is None:
             continue
-        stage_goal_early = (step.get("roadmap_learning_goal") or "").strip()
         bundle = _load_exercise_text_bundle(cur, int(step["exercise_id"]))
-        from planning_exercise_semantics import exercise_title_equivalent_to_stage_goal
-
-        if stage_goal_early and exercise_title_equivalent_to_stage_goal(
-            bundle["title"], stage_goal_early
-        ):
-            continue
         blob = _blob_from_fields(
             bundle["title"],
             bundle["summary"],
diff --git a/backend/planning_exercise_retrieval.py b/backend/planning_exercise_retrieval.py
index deb0d13..085e9e7 100644
--- a/backend/planning_exercise_retrieval.py
+++ b/backend/planning_exercise_retrieval.py
@@ -431,8 +431,30 @@ def rank_visible_library_hits(
                 step_phase=step_phase,
             )
 
+        rank_stage_sem = stage_semantic_score
+        stage_lg = (stage_learning_goal or "").strip()
+        if roadmap_stage_match and stage_lg:
+            raw_brief = build_stage_match_brief(
+                learning_goal=stage_lg,
+                anti_patterns=pack.get("stage_anti_patterns"),
+                phase=step_phase,
+            )
+            raw_sem, raw_reasons = score_exercise_stage_fit(
+                title=title_s,
+                summary=summary_s,
+                goal=goal_s,
+                variant_names=variants_by_ex.get(eid, []),
+                stage_brief=raw_brief,
+                step_phase=step_phase,
+            )
+            rank_stage_sem = max(stage_semantic_score, raw_sem)
+            if raw_sem > stage_semantic_score and raw_reasons:
+                for rr in raw_reasons:
+                    if rr not in stage_semantic_reasons:
+                        stage_semantic_reasons.append(rr)
+
         effective_semantic = (
-            stage_semantic_score
+            rank_stage_sem
             if roadmap_stage_match and stage_match_brief
             else semantic_score
         )
@@ -461,7 +483,7 @@ def rank_visible_library_hits(
                 summary=summary_s,
                 goal=goal_s,
                 stage_brief=stage_match_brief,
-                stage_semantic_score=stage_semantic_score,
+                stage_semantic_score=rank_stage_sem,
                 anti_patterns=pack.get("stage_anti_patterns"),
                 step_phase=step_phase,
                 path_primary_topic=pack.get("path_primary_topic"),
@@ -528,6 +550,7 @@ def rank_visible_library_hits(
                 "reasons": reasons,
                 "semantic_score": round(semantic_score, 4),
                 "stage_semantic_score": round(stage_semantic_score, 4),
+                "stage_rank_semantic": round(rank_stage_sem, 4),
                 "goal": goal_s,
             }
         )
diff --git a/backend/planning_exercise_semantics.py b/backend/planning_exercise_semantics.py
index ecb9ac9..cfc79d6 100644
--- a/backend/planning_exercise_semantics.py
+++ b/backend/planning_exercise_semantics.py
@@ -954,6 +954,7 @@ def enrich_brief_with_path_constraints(
 
 _MIN_STAGE_FIT_SEMANTIC = 0.30
 _MIN_STAGE_FIT_RELAXED = 0.20
+_MIN_TITLE_EQUIV_SEMANTIC = 0.15
 
 
 def build_stage_match_brief(
@@ -1101,8 +1102,7 @@ def exercise_passes_stage_fit(
     if constraints.exclude_phrases and _blob_matches_stage_excludes(blob, constraints.exclude_phrases):
         return False
 
-    if exercise_title_equivalent_to_stage_goal(title, learning_goal or lg):
-        return True
+    title_equiv = exercise_title_equivalent_to_stage_goal(title, learning_goal or lg)
 
     primary_path = (path_primary_topic or "").strip()
     if not primary_path and lg:
@@ -1114,7 +1114,7 @@ def exercise_passes_stage_fit(
         for item in technique_sibling_excludes(primary_path):
             if item not in tech_excludes:
                 tech_excludes.append(item)
-    if primary_path and not exercise_passes_technique_path_scope(
+    if primary_path and not title_equiv and not exercise_passes_technique_path_scope(
         primary_topic=primary_path,
         title=title,
         summary=summary,
@@ -1139,7 +1139,12 @@ def exercise_passes_stage_fit(
             step_phase=step_phase,
         )
 
-    threshold = _MIN_STAGE_FIT_RELAXED if relaxed else min_stage_semantic
+    if relaxed:
+        threshold = _MIN_STAGE_FIT_RELAXED
+    elif title_equiv:
+        threshold = _MIN_TITLE_EQUIV_SEMANTIC
+    else:
+        threshold = min_stage_semantic
     return float(stage_sem or 0.0) >= threshold
 
 
@@ -1291,7 +1296,11 @@ def pick_best_path_hit(
             summary = str(hit.get("summary") or "")
             goal_text = str(hit.get("goal") or hit.get("exercise_goal") or "")
             sem = float(hit.get("semantic_score") or 0.0)
-            stage_sem = float(hit.get("stage_semantic_score") or sem)
+            stage_sem = float(
+                hit.get("stage_rank_semantic")
+                or hit.get("stage_semantic_score")
+                or sem
+            )
 
             if roadmap_stage_match and stage_goal:
                 if not exercise_passes_stage_fit(
diff --git a/backend/tests/test_planning_roadmap_stage_match.py b/backend/tests/test_planning_roadmap_stage_match.py
index e620c95..5da8869 100644
--- a/backend/tests/test_planning_roadmap_stage_match.py
+++ b/backend/tests/test_planning_roadmap_stage_match.py
@@ -354,18 +354,57 @@ def test_title_equivalent_to_stage_goal():
     assert not exercise_title_equivalent_to_stage_goal("Kumite", "Hüftmobilität für Mae Geri")
 
 
-def test_stage_fit_passes_for_title_equivalent_despite_missing_path_technique():
+def test_stage_fit_passes_for_title_equivalent_with_sufficient_semantic_score():
     stage_goal = "Koordination Absprung ohne Kick"
     assert exercise_passes_stage_fit(
         learning_goal=stage_goal,
         title=stage_goal,
-        summary="",
+        summary="Absprung und Landung koordinieren",
         goal="",
         path_primary_topic="mawashi geri",
         path_technique_excludes=["kumite"],
+        stage_semantic_score=0.42,
     )
 
 
+def test_pick_best_prefers_semantic_fit_over_coincidental_title():
+    stage_goal = "Hüftmobilität für Mawashi Geri"
+    stage_brief = build_stage_match_brief(learning_goal=stage_goal)
+    hits = [
+        {
+            "id": 1,
+            "title": "Hüftmobilität für Mawashi Geri",
+            "summary": "allgemeine Aufwärmung",
+            "goal": "",
+            "score": 0.9,
+            "semantic_score": 0.12,
+            "stage_semantic_score": 0.12,
+            "stage_rank_semantic": 0.35,
+        },
+        {
+            "id": 2,
+            "title": "Mawashi Hüftmobilität und Adduktoren",
+            "summary": "Dehnung Hüfte für Rundtritt",
+            "goal": "Mawashi Geri Hüftbeweglichkeit",
+            "score": 0.72,
+            "semantic_score": 0.58,
+            "stage_semantic_score": 0.58,
+            "stage_rank_semantic": 0.62,
+        },
+    ]
+    chosen = pick_best_path_hit(
+        hits,
+        set(),
+        stage_learning_goal=stage_goal,
+        roadmap_stage_match=True,
+        stage_match_brief=stage_brief,
+        path_primary_topic="mawashi geri",
+        path_technique_excludes=technique_sibling_excludes("mawashi geri"),
+    )
+    assert chosen is not None
+    assert int(chosen["id"]) == 2
+
+
 def test_pick_roadmap_relaxed_with_path_primary_when_strict_fails():
     """Bestehende Graph-Übungen: relaxed Gate auch bei gesetztem path_primary_topic."""
     stage_goal = "Hüftmobilität für Mawashi Geri"

From 6d130a7e09d30b4ca0ec8446014f5ea9d5f61eea Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Thu, 11 Jun 2026 12:54:07 +0200
Subject: [PATCH 31/33] Implement Learning Goal Candidate Retrieval and Roadmap
 Fallback Logic

- Added `_safe_tsquery_fragment` to sanitize learning goal input for SQL queries, improving query safety.
- Introduced `_fetch_learning_goal_library_candidate_ids` to retrieve exercise IDs matching learning goals, enhancing exercise relevance in roadmap suggestions.
- Enhanced `_match_roadmap_slot` to utilize learning goal candidates, improving the accuracy of supplemental exercise selection.
- Implemented `_pick_roadmap_rank_fallback` to provide a fallback mechanism for selecting the best exercise when strict matching fails, ensuring better exercise retrieval.
- Updated tests to validate the new learning goal retrieval and fallback logic, ensuring robustness in exercise selection processes.
---
 backend/planning_exercise_path_builder.py     | 106 +++++++++++++++++-
 backend/planning_exercise_semantics.py        |  82 +++++++++++++-
 backend/planning_progression_roadmap.py       |   2 +-
 .../test_planning_roadmap_stage_match.py      |  33 ++++++
 frontend/src/utils/progressionGraphDraft.js   |   9 +-
 5 files changed, 227 insertions(+), 5 deletions(-)

diff --git a/backend/planning_exercise_path_builder.py b/backend/planning_exercise_path_builder.py
index 143c804..8dd6327 100644
--- a/backend/planning_exercise_path_builder.py
+++ b/backend/planning_exercise_path_builder.py
@@ -347,6 +347,87 @@ def _graph_visibility_context(
     )
 
 
+def _safe_tsquery_fragment(text: str) -> str:
+    import re
+
+    cleaned = re.sub(r"[^\w\säöüßÄÖÜ]", " ", text or "", flags=re.UNICODE)
+    words = [w for w in cleaned.split() if len(w) >= 2][:10]
+    return " ".join(words) if words else (text or "")[:60].strip()
+
+
+def _fetch_learning_goal_library_candidate_ids(
+    cur,
+    *,
+    tenant: TenantContext,
+    progression_graph_id: Optional[int],
+    learning_goal: str,
+    limit: int = 24,
+) -> List[int]:
+    """Sichtbare Übungen, deren Titel/Volltext zum Stufen-Lernziel passt."""
+    lg = (learning_goal or "").strip()
+    if len(lg) < 3:
+        return []
+    vis_sql, vis_params = _planning_visibility_sql(cur, tenant, progression_graph_id)
+    tsq = _safe_tsquery_fragment(lg)
+    like_pat = f"%{lg[:100].lower()}%"
+    try:
+        cur.execute(
+            f"""
+            SELECT e.id
+            FROM exercises e
+            WHERE ({vis_sql})
+              AND COALESCE(e.status, '') <> %s
+              AND (
+                lower(trim(e.title)) = lower(trim(%s))
+                OR lower(e.title) LIKE %s
+                OR (%s <> '' AND e.search_vector @@ plainto_tsquery('german', %s))
+              )
+            ORDER BY
+              CASE WHEN lower(trim(e.title)) = lower(trim(%s)) THEN 0 ELSE 1 END,
+              CASE WHEN %s <> '' THEN ts_rank_cd(e.search_vector, plainto_tsquery('german', %s)) ELSE 0 END DESC,
+              e.id ASC
+            LIMIT %s
+            """,
+            [
+                *vis_params,
+                "archived",
+                lg,
+                like_pat,
+                tsq,
+                tsq,
+                lg,
+                tsq,
+                tsq,
+                int(limit),
+            ],
+        )
+    except Exception:
+        cur.execute(
+            f"""
+            SELECT e.id
+            FROM exercises e
+            WHERE ({vis_sql})
+              AND COALESCE(e.status, '') <> %s
+              AND (
+                lower(trim(e.title)) = lower(trim(%s))
+                OR lower(e.title) LIKE %s
+              )
+            ORDER BY CASE WHEN lower(trim(e.title)) = lower(trim(%s)) THEN 0 ELSE 1 END, e.id ASC
+            LIMIT %s
+            """,
+            [*vis_params, "archived", lg, like_pat, lg, int(limit)],
+        )
+    out: List[int] = []
+    for row in cur.fetchall() or []:
+        try:
+            eid = int(row.get("id") or 0)
+        except (TypeError, ValueError):
+            continue
+        if eid > 0:
+            out.append(eid)
+    return out
+
+
 def _load_supplemental_exercise_rows(
     cur,
     *,
@@ -1000,10 +1081,31 @@ def _match_roadmap_slot(
     step_kind = resolve_step_exercise_kind_filter(stage_spec, body.exercise_kind_any)
 
     supplemental_ids = _supplemental_exercise_ids_from_body(cur, body)
+    lg_candidates = _fetch_learning_goal_library_candidate_ids(
+        cur,
+        tenant=tenant,
+        progression_graph_id=body.progression_graph_id,
+        learning_goal=stage_goal,
+    )
+    supplemental_ids = list(
+        dict.fromkeys(
+            int(x)
+            for x in [
+                *supplemental_ids,
+                *lg_candidates,
+                slot_priority_exercise_id,
+            ]
+            if x is not None and int(x) > 0
+        )
+    )
     priority_ids = list(
         dict.fromkeys(
-            x
-            for x in [slot_priority_exercise_id, *(body.retrieval_boost_exercise_ids or [])]
+            int(x)
+            for x in [
+                slot_priority_exercise_id,
+                *(body.retrieval_boost_exercise_ids or []),
+                *lg_candidates[:8],
+            ]
             if x is not None and int(x) > 0
         )
     )
diff --git a/backend/planning_exercise_semantics.py b/backend/planning_exercise_semantics.py
index cfc79d6..501c884 100644
--- a/backend/planning_exercise_semantics.py
+++ b/backend/planning_exercise_semantics.py
@@ -955,6 +955,7 @@ def enrich_brief_with_path_constraints(
 _MIN_STAGE_FIT_SEMANTIC = 0.30
 _MIN_STAGE_FIT_RELAXED = 0.20
 _MIN_TITLE_EQUIV_SEMANTIC = 0.15
+_MIN_ROADMAP_FALLBACK_RANK = 0.15
 
 
 def build_stage_match_brief(
@@ -1260,6 +1261,76 @@ def exercise_passes_path_semantic_gate(
     return False
 
 
+def _pick_roadmap_rank_fallback(
+    hits: List[Dict[str, Any]],
+    used_exercise_ids: Set[int],
+    *,
+    stage_learning_goal: str,
+    stage_anti_patterns: Optional[Sequence[str]] = None,
+    path_primary_topic: Optional[str] = None,
+    path_technique_excludes: Optional[Sequence[str]] = None,
+) -> Optional[Dict[str, Any]]:
+    """
+    Roadmap-Notfall: bester Treffer nach Stufen-Ranking, wenn striktes Gate leer läuft.
+
+    Filtert weiterhin Ausschlüsse und Technik-Scope (Kumite etc.), aber ohne
+    Mindest-Semantik-Schwelle — so finden auch wortnahe Bibliotheks-Übungen den Slot.
+    """
+    stage_goal = (stage_learning_goal or "").strip()
+    if not stage_goal or not hits:
+        return None
+
+    best: Optional[Dict[str, Any]] = None
+    best_key: Tuple[float, float] = (-1.0, -1.0)
+    for hit in hits:
+        try:
+            eid = int(hit["id"])
+        except (TypeError, ValueError, KeyError):
+            continue
+        if eid in used_exercise_ids:
+            continue
+        title = str(hit.get("title") or "")
+        summary = str(hit.get("summary") or "")
+        goal_text = str(hit.get("goal") or hit.get("exercise_goal") or "")
+        blob = _blob_from_fields(title, summary, goal_text, [])
+        constraints = parse_stage_goal_constraints(stage_goal, stage_anti_patterns)
+        if constraints.exclude_phrases and _blob_matches_stage_excludes(
+            blob, constraints.exclude_phrases
+        ):
+            continue
+        title_equiv = exercise_title_equivalent_to_stage_goal(title, stage_goal)
+        primary = (path_primary_topic or "").strip()
+        if primary and not title_equiv:
+            tech_excludes = list(path_technique_excludes or [])
+            for item in technique_sibling_excludes(primary):
+                if item not in tech_excludes:
+                    tech_excludes.append(item)
+            if not exercise_passes_technique_path_scope(
+                primary_topic=primary,
+                title=title,
+                summary=summary,
+                goal=goal_text,
+                learning_goal=stage_goal,
+                sibling_excludes=tech_excludes,
+                relaxed=True,
+            ):
+                continue
+        rank_sem = float(
+            hit.get("stage_rank_semantic")
+            or hit.get("stage_semantic_score")
+            or hit.get("semantic_score")
+            or 0.0
+        )
+        score = float(hit.get("score") or 0.0)
+        key = (rank_sem, score)
+        if key > best_key:
+            best_key = key
+            best = hit
+    if best is None or best_key[0] < _MIN_ROADMAP_FALLBACK_RANK:
+        return None
+    return best
+
+
 def pick_best_path_hit(
     hits: List[Dict[str, Any]],
     used_exercise_ids: Set[int],
@@ -1341,7 +1412,16 @@ def pick_best_path_hit(
 
     if roadmap_stage_match:
         chosen = _scan(strict=False)
-        return chosen
+        if chosen:
+            return chosen
+        return _pick_roadmap_rank_fallback(
+            hits,
+            used_exercise_ids,
+            stage_learning_goal=stage_goal,
+            stage_anti_patterns=stage_anti_patterns,
+            path_primary_topic=path_primary_topic,
+            path_technique_excludes=path_technique_excludes,
+        )
 
     chosen = _scan(strict=False)
     if chosen:
diff --git a/backend/planning_progression_roadmap.py b/backend/planning_progression_roadmap.py
index f772345..dfab0c2 100644
--- a/backend/planning_progression_roadmap.py
+++ b/backend/planning_progression_roadmap.py
@@ -856,7 +856,7 @@ def build_roadmap_unfilled_gap_specs(
                 "roadmap_major_step_index": stage_spec.major_step_index,
             }
         )
-    return specs[:5]
+    return specs[:12]
 
 
 def build_stage_specs(
diff --git a/backend/tests/test_planning_roadmap_stage_match.py b/backend/tests/test_planning_roadmap_stage_match.py
index 5da8869..21ae1c2 100644
--- a/backend/tests/test_planning_roadmap_stage_match.py
+++ b/backend/tests/test_planning_roadmap_stage_match.py
@@ -367,6 +367,39 @@ def test_stage_fit_passes_for_title_equivalent_with_sufficient_semantic_score():
     )
 
 
+def test_roadmap_rank_fallback_picks_best_stage_semantic():
+    from planning_exercise_semantics import _pick_roadmap_rank_fallback
+
+    stage_goal = "Hüftmobilität für Mawashi Geri"
+    hits = [
+        {
+            "id": 1,
+            "title": "Hüftmobilität für Mawashi Geri",
+            "summary": "Aufwärmen",
+            "goal": "",
+            "score": 0.9,
+            "stage_rank_semantic": 0.32,
+        },
+        {
+            "id": 2,
+            "title": "Mawashi Hüftdehnung",
+            "summary": "Adduktoren und Hüfte",
+            "goal": "Mobilität für Mawashi Geri",
+            "score": 0.7,
+            "stage_rank_semantic": 0.58,
+        },
+    ]
+    chosen = _pick_roadmap_rank_fallback(
+        hits,
+        set(),
+        stage_learning_goal=stage_goal,
+        path_primary_topic="mawashi geri",
+        path_technique_excludes=technique_sibling_excludes("mawashi geri"),
+    )
+    assert chosen is not None
+    assert int(chosen["id"]) == 2
+
+
 def test_pick_best_prefers_semantic_fit_over_coincidental_title():
     stage_goal = "Hüftmobilität für Mawashi Geri"
     stage_brief = build_stage_match_brief(learning_goal=stage_goal)
diff --git a/frontend/src/utils/progressionGraphDraft.js b/frontend/src/utils/progressionGraphDraft.js
index c3960e6..9a98e79 100644
--- a/frontend/src/utils/progressionGraphDraft.js
+++ b/frontend/src/utils/progressionGraphDraft.js
@@ -727,7 +727,7 @@ export function slotsToSlotAssignments(draft) {
     }))
 }
 
-/** Alle Graph-Übungs-IDs für Retriever-Boost (Slots + Geschwister). */
+/** Alle Graph-Übungs-IDs für Retriever-Boost (Slots + Geschwister + gespeichertes Artefakt). */
 export function draftRetrievalBoostExerciseIds(draft) {
   const ids = new Set()
   for (const slot of draft.slots || []) {
@@ -737,6 +737,13 @@ export function draftRetrievalBoostExerciseIds(draft) {
       if (sib.kind === 'library' && sib.exerciseId != null) ids.add(sib.exerciseId)
     }
   }
+  const saved = draft?.slot_contents || draft?.planningArtifact?.slot_contents
+  if (Array.isArray(saved)) {
+    for (const raw of saved) {
+      const eid = raw?.primary?.exercise_id ?? raw?.exercise_id
+      if (eid != null && Number.isFinite(Number(eid))) ids.add(Number(eid))
+    }
+  }
   return [...ids]
 }
 

From de939481ba60ec5dbe6d4e518b7a46ae920bda8a Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Thu, 11 Jun 2026 13:13:46 +0200
Subject: [PATCH 32/33] Enhance Gap Fill Offer Handling and Progression Path
 Logic

- Updated `suggest_progression_path` to ensure unique gap fill offers are collected and added based on their IDs, improving the relevance of suggestions.
- Refined the logic for setting `slot_status` and handling `gap_offer` and `proposal_key` in steps, enhancing clarity in progression path management.
- Improved the `collectGapOffersFromApiResponse` function to consolidate gap offers from various sources, ensuring comprehensive offer retrieval.
- Enhanced the handling of unfilled slots in `applyMatchStepsToSlots`, ensuring proper assignment of proposals and gap offers.
- Added tests to validate the new logic for gap fill offers and slot assignments, ensuring robustness in path suggestion features.
---
 backend/planning_exercise_path_builder.py   | 25 +++++++++---
 frontend/src/utils/progressionGraphDraft.js | 45 ++++++++++++++++-----
 2 files changed, 53 insertions(+), 17 deletions(-)

diff --git a/backend/planning_exercise_path_builder.py b/backend/planning_exercise_path_builder.py
index 8dd6327..4f2c912 100644
--- a/backend/planning_exercise_path_builder.py
+++ b/backend/planning_exercise_path_builder.py
@@ -2107,7 +2107,7 @@ def suggest_progression_path(
             max_steps=max_steps,
         )
         if body.include_ai_gap_fill:
-            seen_offer_ids = {o.get("offer_id") for o in gap_fill_offers}
+            seen_offer_ids = {o.get("offer_id") for o in gap_fill_offers if o.get("offer_id")}
             for step in steps:
                 if step.get("exercise_id") is not None:
                     continue
@@ -2115,6 +2115,12 @@ def suggest_progression_path(
                     major_idx = int(step["roadmap_major_step_index"])
                 except (TypeError, ValueError, KeyError):
                     continue
+                if step.get("gap_offer") and step.get("proposal_key"):
+                    oid = step["gap_offer"].get("offer_id")
+                    if oid and oid not in seen_offer_ids:
+                        gap_fill_offers.append(dict(step["gap_offer"]))
+                        seen_offer_ids.add(oid)
+                    continue
                 stage_spec = next(
                     (
                         s
@@ -2123,15 +2129,19 @@ def suggest_progression_path(
                     ),
                     None,
                 )
-                if stage_spec is None:
-                    continue
+                learning_goal = (
+                    (stage_spec.learning_goal if stage_spec else None)
+                    or step.get("roadmap_learning_goal")
+                    or step.get("title")
+                    or ""
+                ).strip()
                 spec = {
                     "source": "roadmap_unfilled",
                     "insert_after_index": max(major_idx - 1, -1),
                     "roadmap_major_step_index": major_idx,
                     "phase": (step.get("roadmap_phase") or "vertiefung").strip().lower(),
-                    "title_hint": (stage_spec.learning_goal or step.get("title") or f"Slot {major_idx + 1}")[:120],
-                    "sketch": (stage_spec.learning_goal or "").strip(),
+                    "title_hint": (learning_goal or f"Slot {major_idx + 1}")[:120],
+                    "sketch": learning_goal,
                     "rationale": f"Slot {major_idx + 1} — keine passende Bibliotheks-Übung; KI-Entwurf für diese Stufe.",
                 }
                 offer = build_gap_fill_offer(
@@ -2148,7 +2158,10 @@ def suggest_progression_path(
                         semantic_brief=semantic_brief,
                     ),
                 )
-                if offer.get("offer_id") not in seen_offer_ids:
+                step["gap_offer"] = offer
+                step["proposal_key"] = offer.get("offer_id")
+                step["slot_status"] = "unfilled"
+                if offer.get("offer_id") and offer.get("offer_id") not in seen_offer_ids:
                     gap_fill_offers.append(offer)
                     seen_offer_ids.add(offer.get("offer_id"))
 
diff --git a/frontend/src/utils/progressionGraphDraft.js b/frontend/src/utils/progressionGraphDraft.js
index 9a98e79..4c57960 100644
--- a/frontend/src/utils/progressionGraphDraft.js
+++ b/frontend/src/utils/progressionGraphDraft.js
@@ -214,10 +214,21 @@ const GAP_OFFER_SOURCE_PRIORITY = {
 }
 
 export function collectGapOffersFromApiResponse(res) {
-  const top = Array.isArray(res?.gap_fill_offers) ? res.gap_fill_offers : []
-  if (top.length) return top
-  const qa = res?.path_qa || {}
-  return Array.isArray(qa?.gap_fill_offers) ? qa.gap_fill_offers : []
+  const out = []
+  const seen = new Set()
+  const add = (offer) => {
+    if (!offer || typeof offer !== 'object') return
+    const id = offer.offer_id || `${offer.source}-${offer.roadmap_major_step_index}`
+    if (seen.has(id)) return
+    seen.add(id)
+    out.push(offer)
+  }
+  for (const offer of res?.gap_fill_offers || []) add(offer)
+  for (const offer of res?.path_qa?.gap_fill_offers || []) add(offer)
+  for (const step of res?.steps || []) {
+    if (step?.gap_offer) add(step.gap_offer)
+  }
+  return out
 }
 
 /** Maximal ein Angebot pro Slot — Roadmap-Lücken vor Brücken/QS. */
@@ -805,13 +816,25 @@ export function applyMatchStepsToSlots(draft, apiSteps) {
 
     const isProposal = Boolean(step.is_ai_proposal) || step.exercise_id == null
     const hasAiPayload = Boolean(step.ai_suggestion) || Boolean(step.proposal_key)
-    if (isProposal && !hasAiPayload) {
-      const wasLibrary =
-        nextSlots[idx].primary?.kind === 'library' && nextSlots[idx].primary.exerciseId != null
-      const mustClear = step.slot_status === 'unfilled' || step.slot_status === 'stripped'
-      if (!wasLibrary || mustClear) {
-        nextSlots[idx].primary = emptySlotExercise()
-      }
+    const isUnfilledSlot =
+      step.slot_status === 'unfilled' ||
+      step.slot_status === 'stripped' ||
+      step.roadmap_match_source === 'unfilled' ||
+      Boolean(step.gap_offer)
+    if (isProposal && !hasAiPayload && isUnfilledSlot) {
+      const offer = step.gap_offer || {}
+      nextSlots[idx].primary = proposalSlotExercise({
+        title:
+          offer.title_hint ||
+          step.roadmap_learning_goal ||
+          step.title ||
+          nextSlots[idx].learning_goal ||
+          `Slot ${idx + 1}`,
+        proposalKey: offer.offer_id || step.proposal_key || `roadmap-unfilled-${idx}`,
+        aiSuggestion: offer.ai_suggestion || null,
+      })
+    } else if (isProposal && !hasAiPayload) {
+      nextSlots[idx].primary = emptySlotExercise()
     } else if (isProposal) {
       nextSlots[idx].primary = proposalSlotExercise({
         title: step.title || nextSlots[idx].learning_goal,

From df93da9a03167097f6e87af4bc4fc29749ef4c90 Mon Sep 17 00:00:00 2001
From: Lars <Lars@stommer.de>
Date: Thu, 11 Jun 2026 21:20:47 +0200
Subject: [PATCH 33/33] Enhance Gap Fill and Rematch Logic in Progression Path

- Introduced `_step_neighbors_at_index` to safely retrieve neighboring steps without causing IndexErrors, improving robustness in gap fill specifications.
- Updated `collect_gap_fill_specs` to utilize the new neighbor retrieval function, ensuring safe access to adjacent steps during gap fill processing.
- Enhanced rematch logic in `_run_roadmap_rematch_loop` to incorporate `max_rematch_rounds`, allowing for controlled iterations during roadmap rematching.
- Improved handling of unfilled roadmap slots in `collect_rematch_slot_indices`, ensuring accurate identification of gaps in the progression path.
- Added tests to validate the new gap fill handling and rematch logic, ensuring reliability in path suggestion features.
---
 backend/planning_exercise_path_ai_fill.py     |  27 +++-
 backend/planning_exercise_path_builder.py     | 149 +++++++++++++-----
 backend/planning_path_rematch.py              |  15 +-
 .../test_planning_exercise_path_ai_fill.py    |  52 ++++++
 backend/tests/test_planning_path_rematch.py   |  13 ++
 backend/version.py                            |  14 +-
 6 files changed, 217 insertions(+), 53 deletions(-)

diff --git a/backend/planning_exercise_path_ai_fill.py b/backend/planning_exercise_path_ai_fill.py
index e798161..81373bf 100644
--- a/backend/planning_exercise_path_ai_fill.py
+++ b/backend/planning_exercise_path_ai_fill.py
@@ -337,6 +337,18 @@ def _spec_dedupe_key(spec: Mapping[str, Any]) -> Tuple[Any, ...]:
     )
 
 
+def _step_neighbors_at_index(
+    steps: Sequence[Mapping[str, Any]],
+    idx: int,
+) -> Tuple[Optional[Mapping[str, Any]], Optional[Mapping[str, Any]]]:
+    """Vorheriger/nächster Pfadschritt ohne IndexError (Rand-Slots, leere Stufen)."""
+    if idx < 0 or idx >= len(steps):
+        return None, None
+    step_a = steps[idx - 1] if idx > 0 else None
+    step_b = steps[idx + 1] if idx + 1 < len(steps) else None
+    return step_a, step_b
+
+
 def collect_gap_fill_specs(
     *,
     steps: Sequence[Mapping[str, Any]],
@@ -364,8 +376,10 @@ def collect_gap_fill_specs(
             int(gap["from_exercise_id"]),
             int(gap["to_exercise_id"]),
         )
-        if idx is None:
+        if idx is None or idx + 1 >= len(steps):
             continue
+        step_a = steps[idx]
+        step_b = steps[idx + 1]
         phase = gap.get("expected_phase") or "vertiefung"
         add(
             {
@@ -377,12 +391,12 @@ def collect_gap_fill_specs(
                 "sketch": _default_sketch(
                     goal_query=goal_query,
                     brief=brief,
-                    step_a=steps[idx],
-                    step_b=steps[idx + 1],
+                    step_a=step_a,
+                    step_b=step_b,
                     phase=str(phase),
                     rationale="Bibliothek enthält keine passende Brücke.",
                 ),
-                "rationale": "Lücke zwischen benachbarten Schritten — keine passende Bibliotheks-Übung.",
+                "rationale": "Lücke zwischen benachbaren Schritten — keine passende Bibliotheks-Übung.",
             }
         )
 
@@ -408,6 +422,7 @@ def collect_gap_fill_specs(
             idx = int(ot.get("step_index") or 0)
         if idx < 0 or idx >= len(steps):
             continue
+        step_a, step_b = _step_neighbors_at_index(steps, idx)
         phase = ot.get("expected_phase") or "vertiefung"
         insert_after = max(idx - 1, -1)
         add(
@@ -426,8 +441,8 @@ def collect_gap_fill_specs(
                 "sketch": _default_sketch(
                     goal_query=goal_query,
                     brief=brief,
-                    step_a=steps[idx - 1],
-                    step_b=steps[idx + 1],
+                    step_a=step_a,
+                    step_b=step_b,
                     phase=str(phase),
                     rationale=f"Ersetzt themenfremden Schritt „{ot.get('title')}“.",
                 ),
diff --git a/backend/planning_exercise_path_builder.py b/backend/planning_exercise_path_builder.py
index 4f2c912..58c08fe 100644
--- a/backend/planning_exercise_path_builder.py
+++ b/backend/planning_exercise_path_builder.py
@@ -108,6 +108,7 @@ class ProgressionPathSuggestRequest(BaseModel):
     include_llm_intent: bool = True
     include_path_qa: bool = True
     auto_rematch_after_qa: bool = True
+    max_rematch_rounds: int = Field(default=2, ge=0, le=3)
     include_llm_path_qa: bool = True
     include_path_reorder: bool = True
     include_ai_gap_fill: bool = True
@@ -438,7 +439,17 @@ def _load_supplemental_exercise_rows(
     vis_params: Sequence[Any],
 ) -> List[Dict[str, Any]]:
     """Supplemental-Übungen mit Graph-Sichtbarkeit, Fallback Library-vis_sql."""
-    ids = list(dict.fromkeys(int(x) for x in (exercise_ids or []) if int(x) > 0))
+    ids: List[int] = []
+    for raw in exercise_ids or []:
+        if raw is None:
+            continue
+        try:
+            eid = int(raw)
+        except (TypeError, ValueError):
+            continue
+        if eid > 0:
+            ids.append(eid)
+    ids = list(dict.fromkeys(ids))
     if not ids:
         return []
     if progression_graph_id and int(progression_graph_id) > 0:
@@ -1222,7 +1233,19 @@ def _normalize_roadmap_steps_coverage(
     return out
 
 
-def _maybe_rematch_roadmap_after_strip(
+def _merge_rematch_unfilled(
+    roadmap_unfilled: List[Tuple[int, StageSpecArtifact]],
+    rematch_new_unfilled: List[Tuple[int, StageSpecArtifact]],
+) -> List[Tuple[int, StageSpecArtifact]]:
+    if not rematch_new_unfilled:
+        return roadmap_unfilled
+    remapped = {sp.major_step_index for _, sp in rematch_new_unfilled}
+    kept = [item for item in roadmap_unfilled if item[1].major_step_index not in remapped]
+    kept.extend(rematch_new_unfilled)
+    return kept
+
+
+def _run_roadmap_rematch_loop(
     cur,
     *,
     tenant: TenantContext,
@@ -1237,6 +1260,7 @@ def _maybe_rematch_roadmap_after_strip(
     stripped_off_topic: List[Dict[str, Any]],
     off_topic_before_strip: List[Dict[str, Any]],
     roadmap_unfilled: List[Tuple[int, StageSpecArtifact]],
+    gaps: List[Dict[str, Any]],
 ) -> Tuple[
     List[Dict[str, Any]],
     List[Dict[str, Any]],
@@ -1245,54 +1269,92 @@ def _maybe_rematch_roadmap_after_strip(
     int,
     List[Tuple[int, StageSpecArtifact]],
 ]:
+    """Phase A/B: Rematch-Schleife aus Strip, unfilled Slots und optimization_hints."""
     rematch_log: List[Dict[str, Any]] = []
     rematch_rounds = 0
-    if not body.auto_rematch_after_qa or not roadmap_ctx.stage_specs:
-        return steps, rematch_log, stripped_off_topic, [], rematch_rounds, roadmap_unfilled
+    max_rounds = int(body.max_rematch_rounds or 0)
+    if not body.auto_rematch_after_qa or max_rounds <= 0 or not roadmap_ctx.stage_specs:
+        off_topic_steps = detect_off_topic_steps(
+            cur,
+            steps,
+            brief=semantic_brief,
+            goal_query=goal_query,
+        )
+        return steps, rematch_log, stripped_off_topic, off_topic_steps, rematch_rounds, roadmap_unfilled
 
-    slot_indices, rematch_reasons = collect_rematch_slot_indices(
-        stripped_off_topic=stripped_off_topic,
-        off_topic_steps=off_topic_before_strip if not stripped_off_topic else [],
-        optimization_hints=[],
-        stage_specs=roadmap_ctx.stage_specs,
-    )
-    if not slot_indices:
-        return steps, rematch_log, stripped_off_topic, [], rematch_rounds, roadmap_unfilled
+    current_stripped = list(stripped_off_topic or [])
+    use_initial_off_topic = not current_stripped
+    off_topic_steps: List[Dict[str, Any]] = []
 
-    steps, rematch_log, rematch_new_unfilled = rematch_roadmap_slots(
-        cur,
-        tenant=tenant,
-        body=body,
-        goal_query=goal_query,
-        max_steps=max_steps,
-        semantic_brief=semantic_brief,
-        path_target_profile=path_target_profile,
-        path_intent=path_intent,
-        roadmap_ctx=roadmap_ctx,
-        steps=steps,
-        slot_indices=slot_indices,
-        rematch_reasons=rematch_reasons,
-        match_slot_fn=_match_roadmap_slot,
-    )
-    rematch_rounds = 1
-    stripped_off_topic = prune_stripped_after_rematch(stripped_off_topic, rematch_log)
-    if rematch_new_unfilled:
-        remapped = {sp.major_step_index for _, sp in rematch_new_unfilled}
-        roadmap_unfilled = [
-            item for item in roadmap_unfilled if item[1].major_step_index not in remapped
-        ]
-        roadmap_unfilled.extend(rematch_new_unfilled)
+    for round_idx in range(max_rounds):
+        mini_qa = run_multistage_path_qa(
+            off_topic_steps=off_topic_steps if round_idx > 0 else [],
+            stripped_off_topic=current_stripped if round_idx == 0 else [],
+            gaps=gaps if round_idx == 0 else [],
+            llm_qa=None,
+            llm_applied=False,
+            roadmap_unfilled=roadmap_unfilled,
+        )
+        optimization_hints = list(mini_qa.get("optimization_hints") or [])
+
+        slot_indices, rematch_reasons = collect_rematch_slot_indices(
+            stripped_off_topic=current_stripped if round_idx == 0 else [],
+            off_topic_steps=off_topic_before_strip if round_idx == 0 and use_initial_off_topic else [],
+            optimization_hints=optimization_hints,
+            stage_specs=roadmap_ctx.stage_specs,
+            roadmap_unfilled=roadmap_unfilled,
+        )
+        if not slot_indices:
+            break
+
+        steps, round_log, rematch_new_unfilled = rematch_roadmap_slots(
+            cur,
+            tenant=tenant,
+            body=body,
+            goal_query=goal_query,
+            max_steps=max_steps,
+            semantic_brief=semantic_brief,
+            path_target_profile=path_target_profile,
+            path_intent=path_intent,
+            roadmap_ctx=roadmap_ctx,
+            steps=steps,
+            slot_indices=slot_indices,
+            rematch_reasons=rematch_reasons,
+            match_slot_fn=_match_roadmap_slot,
+        )
+        rematch_rounds += 1
+        for entry in round_log:
+            tagged = dict(entry)
+            tagged["round"] = rematch_rounds
+            rematch_log.append(tagged)
+
+        current_stripped = prune_stripped_after_rematch(current_stripped, round_log)
+        roadmap_unfilled = _merge_rematch_unfilled(roadmap_unfilled, rematch_new_unfilled)
+        use_initial_off_topic = False
+
+        off_topic_steps = detect_off_topic_steps(
+            cur,
+            steps,
+            brief=semantic_brief,
+            goal_query=goal_query,
+        )
+        if round_idx + 1 >= max_rounds:
+            break
+        if not off_topic_steps and not roadmap_unfilled:
+            break
+
+    if not off_topic_steps:
+        off_topic_steps = detect_off_topic_steps(
+            cur,
+            steps,
+            brief=semantic_brief,
+            goal_query=goal_query,
+        )
 
-    off_topic_steps = detect_off_topic_steps(
-        cur,
-        steps,
-        brief=semantic_brief,
-        goal_query=goal_query,
-    )
     return (
         steps,
         rematch_log,
-        stripped_off_topic,
+        current_stripped,
         off_topic_steps,
         rematch_rounds,
         roadmap_unfilled,
@@ -2000,7 +2062,7 @@ def suggest_progression_path(
                 rematch_off_topic,
                 rematch_rounds,
                 roadmap_unfilled,
-            ) = _maybe_rematch_roadmap_after_strip(
+            ) = _run_roadmap_rematch_loop(
                 cur,
                 tenant=tenant,
                 body=body,
@@ -2014,6 +2076,7 @@ def suggest_progression_path(
                 stripped_off_topic=stripped_off_topic,
                 off_topic_before_strip=off_topic_before_strip,
                 roadmap_unfilled=roadmap_unfilled,
+                gaps=gaps,
             )
             if rematch_off_topic:
                 off_topic_steps = rematch_off_topic
diff --git a/backend/planning_path_rematch.py b/backend/planning_path_rematch.py
index d86f5b9..4bc19dd 100644
--- a/backend/planning_path_rematch.py
+++ b/backend/planning_path_rematch.py
@@ -1,5 +1,5 @@
 """
-Auto-Rematch nach Pfad-QS — betroffene Roadmap-Slots erneut matchen (Phase A).
+Auto-Rematch nach Pfad-QS — betroffene Roadmap-Slots erneut matchen (Phase A/B).
 """
 from __future__ import annotations
 
@@ -14,6 +14,7 @@ def collect_rematch_slot_indices(
     off_topic_steps: Sequence[Mapping[str, Any]],
     optimization_hints: Sequence[Mapping[str, Any]],
     stage_specs: Sequence[StageSpecArtifact],
+    roadmap_unfilled: Optional[Sequence[Any]] = None,
 ) -> Tuple[Set[int], Dict[int, str]]:
     """Major-Step-Indizes für rematch_slot + Begründung pro Slot."""
     spec_by_pos = list(stage_specs)
@@ -64,6 +65,18 @@ def collect_rematch_slot_indices(
         if midx is not None:
             _register(midx, str(hint.get("reason") or hint.get("issue") or "rematch_slot"))
 
+    for item in roadmap_unfilled or []:
+        if isinstance(item, (list, tuple)) and len(item) >= 2:
+            idx, spec = item[0], item[1]
+            midx = getattr(spec, "major_step_index", idx)
+            _register(int(midx), "Keine passende Übung für Roadmap-Stufe")
+        elif isinstance(item, dict):
+            midx = _resolve_major(item)
+            if midx is not None:
+                issue = str(item.get("issue") or "roadmap_unfilled")
+                r = (item.get("reasons") or [issue])[0] if item.get("reasons") else issue
+                _register(midx, str(r))
+
     return indices, reasons
 
 
diff --git a/backend/tests/test_planning_exercise_path_ai_fill.py b/backend/tests/test_planning_exercise_path_ai_fill.py
index 8748b04..f39b3bf 100644
--- a/backend/tests/test_planning_exercise_path_ai_fill.py
+++ b/backend/tests/test_planning_exercise_path_ai_fill.py
@@ -214,3 +214,55 @@ def test_build_gap_fill_offer_exposes_context_preview():
     )
     assert offer["context_preview"]["start_situation"] == "Steppbewegung"
     assert "variable Rhythmen" in offer["goal_for_ai"]
+
+
+def test_collect_gap_fill_specs_off_topic_last_step_no_crash():
+    """Rand-Slot: off_topic am letzten Schritt darf keinen IndexError auslösen (500)."""
+    brief = build_semantic_brief("Mawashi Geri Kumite")
+    steps = [
+        {"exercise_id": 1, "title": "Stand", "roadmap_major_step_index": 0},
+        {"exercise_id": 2, "title": "Yoko Geri", "roadmap_major_step_index": 1},
+    ]
+    specs = collect_gap_fill_specs(
+        steps=steps,
+        unfilled_gaps=[],
+        off_topic_steps=[
+            {
+                "step_index": 1,
+                "roadmap_major_step_index": 1,
+                "title": "Yoko Geri",
+                "expected_phase": "anwendung",
+            }
+        ],
+        llm_specs=[],
+        brief=brief,
+        goal_query="Mawashi Geri Kumite",
+    )
+    assert len(specs) == 1
+    assert specs[0]["source"] == "off_topic"
+    assert "Stand" in specs[0]["sketch"]
+
+
+def test_collect_gap_fill_specs_off_topic_first_step_uses_safe_neighbors():
+    brief = build_semantic_brief("Mawashi Geri")
+    steps = [
+        {"exercise_id": 1, "title": "Yoko Geri", "roadmap_major_step_index": 0},
+        {"exercise_id": 2, "title": "Mawashi", "roadmap_major_step_index": 1},
+    ]
+    specs = collect_gap_fill_specs(
+        steps=steps,
+        unfilled_gaps=[],
+        off_topic_steps=[
+            {
+                "step_index": 0,
+                "roadmap_major_step_index": 0,
+                "title": "Yoko Geri",
+            }
+        ],
+        llm_specs=[],
+        brief=brief,
+        goal_query="Mawashi Geri",
+    )
+    assert len(specs) == 1
+    assert "Mawashi" in specs[0]["sketch"]
+    assert "vorherigem Schritt" in specs[0]["sketch"]
diff --git a/backend/tests/test_planning_path_rematch.py b/backend/tests/test_planning_path_rematch.py
index 46e4b02..78cc99f 100644
--- a/backend/tests/test_planning_path_rematch.py
+++ b/backend/tests/test_planning_path_rematch.py
@@ -68,6 +68,19 @@ def test_collect_rematch_slot_indices_from_optimization_hints():
     assert indices == {0}
 
 
+def test_collect_rematch_slot_indices_from_roadmap_unfilled():
+    specs = _stage_specs()
+    indices, reasons = collect_rematch_slot_indices(
+        stripped_off_topic=[],
+        off_topic_steps=[],
+        optimization_hints=[],
+        stage_specs=specs,
+        roadmap_unfilled=[(1, specs[1])],
+    )
+    assert indices == {1}
+    assert "Roadmap-Stufe" in reasons[1]
+
+
 def test_rematch_roadmap_slots_replaces_only_target_slot():
     specs = _stage_specs()
     ctx = ProgressionRoadmapContext(
diff --git a/backend/version.py b/backend/version.py
index 8ec0719..b09870e 100644
--- a/backend/version.py
+++ b/backend/version.py
@@ -1,7 +1,7 @@
 # Shinkan Jinkendo Version Information
 
-APP_VERSION = "0.8.225"
-BUILD_DATE = "2026-06-07"
+APP_VERSION = "0.8.226"
+BUILD_DATE = "2026-05-22"
 DB_SCHEMA_VERSION = "20260607090"
 
 MODULE_VERSIONS = {
@@ -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.23.0",  # planning_intent_context, finalize stage_specs, Prompt 089
+    "planning_exercise_suggest": "0.23.1",  # Phase B: Rematch-Schleife mit optimization_hints + roadmap_unfilled
     "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,14 @@ MODULE_VERSIONS = {
 }
 
 CHANGELOG = [
+    {
+        "version": "0.8.226",
+        "date": "2026-05-22",
+        "changes": [
+            "Progressionsgraph Phase B: Rematch-Schleife (max_rematch_rounds) mit optimization_hints und roadmap_unfilled.",
+            "Fix: Graph-Bewertung/Match 500 bei off-topic am Rand-Slot (collect_gap_fill_specs IndexError).",
+        ],
+    },
     {
         "version": "0.8.225",
         "date": "2026-06-07",