wow20/raw/architecture-spine/architecture-spine-2026-08-14.md

name, type, purpose, altitude, paradigm, scope, status, created, updated, binds, sources, companions

name	type	purpose	altitude	paradigm	scope	status	created	updated	binds	sources	companions
Wiki of Wikis	architecture-spine	build-substrate	product	agent-native file-based compiler pipeline	Wiki of Wikis MVP	final	2026-08-14	2026-08-14	FR-1..FR-16 NFR-1..NFR-7	PRD — Wiki of Wikis Andrej Karpathy — LLM Wiki Open Knowledge Format 0.2	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.

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.

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.

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.

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 based on , 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:

Existing Knowledge
       +
New Source Material
       ↓
Interpret
       ↓
Reconcile
       ↓
Synthesize
       ↓
Update affected Concepts

Nicht:

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.

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:

wiki/
  flowable/
    timers.md

Concept ID:

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:

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.

Markdown Links
      ↓
optional derivation
      ↓
Knowledge Graph

Nicht:

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:

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.

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:

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:

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:

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.

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.

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

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:

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.