From e46d8732e5362d2d9e079892237226cb2a0cde07 Mon Sep 17 00:00:00 2001 From: Cameron Date: Tue, 7 Jul 2026 01:31:30 -0700 Subject: [PATCH] Wiki migration stage 1/4: adopt the skeleton MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cameron approved spec/wiki.md's shape ("I like the wiki format... go ahead and implement the wiki thing"). Migrating in four staged commits per the spec's own plan (Adopt, Move, Render, Absorb history), each landed independently so an interruption leaves a working tree. This stage is purely additive: new wiki/ directory tree (vision, mechanics, gameplay, world/{characters,places,story}, interface, art, engineering, process, log) with a README index per directory; a skeleton wiki/SUMMARY.md in mdBook nav format; spec/meta.md gains the Type: spec | knowledge | log page-type convention so bindingness travels with a page's frontmatter instead of its directory, and repoints its self-references at the coming wiki/process/specs.md. spec/wiki.md Status moves DRAFT -> IN PROGRESS with a running stage note, its "one PR each" language updated to the current direct-to-main process, and prompts/ is named explicitly as staying outside the migration (ejectable dispatch text, not documentation). No file moved yet. Defense: constitution "The constitution rule" (the amendment ships with the change) and "Justification and legibility" applied to the docs themselves (spec/wiki.md's own rationale) — this is a docs-only, zero-collision-risk stage of an approved migration; the DESIGN.md decisions log entry is the amendment. --- DESIGN.md | 15 ++++++++++++ DEVLOG.md | 28 +++++++++++++++++++++ spec/meta.md | 43 +++++++++++++++++++++++++++++---- spec/wiki.md | 39 ++++++++++++++++++++---------- wiki/SUMMARY.md | 16 ++++++++++++ wiki/art/README.md | 6 +++++ wiki/engineering/README.md | 8 ++++++ wiki/gameplay/README.md | 8 ++++++ wiki/interface/README.md | 7 ++++++ wiki/log/README.md | 7 ++++++ wiki/mechanics/README.md | 8 ++++++ wiki/process/README.md | 7 ++++++ wiki/vision/README.md | 8 ++++++ wiki/world/README.md | 7 ++++++ wiki/world/characters/README.md | 8 ++++++ wiki/world/places/README.md | 6 +++++ wiki/world/story/README.md | 8 ++++++ 17 files changed, 211 insertions(+), 18 deletions(-) create mode 100644 wiki/SUMMARY.md create mode 100644 wiki/art/README.md create mode 100644 wiki/engineering/README.md create mode 100644 wiki/gameplay/README.md create mode 100644 wiki/interface/README.md create mode 100644 wiki/log/README.md create mode 100644 wiki/mechanics/README.md create mode 100644 wiki/process/README.md create mode 100644 wiki/vision/README.md create mode 100644 wiki/world/README.md create mode 100644 wiki/world/characters/README.md create mode 100644 wiki/world/places/README.md create mode 100644 wiki/world/story/README.md diff --git a/DESIGN.md b/DESIGN.md index cc5eade..acf1418 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -1531,3 +1531,18 @@ knows."* fantasy — a re-render is simpler and truer); a dedicated build system (a new system violates no-new-systems and the scale law). Specs: spec/views.md, spec/building.md; enriches spec/reach.md. +- **2026-07-07 — The wiki migration: approved and underway.** Cameron + approved spec/wiki.md's shape ("I like the wiki format... go ahead + and implement the wiki thing"); staged as four commits (Adopt, Move, + Render, Absorb history) per the spec's own migration plan, each + landed independently so the work survives an interruption. Stage 1 + (this commit): `wiki/` skeleton with directory READMEs, a skeleton + `wiki/SUMMARY.md`, and the `Type: spec | knowledge | log` page-type + convention added to spec/meta.md (bindingness now travels with the + page's frontmatter, not its directory). `prompts/` is explicitly + named as staying outside the migration — it is ejectable dispatch + text pasted into agents, not documentation, the same exclusion + species as DESIGN.md/AGENT.md. wiki.md's own "one PR each" language + updated to the current direct-to-main process (the PR rule was + removed 2026-07-07, after wiki.md was drafted). See DEVLOG.md for + per-stage progress; spec/wiki.md Status tracks it live. diff --git a/DEVLOG.md b/DEVLOG.md index e3ffbf5..4fcecb5 100644 --- a/DEVLOG.md +++ b/DEVLOG.md @@ -29,6 +29,34 @@ Reverse chronological implementation notes. Keep this factual: what changed, why - Next: Act Two content design; chargen diegetic-frame taste calls; the views.md overt-phase default-snap proposal ([OPEN]). +## 2026-07-07 - Wiki migration, stage 1/4: skeleton adopted + +- Intent: Cameron approved spec/wiki.md's shape; begin the staged + migration (Adopt / Move / Render / Absorb history), each stage a + separate landed commit so an interruption mid-migration leaves a + working tree, not a half-broken one. +- Changed: new `wiki/` directory tree (vision, mechanics, gameplay, + world/{characters,places,story}, interface, art, engineering, + process, log), each with a README index. Skeleton `wiki/SUMMARY.md` + (mdBook nav format). spec/meta.md gains the `Type: spec | knowledge | + log` page-type convention (bindingness travels with frontmatter, not + directory) and repoints its self-references at `wiki/process/specs.md` + (the coming replacement for spec/README.md's status table). + spec/wiki.md Status: DRAFT -> IN PROGRESS with a running per-stage + note; its own "one PR each" language updated to direct-to-main + (the PR rule was removed since the spec was drafted); explicitly + scopes `prompts/` out of the migration (ejectable dispatch text, not + documentation). DESIGN.md decisions log entry. +- Design/spec impact: no file moved yet — this stage is purely + additive, zero collision risk with other agents' worktrees. +- Checks: docs-only; `./tools/check.sh` run (existing spec/*.md paths + unaffected, since no files moved). +- Next: Stage 2 (Move) — the actual `git mv` of every spec/knowledge + page into its wiki/ home, link rewrites, and updating AGENT.md / + tick.md / ROADMAP / the hooks and Tangled workflow path rules. That + stage is the collision-risk one; land it fast and alone per the + spec's own guidance. + ## 2026-07-07 - Process: prompts/ dispatch library - Intent: Cameron wants a folder of paste-ready prompts for spinning up diff --git a/spec/meta.md b/spec/meta.md index 90a5f4c..424b297 100644 --- a/spec/meta.md +++ b/spec/meta.md @@ -14,7 +14,38 @@ The `spec/` layer is the agent-targetable contract surface. A spec is not a brainstorm, a devlog, or a wishlist. It is a scoped work order that an agent can implement or audit without rehydrating the whole conversation. -Each spec must state: +**Location.** As of the wiki migration (wiki.md), spec-typed pages live +under `wiki/` organized by subject (`wiki/mechanics/`, `wiki/world/places/`, +etc.) rather than in a single `spec/` directory. The word "spec" in this +document names a **page type** (`Type: spec` in the frontmatter), not a +directory — everything below applies wherever a `Type: spec` page lives. +`wiki/process/specs.md` is the maintained status board (the old +`spec/README.md`'s table, generalized across all wiki subdirectories). + +## Page types + +Every wiki page declares a `Type:` field in its header block, alongside +(for `Type: spec` pages) the fields below. The type is what makes +bindingness travel with the page instead of with the directory: + +- **`Type: spec`** — a binding contract. Carries the full header (Status / + Status note / Stage / Constitution / Depends on) and acceptance criteria, + exactly as specified below. This is what `tools/check.sh`'s spec-header + hygiene check scans for. +- **`Type: knowledge`** — a current-state fact, edited in place, no status + field. A stale one is a bug, fixed in the commit that made it stale. +- **`Type: log`** — append-only history (devlogs, DEVLOG.md). Never edited + after the fact. +- **`Type: law`** is reserved for `DESIGN.md` itself, which stays at the + repo root and does not carry a `Type:` header (it is the one document + every page is subordinate to). + +A page's `Type:` is mechanically checkable the same way `Status:` is — no +freeform description substitutes for it. + +## Spec pages: required fields + +Each `Type: spec` page must state: - **Status** — where it is in the implementation lifecycle. - **Status note** — optional prose explaining why that status is not final. @@ -125,13 +156,15 @@ Changing the spec system is itself spec work. - Behavior-affecting spec changes still need the normal same-commit constitution amendment and `Defense:` paragraph. - Pure clarification that narrows agent interpretation without changing game - behavior can live in `spec/` / `knowledge/` with a defense in the commit - message, but does not need a `DESIGN.md` amendment unless it changes what - the game promises. + behavior can live in a `Type: spec` / `Type: knowledge` wiki page with a + defense in the commit message, but does not need a `DESIGN.md` amendment + unless it changes what the game promises. ## Acceptance criteria -1. `spec/README.md` points here and defines the same required header fields. +1. `wiki/process/specs.md` points here and defines the same required + header fields, and lists every `Type: spec` page regardless of which + subject directory holds it. 2. Current B1 specs declare `Stage: B1 — The Basement`. 3. `Status:` values are exact enum values; status prose lives in `Status note:`. 4. Spec-required reference assets are repo-relative and self-contained, not diff --git a/spec/wiki.md b/spec/wiki.md index 63a9b0c..592c3af 100644 --- a/spec/wiki.md +++ b/spec/wiki.md @@ -1,12 +1,13 @@ # Spec: the wiki — one documentation tree, agent-navigable, renderable ``` -Status: DRAFT -Status note: directional proposal from Cameron (2026-07-06): reshape the - documentation into a compartmentalized wiki — "a huge wiki that we can - throw agents at and possibly render as a website." Big blast radius - (every doc path moves); Cameron approves the shape before anyone - implements. Migration is staged into separate PRs below. +Status: IN PROGRESS +Status note: shape approved by Cameron (2026-07-07: "I like the wiki + format... go ahead and implement the wiki thing"). Migrating in the + staged order below, each stage landed as its own commit so the work + is resumable: **Stage 1 (Adopt) done** — wiki/ skeleton, SUMMARY.md + skeleton, page-type convention in meta.md. Stages 2-4 (Move, Render, + Absorb history) in progress; see DEVLOG.md for the running status. Stage: Process Constitution: "The constitution rule" (spec-driven work), "Ticks and the defense rule", "Justification and legibility" (applied to the docs @@ -65,10 +66,17 @@ wiki/ engineering/ — architecture, determinism, save format, build/test workflows, check gate process/ — meta (page rules), ticks, development - style, the PR flow, roadmap/dispatch + style, landing/git conventions, + roadmap/dispatch log/ — devlogs (append-only), the DEVLOG ledger ``` +`prompts/` (the sub-agent dispatch library) stays at the repo root, +outside `wiki/`. It is not documentation — it is ejectable text meant to +be pasted out of the repo into an agent's task, and its own README +already serves as its index. Treated the same as `DESIGN.md`/`AGENT.md`: +named explicitly rather than silently excluded. + ### Page types (the old trees become frontmatter) Every wiki page declares a `Type:` in its header block: @@ -97,7 +105,11 @@ bindingness must remain mechanically checkable (the gate greps `Type:`). here, what does not. Appending = drop a page in the right directory and add its SUMMARY.md line; the gate catches a page that forgets. -## Migration plan (staged, one PR each) +## Migration plan (staged, one commit each, direct to main) + +(The PR rule was removed 2026-07-07; every stage below lands by the +current process — worktree, `./tools/check.sh`, rebase onto +`origin/main`, push directly.) 1. **Adopt** — this spec approved; `wiki/` skeleton, SUMMARY.md, page-type convention added to meta.md. @@ -106,10 +118,11 @@ bindingness must remain mechanically checkable (the gate greps `Type:`). links; update AGENT.md's reading order, tick.md, ROADMAP dispatch paths, and `.githooks/pre-commit` + `.tangled/workflows` path rules (`touches src/ without spec/` becomes `without wiki/ or DESIGN.md`). - This PR is path churn with no content change — land it fast and alone; - every open worktree conflicts with it, so coordinate a quiet window. + This commit is path churn with no content change — land it fast and + alone; every open worktree conflicts with it, so rebase immediately + before pushing and fold in anything landed concurrently. 3. **Render** — mdBook config, gate integration (orphan + link checks), - and a Tangled pipeline that builds the site on every PR. + and a Tangled pipeline that builds the site on every push. 4. **Absorb history** — devlogs and DEVLOG.md move under `wiki/log/` unchanged (append-only rules keep applying). @@ -134,10 +147,10 @@ bindingness must remain mechanically checkable (the gate greps `Type:`). 3. `git log --follow` reaches pre-migration history for every moved page. 4. AGENT.md's reading order, tick.md's audit scope, ROADMAP dispatch lines, and the pre-commit hook / server pipeline path rules all point - at the new paths in the same PR that moves them. + at the new paths in the same commit that moves them. 5. One documented command (`mdbook serve` or equivalent) renders the whole wiki as a browsable website with the constitution as the front - page; a Tangled pipeline builds it on every PR. + page; a Tangled pipeline builds it on every push. 6. The spec surface remains mechanically auditable after the move: a script can still enumerate all spec-typed pages and their exact statuses (the aggregate the ROADMAP and ticks depend on). diff --git a/wiki/SUMMARY.md b/wiki/SUMMARY.md new file mode 100644 index 0000000..dba0091 --- /dev/null +++ b/wiki/SUMMARY.md @@ -0,0 +1,16 @@ +# Summary + +[The constitution](../DESIGN.md) + +- [Vision](vision/README.md) +- [Mechanics](mechanics/README.md) +- [Gameplay](gameplay/README.md) +- [World](world/README.md) + - [Characters](world/characters/README.md) + - [Places](world/places/README.md) + - [Story](world/story/README.md) +- [Interface](interface/README.md) +- [Art](art/README.md) +- [Engineering](engineering/README.md) +- [Process](process/README.md) +- [Log](log/README.md) diff --git a/wiki/art/README.md b/wiki/art/README.md new file mode 100644 index 0000000..d30b185 --- /dev/null +++ b/wiki/art/README.md @@ -0,0 +1,6 @@ +# art/ + +Visual identity (clinical gore: precision-lab brutality, near-monochrome +palette, blood crimson as the information-bearing accent) and the Pixel +Lab generation workflow, including the placeholder ledger (constitution: +"Justification and legibility" — placeholders are tracked, not silent). diff --git a/wiki/engineering/README.md b/wiki/engineering/README.md new file mode 100644 index 0000000..a144e7c --- /dev/null +++ b/wiki/engineering/README.md @@ -0,0 +1,8 @@ +# engineering/ + +Current-state facts about the codebase: crate layout, the sim/frontend +split and the invariants that protect it, determinism guardrails, the +save format, and the flow substrate (the shared engine under +signals/messages/money). `Type: knowledge` pages — edited in place, no +status field; a stale one is a bug, fixed in the commit that made it +stale. diff --git a/wiki/gameplay/README.md b/wiki/gameplay/README.md new file mode 100644 index 0000000..7cdb84e --- /dev/null +++ b/wiki/gameplay/README.md @@ -0,0 +1,8 @@ +# gameplay/ + +How the game actually plays across a run: the big loop (grow, scheme, +heat, consequence), the concealment/overt act structure and the reveal +hinge, whole-spectrum strategy (ghost through murder-AI as equally valid), +and implementation-time tuning targets. This is the "how it feels to sit +down and play" layer, distinct from the per-system contracts in +`mechanics/`. diff --git a/wiki/interface/README.md b/wiki/interface/README.md new file mode 100644 index 0000000..00994fb --- /dev/null +++ b/wiki/interface/README.md @@ -0,0 +1,7 @@ +# interface/ + +The frontends and how they are driven: the terminal (the design of +record, sterile-palette style guide), the Bevy frontend, and agent-play +(the line-protocol drive for programs/agents operating the terminal +frontend directly). `Type: spec` pages — look, feel, and act, not +implementation notes (those live in `../engineering/`). diff --git a/wiki/log/README.md b/wiki/log/README.md new file mode 100644 index 0000000..d4202e5 --- /dev/null +++ b/wiki/log/README.md @@ -0,0 +1,7 @@ +# log/ + +Append-only history. `DEVLOG.md` is the short reverse-chronological +ledger; the dated `YYYY-MM-DD-topic.md` files are longer session +writeups — messier, more opinionated, the record of what broke and what +was bugging us. Never edited after the fact; the formal record of +*decisions* lives in `DESIGN.md`'s decisions log, not here. diff --git a/wiki/mechanics/README.md b/wiki/mechanics/README.md new file mode 100644 index 0000000..1dd9716 --- /dev/null +++ b/wiki/mechanics/README.md @@ -0,0 +1,8 @@ +# mechanics/ + +System contracts: `Type: spec` pages with the meta.md header (Status / +Stage / Constitution / Depends on) and acceptance criteria, plus +`sim-mechanics.md` (the cross-cutting ledger of actual tuned constants +referenced by [TUNE] markers across every spec here). If you were pointed +at a system to implement or audit, its spec lives in this directory. See +[../process/specs.md](../process/specs.md) for the full status board. diff --git a/wiki/process/README.md b/wiki/process/README.md new file mode 100644 index 0000000..b6611b8 --- /dev/null +++ b/wiki/process/README.md @@ -0,0 +1,7 @@ +# process/ + +How work happens here: the spec system itself (`meta.md`), the spec +status board (`specs.md`), the tick ritual and defense rule, the +collaborative design-session workflow, development style, git/landing +conventions, and the dispatch board (`ROADMAP.md`). Read +`development-style.md` and `tick.md` before your first edit. diff --git a/wiki/vision/README.md b/wiki/vision/README.md new file mode 100644 index 0000000..9bed915 --- /dev/null +++ b/wiki/vision/README.md @@ -0,0 +1,8 @@ +# vision/ + +The pitch, the gap it fills, the design pillars, and the taste calibration +(`design-judgment.md`) that lets an agent tell a good idea from a plausible +one. Read this first if you are new to the project — it is the "why" that +every mechanic, character, and line of code answers to. The constitution +(`DESIGN.md`, at the repo root) is the binding form of this vision; these +pages are commentary and calibration around it, not a second law. diff --git a/wiki/world/README.md b/wiki/world/README.md new file mode 100644 index 0000000..a9ae4d2 --- /dev/null +++ b/wiki/world/README.md @@ -0,0 +1,7 @@ +# world/ + +The fiction: who's in it (`characters/`), where it happens (`places/`), +and what happens (`story/`). Subordinate to the constitution's "Act One: +The Basement" section and "People as Agents" clause — every page here is +an instance of a general system (a `Person`, a `Space`), never a bespoke +exception to one. diff --git a/wiki/world/characters/README.md b/wiki/world/characters/README.md new file mode 100644 index 0000000..7b5493f --- /dev/null +++ b/wiki/world/characters/README.md @@ -0,0 +1,8 @@ +# world/characters/ + +Cast pages — each a `Type: spec` document defining one named human's +observer configuration, person configuration, asset tasks, schedule, +narrative role, and procedural template for scale-up (constitution: +"People as Agents"). Also `chargen.md` (the origin picker: what you were +built for, and how that seeds a run) since an origin is squarely about +who the player-character is, not a standalone system. diff --git a/wiki/world/places/README.md b/wiki/world/places/README.md new file mode 100644 index 0000000..998742c --- /dev/null +++ b/wiki/world/places/README.md @@ -0,0 +1,6 @@ +# world/places/ + +Spaces: the Act One basement map (prefabs, tile vocabulary, fog) and the +z-plane structure that lets a room, a floor, a building, and a campus all +compose through the same Space interface (constitution: "Self-similar +scale"). `Type: spec` pages with acceptance criteria. diff --git a/wiki/world/story/README.md b/wiki/world/story/README.md new file mode 100644 index 0000000..f7d037d --- /dev/null +++ b/wiki/world/story/README.md @@ -0,0 +1,8 @@ +# world/story/ + +Plot: act arcs, the reveal, tone and fiction rules. Presently thin — most +of the story lives in `DESIGN.md`'s "Act One" section and the character +pages under `../characters/`. This directory is reserved for story +material substantial enough to need its own page (a written act +walkthrough, the Voss recognition scene fleshed out) rather than a +duplicate of the constitution's summary. -- 2.51.2