188 lines
7.3 KiB
Markdown
188 lines
7.3 KiB
Markdown
---
|
|
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: todo
|
|
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: todo
|
|
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: todo
|
|
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: todo
|
|
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: todo
|
|
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: todo
|
|
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.
|
|
|
|
## 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.
|