Add CB-WP-0001: establish assimilate-and-surpass inner loop via GROUND kernel

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.