undercooked/AGENTS.md

# AGENTS.md — operating rules for this repository

## 1. Read this order, every time

1. `.agents/PLAN.md` — master design. Its **Architectural Anchors** table holds the
   **LOCKED DECISIONS**, which are binding on every task and phase.
2. This file.
3. `.agents/phases/todo/<phase>/00_phase.md`, then the task file you are executing.
4. The user story referenced by the phase (`.agents/user_stories/US-XX_*.md`).
5. `.agents/phases/complete/*/00_phase.md` for what already exists (do not re-build it).

## 2. The phased protocol

- Phase state lives in files, not chat. Pending work: `.agents/phases/todo/NN_name/`
  (`00_phase.md` + `NN_task.md`). Finished work: `.agents/phases/complete/`.
- Execution is owned by the `phased-execution` skill (`run-task.sh`, `run-phase.sh`,
  `auto-phase.sh`). Each task runs in a fresh subprocess and must pass
  `.agents/validate.sh` before it moves to `complete/`. That gate fails fast in this
  order: `ruff check .` → `pyright` → `undercooked-levels validate` (skipped with a
  notice until phase 02 creates the loader) → the **full** `pytest` suite with the
  coverage floor → repo-hygiene checks. It runs from the repo root or from `.agents/`.
- New work is authored by the `phase-authoring` skill as a phase directory — not
  implemented straight from chat.
- **Never** modify `.agents/PLAN.md` or anything under `.agents/phases/complete/`.
- **Ask the user** before editing an existing file in `.agents/phases/todo/`.
- Do not renumber or reuse phase/task numbers.

## 3. LOCKED DECISIONS (summary — the table in PLAN.md is authoritative)

- **Python 3.12+ / uv / FastAPI / native WebSockets** (`uvicorn[standard]`). No
  Socket.IO, no SSE, no WebRTC, no REST for live game traffic.
- **Server-authoritative fixed-tick simulation** (20 Hz) with client interpolation.
  The browser never decides anything true. `src/undercooked/sim/` is pure:
  **no FastAPI, no asyncio, no I/O, no wall-clock, no `random` without the round RNG**.
- **No database, no ORM, no Alembic.** Live state lives in the room supervisor;
  results/scoreboards live in memory and die with the process. User-approved
  deviation from the default FastAPI stack.
- **Data-driven content.** Levels/recipes/hazards come from YAML in `levels/` loaded
  through validated Pydantic models. No hard-coded level or recipe lists in Python.
- **Client: Canvas 2D + vanilla ES modules + this repo's own SVG art.** No bundler,
  no framework, no CDN, no analytics, no external fonts.
- **Tests: pytest + Playwright.** One Playwright suite per user story; multi-player
  stories use two browser contexts against one room.
- Quality gate: ruff + pyright + full pytest, **>90% coverage** on new/modified code,
  **entire suite 100% passing** before a phase may complete or commit.

## 4. Definition of done (every task)

- [ ] Task's own work exists at the named paths and is importable/runnable.
- [ ] Tests written for the task's logic (unit for pure logic, integration for
      rooms/protocol, e2e for user-visible flows) and passing.
- [ ] **Full** project suite passes (`uv run pytest`), coverage gate met — including
      failures the task did not cause: fix them, do not skip, xfail, or delete tests.
- [ ] `uv run ruff check .` and `uv run pyright` report zero errors.
- [ ] `uv run undercooked-levels validate` passes if any level/content file changed.
- [ ] `README.md` and `AGENTS.md` updated when the change is user-visible
      (setup, commands, config, protocol, features, conventions). Every phase's final
      pass re-reviews both **in full, project-wide** and fixes inconsistencies,
      including pre-existing ones.
- [ ] App still launches: `uv run undercooked` serves `http://127.0.0.1:8000/healthz`
      with `200` and the client at `/`.
- [ ] No behavior regression in any completed phase.

## 5. Hard rules

- **Configuration is read once, in `config.py`.** `src/undercooked/config.py` is
  the only module that touches `os.environ`. To add a knob: add a `Settings`
  field + `ENV_KEYS` entry + a line in `.env.example` + a row in the README table
  (a test fails when those disagree), and read it from `get_settings()`. Values
  are validated at startup: an impossible one raises `ConfigError` rather than
  half-configuring the server (`undercooked` prints one line and exits `2`).
  Precedence is **CLI flag > environment > built-in default**: `__main__.py`
  resolves it purely, then hands the flags to `config.apply_cli_overrides()`,
  which is the only writer of `os.environ` (so a uvicorn `--reload` child
  re-reads the same values). `DEBUGPY=1` binds a debugger listener on `0.0.0.0`
  — dev-only, never on a public host.
- **No external CDNs or remote assets.** `tests/unit/test_no_external_assets.py`
  fails the build on `http://`/`https://`/`//host` references, `@import url(`,
  `srcset`, an absolute-URL `fetch()`/`import`, an absolute-URL `WebSocket`, or
  `EventSource` anywhere in `app/static/**` (html/css/js/svg), and requires every
  `<script src>`/`<link href>`/`<img src>` in `index.html` to be a same-origin
  `/static/...` path. It scans the same `STATIC_DIR` `server/app.py` mounts, so it
  cannot pass by scanning the wrong folder; the exemptions are XML `xmlns` URIs, which
  are identifiers the browser never fetches, and a `data:` URL in an `index.html`
  element attribute where the CSP already allows it (`img-src 'self' data:`) — the
  app's own bytes either way. The US-01 e2e suite additionally
  fails if loading the page ever issues an off-origin request. CSP is
  `default-src 'self'` (plus `ws:`/`wss:` same-origin) and is applied by
  `server/headers.py` to **every** response, including errors. FastAPI's `/docs`,
  `/redoc` and `/openapi.json` stay disabled because their bundled HTML pulls Swagger
  assets from `cdn.jsdelivr.net`; the wire contract lives in `docs/PROTOCOL.md`
  (written by phase 06) instead.
- **Docs are guarded like code.** `tests/unit/test_docs_commands.py` requires every
  command line in a `bash` fence of `README.md`/`docs/*.md` to start with a known-safe
  prefix (`uv `, `podman `, `curl `, `cd `, `bash .agents/validate.sh`, `#`, or a
  documented `VAR=value` lead) and to launch only a program declared in
  `pyproject.toml`, and keeps the `UNDERCOOKED_*`/`DEBUGPY*` names in the docs and the
  ones in `config.py`/`.env.example` equal in both directions. So: never document a
  command that does not run yet — describe it in prose until the phase that ships it.
  `tests/unit/test_docs_index.py` keeps PLAN §13's documentation index and the `docs/`
  tree identical (no missing doc for a shipped phase, no doc nothing promises), and
  `docs/TESTING.md` is the reference for test layout, markers and artifact policy.
- **No new technology** (dependency, framework, service) without explicit written
  user permission recorded in the phase's `00_phase.md` and signed off into PLAN.md.
- **The simulation is the single source of truth.** Client-side values are guesses.
  Never trust inbound coordinates, scores, timers, or level ids — validate every
  inbound field against the room's state (`server/protocol.py`).
- **Anonymous by design.** No accounts, no emails, no cookies with personal data.
  Identity = 24 random bytes per browser tab (`secrets.token_urlsafe(24)` when the
  server mints one, `crypto.getRandomValues` + base64url in `app/static/js/app.js`,
  which is the same entropy and the only option in a browser) held in
  `sessionStorage`. Names are sanitized, length-capped, non-authoritative.
- **Frame and rate limits are enforced, not suggested**: `max_message_bytes`,
  `max_inputs_per_s`, room caps, and message-type whitelists per room state.
- **Protocol changes need a version bump**: editing a wire message means editing
  `src/undercooked/server/protocol.py`, `docs/PROTOCOL.md`, and the client in the same task,
  and bumping `PROTOCOL_VERSION` (PLAN §11).
- **Determinism is a contract.** `sim/step.py` must produce identical state given the
  same seed and input script — the replay tests in `tests/sim/` are the guard.
- **ntfy is outbound-only.** Never use it to ask questions or wait for approval.
  If a task is ambiguous, make the best judgment consistent with PLAN.md, or stop
  and let the user rewrite the task.
- **Commits** are made by the pipeline harness (`PHASE_COMMIT=1`), one atomic commit
  per completed phase, `--no-gpg-sign`, subject `phase: <NN_name>`. Child executors
  never run `git add`/`commit`/`mv`/`rm`/`stash`. When a human asks for a commit, use
  the `git-commit` skill (`--no-gpg-sign`, `LLM-Generated: true` trailer).
- Do not commit `.env`, logs, coverage output, `.agents/phase-sessions/`,
  `.agents/pipeline.log`, or `.agents/reports/` (all gitignored).

## 6. Where things go

| Change | Location |
|---|---|
| Configuration (env vars → typed `Settings`), debugpy bootstrap | `src/undercooked/config.py`, `.env.example`, `src/undercooked/debug.py` |
| Pure game rules (movement, stations, orders, scoring, hazards) | `src/undercooked/sim/` |
| Level/recipe content | `levels/*.yaml` |
| Rooms, lobby lifecycle, session records | `src/undercooked/server/rooms.py`, `room.py` |
| Wire messages + validation | `src/undercooked/server/protocol.py`, `docs/PROTOCOL.md` |
| HTTP app (`/`, `/healthz`, `/static`), lifespan | `src/undercooked/server/app.py` |
| Security headers (CSP `default-src 'self'`, no-sniff, frame-ancestors) | `src/undercooked/server/headers.py` |
| CLI entry point (`undercooked`): flags → `--help` → serve | `src/undercooked/__main__.py` |
| Renderer, HUD, input, interpolation | `app/static/js/`, `app/static/assets/` |
| Documentation (design / testing / deployment; per-phase docs) | `docs/*.md`, indexed by PLAN §13 and guarded by `tests/unit/test_docs_index.py` |
| The pipeline gate itself | `.agents/validate.sh` |
| User-visible flow contract | `.agents/user_stories/US-XX_*.md` |

Tests mirror that: `tests/unit/` (pure, no-I/O logic incl. HTTP-route unit tests),
`tests/integration/` (in-process app boot, live uvicorn + WebSocket clients), `tests/sim/`
(headless determinism and replays), `tests/e2e/` (Playwright, named `test_usNN_*.py`,
marked `e2e`). `tests/` is not a package; shared fixtures live in `tests/conftest.py`.

- The browser suites use the **`playwright` sync API directly with fixtures written in
  `tests/e2e/conftest.py`** — `pytest-playwright` is deliberately not a dependency, so
  adding it needs the usual permission. Those `browser`/`context`/`page` fixtures are
  **function-scoped on purpose**: a long-lived sync driver keeps an asyncio loop flagged
  as running in the main thread and breaks every later `async def` test.
- `live_server` (session-scoped, `tests/conftest.py`) is the only fixture that binds a
  socket: an ephemeral `127.0.0.1` port, never a routable interface.