Skip to content

Add Golf game variant with nine-hole match play - #58

Merged
austin-smith merged 4 commits into
mainfrom
golf-variant
Jul 13, 2026
Merged

austin-smith merged 4 commits into
mainfrom
golf-variant

Conversation

@austin-smith

Copy link
Copy Markdown
Owner

What Changed

  • New Golf variant: seven face-up columns of five, play any exposed card one rank up or down onto the waste (suits ignored), single 16-card stock pass with no recycles. Strict classic rules: no Ace↔King wraparound, and nothing plays on a King.
  • Traditional golf scoring, lower is better: the hole score is the cards left on the board; clearing the board subtracts one point per leftover stock card, so negative scores are the best results. Holes roll up into a nine-hole match (par 45) with a scorecard summary, hole-complete interstitials, and a running match total in the header. The floor-0 score clamp, win time bonus, and high-score statistics are all variant-aware so lower-is-better works end to end (best hole, best match, matches completed).
  • Solver-backed hints: GolfPlanner runs an exact plays-first depth-first search over a collision-free 30-bit packed position (12-byte search nodes make the 1M-node budget affordable). Winning lines when a deal is winnable, exact max-clear lines when it is not, silence only when nothing is clearable.
  • Match lifecycle correctness: the match persists atomically with its board in the save payload and survives game switching via the per-mode session stash; undo can never cross a hole boundary; a dead hole freezes the clock until the player advances (undo resumes without counting overlay dwell); a completed match archives its final board — undo and redeal are gated at the model and in every affordance (toolbar, macOS menu, keyboard); statistics resets revoke a mid-match scorecard's eligibility without erasing it.
  • Integration surface: game picker mini-board art, per-game statistics detail with golf-specific rows, rules & scoring in-app copy, hint-probe wiring with recorded ledger baselines, screenshot fixture, README row, and docs/solitaire-rules-golf.md.
  • Docs: all seven rules docs now share one section skeleton; Klondike, FreeCell, and Yukon gain the Scoring sections they were missing; solver/baseline content moves out of rules docs entirely (the hint-probe ledger is the single source for those figures).

Why

Golf is the simpler ancestor of TriPeaks — same match-against-the-waste play with a fully open columnar layout — and the lowest-effort addition to that family. Strict rules and traditional match scoring were chosen deliberately: they are the classic game, and the scoring gives lost deals (the majority under strict rules) a meaningful outcome to optimize.

Closes #46

Validation

  • Full unit suite: 397 tests, 0 failures (macOS Debug, the CI invocation), including 80+ new Golf tests across rules, session, planner, persistence, match lifecycle, and statistics.
  • Hint-probe ledger baseline recorded and reproduced deterministically: 22.6% follower win rate vs 0.0% random control over 500 seeded deals, zero stalemate loops, median 33/35 cards cleared on lost deals (control: 11). Verdict sweep: 26.1% proved winnable / 66.3% proved unwinnable / 7.6% undecided over 10,000 deals.
  • iOS and macOS builds clean; exercised end to end in the simulator: deal, tap/drag play, undo, stock, hole-over interstitial (frozen clock, dwell-free undo resume), match advance, kill/relaunch persistence mid-hole and at the summary, game-picker selection, and VoiceOver reachability of the overlay controls.

UI Changes

  • Golf board (shared tableau layout) with stock + waste top row.
  • Header shows "Hole n/9" on the score tile plus a live Match total tile for Golf.
  • Hole-complete and match-summary overlays (modal to VoiceOver, matching the win overlay's chrome).
  • Golf mini-board in the game picker gallery.

strict classic rules (no wraparound, nothing plays on a king, single
stock pass) with traditional lower-is-better stroke scoring across a
nine-hole match. exact solver-backed hints via a plays-first dfs over a
30-bit packed position; probe-verified 22.6% follower win rate against
a 0.0% random control. includes per-mode picker art, match persistence,
statistics, screenshot fixture, and rules doc
all seven docs now share the same section skeleton; klondike, freecell,
and yukon gain the scoring sections they were missing; solver and
baseline content moves out of rules docs entirely (the hint-probe
ledger is the single source for those figures)
'the linked sources disagree' had been stamped across every rules doc;
freecell and yukon sources don't disagree about anything listed — those
are implementation decisions — and klondike and spider differ only in
specific areas, now named
the solitaire-rules- filename prefix becomes the folder name, so
docs/rules/golf.md replaces docs/solitaire-rules-golf.md; readme links
updated
@austin-smith
austin-smith merged commit 08c719d into main Jul 13, 2026
2 checks passed
@austin-smith
austin-smith deleted the golf-variant branch July 13, 2026 18:57
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.

Add Golf game variant

1 participant