@playcraft/cli 0.0.43 → 0.0.46

package/project-templates/phaser/.claude/agents/refs/implementation-plan-guide.md

@@ -0,0 +1,309 @@
+# Implementation Plan Guide — 开发执行计划
+
+> **用途**：Orchestrator 在 `planning` 阶段 spawn plan-writer subagent 时注入的执行指南。
+> Subagent 基于设计文档、layout contract、atom-tree 和 storyboard 参考，输出 **Developer 可直接执行的实践计划**：`docs/implementation-plan.md`。
+>
+> **Stage**: This subagent runs during the `planning` stage (after atom-tree is ready), not at the start of `development`. Developer enters `development` with a ready execution blueprint.
+>
+> **不是做什么**：
+>
+> - 不是完整工程设计文档
+> - 不是代码草图文档
+> - 不是 file tree / interface / pseudo-code 说明书
+>
+> **产出终点**：`docs/implementation-plan.md` 写入完成，并可被 Developer 直接按顺序执行。
+
+## 输入（subagent 自行读取）
+
+| 文件                        | 关注内容                                                                                                                      |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `docs/design-brief.md`      | 核心玩法循环、规则、胜负条件、Experience Flow、首关保证意图                                                                   |
+| `docs/DESIGN.md`            | 玩家体验契约、反馈重点、阶段节奏、可读性要求                                                                                  |
+| `docs/layout-spec.md`       | zone 布局、assetMapping、atlasPath/frameId、契约路径                                                                          |
+| `docs/atom-tree.json`       | `meta.selectedAtoms`（selected skill refs）、`skillsMatch.matches`、`skillsMatch.mediaGroups`                                 |
+| `docs/atom-tree.md`         | `Acceptance Criteria`、`Selected Gameplay Trunk`、`Gameplay Assembly Link`、`Selected Skill Notes`、`Role Resolution`、`Gaps` |
+| `docs/style-exploration.md` | MC 面板与 UI 目标参考                                                                                                         |
+
+**优先级**：`design-brief` 核心玩法 > `DESIGN` 体验约束 > `layout-spec` 契约路径 > `atom-tree` 借鉴与覆盖提示 > MC 视觉参考
+
+**重要边界**：
+
+- `atom-tree` 是 **借鉴/引用输入**，不是后续制作流程的主轴
+- 可以引用 selected atom / skillRef / mediaGroups 帮助规划，但不要把整个计划写成 atom 镜像
+- 计划的主轴必须是 **面向玩家结果和验收的 Feature**；实践分层只用于思考覆盖面与实现边界，不作为输出章节或拆分主轴
+- 输出优先遵循本 guide 定义的章节和字段；template 是初始化骨架，不是更高优先级规范
+- 允许在不破坏主结构的前提下补充少量高价值说明，但不要新增压过主结构的大章节
+
+---
+
+## Step 1 — 提炼 Feature 主线
+
+先把计划的主线从“玩法承诺”收敛成“少量可执行的 Feature”。
+
+每个一级 Feature 应同时满足：
+
+- 玩家可感知
+- 可以独立验收
+- 依赖关系清晰
+- 可以作为一次实现 / 集成单位
+
+### 可用思考维度（仅供收敛，不单独输出为章节）
+
+| 维度               | 用途                     | 典型内容                                         |
+| ------------------ | ------------------------ | ------------------------------------------------ |
+| `Data`             | 静态配置与棋盘/关卡/常量 | board preset, tile catalog, level config         |
+| `Runtime Data`     | 运行时状态与状态机       | scene state, selected item, timers, result state |
+| `Gameplay Feature` | 核心玩法闭环             | 规则判定、操作响应、胜负推进                     |
+| `Panel`            | 面板/场景/阶段容器       | Hook, Tutorial, Gameplay, EndCard, CTA           |
+| `Visual Feature`   | 玩家能感知到的反馈与表现 | hint、glow、VFX、audio trigger、readability cues |
+
+这些维度用于帮助判断：
+
+- 某个 Feature 覆盖了哪些实现面
+- 是否遗漏了关键边界
+- 哪些 Feature 会共享 runtime boundary
+- 哪些地方会直接影响“首关必胜”
+
+**不要**把这些维度直接抄成 plan 的一级章节，也不要因为某个维度或 skill hit 很多就继续拆更多 feature。
+
+输出时必须让 Developer 一眼看到：
+
+- 先实现哪几个 Feature
+- 哪些 Feature 依赖哪些基础
+- 哪些可以并行
+- 哪些直接影响“首关必胜”
+
+---
+
+## Step 2 — 提炼复用输入，但不要被其绑架
+
+### 2.1 读取可借鉴输入
+
+从 `atom-tree.json` / `atom-tree.md` 里提炼：
+
+- 哪些 selected `skillRef` 明显能借鉴
+- 哪些 `mediaGroups` 可以直接 link
+- 哪些 `Acceptance Criteria` 必须在计划里兑现
+- `Gameplay Assembly Link` 暗示了哪些 trunk-adjacent references 值得先读
+
+### 2.2 复用覆盖度表
+
+计划中保留一张轻量覆盖总览即可（让 Developer 一眼看到哪些 Feature 有参考、哪些从零）：
+
+| Feature                     | Skill Support       | Level | 备注     |
+| --------------------------- | ------------------- | ----- | -------- |
+| {例如：Board + Entry Anim}  | layered-stack-board | L4    | {一句话} |
+| {例如：Match State Machine} | —                   | L0    | 自定义   |
+
+规则：
+
+- 不要求每个 Feature 都硬绑 atom
+- 但如果某个 selected `skillRef` / `mediaGroup` 明显相关，必须在计划中承认它
+- L0 项应简述为什么现有输入不够
+- **覆盖表是总览；Feature 级别的 `Skill Support` 才是执行入口** — Developer 按 Feature 顺序工作时看到 Support 就知道该先读什么
+
+### 2.3 风险项
+
+**风险项的定义边界**：只收"当前无法确定答案"的开放问题，不收"已有方案但要提醒一下"的实现细节。
+
+判断标准：如果你已经知道怎么做了，就不是风险，放到对应 Feature 的 `Acceptance` 或 `Implementation Locus` 里。
+
+典型的真正风险：
+
+- 算法正确性无法在 Phase 1 验证（需要真实数据才能确认）
+- 首关必胜的容错边界不确定（依赖 playtesting 才能定）
+- 某个交互效果需要 TA / Artist 配合才能判断可行性
+
+**不是风险的内容（不要放进风险表）**：
+
+- 资产占位处理方式（这是已知流程，见下方说明）
+- 音频实现方式（Phase 1 只挂事件钩子，已有规范）
+- 任何"已经想好怎么做了"的实现细节
+
+### 2.4 资产占位策略（plan-writer 必读）
+
+build 环原则：**能用占位图就用占位图；不能用占位图的才代码绘制。不考虑视觉表现力，只保证玩法可玩、程序正常执行。**
+
+| 情况                                       | build 环处理方式                                                                |
+| ------------------------------------------ | ------------------------------------------------------------------------------- |
+| ref-flow 已 link（mediaGroups 有匹配）     | Tier 1：直接绑定合约路径                                                        |
+| 无匹配，且 `assetMapping` 期望静态图片文件 | Tier 2：`npm run placeholder:gen` 生成到合约路径                                |
+| Preloader 已 load 的 MP3 缺失              | Tier 2：`npm run placeholder:gen-audio`（先读 `playable-placeholder` skill）    |
+| 动态数字 / 计时文本 / 无图片合约路径       | Tier 3：最小化代码绘制（`fillText` / DOM / `Graphics`），developer-log 记录原因 |
+| 音频                                       | Tier 3：只在正确时机 `emit` 命名事件，不实现播放                                |
+
+**禁止写法**：
+
+- 用 Phaser `Graphics` / canvas 色块**代替**本该生成的占位图文件（有 `assetMapping` 路径时必须先 Tier 2）
+- AI 生成图片、手绘占位图、build 环视觉打磨
+- Web Audio 合成占位音
+
+ring 4（TA 交付后）：TA 把真实文件放到合约路径，代码零改动。
+
+---
+
+## Step 3 — 组织 Feature，不要写成架构白皮书
+
+### Feature 组织原则
+
+- 按 **用户可感知能力** 组织
+- 不按“先写什么文件”组织
+- 不按纯技术 Phase 编号组织
+- 不按 layer 或 skill 命中数扩增一级 feature
+- 不写完整接口 / file tree / pseudo-code
+
+### 推荐 Feature 形态
+
+```text
+Board / Foundation Setup
+Core Interaction Loop
+Tutorial + First-level Success Control
+Feedback + Readability
+End Flow + CTA
+```
+
+如果某个游戏确实需要不同命名，也要保持同样的原则：**面向玩家结果、可独立验收、依赖清楚**。
+
+### Feature 依赖图
+
+输出 ASCII 图，表达：
+
+- 哪些 shared foundation 先行
+- 哪些 Feature 依赖 Runtime Data / scene flow
+- 哪些反馈表现挂在已有 gameplay 事件上
+- 哪些直接影响首关必胜
+
+---
+
+## Step 4 — 写入 `docs/implementation-plan.md`
+
+初始化时直接参考 [templates/plan.template.md](../../../templates/plan.template.md)。
+
+### 强制结构
+
+1. 核心玩法概述
+2. 复用/借鉴覆盖度
+3. Feature 依赖图
+4. Feature 详细清单
+5. 首关保证策略
+6. 风险与开放问题
+
+### 默认写法
+
+- 以 6 个主章节为正文骨架
+- **Feature 详细清单** 应该是全文主体，信息密度最高
+- 允许在章节内部补少量辅助说明，但不要再扩成新的主线章节
+- 除非任务显式要求，否则不要额外加入 `Architecture`、`Implementation Order`、`Asset Pipeline`、`Scene Flow`、`File/Module Structure` 这类大章节
+- 如果确实需要补充实现顺序，请压缩到依赖图说明或 Feature 条目里，不要覆盖主结构
+
+### 每个 Feature 必须包含的字段
+
+```markdown
+### Feature: {名称}
+
+- **Goal**: {这一项解决什么玩家可感知问题}
+- **Player-visible Outcome**: {玩家实际会看到/感受到什么变化}
+- **Depends On**: {无 / Feature X / Feature Y}
+- **Layers Touched**: {Data / Runtime Data / Gameplay Feature / Panel / Visual Feature}
+- **Skill Support**: {skillRef} L{0-4} — {一句话说明在本 Feature 的实际参考价值}
+- **Implementation Locus**: {实现落点，语义级即可，如 GameScene state / board preset / tutorial panel}
+- **Acceptance**: {怎么算完成}
+- **First-Level Success Impact**: {对首关必胜的影响，没有就写 none}
+```
+
+### Skill Support 怎么写
+
+**目的**：让 Developer 在执行到这个 Feature 时，知道"有现成代码值得先看一眼"，而不是从零开始自己想。这不是强制要求，是引导——告诉 Developer 读了能省多少事、参考什么。
+
+**格式**：`{skillRef} L{0-4} — {一句话说明在本 Feature 的实际参考价值}`
+
+**级别含义**（对应 `skill-value-layers.md` 复用级别）：
+
+| 级别 | 含义                    | Developer 期望行为                       |
+| ---- | ----------------------- | ---------------------------------------- |
+| L4   | 有完整可用实现          | 先读 SKILL.md Code 段，理解后适配参数    |
+| L3   | 核心算法/架构可复用     | 读 SKILL.md 提取核心逻辑，在此基础上改写 |
+| L2   | 设计模式/思路有参考价值 | 扫一眼借鉴思路，自己实现                 |
+| L1   | 仅配置/参数有参考       | 快速看下默认值和边界条件                 |
+| L0   | 无参考 / From-scratch   | 不需要读 Skill                           |
+
+**示例**：
+
+```markdown
+- **Skill Support**: `layered-stack-board-phaser` L4 — 入场动画算法 + AABB 遮挡检测完整实现可直接适配
+- **Skill Support**: `brain-age-ui-phaser` L3 — 数值+危险闪烁核心逻辑可用，需自己加 progress bar
+- **Skill Support**: `match-pop.aicomponent` L2 — 粒子爆发效果思路可参考，但需改为双牌同时消除
+- **Skill Support**: none (L0) — 自定义状态机，无现有 Skill 覆盖
+```
+
+**约束**：
+
+- 一个 Feature 最多标注 1-2 个最相关的 Skill Support（不要罗列所有相关 Skill）
+- Skill Support 必须说"在本 Feature 能帮什么"而非泛泛的"这个 Skill 存在"
+- L0 的 Feature 可以省略 Skill Support 行或写 `none`
+
+**禁止**：
+
+- TypeScript `interface`
+- 伪代码算法
+- 完整 scene/file 树
+- `src/...` 级别的 file allocation 清单
+- “Feature 1/2/3 = 技术施工阶段”式线性工程流水账
+
+### Implementation Locus 怎么写
+
+允许：
+
+- `board preset data`
+- `gameplay runtime state`
+- `tutorial overlay panel`
+- `result transition flow`
+- `selection feedback pipeline`
+
+不允许：
+
+- `src/game/board/FreeTileDetector.ts`
+- `interface Tile`
+- `function isTileFree(tile, board)`
+
+---
+
+## Step 5 — 写入 Delivery Checklist
+
+在 `docs/implementation-plan.md` 的 `## 8. Delivery Checklist` 节，从 `DESIGN.md` 和 `layout-spec.md` 提取**可在代码/运行时验证的具体约束**，每项一行。
+
+**格式**：`- [ ] {具体约束} — source: {来源文件}`
+
+**提取原则**：
+
+- 只提取"做错了玩家会直接感知到"的约束，不是所有设计细节
+- 每项必须是可验证的（能在浏览器/代码里确认 pass/fail），不是"做好 UI"这类模糊描述
+- 典型来源：layout zone 边界、UI 可见性时机、交互可达性、关键资产接入要求
+- 数量控制在 5-10 项，覆盖最高风险点即可
+
+**重要**：这个节不是给 Developer 开发时看的，是给 `validate-workflow-stop` hook 在 Developer 自报完成时做验证用的。plan-writer 必须写，Developer 不需要主动查阅。
+
+---
+
+## 完成条件
+
+| #   | 检查项                 | 标准                                                  |
+| --- | ---------------------- | ----------------------------------------------------- |
+| 1   | 计划定位正确           | 是执行计划，不是工程设计白皮书                        |
+| 2   | 主轴正确               | 以 Feature 执行为主，不按 layer / skill 命中数拆分    |
+| 3   | Skill Support 覆盖充分 | 有 skillRef 的 Feature 都标注了 Skill Support + level |
+| 4   | From-scratch 可解释    | L0 Feature 没有现有 Skill 覆盖时有理由                |
+| 5   | Feature 可执行         | 每个 Feature 都有 Goal / Depends / Acceptance         |
+| 6   | 首关必胜闭环           | 有专门策略，并映射到相关 Feature                      |
+| 7   | 无代码污染             | 无接口、伪代码、file tree、源码路径清单               |
+| 8   | Developer 可直接执行   | Developer 无需再次推导计划结构                        |
+
+---
+
+## 注意事项
+
+- **计划服务开发执行，不服务炫技说明**
+- **玩法完整性优先于架构漂亮**
+- **复用输入要承认，但不要被 atom-tree 绑成后续制作流程**
+- **允许写 Implementation Locus，不允许写代码结构**
+- **允许写执行顺序，但应从属于主结构，不要写成新的大章节**

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

@@ -0,0 +1,350 @@
+# Reviewer: Convergence Evaluation (design_check / gameplay_conformance / ui_diff / load_check / playable_validate)
+
+> **Read before executing any Reviewer mode.** Growth-rings verify modes for `growth-rings-v1`.
+> Invoked from `agents/reviewer.md` — orchestrator specifies mode per invoke.
+
+---
+
+## Mode: design_check
+
+Soft checklist only — **do not judge subjective design quality**.
+
+### Ring 1 clarify checklist (minimal package)
+
+```
+[ ] design-brief exists; uses living-brief structure (context / core gameplay / core fun / flow / level intent / confirmed decisions / assumptions / derived constraints)
+[ ] design-brief includes source tags on important claims: [USER] / [WEB] / [SKILL] / [AGENT] / [ASSUMPTION]
+[ ] design-brief records confirmed gameplay-direction decisions from brainstorm, not only retrospective summary prose
+[ ] design-brief does not contain workflow-state claims like gate confirmation / handoff status
+[ ] Style Direction has Dimension / Modality / Arc
+[ ] layout-spec exists; assetMapping non-empty
+[ ] atom-tree.json exists; skillsMatch non-empty
+[ ] atom-tree.json `meta.selectedAtoms` is a compact selected-skill list (not a task / dependency graph)
+[ ] atom-tree.md includes Selected Gameplay Trunk + Gameplay Assembly Link + Role Resolution + Gaps
+[ ] no obvious cross-doc contradictions (assetMapping paths align with atom-tree reading guidance)
+```
+
+**Fail →** list missing items + `routeTo: game-designer` (or `artist` if visual doc gap).
+
+### Ring 3 ASR checklist (structural — hard fail)
+
+Ring 3 ASR **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 — 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/artist-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}})
+[ ] 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
+```
+
+Optional CLI: `playcraft skills validate-asr-coverage --project-dir .`
+
+**Pass →** handoff orchestrator for next verify step. **Fail →** routeTo Artist (or Game Designer if layout-spec/type budget issue).
+
+---
+
+## Mode: gameplay_conformance
+
+> **Preconditions**: `devStatus: ready` set, `docs/DESIGN.md` exists, devUrl valid.
+> **Executes BEFORE `load_check`** in every ring's verify loop — gameplay correctness must be verified before load/browser check.
+
+### Check A: Design Drift Pre-check
+
+对照 `DESIGN.md` 验证代码是否兑现了设计承诺：
+
+```
+[ ] 核心玩法循环 — 代码中是否实现了 DESIGN.md § 二 描述的完整操作→响应→决策闭环？
+[ ] 规则体系 — 对照 DESIGN.md § 三 的合法操作/状态变化表，是否有遗漏？
+[ ] 胜负条件 — 对照 DESIGN.md § 六，所有胜负条件是否有对应代码逻辑？
+[ ] Experience Flow — Hook / Tutorial / Gameplay / EndCard 四阶段是否全部可达？
+[ ] 首关保证 — DESIGN.md § 八 描述的策略是否在代码/配置中体现？
+[ ] Visual Readability — 玩家能否区分可操作/不可操作/目标/风险？（代码 level 审查）
+[ ] Level Progression — DESIGN.md § 七 的关卡配置是否在代码中正确加载？
+```
+
+**输出**: Design Drift 报告
+
+```markdown
+### Design Drift Result
+
+| #   | 检查项       | 结果        | 详情                                                   |
+| --- | ------------ | ----------- | ------------------------------------------------------ |
+| 1   | 核心玩法循环 | ✅          | swap → match → remove → gravity → refill 全部实现      |
+| 2   | 规则体系     | ❌ Blocking | DESIGN.md 写了"锁定元素不可交换"，代码中未实现锁定逻辑 |
+| 3   | 胜负条件     | ✅          | countdown → lose / clearAll → win 正确                 |
+| ... | ...          | ...         | ...                                                    |
+
+**Summary**: N Blocking / M Non-blocking
+```
+
+**判定**: 有 Blocking Drift → 整体 FAIL，返回 Developer 修复。仅有 Non-blocking Drift → 记录到报告但不阻塞推进。
+
+**Blocking Drift 的判定**：
+
+- 核心玩法、设计承诺、复用承诺的偏离
+- 文档写 A，代码做成 B
+- 为了赶进度临时简化核心规则
+
+**Non-blocking Drift 的判定**：
+
+- 轻微细节、注释差异、非核心体验偏差
+- 已按 reading guide 的 reference 方式合理替换了业务逻辑
+
+### Check B: Skill Usage
+
+对照 `atom-tree.md` 的 `Selected Atoms Summary` / `Selected Skill Notes` / `Gameplay Assembly Link` 与 developer-log § Skill Usage，检查 Skill 库的参考价值是否被有效利用：
+
+```
+[ ] developer-log 中是否记录了 Skill 参考情况？全部跳过时原因是否合理？
+[ ] 标记 scaffold 的 Skill — scaffold 代码是否被实际参考/使用？
+[ ] 标记 reference 的 Skill — 是否有体现核心设计模式的影响？
+[ ] trunk-adjacent roles / providers 的关键引用是否被合理承认？
+[ ] 媒体资产是否已 link 到资产路径？
+```
+
+**这不是合规审计**——目的是确认高质量参考没有被无意中忽略。如果 Developer 记录了合理的不使用原因（"Skill X 的架构不适用于这个场景，因为..."），那就是 OK 的。
+
+### Check C: playwright-cli Automated Path Verification (batch — one tool call)
+
+Use **`playwright-cli run-code`** once instead of atomic open/mousemove/eval/screenshot/close per step:
+
+```bash
+playwright-cli open <devUrl>
+playwright-cli run-code "async page => {
+  await page.setViewportSize({ width: 390, height: 844 });
+  await page.waitForTimeout(3000);
+  const state = await page.evaluate(() => window.__playable?.getState?.() ?? null);
+  await page.screenshot({ path: 'logs/conform-load.png' });
+  return JSON.stringify({ state, url: page.url() });
+}"
+playwright-cli console
+playwright-cli close
+```
+
+Optional: simulate tutorial swap inside the same `run-code` block when DESIGN.md requires manual path proof (ring 2+). Ring 1 `firstLevelWin` is script-owned — Reviewer does not re-prove it here.
+
+自动验证三个关键路径（screenshots from single batch):
+
+```
+[ ] Hook → Tutorial: 页面加载 5s 内显示 Hook 视觉 + Tutorial 引导元素
+    logs/conform-load.png (or dedicated conform-hook.png from run-code)
+
+[ ] Tutorial → Gameplay: 模拟交互后进入 Gameplay 状态（或等待 Tutorial 自动推进）
+
+[ ] Gameplay → EndCard: 超时等待（30s+）或手动推进后，EndCard/CTA 可见
+```
+
+```bash
+playwright-cli console
+playwright-cli close
+```
+
+控制台 Error 级别日志记录但不在此模式阻塞（那是 `load_check` 的职责）。
+
+### Output: Conformance Report
+
+写入 `logs/review-report.md` § Gameplay Conformance:
+
+```markdown
+## Gameplay Conformance
+
+### Design Drift (Check A)
+
+{drift result table + summary}
+
+### Skill Usage (Check B)
+
+{skill usage table + 违规判定}
+
+### Path Verification (Check C)
+
+{path result: ✅ Hook / ✅ Tutorial→Gameplay / ✅ EndCard}
+
+### Overall
+
+- **Result**: PASS / FAIL
+- **Blocking Issues**: {count} — {summary}
+- **Non-blocking Notes**: {count} — {summary}
+```
+
+**Pass →** `conformance: passed`, handoff `Invoke @reviewer load_check`
+**Fail →** route Developer with blocking items; handoff `Re-invoke @developer for conformance fixes`
+
+---
+
+## Mode: ui_diff
+
+> **Read `playwright-cli` skill first.** Save all screenshots under `logs/`.
+> **MUST Read each screenshot PNG** with multimodal vision before writing pass/fail. Disk asset size tables and `verify:visual` JSON alone **do not** satisfy ui_diff.
+
+### Procedure
+
+1. Read MC panel paths from `style-exploration.md` / `assets/images/reference/`.
+2. Run `npm run ensure:project` then `npm run verify:ui` first — catch asset/layout drift before screenshots. If it FAILs on asset/layout, route to Developer/TA and stop; do not proceed to screenshots until PASS or only expected warnings.
+3. Optional: `npm run verify:visual` when ASR locked — objective secondary signal only; **does not replace** visual rubric.
+4. Run `npm run state:get -- --json`; if `devUrl` is down, route to Developer to restart with `npm run dev:start`.
+5. For each scene Developer exposed (URL param or UI button):
+
+```bash
+playwright-cli open <devUrl>[?scene=hook|tutorial|endcard|cta]
+playwright-cli resize 390 844
+playwright-cli screenshot --filename=logs/ui-diff-<scene>.png
+```
+
+6. **Read each `logs/ui-diff-*.png`** (and `logs/load-check.png` if captured) — fill § Structured Visual Rubric below with PASS/FAIL + evidence citing what you see in the image.
+7. Compare each screenshot vs corresponding MC panel:
+
+| Scene      | MC panel        | Check                                   |
+| ---------- | --------------- | --------------------------------------- |
+| Initial    | Panel 1 Concept | Layout, hierarchy, element completeness |
+| Hook       | Panel 2         | Color mood, hook composition            |
+| Onboarding | Panel 3         | Tutorial UI, low-pressure layout        |
+| EndCard    | Panel 4         | CTA zone, unresolved emotion            |
+| CTA        | Panel 5         | Button prominence, accent color         |
+
+8. `playwright-cli console` — log errors (informational for ui_diff; critical only if UI broken).
+9. `playwright-cli close`.
+
+### Structured Visual Rubric (MUST fill in review-report.md — ring 4)
+
+Each row: **PASS / FAIL** + **evidence** (describe what you see in the screenshot; cite screenshot path).
+
+| Check ID          | Question                                                                                                                    | Blocks pass? |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------ |
+| `bg_clean`        | Background is a clean plate — no baked board grid, HUD numbers, title text, or fake prop buttons painted into `bg_*` assets | Yes          |
+| `no_double_board` | Only one interactive tile layer — no ghost/static board under playable tiles (double-board)                                 | Yes          |
+| `no_hud_ghost`    | No duplicate HUD (e.g. two score counters, overlapping progress bars)                                                       | Yes          |
+| `no_fake_ui`      | No non-interactive buttons/icons that look clickable but are baked into background art                                      | Yes          |
+| `tile_silhouette` | Same-type gems share consistent silhouette/size (no mix of hex/diamond/square/drop in one set)                              | Yes          |
+| `text_no_overlap` | Baked Phaser text does not overlap art text on CTA/buttons (e.g. INSTALL vs 立即下载)                                       | Yes          |
+| `mc_layout`       | Scene layout matches locked MC/ASR reference (no critical/major drift)                                                      | Yes          |
+
+**Any FAIL on blocking rows → ui_diff fail.** Set `uiDiff: fail` in § Ring DoD Fields and `uiReviewStatus: failed`.
+
+**All blocking rows PASS + no critical/major scene diffs → ui_diff pass.** Set `uiDiff: pass` and `uiReviewStatus: passed`.
+
+### UI Diff Report (write to review-report.md)
+
+For each difference:
+
+- Screenshot path + MC reference path
+- Description + severity (`critical` / `major` / `minor`)
+- `routeTo: developer | ta | artist`
+- Fix suggestion
+
+**Pass:** no critical/major diffs (minor logged, do not block).
+**Fail:** `uiReworkRound` +1; handoff orchestrator to invoke routed agents.
+
+### Routing guide
+
+| Issue type                         | routeTo   |
+| ---------------------------------- | --------- |
+| Layout, code binding, scene switch | developer |
+| Wrong asset color/size/style       | ta        |
+| Ambiguous design intent            | artist    |
+
+---
+
+## Mode: load_check
+
+Minimal pre-Ring Gate sanity check — **not gameplay QA**.
+
+### Procedure
+
+1. `npm run dev` if needed; `playwright-cli open <devUrl>`.
+2. Wait for load (≤10s); confirm not white screen.
+3. `playwright-cli console` — fail if any **Error**-level log.
+4. `playwright-cli screenshot --filename=logs/load-check.png`.
+5. `playwright-cli close`.
+
+### Checklist
+
+```
+[ ] Page loads within 10s (not white screen)
+[ ] Console has no Error-level messages
+[ ] game/index.html reachable
+```
+
+**Pass →** `loadCheck: passed`, handoff `npm run ring:gate -- --iteration N`.
+**Fail →** routeTo Developer with console error summary.
+
+---
+
+## Severity (ui_diff only)
+
+| Severity | Meaning                     | Blocks pass? |
+| -------- | --------------------------- | ------------ |
+| critical | UI broken / missing         | Yes          |
+| major    | Clear visual mismatch vs MC | Yes          |
+| minor    | Polish / slight drift       | No (log)     |
+
+---
+
+## project-state fields (Reviewer writes)
+
+| Field                | Mode              | Values                    |
+| -------------------- | ----------------- | ------------------------- |
+| `uiReviewStatus`     | ui_diff           | pending / passed / failed |
+| `uiReworkRound`      | ui_diff fail      | 0–5                       |
+| `loadCheck`          | load_check        | pending / passed / failed |
+| `loadCheckNotes`     | load_check        | console + load summary    |
+| `optimizationStatus` | playable_validate | pending / passed / failed |
+| `optimizationReport` | playable_validate | path to validate/\*.md    |
+
+---
+
+## Mode: playable_validate
+
+> **Read `playcraft-playable-optimization` skill first.** Heavy convergence check — ring 3+ verify or optional optimization before final Ring Gate.
+
+### Procedure
+
+1. `npm run ensure:project` — ensure toolkit + Playwright ready.
+2. `npm run verify:ui` — catch asset/layout drift first.
+3. `npm run record:mp4 -- --headed --fps=60` — produce `recordings/playable-YYYYMMDD-HHmmss.mp4`.
+4. Watch MP4 against [validation-rules.md](../../skills/playable-validate/validation-rules.md):
+   - HOOK 0–3s:入场、HUD
+   - TUTORIAL 3–8s:引导
+   - GAMEPLAY 8–22s:输入、FX、连击
+   - ENDCARD 22–25s:CTA、尾帧
+5. Each issue: `[MM:SS] 效果 → P0/P1/P2` + `routeTo: developer | ta | artist`.
+6. If baseline MP4 exists (previous recording), compare for regressions.
+7. Write report to `logs/review-report.md` § Playable Validate and `validate/PLAYABLE-YYYYMMDD-HHmmss.md`.
+
+### Output: Playable Validate Report
+
+```markdown
+## Playable Validate
+
+### Baseline
+
+- Current: recordings/playable-YYYYMMDD-HHmmss.mp4
+- Previous: recordings/playable-...mp4 (if any)
+
+### Findings
+
+| Time  | Effect            | Severity | routeTo | Status |
+| ----- | ----------------- | -------- | ------- | ------ |
+| 00:02 | Hook text cut off | P0       | ta      | open   |
+
+### Regression vs baseline
+
+- 改善: ...
+- 仍存: ...
+- 回归: ...
+
+### Overall
+
+- Result: PASS / FAIL
+- P0: {count} | P1: {count} | P2: {count}
+```
+
+**Pass →** `optimizationStatus: passed`, handoff orchestrator for Ring Gate.
+**Fail →** `optimizationStatus: failed`, route per `routeTo`; handoff invoke routed agents then re-verify.

package/project-templates/phaser/.claude/agents/refs/reviewer-legacy-fallback.md

@@ -0,0 +1,14 @@
+# Reviewer Legacy Fallback
+
+Use this reference only when `dispatchPacket` is null and `sliceState` is empty.
+
+This preserves the older growth-ring review path for existing projects. It is not part of slice-axis dispatch.
+
+Legacy behavior:
+
+- Read `npm run state:get -- --json` and follow the disclosed current action.
+- Use the review mode explicitly requested by the orchestrator.
+- Record structured evidence in the legacy report file when required.
+- Route failures to the responsible role and do not modify production files.
+
+When `sliceState` exists, return to the main Reviewer role contract.

package/project-templates/phaser/.claude/agents/refs/reviewer-six-dimension-eval.md

@@ -0,0 +1,6 @@
+# Reviewer: Six-Dimension Evaluation (deprecated)
+
+> **Superseded by [`reviewer-convergence-eval.md`](./reviewer-convergence-eval.md)** in `convergence-v1`.
+> Do not use six-dimension scoring or final `review`/`rework` stages.
+
+See `agents/reviewer.md` for the three modes: `design_check`, `ui_diff`, `load_check`.