---
id: SPEC-wow20
companions:
  - ../planning-artifacts/architecture/architecture-wow20-2026-08-14/ARCHITECTURE-SPINE.md
  - glossary.md
sources:
  - ../planning-artifacts/prds/prd-wow20-2026-08-14/prd.md
---

> **Canonical contract.** This SPEC and the files in `companions:` are the complete, preservation-validated contract for what to build, test, and validate. Source documents listed in frontmatter are for traceability — consult them only if you need narrative rationale or prose color this contract intentionally omits.

# Wiki of Wikis

## Why

**Wiki of Wikis** is a **Knowledge Compiler**, not a retrieval system. It applies Andrej Karpathy's **LLM-Wiki principle**: raw sources are not re-searched and re-interpreted at every query, but are incrementally compiled by an LLM into a persistent, curated, OKF-compliant wiki that compounds knowledge over time. The problem: with growing heterogeneous sources (docs, specs, project artifacts), each query re-derives synthesis from raw material instead of building on already-distilled knowledge. The opportunity to capture: a portable, Git-versioned Markdown knowledge bundle that humans, LLM agents, BMAD, Claude Code, Codex, and other consumers can all use — without a database, server, or proprietary runtime. It transforms **Sources + existing knowledge → improved curated knowledge**.

## Capabilities

- **CAP-1** (FR-1) — **Source intake**
  - **intent:** The user can provide the compiler one or more source materials for a Compilation Run, without first deciding which concept each source belongs to.
  - **success:** A single run accepts 1..n sources; in v1 only locally provided material (no URL retrieval in the compiler core).
- **CAP-2** (FR-2) — **Source/Knowledge separation**
  - **intent:** The system keeps Source Material and the Knowledge Bundle physically and semantically distinct (`raw/` vs. `wiki/`).
  - **success:** Copying a source document is not counted as knowledge integration; consumers can tell Sources from Curated Knowledge.
- **CAP-3** (FR-3) — **Provenance**
  - **intent:** Derived knowledge retains traceable provenance to its sources.
  - **success:** Each created/updated concept references its underlying sources (AD-4a); multiple contributing sources are jointly documented; new sources don't accidentally strip existing provenance.
- **CAP-4** (FR-4) — **Compile against existing knowledge**
  - **intent:** A run processes new source material together with relevant existing curated knowledge.
  - **success:** The existing wiki is input; already-distilled insights need not be rebuilt from raw sources.
- **CAP-5** (FR-5) — **Create concepts**
  - **intent:** The compiler can produce new standalone knowledge units from source material.
  - **success:** New concepts arise; multiple sections of one source may feed different concepts; concepts are not bound to source structure.
- **CAP-6** (FR-6) — **Update existing concepts**
  - **intent:** The compiler can extend, refine, or correct existing concepts.
  - **success:** New information does not automatically create new files; relationships and provenance stay intact where still valid.
- **CAP-7** (FR-7) — **Synthesize knowledge**
  - **intent:** The compiler merges information from multiple sources into a shared knowledge representation.
  - **success:** Multiple sources on the same topic do not end in separate summaries; redundancy is consolidated; the result reflects the recognized knowledge state with merged provenance.
- **CAP-8** (FR-8) — **Handle contradictions visibly**
  - **intent:** Contradictory information is never silently merged into a seemingly unambiguous statement.
  - **success:** Relevant contradictions remain as explicit disagreements in `log.md` (AD-16a preservation default); sources stay traceable; uncertainty may be part of a concept.
- **CAP-9** (FR-9) — **OKF-conformant concepts**
  - **intent:** All generated concepts conform to Open Knowledge Format 0.2 (Markdown + YAML frontmatter, `type` required, optional `sources`/`generated`/`verified`/`status`/`stale_after`).
  - **success:** The bundle validates against `schema/wiki-compiler.md` (AD-1a); no own OKF dialect.
- **CAP-10** (FR-10) — **Link concepts**
  - **intent:** The compiler expresses relationships between concepts with normal Markdown links (one pinned form, AD-7b).
  - **success:** Linked concepts are navigable; consumers need no proprietary software; traversal by agents works.
- **CAP-11** (FR-11) — **Progressive discovery**
  - **intent:** A consumer can discover knowledge stepwise without reading everything, via hierarchy + `index.md`.
  - **success:** Overview first, then open relevant concepts; no proprietary database needed for navigation.
- **CAP-12** (FR-12) — **Incremental evolution**
  - **intent:** A run evolves an existing bundle rather than generating an independent wiki anew.
  - **success:** Unchanged knowledge is preserved; changes concentrate on concepts affected by new insights (AD-5).
- **CAP-13** (FR-13) — **Respect human curation**
  - **intent:** Manually curated content remains existing knowledge; conflicts between human curation and new sources become visible.
  - **success:** A run does not remove human additions merely for lacking provenance from this run; human-reviewed content stays distinguishable from unverified machine output (AD-15); a human can edit concepts directly and the correction survives (FT-9).
- **CAP-14** (FR-14) — **Traceable changes**
  - **intent:** Changes to concepts remain traceable via normal version-control mechanisms.
  - **success:** Git diff shows relevant changes; no proprietary change tracking needed; commit boundary is the mutation boundary (AD-17f).
- **CAP-15** (FR-15) — **Tool-independent access**
  - **intent:** A consumer can read the bundle without a Wiki-of-Wikis-specific runtime.
  - **success:** Humans read concepts with normal Markdown tools; LLM agents read via standard file operations; no proprietary SDK (NFR-1/2/3/5).
- **CAP-16** (FR-16) — **Consumer decoupling**
  - **intent:** The bundle is not tailored to a particular LLM agent or workflow.
  - **success:** BMAD, Claude Code, Codex, and future agents can all be consumers; switching consumers requires no migration of the knowledge format (AD-10).

## Constraints

- **OKF 0.2 is the normative format.** Markdown + YAML frontmatter; `type` is the only required field; optional `sources`/`generated`/`verified` (`human:` prefix)/`status`/`stale_after`; no own OKF dialect; bundle root = `wiki/`; `okf_version` only in bundle-root `index.md` (AD-1, AD-1a, FR-9).
- **Canonical state is the Git-versioned OKF Knowledge Bundle.** Derived indexes/caches/embeddings are rebuildable and never the source of truth (AD-1, AD-14).
- **Separation of Concerns:** Sources → Compilation → Knowledge Bundle → Consumers. A consumer is never a prerequisite for compilation; a source never automatically becomes curated knowledge (AD-2, AD-12).
- **Sources are immutable.** Compilation never modifies source material; copying into `wiki/` is not compilation (AD-3).
- **Provenance is claim-granular; `sources` entries never point at `wiki/` paths** (AD-4a/b/c). A generated concept is never the sole provenance of another.
- **Compilation is incremental** (AD-5); reasoning is separated from mutation (AD-6); concept identity is its OKF path (AD-7/7a); conflicts are preserved explicitly, never silently resolved (AD-16/16a/16b).
- **Coordinated producer writes.** Lease/branch-based workspace convention (`lease/<area>/<id>` + lockfile); no textual auto-merge over the same concept path; lease root-scope includes `log.md` and `index.md`; dirty-tree protection; commit boundary is the mutation boundary; determinism contract: same state + same input → same bundle (AD-17a..h).
- **Relevance determination is textual-deterministic** (grep / ripgrep / markdown traversal / link following), never embedding/vector infrastructure (AD-13, AD-17 appendix, PRD OQ-3).
- **No server process / own LLM runtime in the MVP** (AD-11); agent-independent compiler contract, thin adapters (AD-10).
- **Complexity guardrail:** new infrastructure belongs in the core only if required for "Sources + existing knowledge → improved curated knowledge", otherwise it is a Source/Consumer adapter, not a core component (FT-8, PRD §8.4).
- **MVP boundary:** v1 accepts only locally provided source material (no URL retrieval); no GUI; no interactive block-until-resolution model (PRD A-3/A-4).

## Non-goals

- **Retrieval is consumer behavior, not the compiler core:** no vector database, no vector search, no knowledge-graph database, no RAG platform, no enterprise search, no search backbone (AD-13).
- **No MCP server, no web UI, no wiki rendering server** in the MVP.
- **No automatic internet research, no general web crawler, no automatic scheduling, no automatic source observation.**
- **No BMAD-specific, Claude-Code-specific, or CodeGraph-specific integration** — these are sources/consumers (PRD A-5).
- **No multi-user rights system, no enterprise governance, no proprietary OKF dialect, no extra knowledge schema besides OKF.**
- **Not** a document management/archiving platform, a CMS, an Obsidian/Confluence alternative, a code-analysis platform, or a project-management platform.

## Success signal

**"Knowledge should compound."** After a second Compilation Run, the system evolves existing knowledge without regenerating the bundle from scratch (SM-1/FT-6); a new source produces curated concepts or concept changes with traceable provenance rather than a copy or paraphrase (SM-2/SM-3); a previously unrelated LLM agent can read the bundle via ordinary Markdown files and use it without Wiki-of-Wikis-specific APIs (SM-4); and the bundle stays fully readable when the compiler/LLM/indexes are unavailable (SM-5). A human can correct machine-produced content directly and the correction survives (SM-C3/FT-9); two independent runs over the same state produce the same bundle (AD-17h/FT-10).

## Assumptions

- v1 is primarily a personal/team-internal developer tool (PRD A-1); this must not produce a fully autonomous, unsupervised process (SM-C3).
- No dedicated GUI in v1 (PRD A-3).
- Source acquisition is not the product core; the compiler processes provided source material (PRD A-4).
- BMAD, Claude Code, Codex, CodeGraph are sources/consumers, not core components (PRD A-5).
- Machine-generated and unverified is the v1 default (`generated` without `verified`); human review is expressed via `verified` with a `human:`-prefixed actor; implementation lives in `schema/wiki-compiler.md` (AD-1a).

## Open Questions

- **Human-authored concepts:** Should fully manually authored concepts be treated as first-class knowledge, or merely tolerated? (v1 tolerates them via AD-15; open on first-class status.)
- **Source lifecycle / revocation:** What happens to derived knowledge when a source is removed, replaced, or found to be false? (Currently deferred D-5; the revocation case is not yet designed — Owner: Architecture.)
- **Product name:** Is "Wiki of Wikis" the final product name or only the project name? (Owner: PM.)
- **Determinism enforcement:** How is "same state → same bundle" enforced without a dedicated validator in the MVP? (D-3; as an agent-instruction validator until then — Owner: Architecture.)