feat: Sources lokal unter raw/ materialisieren (Story 1.2)
- PRD, Architecture-Spine und epics als erste Evidenz-Sources unter raw/ materialisiert (Per-Quelle-Verzeichnis + source.md Provenienz-Sidecar) - raw/README um Quellen-Konvention erweitert (Benennung, additive Versionierung AD-3, Artefakt-Carve-out, lokale statt URL-Fetches) - sprint-status.yaml: Story 1.2 auf review gesetzt Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Michael Tamse
@@ -0,0 +1,953 @@
|
||||
---
|
||||
name: Wiki of Wikis
|
||||
type: architecture-spine
|
||||
purpose: build-substrate
|
||||
altitude: product
|
||||
paradigm: agent-native file-based compiler pipeline
|
||||
scope: Wiki of Wikis MVP
|
||||
status: final
|
||||
created: 2026-08-14
|
||||
updated: 2026-08-14
|
||||
binds:
|
||||
- FR-1..FR-16
|
||||
- NFR-1..NFR-7
|
||||
sources:
|
||||
- PRD — Wiki of Wikis
|
||||
- Andrej Karpathy — LLM Wiki
|
||||
- Open Knowledge Format 0.2
|
||||
companions:
|
||||
- PRD — Wiki of Wikis
|
||||
---
|
||||
|
||||
# Architecture Spine — Wiki of Wikis
|
||||
|
||||
## Design Paradigm
|
||||
|
||||
**Agent-native file-based compiler pipeline**
|
||||
|
||||
Wiki of Wikis wird als inkrementeller Knowledge Compiler aufgebaut.
|
||||
|
||||
Der Compiler transformiert unveränderliches Source Material und bereits vorhandenes kuratiertes Wissen in ein aktualisiertes OKF Knowledge Bundle.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
S[Raw Sources] --> C[LLM Wiki Compiler]
|
||||
W[Existing OKF Wiki] --> C
|
||||
|
||||
C --> P[Proposed Changes]
|
||||
P --> V[Validation]
|
||||
V -->|valid| W2[Updated OKF Wiki]
|
||||
|
||||
W2 --> H[Humans]
|
||||
W2 --> A[LLM Agents]
|
||||
W2 --> B[BMAD]
|
||||
W2 --> X[Other Consumers]
|
||||
```
|
||||
|
||||
Der Compiler ist **kein Wissensserver**.
|
||||
|
||||
Das Knowledge Bundle ist das Produktartefakt.
|
||||
|
||||
Der Compiler ist lediglich der Producer dieses Artefakts.
|
||||
|
||||
---
|
||||
|
||||
# Invariants & Rules
|
||||
|
||||
## AD-1 — OKF Knowledge Bundle is canonical knowledge state `[ADOPTED]`
|
||||
|
||||
- **Binds:** FR-9..FR-16, NFR-1..NFR-6
|
||||
- **Prevents:** Eine proprietäre Datenbank, ein Index oder eine Agent-Runtime wird versehentlich zum eigentlichen Knowledge Store.
|
||||
- **Rule:** Das kanonische kuratierte Wissen besteht ausschließlich aus einem OKF-0.2-konformen Markdown Knowledge Bundle.
|
||||
|
||||
Caches, Datenbanken, Embeddings, Search-Indizes oder Graph-Repräsentationen dürfen zukünftig existieren, sind jedoch ausschließlich abgeleitete Artefakte.
|
||||
|
||||
```text
|
||||
Canonical
|
||||
wiki/**/*.md
|
||||
|
||||
Derived
|
||||
indexes
|
||||
embeddings
|
||||
caches
|
||||
search databases
|
||||
visualizations
|
||||
```
|
||||
|
||||
Das Knowledge Bundle muss auch ohne diese Derived Artifacts vollständig verständlich bleiben.
|
||||
|
||||
---
|
||||
|
||||
## AD-2 — Raw Sources and Curated Knowledge are separate states `[ADOPTED]`
|
||||
|
||||
- **Binds:** FR-1, FR-2, FR-3, FR-4
|
||||
- **Prevents:** Rohdokumente und LLM-generiertes Wissen werden vermischt und verlieren ihre unterschiedliche semantische Bedeutung.
|
||||
- **Rule:** Source Material und Knowledge Bundle werden physisch und semantisch getrennt gespeichert.
|
||||
|
||||
```text
|
||||
raw/ immutable source material
|
||||
wiki/ curated OKF knowledge
|
||||
```
|
||||
|
||||
Eine Datei unter `raw/` ist Evidenz.
|
||||
|
||||
Eine Datei unter `wiki/` ist eine aus Evidenz abgeleitete Wissensrepräsentation.
|
||||
|
||||
Das bloße Kopieren eines Source-Dokuments nach `wiki/` ist keine Compilation.
|
||||
|
||||
---
|
||||
|
||||
## AD-3 — Raw Sources are immutable `[ADOPTED]`
|
||||
|
||||
- **Binds:** FR-1..FR-8
|
||||
- **Prevents:** Der Compiler verändert rückwirkend seine eigene Evidenzbasis.
|
||||
- **Rule:** Ein Compilation Run darf bestehendes Source Material niemals verändern.
|
||||
|
||||
Neue Versionen einer Source werden als neue beziehungsweise versionierte Source behandelt.
|
||||
|
||||
Source Lifecycle und Replacement-Semantik bleiben für den MVP deferred.
|
||||
|
||||
---
|
||||
|
||||
## AD-4 — Generated knowledge must remain source-grounded
|
||||
|
||||
- **Binds:** FR-3, FR-7, FR-8, NFR-7
|
||||
- **Prevents:** Das Wiki beginnt, seine eigenen LLM-Synthesen als neue Evidenz zu behandeln und verstärkt dadurch unbelegte Aussagen.
|
||||
- **Rule:** Ein generiertes Concept darf vorhandene Concepts zur Synthese und Kontextbildung verwenden, muss fachliche Aussagen jedoch auf nachvollziehbare Sources zurückführen.
|
||||
|
||||
Wiki-to-Wiki-Links dienen insbesondere:
|
||||
|
||||
- Navigation,
|
||||
- Kontext,
|
||||
- Beziehungen,
|
||||
- Synthese.
|
||||
|
||||
Sie ersetzen nicht die Provenienz zur ursprünglichen Evidenz.
|
||||
|
||||
Bei einer Synthese aus mehreren Concepts wird relevante Source-Provenienz in das resultierende Concept übernommen.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
R1[Raw Source A] --> C1[Concept A]
|
||||
R2[Raw Source B] --> C2[Concept B]
|
||||
|
||||
C1 --> S[Synthesized Concept]
|
||||
C2 --> S
|
||||
|
||||
R1 -. provenance .-> S
|
||||
R2 -. provenance .-> S
|
||||
```
|
||||
|
||||
### AD-4a — Claim-granular provenance
|
||||
|
||||
Provenance must be referencible per asserting unit (block/paragraph), not only per Concept. Minimum form: every backed claim carries an inline reference to `raw/` evidence; context/synthesis reformulations carry an explicit context marker ("taken over from <Concept path> based on <source>, not independently evidenced").
|
||||
|
||||
### AD-4b — Sources target only raw/ or external evidence
|
||||
|
||||
`sources` entries must resolve to `raw/` paths or to externally referenced immutable evidence — never to a `wiki/` concept path. Wiki links remain the navigation/relationship layer (AD-8) and are format-side disambiguated from provenance.
|
||||
|
||||
### AD-4c — No generated Concept is sole provenance of another (binding)
|
||||
|
||||
"Ein generiertes Concept darf nie ein anderes generiertes Concept als alleinige Provenienz führen" wurde von einer ASSUMPTION in eine Rule überführt und ist Teil der `schema/wiki-compiler.md`-Validierung.
|
||||
|
||||
---
|
||||
|
||||
## AD-5 — Compilation is incremental `[ADOPTED]`
|
||||
|
||||
- **Binds:** FR-4..FR-8, FR-12
|
||||
- **Prevents:** Jeder Lauf erzeugt das Wiki erneut aus sämtlichen Rohquellen und verliert den compounding-knowledge Effekt.
|
||||
- **Rule:** Jeder Compilation Run beginnt mit dem aktuell vorhandenen Knowledge Bundle und verändert nur die durch neue Erkenntnisse betroffenen Concepts.
|
||||
|
||||
Der logische Datenfluss lautet:
|
||||
|
||||
```text
|
||||
Existing Knowledge
|
||||
+
|
||||
New Source Material
|
||||
↓
|
||||
Interpret
|
||||
↓
|
||||
Reconcile
|
||||
↓
|
||||
Synthesize
|
||||
↓
|
||||
Update affected Concepts
|
||||
```
|
||||
|
||||
Nicht:
|
||||
|
||||
```text
|
||||
All Sources
|
||||
↓
|
||||
Regenerate Everything
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## AD-6 — Compilation separates reasoning from mutation `[ASSUMPTION]`
|
||||
|
||||
- **Binds:** FR-5..FR-14
|
||||
- **Prevents:** Ein Agent hinterlässt während einer teilweise fehlgeschlagenen Verarbeitung ein inkonsistentes Knowledge Bundle.
|
||||
- **Rule:** Ein Compilation Run unterscheidet logisch zwischen:
|
||||
|
||||
1. Analyse,
|
||||
2. Änderungsplanung,
|
||||
3. Mutation,
|
||||
4. Validierung.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[Analyze] --> R[Reconcile]
|
||||
R --> P[Plan Changes]
|
||||
P --> M[Mutate Bundle]
|
||||
M --> V[Validate]
|
||||
```
|
||||
|
||||
Ein Agent darf diese Phasen technisch innerhalb einer Session durchführen.
|
||||
|
||||
Die Architektur schreibt keine separate Workflow Engine vor.
|
||||
|
||||
Der beobachtbare Endzustand muss jedoch ein konsistentes Bundle sein.
|
||||
|
||||
---
|
||||
|
||||
## AD-7 — Concept identity is its OKF path `[ADOPTED]`
|
||||
|
||||
- **Binds:** FR-5, FR-6, FR-9..FR-12
|
||||
- **Prevents:** Unterschiedliche Producer führen zusätzliche IDs oder proprietäre Identity-Systeme ein.
|
||||
- **Rule:** Die Identität eines Concepts entspricht der OKF-Konvention und wird durch den relativen Pfad innerhalb des Knowledge Bundle bestimmt.
|
||||
|
||||
Beispiel:
|
||||
|
||||
```text
|
||||
wiki/
|
||||
flowable/
|
||||
timers.md
|
||||
```
|
||||
|
||||
Concept ID:
|
||||
|
||||
```text
|
||||
flowable/timers
|
||||
```
|
||||
|
||||
Renames sind deshalb semantische Änderungen und keine rein kosmetischen Dateioperationen.
|
||||
|
||||
### AD-7a — One canonical concept-ID normalization
|
||||
|
||||
Exactly one canonical ID form must be fixed, e.g.: lowercase, path relative to the bundle root, without extension, `index.md` → area path, no trailing dots. Example table:
|
||||
|
||||
```text
|
||||
wiki/flowable/timers.md → flowable/timers
|
||||
wiki/spring/index.md → spring
|
||||
wiki/spring/testing.md → spring/testing
|
||||
```
|
||||
|
||||
### AD-7b — One permitted link form
|
||||
|
||||
AD-8's "normal Markdown links" must be pinned to exactly one form: bundle-relative with or without extension — one of them, never both. (This prevents two producers computing different IDs from the same tree.)
|
||||
|
||||
### AD-7c — Deterministic area attribution
|
||||
|
||||
A rule for "where does a topic belong" is required. The relevance determination is already pinned to textual, deterministic means (AD-17 appendix, deterministic relevance); the same textual determinism must determine the target area, e.g. via an existing `index.md` link or top-level collision-hold on existing paths.
|
||||
|
||||
### AD-7d — Renaming compatibility
|
||||
|
||||
A rename is a new object plus an explicit redirect/deprecation entry in `log.md` (or the OKF `references/` convention), so that old IDs remain machine-discoverable.
|
||||
|
||||
---
|
||||
|
||||
## AD-8 — Standard Markdown links express concept relationships `[ADOPTED]`
|
||||
|
||||
- **Binds:** FR-10, FR-11, FR-15
|
||||
- **Prevents:** Beziehungen funktionieren nur noch mit einer speziellen Graphdatenbank oder einem proprietären Linkformat.
|
||||
- **Rule:** Beziehungen zwischen Concepts werden mit normalen Markdown-Links ausgedrückt. Die eine erlaubte Linkform ist durch AD-7b gepinnt (bundle-relativ, eine einzige Form — nie beide).
|
||||
|
||||
Eine zukünftige Graph-Repräsentation darf diese Links auswerten.
|
||||
|
||||
Der Graph selbst ist jedoch nicht kanonisch.
|
||||
|
||||
```text
|
||||
Markdown Links
|
||||
↓
|
||||
optional derivation
|
||||
↓
|
||||
Knowledge Graph
|
||||
```
|
||||
|
||||
Nicht:
|
||||
|
||||
```text
|
||||
Knowledge Graph
|
||||
↓
|
||||
generated Markdown projection
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## AD-9 — Progressive discovery uses OKF hierarchy and indexes `[ADOPTED]`
|
||||
|
||||
- **Binds:** FR-11, FR-15
|
||||
- **Prevents:** Consumer müssen das komplette Wiki in ihren Context laden oder benötigen frühzeitig eine externe Search Engine.
|
||||
- **Rule:** `index.md` und die hierarchische Bundle-Struktur bilden die erste Discovery-Ebene.
|
||||
|
||||
Beispiel:
|
||||
|
||||
```text
|
||||
wiki/
|
||||
index.md
|
||||
|
||||
spring/
|
||||
index.md
|
||||
testing.md
|
||||
transactions.md
|
||||
|
||||
flowable/
|
||||
index.md
|
||||
timers.md
|
||||
job-execution.md
|
||||
|
||||
project/
|
||||
index.md
|
||||
release-train.md
|
||||
```
|
||||
|
||||
Ein Consumer soll von einer Übersicht schrittweise zu relevanten Concepts navigieren können.
|
||||
|
||||
Search ist eine optionale spätere Optimierung.
|
||||
|
||||
---
|
||||
|
||||
## AD-10 — Compiler behavior is defined independently of a specific agent `[ADOPTED]`
|
||||
|
||||
- **Binds:** FR-15, FR-16, NFR-6
|
||||
- **Prevents:** Wiki of Wikis wird untrennbar mit Claude Code, Codex, BMAD oder einem bestimmten Modell verbunden.
|
||||
- **Rule:** Die kanonischen Compiler-Regeln werden agent-unabhängig beschrieben.
|
||||
|
||||
Provider- oder agentenspezifische Instruktionsdateien sind dünne Adapter.
|
||||
|
||||
```text
|
||||
Canonical compiler contract
|
||||
│
|
||||
┌────┼────┐
|
||||
▼ ▼ ▼
|
||||
Claude Codex Other
|
||||
adapter adapter adapter
|
||||
```
|
||||
|
||||
Ein Adapter darf keine abweichende Knowledge-Semantik definieren.
|
||||
|
||||
---
|
||||
|
||||
## AD-11 — Agent runtime provides reasoning; Wiki of Wikis provides protocol `[ASSUMPTION]`
|
||||
|
||||
- **Binds:** MVP
|
||||
- **Prevents:** Für den MVP entsteht unnötig eine eigene LLM-Orchestrierungsplattform.
|
||||
- **Rule:** Wiki of Wikis implementiert zunächst keine eigene LLM Runtime.
|
||||
|
||||
Ein vorhandener agentischer Host führt den Compiler-Workflow aus und stellt Fähigkeiten wie:
|
||||
|
||||
- Dateien lesen,
|
||||
- Dateien schreiben,
|
||||
- suchen,
|
||||
- LLM Reasoning
|
||||
|
||||
bereit.
|
||||
|
||||
Die konkrete Runtime ist austauschbar.
|
||||
|
||||
Damit ist für den MVP insbesondere **kein eigener Serverprozess erforderlich**.
|
||||
|
||||
---
|
||||
|
||||
## AD-12 — Source acquisition is outside the compiler core `[ADOPTED]`
|
||||
|
||||
- **Binds:** FR-1, MVP boundary
|
||||
- **Prevents:** Der Knowledge Compiler wächst zu Webcrawler, Dokumentenplattform oder Connector Framework.
|
||||
- **Rule:** Der Compiler verarbeitet bereitgestelltes Source Material.
|
||||
|
||||
Wie eine Source beschafft wurde, liegt außerhalb des Compiler-Kerns.
|
||||
|
||||
Beispiele:
|
||||
|
||||
```text
|
||||
Context7 --------\
|
||||
Web Clipper ------\
|
||||
BMAD Archive ------> raw/ ---> Compiler
|
||||
Arc42 ------------/
|
||||
Vendor Docs ------/
|
||||
```
|
||||
|
||||
Zukünftige Source Adapter dürfen Material nach `raw/` materialisieren.
|
||||
|
||||
Sie umgehen nicht die Source-Grenze.
|
||||
|
||||
---
|
||||
|
||||
## AD-13 — Retrieval belongs to consumers `[ADOPTED]`
|
||||
|
||||
- **Binds:** FR-15, FR-16, MVP Non-Goals
|
||||
- **Prevents:** Search, RAG, Embeddings oder CodeGraph werden wieder zum Zentrum der Architektur.
|
||||
- **Rule:** Retrieval ist nicht Bestandteil des kanonischen Knowledge Compilers.
|
||||
|
||||
Ein Consumer kann beispielsweise verwenden:
|
||||
|
||||
```text
|
||||
grep / ripgrep
|
||||
Markdown traversal
|
||||
BM25
|
||||
Vector Search
|
||||
Hybrid Search
|
||||
Knowledge Graph
|
||||
CodeGraph
|
||||
```
|
||||
|
||||
Diese Verfahren lesen das Knowledge Bundle.
|
||||
|
||||
Sie verändern dessen kanonisches Datenmodell nicht.
|
||||
|
||||
---
|
||||
|
||||
## AD-14 — Git provides history, not domain state `[ADOPTED]`
|
||||
|
||||
- **Binds:** FR-14, NFR-4
|
||||
- **Prevents:** Eine zusätzliche proprietäre Versions- oder Audit-Datenbank wird eingeführt.
|
||||
- **Rule:** Änderungen am Knowledge Bundle werden als normale textuelle Änderungen behandelt und können mit Git versioniert werden.
|
||||
|
||||
Git ist verantwortlich für:
|
||||
|
||||
- Diffs,
|
||||
- Version History,
|
||||
- Attribution,
|
||||
- Branching,
|
||||
- Restore.
|
||||
|
||||
Fachliche Provenienz verbleibt dennoch im OKF Concept und darf nicht ausschließlich aus Git-Historie abgeleitet werden.
|
||||
|
||||
---
|
||||
|
||||
## AD-15 — Human curation and machine curation share the same knowledge model `[ADOPTED]`
|
||||
|
||||
- **Binds:** FR-13, NFR-2
|
||||
- **Prevents:** Ein separates Datenmodell für manuelles und generiertes Wissen entsteht.
|
||||
- **Rule:** Sowohl menschlich als auch maschinell gepflegtes Wissen wird als OKF Concept repräsentiert.
|
||||
|
||||
Unterschiede bezüglich Autor, Generierung oder Review werden über OKF-Metadaten ausgedrückt, nicht über getrennte Dateiformate.
|
||||
|
||||
Der Compiler behandelt vorhandene menschliche Inhalte als persistentes Wissen und darf sie nicht allein wegen fehlender Herkunft aus dem aktuellen Compilation Run entfernen.
|
||||
|
||||
Die Trust- und Review-Metadaten folgen der OKF-0.2-Konvention:
|
||||
|
||||
- maschinell erzeugt und ungeprüft → `generated: { by, at }` setzen, kein `verified`;
|
||||
- Evidence-basiert bzw. menschlich reviewed → `verified` mit `human:`-Präfix-Actor;
|
||||
- Lifecycle → `status` (`draft` | `stable` | `deprecated`) und optional `stale_after`.
|
||||
|
||||
Der v1-Default nach PRD-Annahme ist: maschinell erzeugt und ungeprüft, d.h. Trust-Metadaten nur über `generated`, und `verified` bleibt ungesetzt, bis ein Mensch das Concept reviewt.
|
||||
|
||||
---
|
||||
|
||||
## AD-16 — Conflicts are preserved explicitly, never silently resolved `[ADOPTED]`
|
||||
|
||||
- **Binds:** FR-8, FR-13, NFR-7
|
||||
- **Prevents:** Widersprüche werden stillschweigend zu einer scheinbar eindeutigen Aussage zusammengeführt und verlieren damit ihre Quelle.
|
||||
- **Rule:** Der Compiler klassifiziert neue Information vor jeder Änderung:
|
||||
|
||||
```text
|
||||
NEW? → create or extend knowledge
|
||||
CONFIRMING? → strengthen existing knowledge if material
|
||||
CORRECTING? → revise existing knowledge
|
||||
CONTRADICTING?→ preserve the disagreement explicitly
|
||||
REDUNDANT? → no knowledge mutation required
|
||||
```
|
||||
|
||||
Diese Klassifikation ist konzeptionell.
|
||||
|
||||
Sie schreibt keine konkrete interne Datenstruktur vor.
|
||||
|
||||
Relevante Widersprüche (Contradictions) verbleiben als explizite, in `log.md` dokumentierte Disagreements im Bundle. Die jeweiligen Sources bleiben nachvollziehbar; Unsicherheit darf explizit Teil eines Concepts sein.
|
||||
|
||||
### AD-16a — Preservation is the default
|
||||
|
||||
Deterministic default: on contradiction, the default is preservation (CONTRADICTING), unless the new source explicitly supersedes the old one with explicit evidence; otherwise CORRECTING with documented replacement logic. This makes the classification (and hence who owns the resolution artifact) deterministic instead of being left to each producer's discretion.
|
||||
|
||||
### AD-16b — Classification is public and bound to the mutation
|
||||
|
||||
The classification including its rationale must land in the same artifact as the mutation — a `log.md` entry linked to the mutated Concept path — so the resolution decision is reproducible and ownership is auditable.
|
||||
|
||||
---
|
||||
|
||||
## AD-17 — Producer mechanism is the bundle-relative Workspace Convention (Leasing) `[ADOPTED]`
|
||||
|
||||
- **Binds:** PRD OQ-3, OQ-4, AD-5, AD-6, AD-10
|
||||
- **Prevents:** Zwei unabhängige Compiler / Producer / Nutzer (Claude, Codex oder der Mensch selbst) mutieren denselben Concept-Pfad gleichzeitig; Last-Writer-Wins überschreibt damit stillschweigend die Arbeit des jeweils anderen.
|
||||
- **Rule:** Producer arbeiten nach einem lease/branch-basierten Modell auf dem Git-Workspace:
|
||||
|
||||
1. Jeder Producer arbeitet in einem eigenen Workspace (Branch oder Worktree) und räumt Konflikte auf Git-Ebene (Rebase/Merge) selbst ab.
|
||||
2. Der Compiler darf nur veröffentlichte (committed) Inhalte als Input für Compilation verwenden. Während einer Mutation angelegte Zwischenstände sind nie Input.
|
||||
3. Konvergenz auf `data`-Ebene (Konflikte über Datei-Inhalte) folgen dem Sequenz-Diagramm (orkestriert durch den ausführenden Adapter):
|
||||
|
||||
- neue Sources unter `raw/` materialisieren,
|
||||
- den relevanten existierenden Concept-Bereich auf dem Workspace disabled (Lease) holen,
|
||||
- auf delektierte/importierte Areas folgt `raw/` als Zugriffs- und Consistency-Basis,
|
||||
- Mutationen nur innerhalb des geleasten Bereichs, sonst Reichweite nicht verlassen,
|
||||
- nach Abschluss Änderungen committen und Lease freigeben.
|
||||
|
||||
4. **Konfliktbehandlung:** Bei konkurrierenden Änderungen zählt in der `log.md` der produktive Nutzen/Beitrag als Auflösungs-Prinzip (erhaltbarer Inhalt). Der Compiler darf einen bestehenden Concept-Bereich nicht löschen, erweitern oder umschreiben, wenn die Änderung eines anderen Producers davon wirksam ersetzt wäre; stattdessen wird der Konflikt in `log.md` dokumentiert und offengelegt.
|
||||
|
||||
> **Wichtig — funktionaler Grund:** Retrieval ist Consumer-Verhalten (AD-13), daher ist **Relevanzbestimmung** (PRD OQ-3: "Wie findet der Compiler relevante vorhandene Concepts?") begrenzt: Sie muss mit textuellen, deterministischen Mitteln (grep/ripgrep, Markdown-Traversal, Link-Following) umgesetzt werden, nicht mit Embedding- oder Vector-Infrastruktur. Diese Klärung ist eine Antwort des Compilers auf den PRD-Auftrag.
|
||||
|
||||
### AD-17a — Lease contract (mechanism, commit-binding)
|
||||
|
||||
AD-17 must define what a lease is and how it is acquired — against a unique commit-object value (merge-base discipline) and via a single deterministic mechanism (e.g. branch-prefix convention `lease/<area>/<id>` plus a lockfile realized semantically identically in every adapter). The realization must not be freely selectable per adapter.
|
||||
|
||||
### AD-17b — Lease scope includes the bundle root
|
||||
|
||||
The lease must explicitly cover `wiki/` including `log.md`, `index.md`, and all root files ("root scope"): the preservation artifact is otherwise defenseless.
|
||||
|
||||
### AD-17c — No silent textual auto-merge
|
||||
|
||||
Two branches that modified the same Concept path must not be merged via textual Git auto-merge. The merge is compiler-mediated and goes through the AD-16 classification — with an explicit `log.md` entry if the contents are not identical.
|
||||
|
||||
### AD-17d — Lease staleness
|
||||
|
||||
Either a time-to-live plus registration of the lease in the clone-root state, or the rule that uncommitted leases count as stale after a run abort and `raw/` (immutable, AD-3) is the recovery basis.
|
||||
|
||||
### AD-17e — Dirty-tree protection
|
||||
|
||||
Before any mutation the producer must check the working copy for the area being mutated; non-committed foreign changes must be protected (stash/divert into a protected scratch zone), and any displaced uncommitted content must be documented in `log.md`.
|
||||
|
||||
### AD-17f — Commit boundary is the mutation boundary
|
||||
|
||||
Mutation may only operate at directory/commit level, so a foreign dirty working-tree change is never deleted as a side-effect of checkout/rebase.
|
||||
|
||||
### AD-17g — Resolution authority
|
||||
|
||||
Who resolves an AD-16 collision must be fixed (MVP: the compiler run holding the lease, per the AD-16a default; human escalation only when undecidable), and the resolution must be bound to the same commit/log documentation (minimal: commit hash + classification in the entry).
|
||||
|
||||
### AD-17h — Determinism contract
|
||||
|
||||
Over the same Git state and the same input set, two independent runs must produce the same bundle state (as an explicit fitness test analogous to FT-6); otherwise the AD-16 classification is not deterministic enough.
|
||||
|
||||
---
|
||||
|
||||
# Consistency Conventions
|
||||
|
||||
| Concern | Convention |
|
||||
|---|---|
|
||||
| Concept identity | relativer OKF-Dateipfad ohne `.md` (AD-7a) |
|
||||
| Concept format | Markdown + YAML Frontmatter |
|
||||
| Concept relationships | Standard-Markdown-Links (eine erlaubte Form, AD-7b) |
|
||||
| Provenance | OKF `sources` — nie auf `wiki/`-Pfade (AD-4b) |
|
||||
| Source state | immutable |
|
||||
| Knowledge state | mutable, incremental |
|
||||
| Canonical knowledge | `wiki/` |
|
||||
| Canonical evidence | `raw/` bzw. referenzierte externe Source |
|
||||
| Discovery | Hierarchie + `index.md` |
|
||||
| Update history | Git + optional OKF `log.md` |
|
||||
| Agent-specific behavior | Adapter, nicht Knowledge-Modell |
|
||||
| NFR-3 Agent Readability (explicit binding) | gut verlinktes, atomares, frontmatter-sauberes Markdown, konsumierbar von jeder Tool-Klasse — keine Optimierung für eine einzelne Agenten-Familie (FR-16-konform) |
|
||||
| Schema | `schema/wiki-compiler.md` bindet das OKF-Feld-Subset, `log.md`-Typ, Index-Regel, Validitätsprädikate (AD-1a) |
|
||||
| Errors | kein erfolgreicher Run bei OKF-invalidem Bundle laut `schema/wiki-compiler.md` (F-2/AD-1b: strukturell-invalid, nicht bei fehlenden optionalen Feldern) |
|
||||
| Human correctability | ein Mensch kann ein maschinell erzeugtes Concept editieren/corrigieren; die Korrektur wird wie normale Kuratierung behandelt (A-1/SM-C3, FT-9) |
|
||||
| Configuration | textuell und versionierbar |
|
||||
| Derived indexes | rebuildable, niemals Source of Truth |
|
||||
|
||||
---
|
||||
|
||||
# Structural Seed
|
||||
|
||||
**Bundle root:** `wiki/` ist die Bundleroot des OKF Knowledge Bundle. Alle strukturellen OKF-Konventionen (reservierte `index.md`/`log.md`; `okf_version` nur in der Bundleroot-`index.md`) beziehen sich auf dieses Verzeichnis. `raw/`, `schema/` und `adapters/` liegen **außerhalb** des Bundles und sind keine Concept-Dateien.
|
||||
|
||||
```text
|
||||
wiki-of-wikis/
|
||||
│
|
||||
├── raw/
|
||||
│ ├── ...
|
||||
│ │
|
||||
│ └── assets/
|
||||
│
|
||||
├── wiki/
|
||||
│ ├── index.md
|
||||
│ ├── log.md
|
||||
│ │
|
||||
│ ├── <area>/
|
||||
│ │ ├── index.md
|
||||
│ │ └── <concept>.md
|
||||
│ │
|
||||
│ └── ...
|
||||
│
|
||||
├── schema/
|
||||
│ └── wiki-compiler.md
|
||||
│
|
||||
└── adapters/
|
||||
├── claude/
|
||||
├── codex/
|
||||
└── ...
|
||||
```
|
||||
|
||||
`raw/` und `wiki/` sind Architekturgrenzen.
|
||||
|
||||
Die übrige Verzeichnisstruktur ist Seed und darf sich mit der Implementierung verändern.
|
||||
|
||||
Insbesondere sind `schema/` und `adapters/` keine Domain Stores.
|
||||
|
||||
---
|
||||
|
||||
# Capability → Architecture Map
|
||||
|
||||
| Capability | Lives in | Governed by |
|
||||
|---|---|---|
|
||||
| FR-1 Source intake | `raw/` boundary | AD-2, AD-3, AD-12 |
|
||||
| FR-2 Source/Knowledge separation | repository boundaries | AD-2 |
|
||||
| FR-3 Provenance | OKF Concepts | AD-4 |
|
||||
| FR-4 Existing knowledge processing | compiler | AD-5 |
|
||||
| FR-5 Concept creation | compiler → `wiki/` | AD-5, AD-7 |
|
||||
| FR-6 Concept update | compiler → `wiki/` | AD-5 |
|
||||
| FR-7 Cross-source synthesis | compiler | AD-4, AD-5 |
|
||||
| FR-8 Contradictions | compiler + Concepts | AD-16 |
|
||||
| FR-9 OKF compliance | `wiki/` | AD-1 |
|
||||
| FR-10 Relationships | Markdown links | AD-8 |
|
||||
| FR-11 Progressive discovery | hierarchy + indexes | AD-9 |
|
||||
| FR-12 Incremental evolution | compiler | AD-5 |
|
||||
| FR-13 Human curation | `wiki/` | AD-15 |
|
||||
| FR-14 Change history | Git | AD-14 |
|
||||
| FR-15 Tool-independent access | filesystem / Markdown | AD-1, AD-8, AD-9 |
|
||||
| FR-16 Consumer independence | consumer boundary | AD-10, AD-13 |
|
||||
|
||||
---
|
||||
|
||||
# Stack
|
||||
|
||||
The MVP intentionally has no conventional application stack.
|
||||
|
||||
| Concern | Bound technology / standard |
|
||||
|---|---|
|
||||
| Knowledge representation | Open Knowledge Format 0.2 |
|
||||
| Content | Markdown |
|
||||
| Metadata | YAML Frontmatter according to OKF |
|
||||
| Versioning | Git |
|
||||
| Storage | Filesystem / Git repository |
|
||||
| LLM | not bound |
|
||||
| Agent runtime | not bound |
|
||||
| Programming language | not bound |
|
||||
| Database | none required |
|
||||
| Vector database | none |
|
||||
| Server runtime | none required |
|
||||
| MCP | none required |
|
||||
|
||||
Any implementation technology introduced later must justify why the capability cannot reasonably be provided by the existing agent runtime plus filesystem operations.
|
||||
|
||||
---
|
||||
|
||||
# Operational Envelope
|
||||
|
||||
## Local-first execution
|
||||
|
||||
The complete canonical system state can exist inside a normal Git working copy.
|
||||
|
||||
```text
|
||||
git clone
|
||||
↓
|
||||
raw + wiki + compiler contract
|
||||
↓
|
||||
usable knowledge workspace
|
||||
```
|
||||
|
||||
No central service is required to read the Knowledge Bundle.
|
||||
|
||||
## Failure behavior
|
||||
|
||||
A failed Compilation Run must not redefine source truth.
|
||||
|
||||
Because `raw/` is immutable, the original evidence remains available.
|
||||
|
||||
Git provides recovery of erroneous wiki mutations.
|
||||
|
||||
## Portability
|
||||
|
||||
Moving the repository to another machine or agent runtime must not require migration of the canonical knowledge.
|
||||
|
||||
## Environments & access
|
||||
|
||||
Where is the canonical read/write surface? In the MVP the canonical surface is the Git working copy and its remote (e.g. `main` as the canonical read surface; producer branches `lease/<area>/<id>` as the write surface, promoted to `main` via `log.md`-recorded merges). There is no deployment or separate environment, server, or service in the MVP (AD-11).
|
||||
|
||||
Security/access for v1 (PRD A-1: personal/team-internal tool) is deferred: who may write `raw/` vs. `wiki/`, who may set `verified`-trust, and how Git repo access (read vs. write) is granted to team members are decided as D-9 in the Deferred section rather than fixed by this spine.
|
||||
|
||||
---
|
||||
|
||||
# Architectural Boundary
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph Sources
|
||||
C7[Context7]
|
||||
DOC[Vendor Docs]
|
||||
ARC[Arc42]
|
||||
BMADA[BMAD Archive]
|
||||
OTHER[Other Sources]
|
||||
end
|
||||
|
||||
subgraph Core["Wiki of Wikis Core"]
|
||||
RAW[Raw Source Collection]
|
||||
SCM[Operator Contract: schema/wiki-compiler.md]
|
||||
COMP[LLM Wiki Compiler]
|
||||
OKF[OKF Knowledge Bundle]
|
||||
end
|
||||
|
||||
subgraph Consumers
|
||||
HUMAN[Humans]
|
||||
BMAD[BMAD]
|
||||
CLAUDE[Claude Code]
|
||||
CODEX[Codex]
|
||||
CG[CodeGraph]
|
||||
SEARCH[Search / RAG]
|
||||
end
|
||||
|
||||
C7 --> RAW
|
||||
DOC --> RAW
|
||||
ARC --> RAW
|
||||
BMADA --> RAW
|
||||
OTHER --> RAW
|
||||
|
||||
RAW --> COMP
|
||||
OKF --> COMP
|
||||
COMP --> OKF
|
||||
SCM --> COMP
|
||||
|
||||
OKF --> HUMAN
|
||||
OKF --> BMAD
|
||||
OKF --> CLAUDE
|
||||
OKF --> CODEX
|
||||
OKF --> CG
|
||||
OKF --> SEARCH
|
||||
```
|
||||
|
||||
**Only the middle box is Wiki of Wikis.**
|
||||
|
||||
---
|
||||
|
||||
# Deferred
|
||||
|
||||
The following decisions are deliberately not fixed by this spine.
|
||||
|
||||
## D-1 — Source acquisition adapters
|
||||
|
||||
Deferred until sources must be imported automatically.
|
||||
|
||||
Examples:
|
||||
|
||||
- HTTP fetch
|
||||
- Context7 acquisition
|
||||
- Git repositories
|
||||
- PDFs
|
||||
- BMAD artifacts
|
||||
- local documentation trees
|
||||
|
||||
**Revisit when:** manual source materialization becomes a measurable bottleneck.
|
||||
|
||||
---
|
||||
|
||||
## D-2 — Retrieval engine
|
||||
|
||||
No search infrastructure is selected.
|
||||
|
||||
**Revisit when:** hierarchy, Markdown links and ordinary file search no longer allow an agent to find relevant Concepts reliably.
|
||||
|
||||
Possible future solutions are evaluated at that time rather than preselected.
|
||||
|
||||
---
|
||||
|
||||
## D-3 — Standalone compiler implementation
|
||||
|
||||
No Java, Python, Rust, TypeScript or other standalone application is selected.
|
||||
|
||||
**Revisit when:** the agent-instruction implementation proves insufficiently deterministic, testable or portable. (The determinism-enforcement mechanism of AD-17h / Q-6 is explicitly deferred and will likely live as an agent-instruction validator until then.)
|
||||
|
||||
---
|
||||
|
||||
## D-4 — MCP
|
||||
|
||||
No MCP Server is part of the MVP.
|
||||
|
||||
**Revisit when:** multiple Consumers need a shared runtime interface that cannot efficiently operate directly on the Knowledge Bundle.
|
||||
|
||||
---
|
||||
|
||||
## D-5 — Source deletion and replacement semantics
|
||||
|
||||
The MVP assumes additive Source ingestion.
|
||||
|
||||
**Revisit before:** supporting deletion, superseding or revocation of Sources.
|
||||
|
||||
---
|
||||
|
||||
## D-6 — Automatic stale-knowledge detection
|
||||
|
||||
Freshness metadata may be stored using OKF mechanisms.
|
||||
|
||||
Automatic detection of changed external truth is not part of the compiler core.
|
||||
|
||||
**Revisit when:** Sources representing mutable external systems become common.
|
||||
|
||||
---
|
||||
|
||||
## D-7 — Human review workflow
|
||||
|
||||
OKF metadata shall represent the resulting trust/review state.
|
||||
|
||||
A dedicated review workflow or UI is not selected.
|
||||
|
||||
**Revisit when:** multiple humans routinely review generated Concepts.
|
||||
|
||||
---
|
||||
|
||||
## D-8 — Query-to-Wiki writeback
|
||||
|
||||
Karpathy's pattern allows useful conclusions discovered during questions to become new Wiki knowledge.
|
||||
|
||||
This is not required for the first compiler MVP.
|
||||
|
||||
**Revisit after:** Source ingestion, provenance and incremental updates are demonstrably reliable.
|
||||
|
||||
## D-9 — Security & access model
|
||||
|
||||
For v1 no separate access model is selected: who may write `raw/` vs. `wiki/`, who may set `verified` trust metadata, and how team access (read vs. write) is granted follows the Git repository's own access controls.
|
||||
|
||||
**Revisit when:** more than one human routinely writes the wiki, or access boundaries become a requirement.
|
||||
|
||||
## D-10 — Exact OKF field-subset & validator
|
||||
|
||||
The exact OKF-0.2 field subset (list vs. map form of `sources`, `generated`/`verified`, `status` policing) and the concrete validator are pinned by `schema/wiki-compiler.md` (AD-1a) but not fixed by this spine.
|
||||
|
||||
**Revisit when:** the first validator / schema file is authored.
|
||||
|
||||
---
|
||||
|
||||
# Open Questions
|
||||
|
||||
Die folgenden Fragen sind nicht als offene Entscheidungen zu behandeln, solange sie oben über eine ableitbare Regel (hoher +++, D-Items) bereits entschieden sind:
|
||||
|
||||
- Dateisystem-Case und Physical vs. Logical Path: durch AD-7a (eine kanonische ID-Normalisierung) entschieden.
|
||||
- `log.md`-Format: durch AD-1a (Schema-Bindung) und § 9 von OKF entschieden.
|
||||
- Verhältnis `raw/` vs. extern referenzierbare Sources: durch AD-4b entschieden (Sources-Einträge dürfen beide referenzieren, nie `wiki/`-Pfade).
|
||||
|
||||
## Q-1 — AD-4 Source grounding
|
||||
|
||||
Should a generated Concept ever be allowed to use another generated Concept as its sole provenance?
|
||||
|
||||
Current assumption: **No.**
|
||||
|
||||
Existing Concepts may supply context and synthesis, but material claims must remain transitively grounded in actual Sources.
|
||||
|
||||
(The enforceability of this was tightened in AD-4a/b/c: provenance is claim-granular and `sources` entries never point at `wiki/` paths.)
|
||||
|
||||
## Q-2 — Agent ownership
|
||||
|
||||
Should humans routinely edit generated Concepts directly?
|
||||
|
||||
Current interpretation:
|
||||
|
||||
```text
|
||||
Human:
|
||||
supplies sources
|
||||
asks questions
|
||||
reviews
|
||||
corrects when necessary
|
||||
|
||||
Agent:
|
||||
performs routine wiki maintenance
|
||||
```
|
||||
|
||||
This follows the original LLM-Wiki model but does not prevent human edits.
|
||||
|
||||
The coexistence of human edit workflows and compiler runs is coordinated by AD-17e/f (dirty-tree protection, commit boundary as mutation boundary).
|
||||
|
||||
## Q-3 — Raw source location
|
||||
|
||||
Must all Sources be physically copied under `raw/`, or may `raw/` also contain stable references to external immutable resources?
|
||||
|
||||
This affects Source identity and reproducibility and should be resolved before implementation of Source intake.
|
||||
|
||||
(Partially answered by AD-4b: `sources` entries may reference `raw/` paths or external resources, never `wiki/` paths. Whether the external resources themselves must be materialized under `raw/` remains open.)
|
||||
|
||||
## Q-4 — Product name
|
||||
|
||||
Is **Wiki of Wikis** the final product name or only the project name?
|
||||
|
||||
This spine deliberately does not settle it: the frontmatter `name:` is the project name. **Owner:** Product Manager. **Revisit:** before the first external-facing documentation or a UX preparation.
|
||||
|
||||
## Q-5 — Source lifecycle & revocation
|
||||
|
||||
What happens to derived knowledge when a source is removed, replaced, or recognized as false?
|
||||
|
||||
This is currently only deferred (D-5: additive ingestion). The revocation case (false source) is not yet designed. **Owner:** Architecture. **Revisit:** before supporting deletion, superseding, or revocation of sources; must determine the revocation behavior (e.g., removing a provenance link from a Concept vs. deleting the Concept) without silently dropping claims that are still supported by other sources.
|
||||
|
||||
## Q-6 — Determinism envelope
|
||||
|
||||
How is "same Git state + same input set ⇒ same normalized bundle" enforced without a dedicated validator in the MVP (D-3, AD-17h)?
|
||||
|
||||
This is the enforcement mechanism behind the AD-17h determinism contract. It can live as an agent-instruction validator and must be confirmed mechanical before it becomes load-bearing on claims.
|
||||
|
||||
---
|
||||
|
||||
# Architecture Fitness Tests
|
||||
|
||||
The architecture remains conformant only while all of the following are true.
|
||||
|
||||
### FT-1 — No-runtime test
|
||||
|
||||
Delete every optional runtime component.
|
||||
|
||||
The contents of `wiki/` remain understandable.
|
||||
|
||||
### FT-2 — Agent replacement test
|
||||
|
||||
Replace Claude Code with another capable agent.
|
||||
|
||||
No Knowledge Bundle migration is required.
|
||||
|
||||
### FT-3 — Retrieval replacement test
|
||||
|
||||
Replace grep with vector search or vice versa.
|
||||
|
||||
No Concept format changes.
|
||||
|
||||
### FT-4 — Rebuildability test
|
||||
|
||||
Delete all derived indexes.
|
||||
|
||||
The canonical knowledge remains intact.
|
||||
|
||||
### FT-5 — Provenance test
|
||||
|
||||
Select a generated Concept.
|
||||
|
||||
Its material source basis can be traced to actual Source Material.
|
||||
|
||||
### FT-6 — Incrementality test
|
||||
|
||||
Ingest one additional Source.
|
||||
|
||||
Unaffected Concepts do not require regeneration.
|
||||
|
||||
### FT-7 — Portability test
|
||||
|
||||
Clone the repository onto another machine.
|
||||
|
||||
The Knowledge Bundle is readable without Wiki-of-Wikis-specific software.
|
||||
|
||||
### FT-8 — Scope test
|
||||
|
||||
For every proposed new component ask:
|
||||
|
||||
> Is this component required to transform Sources plus existing Knowledge into improved Curated Knowledge?
|
||||
|
||||
If **no**, it belongs outside the Compiler Core unless a later architecture decision explicitly changes this boundary.
|
||||
|
||||
### FT-9 — Human correctability test
|
||||
|
||||
Take a machine-produced Concept. A human must be able to correct or amend it directly (file edit + Git), and the correction must survive as long as it is not itself contradicted by new evidence — without requiring re-compilation of the whole bundle. (Carries the A-1/SM-C3 guardrail "nachvollziehbar/korrigierbar > Autonomie".)
|
||||
|
||||
### FT-10 — Determinism / reproducibility test
|
||||
|
||||
Over the same Git state and the same input set, two independent runs must produce the same bundle state (formalizes AD-17h). If they diverge, the AD-16 classification is not deterministic enough.
|
||||
@@ -0,0 +1,14 @@
|
||||
# source.md — Architecture Spine
|
||||
|
||||
Materialisiert als Quelle unter `raw/` (Story 1.2, AD-12).
|
||||
|
||||
- **Datei (Evidenz):** `architecture-spine-2026-08-14.md`
|
||||
- **Herkunft (kanonisch):** `_bmad-output/planning-artifacts/architecture/architecture-wow20-2026-08-14/ARCHITECTURE-SPINE.md`
|
||||
- **Kopie erstellt:** 2026-08-14
|
||||
- **Kurzbeschreibung:** Architektur-Spine inkl. AD-2 (raw/ vs. wiki/), AD-3 (raw/ immutable), AD-12 (Source-Akquisition außerhalb des Compiler-Kerns).
|
||||
|
||||
## Provenienz-Hinweis
|
||||
|
||||
- Diese `source.md` ist ein Artefakt, **keine Evidenz** (vgl. `raw/README.md`).
|
||||
- Herkunftspfade unter `_bmad-output/` sind generierte Planungs-Artefakte und im Repo nicht versioniert — Reproduktionshinweis, keine feste Referenz.
|
||||
- Ändert sich die Herkunftsquelle, wird eine **neue, datierte Datei** angelegt (AD-3); diese Datei bleibt unverändert.
|
||||
Reference in New Issue
Block a user