11 KiB
11 KiB
id, companions, sources
| id | companions | sources | |||
|---|---|---|---|---|---|
| SPEC-wow20 |
|
|
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.
- intent: The system keeps Source Material and the Knowledge Bundle physically and semantically distinct (
- 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,
typerequired, optionalsources/generated/verified/status/stale_after). - success: The bundle validates against
schema/wiki-compiler.md(AD-1a); no own OKF dialect.
- intent: All generated concepts conform to Open Knowledge Format 0.2 (Markdown + YAML frontmatter,
- 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.
- intent: A consumer can discover knowledge stepwise without reading everything, via hierarchy +
- 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;
typeis the only required field; optionalsources/generated/verified(human:prefix)/status/stale_after; no own OKF dialect; bundle root =wiki/;okf_versiononly in bundle-rootindex.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;
sourcesentries never point atwiki/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 includeslog.mdandindex.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 (
generatedwithoutverified); human review is expressed viaverifiedwith ahuman:-prefixed actor; implementation lives inschema/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.)