houserules/docs/PHASES.md

Project Phases

Phase 0 — Specification Lock

In-scope deliverables:

• packages/rete/SPEC.md — engine semantics (10 sections)
• docs/PHASES.md — this document
• packages/chess/RULES.md — 15 preset custom rules with compat matrix
• packages/server/PROTOCOL.md — WebSocket protocol v1 (8+ message types)
• Monorepo scaffold: Bun workspaces, tsconfig base, eslint flat config, vitest workspace, playwright config, lefthook pre-commit hook, GitHub Actions CI
• Three package skeletons: packages/rete, packages/chess, packages/server

Acceptance gate (executable):

test -f packages/rete/SPEC.md && test -f docs/PHASES.md && test -f packages/chess/RULES.md && test -f packages/server/PROTOCOL.md
bun install && bun run check  # exits 0
gh run list --limit 1 --json conclusion -q '.[0].conclusion'  # "success"

Must NOT have in this phase: any engine implementation, any chess rules, any UI, any server logic.

Phase 1 — Pararules Parity

In-scope deliverables:

• packages/rete/src/schema.ts — typed EAV schema + Fact type
• packages/rete/src/wm.ts — WorkingMemory with deterministic iteration
• packages/rete/src/alpha.ts — AlphaNetwork + AlphaMemory with inverted-index dispatch
• packages/rete/src/session.ts — Session lifecycle (init, add, insert, retract, fireRules)
• packages/rete/src/builder.ts — Typed rule builder + v() variable helper
• packages/rete/src/registry.ts — HandlerRegistry + PredicateRegistry
• packages/rete/src/serialize.ts — JSON round-trip serialization (RULE_SCHEMA_V1)
• packages/rete/src/beta.ts — BetaMemory + Token propagation
• packages/rete/src/join.ts — JoinNode with variable-binding equality tests
• packages/rete/src/condition.ts — FilterNode with registered predicates
• packages/rete/src/query.ts — query() / queryAll() API
• packages/rete/src/derived.ts — thenFinally + truth maintenance
• packages/rete/src/cycle.ts — RecursionLimitExceededError + recursion counter
• packages/rete/src/conflict.ts — deterministic activation ordering
• packages/rete/tests/golden/ — pararules golden-file test port (5-10 tests)
• tsup build output: packages/rete/dist/ with ESM + CJS + .d.ts

Acceptance gate:

bun test packages/rete  # all green
bun run test:coverage -- packages/rete  # ≥90% line coverage
bun run check  # exits 0
git tag v0.1.0-phase1  # after gate passes

Must NOT have: negation nodes, NCC, existential, aggregation (those are Phase 2).

Phase 2 — Rete II + Chess Engine

In-scope deliverables:

• packages/rete/src/negation.ts — NegationNode (NOT)
• packages/rete/src/existential.ts — ExistentialNode (EXISTS)
• packages/rete/src/ncc.ts — NccNode (not-count-condition)
• packages/rete/src/aggregate.ts — AggregationNode (count/sum/collect/min/max)
• packages/chess/src/schema.ts — chess attribute schema (piece types, squares, colors)
• packages/chess/src/coord.ts — square coordinate helpers
• packages/chess/src/starting-position.ts — FIDE starting position fact generator
• packages/chess/src/rules/ — all FIDE chess rules as Rete productions:
  • primitives.ts, pawn.ts, knight.ts, sliding.ts, king.ts, turn.ts, capture.ts
  • castling.ts, enpassant.ts, promotion.ts, check.ts
  • checkmate.ts, stalemate.ts, draws.ts, insufficient.ts
• packages/chess/src/pgn.ts — minimal SAN parser (no external dep)
• packages/chess/tests/fide-games/ — 5 classic game PGN fixtures + replay tests

Acceptance gate:

bun test packages/rete  # Rete II nodes green
bun test packages/chess/tests/fide-games  # 5 games replay to completion
bun run check  # exits 0
git tag v0.2.0-phase2

Must NOT have: time-travel, UI, localStorage, server, presets, Playwright.

Phase 3 — Time-Travel + Presets + UI

In-scope deliverables:

• packages/rete/src/eventlog.ts — append-only event log with monotonic seq
• packages/rete/src/snapshot.ts — Immer snapshots every N ticks
• packages/rete/src/replay.ts — replay engine + stateHash() determinism verifier
• scripts/replay-determinism.ts — CI replay verifier script
• packages/chess/src/presets/ — all 15 preset rules with registry
• packages/chess/src/ui/ — React + Vite chess app:
  • Board.tsx, Rules.tsx, SavePanel.tsx, ImportExport.tsx
• packages/chess/src/persist/ — autosave.ts + io.ts
• packages/chess/e2e/full-flow.spec.ts — end-to-end UI scenario

Acceptance gate:

bun run playwright test packages/chess/e2e/full-flow.spec.ts  # green
bun run scripts/replay-determinism.ts  # all hashes match
bun run check  # exits 0
git tag v0.3.0-phase3

Must NOT have: WebSocket server, multiplayer, networked rooms.

Phase 4 — Authoritative Multiplayer

In-scope deliverables:

• packages/server/src/index.ts — Bun HTTP+WS server
• packages/server/src/protocol.ts — zod message schemas
• packages/server/src/rooms.ts — RoomRegistry (6-char codes)
• packages/server/src/middleware.ts — rate limiting, origin allow-list, 64KB cap
• packages/server/src/game-session.ts — authoritative engine session per room
• packages/server/src/broadcast.ts — move validation + fact-delta broadcast
• packages/server/src/reconnect.ts — 60s grace reconnection
• packages/server/src/logging.ts — pino + Prometheus metrics
• packages/chess/src/net/client.ts — WS client with reconnect + seq ack
• packages/chess/src/net/prediction.ts — client prediction + reconciliation
• packages/chess/src/ui/Lobby.tsx — room create/join UI
• packages/chess/e2e/multiplayer.spec.ts — two-browser multiplayer scenario
• scripts/ws-client.ts — scripted WS client for integration tests

Acceptance gate:

bun run playwright test packages/chess/e2e/multiplayer.spec.ts  # green
bun run test:integration  # WebSocket handshake + move exchange + reconnect
bun run check  # exits 0
git tag v0.4.0-phase4

Must NOT have: spectators, AI opponent, server-side persistence across restart, mid-game rule toggle, accounts.

Non-Goals (v1)

The following are explicitly out of scope for v1. Any agent that adds these will be considered scope-creep:

• Chess AI (Stockfish, minimax, MCTS, opening books)
• Puzzles, tutorials, analysis mode, engine evaluation
• ELO rating, matchmaking, tournaments, leaderboards
• Social features: chat, emotes, friend lists, profiles, avatars
• Rule marketplace, remote rule repository, user-authored JS rule upload
• Mid-game rule toggle (toggle only allowed between games)
• Spectators (2-player rooms only in v1)
• Server-side game persistence across server restart
• Mobile-native clients (responsive web only, no React Native / Capacitor)
• User accounts, OAuth, email/password, session tokens, analytics
• Telemetry, crash reporting, A/B testing, feature flags
• Internationalization (i18n), accessibility beyond keyboard-playable chess
• Additional games on the engine (no "build another game as proof")
• Visual rule editor / node graph editor (preset toggle only)
• Pararules Nim macro equivalents via runtime code-gen or eval
• External Rete library dependency (greenfield)
• chess.js or any hardcoded FIDE chess library
• Stockfish.wasm or any external chess engine
• Persistent user data beyond localStorage

Performance Budgets

These are contractual. CI enforces bundle size. Unit tests enforce microsecond budgets.

Metric	Budget	Enforcement
session.insert(fact)	< 0.5ms @ 10,000 facts	Vitest benchmark
session.fireRules()	< 5ms for chess ruleset (64 rules, ~100 facts)	Vitest benchmark
Replay 1,000 events	< 500ms	scripts/replay-determinism.ts
Alpha dispatch 10,000 inserts	< 50ms	Alpha network benchmark test
3-condition join on 100 entities	< 10ms	Join benchmark test
1,000 Immer snapshots memory	< 10MB (structural sharing)	Snapshot memory test
Engine bundle (@paratype/rete)	< 50KB min+gzip	size-limit in CI
Chess bundle (@paratype/chess)	< 200KB min+gzip	size-limit in CI
Server broadcast p99 latency	< 50ms per delta	Server integration test

Demo Scenarios

One scripted demo per phase that proves the phase deliverable works end-to-end.

Phase 0 Demo: Specs and scaffold exist.

bun install && bun run check  # exits 0 with zero errors
cat packages/rete/SPEC.md | grep '^## ' | wc -l  # outputs 10
cat packages/chess/RULES.md | grep '^### ' | wc -l  # outputs 15
cat packages/server/PROTOCOL.md | grep '^### Message:' | wc -l  # outputs ≥8

Phase 1 Demo: Run pararules golden test suite.

bun test packages/rete/tests/golden  # all green
bun run test:coverage -- packages/rete  # "All files | XX% | ... " with ≥90% line

Phase 2 Demo: Replay Kasparov vs Topalov 1999 (27 moves to spectacular win).

bun test packages/chess/tests/fide-games/kasparov-topalov-1999.test.ts
# Output: "Kasparov vs Topalov: all 27 moves legal, checkmate detected ✓"

Phase 3 Demo: Full UI flow.

bun run dev --filter @paratype/chess &
bun x playwright test packages/chess/e2e/full-flow.spec.ts --headed  # watch in browser

Phase 4 Demo: Two-browser multiplayer with reconnect.

bun run start:server &
bun x playwright test packages/chess/e2e/multiplayer.spec.ts --headed  # watch two windows play