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

id	kind	title	status	state_hub_workstream_id
CB-WP-0001	product	Establish the assimilate-and-surpass inner loop via the GROUND game kernel	done	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

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

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

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)

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

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

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

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

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

id: CB-WP-0001-T09
status: done
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.

Outcome: specs/InnerLoop.md v1.0 and history/260731-inner-loop-retrospective.md. The adversarial review, the parity cap, the provisional mechanism and the ADR gate held. The gap the pass exposed: both serious errors were measurement errors and review caught neither, because review reads prose and these were claims about numbers. v1.0 adds the positive-control rule, metric feasibility and instrument naming, and four implementation rules.