wow20/_bmad-output/implementation-artifacts/epic-3-context.md

# Epic 3 Context: Inkrementelle Kompilation & Synthese

<!-- Compiled from planning artifacts. Edit freely. Regenerate with compile-epic-context if planning docs change. -->

## Goal

Der Compiler verarbeitet neues Source Material gegen das bestehende Knowledge Bundle, statt das Wiki bei jedem Lauf aus sämtlichen Rohquellen neu aufzubauen (Compounding Knowledge). Bestehende Concepts werden durch neue Erkenntnisse erweitert, präzisiert oder in eindeutig belegten Fällen korrigiert; mehrere Sources werden zu einer gemeinsamen Wissensrepräsentation mit gemischter, claim-granularer Provenienz synthetisiert; unverändertes Wissen bleibt erhalten. Relevanzbestimmung und Reconcile-Routing sind textual-deterministisch ohne Embedding- oder Vector-Infrastruktur. Konkurrierende Producer koordinieren sich über eine atomare Root-Scope-Lease mit transaktionalem Dirty-Tree-, Rollback- und Release-Lifecycle. Klassifikationspflichtige Kollisionen und Widersprüche werden bis Epic 4 fail-closed als strukturierter Hold erhalten; der Determinismus-Vertrag wird mechanisch qualifiziert. **Ist (Story 3.13, 2026-08-24 — grüner Re-Run #10 + Review-Loop-2 konvergiert, `done`):** das reale, unabhängige Source→Compilation→Wiki-Abnahmegate `_bmad-output/implementation-artifacts/sandbox-3-13/run-sandbox.sh` (gehärtet, 1005 Z. nach Review-Loop-2) ist als Voll-Lauf ausgeführt. **Re-Run #10 (2026-08-24, committed `09c1c83`): GRÜN — `FAILED=0 PASS_COUNT=51`, SANDBOX-3-13-OK, RUN_OK/Exit 0** (A.5 Pre-Check sauber; C 12/12; D 4/4 SUCCESS; D-NEG 3×FAIL+1×SUCCESS; E.4 `NON_AT=0 AT=2`; E.6 Feldsatz-exakt + Known-Value-Witness gegen `$BASE`; E.9 kanonische `Baseline $BASE`-Form; F G-1..G-8; G-8 Porcelain-Clean + AD-3 ohne Diff); Review-Loop-2 (bmad-code-review 4 Layer): 38 rohe → 4 decision-needed / 11 patch / 2 defer / 4 dismissed — alle Entscheidungen mit ProMods geschlossen, alle Patches angewendet; finaler `done`-Flip (Step-05, Präzedenz 3.7–3.12). Siehe wiki/log.md Story-3.13-Eintrag (2026-08-24). Vorgeschichte: **Erst-Lauf (2026-08-22, vor Härtung):** grün (PASS_COUNT=70, FAILED=0, RUN_OK/Exit 0; 12 Sandbox-Suiten fail-fast, Validator 7/7 SUCCESS über die damals nicht-isolierte Fixture, A/B nur-at, G-1..G-8) — gültiger Erst-Lauf-Beleg. **Härtung (Review-Loop-1, 15 Patches):** isolierte Mini-Fixture (P-4), geankerter E.4-Classifier (P-2), D-NEG 3×FAIL+1×SUCCESS, G-6 perturbed-Tree-Negativ-Kontrolle, Validator-Defizit-Route u. a. **Re-Run #5 (2026-08-23, gehärtetes Gate):** A, B, C 12/12, D 4/4 SUCCESS, D-NEG 3×FAIL+1×SUCCESS, E.1–E.3 und beide frischen Agent-Läufe A/B (`RUN_DONE`) **grün** — **rot an E.4** (`NON_AT=26 AT=4`): ein **korrekt erkannter, echter AD-16-A/B-Divergenz-Befund** in der freien CREATE-Synthese (Slug-Identität `beta` vs. `quanten-observatorium-kanal` + freier Body-/log.md-Wortlaut), **kein false-PASS**; der UPDATE-Pfad (`alpha`) ist byte-identisch bis auf `at:`. Das Gate ändert die Schema-Semantik **nicht still** (AD-3/AC-4); die Behebung liegt in `schema/compiler.md` (read-only) oder im A/B-Vergleichsumfang (A0-20) → **AC-4-Defizit-Roadmap**: Bedarf an einer **separat autorisierten Epic-1-Remediation** wird benannt (Rev 3.8 — kanonische byte-deterministische `log.md`-Eintragsform — autorisiert und ausgeführt); F/G liefen im Voll-Lauf #5 nicht (fail-fast an E.4). **Epic 3 ist abnahmegeeignet und `done`** (grüner Re-Run #10 + konvergierter Review-Loop-2, 2026-08-24; A/B-Vergleichsumfang auf den Update-/Erhaltungs-Kern, D-3.13-6 Option 2); die finale Retrospektive (Epic-3-retrospective, optional) bleibt offen (AD-5, AD-6, AD-13, AD-17a/b/d–h, A0-6/7/12–16/18/19).

## Stories

- Story 3.1: Inkrementellen Datenfluss implementieren (Interpret → Reconcile → Synthesize → Update)
- Story 3.2: Relevanzbestimmung textual-deterministisch umsetzen (grep/ripgrep/Traversal)
- Story 3.3: Bestehende Concepts erweitern/präzisieren/korrigieren
- Story 3.4: Wissen aus mehreren Sources synthetisieren
- Story 3.5: Leasing & Dirty-Tree-Schutz für konkurrierende Producer umsetzen
- Story 3.6: Lease-Staleness & Recovery-Basis absichern
- Story 3.7: Reason/Mutate-Trennung und Konsistenz-Endzustand sicherstellen
- Story 3.8: Determinismus-Vertrag (AD-17h) als Agent-Instruktions-Validator umsetzen
- Story 3.9: Deterministische Relevanz- und Reconcile-Routing schließen
- Story 3.10: Inkrementelle Update- und Synthese-Erhaltung absichern
- Story 3.11: Root-Scope-Leasing atomar und worktree-übergreifend akquirieren
- Story 3.12: Lease-Lifecycle und Commit-Abschluss transaktional schließen
- Story 3.13: Epic-3-Verifikations- und Abnahmegate

## Requirements & Constraints

- Ein Compilation Run nimmt neues Source Material und das bestehende Wiki als Input; das Wiki wird inkrementell weiterentwickelt, nie vollständig regeneriert. Unverändertes Wissen und nicht betroffene Concepts bleiben erhalten; Git-Änderungen konzentrieren sich auf die durch die neue Erkenntnis betroffenen Concepts (FR-4, FR-12, AD-5).
- Neue Informationen führen nicht automatisch zu neuen Dateien: bestehende Concepts werden erweitert, präzisiert oder korrigiert, ohne ihre Struktur zu zerstören; weiterhin gültige Beziehungen und Provenienz bleiben erhalten (FR-6).
- Mehrere Sources zum selben Thema münden in eine gemeinsame Wissensrepräsentation statt getrennter Zusammenfassungen. Das Ergebnis reflektiert den erkannten Wissensstand, konsolidiert Redundanzen und übernimmt die relevante Source-Provenienz der beteiligten Sources — claim-granular (FR-7, AD-4, A0-3).
- Relevanzbestimmung, Routing, Planung und nicht-konfligierende Mutationen sind textual-deterministisch (grep/ripgrep, Markdown-Traversal, Link-Following). Embeddings, Vector-Search, Knowledge-Graph-Datenbank und RAG gehören nicht in den Compiler-Kern (AD-13, A0-18).
- Ein Run verwendet ausschließlich veröffentlichte (committete) Inhalte als Input, nie Zwischenstände während der Mutation (AD-17).
- `raw/` bleibt immutable und dient als Recovery-Basis; ein fehlgeschlagener Run verändert es nicht (AD-3).
- Unvollständiges, ungeprüftes oder widersprüchliches Wissen wird ohne künstliche Gewissheit dargestellt; klassifikationspflichtige Konflikte werden bis Epic 4 ohne Wissensmutation in einem benannten Hold erhalten (NFR-7).

## Technical Decisions

- **Inkrementeller Datenfluss (AD-5, A0-6):** Interpret → Reconcile → Synthesize → Update affected Concepts. Startpunkt ist immer das bestehende Bundle — niemals "Regenerate Everything" (SM-1, FT-6).
- **Reason/Mutate-Trennung (AD-6, A0-7):** Logische Phasen Analyse → Reconcile → Plan Changes → Mutate → Validate. Keine eigene Workflow Engine; ein Agent kann die Phasen in einer Session durchführen, der beobachtbare Endzustand des Bundles muss auch bei Abbruch konsistent sein.
- **Deterministische Relevanz & Routing (A0-18):** Geschlossene, geordnete Term-Gewinnung bzw. explizites persistiertes Term-Manifest; Suchterm und Concept-Body werden identisch normalisiert und literal-sicher verglichen. Eine exklusive Routing-Tabelle unterscheidet `UPDATE`, `CREATE`, `ORPHAN/HOLD` und echten `NO_OP`; gleicher Git-State plus gleiches Eingabemanifest erzeugt dieselbe Candidate-Liste und Reihenfolge. *Ist (Story 3.9, 2026-08-20): in `schema/compiler.md` **§5.15** verankert (Termgewinnung geschlossen, eine exklusive Routing-Tabelle, Raw-Immutability-Guard, reservierte Zielpfade, Zwei-Run-Identität; §3.2 bleibt Erhebungs-Anker, §5.15 Pkt. 3 die Routing-Zuordnung).* *Ist (Story 3.10, 2026-08-21): die Erhaltungs-Absicherung der operativen Update-/Synthese-Schritte und der Hold-Ausbau sind in `schema/compiler.md` **§5.16** verankert (Inkrementelle Update- & Synthese-Erhaltung + Hold-Ausbau, Punkte 1–8: Kontinuitäts-Garantie AC-1, Korrigieren mit Run-Receipt-Trace AC-2, Schutzbestandteile & Byte-Identität AC-3, CONFIRMING-Konsolidierung ohne NO_OP AC-4, gemeinsame Wissensrepräsentation als Synthese-Erhaltung AC-5, byte-erhaltender NO_OP AC-6, Provenienz-/Link-Selbsttest aus aktuellem Run AC-7, benannter Hold über die Erhebungs-Stufen a/b/c + Mehrziel-Auflösung AC-8/NFR-7; Erhaltungs-Nachweis als re-executierbare Sandbox E-1..E-9, Exit 0; kein neuer Regel-Operand, keine §7-Klasse, kein Standalone — Umlaut-vs-Transkription bleibt benannter Defer).*
- **Keine eigene LLM-Runtime:** Der ausführende agentische Host orchestriert den AD-17-Ablauf (Lease holen, innerhalb des geleasten Bereichs mutieren, committen, freigeben); keine separaten Prozesse oder ein Server (AD-11).
- **Atomare Root-Scope-Lease (AD-17a/b, A0-12/13):** Producer behalten die Branch-Konvention `lease/<area>/<id>`, akquirieren aber genau einen atomaren, scope-bezogenen Lock im clone-geteilten Zustand. Die Run-ID ist Lock-Inhalt, nicht Exklusivitätsschlüssel; konkurrierende Producer verschiedener IDs und Worktrees teilen denselben Root-Scope (`wiki/` inklusive `log.md`, `index.md` und aller Root-Dateien). *Ist (Story 3.11, 2026-08-21): die atomare Lock-Präzisierung ist in `schema/compiler.md` **§5.17** verankert (Revision 3.6 — Atomare Root-Scope-Lease-Akquise: Exklusivitätsschlüssel = einziger scope-bezogener Lock im clone-geteilten Zustand, eine committete Ref je Root-Scope `wiki/`, `git update-ref <ref> <wert> $ZERO_SHA` create-only, Run-ID als Lock-Inhalt statt Schlüsselbestandteil, atomare Akquise mit genau einem Gewinner und `LEASE_HOLD` für den Abgewiesenen, Kollisions-Hold mit beiden Commit-Hashes an Epic 4 statt textuellem Auto-Merge; §5.11-Pkt.-1/2-Wortlaut und §5.12-Anker bleiben unverändert maßgeblich, Fugen-Identität).*
- **Fail-closed Kollisionsgrenze (AD-17c, A0-14):** Zwei Branches mit ungleichen Änderungen am selben Concept-Pfad werden nie textuell automatisch gemerged. Epic 3 erhält beide Commit-Hashes und den Scope in einem strukturierten Hold; AD-16-Klassifikation und semantische Auflösung sind Epic 4 / Story 4.x.
- **Transaktionaler Lifecycle (AD-17d–f, A0-15/16, AD-6):** Preflight schützt getrackte und ungetrackte Fremdänderungen (eindeutige Abort-/Protect-Zustandsmaschine), Rollback restauriert exakt den bezeichneten Baseline-Commit (Index + Worktree), Release hinterlässt Mutation, zulässigen Nachweis und sauberen Worktree dauerhaft. Eine lebende Lease wird nicht allein durch Generationserhöhung stale; Staleness verlangt bestätigten Abbruch oder abgelaufene Liveness plus atomare Ownership-Prüfung. *Ist (Story 3.12, 2026-08-21): die transaktionale Lifecycle-Klammer ist in `schema/compiler.md` **§5.18** verankert (Revision 3.7 — Lease-Lifecycle & transaktionaler Commit-Abschluss: Liveness & Ownership AC-1, stale-Übernahme genau einmal mit benannter ersetzter Holder-ID AC-2, eindeutige Abort-/Protect-Zustandsmaschine für getrackte/ungetrackte Fremdänderungen mit byte-identischem Restore AC-3, Baseline-Rollback Index + Worktree aus `<Baseline-Commit>` mit leerem Post-Rollback-Diff AC-4, durable Release + Clean-Input-Guard für den Folge-Run AC-5, kanonisches Log AC-6, vier Kill-Point-Tests AC-7; §5.11/§5.12/§5.13/§5.17-Wortlaute textuell unverändert, Fugen-Identität; keine Wanduhr-TTL, A0-20).*
- **Determinismus-Vertrag (AD-17h/FT-10, A0-19):** Das kanonische Eingabemanifest bindet Baseline, geordnete Sources und jeden output-sichtbaren Run-/Zeit-/Identitätswert; der Run-Receipt (Candidates, Reihenfolge, Plan, Entscheidungen, Output-Hashes) liegt außerhalb des Bundles. Zwei getrennte saubere Worktrees mit frischen Agent-Kontexten erzeugen denselben Bundle-State; hart codierte erwartete Pläne oder Concept-Bodies und pauschal maskierte `verified`-Ereignisse sind kein gültiger Nachweis.
- **Synthese bleibt source-grounded (AD-4):** Bestehende Concepts dürfen Kontext liefern, fachliche Aussagen müssen aber auf nachvollziehbare `raw/`-Evidenz zurückführbar bleiben; Wiki-Links ersetzen nie die Provenienz zur ursprünglichen Evidenz.
- **Epic-3-Abnahmegate:** Ein portables, fail-fast ausführbares Gate führt alle Epic-3-Szenarien aus, ruft den vollständigen autorisierten Schema-Validator über alle `wiki/`-Dateien auf und lässt einen frischen Agent-Kontext die kanonische Instruktion über einer repräsentativen Fixture ausführen — der Harness schreibt keine erwarteten Wiki-Ausgänge selbst. Zwei frische Agent-Kontexte müssen Run-Receipts und Bundle-State angleichen. Ein Defizit des autorisierten Validator-Vertrags blockiert das Gate und verlangt eine separat genehmigte Epic-1-Remediation. *Ist (Story 3.13, 2026-08-24 — grüner Re-Run #10, Review-Loop-2 konvergiert, `done`): realisiert als `sandbox-3-13/run-sandbox.sh` (gehärtet, 1005 Z.) — fail-fast-Orchestrierung (A Setup, B /tmp-Käfig, C 12 Sandbox-Sub-Runs, D Validator-Agent mit Verdikt-Grammatik/-Exhaustivität statt eigener Urteile, E Zwei-frische-Agenten A/B auf git-worktree-$BASE, F G-1..G-8 harte Assertions inkl. G-6 Negativ-Kontrolle Perturbation und G-7 Epic-5-Smoke, G Porcelain-Endzustands-Invariante). Erst-Lauf (2026-08-22, vor Härtung) grün (PASS_COUNT=70, FAILED=0, RUN_OK/Exit 0 — gültiger Erst-Lauf-Beleg); G-7 exkludiert den Bundleroot-Schema-Glossar (../schema/, compiler §5.6 „andere Schicht", AC-8 optionale Provenienz) und das log.md-Protokoll (§5.6 Pkt. 2). **Grüner Re-Run #10 (2026-08-24, committed `09c1c83`): `FAILED=0 PASS_COUNT=51`, SANDBOX-3-13-OK, RUN_OK/Exit 0** — A.5 Pre-Check sauber, C 12/12, D 4/4 SUCCESS, D-NEG 3×FAIL+1×SUCCESS, E.4 `NON_AT=0 AT=2` (Bundle-State identisch bis auf `at:`), E.6 neu hart (Feldsatz-exakt P-L2-2 + A==B + Known-Value-Witness gegen `$BASE` P-L2-1), E.9 kanonische `Baseline $BASE`-Form (P-L2-6), F G-1..G-8 grün (G-6 Negativ-Kontrolle `NON_AT=2` erkannt, Positiv-Kontrolle at-only toleriert, G-7 0 Verletzungen), G-8 Porcelain-Clean (inkl. Untracked) + AD-3 ohne Diff. Review-Loop-2 (bmad-code-review 4 Layer): 38 rohe → 4 decision-needed / 11 patch / 2 defer / 4 dismissed — alle Entscheidungen mit ProMods geschlossen, alle Patches angewendet (P-L2-1..11). Finaler `done`-Flip (Step-05, Präzedenz 3.7–3.12); `epic-3` → `done` (AC-9). Vorhistorie: Re-Run #5 (2026-08-23) rot an E.4 (`NON_AT=26 AT=4`) — korrekt erkannter, echter AD-16-A/B-Divergenz-Befund in der freien CREATE-Synthese (Slug-/Wortlaut-Divergenz), kein false-PASS; UPDATE-Pfad `alpha` byte-identisch bis auf `at:` → AC-4-Defizit-Roadmap (separat autorisierte Epic-1-Remediation Rev 3.8 — kanonische byte-deterministische `log.md`-Eintragsform — ausgeführt; A/B-Vergleichsumfang auf den Update-/Erhaltungs-Kern, D-3.13-6 Option 2); F/G im Voll-Lauf #5 nicht demonstriert (fail-fast an E.4) — im grünen Re-Run #10 vollständig erreicht.*
- **Keine UX-/Design-Anteile relevant:** v1 ist datei-/CLI-basiert ohne GUI (PRD A-3, AD-11).

## Cross-Story Dependencies

- Baut auf dem Workspace aus Epic 1 auf (immutable `raw/`, Bundle-Root, Schema-Validierung) und konsumiert die in Epic 2 erzeugten OKF-konformen, verlinkten Concepts mit claim-granularer Provenienz als vorhandenes Wissen.
- Story 3.9 liefert die deterministische Routing-Basis für Story 3.10; Story 3.11 liefert die atomare Lease-Basis für Story 3.12 (parallel). Story 3.8 ist nach 3.9–3.12 mit echten unabhängigen Runs abgeschlossen (done); **Story 3.13 ist das finale Abnahmegate — `done` (2026-08-24, grüner Re-Run #10 committed `09c1c83`: `FAILED=0 PASS_COUNT=51`, SANDBOX-3-13-OK, RUN_OK/Exit 0 — A.5 Pre-Check sauber, C 12/12, D 4/4 SUCCESS, D-NEG 3×FAIL+1×SUCCESS, E.4 `NON_AT=0 AT=2`, E.6 Feldsatz-exakt + Known-Value-Witness, E.9 kanonische `Baseline $BASE`-Form, F G-1..G-8, G-8 Porcelain-Clean + AD-3 ohne Diff); Review-Loop-2 konvergiert (38 rohe → 4 decision-needed / 11 patch / 2 defer / 4 dismissed, alle ProMods geschlossen, alle Patches angewendet); Vorhistorie: Erst-Lauf 2026-08-22 grün (PASS_COUNT=70, gültiger Erst-Lauf-Beleg), gehärtetes Gate (915 Z.) rot an E.4 im Re-Run #5 (2026-08-23: `NON_AT=26 AT=4`, korrekt erkannter echter AD-16-A/B-Divergenz-Befund in der freien CREATE-Synthese, kein false-PASS) → AC-4-Defizit-Roadmap: separat autorisierte Epic-1-Remediation Rev 3.8 (kanonische byte-deterministische `log.md`-Eintragsform) ausgeführt + A/B-Vergleichsumfang auf den Update-/Erhaltungs-Kern (D-3.13-6 Option 2); finaler `done`-Flip + `epic-3` → `done` (AC-9) im Step-05-Status-Sync (2026-08-24); `epic-3-retrospective` (optional) offen; siehe wiki/log.md Story-3.13-Eintrag (2026-08-24).**
- AD-17c/A0-14 sind geteilt: Epic 3 verantwortet Erkennung und fail-closed Erhaltung, Epic 4 Klassifikation und semantische Auflösung. AD-17g/A0-17 verbleiben vollständig in Epic 4. A0-21 ist ebenfalls geteilt: Story 3.10 verantwortet den Incrementality-Teil (Erhaltung unabhängigen Wissens), Story 4.3 die Human-Curation-Semantik (FT-9).
- Das Leasing-/Dirty-Tree-Modell koordiniert Compiler-Runs mit menschlicher Bearbeitung und trägt die Git-Nachvollziehbarkeit, auf die Epic 5 aufsetzt.