pgn2 0.4.0 → 1.1.0

data/docs/superpowers/plans/2026-08-12-to-pgn-serialization.md

@@ -0,0 +1,162 @@
+# `PGN::Game#to_pgn` serializer — 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:** Produce a canonical PGN string from a `PGN::Game` via `PGN::Game#to_pgn`, backed by a new `PGN::Serializer` class, so that parse → `to_pgn` → parse round-trips.
+
+**Architecture:** A new `PGN::Serializer` class converts a `PGN::Game` into a String (tags section + blank line + movetext section, trailing newline). `PGN::Game#to_pgn` delegates to it. Serialization is purely structural (no board replay, no legality checks), seeding movetext numbering state from `game.starting_position.fullmove`/`player`.
+
+**Tech Stack:** Ruby, RSpec, the existing `pgn2` gem (whittle parser).
+
+## Global Constraints
+
+- No changes to the parser in this sub-project.
+- No move legality validation; serialize moves as given.
+- No line wrapping; v1 emits a single movetext line.
+- Returns a String ending with a trailing newline.
+- No app-specific behavior; nothing here knows about `chessellence`.
+- `nil`/empty annotation, comment, or variations are omitted (no empty `{}`).
+- Tag values escape `\` and `"`; comments escape `\`, `{`, `}`.
+
+---
+
+## File Structure
+
+- Create: `lib/pgn/serializer.rb` — `PGN::Serializer`, all serialization logic.
+- Modify: `lib/pgn.rb` — `require 'pgn/serializer'`.
+- Modify: `lib/pgn/game.rb` — add `PGN::Game#to_pgn` delegating to `PGN::Serializer`.
+- Create: `spec/serializer_spec.rb` — RSpec cases for the serializer.
+- Modify: `spec/game_spec.rb` — add a few `#to_pgn` cases.
+
+---
+
+## Task 1: `PGN::Serializer` core — tags + simple movetext
+
+**Files:**
+- Create: `lib/pgn/serializer.rb`
+- Modify: `lib/pgn.rb`
+- Test: `spec/serializer_spec.rb`
+
+**Interfaces:**
+- Produces: `PGN::Serializer.new(game)` and `PGN::Serializer#to_s` returning the canonical PGN string (with trailing newline).
+
+- [ ] **Step 1: Write failing tests** for the simple cases in `spec/serializer_spec.rb`:
+  - Tags + result: `PGN::Game.new(%w[e4 e5], { 'White' => 'A', 'Black' => 'B' }, '1-0')` → `[White "A"]\n[Black "B"]\n\n1. e4 e5 1-0\n`.
+  - No tags → `[Result "*"]\n\n1. e4 e5 *\n`.
+  - Empty game: `PGN::Game.new([], nil, '*')` → `[Result "*"]\n\n*\n`.
+  - No result → ends with `*\n`.
+
+- [ ] **Step 2: Run tests, verify they fail** with `NameError` (no `PGN::Serializer`).
+
+Run: `bundle exec rspec spec/serializer_spec.rb`
+Expected: FAIL, uninitialized constant `PGN::Serializer`.
+
+- [ ] **Step 3: Implement `PGN::Serializer`** (`lib/pgn/serializer.rb`) with tag escaping, the synthesized `Result` tag, movetext numbering (white `n.`, black `n...` only when needed), and result. Add `require 'pgn/serializer'` to `lib/pgn.rb`.
+
+- [ ] **Step 4: Run tests, verify pass.**
+
+Run: `bundle exec rspec spec/serializer_spec.rb`
+Expected: PASS.
+
+- [ ] **Step 5: Commit.**
+  `git add lib/pgn/serializer.rb lib/pgn.rb spec/serializer_spec.rb && git commit -m "feat: add PGN::Serializer with tags and basic movetext"`
+
+---
+
+## Task 2: Annotations, comments, and variations
+
+**Files:**
+- Modify: `lib/pgn/serializer.rb`
+- Test: `spec/serializer_spec.rb`
+
+**Interfaces:**
+- Consumes: `MoveText#notation`, `#annotation` (Array), `#comment` (String), `#variations` (Array of Arrays of `MoveText`).
+- Produces: move tokens `notation + annotation + {comment} + (variation)`; recursive variation serialization starting from the position before the move.
+
+- [ ] **Step 1: Write failing tests:**
+  - Castling serializes as `O-O` / `O-O-O` (`PGN::Game.new(%w[O-O O-O-O])`).
+  - Annotations: a move with annotation `['$4']` → `e4 $4`; `['??']` → `e4 ??`.
+  - Two annotations: `['$2', '$11']` → `d5 $2 $11`.
+  - Comment: move with comment `c` → `e4 {c}`.
+  - Variations reproduces `spec/pgn_files/variations.pgn` movetext shape, including `2...` after variations: expected movetext `1. e4 e5 2. Nf3 {comment} (2. Nc3 {other} d5 (2... f5) 3. exd5) (2. f4 exf4 {final variation}) 2... Nf6 *` (plus tag section `[White "Somebody"]\n[Black "Petrov"]`).
+
+- [ ] **Step 2: Run tests, verify they fail.**
+
+Run: `bundle exec rspec spec/serializer_spec.rb -e "annotation\|comment\|variation\|Castling"`
+Expected: FAIL.
+
+- [ ] **Step 3: Implement** move-token assembly (notation + annotation + comment + recursive variations) and `prev_had_extras`/`prev_player` numbering rules from the spec. Variations start from the same `fullmove`/`player` as the move they attach to and do not affect enclosing state.
+
+- [ ] **Step 4: Run tests, verify pass.**
+
+Run: `bundle exec rspec spec/serializer_spec.rb`
+Expected: PASS.
+
+- [ ] **Step 5: Commit.**
+  `git add lib/pgn/serializer.rb spec/serializer_spec.rb && git commit -m "feat: serialize annotations, comments, and variations"`
+
+---
+
+## Task 3: Game comment, FEN start, and `--` moves
+
+**Files:**
+- Modify: `lib/pgn/serializer.rb`
+- Test: `spec/serializer_spec.rb`
+
+- [ ] **Step 1: Write failing tests:**
+  - Game comment only: `PGN::Game.new([], nil, '*', nil, 'game comment')` → `[Result "*"]\n\n{ game comment } *\n`.
+  - FEN start with black to move: a game built from `spec/pgn_files/fen.pgn`-style FEN where `active` is `b`, first move numbered `1...`. Construct via `PGN.parse` of a PGN with a `FEN` tag whose active color is `b`.
+  - `--` move serializes verbatim and alternates color/fullmove: `PGN::Game.new(%w[-- e4])` → `1. -- e4`.
+
+- [ ] **Step 2: Run tests, verify they fail.**
+
+Run: `bundle exec rspec spec/serializer_spec.rb -e "game comment\|FEN\|don"`
+Expected: FAIL.
+
+- [ ] **Step 3: Implement** game-comment emission (first movetext token, wrapped in `{ }`), and confirm FEN seeding already works via `starting_position.fullmove`/`player` (no board replay). Add comment escaping.
+
+- [ ] **Step 4: Run tests, verify pass.**
+
+Run: `bundle exec rspec spec/serializer_spec.rb`
+Expected: PASS.
+
+- [ ] **Step 5: Commit.**
+  `git add lib/pgn/serializer.rb spec/serializer_spec.rb && git commit -m "feat: serialize game comments, FEN-start numbering, and -- moves"`
+
+---
+
+## Task 4: `PGN::Game#to_pgn` + round-trip fixture tests
+
+**Files:**
+- Modify: `lib/pgn/game.rb`
+- Modify: `spec/game_spec.rb`
+
+**Interfaces:**
+- Produces: `PGN::Game#to_pgn` returning `PGN::Serializer.new(self).to_s`.
+
+- [ ] **Step 1: Write failing tests** in `spec/game_spec.rb`:
+  - `#to_pgn` returns a string ending in newline for `PGN::Game.new(%w[e4 e5], { 'White' => 'A' }, '1-0')`.
+  - Round-trip: for each fixture in `spec/pgn_files`, parse → `to_pgn` → parse, compare `result`, `moves` (notation), per-move `annotation`/`comment`/`variations`, and that reparsed `tags` are a superset of original (a no-tag game gains a `Result` tag).
+
+- [ ] **Step 2: Run tests, verify they fail** (no `#to_pgn`).
+
+Run: `bundle exec rspec spec/game_spec.rb`
+Expected: FAIL, undefined method `to_pgn`.
+
+- [ ] **Step 3: Implement `PGN::Game#to_pgn`** delegating to `PGN::Serializer`.
+
+- [ ] **Step 4: Run full suite, verify pass.**
+
+Run: `bundle exec rspec`
+Expected: PASS (all examples).
+
+- [ ] **Step 5: Commit.**
+  `git add lib/pgn/game.rb spec/game_spec.rb && git commit -m "feat: add PGN::Game#to_pgn with round-trip fixture tests"`
+
+---
+
+## Self-Review
+
+- **Spec coverage:** tag section + synthesized Result tag (T1), movetext numbering incl. `n...` rules (T1/T2), move token with annotation/comment/variations (T2), recursive variations from prior position (T2), game comment (T3), FEN/black-to-move seeding (T3), `--` (T3), `to_pgn` API + trailing newline (T1/T4), escaping (T1/T3), edge cases (T1/T3), round-trip fixture tests (T4). ✓
+- **Placeholder scan:** no TBD/TODO. ✓
+- **Type consistency:** `PGN::Serializer.new(game)`, `#to_s`, `PGN::Game#to_pgn` consistent across tasks. `MoveText` accessors match existing `game.rb` (`notation`, `annotation`, `comment`, `variations`). ✓

data/docs/superpowers/plans/2026-08-13-whittle-to-racc-migration.md

@@ -0,0 +1,130 @@
+# Plan: Migrate PGN parser from whittle to Racc + StringScanner
+
+Date: 2026-08-13
+Status: **COMPLETE** (all 8 tasks done; 187 examples green; whittle removed).
+Branch: `racc-migration` (branched from `faster` after baseline commit)
+Fallback: tag `pre-racc` on the pre-migration commit.
+
+Result: parse-only allocations -55% objects / -70% bytes, parse-only
+throughput ~3.5x faster (741 -> 212 ms/i). See `bench/IMPROVEMENTS.md`.
+
+## Goal
+
+Replace the abandoned `whittle` (0.0.8, 2011) parser with a maintained,
+stdlib-only `Racc` + `StringScanner` parser that produces **byte-compatible**
+`PGN::Game` objects: identical `tags`, `result`, `moves` (as `MoveText` with
+`annotation`/`comment`/`variations`), `pgn` (verbatim raw text), and `comment`.
+Keep every existing spec green and add many new parser tests.
+
+## Why
+
+- whittle is unmaintained (14 years old) and accounts for ~80% of parse
+  allocations (`terminal.rb` 77k + `parser.rb` 22k of 125k per 50 games).
+- A `StringScanner` (C ext) lexer replaces whittle's pure-Ruby per-token regex
+  churn — the dominant cost.
+- Racc is stdlib runtime (`racc/parser`), maintained; drops whittle, adds no
+  runtime gem.
+- Also fixes the `@@pgn`/`@@game_comment` class-variable reentrancy bug
+  (state moves to parser instances) and the O(n²) `@@pgn` string building.
+
+## Safety strategy (repo stays green at every checkpoint)
+
+1. Keep `whittle` fully working as `PGN::WhittleParser`; `PGN.parse` uses it
+   until the new parser is proven.
+2. Build `PGN::RaccParser` in parallel.
+3. **Golden-equivalence spec**: parse all 14 fixtures + every `parser_spec`
+   example string with BOTH parsers; assert the resulting `PGN::Game` objects
+   are equal (tags/result/moves/pgn/comment). Iterate the new parser until
+   green. This makes the fiddly `game.pgn` verbatim-text and `comment`
+   semantics **convergent, not hand-modelled**.
+4. Cut over `PGN::Parser` → `PGN::RaccParser` only when golden + full suite
+   pass.
+5. Remove `whittle` only after the full suite is green on Racc alone.
+
+If any task cannot be made green, revert to whittle (repo stays on
+`pre-racc`-equivalent state) and report partial progress.
+
+## Tasks
+
+### Task 0 — Stabilize baseline
+
+- Commit the in-tree WIP (double-quotes regex + `Encoding` arg +
+  `spec_helper` cleanup + `board.rb` `@owned` COW refinement + `game.rb`
+  gsub-skip + new fixtures + CHANGELOG + this plan + the existing
+  efficiency plans) so the migration starts from a known, committed state.
+- Tag `pre-racc`. Branch `racc-migration`. Verify `bundle exec rspec` green.
+
+### Task 1 — Preserve whittle as `PGN::WhittleParser`
+
+- Rename `class Parser < Whittle::Parser` → `class WhittleParser` in
+  `lib/pgn/parser.rb`; keep `PGN::Parser` as a thin module/facade that
+  currently delegates to `WhittleParser` (`PGN.parse` unchanged behavior).
+- Add `spec/golden_equivalence_spec.rb` scaffold that iterates all fixtures
+  and asserts `WhittleParser` vs `RaccParser` (RaccParser stubbed to skip
+  until Task 4). For now it just documents WhittleParser output is stable.
+
+### Task 2 — StringScanner lexer
+
+- New `lib/pgn/lexer.rb`: `PGN::Lexer` yielding tokens `[:type, value, offset,
+  line]`. Reuses the **exact** whittle regexes (string, comment with `\g<1>`
+  recursion, game_termination, san_move, move_number_indication, tag_name,
+  numeric_annotation_glyph) so tokenization matches; skips `wsp` and
+  `%`-comments. Token precedence tuned for PGN (terminations and san_move
+  before move_number so `1-0`/`0-0` tokenize correctly).
+- New `spec/lexer_spec.rb`: token-level tests for every token type on
+  representative inputs (including UTF-8 en-dash, inner quotes, nested
+  comments, NAGs, `--`, castling `0-0`/`O-O`, promotion, check/mate).
+
+### Task 3 — Racc grammar + generated parser
+
+- New `lib/pgn/pgn_parser.y`: Racc grammar mirroring the whittle rules.
+  `variation_list` left-recursive (preserves variation order — fixes the
+  current "reverses on parse" quirk; `game_spec` compares order-independently
+  so this is safe). Recursive comments handled in the lexer.
+- `Rakefile`: `rake generate` runs `racc lib/pgn/pgn_parser.y -o
+  lib/pgn/pgn_parser.rb`; commit the generated file (no runtime racc dep for
+  users). Add `racc` as a dev dependency in the gemspec.
+- New `PGN::RaccParser` (`lib/pgn/racc_parser.rb`): `parse(input)` → array of
+  game hashes `{tags:, result:, moves:, pgn:, comment:}` matching the
+  whittle shape. Lexer/parse state held on the instance (no class vars).
+  `pgn` computed from per-game token offsets (start of first token → end of
+  game_termination); converged via the golden test.
+
+### Task 4 — Golden equivalence
+
+- Complete `spec/golden_equivalence_spec.rb`: for each fixture and each
+  parser_spec example string, assert
+  `whittle_games == racc_games` where equality covers tags, result, each
+  move's notation/annotation/comment/variations (recursively), pgn, comment.
+- Iterate lexer token order + grammar + `pgn` slicing until 100% green.
+
+### Task 5 — Cut over
+
+- `PGN::Parser` → delegate to `PGN::RaccParser`. Run the **full** suite
+  (parser_spec, game_spec round-trip-all-fixtures, serializer_spec,
+  board/move/move_calculator/position/fen specs). All must pass.
+
+### Task 6 — Many new explicit parser tests
+
+- Expand `spec/parser_spec.rb` with hardcoded-expected cases (no whittle
+  dependency): empty game, no-moves game, single move, comments, nested
+  comments, multiline comments, variations (incl. nested), annotations,
+  NAGs (`$1`, `?!`, `!?`), FEN tag, `--` move, castling `0-0`/`O-O-O`,
+  promotion `=Q`, check `+`, mate `#`, double-quotes-in-tag-value, UTF-8
+  special chars + `Encoding` arg, multiple games, game comment before moves,
+  `empty_variation_move`, `1/2-1/2` and `*` terminations.
+
+### Task 7 — Remove whittle
+
+- Delete `PGN::WhittleParser` and `require 'whittle'`.
+- Drop `whittle` from `pgn2.gemspec` runtime deps.
+- Remove `spec/golden_equivalence_spec.rb` (its job is done) OR convert it to
+  committed-snapshot expectations (keep coverage but no whittle).
+- `git grep -i whittle` must be clean.
+
+### Task 8 — Bench + verify
+
+- Re-run `rake bench`; record parse-only and parse+replay before/after in
+  `bench/IMPROVEMENTS.md` (add a "parser migration" section).
+- Final: `bundle exec rspec` all green; `git grep -i whittle` clean;
+  summarize deltas.

data/docs/superpowers/specs/2026-08-12-to-pgn-serialization-design.md

@@ -0,0 +1,217 @@
+# `PGN::Game#to_pgn` serialization — design
+
+- Date: 2026-08-12
+- Status: Draft, awaiting review
+- Repo: `git@github.com:muriloime/pgn.git` (gem `pgn2`)
+- Sub-project: 1 of 4 (“add generic, reusable features to pgn2”)
+
+## Context
+
+`chessellence` uses `pgn2` only to parse/validate lesson PGNs at seed time. We
+want to enhance pgn2 with generic, reusable features. This is the first of four
+independent sub-projects, each with its own design → plan → implementation cycle:
+
+1. **`PGN::Game#to_pgn` serializer** ← this document
+2. FEN helpers / position utilities (parse, validate, compare, normalize)
+3. Parser improvements (NAGs, recursive variations)
+4. Server-side move/FEN validation API (legal moves, check/checkmate/draw)
+
+`to_pgn` is first because it is self-contained, closes a long-standing TODO in
+the gem, is immediately useful for exporting/sharing games from `chessellence`,
+and does not depend on a rules engine.
+
+## Goal
+
+Produce a canonical PGN string from a `PGN::Game`’s structured data (tags,
+moves, comments, annotations, variations, result), so that:
+
+- `PGN.parse(game.to_pgn)` is equivalent to `game` (round-trippable).
+- The output is valid PGN per the PGN spec for the features the parser already
+  supports (movetext, comments, NAGs/symbolic annotations, variations, FEN
+  start tag, game result).
+- The gem remains free of app-specific behavior; nothing here knows about
+  `chessellence`.
+
+## Non-goals
+
+- No move legality validation, no check/checkmate detection. A `PGN::Game`
+  built from arbitrary SAN serializes as given. (Validation is sub-project 4.)
+- No line wrapping / 80-column formatting in v1. Output is a single movetext
+  line. Wrapping can be added later as an option without changing the core.
+- No preservation of the original raw `pgn` formatting. `to_pgn` serializes
+  from structured data, not from the `Game#pgn` attribute.
+- No changes to the parser in this sub-project.
+
+## API
+
+```ruby
+class PGN::Game
+  # @return [String] a canonical PGN string for this game
+  def to_pgn
+    PGN::Serializer.new(self).to_s
+  end
+end
+```
+
+- Returns a String ending with a trailing newline.
+- No options in v1 (YAGNI). A future `width:` option for line wrapping can be
+  added without breaking callers.
+
+Implementation lives in a new `PGN::Serializer` class so `PGN::Game` stays thin
+and the serialization logic is independently testable.
+
+## Output structure
+
+A game serializes as up to two sections separated by a blank line:
+
+1. **Tag section** — one tag pair per line, in the order of `game.tags`:
+   `[Key "Value"]`. If `tags` is `nil` or empty, emit a synthesized
+   `[Result "<result or *>"]` tag instead. The current parser grammar
+   requires at least one tag pair, so this keeps no-tag games parseable; it
+   means a no-tag game round-trips with a single `Result` tag added.
+2. **Movetext section** — optional game comment, then moves, then result.
+
+```
+[Event "Zurich Chess Challenge"]
+[White "Carlsen, Magnus"]
+
+1. c4 g6 2. d4 Nf6 ... 1-0
+```
+
+If there are no moves, the movetext section is just the game comment (if any)
+followed by the result. (The tag section is never entirely omitted — see
+above.)
+
+## Movetext rules
+
+State tracked while emitting a line (mainline or variation):
+
+- `fullmove` — starts from `game.starting_position.fullmove` (1 by default).
+- `player` — starts from `game.starting_position.player` (`:white` by default).
+- `prev_player` — the color of the previously emitted move in the current
+  line (`nil` at the start of a line/variation).
+- `prev_had_extras` — whether the previous move emitted any annotation,
+  comment, or variation.
+
+For each `MoveText` in the line:
+
+- If `player == :white`:
+  - Emit `"<fullmove>."` then the move token.
+- If `player == :black`:
+  - Emit `"<fullmove>..."` before the move token when a number is needed:
+    - at the start of a line/variation (`prev_player.nil?`),
+    - after a comment/annotation/variation on the previous move
+      (`prev_had_extras`),
+    - when the previous move was not white (`prev_player != :white`).
+  - Otherwise emit the move token with no number (conventional
+    `1. e4 e5 2. Nf3 ...` style).
+- After emitting, update state:
+  - `prev_player = player`
+  - `prev_had_extras = move had annotation, comment, or variation`
+  - If `player == :black`, `fullmove += 1`.
+  - `player = opposite`.
+
+This reproduces the conventional style and keeps black move numbers
+unambiguous after comments/variations, e.g. the `variations.pgn` fixture:
+
+```
+1. e4 e5 2. Nf3 {comment} (2. Nc3 {other} d5 (2... f5) 3. exd5) (2. f4 exf4 {final variation}) 2... Nf6 *
+```
+
+### Move token
+
+A move token is the notation plus trailing extras, joined by spaces:
+
+1. `move.notation` (e.g. `e4`, `O-O`, `Nef6+`, `--`).
+2. Each element of `move.annotation` (e.g. `$2`, `??`), in order.
+3. `move.comment` as `{ ... }`, if present.
+4. Each variation as `( ... )`, if present.
+
+Variations are serialized recursively with the same movetext rules, starting
+from the position **before** the move they are attached to (same `fullmove`
+and `player` as that move). Variations do not affect the enclosing line’s
+`fullmove`/`player` state.
+
+### Game comment
+
+If `game.comment` is present, it is emitted as the first token of the movetext
+section, wrapped as `{ ... }`, before any move numbers.
+
+### Result
+
+The result token is appended last:
+
+- `game.result` if present and non-empty.
+- `"*"` otherwise.
+
+### Castling and `--`
+
+- The parser already normalizes `0` to `O` in `Game#moves=`, so castling
+  serializes as `O-O` / `O-O-O`.
+- `--` (“don’t care”) moves serialize verbatim and are treated as a normal ply
+  for color/fullmove alternation, matching `Position#move`’s behavior.
+
+## Starting position
+
+`PGN::Game#starting_position` already returns a `PGN::Position` from the `FEN`
+tag (or the standard start). The serializer uses only its `fullmove` and
+`player` to seed movetext state. It does **not** replay moves on a board, so
+invalid games still serialize. This means a game starting with black to move
+from a FEN tag emits its first move as `1... ...`.
+
+## Escaping
+
+- **Tag values:** escape `\` and `"`:
+  `value.to_s.gsub('\\', '\\\\\\\\').gsub('"', '\\"')`.
+- **Comments:** wrap in `{ ... }` and escape `\`, `{`, and `}` for correctness.
+  Note: the current parser’s `MoveText#clean_text` does not unescape inner
+  braces, so a comment containing escaped braces will not round-trip
+  byte-for-byte until parser improvements (sub-project 3) add unescaping. For
+  v1, tests avoid literal braces inside comment text; the serializer is still
+  correct for the spec.
+- **Annotations:** emitted verbatim (`$n` or symbolic `?!` forms).
+- **Notation:** emitted verbatim.
+
+## Edge cases
+
+- No tags → emit a synthesized `[Result "<result or *>"]` tag (keeps output
+  parseable by the current grammar; a no-tag game round-trips with that tag
+  added).
+- No moves → emit game comment (if any) and result only.
+- No result → emit `*`.
+- `nil`/empty annotation or comment → omit (do not emit empty `{}`).
+- `nil`/empty variations → omit.
+- Game starting with black to move (FEN tag) → first move numbered `1...`.
+- Manually constructed game (`PGN::Game.new(%w[e4 e5])`) → tag section
+  `[Result "*"]` then `1. e4 e5 *`.
+
+## Testing
+
+New `spec/serializer_spec.rb` (RSpec, matching existing style) plus a few
+`#to_pgn` cases in `spec/game_spec.rb`. Cases:
+
+1. Simple game with tags and result:
+   `PGN::Game.new(%w[e4 e5], { 'White' => 'A', 'Black' => 'B' }, '1-0')`
+   → `[White "A"]\n[Black "B"]\n\n1. e4 e5 1-0`.
+2. Manually constructed game with no tags → `[Result "*"]\n\n1. e4 e5 *`.
+3. Castling serializes as `O-O` / `O-O-O`.
+4. Annotations: `$4`, `??` emitted after notation.
+5. Comments and variations: reproduces `variations.pgn` movetext shape,
+   including `2...` after variations.
+6. FEN start with black to move → first move `1...`.
+7. Empty game: `PGN::Game.new([], nil, '*')` → `*`.
+8. Game comment only: `PGN::Game.new([], nil, '*', nil, 'game comment')`
+   → `{ game comment } *`.
+9. **Round-trip:** for each fixture in `spec/pgn_files`, parse → `to_pgn` →
+   parse again, then compare `result`, `moves` (notation), per-move
+   `annotation`, `comment`, and `variations`, and that the reparsed `tags` are a
+   superset of the original (a no-tag game gains a `Result` tag). This does not
+   require byte-for-byte equality with the original file.
+
+## Future considerations (not in this sub-project)
+
+- Optional line wrapping (`width:` argument) to respect the PGN 80-column
+  recommendation.
+- Canonical Seven-Tag-Roster ordering/normalization option.
+- Exact raw-PGN preservation is out of scope; callers that want the original
+  source should use `Game#pgn`.