@playcraft/cli 0.0.44 → 0.0.47

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

@@ -1,6 +1,6 @@
-# Reviewer: Convergence Evaluation (design_check / ui_diff / load_check)
+# Reviewer: Convergence Evaluation (design_check / gameplay_conformance / ui_diff / load_check / playable_validate)
 
-> **Read before executing any Reviewer mode.** Replaces six-dimension final review in `convergence-v1`.
+> **Read before executing any Reviewer mode.** Growth-rings verify modes for `growth-rings-v1`.
 > Invoked from `agents/reviewer.md` — orchestrator specifies mode per invoke.
 
 ---
@@ -9,21 +9,26 @@
 
 Soft checklist only — **do not judge subjective design quality**.
 
-### Gate #1 checklist (PM four docs)
+### Ring 1 clarify checklist (minimal package)
 
 ```
-[ ] design-brief exists; Style Direction has Dimension / Modality / Arc
+[ ] 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-plan.json exists; skillsMatch non-empty
-[ ] every atom has assignTo + dependsOn
-[ ] no obvious cross-doc contradictions (assetMapping paths align with atoms)
+[ ] 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: pm` (or `designer` if visual doc gap).
+**Fail →** list missing items + `routeTo: game-designer` (or `artist` if visual doc gap).
 
-### Gate #2b additional checklist (structural — hard fail)
+### Ring 3 ASR checklist (structural — hard fail)
 
-Gate #2b **structural** gaps are hard fails (missing files, row count, type representatives). Do not fail for subjective aesthetics.
+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)
@@ -31,30 +36,166 @@ Gate #2b **structural** gaps are hard fails (missing files, row count, type repr
 [ ] 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)
+[ ] 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}})
-[ ] 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
 ```
 
 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).
+**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 →** classify owner per blocking issue:
+- Contract/design ambiguity, gameplay-vs-spec conflict, malformed layout-spec, product-meaning degradation → **Game Designer**
+- Runtime / `game/**` / Skill usage evidence / scene reachability → **Developer**
+- Asset contract/file gap → **TA or Artist** by evidence
+
+Handoff `Re-invoke <routed agent> 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. `npm run dev` if devUrl down; read devUrl from `project-state.md`.
-3. For each scene Developer exposed (URL param or UI button):
+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]
@@ -62,7 +203,8 @@ playwright-cli resize 390 844
 playwright-cli screenshot --filename=logs/ui-diff-<scene>.png
 ```
 
-4. Compare each screenshot vs corresponding MC panel:
+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                                   |
 | ---------- | --------------- | --------------------------------------- |
@@ -72,8 +214,26 @@ playwright-cli screenshot --filename=logs/ui-diff-<scene>.png
 | EndCard    | Panel 4         | CTA zone, unresolved emotion            |
 | CTA        | Panel 5         | Button prominence, accent color         |
 
-5. `playwright-cli console` — log errors (informational for ui_diff; critical only if UI broken).
-6. `playwright-cli close`.
+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)
 
@@ -81,25 +241,26 @@ For each difference:
 
 - Screenshot path + MC reference path
 - Description + severity (`critical` / `major` / `minor`)
-- `routeTo: developer | ta | designer`
+- `routeTo: developer | ta | artist`
 - Fix suggestion
 
 **Pass:** no critical/major diffs (minor logged, do not block).
-**Fail:** `uiReworkRound` +1; handoff orchestrator to `ui_rework`.
+**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            | designer  |
+| Issue type                                        | routeTo       |
+| ------------------------------------------------- | ------------- |
+| Layout, code binding, scene switch                | developer     |
+| Wrong asset color/size/style                      | ta            |
+| Ambiguous design intent, illustration mismatch    | artist        |
+| Contract ambiguity, design-owned blocker          | game-designer |
 
 ---
 
 ## Mode: load_check
 
-Minimal pre-Gate #3 sanity check — **not gameplay QA**.
+Minimal pre-Ring Gate sanity check — **not gameplay QA**.
 
 ### Procedure
 
@@ -117,7 +278,7 @@ Minimal pre-Gate #3 sanity check — **not gameplay QA**.
 [ ] game/index.html reachable
 ```
 
-**Pass →** `loadCheck: passed`, handoff `Run Gate #3 with devUrl`.
+**Pass →** `loadCheck: passed`, handoff `npm run ring:gate -- --iteration N`.
 **Fail →** routeTo Developer with console error summary.
 
 ---
@@ -134,9 +295,62 @@ Minimal pre-Gate #3 sanity check — **not gameplay QA**.
 
 ## 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    |
+| 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-template/.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.