Strategy-branch guard, full-length round-robins, and session fixes

[isaac0804]

Completes the guard for strategy branches (agent or human), so a strategy/* pull request can't score better without playing better. CI runs tools/check_strategy_branch.py from main's copy, so a branch can't loosen it.

New checks (on top of the existing path allowlist):

• Opponents stay on main's code: a branch either adds new strategy modules or changes exactly one existing strategy, never both; never pickers.py; never deletes a strategy; kernel_strategy.py only gains imports from the added modules (in any order, so isort is fine). This gives the guarantee a pinned main checkout of the opponents would, without a second checkout.
• The candidate can't reach outside its module: no import-time effects or fingerprint hazards (environment, files, dynamic imports, module-level state), no imports of another strategy (relative ones included), no changing what it imports or an alias of it (SomeTactic.x = ..., t = SomeTactic; t.x = ..., module.TABLE.clear(), setattr/delattr), and no changing its own module-level classes or variables from inside a function (both teams share them).
• After Copilot's review: an added module's registry import may not rebind or rename an existing name (it could replace an opponent's factory); a type change (e.g. a strategy turned into a symlink) counts as changing a strategy; strategy/__init__.py is off limits.

Tried for real: strategy/zone-split-shape (#138) passes; a copy that rebinds tiki_taka's factory fails on both counts. Of today's 22 strategies only overload_flow fails the reach check: it keeps a global streak that both teams would share, so changing it on a strategy branch means moving that into the factory's closure. A static check, not a sandbox: the reviewer still reads the diff.

• The side the replay doesn't record skips acceleration estimation: about 4% less CPU per match, identical replay, intentions and score.

Also: match_cache.put writes a per-process temp file, so round-robins on several branches sharing replays/match_cache/ can't tear a record or fail a rename. STRATEGY_DEVELOPMENT.md's strategy-branch section states the new rules.

Tests: 30 checker tests (incl. a tmp git repo end to end), a cache regression test that fails without the fix; full suite 12455 passed.

New tactics (added on request): a strategy branch may add modules under tactics/ (reach-checked like strategy modules), but not change or delete an existing tactic, since the opponents run those. To improve a tactic, copy it into a new module and change the copy. Tests: 42 checker tests.

Session work (2026-10-04), each with a regression test that fails before its fix:

• Round-robins play full 600 s matches. 65 s matches were 55% draws, and 16 of 40 full matches changed result after 180 s. A full round-robin is now about 107 min on 15 workers, plugged in (the final run took 4.7 h). There is no half-time: a match is 600 s of continuous play with config_a on the right taking the only kickoff (comments corrected after Copilot's review).
• Pile-ups fixed in GiveAndGoTactic: the carrier with no receiver re-armed its 4 s hold every time its slot was reshuffled, freezing for 15–20 s while others crowded in; it now holds once per possession. Support runs also kept flipping between targets on either side; they now keep a target once reached.
• DecoyOverloadTactic lets go once the enemy has held the ball 1 s (it never released before, tripping the 10 s frozen watchdog). COMMITTED_FROZEN stalls now say who holds the ball.
• Free kicks can't be held forever. A defender clamped 0.48 m from the ball by the defense-area margin fouled every 2 s, and each foul restarted the 10 s clock, freezing three matches to full time. Only the first foul of each free kick resets it now (cards never remove a robot here, which is what stops repeat fouls in the rulebook).
• A ball over a goal line restarts in the corner. It used to be placed where it crossed and pushed 1 m off the box: a free kick 2 m in front of goal, against the rulebook's corner and goal kicks (§6.2.1–2). 521 such kicks gave 150 goals in the round-robin; without them split_shape's 11-point lead over counter_flow drops to 1. Corner kicks sit 0.5 m from both lines, goal kicks 1 m from the goal line (0.5 m, not 0.2 m, from the touch line, keeping the corner-loop margin).
• Robots clearing an opponent free kick go round the ball. Pushed straight out, a robot between the ball and the opponent box aimed inside the planner's box margin and stopped 0.48 m from the ball: a Defender Too Close foul on every such free kick. It now takes the nearest reachable point of the 0.8 m circle.
• GiveAndGoTactic keeps its memory when robots join or leave its slot (new opt-in, keeps_mem_on_robot_change; only GiveAndGo sets it). A/B on 15 matches with the wedge fix: frozen give-and-go carriers 79 → 50, repeat holds in one possession 3 → 0. The kernel wiped it on every robot-set change, so six pickers that shuffle robots with the overload duet re-armed the 4 s no-receiver hold every few seconds, up to the 10 s no_progress stop. Design doc §11 notes the exception.
• go_to_ball: removed the no-op "dribbler on the back" flip. The dribbler is on the front, so facing the ball was already right; behaviour unchanged, now pinned by a test.
• In the sim, a no_progress restart waits for robots to clear the ball. The runner forced FORCE_START on the STOP's first tick, with the ball teleported to where it already lay, so two robots locked on the ball never separated: no_progress fired every 10 s for up to 230 s (19% of matches in the 600 s round-robin had such a wedge). The state machine now advances once every robot is 0.5 m clear (about 1 s). Same 15 matches: no_progress stops 51 → 8, wedges 3 → 0, no stalls.
• ShadowAndMarkTactic markers stand goal-side of their opponent. The sign was reversed, so markers (in about ten strategies) stood on the far side, leaving the opponent a clear run at goal. A related chase (two markers targeting each other walk off the pitch) is listed under Known open bugs, not fixed.
• mirror_swap targets moved off the defense-area edge (the planner was never deadlocked; the spots were unreachable). fpp and trajsample pass all 19 benchmark scenarios; test_mirror_swap is no longer xfail.
• docs/strategies.md: standings from a full 600 s round-robin on this PR's final code (tournament_20261005_170958). split_shape still leads (19-1-1, 2.76 points per match) but its margin over second (high_press, 2.48) fell from 0.52 to 0.28. Against the run before the fixes: no_progress restarts 699 → 296, keep-out fouls 245 → 26, 10 stalled matches (was 9). Out-of-bounds restarts rose 2446 → 2938, not yet investigated.
• STRATEGY_DEVELOPMENT.md notes strategy branches can run in parallel worktrees.
• docs/signals.md: one catalog of every strategy signal (round-robin output and the offline metric_correlation.py ones), grouped by question (broken? creates chances? keeps the ball? defends? restarts?), each with its summary.json key, meaning, reference range from the final run and what an off value points to. Replaces the table in STRATEGY_DEVELOPMENT.md; AGENTS.md points to it.
• docs/signal_report.md: the main signals of the final round-robin in figures (tools/signal_report.py <run_dir> regenerates them): a strategy × signal heatmap, attack vs defense scatters, goals per shot by distance and open goal mouth, ball losses by kind, fouls and stalls, with notes on what stands out (e.g. overload_press was in 5 of the 10 stalled matches; three_slot kicks the ball out 20 times a match).
• Round-robins measure chances, both sides (analysis/chances.py, a CHANCES table and strategies[*].chances): shot distance, angle and open goal mouth; conversion; save rate and how open the shots faced were; open-play regains shot from within 10 s; seconds the enemy held the ball in a side's defensive third; free kicks shot from within 10 s; metres gained per completed pass. Fed from the replay pass the ball-loss breakdown already makes. On the final run, against points per match: regain to shot +0.88, danger conceded −0.76, free kick to shot +0.64 (rank correlation); conversion, save rate and pass progress near 0. Diagnostics, not objectives. The 231 cached records were refreshed so --reuse keeps them. After Copilot's review, a stoppage ends a possession spell, so a shot from a restart is no longer credited to the regain before it (regains fell slightly for 22 strategies; split_shape's regain to shot 27% → 28%; records refreshed again).
• The scenario bench reports the strategy signals of each start next to its outcome: shots, open-goal-weighted shots, regains to shot, entries, real losses, shots faced, open shots faced and danger seconds, with a paired delta and t per signal, overall and per family. On bank_v7 with passes aimed 10° off, the outcome gave t −2.84 while shots and open shots gave t −6.1 and entries −3.6; losses, danger and shots faced didn't move, which says where the change acts.
• README is a front page; docs get an index. The README (196 → ~100 lines) has a quick start, a "what are you working on?" table, the corrected layout and the PR rules; docs/README.md indexes every doc; setup, contributing and the full tools list moved to docs/setup_external.md, docs/contributing.md and docs/tools.md. docs/pipeline_method.md's text matches the current code (refiner names, referee sources, one tick); the diagram is unchanged.

2026-10-06:

• SwitchOfPlayTactic with one robot plays the ball instead of holding it. At its own corner free kicks overload_press's lone switch robot stood 0.13 m from the ball for 10 s until no_progress, with the overload slot committed and waiting: 2 of its stalls in the final run. It now shoots when a lane is open and otherwise carries the ball toward one. Both matches replayed with the fix: no stalls. Used by five strategies, so their cached matches rerun next time.

• scenario_bench.py --play: put a strategy into one start and watch it. Prints the outcome, signals and a timeline (referee, ball, nearest robot of each side, every tactic change); keeps the replay, match log and a picture (--render png|mp4) under replays/scenario_play/. About 12 s a start. For testing a change in a situation the round-robin rarely reaches; a trial of a new strategy on the bench found the A/B outcome too coarse and asked for exactly this.

• Starts are tagged by situation, --where finds them: third, lane, whose restart, who has the ball, robots near the ball (e.g. --where third=defensive ball=theirs: 64 starts in bank_v7). Tagging showed the id's candidate_kicking doesn't say who kicks off (30 of 77 such kickoffs are the opponent's); the restart tag reads it from the referee command.

• Hand-authored starts are played from the candidate's side. They were written with friendly on the left and never mirrored, so the candidate's keeper started in the goal it attacks. Fixed in code; bank_v7's stored copies are left so its results stay comparable.

• docs/pitch_zones.md: one set of names for the pitch (thirds, wings, centre, cells, the box, danger, entry) with a diagram, linked from the docs index and the AGENTS.md glossary.

• Replay sidecar ~100× smaller. The referee's stage clock stopped at 0 (and, after the change below, stands still in stoppages), but the writer predicted it counting down, so the "sparse" referee sidecar stored a full message on about half of all ticks: 979 MB for the final run. One match rewritten: 17783 stored → 163, 4.46 MB → 0.04 MB, every tick identical.

• The referee keeps match time by the rulebook. The clock counts playing time only (paused in STOP, HALT, kick-off and penalty preparation, ball placement); when a half's playing time is up, a 0 s half-time and a second half kicked off by the other team, then full time. Round-robins play the two halves to full time (sim-time cap 1200 s): a match is about 785 s of sim time instead of 600 s. At half-time the teams change ends: the referee fills blue_team_on_positive_half and swaps it, StrategyRunner follows it (from our referee or a real game controller), replays store the side per tick, and analyses and scenario_from_replay read it per frame. In the sim the robots are carried to their new half (as people do in the break), and a kick-off now waits for every robot to be in its own half (at most 10 s). This also fixes score_aware_counter_flow and score_aware_zone_flow, which were in their last-60-s mode from 240 s to the end of every round-robin match.

• Tactic fixes: three_slot gives the robot on the ball to its attack, not to press/mark, which cleared it blind out of the field (~24 a match); man_mark stands goal-side like ShadowAndMarkTactic, so two robots marking each other no longer walk off the pitch; a lone SwitchOfPlayTactic robot fetches the ball before playing it; an empty slot doesn't keep GiveAndGoTactic's memory. Blind full-power clearances in other strategies are recorded as a known weakness (a fixed 4.7 m/s kick rolls ~17 m).

• Strategy-branch guard: classmethods, wildcard imports, parameter defaults and the remaining in-place methods no longer get past the reach check (Copilot).

• Referee, replay and shared-tactic changes rerun every cached match on the next round-robin; standings in docs/strategies.md are from before these changes.

2026-10-09:

• docs/roadmap.md 10c: real-robot profiles and calibration plan. What exists (the vision-to-command roster, trusted ball sensors), what can differ per robot, what is agreed (correct in the controller, expose only the rest, tactics ask about abilities not IDs), and the calibration routine to write before measuring. Records that the kicker stays fixed power and that MAX_VEL=1 on real robots is a safety cap.

• The aimless kick rule (§6.2.3, Division B). A ball touched by a robot that then crosses the halfway line and the opponent's goal line outside the goal, touching no other robot, is now a free kick for the opponent from where it was kicked, not a goal kick in the opponent's corner. Blind clearances from our own half cost nothing before: in the final run 388 of 1377 goal kicks led within seconds to one at the other end. OutOfBoundsRule keeps where the ball was last touched in the current spell of play (last_touch.touching_team); a touch on the halfway line itself (a kick-off) is not aimless. out_of_bounds.aimless_kick, on in both profiles.

• Every goal kick is placed at the same spot (RefereeGeometry.goal_kick_position: 1 m from the goal line, 0.5 m from the touch line). A disallowed goal and a penalty out of time put it 0.2 m from the touch line.

• overload_flow counts its own possession streak. It was a module-level global, shared by two overload_flow teams in one process; it now lives in the picker's closure, and every existing strategy passes the strategy-branch reach check.

• round_robin.py comments say the teams change ends at half-time.

• A ball out of bounds is charged to the robot that last touched it, not to that team's robot nearest the line (a 17 m clearance usually left the kicker far away, so per-tactic out-of-bounds counts named the wrong tactic). docs/strategies.md explains the out-of-bounds rise (2446 → 2938) as the goal-kick ping-pong the aimless-kick rule now meets.

• Merged main (v2.0.3 release bump).

• The referee and overload_flow changes rerun every cached match; the full round-robin and the standings in docs/strategies.md are still pending.

Full suite: 12576 passed, 87 xfailed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SACGSprm9GiBueqKdxsy2j

2026-10-10:

• The test suite no longer leaks a spinning thread. referee_receiver_test mocked a network that returned None forever, so its receiver thread kept a core busy and memory growing for the rest of the session (WSL ran out of memory). It now delivers one packet and then blocks like a quiet socket.
• Evaluation tools renamed and trimmed (repo cleanup merged in): tools/tournament/ → tools/evaluation/, tournament_lib.py → match.py; the old full-match tournament script and the Elo tools are removed.
• Ten strategies retired. The bottom ten of the 2026-10-05 round-robin are left out of a round-robin or a ladder pool unless named (RETIRED in round_robin.py); their code stays. A full round-robin is now 66 matches instead of 231, about 30 min on 14 workers.
• --reuse records spot-check mismatches in summary.json (reuse.mismatches).
• Sim PvP refines each tick's vision once and mirrors it for the opponent, plus three refiner speed-ups: about 9% less time per match, every replay array, intention log, stats file and referee log byte-identical (checked on a pairing the change was not developed on).
• Half-time no longer crashes on a robot past a line. Carried to the mirrored spot, a robot in the run-off at x = −4.594 went to +4.594, outside the field, and the sim refused it: clear_danger vs decoy_and_overload crashed at half-time. It is now placed on the line.
• docs/strategies.md and docs/signal_report.md: the 2026-10-10 round-robin (tournament_20261010_090819, 12 strategies, 66 matches, no stalls, no reuse mismatches). split_shape won all 11; counter_flow second (2.09 points per match); clear_danger, fourth before, last.
• A determinism check (identical matches under different hash seeds and 14 concurrent copies) and a measurement that blind kick_upfield clearances leave the pitch 17% of the time, not usually; the open-bug note claiming otherwise is removed.
• Motion-planning benchmark: four crowd scenarios from real match situations (ball_scrum, recovery_run, wing_switch, kickoff_reset, the last from a real goal in the round-robin). In the round-robin a moving robot has 3+ robots within 1 m 40% of the time, mostly at the ball; mirror_swap stays as a stress test. Both planners fail kickoff_reset often (trajsample about half of 40 sampler seeds, fpp at the default seed): the next planner target. Trajectory-sampling planner work (Sumatra-style sampling and fallback) is on its own branches for a later PR.

Tests: full suite 12603 passed, 87 xfailed; each fix has a regression test that fails without it.

[Copilot]

Copilot review overview

🟡 Changes recommended

The checker still permits several direct ways to import, mutate, or replace opponent strategy behavior.

Review effort: Balanced
Findings: 4

Open (4)

• Restrict registry imports to the module's exact factory · New
• Detect mutations of module-owned class and object state · New
• Resolve relative imports before applying the strategy allowlist · New
• Track imported-object aliases before allowing state mutations · New

What changed in this PR

Strengthens strategy-branch isolation and prevents concurrent match-cache writes from sharing temporary files.

Changes:

• Adds opponent and strategy reach checks.
• Uses process-specific cache temporary files.
• Expands regression tests and documentation.

File	Description
.github/​workflows/​ci.yml	Clarifies strategy-branch CI enforcement.
docs/​STRATEGY_DEVELOPMENT.md	Documents new isolation rules.
tools/​check_strategy_branch.py	Implements AST-based branch checks.
utama_core/​replay/​match_cache.py	Adds PID-specific temporary files.
utama_core/​tests/​engine/​test_check_strategy_branch.py	Tests branch restrictions.
utama_core/​tests/​replay/​test_match_cache.py	Tests distinct process temporary files.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

The strategy checker still permits registry aliasing, relative imports, shared-state mutation, and symlink-based opponent changes.

Review effort: Balanced
Findings: 5

Open (5)

• Treat symlink type changes as modified strategy files · New
• Track imported-object aliases before allowing state mutations
• Resolve relative imports before applying the strategy allowlist
• Detect mutations of module-owned class and object state
• Restrict registry imports to the module's exact factory

[Copilot]

Copilot review overview

🟡 Changes recommended

The checker still permits several paths that can alter or replace opponent strategy code.

Review effort: Balanced
Findings: 6

Open (6)

• Reject modifications to the shared strategy package initializer · New
• Treat symlink type changes as modified strategy files
• Track imported-object aliases before allowing state mutations
• Resolve relative imports before applying the strategy allowlist
• Detect mutations of module-owned class and object state
• Restrict registry imports to the module's exact factory

[Copilot]

Copilot review overview

🔵 Needs a closer look

The strategy checker still permits registry shadowing and several bypasses that can affect opponent code.

Review effort: Balanced
Findings: 6

Open (6)

• Reject modifications to the shared strategy package initializer
• Treat symlink type changes as modified strategy files
• Track imported-object aliases before allowing state mutations
• Resolve relative imports before applying the strategy allowlist
• Detect mutations of module-owned class and object state
• Restrict registry imports to the module's exact factory

[Copilot]

Copilot review overview

🟡 Changes recommended

The checker has opponent-isolation bypasses, and the 600-second fixture does not implement the claimed two-half match.

Review effort: Balanced
Findings: 8 · 1 · 1

Open (10)

• Detect mutations through imported shared-state bindings · New
• Implement halftime orchestration for full-match duration · New
• Reject modifications to the shared strategy package initializer
• Treat symlink type changes as modified strategy files
• Track imported-object aliases before allowing state mutations
• Resolve relative imports before applying the strategy allowlist
• Detect mutations of module-owned class and object state
• Restrict registry imports to the module's exact factory
• Separate tactic and evaluation changes from guard/cache work · New
• Update documentation for the new tournament duration · New

[Copilot]

Copilot review overview

🔵 Needs a closer look

The strategy guard has multiple bypasses, and the 600-second tournament remains one extended first half rather than two halves.

Review effort: Balanced
Findings: 8 · 1 · 1

Open (10)

• Implement halftime orchestration for full-match duration
• Detect mutations through imported shared-state bindings
• Reject modifications to the shared strategy package initializer
• Treat symlink type changes as modified strategy files
• Track imported-object aliases before allowing state mutations
• Resolve relative imports before applying the strategy allowlist
• Detect mutations of module-owned class and object state
• Restrict registry imports to the module's exact factory
• Separate tactic and evaluation changes from guard/cache work
• Update documentation for the new tournament duration