diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..8eeba29 --- /dev/null +++ b/.gitignore @@ -0,0 +1,6 @@ +# IDE state +.idea/ + +# OS cruft +.DS_Store +Thumbs.db diff --git a/README.md b/README.md new file mode 100644 index 0000000..119c6d5 --- /dev/null +++ b/README.md @@ -0,0 +1,19 @@ +# Wiki of Wikis — Wissens-Workspace + +Ein agent-nativer, dateibasierter Knowledge Compiler (AD-2, AD-10). Der Workspace trennt Source Material physisch und semantisch vom kuratierten OKF-Knowledge Bundle. + +## Struktur + +```text +raw/ immutable Source Material (Evidenz) +wiki/ kuratiertes OKF-Knowledge Bundle (Bundleroot: wiki/index.md) +schema/ Compiler-Schema-Vertrag (schema/wiki-compiler.md) +adapters/ dünne agenten-spezifische Adapter (z.B. adapters/claude/) +``` + +- **`raw/`** — Evidenz. Bediener zu AD-2/AD-3: immutable, niemals durch einen Compilation Run verändert. +- **`wiki/`** — kanonisches kuratiertes Wissen als OKF-0.2-Bundle. Einstieg: `wiki/index.md`. +- **`schema/`** — verbindlicher OKF-Feldsubset-Vertrag, außerhalb des Bundles (AD-1). +- **`adapters/`** — dünne Adapter, die keine abweichende Knowledge-Semantik definieren (AD-10). + +Vgl. Architektur-Spine unter `_bmad-output/planning-artifacts/architecture/`. diff --git a/_bmad-output/implementation-artifacts/epic-1-context.md b/_bmad-output/implementation-artifacts/epic-1-context.md new file mode 100644 index 0000000..2a8aa69 --- /dev/null +++ b/_bmad-output/implementation-artifacts/epic-1-context.md @@ -0,0 +1,39 @@ +# Epic 1 Context: Wissens-Workspace & Quellen-Aufnahme + + + +## Goal + +Der Nutzer richtet den kanonischen, Git-versionierten Wissens-Workspace ein und stellt dem Compiler Sources bereit. Der Workspace zerlegt die vier Verantwortungsbereiche physisch und semantisch: `raw/` (immutable Source Material / Evidenz), `wiki/` (kuratiertes OKF-Knowledge Bundle), `schema/` (verbindlicher OKF-Schema-Vertrag) und `adapters/` (dünne agenten-spezifische Instruktionen, außerhalb des Bundles). Eine Datei unter `raw/` ist Evidenz, eine Datei unter `wiki/` ist abgeleitete Wissensrepräsentation — das bloße Kopieren eines Quell-Dokuments zählt nicht als Wissensintegration. Am Ende entsteht eine validierte Basis, in der jeder Compilation Run den kompletten Workspace inkrementell weiterentwickeln kann (AD-2, AD-3, AD-12, AD-1a, AD-1b). + +## Stories + +- Story 1.1: Kanonischen Workspace-Stamm erstellen +- Story 1.2: Sources lokal unter `raw/` bereitstellen +- Story 1.3: OKF-Schema-Vertrag `schema/wiki-compiler.md` autorisieren +- Story 1.4: Schema-Validierung für Bundle implementieren + +## Requirements & Constraints + +- Der Nutzer kann eine oder mehrere Sources (1..n) bereitstellen, ohne vorab die Wiki-Struktur entscheiden zu müssen; v1 akzeptiert nur lokal materialisiertes Source Material — URL-Abrufe werden als nicht unterstützt zurückgewiesen (FR-1, A-4). +- Die Phasen "bereitgestelltes Source Material" und "Curated Knowledge" sind eindeutig unterscheidbar; ein Quell-Dokument wird nie automatisch zum Concept und eine Kopie unter `wiki/` ist keine erfolgreiche Kompilation (FR-2). +- Ein Compilation Run verändert bestehendes Source Material niemals — `raw/` bleibt immutable; neue Source-Versionen sind neue/versionierte Sources (AD-3). Ein fehlgeschlagener Run lässt `raw/` unangetastet. +- Der Workspace ist als normale Git-Working-Copy portabel: nach `git clone` liegt `raw/` + `wiki/` + Compiler-Vertrag bereit, kein Server und keine Datenbank erforderlich (NFR-1, NFR-5). Mutiert wird textuell, damit Git-Diffs fachlich aussagekräftig bleiben (NFR-4, AD-14). +- Das Lesen/Bearbeiten des Bundles setzt generell keine Wiki-of-Wikis-Runtime voraus — Standard-Markdown-Werkzeuge und Dateioperationen genügen (FR-15, NFR-2, NFR-3). +- Es gibt keine GUI in v1: der gesamte Workflow ist datei-/CLI-basiert (A-3). + +## Technical Decisions + +- **Struktur (Seed):** `raw/` (inkl. optionalem `assets/`), `wiki/`, `schema/wiki-compiler.md`, `adapters//`. Nur `wiki/` ist Bundleroot des OKF Bundles; `raw/`, `schema/`, `adapters/` liegen außerhalb des Bundles und sind keine Concept-Dateien (AD-2, AD-10). +- **Bundle und Fundament:** Bundleroot `wiki/index.md` mit Frontmatter `type: bundle` und `okf_version: "0.2"`; leere Protokolldatei `wiki/log.md`. Area-Verzeichnisse innerhalb von `wiki/` folgen dem Muster `/index.md` + `.md` (AD-1, AD-9). +- **Schema-Vertrag (AD-1a, A0-1):** `schema/wiki-compiler.md` bindet verbindlich das erlaubte OKF-0.2-Feldsubset — `type` als einziges Pflichtfeld; optional `sources`, `generated`, `verified`, `status`, `stale_after`; festgelegt werden Liste-vs.-Map-Form von `sources`, Zulässigkeit von `generated`/`verified` und `status`-Policing — dazu die Typdefinition von `log.md`, die Index-Regel (jedes Area hat eine `index.md`) und Validitätsprädikate für Concepts und Bundle-Root. +- **Provenienz-Grenze (AD-4b, A0-4):** `sources`-Einträge lösen ausschließlich auf `raw/`-Pfade oder extern referenzierte immutable Evidenz auf — nie auf `wiki/`-Concept-Pfade; das Schema bindet dieses Verbot. +- **Validierung (F-2/AD-1b, A0-2):** Vor jeder Mutation wird das Bundle gegen `schema/wiki-compiler.md` geprüft; ein strukturell OKF-invalides Bundle (z.B. fehlender `type`) schlägt den gesamten Run fehl, fehlende optionale Felder gelten nicht als invalide. Die Validierung ist eine eigenständige, deterministische, ohne LLM-Urteil aufrufbare Prüfung (AD-13/AD-17h-konform). +- **Kein eigener OKF-Dialekt / kein eigenes Schema neben OKF (AD-1);** `adapters/` dürfen keine abweichende Knowledge-Semantik definieren, nur agenten-spezifische Ausführung (AD-10). + +## Cross-Story Dependencies + +- Alle späteren Epics (Concept-Erzeugung, Kompilation, Wissenstreue, Consumer-Zugriff) setzen die hier etablierte Workspace-Trennung, die Bundle-Root und den Schema-Vertrag voraus. +- Der Schema-Vertrag aus Story 1.3 ist die Eingabe für die Validierung in Story 1.4 und definiert zugleich die Feld-Subset-Basis, auf der Epic 2 OKF-konforme Concepts produziert. +- Die Immutability von `raw/` (Story 1.2) ist die Recovery-Basis für Leasing-/Stale-Szenarien späterer Epics (AD-17d). +- Keine UX/Design-Anteile relevant für diesen Epic: v1 ist datei-/CLI-basiert ohne GUI (A-3, AD-11). diff --git a/_bmad-output/implementation-artifacts/spec-1-1-kanonischen-workspace-stamm-erstellen.md b/_bmad-output/implementation-artifacts/spec-1-1-kanonischen-workspace-stamm-erstellen.md new file mode 100644 index 0000000..96c0753 --- /dev/null +++ b/_bmad-output/implementation-artifacts/spec-1-1-kanonischen-workspace-stamm-erstellen.md @@ -0,0 +1,43 @@ +--- +title: 'Kanonischen Workspace-Stamm erstellen (Story 1.1)' +type: 'feature' +created: '2026-08-14' +status: 'done' +route: 'one-shot' +review_loop_iteration: 0 +context: + - _bmad-output/implementation-artifacts/epic-1-context.md +--- + +## Intent + +**Problem:** Das Projekt besitzt noch keinen kanonischen Wissens-Workspace; Source Material und kuratiertes Knowledge Bundle sind nicht physisch/semantisch getrennt. + +**Approach:** Den Workspace-Stamm `raw/ | wiki/ | schema/ | adapters/` als Git-versionierte Seed anlegen, mit OKF-Bundleroot `wiki/index.md` (`type: bundle`, `okf_version: "0.2"`), leerem `wiki/log.md` und Platzhaltern für Schema-Vertrag und Adapter. + +## Suggested Review Order + +**Workspace-Trennung & Einstieg** + +- Bundleroot mit `okf_version: "0.2"` und Frontmatter-Regel — Einstiegspunkt der Discovery + [`index.md`](../../wiki/index.md#L1) + +- OPF-README: Area, Platzhalter mit Verweis auf Story 1.3 + [`wiki-compiler.md`](../../schema/wiki-compiler.md#L1) + +- Dünne-Adapter-Konvention (AD-10), Multi-Adapter-Layout dokumentiert + [`README.md`](../../adapters/README.md#L1) + +- Claude-Adapter-Platzhalter (Story 5.3 hält den Rest) + [`README.md`](../../adapters/claude/README.md#L1) + +- Immutability & Evidenz-Grenze von `raw/` inkl. Artefakt-Carve-out + [`README.md`](../../raw/README.md#L1) + +**Peripherie** + +- Root-Orientierung über alle vier Verzeichnisse + [`README.md`](../../README.md#L1) + +- IDE-/OS-Ignore-Regeln + [`.gitignore`](../../.gitignore#L1) diff --git a/_bmad-output/implementation-artifacts/sprint-status.yaml b/_bmad-output/implementation-artifacts/sprint-status.yaml new file mode 100644 index 0000000..bd4c6a3 --- /dev/null +++ b/_bmad-output/implementation-artifacts/sprint-status.yaml @@ -0,0 +1,75 @@ +# STATUS DEFINITIONS: +# ================== +# Epic Status: +# - backlog: Epic not yet started +# - in-progress: Epic actively being worked on +# - done: All stories in epic completed + +# Story Status: +# - backlog: Story only exists in epic file +# - ready-for-dev: Story file created, ready for development +# - in-progress: Developer actively working on implementation +# - review: Implementation complete, ready for review +# - done: Story completed + +# Retrospective Status: +# - optional: Can be completed but not required +# - done: Retrospective has been completed + +# Action Item Status: +# - open: Committed during a retrospective, not yet addressed +# - in-progress: Actively being worked on +# - done: Completed + +# WORKFLOW NOTES: +# =============== +# - Epic transitions to 'in-progress' automatically when its first story starts (via build's sprint sync) +# - Stories can be worked in parallel if team capacity allows +# - Developer typically creates the next story after the previous one is 'done' to incorporate learnings +# - Dev moves story to 'review', then runs code-review (fresh context, different LLM recommended) +# - Retrospective appends its action items to action_items; the status view surfaces open ones +generated: 08-14-2026 00:00 +last_updated: 08-14-2026 19:42 +project: wow20 +project_key: NOKEY +tracking_system: file-system +story_location: D:/mita/wow-2nd/_bmad-output/implementation-artifacts +development_status: + epic-1: in-progress + 1-1-kanonischen-workspace-stamm-erstellen: review + 1-2-sources-lokal-unter-raw-bereitstellen: backlog + 1-3-okf-schema-vertrag-schema-wiki-compiler-md-autorisieren: backlog + 1-4-schema-validierung-für-bundle-implementieren: backlog + epic-1-retrospective: optional + + epic-2: backlog + 2-1-concepts-aus-source-material-erzeugen-okf-konform: backlog + 2-2-claim-granulare-provenienz-dokumentieren: backlog + 2-3-concepts-verlinken-eine-erlaubte-linkform: backlog + 2-4-deterministische-bereichszuordnung-concept-hierarchie: backlog + 2-5-progressive-discovery-über-index-md-bereitstellen: backlog + epic-2-retrospective: optional + + epic-3: backlog + 3-1-inkrementellen-datenfluss-implementieren-interpret-reconcile: backlog + 3-2-relevanzbestimmung-textual-deterministisch-umsetzen-grep-rip: backlog + 3-3-bestehende-concepts-erweitern-präzisieren-korrigieren: backlog + 3-4-wissen-aus-mehreren-sources-synthetisieren: backlog + 3-5-leasing-dirty-tree-schutz-für-konkurrierende-producer-umsetz: backlog + 3-6-lease-staleness-recovery-basis-absichern: backlog + 3-7-reason-mutate-trennung-und-konsistenz-endzustand-sicherstell: backlog + 3-8-determinismus-vertrag-ad-17h-als-agent-instruktions-validato: backlog + epic-3-retrospective: optional + + epic-4: backlog + 4-1-information-vor-jeder-änderung-klassifizieren-new-confirming: backlog + 4-2-disagreements-in-log-md-explizit-dokumentieren: backlog + 4-3-menschliche-kuratierung-respektieren-human-curation: backlog + 4-4-trust-metadaten-maschinell-vs-human-reviewed-unterscheiden: backlog + epic-4-retrospective: optional + + epic-5: backlog + 5-1-git-nachvollziehbare-änderungen-konsistenz-commit-boundary: backlog + 5-2-tool-unabhängigen-zugriff-und-agent-lesbarkeit-gewährleisten: backlog + 5-3-agent-unabhängige-compiler-regeln-dünne-adapter: backlog + epic-5-retrospective: optional diff --git a/_bmad-output/planning-artifacts/epics.md b/_bmad-output/planning-artifacts/epics.md new file mode 100644 index 0000000..ae56b28 --- /dev/null +++ b/_bmad-output/planning-artifacts/epics.md @@ -0,0 +1,471 @@ +--- +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 auf Basis von , 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//`-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 auf `lease//`-Branches mit Dirty-Tree-Schutz, Root-Scope-Lease und commit-gebundener Mutation (AD-17a..h). +**FRs covered:** FR-4, FR-6, FR-7, FR-12 +**NFRs covered:** NFR-7 +**AD/A0:** AD-5, AD-6, AD-13, AD-17, AD-17a..17h, A0-6, A0-7, A0-12..A0-18, A0-19, A0-21 + +### 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, A0-11, A0-17, A0-20 + +### 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 auf Basis von , 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 auf `lease//`-Branches mit Dirty-Tree-Schutz, Root-Scope-Lease und commit-gebundener Mutation (AD-17a..h). +**FRs covered:** FR-4, FR-6, FR-7, FR-12 · **NFRs:** NFR-7 · **AD/A0:** AD-5, AD-6, AD-13, AD-17, AD-17a..17h, A0-6, A0-7, A0-12..A0-18, A0-19, A0-21 + +### 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//`-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-17, AD-17a..f, A0-12..A0-16). + +**Acceptance Criteria:** + +**Given** ein Producer, **When** er einen Bereich bearbeitet, **Then** arbeitet er auf einem `lease//`-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 Änderungen am selben Concept-Pfad, **When** gemerged werden soll, **Then** erfolgt kein stiller textueller Auto-Merge (AD-17c, A0-14) — Auflösung compiler-vermittelt über AD-16 mit explizitem `log.md`-Eintrag. +**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 die AD-16-Klassifikation deterministisch genug ist (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 Fehler im AD-16-Klassifikations-Mechanismus behandelt (nicht als akzeptables Rauschen) (AD-17h). +**Given** der MVP (D-3), **When** die Determinsmus-Enforcement fehlt, **Then** lebt sie als Agent-Instruktions-Validator und ist vor Last tragenden Anspruch als mechanisch bestätigt (Q-6, A0-19). +**And** der Validator hält keine Embedding-/Vector-Infrastruktur vor (AD-13; FT-3, FT-4). + +--- + +## 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:** NFR-7 · **AD/A0:** AD-16, AD-16a, AD-16b, AD-15, A0-11, A0-17, A0-20 + +### 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). diff --git a/adapters/README.md b/adapters/README.md new file mode 100644 index 0000000..fda0f8e --- /dev/null +++ b/adapters/README.md @@ -0,0 +1,13 @@ +# adapters/ — Dünne Agenten-Adapter + +Provider- bzw. agentenspezifische Instruktionen. Die kanonischen Compiler-Regeln werden **agent-unabhängig** beschrieben (AD-10, A0-22) und leben im Schema-Vertrag `schema/wiki-compiler.md`. + +Ein Adapter: + +- beschreibt ausschließlich agenten-spezifische Ausführung; +- definiert **keine** abweichende Knowledge-Semantik; +- erfordert beim Adapter-Wechsel keine Migration des Knowledge Bundles (FR-16). + +Erwartete Layout: ein Verzeichnis pro Agent, z.B. `claude/`, `codex/` … Weitere Adapter werden in Story 5.3 ergänzt. + +`adapters/` liegt **außerhalb** des Bundles (`wiki/`) und enthält keine Concept-Dateien (Structural Seed, AD-1). diff --git a/adapters/claude/README.md b/adapters/claude/README.md new file mode 100644 index 0000000..8b5107f --- /dev/null +++ b/adapters/claude/README.md @@ -0,0 +1,7 @@ +# adapters/claude/ — Claude-Adapter (Platzhalter) + +> **Status:** Platzhalter. Zuständig ist die Story 5.3 «Agent-unabhängige Compiler-Regeln & dünne Adapter» (AD-10, A0-22). + +Dünner Adapter für den Claude-Code-Agenten. Kanonische Compiler-Regeln werden agent-unabhängig beschrieben; Provider-Instruktionen sind **dünne Adapter**, die keine abweichende Knowledge-Semantik definieren (AD-10). + +`adapters/` liegt **außerhalb** des Bundles (`wiki/`) und enthält keine Concept-Dateien (Structural Seed, AD-1). diff --git a/raw/README.md b/raw/README.md new file mode 100644 index 0000000..ce2d51d --- /dev/null +++ b/raw/README.md @@ -0,0 +1,13 @@ +# raw/ — Source Material (immutable Evidenz) + +Dieses Verzeichnis ist die Architekturgrenze für **Source Material** (AD-2, AD-3, AD-12). + +- Eine Datei unter `raw/` ist **Evidenz**. +- `raw/` ist **immutable**: Ein Compilation Run verändert bestehendes Source Material niemals (AD-3). +- Neue Versionen einer Source werden als neue bzw. versionierte Source behandelt. +- Quellen werden hier **lokal** materialisiert; URL-Abrufe sind im MVP nicht unterstützt (A-4). + +Unterverzeichnisse (z.B. `assets/`) können je nach Quelle ergänzt werden. Die Quelle selbst wird nie automatisch nach `wiki/` kopiert — das Kopieren eines Quell-Dokuments ist keine Wissensintegration (FR-2). + +> Diese README-Datei ist ein **Grenz-/Artefakt-Datei** (Orientierung), keine Evidenz; sie markiert die Grenze, ist selbst aber kein zu verarbeitendes Source Material. + diff --git a/raw/assets/.gitkeep b/raw/assets/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/schema/wiki-compiler.md b/schema/wiki-compiler.md new file mode 100644 index 0000000..c97ca06 --- /dev/null +++ b/schema/wiki-compiler.md @@ -0,0 +1,15 @@ +# Wiki of Wikis — Compiler-Schema-Vertrag (Platzhalter) + +> **Status:** Platzhalter (Story 1.3 «OKF-Schema-Vertrag autorisieren» füllt diesen Vertrag aus und **autorisiert** die folgenden Entscheidungen). Dieser Liste ist eine offene Entscheidungsvorlage, keine normative Festlegung. + +Hier wird der **verbindliche OKF-0.2-Feldsubset-Vertrag** (AD-1a, A0-1) verankert, den Story 1.3 autorisiert. Zu entscheiden sind: + +- erlaubtes OKF-0.2-Feldsubset — `type` als einziges Pflichtfeld; optional `sources`, `generated`, `verified`, `status`, `stale_after`; +- Liste-vs.-Map-Form von `sources`; +- Zulässigkeit von `generated`/`verified` und `status`-Policing; +- Typdefinition von `log.md`; +- Index-Regel (jedes Area besitzt eine `index.md`); +- Validitätsprädikate für Concepts und Bundle-Root; +- Bindung des Verbots: `sources`-Einträge lösen niemals auf `wiki/`-Concept-Pfade auf (AD-4b, A0-4). + +Das Schema liegt **außerhalb** des Bundles (`wiki/`) und ist keine Concept-Datei (Structural Seed, AD-1). diff --git a/wiki/index.md b/wiki/index.md new file mode 100644 index 0000000..f47d0a4 --- /dev/null +++ b/wiki/index.md @@ -0,0 +1,25 @@ +--- +type: bundle +okf_version: "0.2" +--- + +# Wiki of Wikis — Knowledge Bundle + +Bundleroot des kuratierten OKF-Knowledge Bundles (AD-1). `okf_version: "0.2"` und Frontmatter sind **nur** in dieser Bundleroot-`index.md` erlaubt — Area-`index.md`-Dateien und andere Bundle-Dateien tragen kein Frontmatter. + +Hier startet die progressive Discovery (AD-9): von dieser Bundleroot führt der Weg über die Area-`index.md`-Dateien zu den Concepts. + +```text +wiki/ + index.md + log.md + + / + index.md + .md +``` + +- **`log.md`** — reserviertes Protokoll des Bundles: dokumentiert fachliche Änderungen und Disagreements (AD-16b) und ist Teil der Lease-Root-Scope (AD-17b). Typdefinition folgt im Schema-Vertrag (Story 1.3). +- Noch keine Areas vorhanden — dieses Bundle wird in späteren Epics inkrementell gefüllt. + +Der Workspace umfasst außerdem: `raw/` (immutable Source Material/Evidenz, AD-2/AD-3), `schema/` (Compiler-Schema-Vertrag, AD-1) und `adapters/` (dünne Agenten-Adapter, AD-10). diff --git a/wiki/log.md b/wiki/log.md new file mode 100644 index 0000000..e69de29