@playcraft/cli 0.0.41 → 0.0.43

package/project-template/templates/designer-log.template.md

@@ -48,19 +48,67 @@ Repeat this section for each atom.
 Fill in details as you complete each one.
 -->
 
+## Image Production Preflight (Phase 1 — Gate #2b)
+
+> **Mandatory before MC/ASR generation and before `#2b` STOP.** Read all three Skills; record key decisions.
+
+| Skill / Check               | 已读 | 关键决策摘要                                             |
+| --------------------------- | ---- | -------------------------------------------------------- |
+| playcraft-storyboard        | ☐    | MC 45:16 · model whitelist · Panel 1 all element types   |
+| playcraft-asset-state-sheet | ☐    | ASR grid · isolated cells · sheet #808080 · cell chroma  |
+| playcraft-image-generation  | ☐    | §3 chroma matrix · §3.1 ASR branch · no remove-bg on ASR |
+
+<!--
+  MUST be filled before generating ASR (Step 4) and before Gate #2b STOP.
+  Hook validate-workflow-stop enforces this section in style_exploration stage.
+-->
+
 ## ASR Coverage Matrix (designer-handoff-v2 — 100% contract rows)
 
 > UI: `assets/images/reference/ui_state_sheet_{{option}}.png`  
 > Element: `assets/images/reference/element_state_sheet_{{option}}.png`
 
-| Contract id                      | Type   | ASR sheet    | Grid (row,col) | State(s)    | TA extends? |
-| -------------------------------- | ------ | ------------ | -------------- | ----------- | ----------- |
-| {{element_id_from_assetMapping}} | visual | ui / element | {{1,1}}        | {{default}} | {{yes/no}}  |
-| {{static_text_id}}               | text   | ui / MC-crop | —              | baked       | {{yes/no}}  |
+### Sheet grid metadata (供 TA crop 计算)
+
+| Sheet                                  | Total rows    | Total cols | Cell W×H (px) | Cell padding (px) | Origin            |
+| -------------------------------------- | ------------- | ---------- | ------------- | ----------------- | ----------------- |
+| `ui_state_sheet_{{option}}.png`        | 2             | 4          | 800×800       | 80                | top-left (R1, C1) |
+| `element_state_sheet_{{option}}.png`   | 2             | 4          | 800×800       | 80                | top-left (R1, C1) |
+| `element_state_sheet_{{option}}_2.png` | (if overflow) |            |               |                   |                   |
+
+<!--
+Grid coordinates use 1-based indexing, row-major.
+Cell W×H = visible cell area (without padding). Padding = margin between cells AND outer margin.
+Pixel coordinates of cell (R, C):
+  x = (C - 1) × (cellW + padding) + padding
+  y = (R - 1) × (cellH + padding) + padding
+TA uses these for `playcraft image crop --x ... --y ... --width cellW --height cellH`.
+-->
+
+### Coverage
+
+| Contract id                      | elementType | Type   | CoverageLayer                 | ASR sheet    | Grid (row,col) | State(s)    | TA extends? |
+| -------------------------------- | ----------- | ------ | ----------------------------- | ------------ | -------------- | ----------- | ----------- |
+| {{element_id_from_assetMapping}} | {{type}}    | visual | on-asr / mc-crop / ta-extends | ui / element | {{R1C1}}       | {{default}} | {{yes/no}}  |
+| {{static_text_id}}               | —           | text   | mc-crop or on-asr             | ui / MC-crop | —              | baked       | {{yes/no}}  |
 
 <!--
 One row per layout-spec assetMapping elementId and per static text id.
-TA crop index + Phase 2 VisualAtom actualOutput: ASR:sheet:R#C#
+CoverageLayer:
+  on-asr     — physical slot on ASR PNG; Grid required; mirror atoms[].asrSlot
+  mc-crop    — MC Panel 1 only; ASR sheet = MC-crop
+  ta-extends — variant/extra states; TA extends? = yes + Style Intent note
+
+Type rule: each distinct elementType must have ≥1 row with on-asr OR mc-crop.
+Grid syntax: R{row}C{col}, e.g. R1C2, 1-based, row-major.
+TA crop + Phase 2 VisualAtom actualOutput: ASR:<sheet>:R#C#
+
+After filling this table, MIRROR each visual row into atom-plan.json:
+  atoms[].asrSlot = { "sheet": "ui" | "element", "row": <n>, "col": <n> }
+
+This lets TA batch-crop from atom-plan.json directly (see ta-pipeline-cookbook.md
+§ ASR 提取方法 "优先路径") instead of manually re-reading this Coverage table.
+See docs/team/atom-plan-format.md § `asrSlot` for full schema + crop formula.
 -->
 
 ## Palette Locked (from MC option {{option}})
@@ -74,6 +122,47 @@ TA crop index + Phase 2 VisualAtom actualOutput: ASR:sheet:R#C#
 
 **Delta vs layout-spec Color Palette**: {{match | PM update: one line}}
 
+## Skill Preflight (Phase 2)
+
+> **Mandatory before audio/digit production.** Read relevant Skills + check mediaGroups.
+
+| Skill / Check              | 已读 | 关键决策摘要                                  |
+| -------------------------- | ---- | --------------------------------------------- |
+| playcraft-audio-generation | ☐    | {{BGM mood, SFX prompt pattern, loop config}} |
+| playcraft-text-rendering   | ☐    | {{digit strip chroma strategy, font style}}   |
+| playcraft-image-generation | ☐    | {{background decision for digit strip}}       |
+| mediaGroups (.aiaudio)     | ☐    | {{linked: X, skipped: Y, reason: Z}}          |
+
+<!--
+  MUST be filled before generating any audio or digit strip in Phase 2.
+  mediaGroups: list each .aiaudio match disposition (linked/skipped + reason).
+-->
+
+## mediaGroups Reuse (Phase 2)
+
+> **Mandatory before any audio generation.** Filter `atom-plan.json` → `skillsMatch.mediaGroups` by `extension`; Designer is responsible for **`.aiaudio` only** (TA handles `.aiimage` / `.aisprite`).
+
+| mediaGroup atomId | extension | Matches Designer atom? | Disposition   | Reason (if skipped)                | Output path (if linked) |
+| ----------------- | --------- | ---------------------- | ------------- | ---------------------------------- | ----------------------- |
+| {{mg_atomId}}     | .aiaudio  | {{atom_id / —}}        | linked / skip | {{mood mismatch / wrong loop / —}} | {{path / —}}            |
+
+<!--
+  Designer scope (this table):
+    .aiaudio — BGM / SFX bundles → link or skip (with reason)
+
+  Out of Designer scope (do NOT fill rows for these — TA owns them):
+    .aiimage  — single-shot image atoms
+    .aisprite — sprite-sheet atoms (multi-frame)
+    .aigameplay / .aiconfig — Developer reads via skillRef
+
+  Filter command:
+    cat docs/atom-plan.json | jq '.skillsMatch.mediaGroups[] | select(.extension == ".aiaudio")'
+
+  Disposition rules:
+    linked → playcraft skills link → verify mood matches MC → status: done
+    skip   → quality / mood / loop mismatch → document reason → generate from scratch
+-->
+
 ## Style Consistency Self-Check
 
 - [ ] All visual assets share the same art style?

package/project-template/templates/developer-log.template.md

@@ -2,116 +2,119 @@
 
 ## Upstream Intake
 
-> **Step 0 — mandatory before Spec Quick-Check or any `game/` edit.** Summarize what PM/Designer/TA already decided so implementation matches intent.
+> **Step 0 — mandatory before Spec Quick-Check or any `game/` edit.**
+
+| Doc                         | Read ✓ | One-line takeaway                         |
+| --------------------------- | ------ | ----------------------------------------- |
+| `docs/project-state.md`     | ☐      | {{e.g. ui_pass, Wave 2 done}}             |
+| `docs/design-brief.md`      | ☐      | {{e.g. flow scenes for navigation}}       |
+| `docs/layout-spec.md`       | ☐      | {{e.g. zones, assetMapping, atlas paths}} |
+| `docs/atom-plan.json`       | ☐      | {{e.g. Developer atoms + skillRefs}}      |
+| `docs/atom-plan.md`         | ☐      | Impl Skill Context + acceptance           |
+| `docs/style-exploration.md` | ☐      | {{e.g. MC panel layout per scene}}        |
+| `logs/designer-log.md`      | ☐      | {{e.g. palette locked, motion notes}}     |
+| `logs/ta-log.md`            | ☐      | {{e.g. compliance green, atlas params}}   |
 
-| Doc                         | Read ✓ | One-line takeaway (what you will implement from it)    |
-| --------------------------- | ------ | ------------------------------------------------------ |
-| `docs/project-state.md`     | ☐      | {{e.g. integration, Wave 2 done, no spec-gap}}         |
-| `docs/design-brief.md`      | ☐      | {{e.g. PGS=match-3, tutorial 2 taps, first level win}} |
-| `docs/layout-spec.md`       | ☐      | {{e.g. board zone, tile atlas path + frameIds}}        |
-| `docs/atom-plan.json`       | ☐      | {{e.g. 6 Developer atoms, skillRef memory_match}}      |
-| `docs/atom-plan.md`         | ☐      | Impl Skill Context + acceptance criteria               |
-| `docs/style-exploration.md` | ☐      | {{e.g. MC panel1 UI layout, Hook frame contrast}}      |
-| `logs/designer-log.md`      | ☐      | {{e.g. motion: slow-mo near-win}}                      |
-| `logs/ta-log.md`            | ☐      | {{e.g. Compliance green, tile atlas 8 frames}}         |
+---
+
+## Skill Preflight
+
+> **Before any `game/` edits (ui_pass).** See `refs/developer-phase1-flow.md` Step 3.
 
-**MUST NOT** start Skill Preflight until every row is checked with a non-empty takeaway.
+| skillRef     | access                | `ref/` files read (paths) | `scaffold` included |
+| ------------ | --------------------- | ------------------------- | ------------------- |
+| {{skillRef}} | linked / cli-fallback | {{paths}}                 | yes / no            |
 
 ---
 
-## Skill Preflight
+## UI Pass Plan
 
-> **Ph.1 gate — before any `game/` edits.** Per `docs/atom-plan.json` `atoms[]` (`assignTo: Developer`, non-null `skillRef`). See `refs/developer-phase1-flow.md` Step 3.
+> **ui_pass only — mandatory before UI implementation.** Hook enforces on STOP.
 
-| skillRef     | access                | `ref/` files read (paths)                       | `scaffold` included |
-| ------------ | --------------------- | ----------------------------------------------- | ------------------- |
-| {{skillRef}} | linked / cli-fallback | {{e.g. .claude/skills/.../ref/pgs-schema.json}} | yes / no            |
+### Architecture
 
-```bash
-# Paste actual CLI output snippets (or summary) below — empty section = Ph.1 incomplete
-{{skills_read_and_scaffold_output}}
-```
+- **Engine**: {{engine}}
+- **Entry**: `game/index.html`
+- **Scene flow**: Hook → Tutorial → EndCard → CTA (navigation only in ui_pass)
 
-<!--
-Rules:
-  - One row per non-dash skillRef from atom-plan
-  - access: `linked` = read `.claude/skills/<skillRef>/`; `cli-fallback` = soft link missing, used `playcraft skills read` + Package Skills Root
-  - If skillRef = — for an atom, note "skills match" or playcraft-research in Impl Skill Context instead
-  - Do NOT mark GameplayAtom/ConfigAtom done in atom-plan until this table is filled
--->
+### Scene-Asset Binding Plan
 
-## Delivery Summary
+| Scene    | Assets (assetMapping) | Atlas/Frame | On disk? |
+| -------- | --------------------- | ----------- | -------- |
+| hook     | {{paths}}             | {{json}}    | {{y/n}}  |
+| tutorial | {{paths}}             | {{json}}    | {{y/n}}  |
+| endcard  | {{paths}}             | {{json}}    | {{y/n}}  |
 
-- **Assigned**: {{total_assigned}}
-- **Completed**: {{total_completed}}
-- **Bindings resolved**: {{resolved}}/{{total_bindings}}
+### Scene navigation (for Reviewer ui_diff)
 
-## Experience Flow → Code Mapping
+| MC panel   | Scene key   | How to reach (URL param / button)  |
+| ---------- | ----------- | ---------------------------------- |
+| Concept    | {{initial}} | {{e.g. ?scene=main or default}}    |
+| Hook       | hook        | {{e.g. ?scene=hook}}               |
+| Onboarding | tutorial    | {{e.g. button or ?scene=tutorial}} |
+| EndCard    | endcard     | {{...}}                            |
+| CTA        | cta         | {{...}}                            |
 
-> **Step 0c — Mandatory. Map each storyboard frame to code scene.**
-> Read `docs/style-exploration.md` concept mockup + storyboard composite image before implementing.
-> The storyboard is a single composite image with 4 frames in a grid — study each frame's position.
-
-| Storyboard Frame          | Scene/State      | Code Location             | Visual Intent                 |
-| ------------------------- | ---------------- | ------------------------- | ----------------------------- |
-| Hook (0-3s)               | `scene.hook`     | `game/scenes/hook.ts`     | {{visual_intent_description}} |
-| Tutorial (3-10s)          | `scene.tutorial` | `game/scenes/tutorial.ts` | {{visual_intent_description}} |
-| Gameplay+NearWin (10-25s) | `scene.gameplay` | `game/scenes/gameplay.ts` | {{visual_intent_description}} |
-| EndCard (25-30s)          | `scene.endcard`  | `game/scenes/endcard.ts`  | {{visual_intent_description}} |
-
-<!--
-Rules:
-  - Every scene code file MUST have a top comment referencing the storyboard:
-    // Visual reference: assets/images/storyboard/storyboard_confirmed.png (frame: top-left=Hook)
-  - If storyboard frame visuals conflict with layout-spec zones coordinates:
-    → storyboard takes precedence, ask PM in intent-clarifications.md
-  - Visual Intent column should capture the EMOTION and ATTENTION FLOW, not just mechanics
--->
+### Risk Checklist (ui_pass)
 
-## Per-Atom Delivery
+- [ ] Every assetMapping path verified on disk
+- [ ] Scene navigation documented for all 5 MC panels
+- [ ] No core gameplay rules in ui_pass scope
+- [ ] No external network dependencies
 
-### {{atom_id}} — {{slot_name}}
+---
 
-- **Status**: {{status}}
-- **Reference Skill**: {{skillRef}} (Skill Preflight: linked or cli-fallback + ref/)
-- **Output path**: {{file_path}}
-- **Test results**: {{passed}}/{{total}} passed
-- **Notes**: {{implementation_notes}}
+## Gameplay Pass Plan
+
+> **gameplay_pass only — mandatory before PGS / rules implementation.**
 
-<!--
-Repeat for each atom.
-For GameplayAtom: include PGS path + test results
-For ConfigAtom: include config path + parameter summary
--->
+### PGS Strategy
 
-## Binding Status
+- **Gameplay type**: {{from design-brief}}
+- **Core rules**: {{from Skill recipe}}
+- **First level guarantee**: {{how tutorial ensures win}}
+- **State machine**: {{states and transitions}}
 
-| Binding Target               | Source Atom        | File                | Status                     |
-| ---------------------------- | ------------------ | ------------------- | -------------------------- |
-| {{scene_path_or_config_key}} | {{source_atom_id}} | {{asset_file_path}} | {{bound/missing/mismatch}} |
+### Risk Checklist (gameplay_pass)
 
-<!--
-List every asset reference in your code:
-- Every image loaded from assets/images/
-- Every audio file referenced from assets/audio/
-- Every config value from layout-spec
+- [ ] UI shell unchanged unless open UI Diff items
+- [ ] testCases written before rule implementation
+- [ ] First level guarantees player success
+- [ ] CTA handler with platform fallbacks
+- [ ] Zero external network requests
+
+---
+
+## Experience Flow → Code Mapping
 
-Status values:
-  bound    — File exists and is correctly referenced
-  missing  — File not found at expected path
-  mismatch — File exists but wrong dimensions/format
--->
+| Storyboard Frame | Scene/State      | Code Location             | Visual Intent |
+| ---------------- | ---------------- | ------------------------- | ------------- |
+| Hook             | `scene.hook`     | `game/scenes/hook.ts`     | {{intent}}    |
+| Tutorial         | `scene.tutorial` | `game/scenes/tutorial.ts` | {{intent}}    |
+| Gameplay         | `scene.gameplay` | `game/scenes/gameplay.ts` | {{intent}}    |
+| EndCard          | `scene.endcard`  | `game/scenes/endcard.ts`  | {{intent}}    |
+
+---
 
 ## Dev self-check
 
-> After `npm run dev` — record each integration pass. See `refs/developer-dev-handoff.md`.
+### ui_pass completion
 
 - **devUrl**: {{http://localhost:...}}
-- **devLastChecked**: {{ISO timestamp}}
+- **devStatus**: ui_ready
 - **UI vs MC + layout-spec**: {{pass/fail — notes}}
+- **Scene navigation works**: {{yes/no}}
+- **Ready for Reviewer ui_diff**: {{yes/no}}
+
+### gameplay_pass completion
+
+- **devUrl**: {{http://localhost:...}}
+- **devStatus**: ready
 - **Gameplay vs design-brief + PGS**: {{pass/fail — notes}}
-- **Runtime** (no white screen, CTA, audio, state machine): {{pass/fail — notes}}
-- **Ready for Reviewer**: {{yes/no}}
+- **Runtime** (CTA, audio, state machine): {{pass/fail — notes}}
+- **Ready for Reviewer load_check**: {{yes/no}}
+
+---
 
 ## Upstream blockers
 
@@ -119,22 +122,13 @@ Status values:
 | -------- | --------- | -------------- | ------------------ | --------------- |
 | {{path}} | {{issue}} | {{acceptance}} | TA / Designer / PM | open / resolved |
 
-<!--
-When any row is open:
-  - Set project-state devStatus: blocked_upstream
-  - Write intent-clarifications.md with acceptance criteria
-  - STOP — wait for orchestrator rework invoke
--->
-
-## Technical Self-Check (static)
-
-- [ ] Board dimensions match layout-spec `zones["board"].rect`?
-- [ ] Element IDs match layout-spec `colorPalette.tileColors[].id`?
-- [ ] All asset paths match layout-spec `assetMapping`?
-- [ ] Zero external network requests (no fetch/XHR/external scripts)?
-- [ ] CTA handler implemented with multi-platform fallback?
-- [ ] `game/index.html` has viewport meta with user-scalable=no?
-- [ ] All CSS/JS inline (no external resources)?
-- [ ] First level guarantees player success?
-
-> **Not required for integration complete**: `playcraft build` (future delivery path only).
+---
+
+## Per-Atom Delivery
+
+### {{atom_id}} — {{slot_name}}
+
+- **Status**: {{status}}
+- **Phase**: ui_pass / gameplay_pass
+- **Output path**: {{file_path}}
+- **Notes**: {{notes}}

package/project-template/templates/layout-spec.template.md

@@ -82,12 +82,33 @@ Single large assets (full-screen bg) → one webp path only. Digit strip → sep
 Each elementId in assetMapping uses atlasPath + frameId OR single visualAsset path.
 -->
 
+Single-element groups stay as single-file paths; do not invent atlases for one texture.
+
+---
+
+## Element Type Registry (ASR capacity budget)
+
+Group `assetMapping` elementIds by **visual type** before Gate #1 lock. Designer needs **one representative per type** on ASR or MC Panel 1; color variants are `ta-extends`.
+
+| typeId   | elementIds (variants)        | Notes                           |
+| -------- | ---------------------------- | ------------------------------- |
+| {{type}} | {{id_a}}, {{id_b}}, {{id_c}} | e.g. tile colors share one type |
+
+**Budget**: aim for **≤ 20 unique types** and **≤ ~24 ASR physical slots** (ui board ~12 + element board ~12). If types > 12, plan `element_state_sheet_[X]_2.png` or extra `mc-crop` + `ta-extends` rows.
+
+Designer Coverage Matrix **elementType** column should match `typeId` here.
+
+---
+
 ## Asset Mapping
 
 | elementId      | visualAsset / atlas                   | frameId | sfx                                   |
 | -------------- | ------------------------------------- | ------- | ------------------------------------- |
 | {{element_id}} | assets/images/tiles/tiles_atlas.webp  | tile_01 | {{sfx_path_or_dash}}                  |
 | —              | assets/images/bg/{{bg_filename}}.webp | —       | —                                     |
+| —              | assets/images/ui/{{ui_element}}.webp  | —       | —                                     |
+| —              | assets/images/txt/{{text}}.webp       | —       | —                                     |
+| —              | assets/images/vfx/{{vfx}}.webp        | —       | —                                     |
 | —              | —                                     | —       | assets/audio/sfx/{{sfx_filename}}.mp3 |
 | —              | —                                     | —       | assets/audio/bgm/{{bgm_filename}}.mp3 |
 
@@ -97,6 +118,17 @@ CRITICAL: This mapping is the integration contract!
 - Developer references EXACTLY these paths in code
 - Path mismatch = integration failure
 - Use "—" for cells that don't apply
+
+Transparency convention (TA auto-derives from path — PM does NOT define):
+  assets/images/bg/   → opaque, full-screen background (TA verifies edge-to-edge)
+  assets/images/ui/   → needs alpha (TA applies chroma key + remove-background)
+  assets/images/txt/  → needs alpha (TA applies chroma key + remove-background)
+  assets/images/vfx/  → needs alpha (TA applies chroma key + remove-background)
+  assets/images/tiles/ → needs alpha by default (except card faces / board pieces)
+  assets/audio/       → N/A (not image)
+
+TA determines chroma key color (green/blue/magenta) based on element color palette
+and color conflict rules — see ta-pipeline-cookbook.md Step 0e.
 -->
 
 ## Text Assets
@@ -117,16 +149,38 @@ TA extracts each text element using segment and saves to the specified path.
 
 ### Digit Sprite Strip (for dynamic numbers)
 
-- **Characters**: `{{digit_characters}}`
+- **Characters**: `{{digit_characters}}` _(typical "0123456789" — frameCount = 10)_
 - **Cell size**: {{cell_w}}x{{cell_h}}
-- **Asset path**: `assets/images/ui/digits.webp`
+- **Asset path**: `assets/images/txt/digits.webp` _(recommended: text-class lives under `images/txt/` per Transparency Classification)_
+- **Sidecar path (optional)**: `assets/images/txt/digits.json` _(only when laid out as multi-row grid; single-row strip can omit)_
+- **Layout**: single-row horizontal strip (default) — total width = `cell_w × frameCount`, height = `cell_h`
+- **Alpha**: required (channels = 4); TA uses **bluescreen** chroma (text typically gold/white — avoid green key)
 
 <!--
 PM defines the character set based on what dynamic text the game needs.
-Common sets:
-- Score only: "0123456789"
-- Score + timer: "0123456789:."
-- Score + multiplier: "0123456789x+,."
-Designer generates a single horizontal strip image with all characters in order.
-Developer slices by character index at runtime (char_x = index * cell_w).
+
+Common sets (always include digits 0–9 first, then any symbols):
+- Score only:         "0123456789"                 (frameCount = 10)
+- Score + timer:      "0123456789:."               (frameCount = 12)
+- Score + multiplier: "0123456789x+,."             (frameCount = 14)
+
+Path convention (TA Transparency Classification + Compliance Gate):
+- `assets/images/txt/digits.webp`   — preferred (text class → bluescreen, channels=4)
+- `assets/images/txt/digits_{{label}}.webp` — when multiple digit styles exist (score / countdown / level)
+- Legacy `assets/images/ui/digits.webp` works but TA must still classify it as text (bluescreen, not greenscreen).
+
+Layout (default single horizontal row):
+- Total width  = cell_w × frameCount
+- Total height = cell_h
+- Cell origin (0-based, row-major): x = index × cell_w, y = 0
+- Developer slices at runtime: char_x = index × cell_w
+
+Multi-row digit grid (rare — e.g. small + large digits in one sheet) MUST supply a `.json` sidecar
+describing each frame; Compliance Gate then checks dimensions against that sidecar.
+
+Compliance Gate (TA verifies before STOP):
+- frameCount = character count above
+- total width × height matches the layout (single-row or sidecar)
+- channels = 4 (alpha)
+- dark-bg verify: no chroma residue around digit edges
 -->

package/project-template/templates/project-state.template.md

@@ -4,11 +4,11 @@
 
 | Field                   | Value                                                                 |
 | ----------------------- | --------------------------------------------------------------------- |
-| **workflowSpecVersion** | `production-serial-v1`                                                |
+| **workflowSpecVersion** | `convergence-v1`                                                      |
 | **Changelog**           | [docs/team/workflow-changelog.md](../docs/team/workflow-changelog.md) |
 
 <!--
-  production-serial-v1: Gate #2b → production Wave 1 Designer Ph.2 → Wave 2 TA → integration Developer.
+  convergence-v1: Three convergence loops — design_check (Gate #1/#2b) → ui_pass/ui_review/ui_rework → gameplay_pass/load_check → Gate #3.
   Visual baseline (designer-handoff-v2): Phase 1 = MC + ASR; Phase 2 Designer = audio + digit strip + VisualAtom status only.
 -->
 
@@ -32,7 +32,7 @@
 
 **{{current_stage}}** — {{stage_description}}
 
-`pm` → `style_exploration` → `production` → `integration` → `review` ⇄ `rework` → `done`
+`pm` → `style_exploration` → `production` → `ui_pass` → `ui_review` ⇄ `ui_rework` → `gameplay_pass` → `done`
 
 <!-- Stage definitions: see CLAUDE.md § Stage Model -->
 
@@ -40,12 +40,12 @@
 
 > Only the **orchestrator** runs `AskUserQuestion` toward the user. Sub-agents set `pending` and STOP.
 
-| Gate               | Status             | Notes                                                                           |
-| ------------------ | ------------------ | ------------------------------------------------------------------------------- |
-| #1 Direction       | {{passed/pending}} | Orchestrator confirms after PM four docs + STOP                                 |
-| #2a MC selection   | {{passed/pending}} | Orchestrator picks A/B/C → sets `selectedMcOption` below                        |
-| #2b MC + ASR final | {{passed/pending}} | Orchestrator confirms MC + ASR sheets (UI + element) → then `stage: production` |
-| #3 Dev acceptance  | {{passed/pending}} | User opens devUrl (orchestrator link only)                                      |
+| Gate               | Status             | Notes                                                                        |
+| ------------------ | ------------------ | ---------------------------------------------------------------------------- |
+| #1 Direction       | {{passed/pending}} | Orchestrator confirms after PM four docs + Reviewer design_check + STOP      |
+| #2a MC selection   | {{passed/pending}} | Orchestrator picks A/B/C → sets `selectedMcOption` below                     |
+| #2b MC + ASR final | {{passed/pending}} | Reviewer design_check → Orchestrator confirms MC + ASR → `stage: production` |
+| #3 Dev acceptance  | {{passed/pending}} | Reviewer load_check pass → user opens devUrl (orchestrator link only)        |
 
 ## Agent handoff
 
@@ -82,13 +82,21 @@ Designer Gate #2a STOP:
   next_orchestrator_action: "Run Gate #2a"
   last_completed_by: designer
 
-Developer integration STOP:
+Developer ui_pass STOP:
   subagent: developer
   subagent_stop: true
   waiting_for: orchestrator
   gate_pending: null
-  next_orchestrator_action: "Invoke @reviewer"
+  next_orchestrator_action: "Invoke @reviewer ui_diff"
   last_completed_by: developer
+
+Reviewer ui_diff pass STOP:
+  subagent: reviewer
+  subagent_stop: true
+  waiting_for: orchestrator
+  gate_pending: null
+  next_orchestrator_action: "Set stage=gameplay_pass, invoke @developer"
+  last_completed_by: reviewer
 -->
 
 ## Gate resume fields
@@ -96,30 +104,40 @@ Developer integration STOP:
 | Field            | Value                                              |
 | ---------------- | -------------------------------------------------- |
 | selectedMcOption | {{A / B / C — set by orchestrator after Gate #2a}} |
-| reworkRound      | {{0 / 1 / 2 — incremented by Reviewer on fail}}    |
+| uiReworkRound    | {{0–5 — incremented by Reviewer on ui_diff fail}}  |
 
 ## Dev Preview
 
-| Field            | Value                                                                        |
-| ---------------- | ---------------------------------------------------------------------------- |
-| devCommand       | npm run dev                                                                  |
-| devScript        | {{from package.json scripts.dev}}                                            |
-| devUrl           | {{http://... — Developer records when ready; orchestrator uses for Gate #3}} |
-| devStatus        | pending / ready / blocked_upstream / failed                                  |
-| devBlockers      | {{list: assetPath, issue, routeTo (TA/Designer/PM), status}}                 |
-| devStartedBy     | developer / reviewer / orchestrator                                          |
-| devLastChecked   | {{ISO timestamp}}                                                            |
-| reviewerDevCheck | pending / passed / failed                                                    |
-| reviewerDevNotes | {{UI + gameplay check summary}}                                              |
+| Field          | Value                                                                        |
+| -------------- | ---------------------------------------------------------------------------- |
+| devCommand     | npm run dev                                                                  |
+| devScript      | {{from package.json scripts.dev}}                                            |
+| devUrl         | {{http://... — Developer records when ready; orchestrator uses for Gate #3}} |
+| devStatus      | pending / ui_ready / ready / blocked_upstream / failed                       |
+| devBlockers    | {{list: assetPath, issue, routeTo (TA/Designer/PM), status}}                 |
+| devStartedBy   | developer / reviewer / orchestrator                                          |
+| devLastChecked | {{ISO timestamp}}                                                            |
+| loadCheck      | pending / passed / failed                                                    |
+| loadCheckNotes | {{console errors, white screen, load time}}                                  |
+
+## UI Review
+
+| Field            | Value                                      |
+| ---------------- | ------------------------------------------ |
+| uiReviewStatus   | pending / passed / failed                  |
+| uiReworkRound    | {{0–5}}                                    |
+| uiDiffReportPath | logs/review-report.md                      |
+| uiDiffNotes      | {{summary of MC vs screenshot comparison}} |
 
 <!--
 devStatus:
-  pending           — integration not finished
-  ready             — Developer self-check passed, no open blockers; safe to invoke Reviewer
+  pending           — ui_pass or gameplay_pass not finished
+  ui_ready          — UI shell complete (scene switch, layout, simple states); safe to invoke Reviewer ui_diff
+  ready             — gameplay_pass complete; safe to invoke Reviewer load_check
   blocked_upstream  — Developer waiting on TA/Designer rework (orchestrator re-invokes)
   failed            — dev server could not start; document error
 
-Developer MUST NOT set ready while devBlockers has open items.
+Developer MUST NOT set ui_ready/ready while devBlockers has open items.
 -->
 
 ## File Index
@@ -164,21 +182,21 @@ Developer MUST NOT set ready while devBlockers has open items.
 
 ### Reviewer Output
 
-| File                                                      | Description                                      | Status     |
-| --------------------------------------------------------- | ------------------------------------------------ | ---------- |
-| [review-report.md](logs/review-report.md)                 | Six-dimension evaluation + Dev walkthrough notes | {{status}} |
-| [intent-clarifications.md](docs/intent-clarifications.md) | Agent-to-agent Q&A (ICP)                         | {{status}} |
+| File                                                      | Description                                 | Status     |
+| --------------------------------------------------------- | ------------------------------------------- | ---------- |
+| [review-report.md](logs/review-report.md)                 | design_check / ui_diff / load_check reports | {{status}} |
+| [intent-clarifications.md](docs/intent-clarifications.md) | Agent-to-agent Q&A (ICP)                    | {{status}} |
 
 ## Production Pipeline (Serial)
 
-<!-- Only relevant when stage = production or transitioning to integration -->
+<!-- Only relevant when stage = production or transitioning to ui_pass -->
 
 | Wave | Agent            | Status     | Notes                                      |
 | ---- | ---------------- | ---------- | ------------------------------------------ |
 | 1    | Designer         | {{status}} | Ph.2: audio + digit + VisualAtom status    |
 | 2    | Technical Artist | {{status}} | Spec Quick-Check → bulk → Compliance green |
 
-<!-- Wave 3 Developer runs in stage = integration only — not tracked here -->
+<!-- Wave 3 Developer runs in stage = ui_pass — not tracked here -->
 
 ## Intent Clarification Tracking
 
@@ -203,7 +221,7 @@ PM monitors this table:
 Orchestrator serial rules:
   - Gate #2b passed → invoke @designer only (Wave 1)
   - Wave 1 = done → invoke @technical-artist (Wave 2)
-  - Wave 2 = done → stage: integration → invoke @developer
+  - Wave 2 = done → stage: ui_pass → invoke @developer
   - Optional: 30s spot-check ta-log Compliance + contract paths exist before @developer
 -->