EVOLV/wiki/Archive/SCHEMA.md

⚠️ ARCHIVED — pre-refactor (Tier 1–4, 2026-05)

This page describes the architecture before the platform refactor. The current page is the per-node wiki on gitea.wbd-rd.nl/RnD or Home.

Kept for historical reference only. Do not update.

Project Wiki Schema

Purpose

LLM-maintained knowledge base for this project. The LLM writes and maintains everything. You read it (ideally in Obsidian). Knowledge compounds across sessions instead of being lost in chat history.

Directory Structure

wiki/
  SCHEMA.md          — this file (how to maintain the wiki)
  index.md           — catalog of all pages with one-line summaries
  log.md             — chronological record of updates
  overview.md        — project overview and current status
  metrics.md         — all numbers with provenance
  knowledge-graph.yaml — structured data, machine-queryable
  tools/             — search, lint, query scripts
  concepts/          — core ideas and mechanisms
  architecture/      — design decisions, system internals
  findings/          — honest results (what worked AND what didn't)
  sessions/          — per-session summaries

Page Conventions

Frontmatter

Every page starts with YAML frontmatter:

---
title: Page Title
created: YYYY-MM-DD
updated: YYYY-MM-DD
status: proven | disproven | evolving | speculative
tags: [tag1, tag2]
sources: [path/to/file.py, commit abc1234]
---

Status values

• proven: tested and verified with evidence
• disproven: tested and honestly shown NOT to work (document WHY)
• evolving: partially working, boundary not fully mapped
• speculative: proposed but not yet tested

Cross-references

Use [[Page Name]] Obsidian-style wikilinks.

Contradictions

When new evidence contradicts a prior claim, DON'T delete the old claim. Add:

> [!warning] Superseded
> This was shown to be incorrect on YYYY-MM-DD. See [[New Finding]].

Honesty rule

If something doesn't work, say so. If a result was a false positive, document how it was discovered. The wiki must be trustworthy.

Operations

Ingest (after a session or new source)

1. Read outputs, commits, findings
2. Update relevant pages
3. Create new pages for new concepts
4. Update index.md, log.md, knowledge-graph.yaml
5. Check for contradictions with existing pages

Query

1. Use python3 wiki/tools/query.py for structured lookup
2. Use wiki/tools/search.sh for full-text
3. Read index.md to find relevant pages
4. File valuable answers back into the wiki

Lint (periodically)

bash wiki/tools/lint.sh

Checks: orphan pages, broken wikilinks, missing frontmatter, index completeness.

Data Layer

• knowledge-graph.yaml — structured YAML with every metric and data point
• metrics.md — human-readable dashboard
• When adding new results, update BOTH the wiki page AND the knowledge graph
• The knowledge graph is the single source of truth for numbers

Source of Truth Hierarchy

1. Test results (actual outputs) — highest authority
2. Code (current state) — second authority
3. Knowledge graph (knowledge-graph.yaml) — structured metrics
4. Wiki pages — synthesis, may lag
5. Chat/memory — ephemeral, may be stale