pgn2 1.5.0 → 2.0.1

data/docs/superpowers/plans/2026-08-15-small-medium-roadmap-plan.md

@@ -0,0 +1,384 @@
+# Small + Medium TODO Roadmap Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Clear the small and medium TODO items left in `TODO.md`, leaning on the chessie-backed `PGN::Bitboard::Engine` where it removes pure-Ruby rewrite work.
+
+**Status (2026-08-15):** All ten tasks implemented on branch `feat/small-medium-roadmap` (worktree `.worktrees/feat-small-medium-roadmap`). 311 specs green, RuboCop clean. Commits (newest first):
+
+- `ce5046f` M6: wire `cross_compile` config + `native:clean` task (Docker build still wants final verification)
+- `f76f791` M5: `Game#push`/`#pop` mutable history (legal-move validated)
+- `73b3afd` M4: nested-comment + brace-escape round-trip (clean_text unescapes)
+- `0e2a22a` M3: idempotent `MoveText#clean_text`, drop brace sniff
+- `aef5c59` S4: left-recursive `tag_section`/`variation_list` with explicit `.reverse`
+- `4616db6` S3: UCI-style castling (`0-0`) normalization
+- `018192f` S2: `PGN::EPD` read/write + `FEN#to_epd`
+- `8690543` M2: game/position outcome detection (checkmate/stalemate/insufficient/50-move/threefold)
+- `ad43774` M1: `Position#in_check?`/`#attackers` via extracted `PGN::Attack`
+- `99fac3f` S1: `Position#legal?` (SAN+UCI) + `#legal_moves_san`
+
+Remaining (carried to `TODO.md`): final Docker cross-compile verification (M6), tolerant parse mode, streaming reader, richer game-tree API, pin-aware helpers, UCI wrapper, incremental Zobrist.
+
+**Architecture:** The gem stays pure-Ruby for parsing/serialization/position replay; legal-move generation and perft delegate to the native `PGN::Bitboard::Engine` (adapter over `chessie`). New public APIs live on `PGN::Position` / `PGN::Game` and delegate to the engine or to existing private `PGN::Notation` logic. No new Rust is required for these tasks except where noted.
+
+**Tech Stack:** Ruby 3.0+, RSpec, RuboCop, Racc parser, `chessie` 2.0 via `pgn2-bitboard`/`pgn2_native`.
+
+**Spec:** `TODO.md` (cleaned 2026-08-15) plus the in-chat sizing review. There is no separate design spec; this plan is the spec for these tasks.
+
+## Global Constraints
+
+- Ruby `>= 3.0` (`pgn2.gemspec`).
+- Serialized PGN/FEN output must stay byte-identical unless a task explicitly changes a documented quirk.
+- `PGN::Bitboard::Engine` is a required compiled artifact; APIs that need it raise `NameError` naturally if the extension is absent (match the existing `Position#legal_moves` behavior).
+- Each task: write failing spec, implement, run `bundle exec rspec`, run `bundle exec rubocop`, commit.
+- Native-dependent specs are skipped automatically when `PGN::Bitboard::Engine` is not defined (see `spec/bitboard_spec.rb`).
+
+---
+
+## Sizing summary
+
+- Small: S1 `Position#legal?` + SAN legal moves, S2 EPD read/write, S3 UCI-style castling normalization, S4 left-recursive parser rules.
+- Medium: M1 check/pin/attackers helpers, M2 game outcome detection, M3 idempotent `MoveText#clean_text`, M4 nested-comment normalization + brace escaping, M5 mutable push/pop history, M6 verify `release-gems.yml` cross-compile.
+
+Suggested order: S1 → M1 → M2 (M2 uses S1), then S2, S3, S4, then M3 → M4 (related), then M5, then M6 (CI/packaging, can run in parallel with any).
+
+---
+
+## Task S1: Public `Position#legal?` and SAN legal moves
+
+**Files:**
+- Modify: `lib/pgn/position.rb`
+- Create: `spec/position_legal_spec.rb`
+- Reference: `lib/pgn/notation.rb` (`Notation.san(position, from, to, promotion)`), `ext/pgn2_native/pgn2_native/src/lib.rs` (`Engine#legal?(uci)`, `#legal_moves`)
+
+**Interfaces:**
+- Consumes: `PGN::Bitboard::Engine.new(fen).legal_moves` -> `Array<String>` sorted UCI; `PGN::Notation.san(position, from, to, promotion)` -> SAN string.
+- Produces:
+  - `PGN::Position#legal?(move)` -> `Boolean`; accepts SAN (`"Nf3"`, `"e4"`, `"O-O"`) or UCI (`"g1f3"`).
+  - `PGN::Position#legal_moves_san` -> `Array<String>` sorted SAN.
+  - `PGN::Position#to_uci(san)` -> `String` (private helper) returning the UCI whose SAN matches, or `nil`.
+
+- [ ] **Step 1: Write failing spec**
+
+```ruby
+require 'spec_helper'
+
+RSpec.describe PGN::Position, '#legal?' do
+  let(:start) { PGN::Position.start }
+
+  it 'accepts SAN' do
+    expect(start.legal?('e4')).to be(true)
+    expect(start.legal?('e5')).to be(false)
+    expect(start.legal?('Nf3')).to be(true)
+  end
+
+  it 'accepts UCI' do
+    expect(start.legal?('e2e4')).to be(true)
+    expect(start.legal?('e2e5')).to be(false)
+  end
+
+  it 'handles castling and promotion SAN' do
+    pos = PGN::FEN.new('r3k2r/8/8/8/8/8/8/R3K2R w KQkq - 0 1').to_position
+    expect(pos.legal?('O-O')).to be(true)
+    expect(pos.legal?('O-O-O')).to be(true)
+    promo = PGN::FEN.new('8/P7/8/8/8/8/8/4k2K w - - 0 1').to_position
+    expect(promo.legal?('a8=Q')).to be(true)
+    expect(promo.legal?('a8=N')).to be(true)
+  end
+end
+
+RSpec.describe PGN::Position, '#legal_moves_san' do
+  it 'returns sorted SAN for the start position' do
+    sans = PGN::Position.start.legal_moves_san
+    expect(sans.length).to eq(20)
+    expect(sans).to include('e4', 'Nf3', 'd4')
+  end
+end
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bundle exec rspec spec/position_legal_spec.rb`
+Expected: FAIL with `undefined method 'legal?'` / `'legal_moves_san'`.
+
+- [ ] **Step 3: Implement**
+
+Add to `lib/pgn/position.rb`:
+
+```ruby
+# All legal moves from this position as sorted SAN strings, via the
+# native engine's UCI move list and Notation.san. Requires the native
+# extension; raises NameError if it is absent.
+#
+# @return [Array<String>] sorted lexicographically
+def legal_moves_san
+  engine = PGN::Bitboard::Engine.new(to_fen.to_s)
+  engine.legal_moves.map { |uci| uci_to_san(uci) }.sort
+end
+
+# Whether +move+ is legal. Accepts SAN ("Nf3", "e4", "O-O", "a8=Q") or
+# UCI ("g1f3", "e2e4", "e1g1", "a7a8q"). Requires the native extension.
+#
+# @param move [String] SAN or UCI
+# @return [Boolean]
+def legal?(move)
+  return PGN::Bitboard::Engine.new(to_fen.to_s).legal?(move) if uci?(move)
+
+  legal_moves_san.any? { |san| san == move || san.tr('+#!', '') == move }
+end
+
+private
+
+def uci?(move)
+  move.match?(/\A[a-h][1-8][a-h][1-8][qrbn]?\z/)
+end
+
+def uci_to_san(uci)
+  from = uci[0, 2]
+  to = uci[2, 2]
+  promo = uci[5]
+  PGN::Notation.san(self, from, to, promo)
+end
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `bundle exec rspec spec/position_legal_spec.rb`
+Expected: PASS.
+
+- [ ] **Step 5: Run full suite and RuboCop**
+
+Run: `bundle exec rspec` and `bundle exec rubocop`
+Expected: all green, no new offenses.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add lib/pgn/position.rb spec/position_legal_spec.rb
+git commit -m "feat(position): add #legal? and #legal_moves_san via chessie engine"
+```
+
+---
+
+## Task S2: EPD read/write
+
+**Files:**
+- Create: `lib/pgn/epd.rb`
+- Create: `spec/epd_spec.rb`
+- Modify: `lib/pgn.rb` (require `pgn/epd`)
+- Reference: `lib/pgn/fen.rb` for the shared board/side/castling/ep parsing.
+
+**Interfaces:**
+- Consumes: `PGN::FEN.from_attributes`, `PGN::Board.new`, `PGN::Position`.
+- Produces:
+  - `PGN::EPD.new(epd_string)` parses `placement side castling ep ops...`.
+  - `PGN::EPD#to_position` -> `PGN::Position` (halfmove/fullmove default to `0`/`1`).
+  - `PGN::EPD#to_s` -> EPD string.
+  - `PGN::FEN#to_epd` -> EPD string (drop halfmove/fullmove).
+
+- [ ] **Step 1: Write failing spec**
+
+```ruby
+require 'spec_helper'
+
+RSpec.describe PGN::EPD do
+  it 'parses the placement/side/castling/ep fields' do
+    epd = PGN::EPD.new('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq -')
+    expect(epd.to_position.player).to eq(:white)
+    expect(epd.to_position.castling).to eq(%w[K Q k q])
+  end
+
+  it 'round-trips a simple position' do
+    s = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq -'
+    expect(PGN::EPD.new(s).to_s).to eq(s)
+  end
+
+  it 'FEN#to_epd drops the move counters' do
+    expect(PGN::FEN.start.to_epd).to eq('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq -')
+  end
+end
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `bundle exec rspec spec/epd_spec.rb`
+Expected: FAIL with `uninitialized constant PGN::EPD`.
+
+- [ ] **Step 3: Implement**
+
+Create `lib/pgn/epd.rb` mirroring `PGN::FEN` but storing only `board`, `active`, `castling`, `en_passant`, and an `ops` string (remainder after the first four fields). Implement `#to_position` (halfmove `0`, fullmove `1`), `#to_s` (join the four fields plus `ops`), and `PGN::FEN#to_epd` returning `EPD.new(...).to_s` from the FEN's first four fields. Require it from `lib/pgn.rb`.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `bundle exec rspec spec/epd_spec.rb`
+Expected: PASS.
+
+- [ ] **Step 5: Run full suite and RuboCop; commit**
+
+```bash
+bundle exec rspec && bundle exec rubocop
+git add lib/pgn/epd.rb spec/epd_spec.rb lib/pgn.rb
+git commit -m "feat: add PGN::EPD read/write and FEN#to_epd"
+```
+
+---
+
+## Task S3: UCI-style castling normalization
+
+**Files:**
+- Modify: `lib/pgn/move.rb` (`Move#castle=`) or add `Move#to_uci`-aware normalization
+- Modify: `lib/pgn/game.rb` (`standardize_castling`) to also accept UCI-style `e1g1`? (scope: normalize `0-0` -> `O-O` is done; this task adds UCI-style castling recognition in SAN parsing where needed)
+- Create: `spec/castling_normalization_spec.rb`
+
+**Scope note:** This task is deliberately narrow: ensure `PGN::Move` and the serializer handle UCI-style castling tokens if they appear in movetext, and document that the canonical form remains `O-O`/`O-O-O`. If investigation shows the parser already rejects `e1g1` as a non-SAN move, the task reduces to a spec pinning the current behavior plus a `Move#castle` helper used by S1.
+
+- [ ] **Step 1: Write failing spec** pinning expected behavior for `O-O`, `0-0`, and the UCI -> SAN mapping used by S1.
+- [ ] **Step 2: Run test to verify it fails.**
+- [ ] **Step 3: Implement** the smallest normalization needed (likely a `Move#to_san` or a constant map in `Notation` for castling UCI -> SAN).
+- [ ] **Step 4: Run tests and RuboCop.**
+- [ ] **Step 5: Commit** with `feat: normalize UCI-style castling to SAN`.
+
+---
+
+## Task S4: Left-recursive `tag_section` / `variation_list` rules
+
+**Files:**
+- Modify: `lib/pgn/pgn_parser.y` (`tag_section`, `variation_list`)
+- Regenerate: `lib/pgn/pgn_parser.rb` via Racc (part of the build)
+- Modify: `spec/parser_spec.rb` as needed to pin order
+- Reference: `lib/pgn/pgn_parser.y` current right-recursive rules and their `reverse`/`merge` semantics.
+
+**Interfaces:**
+- Consumes: Racc grammar; existing `pgn_game` consumes `tag_section` and `element_sequence`.
+- Produces: same parsed-game hashes with byte-identical `tags` order and `variations` order, but the reversal is a single explicit `.reverse` at consumption instead of implicit in recursion direction.
+
+- [ ] **Step 1: Write/extend spec** that pins tag order and variation order for a multi-tag, multi-variation game (use the existing fixtures plus a crafted case).
+- [ ] **Step 2: Run spec to confirm current behavior passes (baseline).**
+- [ ] **Step 3: Rewrite rules** to ordinary left-recursion, building an in-order array, and add one explicit `.reverse` (and `merge` for first-occurrence-wins on tags) where `pgn_game` / `element` consumes the list.
+- [ ] **Step 4: Regenerate parser** with Racc and run the full suite; confirm byte-identical output for all fixtures.
+- [ ] **Step 5: Commit** with `refactor(parser): left-recursive tag/variation rules with explicit reverse`.
+
+---
+
+## Task M1: Check / pin / attackers helpers on `Position`
+
+**Files:**
+- Modify: `lib/pgn/position.rb`
+- Reference: `lib/pgn/notation.rb` (`attacked?`, `king_idx`, `any_legal_move?` are private; `PGN::Bitboard::Engine#legal_moves` can also answer "in check")
+- Create: `spec/position_attack_spec.rb`
+
+**Interfaces:**
+- Produces:
+  - `PGN::Position#in_check?` -> `Boolean`
+  - `PGN::Position#attackers(square)` -> `Array<String>` (algebraic squares attacking `square` for the side to move's opponent)
+  - `PGN::Position#pinned?` (optional; can defer if chessie does not expose it easily)
+
+- [ ] **Step 1: Write failing spec** for `in_check?` on a known checked position and `attackers` listing the checking pieces.
+- [ ] **Step 2: Run to verify fail.**
+- [ ] **Step 3: Implement** by extracting `Notation`'s private `attacked?`/`king_idx` into reusable module methods (or a thin `PGN::Attack` module) and exposing them on `Position`; prefer pure-Ruby extraction over a FFI round-trip for attackers listing.
+- [ ] **Step 4: Run full suite and RuboCop.**
+- [ ] **Step 5: Commit** with `feat(position): expose in_check? and attackers`.
+
+---
+
+## Task M2: Game outcome detection
+
+**Files:**
+- Modify: `lib/pgn/position.rb` / `lib/pgn/game.rb`
+- Create: `spec/outcome_spec.rb`
+- Reference: S1 (`#legal_moves`, `#legal_moves_san`), `PGN::Zobrist`/`Position#hash` for threefold.
+
+**Interfaces:**
+- Produces:
+  - `PGN::Position#outcome` -> `:checkmate` | `:stalemate` | `:draw` | `nil`
+  - `PGN::Game#outcome` -> same, computed from the final position plus history.
+  - `PGN::Position#insufficient_material?` -> `Boolean`
+  - `PGN::Position#fifty_move?` -> `Boolean` (uses `halfmove`)
+  - `PGN::Game#threefold?` -> `Boolean` (uses `positions` hashes)
+
+- [ ] **Step 1: Write failing spec** covering checkmate, stalemate, insufficient material (K vs K, K+B vs K), 50-move, and threefold via a short repeating game.
+- [ ] **Step 2: Run to verify fail.**
+- [ ] **Step 3: Implement** checkmate/stalemate with `legal_moves.empty?` + `in_check?` (S1/M1); insufficient material with a small piece-set rule; fifty-move with `halfmove >= 100`; threefold by counting `positions.map(&:hash)` (or streaming `each_position` to avoid materializing).
+- [ ] **Step 4: Run full suite and RuboCop.**
+- [ ] **Step 5: Commit** with `feat: add game/position outcome detection`.
+
+---
+
+## Task M3: Idempotent `MoveText#clean_text`
+
+**Files:**
+- Modify: `lib/pgn/game.rb` (`MoveText#clean_text`, `MoveText#initialize`, `Game#standardize_castling`)
+- Modify: `spec/serializer_spec.rb` / `spec/parser_spec.rb`
+- Reference: `lib/pgn/lexer.rb` `COMMENT` regex (already supports nested braces and escaped braces).
+
+**Interfaces:**
+- Produces: `MoveText#clean_text` returns the same result whether called zero, one, or many times; `Game#moves=` no longer sniffs for `{`/`}` to decide reuse.
+
+- [ ] **Step 1: Write failing spec** that builds a `MoveText` with a nested/escaped comment, calls `clean_text` twice, and asserts equality; plus a spec that `moves=` reuses a braced-comment `MoveText` without re-cleaning.
+- [ ] **Step 2: Run to verify fail.**
+- [ ] **Step 3: Implement** a single-pass normalizer that strips only the outermost braces and preserves inner braces/escapes in a canonical form; cache the cleaned value on `@comment` so subsequent calls are no-ops; simplify `standardize_castling` to reuse unconditionally.
+- [ ] **Step 4: Run full suite (watch for byte-output regressions) and RuboCop.**
+- [ ] **Step 5: Commit** with `refactor(movetext): make clean_text idempotent and drop brace sniff`.
+
+---
+
+## Task M4: Nested-comment normalization + brace escaping for round trips
+
+**Files:**
+- Modify: `lib/pgn/lexer.rb` (comment token value), `lib/pgn/game.rb` (`MoveText`), `lib/pgn/serializer.rb` (`escape_comment`)
+- Modify: `spec/parser_spec.rb`, `spec/serializer_spec.rb`
+- Reference: `spec/pgn_files` for `nested_comments.pgn` fixture.
+
+**Interfaces:**
+- Produces: parse -> serialize -> parse is byte-identical for comments containing literal braces/escapes.
+
+- [ ] **Step 1: Write failing spec** using the nested-comments fixture asserting `PGN.parse(game.to_pgn).first` equals the original parsed game for comment fields.
+- [ ] **Step 2: Run to verify fail.**
+- [ ] **Step 3: Implement** symmetric unescape in `MoveText#clean_text` (or a dedicated `Comment` value object) matching `Serializer#escape_comment`; decide one canonical internal representation and document it.
+- [ ] **Step 4: Run full suite and RuboCop.**
+- [ ] **Step 5: Commit** with `feat: round-trip nested comments and escaped braces`.
+
+---
+
+## Task M5: Mutable push/pop history
+
+**Files:**
+- Modify: `lib/pgn/game.rb`
+- Create: `spec/game_history_spec.rb`
+
+**Interfaces:**
+- Produces:
+  - `PGN::Game#push(san)` -> `self`; appends a move, invalidates `@positions`.
+  - `PGN::Game#pop` -> `PGN::MoveText` or `nil`; removes the last move, invalidates `@positions`.
+  - `PGN::Game#positions` stays consistent after mutations (memoization invalidated).
+
+- [ ] **Step 1: Write failing spec** for push/pop and for `positions` reflecting the new move list after mutation.
+- [ ] **Step 2: Run to verify fail.**
+- [ ] **Step 3: Implement** `push` (validate via `Position#legal?` from S1 when available, else accept and document) and `pop`; clear `@positions`/`@starting_position` caches on mutation.
+- [ ] **Step 4: Run full suite and RuboCop.**
+- [ ] **Step 5: Commit** with `feat(game): add mutable push/pop history`.
+
+---
+
+## Task M6: Verify `release-gems.yml` cross-compile
+
+**Files:**
+- Modify: `.github/workflows/release-gems.yml` if needed
+- Reference: `Rakefile` `native:gem` task, `ext/pgn2_native/extconf.rb`.
+
+**Interfaces:** No code API; produces a verified CI artifact path.
+
+- [ ] **Step 1: Run the cross-compile locally** with `bundle exec rake native:gem` (requires Docker) for x86_64/aarch64 linux+darwin.
+- [ ] **Step 2: Inspect** the resulting platform gems and confirm `pgn2_native.so` is included for each platform.
+- [ ] **Step 3: If the workflow is missing/broken**, update `.github/workflows/release-gems.yml` to run the same cross-compile on tag push.
+- [ ] **Step 4: Trigger or simulate the workflow** and confirm it produces gems.
+- [ ] **Step 5: Commit** any workflow fix with `ci: verify/fix prebuilt platform gem cross-compile`.
+
+---
+
+## Notes for executors
+
+- S1 is the keystone for M1/M2; do it first.
+- M3 and M4 are related; doing M3 first makes M4's scope clearer.
+- Any task that changes parser output must be checked against `spec/pgn_files` fixtures for byte-identical round trips.
+- If a task discovers the native extension cannot answer something needed (e.g., `pinned?`), prefer extracting existing pure-Ruby `Notation` logic over adding new Rust surface.

data/docs/superpowers/specs/2026-08-13-attack-masks-design.md

@@ -0,0 +1,57 @@
+# Attack Masks + Retention Benchmark — Design
+
+**Goal:** (1) Replace per-call knight/king offset loops with precomputed
+on-board attack masks; (3) add a retained-memory benchmark section
+showing the lazy `each_position` retention win. Pure Ruby, no behavior
+change, byte-identical output.
+
+## 1. Precomputed knight/king attack masks
+
+**Where the offsets are used today:**
+- `PGN::Notation#reaches?` (N/K): `KNIGHT_OFFS.any? { |o| from + o == to }`.
+- `PGN::Notation#knight_attacked?` / `#king_attacked?`: `OFFS.any? { off; i = target+off; (i & 0x88).zero? && at_index(i) == piece }`.
+- `PGN::Notation#leaper_moves?` (N/K in `any_legal_move?`): same offset + on-board pattern.
+- `PGN::MoveCalculator#move_origins` (K/N origin lookup on the replay path): `offsets.each { off; target = dest+off; next unless on_board?(target); ... }`.
+
+**Change.** Add two frozen 128-element tables to `PGN::Board`:
+`KNIGHT_ATTACKS` and `KING_ATTACKS`, where entry `idx` is a frozen `Array`
+of the on-board 0x88 target indices reachable from `idx` by that piece
+(built from the existing `Notation::KNIGHT_OFFS`/`KING_OFFS` offsets,
+filtering `(t & 0x88).zero?`). Then:
+
+- `Notation#reaches?` N/K → `Board::KNIGHT_ATTACKS[from].include?(to)`.
+- `Notation#knight_attacked?` / `#king_attacked?` → iterate the mask
+  (no per-call off-board test).
+- `Notation#leaper_moves?` N/K → iterate the mask.
+- `MoveCalculator#move_origins` for K/N → a new `leaper_origins(mask, piece)`
+  that iterates pre-filtered on-board targets; pawns keep the offset path.
+
+**Correctness:** the masks are exactly the precomputed set of on-board
+targets the current code computes per call, so output is byte-identical.
+The existing `move_calculator_spec`, `notation_spec`, and the full
+round-trip suite pin this.
+
+**Benchmark:** add a `Notation.san` reconstruction section to
+`bench/profile_moves.rb` (rebuild SAN for every move of the immortal game
+from its coordinate from/to); re-check section 1 (replay) and section 4
+(replay throughput) for the `MoveCalculator` change. Report honestly: if
+the masks don't move the needle (the offset loops are tiny vs. the O(128)
+scans that dominate `Notation`), say so.
+
+## 3. Retained-memory benchmark for `each_position`
+
+**Change.** Add a section to `bench/profile_moves.rb` measuring
+`MemoryProfiler` **retained** objects/memsize for "last position only",
+lazy (`each_position`) vs eager (`positions`). Lazy retains only the last
+`Position` (+ enumerator); eager memoizes the full array on the `Game` and
+retains all `PLY+1` positions.
+
+Uses `report.total_retained` / `report.total_retained_memsize` (objects
+allocated during the report still alive at its end). Fresh `PGN::Game`
+per path so construction cost cancels.
+
+## Global constraints
+- Pure Ruby; no new deps; no native.
+- Byte-identical FEN/PGN; full suite green; no new RuboCop offenses on
+  touched files (existing offenses may remain).
+- TDD; commit per task.

data/docs/superpowers/specs/2026-08-13-perf-internals-design.md

@@ -0,0 +1,111 @@
+# Performance / Internals (Group 4) — Design
+
+**Goal:** Make the existing pure-Ruby PGN/FEN hot paths faster and lay a
+hashing foundation later groups can build on, without changing the public
+behavior or byte output, and without adding native dependencies.
+
+**Scope (this pass):** three concrete, benchmark-validated changes.
+Everything else in Group 4 (precomputed attack masks, bitboard/C backend)
+is deferred to a later pass.
+
+1. Direct 0x88 FEN board-string builder.
+2. Lazy position iteration for `PGN::Game`.
+3. Incremental Zobrist hash on `PGN::Position`.
+
+## 1. Direct 0x88 FEN board-string builder
+
+**Problem.** `PGN::FEN#board_string` calls `board.squares`, which
+rebuilds the full 8x8 array from the 0x88 `@cells` array on every call (8
+file-maps × 8 rank-maps = 64 reads plus array allocations). `FEN#to_s` —
+and therefore every `position.to_fen` / `game.fen_list` call — pays this
+cost.
+
+**Change.** Add `PGN::Board#fen_board_string` that walks `@cells` directly
+in FEN order (rank 8 → rank 1, file a → file h), collapsing runs of `nil`
+into digit counters, and joining the rows with `/`. `FEN#board_string` is
+rewritten to delegate to it. The public `Board#squares` 8x8 API stays
+unchanged (it is still used by `Board#inspect` and equality specs); only
+the FEN path stops going through it.
+
+**Output:** byte-identical to today (the `board_string round-trip` spec
+already pins this).
+
+**Benchmark signal:** a new `bench/profile_moves.rb` section measuring
+FEN generation allocations/throughput for the immortal game's positions;
+allocation count for `to_fen` must drop vs. the committed baseline.
+
+## 2. Lazy position iteration for `PGN::Game`
+
+**Problem.** `PGN::Game#positions` eagerly builds the full `Array` of
+positions (one `Position` + one `Board#dup` per ply) the first time it is
+called, and memoizes it. For a caller that only needs the last position,
+or that wants to stream positions, this allocates and retains the whole
+sequence.
+
+**Change.** Keep `#positions` returning an `Array` (back-compat) but build
+it lazily: add `#each_position` (returns an `Enumerator` when no block is
+given, yields each successive position without materializing the array),
+and have `#positions` be `each_position.to_a` with the existing memoization.
+The replay loop is shared, so the eager and lazy paths produce identical
+positions.
+
+**Output/behavior:** `game.positions` still returns the same `Array`
+(same objects, same order); `game.each_position.to_a == game.positions`.
+New code can use `game.each_position { |p| ... }` to avoid the array.
+
+**Benchmark signal:** a new section measuring allocations for "last
+position only" via `each_position` vs. the eager `positions`; the lazy
+path must allocate far fewer objects because it does not create the
+`Array` and does not retain intermediate positions.
+
+## 3. Incremental Zobrist hash on `PGN::Position`
+
+**Problem / opportunity.** `Position` has no hash/equality; later groups
+(threefold repetition, transposition tables) need one. Computing a hash
+from scratch each move is wasteful; doing it incrementally on
+`Position#move` keeps the cost off any future hot path and gives us
+`Position#hash` / `#eql?` for free.
+
+**Change.** Add a frozen `PGN::Zobrist` module containing:
+- piece × square random 64-bit Integer table (`TABLE`),
+- side-to-move (`SIDE`), castling (`CASTLING`), and en-passant-file
+  (`EP_FILE`) keys,
+- `Zobrist.seed(board, player, castling, en_passant)` for fresh hashes,
+- `Zobrist.update(position, move, calculator, new_board, new_castling,
+  new_ep)` for incremental hashes.
+
+`Position` stores `@zobrist` (an Integer). `Position.start` seeds it
+from the starting board; `Position#move` uses `Zobrist.update` to derive
+the new hash by XOR-ing out/in only the changed squares, flipping the
+side-to-move key, and updating castling/ep contributions. To avoid
+seeding a new position twice, `Position#initialize` accepts an optional
+`zobrist:` keyword; `#move` passes the precomputed incremental hash into
+the constructor.
+
+`Position#hash` returns `@zobrist`; `Position#eql?`/`#==` compare the
+FEN-relevant fields (board cells, player, castling, en_passant — *not*
+halfmove/fullmove, to match repetition semantics).
+
+This is additive: no existing method is removed; `==`/`hash` are new and
+only consumed by new specs in this pass. No existing behavior changes.
+
+**Output/behavior:** no change to existing output; new `Position#hash`/
+`#eql?`/`#==` are covered by dedicated specs.
+
+**Benchmark signal:** `Position#hash` is O(1) (a single integer read).
+The replay benchmark (section 1) will show a small allocation increase
+because every position now carries `@zobrist`; that increase is an
+acceptable, documented trade-off for the new capability. No other
+benchmark section should regress.
+
+## Global constraints
+
+- Pure Ruby only; no new runtime dependencies; no C extension.
+- Ruby 3.x stdlib (`Racc` + `StringScanner` already in use).
+- Public output (FEN, PGN) stays byte-identical; the full spec suite
+  stays green; no *new* RuboCop offenses in changed files (some files on
+  `main` already have offenses; do not increase their offense count).
+- Every change is validated against `bench/baseline_*.txt` (allocations
+  drop or stay flat; throughput rises or stays flat), with the noted
+  exception of the Zobrist maintenance cost in replay benchmarks.
+- TDD: failing test first, then implementation, then green, then commit.