clay-borg/README.md

# clay-borg

A rebuild from scratch simulation and games engine framework set up to assimilate and optimize techniques and implementations useful for games, simulations, robotics.

Licensed under the Target Revenue Source License (TRSL V1C1) — see [LICENSE](LICENSE); canonical text lives in the org's `target-revenue` repository.

## Picking the work back up

**[`HANDOFF.md`](HANDOFF.md)** — written by hand at the end of each
working session, unlike the generated `.custodian-brief.md`. It records
what is true, what is only *reported*, and what would be a mistake to
assume. Read it before `make design`.

## Running the gates

```sh
make all                      # every gate, from a clean shell
make -C /path/to/clay-borg all   # …or from any other directory
```

**There is no environment setup step.** No `cd`, no `export PATH`, no
activation script. `make` locates the repo from its own path and `cargo`
from the standard rustup locations; the Python tools do the same via
`tools/repo.py`. The only prerequisites are a rustup toolchain and Python
3.11+.

This is deliberate and enforced: `make env-test` runs every tool from `/`
with a PATH containing no cargo, and `make all` includes it. CB-RES-0003
measured 84 agent turns and $15.33 spent prefixing commands with `cd` and
`export PATH` before that friction was fixed at the root (CB-WP-0004 T01).

Other useful targets: `make cost` (spend per task), `make cost-budget`
(spend since the last commit), `make cost-mix` (mechanical vs judgment
turns), `make loop-lint` (executable InnerLoop rules), `make self-tests`
(every tool's positive control).

## GROUND

The first product vertical is a virtual tabletop implementation of **GROUND — A Game of Bonds and Rivalry: DARVO Edition**. The boardgame itself (rules, editions, content) is at home in the sister repository **`ground-game`** — that repo is authoritative for what GROUND *is*; clay-borg implements the engine that runs it.
Initial commit 2026-07-30 21:18:53 +00:00			`# clay-borg`

Adopt TRSL V1C1 license; link ground-game and target-revenue sister repos 2026-07-31 00:25:30 +02:00			`A rebuild from scratch simulation and games engine framework set up to assimilate and optimize techniques and implementations useful for games, simulations, robotics.`

			Licensed under the Target Revenue Source License (TRSL V1C1) — see [LICENSE](LICENSE); canonical text lives in the org's `target-revenue` repository.

HANDOFF.md: what a generated brief cannot say Every workplan is done and nothing is in flight -- the session stopped at a boundary, not mid-change -- so the risk on pick-up is not lost context but MISREAD context. Records the three findings most likely to be misread (attack_relief is unreachable-then-real, not null; H1's rejection covers half of H1; the scope module is inert in round one), what is waiting on ground-game versus what is ours, the conventions a new session trips over (hub is a read model; workplan status is active not in_progress; make vendor; replays/ is gitignored), and the two habits that paid for themselves repeatedly -- mutate every control, and test the path a player takes. Linked from the README above the gates, since it should be read before design — the finding register QUEUE (open findings) repro F17 degenerate raised 6d ground-game repro F18 inert raised 6d clay-borg repro F24 inert raised 5d clay-borg repro F25 inert raised 4d clay-borg repro F26 inert ruled 4d ground-game repro F27 unplayed reported 4d clay-borg repro F31 unplayed reported 4d clay-borg repro F30 degenerate ruled 4d ground-game NOTES (not reportable — GameDesign §3.1) F12 degenerate 11d F15 underdetermined 7d F21 degenerate 6d findings 28 (+3 note(s)) with a resolving reproduction 19/28 = 67% target 100% open, lacking a reproduction 0 target 0 reproductions green while open 0 target 0 notes past 30 days 0 target 0 closed (log) 20 [U1, U2, U3, U4, U5, U6, U7, U8, U9, U10, F11, F13, F14, F16, F19, F20, F23, F22, F29, F28]. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> 2026-08-12 00:00:50 +02:00			`## Picking the work back up`

			[`HANDOFF.md`](HANDOFF.md) — written by hand at the end of each
			working session, unlike the generated `.custodian-brief.md`. It records
			`what is true, what is only reported, and what would be a mistake to`
			assume. Read it before `make design`.

CB-WP-0004 T01: fix environment friction at the root CB-RES-0003 measured 84 turns and $15.33 — the largest mechanical category — spent prefixing commands with `cd` and `export PATH="$HOME/.cargo/bin:$PATH"`. Both causes are now fixed once instead of per-leaf. tools/repo.py resolves the repo root from __file__ and cargo from PATH then the standard rustup locations. Every tool imports ROOT from it, so the repo path is stated once rather than redefined in four files — single source of fact, the rule DFD earned in InnerLoop v1.2. rule-coverage and dep-weight now call enter_root(), which is why their relative paths did not need rewriting one by one. The Makefile derives REPO from MAKEFILE_LIST and resolves CARGO the same way, so `make -C <repo> <target>` works from any directory with no prefix. make env-test is the positive control, and is in `make all`: every tool runs from / with PATH=/usr/bin:/bin. Without it this fix could regress silently and invalidate T05's measurement — the whole point of the control loop. dep-weight's "cargo not on PATH" error is kept rather than deleted. It should now be unreachable, and --self-test asserts cargo_bin() resolves unaided; a control that never fires is cheaper than a regression. loop-lint failed on repo.py on its first run — a reporting tool with a positive control but no --self-test entry point. Second time the gate has caught work from its own pass within the hour. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> 2026-07-31 10:13:52 +02:00			`## Running the gates`

			```sh
			`make all # every gate, from a clean shell`
			`make -C /path/to/clay-borg all # …or from any other directory`
			```

			There is no environment setup step. No `cd`, no `export PATH`, no
			activation script. `make` locates the repo from its own path and `cargo`
			`from the standard rustup locations; the Python tools do the same via`
			`tools/repo.py`. The only prerequisites are a rustup toolchain and Python
			`3.11+.`

			This is deliberate and enforced: `make env-test` runs every tool from `/`
			with a PATH containing no cargo, and `make all` includes it. CB-RES-0003
			measured 84 agent turns and $15.33 spent prefixing commands with `cd` and
			`export PATH` before that friction was fixed at the root (CB-WP-0004 T01).

			Other useful targets: `make cost` (spend per task), `make cost-budget`
			(spend since the last commit), `make cost-mix` (mechanical vs judgment
			turns), `make loop-lint` (executable InnerLoop rules), `make self-tests`
			`(every tool's positive control).`

			`## GROUND`

Adopt TRSL V1C1 license; link ground-game and target-revenue sister repos 2026-07-31 00:25:30 +02:00			The first product vertical is a virtual tabletop implementation of GROUND — A Game of Bonds and Rivalry: DARVO Edition. The boardgame itself (rules, editions, content) is at home in the sister repository `ground-game` — that repo is authoritative for what GROUND is; clay-borg implements the engine that runs it.