The wiki as a system

Documentation drifts because nothing stops it from drifting: the code changes, the prose doesn’t, and six months later nobody can say why a behavior exists. Supernova’s answer is to make the docs a machine-validated artifact — a requirement graph the build is not allowed to diverge from, checked by a blocking gate on every commit. The founding directive is Matt’s, verbatim: “point of system is that every bug, inconsistency, missing feature or quirky behavior is traceable back to concrete root cause all way to creation of feature.”

This design carries over nearly verbatim from automatt, the predecessor platform, where it runs in production [live in automatt]. Matt’s carry-over ruling (2026-06-04): “I have yet to see anyone else build anything even close to as comprehensive as wiki system we use.” The Rust reimplementation is further along than most of Supernova — it is the working gate on the Supernova repo itself today — but it is in-repo proof, not a deployed service [built in-repo].

Three layers, one mapping

RII is the build contract for a system: what it must do, what must never be false, and what it exposes. Matt mandated the triple on 2026-06-04 (“for each system I want requirements + invariants + interfaces”), and on 2026-06-20 it graduated from convention to a validator-enforced rule. Every system folder must also have an index.md that references each sibling file — likewise a validated requirement, not a habit.

The spec layer is where the contract touches code. The path mapping is mechanical: prepend wiki/specs/, append .spec.md. The wiki system’s own invariant WIKI-I1 states it flatly: “Deterministic spec path mapping is sacred.” No exceptions, no overrides — this is what makes traceability work without search. The inverse holds too: a spec without a source file, or an annotated source file without a spec, is a validation error. Inside each spec, numbered requirements (R#s) form a DAG with typed evidence obligations and line-level source annotations; that machinery — percolation, @R# spans, evidence kinds, coverage joins — is the subject of the requirements page.

Frontmatter is typed

Every wiki page must carry title, category, updated, and author. The status: field is a closed enum — draft | living | ratified | superseded | historical | findings — collapsed in June 2026 from roughly fifteen ad-hoc values that had sprawled across the corpus. Historical and superseded docs additionally carry current_truth: false, so a reader or a validator can tell a settled truth from a captured artifact without parsing prose. Spec files add two more fields: source: (the repo-relative path they mirror) and covers: (references up to the design-level requirements they implement). None of this is convention; every field is checked.

The validator is the gate

sun wiki validate is a pre-commit gate with deliberately binary semantics — per the wiki requirements doc, “a failed validation gate crashes the commit; it never degrades to ‘warn and allow.’” The same checks run in a second mode, --audit, which surfaces findings as data for the monitor system (described on the supporting-cast page) instead of blocking.

flowchart LR
    C["commit attempt"] -->|"pre-commit hook"| V["sun wiki validate"]
    V -->|"gate mode"| K["links, frontmatter, mapping, RII shape, DAG, annotations, evidence"]
    K -->|"all pass"| OK["commit lands"]
    K -->|"any failure"| X["commit crashes"]
    V -.->|"--audit mode"| M["findings stream to monitor"]

What it enforces on the Supernova repo today, verified against the readiness dashboard (2026-06-30):

The staging of the standards row is stated in the standards doc itself: until each mechanical check lands, that standard is “enforced by review … [which] is honor-system and exactly why the mechanical checks are the priority.”

Why this beats prose docs

The thesis, from the standards doc: “Uniform shape is what makes the docs a build contract rather than a sketch.” With prose docs, drift is a discovery someone makes; here, drift is a computed error with a location. Rename a file without its spec — error. Change a requirement’s text — its done status reverts to draft, because done-ness must not outlive its description. Delete a requirement something still references — blocked until the last inbound reference is gone. Cite a test as evidence that doesn’t actually execute the annotated lines — fails closed (the per-test coverage rule, from Matt’s 2026-06-25 parity directive).

Each rule earned its place through a concrete corpus failure. Six incompatible invariant-ID styles made review citations unresolvable, so IDs got a scheme. A superseded design survived as authoritative prose on the same page that marked its replacement done, so supersession now propagates mechanically. A plausible-but-wrong config path survived multiple semantic audits, which produced the grounding rule in the standards catalog: “Reviewers, human or AI, get fooled by plausibility; grounding does not” (standard S22, anchored in Matt’s D35 ruling). The standards themselves became a validated wiki artifact by ruling D22 (2026-06-18) — with the explicit rider that “it will need enforcement mechanisms too.”

One boundary worth noting: the wiki deliberately does not own all provenance. D59 (2026-06-20) ruled provenance a cross-cutting concept realized in four slices — auth answers who, the bus’s trail answers what happened, the wiki answers why does this requirement exist, vcs answers what changed in code — with a unified grading surface planned as a monitor read-lens. An earlier framing that put case-law inside the wiki was superseded, and its requirement retired as a tombstone in the graph.

Self-hosting

The wiki system is itself a Supernova system, with its own RII doc (R0–R34, twenty invariants), its own per-file specs, and its own annotations — validated by the very gate it implements. The Rust crate is about 8,000 lines across 16 modules (the validator alone is 2,564 lines) with 18 test modules and no TODO(req:) stubs in source. The corpus it gates is 250 spec files (a count measured on the Rust page) carrying roughly a thousand requirements, and all of it passes the gate. The gate is also how the delivery flow knows when work is actually done: requirements close on evidence the validator can check, not on a human ticking a box.

That self-hosting is real, and it is also the ceiling of the claim: the readiness verdict for the wiki row is “partial.” Bus events flow through a file-backed outbox with tests; real broker delivery exists only in opt-in end-to-end runs [built in-repo]. Several capabilities marked done in the requirements doc are done on unit evidence — proven in-repo, never production-exercised.

What this costs

• Authoring overhead is enormous. Every source file needs a spec, every code-bearing line an annotation, every requirement five fields plus a typed proof obligation. This is tractable because agents write most of it; for a human-only team it would be brutal. The design quietly assumes agent labor at scale.
• Status words can still overstate. The readiness dashboard exists precisely because R# statuses alone conflate in-repo proof with live capability — a requirement can be done on a single unit test. The dashboard is the correction, but it is a second thing to keep honest.
• The enforcement layer is partially aspirational. Standards are normative with specced checks, yet many checks are tracked follow-ons; until wired they fall back to exactly the honor-system review the doc warns about.
• The gate is load-bearing infrastructure. Every commit passes through it; a validator bug or an over-strict check halts all work. Crash-never-degrade is deliberate, but it concentrates risk in one binary.
• Design churn left scar tissue. Test: became Evidence:; a standalone refactor verb was folded into move/rename; the case-law framing was superseded by D59. The machinery handles supersession cleanly, but each superseded framing had already propagated before it was corrected.
• Open questions remain: percolation performance on large DAGs is untested at scale, the store substrate (filesystem vs database) is unresolved, and validator error reporting is a flat error list.