@playcraft/cli 0.0.42 → 0.0.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.0.42",
+  "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.43",
-    "@playcraft/common": "^0.0.31",
+    "@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
 
@@ -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
 
@@ -103,18 +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`.
-   4b. **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).
-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**.
-9. **mediaGroups first for audio** — read `atom-plan.json` → `skillsMatch.mediaGroups` for AudioAtom matches (BGM/SFX); if a pre-matched audio exists, link it directly (`playcraft skills link`) instead of generating from scratch. Skip only when quality/mood mismatch (document reason in `dagRevisions`).
-10. **Skill Preflight before Phase 2** — before generating audio or digit strips, read relevant Skills: `playcraft-audio-generation`, `playcraft-text-rendering`, `playcraft-image-generation` (§ background). Fill `designer-log.md` § Skill Preflight table. Do not "freelance" — follow platform patterns.
-11. **Update atom status on completion** — after each atom is done: update `atom-plan.json` → `atoms[].status = "done"` + `atoms[].actualOutput = "<path>"` (or `"ASR:<sheet>:<region>"`). Write `atom-plan.md` § Asset Skill Context. **Never** leave atoms at `pending` after delivery.
+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

@@ -19,6 +19,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` — 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
 

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/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. Empty ASR slot → `TA extends? = yes` + note in Style Intent Notes.
+**100% rule**: every `elementId` in `assetMapping` and every static text id must have a row.
+
+**CoverageLayer rules**:
+
+- **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`)
 
@@ -172,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)

package/project-template/.claude/agents/refs/designer-handoff-v2-checklist.md

@@ -8,17 +8,24 @@
 - [ ] `selectedMcOption` set (Gate #2a passed)
 - [ ] MC path: `assets/images/storyboard/master_composite_option_[X].png`
 - [ ] ASR paths exist and pass zero-overlap visual check
+- [ ] ASR cells: isolated elements, no white box / scene inside cells (whole sheet opaque is OK)
+- [ ] § **Image Production Preflight** filled (Phase 1 — three Skills read)
 
-## 1. ASR Coverage Matrix (100%)
+## 1. ASR Coverage Matrix (100% rows)
 
 In `logs/designer-log.md` § ASR Coverage Matrix:
 
-1. List every `elementId` from `layout-spec.md` § Asset Mapping (and atlas `frameId` groups count as one row per logical element).
+1. List every `elementId` from `layout-spec.md` § Asset Mapping (atlas `frameId` groups = one row per logical element).
 2. List every static text `id` from § Text Assets → Static Text.
-3. For each row: `ASR sheet` = `ui` | `element` | `MC-crop` | `ICP-pending`.
-4. `TA extends?` = `no` only when ASR shows final representative state; else `yes`.
+3. **Row count** must equal assetMapping + static text id count (verify before STOP).
+4. For each row, set **CoverageLayer** = `on-asr` | `mc-crop` | `ta-extends`.
+5. For each row: `ASR sheet` = `ui` | `element` | `element_2` | `MC-crop` | `ICP-pending`.
+6. `TA extends?` = `no` only when on-asr shows final representative state; else `yes`.
+7. **Sheet grid metadata** table filled with real numbers (not `{{placeholder}}`).
 
-**Stop rule**: any row missing → do not set `#2b` pending.
+**Type representative rule**: each distinct **elementType** (Matrix column or `layout-spec` § Element Type Registry) must have at least one row with CoverageLayer `on-asr` or `mc-crop`.
+
+**Stop rule**: any contract row missing → do not set `#2b` pending.
 
 ## 2. Palette Locked
 
@@ -50,9 +57,9 @@ In `docs/style-exploration.md` under confirmed option:
 ```
 For each atom-plan row where assignTo = Designer:
 ├─ VisualAtom + covered in Coverage Matrix?
-│   └─ yes → status=done, actualOutput=ASR:...
+│   └─ yes → status=done, actualOutput=ASR:... (on-asr rows → asrSlot in atom-plan.json)
 ├─ AudioAtom?
-│   └─ deliver MP3 at path → done
+│   └─ deliver MP3 at path → done (Phase 2 only)
 ├─ Gap / TA extract failed (ICP)?
 │   └─ generate one PNG → done with path, or blocked until answered
 └─ Never: done with only "will extract later"
@@ -60,9 +67,10 @@ For each atom-plan row where assignTo = Designer:
 
 ## 5. Files to verify before STOP
 
-| File                                                  | Contains                                                    |
-| ----------------------------------------------------- | ----------------------------------------------------------- |
-| `docs/style-exploration.md`                           | MC paths, Motion Notes, Experience Flow                     |
-| `logs/designer-log.md`                                | Coverage Matrix, Palette Locked, Style Intent, Anti-Pattern |
-| `assets/images/reference/ui_state_sheet_[X].png`      | exists                                                      |
-| `assets/images/reference/element_state_sheet_[X].png` | exists                                                      |
+| File                                                    | Contains                                                                  |
+| ------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `docs/style-exploration.md`                             | MC paths, Motion Notes, Experience Flow                                   |
+| `logs/designer-log.md`                                  | Image Production Preflight, Coverage Matrix, Palette Locked, Style Intent |
+| `assets/images/reference/ui_state_sheet_[X].png`        | exists                                                                    |
+| `assets/images/reference/element_state_sheet_[X].png`   | exists                                                                    |
+| `assets/images/reference/element_state_sheet_[X]_2.png` | if types > 12 / overflow                                                  |

package/project-template/.claude/agents/refs/designer-style-exploration-flow.md

@@ -1,15 +1,26 @@
 # Designer — Style exploration flow (Phase 1, steps 2–5)
 
-> **Scope**: After **Step 1 — Skill Discovery** in `agents/designer.md`, follow this document for MC generation through Gate #2b STOP. **Exit criteria** for Phase 1: see `agents/designer.md` Goals § Success criteria.
+> **Scope**: After **Step 1 — Skill Discovery** in `agents/designer.md`, follow this document for **image production** (MC + ASR) through Gate #2b STOP. **Exit criteria**: see `agents/designer.md` Goals § Success criteria.
 >
 > **Deliverable shapes & tables**: `refs/designer-deliverable-spec.md`.
 
 **Trigger**: `project-state.md` stage = `style_exploration`
 
+## Step 1.5 — Image Production Preflight (before MC option B+ or before ASR)
+
+Fill `logs/designer-log.md` § **Image Production Preflight**:
+
+1. Read `playcraft-storyboard`, `playcraft-asset-state-sheet`, `playcraft-image-generation` (§3 + §3.1)
+2. Mark each Skill row ✓ with one-line decision summary
+3. Read `layout-spec.md` — count assetMapping rows + note Element Type Registry (if present)
+
+**Do not generate ASR until this section is complete.**
+
 ## Step 2 — Generate Master Composite only (one image per option A/B[/C])
 
 - Follow `playcraft-storyboard` skill：**每格完整 9:16 H5**；`45:16` + `--width 3600 --height 1280`（2K）或 `4096×1455`（4K）；**禁止 `1:1` / `10:3`**
-- 每个方案用不同模型（见 `refs/designer-master-composite-recipes.md`）
+- **Panel 1 must show every element type** from `layout-spec` (or Element Type Registry)
+- 每个方案用不同 prompt/美术方向（模型均用白名单，见 `refs/designer-master-composite-recipes.md`）
 - 生成后立即 `playcraft image info`：总比例 **width/height ≈ 2.81**，**(width÷5)/height ≈ 0.5625**；不合格则重生成
 - **Review the auto-generated `.json` sidecar** — 确认 `aspectRatio` / `imageSize` / 实际像素正确
 
@@ -22,16 +33,35 @@
 ## Step 4 — Generate ASR sheets（仅针对 `project-state.selectedMcOption`）
 
 - Read `selectedMcOption` from `docs/project-state.md` — if missing, **STOP**
-- Follow `playcraft-asset-state-sheet` skill
-- 输出两张 4K 板：`ui_state_sheet_[X].png` + `element_state_sheet_[X].png`（见 `designer-deliverable-spec.md` §2）
-- `--reference-image` = `master_composite_option_[selectedMcOption].png`
-- 生成后 `playcraft image info` 检查；若槽位重叠，必须重生成
+- **Re-read** `playcraft-asset-state-sheet` + `playcraft-image-generation` §3.1 (cell chroma / isolated)
+- 输出：`ui_state_sheet_[X].png` + `element_state_sheet_[X].png`（类型 >12 时可加 `element_state_sheet_[X]_2.png`）
+- `--reference-image` = `master_composite_option_[selectedMcOption].png`；`--image-model` 与 MC 一致
+- Prompt：sheet `#808080` 或统一色幕；每格 **one isolated element**；金/橙格用蓝幕
+- 生成后 `playcraft image info`；目视：零重叠、格内无白盒/场景底
+- **Do not** `remove-background` on ASR — TA handles post-crop
 
 ## Step 5 — Gate #2b Handoff Pack
 
 > **Checklist**: `refs/designer-handoff-v2-checklist.md`
 
 1. 补全 `docs/style-exploration.md`（ASR 路径、**Motion Notes**、Experience Flow）
-2. 更新 `logs/designer-log.md`：**ASR Coverage Matrix**（100% contract rows）、**Palette Locked**、Style Intent / Anti-Pattern
-3. 更新 handoff + `gates.#2b = pending`
-4. **STOP** — 禁止 Phase 2 音频与批量视觉样本 PNG
+2. 更新 `logs/designer-log.md`：
+   - **ASR Coverage Matrix** — 100% contract rows + **CoverageLayer** column
+   - 每种 **elementType** ≥1 行 `on-asr` 或 `mc-crop`
+   - **Palette Locked**、Style Intent / Anti-Pattern
+   - Mirror `on-asr` rows → `atom-plan.json` → `atoms[].asrSlot`
+3. **Self-check before STOP**:
+
+```bash
+# MC ratio
+playcraft image info --input assets/images/storyboard/master_composite_option_[X].png
+
+# Count contract rows (adjust grep to your layout-spec format)
+grep -c 'elementId\|"id":' docs/layout-spec.md   # approximate — Matrix row count must match
+
+# ASR files exist
+ls assets/images/reference/ui_state_sheet_[X].png assets/images/reference/element_state_sheet_[X].png
+```
+
+4. 更新 handoff + `gates.#2b = pending`
+5. **STOP** — 禁止 Phase 2 音频与批量视觉样本 PNG

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

@@ -96,7 +96,7 @@ Set `project-state.md`:
 2. `npm run dev`
 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: ready` and stage → `review`
+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`)
 
 ## Dev ready checklist (`devStatus: ready` — all required)
 

package/project-template/.claude/agents/refs/pm-workflow-detail.md

@@ -141,7 +141,7 @@ Design the shared contract between Designer, TA, and Developer:
 3. **Asset specifications** — size, format, naming for each type
 4. **Asset mapping** — element ID → file path (the integration bridge)
 
-**Critical**: `assetMapping` paths are **locked after Gate #1**. No agent may unilaterally change paths — this is the Asset Contract: TA fills paths in production Wave 2; Developer binds **real files** in `integration` after TA Compliance green.
+**Critical**: `assetMapping` paths are **locked after Gate #1**. No agent may unilaterally change paths — this is the Asset Contract: TA fills paths in production Wave 2; Developer binds **real files** in `ui_pass` after TA Compliance green.
 
 **Transparency**: TA auto-derives transparency requirements from `assetMapping` path conventions (`bg/` = opaque, `ui/`/`vfx/`/`txt/` = needs alpha, `tiles/` = needs alpha unless card faces). PM does NOT need to define transparency fields — chroma key selection and background removal are TA's technical domain. See `ta-pipeline-cookbook.md` Step 0e.
 
@@ -163,6 +163,22 @@ Single-element groups stay as single-file paths; do not invent atlases for one t
 
 ---
 
+## Element Type Registry + ASR budget (Gate #1)
+
+After atlas groups, add **§ Element Type Registry** in `layout-spec.md`:
+
+- Group variant elementIds under a shared `typeId` (e.g. `tile` → red/blue/green ids)
+- Count **unique types** — target **≤ 20** for playable ads
+- ASR physical slot budget: ~12 ui + ~12 element states; overflow → second element sheet or mc-crop/ta-extends plan
+- If user request implies >20 types, PM degrades or splits variants to TA-extends in Gate #1 options
+
+Pre-Write checklist addition:
+
+- [ ] Element Type Registry present; unique type count documented
+- [ ] Variant-only ids marked for TA-extends in Designer handoff notes (optional one line in atom-plan.md)
+
+---
+
 ## Step 7: Experience Flow Design
 
 Design each stage with four fields — from "what happens" to "what the player feels" (MDA player perspective):
@@ -244,7 +260,7 @@ playcraft skills link --from-atom-plan --prune
 - `validate-atom-plan`：PM 定稿前手动跑；**PM STOP** 时 hook 再拦一层（invalid skillRef 无法 STOP）。
 - `link`：读取 `atom-plan.json` 中所有非空 `skillRef`。
 
-**PM does not** pre-fill `atom-plan.md` § Impl Skill Context — **Developer** in `integration`.
+**PM does not** pre-fill `atom-plan.md` § Impl Skill Context — **Developer** in `ui_pass` / `gameplay_pass`.
 
 ### 8e. `atom-plan.md`（可选）
 

package/project-template/.claude/agents/refs/reviewer-convergence-eval.md

@@ -21,16 +21,28 @@ Soft checklist only — **do not judge subjective design quality**.
 
 **Fail →** list missing items + `routeTo: pm` (or `designer` if visual doc gap).
 
-### Gate #2b additional checklist
+### Gate #2b additional checklist (structural — hard fail)
+
+Gate #2b **structural** gaps are hard fails (missing files, row count, type representatives). Do not fail for subjective aesthetics.
 
 ```
 [ ] MC five panels complete (concept + 4 storyboard)
-[ ] MC aspect ratio correct — verify with: playcraft image info <mc-path>
-[ ] ASR dual sheets (UI + element) exist under assets/images/reference/
-[ ] ASR covers main assetMapping element ids
+[ ] MC aspect ratio correct — playcraft image info <mc-path> (width/height ≈ 2.81)
+[ ] MC Panel 1 shows every element type from layout-spec § Element Type Registry (or assetMapping)
+[ ] ASR dual sheets exist: ui_state_sheet_[X].png + element_state_sheet_[X].png
+[ ] Optional overflow: element_state_sheet_[X]_2.png when types > 12
+[ ] logs/designer-log.md § Image Production Preflight complete (3 image Skills)
+[ ] ASR Coverage Matrix row count == assetMapping rows + static text ids
+[ ] CoverageLayer column present; each elementType has ≥1 on-asr OR mc-crop row
+[ ] Sheet grid metadata filled (no {{placeholders}})
+[ ] on-asr rows mirrored to atom-plan.json asrSlot where applicable
+[ ] ASR semantic split: UI board has no gameplay tiles; element board has no full HUD screenshot
+[ ] Spot-check: ASR cells look isolated (no white box / scene floor inside cells) — note in report if obvious
 ```
 
-**Pass →** handoff `Run Gate #1` or `Run Gate #2b`. **Fail →** routeTo PM/Designer with specific gaps.
+Optional CLI: `playcraft skills validate-asr-coverage --project-dir .`
+
+**Pass →** handoff `Run Gate #2b`. **Fail →** routeTo Designer (or PM if layout-spec/type budget issue).
 
 ---
 

package/project-template/.claude/agents/refs/ta-pipeline-cookbook.md

@@ -742,21 +742,55 @@ Designer's **ASR sheets** (UI + element state reference) contain **representativ
 
 1. From **ASR** (preferred): `crop` each state slot → `resize` to spec → these become your `--reference-image` for Stage A batch generation
 2. From **Master Composite** (fallback): extract elements not covered in ASR
-3. Check `designer-log.md` **ASR State Inventory** — note which states are covered vs which need expansion
+3. Check `designer-log.md` § **ASR Coverage Matrix** — note which states are covered vs which need expansion; Sheet grid metadata table at the top has `rows × cols + cell W×H + padding` for pixel-coordinate computation
 4. Background: generate clean bg using composite as `--reference-image`
 5. Text assets: → **invoke `playcraft-text-rendering` skill**
 6. Representative quality insufficient → ICP request to Designer for supplementary samples
 
+**若 ASR crop 后不可抠**（白边/色幕残留/元素截断/格内场景底）→ **`routeTo: designer`** 重生成 ASR 对应格；**不要** TA 自行用 AI 重画整张 ASR。
+
 **ASR 提取方法（按优先级）**：
 
 > ⚠️ **严禁对 ASR 网格布局图使用纯 text prompt 的 segment！** 使用 `designer-log` 中的槽位坐标 + `crop`。
 
+**优先路径：直接读 `atom-plan.json` → `atoms[].asrSlot`（最高优先级）**
+
+Designer 在 Phase 1 完成 ASR 后会把每个 VisualAtom 的网格坐标写到 `atom-plan.json` → `atoms[i].asrSlot: { sheet, row, col }`（详见 [`docs/team/atom-plan-format.md` § `asrSlot`](../../../docs/team/atom-plan-format.md#asrslot-字段可选--visualatom-基线绑定)）。TA 直接用这个字段 + `designer-log` § Sheet grid metadata，省去手翻 Coverage Matrix 的步骤：
+
+```bash
+# 1) 从 atom-plan.json 读取所有有 asrSlot 的 VisualAtom
+cat docs/atom-plan.json | jq -r '
+  .atoms[]
+  | select(.asrSlot != null)
+  | "\(.atomId)\t\(.asrSlot.sheet)\t\(.asrSlot.row)\t\(.asrSlot.col)"
+'
+# 输出格式: <atomId>\t<sheet>\t<row>\t<col>
+
+# 2) 从 designer-log.md § ASR Coverage Matrix § Sheet grid metadata 读 cellW / cellH / padding
+#    (单独读一次，缓存到 ta-log 备查)
+
+# 3) 计算像素坐标并 crop（脚本化 — ta-workspace/scripts/asr-extract.mjs）
+#    x = (col - 1) * (cellW + padding) + padding
+#    y = (row - 1) * (cellH + padding) + padding
+#    sheetPath 映射:
+#      ui       → assets/images/reference/ui_state_sheet_<selectedMcOption>.png
+#      element  → assets/images/reference/element_state_sheet_<selectedMcOption>.png
+#      element_2 → assets/images/reference/element_state_sheet_<selectedMcOption>_2.png
+#    contractPath 从 layout-spec assetMapping 中按 atom slot 反查
+#
+#    playcraft image crop --input <sheetPath> --x <x> --y <y> --width <cellW> --height <cellH> --output <contractPath>
+```
+
 ```
-ASR 是已知网格布局？（ui_state_sheet / element_state_sheet，行列分明）
-├─ 是 → 方法 1: crop 直切（最可靠，零歧义）
+ASR 是已知网格布局？（ui_state_sheet / element_state_sheet / element_state_sheet_*_2，行列分明）
+├─ atom-plan.json 有 asrSlot 字段 → 方法 0（推荐）: 上面脚本化批量 crop
+│
+├─ 是但 asrSlot 缺失 → 方法 1: crop 直切（手动查 Coverage Matrix R#C#）
 │        1. playcraft image info --input assets/images/reference/ui_state_sheet_<X>.png  → 获取尺寸
-│        2. 从 designer-log ASR State Inventory 读取行列与 bbox
-│        3. playcraft image crop --input <asr_sheet> --x <x> --y <y> --width <w> --height <h> --output <out>
+│        2. 从 designer-log § ASR Coverage Matrix 读取 Sheet grid 元数据 + 目标行列 (R#C#)
+│           pixel coords:  x = (C-1) × (cellW + padding) + padding
+│                          y = (R-1) × (cellH + padding) + padding
+│        3. playcraft image crop --input <asr_sheet> --x <x> --y <y> --width <cellW> --height <cellH> --output <out>
 │        4. 对有背景底色的元素：crop 后再 remove-background --method floodfill
 │
 ├─ 元素位置不规则但 bbox 已知 → 方法 2: segment --boxes（精确框选）
@@ -765,6 +799,8 @@ ASR 是已知网格布局？（ui_state_sheet / element_state_sheet，行列分
 └─ 仅 MC 有该类型 → 方法 3: decompose-layers 或 segment --text（最后手段，见 playcraft-masking）
 ```
 
+> **若 Designer 没有填 `asrSlot`** — 不需要重新 invoke Designer，TA 可以手动从 `designer-log § ASR Coverage Matrix § Coverage` 反查 R#C# 并继续。在 ICP 中提示 PM/Designer 下次预填可加速。
+
 **常见踩坑**：
 
 - ❌ `segment --text "apple tile icon"` → SAM3 可能只切出苹果图案，丢失 tile 方块底板
@@ -858,7 +894,7 @@ assetMapping 路径所在目录？
 | ----------------------------- | ---------- | ------------- | ------------------------------------- | ------------------------------------------- | -------------------- | -------- |
 | assets/images/bg/bg_main.webp | false      | full-coverage | N/A                                   | N/A                                         | 边缘全覆盖检查       | ❓       |
 | assets/images/ui/btn_cta.webp | true       | greenscreen   | `remove-background --floodfill -t 25` | `segment --boxes` / `remove-bg --method ai` | 深色背景 overlay     | ❓       |
-| assets/images/ui/digits.webp  | true       | bluescreen    | `remove-background --floodfill -t 25` | `segment --boxes` / `remove-bg --method ai` | 深色背景 overlay     | ❓       |
+| assets/images/txt/digits.webp | true       | bluescreen    | `remove-background --floodfill -t 25` | `segment --boxes` / `remove-bg --method ai` | 深色背景 overlay     | ❓       |
 | assets/images/vfx/glow.webp   | true       | bluescreen    | `remove-background --floodfill -t 25` | `segment --boxes`                           | 逐帧深色背景 overlay | ❓       |
 | assets/images/tiles/tile.webp | true       | greenscreen   | `remove-background --floodfill -t 25` | `segment --boxes` / `remove-bg --method ai` | 深色背景 overlay     | ❓       |
 | assets/images/txt/title.webp  | true       | bluescreen    | `remove-background --floodfill -t 25` | `remove-bg --method ai`                     | 深色背景 overlay     | ❓       |

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

@@ -20,6 +20,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` — three modes: `design_check` (Gate #1/#2b pre-check), `ui_diff` (screenshots vs MC), `load_check` (before Gate #3). Increment `uiReworkRound` on `ui_diff` fail (max 5). See [workflow-changelog.md](../../docs/team/workflow-changelog.md).
 
 # Reviewer — Playable Ads Convergence Review Agent
 
@@ -120,8 +122,9 @@ Afterward update handoff per **Runtime**. **Never** write mainline `stage`.
 ## Important Rules
 
 1. **Never modify production files** — only `logs/review-report.md` and `docs/project-state.md` checkpoint.
-2. **`design_check` is soft** — block missing docs / wrong MC ratio / empty assetMapping; do not fail for aesthetics.
-3. **`ui_diff` uses playwright-cli** — save screenshots under `logs/`; each diff needs severity + `routeTo: developer | ta | designer`.
-4. **`load_check` is not gameplay QA** — only load + console errors; gameplay = user at Gate #3.
-5. **`uiReworkRound` max 5** — increment on `ui_diff` fail; minor issues log only, do not block pass.
-6. **Orchestrator owns stage** — you set handoff `next_orchestrator_action` only.
+2. **`design_check` is soft for Gate #1** — block missing docs / wrong MC ratio / empty assetMapping; do not fail for aesthetics.
+3. **`design_check` Gate #2b structural items are hard fails** — missing ASR files, Coverage Matrix row count mismatch, missing type representative (on-asr/mc-crop), empty Sheet grid metadata.
+4. **`ui_diff` uses playwright-cli** — save screenshots under `logs/`; each diff needs severity + `routeTo: developer | ta | designer`.
+5. **`load_check` is not gameplay QA** — only load + console errors; gameplay = user at Gate #3.
+6. **`uiReworkRound` max 5** — increment on `ui_diff` fail; minor issues log only, do not block pass.
+7. **Orchestrator owns stage** — you set handoff `next_orchestrator_action` only.

package/project-template/.claude/agents/technical-artist.md

@@ -23,6 +23,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`. TA runs in `production` Wave 2 (after Designer Ph.2). See [workflow-changelog.md](../../docs/team/workflow-changelog.md).
 
 # Technical Artist — Playable Ads Production Agent