Files

T

jpmschweitzerandClaude Opus 5 6949f800dc docs(governance): D-262 — the wiki generator flow has one canonical map

The relationship between wiki/, the generators, systems.db and the runtime is
a directed graph with two edges running opposite to the obvious direction and
one running backwards into its own producer. Prose renders that badly: every
document that has described it states a single ownership direction and is
therefore wrong about part of the tree. D-262 makes the diagram the source of
truth and points CLAUDE.md, Skill(wiki), project-structure.md and
wiki/GOVERNANCE.md at it.

The correction that matters most: body pages were described everywhere as
machine-owned and reverted on sync. They are not. scaffold_bodies.py writes
one once and never overwrites it, and import_economics then reads that
frontmatter directly as input — so a hand-edit is not reverted, it is obeyed,
and silently changes world generation. Worse than being overwritten, and the
actual reason GOVERNANCE.md forbids the edit.

New: tooling/check-dataflow-graph.py, wired into the Makefile and the pre-push
hook. It asserts every repo path named in a hand-authored diagram still
resolves — and its docstring states plainly what it cannot do: verify that an
edge still MEANS what it says. If wiki_sync.py stopped writing body pages
tomorrow, every path would still exist and the check would still pass. Edge
semantics stay a human check against the tool's source, so nobody reads a green
gate as a verified map.

Verified by breaking it: pointing one label at a moved path fails with exit 1
naming that path; restoring it passes. Building the checker also caught two
real vaguenesses in the diagram — "GJ-*/index.md" and "bodies/{id}/index.md"
were written without their wiki/star-systems/ prefix, which is precisely the
ambiguity this map exists to remove. Generated star-map .d2 files are excluded
by name; their correctness belongs to their generator under D-223.

Also files Q-124 + T-1246 (tooling): whether the 123 Python files under
tooling/ should become one Rust CLI of pql's calibre. The friction is real and
mostly not about the language — the permission gate prefix-matches whole
command strings and a blanket Bash(python3 *) grant is forbidden, so each tool
prompts near-individually, while a single binary is one allowlist entry. The
record requires pricing the cheap alternative (a Python dispatcher entrypoint)
before recommending Rust, and flags the hard constraint: import_economics is
stamped by source SHA, so any port must keep that contract intact through the
transition rather than disabled during it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-20 01:56:12 +02:00

6.8 KiB

Raw Permalink Blame History

Wiki Governance

Owner: Miri (structure and worldbuilding) Contributors: Anyone on the team, following templates

Two Ownership Models

The canonical map of this is a diagram (D-262): docs/diagrams/data-flow/wiki-generator-flow.d2. Every edge in it was read in the generator's own source. The two models below are a summary; the diagram also records the parts that do not fit a two-way split — wiki_sync.py runs in both directions, and body pages are read back into the generator as input. Where this text and the diagram disagree, the diagram is right.

The wiki has two kinds of content with different sources of truth (see tooling/db/wiki_sync.py):

DB owns structured fields, wiki owns prose (star-systems/): identity, gates, history, economy, factions, and culture live in server/data/systems.db and are rendered into READ-ONLY page sections. Authored prose sections (Supply Dependency, Faction Notes, Silence Topic, Narrative Hook, Calibration Note) are written in the wiki and preserved across regeneration. Never edit a section marked  — it will be overwritten by the next sync.
Wiki is truth (flat categories): corporations/, factions/, contraband/, economics/, etc. are authored markdown (plus TOML in economics/). Where machine-readable, the generators import FROM the wiki (e.g. corporation frontmatter → systems.db per D-182).

Status Lifecycle

Authored flat-category entries (corporations, factions, contraband, concepts, triangles, …) carry a status field in their YAML frontmatter:

Status	Meaning	Who Can Set
`proposed`	Under consideration, not yet reviewed	Anyone
`draft`	In review, content being refined	Author + reviewer
`canonical`	Confirmed setting truth, safe to reference	Miri or project lead

Progression: proposed → draft → canonical

Demotion: A canonical entry can be demoted to draft if a decision changes its foundation. Only Miri or the project lead can demote canonical entries.

Out of scope: generated star-systems/ pages have no status field. System pages carry no frontmatter at all; body pages carry frontmatter that IS the body definition (machine-owned, see below), not an editorial status.

Creating New Entries

For flat-category entries:

Copy the appropriate template from _templates/
Fill in the YAML frontmatter (all fields)
Write a concise description — one line that captures what makes this entry distinct. This field enables context-aware loading (agents filter by description before loading full files).
Set status: proposed
Write the content following the template structure
Submit for review

Templates available: star-system, station, district, location, character, faction, technology, cultural-group, contraband, institution, species, lore, concept, triangle

Do not hand-create system or body pages under star-systems/ — they are produced by the generator pipeline (wiki_sync.py, the atlas sync, and scaffold_bodies.py). Authoring happens inside the designated prose sections of generated pages, or in the GTTR files alongside them.

Directory Rules

Spatial Hierarchy (`star-systems/`) — generated

star-systems/
  index.md                      # Sector/hop navigation (companions as unlinked text)
  catalog.md                    # Full table of all systems by GJ designation
  gttr-{corridor}.md            # Corridor-level Drifter's Guide prose (core, east, …)
  GJ-{id}/
    index.md                    # System page — NO frontmatter:
                                #   title block + System Profile (READ-ONLY, systems.db)
                                #   + authored prose sections (Supply Dependency,
                                #     Faction Notes, Silence Topic, Narrative Hook,
                                #     Calibration Note)
                                #   + Topology (READ-ONLY, star-map.json)
                                #   + Celestial Bodies / Stations & Facilities tables
                                #     (READ-ONLY, systems.db via atlas sync)
                                #   + Stations GTTR link line
    gttr.md                     # System-level Drifter's Guide prose (→ gttr_hook)
    gttr-{location}.md          # Station/settlement-level Guide prose, flat per system
    bodies/
      {body_id}/
        index.md                # Body page — YAML frontmatter IS the body definition
                                #   (generator input; e.g. axial_tilt feeds
                                #   import_economics). Prose below the frontmatter.
        globe.png               # Rendered globe (all bodies)
        reliefmap.png           # Color hypsometric render (non-gas bodies)
        heightmap.png           # 16-bit canonical elevation — inhabited bodies only
        terrain.npz             # Simulation grids
        markers.json            # Names-only city markers (D-223) → atlas_city_names

Stations and districts have no wiki directories. They are rows in systems.db, rendered into each system page's Stations & Facilities table. Station-level prose lives in flat gttr-{slug}.md files in the system dir.
Body directories are keyed by body id (e.g. GJ71d-1), not by display-name slug.
Never edit READ-ONLY sections or bodies/*/index.md frontmatter by hand — regenerate from sources instead.

Flat Categories

All other categories use flat file structure:

{category}/
  {entry-slug}.md

No nesting within flat categories. Use cross_refs in frontmatter for relationships.

Cross-Referencing

Use cross_refs in YAML frontmatter for machine-readable references (slugs only)
Use markdown links in body text for human-readable navigation
Use decision_refs for links to governance/decisions/*.md entries (e.g., [D-036])

Scale Considerations

The generated spatial model already covers the full Reach (~301 systems, ~2,600 body pages):

Each system is a self-contained generated directory tree; adding systems means adding rows to the sources (systems.db pipeline + star-map.json), not hand-building directories
Cross-system references in prose use relative links to GJ-{id}/index.md
Characters, factions, and other flat categories remain at wiki root — they are not nested per system

Naming Conventions

File slugs: lowercase, hyphenated (e.g., vuurkloof.md, freight-exchange.md)
System directories: GJ designation with hyphen (e.g., GJ-71/, GJ-820B/)
Body directories: body id from the Celestial Bodies table (e.g., GJ71d-1/)
Canonical IDs: match content schema format (e.g., npc:{character-slug})
Display names: title case, as they appear in-game

Last updated: 2026-06-12

6.8 KiB Raw Permalink Blame History