shinkan-jinkendo/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md

Progressionsgraph — KI-Planung (Ist-Stand)

Stand: 2026-05-22 (Dokumentation) · App-Version: 0.8.233 · DB: Migration 088
Maßgeblich für Code: backend/version.py (APP_VERSION, DB_SCHEMA_VERSION, MODULE_VERSIONS.planning_exercise_suggest)

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) ·
PLANNING_CATALOG_PROMPT_SNIPPETS.md (H1 — modulare Katalog-Prompts) ·
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)

Primär: ProgressionGraphEditor.jsx (integrierter Slot-Editor, Phase B).
Legacy/Parallel: ExerciseProgressionPathBuilder.jsx (Scroll-Monolith — gleiche API, Katalog-Kontext-Dropdowns dort noch nachziehen).

① Ziel eingeben (+ Planungskontext: Primärfokus, Stil, Trainingsstil, Zielgruppe)
② Optional: Start/Ziel-Felder manuell oder „Start/Ziel analysieren“
③ „Roadmap generieren“ (roadmap_only, LLM-Roadmap)
④ Roadmap bearbeiten (Major Steps + Stufen-Details)
⑤ „Übungen matchen“ (roadmap_first + roadmap_override + Auto-QS/Rematch)
⑥ Lücken: KI-Angebote → „KI anlegen“ (Gap-Prep-Modal) → in Slot
⑦ „Graph speichern“ (planning_roadmap + optional Kanten-Sequenz)

Bekannte UX-Schuld: PathBuilder = lange Scroll-Seite; GraphEditor = kompakter, aber noch kein Wizard. Stepper geplant (separater UI-Chat). Briefing §12.

---

3. Architektur (Module)

flowchart TB
    subgraph ui [Frontend]
        PGE[ProgressionGraphEditor]
        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]
        PCC[planning_catalog_context.py]
        REM[planning_path_rematch.py]
        REF[planning_path_refine_stage.py]
        QAP[planning_path_qa_pipeline.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
    PGE --> PPS
    PGE --> SEQ
    PGE --> PUT
    GFM --> EAI
    PPS --> PR
    PPS --> PB
    PB --> PCC
    PB --> REM
    PB --> REF
    PB --> QAP
    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, Auto-QS, Rematch, Gap-Offers
planning_catalog_context.py	Expliziter Katalog-Kontext (Fokus, Stil, Trainingsstil, Zielgruppe) → PlanningTargetProfile
planning_path_rematch.py	Auto-Rematch betroffener Slots (max_rematch_rounds)
planning_path_refine_stage.py	Stufen-Spec-Verfeinerung bei stage_mismatch (Phase C)
planning_path_qa_pipeline.py	Mehrstufige QS → optimization_hints
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)
planning_exercise_profiles.py	Katalog-Scoring (Fokus/Stil/TT/ZG/Skills) — gemeinsam mit Einheitsplanung
planning_exercise_target_pipeline.py	Query-Intent-Pipeline — Progressionsgraph nutzt query_only-Modus + Katalog-Overlay

---

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)
planning_catalog_context	object?	Primärfokus, Stilrichtung, Trainingsstil, Zielgruppe (IDs + is_primary)
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
auto_rematch_after_qa	bool	Auto-Rematch nach QS (Default true)
auto_refine_stage_spec	bool	Stufen-Spec bei stage_mismatch schärfen (Default true)
max_rematch_rounds	int	Rematch-Runden 0–4 (Default 3)
include_path_qa, include_llm_path_qa, include_ai_gap_fill	bool	QS, LLM-Ganzpfad, 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. qa_tiers, optimization_hints, rematch_log, refine_log
target_profile_summary	Erwartungsprofil inkl. Katalog-Dimensionen (nach Match)
match_summary	library_matches, gap_fill_offer_count, roadmap_unfilled_count

---

4.4 Planungskontext — Katalog vs. Technik-Vokabular

Shinkan unterscheidet drei Schichten (kein monolithisches „Vokabular“):

Schicht	Was	Wo	Beispiel
Katalog-Dimensionen	Was für Training?	DB: focus_areas, style_directions, training_types, target_groups, skills	Gewaltschutz, Breitensport, Shotokan
Disambiguierung (Technik)	Verwechslungs-Nachbarn	Code: planning_exercise_semantics.py (_GERI_TECHNIQUES, …)	Mae Geri ≠ Mawashi Geri
Didaktik / Kausalität	Reihenfolge, Lernphasen	Roadmap + LLM Pfad-QS	Grundlagen vor Geschwindigkeit

Seit 0.8.233: planning_catalog_context im Request und im Graph-Artefakt (planning_catalog_context JSON). Fließt in PlanningTargetProfile → Hybrid-Retrieval (score_exercise_against_target: „Fokusbereich passend“, …). Zusätzlich additive Text-Signale aus Anfrage + Start/Ziel + Notizen (planning_exercise_text_signals).

Geplant (H1): dieselben Dimensionen als kaskadierte Prompt-Snippets in Roadmap-, Stufen-Spec- und Pfad-QS-Prompts — Priorität Primärfokus → Trainingsstil → Zielgruppe → Stilrichtung — siehe PLANNING_CATALOG_PROMPT_SNIPPETS.md.

Technik-Gates (technique_scope, Geschwister-Ausschluss) nur bei topic_type == "technique" — Fokus-Pfade (Gewaltschutz, Fitness, …) werden nicht wie Mae-Geri-Pfade behandelt.

Fallback: fehlt planning_catalog_context im Request, wird aus gespeichertem planning_roadmap am Graph geladen.

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. Roadmap-Match — Stufen-Qualität (0.8.218–0.8.233)

Pro Major Step gilt:

1. Stufen-Brief — build_stage_match_brief() aus Lernziel, anti_patterns, Erfolgskriterien, Pfad-Kontext.
2. Stufen-Gate — exercise_passes_stage_fit() / exercise_passes_stage_learning_goal_gate() auf vollem Übungstext.
3. Kein blindes Rank-Fallback — ohne Gate-Passung → roadmap_unfilled, nicht themenfremde Übung.
4. Post-Match-Gate — _roadmap_step_passes_post_match_gate() = gleiche QS wie detect_off_topic_steps (kein Rematch-Treffer, der sofort wieder stage_mismatch wäre).
5. Retrieval — Hybrid-Score: Volltext + Semantik + Profil/Katalog + Skill-Erwartungen + optional Graph-Bias.
6. Auto-Optimierung (ein Match-Lauf):
   • Phase B: Rematch-Schleife (planning_path_rematch.py) für rematch_slot / roadmap_unfilled
   • Phase C: planning_path_refine_stage.py — anti_patterns / Erfolgskriterien aus QS
   • Purge persistent stage_mismatch → Slot leeren + KI-Gap
   • LLM Pfad-QS nach Rematch auf finalem Pfad
   • Gap-Offers für alle leeren Slots vor path_qa-Summary

Tests: test_planning_roadmap_stage_match.py, test_planning_path_rematch.py, test_planning_path_refine_stage.py, test_planning_catalog_context.py

Referenz-Validierung (Mae Geri, 2026-05)

Phase	Pfad-QS	Ergebnis
Vor Roadmap/KI-Anpassung	~65 %	Strukturelle Lücken (Grundlagen, Reihenfolge, Zielgenauigkeit)
Nach Trainer-Roadmap + KI-Angebote in leeren Slots	~88 % OK	Vollständige Curriculum-Abdeckung; positive LLM-Empfehlungen

Lesson: Workbench + Katalog-Kontext + Roadmap sind der Hebel; Technik-Hardcoding allein reicht nicht für Didaktik.

---

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

---

7. 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:

{
  "schema_version": 1,
  "goal_query": "…",
  "start_situation": "…",
  "target_state": "…",
  "roadmap_notes": "…",
  "max_steps": 5,
  "progression_roadmap": { },
  "path_skill_expectations": { },
  "planning_catalog_context": {
    "focus_areas": [{ "id": 1, "is_primary": true }],
    "style_directions": [],
    "training_types": [{ "id": 2, "is_primary": true }],
    "target_groups": []
  },
  "slot_contents": [ ],
  "last_findings": { }
}

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.

---

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

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

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

---

10. 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

---

11. 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
F10	Stufen-Lernziel-Gate + kein goal_query-Fallback	✅	0.8.218
F11	Auto-Rematch + Stufen-Spec-Refine + mehrstufige QS	✅	0.8.225–0.8.230
F12	Post-Match-Gate, LLM-QA nach Rematch, Gap-Timing, roadmap_unfilled-Sync	✅	0.8.231–0.8.232
F13	Katalog-Kontext (planning_catalog_context) im Match + Graph-Artefakt	✅	0.8.233
F14	ProgressionGraphEditor Slot-UI + Planungskontext-Dropdowns	✅	0.8.233
H1	Katalog-Prompt-Snippets — modulare LLM-Anweisungen pro Dimension	🔲	Spec PLANNING_CATALOG_PROMPT_SNIPPETS.md
G	Trainingsplanung: eigene Pipeline + Wiederverwendung Bausteine (§16)	🔲	—
UX	Wizard/Stepper; PathBuilder-Parität Katalog	🔲	—
H	Technik-Disambiguierung konfigurierbar (DB statt Code-Tuples)	🔲	Backlog
D′	Auto Gap-Fill (KI generiert bei persistent roadmap_unfilled)	🔲	Backlog

---

12. Offenes Backlog (priorisiert)

1. H1 Katalog-Prompt-Snippets — modulare LLM-Anweisungen (Priorität: Primärfokus → Trainingsstil → Zielgruppe → Stilrichtung) — PLANNING_CATALOG_PROMPT_SNIPPETS.md
2. Dev-Regression: Gewaltschutz + Breitensport + Kinder (ohne Mae Geri) — Katalog-Match verifizieren
3. PathBuilder-Parität — gleiche planning_catalog_context-Dropdowns in ExerciseProgressionPathBuilder
4. QS-UI — positive LLM-Hinweise als „Highlights“, nicht als „Optimierungspotenziale“
5. UI-Wizard — 4 Schritte (Ziel → Roadmap → Match → Lücken); Backend unverändert
6. Graph-Erweiterungsmodus — Start ab gewähltem Knoten / letzter Sequenz
7. Phase D′ — automatisches KI-Gap-Fill bei persistent leeren Slots
8. Trainingsplanung Phase G — siehe §16
9. Technik-Katalog externalisieren — konfigurierbare concept_groups (Backlog)
10. Graph-Metadaten: Primärfokus/Stil als Spalten (Reporting)
11. Mitai Workflow-Engine (langfristig)

Briefing-Vorlage UI-Chat

Kern: Wizard ① Ziel & Planungskontext → ② Roadmap → ③ Match → ④ Lücken & Speichern; Backend-Pipeline unverändert lassen.

---

16. Wiederverwendung in der Trainingsplanung (Phase G)

Die komplexere Trainingsplanung (Einheit, Rahmen-Slot, Abschnitt, parallele Streams) soll keine zweite Retrieval-Welt bauen, sondern bestehende Module mit anderem Kontext-Pack nutzen.

16.1 Was Progressionsgraph liefert (Workbench-Muster)

Baustein	Progressionsgraph	Trainingsplanung (Ziel)
PlanningTargetProfile	Query + Katalog + Skills	Einheit + Abschnitt + Slot + Katalog + Historie
planning_catalog_context	Am Graph gespeichert	Pro Einheit / Slot / Trainer-Voreinstellung
planning_skill_expectations	progression_stage / progression_path	training_section, framework_slot
planning_exercise_retrieval	Roadmap-Stufen-Match	Abschnitts-Suche (suggest_planning_exercises) — produktiv
planning_path_qa_pipeline	Curriculum-QS	Abschnitts-QS (Kohärenz, Streams)
planning_intent_context	Pfad-Ausschlüsse → Stufen	Abschnitts-Guidance → Brief
planning_exercise_form_context	Pfad-Lücken	Abschnitts-/Slot-Lücken
Roadmap-Pipeline	Curriculum Major Steps	Nicht 1:1 — Phasen/Streams + Vorlagen
Technik-Disambiguierung	bei topic_type=technique	nur bei explizitem Technik-Abschnitt

16.2 Was Phase G neu braucht

• Gruppen-/Historie-Kontext-Pack (AI_PLANNING_KI_MULTISTAGE_FORECAST S0–S4)
• Abschnitts-Didaktik — Dauer, Parallel-Streams, Coaching (training_unit_phases)
• Rahmen-Blueprint — bereits training_framework_programs / Slot-Blueprints
• Eigene Orchestrierung pro Einheit — kein Curriculum über N Wochen

16.3 Integrations-Reihenfolge (Phase G)

1. G0 — Katalog in Einheits-Editor → bestehende Suggest-Pipeline
2. G1 — Scope training_section + Skill-Erwartungen aktiv
3. G2 — Abschnitts-QS (Hint-Struktur wie Graph)
4. G3 — Framework-Slot + Gap-Fill
5. G4 — Gruppenkontext-Pack

Nicht: Roadmap-first-Loop 1:1 auf Trainingseinheit mappen.

Domänenbezug: DOMAIN_MODEL.md §1–2 (Katalog-Dimensionen).

---

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
test_planning_exercise_progression.py	Graph-Auflösung, Nachfolger
test_planning_path_rematch.py	Auto-Rematch, unfilled-Platzhalter
test_planning_path_refine_stage.py	Stufen-Spec-Refine
test_planning_stage_anti_patterns.py	Anti-Pattern-Sanitizer, Stufen-Gate
test_planning_catalog_context.py	Katalog-Kontext → Target-Profil

---

14. 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.

---

15. Changelog (Dokument)

Datum	Änderung
2026-05-22	Erstfassung Ist-Stand 0.8.217 — zentrale Referenz nach F5–F9
2026-05-22	F11–F14: Auto-Optimierung, Katalog-Kontext, GraphEditor, Mae-Geri-Validierung, Phase-G-Wiederverwendung §16