suaveplan/openspec/archive/2026-05-24-game-server-matchmaking/tasks.md

Tasks: Wave B-5a game-server matchmaking

0. Pre-flight

• pwd && git worktree list && git status — confirm isolated worktree.
• Confirm worktree HEAD is descended from genesis tip (Wave A + B-1/3/4 merged).
• Read CLAUDE.md, openspec/AGENTS.md, existing src/core, src/errors, src/types.
• Read upstream reference: /mnt/s/web/suaveplan/packages/universal/game-server/src/matchmaking/{MatchmakingEngine,QueueManager,SpectatorManager,skill-matcher,winner-stays-on}.ts.

1. Error registry

• Append eight matchmaking codes to GAME_SERVER_CODES (MATCHMAKING_QUEUE_FULL, INVALID_QUEUE_REQUEST, INVALID_MATCH_CRITERIA, NO_MATCH_FOUND, INVALID_SKILL_SCORE, SPECTATOR_LIMIT_REACHED, INVALID_SPECTATOR_REQUEST, UNKNOWN_MATCHING_ALGORITHM).
• Extend game-server-error.test.ts with assertions on the new codes.
• Update game-server-error.md to enumerate the new codes.

2. winner-stays-on

• winner-stays-on.types.ts — WinnerStaysOnConfig, WinnerStaysOnStats, Zod config schema.
• winner-stays-on.ts — recordResult/addChallenger/ nextChallenger/forceRotateChampion/reset/getStats, two OTel counters, typed-error boundary.
• winner-stays-on.test.ts — 100% coverage incl. error paths.
• winner-stays-on.md — six sections, ≥200 words.
• index.ts barrel.

3. skill-matcher

• skill-matcher.types.ts — SkillEntry, SkillMatcherConfig, SkillScoringFn, Zod schemas.
• skill-matcher.ts — findMatch/effectiveRange, pluggable scoring, injectable Clock/Rng, OTel counter + histogram.
• skill-matcher.test.ts — 100% coverage incl. tie-break paths.
• skill-matcher.md — six sections, ≥200 words.
• index.ts barrel.

4. queue-manager

• queue-manager.types.ts — QueueRequest, QueueConfig, QueueStats, Zod schemas.
• queue-manager.ts — addToQueue/removeFromQueue/findMatch/ getQueueSize/getQueuePosition/getStats/clear, four OTel instruments, typed-error boundary.
• queue-manager.test.ts — 100% coverage incl. cap rejection + wait-time priority.
• queue-manager.md — six sections, ≥200 words.
• index.ts barrel.

5. spectator-manager

• spectator-manager.types.ts — Spectator, SpectatorPermissions, SpectatorManagerConfig, Zod schemas.
• spectator-manager.ts — addSpectator/removeSpectator/ removeAllSpectators/getters, three OTel counters, typed-error boundary, optional join/leave listeners.
• spectator-manager.test.ts — 100% coverage incl. cap rejection + duplicate spectator rejection.
• spectator-manager.md — six sections, ≥200 words.
• index.ts barrel.

6. matchmaking-engine

• matchmaking-engine.types.ts — Match, MatchCriteria, MatchingAlgorithm, Zod schemas.
• matchmaking-engine.ts — createMatch (quick / skill-based) + createMatchFromQueue (drain with max→min fallback) + getMatch / removeMatch / dispose, three OTel instruments, injectable IdGenerator/Clock/Rng, optional onMatchFound callback.
• matchmaking-engine.test.ts — 100% coverage incl. unknown algorithm + invalid criteria + skill-range edge cases.
• matchmaking-engine.md — six sections, ≥200 words.
• index.ts barrel.

7. Wiring

• Re-export every public surface from src/index.ts.
• Add subpath exports to package.json for each module.

8. Verification

• bunx turbo lint typecheck test --filter=@suaveplan/game-server green.
• bunx turbo test:coverage --filter=@suaveplan/game-server = 100/100/100/100.
• grep -rnE "from ['\"](vitest|bun:test)['\"]" packages/gaming/games/game-server/src/ → zero output.
• grep -rn "biome-ignore|TODO|FIXME|XXX" packages/gaming/games/game-server/src/matchmaking → zero output.
• All source files ≤300 lines; all test files ≤500 lines.
• bun run docs:check reports 100% coverage.