Merge branch 'main' into john/scml-ladder

# Conflicts:
#	codeclash/cli/ladder.py
#	configs/ablations/ladder/corewar__gemini_3_5_flash.yaml
#	configs/ablations/ladder/corewar__gpt_5_5.yaml
#	configs/ablations/ladder/corewar__opus_4_7.yaml
#	configs/ablations/ladder/corewar__opus_4_8.yaml
#	configs/ablations/ladder/corewar__sonnet_5.yaml
#	configs/ablations/ladder/robotrumble__gemini_3_5_flash.yaml
#	configs/ablations/ladder/robotrumble__gpt_5_5.yaml
#	configs/ablations/ladder/robotrumble__opus_4_7.yaml
#	configs/ablations/ladder/robotrumble__opus_4_8.yaml
#	configs/ablations/ladder/robotrumble__sonnet_5.yaml
#	configs/ladder/README.md
#	configs/ladder/battlesnake.yaml
#	configs/ladder/battlesnake__gemini_3_5_flash.yaml
#	configs/ladder/battlesnake__gpt_5_5.yaml
#	configs/ladder/battlesnake__opus_4_7.yaml
#	configs/ladder/battlesnake__opus_4_8.yaml
#	configs/ladder/battlesnake__sonnet_5.yaml
#	configs/ladder/battlesnake_llama_smoke.yaml
#	configs/ladder/corewar.yaml
#	configs/ladder/make_scml.yaml
#	configs/ladder/robotrumble.yaml

Author: john-b-yang

.claude/skills/create-arena-ladder/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: create-arena-ladder
+description: >-
+  Build a CC:Ladder for any CodeClash arena: import human-written solutions as git
+  branches, rank them via round-robin PvP + Elo, and assemble the ladder configs.
+  Use when asked to "create a ladder", "import human solutions", "push human bots as
+  branches", or "make a CC:<arena> ladder" for arenas like BattleSnake, RobotRumble,
+  CoreWar, Gomoku, RoboCode, SCML, etc.
+---
+
+# Create an Arena Ladder (CC:Ladder)
+
+A **ladder** turns a curated set of human-written bots into a ranked gauntlet, then
+measures how far up a model can climb. Two phases: **make the ladder** (rank the humans
+via round-robin), then **run the ladder** (a model climbs rung by rung until it loses).
+
+This skill produces, for arena `<A>`: `human/<author>/<name>` branches on `CodeClash-ai/<A>`,
+a `make_<a>.yaml` (round-robin), a ranked `rungs/<a>.yaml`, and a run config `<a>.yaml`.
+
+Work in the `repo/` clone. Reference implementations to mirror:
+`configs/ablations/ladder/{make_battlesnake,battlesnake,rungs/battlesnake}.yaml` and its
+`README.md`. For worked examples of the import step, the `john/*-ladder` branches show two
+shapes end-to-end (gomoku = function-port, robocode = copy-in).
+
+---
+
+## Mechanics you must respect (arena-agnostic)
+
+- **Where human code lives:** each arena has its **own** repo under `CodeClash-ai`
+  (hardcoded `GH_ORG` in `codeclash/constants.py`). The arena Dockerfile `git clone`s it
+  into `/workspace`. Human bots are **branches of that per-arena repo**, NOT of this
+  monorepo — so `git branch -a` here shows no `human/*`.
+- **How a branch becomes a player:** a player with `branch_init: human/foo/bar` makes
+  `Player.__init__` (`codeclash/agents/player.py`) run `git fetch && git checkout` in the
+  clone; that branch's files overlay `/workspace`. `agent: dummy` = static opponent.
+  `push: True` (the climbing player) needs `GITHUB_TOKEN`.
+- **What a branch must contain:** the arena's **submission file(s)** at the path its
+  `validate_code` expects; everything else (engine, assets) comes from the base clone.
+  **The single source of truth is `codeclash/arenas/<a>/<a>.py` — read its `submission`
+  attribute and `validate_code` method.** Those two define the contract. Examples:
+  BattleSnake → `main.py` HTTP server (`info/start/end/move`); Gomoku → `main.py` with
+  `get_move(board,color)`; SCML → agent with `decide(observation)`; RoboCode → Java class
+  under `robots/custom/`; CoreWar → `warrior.red`.
+
+---
+
+## Phase 0 — Prerequisites
+
+- Arena class `codeclash/arenas/<a>/<a>.py` exists; record its `submission` path + exact
+  `validate_code` requirements.
+- Arena repo `github.com/CodeClash-ai/<A>` exists and its Dockerfile clones it.
+- Docker running; `GITHUB_TOKEN` set (public repos → `gh auth token` works for push + run).
+
+## Phase 1 — Source many human solutions
+
+The hard part is finding a large set. Best sources: official leaderboards and
+`awesome-<arena>` repos (BattleSnake used `awesome-battlesnake`; RobotRumble crawled
+`robotrumble.org/boards/2`; RoboCode drew from RoboWiki/GitHub). Capture author + bot name
+per candidate → these become the branch slugs. Keep a provenance record (source URL,
+author, license) as you go — a table plus a header comment in each imported file.
+
+## Phase 2 — Adapt each solution to the arena's contract
+
+Every bot must end up matching the one submission contract. Do NOT discard a bot merely for
+being in another language — pick the cheapest import shape:
+
+- **Copy-in** — source is already in the arena's language/framework: drop the files in and
+  rename/repackage (e.g. RoboCode: main class → `MyTank`, `package custom;`). Mechanical.
+- **Function-contract port** — reimplement the core "given state, choose a move" logic as
+  the arena's single entry function (Gomoku `get_move`, SCML `decide`, BattleSnake `move`).
+  Ignore the source's GUI/protocol/CLI wrapper; keep its evaluation + search faithful.
+
+Porting hard rules (adapt per arena; worth writing up as a guide for any porting agents):
+- **Runtime-only deps** — match the arena image (often stdlib-only Python 3.10; re-express
+  array math in pure Python). No trained weights / NN unless you can obtain the binary.
+- **One entry point, never raise** — a crash or illegal move = a forfeit; wrap the body and
+  fall back to a safe legal move.
+- **Fast enough** — a round-robin plays many games; cap search depth / rollouts.
+- Only skip a bot if it truly can't run. **Log every skip with a reason — never silently
+  drop bots.**
+
+## Phase 3 — Validate (two-stage), then push
+
+Local validation is necessary but NOT sufficient — a local shim skips Docker, the repo's
+`server.py`, and real payloads. Gate every bot in two stages before it earns a branch:
+
+1. **Stage 1 (local):** syntax/import + the arena's `validate_code` legality check. Cheap;
+   catches most breakage without Docker. Fix or drop failures.
+2. **Stage 2 (arena, REQUIRED):** play each stage-1 pass through the real arena image and
+   confirm it completes a full game without erroring. This is the step that actually gates.
+   Requires Docker. (Scripting both stages over a folder of candidates is worth it at scale.)
+3. **Push** each stage-2-healthy bot as `human/<author>/<name>` (dedupe identical content).
+   Use consistent kebab/lowercase slugs; branches must be pushed before any arena run, since
+   `branch_init` fetches from the remote.
+
+## Phase 4 — Make the ladder (round-robin + Elo)
+
+1. Write `configs/ablations/ladder/make_<a>.yaml` (mirror `make_battlesnake.yaml`):
+   `tournament.rounds: 0`, a `game` block, and `players:` = every `human/*` branch as
+   `{agent: dummy, branch_init: ...}`.
+2. Pre-build the image **once** to avoid a build stampede under many workers:
+   `docker build -t codeclash/<a> -f codeclash/arenas/<a>/<A>.Dockerfile .`
+3. Run all-pairs PvP (resumable — skips pairs already logged; `--workers ≈ cores-2`):
+   `GITHUB_TOKEN=$(gh auth token) uv run codeclash ladder make configs/ablations/ladder/make_<a>.yaml --workers N`
+   → logs land under `logs/ladder/<A>/`. Fast arenas run on a laptop; big ones (e.g. SCML's
+   ~1275 pairs) want an AWS box under `tmux`/`nohup`.
+4. Rank: `python -m codeclash.analysis.metrics.elo -d logs/ladder/<A> --output-dir assets/<a>_elo`
+   → prints the Bradley-Terry/Elo order (weakest → strongest); that ordering IS the ladder.
+   Tip: run a cheap low-`sims` pilot first and eyeball that baselines sit near the bottom.
+
+## Phase 5 — Assemble the ranked configs
+
+1. `configs/ablations/ladder/rungs/<a>.yaml` — the ranked opponents, **weakest first,
+   strongest last** (each `{agent: dummy, branch_init: human/...}`), in Elo order.
+2. `configs/ablations/ladder/<a>.yaml` — the climber `player` (starting at the weakest
+   rung, `push: True`) + `ladder: !include ablations/ladder/rungs/<a>.yaml` + a
+   `ladder_rules` block. Model on `battlesnake.yaml`.
+3. Optional `<a>__<model>.yaml` per-model variants (swap `model: !include mini/models/...`);
+   they share the same `rungs/<a>.yaml` include.
+
+`ladder_rules` (optional; defaults reproduce historical behavior):
+```yaml
+ladder_rules:
+  min_round_win_fraction: 0.5   # must win strictly more than this fraction of rounds
+  win_last_k: 1                 # ...and must win the last K rounds
+```
+
+## Phase 6 — Run the ladder
+
+`uv run codeclash ladder run configs/ablations/ladder/<a>.yaml`
+→ prints the highest rung reached; logs under `LOCAL_LOG_DIR/<user>/LadderTournament.*`.
+
+---
+
+## Deliverables checklist
+- [ ] N validated `human/<author>/<name>` branches pushed to `CodeClash-ai/<A>`.
+- [ ] **Stage-2 arena smoke passed** (each bot plays a real game in Docker), skips logged.
+- [ ] `make_<a>.yaml` + round-robin run + Elo ranking (`assets/<a>_elo`).
+- [ ] `rungs/<a>.yaml` (weakest→strongest) + `<a>.yaml` (climber + `ladder_rules`).
+- [ ] `ladder run` executes end-to-end against a sample model.
+- [ ] Provenance recorded (source/author/license per bot); note in `ladder/README.md` if
+      the arena is new.
+
+## Gotchas
+- Human branches go to the **per-arena** repo, not the monorepo; `branch_init` fetches from
+  the remote, so **push before any run** and keep Docker up.
+- A bot that fails `validate_code` silently forfeits. A local shim can pass yet fail in the
+  arena — the **stage-2 Docker smoke** is the real gate, not stage 1.
+- Pre-build the arena image once before a `--workers N` run, or workers stampede the build.
+- Port aggressively into the single submission contract; skip only un-runnable bots, and
+  log every skip. A port must reproduce the original's behavior.

README.md

@@ -73,7 +73,7 @@ codeclash run configs/test/battlesnake.yaml
 Once this works, you should be set up to run a real tournament!
 To run *Claude Sonnet 4.5* against *o3* in a *BattleSnake* tournament with *5 rounds* and *1000 competition simulations* per round, run:
 ```bash
-uv run codeclash run configs/examples/BattleSnake__claude-sonnet-4-5-20250929__o3__r5__s1000.yaml
+uv run codeclash run configs/pvp/BattleSnake__claude-sonnet-4-5-20250929__o3__r15__s1000.yaml
 ```
 
 ## ⚔️ How It Works

codeclash/agents/mini_anthropic_model.py

@@ -11,7 +11,7 @@
 `model_class: codeclash.agents.mini_anthropic_model.AnthropicModel` and provide the API key,
 base URL, and model name (see the `*_env` config fields, which keep endpoint-specific values in
 the environment rather than in committed configs). Requires the optional `anthropic` dependency
-(`uv pip install -e '.[llama]'`). See configs/ablations/ladder/robotrumble_llama.yaml.
+(`uv pip install -e '.[llama]'`). See configs/ladder/robotrumble_llama.yaml.
 """
 
 import json

codeclash/agents/utils.py

@@ -26,6 +26,7 @@ class GameContext(BaseModel):
     round: int
     rounds: int
     working_dir: str
+    arena_description: str = ""
 
     def _render_prompt_templates(self) -> dict:
         context = self.model_dump()

codeclash/analysis/code_evolve/main.py

@@ -18,7 +18,7 @@
 from codeclash.arenas import ARENAS
 from codeclash.constants import LOCAL_LOG_DIR
 
-MODELS_PATH = Path("configs/models.yaml")
+MODELS_PATH = Path("configs/mini/model_roster.yaml")
 TARGET_ROUNDS = [1, 15, 5, 10]
 
 

codeclash/arenas/battlesnake/battlesnake.py

@@ -203,4 +203,9 @@ def validate_code(self, agent: Player) -> tuple[bool, str | None]:
                 error_msg.append(f"There should be a `{func}` function implemented in `{self.submission}`")
         if len(error_msg) > 0:
             return False, "\n".join(error_msg + ["Don't change the function signatures!"])
+        if "__main__" not in bot_content:
+            return False, (
+                f'`{self.submission}` must keep its `if __name__ == "__main__"` block that starts '
+                "the server, or the bot fails to launch."
+            )
         return True, None

codeclash/cli/ladder.py

@@ -46,9 +46,7 @@ def _resolve_ladder_rules(ladder_rules: dict, rounds: int) -> tuple[int, int]:
         typer.echo(f"ladder_rules.min_round_wins must be an integer, got {min_round_wins!r}.")
         raise typer.Exit(1)
     if not 1 <= min_round_wins <= rounds:
-        typer.echo(
-            f"ladder_rules.min_round_wins must be in [1, {rounds}] (tournament.rounds), got {min_round_wins}."
-        )
+        typer.echo(f"ladder_rules.min_round_wins must be in [1, {rounds}] (tournament.rounds), got {min_round_wins}.")
         raise typer.Exit(1)
 
     # win_last_k: number of trailing rounds the player must win (1 == just the final round, 0 == disabled).
@@ -87,7 +85,7 @@ def make(
 ):
     """Build a ladder: run PvP tournaments across all pairs of players (for ranking).
 
-    [dim]• codeclash ladder make configs/ablations/ladder/make_battlesnake.yaml[/dim]
+    [dim]• codeclash ladder make configs/ladder/make_battlesnake.yaml[/dim]
     """
     yaml_content = config_path.read_text()
     preprocessed_yaml = resolve_includes(yaml_content, base_dir=CONFIG_DIR)

codeclash/tournaments/pvp.py

@@ -79,6 +79,7 @@ def get_agent(self, agent_config: dict, prompts: dict) -> Player:
             round=1,
             rounds=self.rounds,
             working_dir=str(DIR_WORK),
+            arena_description=self.game.description,
         )
 
         return get_agent(agent_config, game_context, environment)

codeclash/utils/generate_confs.py

@@ -3,14 +3,14 @@
 
 Each configuration file specifies a tournament between two models in a given arena,
 including the number of rounds and simulations per round. The configurations are saved
-as YAML files in the specified output directory (default: configs/main/).
+as YAML files in the specified output directory (default: configs/pvp/).
 
 Also generates a tracking JSON file at configs/tracker.json to keep track of
 the number of tournaments and rounds played for each pair of models in each arena.
 
 Usage:
 
-python codeclash/utils/generate_confs.py -m configs/models.yaml -r 15 -s 1000
+python codeclash/utils/generate_confs.py -m configs/mini/model_roster.yaml -r 15 -s 1000
 """
 
 import argparse
@@ -184,7 +184,7 @@ def main(models, arenas, rounds: int, simulations: int, record_ratio: float, out
         "-m",
         "--models",
         type=str,
-        default="configs/models.yaml",
+        default="configs/mini/model_roster.yaml",
         help="Path to model configurations.",
     )
     parser.add_argument(
@@ -218,7 +218,7 @@ def main(models, arenas, rounds: int, simulations: int, record_ratio: float, out
         "-o",
         "--output",
         type=Path,
-        default=Path("configs/main/"),
+        default=Path("configs/pvp/"),
         help="Output directory for configuration files (default: main/).",
     )
     args = parser.parse_args()

codeclash/viewer/static/js/picker.js

@@ -503,7 +503,7 @@ async function fillTextareaWithAWSSubmitCommands() {
     // Format output as AWS submit commands
     const commands = successfulResults.map(
       (result) =>
-        `aws/run_job.py -- aws/docker_and_sync.sh codeclash run configs/main/${result.config_name}`,
+        `aws/run_job.py -- aws/docker_and_sync.sh codeclash run configs/pvp/${result.config_name}`,
     );
     textarea.value = commands.join("\n");