clay-borg/workplans/CB-WP-0001-inner-loop.md

---
id: CB-WP-0001
title: "Establish the assimilate-and-surpass inner loop via the GROUND game kernel"
status: active
state_hub_workstream_id: "a1b434dc-b1c6-46b5-bbd9-80a4e6b7620f"
---

# 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: done
priority: high
state_hub_task_id: "7a0ff270-395c-4774-b0d1-332c10acbd8e"
```

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: done
priority: high
state_hub_task_id: "04e2c44c-6db3-4799-94b0-e22ef395d7fe"
```

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: done
priority: high
state_hub_task_id: "8dec6577-9397-40ee-b99b-9119dcdac115"
```

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. This pass is
**tier L** and **high-leverage**: the runnable-baseline option is invoked —
ship a fidelity-noted local harness for the leading runnable candidate
(boardgame.io expected). Document the research trail in
history/YYMMDD-game-kernel-research.md per InnerLoop §Step 2.

## Task: Approval and implementation decision (ADR)

```task
id: CB-WP-0001-T04
status: done
priority: high
state_hub_task_id: "2024c17d-9a37-48d2-8cb6-0fb3d8a19691"
```

Adversarial review first (InnerLoop §Step 2): a separate session attacks
the survey; challenge and response are committed as
history/YYMMDD-game-kernel-challenge.md and -response.md, one round. Then
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: done
priority: high
state_hub_task_id: "2b35574b-0e14-4074-903f-294c32fa22ae"
```

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. **Source of truth is the sister repo
`~/ground-game` (edition `ground-darvo-r0`)** — this spec is a
simulation-oriented derivation of those rules, not an independent design;
divergences must be flagged back to ground-game, never silently resolved
here. Each numbered rule maps to at least one scenario.

## Task: Write the kernel specification with acceptance metrics

```task
id: CB-WP-0001-T06
status: done
priority: medium
state_hub_task_id: "fc3fa174-8a1f-46ac-a922-5d7b80231d5f"
```

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: done
priority: medium
state_hub_task_id: "9988219a-aaea-4a34-986c-e350e8b28a3a"
```

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: done
priority: medium
state_hub_task_id: "3a42ff70-f3c6-4e3e-b022-f701729e71ff"
```

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.

**Outcome:** evidence/CB-EV-0001-game-kernel.md. 21 scenarios pass, AM-1
rule coverage 58/58, AM-6/AM-7/AM-8/AM-10 met with margin. **AM-4 is not
met** (33 crates vs ≤20) and is carried into T09 as a decision: make
serde_yaml optional, or move a target that the spec's own K5/K7
contracts make unreachable. AM-12 could not be computed honestly because
per-task token counts were never instrumented — also a T09 input.

## Task: Retrospective — harden the loop from what the example taught

```task
id: CB-WP-0001-T09
status: todo
priority: low
state_hub_task_id: "e99b107e-087e-49e1-96b5-67805deb242f"
```

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.