Scaffold project and author 14-phase roadmap

Browser co-op kitchen game: FastAPI + native WebSockets, server-authoritative 20 Hz simulation, in-memory anonymous lobbies, data-driven YAML levels, Canvas 2D vanilla ES-module client with locally authored SVG art and no external CDNs. .agents/PLAN.md records the LOCKED decisions; .agents/user_stories/ holds the 12 flow contracts; .agents/phases/todo/ breaks them into 14 sequential, test-gated phases (71 task files), each leaving the app launchable and the suite green. LLM-Generated: true
2026-10-05 17:05:56 -04:00
commit f84c6ebaef
105 changed files with 5752 additions and 0 deletions
@@ -0,0 +1,48 @@
+# Phase 01 — Runnable service scaffold
+
+**Story:** `US-01_create_anonymous_lobby` (partial — landing surface only)
+**Context:** `.agents/PLAN.md` §4 (app/static/HTTP boundary), A1, A2, A12, A17, A18, A20
+
+## Objective
+Turn the empty repository into a launchable FastAPI service that serves the client
+shell, exposes `/healthz`, enforces the no-external-asset rule, and has its quality
+toolchain wired end to end. Nothing about gameplay exists yet; the app must still boot,
+serve, and pass every check.
+
+## Dependencies
+- none (first phase; `pyproject.toml`, `Containerfile`, `compose.yaml`, `README.md`,
+  `AGENTS.md`, `.agents/PLAN.md` already exist in the repo)
+
+## Tasks
+1. `01_lock_toolchain_and_packages.md` — deps resolve, `uv sync` clean, test tree + markers, first passing test
+2. `02_config_and_debugpy.md` — typed env config, `.env.example`, debugpy bootstrap
+3. `03_fastapi_app_and_static_shell.md` — app factory, CLI entry point, static shell page, security headers
+4. `04_no_cdn_guard_and_docs.md` — no-external-asset test, header tests, README/AGENTS verified
+
+## Testing & Quality
+- Unit: config parsing/defaults/overrides; static asset scan finds zero external URLs;
+  security headers present; `/healthz` returns 200 with a JSON body.
+- Integration: app boots through `create_app()` and serves `/` and `/static/*`.
+- Coverage: **>90%** on new/modified code (`config.py` and `server/app.py` fully covered).
+- The phase is "Complete" only when the **entire** project test suite passes 100%
+  (every test in the project, not just this phase's).
+- Gate commands, all green: `uv run ruff check .`, `uv run pyright`, `uv run pytest`.
+
+## Documentation & Consistency
+- The final pass reviews `README.md` and `AGENTS.md` in full against the project as it
+  will stand after this phase — fixing every inconsistency found, **including
+  pre-existing ones not caused by this phase** (e.g. commands or variable names that
+  drifted from `config.py`).
+- Tasks update `README.md`/`AGENTS.md` immediately when their own changes are
+  user-visible (setup, commands, configuration, features, conventions).
+
+## Completion Criteria
+- [ ] `uv sync --extra dev` succeeds and `uv.lock` is committed
+- [ ] `uv run undercooked --host 127.0.0.1 --port 8000 &` then
+      `curl -fsS http://127.0.0.1:8000/healthz` → `{"status":"ok"}`; `curl -fsS http://127.0.0.1:8000/` → the shell HTML
+- [ ] `DEBUGPY=1 uv run undercooked` opens port 5678 and still serves `/healthz`
+- [ ] `uv run pytest -q` → 100% passing, coverage ≥ 90%
+- [ ] `uv run ruff check .` and `uv run pyright` → zero errors
+- [ ] no file under `app/static/` references an external URL (test-enforced)
+- [ ] README.md and AGENTS.md are accurate and consistent with the whole project (verified in the final pass)
+- [ ] no behavior change in completed phases (n/a — first phase)