Michael TamseandClaude
efc543c9e1
- schema/compiler.md: §3 Pkt. 2 Update-Routing (statt Kollision-Hold) + textuell-deterministische Kandidatenliste (AD-13); §5.9 Update-Mutationsmechanik (Erweitern/Präzisieren/Korrigieren, sources nur echte Belege, generated.at-Konvention, log.md-Eintragspflicht Story-3.1-Update, Mehrfach-Treffer-Konsolidierung); Erhaltungs-Invariante + deterministischer Diff-Selbsttest (git diff --name-only -- wiki/ ⊆ Kandidatenliste∪log.md∪Index, Ghost-Diff-Rück-Rollen); Run-Vorphase-Bausteine (Defer R-1 Change-Detection + P2 Pre-Run-Reconcile; Baseline = HEAD der vorherigen Mutations-Boundary); §0-Aufruf Update-Variante; §5.7/§5.8-Referenzen nachgeführt; §7 Update entlassen; §8 Prüfgrundlage Revision 9 (Punkt-11-Area-Lesart, Rev-9-Lücke geschlossen) + Revisionslog 2.4/2.4.1 (Step-04-Review-Patch-Runde, AD-3/D-3 gehalten, Worked Example real) - wiki/log.md: Story-3.1-Nachweis (Diff-Selbsttest wiki/log.md, per-Datei-Verdikt, Rev-9-Präzisierung, Sprint in-progress→review) - deferred-work.md: R-1/P2 aufgegriffen (2026-08-18 §5.9); Review-Findings-Protokoll bzw. F17-Defer (git-lose Ausweichform ab Story 3.2) - sprint-status.yaml: Story 3.1 → in-progress → review (Sprint-Sync), last_updated 22:30 - neu: epic-3-context.md, spec-3-1-… (status done, Suggested Review Order) Co-Authored-By: Claude <noreply@anthropic.com>
51 lines
7.4 KiB
Markdown
51 lines
7.4 KiB
Markdown
# 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 es bei jedem Lauf aus sämtlichen Rohquellen neu aufzubauen (Compounding Knowledge). Bestehende Concepts werden durch neue Erkenntnisse erweitert, präzisiert oder korrigiert; Informationen aus mehreren Sources werden zu einer gemeinsamen Wissensrepräsentation mit gemischter, claim-granularer Provenienz synthetisiert; unverändertes Wissen bleibt erhalten. Die Relevanzbestimmung ("welche bestehenden Concepts sind betroffen") ist textual-deterministisch (grep/ripgrep, Markdown-Traversal, Link-Following) — ohne Embedding- oder Vector-Infrastruktur. Konkurrierende Producer koordinieren sich über ein leasing-/branch-basiertes Workspace-Modell mit Root-Scope-Lease und Dirty-Tree-Schutz; Mutationen sind commit-gebunden, und jeder Run endet in einem konsistenten, über denselben Git-State reproduzierbaren Bundle (AD-5, AD-6, AD-13, AD-17a..h).
|
|
|
|
## 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
|
|
|
|
## 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 bleibt erhalten; Git-Änderungen konzentrieren sich auf die durch die neue Erkenntnis betroffenen Concepts (FR-4, FR-12).
|
|
- Neue Informationen führen nicht automatisch zu neuen Dateien: bestehende Concepts werden erweitert, präzisiert oder korrigiert, ohne ihre Struktur zu zerstören; Beziehungen und Provenienz bleiben soweit weiterhin gültig 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 (FR-7, AD-4).
|
|
- Unvollständiges, ungeprüftes oder teilweise widersprüchliches Wissen wird dargestellt, ohne künstliche Gewissheit zu erzeugen (NFR-7).
|
|
- Relevanzbestimmung und Merges sind textual-deterministisch; Embeddings, Vector-Search, Knowledge-Graph-DB und RAG gehören nicht in den Compiler-Kern (AD-13, AD-17h, PRD-No-Goals).
|
|
- 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).
|
|
|
|
## Technical Decisions
|
|
|
|
- **Inkrementeller Datenfluss (AD-5, A0-6):** Interpret → Reconcile → Synthesize → Update affected Concepts. Startpunkt ist immer das bestehende Bundle — niemals "Regenerate Everything" aus allen Rohquellen. Validiert durch die Incrementality-Anforderung (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 bei Abbruch konsistent sein.
|
|
- **Deterministische Relevanzbestimmung (A0-18):** Führt zu einer nachvollziehbaren Candidate-Liste von Concept-Pfaden über grep/ripgrep auf `wiki/`, Markdown-Traversal von `index.md` und Link-Following — deterministisch statt probabilistisch. Gleichsam Grundlage für die Bereichszuordnung (gleiches textuelles Prinzip wie AD-7c).
|
|
- **Keine eigenständige LLM-Runtime:** Der ausführende agentische Host (Claude/Codex-Adapter) orchestriert die Sequenz gemäß AD-17 (Lease holen, innerhalb des geleasten Bereichs mutieren, committen, freigeben); keine separaten Prozesse oder ein Server (AD-11).
|
|
- **Leasing-Modell (AD-17a..f, A0-12..A0-16):** Producer arbeiten auf `lease/<area>/<id>`-Branches; Lease-Akquise gegen einen eindeutigen Commit-Object-Wert (Merge-Base-Disziplin); ein Lockfile realisiert semantisch identisch in jedem Adapter — Realisierung ist nicht pro Adapter frei wählbar. Die Lease umfasst die Root-Scope (`wiki/` inklusive `log.md`, `index.md` und aller Root-Dateien).
|
|
- **Kein textueller Auto-Merge (AD-17c, A0-14):** Zwei Branches mit Änderungen am selben Concept-Pfad werden nie textuell automatisch gemerged; der Merge ist compiler-vermittelt und durchläuft die AD-16-Klassifikation mit explizitem `log.md`-Eintrag, falls die Inhalte ungleich sind.
|
|
- **Dirty-Tree-Schutz (AD-17e/f, A0-16):** Vor jeder Mutation wird die Working Copy des zu mutierenden Bereichs geprüft; fremde uncommittete Änderungen werden geschützt (Stash/Scratch-Zone) und in `log.md` dokumentiert. Mutationen operieren nur auf Directory-/Commit-Ebene — Commit-Boundary ist die Mutation-Boundary.
|
|
- **Lease-Staleness (AD-17d, A0-15):** TTL plus Lease-Registrierung im Clone-Root-State; uncommittete Leases gelten nach Run-Abbruch als stale, verwaiste Leases können übernommen oder als stale markiert und protokolliert werden; `raw/` dient als Zugriffs- und Consistency-Basis.
|
|
- **Auflösungsautorität (AD-17g, A0-17):** Der die Lease haltende Compilation Run löst AD-16-Kollisionen (Default: Erhaltung) auf; menschliche Eskalation nur bei Unentscheidbarkeit; die Auflösung wird an Commit-Hash und Klassifikation im `log.md` gebunden.
|
|
- **Determinismus-Vertrag (AD-17h/FT-10, A0-19):** Über denselben Git-State und dasselbe Eingabeset erzeugen zwei unabhängige Runs denselben Bundle-State; Abweichung gilt als Fehler der Klassifikation, nicht als Rauschen. Das Enforcement lebt im MVP als Agent-Instruktions-Validator (D-3/Q-6) und muss mechanisch bestätigt sein, bevor es tragend wird.
|
|
- **Inkrementelle Evolution und menschliche Kuratierung (A0-21, FT-9):** Unabhängige Concepts werden nicht bei jedem Lauf regeneriert; eine menschliche Korrektur eines maschinell erzeugten Concepts überlebt als normale Kuratierung (Datei-Edit + Git) — kein Nulling-Diff und keine Re-Kompilation des ganzen Bundles.
|
|
- **Synthese bleibt source-grounded (AD-4):** Bestehende Concepts dürfen Kontext und Synthese liefern, fachliche Aussagen müssen aber auf nachvollziehbare Sources zurückführbar bleiben; Wiki-Links ersetzen nie die Provenienz zur ursprünglichen Evidenz.
|
|
|
|
## Cross-Story Dependencies
|
|
|
|
- Baut auf dem Workspace aus Epic 1 auf (`raw/` immutable, Bundle-Root, Schema-Validierung) und konsumiert die in Epic 2 erzeugten, OKF-konformen, verlinkten Concepts mit claim-granularer Provenienz als vorhandenes Wissen.
|
|
- Der compiler-vermittelte Merge (AD-17c) und die Kollisionsauflösung (AD-17g) setzen die AD-16-Klassifikation samt `log.md`-Dokumentation voraus, die in Epic 4 umgesetzt wird.
|
|
- Das Leasing-/Dirty-Tree-Modell dieses Epics koordiniert Compiler-Runs mit menschlicher Bearbeitung (Q-2) und liefert die Grundlage für die Git-Nachvollziehbarkeit und Auflösungs-Dokumentation, auf die Epic 5 aufsetzt.
|
|
- Keine UX/Design-Anteile relevant: v1 ist datei-/CLI-basiert ohne GUI (A-3, AD-11).
|