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

Epic 3 Context: Inkrementelle Kompilation & Synthese

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-23 — gehärtetes Gate, Re-Run #5 rot an E.4): das reale, unabhängige Source→Compilation→Wiki-Abnahmegate _bmad-output/implementation-artifacts/sandbox-3-13/run-sandbox.sh (gehärtet, 915 Z.) ist als Voll-Lauf ausgeführt. 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: Story 3.13 bleibt offen, Bedarf an einer separat autorisierten Epic-1-Remediation (bzw. menschliche A/B-Umfangs-Entscheidung) wird benannt; F/G liefen im Voll-Lauf nicht (fail-fast an E.4). Siehe wiki/log.md Story-3.13-Eintrag (2026-08-23). Epic 3 ist damit noch nicht abnahmegeeignet (epic-3 in-progress); die finale Retrospektive (Epic-3-retrospective) schließt das Epic erst nach grünem Re-Run + Review-Loop-2 ab (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-23): realisiert als sandbox-3-13/run-sandbox.sh (gehärtet, 915 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). Härtung + 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 (Story 3.13 offen, separat autorisierte Epic-1-Remediation bzw. A/B-Umfangs-Entscheidung). F/G im Voll-Lauf nicht demonstriert (fail-fast an E.4).
• 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 — ausgeführt (Erst-Lauf 2026-08-22 grün: PASS_COUNT=70, RUN_OK/Exit 0, A/B identisch bis auf at-Ausnahme, Validator 7/7 SUCCESS — gültiger Erst-Lauf-Beleg); das gehärtete Gate (915 Z.) rot an E.4 im Re-Run #5 (2026-08-23): korrekt erkannter, echter AD-16-A/B-Divergenz-Befund in der freien CREATE-Synthese (Slug-/Wortlaut-Divergenz, NON_AT=26 AT=4), kein false-PASS, UPDATE-Pfad alpha byte-identisch bis auf at:. AC-4-Defizit-Roadmap: Story 3.13 bleibt in-progress (kein stiller Schema-Change), Bedarf an separat autorisierter Epic-1-Remediation bzw. menschlicher A/B-Umfangs-Entscheidung benannt; grüner Re-Run + Review-Loop-2 ausstehend; siehe wiki/log.md Story-3.13-Eintrag (2026-08-23).
• 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.