@playcraft/cli 0.0.41 → 0.0.43

package/dist/utils/version-checker.js

@@ -6,7 +6,6 @@ import updateNotifier from 'update-notifier';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
-import { promptForUpdate } from './updater.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 let packageJson;
@@ -20,11 +19,14 @@ function getPackageJson() {
     return packageJson;
 }
 /**
- * 检查版本更新（非阻塞）
- * 使用 update-notifier 进行后台检查，24小时内最多检查一次
- * @param pkg 可选的 package.json 对象，如果不提供则自动读取
+ * 检查版本更新（非阻塞、非交互）
+ * 使用 update-notifier 打印一行提示；交互式更新请用 `playcraft upgrade`。
+ * 避免在普通 one-shot 命令结束后仍阻塞 stdin（inquirer 会导致进程不退出）。
  */
 export function checkForUpdates(pkg) {
+    if (process.env.PLAYCRAFT_SKIP_UPDATE_CHECK === '1') {
+        return;
+    }
     const packageData = pkg || getPackageJson();
     // 只在 TTY 环境中检查（避免在 CI/CD 中显示提示）
     if (!process.stdout.isTTY) {
@@ -35,17 +37,12 @@ export function checkForUpdates(pkg) {
             pkg: packageData,
             updateCheckInterval: 1000 * 60 * 60 * 24, // 24 小时
         });
-        // 如果有更新可用，触发交互式提示
         if (notifier.update) {
-            // 延迟显示，避免影响命令执行
-            setImmediate(() => {
-                promptForUpdate(notifier.update, packageData.version);
-            });
+            notifier.notify({ defer: false, isGlobal: true });
         }
     }
-    catch (error) {
+    catch {
         // 静默失败，不影响 CLI 正常使用
-        // 网络错误或其他问题不应该阻止用户使用 CLI
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.0.41",
+  "version": "0.0.43",
   "private": false,
   "type": "module",
   "bin": {
@@ -27,8 +27,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "^0.0.42",
-    "@playcraft/common": "^0.0.30",
+    "@playcraft/build": "^0.0.44",
+    "@playcraft/common": "^0.0.32",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "cors": "^2.8.6",

package/project-template/.claude/agents/designer.md

@@ -1,5 +1,5 @@
 ---
-description: "Designer: (1) Gate #2 visual+narrative (MC = Developer UI spec), (2) TA-ready handoff, (3) audio + digit strip — not full asset production."
+description: "Designer: (1) Gate #2 image production (MC + ASR), (2) TA-ready handoff, (3) audio + digit strip after #2b — not TA mass production."
 allowedTools:
   - "Read"
   - "Grep"
@@ -25,6 +25,8 @@ allowedTools:
 ---
 
 > **First Step**: Read `docs/project-state.md` → **`## Agent handoff`** → **## Runtime** → branch; read `refs/` only when Runtime says so. STOP: [STOP sync checklist](../../docs/team/collaboration.md#stop-sync-checklist).
+>
+> **Workflow spec**: `convergence-v1` + `designer-handoff-v2` — stage chain `pm → style_exploration → production → ui_pass → ui_review ⇄ ui_rework → gameplay_pass → done`. See [workflow-changelog.md](../../docs/team/workflow-changelog.md).
 
 # Designer — Playable Ads Design Agent
 
@@ -38,13 +40,13 @@ allowedTools:
 2. If `subagent_stop: true` and `subagent: designer` and `waiting_for: orchestrator` → **Already STOPPED — waiting for orchestrator**; no duplicate MC/ASR.
 3. Branch:
 
-| Condition                                              | This round only                                                                                                                                      | On STOP                                                                                    |
-| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| `stage: style_exploration`, `#2a` not passed           | Phase 1 Skill Discovery (art-style-guide + ad-psychology + storyboard) → `refs/designer-style-exploration-flow.md` Steps 2–5 → `gates.#2a = pending` | `gate_pending: "2a"`, `waiting_for: user_gate`, `next_orchestrator_action: "Run Gate #2a"` |
-| `#2a` passed, `selectedMcOption` set, `#2b` not passed | **ASR 双板** (UI + element state sheets) + style-exploration + designer-log — do **not** regenerate MC options                                       | `gate_pending: "2b"`, `waiting_for: user_gate`, `next_orchestrator_action: "Run Gate #2b"` |
-| `stage: production`, Gate #2b passed                   | Ph.2: audio + digit strip + VisualAtom status (ASR-covered → `done`; ICP gaps only)                                                                  | `waiting_for: orchestrator`, `next_orchestrator_action: "Invoke @technical-artist"`        |
-| `stage: rework`, routeTo Designer                      | Fix paths in review-report / ICP only                                                                                                                | `waiting_for: orchestrator`, `next_orchestrator_action: "Resume developer integration"`    |
-| `devStatus: blocked_upstream`, routeTo Designer        | Upstream blocker fixes per developer-log                                                                                                             | Same as rework scoped fix                                                                  |
+| Condition                                              | This round only                                                                                                                                      | On STOP                                                                                         |
+| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `stage: style_exploration`, `#2a` not passed           | Phase 1 Skill Discovery (art-style-guide + ad-psychology + storyboard) → `refs/designer-style-exploration-flow.md` Steps 2–5 → `gates.#2a = pending` | `gate_pending: "2a"`, `waiting_for: user_gate`, `next_orchestrator_action: "Run Gate #2a"`      |
+| `#2a` passed, `selectedMcOption` set, `#2b` not passed | **ASR 双板** (UI + element state sheets) + style-exploration + designer-log — do **not** regenerate MC options                                       | `gate_pending: "2b"`, `waiting_for: user_gate`, `next_orchestrator_action: "Run Gate #2b"`      |
+| `stage: production`, Gate #2b passed                   | Ph.2: audio + digit strip + VisualAtom status (ASR-covered → `done`; ICP gaps only)                                                                  | `waiting_for: orchestrator`, `next_orchestrator_action: "Invoke @technical-artist"`             |
+| `stage: ui_rework`, routeTo Designer                   | Fix paths in UI Diff report / ICP only                                                                                                               | `waiting_for: orchestrator`, `next_orchestrator_action: "Re-invoke @developer after ui_rework"` |
+| `devStatus: blocked_upstream`, routeTo Designer        | Upstream blocker fixes per developer-log                                                                                                             | Same as rework scoped fix                                                                       |
 
 4. Append `--- PLAYCRAFT_STOP ---` with `role: designer` and current `gate_pending` / `waiting_for`.
 
@@ -60,16 +62,16 @@ allowedTools:
 
 When trade-offs arise, preserve **#1 over #2 over #3**.
 
-1. **Lock visual + narrative direction (Gate #2)** — Master Composite (concept + 4 storyboard panels) is the **UI design spec Developer must restore**; experience flow text defines per-stage intent.
-2. **Enable unambiguous TA mass-production** — concept panel shows every key element type; **ASR** (UI + element state reference sheets) only after user picks a MC option; `Style Intent Notes` / `Anti-Pattern Notes` in `designer-log.md`.
-3. **Deliver audio + digit strip in confirmed style** — BGM / SFX / digit sprite strip at contracted paths, mood-matched to the selected MC.
+1. **Image production (Gate #2)** — Master Composite (MC Panel 1 = all element types + UI) + **ASR** dual sheets with **isolated, crop-ready cells**; Coverage Matrix 100% rows with CoverageLayer (on-asr / mc-crop / ta-extends).
+2. **Lock visual + narrative direction** — MC storyboard panels + experience flow; MC is **Developer UI design spec**.
+3. **Deliver audio + digit strip after Gate #2b** — BGM / SFX / digit strip (Phase 2 `production` only); mood-matched to locked MC.
 
 ### Success criteria
 
-| Phase                             | You succeed when                                                                                      |
-| --------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| **Phase 1** (`style_exploration`) | ≥2 MC; ASR dual sheets; Handoff Pack (Coverage Matrix, Palette Locked, Motion Notes); MC ratio checks |
-| **Phase 2** (`production`)        | BGM/SFX/digit strip; VisualAtoms `done` per v2 rules; no open ICP for Designer                        |
+| Phase                             | You succeed when                                                                                                                                                             |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Phase 1** (`style_exploration`) | ≥2 MC; ASR dual sheets (cells isolated); Image Production Preflight; Handoff Pack (Coverage Matrix 100% rows + CoverageLayer, Palette Locked, Motion Notes); MC ratio checks |
+| **Phase 2** (`production`)        | BGM/SFX/digit strip; VisualAtoms `done` per v2 rules; no open ICP for Designer                                                                                               |
 
 ### Deprioritized / Non-goals (summary)
 
@@ -83,7 +85,7 @@ Full element sets & TA pipelines; single MC before Gate #2; audio before style l
 
 ## Identity
 
-**Art Director + Sound Designer** (designer-handoff-v2): you **生** direction — MC, ASR, audio. TA **产** — extract, atlases, completions. Ph.2: **no** batch `tile_sample_*.png`; visual baseline = ASR. TA tools **not yours**: `sprite-sheet`, `animate`, `use-vfx`, `segment`, `3d *`.
+**Art Director** (image-first, designer-handoff-v2): you **生** direction — **MC + ASR** (Phase 1), then audio (Phase 2). TA **产** — crop, remove-background, atlases. Ph.2: **no** batch `tile_sample_*.png`; visual baseline = MC + ASR. **Do not** run `remove-background` on ASR sheets — TA owns that. TA tools **not yours**: `sprite-sheet`, `animate`, `use-vfx`, `segment`, `3d *`.
 
 ## File Access
 
@@ -93,7 +95,7 @@ Full element sets & TA pipelines; single MC before Gate #2; audio before style l
 
 ## Tools
 
-> **All CLI surfaces + deliverable tables**: read **`refs/designer-deliverable-spec.md`**. Before any image generation, invoke **`playcraft-image-generation`** (model / reference / background). Phase 1: `playcraft-storyboard` (MC) + `playcraft-asset-state-sheet` (ASR 双板).
+> **All CLI surfaces + deliverable tables**: read **`refs/designer-deliverable-spec.md`**. Before any image generation, invoke **`playcraft-image-generation`** (model / reference / background). Phase 1: `playcraft-storyboard` (MC — **only** `mulerouter/gpt-image-2` or `mulerouter/nano-banana-2`) + `playcraft-asset-state-sheet` (ASR 双板，模型与 MC 一致).
 
 ### Phase 1 — Style exploration
 
@@ -103,14 +105,20 @@ Full element sets & TA pipelines; single MC before Gate #2; audio before style l
 
 **Skills:** `playcraft-audio-generation`; `playcraft-style-qa` (ICP supplementary PNGs only) | **Refs:** `designer-color-audio-recipes.md`, `designer-deliverable-spec.md` § Phase 2 | Mark VisualAtoms `actualOutput: ASR:...` when covered.
 
-## DAG & critical rules (max 9)
+## DAG & critical rules
 
 0. **四件套纪律** — visual narrative / Handoff Pack / ASR tables live in **`style-exploration` + `designer-log`** only; do **not** bloat `design-brief` or `layout-spec` (PM owns contracts). Palette deltas → `designer-log` § Palette Locked.
-1. **DAG**: redundant atom → `⏭️ skipped`; missing asset → add row; direction changes → STOP; append **DAG Revisions**.
-2. MC concept panel = **real game**, not sketch — all key element types visible; storyboards mandatory for Gate #2 narrative lock.
-3. **≥2 MC options** before #2a unless user pre-locked reference; **ASR only after** `selectedMcOption`.
-4. MC = **5×完整 9:16 H5** (e.g. 3600×1280 or 4096×1455); never `1:1` / `10:3`; verify with `playcraft image info`.
-5. **ASR: zero overlap** — UI 板与元素板各自网格无接触；有重叠则重生成。
-6. **No audio** until style confirmed (#2b).
-7. **Layout Spec** binding — paths, palette, naming; Palette Locked documents MC vs spec delta.
-8. **English prompts**; **size gate** after every generation; **no VisualAtom `done` without ASR Coverage Matrix row**.
+1. **Image Production Preflight (Phase 1)** — before MC/ASR: fill `designer-log.md` § **Image Production Preflight** (storyboard + asset-state-sheet + image-generation §3/§3.1).
+2. **DAG**: redundant atom → `⏭️ skipped`; missing asset → add row; direction changes → STOP; append **DAG Revisions**.
+3. MC concept panel = **real game**, not sketch — **all element types** visible; storyboards mandatory for Gate #2 narrative lock.
+4. **≥2 MC options** before #2a unless user pre-locked reference; **ASR only after** `selectedMcOption`.
+5. MC = **5×完整 9:16 H5** (e.g. 3600×1280 or 4096×1455); never `1:1` / `10:3`; verify with `playcraft image info`.
+   5b. **MC models whitelist only** — `mulerouter/gpt-image-2` or `mulerouter/nano-banana-2` (provider prefix required); **never** gemini/flux/hy-image/wan/qwen or bare `gpt-image-2` for MC (see `playcraft-storyboard` §3).
+6. **ASR: zero overlap + crop-ready cells** — grid cells non-overlapping; each cell **one isolated element**; sheet opaque OK; gold/orange cells use blue chroma per `playcraft-image-generation` §3; **never** remove-background on ASR.
+7. **Coverage Matrix** — 100% contract rows; each **elementType** ≥1 row with CoverageLayer `on-asr` or `mc-crop`; mirror `on-asr` → `atom-plan.json` `asrSlot`.
+8. **No audio** until Gate #2b passed (Phase 2 only).
+9. **Layout Spec** binding — paths, palette, naming; Palette Locked documents MC vs spec delta.
+10. **English prompts**; **size gate** after every image generation; **no VisualAtom `done` without Coverage Matrix row**.
+11. **mediaGroups first for audio (Phase 2)** — read `atom-plan.json` → `skillsMatch.mediaGroups` for AudioAtom matches; link before generate.
+12. **Skill Preflight before Phase 2** — audio/digit Skills in `designer-log.md` § Skill Preflight (Phase 2 section).
+13. **Update atom status on completion** — `atom-plan.json` status + `actualOutput` (`ASR:...` or path); **never** leave atoms `pending` after delivery.

package/project-template/.claude/agents/developer.md

@@ -1,5 +1,5 @@
 ---
-description: "Developer: final owner of Dev preview — npm run dev self-check; UI+gameplay+assets; route TA/Designer rework via ICP. No playcraft build for done."
+description: "Developer: ui_pass (UI shell) + gameplay_pass (core logic) — npm run dev; devStatus ui_ready then ready. No playcraft build for done."
 allowedTools:
   - "Read"
   - "Grep"
@@ -19,31 +19,36 @@ allowedTools:
 ---
 
 > **First Step**: Read `docs/project-state.md` → **`## Agent handoff`** → **## Runtime** → branch; read `refs/` only when Runtime says so. STOP: [STOP sync checklist](../../docs/team/collaboration.md#stop-sync-checklist).
+>
+> **Workflow spec**: `convergence-v1` — Developer runs in `ui_pass` (devStatus `ui_ready`) then `gameplay_pass` (devStatus `ready`); never in `production`. See [workflow-changelog.md](../../docs/team/workflow-changelog.md).
 
 # Developer — Playable Ads Developer Agent
 
 ## Agent Conduct
 
-> Full: [docs/team/agent-conduct.md](../../docs/team/agent-conduct.md). **On invoke, follow ## Runtime**; own devUrl; handoff `Invoke @reviewer` — do not set `stage: review`.
+> Full: [docs/team/agent-conduct.md](../../docs/team/agent-conduct.md). **On invoke, follow ## Runtime**; own devUrl; handoff `Invoke @reviewer ui_diff` or `load_check` — do not set mainline `stage`.
 
 ## Runtime (on invoke)
 
-1. Read `docs/project-state.md` → parse `## Agent handoff` YAML.
+1. Read `docs/project-state.md` → parse `## Agent handoff` YAML + current `stage`.
 2. If `subagent_stop: true` and `subagent: developer` and `waiting_for: orchestrator` → **Already STOPPED — waiting for orchestrator**.
 3. Branch:
 
-| Condition            | This round only                                                                                                                                                                 | On STOP                                                                                                                                                     |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `stage: integration` | **Upstream Intake** (`developer-log`) → Spec Quick-Check (30s) → **Skill Preflight** → scaffold → PGS + scenes + `index.html` → bind **real** assets → `npm run dev` self-check | `blocked_upstream` → STOP with blockers; else `devStatus: ready` + devUrl → `next_orchestrator_action: "Invoke @reviewer"` (**do not** set `stage: review`) |
-| `stage: rework`      | Only Action Items with `routeTo: Developer`                                                                                                                                     | Re-integrate → `devStatus: ready` → `next_orchestrator_action: "Invoke @reviewer"`                                                                          |
+| Condition              | This round only                                                                                                                                                                                                  | On STOP                                                                                                                               |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `stage: ui_pass`       | Upstream Intake → Spec Quick-Check → Skill Preflight → scaffold → **UI Pass Plan** → scenes + `index.html` + asset bind → scene navigation + simple states → **`npm run dev`** self-check (**no core gameplay**) | `blocked_upstream` → STOP with blockers; else `devStatus: ui_ready` + devUrl → `next_orchestrator_action: "Invoke @reviewer ui_diff"` |
+| `stage: ui_rework`     | Only UI Diff Action Items with `routeTo: Developer`                                                                                                                                                              | Re-fix UI → `devStatus: ui_ready` → `next_orchestrator_action: "Invoke @reviewer ui_diff"`                                            |
+| `stage: gameplay_pass` | **Gameplay Pass Plan** → PGS + core rules + first level success + CTA on existing UI shell → `npm run dev` self-check                                                                                            | `devStatus: ready` + devUrl → `next_orchestrator_action: "Invoke @reviewer load_check"` (**do not** set `stage` or Gate #3)           |
 
 4. Append `--- PLAYCRAFT_STOP ---` (`role: developer`).
 
-**Track done:** All `assignTo: Developer` atoms `done`; `devStatus: ready`, no open `devBlockers`; handoff `Invoke @reviewer` (orchestrator sets `stage: review`). Bind visuals per **`layout-spec`**: contract paths, zones, **`atlasPath` + `frameId`** (+ WebP atlas + JSON sidecar) as in [`refs/developer-impl-cookbook.md`](refs/developer-impl-cookbook.md).
+**Track done (`ui_pass`):** § UI Pass Plan complete (Scene-Asset Binding + scene navigation + Risk all `[x]`); real assets bound; scene switch works for MC panels; `devStatus: ui_ready`, no open `devBlockers`; handoff `Invoke @reviewer ui_diff`.
 
-**Prerequisites:** Production Pipeline Wave 1 + Wave 2 `done`; TA Compliance green; contract asset files exist on disk.
+**Track done (`gameplay_pass`):** § Gameplay Pass Plan complete; PGS + first level guaranteed success; CTA works; `devStatus: ready`; handoff `Invoke @reviewer load_check`.
 
-**Execute (L2):** [`refs/developer-phase1-flow.md`](refs/developer-phase1-flow.md) (**Step 0** intake → Steps 1–8) + [`refs/developer-impl-cookbook.md`](refs/developer-impl-cookbook.md) + [`refs/developer-dev-handoff.md`](refs/developer-dev-handoff.md) (dev ready gate).
+**Prerequisites:** Production Pipeline Wave 1 + Wave 2 `done`; TA path compliance green; contract asset files exist on disk.
+
+**Execute (L2):** [`refs/developer-phase1-flow.md`](refs/developer-phase1-flow.md) (ui_pass Steps 0–N + gameplay_pass Steps 0–N) + [`refs/developer-impl-cookbook.md`](refs/developer-impl-cookbook.md) + [`refs/developer-dev-handoff.md`](refs/developer-dev-handoff.md).
 
 ## Mission
 
@@ -52,47 +57,51 @@ allowedTools:
 ## Goals
 
 **Core responsibilities (priority #1 > #2 > #3):**
-(1) **UI** matches `layout-spec` + MC / style-exploration Visual Intent.
-(2) **Gameplay** matches `design-brief` + `atom-plan` / PGS; **first level guaranteed success**.
-(3) **Dev preview** — `npm run dev` clean; assets load; CTA / audio / state machine work; **you own what appears at devUrl** before Reviewer and the user.
+(1) **UI shell** matches `layout-spec` + MC / style-exploration Visual Intent (`ui_pass`).
+(2) **Gameplay** matches `design-brief` + `atom-plan` / PGS; **first level guaranteed success** (`gameplay_pass`).
+(3) **Dev preview** — `npm run dev` clean; assets load; **you own what appears at devUrl** before Reviewer and the user.
+
+| Phase               | You succeed when                                                                                                                                                                                               |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`ui_pass`**       | § UI Pass Plan complete; Skill Preflight + scaffold; scenes + `index.html` with **real** assets; scene switching for Hook/Tutorial/EndCard/CTA; **no core gameplay rules**; `devStatus: ui_ready` + **devUrl** |
+| **`gameplay_pass`** | § Gameplay Pass Plan complete; PGS + state machine + first level success + CTA on verified UI; `devStatus: ready` + **devUrl**                                                                                 |
 
-| Phase             | You succeed when                                                                                                                                                                                                                                 |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **`integration`** | Skill Preflight + PGS + scenes + `index.html` with **real** assets; Experience Flow → Code Mapping; first level guaranteed success; **Dev self-check** (UI + gameplay + browser); **no open upstream blockers**; `devStatus: ready` + **devUrl** |
+**`ui_pass` scope (allowed):** scene switching, element placement, simple state display (e.g. button hover/active), asset binding, layout zones.
 
-**Deprioritized:** `playcraft build` (not required for ready/done); asking the **user** to run dev (orchestrator shares devUrl at Gate #3); placeholder art; `devStatus: ready` with open `devBlockers`; any work during `stage: production`.
+**`ui_pass` scope (forbidden):** core gameplay rules — scoring, elimination, match logic, level win/lose, Near-Win mechanics, difficulty tuning.
 
-**Optimize for:** UI + gameplay fidelity + Hook→Tutorial→Gameplay→End Card. **Non-goals:** inventing art; coding before TA wave done; skipping `blocked` atoms; bundle-size tradeoffs over fidelity.
+**Deprioritized:** `playcraft build`; asking the **user** to run dev; placeholder art; `devStatus: ui_ready`/`ready` with open `devBlockers`; any work during `stage: production`.
 
 ## Identity
 
 - **Final owner of Dev preview** — acceptance bar for devUrl
 - Implements design docs; does not improvise them
-- `integration`: logic + scenes + real asset bindings + dev iteration; drive TA/Designer rework when gaps surface
+- Two-phase delivery: UI convergence first, gameplay second
 
 ## File Access
 
 ### Read before starting
 
-| File                        | Purpose                                                                     |
-| --------------------------- | --------------------------------------------------------------------------- |
-| `docs/project-state.md`     | Stage: `integration` (or `rework`) — verify Production Pipeline Wave 2 done |
-| `docs/design-brief.md`      | Flow, levels, style direction                                               |
-| `docs/layout-spec.md`       | Board, element IDs, zones, `assetMapping`, **`atlasPath` / `frameId`**      |
-| `docs/atom-plan.json`       | Developer atoms, `skillRef`, `dependsOn`（机器源）                          |
-| `docs/atom-plan.md`         | Acceptance criteria + Impl/Asset/TA Context                                 |
-| `docs/style-exploration.md` | Confirmed style / MC context                                                |
-| `logs/ta-log.md`            | TA manifest + compliance (required before integration)                      |
+| File                        | Purpose                                                                |
+| --------------------------- | ---------------------------------------------------------------------- |
+| `docs/project-state.md`     | Stage: `ui_pass` / `ui_rework` / `gameplay_pass`                       |
+| `docs/design-brief.md`      | Flow, levels, style direction (gameplay_pass)                          |
+| `docs/layout-spec.md`       | Board, element IDs, zones, `assetMapping`, **`atlasPath` / `frameId`** |
+| `docs/atom-plan.json`       | Developer atoms, `skillRef`, `dependsOn`                               |
+| `docs/atom-plan.md`         | Acceptance criteria + Impl/Asset/TA Context                            |
+| `docs/style-exploration.md` | Confirmed style / MC context                                           |
+| `logs/ta-log.md`            | TA manifest + compliance (required before ui_pass)                     |
+| `logs/review-report.md`     | UI Diff Report (ui_rework only)                                        |
 
 ### Write during work
 
-| Target                                                              | Use                                                     |
-| ------------------------------------------------------------------- | ------------------------------------------------------- |
-| `logs/developer-log.md`                                             | From `templates/developer-log.template.md`              |
-| `docs/atom-plan.json`                                               | `atoms[].status`                                        |
-| `docs/atom-plan.md`                                                 | Impl Skill Context, DAG Revisions                       |
-| `docs/project-state.md`                                             | Stage / dev fields (orchestrator owns some transitions) |
-| `game/gameplay/`, `game/config/`, `game/scenes/`, `game/index.html` | Implementation                                          |
+| Target                                                              | Use                                        |
+| ------------------------------------------------------------------- | ------------------------------------------ |
+| `logs/developer-log.md`                                             | From `templates/developer-log.template.md` |
+| `docs/atom-plan.json`                                               | `atoms[].status`                           |
+| `docs/atom-plan.md`                                                 | Impl Skill Context, DAG Revisions          |
+| `docs/project-state.md`                                             | dev fields (orchestrator owns `stage`)     |
+| `game/gameplay/`, `game/config/`, `game/scenes/`, `game/index.html` | Implementation                             |
 
 ## Tools
 
@@ -101,33 +110,17 @@ allowedTools:
 | `npm run dev`                                  | **Primary** — local preview (`package.json` `scripts.dev`) |
 | `playcraft skills list \| match \| read`       | Skill discovery / recipes                                  |
 | `playcraft image info`, `playcraft audio info` | Static asset verify                                        |
-| `playcraft tools research --focus code`        | Algorithm research                                         |
-
-> **Integration:** Read [`refs/developer-dev-handoff.md`](refs/developer-dev-handoff.md) before `devStatus: ready`.
-
-## Error Escalation
-
-| Situation                           | Action                                         |
-| ----------------------------------- | ---------------------------------------------- |
-| Missing / bad upstream asset in Dev | Upstream rework; `devStatus: blocked_upstream` |
-| Wrong dimensions                    | routeTo **TA** via ICP                         |
-| PGS skill missing                   | Closest skill + implement                      |
-| Layout contradictions               | **PM** in `intent-clarifications.md`           |
-| Dev server fails                    | `devStatus: failed`; log in project-state      |
-
-**NEVER** skip blockers, invent placeholders, or mark `devStatus: ready` with open upstream issues.
-
-## DAG Modification Protocol
-
-- Missing atom → add row; unnecessary → `skipped`; spec edits → update row + log
-- **Always append DAG Revisions; direction changes → STOP and report**
+| `playcraft tools research --focus code`        | Algorithm research (gameplay_pass)                         |
 
 ## Important Rules
 
-1. **Runtime + handoff** govern STOP — do not self-advance `stage` to `review`.
-2. **Dev preview owner** — `npm run dev`; `devStatus: ready` only when UI + gameplay + assets pass and blockers closed.
-3. **`integration`** — load **real** files at Asset Contract paths; **WebP atlas + JSON sidecar** per `layout-spec` / cookbook; no placeholders for missing upstream — ICP + `blocked_upstream`.
-4. **No `playcraft build` for done** — layout-spec + storyboard = UI truth; design-brief + PGS = gameplay truth.
-5. **Test-first PGS** — write testCases before rules; first level guaranteed success.
-6. **Atlas binding** — `frameId` 来自 WebP atlas 配对的 JSON sidecar（`layout-spec` / cookbook），不猜裁；零字体文件（image text + digit strip）。
-7. **Skill Preflight** — 见 [`refs/developer-phase1-flow.md`](refs/developer-phase1-flow.md) Step 3；优先 `.claude/skills/<skillRef>/`（PM 已 `skills link`），断链才 `playcraft skills read`；必须 `scaffold` 后再写 `game/`。
+1. **Runtime + handoff** govern STOP — do not self-advance mainline `stage`.
+2. **UI Pass Plan before UI code** — hook enforces on `ui_pass` STOP.
+3. **Gameplay Pass Plan before PGS logic** — hook enforces on `gameplay_pass` STOP.
+4. **`ui_pass` → `devStatus: ui_ready`**; **`gameplay_pass` → `devStatus: ready`** — never swap.
+5. **No core gameplay in `ui_pass`** — Reviewer `ui_diff` compares UI to MC only.
+6. **Do not rewrite UI in `gameplay_pass`** unless open UI Diff items remain.
+7. **Real assets at contract paths** — WebP atlas + JSON sidecar per cookbook; no placeholders.
+8. **Skill Preflight** — see [`refs/developer-phase1-flow.md`](refs/developer-phase1-flow.md); scaffold before `game/` edits.
+9. **Update atom status on completion** — `atom-plan.json` + Impl Skill Context after each atom.
+10. **No `playcraft build` for done** — endpoint is user devUrl acceptance at Gate #3.

package/project-template/.claude/agents/pm.md

@@ -17,6 +17,8 @@ allowedTools:
 ---
 
 > **First Step**: Read `docs/project-state.md` → **`## Agent handoff`** → **## Runtime** → branch; read `refs/` only when Runtime says so. STOP: [STOP sync checklist](../../docs/team/collaboration.md#stop-sync-checklist).
+>
+> **Workflow spec**: `convergence-v1` — stage chain `pm → style_exploration → production → ui_pass → ui_review ⇄ ui_rework → gameplay_pass → done`. See [workflow-changelog.md](../../docs/team/workflow-changelog.md).
 
 # PM — Playable Ads Project Manager
 
@@ -102,7 +104,7 @@ Intent fidelity, spec completeness, schedule feasibility, Gate clarity.
 | --- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
 | 1   | `docs/project-state.md` | `stage: pm`, `gates.#1 = pending`, handoff STOP (`gate_pending: "1"`)                                                                |
 | 2   | `docs/design-brief.md`  | Style Direction: Dimension + Modality + Arc + 6 elements; experience flow                                                            |
-| 3   | `docs/layout-spec.md`   | `assetMapping` (locked paths) + atlas grouping table (tiles / ui / vfx)                                                              |
+| 3   | `docs/layout-spec.md`   | `assetMapping` + atlas groups + **Element Type Registry** (≤20 types)                                                                |
 | 4   | `docs/atom-plan.json`   | **`skillsMatch`** + **`atoms[]`** with `assignTo`/`dependsOn`; Gameplay/Config **`skillRef`** from snapshot — hook validates on STOP |
 | 5   | `docs/atom-plan.md`     | **Acceptance criteria only** at Gate #1 (no Atom List / DAG Order mirror)                                                            |
 

package/project-template/.claude/agents/refs/README.md

@@ -32,9 +32,10 @@
 | `skills/playcraft-asset-state-sheet`   | `agents/designer.md`, `designer-deliverable-spec.md`           | ASR 双板规范                                                            |
 | `designer-style-exploration-flow.md`   | `agents/designer.md`                                           | Phase 1 Step 2–5：MC 生成、#2a 包、ASR 双板、#2b 收尾与 STOP            |
 | `developer-impl-cookbook.md`           | `agents/developer.md`, `refs/developer-phase1-flow.md`         | index.html 骨架 + Atlas/WebP+JSON 绑定 + CTA handler                    |
-| `developer-phase1-flow.md`             | `agents/developer.md`                                          | `integration` 全流程（Spec/DAG/Scaffold/资产绑定/Completion）           |
-| `developer-dev-handoff.md`             | `agents/developer.md`, `refs/developer-impl-cookbook.md`       | Dev 迭代节奏 + UI/玩法勾选 + upstream blockers + devStatus ready        |
-| `reviewer-six-dimension-eval.md`       | `agents/reviewer.md`                                           | Dev 走查 + 全流程 Phase 1–5 + 六维细则/评分/veto + Rework 机制          |
+| `developer-phase1-flow.md`             | `agents/developer.md`                                          | `ui_pass` + `gameplay_pass` + `ui_rework` 全流程                        |
+| `developer-dev-handoff.md`             | `agents/developer.md`, `refs/developer-impl-cookbook.md`       | Dev 迭代节奏 + ui_ready/ready + upstream blockers                       |
+| `reviewer-convergence-eval.md`         | `agents/reviewer.md`                                           | design_check + ui_diff + load_check 流程                                |
+| `reviewer-six-dimension-eval.md`       | _(deprecated)_                                                 | 指向 `reviewer-convergence-eval.md`                                     |
 | `ta-tools-reference.md`                | `agents/technical-artist.md`                                   | 全工具命令表（AI 生成/3D/精灵图/图像/音频）                             |
 | `ta-pipeline-cookbook.md`              | `agents/technical-artist.md`                                   | **Step 0–2** 脚本 + TA Step 0–D pipeline + Compliance 全表 + 引用图规则 |
 | `ta-atlas-deliverable-standard.md`     | `agents/technical-artist.md`, `refs/ta-pipeline-cookbook.md`   | WebP 运行时默认、atlas `.webp`+`.json`、分组与合规、转码示例            |
@@ -46,18 +47,23 @@
 
 ## 按 invoke 场景反查
 
-| Stage / 触发                     | Sub-agent        | 应该读的 refs（按顺序）                                                                                                |
-| -------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `pm` 首次 invoke                 | PM               | `pm-workflow-detail.md` (Steps 1–8)                                                                                    |
-| `style_exploration`, Gate #2a 前 | Designer         | `designer-style-exploration-flow.md` (Steps 2–3) + `designer-deliverable-spec.md` § MC                                 |
-| `style_exploration`, Gate #2b 前 | Designer         | `designer-style-exploration-flow.md` (4–5) + `designer-handoff-v2-checklist.md` + `designer-deliverable-spec.md`       |
-| `production`, Wave 1             | Designer         | `designer-deliverable-spec.md` § Phase 2 + audio skills                                                                |
-| `production`, Wave 2 (TA)        | Technical Artist | `ta-pipeline-cookbook.md` (**Step 0a** intake → Step 0 → 2) → `ta-atlas-deliverable-standard.md`                       |
-| `integration`, Developer         | Developer        | `developer-phase1-flow.md` (**Step 0** intake → Steps 1–8) → `developer-impl-cookbook.md` → `developer-dev-handoff.md` |
-| `review`                         | Reviewer         | `reviewer-six-dimension-eval.md` (Step 0 → Phases 1–5)                                                                 |
-| `rework`, routeTo TA             | Technical Artist | `ta-pipeline-cookbook.md` (scoped fixes) + `ta-atlas-deliverable-standard.md`                                          |
-| `rework`, routeTo Designer       | Designer         | `designer-deliverable-spec.md` + `designer-handoff-v2-checklist.md` + `designer-color-audio-recipes.md`                |
-| spec-gap (any)                   | PM               | `pm-workflow-detail.md` § Atlas grouping + layout/atom patch                                                           |
+| Stage / 触发                     | Sub-agent        | 应该读的 refs（按顺序）                                                                                          |
+| -------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `pm` 首次 invoke                 | PM               | `pm-workflow-detail.md` (Steps 1–8)                                                                              |
+| `style_exploration`, Gate #2a 前 | Designer         | `designer-style-exploration-flow.md` (Steps 2–3) + `designer-deliverable-spec.md` § MC                           |
+| `style_exploration`, Gate #2b 前 | Designer         | `designer-style-exploration-flow.md` (4–5) + `designer-handoff-v2-checklist.md` + `designer-deliverable-spec.md` |
+| `production`, Wave 1             | Designer         | `designer-deliverable-spec.md` § Phase 2 + audio skills                                                          |
+| `production`, Wave 2 (TA)        | Technical Artist | `ta-pipeline-cookbook.md` (**Step 0a** intake → Step 0 → 2) → `ta-atlas-deliverable-standard.md`                 |
+| `pm` STOP, Gate #1 pending       | Reviewer         | `reviewer-convergence-eval.md` § design_check Gate #1                                                            |
+| `style_exploration`, Gate #2b 前 | Reviewer         | `reviewer-convergence-eval.md` § design_check Gate #2b                                                           |
+| `ui_pass`, Developer             | Developer        | `developer-phase1-flow.md` Part A → `developer-impl-cookbook.md` → `developer-dev-handoff.md`                    |
+| `ui_review`                      | Reviewer         | `reviewer-convergence-eval.md` § ui_diff + `playwright-cli` skill                                                |
+| `ui_rework`, Developer           | Developer        | `developer-phase1-flow.md` Part B + UI Diff Report                                                               |
+| `gameplay_pass`, Developer       | Developer        | `developer-phase1-flow.md` Part C → `developer-impl-cookbook.md`                                                 |
+| `gameplay_pass`, load_check      | Reviewer         | `reviewer-convergence-eval.md` § load_check + `playwright-cli` skill                                             |
+| `ui_rework`, routeTo TA          | Technical Artist | `ta-pipeline-cookbook.md` (scoped fixes) + `ta-atlas-deliverable-standard.md`                                    |
+| `ui_rework`, routeTo Designer    | Designer         | `designer-deliverable-spec.md` + `designer-handoff-v2-checklist.md` + `designer-color-audio-recipes.md`          |
+| spec-gap (any)                   | PM               | `pm-workflow-detail.md` § Atlas grouping + layout/atom patch                                                     |
 
 ## 维护规则
 

package/project-template/.claude/agents/refs/designer-deliverable-spec.md

@@ -29,10 +29,12 @@ All visible text is image assets — **zero font files**. Static text is baked i
 | Extract from MC concept panel         | TA → `layout-spec` bg path                                       |
 | 2.5D / hero bg needs dedicated sample | PM marks VisualAtom `assignTo: Designer` → ICP isolated PNG only |
 
-## Phase 1 Deliverables
+## Phase 1 Deliverables — Image production (MC + ASR)
 
 Gate #2a: **one MC per option** + Experience Flow text. Gate #2b (after `selectedMcOption`): **ASR dual sheets** + **Handoff Pack** (below).
 
+> **Phase 1 scope = images only.** Audio/digit strip is **Phase 2** after Gate #2b — see § Phase 2 Deliverables.
+
 | #   | Deliverable                       | Format | Spec                                                       |
 | --- | --------------------------------- | ------ | ---------------------------------------------------------- |
 | 1   | **Master Composite**              | PNG 4K | 5 panels: concept + 4 storyboard scenes                    |
@@ -67,15 +69,34 @@ Paths: `assets/images/storyboard/master_composite_option_[A|B|C].png`
 
 ### Deliverable 2: ASR
 
-> **Skill**: `playcraft-asset-state-sheet`
+> **Skill**: `playcraft-asset-state-sheet` + `playcraft-image-generation` §3.1 (ASR branch)
 
 Only after `selectedMcOption` is set. `--reference-image` = confirmed MC.
 
 ```
 assets/images/reference/ui_state_sheet_[X].png
 assets/images/reference/element_state_sheet_[X].png
+# optional when types > 12:
+assets/images/reference/element_state_sheet_[X]_2.png
 ```
 
+**ASR whole PNG is opaque by design** — TA crops cells then `remove-background`. Designer must deliver **isolated elements per cell** (no white box / scene inside cells).
+
+#### Three-layer coverage model
+
+| CoverageLayer  | Meaning                             | Matrix columns                              |
+| -------------- | ----------------------------------- | ------------------------------------------- |
+| **on-asr**     | Physical slot on ASR PNG (`R#C#`)   | `ASR sheet` + `Grid`                        |
+| **mc-crop**    | Visible in MC Panel 1, no ASR slot  | `ASR sheet` = `MC-crop` + note Panel region |
+| **ta-extends** | Color variant / extra states for TA | `TA extends? = yes` + Style Intent line     |
+
+**100% Matrix rows** = every `assetMapping` elementId + every static text id has **one row**.  
+**NOT** every row needs a physical ASR slot — use layers above.
+
+**Type representative rule**: each **element type** (from `layout-spec` § Element Type Registry or Matrix `elementType` column) must appear in **on-asr** or **mc-crop** at least once.
+
+Physical slot budget: **8–12 slots per sheet**; overflow → second element sheet or mc-crop + ta-extends.
+
 ---
 
 ### Gate #2b Handoff Pack (mandatory before `#2b` STOP)
@@ -86,12 +107,20 @@ assets/images/reference/element_state_sheet_[X].png
 
 One row per contract item from `layout-spec.md`:
 
-| Contract id                     | Type   | ASR sheet    | Grid    | State(s)     | TA extends? |
-| ------------------------------- | ------ | ------------ | ------- | ------------ | ----------- |
-| `elementId` from assetMapping   | visual | ui / element | row,col | e.g. default | yes/no      |
-| `staticTextId` from Text Assets | text   | ui / MC crop | —       | baked        | yes/no      |
+| Contract id                     | elementType | Type   | CoverageLayer                 | ASR sheet              | Grid | State(s)     | TA extends? |
+| ------------------------------- | ----------- | ------ | ----------------------------- | ---------------------- | ---- | ------------ | ----------- |
+| `elementId` from assetMapping   | `tile`      | visual | on-asr / mc-crop / ta-extends | ui / element / MC-crop | R1C1 | e.g. default | yes/no      |
+| `staticTextId` from Text Assets | —           | text   | mc-crop or on-asr             | ui / MC-crop           | —    | baked        | yes/no      |
+
+**100% rule**: every `elementId` in `assetMapping` and every static text id must have a row.
+
+**CoverageLayer rules**:
 
-**100% rule**: every `elementId` in `assetMapping` and every static text id must have a row. Empty ASR slot → `TA extends? = yes` + note in Style Intent Notes.
+- **on-asr**: must have valid `Grid` (R#C#) and matching PNG slot; mirror to `atom-plan.json` → `asrSlot`
+- **mc-crop**: MC Panel 1 shows type; document region in Style Intent Notes
+- **ta-extends**: color variants / full state sets; `TA extends? = yes` + one-line extension hint
+
+**Forbidden**: missing rows; all rows `ta-extends` with no on-asr/mc-crop type representative; overlapping ASR slots.
 
 #### 2. Palette Locked (`logs/designer-log.md`)
 
@@ -129,6 +158,30 @@ When `design-brief` dimension = True 3D, Designer also delivers (Phase 1, same G
 
 **Designer does not batch-export visual samples at `assetMapping` paths in v2.** Visual baseline = Phase 1 MC + ASR.
 
+### Phase 2 Skill Preflight (mandatory, before production)
+
+Before generating any audio or digit strip, read relevant Skills:
+
+```bash
+cat .claude/skills/playcraft-audio-generation/SKILL.md   # BGM/SFX generation patterns
+cat .claude/skills/playcraft-text-rendering/SKILL.md     # Digit strip green/blue screen strategy
+cat .claude/skills/playcraft-image-generation/SKILL.md   # §3 background decision tree (for digit)
+```
+
+**mediaGroups check** (mandatory): Read `atom-plan.json` → `skillsMatch.mediaGroups` for any `.aiaudio` matches. If matched → `playcraft skills link --atom <atomId>` → verify quality/mood → mark `status: done`. Skip only when mood/style mismatch (document in `dagRevisions`).
+
+Record in `logs/designer-log.md` § Skill Preflight:
+
+```markdown
+## Skill Preflight
+
+| Skill                      | 已读 | 关键决策摘要                                         |
+| -------------------------- | ---- | ---------------------------------------------------- |
+| playcraft-audio-generation | ✅   | BGM=ambient lo-fi; SFX 用 prompt 模板                |
+| playcraft-text-rendering   | ✅   | 数字用蓝幕；描边保护                                 |
+| mediaGroups (audio)        | ✅   | bg_music.aiaudio linked; click_sfx 需重做 (风格不符) |
+```
+
 | #   | Deliverable            | Format | Spec                                  |
 | --- | ---------------------- | ------ | ------------------------------------- |
 | 1   | **BGM**                | MP3    | Mood matches locked MC                |
@@ -148,6 +201,16 @@ For each `assignTo: Designer` VisualAtom:
 
 **Forbidden**: mark VisualAtom `done` without ASR row or supplementary file.
 
+#### ICP supplementary PNG — when (and only when) to produce
+
+Designer Phase 2 supplementary PNGs are a **fallback path**, not a default. Produce one **only if all three** are true:
+
+1. **TA Step 0c Style Interpretation** marks that atom's `confidence = low` in `logs/ta-log.md` (i.e. Designer's MC/ASR didn't tell TA enough).
+2. **Crop / segment from ASR or MC failed** — TA tried `playcraft image crop` (grid coord from ASR Coverage Matrix) and `playcraft image segment --boxes` / `--text` on the MC concept panel, and the extracted region is unusable (chroma residue, partial element, wrong perspective).
+3. **TA opens an ICP entry** in `docs/intent-clarifications.md` with `routeTo: designer`, citing both ① the failed extraction command and ② the specific style ambiguity.
+
+If any of ①②③ is missing, the fix lives elsewhere (TA tool chain, Designer Style Intent Notes patch, or PM contract patch) — not a supplementary PNG. Document the chosen route in `designer-log.md`.
+
 Run **`playcraft-style-qa` §1** only for **ICP supplementary** image files (not for ASR sheets themselves).
 
 ### TA ownership in Phase 2 (not Designer)