claude (blind_chess)
729199097e
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>
56 lines
4.5 KiB
Markdown
56 lines
4.5 KiB
Markdown
# 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.
|