@playcraft/cli 0.0.43 → 0.0.46

package/project-template/.claude/agents/refs/developer-dev-handoff.md

@@ -1,50 +1,67 @@
 # Developer Dev Handoff (L2)
 
-Use during **Phase 2 integration** and before marking `devStatus: ready`.
+Use when Developer is validating preview quality, recording ready-state, or routing upstream blockers.
+
+This file is a handoff/verification companion. Role ownership stays in `developer.md`; runtime routing and STOP ownership stay in the shared workflow docs.
 
 ## Dev command
 
 ```bash
-cat package.json   # read scripts.dev (webpack / vite / etc.)
-npm run dev
+npm run dev:start   # starts persistent dev server + records the real devUrl
+# npm run dev:stop  # only when intentionally tearing down before Ring Gate
+```
+
+- **Not** `playcraft start`, and **not** a bare `npm run dev`. `dev:start` wraps the project's `scripts.dev` and additionally:
+  - detects the actual listening port from Vite output (handles port drift when 3000 is taken),
+  - appends `?debug=1`,
+  - writes `devUrl` through the same programmatic state layer `state:set` uses.
+- **Do not** read a port from the terminal or hand-edit `devUrl` — `dev:start` is the source of truth for it.
+- Prefer leaving the server running for Reviewer and Ring Gate user preview; **do not `pkill` vite before Ring Gate** (use `npm run dev:stop` if you must).
+- **`verify:contract` / `verify:firstwin` / `record:mp4` spawn their own dev server** — run them directly; **never** start a separate dev server just to satisfy verify scripts.
+
+## Verify scripts (self-managed server)
+
+```bash
+npm run verify:contract   # boots dev server internally, exits when done
+npm run verify:firstwin   # same — no manual npm run dev needed
 ```
 
-- **Not** `playcraft start` — Dev is the project's `scripts.dev`.
-- Record the URL from terminal output (e.g. `http://localhost:5173`) in `project-state.md` → `devUrl`.
-- Prefer leaving the server running for Reviewer; if it stops, Reviewer or orchestrator may restart and refresh `devUrl`.
+Do **not** run `npm run dev & sleep && curl` before verify commands. The scripts auto-detect the listening port from Vite stdout.
 
 ## Dev iteration rhythm
 
 During integration, repeat:
 
 1. Change code / wire assets
-2. `npm run dev` (restart if HMR is insufficient)
+2. `npm run dev:start` (HMR usually suffices; rerun only to restart)
 3. Self-check UI + gameplay + runtime (checklists below)
 4. Log in `developer-log.md` → **Dev self-check**
-5. If upstream issue → blockers + ICP + STOP (orchestrator routes TA/Designer)
+5. If upstream issue → blockers + ICP + STOP (orchestrator routes TA/Artist)
 
 **Do not** wait until the last minute for a single Dev pass.
 
 ## UI checklist (vs MC + layout-spec)
 
-| Check                                              | Source                                  |
-| -------------------------------------------------- | --------------------------------------- |
-| Zones and hierarchy match layout-spec              | `docs/layout-spec.md`                   |
-| Colors / mood match approved style                 | `docs/style-exploration.md`, Gate #2 MC |
-| Element placement matches storyboard Visual Intent | Master Composite frames                 |
-| Text-as-image assets visible, correct aspect       | `assetMapping` paths                    |
-| No broken images / wrong sprites / style drift     | Dev browser                             |
-| Mobile viewport (e.g. 750×1334) acceptable         | Dev browser resize                      |
-
-## Gameplay checklist (vs design-brief + PGS)
-
-| Check                                      | Source                 |
-| ------------------------------------------ | ---------------------- |
-| Hook → Tutorial → Gameplay → End Card flow | `docs/design-brief.md` |
-| Rules, scoring, win/lose match PM contract | design-brief + PGS     |
-| **First level guaranteed success**         | atom-plan / PGS        |
-| Near-Win and difficulty feel as specified  | design-brief           |
-| CTA on End Card                            | runtime test           |
+| Check                                              | Source                                        |
+| -------------------------------------------------- | --------------------------------------------- |
+| Zones and hierarchy match layout-spec              | `docs/layout-spec.md`                         |
+| Colors / mood match approved style                 | `docs/style-exploration.md`, ring 3 locked MC |
+| Element placement matches storyboard Visual Intent | Master Composite frames                       |
+| Text-as-image assets visible, correct aspect       | `assetMapping` paths                          |
+| No broken images / wrong sprites / style drift     | Dev browser                                   |
+| Mobile viewport (e.g. 750×1334) acceptable         | Dev browser resize                            |
+
+## Gameplay checklist (vs DESIGN.md + PGS)
+
+> Gameplay contract source is `docs/DESIGN.md` in every ring. `design-brief.md` only exists from ring 2+ as supplementary process detail.
+
+| Check                                                 | Source            |
+| ----------------------------------------------------- | ----------------- |
+| Hook → Tutorial → Gameplay → End Card flow            | `docs/DESIGN.md`  |
+| Rules, scoring, win/lose match Game Designer contract | `DESIGN.md` + PGS |
+| **First level guaranteed success**                    | atom-tree / PGS   |
+| Near-Win and difficulty feel as specified             | `DESIGN.md`       |
+| CTA on End Card                                       | runtime test      |
 
 ## Runtime checklist
 
@@ -55,16 +72,16 @@ During integration, repeat:
 
 ## devUrl recording
 
-In `docs/project-state.md` → **Dev Preview**:
+`devUrl` is written **programmatically** by `npm run dev:start` (real port + `?debug=1`). Do not hand-edit it. The remaining Dev Preview fields are set via `npm run state:set`:
 
-| Field            | When                                                 |
-| ---------------- | ---------------------------------------------------- |
-| `devUrl`         | After `npm run dev` shows listening URL              |
-| `devStatus`      | `pending` → `ready` or `blocked_upstream` / `failed` |
-| `devStartedBy`   | `developer`                                          |
-| `devLastChecked` | ISO timestamp after each meaningful Dev pass         |
+| Field            | When                                                 | Written by          |
+| ---------------- | ---------------------------------------------------- | ------------------- |
+| `devUrl`         | When `npm run dev:start` runs                        | `dev:start` (auto)  |
+| `devStatus`      | `pending` → `ready` or `blocked_upstream` / `failed` | `npm run state:set` |
+| `devStartedBy`   | `developer`                                          | `npm run state:set` |
+| `devLastChecked` | ISO timestamp after each meaningful Dev pass         | `npm run state:set` |
 
-Also note devUrl in `docs/developer-log.md` → **Dev self-check**.
+Also note devUrl in `docs/developer-log.md` → **Dev self-check** (copy from `dev:start` output).
 
 ## Upstream blocker template
 
@@ -81,22 +98,45 @@ In `docs/intent-clarifications.md`:
 - **Context**: what Dev showed (screenshot description or path)
 - **Gap**: vs MC / contract / design-brief
 - **Acceptance**: exact path, dimensions, style, or audio mood required
-- **routeTo**: TA | Designer | PM
+- **routeTo**: TA | Artist | Game Designer
 
-Set `project-state.md`:
+Set state programmatically:
 
-- `devStatus: blocked_upstream`
-- `devBlockers`: same rows as log
+```bash
+npm run state:set -- \
+  devStatus=blocked_upstream \
+  devBlockers='[{"routeTo":"technical-artist","issue":"missing production asset","status":"open"}]'
+```
 
 **STOP** after filing — wait for orchestrator to re-invoke upstream role, then **re-run Dev loop**.
 
 ## After rework — re-verify checklist
 
 1. Confirm blocker paths exist on disk (`ls`, `playcraft image info` if needed)
-2. `npm run dev`
+2. `npm run dev:start`
 3. Re-run UI + gameplay + runtime checklists for affected areas
 4. Close blocker rows (`status: resolved`) or escalate if still wrong
-5. Only then set `devStatus: ui_ready` (after `ui_pass`) or `devStatus: ready` (after `gameplay_pass`) and handoff `next_orchestrator_action: "Invoke @reviewer ui_diff"` (or `load_check`)
+5. Only then set `devStatus: ready` (no open `devBlockers`) and handoff `next_orchestrator_action: "Invoke @reviewer gameplay_conformance"`
+
+## Integration complete — verify before ready
+
+When TA's production assets land (Phase 2 / ui_rework), run this before setting `devStatus: ready`:
+
+| Requirement                                                     | How to verify                            |
+| --------------------------------------------------------------- | ---------------------------------------- |
+| Entry point is `game/index.html`                                | `ls game/index.html`                     |
+| All asset references use relative paths                         | Read game code                           |
+| No Node.js APIs in `game/`                                      | Code review                              |
+| No dynamic imports or CDN references                            | `grep -r "import(" game/`                |
+| Zero external requests                                          | Browser console + `grep -r "http" game/` |
+| Every `tileColors[].id` has image at `assetMapping.visualAsset` | `layout-spec` + `ls`                     |
+| All SFX files exist per `assetMapping`                          | `layout-spec` + `ls`                     |
+| Background at correct path                                      | `layout-spec` + `ls`                     |
+| Atlas `.webp` + `.json` bound with correct `frameId`            | `playcraft image info <atlasPath>`       |
+| Board position = `zones["board"].rect`                          | layout-spec                              |
+| Elements positioned per `zones[].rect`                          | Dev browser                              |
+
+> **`playcraft build` is not required** for `devStatus: ready` or project `done`.
 
 ## Dev ready checklist (`devStatus: ready` — all required)
 
@@ -106,4 +146,7 @@ Set `project-state.md`:
 - [ ] No open rows in Upstream blockers / `devBlockers`
 - [ ] `devUrl` recorded and server reachable
 - [ ] `developer-log.md` Dev self-check complete
+- [ ] `npm run ensure:project` executed (prepares optimization toolkit)
+- [ ] `npm run verify:ui` PASS or only expected warnings (catches asset/layout drift)
+- [ ] Headed full-playthrough baseline recorded: `npm run record:mp4 -- --headed --fps=60`
 - [ ] **Not** required: `playcraft build`, user running terminal commands