undercooked/.agents/PLAN.md

PLAN.md — Undercooked (master design, LOCKED)

Type: real-time multiplayer web game (in-browser, cooperative) Working title: Undercooked — an independent Overcooked-style homage Status: design locked, implementation begins at phase 01

---

1. Vision

One browser tab is enough to start playing: open the site, create a lobby, read the 5-character code out loud to your friends, hit Start, and cook together. No signup, no download, no install, no email. Each player's phone or laptop is one cook; the kitchen is shared and authoritative on the server. A campaign of ~10 hand-authored levels ratchets the pressure — more recipes, fewer stations, hostile floors — and an endless mode keeps the escalation going after the campaign ends.

The one thing a user does on day one: create/join a lobby by code and finish level 1 with 2+ other people, seeing each other's cooks move with no perceptible lag.

Success criteria (v1)

1. 4 players on 4 devices complete level 1 of a lobby in one sitting, no page reloads.
2. Creating a lobby, sharing the code, and joining takes < 20 seconds end to end.
3. A player who closes their laptop and returns mid-round rejoins and keeps playing.
4. All 10 campaign levels load, validate as solvable, and are measurably harder than their predecessor by the difficulty metrics in §8.
5. Full test suite passes; the game survives a 200-room stress run on one node.

Non-goals for v1

Accounts, auth, payments, persistent accounts/friend lists, matchmaking with strangers, cross-node scaling, mobile-native apps, voice/chat (text-free emotes only), level editor UI, gamepads, internationalization, ranked/online leaderboards.

---

2. Assumptions

1. Sessions are short (a round is 60–180 s) and rooms are small (≤ 4 players), so a single asyncio process can hold thousands of rooms with a 20 Hz tick each.
2. Anonymous is a feature, not a fallback. Losing progress on server restart is acceptable; therefore no database is required (user-approved, §3).
3. Browser is the only client. Desktop keyboard and touch are both first-class; the client must degrade gracefully on a 360 px-wide phone.
4. Art is ours. Simple vector shapes/sprites generated in-repo; no third-party asset packs, no CDN fonts.
5. Trust model: players are guests on our server, potentially hostile. The server validates everything; nothing client-reported is authoritative.
6. Python is fast enough for a 20 Hz tick over ≤ 4 players + ≤ 60 entities (≈ 0.5–2 ms CPU per room per tick). The perf budget in §10 protects this; if a room misses budget, it drops to a lower tick rate rather than changing the stack.

---

3. Architectural Anchors (LOCKED DECISIONS)

#	Component	Decision	Rationale	Status
A1	Language / tooling	Python ≥ 3.12, uv for env + run	Project standard; uv sync/uv run everywhere	LOCKED
A2	Web framework	FastAPI + uvicorn (uvicorn[standard])	Async-native, first-class WebSocket support, Pydantic integration	LOCKED
A3	Realtime transport	Native WebSocket (/ws/{room_code}), JSON frames	Lowest-latency simple option; no polling fallback needed for a game. Socket.IO rejected: extra abstraction, no benefit	LOCKED
A4	Simulation authority	Server-authoritative fixed-tick sim at 20 Hz; snapshots out, inputs in; client interpolation + local prediction	Single source of truth (anti-cheat, no drift), reconnectable, testable headless	LOCKED
A5	Sim purity	src/undercooked/sim/ has zero I/O, asyncio, wall-clock, or unseeded random; step(state, dt) is a pure function	Enables headless determinism tests and frame-rate-independent logic	LOCKED
A6	Persistence	None. Rooms live in the supervisor's memory; results/session scoreboards in memory. No Postgres, no SQLite, no ORM, no Alembic, no Redis	Anonymous, ephemeral by design; user explicitly chose this over the default Postgres rigour	LOCKED (user-approved deviation)
A7	Cache / queue	None (single process, in-process asyncio tasks)	Multi-node fan-out is a v2 concern; adding Valkey now buys nothing	LOCKED
A8	Content format	Data-driven levels + recipes as YAML in levels/, parsed into Pydantic models and validated at startup	No hard-coded content lists; new levels require no Python change	LOCKED
A9	Client rendering	Canvas 2D, requestAnimationFrame, DPR-aware	Smooth motion between snapshots; DOM tiles stutter with many moving entities	LOCKED
A10	Client code	Vanilla ES modules, no bundler, no framework	Zero build step, debuggable in the browser, satisfies the no-CDN rule trivially	LOCKED
A11	Art	In-repo generated SVG tileset/sprites + CSS; system font stack	Portable, tiny, no external fonts/CDN	LOCKED
A12	No external CDNs	Every asset served from app/static/; CSP default-src 'self' ws: wss:; enforced by a test	Project rule; also removes a privacy and availability risk	LOCKED
A13	Test stack	pytest (+pytest-asyncio) for unit/integration/sim; Playwright for E2E, one suite per user story, multi-context for multiplayer	Stories are the delivery unit; two browser contexts = two real players	LOCKED
A14	Protocol	Versioned JSON messages (p protocol int, type discriminator) documented in docs/PROTOCOL.md; server rejects unknown versions/major mismatch	Debuggable, testable, forward-compatible	LOCKED
A15	Lobby codes	5 chars, Crockford base32 (no I L O U), server-generated, collision-checked, ~33 M space	Shoutable out loud, quick to type on a phone	LOCKED
A16	Player identity	secrets.token_urlsafe(24) token per browser tab in sessionStorage; display name optional, sanitized, non-unique	Anonymous, rejoinable, no PII	LOCKED
A17	Config	Env vars (UNDERCOOKED_*) + .env via python-dotenv; typed config.py; no hard-coded paths/ports	Deployable, testable	LOCKED
A18	Debugging	debugpy gated by DEBUGPY=1 (non-blocking listen on DEBUGPY_PORT)	Real-time server is hard to debug by printing	LOCKED
A19	Packaging	Multi-stage Containerfile (slim runtime, non-root) + compose.yaml (app only, no DB)	Single-artifact deploy	LOCKED
A20	Quality gate	ruff + pyright + pytest with >90% coverage on new/changed code; full suite green before any phase completes	Project standard	LOCKED
A21	Determinism harness	Input scripts + seed replay to a golden state hash (tests/sim/test_replay_*.py)	Proves A4/A5 and makes balance regressions cheap to catch	LOCKED
A22	Lint/format targets	pyproject.toml [tool.ruff], [tool.pyright], [tool.pytest.ini_options] as scaffolded	One source of truth for checks	LOCKED

Anything not in this table is fair game to choose within an existing anchor. Using a new dependency, service, protocol, or framework requires explicit user permission, recorded in the phase's 00_phase.md and appended to this table by the user.

---

4. High-level architecture

            browser (player)                        server (one asyncio process)
 ┌───────────────────────────────────┐   WS    ┌──────────────────────────────────────┐
 │ app/static/js                      │         │ server/app.py         FastAPI app     │
 │  app.js        screen state mach.  │═══════▶ │  ├─ /            index.html          │
 │  net/connection.js  WS + backoff   │  JSON   │  ├─ /static/*    ES modules, SVG     │
 │  net/predict.js     local predict  │◀═══════ │  ├─ /healthz /api/levels /api/rooms  │
 │  net/snapshots.js   buffer+lerp    │ frames  │  └─ /ws/{code}   ws endpoint         │
 │  input/keyboard.js|touch.js        │         │        │                             │
 │  render/canvas.js  layers, camera  │         │ server/protocol.py  msg models+valid. │
 │  render/hud.js     score/time/orders│        │ server/room.py      Room + FSM       │
 │  ui/…              lobby/result DOM│         │        │ 20 Hz tick task             │
 └───────────────────────────────────┘         │ server/rooms.py     RoomSupervisor   │
                                               │ server/sessions.py  in-memory runs   │
                                               │        │                             │
                                               │ sim/*  pure simulation kernel        │
                                               │ levels/*.yaml → sim/level.py         │
                                               └──────────────────────────────────────┘
                                                       (no database, no external calls)

Component responsibilities

Component	Owns	Never does
sim/	game truth: state, step(), interactions, scoring, hazards	network, HTTP, time, randomness outside round seed
sim/level.py + sim/validation.py	YAML → typed LevelDef; reachability/solvability validation	simulation stepping
server/room.py	one match: player seats, FSM, tick loop, snapshot/event emission, rejoin seats	routing, HTTP, cross-room logic
server/rooms.py	room registry, code issuance/collision, capacity, GC of idle rooms	game rules
server/protocol.py	message models, per-state whitelists, inbound validation, framing caps	game rules
server/sessions.py	in-memory records: completed rounds, best scores per session token	durable storage
server/app.py	FastAPI factory, static files, headers/CSP, startup level validation	game rules
client net/	connection lifecycle, snapshot buffer, interpolation, prediction/reconciliation	deciding anything
client render/	drawing, camera, HUD, effects	mutating game state

Data flow (one tick, 20 Hz)

1. Each connected client sends at most one input per frame: {seq, move:{x,y}, act, face} — only on change, plus a keep-alive at ≥ 5 Hz.
2. protocol.py validates shape, size, rate, and legality for the room's state; stale seq is dropped; illegal moves are clamped, never trusted.
3. room.tick() applies queued inputs to the sim, then sim.step(state, dt) advances physics, station timers, order spawning, hazards, and win/loss checks.
4. The sim returns (state, events); events are transient FX/log lines (chopped, burnt, served, order_missed, fire_started, score, …).
5. The room builds a snapshot (compacted: entities quantized to 1/64 tile, station arrays, order list, score/timer) and pushes snap frames to players at SNAPSHOT_HZ and to spectators at half that; events ride along with the frame.
6. Client buffers snapshots and renders at now − 100 ms, interpolating between the two bracketing snapshots; own player is additionally dead-reckoned from local input and reconciled when a snapshot contradicts it.

Snapshot content (contract, compact)

{ "t": 4821, "p": [ { "i":"ab12", "x":12.34, "y":8.06, "f":2, "h":"tomato_chopped",
                     "s":"move", "pi":0 } ],
  "st":[ {"k":"chop","x":3,"y":2,"g":"onion","q":6,"p":0.42,"s":1} ],
  "o": [ {"id":17,"r":"soup","l":0.63,"pts":40} ],
  "s": 120, "tgt": 140, "tl": 83.65, "hz": [ {"t":"fire","x":7,"y":5,"l":0.8} ],
  "e": [ {"k":"served","x":9,"y":1,"i":17} ] }

Quantization: positions are floats rounded to 2 decimals on the wire, progress to 2 decimals — enough for smooth interpolation, small enough to keep frames ≈ 300–900 B.

---

5. Simulation model (pure)

Entity/state types (sim/model.py)

• Vec2, Facing (up/right/down/left), TileKind (FLOOR, COUNTER, WALL, VOID)
• StationKind (SPAWN_SHELF, CHOP_BOARD, STOVE, POT, PREP, SERVE, SINK, TRASH)
• Station — position, kind, contents (list[Item]), progress, state (idle|working|ready|burning|dirty|blocked), per-station cooldown
• Item — kind (tomato|onion|lettuce|dough|patty|rice|fish|…), form (raw|chopped|cooking|cooked|burnt|plated|dirty), quality (1.0 → 0.0 as it burns), ttl
• Player — id, pos, vel, facing, carrying (Item|None), action state, state (idle|moving|using|stunned), stun, score_share, connected
• Order — id, recipe id, deadline, time_left, value
• Hazard — fire|spill|moving_obstacle, pos, life, path/period for movers
• KitchenState — level id, seed, tick, grid, stations, players, items, orders, hazards, score, target, time_left, result (None|won|lost), counters, rng state

Movement

Continuous positions in tile units, velocity from the input vector, radius 0.35 tile, axis-separated AABB resolution against blocked tiles, other players (soft push, mass 1), and carried items. Max speed 3.5 tiles/s, accel 30 tiles/s², no diagonal speed boost. Void tiles are lethal to movement (blocked, not falling — v1 keeps it simple); a moving_obstacle occupies tiles it passes over and stuns on contact (0.6 s).

Interaction model

One action button. interact(state, player) resolves against, in priority order:

1. carrying → drop/transfer onto target station (throwing is out of scope v1),
2. station in reach (1 tile in front, then radius 0.6): pick item, start work, place item, plate, serve, wash, trash (long-press),
3. nothing → short "empty" event (client plays a whiff).

Two-hand rules: one carried item per player. Chopping requires holding act for the chop duration; taking a chopped item off the board requires the board to be ready. Contested targets resolve by earliest server-received input, tie-broken by player seat index; the loser gets denied (client shows a nudge) — never a silent no-op.

Station pipelines

Station	Input	Progress	Output
Spawn shelf	—	instant, infinite while orders need it	raw item
Chop board	raw	hold act ~0.9 s	chopped (rot raw in 20 s)
Stove + pot	chopped (soup) / raw (rice)	4–8 s	cooked → burnt after 8 s idle
Pan/griddle	raw patty/fish	5 s	cooked → burnt; can start fire
Prep/assemble	cooked/chopped + plate	per recipe	plated dish
Serve window	plated	instant match vs orders	score, quality bonus, streak
Sink	dirty plate/pot	1.2 s	clean (dirty stock caps available plates/pots)
Trash	any item	instant	gone (small score nudge −2)

Orders, scoring, results

• Orders spawn from the level's pool with concurrent and spawn_interval bounds.
• Serving a correct dish: base × quality × streak_mult × time_bonus. Wrong dish: rejection event, no score, order stays.
• Missed order (deadline 0): −order_penalty, streak reset, client shake.
• target_score reached → result=won immediately (with stars from remaining time); time_left == 0 → won if score ≥ target else lost.
• Per-player contribution is tracked for the result screen (display only, never competitive gatekeeping).

---

6. Lobby, rooms, and state machines

Room FSM (server/room.py)

LOBBY ──(host starts, ≥1 ready)──▶ COUNTDOWN(3s) ──▶ PLAYING
  ▲                                                    │
  │                                          result=won|lost|aborted
  │  next-level / retry                                ▼
  └──────────────(≤ 20 s auto, any host action)── ROUND_END
       │ ROUND_END ──(idle > lobby_idle_timeout)──▶ CLOSED (GC, seats freed)
       └ LOBBY ──(all seats empty > grace)────────▶ CLOSED

• LOBBY: joinable/leavable, ready flags, level pick (host; limited to unlocked), chat-free emotes only.
• COUNTDOWN: 3…2…1 broadcast; late joins wait in SPECTATING until LOBBY.
• PLAYING: inputs accepted from seated players; joiners become spectators; dropouts keep their seat (connected=false, sim keeps them idle 3 s then parks them).
• ROUND_END: results, unlocked-next-level state, retry/next/host-picked level.
• CLOSED: supervisor drops the room; tokens become invalid.

Supervisor rules

• Codes: Crockford base32, 5 chars, retried on collision; never reused within the process; the empty-lobby room is created on click, not on page load.
• Caps: max_players (4) per room, max_rooms (200) process-wide → 503 room_full.
• GC task every 5 s: close idle lobbies, evict orphaned rooms, purge stale seats.
• Every room owns exactly one asyncio tick task; task cancellation is the only teardown.
• Crash isolation: a room's tick exception is caught, logged, the room is marked aborted, players are told, and the rest of the server is unaffected.

Session records (server/sessions.py, in memory, bounded)

session_token → {display_name, unlocked_level, best[ level_id ] = {score, stars, completed_at}, rounds_played}. LRU-capped at 10 000 entries; wiped on process restart (acceptable per A6).

---

7. Wire protocol (docs/PROTOCOL.md)

Protocol version p: 1. Server closes the socket with code 4400 on major mismatch.

Direction	type	Payload	Accepted when
C→S	hello	{token?, name?, p}	connecting
C→S	ready	{}	LOBBY
C→S	set_level	{level}	LOBBY, host only, level unlocked
C→S	start	{}	LOBBY, host only
C→S	input	{seq, move:{x,y}, act, face}	PLAYING
C→S	emote	{id}	LOBBY, PLAYING
C→S	to_lobby / next_level	{}	ROUND_END
C→S	ping	{t}	always
S→C	welcome	{you, room, state, level, seats}	after hello
S→C	lobby	{seats[], level, host, can_start}	lobby-state changes
S→C	countdown	{n}	COUNTDOWN
S→C	snap	snapshot (§4)	PLAYING
S→C	round	{result, score, target, stars, unlocked, players[]}	ROUND_END
S→C	ev	[{k, …}] (FX/log)	any
S→C	err	{code, msg, seq?}	on rejection
S→C	pong	{t, now}	after ping

Inbound guards: max max_message_bytes; JSON-only; unknown type → err unknown_type (disconnect after 5); per-state whitelist; per-connection token bucket max_inputs_per_s; name sanitization (strip control chars, trim, 16 chars); one socket per token (second connection evicts the first).

---

8. Level content and the difficulty curve

levels/recipes.yaml defines ingredients and recipes; levels/NN_*.yaml defines each level. Every list the game reads comes from these files — the code never enumerates levels or recipes (validated by a test that adds a fixture level and expects it to appear in /api/levels).

id: 07_riverboat
name: Riverboat Galley
order: 7
time_limit: 100
target_score: 150
grid:                       # ASCII, one char per tile; '#'=wall '.'=floor …
  - "##############"
  - "#S..C..P....X#"
  - "#..==..==....#"
  - "#P1.2......ZZ#"
tiles: { "S": {kind: spawn_shelf, item: tomato}, "C": {kind: chop_board}, … }
spawns: [{x: 1, y: 9}, {x: 12, y: 9}]
orders:
  pool: [soup, salad, fried_rice]
  concurrent: 3
  spawn_interval: [7, 11]
  deadline: 42
hazards:
  - {type: fire, station: stove_2, chance_per_s: 0.02, extinguish: sink}
  - {type: spill, x: 6, y: 5, respawn_s: 25}
  - {type: moving_obstacle, path: [[4,3],[10,3]], period_s: 9}
station_limits: {plates: 3, pots: 2}
escalation_notes: "splits the kitchen; fire pressure without an extinguish shortcut"

Escalation axes (each campaign level must move ≥ 2 of them vs. its predecessor)

1. Recipe complexity — 1 → 4 ingredients, multi-station chains.
2. Order pressure — concurrent 1 → 4, spawn_interval 16 s → 6 s, deadline 60 → 30 s.
3. Time budget — time_limit 150 → 75 s against rising target_score.
4. Station scarcity — 1 shared stove for 4 players, limited plates/pots (dirty loop).
5. Layout hostility — open room → two halves → narrow bridges → void gaps.
6. Hazards — none → spills → fires → moving obstacles → order-spam "rush" waves.
7. Distance — ingredient ↔ cook ↔ serve travel 3 → 14 tiles.

Campaign: L1 tutorial (solo-friendly), L2 two orders, L3 chop+cook chain, L4 dirty-dish loop, L5 split kitchen, L6 fire, L7 boat + movers, L8 bridge/void, L9 rush waves, L10 gauntlet (all axes). Then endless: generated by sampling a difficulty scalar d = 10 + rounds against the same axes over the authored layouts.

Validation gate (undercooked-levels validate, also a test over every shipped level): ids unique; grid rectangular, spawns/stations on floor; every spawn, station, and serve window mutually reachable (BFS on walkable tiles, movers excluded); every recipe's ingredient reachable and every required station kind present; time_limit > 0; target_score ≤ theoretical_max_score × 0.6 (greedy plausibility: orders possible in the time window × mean order value); hazards reference existing stations; escalation axes actually increase between consecutive order values.

---

9. Validation / verification workflow (how we know it is right)

Layered, cheapest first — every phase runs the layers it touched, and the pipeline gate runs all of them:

1. Static: ruff check (lint incl. ASYNC, S, PERF), pyright.
2. Pure-sim unit tests: movement/collision, station state machines, recipe/serve resolution, scoring, hazards, validation rules — table-driven, no I/O.
3. Determinism/replay: seeded input script → N ticks → state hash compared to a golden file; a second run after a refactor must match bit-for-bit.
4. Room/protocol integration: in-process FastAPI + real WebSocket clients — create/join/ready/start/snap/round/rejoin, illegal-message rejection, rate limiting, 4-player full round, room GC.
5. Content gate: undercooked-levels validate over every YAML (fixture + shipped).
6. E2E per user story (Playwright): real browser, real sockets; multiplayer stories drive two browser contexts against the same room and assert both observe the same outcome (score, result, seats).
7. Netcode tests: server-side latency injection (UNDERCOOKED_SIM_LATENCY_MS=150), socket-kill mid-round + rejoin, prediction error bound assertions.
8. Scale/perf budget (marked slow): 200 rooms × 4 clients ticking 60 s — mean tick ≤ 2 ms/room, RSS growth < 20 %, zero missed ticks > 50 ms.
9. Doc & a11y pass: README/AGENTS reviewed project-wide; axe-core-free checks (contrast, focus order, aria-live result announcements) in the a11y story's suite.

A phase is Complete only when layers 1–5 relevant to its change pass and the entire suite is green with >90% coverage on new/modified code.

---

10. Performance and reliability budgets

Budget	Target	How measured
Server tick cost	mean ≤ 2 ms, p99 ≤ 8 ms (4 players)	room.tick timing histogram, stress test
Snapshot size	≤ 1.5 KB JSON	encoded-size assert in integration test
Downlink rate	≤ 60 KB/s per player	measured in integration test
Client frame time	≤ 16 ms at 4 players on a mid-tier laptop	Playwright performance.now() sampling
Input → visible echo	≤ 120 ms (incl. 100 ms interpolation)	netcode test
Room memory	≤ 1 MB per active room	RSS delta in stress test
Room capacity	≥ 200 concurrent rooms	stress test
Rejoin to playable	≤ 3 s after page load	e2e test

Degradation policy: if a tick exceeds budget, halve that room's effective tick rate for 5 s and emit ev{kind:"tick_slow"}; never drop players for lagging.

---

11. Security & privacy posture

• No PII collected; no cookies; no localStorage beyond the session token and last room code; no third-party requests at runtime (test-enforced).
• WebSocket: origin check (ALLOWED_ORIGINS, default same-host), message-size and rate limits, per-state whitelists, one socket per token, idle close.
• Room codes are unguessable-ish but are capability secrets: never logged with contents, and every server-side check assumes the code holder is a legitimate player and validates their actions, not their identity.
• Static serving: no directory listing, path traversal guarded by StaticFiles, X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer, CSP default-src 'self'; connect-src 'self' ws: wss:; img-src 'self' data:; style-src 'self'.
• No eval, no dynamic JS assembly from server strings, no user HTML rendering (names are rendered via textContent).

---

12. Roadmap (phases; details in .agents/phases/todo/)

#	Phase	Delivers (player-visible if shipped)
01	runnable_service_scaffold	uv run undercooked serves the shell page + /healthz; checks green
02	level_content_and_validation	level/recipe schema, loader, validator, 2 levels, undercooked-levels validate
03	simulation_movement_and_interaction	deterministic movement, reach, carry; replay hashes pinned
04	kitchen_pipeline_and_scoring	full cook chain, orders, scoring, win/lose; headless round sim
05	anonymous_lobbies_and_room_lifecycle	supervisor, codes, ready-up, round FSM, session progression
06	realtime_websocket_protocol	/ws/{code}, inputs in, snapshots out, docs/PROTOCOL.md
07	canvas_client_and_hud	playable-in-browser single player vs. clock, HUD, art
08	client_prediction_and_touch	smooth remote play, prediction/reconciliation, touch controls
09	co_op_two_player_e2e	two real browsers cooking together, contested-resource arbitration
10	hazards_and_escalation_mechanics	fire, spills, movers, rush waves + client FX
11	campaign_levels_and_progression	all 10 levels authored+validated, campaign flow, curve check
12	reconnect_resilience_and_scale	mid-round rejoin, seat grace, room GC, 200-room stress test
13	endless_mode_and_scoreboard	endless generator, session scoreboard, post-campaign loop
14	accessibility_polish_and_hardening	contrast/reduced-motion/screen-reader, perf+security pass, docs

Every phase leaves the app launchable and the suite green; phases 01→14 are strictly sequential (each depends on the previous phase's capability).

---

13. Risks and mitigations

Risk	Impact	Mitigation
Python tick too slow at scale	laggy rooms	perf budget test in phase 12 from day one; sim purity keeps the hot loop cheap; halve-tick degradation
Client desync/rubber-banding feels bad	unplayable	server-authoritative + interpolation delay + reconciliation tests (phase 08)
Contested pickups feel unfair	co-op friction	deterministic arbitration + explicit denied feedback (phase 09)
Difficulty curve guesswork	too easy/hard	escalation-axis metrics + headless greedy solver bound (phase 11)
Level content explodes in complexity	unmaintainable	strict YAML schema + validator + content test that never hard-codes lists
Anonymous rooms abused (spam)	noisy lobbies	no chat in v1, emote whitelist, rate limits
Restart wipes runs	lost progress	accepted by design (A6); result screen encourages saving nothing; endless/scoreboard explicitly in-memory
Trademark confusion with "Overcooked"	legal	original art, names, and content; homage note in README

Documentation index (canonical)

These are the only docs the project promises. A phase creates a file the first time it needs one; no phase references a doc that does not exist by the end of the last phase.

Path	Contents	Created by
README.md	what it is, quickstart, how to play, controls, deploy pointer, demo-vs-production	phase 01, refined throughout
AGENTS.md	agent rules: commands, architecture, conventions, guardrails	phase 01, verified every phase
BUDGETS.md	measured performance/latency budgets vs §10 targets, dated	phase 08
docs/DESIGN.md	architecture, module map, the decisions behind A1–A12 in prose	phase 01 (stub) → phase 09
docs/SIMULATION.md	tick contract, movement/collision, pipeline rules, arbitration, hazard rules	phase 02/03
docs/LEVELS.md	level + recipe YAML format, escalation axes, how to author and validate a level	phase 02, phase 11
docs/PROTOCOL.md	wire messages, enums, error codes, close codes, budgets, versioning policy	phase 06
docs/CLIENT.md	client module map, render loop, snapshot buffer, input, assets	phase 07
docs/DEPLOYMENT.md	container build/run, compose, TLS/reverse proxy, ops runbook	phase 01 (stub) → phase 14
docs/TESTING.md	test layout, how to run everything, artifact policy	phase 01
docs/ACCESSIBILITY.md	what WCAG 2.1 AA guarantees, how each is tested, text-mode contract, known limits	phase 14
docs/SECURITY.md	threat model + finding table with severity, status, and the evidence test per row	phase 14
tests/e2e/README.md	multiplayer harness usage, debugging failing browser tests	phase 07

tests/unit/test_docs_index.py (phase 01) keeps this table and the docs/ tree identical, so neither can drift silently.

---

14. Execution

• Run the pipeline with the phased-execution skill (/next-phase, /run-phase, /phase-status); task files in .agents/phases/todo/NN_name/ are the unit of work, and each phase moves to .agents/phases/complete/ only when its 00_phase.md Completion Criteria are all checked.
• New work is never implemented directly: it is captured as a phase via the phase-authoring skill first, so this roadmap stays the record of what the project claims to do.
• Amending a LOCKED decision (§3) requires editing §3 itself in the same phase, with the reason and the phase number recorded inline — no silent reversals.