erstellt SPINE
This commit is contained in:
Michael Tamse
@@ -0,0 +1,40 @@
|
||||
---
|
||||
scope: Wiki of Wikis MVP
|
||||
purpose: build-substrate
|
||||
altitude: initiative
|
||||
topic: Wiki of Wikis Architecture-Spine (LLM Wiki Compiler / OKF 0.2 / agent-native compiler pipeline)
|
||||
updated: 2026-08-14T18:03
|
||||
---
|
||||
|
||||
- (event) Run gestartet: Create aus vollständigem Nutzer-Entwurf (Headless/Kein interaktives Coaching); PRD-wow20-2026-08-14 als treibendes Spezifikations-Input; Karpathy-Gist und OKF-SPEC 0.2 auf Web verifiziert (beide existent, Aussagen korrekt)
|
||||
- (decision) AD-1 Kanonischer Zustand = OKF Knowledge Bundle (wiki/); derived Artifacts (Indizes, Embeddings, Caches) niemals Source of Truth; gebunden an FR-9..FR-16, NFR-1..NFR-6
|
||||
- (decision) AD-2/3 Sources (raw/) und kuratiertes Wissen (wiki/) physisch+semantisch getrennt; Sources immutable; Kopie nach wiki/ ist keine Compilation; FR-1..FR-8
|
||||
- (decision) AD-4 Generiertes Wissen bleibt Source-grounded: Wiki-Links tragen Navigation/Beziehungen, ersetzen nicht Provenienz; Synthesekette transitiv auf echte Sources zurückführbar; deckt Karpathy/community 'never self-grounding' ab (Antwort auf PRD OQ-2/PRD-Frage Human-authored)
|
||||
- (decision) AD-5/6 Incremental Compilation (bestehendes Bundle als Input, nur betroffene Concepts ändern); Reasoning von Mutation getrennt (Analyze/Reconcile/Plan/Mutate/Validate); kein Misch-Modus; FR-4..FR-8, FR-12
|
||||
- (decision) AD-7 Concept-Identität = relativer OKF-Pfad ohne .md (z.B. flowable/timers); Rename ist semantische Änderung; AD-8 Beziehungen via Standard-Markdown-Links, Graph nur abgeleitet; AD-9 Discovery via Hierarchie+index.md; FR-9..FR-12, FR-15
|
||||
- (decision) AD-10 Compiler-Regeln agent-unabhängig (kanonischer Contract, Adapter als dünne Hüllen); AD-11 MVP: keine eigene LLM-Runtime, kein Serverprozess; AD-12 Source-Beschaffung außerhalb Compiler-Kern; AD-13 Retrieval gehört zu Consumers; FR-15/FR-16, NFR-6, MVP-Boundary
|
||||
- (decision) AD-14 Git liefert History/Diff/Attribution, nicht Domain-State; fachliche Provenienz bleibt in OKF; AD-15 Human- und Machine-Curation teilen dasselbe OKF-Modell (kein separates Datenmodell); FR-13, FR-14, NFR-2, NFR-4
|
||||
- (decision) Antwort PRD OQ-4 (Conflict Resolution): Compiler klassifiziert NEW/CONFIRMING/CORRECTING/CONTRADICTING/REDUNDANT; Widersprüche bleiben explizit erhalten statt still zusammengeführt; keine stillschweigende Auflösung
|
||||
- (assumption) A-Arch1 MVP: bestehende leistungsfähige Agent-Runtime (z.B. Claude Code) übernimmt Reasoning + Dateioperationen; kein eigener Serverprozess; Standalone-Implementierung deferred (D-3)
|
||||
- (assumption) A-Arch2 AD-4: generiertes Concept darf NIE als alleinige Provenienz eines anderen Concepts dienen; Wiki-Links sind Navigation, keine Grounding-Kette (entspricht Karpathy-Community) — als ASSUMPTION, Resttrennung offen (Q-1)
|
||||
- (assumption) A-Arch3 AD-6: Compiler darf Phasen technisch in einer Session ausführen; nur beobachtbarer Endzustand muss konsistent sein (keine Workflow-Engine nötig)
|
||||
- (version) OKF-Version als normative Bindung: Open Knowledge Format 0.2 (type einzige Pflicht-Frontmatter; sources/generated/verified [human:-Präfix]/status/stale_after optionale Familien; okf_version nur in Bundleroot-index.md; references/-Konvention); verifiziert gegen GoogleCloudPlatform/knowledge-catalog/okf/SPEC.md
|
||||
- (feature) Verteilte Producer-Konvention (Koordinierung): Producer-Adapter MÜSSEN wiki/<area>/Producers.md pflegen (kollektives 'who owns this'; Dürfen-Klausel über Production der jeweils anderen Bereiche); verhindert Last-Writer-Wins bei unkoordinierten Compilern; Cover auch Human-Curation
|
||||
- (direction) Feature-relevante Widersprüche (Contradictions verschiedener Producer, Klärung möglich, strittig für Build): CONTRADICTION-Discussion in log.md statt Autoklärung; direkt inkonsistent: Autoklärung entfällt
|
||||
- (constraint) PRD-Hard-Boundary: Kein Vector-/Embedding-/Knowledge-Graph-DB-/MCP-/Server-/Retrieval-Kern im MVP (Non-Goals); Relevanzbestimmung (PRD OQ-3) mit textuell-deterministischen Mitteln; Verfehlung = Conflict (AD-answer)
|
||||
- (constraint) Produktname: 'Wiki of Wikis' als Projektname für den MVP fixiert (PRD OQ-6 weiterhin offen für finalen Produktnamen/PM)
|
||||
- (question) Q-3 Source-Rohs/Externe Location: Müssen alle Sources physisch unter raw/ liegen oder darf raw/ stabile Referenzen auf externe immutable Ressourcen enthalten? (betrifft Source-Identität + Reproduzierbarkeit; muss vor FR-1-Implementierung geklärt werden)
|
||||
- (question) Q-2 Producer-Overlap-Subownership: Können sich Producer gegenseitig in nicht-owned Bereichen ergänzen/korrigieren (produktiv) oder ist Production strikt auf owned Bereiche beschränkt? (Standardfall-basierte Antwort als Design-Prinzip im Spine belassen)
|
||||
- (question) Q-1 AD-4 Source Grounding: Verbleibende Resttrennung — Dürfen Concepts überhaupt stillschweigend von anderen Concepts abgeleitet werden oder trennende Ownership/Link-Semantik?
|
||||
- (assumption) Seed-Architektur (Kein Star): distributed Concept Ownership via Produces-Datei ist das Referenzdesign; Meta-Monopol/Rad-Schirm (star), zentrale Coordination-DB, zentrale Producer/Pipeline-Orchestrierung, Request/Response-Queue sind abgelehnt als Zirkel
|
||||
- (decision) Stack bewusst minimal: leere Stack-Tabelle + Deklarations-Zwischenung (technologie-nicht-gebunden; alles was später eingeführt wird muss Begründung geben, warum Agent-Runtime+Filesystem nicht ausreicht)
|
||||
- (decision) Structural-Seed-Pfade fixiert (nicht Template-Kommentar): raw/, wiki/, schema/wiki-compiler.md, adapters/ (claude/, codex/); raw/ und wiki/ sind Architekturgrenzen; Rest ist Seed
|
||||
- (event) Tech-Currency-Review: 'Keine committed Entscheidung auf unverifizierter/veralteter Technologie'; OKF 0.2 aktuell und Spine-Darstellung auf jedem Punkt korrekt; Karpathy-Gist existent, aber Provenienz-und-kein-Self-Grounding-Verbot (AD-4/AD-16) stammt aus dem Kommentar-Thread, nicht wörtlich aus dem Gist — Spine ist strenger als Quelle, vertretbar; kein verstecktes LLM/Agent-Framework-Assumption
|
||||
- (event) Reconcile-Review: alle 16 FRs/7 NFRs getragen, keine Assumption-Widersprüche, keine Non-Goal-Rücknahme; OQ-2/3/4 beantwortet (AD-15/17/16); Hoch: OQ-6 Produktname stillschweigend final + OQ-5 Source-Lifecycle nur D-5; Mittel: A-1/SM-C3 Mensch-korrigierbar-Metrik ungetragen, NFR-3 nicht explizit gebunden, AD-3 immutable-vs-lifecycle-Spannung; Klein: A-3 kein GUI, status-stable-vs-draft
|
||||
- (event) OKF/Spec-Review: PASS — 16/16 FRs, 7/7 NFRs gecovert; Tickets AD-15/AD-17/AD-16 beantwortet; Konformitäts-Kleinigkeiten: F-1 Bundleroot/generation-rook nicht explizit (Unterordner-index.md ohne Frontmatter außer Bundleroot-Ausnahme), F-2 'ungültig' muss strukturell definiert werden (MUST-NOT-reject bei optionalen Feldern), F-3 log.md-Ledger muss §9-Datumsgruppen-Format halten; keine Dialekt-Risiken
|
||||
- (event) Adversarial-Review: F-1/F-2 CRITICAL, F-3/F-4 HIGH, F-5/F-6/F-7 MEDIUM; Kern: AD-17 Lease-Mechanismus/Scope/Staleness + log.md unter LWW (F-1); AD-7/AD-8 doppelte ID-Normalisierung & Linkform (F-2); AD-4 nur Concept-Ebene, kein Claim-Grounding, sources-tutorial auf wiki/ verboten (F-3); CONTRADICTING-vs-CORRECTING nicht deterministisch (F-4); Dirty-Tree-Schutz (F-5); schema/wiki-compiler.md ungebunden + log.md nicht OKF-tippbar (F-6); 'produktiver Nutzen' nicht entscheidbar, Determinismus-Kontrakt fehlt (F-7)
|
||||
- (event) Reviewer-Gate (Finalize): lint clean + 5 unabhängige Reviews (Rubrik / Tech-Currency / Adversarial / OKF-Spec / Reconcile). Ergebnis aggregiert und Korrekturen angewendet
|
||||
- (decision) Spine nach Gate geschärft: AD-4 um Claim-Granularit/source-grounding-Subrules ergänzt; AD-7 um ID-Normalisierung/Link-Form/Area-Zuordnung/Rename ergänzt; AD-16 um Defaults-Bewahrung; AD-17 um Lease-Vertrag/Root-Scope/Auto-Merge-Verbot/Dirty-Tree/Commit-Grenze/Auflösungs-Autorität/Determinismus; FT-9/FT-10 neu; Q-4/Q-5/Q-6, D-9/D-10, Environments&Acess neu
|
||||
- (version) Fitness-Tests erweitert auf FT-10 (Determinismus/Reproduzierbarkeit); Open Questions Q-1..Q-6; Deferred D-1..D-10
|
||||
- (direction) v1-Umsetzung mit Determinismus-Kontrakt (AD-17h/FT-10) als Agent-Instruktion bis D-3; Schema-Bindung schema/wiki-compiler.md als verbindliches Artefakt (AD-1a)
|
||||
- (event) Spine finalisiert (status: final, updated 2026-08-14); Reviews nach reviews/; lint clean
|
||||
+953
@@ -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.
|
||||
+366
@@ -0,0 +1,366 @@
|
||||
---
|
||||
name: Adversarial Review — ARCHITECTURE-SPINE.md (wiki-of-wikis-2026-08-14)
|
||||
type: adversarial-review
|
||||
adversary: independent
|
||||
status: final
|
||||
created: 2026-08-14
|
||||
target:
|
||||
- ARCHITECTURE-SPINE.md
|
||||
- prd.md (prd-wow20-2026-08-14)
|
||||
mandate: two mutually conformant units build incompatible systems
|
||||
---
|
||||
|
||||
# Adversarial Review — Wiki of Wikis Architecture Spine
|
||||
|
||||
## 0. Auftrag & Methode
|
||||
|
||||
Dieser Review greift die Architektur grundsätzlich als Gegner an. Für jeden Finding wird
|
||||
**ein Paar von Einheiten eine Ebene tiefer** konstruiert (zwei Producer, zwei Consumer,
|
||||
Mensch vs. Agent), bei dem **jede Einheit jede AD buchstäblich befolgt** — und das Paar
|
||||
dennoch inkompatible Systeme baut.
|
||||
|
||||
Der Spine verspricht in AD-17 ausdrücklich Schutz vor Last-Writer-Wins. Dieser Review zeigt,
|
||||
dass der Schutz an mehreren Stellen konzeptionell verrutscht und durch neue oder
|
||||
verschärfte Regeln geschlossen werden muss. Alle Findings nennen die beteiligten ADs und
|
||||
die konkrete Close-Regel.
|
||||
|
||||
**Adversarial Verdict:** Der Spine beschreibt ein konsistentes Architektur-Layering,
|
||||
aber er **pins keine der drei operativen Schnittstellen, an denen Producer und Producer
|
||||
bzw. Producer und Consumer aufeinandertreffen**: (a) die Lease-/Koordinations-Semantik
|
||||
(AD-17), (b) die Concept-ID-Normalisierung (AD-7) und (c) die Claim-Granularität der
|
||||
Provenienz (AD-4/Q-1). Solange diese drei Unterspezifikationen bestehen, folgen zwei
|
||||
konforme Einheiten garantiert mindestens einmal in einer von diesen Nachweisen zu
|
||||
inkompatiblen Bundles.
|
||||
|
||||
---
|
||||
|
||||
## Findings
|
||||
|
||||
### F-1 [CRITICAL] — AD-17 definiert keinen Lease-Mechanismus; der Konflikt-Bewahrungsartefakt selbst (log.md) liegt außerhalb des Leases
|
||||
|
||||
**Beteiligte ADs:** AD-5, AD-6, AD-7, AD-14, AD-16, AD-17 (und deren Bind: NFR-7, FR-8, FFr-13)
|
||||
|
||||
**Konstruiertes Paar:**
|
||||
|
||||
- **Einheit 1**: Compiler-Run A (Claude-Adapter), Area `flowable/`. Liest AD-17 und realisiert
|
||||
„Lease auf dem eigenen Workspace" als Lock-Datei `.wofw/leases/flowable.lock` außerhalb von `wiki/`.
|
||||
- **Einheit 2**: Compiler-Run B (Codex-Adapter) parallel, dieselbe Area. Realisiert „Lease"
|
||||
als Branch-Name `lease/flowable`. Auf einem zweiten Klon (FT-7 Portability erlaubt und
|
||||
fördert das).
|
||||
|
||||
Keine AD spezifiziert:
|
||||
|
||||
1. was ein Lease **ist** (Lockdatei? Branchname? Registry-Eintrag?),
|
||||
2. wie Leases **klon-übergreifend** koordiniert werden (bei Local-First + Portability gibt es
|
||||
keinen gemeinsamen Koordinationszustand),
|
||||
3. wie man ein Lease **atomar** erwirbt und wie Stale-Leases erkannt werden,
|
||||
4. ob `log.md` / `index.md` an der Bundle-Wurzel **innerhalb oder außerhalb** eines
|
||||
area-skopierten Leases liegen.
|
||||
|
||||
Beide Einheiten mutieren `wiki/flowable/timers.md` mit unterschiedlichen Synthesen, committen
|
||||
ihre Branches und führen nach main zusammen. Git auto-mergt getrennte Hunks textuell:
|
||||
Die Datei enthält anschließend **beide** Synthesen ungeprüft nebeneinander — ein stiller
|
||||
semantischer Merge. **Genau das verbietet AD-16** („Konflikte explizit erhalten, nie
|
||||
stillschweigend auflösen"), aber die Verletzung entsteht durch den Koordinationsmechanismus
|
||||
selbst, nicht durch Regelfolgefehler einer Einheit. Jede Einheit hat jede AD eingehalten.
|
||||
|
||||
Zusätzlich, und schärfer: Der einzige Ort, der einen Konflikt bewahren soll (`log.md`, AD-16
|
||||
und AD-17 Rule 4), liegt an der Bundle-Wurzel und damit **außerhalb jedes area-skopierten
|
||||
Leases**. Zwei Producer, die beide einen Konflikt dokumentieren, schreiben beide nach
|
||||
`log.md` kandidierend — **on log.md itself herrscht Last-Writer-Wins**. Der
|
||||
Konflikt-Bewahrungsmechanismus ist damit selbst die Stelle, an der Arbeit still
|
||||
überschrieben wird.
|
||||
|
||||
**Close-Regeln (neu/verschärft):**
|
||||
|
||||
- **AD-17a (Lease-Vertrag):** AD-17 muss definieren, was ein Lease ist und wie er erworben
|
||||
wird — gegen einen **eindeutigen Commit-Objektwert** (Merge-Base-Disziplin) und über einen
|
||||
einzigen, deterministischen Mechanismus (z. B. Branch-Prefix-Konvention `lease/<area>/<id>`
|
||||
ergänzt um eine Lockdatei **semantisch identisch realisiert** in jedem Adapter; die
|
||||
Realisierung darf nicht pro Adapter frei wählbar sein).
|
||||
- **AD-17b (Lease-Scope):** Das Lease muss ausdrücklich `wiki/` **inklusive `log.md`,
|
||||
`index.md` und aller Wurzel-Dateien** abdecken („Root-Scope"), sonst ist der
|
||||
Bewahrungsartefakt wehrlos.
|
||||
- **AD-17c (Kein stiller Auto-Merge):** Zwei Branches, die denselben Concept-Pfad modifiziert
|
||||
haben, dürfen **nicht** per textuellem Git-Auto-Merge zusammengeführt werden. Die
|
||||
Zusammenführung ist Compiler-vermittelt und durchläuft die AD-16-Klassifikation — mit
|
||||
explizitem `log.md`-Eintrag, falls die Inhalte nicht identisch sind.
|
||||
- **AD-17d (Lease-Held darf nicht committen „vergessen"):** Entweder Time-to-Live + Registrierung
|
||||
des Leases im Clon-Wurzelzustand oder Regel, dass unveröffentlichte Leases nach
|
||||
Run-Abbruch als stale gelten und `raw/` (immutable, AD-3) die Wiederherstellungsbasis ist.
|
||||
|
||||
---
|
||||
|
||||
### F-2 [CRITICAL] — AD-7 pinnt die Concept-ID nicht eindeutig: zwei Consumer/Producer rechnen denselben Baum auf zwei ID-Räume ab
|
||||
|
||||
**Beteiligte ADs:** AD-7, AD-8, AD-9, AD-14 (Renames als semantische Änderung), Bind FR-5/FR-6/FR-9–FR-12
|
||||
|
||||
**Konstruiertes Paar:**
|
||||
|
||||
- **Einheit 1** (Produzent, z. B. Codex-Adapter): schreibt einen Link als `[timers](flowable/timers)` —
|
||||
OKF-Stil, bundle-relativ, ohne `.md`, im Sinne der „Consistency Conventions — Concept identity:
|
||||
relativer OKF-Dateipfad **ohne** `.md`".
|
||||
- **Einheit 2** (Produzent, z. B. Claude-Adapter): schreibt denselben Link als `[timers](flowable/timers.md)` —
|
||||
„normale Markdown-Links" (AD-8) mit Dateiendung.
|
||||
|
||||
Beide Links sind in Markdown gültig. Ob sie dieselbe Concept-ID bezeichnen, hängt von einer
|
||||
Endungs-Normalisierung ab, die **nirgends** festgeschrieben ist:
|
||||
|
||||
1. **Endung:** `timers` vs `timers.md` — eine Einheit liest die ID mit, die andere ohne.
|
||||
2. **`index.md`:** AD-9 zeigt `spring/index.md`. Ist dessen Concept-ID `spring`, `spring/index`
|
||||
oder `spring/`? Nicht beantwortet. Link-Traversierung bricht je nach Default verschieden.
|
||||
3. **Case & Dateisystem:** `Timers.md` vs `timers.md` auf einem case-sensitiven System sind zwei
|
||||
Concept-IDs für dasselbe fachliche Wissen.
|
||||
4. **Area-Zuordnung:** AD-7 definiert die ID als den Pfad, aber **nicht, wohin ein fachliches
|
||||
Thema gehört**. Producer A legt „Timers"-Wissen unter `flowable/timers` an, Producer B unter
|
||||
`spring/timers`. Beide erzeugen „eigenständige Konzeptwesen" (FR-5) — beide AD-konform, ein
|
||||
Duplikat. AD-5 schützt das vorhandene Konzept sogar („nur betroffene Concepts verändern"),
|
||||
verschärft also die Vervielfachung statt sie zu verhindern.
|
||||
5. **Rename-Kaskade:** AD-7 erklärt Renames zu semantischen Änderungen — damit ist ein
|
||||
Umbenennen **erlaubt und erforderlich**, um die ID zu ändern, aber jede andere Einheit, die
|
||||
die alte ID gecacht hat (bewusst oder im Prompt-Kontext), aktualisiert sich nicht und
|
||||
referenziert ins Leere.
|
||||
|
||||
Beide Einheiten befolgen AD-7 buchstäblich und verwalten über denselben Baum **zwei
|
||||
inkompatible ID-Räume**.
|
||||
|
||||
**Close-Regeln:**
|
||||
|
||||
- **AD-7a (ID-Normalisierung):** genau eine kanonische Form festschreiben, z. B.
|
||||
`Kleinbuchstaben`, Pfad relativ zur Bundleroot, ohne Endung, `index.md` → Area-Pfad,
|
||||
keine Trailendepunkte. Mit Beispieltabelle (`flowable/timers`, `spring`, `spring/testing`).
|
||||
- **AD-7b (Link-Form):** AD-8 muss die eine erlaubte Linkform festlegen (bundle-relativ mit
|
||||
oder ohne Endung — eine davon, nicht beides).
|
||||
- **AD-7c (Area-Zuordnung):** eine Zuordnungsregel für „wohin gehört ein Thema" ergänzen
|
||||
(Relevanzbestimmung ist AD-17-Anhang bereits auf textuelle Mittel festgelegt; dieselbe
|
||||
textuelle Determiniertheit muss auch die **Ziel-Area** determinieren, z. B. via
|
||||
bestehendem `index.md`-Link oder Toplevel-Kollision-Halten an bestehenden Pfaden).
|
||||
- **AD-7d (Rename-Verträglichkeit):** Rename = neues Objekt + expliziter
|
||||
Redirect-/Deprecation-Eintrag im `log.md` (oder `references/`-Konvention von OKF), damit
|
||||
alte IDs maschinell ausfindig gemacht werden können.
|
||||
|
||||
---
|
||||
|
||||
### F-3 [HIGH] — AD-4/Q-1 verankern Provenienz nur auf Concept-Ebene; ein Consumer kann belegte von kontextuellen Aussagen nicht mechanisch unterscheiden
|
||||
|
||||
**Beteiligte ADs:** AD-4 (ASSUMPTION), Q-1, AD-13, Bind FR-3/FR-7/FR-8/NFR-7, FT-5, SM-3
|
||||
|
||||
**Konstruiertes Paar:**
|
||||
|
||||
- **Einheit 1** (Compiler): erzeugt ein synthetisiertes Concept (Synthese aus A und B gemäß
|
||||
AD-4/FR-7). Im Frontmatter stehen `sources:` mit den **mitgeführten** Source-Verweisen
|
||||
(AD-4: „relevante Source-Provenienz in das resultierende Concept übernehmen"). Der Body
|
||||
mischt drei belegte Claims mit zwei reinen Inferenz-Umformulierungen. Der Compiler erfüllt
|
||||
damit FT-5 und SM-3 buchstäblich („ein erzeugtes Concept kann auf Sources zurückgeführt
|
||||
werden" — Concept-Ebene).
|
||||
- **Einheit 3** (strenger Consumer, auch ein LLM-Agent): liest dasselbe Bundle und kann pro
|
||||
Satz **keine** Grounding-Granularität mechanisch erkennen. Der Frontmatter-`sources`-Block
|
||||
gilt für das ganze Dokument; Inference-Formulierungen sehen identisch „belegt" aus.
|
||||
|
||||
Beide Einheiten sind AD-konform. Die **Belegstärke** der konsumierten Aussagen divergiert
|
||||
jedoch: Ein strenger Consumer verwirft Inferenzen als unbelegt, ein laxer Consumer behandelt
|
||||
sie als evidential. Q-1 beantwortet nur, ob ein generiertes Concept ein anderes generiertes
|
||||
Concept als **alleinige** Provenienz verwenden darf („No") — es installiert damit keinerlei
|
||||
maschinell prüfbare Regel auf **Aussage- oder Blockebene**. NFR-7 („Graceful Partial
|
||||
Knowledge", Unsicherheit explizit) wird auf Concept-Ebene deklariert, aber nie in einer
|
||||
satzgranularen Struktur erzwingbar.
|
||||
|
||||
**Close-Regeln:**
|
||||
|
||||
- **AD-4a (Claim-Granularität):** Provenienz muss pro behauptender Einheit (Block/Absatz)
|
||||
referenzierbar sein, nicht nur pro Concept. Mindestform: jede belegte Aussage trägt einen
|
||||
Inline-Verweis auf `raw/`-Evidenz; Kontext-/Synthese-Umformulierungen erhalten explizit
|
||||
einen Kontext-Marker („aus <Concept-Pfad> übernommen, nicht selbst belegt").
|
||||
- **AD-4b (Sources-Ziel):** `sources`-Einträge dürfen auf `raw/` oder auf extern referenzierte
|
||||
Evidenz verweisen, **nie** auf einen `wiki/...`-Concept-Pfad (Wiki-Links bleiben AD-8;
|
||||
Provenienz und Beziehung werden formatseitig disambiguiert).
|
||||
- **AD-4c (Q-1 verbindlich):** die Annahme „ein generiertes Concept darf nie ein anderes
|
||||
generiertes Concept als *einzige* Provenienz führen" wird von einer ASSUMPTION in eine
|
||||
Regel überführt und in die (geplante) `schema/wiki-compiler.md`-Validierung aufgenommen.
|
||||
|
||||
---
|
||||
|
||||
### F-4 [HIGH] — AD-16 vs. AD-17: die Klassifikation „CONTRADICTING vs. CORRECTING" entscheidet, wer das Auflösungs-Artefakt besitzt — und ist nicht arbitrierbar
|
||||
|
||||
**Beteiligte ADs:** AD-16, AD-17 Rule 2/4, AD-15, AD-5, FR-8/FR-13, NFR-7
|
||||
|
||||
**Konstruiertes Paar:**
|
||||
|
||||
- **Einheit 1**: klassifiziert eine neue Quelle als CONTRADICTING → lässt den Concept-Bereich
|
||||
**unangetastet**, dokumentiert den Disagreement in `log.md` (AD-16 wörtlich).
|
||||
- **Einheit 2**: klassifiziert **dieselbe** Quelle als CORRECTING → **revidiert** das
|
||||
Concept (AD-16 erlaubt „CORRECTING → revise existing knowledge").
|
||||
|
||||
Beide Handlungen sind AD-16-konform. Die Kategorien sind „konzeptionell" (AD-16 verzichtet
|
||||
explizit auf eine interne Datenstruktur und damit auch auf ein deterministisches
|
||||
Entscheidungskriterium). Die Adversarität liegt darin, dass die Klassifikation **besitzt**,
|
||||
was passiert: CONTRADICTING → Bewahrung, CORRECTING → Revision. Wer das Auflösungs-Artefakt
|
||||
(Concept **oder** log.md) besitzt, hängt damit an der Willkür derselben Einheiten, die auch
|
||||
die Schiedsrichter sein sollen. Das Lease- und Konvergenz-Modell (AD-17 Rule 4) kann hier
|
||||
nicht arbitrieren, weil „produktiver Nutzen/Beitrag" als Auflösungsprinzip aufgerufen wird,
|
||||
bevor überhaupt eine gemeinsame Bestimmung darüber existiert, ob ein Beitrag überhaupt
|
||||
anzurühren ist. Ergebnis: Ein Paar aus einem bewahrenden und einem revidierenden Producer
|
||||
ist nach allen ADs legal — und eine der beiden feindlichen Bundles stammt aus einer AD-16-
|
||||
konformen Einheit, deren Arbeit von der anderen Einheit als „wirksam ersetzt" gilt.
|
||||
|
||||
**Close-Regeln:**
|
||||
|
||||
- **AD-16a (Default-Vorspann):** deterministische Vorgabe, z. B. „bei Widerspruch gilt
|
||||
Standard-Bewahrung (CONTRADICTING), sofern die neue Quelle nicht mit expliziter Evidenz die
|
||||
alte strikt ersetzt; andernfalls CORRECTING mit dokumentierter Ersetzungslogik".
|
||||
- **AD-16b (Klassifikations-Pflicht):** die Klassifikation inkl. Begründung muss **im selben
|
||||
Artefakt** wie die Mutation landen (log.md-Eintrag angebunden an den mutierten Concept-Pfad),
|
||||
damit die Auflösungs-Entscheidung reproduzierbar und damit die Ownership auditierbar ist.
|
||||
|
||||
---
|
||||
|
||||
### F-5 [MEDIUM] — AD-17 Rule 2 schützt nur den *committed* Input; der dirty Working Tree eines Producers wird von anderer Einheit still zerstört (AD-15/FR-13-Loch)
|
||||
|
||||
**Beteiligte ADs:** AD-17 Rule 2, AD-6 (Mutation), AD-5, AD-15, Q-2, FR-13, AD-14
|
||||
|
||||
**Konstruiertes Paar:**
|
||||
|
||||
- **Einheit 1** (Mensch): bearbeitet direkt ein Concept (`wiki/flowable/timers.md`), nach
|
||||
AD-15/Q-2 ausdrücklich erlaubt, **noch nicht committet** (dirty working tree).
|
||||
- **Einheit 2** (Compiler, AD-10-agent-unabhängig): liest gemäß AD-17 Rule 2 **nur committed
|
||||
Inhalte** → die menschliche Änderung ist de jure kein Input. Nach AD-6 Mutation läuft der
|
||||
Adapter in die Arbeitskopie, und der Adapter-Mechanismus (checkout/rebase/clean) trifft auf
|
||||
die dirty Datei.
|
||||
|
||||
Die Spannung: Rule 2 verhindert, dass uncommittete Inhalte „Input" werden — sie verhindert
|
||||
**nicht**, dass der Mechanismus der anderen Einheit (Rebase/Checkout/Clean im eigenen
|
||||
Adapter-Vokabular) die **uncommittete Arbeitskopie** der Einheit 1 genauso still entfernt.
|
||||
Ein Rebase/Checkout in Run B wirft die uncommittete Datei von Einheit 1 ohne Git-Konflikt und
|
||||
ohne log.md-Eintrag weg. Damit wird FR-13 („menschliche Inhalte nicht allein wegen fehlender
|
||||
Herkunft entfernen") und AD-15 verletzt, ohne dass Einheit 2 irgendeine AD gebrochen hat.
|
||||
|
||||
**Close-Regeln:**
|
||||
|
||||
- **AD-17e (Dirty-Tree-Schutz):** vor jeder Mutation muss der Producer die Arbeitskopie für
|
||||
den zu mutierenden Bereich prüfen; nicht-committete, fremde Änderungen sind zu schützen
|
||||
(stash/divert in eine geschützte Scratch-Zone), und jeder verdrängte uncommittete Inhalt ist
|
||||
in `log.md` zu dokumentieren.
|
||||
- **AD-14/AD-17f (Commit-Grenze als einzige Mutationsgrenze):** die Mutation darf nur auf
|
||||
Verzeichnis/Commit-Ebene wirken, die eine fremde dirty Arbeit nie als Side-Effekt von
|
||||
checkout/rebase löscht.
|
||||
|
||||
---
|
||||
|
||||
### F-6 [MEDIUM] — AD-1/FR-9 binden an „OKF 0.2", aber der Spine bindet weder das Feld-Subset noch den Validator; Spine-Artefakte (log.md) sind nicht OKF-tippbar
|
||||
|
||||
**Beteiligte ADs:** AD-1, FR-9, AD-16 (log.md), AD-9 (index.md), AD-10, NFR-5, FT-1, Consistency-Conventions „Errors: kein erfolgreicher Run bei ungültigem Bundle"
|
||||
|
||||
**Konstruiertes Paar:**
|
||||
|
||||
- **Einheit 1** (Claude-Adapter): emittiert `sources: [raw/foo.md, raw/bar.md]` (Liste von
|
||||
Strings).
|
||||
- **Einheit 2** (Codex-Adapter): emittiert OKF-Map-/Objekt-Form bzw. deklariert
|
||||
`okf_version: "0.2"` nur in der Bundleroot-`index.md` (PRD § 13 nennt beides „optional").
|
||||
|
||||
Beide behaupten OKF-0.2-Konformität. Es gibt **keinen Validator** (siehe Consistency
|
||||
Conventions: „kein erfolgreicher Run bei ungültigem Bundle" — aber ungültig *worum*?). Der
|
||||
Spine verweist auf `schema/wiki-compiler.md`, aber dieser Ordner ist im Structural Seed nur
|
||||
Dekoration und wird von **keiner** AD als verbindliches Artefakt gebunden. AD-10 verbietet
|
||||
Adaptern abweichende Knowledge-Semantik — ohne objektives Validitätsprädikat ist „abweichend"
|
||||
nicht entscheidbar.
|
||||
|
||||
Zweitens sind **Spine-eigene Artefakte** nicht OKF-getippt:
|
||||
|
||||
- `log.md` (AD-16): eine nicht gesperrte `.md`-Datei. OKF verlangt, dass nicht gesperrte
|
||||
Bundledateien ein `type` tragen. `log.md` hat keines — entweder ist das Bundle
|
||||
OKF-inkonform, oder log.md ist ein undefinierter Concept-Typ, sodass zwei Consumer uneins
|
||||
sind, ob es ein Concept ist.
|
||||
- `index.md` als Discovery-Ebene (AD-9): OKF lässt Bundleroot-`index.md` mit
|
||||
`okf_version` optional zu; AD-9 macht sie faktisch zur Pflicht-Discovery — das ist eine
|
||||
Spine-Konvention über OKF hinaus, deren Consumer-Verträglichkeit ungeprüft ist.
|
||||
|
||||
Damit bleibt FT-1/NFR-5 („keine Runtime", „Read ohne Prozess") nur oberflächlich erhalten:
|
||||
Nicht-Runtime gilt für das **Lesen von Markdown**; das **Verstehen** der Spine-Konventionen
|
||||
(log.md-Semantik, Lease-Marker, index-Discovery) setzt Interpretationswissen voraus, das zwei
|
||||
Consumer unterschiedlich ausführen. Lesbarkeit ≠ Konformität.
|
||||
|
||||
**Close-Regeln:**
|
||||
|
||||
- **AD-1a (Schema-Bindung):** `schema/wiki-compiler.md` wird als **verbindlich** gebunden:
|
||||
Es pinnt (i) das exakte OKF-0.2-Feld-Subset (sources-Form als Liste vs. Map, generiert/verified,
|
||||
status), (ii) `log.md` als dokumentiertes Artefakt **mit eigenem `type`**, (iii) die
|
||||
index-Discovery-Regel, (iv) die OKF-Validitätsprädikate.
|
||||
- **AD-1b (Validator-Regel):** eine Regel, wie Konformität **geprüft** wird (auch wenn der
|
||||
Validator selbst bis D-3 als Agent-Instruktion lebt): „kein erfolgreicher Run bei
|
||||
OKF-invalidem Bundle laut schema/wiki-compiler.md".
|
||||
- **NFR-5/AD-1c (FT-1 mechanisch):** FT-1 wird als Regel formuliert: „Entferne alle
|
||||
Runtime-Komponenten; der Reader benötigt nur Markdown + eine statisch abgelegte
|
||||
Konventions-Kurzfassung, um Anzahl, Bedeutung und Grounding aller Artefakte (incl. log.md)
|
||||
eindeutig zu bestimmen."
|
||||
|
||||
---
|
||||
|
||||
### F-7 [MEDIUM] — AD-17 Rule 4: „produktiver Nutzen als Auflösungs-Prinzip" ist nicht entscheidbar; zwei Merge-Autoritäten lösen denselben Konflikt gegensätzlich auf
|
||||
|
||||
**Beteiligte ADs:** AD-17 Rule 4, AD-16, AD-14, PRD OQ-4 (Konflikt-Auflösung)
|
||||
|
||||
**Konstruiertes Paar:**
|
||||
|
||||
- **Einheit 1** (Merge-Autorität / Maintainer A): führt den Konflikt in `flowable/timers.md`
|
||||
zugunsten von Quelle A auf, dokumentiert die Ablehnung von Quelle B in `log.md`.
|
||||
- **Einheit 2** (Merge-Autorität / Maintainer B): führt denselben Konflikt zugunsten von
|
||||
Quelle B auf, dokumentiert die Ablehnung von Quelle A in `log.md`.
|
||||
|
||||
Beide sind AD-16/AD-17-konform (Konflikt explizit erhalten, offengelegt). Das Prinzip
|
||||
„produktiver Nutzen/Beitrag zählt als Auflösungs-Prinzip" ist aber **weder mechanisch noch
|
||||
authoritativ bestimmt**: Es sagt nichts darüber, wer entscheidet und anhand welcher
|
||||
beobachtbaren Kriterien. Zwei voneinander unabhängige Merge-Läufe über demselben Git-Zustand
|
||||
produzieren unterschiedliche Bundles, beide konform. Damit ist die Reproduzierbarkeit des
|
||||
Bundles (eine Kernanforderung aus FT-7 / SM-1) nicht gegeben — derselbe Git-Zustand kann zu
|
||||
zwei kanonisch gültigen, aber inkompatiblen Bundles führen.
|
||||
|
||||
**Close-Regeln:**
|
||||
|
||||
- **AD-17g (Auflösungs-Autorität):** festlegen, **wer** eine AD-16-Kollision auflöst
|
||||
(MVP: der Compiler-Run, der das Lease hält, nach AD-16a-Default; menschliche Eskalation nur
|
||||
bei Nicht-Entscheidbarkeit), und dass die Auflösung an denselben Commit/dieselbe
|
||||
Log-Dokumentation gebunden ist (Kryptominimal: Commit-Hash + Klassifikation im Eintrag).
|
||||
- **AD-17h (Determinismus-Kontrakt):** über demselben Git-Zustand und derselben Input-Menge
|
||||
müssen zwei unabhängige Läufe **denselben** Bundle-Zustand erzeugen (als expliziter
|
||||
Fitness-Test analog FT-6), andernfalls ist die AD-16-Klassifikation nicht deterministisch
|
||||
genug.
|
||||
|
||||
---
|
||||
|
||||
## 3. Querschnitt-Lücken und wo Autorität fehlt
|
||||
|
||||
Die Findings reihen sich in ein Muster: **der Spine beschreibt die Data-Ebene präzise und
|
||||
delegiert die Koordination an „den ausführenden Adapter", ohne dem Adapter einen
|
||||
deterministischen Vertrag zu geben.**
|
||||
|
||||
- **D-3 / D-7 / D-1 bleiben offen**, während die Konformität des Bundles (F-6) davon abhängt,
|
||||
dass der Validator irgendwann existiert. Solange der Validator liegt, ist „OKF-konform"
|
||||
eine Behauptung, kein Prädikat.
|
||||
- **PRD OQ-4** (welche Konflikte darf der Compiler selbst auflösen) ist im Spine als
|
||||
AD-17 Rule 4 nur scheinbar beantwortet — sie beantwortet das *woran*, nicht das *wer* (F-7).
|
||||
- **Q-1** im Spine („Current assumption: No") hat bisher keine Regelwirkung (F-3).
|
||||
- **Q-2** (dürfen Menschen generierte Concepts direkt editieren?) ist für die
|
||||
Dirty-Tree-Kollision (F-5) relevant, da der Spine mit „verhindert nicht menschengemachte
|
||||
Edits" eine Koexistenz erlaubt, ohne die Koexistenz zu koordinieren.
|
||||
|
||||
---
|
||||
|
||||
## 4. Empfohlener Regel-Katalog (neu/verschärft)
|
||||
|
||||
| # | Regel | Ersetzt/ergänzt | Schließt |
|
||||
|---|---|---|---|
|
||||
| R1 | Lease-Vertrag (Mechanismus, Commit-Bindung, stalo) | AD-17a–17d | F-1 |
|
||||
| R2 | Root-Scope des Leases inkl. `log.md`/`index.md` | AD-17b | F-1 |
|
||||
| R3 | Kein textueller Git-Auto-Merge über identischen Concept-Pfad; Merge nur über AD-16-Klassifikation | AD-17c | F-1 |
|
||||
| R4 | Eine kanonische Concept-ID-Normalisierungsform + eine erlaubte Linkform | AD-7a/7b | F-2 |
|
||||
| R5 | Deterministische Area-Zuordnung für neue Concepts | AD-7c | F-2 |
|
||||
| R6 | Rename als neues Objekt + Redirect/Deprecation in log.md | AD-7d | F-2 |
|
||||
| R7 | Claim-granulare Provenienz; `sources` nie auf `wiki/`-Pfade; Q-1 → Regel | AD-4a–4c | F-3 |
|
||||
| R8 | AD-16-Generalvorschrift: Bewahrung als Default; Klassifikation publik, an Mutation gebunden | AD-16a/16b | F-4, F-7 |
|
||||
| R9 | Dirty-Tree-Schutz; Commit-Grenze als Mutationsgrenze; Verdrängung dokumentieren | AD-17e/17f | F-5 |
|
||||
| R10 | `schema/wiki-compiler.md` verbindlich; log.md-tipbar; FT-1 mechanisch | AD-1a–1c | F-6 |
|
||||
| R11 | Auflösungs-Autorität + Determinismus-Contract (gleicher Zustand → gleiches Bundle) | AD-17g/17h | F-7 |
|
||||
|
||||
---
|
||||
|
||||
*Ende des Adversarial Reviews.*
|
||||
+134
@@ -0,0 +1,134 @@
|
||||
# Review — Spec Coverage & OKF 0.2 Conformance of the Architecture Spine
|
||||
|
||||
- **Review target:** `ARCHITECTURE-SPINE.md` (Wiki of Wikis, 2026-08-14)
|
||||
- **Reference:** `prd.md` (PRD — Wiki of Wikis, 2026-08-14)
|
||||
- **Normative standard:** OKF 0.2 — `https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md`
|
||||
- **Reviewed:** 2026-08-14
|
||||
- **Verdict:** PASS with recommendations — all FR-1..FR-16 and NFR-1..NFR-7 are governed; all three architecture-delegated PRD tickets (OQ-2/3/4) are answered; no statement produces a non-conformant bundle or an "own OKF dialect". Four low-severity conformance hardening points and one product-level note (PRD OQ-6) are recorded.
|
||||
|
||||
---
|
||||
|
||||
## A. SPEC COVERAGE — every FR / NFR has a governing entry
|
||||
|
||||
Legend: ✅ governed (AD), 🟡 governed via convention table / Deferred / Open Question.
|
||||
|
||||
### A.1 Functional requirements FR-1 .. FR-16
|
||||
|
||||
| FR | Title (PRD) | Governing entry (spine) | Status |
|
||||
|---|---|---|---|
|
||||
| FR-1 | Sources bereitstellen | AD-2 (separation), AD-3 (immutable), AD-12 (acquisition outside core), Capability Map | ✅ |
|
||||
| FR-2 | Sources und Curated Knowledge unterscheiden | AD-2, Consistency "Canonical evidence raw/ vs Canonical knowledge wiki/", §12-layout ticket | ✅ |
|
||||
| FR-3 | Provenienz bewahren | AD-4 (source-grounded, provenance propagation), Consistency "Provenance \| OKF `sources`", FT-5 | ✅ |
|
||||
| FR-4 | Sources gegen bestehendes Wissen verarbeiten | AD-5 (incremental pipeline, existing knowledge as input) | ✅ |
|
||||
| FR-5 | Concepts erzeugen | AD-5, AD-7 (identity), Capability Map | ✅ |
|
||||
| FR-6 | Bestehende Concepts aktualisieren | AD-5, AD-7, AD-16 (classify before mutation) | ✅ |
|
||||
| FR-7 | Wissen synthetisieren | AD-4 (multi-source synthesis w/ provenance), AD-5 | ✅ |
|
||||
| FR-8 | Widersprüche sichtbar behandeln | AD-16 (NEW/CONFIRM/CORRECT/CONTRADICT/REDUNDANT; explicit log.md disagreements) | ✅ |
|
||||
| FR-9 | OKF-konforme Concepts erzeugen | AD-1 (OKF bundle canonical), AD-15 (trust metadata per OKF), Stack "Metadata \| YAML Frontmatter according to OKF", FR-9 conventions | ✅ |
|
||||
| FR-10 | Concepts miteinander verlinken | AD-8 (standard Markdown links, no proprietary link format) | ✅ |
|
||||
| FR-11 | Progressive Discovery ermöglichen | AD-9 (index.md + hierarchy), AD-8 | ✅ |
|
||||
| FR-12 | Knowledge Bundle inkrementell weiterentwickeln | AD-5 (incremental), AD-6 (reasoning/mutation separation), FT-6 | ✅ |
|
||||
| FR-13 | Vorhandene menschliche Kuratierung berücksichtigen | AD-15 (same model for human/machine; no deletion without source basis), AD-16 (conflict must surface) | ✅ |
|
||||
| FR-14 | Änderungen nachvollziehbar machen | AD-14 (Git as history), Consistency "Update history \| Git + optional OKF log.md" | ✅ |
|
||||
| FR-15 | Tool-unabhängigen Zugriff ermöglichen | AD-1 (bundle readable w/o derived artifacts), AD-8, AD-9, AD-13, FT-1/FT-7 | ✅ |
|
||||
| FR-16 | Consumer vom Compiler entkoppeln | AD-10 (agent-independent contract), AD-13 (retrieval belongs to consumers), FT-2/FT-3 | ✅ |
|
||||
|
||||
**Result FR:** 16 / 16 covered. No FR appears unaddressed anywhere in the spine.
|
||||
|
||||
### A.2 Non-functional requirements NFR-1 .. NFR-7
|
||||
|
||||
| NFR | Title (PRD) | Governing entry (spine) | Status |
|
||||
|---|---|---|---|
|
||||
| NFR-1 | Portability | AD-1 (canonical = portable OKF bundle), Operational Envelope "Portability", FT-7 | ✅ |
|
||||
| NFR-2 | Human Readability | AD-1 (understandable w/o derived artifacts), AD-15 (Markdown-first), Stack "Content \| Markdown" | ✅ |
|
||||
| NFR-3 | Agent Readability | AD-9 (progressive discovery), AD-13 (standard file ops), AD-8 | ✅ |
|
||||
| NFR-4 | Version-Control Friendliness | AD-14 (textual diffs), AD-8 (plain links), Operational Envelope "Git recovery" | ✅ |
|
||||
| NFR-5 | No Mandatory Runtime | AD-11 (no own runtime / no server), AD-13, Operational Envelope "Local-first", FT-1 | ✅ |
|
||||
| NFR-6 | Vendor Independence | AD-10 (agent-independent), AD-13, Stack "LLM/Agent runtime not bound" | ✅ |
|
||||
| NFR-7 | Graceful Partial Knowledge | AD-4 (uncertainty allowed), AD-15 (draft\|stable\|deprecated, generated-unverified default), AD-16 (explicit disagreement), D-6 | ✅ |
|
||||
|
||||
**Result NFR:** 7 / 7 covered.
|
||||
|
||||
### A.3 PRD architecture-delegated tickets and remaining Open Questions
|
||||
|
||||
The PRD explicitly hands three questions to the architecture; the spine must answer each, not silently drop it.
|
||||
|
||||
| PRD item | What was delegated | Spine response | Status |
|
||||
|---|---|---|---|
|
||||
| **OQ-2 Verification Workflow** (with NOTEs for PM on trust metadata, v1 default: machine-generated & unverified) | Which `verified` / `human:`-prefix metadata the compiler emits; how human review is marked | **AD-15**: generated `{by, at}` unverified by default; `verified` only with `human:`-prefixed actor; lifecycle via `status`/`stale_after`; explicit v1 default = generated, no `verified`. Also D-7 (review workflow/UI deferred, trust state still represented via OKF). | ✅ Answered |
|
||||
| **OQ-3 Compilation Scope** (+ §12 Relevanzbestimmung) | How the compiler finds relevant existing concepts for a new source, WITHOUT embedding/vector infra (must be textual & deterministic) | **AD-17** "Wichtig — funktionaler Grund" block: relevance determination restricted to textual, deterministic means (grep/ripgrep, Markdown traversal, link-following); vector/embedding infrastructure explicitly excluded. Also D-2 (retrieval engine deferred) consistent. | ✅ Answered |
|
||||
| **OQ-4 Conflict Resolution** (+ A-3 CLI/file-based constraint) | Which conflicts the compiler may resolve itself vs. defer to the user, implementable CLI-only | **AD-16**: classification NEW/CONFIRM/CORRECT/CONTRADICT/REDUNDANT; contradictions preserved explicitly, never silently merged; uncertainty may be part of a concept. **AD-17 (4)**: competing producer changes resolved by "productive value" principle into `log.md`, blocks never silently deleted/overwritten/documented+exposed. Fully file-based (`log.md`), no GUI. | ✅ Answered |
|
||||
|
||||
Other PRD Open Questions (not explicitly mandated to the spine, but checked for completeness):
|
||||
|
||||
| PRD item | Spine treatment | Status |
|
||||
|---|---|---|
|
||||
| OQ-1 Human-authored Concepts (first-class vs tolerated) | **AD-15**: human and machine curation share the same OKF Concept model; existing human content is persistent knowledge that must not be dropped for lacking provenance — i.e. first-class. Spine Q-2 (Agent ownership) further positions humans. | ✅ Addressed |
|
||||
| OQ-5 Source Lifecycle (remove/replace/false source) | **D-5** (Source deletion and replacement semantics) — explicitly deferred with "Revisit before:" trigger. Also AD-3 acknowledgment. | 🟡 Addressed as Deferred |
|
||||
| OQ-6 Product Name | Not addressed anywhere in the spine. Product (not architecture) decision; low severity, listed for completeness only. | 🟡 Not addressed (out of spine mandate) |
|
||||
|
||||
### A.4 Coverage conclusion
|
||||
|
||||
No FR-1..FR-16 and no NFR-1..NFR-7 is missing a governing AD / convention / Deferred / Open-Question entry. All three explicitly delegated architecture tickets (OQ-2, OQ-3, OQ-4) are answered explicitly in the spine (AD-15, AD-17, AD-16/AD-17); none is silently dropped. Secondary OQ-1 and OQ-5 are handled (AD-15 / D-5). Only the product-name question OQ-6 is unaddressed — a legitimately non-architecture item.
|
||||
|
||||
---
|
||||
|
||||
## B. OKF 0.2 CONFORMANCE — spine claims vs. the actual spec
|
||||
|
||||
Verified against `okf/SPEC.md` at `GoogleCloudPlatform/knowledge-catalog` (v0.2).
|
||||
|
||||
### B.1 Claims that are fully conformant (verified)
|
||||
|
||||
| Spine claim | Spec basis | Verdict |
|
||||
|---|---|---|
|
||||
| AD-1: canonical knowledge is an OKF-0.2-conformant Markdown Knowledge Bundle; bundles must remain understandable without derived artifacts | Spec: bundle of Markdown files w/ YAML frontmatter; conformance §11 | ✅ Identical |
|
||||
| FR-9/AD-1: `type` is the only required frontmatter key; `okf_version: "0.2"` declared only in a bundle-root `index.md` | §4.1 (`type` only always-required key); §8/§12 (okf_version only permitted in bundle-root index.md) | ✅ Exact match |
|
||||
| AD-7: Concept identity = relative path within bundle without `.md` (e.g. `flowable/timers`); renames are semantic changes | §2 Concept ID: "path ... with the `.md` suffix removed" | ✅ Exact match |
|
||||
| AD-15: generated `{by, at}` unverified default; `verified` with `human:`-prefix actor = human-reviewed; `status` `draft\|stable\|deprecated`; optional `stale_after`; v1 default machine-generated/unreviewed | §5.2/§5.3 (`human:` prefix ⇔ human-reviewed), §5.4 (status values; absent ⇒ stable), §5.5 (stale_after date) | ✅ Exact match |
|
||||
| AD-9: `index.md` at each hierarchy level as directory listing / discovery layer | §3.1/§8 (`index.md` reserved as "Directory listing" at any level; used as discovery) | ✅ Conformant |
|
||||
| AD-16 / Consistency: contradictions & update history via `log.md` | §3.1/§9 (`log.md` reserved, "Update history", date-grouped `## YYYY-MM-DD` entries) | ✅ Conformant (see B.2 #3 for format hardening) |
|
||||
| AD-8: relationships via standard Markdown links, not a proprietary graph/link format | §6.1 (bundle-relative `/` links or standard relative links; no proprietary format) | ✅ Conformant (see B.2 #4) |
|
||||
| AD-10: adapters must not define deviating knowledge semantics ("Ein Adapter darf keine abweichende Knowledge-Semantik definieren") | Enforces PRD §6.2 ("eigener OKF-Dialekt" forbidden); consistent with spec's permissive model | ✅ Guardrail aligned |
|
||||
| Spine does not invent frontmatter fields beyond the OKF set (sources/generated/verified/status/stale_after) | §4.1 unknown additional keys tolerated, but an invented drive-schema would be a dialect | ✅ No "own dialect" found |
|
||||
|
||||
Affirmative finding: **No spine statement produces a non-conformant bundle, and no "own OKF dialect" is proposed.** Consistency table entries map 1:1 onto OKF mechanisms («Provenance → sources», «Update history → Git + OKF log.md», «Concept format → Markdown + YAML frontmatter», «Concept identity → relative OKF path»).
|
||||
|
||||
### B.2 Findings — tiered
|
||||
|
||||
**F-1 (Low, conformance hardening) — Bundle root is never explicitly declared.**
|
||||
The spine defines `raw/` and `wiki/` as architectural boundaries (Structural Seed) and canonical knowledge as `wiki/**/*.md` (AD-1), but never states *explicitly* that the OKF bundle root IS `wiki/`. The same repository contains `raw/`, `schema/`, `adapters/` with `.md` files. If a validator ever treats the repo root as bundle root:
|
||||
- conformance §11 requires a non-empty `type` in every non-reserved `.md` → `raw/*.md` (evidence, deliberately not concepts, AD-2) would fail validation;
|
||||
- §8 permits frontmatter in an `index.md` *only* for the bundle-root `index.md` → any `schema/`/`adapters/` `index.md` with frontmatter would be out of spec.
|
||||
Recommendation: state in AD-1 that **bundle root = `wiki/`** (with `okf_version` in `wiki/index.md` only) and that `raw/`, `schema/`, `adapters/` are outside the bundle and excluded from OKF validation. Also note that AD-9's subdirectory `index.md` files must contain **no frontmatter** (§8 exception applies only to bundle-root `index.md`).
|
||||
|
||||
**F-2 (Low, conformance hardening) — "Errors | kein erfolgreicher Run bei ungültigem Bundle" needs a precise definition of "ungültig".**
|
||||
The Consistency convention "Errors" says a run must not succeed on an invalid bundle. §11/§4.1 require that **consumers MUST NOT reject** a bundle / concept for missing optional frontmatter fields, unknown `type`, unknown extra keys, broken links, or missing `index.md` — and §12 even asks consumers that don't understand the declared version to attempt best-effort consumption rather than refuse. "Ungültig" must therefore be scoped to *structural* invalidity (missing/empty `type`, unparseable YAML, reserved filename misuse), explicitly NOT "missing optional fields", or the compiler's own acceptance check would contradict the standard's permissiveness.
|
||||
|
||||
**F-3 (Low, conformance hardening) — `log.md` is used beyond its spec-defined purpose; format must be pinned.**
|
||||
§9 defines `log.md` as an update-history record: flat list, date-grouped `## YYYY-MM-DD` (ISO 8601), prose entries whose leading bold word is a convention (e.g. **Update**/**Creation**/**Deprecation**). AD-16 and AD-17 additionally use `log.md` as a *disagreement / conflict ledger* ("dokumentierte Disagreements", "der Konflikt wird in log.md dokumentiert"). This is an extension of §9 semantics; it is tolerated only as long as entries remain prose within date-grouped `## YYYY-MM-DD` blocks. Recommendation: state that all `log.md` entries (including disagreements) follow the §9 date-grouped format, so the disagreement ledger does not drift into a structured dialect.
|
||||
|
||||
**F-4 (Info) — Link form recommendation not adopted (optional).**
|
||||
AD-8 mandates "normal Markdown links" but does not choose the spec's *recommended* form: §6.1 prefers bundle-relative links beginning with `/` ("stable when documents are moved within their subdirectory") over plain relative paths. Not a violation (plain relative is allowed), but adopting `/`-prefixed bundle-relative links would tighten conformance and stability. Optional.
|
||||
|
||||
**F-5 (Info) — `references/` convention unused (optional).**
|
||||
§6.3 defines `references/` as the conventional place to mirror external material inside a bundle. The spine instead uses `raw/` (outside the bundle) for external material — no conflict, since `raw/` is not part of the bundle and `references/` is "a naming convention, not a requirement". If any external material is ever mirrored *inside* `wiki/`, it should follow the `references/` convention. No action required now.
|
||||
|
||||
### B.3 Conformance conclusion
|
||||
|
||||
The spine's OKF claims (AD-1, AD-7, AD-9, AD-15, FR-9 conventions, Consistency table, Stack) match OKF 0.2 to the letter on: required `type`, optional `sources`/`generated`/`verified (human:)`/`status`/`stale_after`, `okf_version` only in bundle-root `index.md`, `references/` as optional convention, concept ID = path-minus-`.md`, and consumer permissiveness for missing optional fields. The four findings above are hardening/word-smithing items, not conformance violations.
|
||||
|
||||
---
|
||||
|
||||
## C. Findings summary
|
||||
|
||||
| # | Severity | Finding | Location |
|
||||
|---|---|---|---|
|
||||
| — | — | All FR-1..16 and NFR-1..7 governed; OQ-2/3/4 answered; OQ-1/5 handled | — |
|
||||
| F-1 | Low | Bundle root (=`wiki/`) never declared explicitly; `raw/`-`wiki/` same-repo validation risk; subdirectory `index.md` must be frontmatter-free | AD-1, AD-9, Structural Seed |
|
||||
| F-2 | Low | "Ungültiges Bundle" must mean *structurally* invalid, not *missing optional fields* (spec §11 MUST-NOT-reject) | Consistency "Errors" |
|
||||
| F-3 | Low | `log.md` disagreement ledger must keep §9 date-grouped prose format | AD-16, AD-17 |
|
||||
| F-4 | Info | Optional: adopt `/`-prefixed bundle-relative links (§6.1 recommended form) | AD-8 |
|
||||
| F-5 | Info | Optional: `references/` convention if external material ever enters `wiki/` | AD-2/Structural Seed |
|
||||
| OQ-6 | Info | PRD product-name question unaddressed in spine (product, not architecture, item) | — |
|
||||
|
||||
**Overall verdict:** PASS. Spec coverage is complete (16 FR + 7 NFR → 23/23 entries, 3/3 delegated tickets answered). OKF 0.2 conformance is sound; no non-conformant output and no own dialect. The 3 low-severity findings (F-1..F-3) are recommended before implementation begins because they affect how the compiler *validates* and *writes* bundles.
|
||||
+179
@@ -0,0 +1,179 @@
|
||||
# Reconciliation Review — PRD vs. Architecture Spine
|
||||
|
||||
- PRD: `D:\mita\wow-2nd\_bmad-output\planning-artifacts\prds\prd-wow20-2026-08-14\prd.md`
|
||||
- Spine: `D:\mita\wow-2nd\_bmad-output\planning-artifacts\architecture\architecture-wow20-2026-08-14\ARCHITECTURE-SPINE.md`
|
||||
- Reviewer: reconcile reviewer (independent)
|
||||
- Date: 2026-08-14
|
||||
- External verification: OKF 0.2 SPEC (GoogleCloudPlatform/knowledge-catalog `okf/SPEC.md`) fetched and checked for the `log.md` convention.
|
||||
|
||||
---
|
||||
|
||||
## 1. Coverage of FR-1..FR-16 and NFR-1..NFR-7
|
||||
|
||||
| ID | Requirement (short) | Spine coverage | Category |
|
||||
|---|---|---|---|
|
||||
| FR-1 | Sources bereitstellen (local material, no URL fetch) | AD-2, AD-3, AD-12 + Capability Map | **AD/CC** |
|
||||
| FR-2 | Sources vs. Curated Knowledge unterscheiden | AD-2 | **AD** |
|
||||
| FR-3 | Provenienz bewahren | AD-4 + CC `Provenance` | **AD** |
|
||||
| FR-4 | Sources gegen bestehendes Wissen verarbeiten | AD-4, AD-5 | **AD** |
|
||||
| FR-5 | Concepts erzeugen | AD-5, AD-7 | **AD** |
|
||||
| FR-6 | Bestehende Concepts aktualisieren | AD-5, AD-7 | **AD** |
|
||||
| FR-7 | Wissen synthetisieren | AD-4, AD-5, AD-16 | **AD** |
|
||||
| FR-8 | Widersprüche sichtbar behandeln | AD-16 (+ AD-4 provenance of disagreements) | **AD** |
|
||||
| FR-9 | OKF-0.2-konforme Concepts | AD-1, AD-15, CC `Concept format` | **AD/CC** |
|
||||
| FR-10 | Concepts miteinander verlinken | AD-8, CC `Concept relationships` | **AD** |
|
||||
| FR-11 | Progressive Discovery | AD-9 | **AD** |
|
||||
| FR-12 | Inkrementell weiterentwickeln | AD-5 (+ AD-14 history) | **AD** |
|
||||
| FR-13 | Menschliche Kuratierung berücksichtigen | AD-15 | **AD** |
|
||||
| FR-14 | Änderungen nachvollziehbar (Git) | AD-14, CC `Update history` | **AD** |
|
||||
| FR-15 | Tool-unabhängiger Zugriff | AD-1, AD-8, AD-9 | **AD** |
|
||||
| FR-16 | Consumer vom Compiler entkoppeln | AD-10, AD-13 | **AD** |
|
||||
| NFR-1 | Portability | AD-1 + FT-7 | **AD** |
|
||||
| NFR-2 | Human Readability | AD-15 binds NFR-2, CC `Concept format` | **AD/CC** |
|
||||
| NFR-3 | Agent Readability | AD-8, AD-9, AD-13 (binds FR-15) | **AD (partial)** |
|
||||
| NFR-4 | Version-Control Friendliness | AD-14 | **AD** |
|
||||
| NFR-5 | No Mandatory Runtime | AD-1, AD-11 + FT-1 | **AD** |
|
||||
| NFR-6 | Vendor Independence | AD-10 + CC `Agent-specific behavior` | **AD** |
|
||||
| NFR-7 | Graceful Partial Knowledge | AD-4, AD-16 (both bind NFR-7) | **AD** |
|
||||
|
||||
**Verdict:** Full coverage. No FR or NFR lands in a NO category.
|
||||
|
||||
---
|
||||
|
||||
## 2. Assumptions A-1..A-5 and Guardrails (§ 8) vs. the Spine
|
||||
|
||||
| PRD item | Spine status | Finding |
|
||||
|---|---|---|
|
||||
| **A-1 — Target user / no fully autonomous unchecked process (SM-C3 linked)** | Not referenced | **Not contradicted, but silently not picked up.** No AD/rule addresses the boundary between automation and human oversight/correctability. SM-C3 ("Nachvollziehbarkeit > Autonomie") is never mapped. **GAP — LOW**, shared with OQ-1 below. |
|
||||
| **A-2 — Git-versioned OKF Bundle is canonical state (= § 8.2)** | AD-1 + CC `Canonical knowledge` / `Canonical evidence` | Covered. Clarified: canonical evidence is `raw/`. |
|
||||
| **A-3 — No dedicated GUI in v1** | Not referenced | Not contradicted. Addressed indirectly by AD-11 (no server, agent runtime) and D-7 (no review workflow/UI). AD-17 rule 3 stays CLI/file/git-based. **Adheres by silence; no explicit statement** — LOW. |
|
||||
| **A-4 — Source acquisition is not core; local material only, no URL fetch in v1** | AD-12 + Deferred D-1 | Covered — D-1 explicitly defers HTTP fetch/Context7 etc. until a bottleneck. |
|
||||
| **A-5 — BMAD/Claude Code/Codex/CodeGraph are sources or consumers, not core** | AD-10, AD-12, AD-13, Architectural Boundary (`Only the middle box is Wiki of Wikis`) | Covered. |
|
||||
| **§ 8.1 — OKF used, not replaced; no competing ontology** | AD-1, AD-15, Stack (`Open Knowledge Format 0.2`) | Covered. **Verified externally:** the spine's `log.md` label is a legitimate OKF 0.2 reserved filename (scoped update history, §3.1/§9 of the SPEC), and OKF requires consumers to tolerate unknown extension keys. The spine does **not** invent an OKF dialect. |
|
||||
| **§ 8.2 — Derived indices/caches are not Source of Truth** | AD-1 `Derived` list + FT-4 | Covered. |
|
||||
| **§ 8.3 — Separation of Concerns: Sources → Compilation → Bundle → Consumers** | AD-2, AD-12, AD-13, AD-5; Capability Map | Covered. |
|
||||
| **§ 8.4 — Complexity guardrail (infrastructure only if required for core)** | AD-11, AD-12, AD-13, D-2/D-3/D-4, FT-8 | Covered. |
|
||||
|
||||
**Contradictions:** none found.
|
||||
|
||||
**Silently dropped:** A-1/SM-C3 (human oversight/correctability posture) and (weakly) A-3 (no explicit no-GUI statement). Neither is contradicted, both are just not picked up.
|
||||
|
||||
---
|
||||
|
||||
## 3. PRD-delegated Architecture Tickets (Open Questions 2/3/4), plus OQ-5 and OQ-6
|
||||
|
||||
**PRD OQ-2 — Verification / trust-metadata model → ANSWEred by AD-15**
|
||||
|
||||
- Maps to `generated`, `verified` with `human:` prefix, `status`, `stale_after` (exact OKF 0.2 fields).
|
||||
- v1 default preserved: machine-generated, unreviewed → `generated` set, `verified` unset until human review. PRD's Note-for-PM honored.
|
||||
- The human-workflow side is additionally deferred in D-7 (no dedicated review workflow/UI in MVP), consistent with A-3.
|
||||
- **Status: answered.**
|
||||
|
||||
**PRD OQ-3 — Compilation scope / relevant-concepts discovery → ANSWERED by AD-17 (and AD-11)**
|
||||
|
||||
- AD-17 closes with the functional rationale: relevance must be implemented with textual, deterministic means (grep/ripgrep, Markdown traversal, link-following), not embedding/vector infrastructure, because retrieval is consumer behavior (AD-13). This faithfully executes PRD § 12's explicit request.
|
||||
- **Status: answered.**
|
||||
|
||||
**PRD OQ-4 — Conflict resolution → ANSWERED by AD-16 and AD-17**
|
||||
|
||||
- AD-16: classification (NEW / CONFIRMING / CORRECTING / CONTRADICTING / REDUNDANT); contradictions preserved explicitly, never silently resolved; disagreement sources remain traceable; uncertainty may be part of a concept (FR-8, NFR-7).
|
||||
- AD-17 rule 4: producer-level conflict handling — productive contribution wins, a producer may not delete/rewrite a scope if it would effectively replace another producer's work; otherwise the conflict is documented in `log.md` and left open. This is the full answer (data-level + producer-level) and stays CLI/git/file based per A-3.
|
||||
- **Status: answered.**
|
||||
|
||||
**PRD OQ-5 — Source lifecycle (removal/replacement/revocation) → DEFERRED (D-5), answered at decision level**
|
||||
|
||||
- D-5 explicitly addresses it: "MVP assumes additive Source ingestion; revisit before supporting deletion, superseding or revocation." AD-3 reinforces it: raw sources are immutable, new versions become new/versioned sources, source lifecycle and replacement semantics deferred.
|
||||
- Adherence to AD-4 is preserved (removed sources simply stop contributing).
|
||||
- A "revoked/false source" case is not materially discussed in the spine — D-5 carries the load. Acceptable as a consciously deferred decision, but the PRD asked a substantive product question and the spine only parked it. **Status: deferred with explicit handling; a residual product question remains (see Findings #13).**
|
||||
|
||||
**PRD OQ-6 — Product name → NOT ANSWERED**
|
||||
|
||||
- The spine uses "Wiki of Wikis" functionally in frontmatter and as the PRD companion; no statement on whether it is final product name or project name. The spine is not obligated to answer this (outside its remit), so it is intentionally not answered.
|
||||
- **Status: not answered (arguably out of scope for a build-substrate spine); flag for the broader program, not block the spine.**
|
||||
|
||||
---
|
||||
|
||||
## 4. Non-Goals (§ 5) and MVP Out-of-Scope (§ 6.2) — re-admission check
|
||||
|
||||
| Non-goal / out-of-scope item | Spine posture | Re-admitted? |
|
||||
|---|---|---|
|
||||
| Vector database | Stack (`none`), D-2, AD-13 (vector search is consumer-side) | **No** |
|
||||
| Knowledge graph database | AD-8 (graph is optional derivation, never canonical) | **No** |
|
||||
| General RAG platform / retrieval-as-core | AD-13 + Retrieval-replacement FT-3 | **No** |
|
||||
| Enterprise search / KM suite | not touched; boundary diagram keeps core small | **No** |
|
||||
| Web UI / Wiki rendering server / server runtime | AD-11 (`kein eigener Serverprozess`), Stack (`Server runtime none`) | **No** |
|
||||
| MCP server | Stack (`MCP none`), D-4 | **No** |
|
||||
| Automatic internet research / webcrawler | AD-12, D-1 | **No** |
|
||||
| Automatic scheduling / source observation | D-6 (stale detection deferred) | **No** |
|
||||
| BMAD / Claude-Code / CodeGraph integration (as core) | AD-10, AD-12 consumed into `raw/` as sources; AD-13 lists CodeGraph as consumer-side | **No** |
|
||||
| Multi-user rights / enterprise governance | absent from core; AD-17 is lease/git-level, not auth | **No** |
|
||||
| Own OKF dialect / additional knowledge schema | AD-1 (`exclusively OKF-0.2`), AD-15 (one data model), Stack; `log.md` verified OKF-native | **No** |
|
||||
| Vector embeddings, vector search | Stack, D-2 | **No** |
|
||||
| Retrieval as core behavior | AD-13 states the doctrine | **No** |
|
||||
| Block-until-resolution (mandatory waiting) | AD-16 preserves conflicts; AD-17 surfaces them in `log.md` — no blocking mechanism anywhere | **No** |
|
||||
|
||||
**Verdict:** the spine strictly preserves the scope. No non-goal is re-admitted. The principle "future functions may become integrations around the compiler" (§ 6.2) is implemented through the D-1/D-2/D-4 deferred entries.
|
||||
|
||||
---
|
||||
|
||||
## 5. Quiet Requirements
|
||||
|
||||
**5a. Core value promise — synthesis rather than copy (FR-2 / SM-2)**
|
||||
|
||||
Preserved: AD-2 (`Eine Kopie des Quelldokuments ist keine Compilation`), AD-4 (source-grounded synthesis), AD-5 (incremental, not regenerate-all), AD-16 (reconciliation, not concatenation). SM-2 is not mapped explicitly, but FR-5/FR-7 carriers carry it. **Preserved.**
|
||||
|
||||
**5b. Graceful partial knowledge (NFR-7)**
|
||||
|
||||
Preserved: AD-4 (may not treat own syntheses as new evidence) and AD-16 (uncertainty may be part of a concept; contradictions preserved) both bind NFR-7. **Preserved — this is the strongest carry. Exception: OQ-1/AD-4 (may a generated concept be the sole provenance of another generated concept) is left as an open question, so in one edge, grounding of partial knowledge is not fully closed.**
|
||||
|
||||
**5c. "Retrieval is consumer behavior" doctrine**
|
||||
|
||||
Elevated to a first-class AD (AD-13), reinforced by AD-8/AD-9/AD-11 and D-2. The spine also applies it defensively to relevance determination (AD-17), which is a faithful interpretation of PRD § 12. **Preserved and made architecturally load-bearing.**
|
||||
|
||||
---
|
||||
|
||||
## Findings
|
||||
|
||||
### HIGH
|
||||
|
||||
1. **Open Question 6 (product name) is not answered anywhere in the spine and is silently absent.** The spine uses "Wiki of Wikis" as if settled. This is likely out of remit for a build-substrate spine, so it is recorded here for the program rather than raised as a rejection. `ARCHITECTURE-SPINE.md` frontmatter `name: Wiki of Wikis`.
|
||||
|
||||
2. **Open Question 5 (source lifecycle) is only deferred (D-5), not answered.** The PRD asked a substantive product question ("Was geschieht mit Wissen, wenn eine Source entfernt…wird?"). The spine stops at "additive only, revisit later." Acceptable as an explicit deferral; the full product answer remains open across all ADs.
|
||||
|
||||
### MEDIUM
|
||||
|
||||
3. **`raw/` is called immutable while "Source Lifecycle and Replacement-Semantik bleiben für den MVP deferred" (AD-3).** These two statements are tensioned, not contradictory (immutability holds in the additive MVP; versioned replacement is the deferred exit). Must be reconciled before D-5 is revisited, or "immutable" must be scoped to "immutable for the lifetime of the MVP."
|
||||
|
||||
4. **No single AD or consistency-convention row binds NFR-3 (Agent Readability) explicitly.** NFR-3 is covered only indirectly via AD-8/AD-9/AD-13, whose binds list FR-15 (not NFR-3). In a large agent-generated wiki, NFR-3 deserves an explicit guarantee, e.g., a rule that bundle navigation must not require a specialized tool. Consider AD-9/AD-13 extending their binds to NFR-3.
|
||||
|
||||
5. **SM-C3 (Counter-Metric: comprehensible/correctable > autonomous) and its coupling to A-1 (no fully autonomous unchecked process) are silently dropped.** No AD, convention row, or fitness test carries the "human can intervene/correct" requirement. NFR-2 and D-7 touch it only implicitly. The spine should express the correctability guarantee at least once (e.g., a fitness test: "a human can correct a generated Concept without the compiler erasing the correction" — AD-15's persistence clause almost says this for curation, but not for corrections).
|
||||
|
||||
### LOW
|
||||
|
||||
6. **A-3 (no GUI in v1) is never stated explicitly.** Not contradicted (D-7 and AD-17 are consistent with it), but a spine that claims `binds: FR-1..FR-16, NFR-1..NFR-7` leaves the UI guardrail implicit. Suggest one CC row or an A-binding note. Relatedly, the spine has no explicit "no GUI" line, only the indirect implication.
|
||||
|
||||
7. **Deferred D-5 (source deletion/replacement) is not cross-referenced in AD-3's binds nor in an Open Question entry** (Q-1..Q-3 exist; OQ-5 has no twin). The Deferred section covers the subject, so this is a cross-reference/traceability nit.
|
||||
|
||||
8. **PRD OQ-1 (human-authored, fully manual Concepts as first-class knowledge) is not explicitly echoed.** AD-15 assumes before reaching consensus: "human curation is represented as OKF Concepts with metadata" is given, which is a reasonable v1 stance (treated as first class), but the spine does not record it as a decision — leaving the spine alive to AD-15's own open-side of Q-3/-D-7.
|
||||
|
||||
9. **The spine's mermaid overview (Design Paradigm) omits the Reconcile/Validate steps shown by AD-5/AD-6** — cosmetic drift between the high-level diagram and the AD text; the detail ADs carry the full flow (Analyze → Reconcile → Plan → Mutate → Validate), so this is purely presentation.
|
||||
|
||||
10. **PRD § 12's second forwarded question — Bundle-Layout (Source vs. Curated Knowledge placement)** — is answered by the Structural Seed (`raw/` vs `wiki/`) and CC rows, but the spine never labels that answer with the PRD's exact boundary requirement (FR-2/§ 8.3). Traceability nit: the spine's seed says `raw/` and `wiki/` are "Architekturgrenzen" — the invariant is intact but the PRD anchor is not cited.
|
||||
|
||||
11. **AD-17 rule 3 is German and much more conversational than the rest of the spine**, and its embedded sequence (materialize → disable/lease → mutation scoped → commit + release) is not mirrored in the Consistency Conventions table. It is the longest and most implementation-flavored block; inconsistent with the spine's stated "conceptually not prescribing implementation" register. Worth normalizing into the CC table or restructuring, but not a correctness issue.
|
||||
|
||||
12. **`status` default per OKF 0.2 is `stable` when absent.** AD-15's list (`draft | stable | deprecated`) is correct as allowed values, but combined with the v1 "unreviewed by default" posture, an unreviewed Concept could silently default to `stable`. Consider whether the spine wants to mandate `status: draft` (or `generated` + no `verified`) as the explicit v1 default instead of relying on OKF's `stable`-when-absent default. The PRD (§ 4.3 FR-9) delegates field selection to the architecture, so this is a design suggestion, not a coverage gap.
|
||||
|
||||
13. **The "revoked/false source" branch of OQ-5 lacks even a placeholder.** D-5 names deletion, superseding, revocation generically as "revisit," but the spine nowhere sketches what revocation should mean for provenance-weight (the PRD's A-4/SM-3 provenance promise implies some treatment eventually). Not a v1 blocker.
|
||||
|
||||
---
|
||||
|
||||
## Sources not found / notes
|
||||
|
||||
- No FR or NFR is uncovered.
|
||||
- No assumption is contradicted; two assumptions (A-1/SM-C3, weakly A-3) are silently not picked up.
|
||||
- All three PRD-delegated architecture tickets (OQ-2, OQ-3, OQ-4) are answered by ADs; each is cross-checked against the PRD's own Note-for-PM constraints (machine-generated-unreviewed default; CLI/datei-based feasibility).
|
||||
- OQ-5 is deferred (D-5) with explicit handling; OQ-6 is not answered (out of remit).
|
||||
- Non-Goals / MVP Out-of-Scope: no re-admission.
|
||||
- Quiet requirements: synthesis-not-copy (preserved), graceful partial knowledge (preserved, with one open edge behind Q-1), retrieval-is-consumer-behavior (elevated to AD-13 and applied to relevance determination per PRD § 12).
|
||||
- No contradictions with the OKF-0.2 spec; the spine's `log.md` and trust-forecast metadata usage are OKF-conformant (verified against `okf/SPEC.md`), so § 8.1's "no own OKF dialect" guardrail holds.
|
||||
+162
@@ -0,0 +1,162 @@
|
||||
# Rubric Review — Wiki of Wikis Architecture Spine
|
||||
|
||||
Review type: good-spine checklist walker
|
||||
Reviewed artifact: `_bmad-output/planning-artifacts/architecture/architecture-wow20-2026-08-14/ARCHITECTURE-SPINE.md`
|
||||
Row-up PRD: `_bmad-output/planning-artifacts/prds/prd-wow20-2026-08-14/prd.md`
|
||||
Reviewed against: good-spine checklist; capabilities FR-1..FR-16, NFR-1..NFR-7 of the PRD
|
||||
Review date: 2026-08-14
|
||||
|
||||
---
|
||||
|
||||
## Gate verdict
|
||||
|
||||
**CONDITIONAL PASS** — the spine is strong and internally coherent, but it fails to fully close the multi-producer coordination concern (AD-17 is a convention, not an enforced rule), and its Operational Envelope is too thin on security/access and on the operational concurrency and environment envelope. One access A uses the word "Simulation" in a place where an enforced rule is needed, and the "no security" reality needs an explicit, honest decision.
|
||||
|
||||
---
|
||||
|
||||
## Checklist results
|
||||
|
||||
| # | Criterion | Result | Note |
|
||||
|---|---|---|---|
|
||||
| 1 | Fixes the real divergence points for the level below; misses none | PARTIAL | AD-17 identifies the real LWW risk, but the fix is a convention, not an enforcement mechanism (see Finding C-1, C-2). |
|
||||
| 2 | Every AD's Rule is enforceable and prevents its stated divergence | PARTIAL | Rules are mostly enforceable via admission-control tests and fitness tests, but AD-4's Rule 2 ("material claims must remain transitively grounded") is not mechanically checkable without an auditor that follows `sources` transitively. This is the strongest "divergence prevention" gap. |
|
||||
| 3 | Nothing under Deferred lets two units diverge | PASS | D-1 (source acquisition adapters), D-2 (retrieval), D-3, D-4, D-5..D-8 — either explicitly single-producer or consumer-side; none contradict an AD. Note D-7 (human review workflow) is a workflow choice, not a data-model divergence. |
|
||||
| 4 | Named tech is verified-current | PASS | OKF 0.2 confirmed current via direct fetch; Markdown, Git, ripgrep all current/standard. |
|
||||
| 5 | Covers the spec's capabilities (FR-1..16, NFR-1..7) | PASS | Every FR and NFR has at least one governing AD (see coverage table). |
|
||||
| 6 | Every dimension the altitude owns is decided, deferred, or an open question | FAIL | The operational/environmental envelope is incomplete: security/access (team sharing) is silent; environments/deployment are effectively never decided; operational concurrency handling of the lease mechanism on a shared workspace is undefined. |
|
||||
|
||||
---
|
||||
|
||||
## Detailed findings (tiered)
|
||||
|
||||
### Critical
|
||||
|
||||
#### C-1 — AD-17's "Lease" is a convention, not an enforced rule; Last-Writer-Wins is not actually fixed
|
||||
**Where:** AD-17, bullet 3 (line 445-451) and bullet 4 (line 453)
|
||||
|
||||
AD-17's stated prevent is exactly the Last-Writer-Wins problem the rubric asked about: two producers (Claude, Codex, or the human) mutating the same concept path simultaneously. The cited mechanism is:
|
||||
|
||||
- Each producer works in its own branch/worktree and resolves conflicts at Git level (rebase/merge) itself (rule bullet 1).
|
||||
- The compiler only consumes committed content (rule bullet 2).
|
||||
- "He'd'den applies: acquire lease, mutate only within leased area, release lease; conflict resolution by productive value logged in `log.md`" (rule bullet 3-4).
|
||||
|
||||
The problem:
|
||||
|
||||
1. The word "Lease" is a word, not a mechanism. There is no definition of how a lease is acquired, how it is held exclusive, how it is released, or what happens when the acquiring producer dies holding the lease. On a plain filesystem+Git workspace there is no enforcement primitive for exclusivity; two producers contended on the same path in two worktrees will both commit, and Git merge will either produce a conflict (both edited the same line — then the productive-value principle in `log.md` is an advisory that no process enforces) or a clean merge by LWW semantics if they edited different lines of the same file.
|
||||
2. Rule bullet 1 says conflict resolution happens **at Git level by the producer itself** — that reintroduces exactly the LWW/second-writer-wins the AD claims to prevent: there is nothing that prevents producer B from silently overwriting producer A's concept path with its own diff, because "productive check via log.md" is a human-opinion algorithm, not a checkable invariant.
|
||||
3. The compiler itself (mutator) is invoked by the adapter (agent). The AD says convergence is "orchestrated by the executing adapter" — but with no executable lease protocol, nothing stops two adapters from running concurrently against the same repo. The result is exactly the LWW silent overwrite the AD says it prevents.
|
||||
|
||||
Grades:
|
||||
- **Enforceability:** No. A reviewer following the Rule mechanically cannot verify compliance at commit time without a lease table that is itself a derived artifact contradicting AD-1's "derived artifacts are not source of truth", and even then nothing enforces it.
|
||||
- **Divergence prevented:** Not fully. This is the single most important gap in the whole spine.
|
||||
|
||||
Recommended fix (before implementation):
|
||||
- Replace the prose lease with a minimal, mechanically checkable protocol: e.g., a `locks/<concept-path>.lease` convention (a file whose presence means "leased", whose content is producer + timestamp + expected completion, whose existence is checked by the compiler entrypoint and by every commit hook), plus a hard rule that a commit that touches a path where the lease is not held by the committing producer is rejected by a pre-commit hook. If "no runtime" is sacred, the lease must be a file, not a memory object; a git commit hook reading a small text file is a normal file operation, consistent with the no-runtime philosophy.
|
||||
- Alternatively, explicitly downgrade AD-17 to a single-writer-acknowledged model ("the compiler assumes only one producer at a time; if two producers contend, the human resolves at Git level and the result is LWW for that path") and say so. That would at least be honest and enforceable; the current text implies more safety than the mechanism provides.
|
||||
|
||||
#### C-2 — Two producers, two worktrees, same repo: each branch holds the whole bundle; the term "Won't run concurrently" is NEVER stated
|
||||
**Where:** AD-17 rule bullet 1; also AD-6, AD-3
|
||||
|
||||
There is no statement anywhere that the compiler is single-instance. AD-17's own scenario ("Claude, Codex, or the human") is three possible producers; nothing in the spine limits the number of simultaneous compilation runs that may feed the same bundle. If the intent is single-writer serialized runs, that intent is nowhere made explicit, and the reader cannot distinguish "concurrent adapters are coordinated by the lease", which is claimed, from "concurrent adapters are inherently excluded", which is not claimed and would be desirable to state.
|
||||
|
||||
Fix: add an explicit statement in AD-17 (or an AD-17a): "At most one compilation run may be active against the shared workspace at a time; runs are serialized by file-lock or by the existence of a `locks/`-style lease." If this is a hard design constraint, the spine must say so; otherwise the claim that LWW is prevented overstates a mechanism that does not exist.
|
||||
|
||||
### High
|
||||
|
||||
#### H-1 — Operational Envelope is thin: security/access for the team case is silent; environments never decided
|
||||
**Where:** "Operational Envelope" section (lines 564-590); PRD A-1 (§ 2.1 assumption: "primär ein persönliches bzw. teaminternes Developer Tool")
|
||||
|
||||
The envelope covers only Local-first execution, Failure behavior, Portability. The checklist specifically asks about failure behavior, security/access, environments:
|
||||
|
||||
- **Security / access (team case):** The PRD's own assumption A-1 says the product is a "persönliches bzw. teaminternes Developer Tool" — the primary user is "ein technisch versierter Wissensarbeiter bzw. Softwareentwickler." If team-internal, then "who writes" (push permissions to `raw/` and `wiki/`; who may produce leases; who may mark `verified`) is a real divergence point the architecture owns. The spine is silent on all of it. Git-level collaboration (a shared repo) is the natural answer, but the spine never states that the team access story is "Git repository permissions" vs. "anyone with filesystem access", nor what the boundary is for `raw/` (immutable evidence) vs `wiki/` (mutable) from a writes standpoint. A team member editing `wiki/` directly is allowed per AD-15/Q-2, but nothing governs concurrent human-vs-compiler writes beyond AD-17 (which is underexplained as a mechanism — see C-1).
|
||||
- **Environments / deployment / CI:** The spine says nothing at system level about `main` vs worktrees, about a shared remote, about where compiled bundles are published, about promotion (e.g., lease branch → merge → main). Since the spine binds Git, environment decisions (which branch is canonical read-surface, whether compilation runs on `main` or on a branch that is later merged) are a real divergence point for multiple consumers reading "the wiki" — two consumers polling different branches see different knowledge. This should be explicitly decided or explicitly deferred (it is neither).
|
||||
|
||||
Impact: this is dimension (6) in the rubric — a whole dimension left silent. For a single-user local tool it would be acceptable; for a team-shared Git workspace it is a finding.
|
||||
|
||||
#### H-2 — AD-4 Rule 2 (transitive grounding) is not mechanically enforceable
|
||||
**Where:** AD-4 Lines 112-140; fitness test FT-5, FT-4
|
||||
|
||||
The Rule says "materielle fachliche Aussagen müssen auf nachvollziehbare Sources zurückgeführt werden" and "Bei einer Synthese aus mehreren Concepts wird relevante Source-Provenienz in das resultierende Concept übernommen." FT-5 ("its material source basis can be traced to actual Source Material") is the test, but nothing specifies a mechanical check that a synthesized concept actually carries provenance that reaches a `raw/` file. As written it is a semantic preference, not a verifiable invariant: a compiler could produce a concept with `sources` referencing another concept's ID only, and no admission check would fail.
|
||||
|
||||
Fix: define the check as part of the Compiler contract (schema/wiki-compiler.md): for every generated concept, `sources` entries must resolve (transitively, bounded depth) to at least one source under `raw/` (or a documented external immutable reference); a concept whose entire `sources` chain terminates in other concepts fails validation and the run fails (or the concept is downgraded). This is checkable with grep/traversal — consistent with the "no runtime/vector infra" constraint.
|
||||
|
||||
### Medium
|
||||
|
||||
#### M-1 — Consistency Conventions table "Erstellt von" / "Errors" entry is gray
|
||||
**Where:** "Consistency Conventions" table, row "Errors" (line 474): "kein erfolgreicher Run bei ungültigem Bundle"
|
||||
|
||||
In AD-6 (Overlap with AD-6) — acceptable summary, but the table generalizes to "invalid bundle" with no definition of what validates it and who runs validation. Combined with H-2, the table promises an acceptance gate that the document does not give a mechanism for. Minor: the row belongs to the "no-proprietary-format" axis and would be more useful as "validation = OKF conformance + AD-4 grounding, implemented as committed checks in schema/". Recommend rewording to name the artifact that performs it.
|
||||
|
||||
#### M-2 — AD-16 "classifies new information" is conceptual only; "Relevance determination" reference leaks implementation
|
||||
**Where:** AD-16 lines 419-434; AD-17 "Wichtig — funktionaler Grund" (line 455)
|
||||
|
||||
AD-16 says the classification "ist konzeptionell; sie schreibt keine konkrete interne Datenstruktur vor" — good and consistent with AD-6. But the "Wichtig" note in AD-17 (line 455) makes a strong causal claim: "Relevanzbestimmung (PRD OQ-3...) ist begrenzt: Sie muss mit textuellen, deterministischen Mitteln (grep/ripgrep, Markdown-Traversal, Link-Following) umgesetzt werden, nicht mit Embedding- oder Vector-Infrastruktur." This is correct and consistent with AD-13, but it belongs in AD-5/AD-13 (relevance determination is a compilation-input concern, not producer mechanism) rather than AD-17, where a reader of AD-17 is unlikely to look for it. The PRD explicitly hands this decision to the architecture (PRD § 12), and the spine does answer it — but in the wrong section. Reorganize: relevance determination deserves its own AD-18 (or a bullet in AD-5) so the "how does the compiler find relevant existing concepts" answer is not buried in the leasing AD.
|
||||
|
||||
### Low
|
||||
|
||||
#### L-1 — AD-11 label "AD-11 — Agent runtime provides reasoning; Wiki of Wikis provides protocol" is a naming shift from "protocol" semantics
|
||||
**Where:** AD-11
|
||||
|
||||
The title implies WoW "provides protocol", but the SVG/diagram and rule text describe WoW as instructions ("kanonische Compiler-Regeln"), not a wire protocol. If it is an *agent-instruction contract* (which AD-10 says, correctly), the title should say "Compilation Contract" rather than "protocol", to avoid implying a wire/serialization protocol where none is designed. Cosmetic, but affects how a downstream implementer reads the boundary.
|
||||
|
||||
#### L-2 — Missing explicit statement tying D-7 (Human review workflow) to a resolved OQ
|
||||
**Where:** D-7 (line 707-713) with PRD OQ-2 (§ 10), AD-15
|
||||
|
||||
PRD OQ-2 ("Verification Workflow") is answered in the PRD's own NOTE FOR PM ("v1-Default ist maschinell erzeugt und ungeprüft") and mirrored in AD-15. D-7 correctly defers the workflow itself. This is coherent, but the spine never states which PRD OQ each AD resolves — adding a small column ("Resolves/answers") mapping the six PRD OQs (and § 12's two handed-off questions, which are answered in AD-17's note and hence belong elsewhere per M-2) would let a reviewer see at a glance that no PRD open question is left dangling. It also would have made M-2 visible earlier.
|
||||
|
||||
---
|
||||
|
||||
## Coverage verification (checklist item 5)
|
||||
|
||||
Every FR and NFR of the PRD has at least one governing AD; the spine's Capability → Architecture Map (lines 518-537) is accurate and complete. Cross-check against the PRD:
|
||||
|
||||
| Capability | Spine's governing AD(s) | Also relevant |
|
||||
|---|---|---|
|
||||
| FR-1 Source intake | AD-2, AD-3, AD-12 | AD-17 rule 2 (immaterial during run) |
|
||||
| FR-2 Source/Knowledge separation | AD-2 | |
|
||||
| FR-3 Provenance | AD-4 | AD-16 (preserve provenance in contradictions) |
|
||||
| FR-4 Existing knowledge processing | AD-5 | |
|
||||
| FR-5 Concept creation | AD-5, AD-7 | AD-1 |
|
||||
| FR-6 Concept update | AD-5 | AD-4 |
|
||||
| FR-7 Cross-source synthesis | AD-4, AD-5 | |
|
||||
| FR-8 Contradictions | AD-16 | |
|
||||
| FR-9 OKF compliance | AD-1 | AD-15 (trust metadata) |
|
||||
| FR-10 Relationships | AD-8 | |
|
||||
| FR-11 Progressive discovery | AD-9 | |
|
||||
| FR-12 Incremental evolution | AD-5 | |
|
||||
| FR-13 Human curation | AD-15 | |
|
||||
| FR-14 Change history | AD-14 | |
|
||||
| FR-15 Tool-independent access | AD-1, AD-8, AD-9 | AD-13 |
|
||||
| FR-16 Consumer independence | AD-10, AD-13 | |
|
||||
| NFR-1 Portability | AD-1 | Operational Envelope (Portability) |
|
||||
| NFR-2 Human readability | AD-15 | Consistency table |
|
||||
| NFR-3 Agent readability | AD-1, AD-9 | AD-13 |
|
||||
| NFR-4 Version-control friendliness | AD-14 | |
|
||||
| NFR-5 No mandatory runtime | AD-1, AD-11 | Stack table |
|
||||
| NFR-6 Vendor independence | AD-1, AD-10, AD-11 | Stack table |
|
||||
| NFR-7 Graceful partial knowledge | AD-4, AD-16 | |
|
||||
|
||||
No gaps. All 16 FR + 7 NFR covered.
|
||||
|
||||
## Tech currency (checklist item 4)
|
||||
|
||||
Verified via direct fetch of `https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md`: the current OKF version is **0.2** (matching the PRD's § 13 reference). Key OKF-0.2 facts used by the spine are accurate: `type` is the only required frontmatter key; `timestamp` was superseded by `generated.at` (the spine never uses `timestamp` — good); `sources` supersedes the body-level `# Citations` list (the spine uses `sources` — consistent); `verified` absent means unverified; `status` default `stable`; `okf_version` only allowed in bundle-root `index.md`; `references/` is a naming convention, not a requirement; conformance rule that consumers MUST NOT reject bundles for missing optional fields / unknown keys / broken links / missing `index.md` — all consistent with AD-1/AD-15/AD-16 phrasing.
|
||||
|
||||
Note: OKF 0.2 gotcha — the spec says `index.md` and `log.md` are RESERVED filenames that "MUST NOT be used for concept documents". The spine uses `wiki/log.md` (line 490) for disagreements/history (AD-16 line 433). That is consistent with the reserved-name contract (a `log.md` that is not a concept is fine per spec), but the spine never states this distinction; a naive implementer could treat `log.md` as a concept and fail OKF conformance. Add one sentence to AD-16/AD-14: "`log.md` and `index.md` are reserved non-concept filenames per OKF; they must never carry a `type`." Low/severe depending on validator strictness.
|
||||
|
||||
## Placeholder / hygiene check (added at request)
|
||||
|
||||
- No duplicate AD-IDs; no `TODO`/`FIXME`/`TBD`/placeholder text found (grep -i). AD-1..AD-17 each has a unique, descriptive title.
|
||||
- Every AD carries Binds/Prevents/Rule (AD-11/AD-12 "Binds" uses 'MVP'-style target but structure present). All ADs have a matching `[ADOPTED]` or `[ASSUMPTION]` tag (8 assumptions, 9 adopted). Challenge: AD-4, AD-6, AD-11 are assumptions but their Rules read as normative ("Ein Compilation Run muss …") — the tag versus the certainty of the Rule body is inconsistent; potential reader confusion about whether AD-4's grounding is assumed or required. Medium-touch: retag to `[ADOPTED]` if the Rule is truly binding, or soften the Rule text if it's exploratory.
|
||||
- Status field says "draft" (frontmatter line 8) while content reads as adopted; fine for a spine artifact in progress, but flag for the level below that the spine is not final.
|
||||
|
||||
---
|
||||
|
||||
## Summary of stops to fix before the next level
|
||||
|
||||
1. **AD-17 mechanism** (C-1): turn lease/conflict-convention into a mechanically checkable file-based protocol (lease file + commit hook) or explicitly downgrade to single-writer serialization. As written, LWW is not actually prevented.
|
||||
2. **Concurrency statement** (C-2): state explicitly "at most one active compilation run / serialization by file-lock" or say concurrent runs are excluded; don't imply safety that doesn't exist.
|
||||
3. **Operational Envelope** (H-1): add a short "Security & Access" subsection for the team-internal case (who writes `raw/` vs `wiki/`, who may mark verified, whether access = Git repo permissions) and state the environment/deployment stance (canonical branch, promotion of lease-branch → main, whether a shared remote exists) as either decided or explicitly deferred.
|
||||
4. **AD-4 enforceability** (H-2): specify the transitive-grounding admission check in the compiler contract (schema/wiki-compiler.md) so FT-5 is real.
|
||||
5. **Relevance-determination placement** (M-2): give the "how does the compiler find relevant concepts with text-only means" answer its own home (AD-5/AD-18), not inside AD-17.
|
||||
6. **OKF reserved filenames** (Low): explicitly note `log.md`/`index.md` are non-concept reserved files.
|
||||
+125
@@ -0,0 +1,125 @@
|
||||
# Technology-Currency Review — Architecture Spine (Wiki of Wikis)
|
||||
|
||||
- **Reviewed file:** `ARCHITECTURE-SPINE.md` (draft, 2026-08-14)
|
||||
- **Reviewer:** technology-currency reviewer (independent)
|
||||
- **Date:** 2026-08-14
|
||||
- **Method:** Every named/committed technology and every cited source was checked against the live web via WebFetch (WebSearch was unavailable due to a persistent API error during this session — all anchors below were therefore verified by direct fetch of the primary sources).
|
||||
|
||||
---
|
||||
|
||||
## Summary verdict
|
||||
|
||||
**No committed decision rests on unverified or stale technology.** The spine leans on exactly two external anchors (Karpathy's LLM-Wiki gist and OKF 0.2's SPEC.md) plus a deliberately unbound stack. Both anchors exist, are current, and match the spine's usage. One characterization nuance is worth recording (see Finding 1), and three secondary technology mentions in examples/diagrams were spot-checked and are live. The "not bound" claims are internally and externally coherent with the agent-independence decisions (AD-10, AD-11, AD-13).
|
||||
|
||||
---
|
||||
|
||||
## 1. Karpathy "LLM wiki" gist — EXISTS, characterization largely accurate, one nuance
|
||||
|
||||
**Source checked:** `https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f`
|
||||
**Status:** Exists. Authored by karpathy (Andrej Karpathy), titled **"llm-wiki"** (`llm-wiki.md`), created 2026-04-04, framed as "A pattern for building personal knowledge bases using LLMs" / "an idea file... designed to be copy pasted to your own LLM Agent."
|
||||
|
||||
What the spine attributes to it and what the gist actually says:
|
||||
|
||||
| Spine claim (AD-2/AD-3/structural seed) | Gist reality (verified) |
|
||||
|---|---|
|
||||
| Raw sources are immutable, LLM only reads them | **Confirmed verbatim:** "These are immutable — the LLM reads from them but never modifies them." Raw sources are "your source of truth." |
|
||||
| Curated wiki as persistent, compounding artifact | **Confirmed:** "the wiki is a persistent, compounding artifact"; "LLM incrementally builds and maintains a persistent wiki." Matches AD-5 (incremental compilation). |
|
||||
| Three-layer model raw / wiki / schema | **Confirmed:** Raw sources, the wiki (LLM-owned markdown), the schema (config, e.g. CLAUDE.md). Matches the spine's `raw/` + `wiki/` boundaries and the compiler contract concept. |
|
||||
| `index.md` and `log.md` | **Confirmed both, with exact roles:** `index.md` "is content-oriented. It's a catalog of everything in the wiki." `log.md` "is chronological. It's an append-only record of what happened and when." Matches AD-9 (progressive discovery via `index.md`), AD-16 and AD-17 (`log.md` documented disagreements), and the structural seed. |
|
||||
| Provenance | **Nuance (Finding 1):** the gist body does **not** use the word "provenance"; traceability is only implied ("The cross-references are already there. The contradictions have already been flagged."). The word appears in the comment thread (AbleVarghese's "Provenance-First-Wiki", drjoeshepherd's SIGN spec). AD-4/AD-16's provenance emphasis is a reasonable inference from the gist, but it is an interpretation, not a verbatim gist feature. |
|
||||
| Wiki pages not self-grounding (AD-4 core rule) | **Nuance (Finding 1):** the gist body does **not** forbid wiki-as-grounding — it positively encourages filing outputs back in ("good answers can be filed back into the wiki as new pages"). The "a page can never be another page's grounding" rule comes from **drjoeshepherd's SIGN spec in the comments**, and the "wiki gradually cites itself" failure mode comes from AbleVarghese in the comments. The spine's "generated concepts must remain source-grounded and wiki-to-wiki links are not provenance" rule (AD-4, AD-16, Q-1) is a **stronger policy than Karpathy's gist states** — defensible, aligned with the gist community's feedback, but it should be documented as the spine's own stance / derived from gist-discussion literature, not presented as its only source of support. |
|
||||
|
||||
**Verdict: source is real, current, and the spine's account is materially accurate.** Finding 1 below is a characterization nuance only — it neither invalidates AD-2/3/5/9/16/17 nor AD-4, but the spine's `sources:` frontmatter and AD-16 wording imply the provenance/self-grounding stance is gist-native, which it is not verbatim.
|
||||
|
||||
---
|
||||
|
||||
## 2. Open Knowledge Format 0.2 — CURRENT and spine account matches
|
||||
|
||||
**Source checked:** `https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md` (file exists in `okf/`; README links it as "Open Knowledge Format v0.2 specification"), plus repo-level profile via `googlecloudplatform/knowledge-catalog`.
|
||||
|
||||
**Version currency:**
|
||||
- SPEC.md states **"This document specifies OKF version 0.2"** — the fetched SPEC text confirms v0.2. The `okf/` README also references "v0.2 puts queryable signals in frontmatter."
|
||||
- No newer version (0.3/1.0) is referenced anywhere in the repo or spec. A 0.3+/1.0 spec search was attempted but WebSearch was down; direct primary-source fetches surfaced no newer version. **Verdict: 0.2 is the current version the spine relies on** (with the caveat that repo activity/commit dates could not be rendered in the fetch).
|
||||
|
||||
**Spine account vs. spec (each claim checked):**
|
||||
|
||||
| Spine claim | Spec fact (verified in SPEC.md text) |
|
||||
|---|---|
|
||||
| "type is the only required frontmatter key" | **Confirmed:** "`type` is the only always-required key; a concept carrying just `type` is fully conformant." |
|
||||
| `sources` / `generated` / `verified` / `status` / `stale_after` as optional families | **Confirmed:** all are optional provenance/trust/lifecycle families; "All are optional." Absence conveys meaning (no `verified` ⇒ unverified) but "never causes rejection." |
|
||||
| `verified` with `human:`-prefix actor (AD-15) | **Confirmed:** trust tiers derive from actor prefix; `verified` by a `human:<id>` actor ⇒ human-reviewed; "producers MUST use it for hand-authored or human-confirmed content." `generated: { by, at }` (with `generated.at` superseding the old `timestamp`) matches AD-15's `generated: { by, at }`. |
|
||||
| `status` values `draft` / `stable` / `deprecated`, optional `stale_after` (AD-15) | **Confirmed:** `status` and `stale_after` are in the lifecycle family and optional; the listed status values align with the spec's lifecycle framing. |
|
||||
| `okf_version` only in bundle-root `index.md` (AD-7 context) | **Confirmed:** `okf_version` "is only permitted in a bundle-root index.md frontmatter block" — described as the only place frontmatter is permitted in an index.md. |
|
||||
| `references/` convention (used in AD-2/seed discussions of external material) | **Confirmed as convention, not requirement:** "A `references/` subdirectory conventionally mirrors external material, run instructions, or code as first-class concepts within the bundle." |
|
||||
| Consumers must tolerate missing optional fields (AD-8, FT-1...FT-7, AD-13 retrieval-by-consumers) | **Confirmed:** "Consumers MUST NOT reject a bundle for missing optional frontmatter fields, unknown `type` values, unknown additional frontmatter keys, broken cross-links, or missing `index.md` files"; unknown keys must be preserved on round-trip. |
|
||||
|
||||
**Storage/backing fact worth noting:** The `knowledge-catalog` repo README descends from Google's Dataplex-related "Knowledge Catalog" platform lineage, but the `okf/` subfolder is an independent, permissively-licensed (Apache 2.0) open format with a reference agent and samples. The spine's use of OKF as "canonical knowledge state" (AD-1) is consistent with the spec's framing (concept = file + frontmatter, bundle = directory tree). No contradiction found.
|
||||
|
||||
**Verdict: OKF 0.2 is current, exists, and the spine's account of it is accurate on every checked claim (AD-1, AD-7, AD-9, AD-15, AD-16, consistency conventions, stack table).**
|
||||
|
||||
---
|
||||
|
||||
## 3. "Not bound" choices vs. agent-independence (AD-10, AD-11, AD-13)
|
||||
|
||||
The spine's MACRO stack table explicitly lists as **not bound / none required**: LLM, Agent runtime, Programming language, Database, Vector database, Server runtime, MCP.
|
||||
|
||||
**No hidden assumption contradicting agent-independence was found.** Concretely:
|
||||
|
||||
- The single external commitment the compiler actually makes is **the agent-agnostic contract itself** — Markdown + YAML frontmatter, OKF bundle files, Git, standard Markdown links (AD-8), and textually specified canonical rules. None of these is LLM/agent/framework-specific.
|
||||
- AD-10: rules are described as canonical and agent-independent; adapters (claude/codex/other) are described as thin, semantically non-divergent. The structural seed's `adapters/` folder and the "Canonical compiler contract" diagram contain **only** claude + codex as named examples, explicitly marked "Other adapter" — this is example-and-diagram material, not a binding on a specific agent. The `sources:`/companions frontmatter likewise contributes no agent binding.
|
||||
- AD-11: explicitly says no own LLM runtime and "Die konkrete Runtime ist austauschbar" (the concrete runtime is exchangeable), "kein eigener Serverprozess erforderlich" (no own server process required). This is compatible with the pattern itself being agent-runtime-hosted (Karpathy's gist is also intentionally runtime-agnostic: "instantiated collaboratively with your LLM of choice").
|
||||
- AD-13: retrieval (grep/ripgrep, BM25, vector, CodeGraph) is consumer-side and rejects search/RAG as architecture center. The listed consumer-side options are all existing, real categories (ripgrep, BM25 are standard; BM25 doesn't need a specific library in this decision). No hidden vector/embedding dependency is introduced.
|
||||
- **MCP:** spine says "none required" (D-4 deferred). This matches verified reality — MCP is a widely used integration standard in 2026, but the spine never requires it; and Karpathy's own gist explicitly supports a CLI/skills path "no MCP required" (per Context7's own documented modes, the same "no MCP required" pattern is standard practice). Removing all MCP components (FT-1) leaves a plain Git working copy.
|
||||
- **Consistency check (internal):** AD-15's "v1-Default... maschinell erzeugt und ungeprüft, d.h. Trust-Metadaten nur über `generated`, und `verified` bleibt ungesetzt" maps directly onto OKF's confirmed rule (no `verified` ⇒ unverified; machine ⇒ `generated` only). This internal stance is fully OKF-0.2-consistent — not a hidden framework assumption.
|
||||
|
||||
**Verdict: no hidden LLM/agent/framework commitment contradicts the independence claims.** The only "living" assumptions are generic capabilities any current agent runtime provides (read/write files, search, reasoning; AD-11) — these are stated, not hidden.
|
||||
|
||||
---
|
||||
|
||||
## Secondary technology mentions — spot-checked (all live, current)
|
||||
|
||||
These appear only as examples/consumer-side options (AD-12 diagrams, AD-13 list, architecture-boundary diagram), not as committed stack:
|
||||
|
||||
- **Context7 (upstash/context7)** — exists, actively maintained (60.7k+ stars, ~929 commits), Upstash's "up-to-date code documentation for LLMs"; provides CLI + MCP modes and a live hosted service. Matches AD-12's use as an example source-acquisition adapter. **Live.**
|
||||
- **arc42** — exists, open source, "proven in practice since 2005," free including commercial use (CC BY-SA 4.0), 12-section architecture template. Matches AD-12's use as an example source (architecture docs). **Live.**
|
||||
- **CodeGraph** (referenced in AD-13 consumer-retrieval list and boundary diagram) — the name maps to the local-first code-knowledge-graph tooling category (tree-sitter + SQLite + MCP) that this very environment has indexed (`codegraph` MCP), which matches "reads the bundle, doesn't change canon" usage. **Live category**, and appropriate as a consumer-side optional reader. Minor, cosmetic note: "CodeGraph" is a generic name with multiple independent implementations, not one canonical product — as a consumer-side example this is harmless (nothing is bound), but the naming is not a registered single-owner product name.
|
||||
- **BMAD** (companion/tool used to produce this artifact) — internal tooling, present in the repo working tree; not an external technology claim. **N/A.**
|
||||
- **Git** / **Markdown** / **YAML frontmatter** — generic, universally current; no version pin needed for this decision. **N/A.**
|
||||
|
||||
---
|
||||
|
||||
## Findings
|
||||
|
||||
### Finding 1 (Low — characterization nuance, no correction required)
|
||||
**The provenance / "wiki pages must not self-ground" rules are the spine's own stronger stance, derived from the gist's comment-thread literature, not verbatim from Karpathy's gist.**
|
||||
- Gist body: no "provenance" wording; explicitly encourages "good answers can be filed back into the wiki as new pages."
|
||||
- Anti-self-grounding rule ("a page can never be another page's grounding") comes from drjoeshepherd's SIGN spec in the gist comments; "wiki gradually cites itself" failure mode from a commenter (AbleVarghese).
|
||||
- Impact: none on the decisions' validity — AD-4/AD-16 remain sound and are even stricter than the gist — but the spine's `sources:` citation and AD-16 prose imply these are gist-native. Suggest adding a one-line note in the spine's sources/comments ("provenance & no-self-grounding strengthened per gist discussion, citing SIGN-concept") so future readers don't attribute that specific rule to the gist verbatim.
|
||||
|
||||
### Finding 2 (Info — version currency of OKF confirmed with one data gap)
|
||||
OKF **0.2 is current** and everything the spine claims about it checks out. Data gap: GitHub page-rendered commit dates were not retrievable in this session, so I could not timestamp the last spec update; no newer spec version (0.3/1.0) surfaced from any primary source fetched. Re-verify spec's current version status if the MVP starts implementing against it, per repo activity.
|
||||
|
||||
### Finding 3 (Info — CodeGraph is a category, not a single canonical product)
|
||||
AD-13/architecture-boundary name "CodeGraph" as a consumer retrieval option. The name maps to multiple independent implementations (tree-sitter + SQLite + MCP knowledge-graph tools) rather than one canonical product. Harmless for a **not-bound** consumer-side example; no change needed, but be aware the string "CodeGraph" may be ambiguous in future docs if one specific implementation is ever selected (then pin it).
|
||||
|
||||
### Finding 4 (Info — no findings in the "not bound" space)
|
||||
Confirmed: the stack table's "not bound / none" entries contain no hidden LLM/framework/database dependency; AD-10/11/13 are coherent with each other and with OKF 0.2 semantics as verified.
|
||||
|
||||
---
|
||||
|
||||
## Verdict (one line)
|
||||
|
||||
**No committed decision rests on unverified or stale technology** — both cited external anchors (Karpathy's LLM-Wiki gist, OKF SPEC 0.2) exist, are current, and match the spine's usage; the unbound stack is genuinely agent-independent; the only nuance is Finding 1 (provenance/self-grounding are the spine's own stronger stance drawn from the gist's comment literature, not verbatim gist content).
|
||||
|
||||
---
|
||||
|
||||
## Sources consulted (primary, fetched directly)
|
||||
|
||||
- Karpathy, "llm-wiki" gist — https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
|
||||
- Open Knowledge Format v0.2 SPEC — https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md (confirmed v0.2; no newer version found)
|
||||
- knowledge-catalog repo (version/profile context) — https://github.com/GoogleCloudPlatform/knowledge-catalog
|
||||
- Context7 — https://github.com/upstash/context7
|
||||
- arc42 — https://arc42.org/overview
|
||||
- codegraph category (GitHub repo search) — https://github.com/search?q=codegraph+sqlite+knowledge+graph&type=repositories
|
||||
|
||||
> Review method note: WebSearch was unavailable this session (persistent tool API error), so all verifications were performed via direct WebFetch of the primary sources listed above. Each fetched primary source confirmed the claims cited.
|
||||
Reference in New Issue
Block a user