Michael TamseandClaude
2625e1d4c0
- raw/ wiki/, schema/, adapters/ als Architekturgrenzen angelegt (AD-2, AD-3, AD-10) - OKF-Bundleroot wiki/index.md mit type: bundle und okf_version: "0.2" (AD-1) - Reserviertes wiki/log.md (leer) als Protokoll- und Lease-Root-Scope-Bestandteil - Platzhalter schema/wiki-compiler.md (Story 1.3) und adapters/claude (Story 5.3) - Orientierungs-READMEs, .gitignore fuer IDE/OS-Cruft - Sprint-Status Story 1.1 auf review, Epic 1 auf in-progress - Spec-Trace + Epic-1-Kontext generiert Co-Authored-By: Claude <noreply@anthropic.com>
40 lines
4.7 KiB
Markdown
40 lines
4.7 KiB
Markdown
# Epic 1 Context: Wissens-Workspace & Quellen-Aufnahme
|
|
|
|
<!-- Compiled from planning artifacts. Edit freely. Regenerate with compile-epic-context if planning docs change. -->
|
|
|
|
## 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/<agent>/`. 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 `<area>/index.md` + `<concept>.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).
|