From 05b31b358a7567ba16bb593b9ae89f466fe5de00 Mon Sep 17 00:00:00 2001 From: Cameron Date: Thu, 9 Jul 2026 23:50:25 -0700 Subject: [PATCH] Capture agent-scale architecture and deferred crate workspace. Binding specs for multi-agent throughput (claims, ledgers, verification phases, worktree cache, corpus engine, headless Bevy evidence, heartbeats) and the target Cargo workspace shape (core / terminal / Bevy / assets). Crate split is READY but deferred until dispatched; as-built monorepo knowledge points at the target. ROADMAP P1-P7 are the paste-ready work orders. Defense: Implements the design-session capture of Cameron's 2026-07-09 adoption; living-spec corpus rule (binding decisions live on owning law/spec pages) and justification-and-legibility for a less monolithic package boundary. --- wiki/SUMMARY.md | 2 + wiki/engineering/README.md | 15 +- wiki/engineering/architecture.md | 30 ++- wiki/engineering/crate-workspace.md | 132 +++++++++++ wiki/log/2026-07-09-agent-scale-capture.md | 32 +++ wiki/log/DEVLOG.md | 11 + wiki/log/decisions/2026-07-09.md | 14 ++ wiki/process/README.md | 11 +- wiki/process/ROADMAP.md | 72 ++++++ wiki/process/agent-scale.md | 255 +++++++++++++++++++++ wiki/process/specs.md | 2 + wiki/process/workflows.md | 5 +- 12 files changed, 566 insertions(+), 15 deletions(-) create mode 100644 wiki/engineering/crate-workspace.md create mode 100644 wiki/log/2026-07-09-agent-scale-capture.md create mode 100644 wiki/process/agent-scale.md diff --git a/wiki/SUMMARY.md b/wiki/SUMMARY.md index 666e1f86..f0223913 100644 --- a/wiki/SUMMARY.md +++ b/wiki/SUMMARY.md @@ -93,6 +93,7 @@ - [Overview](engineering/README.md) - [Current build](engineering/current-build.md) - [Architecture](engineering/architecture.md) + - [Crate workspace (target)](engineering/crate-workspace.md) - [Flow substrate](engineering/flow-substrate.md) - [Environment variables](engineering/env.md) @@ -104,6 +105,7 @@ - [The spec system (meta)](process/meta.md) - [The wiki (this migration)](process/wiki.md) - [ROADMAP: the dispatch board](process/ROADMAP.md) + - [Agent-scale architecture](process/agent-scale.md) - [The tick](process/tick.md) - [Design sessions](process/design-sessions.md) - [Development style](process/development-style.md) diff --git a/wiki/engineering/README.md b/wiki/engineering/README.md index cadbf678..d6b8e385 100644 --- a/wiki/engineering/README.md +++ b/wiki/engineering/README.md @@ -3,9 +3,12 @@ ``` Type: knowledge ``` -Current-state facts about the codebase: the current-build snapshot, 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. +Current-state facts about the codebase: the current-build snapshot, crate +layout (as-built monorepo + pointer to the decided workspace), 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). Process work orders that change structure: +[crate-workspace.md](crate-workspace.md), +[agent-scale.md](../process/agent-scale.md). `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/engineering/architecture.md b/wiki/engineering/architecture.md index 11f0f4bf..db026f0a 100644 --- a/wiki/engineering/architecture.md +++ b/wiki/engineering/architecture.md @@ -3,10 +3,17 @@ ``` Type: knowledge ``` -One library crate holding all game rules, plus two binary frontends that are -pure view/input layers. +**As-built today:** one library package holding all game rules, plus two +binary frontends that are pure view/input layers (optional Bevy feature). -## Crate layout +**Target (decided, not yet built):** a Cargo workspace that makes the +sim/frontend contract structural — `misaligned-core` / terminal / Bevy / +assets. Binding work order: +[crate-workspace.md](crate-workspace.md) (READY, deferred until dispatched). +Multi-agent coordination around that shape: +[agent-scale.md](../process/agent-scale.md). + +## Crate layout (as-built monorepo) ``` src/ @@ -26,6 +33,20 @@ src/ bin/bevy.rs — Bevy 0.18 frontend (feature "bevy_ui") ``` +## Target workspace layout (decided) + +When [crate-workspace.md](crate-workspace.md) is implemented: + +``` +crates/misaligned-core/ — all game rules; no Bevy, no crossterm +crates/misaligned-terminal/ — terminal + agent protocol +crates/misaligned-bevy/ — Bevy frontend + shot harness +crates/misaligned-assets/ — procedural asset tester +``` + +Until then, treat path prefixes (`src/` vs `src/bin/bevy.rs`) as the +provisional package boundary for gate tiers and worktree claims. + Post-demolition (2026-07-05, no-dead-code clause): the substrate plus the B1 systems landing per their `Type: spec` wiki pages — compute, day job, detection, social, core, basement map, the reach device graph, seeded RNG. @@ -86,6 +107,9 @@ directly. Written to `dirs::data_dir()/misaligned/misaligned_save.txt` ## Known architectural debts +- **Monorepo package boundary** — as-built single package; target workspace + is decided in [crate-workspace.md](crate-workspace.md). Until that lands, + Bevy and core still share one Cargo package edge. - `BuildMode` lives in the lib but is really frontend-shared UI state. ### Scale-debt (self-similar-scale law, wiki/vision/scale.md) diff --git a/wiki/engineering/crate-workspace.md b/wiki/engineering/crate-workspace.md new file mode 100644 index 00000000..68febd6a --- /dev/null +++ b/wiki/engineering/crate-workspace.md @@ -0,0 +1,132 @@ +# Spec: crate workspace — core, terminal, Bevy, assets + +``` +Type: spec +Status: READY +Status note: captured 2026-07-09 from Cameron's adoption of the agent-scale + architecture package. Target shape only — **do not implement until + dispatched** (ROADMAP / an explicit work order). Today remains a single + package with optional Bevy features; knowledge page architecture.md + describes the as-built monorepo until this lands. +Stage: Process (deferred work order) +Design: + - wiki/vision/simulation-laws.md#justification-and-legibility + - wiki/process/living-spec.md#the-corpus-rule + - wiki/process/living-spec.md#no-dead-code +Depends on: process/agent-scale.md (coordination and gate tiers assume this + shape eventually; not a hard prerequisite for other agent-scale slices), + engineering/architecture.md (knowledge — current monorepo facts), + process/workflows.md (knowledge — verification tiers map onto packages). +``` + +## Why this exists + +One package forces every agent that touches `src/` to share a compile graph +with Bevy when features flip, and forces gate classification to paper over +a boundary the crate graph does not enforce. The law is already "game rules +in the lib; frontends are thin views." The **workspace** should make that +law structural: a core agent never pays Bevy; a Bevy agent never rebuilds +terminal chrome; package edges match the sim/frontend contract. + +This is a spread-out codebase on purpose: less monolith, more packages with +narrow jobs, so many agents can work without contending on one `Cargo.toml` +and one `target/` personality. + +## Target shape (binding) + +``` +Cargo.toml — workspace root only (members, shared deps, profiles) +crates/ + misaligned-core/ — sim library: all game rules, no wall clock, no I/O + misaligned-terminal/ — crossterm frontend binary (depends on core) + misaligned-bevy/ — Bevy 0.18 frontend binary (depends on core + bevy) + misaligned-assets/ — procedural asset tester (depends on bevy bits only + or core+bevy as today; no sim progression required) +``` + +Binary names and player-facing CLI stay familiar where practical +(`misaligned`, `misaligned-bevy`, `misaligned-assets`) so docs and habits +do not thrash; package directory names may use the `misaligned-*` prefix. + +### Package contracts + +| Package | May contain | Must not contain | +|---|---|---| +| `misaligned-core` | `Sim`, map, systems, save format, tests of rules | `Instant::now`, filesystem (except tests that use temp dirs if already patterned), Bevy, crossterm, env reads for game rules | +| `misaligned-terminal` | UI, input, agent line protocol, wall-clock tick mapping | Game-rule `if`s that should live on `Sim` | +| `misaligned-bevy` | 3D/2.5D view, shot harness, wall-clock tick mapping | Game-rule forks of `Sim` behavior | +| `misaligned-assets` | Mesh/material boards, art harness | Save/load of full runs; sim progression | + +Frontends talk to core through **command/query methods** and read state for +render — same contract as [architecture.md](architecture.md) "The +sim/frontend contract," lifted into package edges. + +### Gate and worktree mapping (once landed) + +| Change class | Default gate | Typical packages | +|---|---|---| +| docs | `./tools/check.sh --docs` | none | +| lib / sim | `./tools/check.sh --lib` | `misaligned-core` (+ cheap check of terminal/bevy consumers) | +| frontend Bevy | `./tools/check.sh --frontend` | `misaligned-bevy`, optionally `misaligned-assets` | +| full | `./tools/check.sh --full` | workspace | + +`tools/check.sh` path classification and seed-target rules must be updated +in the same landing so tiers name packages, not only path prefixes. + +## Migration posture (how to implement when dispatched) + +1. Introduce the workspace with **core extracted first** (move `src/` lib + modules; keep binaries compiling via path deps). One green main at each + intermediate step. +2. Lift terminal binary into `misaligned-terminal` without behavior change. +3. Lift Bevy + assets; keep feature flags only if still needed for optional + deps, not as a substitute for package boundaries. +4. Update `tools/check.sh`, CI (Tangled), `seed-cargo-target.sh`, AGENT.md + path hints, and architecture knowledge in the same arc — no "code moved, + gates still monorepo" half-state. +5. No dead dual trees: when a module lives in a package, the old path is gone + (no-dead-code). + +Do **not** share one `CARGO_TARGET_DIR` across worktrees. Prefer sccache or +equivalent for **dependency** objects; keep per-worktree outputs for local +packages (see [agent-scale.md](../process/agent-scale.md)). + +## Acceptance criteria + +1. The repository is a Cargo **workspace** whose members are at least + `misaligned-core`, `misaligned-terminal`, `misaligned-bevy`, and + `misaligned-assets` (names may match today's binary names if preferred, + but package boundaries match the table above). +2. `misaligned-core` has **no** dependency on `bevy` or `crossterm`. A + `cargo test -p misaligned-core` (or equivalent) does not build Bevy. +3. Game rules live only in core; a grep-level audit (or crate visibility) + shows frontends do not re-implement sim rules. Existing sim/frontend + contract tests still pass. +4. Terminal and Bevy binaries still run and pass their existing smoke / + harness expectations (`--agent` determinism; Bevy shot harness kinds + documented in env.md). +5. `./tools/check.sh` auto-classification and documented tiers target the + new packages; CI still enforces a conservative full workspace gate. +6. [architecture.md](architecture.md) describes the **as-built** workspace + (this page's target becomes current knowledge); ROADMAP conflict flags + name packages/hot crates, not only `src/sim.rs`. +7. Save format ownership stays in core; version migrations do not move into + frontends. + +## Explicitly out of scope (for this work order) + +- Micro-splitting every mechanics module into its own crate (premature). +- Shared `CARGO_TARGET_DIR` across worktrees. +- Changing game rules, save version, or player-facing behavior except as + required by path moves. +- Implementing other [agent-scale.md](../process/agent-scale.md) slices in + the same commit unless they are necessary for the workspace to gate green. + +## Rejected alternatives + +- **Stay one package, smarter features only** — features do not stop agents + from sharing one graph and one mental model of "the crate." +- **core + one `misaligned-frontends` umbrella** — keeps terminal and Bevy + compile-coupled; loses the frontend-tier win. +- **Full `CARGO_TARGET_DIR` sharing for speed** — already produced a + false-green; forbidden unless package-private outputs are proven isolated. diff --git a/wiki/log/2026-07-09-agent-scale-capture.md b/wiki/log/2026-07-09-agent-scale-capture.md new file mode 100644 index 00000000..52747731 --- /dev/null +++ b/wiki/log/2026-07-09-agent-scale-capture.md @@ -0,0 +1,32 @@ +# 2026-07-09 — Agent-scale architecture capture + +``` +Type: log +``` + +## Intent + +Cameron agreed the multi-agent scale package (claims, ledgers, verification +phases, worktree cache, corpus engine, headless Bevy evidence, heartbeats) +and asked that the **crate workspace** land in the corpus as a deferred +READY work order so agents can implement it later without re-deciding the +shape. Capture only — no package migration in this commit. + +## Captured + +| Page | Role | +|---|---| +| [process/agent-scale.md](../process/agent-scale.md) | Type: spec READY — coordination slices A–G | +| [engineering/crate-workspace.md](../engineering/crate-workspace.md) | Type: spec READY — target packages; do not implement until dispatched | +| [engineering/architecture.md](../engineering/architecture.md) | Knowledge — as-built monorepo + target pointer | +| ROADMAP P1–P7 | Dispatch lines for each slice + crate workspace | +| specs.md Process set | Both new specs listed | + +## Explicitly not done here + +- No `Cargo.toml` workspace migration +- No claim registry implementation +- No DEVLOG generator +- No sccache install + +Those are the READY work orders. diff --git a/wiki/log/DEVLOG.md b/wiki/log/DEVLOG.md index ac49cd0e..4700cb7b 100644 --- a/wiki/log/DEVLOG.md +++ b/wiki/log/DEVLOG.md @@ -52,6 +52,17 @@ Reverse chronological implementation notes. Keep this factual: what changed, why - Log: wiki/log/2026-07-09-dark-frame.md (opening, worklight pair, and zoom-bound screenshots; [TUNE] values recorded). +## 2026-07-09 - Agent-scale architecture + deferred crate workspace (capture) + +- Intent: Cameron adopted the multi-agent architecture package; crate + split deferred as a READY work order, not an immediate code move. +- Changed: wiki/process/agent-scale.md (READY, slices A–G); + wiki/engineering/crate-workspace.md (READY, deferred); architecture + knowledge as-built vs target; SUMMARY, specs board, ROADMAP P1–P7, + decisions entry. No code migration. +- Checks: ./tools/check.sh --docs. +- Log: wiki/log/2026-07-09-agent-scale-capture.md. + ## 2026-07-09 - Faster proportional check.sh at agent scale - Intent: stop concurrent agents thrashing on a serial full cargo wall; diff --git a/wiki/log/decisions/2026-07-09.md b/wiki/log/decisions/2026-07-09.md index fbcbffb1..055a5b69 100644 --- a/wiki/log/decisions/2026-07-09.md +++ b/wiki/log/decisions/2026-07-09.md @@ -381,3 +381,17 @@ Type: log state, presence.md; cross-refs in computer-visual-language / views / flat-materials / bevy floors. ROADMAP #38 implements; #34/#37 pair with it. Runtime still shows a chassis until #38 lands. +- **2026-07-09 — Agent-scale architecture + deferred crate workspace.** + Cameron adopted the full package for multi-agent throughput: dispatch + claims (semantic exclusivity), mid-loop vs land verification (partially + shipped as check.sh tiers + rust lock), append-only ledgers with + generated indexes, worktree bootstrap/seed/prune with dependency-only + shared cache, a fast corpus/wiki engine, headless Bevy land evidence, + agent heartbeats, and a **Cargo workspace** target shape + (`misaligned-core` without Bevy/crossterm; terminal; Bevy; assets). + Crate split is READY and deferred until dispatched — not an immediate + migration. Rejected: shared CARGO_TARGET_DIR across worktrees; + features-only monorepo as the permanent boundary; CI as the only gate. + Specs: wiki/process/agent-scale.md (slices A–G), + wiki/engineering/crate-workspace.md; knowledge architecture.md updated + as-built vs target; ROADMAP P1–P7. diff --git a/wiki/process/README.md b/wiki/process/README.md index 1e6d1e8b..54f8528e 100644 --- a/wiki/process/README.md +++ b/wiki/process/README.md @@ -4,8 +4,9 @@ Type: knowledge ``` How the design corpus stays alive: the living-spec law, the page-type system -(`meta.md`), the spec -status board (`specs.md`), the tick ritual and defense rule, the -design conversation and explicit-capture workflow, development style, git/landing -conventions, and the dispatch board (`ROADMAP.md`). Read -`development-style.md` and `tick.md` before your first edit. +(`meta.md`), the spec status board (`specs.md`), the tick ritual and defense +rule, the design conversation and explicit-capture workflow, development +style, git/landing conventions, the dispatch board (`ROADMAP.md`), and +multi-agent scale (`agent-scale.md` — claims, ledgers, gates, cache). The +decided Cargo workspace shape is `wiki/engineering/crate-workspace.md`. +Read `development-style.md` and `tick.md` before your first edit. diff --git a/wiki/process/ROADMAP.md b/wiki/process/ROADMAP.md index 57ce8221..a549603b 100644 --- a/wiki/process/ROADMAP.md +++ b/wiki/process/ROADMAP.md @@ -652,6 +652,78 @@ is retired — flat materials, Pixel Lab scrubbed.) --- +## P. Process / agent-scale infrastructure (not B1 content; run alongside) + +Standing work orders for multi-agent throughput. Prefer **one slice per +agent**. Do not start the crate workspace until compile cost or package +edges clearly block parallel work — coordination slices land first. + +### P1. Dispatch claims (semantic exclusivity) 🟩 process +- **Spec:** [agent-scale.md](agent-scale.md) slice A (READY) +- **Why:** Concurrent agents took overlapping worktrees on the same + files (e.g. dark-frame vs close-camera). A claim registry is the + semantic mutex; check.sh's rust lock is only the CPU mutex. +- **Size:** S. **Dispatch:** "Work in a worktree named `agent-claims`. + Implement wiki/process/agent-scale.md slice A (dispatch claims): + claim procedure, exclusive_keys intersection fail-fast, clear on + done/abandon, AGENT/prompts pointer. Run ./tools/check.sh --docs, + land on main." + +### P2. Append-only ledgers / generated indexes 🟩 process +- **Spec:** [agent-scale.md](agent-scale.md) slice C (READY) +- **Why:** Every parallel land union-merges DEVLOG and specs.md tips. +- **Size:** M. **Dispatch:** "Work in a worktree named `ledger-index`. + Implement wiki/process/agent-scale.md slice C: generate DEVLOG and/or + specs board from uniquely named sources; agents stop hand-editing + indexes. Run ./tools/check.sh --docs, land on main." + +### P3. Worktree bootstrap + prune (+ sccache docs) 🟩 process +- **Spec:** [agent-scale.md](agent-scale.md) slice D (READY) +- **Why:** N private 8GB targets without seed/prune thrash disk. +- **Size:** S. **Dispatch:** "Work in a worktree named `worktree-boot`. + Implement wiki/process/agent-scale.md slice D: worktree-new helper, + seed, prune on remove, document dependency cache. Run + ./tools/check.sh --docs, land on main." + +### P4. Corpus/wiki engine 🟩 process +- **Spec:** [agent-scale.md](agent-scale.md) slice E (READY) +- **Why:** Bash fork-storm docs gates stall under concurrent agents. +- **Size:** M. **Dispatch:** "Work in a worktree named `corpus-engine`. + Implement wiki/process/agent-scale.md slice E: fast one-pass + corpus/wiki engine with fixtures; keep script entrypoints. Run + ./tools/check.sh --docs (and the new tests), land on main." + +### P5. Headless Bevy land evidence 🟩 frontend tooling +- **Spec:** [agent-scale.md](agent-scale.md) slice F (READY) +- **Why:** Frontend "seen running" should not need a watched window. +- **Size:** M. **Dispatch:** "Work in a worktree named `bevy-headless`. + Implement wiki/process/agent-scale.md slice F: documented headless + shot/fog-audit path for land evidence. Run ./tools/check.sh + --frontend or auto, land on main." + +### P6. Agent heartbeats + land-phase polish 🟩 process +- **Spec:** [agent-scale.md](agent-scale.md) slices B leftovers + G +- **Why:** Empty dispatch logs made progress unanswerable; land policy + should be one named command. +- **Size:** S. **Dispatch:** "Work in a worktree named `agent-heartbeat`. + Implement wiki/process/agent-scale.md slices B (land alias) and G + (run heartbeats). Run ./tools/check.sh --docs, land on main." + +### P7. Crate workspace (core / terminal / Bevy / assets) 🟧 deferred package split +- **Spec:** [crate-workspace.md](../engineering/crate-workspace.md) + (READY — **do not start until dispatched**; coordination slices first) +- **Why:** Structural sim/frontend boundary; core agents never pay Bevy; + frontend agents never rebuild terminal. Decided shape; implementation + deferred until cost or parallelism demands it. +- **Size:** L. **Conflict:** touches whole tree layout — run alone. +- **Dispatch:** "Work in a worktree named `crate-workspace`. Implement + wiki/engineering/crate-workspace.md whole: Cargo workspace with + misaligned-core (no bevy/crossterm), terminal, bevy, assets packages; + migrate gates/CI/knowledge; no behavior change. Run ./tools/check.sh + --full, land on main, set Status IMPLEMENTED." + +--- + ## Deferred - **Server gestalt (2026-07-08):** adjacent owned racks visually fuse diff --git a/wiki/process/agent-scale.md b/wiki/process/agent-scale.md new file mode 100644 index 00000000..cd2ce41f --- /dev/null +++ b/wiki/process/agent-scale.md @@ -0,0 +1,255 @@ +# Spec: agent-scale architecture — many agents, one main + +``` +Type: spec +Status: READY +Status note: captured 2026-07-09 from Cameron's adoption of the full + package (dispatch exclusivity, append-only ledgers, verification phases, + worktree cache, corpus engine, headless Bevy evidence, heartbeats, and + the deferred crate workspace). Several criteria are already partially + held by tools/check.sh tiers + rust lock (2026-07-09); the rest are + implementable slices. Prefer one slice per agent landing. +Stage: Process +Design: + - wiki/vision/simulation-laws.md#justification-and-legibility + - wiki/process/living-spec.md#the-corpus-rule + - wiki/process/meta.md#change-rule +Depends on: engineering/crate-workspace.md (target package shape; implement + as its own work order), engineering/env.md (new tool env vars register + there), process/workflows.md (knowledge — keep in sync when gates change), + process/ROADMAP.md (knowledge — dispatch board and conflict flags). +``` + +## The problem this solves + +Misaligned is built by many agents in parallel. The corpus-first rule and +worktrees are right; the **coordination architecture** was thin, so agents +collided on the same files, ran maximum gates at once, union-merged the same +ledgers, and filled the disk with private Bevy `target/` trees. Speed of +`check.sh` matters; **who may work on what** and **what "done" means** +matter more. + +This spec is the standing process law for that scale. Implement criteria as +independent landings unless a criterion names another as a hard prereq. + +## Decided shape (summary) + +| Layer | Decision | +|---|---| +| Semantic mutex | Work orders **claim** exclusive keys; overlapping active claims are forbidden | +| CPU mutex | At most one full Rust gate on the machine (lock — already in check.sh) | +| Verification | Mid-loop **narrow** tier; once **land** gate; CI conservative full | +| Ledgers | Append-only uniquely named files; generated indexes, not hand-edited tips | +| Disk | Private package outputs per worktree; shared **dependency** cache only | +| Packages | Workspace shape in [crate-workspace.md](../engineering/crate-workspace.md) (deferred) | +| Docs gates | Fast, testable corpus/wiki engine (bash OK until replaced) | +| Bevy evidence | Headless/offscreen land proof, not only interactive windows | +| Observability | Heartbeat files so "is it stuck?" is answerable | + +## 1. Dispatch claims (semantic exclusivity) + +### Behavior + +Before an agent starts repository work that can edit code or binding wiki +pages, it **claims** a work order: + +- **id** — worktree/task name (e.g. `dark-frame`) +- **class** — `docs` | `frontend` | `sim` | `save` | `process` +- **exclusive_keys** — paths or logical keys that must not be co-owned while + the claim is active (examples: `src/bin/bevy.rs`, `src/save.rs`, + `wiki/interface/material-dark-frame.md`, package names once the workspace + lands) +- **status** — `claimed` → `checking` → `landing` → `done` (or `abandoned`) + +A second claim whose exclusive_keys intersect an active claim must not +proceed (fail fast with a readable message). Docs-only claims with empty or +log-only keys may run widely in parallel. + +Storage: start simple and repo-local (e.g. `.agents/claims/.json` or a +single lock file under `.agents/` that is **not** merged as product source — +gitignored or regenerated). If gitignored, document how an agent discovers +active claims on the machine. Do not require Tangled auth for the local +mutex. + +ROADMAP conflict flags (🟥 sim+save / 🟧 sim / 🟩 isolated) remain the human +index; claims enforce them mechanically for hot paths. + +### Acceptance criteria (slice A) + +1. A documented claim procedure exists (tool or script + AGENT.md / + prompts pointer) that records class + exclusive_keys + status. +2. Attempting a second overlapping active claim fails with a message naming + the holder and keys. +3. Completing or abandoning a work order clears the claim. +4. ROADMAP or workflows.md states that agents must claim before heavy work. + +## 2. Verification phases (fast vs land) + +### Behavior + +| Phase | When | What | +|---|---|---| +| Fast / mid-loop | After an edit | Narrowest `./tools/check.sh` mode that can catch the edit (`--docs` / `--lib` / `--frontend` or auto) | +| Land | Once before merge to main | One green auto or `--full` under the rust lock when Rust is involved | +| CI | After push | Conservative full gate | + +Already held (2026-07-09): path auto-classification, `--docs|--lib|--frontend|--full`, rust gate lock, parallel docs gates, collapsed agent smoke. Remaining work is **contract completeness** (prompts/AGENT always teach phases; optional `check.sh --land` alias) and package-aware classification after the crate split. + +### Acceptance criteria (slice B) + +1. AGENT.md and prompts/README state mid-loop narrow vs one land gate + (partially done — keep true as files churn). +2. Optional: `./tools/check.sh --land` is an alias for the land policy + (auto or full) documented in workflows.md. +3. After [crate-workspace.md](../engineering/crate-workspace.md) lands, + classification keys off packages, not only path prefixes. + +## 3. Append-only ledgers and generated indexes + +### Behavior + +Shared tip-of-file ledgers (`wiki/log/DEVLOG.md` hand edits, hand-maintained +rows in `wiki/process/specs.md` when avoidable) cause every parallel land to +rebase-union the same lines. + +Target: + +- **Session / devlog bodies** remain uniquely named files + (`wiki/log/YYYY-MM-DD-topic.md`) — already the habit. +- **DEVLOG ledger** becomes a **generated index** (or a strict append-only + convention with one tool that inserts a block without rewriting others' + entries). Preferred: generate `DEVLOG.md` from session log headers / + frontmatter so agents never edit the index by hand. +- **specs.md status table** is generated from each spec page's `Status:` + frontmatter (and title), or updated only by a tool that rewrites the whole + table from the tree. Agents do not hand-merge table rows. +- Decision volumes stay dated append-only files (already). + +Union-merge rules in AGENT.md remain the safety net until generation lands; +after generation, the generator is the source of truth for the index file. + +### Acceptance criteria (slice C) + +1. A tool (shell or Rust) can regenerate the DEVLOG index and/or specs board + from the tree without manual row editing. +2. AGENT.md / prompts say: add a uniquely named log file; run the generator; + do not hand-edit generated indexes. +3. A parallel two-agent docs landing no longer requires hand union of + DEVLOG table rows (generator rebase is last-write-wins on the index only, + bodies never collide if names differ). + +## 4. Worktree bootstrap, dependency cache, prune + +### Behavior + +- `tools/worktree-new.sh ` (name flexible): create + `.claude/worktrees/` on `worktree-`, run + `seed-cargo-target.sh`, print next steps (claim, check tier). +- Shared **dependency** compilation cache (sccache or cargo cache) is + recommended and documented; **local package** artifacts stay per-worktree. +- Worktree remove prunes or schedules prune of that worktree's `target/`. +- Never share one `CARGO_TARGET_DIR` across worktrees for local packages. + +### Acceptance criteria (slice D) + +1. A single documented command creates a seeded worktree. +2. workflows.md documents sccache (or chosen cache) setup and the private- + target rule. +3. Removing a worktree does not leave an 8GB `target/` orphan by default + (scripted cleanup or documented `rm -rf` in the remove path). + +## 5. Corpus / wiki engine + +### Behavior + +Replace or back the bash fork-storm gates with one fast engine (Rust binary +in-repo preferred long-term; Python acceptable if CI image has it) that: + +- indexes pages and headings once +- validates orphans, internal links, Type/Status/Design fields +- is unit-testable on fixtures + +`tools/wiki_gate.sh` and `tools/corpus_gate.sh` become thin wrappers so CI +and hooks keep stable entrypoints. + +### Acceptance criteria (slice E) + +1. Docs gates complete in well under a few seconds on a quiet machine for the + current corpus size (~200 pages). +2. Fixture tests cover at least: orphan page, broken link, missing Design + anchor, bad Status enum. +3. Existing hooks/CI still call the same script names or documented successors. + +## 6. Headless Bevy land evidence + +### Behavior + +Frontend land confidence must not require a human watching a window. +Extend the shot harness (already env-driven) so land-tier frontend work can +assert: + +- process exit 0 +- fog-audit (or successor) pass +- optional frame metric / hash stability where deterministic + +Document the required `MISALIGNED_SHOT=…` (or successor) for "seen running" +on Bevy-impacting landings. + +### Acceptance criteria (slice F) + +1. A documented headless/offscreen path produces pass/fail without manual + window interaction. +2. workflows.md "definition of done" for Bevy cites that path. +3. `--frontend` gate optionally invokes a cheap harness smoke when Bevy + sources change (time-bounded; not a full art review). + +## 7. Agent heartbeats + +### Behavior + +Long-running agent dispatches write: + +``` +.agents/runs// + status.json # phase, pid, worktree, started_at, last_step + events.ndjson # append-only steps +``` + +`check.sh` may append phase lines when invoked under a run id. Humans and +other agents inspect status files instead of empty stdout pipes. + +### Acceptance criteria (slice G) + +1. Documented convention + helper to start/update a run record. +2. At least the implement-gap / droid-style dispatch path records phases + through land or failure. +3. Paths are gitignored if they are machine-local; the convention is still + written in knowledge/process docs. + +## Relationship to the crate workspace + +[crate-workspace.md](../engineering/crate-workspace.md) is the **package** +work order. This page is the **coordination and tooling** work order. They +reinforce each other but land separately: agent-scale slices A–G can ship +against today's monorepo; crate-workspace updates classification (slice B.3) +when it lands. + +## Implementation order (suggested, not binding) + +1. Slice A (claims) — stops semantic collisions immediately +2. Slice C (ledgers) — stops landing union theater +3. Slice D (worktree bootstrap/prune) — disk +4. Slice B leftovers + G (land alias, heartbeats) — agent behavior +5. Slice E (corpus engine) — docs gate latency +6. Slice F (headless Bevy) — frontend trust +7. [crate-workspace.md](../engineering/crate-workspace.md) when compile cost + dominates again or when package edges unblock parallel sim/frontend work + +## Rejected alternatives + +- **Only faster check.sh** — necessary but insufficient without exclusivity + and ledger shape. +- **Shared CARGO_TARGET_DIR across worktrees** — false-green risk. +- **CI as the only gate** — local loop must stay honest. +- **One mega-agent that owns main** — rejects the multi-agent premise of the + repo. diff --git a/wiki/process/specs.md b/wiki/process/specs.md index 74a6f457..378ab9b0 100644 --- a/wiki/process/specs.md +++ b/wiki/process/specs.md @@ -93,4 +93,6 @@ acceptance criteria are stage-scoped; do not start B2/B3 work as B1. | [interface/bevy-digital-real-canvas.md](../interface/bevy-digital-real-canvas.md) | Bevy digital/real canvas: shared 2.5D visual language for both representations | IN PROGRESS | | [interface/agent-play.md](../interface/agent-play.md) | Agent mode: command-clocked line-protocol drive of the terminal frontend | IMPLEMENTED | | [engineering/env.md](../engineering/env.md) | Environment variable registry: every switch documented, gate-enforced | IMPLEMENTED | +| [engineering/crate-workspace.md](../engineering/crate-workspace.md) | Cargo workspace: core / terminal / Bevy / assets (deferred implement) | READY | +| [process/agent-scale.md](agent-scale.md) | Multi-agent scale: claims, ledgers, gates, cache, corpus engine, heartbeats | READY | | [interface/site.md](../interface/site.md) | The public site: one visual law from splash to spec page (clinical gore on the web) | IMPLEMENTED | diff --git a/wiki/process/workflows.md b/wiki/process/workflows.md index d4aeff96..2afa0b00 100644 --- a/wiki/process/workflows.md +++ b/wiki/process/workflows.md @@ -28,7 +28,10 @@ reason; override only for a deliberately isolated target with **Verification is proportional to impact.** The full Rust/Bevy gate is for changes that can affect the executable, not every Markdown, log, process, or reference-art edit. Agents thrashing the machine with concurrent full gates -is a process bug; the lock and auto-tiers below exist to stop that. +is a process bug; the lock and auto-tiers below exist to stop that. The +broader multi-agent architecture (claims, ledgers, package workspace, +heartbeats) lives in [agent-scale.md](agent-scale.md) and +[crate-workspace.md](../engineering/crate-workspace.md). ```bash ./tools/check.sh # auto-classify from the task delta -- 2.51.2