@playcraft/cli 0.0.41 → 0.0.43

package/project-template/docs/team/atom-plan-format.md

@@ -67,8 +67,107 @@ jq -n \
 | 角色                     | 读 JSON                  | 读 MD                    | Skills 路径                                      |
 | ------------------------ | ------------------------ | ------------------------ | ------------------------------------------------ |
 | Orchestrator / Developer | `atoms[]`、`skillsMatch` | `## Impl Skill Context`  | `playcraft.config.json` + `.claude/skills/` 软链 |
-| TA                       | `atoms[]`                | `## TA Skill Context`    | 同上                                             |
-| Designer                 | `atoms[]`                | `## Asset Skill Context` | 同上                                             |
+| TA                       | `atoms[]`、`mediaGroups` | `## TA Skill Context`    | 同上                                             |
+| Designer                 | `atoms[]`、`mediaGroups` | `## Asset Skill Context` | 同上                                             |
 | Reviewer                 | 两者只读                 | 两者只读                 | —                                                |
 
 Developer 软链：`.claude/skills/<skillRef>/`（`playcraft skills link --from-atom-plan`）。断链时用 `playcraft skills read <skillRef>`（自动读 config，勿手抄 node_modules 路径）。
+
+## Status Update Protocol（所有产出 Agent 必须遵守）
+
+**atom-plan.json 是活的追踪系统，不是一次性规划文档。** 每个 Agent 完成 atom 后立即更新：
+
+```json
+{
+  "atomId": "<id>",
+  "status": "done", // or "skipped" with reason in dagRevisions
+  "actualOutput": "<path>" // the actual deliverable path on disk
+}
+```
+
+| Agent     | 何时更新                        | `actualOutput` 格式                                   |
+| --------- | ------------------------------- | ----------------------------------------------------- |
+| Designer  | Phase 2 每完成一个 atom         | `"assets/audio/bgm.mp3"` 或 `"ASR:ui_sheet:region_3"` |
+| TA        | 每完成一个 atlas/asset          | `"assets/images/ui/ui_atlas.webp"`                    |
+| Developer | 每完成一个 gameplay/config atom | `"game/gameplay/reducer.ts"`                          |
+
+**Context 回填同样强制**：对应 agent 的 `atom-plan.md` § Context 区不得为空（`Pending`）。Orchestrator 在阶段转换前验证。
+
+## `asrSlot` 字段（可选 — VisualAtom 基线绑定）
+
+`atoms[].asrSlot` 是 **VisualAtom**（`assignTo: Designer`）专用的可选字段，把"Designer ASR Coverage Matrix 上的网格坐标"机器可读化，TA 据此自动算 crop 像素坐标，省掉人工对照表的步骤。
+
+### Schema
+
+```ts
+type AsrSlot = {
+  sheet: "ui" | "element" | "element_2"; // element_2 = overflow ASR board when types > 12
+  row: number;                    // 1-based 行号 (row-major)
+  col: number;                    // 1-based 列号
+};
+
+// 字段位置
+atoms[i].asrSlot?: AsrSlot | null
+```
+
+### 谁写
+
+| 谁           | 何时                                              | 写什么                                                                                                                     |
+| ------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| **PM**       | Gate #1（可选）                                   | 已知会出现在 ASR 的 VisualAtom 预填一个建议 slot（Designer 可改）；不确定时留空                                            |
+| **Designer** | Phase 1 完成 ASR 后（必填，所有 ASR-覆盖的 atom） | 与 `designer-log.md § ASR Coverage Matrix § Coverage` 一致；同时 `status: done` + `actualOutput: ASR:<sheet>:R{row}C{col}` |
+| **TA**       | 只读                                              | 用 `asrSlot.sheet/row/col` + `designer-log` § Sheet grid metadata → 算 `playcraft image crop` 像素                         |
+
+### TA crop 自动化（参考公式）
+
+`designer-log.md § ASR Coverage Matrix § Sheet grid metadata` 给出每张 sheet 的 `cellW × cellH × padding`。
+
+```
+sheetPath = sheet === "ui"
+  ? "assets/images/reference/ui_state_sheet_<selectedMcOption>.png"
+  : sheet === "element_2"
+    ? "assets/images/reference/element_state_sheet_<selectedMcOption>_2.png"
+    : "assets/images/reference/element_state_sheet_<selectedMcOption>.png"
+
+x = (col - 1) * (cellW + padding) + padding
+y = (row - 1) * (cellH + padding) + padding
+width  = cellW
+height = cellH
+
+playcraft image crop <sheetPath> --x <x> --y <y> --width <width> --height <height> --output <assetMapping_path>
+```
+
+### 与 `actualOutput` 的关系
+
+`asrSlot` 是**绑定信息**（这个 atom 对应 ASR 哪个格子），`actualOutput` 是**完成证明**（已交付到哪里）。
+两者并存而非互斥：
+
+```json
+{
+  "atomId": "vatom_tile_default",
+  "type": "VisualAtom",
+  "assignTo": "Designer",
+  "asrSlot": { "sheet": "element", "row": 1, "col": 2 },
+  "status": "done",
+  "actualOutput": "ASR:element_state_sheet_B:R1C2"
+}
+```
+
+TA 之后用 `asrSlot` 提取出 PNG 到 `assets/images/tiles/tile_default.webp`；这一步发生时 TA atom（不同的 atomId）有自己的 `actualOutput`，**不修改** Designer atom 的 `actualOutput`。
+
+### 禁止
+
+- 跨 ASR-mediaGroups 混用：`asrSlot` 只描述"本项目 Designer 产出的 ASR"，**不**复用 `skillsMatch.mediaGroups`（那是技能库预制资产，不在项目 ASR 上）。
+- ICP 补丁 PNG 的 VisualAtom 不设 `asrSlot`（已脱离 ASR 网格）。`actualOutput` 直接给文件路径。
+- TA atom 不写 `asrSlot`（这是 Designer-owned 字段，TA 通过 `dependsOn` 引用 Designer atom）。
+
+## mediaGroups 使用规则
+
+`skillsMatch.mediaGroups` 包含 `playcraft skills match` 自动发现的可复用预制资产（图片/音频/3D）。
+
+**协议**：
+
+1. **Designer / TA 必须读** `mediaGroups` 并对每个 entry 判断是否匹配当前 atom
+2. **匹配 → 直接 link**：`playcraft skills link --atom <atomId>` → 后处理（resize/convert/mix）→ `status: done`
+3. **不匹配 → 跳过并记录**：在 `dagRevisions` 记录 skip 原因
+4. **禁止**：mediaGroups 中有匹配项却无视、从零生成

package/project-template/docs/team/collaboration.md

@@ -12,13 +12,20 @@ Canonical terms used across `CLAUDE.md`, agent L1 files, and `refs/`. Prefer the
 | **Designer Phase 1 / Phase 2** | —                                          | Ph.1 = MC + ASR + Handoff Pack; Ph.2 = audio + digit + VisualAtom status (v2)                                                                                                      |
 | **ASR Coverage Matrix**        | —                                          | `designer-log` table: every contract id → ASR slot; Gate #2b mandatory                                                                                                             |
 | **Palette Locked**             | —                                          | MC-sampled hex in `designer-log`; delta vs `layout-spec`                                                                                                                           |
-| **production-serial-v1**       | workflow spec version (current)            | See `workflow-changelog.md`; serial production waves + `integration` Developer                                                                                                     |
-| **designer-handoff-v2**        | visual handoff spec                        | MC + ASR + Handoff Pack; bundled in `production-serial-v1` changelog                                                                                                               |
-| **Production Pipeline**        | serial waves in `project-state`            | Wave 1 Designer Ph.2 → Wave 2 TA; Developer only in `integration`                                                                                                                  |
-| **Developer integration**      | —                                          | Single `integration` stage: Skill Preflight + PGS + asset bind + Dev self-check (replaces parallel Ph.1 in `production`)                                                           |
+| **production-serial-v1**       | workflow spec version (superseded)         | See `workflow-changelog.md`; serial production waves within `production` stage                                                                                                     |
+| **convergence-v1**             | workflow spec version (current)            | Three convergence loops: design_check → ui_diff → load_check + Gate #3 user                                                                                                        |
+| **design_check**               | Reviewer mode                              | Soft checklist before Gate #1 / #2b — completeness only, not subjective quality                                                                                                    |
+| **ui_diff**                    | Reviewer mode                              | Browser screenshots vs MC panels; routes ui_rework (max 5 rounds)                                                                                                                  |
+| **load_check**                 | Reviewer mode                              | Page loads + no console errors before Gate #3; no gameplay walkthrough                                                                                                             |
+| **ui_ready**                   | devStatus value                            | UI shell complete; gameplay rules not yet implemented                                                                                                                              |
+| **designer-handoff-v2**        | visual handoff spec                        | MC + ASR + Handoff Pack; bundled in convergence-v1                                                                                                                                 |
+| **Production Pipeline**        | serial waves in `project-state`            | Wave 1 Designer Ph.2 → Wave 2 TA; Developer in `ui_pass`                                                                                                                           |
+| **Developer ui_pass**          | —                                          | UI shell + scene switch + simple states; no core gameplay rules                                                                                                                    |
+| **Developer gameplay_pass**    | —                                          | Core gameplay on verified UI; PGS + first level success                                                                                                                            |
 | **Four-doc discipline**        | 四件套写作纪律                             | PM/Designer: contracts only in four docs; narrative in style-exploration + designer-log; TA/Dev intake: agent-conduct + log templates                                              |
 | **TA Step 0 / 1 / 2**          | (not "Phase")                              | **TA cookbook only**: Step 0 = Skill Discovery; Step 1 = Asset Completion; Step 2 = Technical Pipeline — TA runs all three in one `production` invoke                              |
-| **reworkRound**                | `handoff.rework_round`                     | Counts **review failures** (0 → 1 → 2). At `2`, next fail → forced Gate #3 (3rd failure)                                                                                           |
+| **reworkRound**                | `handoff.rework_round` (legacy)            | Superseded by **`uiReworkRound`** for UI convergence (0–5)                                                                                                                         |
+| **uiReworkRound**              | `handoff.ui_rework_round`                  | Counts **ui_diff failures** (0 → 5 max); at 5 → orchestrator decision                                                                                                              |
 | **ICP**                        | Intent Clarification Protocol              | Async agent Q&A in `docs/intent-clarifications.md`; orchestrator does not interrupt user                                                                                           |
 | **MC**                         | Master Composite                           | Five 9:16 panels in one image: concept panel + Hook / Onboarding / End Card / CTA storyboards                                                                                      |
 | **ASR**                        | Asset State Reference Sheet                | 资产状态参考精灵图板：UI 组件状态板 + 元素状态板；Gate #2a 后产出；供 TA crop 量产（非 runtime atlas）                                                                             |
@@ -37,12 +44,12 @@ When instructions conflict: **Goals § Core responsibilities** wins over workflo
 
 Only the **Orchestrator** (main session) may use `AskUserQuestion` toward the user. Sub-agents prepare materials, update `project-state`, then **STOP**.
 
-| Gate    | Sub-agent deliverable                                            | STOP signal (`project-state`) | Orchestrator action                                                                                        |
-| ------- | ---------------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| **#1**  | PM: four design docs ready for review                            | `gates.#1 = pending`          | `AskUserQuestion` → on pass: `gates.#1 = passed`, `stage: style_exploration`, invoke `@designer`           |
-| **#2a** | Designer: MC options A/B[/C] + partial `style-exploration.md`    | `gates.#2a = pending`         | `AskUserQuestion` pick option → set `selectedMcOption` → resume `@designer`                                |
-| **#2b** | Designer: ASR 双板 + complete `style-exploration` + designer-log | `gates.#2b = pending`         | `AskUserQuestion` confirm MC+ASR → `gates.#2b = passed`, `stage: production`, invoke `@designer` Ph.2 only |
-| **#3**  | Reviewer pass + `devStatus: ready`                               | `gates.#3 = pending`          | Show **devUrl** → user accept → `stage: done`                                                              |
+| Gate    | Sub-agent deliverable                                            | STOP signal (`project-state`) | Orchestrator action                                                                                                                                 |
+| ------- | ---------------------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **#1**  | PM: four design docs ready for review                            | `gates.#1 = pending`          | Invoke `@reviewer design_check` → pass → `AskUserQuestion` → on pass: `gates.#1 = passed`, `stage: style_exploration`, invoke `@designer`           |
+| **#2a** | Designer: MC options A/B[/C] + partial `style-exploration.md`    | `gates.#2a = pending`         | `AskUserQuestion` pick option → set `selectedMcOption` → resume `@designer` (no Reviewer pre-check)                                                 |
+| **#2b** | Designer: ASR 双板 + complete `style-exploration` + designer-log | `gates.#2b = pending`         | Invoke `@reviewer design_check` → pass → `AskUserQuestion` confirm MC+ASR → `gates.#2b = passed`, `stage: production`, invoke `@designer` Ph.2 only |
+| **#3**  | Reviewer `load_check` pass + `devStatus: ready`                  | `gates.#3 = pending`          | Show **devUrl** → user accept → `stage: done` (gameplay judged by user)                                                                             |
 
 Sub-agent pattern: **write artifacts → update `## Agent handoff` + gates → STOP (no user questions).**
 
@@ -50,16 +57,16 @@ Sub-agent pattern: **write artifacts → update `## Agent handoff` + gates → S
 
 Machine-readable runtime block in `docs/project-state.md` (YAML fence under `## Agent handoff`). Sub-agents and orchestrator use it as the **single source** for STOP / resume / next step.
 
-| Field                      | Writer                           | Meaning                                                                                          |
-| -------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `subagent`                 | Sub-agent on STOP                | Role that just finished (`pm`, `designer`, `technical-artist`, `developer`, `reviewer`, `none`)  |
-| `subagent_stop`            | Sub-agent on STOP                | `true` = do not continue work until orchestrator acts                                            |
-| `waiting_for`              | Both                             | `user_gate` = orchestrator must run Gate; `orchestrator` = wait for invoke; `none` = active work |
-| `gate_pending`             | Sub-agent when gate pending      | `"1"` \| `"2a"` \| `"2b"` \| `"3"` \| `null` — sync with Gates table                             |
-| `next_orchestrator_action` | Sub-agent on STOP (**required**) | One sentence: the **only** legal next step for orchestrator                                      |
-| `last_completed_by`        | Sub-agent on STOP                | Same as `subagent` or action label                                                               |
-| `rework_round`             | Reviewer on fail / orchestrator  | Keep in sync with `reworkRound` in Gate resume fields                                            |
-| `block_reason`             | Optional                         | Why pipeline cannot advance                                                                      |
+| Field                      | Writer                                  | Meaning                                                                                          |
+| -------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `subagent`                 | Sub-agent on STOP                       | Role that just finished (`pm`, `designer`, `technical-artist`, `developer`, `reviewer`, `none`)  |
+| `subagent_stop`            | Sub-agent on STOP                       | `true` = do not continue work until orchestrator acts                                            |
+| `waiting_for`              | Both                                    | `user_gate` = orchestrator must run Gate; `orchestrator` = wait for invoke; `none` = active work |
+| `gate_pending`             | Sub-agent when gate pending             | `"1"` \| `"2a"` \| `"2b"` \| `"3"` \| `null` — sync with Gates table                             |
+| `next_orchestrator_action` | Sub-agent on STOP (**required**)        | One sentence: the **only** legal next step for orchestrator                                      |
+| `last_completed_by`        | Sub-agent on STOP                       | Same as `subagent` or action label                                                               |
+| `rework_round`             | Reviewer on ui_diff fail / orchestrator | Keep in sync with `uiReworkRound` in Gate resume fields (legacy alias)                           |
+| `block_reason`             | Optional                                | Why pipeline cannot advance                                                                      |
 
 **Orchestrator loop:** read handoff → if `gate_pending` + `user_gate` → Gate only → else if `subagent_stop` → execute `next_orchestrator_action` → reset handoff before invoke.
 
@@ -73,6 +80,7 @@ On every sub-agent STOP, update **in order** (see [agent-conduct.md § Invoke pr
 2. **`## Agent handoff`** — all fields; `subagent_stop: true`; `next_orchestrator_action` required.
 3. **Progress Checkpoint** — one row (stage, agent, action, outcome).
 4. **Production Pipeline** — when `stage: production`, set this role's wave row to `done` + notes when wave complete.
+5. **Plan convergence (TA / Developer only)** — before STOP, ensure `logs/ta-log.md` § **Production Plan** or `logs/developer-log.md` § **UI Pass Plan** / **Gameplay Pass Plan** is complete (Risk Checklist all `[x]`, no `{{placeholders}}`). Hook `validate-workflow-stop.mjs` enforces on subagent stop.
 
 Example (update only your row when track complete):
 
@@ -85,24 +93,25 @@ Checkpoint is a **human log** for context — **not** the routing source (handof
 
 ## Stage field ownership
 
-| Field / transition                                                                                          | Writer                                                               |
-| ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `gates.#N = pending`                                                                                        | Sub-agent before STOP                                                |
-| `gates.#N = passed`                                                                                         | **Orchestrator** after user confirms Gate                            |
-| Mainline `stage` (`pm` → `style_exploration` → `production` → `integration` → `review` → `rework` → `done`) | **Orchestrator only**                                                |
-| `selectedMcOption`                                                                                          | Orchestrator after Gate #2a                                          |
-| `devStatus`, `devUrl`, `devBlockers`                                                                        | Developer                                                            |
-| `reviewerDevCheck`, `reviewerDevNotes`                                                                      | Reviewer                                                             |
-| `reworkRound`                                                                                               | Reviewer on fail (+1); orchestrator may read for Gate #3 forced path |
+| Field / transition                                                                                                              | Writer                                    |
+| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| `gates.#N = pending`                                                                                                            | Sub-agent before STOP                     |
+| `gates.#N = passed`                                                                                                             | **Orchestrator** after user confirms Gate |
+| Mainline `stage` (`pm` → `style_exploration` → `production` → `ui_pass` → `ui_review` → `ui_rework` → `gameplay_pass` → `done`) | **Orchestrator only**                     |
+| `selectedMcOption`                                                                                                              | Orchestrator after Gate #2a               |
+| `devStatus`, `devUrl`, `devBlockers`                                                                                            | Developer                                 |
+| `uiReviewStatus`, `uiReworkRound`, `loadCheck`                                                                                  | Reviewer                                  |
 
 Sub-agents **MUST NOT** set mainline `stage`. They request orchestrator via `next_orchestrator_action` (e.g. `Invoke @reviewer`).
 
-## Rework sequence (orchestrator-owned)
+## UI rework sequence (orchestrator-owned)
 
-1. **Reviewer** — Dev walkthrough + six dimensions → fail: `review-report.md`, `reworkRound` +1, handoff `next_orchestrator_action: "Set stage=rework, invoke routed agents per review-report"` → STOP (**no** `stage: rework` in reviewer write).
-2. **Orchestrator** — Set `stage: rework`, clear `subagent_stop`, invoke `@developer` / `@technical-artist` / `@designer` per Action Items (parallel when independent).
-3. **Developer** (and others) — Fix scoped items → `devStatus: ready` → handoff `Invoke @reviewer` → STOP.
-4. **Orchestrator** — Invoke `@reviewer` again; on pass → Gate #3.
+1. **Reviewer** (`ui_diff`) — screenshots vs MC panels → fail: UI Diff Report in `review-report.md`, `uiReworkRound` +1, handoff `next_orchestrator_action: "Set stage=ui_rework, invoke routed agents per review-report"` → STOP (**no** `stage: ui_rework` in reviewer write).
+2. **Orchestrator** — Set `stage: ui_rework`, invoke `@developer` / `@technical-artist` / `@designer` per Action Items (`routeTo`).
+3. **Developer** (primary) — Fix UI issues → `devStatus: ui_ready` → handoff `Invoke @reviewer ui_diff` → STOP.
+4. **Orchestrator** — Invoke `@reviewer ui_diff` again; on pass (or `uiReworkRound == 5`) → `stage: gameplay_pass`.
+
+Max **5** UI rework rounds. Gameplay has no AI rework loop — only `load_check` before Gate #3.
 
 ## Master Composite — five panels
 
@@ -116,19 +125,19 @@ Sub-agents **MUST NOT** set mainline `stage`. They request orchestrator via `nex
 | Phase                | User                                                            | Agents                                                                              |
 | -------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
 | **A — Choose**       | **Orchestrator only** — `AskUserQuestion` for Gate #1, #2a, #2b | Sub-agents STOP when gate materials ready; no mass production until Gate #2b passed |
-| **B — Produce**      | Not interrupted for terminal commands                           | Serial: Designer Ph.2 → TA → Developer (`integration`)                              |
-| **C — Dev delivery** | **Gate #3 only**: open **devUrl** from orchestrator             | Developer owns Dev quality → Reviewer Dev walkthrough → user accepts                |
+| **B — Produce**      | Not interrupted for terminal commands                           | Serial: Designer Ph.2 → TA → Developer (`ui_pass` → `gameplay_pass`)                |
+| **C — Dev delivery** | **Gate #3 only**: open **devUrl** from orchestrator             | Developer UI+gameplay → Reviewer `load_check` → user accepts gameplay in browser    |
 
 **User never runs `npm run dev`.** Delivery endpoint = Dev URL acceptance (`done`), not `playcraft build`.
 
 ## Agent responsibility matrix (priority order)
 
-| #        | PM                                                        | Designer                                                          | Technical Artist                                            | Developer                                                        | Reviewer                                         |
-| -------- | --------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------ |
-| **1**    | Define experience + gameplay (`design-brief`, flow)       | Lock visual + narrative — **MC = UI spec for Developer**          | Style-faithful mass production from MC/ASR                  | **Restore UI** (`layout-spec` + MC storyboard)                   | Audit intent vs design docs                      |
-| **2**    | Zero-ambiguity contracts (`layout-spec`, `atom-plan`)     | Handoff Pack: ASR Coverage Matrix, Palette Locked, Motion Notes   | 100% `assetMapping` at spec                                 | **Restore PM gameplay** (PGS, first level success)               | Audit player experience (UI + gameplay fidelity) |
-| **3**    | Gates + ICP; **spec-gap** vs **asset rework** arbitration | Audio + digit strip; **respond to Developer visual/audio rework** | Production-grade assets; **respond to Developer TA rework** | **Dev preview owner** (`npm run dev`, devUrl, upstream blockers) | **Dev walkthrough** UI + gameplay, then verdict  |
-| **Last** | —                                                         | —                                                                 | —                                                           | `playcraft build` = **future**, not `done`                       | —                                                |
+| #        | PM                                                        | Designer                                                          | Technical Artist                                                 | Developer                                                        | Reviewer                                         |
+| -------- | --------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------ |
+| **1**    | Define experience + gameplay (`design-brief`, flow)       | Lock visual + narrative — **MC = UI spec for Developer**          | Style-faithful mass production from MC/ASR                       | **UI shell** (`ui_pass`: layout + scene switch)                  | `design_check` before Gates; `ui_diff` vs MC     |
+| **2**    | Zero-ambiguity contracts (`layout-spec`, `atom-plan`)     | Handoff Pack: ASR Coverage Matrix, Palette Locked, Motion Notes   | 100% `assetMapping` at spec (path check only)                    | **Gameplay** (`gameplay_pass`: PGS, first level success)         | `load_check` before Gate #3                      |
+| **3**    | Gates + ICP; **spec-gap** vs **asset rework** arbitration | Audio + digit strip; **respond to Developer visual/audio rework** | Production-grade assets; **respond on `routeTo: ta` in ui_diff** | **Dev preview owner** (`npm run dev`, devUrl, upstream blockers) | Route UI issues in ui_diff; no gameplay AI audit |
+| **Last** | —                                                         | —                                                                 | —                                                                | `playcraft build` = **future**, not `done`                       | —                                                |
 
 Full detail: `.claude/agents/<role>.md` § Goals.
 
@@ -245,7 +254,7 @@ Full detail: `.claude/agents/<role>.md` § Goals.
 - **Exceptions**: full-screen bg (single webp), digit strip (single webp), MC/ASR reference (non-runtime)
 - **Designer** delivers MP3 audio + digit strip webp at contracted paths
 - **TA** delivers runtime atlases + post-processed MP3 per [ta-atlas-deliverable-standard.md](../../.claude/agents/refs/ta-atlas-deliverable-standard.md)
-- **Developer** (`integration`) binds `loadImage`/atlas+frame at contract paths with **real files** on disk, then integrates in Dev
+- **Developer** (`ui_pass` / `gameplay_pass`) binds `loadImage`/atlas+frame at contract paths with **real files** on disk, then integrates in Dev
 - **Path / frame mismatch = integration failure** — TA Compliance + Reviewer check
 - **No unilateral path changes** — PM + user-approved contract change only
 
@@ -265,10 +274,10 @@ Enforceable rules: [agent-conduct.md](agent-conduct.md) (§ PM / Designer / TA /
 
 Within 30 seconds of each wave start, the active agent validates Layout Spec:
 
-| Checker   | When                                         | Checks                                               | On Gap                                                            |
-| --------- | -------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
-| TA        | Production Pipeline Wave 2 (TA entry)        | Every assetMapping entry has clear size/format specs | Write `spec-gap` to project-state.md, PM supplements within 5 min |
-| Developer | `integration` start (after TA Wave 2 `done`) | Every GameplayAtom reference exists in assetMapping  | Same                                                              |
+| Checker   | When                                                       | Checks                                               | On Gap                                                            |
+| --------- | ---------------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
+| TA        | Production Pipeline Wave 2 (TA entry)                      | Every assetMapping entry has clear size/format specs | Write `spec-gap` to project-state.md, PM supplements within 5 min |
+| Developer | `ui_pass` / `gameplay_pass` start (after TA Wave 2 `done`) | Every GameplayAtom reference exists in assetMapping  | Same                                                              |
 
 ## DAG Modification Protocol
 

package/project-template/docs/team/core-model.md

@@ -24,27 +24,28 @@ ScaffoldAtom (skeleton)
 
 ## Atom Assignment Rules (5 Agents)
 
-| Atom Type                                      | assignTo  | Notes                                                                                                                                    |
-| ---------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `GameplayAtom`                                 | Developer | PGS rules, state machine                                                                                                                 |
-| `ConfigAtom`                                   | Developer | Level config, difficulty curve                                                                                                           |
-| `VisualAtom` (baseline)                        | Designer  | **designer-handoff-v2**: baseline = ASR slots in Phase 1; Phase 2 mark `done` with `actualOutput: ASR:...` or ICP supplementary PNG only |
-| `VisualAtom` (completions: remaining elements) | TA        | Derive full set from samples                                                                                                             |
-| `VisualAtom` (sprite sheets/animation/VFX)     | TA        | Technical pipeline                                                                                                                       |
-| `VisualAtom` (3D models/GLB)                   | TA        | 3D pipeline; needs `referenceSource`                                                                                                     |
-| `AudioAtom` (original generation)              | Designer  | BGM/SFX generation                                                                                                                       |
-| `AudioAtom` (post-processing)                  | TA        | compress/trim/loop                                                                                                                       |
-| `VFXAtom`                                      | TA        | VFX sprite sheets                                                                                                                        |
-| `AnimationAtom`                                | TA        | Animation sprite sheets                                                                                                                  |
+| Atom Type                                      | assignTo  | Notes                                                                                                                                                                                                                                                                                   |
+| ---------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GameplayAtom`                                 | Developer | PGS rules, state machine                                                                                                                                                                                                                                                                |
+| `ConfigAtom`                                   | Developer | Level config, difficulty curve                                                                                                                                                                                                                                                          |
+| `VisualAtom` (baseline)                        | Designer  | **designer-handoff-v2**: baseline = ASR slots in Phase 1; set `atoms[].asrSlot: { sheet, row, col }` (see [atom-plan-format.md § `asrSlot`](atom-plan-format.md#asrslot-字段可选--visualatom-基线绑定)); Phase 2 mark `done` with `actualOutput: ASR:...` or ICP supplementary PNG only |
+| `VisualAtom` (completions: remaining elements) | TA        | Derive full set from samples                                                                                                                                                                                                                                                            |
+| `VisualAtom` (sprite sheets/animation/VFX)     | TA        | Technical pipeline                                                                                                                                                                                                                                                                      |
+| `VisualAtom` (3D models/GLB)                   | TA        | 3D pipeline; needs `referenceSource`                                                                                                                                                                                                                                                    |
+| `AudioAtom` (original generation)              | Designer  | BGM/SFX generation                                                                                                                                                                                                                                                                      |
+| `AudioAtom` (post-processing)                  | TA        | compress/trim/loop                                                                                                                                                                                                                                                                      |
+| `VFXAtom`                                      | TA        | VFX sprite sheets                                                                                                                                                                                                                                                                       |
+| `AnimationAtom`                                | TA        | Animation sprite sheets                                                                                                                                                                                                                                                                 |
 
 **Simple rule** (v2): Designer locks **MC + ASR** direction; TA mass-produces from ASR/MC to contract paths. Designer does not batch-export tile/UI PNGs at `assetMapping` in Phase 2.
 
 ## Scheduling Metadata (PM injects into `docs/atom-plan.json` → `atoms[]`)
 
-| Field                       | Meaning                             | Impact                                                              |
-| --------------------------- | ----------------------------------- | ------------------------------------------------------------------- |
-| `assignTo`                  | Which agent executes                | Required for all atoms                                              |
-| `referenceSource`           | Reference image source for 3D atoms | `"designer-sample"` → starts immediately; `"ta-completion"` → waits |
-| `dependsOn: [atomId]`       | Explicit prerequisites              | Determines execution order                                          |
-| `priority: high/normal/low` | Priority level                      | Affects TA scheduling                                               |
-| `parallelGroup`             | Parallel execution group            | Same-group atoms start simultaneously                               |
+| Field                          | Meaning                                        | Impact                                                                                           |
+| ------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `assignTo`                     | Which agent executes                           | Required for all atoms                                                                           |
+| `referenceSource`              | Reference image source for 3D atoms            | `"designer-sample"` → starts immediately; `"ta-completion"` → waits                              |
+| `dependsOn: [atomId]`          | Explicit prerequisites                         | Determines execution order                                                                       |
+| `priority: high/normal/low`    | Priority level                                 | Affects TA scheduling                                                                            |
+| `parallelGroup`                | Parallel execution group                       | Same-group atoms start simultaneously                                                            |
+| `asrSlot: { sheet, row, col }` | VisualAtom baseline → ASR grid cell (optional) | TA auto-derives crop pixels from `designer-log § Sheet grid metadata` — eliminates manual lookup |

package/project-template/docs/team/workflow-changelog.md

@@ -2,32 +2,46 @@
 
 Template workflow spec versions for `packages/cli/project-template`. New projects from `playcraft create` copy the current template; record the version in each project's `docs/project-state.md` § Workflow spec.
 
-## production-serial-v1 (current)
+## convergence-v1 (current)
 
 **Effective**: project-template default for new playable-ad projects.
 
 ### Summary
 
-- **Production orchestration**: after Gate #2b, **strict serial** — Designer Ph.2 → TA → Developer (`integration`). No parallel spawn of `@developer` during `production`.
-- **Production Pipeline** replaces Parallel Tracking: Wave 1 Designer, Wave 2 TA; Developer runs only in `integration` with real assets on disk.
-- **Developer**: single `integration` invoke — Spec Quick-Check, Skill Preflight, PGS/scenes, asset bind, `npm run dev` → `devStatus: ready`.
+- **Three convergence loops**: (1) Reviewer `design_check` before Gate #1 / #2b; (2) `ui_pass` → `ui_review` ⇄ `ui_rework` (max 5 rounds) with `ui_diff` (browser screenshots vs MC); (3) `gameplay_pass` → Reviewer `load_check` → Gate #3 user gameplay acceptance.
+- **Developer split**: `ui_pass` (UI shell + light logic, `devStatus: ui_ready`) then `gameplay_pass` (core gameplay, `devStatus: ready`).
+- **Removed**: `integration`, `review`, `rework`, six-dimension final review, AI gameplay walkthrough.
+- **Production orchestration** unchanged: after Gate #2b, **strict serial** — Designer Ph.2 → TA → Developer (`ui_pass`).
 - Visual delivery unchanged from **designer-handoff-v2** (MC + ASR, Handoff Pack, Phase 2 audio/digit only).
-- **atom-plan Gate #1**: PM writes `docs/atom-plan.json` (`skillsMatch` + `atoms[]`); `skillRef` only from `skillsMatch.items`; `playcraft skills validate-atom-plan` + PM STOP hook; `atom-plan.md` for Context 富集 only.
+- **Reviewer tooling**: `playwright-cli` skill for browser automation (screenshot, console, resize).
+
+### Stage chain
+
+```
+pm → style_exploration → production → ui_pass → ui_review ⇄ ui_rework → gameplay_pass → done
+```
 
 ### Production waves (serial)
 
-| Wave | Agent            | Stage         | Orchestrator invoke                                 |
-| ---- | ---------------- | ------------- | --------------------------------------------------- |
-| 1    | Designer         | `production`  | `@designer` Ph.2 only after Gate #2b                |
-| 2    | Technical Artist | `production`  | `@technical-artist` after Wave 1 `done`             |
-| 3    | Developer        | `integration` | `@developer` after Wave 2 `done` + Compliance green |
+| Wave | Agent            | Stage        | Orchestrator invoke                                 |
+| ---- | ---------------- | ------------ | --------------------------------------------------- |
+| 1    | Designer         | `production` | `@designer` Ph.2 only after Gate #2b                |
+| 2    | Technical Artist | `production` | `@technical-artist` after Wave 1 `done`             |
+| 3    | Developer        | `ui_pass`    | `@developer` after Wave 2 `done` + Compliance green |
 
 ### Trade-offs
 
-| Benefit                                                                  | Cost                                                               |
-| ------------------------------------------------------------------------ | ------------------------------------------------------------------ |
-| Developer codes against real TA output; fewer integration visual reworks | Longer wall-clock before `integration` (no TA ∥ Developer overlap) |
-| TA Compliance before gameplay code                                       | Spec-gap blocks the whole chain until PM supplements               |
+| Benefit                                                      | Cost                                              |
+| ------------------------------------------------------------ | ------------------------------------------------- |
+| UI convergence independently verifiable before gameplay      | Extra Reviewer round + up to 5 UI rework cycles   |
+| Design defects caught before user Gates                      | Gate #1/#2b require extra Reviewer invoke         |
+| Gameplay quality left to human (Canvas opaque to automation) | No AI gameplay audit — user must judge at Gate #3 |
+
+---
+
+## production-serial-v1
+
+**Superseded by** `convergence-v1` for orchestration; serial production waves below still apply within `production` stage.
 
 ---
 

package/project-template/docs/team/workflow-consistency-checklist.md

@@ -121,6 +121,70 @@ Maintenance checklist after editing `packages/cli/project-template`. Run before
 - [x] `CLAUDE.md` + `playcraft-orchestrator.mdc` + `collaboration.md` + `agent-conduct.md` + `agent-runtime-matrix.md` aligned
 - [x] Vitest `production-serial-v1` cases pass
 
+## Phase K — Plan convergence (TA + Developer)
+
+- [x] `templates/ta-log.template.md`: § Production Plan (Coverage / Atlas / Pipeline Order / Risk)
+- [x] `templates/developer-log.template.md`: § Implementation Plan (Architecture / Scene-Asset / PGS / Risk)
+- [x] `validate-workflow-stop.mjs`: validates Plan section + Risk Checklist + no placeholders
+- [x] `.claude/hooks/README.md`: documents Plan validation on STOP
+- [x] `technical-artist.md` + `developer.md`: Runtime + Track done + Important Rules reference Plan
+- [x] `ta-pipeline-cookbook.md` Step 0d + `developer-phase1-flow.md` Step 3b
+- [x] `agent-conduct.md`: TA/Developer MUST/MUST NOT for Plan before production/code
+- [x] `collaboration.md` § STOP sync checklist step 5 (Plan convergence)
+- [x] Vitest `validate-workflow-stop.test.ts` covers `validatePlan`
+
+## Phase L — convergence-v1 doc alignment audit (2026-05)
+
+Documents missed during the `production-serial-v1` → `convergence-v1` upgrade (commit `9fdc39a06`). Each item below has a [W#] tag indicating which audit wave applied the fix.
+
+> **⚠️ Critical finding** — commit `9fdc39a06` introduced `convergence-v1` but did **not modify any vitest test files**. Result: 23 tests under `packages/cli/test/project-template-workflow.test.ts` + `validate-workflow-stop.test.ts` are pre-existing failures against the new spec. Audit Wave W4 includes the full test suite re-alignment.
+
+### W1 — Doc alignment
+
+- [x] `agent-runtime-matrix.md`: rewritten — replaced `integration` / `review` / `rework` with `ui_pass` / `ui_review` / `ui_rework` / `gameplay_pass`; `reworkRound` → `uiReworkRound`; added `devStatus` / `loadCheck` columns; added Post-STOP verification table
+- [x] All five agent L1 files (`pm.md`, `designer.md`, `technical-artist.md`, `developer.md`, `reviewer.md`): added `> **Workflow spec**: convergence-v1` declaration line at top
+- [x] `pm-workflow-detail.md`: `integration` → `ui_pass` (lines 144, 247)
+- [x] `developer-dev-handoff.md`: `stage → review` → `devStatus: ui_ready` / `ready` + handoff `Invoke @reviewer ui_diff/load_check` (line 99)
+
+### W2 — Term alignment (ASR)
+
+- [ ] `playcraft-asset-state-sheet` Skill: "ASR State Inventory" → "ASR Coverage Matrix" (designer-log only has Coverage Matrix)
+- [ ] `designer-log.template.md` § ASR Coverage Matrix: add "Sheet grid" metadata (rows × cols + cell width × height + cell padding)
+- [ ] `ta-pipeline-cookbook.md` Step 0a + ASR extraction: aligned references
+
+### W3 — Machine-readable ASR binding
+
+- [x] `atom-plan.template.json`: add `atoms[].asrSlot?: { sheet, row, col }` optional field (example VisualAtom row included)
+- [x] `atom-plan-format.md`: document `asrSlot` field semantics + crop formula + ownership table
+- [x] `core-model.md`: VisualAtom baseline → `asrSlot` linkage (assignment rule + scheduling metadata table)
+- [x] `ta-pipeline-cookbook.md` § ASR 提取方法: prepend "优先路径" reading `atom-plan.json` → `atoms[].asrSlot` for batch crop
+- [x] `designer-log.template.md` § Coverage: instruct Designer to mirror Coverage rows into `atom-plan.json asrSlot`
+
+### W4 — Hook hardening + test suite re-alignment
+
+- [ ] `validate-workflow-stop.mjs`: add `designer` branch validating `designer-log.md § Skill Preflight`
+- [ ] `validate-workflow-stop.mjs`: `readStage()` regex accepts `stage: ui_pass` (YAML, no backticks)
+- [ ] `packages/cli/test/validate-workflow-stop.test.ts`: add designer + YAML stage test cases; rewrite `Developer Implementation Plan sample` → use `UI Pass Plan` / `Gameplay Pass Plan`
+- [ ] `packages/cli/test/project-template-workflow.test.ts`: rewrite stale describes (originally pre-existing failures from commit `9fdc39a06`):
+  - `workflow-docs` (9 tests): replace six-dimension scoring / `rework_round` / `stage: review` assertions with `convergence-v1` equivalents (`uiReworkRound`, `ui_diff`, `load_check`)
+  - `production-serial-v1` (6 tests): delete or migrate to `convergence-v1` describe
+  - `upstream-intake-four-doc-discipline` (1 test): align with current `developer-phase1-flow.md`
+  - `plan-convergence-ta-developer` (6 tests): "Implementation Plan" → "UI Pass Plan" / "Gameplay Pass Plan"
+  - hooks README test: same alignment
+
+### W5 — TA Compliance Gate coverage
+
+- [x] `ta-log.template.md` § Compliance Gate: add `Text dimensions` row (for `images/txt/*`)
+- [x] `ta-log.template.md` § Compliance Gate: add `Digit Strip dimensions` row (separate from UI)
+- [x] `layout-spec.template.md` Digit Sprite Strip section: recommend `images/txt/digits.webp` path
+- [x] `ta-pipeline-cookbook.md` § Transparency Classification example table: align digit path with `images/txt/` recommendation
+
+### W6 — Interface polish
+
+- [x] `designer-deliverable-spec.md` § Phase 2: clarify ICP supplementary PNG trigger condition (only when TA Step 0c confidence=low **and** crop/segment failed)
+- [x] `ta-log.template.md` Style Interpretation: change "Do NOT proceed with any asset type where confidence = low" → atom-granularity ("hold that asset type; other types continue")
+- [x] `designer-log.template.md` + `ta-log.template.md` § mediaGroups Reuse: add `extension` column + filter note (Designer: `.aiaudio` only; TA: `.aiimage` + `.aisprite`)
+
 ## Automated
 
 ```bash

package/project-template/templates/atom-plan.template.json

@@ -20,6 +20,24 @@
       "referenceSource": null,
       "status": "pending",
       "actualOutput": null
+    },
+    {
+      "atomId": "{{visual_atom_id}}",
+      "slot": "{{element_id_from_assetMapping}}",
+      "type": "VisualAtom",
+      "assignTo": "Designer",
+      "dependsOn": [],
+      "skillRef": null,
+      "priority": "normal",
+      "parallelGroup": null,
+      "referenceSource": null,
+      "asrSlot": {
+        "sheet": "element",
+        "row": 1,
+        "col": 1
+      },
+      "status": "pending",
+      "actualOutput": null
     }
   ],
   "dagRevisions": []

package/project-template/templates/atom-plan.template.md

@@ -11,6 +11,8 @@
 
 > **Living Document**: Designer / TA / Developer enrich **their** sections below without overwriting PM's JSON.
 
+> **⚠️ Status Contract**: Every agent MUST update `atom-plan.json` → `atoms[].status` + `atoms[].actualOutput` upon completing each assigned atom. Atoms left at `pending` with `actualOutput: null` after delivery = workflow violation.
+
 ## JSON 主文件（PM Gate #1）
 
 ```bash
@@ -21,6 +23,16 @@ playcraft skills link --from-atom-plan --prune
 
 - **Never** use `playcraft-*` in `skillRef`; values must come from `skillsMatch.items[].atomId` (or `null` + `dagRevisions` gap)
 
+## mediaGroups — Pre-Matched Reusable Assets
+
+> **`skillsMatch.mediaGroups`** lists assets from the skills library that match this project's needs. Downstream agents (Designer for audio, TA for images) **MUST check mediaGroups before generating from scratch**.
+
+**Usage protocol:**
+
+1. **Designer (audio)**: Read `mediaGroups` → any `.aiaudio` match? → `playcraft skills link --atom <atomId>` → post-process → mark `status: done`
+2. **TA (visual)**: Read `mediaGroups` → any `.aiimage` / `.aisprite` match? → `playcraft skills link --atom <atomId>` → post-process (resize/convert/transparency) → mark `status: done`
+3. **Skip only when**: quality/style/mood mismatch — document reason in `## DAG Revisions`
+
 ---
 
 ## Acceptance Criteria
@@ -40,7 +52,13 @@ Gate #1 — one line per atom in atoms[]; point elsewhere for details:
 
 ## Asset Skill Context
 
-> **Designer fills** after Phase 1 Skill Discovery.
+> **Designer fills** after Phase 1 Skill Discovery. **MUST NOT** leave empty after Phase 2 delivery.
+
+<!-- Designer: for each assigned atom, record:
+  - Which Skills you read and applied (playcraft-audio-generation, playcraft-text-rendering, etc.)
+  - Whether a mediaGroup match was used or skipped (with reason)
+  - Key generation parameters (model, prompt strategy, reference images)
+-->
 
 (Pending Designer Phase 1)
 
@@ -48,7 +66,14 @@ Gate #1 — one line per atom in atoms[]; point elsewhere for details:
 
 ## TA Skill Context
 
-> **Technical Artist fills** during production Wave 2.
+> **Technical Artist fills** during production Wave 2. **MUST NOT** leave empty after delivery.
+
+<!-- TA: for each assigned atom, record:
+  - Production approach (linked from mediaGroups / generated from scratch)
+  - Atom Skill recipe (if skillRef present): base prompt, model, variants
+  - Matched pipeline Skills: which playcraft-* skills were applied
+  - Pipeline decision: key choices made during production
+-->
 
 (Pending Technical Artist Phase 1)
 
@@ -56,7 +81,14 @@ Gate #1 — one line per atom in atoms[]; point elsewhere for details:
 
 ## Impl Skill Context
 
-> **Developer fills** during integration Skill Preflight.
+> **Developer fills** during integration Skill Preflight. **MUST NOT** leave empty after implementation.
+
+<!-- Developer: for each assigned atom, record:
+  - Implementation approach (based on SKILL.md Recipe)
+  - Matched Skills: which .aigameplay / .aiconfig skills were scaffolded
+  - ref files used: PGS schemas, reducer templates, etc.
+  - Implementation decisions: deviations from Skill template + reason
+-->
 
 (Pending Developer Phase 1)