Files

T

claude (blind_chess) 729199097e docs: log AI-player spec approval, update context, add handoff

Updates CLAUDE.md "Current State" + "Key files" to point at the new spec.
Adds DECISIONS.md "AI / computer player" section (11 settled decisions).
Strikes through the prior "Client-side AI / hint generation — out of scope"
row with a "partially superseded" note: the reversal applies only to the
human-vs-AI path. Adds 7 new Deferred/Rejected rows for AI-feature scope.

Handoff at .claude/handoffs/2026-04-28-170713-ai-player-spec.md captures
session state for the next pickup (writing-plans → Phase 1 implementation).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-28 13:12:04 -04:00

4.5 KiB

Raw Blame History

blind_chess

Web-based two-player chess where each player sees only their own pieces; the server acts as moderator.

Start Here

Read the latest handoff first: .claude/handoffs/ (most recent file).

Then check DECISIONS.md for settled choices, and the design specs:

docs/superpowers/specs/2026-04-28-blind-chess-design.md — original MVP spec (data model, protocol, FSM, testing).
docs/superpowers/specs/2026-04-28-ai-player-design.md — AI/computer player spec (Casual + gemma4 recon bots, two-phase plan).

Project Identity

A digitization of a battleship-style chess variant. Two players, separated; a moderator who sees both boards and announces a fixed vocabulary of events ("Black has moved and captured", "Moving that piece will not help you", "White is in check"). The physical version requires three people; this version replaces the moderator with a server. Ships with both vanilla mode (full reveal — normal chess) and blind mode (the variation) on day one. Mode is a per-player view filter on a shared engine, not a different game.

The system's most distinctive property: highlighting in blind mode reveals zero opponent information. It's computed purely from (piece type, position, own-piece set) — a function whose signature literally cannot read opponent state. The moderator vocabulary is the only legitimate channel for opponent events.

Current State

Phase: MVP deployed and live at https://chess.sethpc.xyz (2026-04-28). AI/computer player feature spec written and approved (2026-04-28); implementation pending.
Repo: git.sethpc.xyz/Seth/blind_chess.
Stack: Node 22 + TypeScript, Fastify + ws, Svelte 5 + Vite, chess.js. pnpm workspace with packages/{server,client,shared}.
Deploy: LXC CT 690 on node-241 at 192.168.0.245, behind Caddy CT 600. Systemd unit blind-chess.service, port 3000. In-memory state only.
Tests: 43 passing — 21 in shared (geometric helper), 22 in server (FSM + view + 4 real-WS integration).
Known gaps (deferred): drag-and-drop input (click-to-move only), full integration coverage of every endgame path, mobile-specific polish, observability beyond /api/health.
AI player (designed, not built): Two-phase plan in docs/superpowers/specs/2026-04-28-ai-player-design.md. Phase 1 = Casual bot (algorithmic, ~200 LoC). Phase 2 = gemma4 recon bot (gemma4:26b chat agent on steel141 RTX 3090 Ti primary, pve197 V100 fallback). Bots play through the same view filter and FSM as humans — no oracle access.

Key files

IDEA.md — original project brief (Seth's words)
DECISIONS.md — locked architectural and gameplay decisions
docs/superpowers/specs/2026-04-28-blind-chess-design.md — full design spec (data model, protocol, FSM, testing)
docs/superpowers/specs/2026-04-28-ai-player-design.md — AI/computer player spec (Casual + gemma4 recon, two-phase plan, endpoint priority list, acceptance bars)
packages/shared/src/geometric.ts — the zero-leak helper. The signature is the proof.
packages/server/src/view.ts — buildView, the security boundary.
packages/server/src/commit.ts — touch-move FSM (the spec's hierarchy decision table).
packages/server/src/translator.ts — chess.js Move → moderator-vocabulary enum.
deploy/blind-chess.service — systemd unit (canonical at /etc/systemd/system/blind-chess.service on the CT).
deploy/Caddyfile.snippet — block already added to /etc/caddy/Caddyfile on CT 600.

Operations

Logs: ssh root@192.168.0.245 'journalctl -u blind-chess -f'
Restart: ssh root@192.168.0.245 'systemctl restart blind-chess'
Health: curl https://chess.sethpc.xyz/api/health
Deploy update: pnpm -r build → pnpm --filter @blind-chess/server deploy --prod --legacy .deploy-server → rsync server bundle to /opt/blind-chess/server/ and client dist/ to /opt/blind-chess/client/dist/ → chown -R blindchess:blindchess /opt/blind-chess → systemctl restart blind-chess. Server restart drops in-memory games (acceptable for MVP).

Conventions

Inherits global homelab conventions from ~/bin/CLAUDE.md (gitea CLI, conventional commits, .claude/handoffs/ for session state).
pnpm workspace; do not use npm/yarn lockfiles.
All inter-package types live in packages/shared/. Never duplicate protocol types in client or server.
Server is the single authority on game state. Client commit messages are requests, not facts.
The view filter (buildView) is the only egress for board state. Don't bypass it.

4.5 KiB Raw Blame History