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.