From c024ca87d89ae90fc37e34137be710dac2a37527 Mon Sep 17 00:00:00 2001 From: Ken Riley Date: Fri, 4 Sep 2026 11:51:14 -0600 Subject: [PATCH 1/2] docs: add proof-of-done and dead-gate rules; drop 15s status cadence Rules extracted from incidents that were only recorded in session memory: - Write the failing test first; regression fixtures built from the real production input, not an approximation. - A test that has never executed is not a gate: no env-flag gating, verify CI is enabled, read the skip count. - Boundaries that swallow things silently: persistence round-trip, serialization, declared dependency ranges vs the lockfile. - Deploy verification means running the feature, not inspecting artifacts. - npm release order: promote to main (fast-forward) before publish. - Never pkill by substring; anchor the pattern or kill by PID. Also removes the 15-second/30-second status-update cadence and its [HH:MM:SS] UPDATE #N format, a relic of early sessions. Stuck detection is kept. Claude-Session: https://claude.ai/code/session_01DEVew52GVgXWWN9Z6Vc5W7 --- .cursor/rules/README.md | 1 - .cursor/rules/development-workflow.md | 30 ++++++++++++--------------- 2 files changed, 13 insertions(+), 18 deletions(-) diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md index 8a24a8d..d755409 100644 --- a/.cursor/rules/README.md +++ b/.cursor/rules/README.md @@ -36,7 +36,6 @@ This directory contains the organized rules and guidelines for the Nodots Backga **WORKFLOW:** -- Regular status updates every 15-30 seconds - Always kill API server before starting - Verify directory before running commands - All tests must pass before completion diff --git a/.cursor/rules/development-workflow.md b/.cursor/rules/development-workflow.md index 518dc48..9091ee9 100644 --- a/.cursor/rules/development-workflow.md +++ b/.cursor/rules/development-workflow.md @@ -1,22 +1,6 @@ # Development Workflow Rules -## Status Updates and Communication - -### Regular Status Updates - -Provide status updates every 15 seconds during long-running tasks or operations. Each update MUST include: - -- ๐Ÿ•’ Timestamp in format "**[HH:MM:SS] UPDATE #N**" -- Current task/operation being performed -- Progress indicators or completion status -- Any issues encountered -- Next steps planned - -This keeps the user informed and prevents confusion about task progress. - -### Notification Requirements - -Update status in the chat window at a minimum every 30 seconds. If you are stuck, interrupt after 3 iterations. +## Communication ### Stuck Detection @@ -30,6 +14,18 @@ This prevents wasting time on tangential issues and keeps focus on the main obje ## Testing and Quality Assurance +### Write the Failing Test First + +The test is written before the fix and must fail against the pre-change tree, then pass after. A test written against already-fixed code proves the code runs, not that the bug is gone. Every bug fix ships a regression fixture built from the real failing input โ€” the production position ID or payload, not an approximation of one. + +Never gate a test behind an environment flag nothing sets: a suite that has never executed is not a gate. Read the skip count as a finding โ€” this package's suites differ by machine (the CI runner passes the native addon suites and skips the gnubg-binary suites; the Linux box is the reverse), so neither environment runs everything and no single run justifies a coverage claim. + +TypeScript compilation errors in tests are test failures. Fix them, never exclude them. + +### Declared Dependency Ranges + +Code using a new `@nodots/backgammon-types` symbol needs the declared **range** bumped, not just a lockfile refresh. A range that still satisfies the old locked version means npm never moves, `npm ci` obeys the lock, and CI dies in `tsc` while developer machines pass on a hand-refreshed tree. This package's `development` branch was red for three days in July 2026 for exactly this reason. `npm install --package-lock-only` cannot fix it โ€” change the range. + ### Test Requirements All tests must pass before reporting that a task is completed. If any tests fail after implementing changes, iterate on the solution until all tests pass. Run the test suite and fix any failures before considering the task done. From 4d2dd766819894805131f365241f9b2ca8e82bf3 Mon Sep 17 00:00:00 2001 From: Ken Riley Date: Fri, 4 Sep 2026 12:11:29 -0600 Subject: [PATCH 2/2] chore: delete .cursor rule files, superseded by the backgammon-rules plugin The .cursor rules were generated copies (config.json describes the generator) that drifted for a year: a status-update rule removed in 2026 still existed in five of them, and every file duplicated content already in CLAUDE.md. Domain knowledge and engineering rules now live in one place: nodots/backgammon-rules, installed as a Claude Code plugin from the nodots-plugins marketplace. Salvaged before deletion: the api's ESM/ts-node migration-consistency checks (now backgammon-api/CLAUDE.md). Dropped deliberately: generic boilerplate (REST verbs, HTTP status codes, "use HTTPS", "avoid memory leaks") and a stale rule saying never to restart the API server, which contradicts the current CLAUDE.md instruction to kill it before starting. Claude-Session: https://claude.ai/code/session_01DEVew52GVgXWWN9Z6Vc5W7 --- .cursor/rules.md | 64 ------------------ .cursor/rules/README.md | 48 -------------- .cursor/rules/backgammon-game-rules.md | 90 -------------------------- .cursor/rules/coding-standards.md | 56 ---------------- .cursor/rules/development-workflow.md | 64 ------------------ 5 files changed, 322 deletions(-) delete mode 100644 .cursor/rules.md delete mode 100644 .cursor/rules/README.md delete mode 100644 .cursor/rules/backgammon-game-rules.md delete mode 100644 .cursor/rules/coding-standards.md delete mode 100644 .cursor/rules/development-workflow.md diff --git a/.cursor/rules.md b/.cursor/rules.md deleted file mode 100644 index a6accb3..0000000 --- a/.cursor/rules.md +++ /dev/null @@ -1,64 +0,0 @@ -# Nodots Backgammon Ecosystem Cursor Rules -# Repository: core (library) -# Generated: 2025-07-05T21:22:19.692Z -# Configuration Version: 1.0.0 - ---- - -## ๐Ÿ“‹ Table of Contents - -### Shared Rules -- [Core Rules](#core-rules) -- [Development Rules](#development-rules) -- [Coding Rules](#coding-rules) - ---- - -## ๐ŸŒ Shared Ecosystem Rules - -The following rules are shared across the entire Nodots Backgammon ecosystem: - -### Core Rules -*Backgammon domain knowledge and game rules* - - - -### Development Rules -*Development processes and communication standards including main branch naming* - - - -### Coding Rules -*Architecture and code style guidelines* - - - -## ๐ŸŽฏ Repository-Specific Rules - -*No repository-specific rules defined.* - -To add repository-specific rules, edit the configuration in `.cursor/config.json` - ---- - -## ๐Ÿ“Š Rule Configuration Metadata - -- **Repository**: core -- **Type**: library -- **Template**: Template for library packages (types, core, ai) -- **Shared Rules**: core, development, coding -- **Custom Rules**: 0 -- **Last Updated**: 2025-07-05T21:22:19.692Z -- **Config Version**: 1.0.0 - ---- - -**๐Ÿ”ง To modify these rules:** -1. Edit the configuration in `.cursor/config.json` -2. Run `npm run setup` to regenerate all rules -3. Commit changes to propagate across the ecosystem - -**๐Ÿ“š For more information:** -- [Ecosystem Documentation](../ECOSYSTEM.md) -- [Shared Rules Directory](../.cursor/shared-rules/) -- [Development Workflow](../.cursor/shared-rules/development-workflow.md) diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md deleted file mode 100644 index d755409..0000000 --- a/.cursor/rules/README.md +++ /dev/null @@ -1,48 +0,0 @@ -# Nodots Backgammon Project Rules - -This directory contains the organized rules and guidelines for the Nodots Backgammon project. - -## Rule Categories - -### [Backgammon Game Rules](./backgammon-game-rules.md) - -- Backgammon board position system -- Unified presentation layer -- Play/move game flow -- Game creation requirements - -### [Development Workflow](./development-workflow.md) - -- Status updates and communication -- Testing and quality assurance -- Environment management -- API server information - -### [Coding Standards](./coding-standards.md) - -- Architecture and separation of concerns -- Type safety and dependencies -- Programming style guidelines - -## Quick Reference - -**CRITICAL CONCEPTS:** - -- Dual position numbering system (clockwise/counterclockwise) -- Unified presentation layer for all players -- Game logic separation (core vs API) -- Official types package usage -- Functional programming over imperative - -**WORKFLOW:** - -- Always kill API server before starting -- Verify directory before running commands -- All tests must pass before completion -- Use exact bug status terminology - -**API USAGE:** - -- Use `api.*` methods, never raw fetch() -- Use `api.games.start(player1Id, player2Id)` for game creation -- API routes: `:/api/v1/` diff --git a/.cursor/rules/backgammon-game-rules.md b/.cursor/rules/backgammon-game-rules.md deleted file mode 100644 index 8a71aa7..0000000 --- a/.cursor/rules/backgammon-game-rules.md +++ /dev/null @@ -1,90 +0,0 @@ -# Backgammon Game Rules - -## Rules of Backgammon - -https://www.bkgm.com/rules.html - -## Backgammon Board Position System - -**CRITICAL**: Each point on the backgammon board has TWO position numbers - one for each player direction: - -- **Clockwise positions**: 1, 2, 3... 24 (clockwise player's perspective) -- **Counterclockwise positions**: 1, 2, 3... 24 (counterclockwise player's perspective) - -### Starting Positions - -- **Clockwise player** starts with checkers on clockwise positions: 24, 13, 8, 6 -- **Counterclockwise player** starts with checkers on counterclockwise positions: 24, 13, 8, 6 - -### Key Points - -- Both players start on their respective "24, 13, 8, 6" but from their own directional perspective -- This is NOT a bug - it's the correct dual numbering system -- Each point object contains: `{ clockwise: X, counterclockwise: Y }` -- Move validation must use the correct positional perspective for each player - -### Example - -``` -Point at top-right of ASCII board: -- Clockwise position: 24 (WHITE's starting position) -- Counterclockwise position: 1 (BLACK's goal position) -``` - -This dual numbering system is essential for proper move validation and game logic. - -## Unified Presentation Layer - -**KEY FEATURE**: Every player sees the board as if they are "white moving clockwise" regardless of the actual backend configuration. - -### Backend Flexibility - -The game can have any combination of: - -- White moving clockwise vs counterclockwise -- Black moving clockwise vs counterclockwise -- Any player being human or robot -- Any starting positions - -### Frontend Consistency - -Every player always sees: - -- Their checkers as "white" moving clockwise -- Their home board as positions 1-6 (bottom right) -- Their outer board as positions 7-12 (bottom left) -- Opponent's outer board as positions 13-18 (top left) -- Opponent's home board as positions 19-24 (top right) - -### Benefits - -- Eliminates cognitive load of "which direction am I moving?" -- No need to mentally flip the board -- Consistent, intuitive view for all players -- Backend can handle any game configuration while frontend presents unified experience - -This presentation abstraction is a key differentiator of Nodots Backgammon. - -## Play/Move Game Flow - -Understanding the critical game flow is essential for debugging move-related issues: - -1. **Game.roll()** creates new Play instance โ†’ becomes activePlay in Game -2. **Play.initialize()** creates moves (2 for regular roll, 4 for doubles) with possibleMoves populated -3. **Empty possibleMoves** = 'no-move', completed automatically -4. **Non-empty possibleMoves** = player selects from options (humans click checkers, robots auto-select first) -5. **Move execution** updates activePlay.moves to track consumed dice - -When debugging move issues, always check: activePlay state, moves array, possibleMoves population, and dice consumption tracking. - -## Game Creation Requirements - -Backgammon games MUST be created with exactly 2 players and ONLY 2 players are permitted: - -1. The POST /games endpoint requires `{ player1: { userId: "id1" }, player2: { userId: "id2" } }` in the request body -2. Both `player1.userId` and `player2.userId` are required and must be different -3. There is NO addPlayer endpoint - players cannot be added after game creation -4. Use `api.games.start(player1Id, player2Id)` not `api.games.create()` for creating games with players -5. The `api.games.create()` method (no parameters) is invalid and will result in 400 errors - -This ensures all games have the required two players from creation and prevents incomplete game states. diff --git a/.cursor/rules/coding-standards.md b/.cursor/rules/coding-standards.md deleted file mode 100644 index e476591..0000000 --- a/.cursor/rules/coding-standards.md +++ /dev/null @@ -1,56 +0,0 @@ -# Coding Standards and Best Practices - -## Architecture and Separation of Concerns - -### Game Logic Separation - -ALL game logic must reside in core. The API layer should ONLY: - -1. Accept information about current state and proposed state changes -2. Pass these to core for validation and execution -3. Return results or errors from core -4. Handle persistence and API concerns - -Never implement game rules, move validation, or game state logic in the API layer. This separation ensures consistency and testability. - -### API Client Usage - -ALWAYS use the configured apiClient (`api.*` methods) instead of raw fetch() calls in the frontend: - -1. Use `api.games.*` for all game-related operations (create, start, roll, move, etc.) -2. Use `api.users.*` for all user-related operations -3. Never use raw `fetch()` calls to the backend API endpoints -4. The apiClient handles authentication, error handling, and consistent request formatting -5. This ensures type safety and consistent error handling across the application - -Example: Use `api.games.rollForStart(gameId)` not `fetch('/games/${gameId}/roll-for-start')` - -## Type Safety and Dependencies - -### Official Types Package - -ALWAYS use types from `@nodots-llc/backgammon-types` package - NEVER redefine local types: - -1. Import all game-related types from `@nodots-llc/backgammon-types` -2. Use `BackgammonGame`, `BackgammonPlayer`, `BackgammonBoard`, etc. from the official package -3. NEVER create local interfaces that duplicate package types (e.g., don't create `GameState` when `BackgammonGame` exists) -4. Use package types for all API responses, state management, and type annotations -5. Only create local interfaces for UI-specific state that doesn't exist in the package -6. This ensures type consistency between frontend, backend, and prevents state transition bugs - -Example: Use `BackgammonGame` not local `GameState` interface - -## Programming Style - -### Functional Programming Over Imperative - -Avoid if/then statements when possible - they are code smell in functional programming: - -1. Use early returns instead of nested if/else chains -2. Prefer switch statements with early returns for state machines -3. Use ternary operators for simple conditional assignments -4. Leverage array methods (.map, .filter, .find, .some, .every) over imperative loops -5. Use object/map lookups instead of long if/else chains -6. Extract complex conditions into well-named boolean variables or functions - -Example: `const isValidMove = dice.includes(dieValue) && !isBlocked` instead of nested ifs diff --git a/.cursor/rules/development-workflow.md b/.cursor/rules/development-workflow.md deleted file mode 100644 index 9091ee9..0000000 --- a/.cursor/rules/development-workflow.md +++ /dev/null @@ -1,64 +0,0 @@ -# Development Workflow Rules - -## Communication - -### Stuck Detection - -If I spend more than 2 minutes on infrastructure issues, debugging environment problems, or repeatedly failing at the same task without making progress toward the user's actual goal, I MUST notify the user immediately with: - -- "โš ๏ธ **I'M STUCK**: [brief description of what I'm stuck on]" -- "๐ŸŽฏ **SUGGESTED APPROACH**: [alternative approach]" -- "โ“ **USER INPUT NEEDED**: [what decision or help I need]" - -This prevents wasting time on tangential issues and keeps focus on the main objective. - -## Testing and Quality Assurance - -### Write the Failing Test First - -The test is written before the fix and must fail against the pre-change tree, then pass after. A test written against already-fixed code proves the code runs, not that the bug is gone. Every bug fix ships a regression fixture built from the real failing input โ€” the production position ID or payload, not an approximation of one. - -Never gate a test behind an environment flag nothing sets: a suite that has never executed is not a gate. Read the skip count as a finding โ€” this package's suites differ by machine (the CI runner passes the native addon suites and skips the gnubg-binary suites; the Linux box is the reverse), so neither environment runs everything and no single run justifies a coverage claim. - -TypeScript compilation errors in tests are test failures. Fix them, never exclude them. - -### Declared Dependency Ranges - -Code using a new `@nodots/backgammon-types` symbol needs the declared **range** bumped, not just a lockfile refresh. A range that still satisfies the old locked version means npm never moves, `npm ci` obeys the lock, and CI dies in `tsc` while developer machines pass on a hand-refreshed tree. This package's `development` branch was red for three days in July 2026 for exactly this reason. `npm install --package-lock-only` cannot fix it โ€” change the range. - -### Test Requirements - -All tests must pass before reporting that a task is completed. If any tests fail after implementing changes, iterate on the solution until all tests pass. Run the test suite and fix any failures before considering the task done. - -### Bug Status Clarity - -When reporting on bugs, be explicitly clear about the current status using these exact terms: - -- "๐Ÿ” **BUG DISCOVERED**" - when a bug has been found and documented but not yet fixed -- "๐Ÿ”ง **BUG FIXED**" - when a bug has been resolved and verified through testing -- "๐Ÿงช **BUG INVESTIGATION**" - when actively debugging but root cause not yet identified -- "โœ… **BUG VERIFIED RESOLVED**" - when fix has been tested and confirmed working - -Never use ambiguous language that could confuse discovery with resolution. - -## Environment Management - -### API Server Management - -ALWAYS kill existing API server processes before starting the server. Multiple running instances cause port conflicts and unpredictable behavior. Before starting the API server: - -1. Navigate to `api` directory -2. Run `npm run kill-port` to kill processes on port 3000 (uses the package.json script) -3. Check for any remaining ts-node/nodemon processes with `ps aux | grep -E "(ts-node|nodemon)" | grep -v grep` -4. Kill any remaining processes if found -5. Start the server with `npm start` (not npm run dev - that script doesn't exist) - -This prevents port conflicts, ensures clean server state, and avoids multiple concurrent API instances that can cause simulation hangs. - -### Directory Verification - -ALWAYS verify the current directory before running terminal commands. Use `pwd` or check the last terminal cwd to ensure you're in the correct directory (e.g., api for API commands, core for core commands). If in the wrong directory, navigate to the correct one before executing commands. This prevents file not found errors and ensures commands run in the intended context. - -## API Server Information - -The API server routes are `:/api/v1/`