erstellt SPINE

This commit is contained in:
Michael Tamse
2026-08-14 19:05:39 +02:00
parent 8f0af81f83
commit 6a95d96a00
10 changed files with 2131 additions and 0 deletions
+44
View File
@@ -0,0 +1,44 @@
---
topic: Wiki of Wikis — Knowledge Compiler (LLM Wiki / OKF 0.2)
updated: 2026-08-14T18:10
---
- (capability) CAP-1 (FR-1) Sources bereitstellen: Nutzer kann dem Compiler ein oder mehrere Source-Materialien zur Verarbeitung bereitstellen, ohne die Wiki-Struktur vorher bestimmen zu müssen (v1: nur lokal bereitgestelltes Material, A-4). Success: Ein Compilation Run akzeptiert 1..n Sources; keine URL-Beschaffung im Compiler-Kern.
- (capability) CAP-2 (FR-2) Sources vs. Curated Knowledge unterscheiden: System hält Source Material und Knowledge Bundle physisch+semantisch getrennt (raw/ vs. wiki/). Success: Kopie eines Quelldokuments zählt nicht als Wissensintegration; Consumers können beide trennen.
- (capability) CAP-3 (FR-3) Provenienz bewahren: abgeleitetes Wissen bleibt auf Sources rückführbar; neue Quellen entfernen bestehende Provenienz nicht. Success: Jedes erzeugte/aktualisierte Concept referenziert seine zugrunde liegenden Sources (AD-4a); mehrere Contributing Sources dokumentierbar.
- (capability) CAP-4 (FR-4) Gegen bestehendes Wissen kompilieren: Ein Run berücksichtigt neues Source Material UND relevantes vorhandenes kuratiertes Wissen. Success: Bestehendes Wiki ist Input; erarbeitete Erkenntnisse müssen nicht aus Rohquellen neu aufgebaut werden.
- (capability) CAP-5 (FR-5) Concepts erzeugen: Compiler kann aus Source Material neue eigenständige Wissenseinheiten erzeugen. Success: Neues Concept; mehrere Abschnitte einer Source können in unterschiedliche Concepts fließen; nicht an Source-Struktur gebunden.
- (capability) CAP-6 (FR-6) Bestehende Concepts aktualisieren: Compiler kann vorhandene Concepts erweitern/präzisieren/korrigieren. Success: Neue Informationen führen nicht automatisch zu neuen Dateien; Beziehungen+Provenienz bleiben soweit gültig erhalten.
- (capability) CAP-7 (FR-7) Wissen synthetisieren: Compiler führt mehrere Sources zu einer gemeinsamen Wissensrepräsentation zusammen (Wissensstand, nicht Aneinanderreihung). Success: Mehrere Sources zum selben Thema enden nicht in getrennten Zusammenfassungen; Redundanz konsolidiert; relevante Provenienz übernommen.
- (capability) CAP-8 (FR-8) Widersprüche sichtbar behandeln: widersprüchliche Informationen werden nie stillschweigend zu einer eindeutigen Aussage verschmolzen. Success: Relevante Widersprüche bleiben in log.md als explizite Disagreements erhalten (AD-16a Bewahrung als Default); Quellen nachvollziehbar; Unsicherheit darf Teil eines Concepts sein.
- (capability) CAP-9 (FR-9) OKF-konforme Concepts: alle erzeugten Concepts entsprechen OKF 0.2 (Markdown+YAML, type Pflichtfeld, optionale sources/generated/verified/status/stale_after). Success: Bundle validiert gegen schema/wiki-compiler.md; kein eigener OKF-Dialekt.
- (capability) CAP-10 (FR-10) Concepts verlinken: Compiler drückt Beziehungen mit normalen Markdown-Links aus (eine gepinnte Form, AD-7b). Success: Verlinkte Concepts navigierbar; Consumer brauchen keine proprietäre Software; Traversal durch Agenten möglich.
- (capability) CAP-11 (FR-11) Progressive Discovery: Consumer können Wissen schrittweise entdecken ohne alles zu lesen, über Hierarchie+index.md. Success: Übersicht zuerst, dann relevante Concepts öffnen; keine proprietäre Datenbank für Navigation nötig.
- (capability) CAP-12 (FR-12) Inkrementelle Weiterentwicklung: Ein Run entwickelt ein bestehendes Bundle weiter, statt ein unabhängiges Wiki neu zu erzeugen. Success: Unverändertes Wissen bleibt erhalten; Änderungen konzentrieren sich auf betroffene Concepts (AD-5).
- (capability) CAP-13 (FR-13) Menschliche Kuratierung berücksichtigen: manuell gepflegte Inhalte bleiben bestehendes Wissen; bei Konflikt erkennbar. Success: Run entfernt menschl. Ergänzungen nicht wegen fehlender Herkunft; Human-reviewed unterscheidbar von ungeprüft maschinellem (AD-15, generated/verified mit human:-Präfix); Mensch kann direkt editieren (FT-9).
- (capability) CAP-14 (FR-14) Änderungen nachvollziehbar: Änderungen erfolgen an textuellen Artefakten, Git-Diff zeigt fachliche Veränderungen. Success: Git-Diff unterscheidbar; keine proprietäre Änderungsverfolgung; Commit-Boundary als Mutationsgrenze (AD-17f).
- (capability) CAP-15 (FR-15) Tool-unabhängiger Zugriff: Bundle ohne Wiki-of-Wikis-Runtime lesbar (Menschen, LLM-Agenten, Standard-Dateioperationen). Success: Kein proprietäres SDK nötig; Markdown lesbar ohne Wiki-of-Wikis-spezifische Software (NFR-1/2/3/5).
- (capability) CAP-16 (FR-16) Consumer entkoppeln: Bundle nicht auf einen bestimmten LLM-Agenten/Workflow zugeschnitten. Success: BMAD/Claude/Codex/zukünftige Agenten können Consumer sein; Wechsel des Consumers erfordert keine Migration des Wissensformats (AD-10).
- (constraint) Constraint: OKF 0.2 ist der normative Format-Standard (Markdown+YAML-Frontmatter, type Pflichtfeld, optionale sources/generated/verified[human:]/status/stale_after); kein eigener OKF-Dialekt; Bundle-Root = wiki/, okf_version nur in Bundleroot-index.md (AD-1, AD-1a).
- (constraint) Constraint: Kanonischer persistenter Zustand = Git-versioniertes OKF-Knowledge-Bundle; abgeleitete Indizes/Caches/Embeddings sind rebuildable, niemals Source of Truth (AD-1/AD-14).
- (constraint) Constraint: Separation-of-Concerns — Sources → Compilation → Knowledge Bundle → Consumers; Consumer nicht Voraussetzung für Compilation; Source nicht automatisch Teil des Curated Knowledge (AD-2, AD-12).
- (constraint) Constraint: Source-Material immutable (AD-3); Copieren nach wiki/ ist keine Compilation; Relevanzbestimmung textuell-deterministisch (grep/link-traversal), keine Embedding/Vector-Infrastruktur (AD-13, AD-17-Anhang).
- (constraint) Constraint: Provenienz claim-granular; sources-Einträge zeigen nie auf wiki/-Pfade (AD-4a/4b/4c); generiertes Concept nie als alleinige Provenienz eines anderen.
- (constraint) Constraint: Compilation inkrementell (AD-5), Reasoning von Mutation getrennt (AD-6); Concept-ID = OKF-Pfad (AD-7/7a); Konflikte explizit bewahrt, nie still aufgelöst (AD-16/16a/16b).
- (constraint) Constraint: Koordination — lease/branch-basierte Workspace-Konvention, kein textueller Auto-Merge über denselben Concept-Pfad, Root-Scope inkl. log.md und index.md, Dirty-Tree-Schutz, Commit-Boundary als Mutationsgrenze, Determinismus-Kontrakt (AD-17a..h).
- (constraint) Constraint: Kein eigener Serverprozess/eigene LLM-Runtime im MVP (AD-11); agent-unabhängiger Compiler-Contract, Adapter als dünne Hüllen (AD-10).
- (constraint) Constraint: Complexity Guardrail — neue Infrastruktur nur wenn für 'Sources + existing knowledge → improved curated knowledge' erforderlich, sonst Source/Consumer-Adapter (FT-8).
- (constraint) Constraint: (PRD-MVP) v1 kein URL-Abruf; lokal bereitgestelltes Source-Material; keine GUI; kein Block-until-Interaktion-Modell.
- (constraint) Non-goal: keine Vector-DB/Vector-Search/Knowledge-Graph-DB/MCP-Server/Web-UI/Wiki-Rendering-Server/automatische Internetrecherche/Webcrawler/Scheduling/Source-Beobachtung/BMAD- oder Claude-Code- oder CodeGraph-Integration/Multi-User-Rechte/Enterprise-Governance/konkurrierende Ontologie
- (constraint) Non-goal: Retrieval ist Consumer-Verhalten, nicht Kern des Wiki-Compilers (AD-13); Wiki of Wikis ist keine RAG-Plattform, kein CMS, keine Suchmaschine, kein Dokumentenarchiv, keine Obsidian/Confluence-Alternative
- (constraint) Success-Signal (Kern): 'Knowledge should compound' — kein erneutes Rekonstruieren erarbeiteter Synthese bei jeder Anfrage; Lauf 2 baut auf Lauf 1 auf (SM-1/FT-6); plus Proof-origin Weg raw/→wiki/ (SM-2).
- (constraint) Assumption: v1 persönlich/teaminternes Developer Tool (A-1); keine GUI (A-3); Source-Beschaffung nicht Kern, nur bereitgestelltes Material (A-4); BMAD/Claude/Codex/CodeGraph sind Sources/Consumers, keine Kernbestandteile (A-5).
- (constraint) Assumption: AD-4g dawikig; maschinell erzeugt+ungeprüft ist v1-Default (generated ohne verified); Human-Review via verified human:-Präfix; Chip in AD-15 ist Implementierung.
- (constraint) Open Question (PRD OQ-1/Spine): Sollen vollständig manuell erstellte Concepts first-class behandelt oder nur toleriert werden? (Trägt auf FR-13/CAP-13; in v1 toleriert gemäß AD-15.)
- (constraint) Open Question (PRD OQ-5/Spine Q-5): Was passiert mit abgeleitetem Wissen, wenn eine Source entfernt/ersetzt/als falsch erkannt wird? (D-5; Revocation-Fall undesignet.)
- (constraint) Open Question (PRD OQ-6/Spine Q-4): Produktname 'Wiki of Wikis' final oder nur Projektname? (Owner PM.)
- (constraint) Open Question (Spine Q-6): Determinismus-Durchsetzung ohne dedizierten Validator im MVP (D-3) — als Agent-Instruktion bis dahin.
- (assumption) Assumption (korrigiert, ersetzt die obige 'AD-4g'-Zeile): maschinell erzeugt+ungeprüft ist v1-Default (generated ohne verified, kein verified gesetzt); Human-Review via 'verified' mit human:-Präfix-Actor; die konkrete Umsetzung folgt AD-15/FR-9, Implementierung geschieht in schema/wiki-compiler.md (AD-1a).
- (decision) Decision: PRD wird als 'sources' vollständig absorbiert (frontmatter sources:); Architecture-Spine als adopted companion referenziert (AD-IDs 1-17 + Subrules bleiben stabil und zitierbar); Glossary als spec-authored companion.
- (event) Self-Validate Pass 1 (Coherence): alle 16 CAPs haben intent+success (Spec Law 1); intents sind WHAT (2); Constraints nützen echte Grenzen (3); Non-goals explizit (4); Success signal testbar (5); CAP-ID-1..16 stabil (6); lean prose (8).
- (event) Self-Validate Pass 2 (Preservation): FR-1..16/NFR-1..7, A-1..5, Non-Goals, Guardrails alle gelandet (SPEC kernel + companions + architecture spine). Wrapper-only: Sektionen 0/§2-Journeys/§12-Diagramm usw. sind narrative Kapseln, nicht load-bearing Einzel-Claims.
+109
View File
@@ -0,0 +1,109 @@
---
id: SPEC-wow20
companions:
- ../planning-artifacts/architecture/architecture-wow20-2026-08-14/ARCHITECTURE-SPINE.md
- glossary.md
sources:
- ../planning-artifacts/prds/prd-wow20-2026-08-14/prd.md
---
> **Canonical contract.** This SPEC and the files in `companions:` are the complete, preservation-validated contract for what to build, test, and validate. Source documents listed in frontmatter are for traceability — consult them only if you need narrative rationale or prose color this contract intentionally omits.
# Wiki of Wikis
## Why
**Wiki of Wikis** is a **Knowledge Compiler**, not a retrieval system. It applies Andrej Karpathy's **LLM-Wiki principle**: raw sources are not re-searched and re-interpreted at every query, but are incrementally compiled by an LLM into a persistent, curated, OKF-compliant wiki that compounds knowledge over time. The problem: with growing heterogeneous sources (docs, specs, project artifacts), each query re-derives synthesis from raw material instead of building on already-distilled knowledge. The opportunity to capture: a portable, Git-versioned Markdown knowledge bundle that humans, LLM agents, BMAD, Claude Code, Codex, and other consumers can all use — without a database, server, or proprietary runtime. It transforms **Sources + existing knowledge → improved curated knowledge**.
## Capabilities
- **CAP-1** (FR-1) — **Source intake**
- **intent:** The user can provide the compiler one or more source materials for a Compilation Run, without first deciding which concept each source belongs to.
- **success:** A single run accepts 1..n sources; in v1 only locally provided material (no URL retrieval in the compiler core).
- **CAP-2** (FR-2) — **Source/Knowledge separation**
- **intent:** The system keeps Source Material and the Knowledge Bundle physically and semantically distinct (`raw/` vs. `wiki/`).
- **success:** Copying a source document is not counted as knowledge integration; consumers can tell Sources from Curated Knowledge.
- **CAP-3** (FR-3) — **Provenance**
- **intent:** Derived knowledge retains traceable provenance to its sources.
- **success:** Each created/updated concept references its underlying sources (AD-4a); multiple contributing sources are jointly documented; new sources don't accidentally strip existing provenance.
- **CAP-4** (FR-4) — **Compile against existing knowledge**
- **intent:** A run processes new source material together with relevant existing curated knowledge.
- **success:** The existing wiki is input; already-distilled insights need not be rebuilt from raw sources.
- **CAP-5** (FR-5) — **Create concepts**
- **intent:** The compiler can produce new standalone knowledge units from source material.
- **success:** New concepts arise; multiple sections of one source may feed different concepts; concepts are not bound to source structure.
- **CAP-6** (FR-6) — **Update existing concepts**
- **intent:** The compiler can extend, refine, or correct existing concepts.
- **success:** New information does not automatically create new files; relationships and provenance stay intact where still valid.
- **CAP-7** (FR-7) — **Synthesize knowledge**
- **intent:** The compiler merges information from multiple sources into a shared knowledge representation.
- **success:** Multiple sources on the same topic do not end in separate summaries; redundancy is consolidated; the result reflects the recognized knowledge state with merged provenance.
- **CAP-8** (FR-8) — **Handle contradictions visibly**
- **intent:** Contradictory information is never silently merged into a seemingly unambiguous statement.
- **success:** Relevant contradictions remain as explicit disagreements in `log.md` (AD-16a preservation default); sources stay traceable; uncertainty may be part of a concept.
- **CAP-9** (FR-9) — **OKF-conformant concepts**
- **intent:** All generated concepts conform to Open Knowledge Format 0.2 (Markdown + YAML frontmatter, `type` required, optional `sources`/`generated`/`verified`/`status`/`stale_after`).
- **success:** The bundle validates against `schema/wiki-compiler.md` (AD-1a); no own OKF dialect.
- **CAP-10** (FR-10) — **Link concepts**
- **intent:** The compiler expresses relationships between concepts with normal Markdown links (one pinned form, AD-7b).
- **success:** Linked concepts are navigable; consumers need no proprietary software; traversal by agents works.
- **CAP-11** (FR-11) — **Progressive discovery**
- **intent:** A consumer can discover knowledge stepwise without reading everything, via hierarchy + `index.md`.
- **success:** Overview first, then open relevant concepts; no proprietary database needed for navigation.
- **CAP-12** (FR-12) — **Incremental evolution**
- **intent:** A run evolves an existing bundle rather than generating an independent wiki anew.
- **success:** Unchanged knowledge is preserved; changes concentrate on concepts affected by new insights (AD-5).
- **CAP-13** (FR-13) — **Respect human curation**
- **intent:** Manually curated content remains existing knowledge; conflicts between human curation and new sources become visible.
- **success:** A run does not remove human additions merely for lacking provenance from this run; human-reviewed content stays distinguishable from unverified machine output (AD-15); a human can edit concepts directly and the correction survives (FT-9).
- **CAP-14** (FR-14) — **Traceable changes**
- **intent:** Changes to concepts remain traceable via normal version-control mechanisms.
- **success:** Git diff shows relevant changes; no proprietary change tracking needed; commit boundary is the mutation boundary (AD-17f).
- **CAP-15** (FR-15) — **Tool-independent access**
- **intent:** A consumer can read the bundle without a Wiki-of-Wikis-specific runtime.
- **success:** Humans read concepts with normal Markdown tools; LLM agents read via standard file operations; no proprietary SDK (NFR-1/2/3/5).
- **CAP-16** (FR-16) — **Consumer decoupling**
- **intent:** The bundle is not tailored to a particular LLM agent or workflow.
- **success:** BMAD, Claude Code, Codex, and future agents can all be consumers; switching consumers requires no migration of the knowledge format (AD-10).
## Constraints
- **OKF 0.2 is the normative format.** Markdown + YAML frontmatter; `type` is the only required field; optional `sources`/`generated`/`verified` (`human:` prefix)/`status`/`stale_after`; no own OKF dialect; bundle root = `wiki/`; `okf_version` only in bundle-root `index.md` (AD-1, AD-1a, FR-9).
- **Canonical state is the Git-versioned OKF Knowledge Bundle.** Derived indexes/caches/embeddings are rebuildable and never the source of truth (AD-1, AD-14).
- **Separation of Concerns:** Sources → Compilation → Knowledge Bundle → Consumers. A consumer is never a prerequisite for compilation; a source never automatically becomes curated knowledge (AD-2, AD-12).
- **Sources are immutable.** Compilation never modifies source material; copying into `wiki/` is not compilation (AD-3).
- **Provenance is claim-granular; `sources` entries never point at `wiki/` paths** (AD-4a/b/c). A generated concept is never the sole provenance of another.
- **Compilation is incremental** (AD-5); reasoning is separated from mutation (AD-6); concept identity is its OKF path (AD-7/7a); conflicts are preserved explicitly, never silently resolved (AD-16/16a/16b).
- **Coordinated producer writes.** Lease/branch-based workspace convention (`lease/<area>/<id>` + lockfile); no textual auto-merge over the same concept path; lease root-scope includes `log.md` and `index.md`; dirty-tree protection; commit boundary is the mutation boundary; determinism contract: same state + same input → same bundle (AD-17a..h).
- **Relevance determination is textual-deterministic** (grep / ripgrep / markdown traversal / link following), never embedding/vector infrastructure (AD-13, AD-17 appendix, PRD OQ-3).
- **No server process / own LLM runtime in the MVP** (AD-11); agent-independent compiler contract, thin adapters (AD-10).
- **Complexity guardrail:** new infrastructure belongs in the core only if required for "Sources + existing knowledge → improved curated knowledge", otherwise it is a Source/Consumer adapter, not a core component (FT-8, PRD §8.4).
- **MVP boundary:** v1 accepts only locally provided source material (no URL retrieval); no GUI; no interactive block-until-resolution model (PRD A-3/A-4).
## Non-goals
- **Retrieval is consumer behavior, not the compiler core:** no vector database, no vector search, no knowledge-graph database, no RAG platform, no enterprise search, no search backbone (AD-13).
- **No MCP server, no web UI, no wiki rendering server** in the MVP.
- **No automatic internet research, no general web crawler, no automatic scheduling, no automatic source observation.**
- **No BMAD-specific, Claude-Code-specific, or CodeGraph-specific integration** — these are sources/consumers (PRD A-5).
- **No multi-user rights system, no enterprise governance, no proprietary OKF dialect, no extra knowledge schema besides OKF.**
- **Not** a document management/archiving platform, a CMS, an Obsidian/Confluence alternative, a code-analysis platform, or a project-management platform.
## Success signal
**"Knowledge should compound."** After a second Compilation Run, the system evolves existing knowledge without regenerating the bundle from scratch (SM-1/FT-6); a new source produces curated concepts or concept changes with traceable provenance rather than a copy or paraphrase (SM-2/SM-3); a previously unrelated LLM agent can read the bundle via ordinary Markdown files and use it without Wiki-of-Wikis-specific APIs (SM-4); and the bundle stays fully readable when the compiler/LLM/indexes are unavailable (SM-5). A human can correct machine-produced content directly and the correction survives (SM-C3/FT-9); two independent runs over the same state produce the same bundle (AD-17h/FT-10).
## Assumptions
- v1 is primarily a personal/team-internal developer tool (PRD A-1); this must not produce a fully autonomous, unsupervised process (SM-C3).
- No dedicated GUI in v1 (PRD A-3).
- Source acquisition is not the product core; the compiler processes provided source material (PRD A-4).
- BMAD, Claude Code, Codex, CodeGraph are sources/consumers, not core components (PRD A-5).
- Machine-generated and unverified is the v1 default (`generated` without `verified`); human review is expressed via `verified` with a `human:`-prefixed actor; implementation lives in `schema/wiki-compiler.md` (AD-1a).
## Open Questions
- **Human-authored concepts:** Should fully manually authored concepts be treated as first-class knowledge, or merely tolerated? (v1 tolerates them via AD-15; open on first-class status.)
- **Source lifecycle / revocation:** What happens to derived knowledge when a source is removed, replaced, or found to be false? (Currently deferred D-5; the revocation case is not yet designed — Owner: Architecture.)
- **Product name:** Is "Wiki of Wikis" the final product name or only the project name? (Owner: PM.)
- **Determinism enforcement:** How is "same state → same bundle" enforced without a dedicated validator in the MVP? (D-3; as an agent-instruction validator until then — Owner: Architecture.)
+19
View File
@@ -0,0 +1,19 @@
---
type: spec-companion
companion-for: Wiki of Wikis
---
# Glossary — Wiki of Wikis
| Term | Definition |
|---|---|
| **Source** | Ein Informationsartefakt, aus dem Wissen gewonnen werden kann: technische Dokumentationen, Spezifikationen, Projektartefakte, Webseiten, Forschungsunterlagen, bestehende interne Dokumente. |
| **Source Material** | Der tatsächlich für einen Compilation Run verfügbare Inhalt einer Source. |
| **Knowledge Bundle** | Die Gesamtheit des durch Wiki of Wikis verwalteten OKF-Wikis. |
| **Concept** | Eine einzelne Wissenseinheit innerhalb des Knowledge Bundle; gemäß OKF als Markdown-Dokument repräsentiert. |
| **Wiki Page** | Informelle Bezeichnung für ein Concept (Anforderungen verwenden den OKF-Begriff **Concept**). |
| **Compiler** | Die Produktfunktion, die Source Material und das bestehende Knowledge Bundle analysiert und daraus ein aktualisiertes Knowledge Bundle erzeugt. |
| **Compilation Run** | Ein einzelner Verarbeitungsvorgang des Compilers. |
| **Curated Knowledge** | Vom Compiler oder einem Menschen bewusst strukturierte, zusammengeführte und interpretierte Wissensinhalte — keine bloße Kopie oder Sammlung von Source Material. |
| **Provenance** | Nachvollziehbare Beziehung zwischen einem Concept bzw. darin enthaltenen Aussagen und den zugrunde liegenden Sources. |
| **Consumer** | Ein Mensch oder Software-Agent, der das Knowledge Bundle liest oder für weitere Aufgaben verwendet. |