6d19038784
12 pages covering architecture, findings, and metrics from the rotatingMachine + machineGroupControl hardening work: - Overview: node inventory, what works/doesn't, current scale - Architecture: 3D pump curves, group optimization algorithm - Findings: BEP-Gravitation proof (0.1% of optimum), NCog behavior, curve non-convexity, pump switching stability - Metrics: test counts, power comparison table, performance numbers - Knowledge graph: structured YAML with all data points and provenance - Session log: 2026-04-07 production hardening - Tools: query.py, search.sh, lint.sh Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
90 lines
3.0 KiB
Markdown
90 lines
3.0 KiB
Markdown
# 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:
|
|
```yaml
|
|
---
|
|
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
|
|
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
|