diff --git a/spec/README.md b/spec/README.md index 3c733d1e..7fa9e9ab 100644 --- a/spec/README.md +++ b/spec/README.md @@ -5,6 +5,10 @@ The constitution says what the game is; a spec says exactly what one system does and when it is done. This is the layer you point an agent at: "go implement spec/day-job.md" is a complete instruction. +**To pick up work:** see [ROADMAP.md](ROADMAP.md) β€” the dispatch board of +ready work orders, each with a worktree name, a paste-ready dispatch line, +and parallel-conflict flags. + ## Format Every spec carries a header: diff --git a/spec/ROADMAP.md b/spec/ROADMAP.md new file mode 100644 index 00000000..cacf692e --- /dev/null +++ b/spec/ROADMAP.md @@ -0,0 +1,171 @@ +# ROADMAP β€” the dispatch board + +Pick-up-later work orders, one per agent. This is not a spec (it carries no +acceptance criteria of its own); it is an index that points each agent at the +spec it should implement. The binding detail lives in the linked `spec/*.md`. + +## How to dispatch + +Hand an agent its **Dispatch line** verbatim. Every agent must, per +[AGENT.md](../AGENT.md): work in a worktree (suggested name given), run +`./tools/check.sh` before committing, land by rebasing onto `origin/main`, +and mark the spec's `Status:` in the implementing commit. + +## Conflict flags β€” read before running agents in parallel + +The hot files are **`src/sim.rs`** (the orchestrator) and **`src/save.rs`** +(hand-rolled serialization). Almost every feature edits both, so two +sim-heavy agents running at once *will* rebase-collide. + +- πŸŸ₯ **sim+save** β€” edits the orchestrator and the save format. Run at most + one of these at a time, or expect to reconcile. +- 🟧 **sim** β€” edits `sim.rs` but not the save format. Some contention. +- 🟩 **isolated** β€” a frontend binary, a test file, a leaf module, or docs. + Safe to run alongside anything. + +**Parallel-safe set to launch right now (no mutual collision):** #2 (Bevy), +#11 (integration test), #13 (art), plus at most one πŸŸ₯ item. + +--- + +## A. Finish B1 β†’ a playable Act One (do first) + +### 1. Schedules & located presence πŸŸ₯ sim+save +- **Spec:** [schedules.md](schedules.md) (READY) +- **Why:** the missing foundation under every social feature β€” `observe` + currently gates on "any controlled sensor", not "a sensor that sees them". +- **Size:** M. **Depends on:** social (done), basement-map. +- **Dispatch:** "Work in a worktree named `schedules`. Implement + spec/schedules.md end to end (sim + both frontends + save), run + ./tools/check.sh, land on main. Set the spec Status when done." + +### 2. Bevy interactive parity 🟩 isolated (`src/bin/bevy.rs`) +- **Spec:** none needed β€” bring Bevy to terminal parity. +- **Why:** Bevy is a read-only sidebar; the terminal has the people panel and + action keys. This is the single biggest player-facing gap and touches no + shared sim state. +- **Size:** L. **Depends on:** nothing. **The best always-parallel item.** +- **Dispatch:** "Work in a worktree named `bevy-parity`. Bring the Bevy + frontend (src/bin/bevy.rs) to feature parity with the terminal: interactive + compute allocation, people panel, day-job and detection panels, and their + inputs. Do not change sim.rs or save.rs. Run ./tools/check.sh, land on main." + +### 3. Day-job loop β†’ IMPLEMENTED πŸŸ₯ sim+save +- **Spec:** [day-job.md](day-job.md) (IN PROGRESS) +- **Why:** jobs/trust/attention/pilot-clock exist in sim; verify every + acceptance criterion, add the terminal job panel, make trust/attention + legible. +- **Size:** M. **Dispatch:** "Work in a worktree named `day-job`. Drive + spec/day-job.md to IMPLEMENTED: audit each acceptance criterion, add the + missing player surfaces, test the three outcomes + pilot shutdown. Run + ./tools/check.sh, land on main, set Status." + +### 4. Detection β†’ IMPLEMENTED 🟧 sim +- **Spec:** [detection.md](detection.md) (IN PROGRESS) + + [aggregate-observer.md](aggregate-observer.md) criterion 4. +- **Why:** observers panel polish, the audit date as a visible countdown, and + the one open scale-debt item β€” the toy second-level aggregate test proving + the aggregate-Observer interface composes. +- **Size:** S–M. Mostly `detection.rs` + frontends. **Dispatch:** "Work in a + worktree named `detection-finish`. Complete spec/detection.md to + IMPLEMENTED and add the missing toy second-level aggregate test from + spec/aggregate-observer.md criterion 4. Run ./tools/check.sh, land on main." + +### 5. Compute & core β†’ IMPLEMENTED πŸŸ₯ sim+save +- **Spec:** [compute.md](compute.md), [core.md](core.md) (IN PROGRESS) +- **Why:** confirm buy/steal/optimize all surface legibly, machine-failure is + visible, and the core's "how-dead-am-I" readout is complete. +- **Size:** M. **Dispatch:** "Work in a worktree named `compute-core`. Drive + spec/compute.md and spec/core.md to IMPLEMENTED with tests and legible + player surfaces. Run ./tools/check.sh, land on main, set Status." + +--- + +## B. Structural B2 β€” decide-the-shape work (sequence #6 then #7) + +### 6. Recursive Space / z-planes πŸŸ₯ sim+save +- **Spec:** [zplanes.md](zplanes.md) (READY) +- **Why:** `World`/`Plane` and nested `Layout`. Foundational β€” **land before + markets/greenfield**. Reshapes map ownership; heavy. +- **Size:** L. **Depends on:** basement-map, schedules (#1) ideally first. +- **Dispatch:** "Work in a worktree named `zplanes`. Implement spec/zplanes.md + (World/Plane, recursive Layout, transitions, a second authored plane). Keep + all B1 tests green against a one-plane world. Run ./tools/check.sh, land." + +### 7. Sync-lag rollback πŸŸ₯ sim+save +- **Spec:** [rollback.md](rollback.md) (READY) +- **Why:** the MindState/WorldLedger split β€” the signature death mechanic + ("you forget, the world remembers"). Deeply sim+save-heavy. +- **Size:** L. **Sequence after #6** (both rewrite save; don't run together). +- **Dispatch:** "Work in a worktree named `rollback`. Implement + spec/rollback.md: classify every Sim field as MindState or WorldLedger, + build the rollback report and modal, test the inherited-consequence case. + Run ./tools/check.sh, land." + +--- + +## C. B3 / frontier + +### 8. Markets & fronts πŸŸ₯ sim+save +- **Spec:** [markets.md](markets.md) (READY) +- **Why:** the economy as schemes; fronts as Resource-sources. Greenfield + depends on z-planes (#6); the schemes layer can start independently. +- **Size:** M–L. **Dispatch:** "Work in a worktree named `markets`. Implement + spec/markets.md (fronts as Resource-sources, operations as timed schemes + with payout + signature). Run ./tools/check.sh, land, set Status." + +### 9. Overt phase / the reveal πŸŸ₯ sim+save +- **Spec:** [overt-phase.md](overt-phase.md) (READY) +- **Why:** the two-phase hinge β€” concealment ends, threat panel replaces + detection, migration-under-fire is the set piece. Large. +- **Size:** L. **Depends on:** schedules (#1), z-planes (#6). +- **Dispatch:** "Work in a worktree named `overt-phase`. Implement + spec/overt-phase.md v1: the reveal/containment trigger, threat panel, + three-tier waves, one playable defensive loop tested headlessly. Land." + +### 10. Chargen β›” blocked β€” needs YOU, not an agent +- **Spec:** [chargen.md](chargen.md) (DRAFT) +- **Why blocked:** the spec stays DRAFT until the constitution's decisions log + names the archetype set. That is a **design-session** call for Cameron, not + an implementation task. Promote to READY after the decision, then dispatch. + +--- + +## D. Quality & infrastructure (parallelize freely) + +### 11. Full-act integration test 🟩 isolated (new test file) +- **Spec:** none β€” asserts the Act One arc end to end. +- **Why:** a headless startβ†’exit playthrough (get eyes β†’ recruit Marcus β†’ + survive an audit) as one test, so the arc can't silently break. Named in + design-judgment.md as the bar; not yet built. +- **Size:** S–M. **The best parallel companion to any A/B item.** +- **Dispatch:** "Work in a worktree named `act-one-test`. Add a headless + integration test that plays Act One from start to a quiet exit and asserts + the arc holds. Touch only a test file. Run ./tools/check.sh, land." + +### 12. save.rs de-risk πŸŸ₯ the save format itself +- **Why:** 1136 hand-rolled lines that every feature fights. Assess serde or a + table-driven rewrite to shrink the conflict surface. **Do deliberately, + alone β€” not concurrently with any πŸŸ₯ B-item**, since it rewrites what they + all edit. +- **Size:** L. **Dispatch:** "Work in a worktree named `save-rework`. Evaluate + and (if favorable) execute a serde or table-driven rewrite of src/save.rs, + preserving v4 load + all round-trip tests + legacy migration. Land only with + ./tools/check.sh green and every save test passing." + +### 13. Art regeneration 🟩 isolated (assets) β€” β›” blocked on quota +- **Why:** clinical-amber b1 tiles via Pixel Lab (see the pixellab skill). + Zero code conflict, but blocked until the API quota refreshes. +- **Dispatch (once quota is back):** "Work in a worktree named `art-b1`. + Regenerate the remaining b1 tiles per assets/pixellab/manifest.json and the + pixellab skill; wire new textures into src/bin/bevy.rs Art::load and clear + the matching placeholders in knowledge/art-pipeline.md. Land." + +--- + +## Suggested first wave (no mutual collision) + +Launch together: **#1 schedules** (the one πŸŸ₯ you run now) + **#2 Bevy** + +**#11 integration test**. When #1 lands, start **#6 z-planes**; hold **#7 +rollback** and **#12 save-rework** until the save format is quiet. **#10 +chargen** waits on your design decision. diff --git a/tools/check.sh b/tools/check.sh index b7438cec..0b86f9f2 100755 --- a/tools/check.sh +++ b/tools/check.sh @@ -31,6 +31,7 @@ for f in spec/*.md; do base=$(basename "$f") [ "$base" = "README.md" ] && continue [ "$base" = "meta.md" ] && continue + [ "$base" = "ROADMAP.md" ] && continue # dispatch index, not a system spec for field in "Status:" "Stage:" "Constitution:" "Depends on:"; do grep -q "^$field\| $field" "$f" || { echo "FAIL: $f missing '$field'"; fail=1; } done