jpmschweitzerandClaude Opus 5
6949f800dc
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>
4.6 KiB
4.6 KiB
Project Structure (detailed)
For how wiki/, the generators, systems.db and the runtime relate — which
way the arrows point for any given file — the canonical map is the diagram
docs/diagrams/data-flow/wiki-generator-flow.d2 (D-262), not the tree
below. The tree says where things live; the diagram says who writes them.
wiki/ # THE SEED (11,864 files, the largest tree here). Authored
# world content the generator varies from — NOT a
# reference work, and mostly NOT hand-written.
# See Skill(wiki) before editing anything below.
index.md # the map: 301 systems, 220 named
GOVERNANCE.md # ownership models, status lifecycle, directory rules
_templates/ # 17 templates, one per entity kind — copy to author
authoring/ # 10 guides (monologue, culture, dual-lens, line-id…)
economics/ # INPUT. TOML vocabularies + schema.md. Seeds systems.db
# AND, from Phase 4 on, world content generation
star-systems/ # OUTPUT, 93% of the wiki. Generated by
# tooling/db/wiki_sync.py FROM systems.db + star-map.json
GJ-{id}/ # system dir (hyphenated id)
index.md # no frontmatter; <!-- READ-ONLY --> blocks are
# regenerated — authored prose lives in the named
# sections between them
gttr*.md # Drifter's Guide prose (corridor/system/location)
bodies/{id}/ # body dir (UN-hyphenated id, e.g. GJ820Bc)
index.md # frontmatter IS the body definition: seed,
# land_fraction, axial_tilt_deg — generator INPUT,
# machine-owned, never hand-edited
*.png, *.npz # globe/relief/heightmap renders + terrain grids
markers.json # names-only city pool (D-223)
corporations/ factions/ contraband/ concepts/ triangles/ species/
institutions/ cultural-groups/ lore/ technology/ glossary.md
# INPUT, flat, wiki-is-truth. YAML frontmatter carries
# status (proposed|draft|canonical), cross_refs,
# decision_refs, and `description` — which exists so
# AGENTS can filter before loading whole files
client/ # Godot 4 client
ui/
implant/ # Implant UI component library (D-169): ImplantPanel, ImplantHeader,
# ImplantSeparator, ImplantDataRow, ImplantTextBlock, default_implant.tres
scripts/
autoloads/
hud_groups.gd # HUD z-index layer manager (D-170): GAMEPLAY/INSERT/FULLSCREEN/MODAL modes
rendering/
gameplay_renderer.gd # Base class for occludable renderers; connects to HudGroups signal
server/ # Rust/bevy_ecs simulation server
tooling/ # Build tools, scripts, asset pipelines
tests/ # Integration and end-to-end tests
.config/ # Configuration files (linters, formatters, CI)
.cache/ # Local caches for testing/linting (gitignored)
docs/
discussions/ # Discussion rounds (archived here when complete)
briefings/ # Per-agent context briefings (maintained by Qatux)
architecture/ # Technical architecture documents
design/ # Game design documents
diagrams/ # d2 source + PNG renders
sprints/ # Historical archive (Sprint 1–38) — no new sprint directories
workshops/ # Workshop briefs and outputs
db/
schema.sql # Database schema
tooling/
db/ # Asset/connector scripts (audio, image, trellis, wiki)
config.json # Endpoint configuration
common.py # Shared venv/config helpers
audio_connector.py # Stable Audio Open connector
pql-migrate/ # One-shot scripts from the pql migration (provenance)
.claude/
agents/ # Agent personality files
skills/ # Skill definitions
rules/ # Auto-loaded instruction modules
governance/ # Decision records (pql DQR tree, source of truth)
README.md # Domain guide + pql-maintained record index
decisions/ # D-NNN confirmed — <domain>.md (architecture, perception, content, scope, economics, process)
questions/ # Q-NNN open — <domain>.md
rejected/ # R-NNN rejected — <domain>.md
DECISIONS.md # Redirect to governance/ tree
TEAM.md # Team roster and roles