Version 04 als eigenes Repository

Erster Commit des Strangs "Optimierte Entscheidungsfindung mit Python"
(Version 04). Die Historie der 71 Commits bis zur Trennung bleibt im
uebergeordneten Repository OR_mit_Python liegen, das ab jetzt nur noch
Version_03 (eingefroren) verwaltet und Version_04/ ignoriert.

Bewusst kein "git subtree split": Der Pfad Version_04/ existiert erst seit
der Verzeichnistrennung, ein Split braechte daher nur 7 der 41 einschlaegigen
Commits - eine Teilhistorie, die vollstaendig aussieht und es nicht ist.

Stand: 5 Teile, 23 Kapitel, 5 Anhaenge, 292 Abschnitte, 703 Querverweise,
325 Indexmarken, 73 Beispielprogramme, 32 SVGs, 4 Plotly-Figuren,
25 Notebooks, PDF mit 715 Seiten.

Zusaetzlich in diesem Commit:

* pyproject.toml mit Abhaengigkeitsgruppen finance, large-scale, api,
  figures, dev, empfehlungen. Die abgedruckte requirements.txt bleibt
  unveraendert daneben bestehen. ortools steht in der Grundausstattung,
  highspy erst in [large-scale] - so kann der HiGHS-Symbolkonflikt bei der
  schlanken Installation gar nicht erst auftreten.

* Dabei zwei Funde: graphviz wird von erzeuge_architektur_diagramme.py
  importiert, fehlt aber in requirements.txt (jetzt in [figures]); pymoo
  steht in requirements.txt, wird aber von keinem Programm importiert,
  sondern nur im Kapitel Metaheuristiken empfohlen (jetzt in
  [empfehlungen]).

* NEUER_TITEL.md nach Kritik_und_Verbesserungsvorschlaege/ verschoben - es
  ist die Vorlage des Titelblatts, kein Bestandteil des Werks. Die beiden
  Fundstellen in PROGRESS.md und erzeuge_titelseite.py nachgezogen.

* PROGRESS.md nannte noch den Untertitel der ersten Fassung; auf den
  tatsaechlichen aus erzeuge_titelseite.py korrigiert.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

PLAN.md

@@ -0,0 +1,413 @@
+# PLAN — Optimierte Entscheidungsfindung mit Python, Version 04
+
+**Zweck dieser Datei:** Sie hält den *vollständigen* Umbauplan von Version 03 zu Version 04
+fest, mit allen Phasen, Konventionen und Prüfschritten — unabhängig davon, wie weit die
+Arbeit gediehen ist. Was davon bereits erledigt ist, steht in **[PROGRESS.md](PROGRESS.md)**.
+
+> **Arbeitsteilung der beiden Planungsdateien**
+>
+> | Datei | Inhalt | ändert sich |
+> | --- | --- | --- |
+> | `PLAN.md` (diese Datei) | das Ziel und der Weg dorthin | selten — nur bei Kurswechsel |
+> | `PROGRESS.md` | der erreichte Stand, mit Zahlen und Funden | nach jedem Arbeitsschritt |
+>
+> Beide liegen im **Repo-Wurzelverzeichnis**, nicht im Kapitelverzeichnis: Sie regieren
+> sechs Verzeichnisse, nicht nur die Kapitelquellen, und stehen dort neben `CLAUDE.md`, das
+> als einzige Datei von jeder neuen Sitzung automatisch gelesen wird und auf sie verweist.
+>
+> Die frühere `Operations_Research_mit_Python_Version_04/ARBEITSPLAN.md` ist am
+> 7. September 2026 in diesen beiden Dateien aufgegangen und wurde gelöscht (Commit-Historie
+> bewahrt sie auf). Eine Sache an zwei Stellen zu pflegen ist genau der Fehler, an dem in
+> diesem Projekt schon einmal Buch und Programme-Verzeichnis auseinandergelaufen sind.
+
+**Stand des Plans:** 7. September 2026 · Branch `main` · Version 03 bleibt unangetastet und
+weiter baubar; Version 04 ist ein paralleler Strang.
+
+---
+
+## 1. Warum es Version 04 gibt
+
+Grundlage ist die Rezension in `Kritik_und_Verbesserungsvorschlaege/Kritik.md`. Sie benennt
+drei Schwächen von Version 03:
+
+1. den steilen thematischen Bruch zwischen Logistik (Teil II/III) und Finanzmärkten (Teil IV),
+2. die hohe mathematische und architektonische Einstiegshürde,
+3. die Lücke bei Metaheuristiken und nicht-konvexer Optimierung.
+
+Version 03 ist ein fachlich starkes, aber akademisch getaktetes Kompendium (22 Dateien,
+~13 650 Zeilen, 42 Beispielprogramme). Version 04 baut es vom **Nachschlagewerk zum
+Kursbegleiter** um: Die Teilnehmer sollen schnelle, messbare Erfolge erleben und die
+Verfahren am nächsten Arbeitstag anwenden können.
+
+### Die drei Leitprinzipien
+
+1. **Time-to-First-Success minimieren** — ein lauffähiges Aha-Erlebnis *vor* der formalen
+   Theorie.
+2. **Kognitive Entlastung** — Formeln konsequent in Klartext, Alltagssprache und Geometrie
+   übersetzen.
+3. **Robuste Praxistauglichkeit** — Typsicherheit, echte Datenpipelines, ehrliches
+   Debugging statt idealisierter Beispiele.
+
+### Getroffene Grundsatzentscheidungen
+
+| Frage | Entscheidung |
+| --- | --- |
+| Bilder | eigenes `bilder_04/`, damit V03 eingefroren bleibt |
+| Fremdbibliotheken | polars, pyomo, linopy, pymoo, celery, cvxpylayers **installiert** — die Programme laufen wirklich. Ipopt/CyIpopt und Redis/Docker bleiben illustrativ mit dokumentiertem Fallback |
+| Notebooks | lokal in `Notebooks_04/`, Colab-Link aus **einer** Konstanten `COLAB_BASIS_URL` in `build_version_04.py` |
+| Plotly | zweigleisig: Matplotlib/Graphviz bleibt PDF-Quelle, Plotly zusätzlich in die Website eingebettet |
+| Nicht ausführbare Inhalte | ausdrücklich als solche kennzeichnen (z. B. MINLP/Ipopt) statt Ausgaben zu erfinden |
+
+---
+
+## 2. Zielstruktur
+
+22 → 29 Textdateien. Neue Kapitel **fett**. Kapitelnummern entstehen automatisch aus
+`{#kap:label}`, Querverweise laufen über `{ref:...}`, Abschnittsnummern vergibt der Build —
+Einfügen ist daher an keiner Stelle mit Handarbeit verbunden.
+
+| Teil | Kapitel |
+| --- | --- |
+| I Grundlagen | 1 Einführung · 2 Fundament · 3 Python-Ökosystem · **4 Vom Management-Wunsch zum Modell** |
+| II Kernverfahren | *Entscheidungs-Flussdiagramm* · 5 LP · 6 MILP · 7 CP-SAT · 8 Graphen/Touren · **9 Metaheuristiken** |
+| III Nichtlinearität/Unsicherheit | *Entscheidungs-Flussdiagramm* · 10 QP/NLP/MINLP · 11 Unsicherheit · 12 Dynamische Programmierung · **13 Mehrziel & Pareto** |
+| IV Brücke & Vertiefung | **14 Strukturbrücke Logistik ↔ Finance** · **15 Predict-then-Optimize** · **16 Supply-Chain & Energieeinsatz unter Unsicherheit** |
+| V Finanzmärkte (Vertiefung) | 17 Finanzdaten · 18 Markowitz · 19 CVaR · 20 Handelsmaschine |
+| VI Praxis | 21 Praxisfallen · **22 Testing, Benchmarking, Deployment** · Projektwerkstatt |
+| Anhänge | A Lösungen · B Modellierungsmuster · C Fehlerdiagnose & IIS · **D Spickzettel** · E Glossar/Literatur |
+
+Teil V (Finanzmärkte) wird im Vorwort und im Teil-Auftakt ausdrücklich als **spezialisierte
+Vertiefungsdomäne** gekennzeichnet; Kapitel 16 ist die gleichwertige Nicht-Finanz-Alternative
+mit denselben Werkzeugen.
+
+### Verzeichnisse
+
+```
+Operations_Research_mit_Python_Version_04/            Quelle: Kapiteldateien + Build-Skripte
+Operations_Research_mit_Python_Version_04_Programme/  generiert: Beispielprogramme
+Notebooks_04/                                         generiert: ein .ipynb je Kapitel
+bilder_04/                                            Quelle: Diagramme + Generatorskripte
+OR_HTML_04/                                           generiert: Mehrseiten-Website
+Operations_Research_mit_Python_Version_04.md / .pdf   generiert
+```
+
+---
+
+## 3. Phase 0 — Infrastruktur
+
+*Voraussetzung für alles Weitere; wird zuerst und vollständig abgeschlossen.*
+
+**`build_version_04.py`** — Fork von `build_version_03.py` mit vier Eingriffen; alles andere
+bleibt identisch:
+
+1. **Pfadkonstanten zentralisieren.** Ein Versionsblock am Dateikopf: `ZIEL_MD`,
+   `PDF_DATEINAME`, `PROGRAMME_VERZ`, `BUILD_BASISNAME`, `BILDER_NAME/VERZ`,
+   `HTML_NAME/VERZ`, `NOTEBOOK_NAME/VERZ`, `COLAB_BASIS_URL`.
+2. **Bildpfade.** V04-Markdown referenziert `bilder_04/…`. Fürs PDF löst Pandoc relativ zum
+   Repo-Wurzelverzeichnis auf; für die Website spiegelt `spiegle_bilder()` das Verzeichnis
+   nach `OR_HTML_04/`.
+3. **Automatische Abschnittsnummerierung.** `nummeriere_abschnitte()` vergibt `## 5.4 Titel`
+   (im Anhang `## C.4 Titel`) beim Bauen; `ABSCHNITT_RE` erwartet im Quelltext **keine**
+   Nummer mehr. Analog in `baue_seiten_registry()` / `resolve_numbering_seite()`. **Ohne
+   diesen Eingriff zöge jedes eingefügte Kapitel Handarbeit in allen Folgekapiteln nach
+   sich.**
+4. **Neue Bausteine.** `resolve_plotly()` + `kopiere_plotly_bibliothek()` (Plotly-Fragmente
+   in die Kapitelseiten einbetten, im PDF statischer Ersatz), `baue_notebooks()` +
+   `ergaenze_notebook_hinweis()` + `spiegle_notebooks()`, erweitertes `markiere_karten()`
+   für die neuen Kartentypen, `KEINE_KAPITELDATEIEN`.
+
+**`extract_programme_04.py`** — Fork von `extract_programme.py`, nur `ZIEL_DIR`/`HIER` und
+die README-Vorlage umgestellt. Extraktionsmuster (`#!/usr/bin/env python3`, Leerzeile,
+`# Name.py`) bleibt unverändert.
+
+**`OR_HTML_04/assets/site.css`** — neue Boxklassen für 5-Minuten-Box, Formel-Übersetzer,
+Excel-Brücke, Micro-Quiz und Denkfehler-Aufgabe.
+
+**Abschluss:** `--check`, `--pdf` und `--html` laufen mit inhaltlich unverändertem V03-Text
+sauber durch. Erst dann beginnt inhaltliche Arbeit.
+
+---
+
+## 4. Phase 1 — Didaktik-Layer über alle bestehenden Kapitel
+
+Pro Kapitel, in Lesereihenfolge, jeweils dieselben Bausteine (siehe Abschnitt 8):
+
+* **„In 5 Minuten gelöst“** als erster Abschnitt: 4–6 Zeilen Daten, ≤ 15 Zeilen Code,
+  betriebswirtschaftlich sofort lesbares Ergebnis — danach erst „Warum funktioniert das?“.
+* **Formel-Übersetzer-Tabellen** (zweispaltig Mathematik | Alltagssprache) an jeder
+  zentralen Formel; die bestehenden „Lesehilfe“-Blöcke gehen darin auf.
+* **Micro-Quiz** (genau 3 Multiple-Choice-Fragen) und **„Finde den Denkfehler“**
+  (lauffähiger Code mit betriebswirtschaftlich unsinnigem Ergebnis: `>=` statt `<=`,
+  vergessene Ganzzahligkeit, Big-M zu klein, Zirkelbezug) je Kapitelende; Lösungen nach
+  Anhang A.
+* **Notebook-Badge** im „Kapitel auf einen Blick“-Block.
+
+### Kapitelspezifische Ergänzungen
+
+| Kapitel | Ergänzung |
+| --- | --- |
+| 1 Einführung | **Excel-zu-Python-Brücke:** Excel-Solver-Modell Zelle für Zelle übersetzt, `pandas.read_excel()` → Modell → formatierter Export |
+| 2 Fundament | **Numerik-Deep-Dive:** Konditionszahl $\kappa(A)$ als Experiment (Kosten $10^7$ gegen Toleranzen $10^{-6}$ → falsches `INFEASIBLE`), Ruiz-Equilibrierung, Geometrie vor Algebra |
+| 3 Ökosystem | Pyomo/Linopy im Vergleich zu CVXPY/OR-Tools; vektorisierte Modellgenerierung (NumPy, Polars) gegen `for`-Schleifen gebenchmarkt; wiederverwendbare Excel-/CSV-Pipeline |
+| 4 LP | Primal-/Dual-/Integralitätstoleranzen, Degeneriertheit als Vorschau auf Anhang C |
+| 5 MILP | MIP-Gap, Time-Limit, Warm-Starts (`SetHint`/`highspy`), warum `0.99999998` nicht `int()` verträgt |
+| 6 CP-SAT | vollständige Statusauswertung, interaktives Gantt (Plotly) |
+| Teil-Auftakte II und III | Entscheidungs-Flussdiagramm „Welcher Solver passt zu meinem Problem?“ (Graphviz) |
+
+---
+
+## 5. Phase 2 — Code-Architektur auf Enterprise-Niveau
+
+Neues gemeinsames Modul **`or_kern.py`** im Programme-Verzeichnis (folgt dem
+Extraktionsmuster, wird also mitgeneriert) — der greifbare Beleg für Clean Architecture:
+
+```
+Rohdaten (Excel/CSV)
+    → Domänenmodell (Pydantic, geprüft)
+        → Modellbauer (solverabhängig)
+            → Lösung (DTO, solverunabhängig)
+                → Abnahmeprüfung
+```
+
+* **Pydantic-v2-Basismodelle** für Ressourcen, Bedarfe, Kosten- und Renditematrizen mit
+  Validierung beim Einlesen (strikt positive Kapazitäten, Wahrscheinlichkeiten summieren
+  auf 1, Spaltenzuordnung über Namen statt Positionen).
+* **Einheitliches `Loesung`-DTO** plus `SolverStatus`-Enum (`OPTIMAL`, `ZULAESSIG`,
+  `UNZULAESSIG`, `UNBESCHRAENKT`, `ZEITLIMIT`, `FEHLERHAFT`, `UNBEKANNT`) mit Übersetzern
+  für pywraplp, CP-SAT, highspy, SciPy und CVXPY. **Lazy imports**, weil `ortools` und
+  `highspy` sich nicht gemeinsam importieren lassen.
+* **Excel-/CSV-Ein- und -Ausgabe** (`lade_produktionsproblem()`, `schreibe_ergebnis()`),
+  pandas als optionale Abhängigkeit.
+
+Alle bestehenden Programme werden darauf umgestellt: durchgängige Type Hints
+(mypy-kompatibel), Domäne strikt vom Solver getrennt, keine impliziten
+Optimalitätsannahmen mehr. Der **Solver-Austausch HiGHS ↔ CP-SAT** wird an einem Beispiel
+real vorgeführt.
+
+> **Maßstab bei jeder Umstellung:** Wird das Programm dadurch kürzer *und* klarer? Wenn
+> nicht, bleibt es. Ein Lehrbeispiel darf nicht an Architektur ersticken — das gilt
+> besonders für die frühen Kapitel, wo die Leser das Modul noch nicht kennen.
+
+---
+
+## 6. Phase 3 — Neue Kapitel
+
+* **Kap. 4 Vom Management-Wunsch zum Modell** — Anforderungsanalyse für OR-Projekte,
+  realistischer Dialog („Kosten senken, aber die Mitarbeiter sollen nicht meckern“),
+  systematische Zerlegung in Entscheidungsvariablen / harte vs. weiche Restriktionen
+  (Strafkosten) / fehlanreizfreie Zielfunktion.
+* **Kap. 9 Metaheuristiken** — wenn HiGHS/CP-SAT skalierungsbedingt aussteigen: lokale
+  Suche mit Kostenänderung in $O(1)$, Simulated Annealing samt Kalibrierung der Temperatur,
+  der gemessene Umschlagpunkt gegen den exakten Solver, Large Neighborhood Search
+  (zerstören / exakt reparieren).
+  **Dekomposition wurde aus diesem Kapitel herausgenommen** und ist ein eigener offener
+  Punkt: Spaltengenerierung gibt eine *andere* Antwort auf dieselbe Frage — sie approximiert
+  nicht die Lösung, sondern formuliert das Modell um. Genetische Algorithmen (`pymoo`) und
+  Tabu-Suche sind im Kapitel benannt und eingeordnet, aber nicht ausgeführt: Für Reihenfolgen
+  ist die „Kreuzung“ zweier Lösungen gerade der schwierige Teil, und ein halbherziges
+  Beispiel dazu wäre irreführend.
+* **Kap. 13 Mehrziel & Pareto** — warum lineare Skalarisierung bei nicht-konvexen Fronten
+  versagt; $\epsilon$-Constraint und lexikografische Optimierung an Kosten vs. CO₂ in der
+  Tourenplanung; exakte Pareto-Front, statisch fürs PDF und interaktiv (Plotly) auf der
+  Website.
+* **Kap. 14 Strukturbrücke** — dieselbe Mathematik, zwei Welten: Ressourcenallokation ↔
+  Kapitalallokation, Lieferausfall-Robustheit ↔ Worst-Case-Risikomaße; Gegenüberstellung
+  als Tabelle plus ein Modell, das beide Datensätze frisst.
+* **Kap. 15 Predict-then-Optimize** — Nachfrageprognose → Lagerbestand: ein Modell mit
+  kleinerem MSE erzeugt teurere Entscheidungen; Entscheidungskosten statt Prognosefehler
+  messen; Ausblick `cvxpylayers`/PyTorch.
+* **Kap. 16 Supply-Chain & Energieeinsatz unter Unsicherheit** — die Nicht-Finanz-Alternative
+  zu Teil V mit denselben Werkzeugen (Szenarien, CVaR, DP): Netzwerkdesign mit
+  Standortentscheidungen, Kraftwerkseinsatzplanung.
+* **Kap. 22 Testing, Benchmarking, Deployment** — pytest-Framework für Optimierungsmodelle
+  (Regression gegen Benchmark-Instanzen, Restriktionsverletzungs-Checks,
+  Skalierungsinvarianz), reproduzierbare Benchmark-Pipeline SciPy/HiGHS/OR-Tools/CVXPY über
+  $N \in \{10^2, 10^3, 10^4\}$ (Zeit und Speicher), FastAPI-Microservice mit asynchroner
+  Job-Queue und schlankem `Dockerfile`.
+
+### Empfohlene Reihenfolge
+
+Nicht strikt nach Kapitelnummer, sondern nach Nutzen — falls vor einem Kurstermin ein
+brauchbarer Zwischenstand gebraucht wird:
+
+1. **Kap. 9 Metaheuristiken** — schließt die von der Rezension am schärfsten benannte Lücke.
+2. **Kap. 22 Testing/Deployment** — zweite große Lücke; der Unterbau (`or_kern.py`) steht
+   bereits und ist genau das, was sich testen lässt.
+3. **Kap. 4 Vom Management-Wunsch zum Modell** — kurz, didaktisch tragend, ohne neue
+   Bibliotheken.
+4. **Kap. 13 Mehrziel**, **Kap. 14 Strukturbrücke**, **Kap. 15 Predict-then-Optimize**.
+5. **Kap. 16 Supply-Chain & Energie** — die aufwendigste Einheit und am ehesten verzichtbar,
+   falls der Umfang begrenzt werden muss.
+
+---
+
+## 7. Phase 4 — Anhänge · Phase 5 — Medien, Rahmen, Gesamtbau
+
+### Phase 4 — Anhänge
+
+* **Anhang C → vollwertiges Troubleshooting-Handbuch:** IIS/Conflict Refiner in Python
+  (deletion filter, der aus tausenden Restriktionen die minimale widersprüchliche Teilmenge
+  isoliert), duale Entartung und instabile Schattenpreise, Toleranzkunde
+  (`feasibility_tolerance` HiGHS vs. OR-Tools), Skalierung/Ruiz.
+* **Anhang D (neu) Spickzettel** — je eine Seite SciPy, HiGHS, CP-SAT, CVXPY, Pyomo/Linopy:
+  Variablentypen, Big-M-Entweder-Oder, weiche Restriktionen mit Slack, Dualwerte und Status
+  abfragen.
+* **Anhang B** — Rezeptkarten für Alltagsfragen (Mindestabnahmemengen, Rüstzeiten,
+  Budgetlimit), abgestimmt auf Anhang D.
+* **Anhang A** — Lösungen für alle neuen Aufgaben, Micro-Quizzes und Denkfehler-Übungen;
+  läuft parallel zu jeder Phase mit.
+
+### Phase 5 — Medien, Rahmen, Gesamtbau
+
+* **Diagramme** in `bilder_04/`: zwei Entscheidungs-Flussdiagramme, Branch-and-Bound-Baum,
+  Pareto-Front, Konditionszahl-Experiment, Metaheuristik-Landschaft,
+  Clean-Architecture-Schichten, FastAPI-Deployment — Graphviz bzw. Matplotlib, jeweils
+  SVG + PNG. **Diesmal mit mitgelieferten Generatorskripten** (`bilder_04/erzeuge_*.py`);
+  in V03 fehlen die Diagrammquellen.
+* **Plotly-Figuren** nach `bilder_04/plotly/*.html`, vom Build in die Kapitelseiten
+  eingebettet; im PDF steht die statische Variante.
+* **Notebooks** je Kapitel nach `Notebooks_04/`, aus den Kapitel-Codeblöcken generiert, mit
+  `pip install`-Startzelle.
+* **Rahmen aktualisieren:** Vorwort (Lernpfade um die neuen Kapitel und den
+  Finanz-/Industrie-Gabelpunkt erweitert), Notation, Projektwerkstatt (Projekte zu
+  Metaheuristik, Mehrziel und Deployment), Programme-README-Vorlage, `requirements.txt`,
+  `CLAUDE.md` um den V04-Strang ergänzt.
+* **Abschluss:** vollständiger Bau von Markdown, PDF und Website.
+
+---
+
+## 8. Der Kapitel-Baukasten
+
+Jedes Kapitel der Version 04 erhält dieselben Bausteine in derselben Reihenfolge:
+
+```
+# Kapitel: <Titel> {#kap:<label>}
+
+> 📌 Kapitel auf einen Blick        (Worum / Voraussetzungen / Danach / Zeitbedarf / Programme)
+                                     Der Notebook-Hinweis wird vom Build ergänzt.
+
+## In 5 Minuten gelöst {#sec:<label>-schnellstart}
+   > 🚀 …    4–6 Zeilen Daten, ≤15 Zeilen Code, sofort lesbares Ergebnis
+   danach im Fließtext: „Und jetzt der Punkt“ + „Warum funktioniert das?“
+
+## Lernziele
+## <Fachabschnitte>                  darin: > 🔤 Formel-Übersetzer an jeder zentralen Formel
+## Übungsaufgaben
+## Finde den Denkfehler {#sec:<label>-denkfehler}
+   > 🐛 …    Code läuft fehlerfrei, Ergebnis ist betriebswirtschaftlich Unsinn
+## Micro-Quiz {#sec:<label>-quiz}
+   > ❓ …    genau 3 Multiple-Choice-Fragen
+## Selbsttest                        (offene Fragen, aus V03 übernommen)
+## Zusammenfassung
+```
+
+**Kartentypen** (Erkennung am führenden Emoji, `KARTEN_TYPEN` in `build_version_04.py`):
+
+| Emoji | CSS-Klasse | Verwendung |
+| --- | --- | --- |
+| 📌 | `card-blick` | Kapitel auf einen Blick |
+| 🚀 | `card-schnellstart` | In 5 Minuten gelöst |
+| 🔤 | `card-formel` | Formel-Übersetzer (zweispaltig: Mathematik \| Alltagssprache) |
+| 📊 | `card-excel` | Excel-Brücke |
+| ❓ | `card-quiz` | Micro-Quiz |
+| 🐛 | `card-denkfehler` | Finde den Denkfehler |
+| 📎 | *(Blockquote)* | Verweis auf ein Modul oder einen späteren Abschnitt |
+
+Bestehende Blockquotes (🎯 Merksatz, ⚠️ Typische Fehler, ✏️ Handrechnung, 💻 Code-Durchgang,
+📖 Definition, 📐 Formel-Lesehilfe, 💡 Hinweis) bleiben unverändert und werden weiter
+verwendet.
+
+---
+
+## 9. Regeln, die eingehalten werden müssen
+
+1. **Abschnittsnummern nicht in den Quelltext schreiben.** `## Titel {#sec:label}` genügt;
+   die Nummer vergibt der Build. Verweise im Fließtext immer als `{ref:sec:label}`.
+2. **Keine Abschnittsnummern in Code-Kommentaren.** Dort den Abschnitts*titel* nennen —
+   Nummern verschieben sich beim Einfügen neuer Kapitel.
+3. **Bildpfade heißen `bilder_04/…`** — fürs PDF löst Pandoc relativ zur Repo-Wurzel auf,
+   für die Website spiegelt der Build das Verzeichnis.
+4. **Jede abgedruckte Ausgabe stammt aus einem echten Lauf.** Programm ausführen, Ausgabe
+   kopieren, nicht plausibel erfinden. Bei Zufallszahlen: festen Seed setzen und
+   Determinismus durch mehrfachen Lauf prüfen.
+5. **Jede Solver-Auswertung behandelt alle Statusfälle explizit** — `OPTIMAL`, `FEASIBLE`,
+   `INFEASIBLE`, `UNBOUNDED`, `TIME_LIMIT`.
+6. **Änderungen an Programmen gehören in den Kapitel-Codeblock**, danach
+   `extract_programme_04.py` laufen lassen. Das Programme-Verzeichnis ist ein Artefakt,
+   keine zweite Quelle.
+7. **Neue `{idx:…}`-Begriffe vorher prüfen:**
+   `grep -ohE '\{idx:[^}]+\}' Operations_Research_mit_Python_Version_04/*.md | sort -u`
+8. **Neues Programm ⇒ drei Stellen pflegen:** Kapitelkopf („Programme:“), Vorwort
+   („Verzeichnis der Beispielprogramme“), bei neuer Abhängigkeit `requirements.txt`.
+9. **Vor jedem neuen Programm prüfen, ob der Stoff schon abgedeckt ist.** Erst die
+   vorhandenen Programme des Kapitels lesen, dann schreiben — ein Denkfehler kann auch auf
+   einem bestehenden Programm aufbauen.
+10. **Nach jedem Ersetzen eines Codeblocks die Codezäune zählen.** Ein fehlender
+    schließender ` ``` ` fällt weder Pandoc noch dem Auge auf, lässt aber
+    `reflow_markdown()` den gesamten Rest der Datei zu Fließtext falten — im PDF steht dann
+    Programmcode als Absatz. `--check` prüft das seit Phase 2 automatisch
+    (`pruefe_dateien()`).
+11. **Am Ende jeder Phase die GESAMTE Programmsuite laufen lassen**, nicht nur die
+    angefassten Programme. Der Durchlauf dauert wenige Minuten und ist die einzige Prüfung,
+    die Altlasten findet.
+12. **Keine Kapitelnummern in Programm-Docstrings.** Dort den Kapitel*namen* nennen —
+    `Kapitel Metaheuristiken:` statt `Kapitel 9:`, so wie es die Code-Kommentare ohnehin
+    halten („siehe Kapitel Oekosystem“). Nach zwei eingefügten Kapiteln waren 66 von 67
+    Programmen falsch nummeriert; die Nummer im Buch stimmt automatisch, die im Docstring
+    nicht. Gleiches gilt für Abschnittsnummern (Regel 2) und Dateinamen.
+13. **`PROGRESS.md` gehört in denselben Commit wie die Arbeit, die sie beschreibt.**
+    Nicht „danach mal nachziehen“ — dann steht dort früher oder später etwas, das nicht mehr
+    stimmt. Eine Fortschrittsdatei, die hinterherhinkt, ist schlimmer als gar keine, weil man
+    ihr glaubt: Man verlässt sich auf einen Stand, den es nicht gibt. Genau an dieser
+    Trennung sind in diesem Projekt schon einmal Buch und Programme-Verzeichnis
+    auseinandergelaufen. Mitzupflegen sind der Phasenstand, die Referenzwerte und der
+    Abschnitt *Was als Nächstes ansteht*.
+
+---
+
+## 10. Verifikation
+
+```bash
+cd ~/Python_Programs/OR_mit_Python/Version_04
+
+# 1. Struktur und Querverweise (meldet unbekannte {ref:...}-Labels und fehlende Codezäune)
+python3 Operations_Research_mit_Python_Version_04/build_version_04.py --check
+
+# 2. Programme extrahieren und jedes einzeln ausführen
+python3 Operations_Research_mit_Python_Version_04/extract_programme_04.py
+MPLBACKEND=Agg bash -c 'for p in Operations_Research_mit_Python_Version_04_Programme/*.py; do
+  echo "== $p"; timeout 600 python3 "$p" >/dev/null || echo "FEHLER: $p"; done'
+
+# 3. Testsuite aus dem Kapitel "Testen, Messen, Ausliefern"
+#    (liegt flach im Programme-Verzeichnis, nicht in einem tests/-Unterordner)
+pytest Operations_Research_mit_Python_Version_04_Programme/test_or_kern.py -q
+
+# 4. PDF und Website
+python3 Operations_Research_mit_Python_Version_04/build_version_04.py --pdf --html
+
+# 5. Gegenprobe: Version 03 muss unverändert bauen
+python3 Operations_Research_mit_Python_Version_03/build_version_03.py --check
+```
+
+Zusätzlich sichtprüfen: `OR_HTML_04/index.html` (Landing-Page, Sidebar, Volltextsuche,
+Stichwortverzeichnis), eine Kapitelseite mit den neuen Karten und einer eingebetteten
+Plotly-Figur, seitenübergreifende Querverweise (`andere-seite.html#anker`).
+
+**Prüfmaßstab pro Kapitel:** jeder abgedruckte Codeblock wurde ausgeführt, die im Buch
+gezeigte Ausgabe stammt aus diesem Lauf, und jede Solver-Auswertung behandelt alle
+Statusfälle explizit.
+
+---
+
+## 11. Umfang und Reihenfolge
+
+Der Umfang entspricht etwa einer Verdopplung des Buches: 7 neue Kapitel, ein neuer Anhang,
+Didaktik-Layer und Code-Refactoring über 22 Bestandsdateien. Die Arbeit läuft in der
+Phasenreihenfolge 0 → 5; **nach jeder Phase ist der Stand baubar und lauffähig**, sodass
+Zwischenstände begutachtet werden können.
+
+Phase 0 wird zuerst und vollständig abgeschlossen, weil ohne automatische
+Abschnittsnummerierung jedes eingefügte Kapitel Handarbeit in allen Folgekapiteln nach sich
+zöge.
+
+**Sprache:** Kommentare, Ausgaben und Fließtext sind durchgängig Deutsch.