@playcraft/cli 0.0.41 → 0.0.42

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/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,18 @@ 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`
+
 ## Automated
 
 ```bash

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)
 

package/project-template/templates/designer-log.template.md

@@ -74,6 +74,22 @@ TA crop index + Phase 2 VisualAtom actualOutput: ASR:sheet:R#C#
 
 **Delta vs layout-spec Color Palette**: {{match | PM update: one line}}
 
+## Skill Preflight (Phase 2)
+
+> **Mandatory before audio/digit production.** Read relevant Skills + check mediaGroups.
+
+| Skill / Check              | 已读 | 关键决策摘要                                  |
+| -------------------------- | ---- | --------------------------------------------- |
+| playcraft-audio-generation | ☐    | {{BGM mood, SFX prompt pattern, loop config}} |
+| playcraft-text-rendering   | ☐    | {{digit strip chroma strategy, font style}}   |
+| playcraft-image-generation | ☐    | {{background decision for digit strip}}       |
+| mediaGroups (.aiaudio)     | ☐    | {{linked: X, skipped: Y, reason: Z}}          |
+
+<!--
+  MUST be filled before generating any audio or digit strip in Phase 2.
+  mediaGroups: list each .aiaudio match disposition (linked/skipped + reason).
+-->
+
 ## Style Consistency Self-Check
 
 - [ ] All visual assets share the same art style?

package/project-template/templates/developer-log.template.md

@@ -2,116 +2,119 @@
 
 ## Upstream Intake
 
-> **Step 0 — mandatory before Spec Quick-Check or any `game/` edit.** Summarize what PM/Designer/TA already decided so implementation matches intent.
+> **Step 0 — mandatory before Spec Quick-Check or any `game/` edit.**
+
+| Doc                         | Read ✓ | One-line takeaway                         |
+| --------------------------- | ------ | ----------------------------------------- |
+| `docs/project-state.md`     | ☐      | {{e.g. ui_pass, Wave 2 done}}             |
+| `docs/design-brief.md`      | ☐      | {{e.g. flow scenes for navigation}}       |
+| `docs/layout-spec.md`       | ☐      | {{e.g. zones, assetMapping, atlas paths}} |
+| `docs/atom-plan.json`       | ☐      | {{e.g. Developer atoms + skillRefs}}      |
+| `docs/atom-plan.md`         | ☐      | Impl Skill Context + acceptance           |
+| `docs/style-exploration.md` | ☐      | {{e.g. MC panel layout per scene}}        |
+| `logs/designer-log.md`      | ☐      | {{e.g. palette locked, motion notes}}     |
+| `logs/ta-log.md`            | ☐      | {{e.g. compliance green, atlas params}}   |
 
-| Doc                         | Read ✓ | One-line takeaway (what you will implement from it)    |
-| --------------------------- | ------ | ------------------------------------------------------ |
-| `docs/project-state.md`     | ☐      | {{e.g. integration, Wave 2 done, no spec-gap}}         |
-| `docs/design-brief.md`      | ☐      | {{e.g. PGS=match-3, tutorial 2 taps, first level win}} |
-| `docs/layout-spec.md`       | ☐      | {{e.g. board zone, tile atlas path + frameIds}}        |
-| `docs/atom-plan.json`       | ☐      | {{e.g. 6 Developer atoms, skillRef memory_match}}      |
-| `docs/atom-plan.md`         | ☐      | Impl Skill Context + acceptance criteria               |
-| `docs/style-exploration.md` | ☐      | {{e.g. MC panel1 UI layout, Hook frame contrast}}      |
-| `logs/designer-log.md`      | ☐      | {{e.g. motion: slow-mo near-win}}                      |
-| `logs/ta-log.md`            | ☐      | {{e.g. Compliance green, tile atlas 8 frames}}         |
+---
+
+## Skill Preflight
+
+> **Before any `game/` edits (ui_pass).** See `refs/developer-phase1-flow.md` Step 3.
 
-**MUST NOT** start Skill Preflight until every row is checked with a non-empty takeaway.
+| skillRef     | access                | `ref/` files read (paths) | `scaffold` included |
+| ------------ | --------------------- | ------------------------- | ------------------- |
+| {{skillRef}} | linked / cli-fallback | {{paths}}                 | yes / no            |
 
 ---
 
-## Skill Preflight
+## UI Pass Plan
 
-> **Ph.1 gate — before any `game/` edits.** Per `docs/atom-plan.json` `atoms[]` (`assignTo: Developer`, non-null `skillRef`). See `refs/developer-phase1-flow.md` Step 3.
+> **ui_pass only — mandatory before UI implementation.** Hook enforces on STOP.
 
-| skillRef     | access                | `ref/` files read (paths)                       | `scaffold` included |
-| ------------ | --------------------- | ----------------------------------------------- | ------------------- |
-| {{skillRef}} | linked / cli-fallback | {{e.g. .claude/skills/.../ref/pgs-schema.json}} | yes / no            |
+### Architecture
 
-```bash
-# Paste actual CLI output snippets (or summary) below — empty section = Ph.1 incomplete
-{{skills_read_and_scaffold_output}}
-```
+- **Engine**: {{engine}}
+- **Entry**: `game/index.html`
+- **Scene flow**: Hook → Tutorial → EndCard → CTA (navigation only in ui_pass)
 
-<!--
-Rules:
-  - One row per non-dash skillRef from atom-plan
-  - access: `linked` = read `.claude/skills/<skillRef>/`; `cli-fallback` = soft link missing, used `playcraft skills read` + Package Skills Root
-  - If skillRef = — for an atom, note "skills match" or playcraft-research in Impl Skill Context instead
-  - Do NOT mark GameplayAtom/ConfigAtom done in atom-plan until this table is filled
--->
+### Scene-Asset Binding Plan
 
-## Delivery Summary
+| Scene    | Assets (assetMapping) | Atlas/Frame | On disk? |
+| -------- | --------------------- | ----------- | -------- |
+| hook     | {{paths}}             | {{json}}    | {{y/n}}  |
+| tutorial | {{paths}}             | {{json}}    | {{y/n}}  |
+| endcard  | {{paths}}             | {{json}}    | {{y/n}}  |
 
-- **Assigned**: {{total_assigned}}
-- **Completed**: {{total_completed}}
-- **Bindings resolved**: {{resolved}}/{{total_bindings}}
+### Scene navigation (for Reviewer ui_diff)
 
-## Experience Flow → Code Mapping
+| MC panel   | Scene key   | How to reach (URL param / button)  |
+| ---------- | ----------- | ---------------------------------- |
+| Concept    | {{initial}} | {{e.g. ?scene=main or default}}    |
+| Hook       | hook        | {{e.g. ?scene=hook}}               |
+| Onboarding | tutorial    | {{e.g. button or ?scene=tutorial}} |
+| EndCard    | endcard     | {{...}}                            |
+| CTA        | cta         | {{...}}                            |
 
-> **Step 0c — Mandatory. Map each storyboard frame to code scene.**
-> Read `docs/style-exploration.md` concept mockup + storyboard composite image before implementing.
-> The storyboard is a single composite image with 4 frames in a grid — study each frame's position.
-
-| Storyboard Frame          | Scene/State      | Code Location             | Visual Intent                 |
-| ------------------------- | ---------------- | ------------------------- | ----------------------------- |
-| Hook (0-3s)               | `scene.hook`     | `game/scenes/hook.ts`     | {{visual_intent_description}} |
-| Tutorial (3-10s)          | `scene.tutorial` | `game/scenes/tutorial.ts` | {{visual_intent_description}} |
-| Gameplay+NearWin (10-25s) | `scene.gameplay` | `game/scenes/gameplay.ts` | {{visual_intent_description}} |
-| EndCard (25-30s)          | `scene.endcard`  | `game/scenes/endcard.ts`  | {{visual_intent_description}} |
-
-<!--
-Rules:
-  - Every scene code file MUST have a top comment referencing the storyboard:
-    // Visual reference: assets/images/storyboard/storyboard_confirmed.png (frame: top-left=Hook)
-  - If storyboard frame visuals conflict with layout-spec zones coordinates:
-    → storyboard takes precedence, ask PM in intent-clarifications.md
-  - Visual Intent column should capture the EMOTION and ATTENTION FLOW, not just mechanics
--->
+### Risk Checklist (ui_pass)
 
-## Per-Atom Delivery
+- [ ] Every assetMapping path verified on disk
+- [ ] Scene navigation documented for all 5 MC panels
+- [ ] No core gameplay rules in ui_pass scope
+- [ ] No external network dependencies
 
-### {{atom_id}} — {{slot_name}}
+---
 
-- **Status**: {{status}}
-- **Reference Skill**: {{skillRef}} (Skill Preflight: linked or cli-fallback + ref/)
-- **Output path**: {{file_path}}
-- **Test results**: {{passed}}/{{total}} passed
-- **Notes**: {{implementation_notes}}
+## Gameplay Pass Plan
+
+> **gameplay_pass only — mandatory before PGS / rules implementation.**
 
-<!--
-Repeat for each atom.
-For GameplayAtom: include PGS path + test results
-For ConfigAtom: include config path + parameter summary
--->
+### PGS Strategy
 
-## Binding Status
+- **Gameplay type**: {{from design-brief}}
+- **Core rules**: {{from Skill recipe}}
+- **First level guarantee**: {{how tutorial ensures win}}
+- **State machine**: {{states and transitions}}
 
-| Binding Target               | Source Atom        | File                | Status                     |
-| ---------------------------- | ------------------ | ------------------- | -------------------------- |
-| {{scene_path_or_config_key}} | {{source_atom_id}} | {{asset_file_path}} | {{bound/missing/mismatch}} |
+### Risk Checklist (gameplay_pass)
 
-<!--
-List every asset reference in your code:
-- Every image loaded from assets/images/
-- Every audio file referenced from assets/audio/
-- Every config value from layout-spec
+- [ ] UI shell unchanged unless open UI Diff items
+- [ ] testCases written before rule implementation
+- [ ] First level guarantees player success
+- [ ] CTA handler with platform fallbacks
+- [ ] Zero external network requests
+
+---
+
+## Experience Flow → Code Mapping
 
-Status values:
-  bound    — File exists and is correctly referenced
-  missing  — File not found at expected path
-  mismatch — File exists but wrong dimensions/format
--->
+| Storyboard Frame | Scene/State      | Code Location             | Visual Intent |
+| ---------------- | ---------------- | ------------------------- | ------------- |
+| Hook             | `scene.hook`     | `game/scenes/hook.ts`     | {{intent}}    |
+| Tutorial         | `scene.tutorial` | `game/scenes/tutorial.ts` | {{intent}}    |
+| Gameplay         | `scene.gameplay` | `game/scenes/gameplay.ts` | {{intent}}    |
+| EndCard          | `scene.endcard`  | `game/scenes/endcard.ts`  | {{intent}}    |
+
+---
 
 ## Dev self-check
 
-> After `npm run dev` — record each integration pass. See `refs/developer-dev-handoff.md`.
+### ui_pass completion
 
 - **devUrl**: {{http://localhost:...}}
-- **devLastChecked**: {{ISO timestamp}}
+- **devStatus**: ui_ready
 - **UI vs MC + layout-spec**: {{pass/fail — notes}}
+- **Scene navigation works**: {{yes/no}}
+- **Ready for Reviewer ui_diff**: {{yes/no}}
+
+### gameplay_pass completion
+
+- **devUrl**: {{http://localhost:...}}
+- **devStatus**: ready
 - **Gameplay vs design-brief + PGS**: {{pass/fail — notes}}
-- **Runtime** (no white screen, CTA, audio, state machine): {{pass/fail — notes}}
-- **Ready for Reviewer**: {{yes/no}}
+- **Runtime** (CTA, audio, state machine): {{pass/fail — notes}}
+- **Ready for Reviewer load_check**: {{yes/no}}
+
+---
 
 ## Upstream blockers
 
@@ -119,22 +122,13 @@ Status values:
 | -------- | --------- | -------------- | ------------------ | --------------- |
 | {{path}} | {{issue}} | {{acceptance}} | TA / Designer / PM | open / resolved |
 
-<!--
-When any row is open:
-  - Set project-state devStatus: blocked_upstream
-  - Write intent-clarifications.md with acceptance criteria
-  - STOP — wait for orchestrator rework invoke
--->
-
-## Technical Self-Check (static)
-
-- [ ] Board dimensions match layout-spec `zones["board"].rect`?
-- [ ] Element IDs match layout-spec `colorPalette.tileColors[].id`?
-- [ ] All asset paths match layout-spec `assetMapping`?
-- [ ] Zero external network requests (no fetch/XHR/external scripts)?
-- [ ] CTA handler implemented with multi-platform fallback?
-- [ ] `game/index.html` has viewport meta with user-scalable=no?
-- [ ] All CSS/JS inline (no external resources)?
-- [ ] First level guarantees player success?
-
-> **Not required for integration complete**: `playcraft build` (future delivery path only).
+---
+
+## Per-Atom Delivery
+
+### {{atom_id}} — {{slot_name}}
+
+- **Status**: {{status}}
+- **Phase**: ui_pass / gameplay_pass
+- **Output path**: {{file_path}}
+- **Notes**: {{notes}}