wow20/_bmad-output/planning-artifacts/epics.md

---
stepsCompleted: ["1-requirements-extraction", "2-design-epics", "3-create-stories", "4-final-validation"]
inputDocuments:
  - _bmad-output/specs/spec-wow20/SPEC.md
  - _bmad-output/planning-artifacts/prds/prd-wow20-2026-08-14/prd.md
  - _bmad-output/planning-artifacts/architecture/architecture-wow20-2026-08-14/ARCHITECTURE-SPINE.md
  - _bmad-output/specs/spec-wow20/glossary.md
---

# wow20 - Epic Breakdown

## Overview

This document provides the complete epic and story breakdown for wow20 — **Wiki of Wikis**, a knowledge compiler that decomposes the requirements from the PRD, the SPEC, and the Architecture Spine into implementable stories. It transforms `Sources + existing knowledge → improved curated knowledge` as an OKF-0.2-compliant, Git-versioned, agent-native file-based knowledge bundle.

## Requirements Inventory

### Functional Requirements

FR-1: Der Nutzer kann dem Compiler eine oder mehrere Sources zur Verarbeitung bereitstellen; in v1 nur lokal bereitgestelltes Source Material (keine URL-Abrufe).
FR-2: Das System unterscheidet Source Material (`raw/`) eindeutig und physisch vom kuratierten Knowledge Bundle (`wiki/`); eine Kopie einer Source ist keine Wissensintegration.
FR-3: Abgeleitetes Wissen bewahrt seine Provenienz; jede belegte Aussage trägt einen Inline-Beleg auf `raw/`; neue Quellen entfernen bestehende Provenienz nicht unbeabsichtigt.
FR-4: Ein Compilation Run verarbeitet neues Source Material zusammen mit relevantem bestehenden kuratierten Wissen; das bestehende Wiki ist Input.
FR-5: Der Compiler kann aus Source Material neue eigenständige Concepts erzeugen; Concepts sind nicht an die Source-Struktur gebunden.
FR-6: Der Compiler kann bestehende Concepts erweitern, präzisieren oder korrigieren; neue Informationen führen nicht automatisch zu neuen Dateien.
FR-7: Der Compiler synthetisiert Informationen aus mehreren Sources zu einer gemeinsamen Wissensrepräsentation mit gemischter Provenienz (keine getrennten Zusammenfassungen).
FR-8: Widersprüchliche Informationen werden nie stillschweigend zu einer scheinbar eindeutigen Aussage zusammengeführt; Disagreements bleiben in `log.md` sichtbar; Unsicherheit darf Teil eines Concepts sein.
FR-9: Alle erzeugten Concepts sind OKF-0.2-konform (Markdown + YAML-Frontmatter, `type` Pflichtfeld, optionale `sources`/`generated`/`verified`/`status`/`stale_after`); kein eigener OKF-Dialekt.
FR-10: Beziehungen zwischen Concepts werden mit normalen Markdown-Links ausgedrückt, in genau einer erlaubten Form (AD-7b: bundle-relativ, mit oder ohne Endung — nie beides).
FR-11: Das Knowledge Bundle ermöglicht Progressive Discovery über Hierarchie + `index.md`, ohne proprietäre Datenbank.
FR-12: Ein Compilation Run entwickelt das bestehende Knowledge Bundle inkrementell weiter; unverändertes Wissen bleibt erhalten.
FR-13: Vorhandene menschliche Kuratierung wird als bestehendes Wissen behandelt; sie wird nicht ohne Provenienz aus dem aktuellen Run entfernt; Konflikte mit neuen Sources werden sichtbar (AD-15).
FR-14: Änderungen an Concepts sind über normale Versionskontrolle nachvollziehbar (Git-Diff); kein proprietäres Change-Tracking.
FR-15: Ein Consumer liest das Knowledge Bundle ohne Wiki-of-Wikis-spezifische Runtime (normale Markdown-Tools bzw. Standard-Dateioperationen).
FR-16: Das Knowledge Bundle ist nicht auf einen bestimmten LLM-Agenten oder Workflow zugeschnitten; BMAD, Claude Code, Codex etc. sind Consumer (Compilersemantik agent-unabhängig, AD-10).

### NonFunctional Requirements

NFR-1: Portability — Das Knowledge Bundle muss ohne Wiki-of-Wikis-spezifische Software kopiert, archiviert und gelesen werden können.
NFR-2: Human Readability — Alle kanonischen Wissensinhalte müssen für Menschen unmittelbar als Markdown lesbar sein.
NFR-3: Agent Readability — Das Knowledge Bundle muss mit Standard-Dateioperationen durch LLM-Agenten erschließbar sein.
NFR-4: Version-Control Friendliness — Änderungen müssen in einer Form erfolgen, die sinnvolle textuelle Diffs ermöglicht.
NFR-5: No Mandatory Runtime — Das Lesen des Knowledge Bundle setzt weder Server noch Datenbank noch laufenden Wiki-of-Wikis-Prozess voraus.
NFR-6: Vendor Independence — Das kanonische Knowledge Bundle hängt von keinem LLM-Hersteller oder Agent Framework ab.
NFR-7: Graceful Partial Knowledge — Das System stellt unvollständiges, ungeprüftes oder teilweise widersprüchliches Wissen dar, ohne künstlich Gewissheit zu erzeugen.

### Additional Requirements

- **A0-1 — Schema-Vertrag (`schema/wiki-compiler.md`, AD-1a):** Verbindliches OKF-0.2-Feldsubset (Liste vs. Map-Form von `sources`, Zulässigkeit von `generated`/`verified`, `status`-Policing), `log.md`-Typdefinition, Index-Regel und Validitätsprädikate; schemaspezifische Validierung bindet das Feldsubset (AD-1a/1b).
- **A0-2 — OKF-Validierung (F-2/AD-1b):** Kein erfolgreicher Compilation Run bei OKF-invalidem Bundle laut `schema/wiki-compiler.md`; strukturelle Invalidität schlägt den Run fehl, fehlende optionale Felder nicht.
- **A0-3 — Claim-granulare Provenienz (AD-4a):** Jede belegte Aussage trägt einen Inline-Verweis auf `raw/`-Evidenz; Kontext-/Synthese-Umformulierungen tragen einen expliziten Kontext-Marker ("übernommen aus <Concept> auf Basis von <source>, nicht eigenständig belegt").
- **A0-4 — Provenienz-Ziellinie (AD-4b):** `sources`-Einträge lösen ausschließlich auf `raw/`-Pfade oder extern referenzierte immutable Evidenz auf — nie auf `wiki/`-Concept-Pfade.
- **A0-5 — Keine abgeleitete Provenienz (AD-4c):** Ein generiertes Concept darf nie ein anderes generiertes Concept als alleinige Provenienz führen (Teil der `schema/wiki-compiler.md`-Validierung).
- **A0-6 — Inkrementeller Datenfluss (AD-5):** Interpret → Reconcile → Synthesize → Update affected Concepts; niemals Regenerate Everything aus allen Rohquellen.
- **A0-7 — Reason/Mutate-Trennung (AD-6):** Analyse → Änderungsplanung → Mutation → Validierung; Endzustand muss konsistent sein; keine eigene Workflow Engine.
- **A0-8 — Concept-Identität (AD-7/7a):** Identität = relativer OKF-Pfad ohne `.md` (`wiki/spring/index.md` → `spring`); genau eine kanonische ID-Normalisierung; Renames sind semantische Änderungen mit `log.md`-Redirect (AD-7d).
- **A0-9 — Eine erlaubte Linkform (AD-7b):** AD-8-Links bundle-relativ, mit oder ohne Endung — genau eine Form, nie beide.
- **A0-10 — Deterministische Bereichszuordnung (AD-7c):** Wohin ein Thema gehört, wird textual-deterministisch bestimmt (bestehender `index.md`-Link oder Top-Level-Kollisions-Hold auf bestehende Pfade).
- **A0-11 — Konflikterhaltung (AD-16a/b):** Default bei Widerspruch ist Erhaltung (CONTRADICTING), außer die neue Source ersetzt die alte mit expliziter Evidenz (CORRECTING mit dokumentierter Ersetzungslogik); Klassifikation samt Begründung landet im selben Artefakt wie die Mutation — `log.md`-Eintrag, verknüpft mit dem mutierten Concept-Pfad.
- **A0-12 — Leasing-Konvention (AD-17/17a):** Producer arbeiten auf `lease/<area>/<id>`-Branches; ein Lockfile realisiert semantisch identisch in jedem Adapter; Lease-Akquise gegen eindeutigen Commit-Object-Wert (Merge-Base-Disziplin).
- **A0-13 — Lease-Root-Scope (AD-17b):** Die Lease umfasst `wiki/` inklusive `log.md`, `index.md` und aller Root-Dateien.
- **A0-14 — Kein textuelles Auto-Merge (AD-17c):** Zwei Branches mit Änderungen am selben Concept-Pfad werden nicht textuell automatisch gemerged; Merge ist compiler-vermittelt und durchläuft die AD-16-Klassifikation mit explizitem `log.md`-Eintrag bei ungleichem Inhalt.
- **A0-15 — Lease-Staleness (AD-17d):** TTL plus Lease-Registrierung im Clone-Root-State; uncommittete Leases gelten nach Run-Abbruch als stale; `raw/` (immutable, AD-3) ist die Recovery-Basis.
- **A0-16 — Dirty-Tree-Schutz (AD-17e/f):** Vor jeder Mutation Prüfung der Working Copy auf den mutierten Bereich; fremde uncommittete Änderungen werden geschützt (Stash/Scratch-Zone) und in `log.md` dokumentiert; Mutation nur auf Directory-/Commit-Ebene (Commit-Boundary = Mutation-Boundary).
- **A0-17 — Auflösungsautorität (AD-17g):** MVP: Der Compilation Run, der die Lease hält, löst AD-16-Kollisionen gemäß AD-16a-Default auf; menschliche Eskalation nur bei Unentscheidbarkeit; Auflösung gebunden an Commit-Hash + Klassifikation im `log.md`.
- **A0-18 — Deterministische Relevanzbestimmung (AD-13, AD-17, PRD OQ-3):** Wie der Compiler relevante vorhandene Concepts findet, wird mit textuellen, deterministischen Mitteln umgesetzt: grep/ripgrep, Markdown-Traversal, Link-Following — keine Embedding-/Vector-Infrastruktur.
- **A0-19 — Determinsmus-Vertrag (AD-17h/FT-10):** Über denselben Git-State und dasselbe Eingabeset produzieren zwei unabhängige Runs denselben Bundle-State; Validierungsmechanismus (D-3/Q-6) lebt zunächst als Agent-Instruktions-Validator.
- **A0-20 — A0-Trust-Metadaten v1 (AD-15, PRD A-1/SM-C3):** v1-Default: maschinell erzeugt und ungeprüft → `generated: { by, at }` gesetzt, `verified` ungesetzt; human reviewed → `verified` mit `human:`-Präfix; Lifecycle via `status` (`draft`|`stable`|`deprecated`) und optional `stale_after`.
- **A0-21 — Inkrementelle Evolution (AD-5, FT-6/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.
- **A0-22 — Agent-unabhängiger Kompiliervertrag (AD-10):** Kanonische Compiler-Regeln werden agent-unabhängig beschrieben; Provider-/Agenten-Instruktionen sind dünne Adapter (`adapters/claude|codex|...`), die keine abweichende Knowledge-Semantik definieren.

### UX Design Requirements

Keine UX-Design-Anforderungen im MVP berücksichtigt: PRD A-3 (keine GUI in v1), AD-11 (kein Serverprozess). Retained: keine UI-Tokens, keine Komponenten, keine Accessibility-Anforderungen für grafische Oberflächen.

## Epic List

### Epic 1: Wissens-Workspace & Quellen-Aufnahme
Der Nutzer richtet den kanonischen Wissens-Workspace ein (`raw/` | `wiki/` | `schema/` | `adapters/`), stellt Sources lokal bereit, und kann Source Material jederzeit vom kuratierten Wissen unterscheiden. Der Workspace ist Git-versioniert und zerlegt Sources/Knowledge gemäß Separation of Concerns; die OKF-Schema-Validierung (F-2/AD-1b) verhindert erfolgreiche Runs auf invaliden Bundles.
**FRs covered:** FR-1, FR-2
**NFRs covered:** NFR-1, NFR-4
**AD/A0:** AD-2, AD-3, AD-12, AD-1a, AD-1b, A0-1, A0-2

### Epic 2: OKF-Concepts erzeugen & verlinken
Aus den Sources entstehen eigenständige, OKF-0.2-konforme Concepts mit claim-granularer Provenienz und v1-Trust-Metadaten (`generated` ohne `verified`); Concepts werden über genau eine Markdown-Linkform (AD-7b) miteinander verlinkt, über eine deterministische Bereichszuordnung (AD-7c) in eine Bundle-Hierarchie eingeordnet und über `index.md` progressiv entdeckbar.
**FRs covered:** FR-3, FR-5, FR-9, FR-10, FR-11
**NFRs covered:** NFR-2, NFR-3, NFR-7
**AD/A0:** AD-1, AD-4, AD-4a, AD-4b, AD-4c, AD-7, AD-7a..7d, AD-8, AD-9, A0-3, A0-4, A0-5, A0-8, A0-9, A0-10, A0-20

### Epic 3: Inkrementelle Kompilation & Synthese
Der Nutzer verarbeitet neue Sources gegen das bestehende Wiki: bestehende Concepts werden erweitert, präzisiert oder korrigiert; mehrere Sources werden zu einer gemeinsamen Wissensrepräsentation synthetisiert; unverändertes Wissen bleibt erhalten. Die Relevanzbestimmung erfolgt textual-deterministisch (grep/ripgrep/Traversal, AD-13); Producer arbeiten mit atomarer Root-Scope-Lease, Dirty-Tree-Schutz und commit-gebundener Mutation. Klassifikationspflichtige Kollisionen enden bis Epic 4 fail-closed in einem strukturierten Hold; der Determinismus-Vertrag wird unabhängig und mechanisch qualifiziert.
**FRs covered:** FR-4, FR-6, FR-7, FR-12
**NFRs covered:** NFR-7
**AD/A0:** AD-5, AD-6, AD-13, AD-17a, AD-17b, AD-17c (Fail-closed-Sicherheitsgrenze), AD-17d..17f, AD-17h, A0-6, A0-7, A0-12, A0-13, A0-14 (No-Auto-Merge-Sicherheitsgrenze), A0-15, A0-16, A0-18, A0-19, A0-21 (Incrementality-Teil)
**Shared boundary:** Epic 3 verantwortet bei AD-17c/A0-14 ausschließlich Erkennung und fail-closed Erhaltung; Epic 4 verantwortet Klassifikation und semantische Auflösung. Bei A0-21 verantwortet Epic 3 die Erhaltung unabhängigen Wissens, Story 4.3 die spezifische Human-Curation-Semantik.

### Epic 4: Wissenstreue — Widersprüche & menschliche Kuratierung
Widersprüche werden nie stillschweigend zur scheinbar eindeutigen Aussage zusammengeführt; relevante Disagreements bleiben als explizite Einträge in `log.md` erhalten; menschlich kuratierte Inhalte werden als bestehendes Wissen respektiert und bleiben über OKF-Trust-Metadaten (`verified: human:...`) von ungeprüftem maschinellem Output unterscheidbar; unvollständiges/ungeprüftes Wissen wird ohne künstliche Gewissheit dargestellt.
**FRs covered:** FR-8, FR-13
**NFRs covered:** NFR-7
**AD/A0:** AD-16, AD-16a, AD-16b, AD-15, AD-17c, AD-17g, A0-11, A0-14, A0-17, A0-20, A0-21

### Epic 5: Consumer-Zugriff & Nachvollziehbarkeit
Menschen und beliebige LLM-Agenten (BMAD, Claude Code, Codex, ...) lesen das Knowledge Bundle ohne Wiki-of-Wikis-spezifische Runtime; Änderungen sind über Git-Diffs nachvollziehbar; die kanonischen Compiler-Regeln sind agent-unabhängig mit dünnen Adaptern; es gibt keinen obligatorischen Server, keine Datenbank und keine proprietäre Abhängigkeit.
**FRs covered:** FR-14, FR-15, FR-16
**NFRs covered:** NFR-1, NFR-3, NFR-5, NFR-6
**AD/A0:** AD-10, AD-11, AD-13, AD-14, A0-21, A0-22

### FR Coverage Map

FR1: Epic 1 - Sources bereitstellen (lokal, 1..n)
FR2: Epic 1 - Sources vs. Curated Knowledge trennen
FR3: Epic 2 - Provenienz bewahren (claim-granular auf raw/)
FR4: Epic 3 - Sources gegen bestehendes Wissen verarbeiten
FR5: Epic 2 - Neue Concepts erzeugen
FR6: Epic 3 - Bestehende Concepts aktualisieren
FR7: Epic 3 - Wissen synthetisieren (mehrere Sources)
FR8: Epic 4 - Widersprüche sichtbar behandeln
FR9: Epic 2 - OKF-konforme Concepts erzeugen
FR10: Epic 2 - Concepts mit Markdown-Links verlinken
FR11: Epic 2 - Progressive Discovery (Hierarchie + index.md)
FR12: Epic 3 - Knowledge Bundle inkrementell weiterentwickeln
FR13: Epic 4 - Menschliche Kuratierung berücksichtigen
FR14: Epic 5 - Änderungen nachvollziehbar machen (Git)
FR15: Epic 5 - Tool-unabhängigen Zugriff
FR16: Epic 5 - Consumer vom Compiler entkoppeln

## Epic 1: Wissens-Workspace & Quellen-Aufnahme

Der Nutzer richtet den kanonischen Wissens-Workspace ein (`raw/` | `wiki/` | `schema/` | `adapters/`), stellt Sources lokal bereit und unterscheidet Source Material jederzeit vom kuratierten Wissen. Der Workspace ist Git-versioniert und zerlegt Sources/Knowledge gemäß Separation of Concerns; die OKF-Schema-Validierung (F-2/AD-1b) verhindert erfolgreiche Runs auf invaliden Bundles.
**FRs covered:** FR-1, FR-2 · **NFRs:** NFR-1, NFR-4 · **AD/A0:** AD-2, AD-3, AD-12, AD-1a, AD-1b, A0-1, A0-2

### Story 1.1: Kanonischen Workspace-Stamm erstellen

As a Nutzer/Compiler,
I want den kanonischen Workspace-Stamm mit `raw/`, `wiki/`, `schema/`, `adapters/` und einer OKF-Bundleroot (`wiki/index.md` mit `okf_version: "0.2"`) einzurichten,
So that Source Material (immutable Evidenz) physisch und semantisch getrennt vom kuratierten OKF-Knowledge Bundle liegt (FR-1, FR-2, AD-2, AD-3).

**Acceptance Criteria:**

**Given** ein leerer Git-repo-fähiger Projektordner, **When** der Workspace-Stamm initialisiert wird, **Then** existieren die Verzeichnisse `raw/`, `wiki/`, `schema/` und `adapters/` (AD-2, AD-10).
**Given** die Initialisierung, **When** `wiki/` angelegt wird, **Then** existiert eine Bundleroot `wiki/index.md` mit Frontmatter `okf_version: "0.2"` und `type: bundle` sowie eine leere `wiki/log.md` (AD-1, AD-9).
**Given** die Bundleroot, **When** ein Consumer oder Agent den Workspace scannt, **Then** unterscheiden sich `raw/` (Evidenz) und `wiki/` (kuratiertes Wissen) eindeutig über ihre Verzeichnisgrenzen (FR-2, AD-2).
**And** `schema/wiki-compiler.md` und `adapters/` (z.B. `adapters/claude/`) existieren als Platzhalter außerhalb des Bundles — nicht als Concept-Dateien (AD-1a, AD-10).

### Story 1.2: Sources lokal unter `raw/` bereitstellen

As a Nutzer,
I want eine oder mehrere lokale Sources (Dokumente, Spezifikationen, Projektartefakte) unter `raw/` zu materialisieren,
So that der Compiler sie in einem Compilation Run verarbeiten kann, ohne dass ich vorab über die Wiki-Struktur entscheiden muss (FR-1, AD-12, A-4).

**Acceptance Criteria:**

**Given** ein initialisierter Workspace, **When** ich eine einzelne Quelle unter `raw/` platziere, **Then** wird sie als immutable Source Material erkannt und nicht automatisch nach `wiki/` kopiert (FR-2, AD-3).
**Given** ein initialisierter Workspace, **When** ich mehrere Quellen (1..n) bereitstelle, **Then** akzeptiert der Compiler sie für einen Run als Eingabe.
**Given** eine bereits verarbeitete Source, **When** ein weiterer Compilation Run sie erneut verarbeitet, **Then** bleibt die Originaldatei unter `raw/` unverändert (AD-3).
**Given** der manuelle Source-Import (v1), **When** eine URL statt lokalen Materials angegeben wird, **Then** wird dies als nicht unterstützt zurückgewiesen (A-4: keine URL-Abrufe im MVP).

### Story 1.3: OKF-Schema-Vertrag `schema/wiki-compiler.md` autorisieren

As a Konsument des Schema-Vertrags,
I want mit `schema/wiki-compiler.md` verbindlich das erlaubte OKF-0.2-Feldsubset festzulegen,
So that alle Producer (Compiler/Adapter) validierbar, portabel und deterministisch dieselben Regeln anwenden (AD-1a, AD-1b, FR-9, NFR-6).

**Acceptance Criteria:**

**Given** der Schemadatei-Standort `schema/wiki-compiler.md`, **When** das Schema autorisiert wird, **Then** definiert es das OKF-Feldsubset (u.a. Liste-vs.-Map-Form von `sources`, Zulässigkeit von `generated`/`verified`, `status`-Policing) sowie Validitätsprädikate für Concepts und Bundle-Root.
**Given** das Schema, **When** ein Concept erzeugt wird, **Then** gilt `type` als einziges Pflichtfeld; optionale Felder (`sources`, `generated`, `verified`, `status`, `stale_after`) werden als Subset validiert (AD-1a).
**Given** das Schema, **When** ein neues Area-Verzeichnis in `wiki/` angelegt wird, **Then** bindet es die Index-Regel (`index.md` vorhanden) und die `log.md`-Typdefinition (AD-1a).
**And** das Schema bindet das Verbot: `sources`-Einträge lösen niemals auf `wiki/`-Concept-Pfade auf (AD-4b, A0-4).

### Story 1.4: Schema-Validierung für Bundle implementieren

As ein Compiler,
I want vor jeder Mutation das Bundle gegen `schema/wiki-compiler.md` zu validieren,
So that ein OKF-invalides Bundle nie als erfolgreicher Run gilt (F-2/AD-1b, A0-2, FR-9).

**Acceptance Criteria:**

**Given** ein Bundle mit struktureller OKF-Invalidität (z.B. fehlender `type`), **When** ein Compilation Run versucht zu mutieren, **Then** schlägt der Run fehl und meldet einen Validierungsfehler — kein erfolgreicher Run (F-2/AD-1b).
**Given** ein Bundle mit fehlenden optionalen Feldern (kein `sources`/`verified`), **When** ein Compilation Run läuft, **Then** gilt der Run nicht als invalide (F-2: strukturell-invalid, nicht bei fehlenden optionalen Feldern).
**Given** ein invalides Bundle, **When** ein Run fehlschlägt, **Then** bleibt `raw/` unverändert und die Fehlerursache ist textuell identifizierbar (AD-3, NFR-4).
**And** die Validierung ist als eigenständige, deterministische Prüfung ohne LLM-Urteil aufrufbar (AD-13/AD-17h-konform).

---

## Epic 2: OKF-Concepts erzeugen & verlinken

Aus den Sources entstehen eigenständige, OKF-0.2-konforme Concepts mit claim-granularer Provenienz und v1-Trust-Metadaten (`generated` ohne `verified`); Concepts werden über genau eine Markdown-Linkform (AD-7b) verlinkt, über deterministische Bereichszuordnung (AD-7c) in eine Bundle-Hierarchie eingeordnet und über `index.md` progressiv entdeckbar.
**FRs covered:** FR-3, FR-5, FR-9, FR-10, FR-11 · **NFRs:** NFR-2, NFR-3, NFR-7 · **AD/A0:** AD-1, AD-4, AD-4a, AD-4b, AD-4c, AD-7, AD-7a..7d, AD-8, AD-9, A0-3, A0-4, A0-5, A0-8, A0-9, A0-10, A0-20

### Story 2.1: Concepts aus Source Material erzeugen (OKF-Konform)

As a Nutzer,
I want dass der Compiler aus Source Material neue, eigenständige OKF-0.2-Concepts erzeugt,
So that neues kuratiertes Wissen entsteht, das nicht an die Struktur der Source gebunden ist (FR-5, FR-9, AD-5, AD-7).

**Acceptance Criteria:**

**Given** eine neue Source mit mehreren Abschnitten, **When** ein Compilation Run sie verarbeitet, **Then** erzeugt der Compiler eigenständige Concepts gemäß der erkannten Wissenseinheiten — nicht 1:1 pro Abschnitt, und nicht an die Source-Struktur gebunden (FR-5).
**Given** die Concept-Erzeugung, **When** ein Concept geschrieben wird, **Then** ist es OKF-0.2-konform: Markdown mit YAML-Frontmatter, `type` als verpflichtendes Feld (AD-1a, FR-9).
**Given** ein erzeugtes Concept, **When** dessen V1-Trust-Metadaten gesetzt werden, **Then** sind sie `generated: { by, at }` ohne `verified` (AD-15: v1-Default maschinell erzeugt und ungeprüft).
**And** mehrere Source-Abschnitte können in unterschiedliche Concepts einfließen (FR-5: keine Bindung an Source-Struktur).

### Story 2.2: Claim-granulare Provenienz dokumentieren

As a Nutzer/Compiler,
I want dass jede belegte Aussage in einem Concept einen Inline-Verweis auf `raw/`-Evidenz trägt,
So that die Herkunft des Wissens claim-granular nachvollziehbar bleibt (FR-3, AD-4a, A0-3).

**Acceptance Criteria:**

**Given** ein Concept mit fachlichen Aussagen, **When** es erzeugt wird, **Then** hat jede belegte Aussage einen Inline-Verweis auf `raw/`-Evidenz (AD-4a).
**Given** eine Kontext-/Synthese-Umformulierung, **When** sie in ein Concept übernommen wird, **Then** trägt sie einen expliziten Kontext-Marker ("übernommen aus <Concept-Pfad> auf Basis von <source>, nicht eigenständig belegt") (AD-4a, A0-3).
**Given** ein Concept mit mehreren Quellen, **When** deren `sources` dokumentiert werden, **Then** lösen diese ausschließlich auf `raw/`-Pfade oder externe immutable Evidenz auf — nie auf `wiki/`-Concept-Pfade (AD-4b, A0-4).
**And** ein generiertes Concept darf niemals ein anderes generiertes Concept als alleinige Provenienz führen (AD-4c, A0-5) — prüfbar über das Schema.

### Story 2.3: Concepts verlinken (eine erlaubte Linkform)

As a Consumer/Compiler,
I want Beziehungen zwischen Concepts mit normalen Markdown-Links auszudrücken — in genau einer erlaubten Form,
So that Concepts navigierbar bleiben und zwei Producer nie unterschiedliche IDs aus demselben Baum berechnen (FR-10, AD-7b, AD-8, A0-9).

**Acceptance Criteria:**

**Given** zwei zusammengehörige Concepts, **When** eine Beziehung ausgedrückt wird, **Then** nutzt sie einen normalen Markdown-Link in genau einer erlaubten Form: bundle-relativ, mit oder ohne Endung — nie beides (AD-7b, A0-9).
**Given** der Link-Form-Standard (unabhängig von Endungs-Wahl), **When** ein Consumer die Links traversiert, **Then** sind die Ziel-Concepts auffindbar (FR-10, AD-8).
**Given** ein Link, **When** er gespeichert wird, **Then** verändert er weder den Concept-Inhalt der Quelle noch das Knowledge-Modell (Links sind die Navigations-/Beziehungsschicht, nicht die Provenienz).
**And** keine proprietäre Link-Datenbank ist nötig; Konsumenten ohne Wiki-of-Wikis-Software können den Link verstehen (FR-10, AD-8).

### Story 2.4: Deterministische Bereichszuordnung & Concept-Hierarchie

As a Compiler,
I want neu erkannte Themen textual-deterministisch einem bestehenden Bereich (Area) oder einem neuen `index.md`-Bereich zuzuordnen,
So that die Concept-Identität eine stabile, kanonische Form hat und der Baum nicht vom Producer-Willkür abhängt (AD-7, AD-7a, AD-7c, A0-8, A0-10).

**Acceptance Criteria:**

**Given** ein erkanntes Thema, **When** der Bereich bestimmt wird, **Then** geschieht dies textual-deterministisch (bestehender `index.md`-Link oder Top-Level-Kollisions-Hold auf bestehende Pfade) — nicht per Embedding (A0-10, AD-13).
**Given** die Concept-Identität, **When** ein Concept abgelegt wird, **Then** entspricht sie dem relativen OKF-Pfad ohne `.md` (`wiki/spring/index.md` → `spring`) mit genau einer kanonischen ID-Normalisierung (AD-7a, A0-8).
**Given** eine Bereichsnavigation, **When** ein Consumer sich orientiert, **Then** führt die Hierarchie (Area-`index.md`) schrittweise zu den Concepts (AD-9, FR-11).
**And** ein Konflikt mit einem existierenden Top-Level-Pfad löst einen Kollisions-Hold aus, statt stillschweigend zu überschreiben (A0-10).

### Story 2.5: Progressive Discovery über `index.md` bereitstellen

As a Consumer/Compiler,
I want dass das Knowledge Bundle über `index.md`-Indexstrukturen progressiv entdeckbar ist,
So that ein Consumer relevantes Wissen schrittweise findet, ohne das gesamte Wiki lesen zu müssen (FR-11, AD-9, A0-10).

**Acceptance Criteria:**

**Given** ein Bundle mit mehreren Areas, **When** ein Consumer die Navigation startet, **Then** liest er zunächst die Bundle-Root `wiki/index.md` und dann relevante Area-`index.md` (AD-9).
**Given** die Hierarchie, **When** ein Concept neu angelegt wird, **Then** wird es passend in `index.md` des zugehörigen Bereichs verlinkt (AD-9, A0-10).
**Given** eine Suche (optional spätere Optimierung), **When** der Consumer sie nutzt, **Then** ist sie klar extern bzw. Consumer-seitig — die Discovery selbst braucht keine proprietäre Datenbank (AD-9, FR-11).
**And** das Bundle bleibt ohne geladene Indizes (z.B. nach Git-Clone) vollständig verständlich (NFR-2, NFR-5, AD-1).

---

## Epic 3: Inkrementelle Kompilation & Synthese

Der Nutzer verarbeitet neue Sources gegen das bestehende Wiki: bestehende Concepts werden erweitert, präzisiert oder korrigiert; mehrere Sources werden zu einer gemeinsamen Wissensrepräsentation synthetisiert; unverändertes Wissen bleibt erhalten. Relevanzbestimmung erfolgt textual-deterministisch (grep/ripgrep/Traversal, AD-13); Producer arbeiten mit atomarer Root-Scope-Lease, Dirty-Tree-Schutz und commit-gebundener Mutation. Klassifikationspflichtige Kollisionen enden bis Epic 4 fail-closed in einem strukturierten Hold; der Determinismus-Vertrag wird unabhängig und mechanisch qualifiziert.
**FRs covered:** FR-4, FR-6, FR-7, FR-12 · **NFRs:** NFR-7 · **AD/A0:** AD-5, AD-6, AD-13, AD-17a, AD-17b, AD-17c (Fail-closed-Sicherheitsgrenze), AD-17d..17f, AD-17h, A0-6, A0-7, A0-12, A0-13, A0-14 (No-Auto-Merge-Sicherheitsgrenze), A0-15, A0-16, A0-18, A0-19, A0-21 (Incrementality-Teil)
**Shared boundary:** Epic 3 verantwortet bei AD-17c/A0-14 ausschließlich Erkennung und fail-closed Erhaltung; Epic 4 verantwortet Klassifikation und semantische Auflösung. Bei A0-21 verantwortet Epic 3 die Erhaltung unabhängigen Wissens, Story 4.3 die spezifische Human-Curation-Semantik.

### Story 3.1: Inkrementellen Datenfluss implementieren (Interpret → Reconcile → Synthesize → Update)

As a Compiler,
I want neue Sources nur gegen die tatsächlich betroffenen Concepts zu verarbeiten,
So that unverändertes Wissen bewahrt bleibt und Wissen nicht bei jedem Lauf aus Rohquellen neu aufgebaut wird (FR-4, FR-12, AD-5, A0-6, SM-1, FT-6).

**Acceptance Criteria:**

**Given** ein bestehendes Bundle und neue Source Material, **When** ein Compilation Run startet, **Then** folgt er dem inkrementellen Datenfluss: Interpret → Reconcile → Synthesize → Update affected Concepts (AD-5, A0-6).
**Given** ein Run, **When** er einen bestehenden Concept-Pfad nicht betrifft, **Then** bleibt dessen Inhalt unverändert erhalten — keine Regeneration (FT-6, FR-12).
**Given** ein Lauf, **When** er abgeschlossen ist, **Then** konzentrieren sich die Git-Änderungen auf durch die neue Erkenntnis betroffene Concepts (AD-5, FR-6).
**And** der Run verwendet published/committed Inhalte als Input und niemals Zwischenstände während der Mutation (AD-17.2).

### Story 3.2: Relevanzbestimmung textual-deterministisch umsetzen (grep/ripgrep/Traversal)

As a Compiler,
I want relevante vorhandene Concepts zu einer neuen Source zu finden — mit grep/ripgrep, Markdown-Traversal und Link-Following,
So dass ohne Embedding-/Vector-Infrastruktur deterministisch bestimmt wird, welche Concepts zu prüfen sind (PRD OQ-3, AD-13, AD-17 Appendix, A0-18).

**Acceptance Criteria:**

**Given** eine neue Source, **When** der Run die Relevanzbestimmung durchführt, **Then** nutzt er ausschließlich textuelle, deterministische Verfahren (Term-übergreifende grep/ripgrep auf `wiki/`; Markdown-Traversal von `index.md`; Link-Following) (AD-13, A0-18).
**Given** gleiche Git-State + gleiche Eingabemenge, **When** zwei unabhängige Runs die Relevanzbestimmung ausführen, **Then** erzeugen sie dasselbe Ergebnis (Ad-17h-Determinsmus, A0-19).
**Given** ein Ergebnis der Relevanzbestimmung, **When** es in einem Run weiterverarbeitet wird, **Then** ist es als nachvollziehbare Candidate-Liste (Concept-Pfade) verfügbar — deterministisch statt probabilistisch.
**And** es findet kein Einsatz von Embeddings, Vektor-Suche oder Knowledge-Graph-Datenbank im Compiler-Kern statt (AD-13, No-Goals).

### Story 3.3: Bestehende Concepts erweitern/präzisieren/korrigieren

As a Compiler,
I want bestehende Concepts zu aktualisieren, ohne automatisch neue Dateien anzulegen,
So dass neues Wissen das vorhandene kuratierte Wissen ergänzt, präzisiert oder korrigiert (FR-6, AD-5).

**Acceptance Criteria:**

**Given** eine neue Erkenntnis zu einem bestehenden Concept, **When** der Run sie verarbeitet, **Then** erweitert er das bestehende Concept anstelle der Anlage einer neuen Datei (FR-6).
**Given** eine präzisierende Information, **When** sie eingearbeitet wird, **Then** wird der Text präzisiert oder korrigiert, ohne die Struktur zu zerstören.
**Given** eine Aktualisierung, **When** sie erfolgt, **Then** bleiben Beziehungen und Provenienz bestehender Concepts soweit weiterhin gültig erhalten (FR-6).
**And** die Mutation erfolgt nur innerhalb des geleasten Bereichs (AD-17.3).

### Story 3.4: Wissen aus mehreren Sources synthetisieren

As a Nutzer,
I want dass der Compiler Informationen aus mehreren Sources zu einer gemeinsamen Wissensrepräsentation zusammenführt,
So dass kein separates Summary pro Quelle entsteht und die gemischte Provenienz erhalten bleibt (FR-7, AD-4, AD-5).

**Acceptance Criteria:**

**Given** mehrere Sources zum selben Thema, **When** der Run synthetisiert, **Then** entsteht eine gemeinsame Wissensrepräsentation statt mehrerer getrennter Zusammenfassungen (FR-7).
**Given** eine Synthese aus mehreren Concepts/Sources, **When** das resultierende Concept erzeugt wird, **Then** übernimmt es relevante Source-Provenienz der beteiligten Sources (AD-4) — claim-granular mit Inline-Verweisen (A0-3).
**Given** redundante Informationen aus mehreren Sources, **When** sie synthetisiert werden, **Then** werden sie konsolidiert, ohne Provenienz zu verlieren (FR-7).
**And** das resultierende Concept reflektiert den erkannten Wissensstand — keine bloße Aneinanderreihung von Source-Zusammenfassungen (FR-7).

### Story 3.5: Leasing & Dirty-Tree-Schutz für konkurrierende Producer umsetzen

As a Producer/Compiler,
I want auf `lease/<area>/<id>`-Branches mit Root-Scope-Lease und Dirty-Tree-Schutz zu arbeiten,
So dass zwei Producer denselben Concept-Pfad nicht stillschweigend überschreiben und Fremdänderungen nie als Nebenwirkung gelöscht werden (AD-17a, AD-17b, AD-17e/f, A0-12, A0-13, A0-16; semantische Kollisionsauflösung in Epic 4).

**Acceptance Criteria:**

**Given** ein Producer, **When** er einen Bereich bearbeitet, **Then** arbeitet er auf einem `lease/<area>/<id>`-Branch und akquiriert die Lease gegen einen eindeutigen Commit-Object-Wert (Merge-Base-Disziplin) (AD-17a, A0-12).
**Given** eine Lease, **When** sie vergeben ist, **Then** umfasst sie die Root-Scope inklusive `log.md`, `index.md` und aller Root-Dateien (AD-17b, A0-13).
**Given** eine vorliegende uncommittete Fremdänderung im zu mutierenden Bereich, **When** der Producer mutieren will, **Then** schützt er sie (Stash/Scratch-Zone) und dokumentiert den Vorgang in `log.md` (AD-17e, A0-16).
**Given** zwei Branches mit ungleichen Änderungen am selben Concept-Pfad, **When** vor Epic 4 ein Merge versucht wird, **Then** erfolgt kein textueller Auto-Merge; der Run endet mit einem strukturierten Kollisions-Hold, der beide Commit-Hashes und den betroffenen Scope erhält. AD-16-Klassifikation und semantische Auflösung folgen in Epic 4 (Sicherheitsgrenze von AD-17c; vollständige Auflösung in Story 4.1/4.2).
**And** Mutationen operieren nur auf Directory-/Commit-Ebene — Commit-Boundary ist die Mutation-Boundary (AD-17f, A0-16).

### Story 3.6: Lease-Staleness & Recovery-Basis absichern

As a Consumer/Operator,
I want dass uncommittete Leases nach Run-Abbruch als stale gelten und `raw/` als Recovery-Basis dient,
So dass ein abgebrochener Run nie dauerhaft Wissen blockiert und die Evidenzbasis intakt bleibt (AD-17d, A0-15).

**Acceptance Criteria:**

**Given** ein abgebrochener Run, **When** uncommittete Leases hinterlassen wurden, **Then** gelten sie als stale (TTL plus Lease-Registrierung im Clone-Root-State) und blockieren keine nachfolgenden Runs (AD-17d, A0-15).
**Given** ein abgebrochener Run, **When** jeweilige uncommittete Änderungen wiederhergestellt werden sollen, **Then** dient `raw/` (immutable, AD-3) als Zugriffs- und Consistency-Basis (AD-17d, A0-15).
**Given** ein neuer Run, **When** er eine verwaiste Lease vorfindet, **Then** kann er die Lease übernehmen oder als stale markieren und protokollieren (AD-17d).
**And** `raw/` wird bei keinem dieser Vorgänge verändert (AD-3).

### Story 3.7: Reason/Mutate-Trennung und Konsistenz-Endzustand sicherstellen

As a Compiler,
I want Analyse, Änderungsplanung, Mutation und Validierung logisch zu trennen,
So dass ein teilweise fehlgeschlagener Run nie ein inkonsistentes Bundle hinterlässt (AD-6, A0-7).

**Acceptance Criteria:**

**Given** ein Run, **When** er Änderungen plant, **Then** erzeugt er zunächst eine konsistente Änderungsplanung (Analyse → Reconcile → Plan Changes → Mutate → Validate) (AD-6, A0-7).
**Given** ein Fehler während der Mutation, **When** der Run abbricht, **Then** bleibt der beobachtbare Endzustand des Bundles konsistent (AD-6).
**Given** ein Run, **When** er abgeschlossen ist, **Then** wurden alle geplanten Mutations-Validierungen erfolgreich durchlaufen (A0-7).
**And** die Architektur erfordert keine eigene Workflow Engine — die Trennung ist logisch, nicht zwingend als separate Prozesse umgesetzt (AD-6).

### Story 3.8: Determinismus-Vertrag (AD-17h) als Agent-Instruktions-Validator umsetzen

As a Compiler,
I want dass derselbe Git-State + dieselbe Eingabemenge bei zwei unabhängigen Runs denselben Bundle-State erzeugt,
So dass Relevanz-, Routing-, Planungs- und Mutationsentscheidungen reproduzierbar sind (AD-17h, FT-10, A0-19).

**Acceptance Criteria:**

**Given** einen Fixed Git-State und eine feste Eingabemenge, **When** zwei unabhängige Runs ausgeführt werden, **Then** produzieren sie identische Bundle-Zustände (FT-10, AD-17h).
**Given** eine Abweichung bei zwei solchen Runs, **When** sie festgestellt wird, **Then** wird sie als Determinismusfehler behandelt und der Run gilt als fehlgeschlagen — nicht als akzeptables Rauschen (AD-17h). *Präzisierung (Review-Loop-3, 2026-08-20): „Determinismusfehler" = **Fehler der AD-16-Klassifikation** (AD-16-Klassifikationsdefekt) im Sinne von §5.14 Pkt. 4 `schema/compiler.md` — der AC-Wortlaut „Determinismusfehler" bleibt erhalten; die Klassifikations-Verknüpfung (AD-16) war bei Story-Aufnahme nicht ausgeschrieben und wird hier nachgeführt, ohne den AC-Sinn zu ändern.*
**Given** der MVP (D-3), **When** der Agent-Instruktions-Validator ausgeführt wird, **Then** laufen die beiden Ausführungen in getrennten sauberen Worktrees und frischen Agent-Kontexten; eine zweite Ausführung in derselben Session genügt nicht (Q-6, A0-19).
**Given** das kanonische Eingabemanifest, **When** ein Run geplant wird, **Then** hält es Baseline-Commit, geordnete Source-Eingaben und jeden im Bundle sichtbaren Run-/Zeit-/Identitätswert explizit fest; der Run-Receipt enthält Candidate-Liste, Reihenfolge, Plan, Entscheidungen und Output-Hashes außerhalb des Knowledge Bundle.
**Given** der Zwei-Run-Nachweis, **When** Pläne und Bundle-State verglichen werden, **Then** dürfen weder erwartete Pläne noch Concept-Bodies im Test hart codiert werden; `verified`-Ereignisse werden niemals pauschal aus dem Vergleich maskiert.
**And** der Validator hält keine Embedding-/Vector-Infrastruktur vor (AD-13; FT-3, FT-4).

### Story 3.9: Deterministische Relevanz- und Reconcile-Routing schließen

As a Compiler,
I want Evidenz deterministisch bestehenden, neuen oder nicht klassifizierbaren Wissenseinheiten zuordnen,
So that keine relevante Information still ignoriert, dupliziert oder falsch verwaist wird (FR-4, FR-5-Interaktion, FR-6, FR-12, AD-5, AD-13, A0-6, A0-18).

**Acceptance Criteria:**

**Given** einen committeten Git-State und ein kanonisches Eingabemanifest, **When** Candidate-Terme gewonnen werden, **Then** folgt die Gewinnung einem geschlossenen, geordneten Algorithmus oder einem expliziten, persistierten Term-Manifest — keine freie Producer-Auswahl.
**Given** semantisch gleiche Schreibweisen mit Groß-/Kleinschreibung, Leerzeichen, Unterstrich, Bindestrich, En-Dash oder Em-Dash, **When** die Stufe-a-Suche läuft, **Then** werden Suchterm und Concept-Body identisch normalisiert und literal-sicher verglichen; `index.md`-Treffer bleiben für die Traversal-Stufe erhalten.
**Given** interpretierte Evidenz, **When** Reconcile abgeschlossen wird, **Then** gilt genau eine Routing-Tabelle: bestehender Match → `UPDATE`; eigenständige neue Wissenseinheit → `CREATE`; nicht klassifizierbare Evidenz → expliziter `ORPHAN/HOLD`; bereits vollständig repräsentierte identische Evidenz → `NO_OP`.
**Given** eine geänderte oder gelöschte bereits committete Datei unter `raw/`, **When** der Run seine Eingaben prüft, **Then** schlägt er vor jeder Mutation fehl; akzeptiert werden nur neu hinzugefügte oder separat versionierte Sources (AD-3).
**Given** ein neues Concept-Ziel, **When** dessen Slug `index` oder `log` beziehungsweise ein anderer reservierter Bundle-Name wäre, **Then** wird das Ziel nicht geschrieben und ein deterministischer Hold verlangt eine disambiguierte Identität.
**And** gleicher Git-State plus gleiches Eingabemanifest erzeugt dieselbe Candidate-Liste, Reihenfolge und Routing-Entscheidung (AD-17h, A0-19), belegt durch positive und negative ausführbare Fixtures.

### Story 3.10: Inkrementelle Update- und Synthese-Erhaltung absichern

As a Compiler,
I want bestehendes Wissen semantisch erweitern und mehrere Sources kohärent synthetisieren,
So that neues Wissen integriert wird, ohne gültiges vorhandenes Wissen oder Provenienz zu verlieren (FR-4, FR-6, FR-7, FR-12, AD-4, AD-5).

**Acceptance Criteria:**

**Given** eine passende neue Erkenntnis zu einem bestehenden Concept, **When** der Run sie verarbeitet, **Then** wird das bestehende Concept in-place erweitert oder präzisiert und kein thematisches Duplikat angelegt.
**Given** explizite aktuelle Evidenz, die eine bestehende Aussage eindeutig korrigiert, ohne dass zwischen weiterhin gültigen Sources ein Widerspruch verbleibt, **When** der Run sie verarbeitet, **Then** wird das bestehende Concept in-place korrigiert und die ersetzte Aussage samt Source-Basis bleibt im Run-Receipt nachvollziehbar; mehrdeutige Fälle gehen in den Hold für Epic 4.
**Given** ein betroffenes Concept mit weiterhin gültigen Aussagen und Provenienz, **When** es aktualisiert wird, **Then** bleiben diese geschützten Bestandteile erhalten; nicht betroffene Concepts bleiben byte-identisch.
**Given** eine neue Source, die eine bestehende Aussage unabhängig bestätigt, **When** synthetisiert wird, **Then** erscheint die Aussage genau einmal und trägt alle beitragenden Evidenzanker; die neue Source ist kein `NO_OP`.
**Given** mehrere Sources mit redundanten und ergänzenden Aussagen, **When** der Run synthetisiert, **Then** entsteht eine gemeinsame Wissensrepräsentation mit claim-granularer gemischter Provenienz — keine Source-A/Source-B-Aneinanderreihung.
**Given** eine bereits vollständig repräsentierte identische Source samt Evidenzanker, **When** sie erneut verarbeitet wird, **Then** ist der Run für dieses Wissen byte-erhaltend (`NO_OP`).
**Given** der Provenienz- und Link-Selbsttest, **When** erwartete Deltas bestimmt werden, **Then** stammen Baseline und Erwartung aus dem aktuellen Run; kein historischer, fest codierter Commit oder globaler Zählwert ist normativ.
**And** klassifikationspflichtige oder widersprüchliche Evidenz wird bis Epic 4 ohne Wissensmutation in einem benannten Hold erhalten; beide Evidenzpfade bleiben im Run-Receipt nachvollziehbar (NFR-7).

### Story 3.11: Root-Scope-Leasing atomar und worktree-übergreifend akquirieren

As a Producer,
I want pro kanonischem Scope genau eine atomare Lease erwerben,
So that verschiedene Run-IDs niemals gleichzeitig Schreibzugriff auf dasselbe Knowledge Bundle erhalten (AD-17a, AD-17b, A0-12, A0-13).

**Acceptance Criteria:**

**Given** den Root-Scope `wiki/`, **When** eine Lease akquiriert wird, **Then** existiert genau ein scope-bezogener Lock im clone-geteilten Zustand; die Run-ID ist Lock-Inhalt und nicht Teil des Exklusivitätsschlüssels.
**Given** zwei Producer mit verschiedenen IDs und Worktrees, **When** beide denselben Root-Scope akquirieren, **Then** ist die Akquise atomar und genau ein Producer erhält die Lease; der andere erhält `LEASE_HOLD`.
**Given** einen abgewiesenen Producer, **When** sein Lauf endet, **Then** verändert er weder `wiki/` noch den bestehenden Lock, erzeugt keinen Compilation Commit und entfernt keine fremde Lease.
**Given** einen realen Zwei-Worktree-/Zwei-Prozess-Test, **When** die Akquise zeitlich überlappt, **Then** beweisen Zwischenzustands-Assertions, dass niemals zwei aktive Root-Leases gleichzeitig existieren.
**And** ungleiche Änderungen am selben Concept-Pfad werden nicht automatisch gemerged, sondern als strukturierter Kollisions-Hold mit beiden Commit-Hashes an Epic 4 übergeben.

### Story 3.12: Lease-Lifecycle und Commit-Abschluss transaktional schließen

As an Operator,
I want Akquise, Dirty-Tree-Schutz, Mutation, Rollback und Freigabe als konsistenten Lifecycle ausführen,
So that SUCCESS und FAIL jeweils einen sauberen, wiederanlaufbaren Zustand hinterlassen (AD-6, AD-17d..17f, A0-7, A0-15, A0-16).

**Acceptance Criteria:**

**Given** einen lebenden Lease-Halter, **When** eine höhere Generation sichtbar wird, **Then** bleibt seine Lease aktiv; Staleness verlangt bestätigten Abbruch oder abgelaufene Liveness sowie atomare Ownership-Prüfung.
**Given** eine nachweislich stale Lease, **When** sie übernommen wird, **Then** gelingt die Übernahme genau einmal, nennt die ersetzte Holder-ID und hinterlässt genau eine aktive Root-Lease.
**Given** getrackte oder ungetrackte fremde Änderungen im Mutationsbereich, **When** der Preflight läuft, **Then** folgt er einer eindeutigen Abort-/Protect-Zustandsmaschine und stellt geschützte Bytes nach dem Run vollständig wieder her.
**Given** einen Fehler nach Mutation oder Staging, **When** Rollback läuft, **Then** restauriert er explizit aus dem bezeichneten Baseline-Commit sowohl Index als auch Worktree; der Post-Rollback-Diff gegen die Baseline ist leer.
**Given** einen erfolgreichen Run, **When** er freigegeben wird, **Then** sind Mutation, zulässiger Log-/Koordinationsnachweis und Release dauerhaft, der aktive Lock ist entfernt, der Worktree ist sauber und der unmittelbar folgende Run besteht den Clean-Input-Guard.
**Given** `wiki/log.md`, **When** ein Run protokolliert wird, **Then** enthält das kanonische Knowledge Log nur vertragskonforme fachliche Änderungen und notwendige Koordinationsereignisse; Build-, Review-, Story- und Sandbox-Historie liegt außerhalb des Knowledge Bundle.
**And** Kill-Point-Tests vor Mutation, nach Mutation, vor Commit und nach Commit beweisen den jeweils konsistenten Endzustand.

### Story 3.13: Epic-3-Verifikations- und Abnahmegate

As a Product Owner/Compiler-Verantwortlicher,
I want Epic 3 durch einen realen, reproduzierbaren Source→Compilation→Wiki-Lauf qualifizieren,
So that seine Fertigstellung durch ausführbare Evidenz statt handgeschriebene Simulationen belegt ist (SM-1, SM-2, FT-6, FT-10).

**Acceptance Criteria:**

**Given** einen sauberen Checkout, **When** das repositoryweite Epic-3-Gate ausgeführt wird, **Then** führt ein Kommando alle Epic-3-Szenarien fail-fast aus; fehlgeschlagene Assertions, übersprungene Szenarien, fehlende Abhängigkeiten und Kindprozessfehler ergeben einen Non-Zero-Exit.
**Given** macOS/BSD- und Linux/GNU-Userland, **When** das Gate dort läuft, **Then** ist es ohne plattformspezifisches `sed -i` reproduzierbar, arbeitet ausschließlich in temporären Repositories und hinterlässt `git status --porcelain` unverändert.
**Given** positive und negative OKF-Fixtures, **When** validiert wird, **Then** wird der vollständige Vertrag aus `schema/validator.md` über alle `wiki/`-Dateien ausgeführt; unter anderem fehlendes `generated.by`, kalenderinvalides `generated.at`, unzulässige Source-Pfade und gebrochene Index-Links verhindern SUCCESS und Commit.
**Given** der autorisierte Validator-Vertrag oder seine ausführbare Aufrufbarkeit weist dabei ein Defizit auf, **When** das Gate es erkennt, **Then** bleibt Story 3.13 offen und benennt den Bedarf für eine separat autorisierte Epic-1-Remediation; Story 3.13 darf die Schema-Semantik nicht still ändern, verantwortet aber die Integration und vollständige Ausführung des bestehenden Vertrags.
**Given** eine repräsentative committete Fixture, **When** ein frischer Agent-Kontext die kanonische Instruktion `schema/compiler.md` ausführt, **Then** darf der Harness nach dem Setup weder erwartete Wiki-Bodies noch Lease-, Log- oder Git-Ausgänge selbst schreiben.
**Given** diese Fixture, **When** der Compilation Run endet, **Then** demonstriert er Update eines bestehenden Concepts, Anlage einer neuen Wissenseinheit, kohärente Multi-Source-Synthese, vollständige Multi-Evidenz-Provenienz, Source-Immutabilität und byte-identische Erhaltung unabhängigen Wissens.
**Given** dasselbe kanonische Eingabemanifest, **When** zwei frische Agent-Kontexte in getrennt aufgebauten Worktrees laufen, **Then** stimmen Run-Receipts und Bundle-State gemäß Story 3.8 überein; eine perturbierte Entscheidung oder Ausgabe wird erkannt.
**Given** nur das erzeugte Knowledge Bundle ohne Planungsartefakte, **When** ein unabhängiger Consumer im Epic-5-Abhängigkeits-Smoke-Test vordefinierte Wissensfragen beantwortet, **Then** benötigt er weder Product Brief, SPEC, Architecture Spine noch Story-Historie zum semantischen Verständnis; solche Referenzen sind höchstens optionale Provenienz/Traceability. Dieser Smoke-Test nimmt die vollständige FR-15/FR-16-Abnahme aus Epic 5 nicht vorweg.
**And** erst nach bestandenem Gate und `done`-Status aller Stories 3.8 bis 3.13 wird Epic 3 auf `done` gesetzt; bis dahin bleibt Epic 3 `in-progress`.

---

## Epic 4: Wissenstreue — Widersprüche & menschliche Kuratierung

Widersprüche werden nie stillschweigend zur scheinbar eindeutigen Aussage zusammengeführt; relevante Disagreements bleiben als explizite Einträge in `log.md` erhalten; menschlich kuratierte Inhalte werden als bestehendes Wissen respektiert und bleiben über OKF-Trust-Metadaten (`verified: human:...`) von ungeprüftem maschinellem Output unterscheidbar; unvollständiges/ungeprüftes Wissen wird ohne künstliche Gewissheit dargestellt.
Epic 4 beginnt nach bestandenem Story-3.13-Abnahmegate und übernimmt die in Epic 3 fail-closed erhaltenen Kollisions-/Widerspruchs-Holds zur semantischen Klassifikation und Auflösung.
**FRs covered:** FR-8, FR-13 · **NFRs:** NFR-7 · **AD/A0:** AD-16, AD-16a, AD-16b, AD-15, AD-17c, AD-17g, A0-11, A0-14, A0-17, A0-20, A0-21

### Story 4.1: Information vor jeder Änderung klassifizieren (NEW/CONFIRMING/CORRECTING/CONTRADICTING/REDUNDANT)

As a Compiler,
I want neue Informationen vor jeder Änderung gemäß AD-16 zu klassifizieren,
So dass Widersprüche nie stillschweigend aufgelöst werden und die Klassifikation deterministisch ist (FR-8, AD-16, AD-16a, A0-11).

**Acceptance Criteria:**

**Given** eine neue Information, **When** der Run sie verarbeitet, **Then** klassifiziert er sie als NEW / CONFIRMING / CORRECTING / CONTRADICTING / REDUNDANT (AD-16).
**Given** ein Widerspruch ohne explizite Ersetzungsevidenz, **When** er klassifiziert wird, **Then** ist der Default Erhaltung (CONTRADICTING), nicht stille Auflösung (AD-16a, A0-11).
**Given** eine Korrektur mit expliziter Ersetzungsevidenz, **When** sie klassifiziert wird, **Then** wird sie als CORRECTING mit dokumentierter Ersetzungslogik behandelt, nicht als CONTRADICTING (AD-16a).
**And** die Klassifikation ist deterministisch und über denselben Git-State reproduzierbar (AD-16a, AD-17h).

### Story 4.2: Disagreements in `log.md` explizit dokumentieren

As a Consumer/Compiler,
I want dass relevante Widersprüche als explizite Disagreements in `log.md` verbleiben — verknüpft mit dem mutierten Concept-Pfad,
So dass Konflikte sichtbar, nachvollziehbar und auditierbar bleiben (FR-8, AD-16b, A0-11).

**Acceptance Criteria:**

**Given** ein Konflikt, **When** der Run ihn feststellt, **Then** wird er als `log.md`-Eintrag dokumentiert, der mit dem betroffenen Concept-Pfad verknüpft ist (AD-16b, A0-11).
**Given** ein `log.md`-Eintrag, **When** er gespeichert wird, **Then** enthält er Klassifikation samt Begründung sowie die zugehörigen Sources (AD-16b, A0-11).
**Given** ein widersprüchliches Concept, **When** es gelesen wird, **Then** bleiben die betroffenen Aussagen und ihre Sources nachvollziehbar; Unsicherheit kann explizit Teil des Concepts sein (FR-8, AD-16).
**And** `log.md` ist selbst Bestandteil der Lease-Root-Scope (AD-17b, A0-13).

### Story 4.3: Menschliche Kuratierung respektieren (Human Curation)

As a Nutzer/Compiler,
I want manuell gepflegte Inhalte als bestehendes Wissen zu behandeln und nicht ohne Provenienz aus dem aktuellen Run zu entfernen,
So dass menschliche Kuratierung überlebt und nur bei echtem Widerspruch mit neuer Evidenz zurücktritt (FR-13, AD-15, A0-21, FT-9).

**Acceptance Criteria:**

**Given** ein manuell kuratiertes Concept ohne Provenienz aus dem aktuellen Run, **When** ein Run es trifft, **Then** wird es nicht entfernt — menschliche Inhalte sind persistentes Wissen (FR-13, AD-15).
**Given** ein Konflikt zwischen menschlicher Kuratierung und neuer Source, **When** er auftritt, **Then** wird er sichtbar (z.B. `log.md`-Eintrag gemäß AD-16), statt stillschweigend überschrieben zu werden (FR-13, AD-16).
**Given** eine menschliche Korrektur eines maschinell erzeugten Concepts, **When** sie erfolgt, **Then** überlebt sie als normale Kuratierung (Datei-Edit + Git), solange sie nicht durch neue Evidenz widerlegt wird (FT-9, A0-21).
**And** die Korrektur erfordert keine Re-Kompilation des ganzen Bundles (FT-9).

### Story 4.4: Trust-Metadaten: maschinell vs. human-reviewed unterscheiden

As a Consumer/Compiler,
I want maschinell erzeugtes (ungeprüftes) von human-reviewed Wissen über OKF-Trust-Metadaten zu unterscheiden,
So dass Leser die Vertrauenswürdigkeit einer Quelle erkennen können, ohne künstliche Gewissheit zu erzeugen (AD-15, A0-20, NFR-7, FR-13).

**Acceptance Criteria:**

**Given** ein maschinell erzeugtes Concept, **When** erzeugt wird, **Then** hat es `generated: { by, at }` und kein `verified` (AD-15, A0-20: v1-Default).
**Given** ein human-reviewed Concept, **When** es reviewt wird, **Then** setzt ein Mensch `verified` mit `human:`-Präfix-Actor (AD-15, A0-20).
**Given** ein Concept mit Lifecycle, **When** es gepflegt wird, **Then** nutzt es `status` (`draft` | `stable` | `deprecated`) und optional `stale_after` (AD-15).
**And** das Verhalten bleibt für alle Consumer agent-unabhängig und in Rein-Markdown lesbar (NFR-2, NFR-3, NFR-7).

---

## Epic 5: Consumer-Zugriff & Nachvollziehbarkeit

Menschen und beliebige LLM-Agenten (BMAD, Claude Code, Codex, ...) lesen das Knowledge Bundle ohne Wiki-of-Wikis-spezifische Runtime; Änderungen sind über Git-Diffs nachvollziehbar; die kanonischen Compiler-Regeln sind agent-unabhängig mit dünnen Adaptern; es gibt keinen obligatorischen Server, keine Datenbank und keine proprietäre Abhängigkeit.
**FRs covered:** FR-14, FR-15, FR-16 · **NFRs:** NFR-1, NFR-3, NFR-5, NFR-6 · **AD/A0:** AD-10, AD-11, AD-13, AD-14, A0-21, A0-22

### Story 5.1: Git-nachvollziehbare Änderungen & Konsistenz (Commit-Boundary)

As a Consumer,
I want dass Concept-Änderungen über normale Versionskontrolle nachvollziehbar sind,
So dass Git-Diffs fachlich relevante Veränderungen sichtbar machen und kein proprietäres Change-Tracking nötig ist (FR-14, AD-14, A0-21).

**Acceptance Criteria:**

**Given** eine Mutation eines Concepts, **When** sie committet wird, **Then** ist sie über einen normalen Git-Diff textuell nachvollziehbar (FR-14, AD-14).
**Given** eine Änderung, **When** sie erstellt wird, **Then** verbleibt fachliche Provenienz im OKF Concept — nicht ausschließlich aus Git-Historie abgeleitet (AD-14).
**Given** eine übernommene Fremdänderung (aus Dirty-Tree-Schutz, AD-17e), **When** sie in einem Commit auftaucht, **Then** ist sie in `log.md` dokumentiert und keine uncommittete Fremdänderung wurde gelöscht (AD-17e/f).
**And** Änderungen erfolgen textuell und als normale Dateiänderungen (NFR-4).

### Story 5.2: Tool-unabhängigen Zugriff und Agent-Lesbarkeit gewährleisten

As a Nutzer/Agent,
I want das Knowledge Bundle ohne Wiki-of-Wikis-spezifische Runtime zu lesen,
So dass Menschen normale Markdown-Werkzeuge und LLM-Agenten Standard-Dateioperationen nutzen können (FR-15, NFR-2, NFR-3, NFR-5).

**Acceptance Criteria:**

**Given** ein Knowledge Bundle, **When** ein Mensch es liest, **Then** nutzt er gewöhnliche Markdown-Werkzeuge ohne spezielle Software (FR-15, NFR-2).
**Given** ein Knowledge Bundle, **When** ein LLM-Agent es erschließt, **Then** genügen Standard-Dateioperationen (Lesen/Grep/Traversal) — kein proprietäres SDK (FR-15, NFR-3).
**Given** ein Bundle ohne Server/Datenbank/Prozess, **When** es gelesen wird, **Then** bleibt es vollständig verständlich (NFR-5).
**And** das Bundle (inkl. `wiki/` nach Git-Clone auf andere Maschine) bleibt portabel lesbar (NFR-1, FT-7).

### Story 5.3: Agent-unabhängige Compiler-Regeln & dünne Adapter

As a Consumer/Operator,
I want dass die Compiler-Regeln agent-unabhängig bleiben und Provider-Instruktionen als dünne Adapter ausgeführt werden,
So dass BMAD, Claude Code, Codex und zukünftige Agenten ohne Knowledge-Modell-Migration wechseln können (FR-16, AD-10, A0-22).

**Acceptance Criteria:**

**Given** die kanonischen Compiler-Regeln, **When** ein Provider-Adapter erstellt wird, **Then** beschreibt er nur spezifische Instruktionen, definiert aber keine abweichende Knowledge-Semantik (AD-10, A0-22).
**Given** ein Adapter-Wechsel (z.B. Claude Code → Codex), **When** er erfolgt, **Then** ist keine Migration des Knowledge Bundle nötig (FR-16, A0-22, FT-2).
**Given** ein optionales Retrieval, **When** ein Consumer es einsetzt, **Then** ist es Consumer-Verhalten (grep/BM25/Vector etc.), das das kanonische Datenmodell nicht verändert (AD-13, FT-3).
**And** die Kompilierung produziert weiterhin ein rein markdown-basiertes Bundle, unabhängig vom Agenten (FR-16, NFR-6).