wow20/_bmad-output/implementation-artifacts/spec-3-7-reason-mutate-trennung-und-konsistenz-endzustand-sicherstell.md

title, type, created, status, baseline_commit, review_loop_iteration, context

title	type	created	status	baseline_commit	review_loop_iteration	context
Story 3.7 — Reason/Mutate-Trennung & Konsistenz-Endzustand sicherstellen	feature	2026-08-20	done	861e65f628	0	_bmad-output/implementation-artifacts/epic-3-context.md

Intent

Problem: AD-6/A0-7 trennen einen Compilation Run logisch in Analyse → Änderungsplanung → Mutation → Validierung, doch die Compiler-Instruktion führt die Phasen-Trennung nirgends explizit als durchsetzbare Disziplin — die feste Ablaufstruktur in §0 zählt nur Phasen (0)–(5), und die Plan-Vorprüfung (P2-Block) ist ein Baustein in §5.9 Pkt. 6, ohne als Änderungsplanungs-Phase mit Endzustands-Garantie ausgewiesen zu sein. Folge: Ein teilweise fehlgeschlagener Run könnte Zwischenstände hinterlassen, deren Konsistenz (AD-6: „Der beobachtbare Endzustand muss ein konsistentes Bundle sein") nur implizit über §6-Rollback abgesichert ist. A0-7-AC-2: „Given ein Fehler während der Mutation, When der Run abbricht, Then bleibt der beobachtbare Endzustand des Bundles konsistent".

Approach: Neue Sektion §5.13 „Reason/Mutate-Phasen-Trennung & Konsistenz-Endzustand (Story 3.7)" (nach §5.12, vor §6): die logische Phasen-Disziplin von AD-6 verbindlich in die Instruktion heben — der P2-Vorprüf-Block (§5.9 Pkt. 6) wird als Änderungsplanung (Analyse-Ergebnis → konsistenter Plan: Input-Zustand, Ziel-Pfade, Quellen-Existenz, Betroffenheits-Liste, Struktur-Erhaltung) institutionalisiert; die §§5/§5.9/§5.10-Mutationsmechanik wird als Mutationsphase unter Veränderungs-Sperre nach Phasenabschluss (Plan freeze), die §§6/§5.3-Rollback-Maschinerie als Validierungsphase mit Zustands-Restaurations-Invariante (Post-Rollback-Zustand == Baseline) geschlossen. Ohne eigene Workflow Engine (D-3, AD-6): die Trennung ist eine textuelle Ausführungs-Disziplin in einer Session. Endzustands-Konsistenz wird als beobachtbare, über Git-State überprüfbare Eigenschaft fixiert — nach einem abgebrochenen/fehlgeschlagenen Run ist der Bundle-Zustand der Baseline (oder der einer abgeschlossenen, valide committeten Mutation).

Boundaries & Constraints

Always:

• Nur schema/compiler.md (neue §5.13 + §7-Auflösung + §8 Revisionslog-Revision 3.2) mutiert (D-3); schema/validator.md, schema/wiki-compiler.md, adapters/, raw/ read-only (AD-3). Kein Standalone (D-3), keine eigene Workflow Engine (AD-6), keine neue §7-Invaliditätsklasse, kein Vertrags-Change, kein neuer Prädikat-/Format-Key, kein neuer Frontmatter-Key.
• Deterministisch aus dem committeten Git-State ableitbar (AD-17h/A0-19): Plan-Inhalt, Phasen-Reihenfolge, Rollback-Trigger und Post-Zustand; keine Wanduhr/now-Steuerung der Phasen-Disziplin (weder Planung noch Rollback hängen von Kalenderzeit ab).
• Endzustands-Konsistenz ist eine beobachtbare, über Git prüfbare Eigenschaft: Post-Rollback-Diff leer gg. Baseline bzw. Bundle == valide committeter Zustand des aktuellen Runs (Commit-Boundary = Mutation-Boundary, AD-17f, §0/§5.3).
• Die vier AD-6-Phasen decken sich logisch mit der §0-Ablaufstruktur (Analyse ≈ §1/§3.2, Änderungsplanung ≈ §5.9 Pkt. 6-P2-Block, Mutation ≈ §§4–5, Validierung ≈ §6); keine neue $Phasen-Nummerierung im §0-Listentext, §0 bleibt die deterministische Ausführungs-Folge.

Ask First:

• Einführung einer echten Planungs-Artefakt-Datei (separater Plan als persistentes Verzeichnis-Artefakt) statt des textuell festgehaltenen P2-Block-Plans — wäre eine neue Datei-/Baum-Regel außerhalb der Erhaltungs-Invariante.
• Änderung des §0-Phasen-Listentextes (Umformulierung der festen Folge) oder zusätzliche Phase — §0 bleibt Takt-Quelle; §5.13 ordnet nur logisch zu.
• Plan-freeze mit maschinellem Vergleich geplanter vs. tatsächlicher Mutationen über den §5.9-Pkt.-5-Diff-Selbsttest hinaus.

Never:

• raw/-Inhalte verändern (AD-3); uncommittete fremde wiki/-Änderungen löschen (AD-17e); textuelle Auto-Merge bei Branch-Konvergenz (AD-17c); Wanduhr/now-Zeitstempel als Phasen- oder Rollback-Steuer-Größe; eigener # Log-Stand in der Registry (wiki/log.md-Akkumulator ist alleiniger Aufzeichnungs-Ort, Vertrag §5); Standalone-Compiler/eigene LLM-Runtime (D-3, AD-11); Änderung an schema/validator.md/schema/wiki-compiler.md/adapters/.

I/O & Edge-Case Matrix

Scenario	Input / State	Expected Output / Behavior	Error Handling
PLAN_BEABSICHTIGT	erkannte Erkenntnis + bestehende Reconcile-Kandidaten; P2-Block-Ausführung	konsistente Änderungsplanung: Input-Zustand ⊇ Zuwachs committet, Ziel-Pfade ⊆ Kandidaten∪Neu-Anlage, Quellen-Existenz (EC-1), Betroffenheits-Liste (§3 Pkt. 2), Struktur-Erhaltung; Plan wird textuell festgehalten	Plan-Defizit benannt (NFR-4); fehlgeschlagene Vorprüfung ⇒ keine Mutation (Kette: Abbruch vor Mutationsphase)
PLAN_FREEZE	Mutationsphase beginnt	Änderungsplanung ist abgeschlossen; Veränderungs-Sperre: kein Plan-Gegenstand außerhalb der erlaubten Pfad-Menge (Kandidatenliste ∪ Neu-Anlage ∪ log.md ∪ index.md) wird mutiert	Verletzung = Ghost-Diff (§5.9 Pkt. 5): zurückrollen, textuell benannt
MUTATION_ABBRUCH	Fehler während der Mutationsphase	Run bricht ab; beobachtbarer Endzustand: Zustands-Restaurations-Invariante — Post-Rollback-Diff gg. Baseline leer / Zustand == Baseline; raw/ unverändert (AD-3)	§5.3-Pkt.-3/§6-Pkt.-3-Rollback-Mechanik greift; Ghost-Diff-Rollback (§5.9 Pkt. 5) greift; beides deterministisch aus Git-Teilen
MUTATION_TEILFOLGE	mehrere geplante Mutationen, nur ein Teil ausgeführt	Rollback stellt Baseline wieder her; kein Teilerfolg wird als fertige Mutation veröffentlicht (Commit-Boundary = Mutation-Boundary)	Textuelle Failure-Benennung (NFR-4); Phasen-Disziplin unverändert
VALIDATION_FAIL	Validierung meldet FAIL	Run als gescheitert; §6-Pkt.-3-Rollback; keine weiteren Mutationen; Endzustand konsistent	Rollback gemäß §5.3/§6; raw/ unverändert
VALIDATION_SUCCESS	alle wiki/-Dateien SUCCESS	Mutationen als Ganzes committen; Konsistenz = valide committeter Zustand; §6-Pkt.-4-Ausführungs-Nachweis	Commit erst nach Diff-Selbsttest ohne Ghost-Diff (§5.9 Pkt. 5); kein Wanduhr-Zeitstempel
KEINE_EIGENE_ENGINE	Anforderung „keine separate Workflow Engine" (AD-6)	logische Trennung in einer Session, kein neuer Prozess/Server/MCP	D-3/AD-11 unverändert; nichts Steuerndes wird gebaut

Code Map

• schema/compiler.md — primär mutiert (D-3): neue Sektion §5.13 „Reason/Mutate-Phasen-Trennung & Konsistenz-Endzustand (Story 3.7)" (nach §5.12, vor §6; Fixierung: §5.12-Ende Z. 341, §6-Start Z. 364 — neue Sektion zwischen beide, §5.13 Z. 343–362); §0-Phasen-Listentext unverändert (Takt-Quelle; §5.13 ordnet nur logisch zu); §5.9-Pkt.-6-P2-Block Wortlaut-unverändert, wird als Änderungsplanung referenziert (Rückverweis, keine Doppel-Instruktion); §6-Pkt.-3/§5.3-Rollback Wortlaut-unverändert, als Validierungsphase + Zustands-Restaurations-Invariante geschlossen; §7 (Z. 390ff.) Reason/Mutate-Vorbehalt als neuer §7-Bullet „in §5.13 verankert (Story 3.7)" (AD-6, A0-7, AC-1/2/3/4); §8-Normreferenz-AD-6 (Z. 430) von reiner Story-Zuordnung auf §5.13-Anker angehoben. Anker (IST-Zeilen nach Implementierung): §5.13-Sektion Z. 343; §7-Bullet nach Z. 420 (nach „Relevanzbestimmung"-Bullet); §8-AD-6 in Z. 430; Revisionslog-Eintrag Revision 3.2 nach Z. 461.
• wiki/log.md — append (append-only, Vertrag §5): Story-3.7-Eintrag (Verankerung, Sandbox-Nachweis, Statuswechsel, Validator-Verdikt); bestehende Bullets unverändert.
• _bmad-output/implementation-artifacts/sandbox-3-7/run-sandbox.sh — neu (re-executierbar, Muster sandbox-3-6, Exit 0): Szenarien CONSIST-1..CONSIST-7 (s. Design Notes), harte Pass/Fail-Assertionen, Erhaltungs-/Restaurations-Invariante erzwungen, keine Berührung des realen Ist-Baums.
• _bmad-output/implementation-artifacts/sprint-status.yaml — mutiert: 3-7-reason-mutate-trennung-und-konsistenz-endzustand-sicherstell backlog → in-progress; last_updated (Format MM-DD-YYYY HH:MM, HEAD-Präzision).
• _bmad-output/implementation-artifacts/deferred-work.md — append (append-only): ggf. Story-3.7-Defers (z. B. maschineller Plan-vs-Ist-Vergleich über den §5.9-Pkt.-5-Diff-Selbsttest hinaus), nach Prüfung der vorhandenen Defer-Liste (keine bereits auf Story 3.7 gedeuteten Einträge; Stand: keine Home-3.7-Defers vorhanden).
• _bmad-output/implementation-artifacts/epic-3-context.md, spec-3-6-…md — read-only (continue-context; Kette unverändert).

Tasks & Acceptance

Execution:

• schema/compiler.md — §5.13 einfügen (nach §5.12, vor §6); §0/§5.9-Pkt.-6/§6 Wortlaut-unverändert referenzieren; kein neuer Prädikat-/Format-/Frontmatter-Key
• schema/compiler.md — Revision 3.2 in §8 belegen (AD-6/A0-7 auf §5.13-Anker, Abschlussklausel) und §7-Bullet Reason/Mutate in §5.13-Verankerung
• _bmad-output/implementation-artifacts/sandbox-3-7/run-sandbox.sh — Szenarien CONSIST-1..7 (Plan-Erzeugung, Freeze-Sperre, Rollback-Restaurations-Invariante, Teilerfolg, Validierungs-Fail, Success-Commit, keine Engine), Exit 0
• _bmad-output/implementation-artifacts/deferred-work.md — ggf. Story-3.7-Defers append-only; keine Spuren in bereits vorhandenen Einträgen (Stand: keine Home-3.7-Defers — nichts anzuhängen, wie per README)
• wiki/log.md — (Implementierung) Story-3.7-Eintrag, sprint-status.yaml → in-progress; Review-Abschluss done im Review-Schritt (Workflow-Konvention)

Acceptance Criteria:

• Given ein Run, when er Änderungen plant, then erzeugt er zunächst eine konsistente Änderungsplanung (Analyse → Reconcile → Plan Changes → Mutate → Validate), textuell festgehalten (AD-6, A0-7; AC-1).
• Given ein Fehler während der Mutation, when der Run abbricht, then bleibt der beobachtbare Endzustand des Bundles konsistent — Post-Rollback-Diff gg. Baseline leer, raw/ unverändert (AD-6; AC-2, I/O-Matrix MUTATION_ABBRUCH).
• Given ein Run, when er abgeschlossen ist, then wurden alle geplanten Mutations-Validierungen erfolgreich durchlaufen und die Mutationen als Ganzes committet (A0-7; AC-3, VALIDATION_SUCCESS).
• Given die Architektur-Anforderung, when umgesetzt, then ist die Trennung logisch, ohne eigene Workflow Engine (AD-6; AC-4, KEINE_EIGENE_ENGINE).

Spec Change Log

Noch leer — wird von step-04 während der Review-Loops befüllt (append-only Konvention).

Design Notes

Warum §5.13 als eigene Sektion, nicht §0-Umbau? §0 (Z. 13) ist die deterministische Takt-Folge — (0)..(5) in fester Reihenfolge, das Rückgrat der Instruktion. AD-6 trennt logisch, ohne neue Workflow-Engine; die vier AD-6-Phasen sind eine konsolidierende Klassifikation derselben Ablaufstruktur (Analyse ≈ §1/§3.2, Änderungsplanung ≈ §5.9 Pkt. 6-P2-Block, Mutation ≈ §§4–5, Validierung ≈ §6). Ein Umbau von §0 allein würde die bestehenden Story-Statements (§5.9/§5.10/§5.11/§5.12: „dieselben Phasen §0: Interpretieren → Reconcile → Synthetisieren → Mutieren → Validieren") brechen. Deshalb: §5.13 referenziert den §0-Wortlaut unverändert und bindet die AD-6-Nomenklatur als Ausführungs-Disziplin an die bestehende Struktur — Review-Layer prüfen die Fugen-Identität (keine Um-Nummerierung im §0-Listentext, keine neue Phase).

Der P2-Block (§5.9 Pkt. 6) ist die natürliche Änderungsplanung. Bereits vorhanden und reproduzierbar: (1) Input-Zustand (AD-17a), (2) Ziel-Pfade, (3) Quellen-Existenz, (4) Betroffenheits-Liste (§3 Pkt. 2), (5) index.md-V-1, (6) Struktur-Erhaltungs-Check. §5.13 macht diese Vorprüfung zur Änderungsplanung der AD-6-Kette und ergänzt zwei institutionalisierte Eigenschaften: den Plan-Freeze (Veränderungs-Sperre — nach Phasenabschluss wird kein Pfad außerhalb der erlaubten Menge berührt, Kopplung an die §5.9-Pkt.-5-Diff-Probe) und den Plan-Nachweis (der Plan wird als Teil der textuellen Ausführungsdisziplin festgehalten — kein Artefakt-File, keine Erhaltungs-Invarianten-Ausweitung).

Die Konsistenz-Garantie ist bereits vorhanden — §5.13 macht sie beobachtbar. §6-Pkt.-3/§5.3-Pkt.-3-Rollback und der Ghost-Diff-Rollback (§5.9 Pkt. 5, „AD-6-Backstop") existieren; die Anforderung „Endzustand konsistent" ist aber bislang eine erzählte Eigenschaft, keine git-überprüfbare Invariante. §5.13 definiert die Zustands-Restaurations-Invariante: nach Abbruch/FAIL ist git diff gegen die Baseline leer (Bundle == Baseline) oder das Bundle ist der valide committete Zustand des Runs (Erfolgsfall; Commit-Boundary = Mutation-Boundary, AD-17f). Beide Pfade sind deterministisch und ohne Wanduhr.

Sandbox (CONSIST-1..CONSIST-7, bash run-sandbox.sh, Exit 0):

• CONSIST-1: konsistente Änderungsplanung — P2-Block erzeugt Plan (Input-Zustand, Ziel-Pfade, Betroffenheit, Struktur-Erhaltung) aus committetem Input, als Variablen-Set captured, Determinismus (AD-17h/A0-19)
• CONSIST-2: Plan-Freeze — Mutation außerhalb der Plan-Pfadmengen wird erkannt und verweigert/verhindert (Veränderungs-Sperre, Ghost-Diff-Kopplung §5.9 Pkt. 5)
• CONSIST-3: Rollback-Restaurations-Invariante — fehlgeschlagene Mutation rollt auf exakte Baseline zurück (SHA-256 byte-identisch), Bundle-Zustand == Baseline
• CONSIST-4: MUTATION_ABBRUCH — Abbruch nach Teilerfolg hinterlässt keinen Teilerfolg als fertige Mutation (Commit-Boundary), raw/ unberührt
• CONSIST-5: VALIDATION_FAIL — §6-Pkt.-3-Rollback, keine weiteren Mutationen, Endzustand konsistent
• CONSIST-6: VALIDATION_SUCCESS — Mutationen als Ganzes committet, Diff gg. Plan-Menge gedeckt, §6-Pkt.-4-Nachweis
• CONSIST-7: Determinismus-Zwei-Run + keine Engine — gleicher Baum-Input → identische Plan-/Rollback-/State-Outputs; Trennung ohne Workflow-Engine (nur Shell/Git/Datei, D-3)

(Code-/Zahlgenauigkeiten: Szenario-Labels sind Fixierung der I/O-Matrix; die Implementierung trägt die harten Assertionen in der Sandbox.)

Verification

Commands (re-executierbar, ab Workspace-Root):

1. bash _bmad-output/implementation-artifacts/sandbox-3-7/run-sandbox.sh — expected: CONSIST-1..CONSIST-7 harte PASS/Fail, Restaurations-Invariante erzwungen, Exit 0.
2. grep -n "§5.13\|Revision 3.2" schema/compiler.md — liefert §5.13-Sektion + Revisionslog-Eintrag; grep -n "Reason/Mutate-Phasen-Trennung" schema/compiler.md — die §5.13-Überschrift wortgleich (inkl. §5.12-Seam-Satz in §5.13-Intro).
3. Read-only (AD-3): git status --porcelain zeigt keinen Change an schema/validator.md/schema/wiki-compiler.md/adapters//raw/.
4. Validator-Lauf: alle wiki/-Dateien SUCCESS (unverändert, keine Inhalts-Mutation).
5. Auf den wiki/-Scope begrenzt (git status --porcelain -- wiki/): ausschließlich wiki/log.md (dieser Eintrag) — Erhaltungs-Invariante §5.9 Pkt. 5 gewahrt; sprint-status.yaml/deferred-work.md/sandbox-3-7/ liegen außerhalb wiki/ und sind nicht Teil der Diff-Probe (wie §5.9 Pkt. 5-Doku, Story-3.6-Präzedenz).

Zu beachten (beim step-04-Review): (a) §0-Phasen-Listentext, §5.9-Pkt.-6-P2-Block und §6-Pkt.-3/§5.3-Referenz müssen textuell unverändert bleiben — §5.13 verweist auf sie (Fugen-Identität: Um-Nummerierung oder neue Phase => Ask-First); (b) „die vier AD-6-Phasen decken sich logisch mit der §0-Struktur" ersetzt keine §0-Normierungen — sie ist eine Zuordnungstabelle, kein Parsing-Muss; (c) die vorhandene §8-Revisionslog-Nummer ist 3.1 (Story 3.6); Revision 3.2 ist für Story 3.7 frei (grep-verifiziert: keine 3.2 im Revisionslog); (d) kein neuer §7-Bullet ersetzt einen bestehenden — der Reason/Mutate-Bullet wird ergänzt, die bestehenden Story-Bullets (2.2/2.3/2.4/2.5/3.2/3.4/3.5/3.6) bleiben unverändert.

Suggested Review Order

§5.13-Reason/Mutate-Trennung-Instruktion

• Einstieg: §5.13-Sektion — logische Phasen-Disziplin (AD-6/A0-7), Kern der Story, §5.12-Seam und §0-Zuordnungstabelle. compiler.md:343
• Änderungsplanung: P2-Block (§5.9 Pkt. 6) als Phase institutionalisiert, Plan-Freeze (Veränderungs-Sperre, Ghost-Diff-Kopplung §5.9 Pkt. 5). compiler.md:356
• Zustands-Restaurations-Invariante: Post-Rollback-Diff gg. Baseline leer / Bundle == valide committet; §6-Pkt.-3/§5.3-Rückverweis unverändert. compiler.md:358
• Keine eigene Workflow Engine (D-3, AD-6): logische Trennung in einer Session, kein Prozess/Server/MCP. compiler.md:362

§7/§8-Nachweis

• §7-Bullet Reason/Mutate-Trennung — „in §5.13 verankert (Story 3.7)", AD-6/A0-7, bestehende Bullets unverändert. compiler.md:420
• §8-Revisionslog Revision 3.2 — Verankerung, Abschlussklausel, AD-6 auf §5.13-Anker. compiler.md:461

Sandbox-Nachweis

• Sandbox CONSIST-1..CONSIST-7 — re-executierbar, harte PASS/Fail, Zustands-Restaurations-Invariante (Exit 0) run-sandbox.sh:1

Story-Protokoll/Defers

• log.md — Story-3.7-Eintrag (Verankerung, Sandbox-Nachweis, Statuswechsel). log.md:1
• sprint-status.yaml — 3-7-… → in-progress (Implementierung) — nur backlog → in-progress; das done-Transition ist nicht Teil dieses Diffs (Review-Schritt). sprint-status.yaml:60
• deferred-work.md — ggf. Story-3.7-Defers append-only. deferred-work.md:1