[isaac0804]

Sim realism measured against real Division B matches, a strategy evaluation system that decides on goals, regression moments, planner and referee fixes, and a set of on-pitch pictures with docs built around them.

Release notes

Strategy evaluation

• tools/evaluation/evaluate.py: is a candidate stronger than the champion of a fixed reference pool (pools/pool_v1.json)? It plays rounds under seeded sim noise, decides on paired goal differences and stops once the answer is clear. Every match goes into a ledger (replays/eval/ledger.jsonl), with ratings over all of it. Goals only: shots, xG and the other signals were tested as rankers and rejected.
• --explain draws candidate-vs-champion pictures before the replays are removed: positions with and without the ball, shots and fouls, plus summary.json and a triage of the candidate's two worst matches.
• Fingerprints ignore comments, docstrings and formatting, so cached matches survive cosmetic edits.
• The scenario bench and the ladder are retired.

Seeing the game

• docs/visual_guide.md: the game drawn on the pitch from real replays, with what each picture has shown us and the command that draws it. It names and shows the position maps and shot maps of every strategy.
• New picture tools:
  • tools/pitch_maps.py: position, shot and foul maps per strategy.
  • tools/match_timeline.py: one match window as swimlanes (referee, each robot's tactic, possession, distance to the ball).
  • tools/restart_picture.py: where the referee override sends each robot at a restart.
  • tools/plan_snapshot.py and tools/plan_trace.py: the fast-path planner's decision on one tick, and over a window.
  • tools/motion_planning_benchmark.py --figures: trajectories and a summary per scenario.
  • tools/package_graph.py and docs/architecture.md: the package dependency graph, with the replay/analysis import rule checked.
• tools/triage.py RUN_DIR: start here when a strategy plays badly. It takes each strategy's worst matches, collects every flagged problem and pictures the worst. Output: index.md, findings.jsonl and pictures.
• --findings on the picture tools: one shared JSON format (utama_core/analysis/findings.py), so agents can filter problems without reading images.
• Architecture pictures drawn in one style (docs/img/diagram_style.py) instead of Mermaid: one tick of StrategyRunner (in the README), the match data flow, the tactic-kernel model, the referee and its state machine, one rsim tick, the planner control schemes and the real robot path. Each comes from a make_*.py script, and a test checks every class and path a picture names still exists.
• docs/signal_report.md was redrawn as figures that explain results instead of rank colours.

Sim realism

• A realism scorecard against real 2025–26 Division B matches (utama_core/analysis/realism), covering ball deceleration, robot motion, dropouts, shots and xG.
• Real logs can be kept raw: convert_ssl_log --keep-raw, with resume and memory caps.
• SimNoise: seeded per-robot latency, kick speed and direction noise, vision noise, and physics knobs (off by default).
• pixi now builds rc-robosim from our fork in vendor/rSim.
• Plan and results: docs/sim_realism.md.

Regression moments and debugging

• Regression moments: replayed or hand-made field states with a fixed check (tools/moments.py, utama_core/tests/moments/), run in pixi run test.
• replay_trace --events/--json, repro_from_replay --summary, moments fouls --by/--json, and tools/setup_worktree.sh for parallel agents.
• docs/STRATEGY_DEVELOPMENT.md, "Debugging a foul or failure": the workflow, and the bugs it has found.

Fixes

• Planner: a robot inside the ball's keep-out is pushed past the edge (to 0.85 m) instead of parking on it; a robot pressed against another may drive straight away.
• Referee:
  • a free kick is taken once the ball moves 0.05 m;
  • push-out targets in a corner stay on the pitch;
  • our ball placer routes round the ball.
• The rolling-ball receive point is clamped to the field.
• carry_exhausted counts reaction time before braking.

Repo hygiene

• Unused helpers, scenario banks v5/v6 and a duplicate GUI demo removed.
• strategy_runner split into modules.
• README cleaned up, and a new drawn one-tick pipeline picture (docs/img/pipeline/one_tick.png, from make_one_tick.py) replaces the outdated 2025 drawio one in the README and pipeline_method.md; the Mermaid version moved to docs/architecture.md.
• Pre-commit ruff bumped to v0.15.12.

Known, not fixed here

• Tactic flip-backs: most strategies that split attack and defence on possession take a tactic for under 1 s and revert about 5 times per live minute, and press_and_pass 13. The tactic_thrash finding flags it.
• Restart clearing stops short: the step that clears robots out of the keep-out at a restart stops 1 cm short, leaving them at 0.79 m (keep_out_short).
• Unexplained lines: the vertical GiveAndGoTactic lines in the position maps.
• Restart findings are slow: about 45 s per match, so triage scans restarts only with --restarts.

Testing

• pixi run test: 12857 passed, 85 xfailed.
• pixi run lint clean.
• No round-robin was rerun for this last batch: the picture and triage tools only read replays.