claude-regelwerk/.vault-tools/plan-kopie/LIESMICH.md

type, status, title, summary, tags, created, updated

type	status	title	summary	tags	created	updated
resource	active	Planwerkzeuge: Plan auf eine Kopie anwenden und jede Welle dagegen vergleichen	Skripte für die Standardschleife bei Plänen mit ausgeschriebenem Code — schlanke Kopie bauen, Plan auf die Kopie anwenden, je Welle Menge und Bytes vergleichen, Aus-wird-Blöcke prüfen, Codeblöcke auf unsichtbare Zeichen absuchen, Escape-Folgen per Codepunkt setzen. Entstanden 2026-09-17 in der Trading Plattform (Teil 3b).	vault-tools codeworkflow	2026-09-17	2026-09-20

Planwerkzeuge für die Kopie mit angewendetem Plan

Die Regel dazu steht in AI/Regelwerk/codeworkflow („Die Kopie mit dem angewendeten Plan bleibt stehen …"). Hier steht nur, wie man die Skripte benutzt. Alle laufen mit dem Windows-Python: PYTHONIOENCODING=utf-8 python -X utf8 <skript> ….

Ablauf

1. Kopie bauen — erst, wenn der Planer fertig gemeldet hat. Den Projektbaum ohne .git, ohne Geheimnisdateien und ohne node_modules in einen Wegwerfordner kopieren. Ausschlüsse als Pfade vom Wurzelordner angeben, nicht als Ordnernamen: Ein Ausschluss von „jedem Ordner namens data" hat am 2026-09-17 auch das Paket trading/data getroffen, und die Suite der Kopie brach mit Sammelfehlern ab. Nach dem Kopieren die Paketliste gegen das Original halten. Beides erledigt kopie_bauen.py <projekt> <ziel> --ohne <relpfad> …: Es nimmt Ausschlüsse nur als Pfade vom Wurzelordner, meldet einen Ausschluss ohne Gegenstück („ein Name statt eines Pfads?"), überspringt Verknüpfungen und Junctions, lässt __pycache__ weg, weigert sich bei einem vorhandenen Ziel und vergleicht am Ende die Python-Pakete beider Bäume. Für die Trading Plattform: --ohne .git dashboard/node_modules dashboard/dist data artifacts config/secrets.toml docs/plans. Braucht die Kopie node_modules, eine Junction setzen (mklink /J) — und sie vor dem Löschen der Kopie mit cmd //c rmdir <pfad> wieder lösen, sonst trifft rm -rf das echte node_modules. Nie tsc -b durch die Junction fahren (schreibt nach node_modules/.tmp); npx tsc -p tsconfig.app.json --noEmit nehmen.

2. Plan anwenden: plan_materialisiere.py <planordner> <kopie> task-01.md task-02.md … in Wellenreihenfolge. Erkennt die Marken Aus: / wird:, „Die ganze Datei ist neu", „vollständig ersetzt" und „Häng diesen Block ans Ende"; Dateien, die ## Zieldateien als „(gelöscht)" führt, löscht es in der Kopie. Prosa-Tasks („wird: ein neuer Abschnitt, er muss sagen …") lassen sich nicht anwenden.

3. Auf der Kopie fahren: Suite, Typprüfung, Mutanten. Ein Mutantenlauf gibt je Mutant die Fehlerzeile aus, nicht nur den Exitcode.

4. Vor jeder Welle und nach jeder Plankorrektur: plan_bloecke.py vor <tasks…> --projekt <projekt> (jeder Aus-Block steht genau einmal im echten Baum) und plan_zeichen.py <planordner> (keine Zeilen- und Absatztrenner, Format- und Steuerzeichen in Codeblöcken).

5. Nach jeder Welle: welle_vergleich.py --projekt <projekt> --mat <kopie> [--prosa <rel> …] -- <taskdateien der Welle>. Prüft, ob genau die Zieldateien geändert sind und ob jede byte-gleich mit der Kopie ist. Es zeigt je Datei nur die erste Abweichung — danach diff auf die ganze Datei. Eigene Plankorrekturen im Baum meldet es zu Recht als „außerhalb der Zieldateien".

6. Escape-Folgen setzen: plan_escape.py <datei> <zeile> <codepunkt-hex> … ersetzt echte Zeichen in einer Zeile durch ihre Escape-Folge, ohne dass eine Schreibschicht mitredet.

7. Rot-Nachweis je Task (seit 2026-09-18): rot_nachweis.py <basis-kopie> <planordner> <arbeitsordner> <spec.json> [--fixturen <ordner>] [--node-modules <pfad>] [--conftest-als-test]. tests/conftest.py gilt dabei als Produktivseite und wird zurückgesetzt; nur wenn die neue Fixture eines Tasks dort liegt, lässt --conftest-als-test sie stehen (Beleg unten, 2026-09-22). plan_materialisiere.py wendet eine Taskdatei immer ganz an; „erst der Test, dann die Umsetzung" lässt sich damit nicht beobachten. Das Skript stellt den Zustand dazwischen auf Wegwerfkopien her — Basis plus Voraussetzungstasks plus der Task, danach die produktiven Zieldateien zurück auf den Stand vor dem Task — und fährt die Testdateien des Tasks (pytest in WSL, vitest unter Windows über eine Junction, die es vor dem Löschen löst). Es meldet je Task ROT mit der ersten Fehlerzeile oder GRUEN; ein Test, der ohne Umsetzung grün ist, misst sie nicht. Die Basis-Kopie zieht man vor der ersten Welle. spec.json nennt je Task die Voraussetzungstasks. Erster Einsatz am 2026-09-18 an vier Plänen der Trading Plattform: 35 Tasks, alle rot an der gemeinten Stelle, keiner grün ohne Umsetzung. Die Executer brauchen den Tanz mit dem Beiseitelegen der Produktivdatei dann nicht mehr; ihr Auftrag sagt das ausdrücklich.

Was belegt ist

Seit 2026-09-18 nimmt welle_vergleich.py unter ## Zieldateien auch Pfade relativ zum Projekt (ohne Laufwerk und ohne Wurzel), weil Pläne für einen Git-Worktree keine absoluten Pfade nennen; ein .. darin ist ein Befund wie ein fremder absoluter Pfad. Jede Zeile braucht weiter die Klammer hinter dem Pfad ((neu), (geändert), (gelöscht)). plan_materialisiere.py erkennt eine Zieldatei ohne Schrägstrich nur mit den Endungen py, ts, tsx, toml, md, css und json — für compose.yaml in der Projektwurzel schreibt die Überschrift ./compose.yaml. Der Treiber fährt dazu drei weitere Fälle (relative Grundlinie, relative Abweichung, .. nach außen), zusammen 17.

Seit 2026-09-22 behandelt rot_nachweis.py tests/conftest.py als Produktivseite. Vorher zählte alles unter tests/ als Testdatei — lag die Korrektur eines Tasks selbst in conftest.py (Trading Plattform, Task 369: die Ersatzfunktionen der Netzsperre trugen eine andere Vorgabe als die Originale), wendete der Lauf „ohne Umsetzung" sie mit an und meldete GRUEN pytest: 147 passed — der eine Zustand, in dem der Nachweis nichts misst, sah aus wie ein sauberer Befund. Gemessen an derselben Basis-Kopie und demselben Task, altes gegen neues Skript: GRUEN 147 passed → ROT 3 failed, 144 passed mit der gemeinten Fehlerzeile (assert ('', '') == ('probe-thema', '')). Die Gegenprobe für den anderen Fall — eine neue Fixture des Tasks liegt in conftest.py (Task 368) — mit --conftest-als-test ROT 1 failed, 11 passed wie vor der Änderung, ohne Schalter ROT 6 failed, 6 passed mit AttributeError: module 'conftest' has no attribute '_gesperrte_pfade' als erster Fehlerzeile: rot aus dem falschen Grund, aber sichtbar, und das Skript sagt je Task, wie es conftest.py behandelt hat. Was es weiter nicht sieht: ob ein Task beides in conftest.py legt, Fixture und Korrektur — dann ist keine der beiden Einstellungen richtig, und der Nachweis läuft von Hand.

Seit 2026-09-20 quotet rot_nachweis.py den Arbeitsordner für den WSL-Aufruf (shlex.quote). Ein Temp-Pfad mit Leerzeichen — der Benutzername steckt im Scratchpad-Pfad — ließ vorher das cd scheitern: Alle sieben Tasks eines Plans der Trading Plattform standen als „ROT pytest: keine Summenzeile" da, ohne dass ein einziger Test lief. Nach der Korrektur derselbe Lauf mit echten Summenzeilen (3 failed, 17 passed, 1 error, …). Wer „keine Summenzeile" bei jedem Task sieht, hat kein Rot gemessen, sondern ein kaputtes Werkzeug.

welle_vergleich_treiber.py fährt 14 Angriffsfälle gegen welle_vergleich.py (Grundlinie zuerst; fremde Datei, unveränderte Zieldatei, Abweichung in erster und letzter Zeile und in der letzten Zieldatei, CRLF, Datei fehlt in der Kopie, Task ohne Zieldateien, Kopie fehlt, Löschung nicht ausgeführt, Prosa-Datei unverändert, Zieldatei außerhalb des Projekts, Datei länger als der Plan). plan_zeichen.py hat am 2026-09-17 an einem echten Fund rot gezeigt (U+2028 im Plan). plan_materialisiere.py reproduziert Task 108 des Teil-3b-Plans aus dem Stand vor den Wellen byte-genau. kopie_bauen.py ist am 2026-09-17 an drei kaputten Eingaben rot gesehen: Ziel existiert schon (Exit 2, nichts kopiert), Ausschluss node_modules ohne Gegenstück im Wurzelordner (Befund), und ein aus der Kopie entferntes Paket trading/data (die Paketprüfung nennt es; nach dem Zurücklegen leer). Einen Treiber dazu gibt es noch nicht — die drei Fälle sind von Hand gefahren.

Offen seit 2026-09-23: plan_materialisiere.py stirbt mit FileNotFoundError, wenn die Zieldatei eines „Häng diesen Block ans Ende"-Blocks in der Kopie fehlt (Trading Plattform, Task 384 hängte einen Nachtrag an die Planübersicht an; die Kopie war ohne docs/plans gebaut). Ein Absturz mitten im Task lässt die davor angewendeten Blöcke halb drin. Bis das ein Befund ist: Kopien für Pläne, die Plandateien selbst anfassen, mit dem Planordner bauen — und eine Kopie nie nach dem Start der Welle ziehen (sie trägt dann den halben Stand des Arbeitsbaums).

Was die Skripte nicht sehen

Dateien, die .gitignore ausblendet; ob die Kopie selbst sauber ist (eine verschmutzte Kopie erzeugt Fehlalarm, kein falsches Grün); ob die Kopie älter ist als der Plan — wird eine Taskdatei nach dem Anwenden noch überarbeitet, meldet welle_vergleich.py eine Abweichung, die keine ist (2026-09-17, Teil 4c: der Planer lief noch, als die Kopie entstand). Dann entscheidet plan_bloecke.py nach gegen den echten Baum, und die betroffenen Dateien der Kopie werden aus git show HEAD:<pfad> neu aufgebaut und der Task erneut angewendet; verwechselbare sichtbare Zeichen (kyrillisches „с"). Sie sind ein Fangnetz, kein Nachweis — den liefert der Lauf mit echten Daten.

Das ältere .vault-tools/plan-diff/plan_diff.py vergleicht Ganzdatei-Blöcke einer früheren Plankonvention und bleibt dafür in Gebrauch.