Skip to content

fix(chess_env): let the opponent move first when a custom FEN gives it the move - #1695

Open
Aafimalek wants to merge 1 commit into
openenv:mainfrom
Aafimalek:fix/chess-fen-side-to-move
Open

Aafimalek wants to merge 1 commit into
openenv:mainfrom
Aafimalek:fix/chess-fen-side-to-move

Conversation

@Aafimalek

@Aafimalek Aafimalek commented Nov 22, 2026 •

Copy link
Copy Markdown
Contributor

Summary

ChessEnvironment.reset() decides whether the opponent moves first from the agent's color alone (self._agent_color == chess.BLACK), not from whose turn it is on the board. With a custom fen where the other side is to move, the agent ends up playing the opponent's pieces, and the reward is computed for the wrong side:

  • opponent="random", agent_color="white", reset(fen=<black to move>): no opponent move is made, the agent is asked to move for Black, and if it delivers mate (d8h4 in the test position) the step returns reward=-1.0, a loss.
  • agent_color="black" with the same FEN: the opponent plays Black's move (c7c5), and the agent then moves for White.

The opponent now moves first whenever self._board.turn != self._agent_color. On the standard starting board this is the same as before, since White is to move.

The README's agent_color=None row said "alternate each episode", but the code picks at random from reset(seed=...)'s RNG. The row now says that, and a sentence explains who moves first with a custom FEN.

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation
  • New environment
  • Refactoring

Alignment Checklist

Before submitting, verify:

  • I have read .claude/docs/PRINCIPLES.md and this PR aligns with our principles
  • I have checked .claude/docs/INVARIANTS.md and no invariants are violated
  • I have run /pre-submit-pr (or bash .claude/hooks/lint.sh and tests) and addressed all issues

RFC Status

  • Not required (bug fix, docs, minor refactoring)
  • RFC exists: #___
  • RFC needed (will create before merge)

Test Plan

  • New tests in TestChessEnvironmentWithOpponent:
    • test_agent_moves_for_its_own_color_after_reset: for both agent colors, on the starting board and on a black-to-move FEN, the side to move after reset() is the agent's.
    • test_agent_mate_from_a_black_to_move_fen_is_a_win: the agent playing Black mates from the black-to-move FEN and gets reward=1.0.
  • With chess_environment.py from main, the two black-to-move cases and the mate test fail (3 tests); with this branch all pass.
  • PYTHONPATH=src:envs python -m pytest tests/envs/test_chess_environment.py tests/envs/test_chess_rubric_migration.py: 47 passed (Linux, Python 3.12).
  • bash .claude/hooks/lint.sh, usort/ruff format on the changed files, and python scripts/sync_env_docs.py --check pass.
  • Not run: the full test suite, since the change touches only chess_env and its tests.

#1693 also touches chess_environment.py (in step(), not reset()), so the two don't overlap.

Claude Code Review

Alignment review by Opus 5.5, in the format of .claude/skills/alignment-review/SKILL.md.

Automated Checks

  • Lint: PASS, bash .claude/hooks/lint.sh
  • Debug code: CLEAN. The diff adds no print, breakpoint or TODO lines.

Open RFCs Context

No open RFC covers chess_env.

Tier 1: Fixes Required

None.

Tier 2: Alignment Discussion

Principle Conflicts

None identified. The reset signature is unchanged and rewards stay inside the environment.

RFC Conflicts

None identified.

Summary

  • 0 mechanical issues to fix
  • 0 alignment points for human review
  • 0 RFC conflicts to discuss

Note

Low Risk
Localized bug fix in chess env reset/turn handling with added regression tests; behavior on the standard starting position is unchanged.

Overview
Fixes ChessEnvironment.reset() so the opponent plays first whenever the board’s side to move is not the agent’s color, not only when agent_color="black" on the standard start position. Custom reset(fen=...) positions where the agent’s opponent is to move no longer let the agent move the wrong color or assign win/loss rewards incorrectly.

Docs now describe agent_color=None as random per episode (reproducible with reset(seed=...)) and note when the opponent moves first with a configured opponent. New tests cover side-to-move after reset for both colors on the start and a black-to-move FEN, and that mating from that FEN as Black yields reward=1.0.

Reviewed by Cursor Bugbot for commit 0edb14a. Bugbot is set up for automated code reviews on this repo. Configure here.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant