From 60c0029e2b6568b56688d3891166be13764a0374 Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 31 Jul 2026 00:13:10 +0200 Subject: [PATCH] Add CB-WP-0001: establish assimilate-and-surpass inner loop via GROUND kernel --- workplans/CB-WP-0001-inner-loop.md | 168 +++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 workplans/CB-WP-0001-inner-loop.md diff --git a/workplans/CB-WP-0001-inner-loop.md b/workplans/CB-WP-0001-inner-loop.md new file mode 100644 index 0000000..185d62a --- /dev/null +++ b/workplans/CB-WP-0001-inner-loop.md @@ -0,0 +1,168 @@ +--- +id: CB-WP-0001 +title: "Establish the assimilate-and-surpass inner loop via the GROUND game kernel" +status: active +--- + +# Purpose + +The primary deliverable of this workplan is **the inner loop**, not the +component it produces. Every Clay-Borg capability, starting now and forever +after, is built by the same sequence: + +1. **Research** — identify the best game-engine component in existence for + this capability. Study its design, data model, performance + characteristics, and failure modes. No implementation starts before the + state of the art is understood and documented. +2. **Approve** — explicitly decide that the survey is complete and name the + benchmark-to-beat. This is a recorded decision, not an implicit one. +3. **Decide** — choose how to implement (assimilate behind a port, reimplement, + or hybrid) such that our result is better in the relevant dimensions: + - **Ease of specification** — how simply the capability's behavior can be + stated, tested, and understood + - **Efficiency of implementation** — code size, dependency weight, build + time, agent-legibility + - **Speed of execution** — runtime performance against measured baselines + - **Optionality** — how cleanly it integrates, extends, and can be replaced +4. **Specify** — write the specification and its acceptance metrics *before* + the implementation. +5. **Loop code with metrics** — implement iteratively; every iteration is + judged against the metrics from step 4 and the baseline from step 2. + +The demanding first example that forces this loop into existence is the +**headless GROUND game kernel**: deterministic authoritative state, +command → validation → events → reducer, simultaneous commit/reveal, and +replay. It is deliberately hard enough that a shallow loop will fail on it. + +State of the art to beat (initial candidates, to be confirmed in T-03): +boardgame.io (turn/phase game-state engines), Tabletop Simulator scripting +(tabletop semantics), event-sourcing kernels, and bevy_ecs-style scheduling. + +## Phase A — Codify the loop + +## Task: Write specs/InnerLoop.md — the assimilate-and-surpass loop + +```task +id: CB-WP-0001-T01 +status: todo +priority: high +``` + +Codify the five-step loop above as a normative spec: the SOTA-survey +template (what a research doc must contain: candidates, benchmarks, +measured/cited baselines, verdict), the four-dimension rubric with how each +dimension is scored, the approval gate, and the definition of done for a +loop iteration. This spec is what every later workplan references. + +## Task: Define the metrics and scenario conventions + +```task +id: CB-WP-0001-T02 +status: todo +priority: high +``` + +Write specs/MetricsAndScenarios.md: the scenario file format (initial +state, command sequence, expected end-state assertions), how benchmarks are +declared and compared against a recorded baseline, and what a replay bundle +contains. These are the instruments the loop measures with; without them +"better in all relevant dimensions" is unfalsifiable. + +## Phase B — First application: the GROUND game kernel + +## Task: SOTA research — game-state kernel survey + +```task +id: CB-WP-0001-T03 +status: todo +priority: high +``` + +Produce research/CB-RES-0001-game-kernel.md following the InnerLoop survey +template. Survey at minimum: boardgame.io, Tabletop Simulator's scripting +model, an event-sourcing kernel, and one ECS-centric approach. For each: +data model, mutation mechanism, determinism/replay story, hidden-information +handling, simultaneous-action handling, measured or cited performance. +Conclude with the named benchmark-to-beat per dimension. + +## Task: Approval and implementation decision (ADR) + +```task +id: CB-WP-0001-T04 +status: todo +priority: high +``` + +Record decisions/ADR-0002-game-kernel.md: survey approved, benchmark-to-beat +named, and the assimilate/reimplement/hybrid choice made with the expected +advantage stated per dimension. The gate: no kernel code before this ADR is +committed. + +## Task: Write the GROUND rules specification + +```task +id: CB-WP-0001-T05 +status: todo +priority: high +``` + +Write specs/GroundRules.md: numbered, individually testable rule statements +for GROUND — setup, phases, relationship graph and capacity, attack/support, +DARVO sequence machine, GROUND practice, commit/reveal windows, resolution +ordering, end conditions. This is the concrete content the kernel must run; +each numbered rule maps to at least one scenario. + +## Task: Write the kernel specification with acceptance metrics + +```task +id: CB-WP-0001-T06 +status: todo +priority: medium +``` + +Write specs/GameKernel.md: canonical state model, command/event/reducer +contracts, determinism requirements (seeded RNG, state hashes), snapshot and +replay format, and the acceptance metrics — each tied to a baseline from +CB-RES-0001 (e.g. spec-to-scenario coverage, lines-per-rule, replay of N +thousand events under a time budget, zero state divergence across M replays). + +## Task: Scaffold the workspace and metrics harness + +```task +id: CB-WP-0001-T07 +status: todo +priority: medium +``` + +Create the minimal Cargo workspace (cb-kernel, cb-events, cb-game-runtime, +games/ground — nothing speculative), CI with fmt/clippy/nextest, the +scenario-runner harness from T02, and Criterion benchmark skeletons wired to +the baselines. An empty-but-compiling, measurable loop bed. + +## Task: Implement the kernel against scenarios and metrics + +```task +id: CB-WP-0001-T08 +status: todo +priority: medium +``` + +The code loop: implement the GROUND kernel iteratively, each iteration +judged against the T06 metrics and T05 scenarios. Done when all GROUND +scenarios pass headless, replay is deterministic, and every acceptance +metric meets or beats its recorded baseline — with the comparison numbers +committed as evidence. + +## Task: Retrospective — harden the loop from what the example taught + +```task +id: CB-WP-0001-T09 +status: todo +priority: low +``` + +Revise specs/InnerLoop.md from actual experience: which steps were too +heavy or too thin, what the survey template missed, what metrics turned out +to matter. Output is InnerLoop v1.0 — the process the next capability +workplan starts from. The loop is only "established" once it has survived +its first full pass and been corrected.