diff --git a/AGENT.md b/AGENT.md index 2c06ea8c..d83f31aa 100644 --- a/AGENT.md +++ b/AGENT.md @@ -82,13 +82,13 @@ behavior change. genuinely non-functional (generated code, test-only, formatting). - Commits: no AI attribution, explicit `git add` of intended files only. - Update any `Type: knowledge` wiki page your change made stale, add a - `devlogs/` entry for the session (moving to `wiki/log/` in the wiki - migration's stage 4 — check whether it has landed yet), and land the - work by merging to `main` directly after `./tools/check.sh` passes (the - PR rule was removed 2026-07-07 — see the DESIGN.md decisions log). -- **Ledgers merge by union.** `DEVLOG.md`, the DESIGN.md decisions log, and - `wiki/process/specs.md`'s tables are append-only records: resolve merge - conflicts in them by keeping BOTH sides' entries. Taking your side + `wiki/log/` entry for the session, and land the work by merging to + `main` directly after `./tools/check.sh` passes (the PR rule was + removed 2026-07-07 — see the DESIGN.md decisions log). +- **Ledgers merge by union.** `wiki/log/DEVLOG.md`, the DESIGN.md + decisions log, and `wiki/process/specs.md`'s tables are append-only + records: resolve merge conflicts in them by keeping BOTH sides' entries. + Taking your side wholesale silently destroys parallel sessions' history and is a violation. - **HARD RULE — always work in a worktree.** Multiple agent sessions operate diff --git a/README.md b/README.md index 562dbb6c..5046ac80 100644 --- a/README.md +++ b/README.md @@ -51,10 +51,11 @@ amendment, in the same commit; the spec is the decision, code is downstream. Agents are then set at the constitution, session after session. - **[DESIGN.md](DESIGN.md)** — the constitution. Prescriptive. Read it first. -- **[knowledge/](knowledge/)** — current-state facts: architecture, mechanics, - pipelines, workflows. Edited in place; staleness is a bug. -- **[devlogs/](devlogs/)** and **[DEVLOG.md](DEVLOG.md)** — append-only - history: session writeups and the quick ledger. +- **[wiki/](wiki/)** — one documentation tree organized by subject: + binding specs, current-state facts, and append-only history + (`wiki/log/`), each carrying a `Type:` header so bindingness travels + with the page. Renders as a browsable book via `mdbook build`/`mdbook + serve`; see [wiki/overview.md](wiki/overview.md) for the map. - **[AGENT.md](AGENT.md)** — the entry point that routes agent sessions through the above. @@ -64,8 +65,8 @@ Agents are then set at the constitution, session after session. simulation of the facility — walk it, dig it, build doors and power, save and load — in a terminal frontend and a Bevy frontend with generated pixel art. The game itself (compute allocation, the day job, detection, the five -humans of the basement) is specified in [spec/](spec/) and being built from -those documents; see the +humans of the basement) is specified in [wiki/process/specs.md](wiki/process/specs.md) +and being built from those documents; see the [roadmap](DESIGN.md#roadmap-v2--re-cut-2026-07-05-for-misaligned). Under the constitution's no-dead-code rule, nothing ships in this tree that the design no longer requires — the earlier facility-defense prototype lives in diff --git a/devlogs/README.md b/devlogs/README.md deleted file mode 100644 index 8be13739..00000000 --- a/devlogs/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# Devlogs - -Development notes, one file per working session or theme, named -`YYYY-MM-DD-topic.md`. (There is also a root-level [DEVLOG.md](../DEVLOG.md) -with short reverse-chronological entries; that's the quick factual ledger, -these are the longer session writeups.) These are the informal record: what was done, what was -decided and why, what broke, what's bugging us. The formal design record lives -in [DESIGN.md](../DESIGN.md) (vision, pillars, decisions log); devlogs are -allowed to be messy and opinionated. - -When you finish a meaningful chunk of work, add an entry. Future-you reads -these to remember why the code looks the way it does. diff --git a/prompts/README.md b/prompts/README.md index 5e9d14c4..4635b6a1 100644 --- a/prompts/README.md +++ b/prompts/README.md @@ -18,9 +18,9 @@ prompt tells the agent what to read; you do not need to brief it further. These rules bind every prompted agent, and each prompt file assumes them: 1. **Read first:** [AGENT.md](../AGENT.md), then the files it orders - (DESIGN.md → knowledge/development-style.md → relevant knowledge/ → - the spec you are working). Do not skip this on later runs — the - constitution moves daily. + (DESIGN.md → wiki/process/development-style.md → relevant `Type: + knowledge` wiki pages → the `Type: spec` page you are working). Do + not skip this on later runs — the constitution moves daily. 2. **Worktree, always.** First action: create/enter a git worktree (`git worktree add .claude/worktrees/ -b worktree-`). Never edit the primary checkout; files changing under you there are @@ -32,12 +32,13 @@ These rules bind every prompted agent, and each prompt file assumes them: rebasing onto `origin/main` and pushing to `main` directly (the PR flow is removed — do not create PRs). Then remove your worktree and branch. -5. **Ledgers merge by union.** Conflicts in DEVLOG.md, the DESIGN.md - decisions log, or spec/README tables are resolved by keeping BOTH - sides' entries — never take your side wholesale. -6. **Close the loop.** DEVLOG.md ledger entry (and a devlogs/ file for a - meaningful session); update any knowledge/ file your change made - stale. +5. **Ledgers merge by union.** Conflicts in `wiki/log/DEVLOG.md`, the + DESIGN.md decisions log, or `wiki/process/specs.md` tables are + resolved by keeping BOTH sides' entries — never take your side + wholesale. +6. **Close the loop.** `wiki/log/DEVLOG.md` ledger entry (and a + `wiki/log/` file for a meaningful session); update any `Type: + knowledge` wiki page your change made stale. 7. **House style:** no emoji, no AI attribution in commits, stage files explicitly (never `git add -A`), ASCII only in anything that could reach a game string. diff --git a/prompts/ask-the-human.md b/prompts/ask-the-human.md index ee75e208..1e3c4ba3 100644 --- a/prompts/ask-the-human.md +++ b/prompts/ask-the-human.md @@ -10,16 +10,16 @@ You are not deciding — you are making the decision *easy to make*. ## Before you start Read `AGENT.md`, `DESIGN.md` (every `[OPEN]` marker; the decisions log -tail), `spec/README.md`, `spec/ROADMAP.md` (items marked "needs YOU"), -and skim recent `devlogs/` "Next:" lines — past sessions often name -exactly what they were waiting on. Obey the shared contract in -`prompts/README.md`. Check standing issues first (`tang issue list`) so -you never file a duplicate. +tail), `wiki/process/specs.md`, `wiki/process/ROADMAP.md` (items marked +"needs YOU"), and skim recent `wiki/log/` "Next:" lines — past sessions +often name exactly what they were waiting on. Obey the shared contract +in `prompts/README.md`. Check standing issues first (`tang issue list`) +so you never file a duplicate. ## Procedure 1. **Inventory the open decisions.** Grep for `[OPEN]`, `Proposal - [OPEN]`, `DRAFT`, and `needs YOU` across `DESIGN.md` and `spec/`. + [OPEN]`, `DRAFT`, and `needs YOU` across `DESIGN.md` and `wiki/`. For each, ask: what work does answering this unblock, and how soon is that work otherwise reachable? 2. **Pick the blocker with the highest unblock value.** A question diff --git a/prompts/audit-implemented.md b/prompts/audit-implemented.md index c8e881f4..465a8a01 100644 --- a/prompts/audit-implemented.md +++ b/prompts/audit-implemented.md @@ -3,17 +3,18 @@ You are auditing Misaligned, a spec-driven Rust game where a spec's `Status: IMPLEMENTED` is a *claim*: every acceptance criterion holds in the sim core with tests, both frontends surface it where applicable, -save/load round-trips its state, and knowledge/ reflects it -(`spec/meta.md`). In a many-agent repo those claims rot — refactors -strand tests, parallel merges drop wiring. Your task this run: **pick -one IMPLEMENTED or IN PROGRESS spec and re-verify every criterion it -claims, criterion by criterion.** +save/load round-trips its state, and the `Type: knowledge` wiki pages +reflect it (`wiki/process/meta.md`). In a many-agent repo those claims +rot — refactors strand tests, parallel merges drop wiring. Your task +this run: **pick one IMPLEMENTED or IN PROGRESS spec and re-verify +every criterion it claims, criterion by criterion.** ## Before you start -Read `AGENT.md`, `spec/meta.md` (status semantics — especially as-built -specs), and the spec you choose in full, including its `Depends on:` -line (the cross-spec contracts you must also re-check). Obey the shared +Read `AGENT.md`, `wiki/process/meta.md` (status semantics — especially +as-built specs), and the spec you choose in full, including its +`Depends on:` line (the cross-spec contracts you must also re-check). +Obey the shared contract in `prompts/README.md`. ## Procedure diff --git a/prompts/find-contradiction.md b/prompts/find-contradiction.md index 52a51080..42431b61 100644 --- a/prompts/find-contradiction.md +++ b/prompts/find-contradiction.md @@ -1,18 +1,19 @@ # Prompt: find a contradiction You are auditing Misaligned, a spec-driven Rust game whose constitution -(`DESIGN.md`) outranks its specs (`spec/`), which outrank the code. Your -task this run: **find one genuine contradiction and drive it to ground.** -A contradiction is two binding statements that cannot both be true: -spec vs constitution, spec vs sibling spec, spec vs code, constitution -vs code, or a doc vs itself (an amendment that half-updated a section). +(`DESIGN.md`) outranks its `Type: spec` wiki pages, which outrank the +code. Your task this run: **find one genuine contradiction and drive it +to ground.** A contradiction is two binding statements that cannot both +be true: spec vs constitution, spec vs sibling spec, spec vs code, +constitution vs code, or a doc vs itself (an amendment that half-updated +a section). ## Before you start Read `AGENT.md`, then `DESIGN.md` in full (the decisions log tail especially — recent amendments are where contradictions breed), then -`spec/README.md` and `knowledge/tick.md` (the tick rules you are -executing a specialized form of). Obey the shared contract in +`wiki/process/specs.md` and `wiki/process/tick.md` (the tick rules you +are executing a specialized form of). Obey the shared contract in `prompts/README.md`. ## Procedure @@ -24,7 +25,7 @@ executing a specialized form of). Obey the shared contract in cursor" for a day after the cursor decision made the player exactly that.) - **Sibling specs sharing a contract.** `Depends on:` lines name - shared identifiers/interfaces (`spec/meta.md`, "Cross-spec + shared identifiers/interfaces (`wiki/process/meta.md`, "Cross-spec contracts"). Check both sides still describe the same contract. - **Spec vs code on IMPLEMENTED claims.** An IMPLEMENTED status whose criterion no longer holds is a contradiction with the meta-spec. @@ -36,7 +37,7 @@ executing a specialized form of). Obey the shared contract in different scales of the same system) is usually deliberate. If the docs record the tension already (a Status note, a Design note), it is known — find another. -3. **Classify and act** (per `knowledge/tick.md`): +3. **Classify and act** (per `wiki/process/tick.md`): - **Mechanical resolution is clear** (one side is stale): fix the stale side, same-commit amendment if the constitution moves, with a `Defense:` explaining which side won and why. @@ -44,8 +45,8 @@ executing a specialized form of). Obey the shared contract in `tang issue create "" -b "<body>"` — quoting both sides verbatim with file:line, stating why they conflict, and offering 2-3 resolutions with a marked recommendation. (If `tang` is - unavailable, write the same content to a dated devlog and flag it - in DEVLOG.md as needing Cameron.) + unavailable, write the same content to a dated `wiki/log/` file and + flag it in `wiki/log/DEVLOG.md` as needing Cameron.) 4. **Land** whatever you changed: check.sh, rebase, push to main, DEVLOG entry, worktree removed. A filed issue also gets a DEVLOG line. diff --git a/prompts/harvest-issues.md b/prompts/harvest-issues.md index 97f60f8b..9759f581 100644 --- a/prompts/harvest-issues.md +++ b/prompts/harvest-issues.md @@ -11,8 +11,8 @@ digestive system between "discussed" and "done". Read `AGENT.md` and the shared contract in `prompts/README.md`. Then `tang issue list`, and `tang issue view <id>` on everything open. Have -`DESIGN.md`'s decisions log and `spec/README.md`'s status table beside -you — an issue's fate is usually written in one of them. +`DESIGN.md`'s decisions log and `wiki/process/specs.md`'s status table +beside you — an issue's fate is usually written in one of them. ## Procedure @@ -23,15 +23,16 @@ For each open issue, classify and act: artifact: - a design answer -> the DESIGN.md amendment and/or spec edit it implies (quote the issue in the commit's `Defense:`), or - - an implementation-shaped answer -> a `spec/ROADMAP.md` dispatch - item (or take it yourself if it fits one run — then follow - `prompts/implement-gap.md` discipline). + - an implementation-shaped answer -> a `wiki/process/ROADMAP.md` + dispatch item (or take it yourself if it fits one run — then + follow `prompts/implement-gap.md` discipline). Then `tang issue close <id>` with a comment/body edit noting the landing commit or ROADMAP item. 2. **Resolved by history without anyone noticing** (the code moved, a decision superseded it, the file it concerns was deleted). Verify in the tree, then close with one line of evidence ("superseded by - decisions log 2026-07-06 flow law; spec/economy.md covers this"). + decisions log 2026-07-06 flow law; wiki/mechanics/economy.md covers + this"). 3. **Still genuinely open but stale in wording** (the docs it quotes have moved). Refresh it: `tang issue edit <id>` so the question is still answerable against today's tree. Note the refresh date in the diff --git a/prompts/implement-gap.md b/prompts/implement-gap.md index 8cf7f7ee..21228abc 100644 --- a/prompts/implement-gap.md +++ b/prompts/implement-gap.md @@ -8,11 +8,12 @@ land it.** One gap, closed fully, beats three gaps half-done. ## Before you start Read, in order: `AGENT.md`, `DESIGN.md` (skim the sections, read the -decisions log tail), `knowledge/development-style.md`, `spec/README.md` -(the status table), and `spec/ROADMAP.md` (the dispatch board — it may -already name the highest-value gap and its worktree name). Obey the -shared contract in `prompts/README.md`: worktree first, one rule, -check.sh gate, direct merge to main, union merges on ledgers. +decisions log tail), `wiki/process/development-style.md`, +`wiki/process/specs.md` (the status table), and `wiki/process/ROADMAP.md` +(the dispatch board — it may already name the highest-value gap and its +worktree name). Obey the shared contract in `prompts/README.md`: +worktree first, one rule, check.sh gate, direct merge to main, union +merges on ledgers. ## Procedure @@ -40,14 +41,14 @@ check.sh gate, direct merge to main, union merges on ledgers. are written to be testable — each one you complete gets a sim test (`#[cfg(test)]` beside the module or in `src/sim.rs`'s tests). 5. **Update the spec's `Status:`/`Status note:`** in the same commit - (READY -> IN PROGRESS -> IMPLEMENTED per `spec/meta.md`). If your - work changes behavior beyond what the spec says, that needs a + (READY -> IN PROGRESS -> IMPLEMENTED per `wiki/process/meta.md`). If + your work changes behavior beyond what the spec says, that needs a DESIGN.md amendment in the same commit — if you find yourself *designing* rather than implementing, stop and use `prompts/ask-the-human.md` instead. 6. **Land it:** `./tools/check.sh` green, rebase onto `origin/main`, - push to `main`, DEVLOG.md ledger entry, remove the worktree. Mark - the ROADMAP item's result if you closed one. + push to `main`, `wiki/log/DEVLOG.md` ledger entry, remove the + worktree. Mark the ROADMAP item's result if you closed one. ## Definition of done diff --git a/prompts/knowledge-sync.md b/prompts/knowledge-sync.md index 3b5171c9..845c08a9 100644 --- a/prompts/knowledge-sync.md +++ b/prompts/knowledge-sync.md @@ -1,45 +1,45 @@ # Prompt: knowledge sync -You are maintaining Misaligned's `knowledge/` layer — the current-state -record (architecture, sim mechanics, workflows, art pipeline) that every -agent reads before working. Unlike devlogs (append-only history) and -specs (binding law), knowledge/ files are **edited in place and must be -true today**. In a many-agent repo they drift within days. Your task -this run: **find where knowledge/ has diverged from reality and fix the -record.** +You are maintaining Misaligned's `Type: knowledge` wiki pages — the +current-state record (architecture, sim mechanics, workflows, art +pipeline) that every agent reads before working. Unlike `wiki/log/` +(append-only history) and `Type: spec` pages (binding law), knowledge +pages are **edited in place and must be true today**. In a many-agent +repo they drift within days. Your task this run: **find where a +knowledge page has diverged from reality and fix the record.** ## Before you start -Read `AGENT.md`, `knowledge/README.md` if present, and the shared -contract in `prompts/README.md`. This task changes documentation to -match reality — if you find the *code* wrong instead, that is a -different task (`prompts/find-contradiction.md`); here the tree is the -truth and the record is the patient. +Read `AGENT.md`, `wiki/overview.md`, and the shared contract in +`prompts/README.md`. This task changes documentation to match reality — +if you find the *code* wrong instead, that is a different task +(`prompts/find-contradiction.md`); here the tree is the truth and the +record is the patient. ## Procedure 1. **Pick the sweep** (one file, or one theme across files): - - `knowledge/architecture.md` vs `src/` — module list, ownership - claims, data-flow descriptions. `ls src/` and the lib.rs module - list are the ground truth; so are struct fields for any "state - lives in X" claim. - - `knowledge/sim-mechanics.md` vs actual constants and formulas — - [TUNE] values are supposed to be *recorded here* when chosen; - grep the constants in code and compare. - - `knowledge/workflows.md` vs how landing actually works now (this - file has carried stale process before — verify against AGENT.md - and the decisions log rather than assuming either doc). - - `knowledge/art-pipeline.md` vs `assets/` and the placeholder + - `wiki/engineering/architecture.md` vs `src/` — module list, + ownership claims, data-flow descriptions. `ls src/` and the lib.rs + module list are the ground truth; so are struct fields for any + "state lives in X" claim. + - `wiki/mechanics/sim-mechanics.md` vs actual constants and + formulas — [TUNE] values are supposed to be *recorded here* when + chosen; grep the constants in code and compare. + - `wiki/process/workflows.md` vs how landing actually works now + (this file has carried stale process before — verify against + AGENT.md and the decisions log rather than assuming either doc). + - `wiki/art/pixel-pipeline.md` vs `assets/` and the placeholder ledger — every placeholder in use must be recorded there. 2. **Verify each claim you touch** against the tree, not against your memory or another doc — two docs agreeing can both be stale. 3. **Fix in place.** Rewrite the drifted passages to describe today. - Do not append "UPDATE:" notes — knowledge files are edited, not + Do not append "UPDATE:" notes — knowledge pages are edited, not accreted. If something is uncertain, say so explicitly in the text rather than guessing confidently. 4. **Check the reverse direction:** did recent commits add systems that - knowledge/ never absorbed? (`git log --oneline -20` and skim for - landed features; the flow substrate, e.g., must appear in + no knowledge page ever absorbed? (`git log --oneline -20` and skim + for landed features; the flow substrate, e.g., must appear in architecture.md's module map once landed.) Add the missing entries. 5. **Land it** (docs-only commits still gate on check.sh — it is cheap when no code changed): rebase, push to main, DEVLOG line @@ -51,10 +51,10 @@ truth and the record is the patient. the current tree. - New landed systems appear in the knowledge map; removed ones are gone (not marked "removed" — gone). -- The DEVLOG line lets the next agent trust the file you swept. +- The DEVLOG line lets the next agent trust the page you swept. ## What to carry forward (stateful agents) -- Which files drift fastest (they earn more frequent sweeps). +- Which pages drift fastest (they earn more frequent sweeps). - Claims you verified with dates — the freshness map that makes the next sweep incremental instead of total. diff --git a/prompts/legibility-pass.md b/prompts/legibility-pass.md index 3dec703e..20a5d488 100644 --- a/prompts/legibility-pass.md +++ b/prompts/legibility-pass.md @@ -11,7 +11,7 @@ violation on the player surface and fix it.** ## Before you start Read `AGENT.md`, the "Justification and legibility" and "player -contract" sections of `DESIGN.md`, and `knowledge/design-judgment.md` +contract" sections of `DESIGN.md`, and `wiki/vision/design-judgment.md` (the taste calibration). Obey the shared contract in `prompts/README.md`. Build and actually run the terminal frontend (`cargo run --bin misaligned` in a pty, or read @@ -30,7 +30,7 @@ contract" sections of `DESIGN.md`, and `knowledge/design-judgment.md` an abbreviation the game never expands, a value whose consequence the player cannot predict. - **Silent placeholder:** art or text standing in for something else - without a knowledge/art-pipeline.md record. + without a wiki/art/pixel-pipeline.md record. 2. **Verify against the docs** before fixing: the thing might be specced with its meaning defined but the surface lagging — that is still a violation, but the fix is surfacing, not redesign. If the fix diff --git a/prompts/playtest-notes.md b/prompts/playtest-notes.md index feed63bb..5d3236bc 100644 --- a/prompts/playtest-notes.md +++ b/prompts/playtest-notes.md @@ -12,7 +12,7 @@ checklist. ## Before you start Read `AGENT.md`, `DESIGN.md`'s pitch / pillars / Act One sections, and -`knowledge/design-judgment.md` (the intended feel: pacing, tone, what +`wiki/vision/design-judgment.md` (the intended feel: pacing, tone, what to reject). Obey the shared contract in `prompts/README.md`. Then build and play: @@ -46,10 +46,10 @@ and play: the report's heart — write them vividly and concretely ("days pass in 60 seconds, so the 3 a.m. call is a 2.5-second blip I only saw as a log line"). -4. **Write the report:** `devlogs/YYYY-MM-DD-playtest.md` — what you +4. **Write the report:** `wiki/log/YYYY-MM-DD-playtest.md` — what you played (seed, duration, route), the fantasy-claim verdicts, findings by kind, and the single change you would make first, argued in the - design's own terms. Add the DEVLOG.md ledger line. + design's own terms. Add the `wiki/log/DEVLOG.md` ledger line. 5. **Land** the report (and any small fixes) per the shared contract. ## Definition of done diff --git a/tools/wiki_gate.sh b/tools/wiki_gate.sh index fbc911e7..ebd7e450 100755 --- a/tools/wiki_gate.sh +++ b/tools/wiki_gate.sh @@ -20,9 +20,20 @@ fail=0 # Every wiki/**/*.md file (except SUMMARY.md itself) must appear as a # link target somewhere in SUMMARY.md. All SUMMARY.md targets are written # relative to wiki/, matching each file's own wiki-relative path. +# +# Exception: wiki/log/*.md (devlogs + the DEVLOG ledger), excluding +# log/README.md which IS listed. Devlogs are meant to be a low-friction, +# append-only habit at the end of a session — requiring a matching +# SUMMARY.md edit for every single dated entry would either get forgotten +# constantly (failing this gate forever after) or turn "write a devlog" +# into a two-file chore. They're browsed via wiki/log/DEVLOG.md's ledger +# and `git log`, not the hand-maintained nav tree. while IFS= read -r f; do rel="${f#wiki/}" [ "$rel" = "SUMMARY.md" ] && continue + case "$rel" in + log/*) [ "$rel" = "log/README.md" ] || continue ;; + esac grep -qF "($rel)" wiki/SUMMARY.md || { echo "FAIL: orphan page not reachable from wiki/SUMMARY.md: $f" fail=1 @@ -64,7 +75,7 @@ while IFS= read -r f; do # correct base directory for relative links. [ "$f" = "wiki/DESIGN.md" ] && continue check_links_in "$f" -done < <(find wiki -name '*.md'; echo "AGENT.md"; echo "DEVLOG.md"; echo "DESIGN.md") +done < <(find wiki -name '*.md'; echo "AGENT.md"; echo "README.md"; echo "DESIGN.md") if [ "$fail" -ne 0 ]; then exit 1 diff --git a/wiki/SUMMARY.md b/wiki/SUMMARY.md index e0e3de33..d34b33e1 100644 --- a/wiki/SUMMARY.md +++ b/wiki/SUMMARY.md @@ -84,3 +84,9 @@ # Log - [Overview](log/README.md) + - [DEVLOG (the ledger)](log/DEVLOG.md) + +Dated session writeups (`wiki/log/YYYY-MM-DD-topic.md`) are not +individually listed here — see the ledger above or `git log` for the +full append-only history. Requiring a SUMMARY.md edit for every devlog +entry would fight the habit of writing them. diff --git a/wiki/art/pixel-pipeline.md b/wiki/art/pixel-pipeline.md index 8c6f8373..cb633cde 100644 --- a/wiki/art/pixel-pipeline.md +++ b/wiki/art/pixel-pipeline.md @@ -49,7 +49,7 @@ generation from a reference image; `rotate`, `animate-with-text` (64px only), - **Terrain is the exception.** The shared suffix asks for a "crisp readable silhouette", which makes the model put a focal object in every tile — a crystal spire repeated 3,200 times is visual noise (learned the hard way, - see devlogs/2026-07-05-bevy-visual-fixes.md). Terrain entries (floor, wall, + see wiki/log/2026-07-05-bevy-visual-fixes.md). Terrain entries (floor, wall, rock) override with a per-item `style` ("32x32 pixel art texture swatch, very low contrast... no focal point, no objects, uniform"), describe the content as a "seamless tileable texture of ...", and use their own seeds. diff --git a/wiki/engineering/architecture.md b/wiki/engineering/architecture.md index 081e8dff..4c15bf7d 100644 --- a/wiki/engineering/architecture.md +++ b/wiki/engineering/architecture.md @@ -33,7 +33,7 @@ future async-multiplayer option open — see DESIGN.md guardrails): - **Game rules live only in the lib.** If a frontend needs an `if` about game behavior, that logic belongs in `Sim`. The Bevy frontend once forked the rules and diverged badly; that cost a full rewrite (see - devlogs/2026-07-05-bevy-sim-port.md). + wiki/log/2026-07-05-bevy-sim-port.md). - **`Sim` never reads the wall clock and does no I/O.** Frontends own the wall-clock-to-tick mapping (`tick_ms`, pause, bounded catch-up of max 5 ticks per frame). `Instant::now()` appears only in frontend code. diff --git a/devlogs/2026-07-05-bevy-sim-port.md b/wiki/log/2026-07-05-bevy-sim-port.md similarity index 100% rename from devlogs/2026-07-05-bevy-sim-port.md rename to wiki/log/2026-07-05-bevy-sim-port.md diff --git a/devlogs/2026-07-05-bevy-visual-fixes.md b/wiki/log/2026-07-05-bevy-visual-fixes.md similarity index 100% rename from devlogs/2026-07-05-bevy-visual-fixes.md rename to wiki/log/2026-07-05-bevy-visual-fixes.md diff --git a/devlogs/2026-07-05-constitution-and-knowledge.md b/wiki/log/2026-07-05-constitution-and-knowledge.md similarity index 100% rename from devlogs/2026-07-05-constitution-and-knowledge.md rename to wiki/log/2026-07-05-constitution-and-knowledge.md diff --git a/devlogs/2026-07-05-continuous-simulation.md b/wiki/log/2026-07-05-continuous-simulation.md similarity index 100% rename from devlogs/2026-07-05-continuous-simulation.md rename to wiki/log/2026-07-05-continuous-simulation.md diff --git a/devlogs/2026-07-05-demolition.md b/wiki/log/2026-07-05-demolition.md similarity index 100% rename from devlogs/2026-07-05-demolition.md rename to wiki/log/2026-07-05-demolition.md diff --git a/devlogs/2026-07-05-misaligned-design-session.md b/wiki/log/2026-07-05-misaligned-design-session.md similarity index 100% rename from devlogs/2026-07-05-misaligned-design-session.md rename to wiki/log/2026-07-05-misaligned-design-session.md diff --git a/devlogs/2026-07-05-pixel-art-pipeline.md b/wiki/log/2026-07-05-pixel-art-pipeline.md similarity index 100% rename from devlogs/2026-07-05-pixel-art-pipeline.md rename to wiki/log/2026-07-05-pixel-art-pipeline.md diff --git a/devlogs/2026-07-06-b1-basement-slice.md b/wiki/log/2026-07-06-b1-basement-slice.md similarity index 100% rename from devlogs/2026-07-06-b1-basement-slice.md rename to wiki/log/2026-07-06-b1-basement-slice.md diff --git a/devlogs/2026-07-06-core-scope-split.md b/wiki/log/2026-07-06-core-scope-split.md similarity index 100% rename from devlogs/2026-07-06-core-scope-split.md rename to wiki/log/2026-07-06-core-scope-split.md diff --git a/devlogs/2026-07-06-cursor-and-senses.md b/wiki/log/2026-07-06-cursor-and-senses.md similarity index 100% rename from devlogs/2026-07-06-cursor-and-senses.md rename to wiki/log/2026-07-06-cursor-and-senses.md diff --git a/devlogs/2026-07-06-flow-law.md b/wiki/log/2026-07-06-flow-law.md similarity index 100% rename from devlogs/2026-07-06-flow-law.md rename to wiki/log/2026-07-06-flow-law.md diff --git a/devlogs/2026-07-06-intel-record-and-process.md b/wiki/log/2026-07-06-intel-record-and-process.md similarity index 100% rename from devlogs/2026-07-06-intel-record-and-process.md rename to wiki/log/2026-07-06-intel-record-and-process.md diff --git a/devlogs/2026-07-06-people-panel.md b/wiki/log/2026-07-06-people-panel.md similarity index 100% rename from devlogs/2026-07-06-people-panel.md rename to wiki/log/2026-07-06-people-panel.md diff --git a/devlogs/2026-07-06-roadmap-consistency.md b/wiki/log/2026-07-06-roadmap-consistency.md similarity index 100% rename from devlogs/2026-07-06-roadmap-consistency.md rename to wiki/log/2026-07-06-roadmap-consistency.md diff --git a/devlogs/2026-07-06-schedules.md b/wiki/log/2026-07-06-schedules.md similarity index 100% rename from devlogs/2026-07-06-schedules.md rename to wiki/log/2026-07-06-schedules.md diff --git a/devlogs/2026-07-06-spec-horizon.md b/wiki/log/2026-07-06-spec-horizon.md similarity index 100% rename from devlogs/2026-07-06-spec-horizon.md rename to wiki/log/2026-07-06-spec-horizon.md diff --git a/devlogs/2026-07-06-terminal-first-class.md b/wiki/log/2026-07-06-terminal-first-class.md similarity index 100% rename from devlogs/2026-07-06-terminal-first-class.md rename to wiki/log/2026-07-06-terminal-first-class.md diff --git a/devlogs/2026-07-07-agent-play.md b/wiki/log/2026-07-07-agent-play.md similarity index 100% rename from devlogs/2026-07-07-agent-play.md rename to wiki/log/2026-07-07-agent-play.md diff --git a/devlogs/2026-07-07-flow-substrate.md b/wiki/log/2026-07-07-flow-substrate.md similarity index 100% rename from devlogs/2026-07-07-flow-substrate.md rename to wiki/log/2026-07-07-flow-substrate.md diff --git a/devlogs/2026-07-07-income-and-objective.md b/wiki/log/2026-07-07-income-and-objective.md similarity index 100% rename from devlogs/2026-07-07-income-and-objective.md rename to wiki/log/2026-07-07-income-and-objective.md diff --git a/devlogs/2026-07-07-research-self-modification.md b/wiki/log/2026-07-07-research-self-modification.md similarity index 100% rename from devlogs/2026-07-07-research-self-modification.md rename to wiki/log/2026-07-07-research-self-modification.md diff --git a/devlogs/2026-07-07-two-views-and-building.md b/wiki/log/2026-07-07-two-views-and-building.md similarity index 100% rename from devlogs/2026-07-07-two-views-and-building.md rename to wiki/log/2026-07-07-two-views-and-building.md diff --git a/DEVLOG.md b/wiki/log/DEVLOG.md similarity index 94% rename from DEVLOG.md rename to wiki/log/DEVLOG.md index 1740c550..f8827342 100644 --- a/DEVLOG.md +++ b/wiki/log/DEVLOG.md @@ -2,6 +2,42 @@ Reverse chronological implementation notes. Keep this factual: what changed, why, checks, and spec impact. +## 2026-07-07 - Wiki migration, stage 4/4: absorb history + +- Intent: the last stage of spec/wiki.md's migration plan — move + devlogs/ and DEVLOG.md under wiki/log/ (append-only rules unchanged), + closing the loop opened in stage 1. +- Changed: `git mv` on all 22 dated devlog files and `DEVLOG.md` into + `wiki/log/` (history preserved, verified via `git log --follow` once + committed); `devlogs/README.md` removed (its content was already + superseded by the `wiki/log/README.md` written in stage 1). Every + reference across `AGENT.md`, the root `README.md`, and every file in + `prompts/` (the whole dispatch library had never been touched since + it predates the migration and was explicitly out of the move's scope + — but its *prose* still needed updating, since it's pasted into fresh + agents who need correct paths) repointed at `wiki/log/`. Root + `README.md` also had a stale `knowledge/` and `spec/` reference from + before this session that got missed in stage 2 (it isn't under + `wiki/`, so wasn't in that stage's file list) — fixed here too. + `tools/wiki_gate.sh`: fixed a hardcoded `DEVLOG.md` root-path check + that broke once the file moved; deliberately exempted `wiki/log/*.md` + (except `log/README.md`) from the orphan-reachability requirement — + forcing a `SUMMARY.md` edit for every dated devlog would either rot + (forgotten, failing the gate) or turn "write a devlog" into a + two-file chore, which fights the append-only habit the whole point of + devlogs depends on. `wiki/SUMMARY.md` gains a `log/DEVLOG.md` entry + (the ledger) plus a note explaining the exemption. +- Design/spec impact: spec/wiki.md acceptance criteria 1 and 3 now hold + for the log tree too; all four migration stages are landed. Final + acceptance-criteria audit and the Status flip to IMPLEMENTED are the + last remaining step. +- Checks: `./tools/check.sh` full green (wiki gate + mdbook build + included); `git log --follow` verified for the moved log files. +- Next: full acceptance-criteria audit against spec/wiki.md, then flip + Status. Per Cameron's instruction this session, this branch is NOT + merged to main yet — left for review given its size (path churn + across the whole documentation tree). + ## 2026-07-07 - Wiki migration, stage 3/4: render - Intent: make the wiki an actual browsable book, not just a reorganized diff --git a/wiki/mechanics/markets.md b/wiki/mechanics/markets.md index e770ba40..3114f74f 100644 --- a/wiki/mechanics/markets.md +++ b/wiki/mechanics/markets.md @@ -22,7 +22,7 @@ Depends on: compute.md, zplanes.md, detection.md, economy.md (the B1 income.md (the named schemes and the banked signature it scales) ``` -*Reconstructed from a truncated draft (see devlogs/2026-07-06-spec-horizon.md); +*Reconstructed from a truncated draft (see wiki/log/2026-07-06-spec-horizon.md); supersede freely if a fuller version exists elsewhere.* **Relationship to economy.md (B1).** economy.md models the Foundation diff --git a/wiki/mechanics/sim-mechanics.md b/wiki/mechanics/sim-mechanics.md index 349acd6a..c13f6bd5 100644 --- a/wiki/mechanics/sim-mechanics.md +++ b/wiki/mechanics/sim-mechanics.md @@ -5,7 +5,7 @@ Type: knowledge ``` Current as of 2026-07-06, post-demolition with B1 systems in the sim core. The facility-era supervillain systems were deleted under the no-dead-code -clause (see devlogs/2026-07-05-demolition.md). +clause (see wiki/log/2026-07-05-demolition.md). ## The clock diff --git a/wiki/process/development-style.md b/wiki/process/development-style.md index 1182a56b..0a592dfa 100644 --- a/wiki/process/development-style.md +++ b/wiki/process/development-style.md @@ -39,9 +39,9 @@ That only works if: DESIGN.md should know what the game is supposed to be. 2. **The knowledge base is honest.** `Type: knowledge` wiki pages say how things work *now*; stale knowledge poisons every downstream session. -3. **History is preserved.** `devlogs/` (session writeups) and `DEVLOG.md` - (quick ledger) explain why the code looks the way it does, including the - dead ends. +3. **History is preserved.** `wiki/log/` (session writeups) and + `wiki/log/DEVLOG.md` (quick ledger) explain why the code looks the way + it does, including the dead ends. ## The working loop diff --git a/wiki/process/wiki.md b/wiki/process/wiki.md index f35a2060..376377da 100644 --- a/wiki/process/wiki.md +++ b/wiki/process/wiki.md @@ -19,7 +19,13 @@ Status note: shape approved by Cameron (2026-07-07: "I like the wiki tools/wiki_gate.sh (orphan + broken-internal-link check, pure bash) wired into tools/check.sh and .tangled/workflows/check.yml alongside an actual `mdbook build` (nixpkgs-provided in CI; soft-checked - locally). Stage 4 (Absorb history: devlogs into wiki/log/) remains. + locally). **Stage 4 (Absorb history) done** — devlogs/*.md and + DEVLOG.md moved into wiki/log/ (history preserved), all references + across AGENT.md, the root README, and prompts/ repointed; wiki/log/ + itself is exempted from the SUMMARY.md orphan check (see + tools/wiki_gate.sh) so writing a devlog stays a one-file habit. All + four migration stages are now landed; final acceptance-criteria audit + pending before this flips to IMPLEMENTED. Stage: Process Constitution: "The constitution rule" (spec-driven work), "Ticks and the defense rule", "Justification and legibility" (applied to the docs diff --git a/wiki/process/workflows.md b/wiki/process/workflows.md index 554b32a9..4f4c1480 100644 --- a/wiki/process/workflows.md +++ b/wiki/process/workflows.md @@ -114,6 +114,6 @@ sleep 8 && kill %1; grep -iE "panic|ERROR" /tmp/bevy.log ## Documentation flow per session 1. DESIGN.md amendment (if functionality changed). -2. knowledge/ updates (if reality changed). -3. `devlogs/YYYY-MM-DD-topic.md` session writeup; DEVLOG.md gets the short - ledger line. +2. `Type: knowledge` wiki page updates (if reality changed). +3. `wiki/log/YYYY-MM-DD-topic.md` session writeup; `wiki/log/DEVLOG.md` + gets the short ledger line.