@playcraft/cli 0.0.44 → 0.0.47

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

@@ -1,51 +1,85 @@
-# Core Model — Remix = DAG(Atom[])
+# Core Model — Atom Tree as the Single Structured Contract
 
-## Atom DAG Structure
+## One Structured Source
 
+```text
+Product Contract
+├── atom-tree.json          ←唯一结构化真源
+├── DESIGN.md              ←人读体验契约
+└── layout-spec.md          ←人读路径/资产契约
+
+Execution Layer
+├── implementation-plan.md
+├── project-state.md
+└── role logs
+
+Optional Reading Guide
+└── atom-tree.md            ←由 atom-tree 生成，不是 handoff 必需文件
 ```
-ScaffoldAtom (skeleton)
-  ├── VisualAtom[] (baseline)   → Designer (Phase 1 ASR; v2)
-  ├── VisualAtom[] (completions)→ Technical Artist
-  ├── VisualAtom[] (sprites/3D) → Technical Artist
-  ├── AudioAtom[] (generation)  → Designer
-  ├── AudioAtom[] (processing)  → Technical Artist
-  ├── VFXAtom[] / AnimationAtom[]→ Technical Artist
-  ├── ConfigAtom[]              → Developer
-  └── GameplayAtom              → Developer
+
+## Responsibilities
+
+| File                          | Purpose                                                                 | Contains                                                                                               | Must not contain                  |
+| ----------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------- |
+| `docs/atom-tree.json`         | Selected Skill contract first; product/content blueprint when disclosed | `meta.skillsMatch`, `meta.selectedAtoms`, `meta.rings`, `engine`, optional `globals`/`scenes`/`review` | role chatter, implementation logs |
+| `docs/DESIGN.md`              | Human-readable player promise                                           | core loop, first-level win, hook/CTA, constraints                                                      | duplicated selected Skill catalog |
+| `docs/layout-spec.md`         | Human-readable layout and asset paths                                   | zones, assetMapping, palette, sizes                                                                    | execution tracking / atom status  |
+| `docs/implementation-plan.md` | Developer execution plan                                                | feature order, module decisions, risks, acceptance path                                                | duplicated product tree           |
+| `docs/project-state.json`     | Workflow cursor machine truth                                           | iteration, loop, ringDoD, handoff, blockers, **sliceState**, dispatch via `state:get`                  | product/source-of-truth decisions |
+| `docs/project-state.md`       | Generated state view                                                    | rendered state tables for humans                                                                       | manual edits or required reading  |
+
+## Slice queue (execution axis)
+
+Structured product truth remains `atom-tree.json` + human docs. **Daily dispatch** when seeded:
+
+- `sliceState.slices[]` — minimal playable slices (`sliceId`, `role`, `doWhat`, `flow`, `verifier`, …)
+- `state:get` → `dispatchPacket` — orchestrator invoke unit; **not** ring loop names
+- Ring `meta.rings[N]` — budget / required paths / acceptance keys for outer gates, not subagent self-routing
+
+## Atom Tree Meaning
+
+`docs/atom-tree.json` is the only structured handoff file.
+
+It answers:
+
+- What playable content exists when disclosed: engine, globals, scenes, layers, entities, rules, media.
+- Which engine root was chosen and which scaffold adapter should be used: `meta.engineDecision`.
+- Which Skill matches were considered: `meta.skillsMatch`.
+- Which reusable atoms are selected and linked: `meta.selectedAtoms`.
+- Which ring slice is currently required: `meta.rings[N].requiredPaths`.
+- Which objective verifiers prove the ring: `meta.rings[N].verifiers` / `acceptanceKeys`.
+
+## Engine-Neutral Fast Path
+
+Fast assembly must not hard-code a single engine. The invariant is:
+
+```text
+atom-tree engine root → engine adapter scaffold → window.__playable contract → shared verifier
+```
+
+`phaser.aicomponent`, `threejs.aicomponent`, `playcanvas.aicomponent`, and future engine atoms may initialize differently. They are unified only at the runtime contract and verifier boundary. Harness methods belong on `window.__playable`; engine objects such as Phaser.Game must stay unmodified.
+
+## Command Contract
+
+- Initialize: `playcraft skills init-atom-tree --intent "..."`
+- Apply engine scaffold: `playcraft remix init-template --from-atom-tree` (reads `meta.engineDecision.adapter`, writes `game/` + `.playcraft-engine`)
+- Select: `playcraft skills select-atom --id "<atomId>"`
+- Validate: `playcraft skills validate-atom-tree-selection`
+- Link: `playcraft skills link --from-atom-tree --prune`
+- Optional guide: `playcraft skills gen-atom-tree-md`
+
+**Ring 1 agent chain (legacy growth-rings — when no active slice):**
+
+```text
+@game-designer → seed sliceState + design-brief + DESIGN.md (slice-axis primary)
+  OR legacy: temporary ref-flow atom-selection subagent
+playcraft remix init-template --from-atom-tree
+npm install && npm run verify:contract
+→ orchestrator dispatches @developer via dispatchPacket (not "Ring 1 build" wording)
 ```
 
-## Atom Three Elements
-
-| Element     | Meaning                                      |
-| ----------- | -------------------------------------------- |
-| **Recipe**  | How it was made (prompt, model, seed)        |
-| **Result**  | What it is (image/audio/JSON file)           |
-| **Binding** | How it's used (where in the DAG it connects) |
-
-## Atom Assignment Rules (5 Agents)
-
-| Atom Type                                      | assignTo  | Notes                                                                                                                                                                                                                                                                                   |
-| ---------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `GameplayAtom`                                 | Developer | PGS rules, state machine                                                                                                                                                                                                                                                                |
-| `ConfigAtom`                                   | Developer | Level config, difficulty curve                                                                                                                                                                                                                                                          |
-| `VisualAtom` (baseline)                        | Designer  | **designer-handoff-v2**: baseline = ASR slots in Phase 1; set `atoms[].asrSlot: { sheet, row, col }` (see [atom-plan-format.md § `asrSlot`](atom-plan-format.md#asrslot-字段可选--visualatom-基线绑定)); Phase 2 mark `done` with `actualOutput: ASR:...` or ICP supplementary PNG only |
-| `VisualAtom` (completions: remaining elements) | TA        | Derive full set from samples                                                                                                                                                                                                                                                            |
-| `VisualAtom` (sprite sheets/animation/VFX)     | TA        | Technical pipeline                                                                                                                                                                                                                                                                      |
-| `VisualAtom` (3D models/GLB)                   | TA        | 3D pipeline; needs `referenceSource`                                                                                                                                                                                                                                                    |
-| `AudioAtom` (original generation)              | Designer  | BGM/SFX generation                                                                                                                                                                                                                                                                      |
-| `AudioAtom` (post-processing)                  | TA        | compress/trim/loop                                                                                                                                                                                                                                                                      |
-| `VFXAtom`                                      | TA        | VFX sprite sheets                                                                                                                                                                                                                                                                       |
-| `AnimationAtom`                                | TA        | Animation sprite sheets                                                                                                                                                                                                                                                                 |
-
-**Simple rule** (v2): Designer locks **MC + ASR** direction; TA mass-produces from ASR/MC to contract paths. Designer does not batch-export tile/UI PNGs at `assetMapping` in Phase 2.
-
-## Scheduling Metadata (PM injects into `docs/atom-plan.json` → `atoms[]`)
-
-| Field                          | Meaning                                        | Impact                                                                                           |
-| ------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `assignTo`                     | Which agent executes                           | Required for all atoms                                                                           |
-| `referenceSource`              | Reference image source for 3D atoms            | `"designer-sample"` → starts immediately; `"ta-completion"` → waits                              |
-| `dependsOn: [atomId]`          | Explicit prerequisites                         | Determines execution order                                                                       |
-| `priority: high/normal/low`    | Priority level                                 | Affects TA scheduling                                                                            |
-| `parallelGroup`                | Parallel execution group                       | Same-group atoms start simultaneously                                                            |
-| `asrSlot: { sheet, row, col }` | VisualAtom baseline → ASR grid cell (optional) | TA auto-derives crop pixels from `designer-log § Sheet grid metadata` — eliminates manual lookup |
+## Boundaries
+
+- `atom-tree.json` may contain structural dependencies and selected atom refs.
+- `atom-tree.json` must not become a task tracker with `assignTo`, `status`, or `actualOutput`.
+- `atom-tree.md` is generated reading guidance only; if it disagrees with `atom-tree.json`, the JSON wins.

package/project-template/docs/team/game-designer-migration-todo.md

@@ -0,0 +1,8 @@
+# Game Designer migration todo (growth-rings-v1)
+
+> **Status**: Superseded by growth-rings-v1 migration (2026-06). Kept for audit trail only.
+
+| Location                                               | Legacy item               | Resolution in growth-rings-v1                                     | Status |
+| ------------------------------------------------------ | ------------------------- | ----------------------------------------------------------------- | ------ |
+| `.claude/agents/game-designer.md`                      | Gate #1 Deliverable Card  | Ring 1 clarify deliverables in role card + collaboration glossary | done   |
+| `.claude/agents/refs/game-designer-workflow-detail.md` | Atlas grouping at Gate #1 | Atlas grouping at ring 2 layout-spec lock                         | done   |

package/project-template/docs/team/harness-legacy-deprecation.md

@@ -0,0 +1,23 @@
+# Harness Legacy Deprecation
+
+## Current (2026-06)
+
+| Surface                                         | Status          | Notes                                                          |
+| ----------------------------------------------- | --------------- | -------------------------------------------------------------- |
+| `window.__playable`                             | **Required**    | Pass standard for `verify:contract`, `record:mp4`, `verify:ui` |
+| `MainScene._onDebugAutoPlay()` + `sceneManager` | **Legacy warn** | Still passes static/live probes with deprecation warning       |
+| Harness methods on `window.__game.start`        | **Blocked**     | Shadowing `Phaser.Game.start` breaks boot                      |
+
+## Timeline
+
+| Milestone             | Target      | Action                                                         |
+| --------------------- | ----------- | -------------------------------------------------------------- |
+| Dual-path support     | 2026-06     | Ship `publishPlayableRuntime()` + Phaser/Three.js engine-packs |
+| Legacy warn in probes | 2026-06     | `evaluateContract` warns when only scene hooks present         |
+| Legacy removal        | **2026-Q3** | `verify:contract` fails if `window.__playable` absent          |
+
+## Migration
+
+1. Call `publishPlayableRuntime()` from `game/index.ts` (see `game/contract/publish.ts`).
+2. Phaser projects: use `registerPlayable()` / `bindPlayableScene()` from `game/adapters/phaser.ts`.
+3. Run `npm run verify:contract` — should report OK without legacy warnings.

package/project-template/docs/team/platform-capabilities.md

@@ -1,15 +1,18 @@
 # Platform Capabilities
 
-| Category            | Command Prefix                                                  | Used By                                              |
-| ------------------- | --------------------------------------------------------------- | ---------------------------------------------------- |
-| AI Image Generation | `playcraft tools generate-image`                                | Designer / TA                                        |
-| AI 3D Generation    | `playcraft tools generate-3d`                                   | **TA**                                               |
-| 3D Pipeline         | `playcraft 3d *`                                                | **TA**                                               |
-| Sprite Sheets       | `playcraft image sprite-sheet/sprite-split/animate/use-vfx`     | **TA**                                               |
-| Image Processing    | `playcraft image resize/crop/convert/remove-background/overlay` | **TA**                                               |
-| Audio Generation    | `playcraft tools generate-sfx/generate-bgm`                     | Designer                                             |
-| Audio Processing    | `playcraft audio compress/trim/loop/...`                        | **TA**                                               |
-| Skills Discovery    | `playcraft skills list/match`                                   | All agents                                           |
-| Asset Info          | `playcraft image info` / `playcraft audio info`                 | TA / Reviewer                                        |
-| Dev preview         | `npm run dev` (project `scripts.dev`)                           | Developer / Reviewer / orchestrator (refresh devUrl) |
-| Build (future)      | `playcraft build` / `build-all`                                 | Not required for current `done` gate                 |
+| Category                   | Command Prefix                                                                      | Used By                                                  |
+| -------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| AI Image Generation        | `playcraft tools generate-image`                                                    | Designer / TA                                            |
+| AI 3D Generation           | `playcraft tools generate-3d`                                                       | **TA**                                                   |
+| 3D Pipeline                | `playcraft 3d *`                                                                    | **TA**                                                   |
+| Sprite Sheets              | `playcraft image sprite-sheet/sprite-split/animate/use-vfx`                         | **TA**                                                   |
+| Image Processing           | `playcraft image resize/crop/convert/remove-background/overlay`                     | **TA**                                                   |
+| Audio Generation           | `playcraft tools generate-sfx/generate-bgm`                                         | Designer                                                 |
+| Audio Processing           | `playcraft audio compress/trim/loop/...`                                            | **TA**                                                   |
+| Skills Discovery           | `playcraft skills *` (load `playcraft-skill-recommender` skill for CLI reference)   | temporary ref-flow / Developer / Artist / TA as assigned |
+| Asset Info                 | `playcraft image info` / `playcraft audio info`                                     | TA / Reviewer                                            |
+| Dev preview                | `npm run dev` (project `scripts.dev`)                                               | Developer / Reviewer / orchestrator (refresh devUrl)     |
+| Placeholder images         | `npm run placeholder:gen` (`skills/_shared/scripts/gen-placeholder.py`)             | **Developer** (ring 1–2 build)                           |
+| Placeholder audio          | `npm run placeholder:gen-audio` (`skills/_shared/scripts/gen-placeholder-audio.py`) | **Developer** (ring 1–2 build, when load paths exist)    |
+| Develop placeholders skill | `skills/playable-placeholder/SKILL.md`                                              | **Developer**                                            |
+| Build (future)             | `playcraft build` / `build-all`                                                     | Not required for current `done` gate                     |

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

@@ -2,64 +2,136 @@
 
 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.
 
-## convergence-v1 (current)
+## growth-rings-v1 (current)
+
+**Effective**: project-template default for new playable-ad projects (template `0.3.2-alpha.0`).
+
+### 2026-06-23 — Ring 1 responsibility split
+
+- **Fix**: split atom-tree selection out of the orchestrator and Game Designer. Ring 1 now routes `@game-designer` → temporary ref-flow atom-selection subagent → scaffold gate → `@developer`.
+- **Scope**: ring 1 atom-tree is a compact selection package for engine scaffold and Skill reading, not a full product tree or execution plan.
+- **Developer scope**: ring 1 build target narrowed to the smallest verifiable playable spine; rings 2+ carry periphery, hook/CTA packaging, and fuller content.
+- **Maintenance**: agent tool surfaces should stay role-minimal. Long command catalogs belong in role refs / skills, not in every role card.
+
+### 2026-06-17 — Ring 1 Dispatch Path (restore multi-agent orchestration)
+
+- **Fix**: Ring 1 "Direct Path" had been interpreted as orchestrator inline execution (test9: single agent wrote DESIGN + game/). Restored **orchestrator dispatch**: `loop: clarify` → `@game-designer`; post-STOP scaffold → `@developer`; `loop: verify` → `ring:gate`.
+- **Still blocked**: internal Task lists (`TaskCreate` / …) during iteration 1 — not `Task` subagent spawn.
+- **`disclosure-config`**: `1:clarify` nextCommands = invoke game-designer; new `1:scaffold` phase after GD STOP; `1:build` = invoke developer + verifiers.
+- **`user-prompt.mjs`**: loop-aware injection tells orchestrator to dispatch, not inline role-play.
+
+### 2026-06-17 — Ring 1 Direct Path default (hook enforcement)
+
+- **`user-prompt.mjs`**: when `iteration: 1`, injects `hookSpecificOutput.additionalContext` with the Ring 1 linear recipe on every `UserPromptSubmit` (soft enforcement).
+- **`block-ring1-tasklist.mjs`**: new `PreToolUse` hook denies `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` / `TaskOutput` / `TaskStop` during iteration 1 (hard enforcement).
+- **`project-state` slimming**: agent entry banner + collapsed deferred tables; agents should use `npm run state:get` instead of reading the full file in Ring 1.
+- **Goal**: bare `claude -p "<goal>"` should follow direct path without a manual hard-constraint prompt (test8-style).
+
+### 2026-06-24 — Knife 7: slice queue producer / plan alignment (slice-axis Ring 1)
+
+- **Ring 1 Game Designer** (slice-axis): `design-brief.md` progressive discovery + `DESIGN.md` seed + `sliceState` developer slice queue — **not** layout/style/CTA/full plan.
+- **`design-brief.template.md`** restored for discovery; **`plan.template.md`** reframed as slice-queue explain view; **`atom-tree.json`** adds `meta.activatedSlices[]`.
+- **STOP**: when `sliceState` is seeded, `validateGameDesignerSliceQueueSeed` requires developer slice + `design-brief`; blocks premature `layout-spec` / `style-exploration` in Ring 1.
+- **Legacy ring 1** (empty `sliceState`): unchanged ref-flow path.
+
+### 2026-06-16 — Ring 1 progressive disclosure (clarify fast path)
+
+- **Ring 1 clarify (legacy pre-slice-axis) = one concise `docs/DESIGN.md`** (core gameplay only). With **slice-axis Knife 7**, `design-brief.md` returns as Ring 1 discovery log alongside the slice queue.
+- **`game-designer.md`** gains an authoritative **Ring 1 clarify — fast path** section: fixed paths, explicit STOP conditions, and a copy-adapt `npm run state:set` STOP recipe. Agents must not reverse-engineer hooks/gates or research style/audio/layout in ring 1.
+- **STOP gate relaxed**: `validate-workflow-stop.mjs` ring 1 required docs = `docs/DESIGN.md` for Game Designer and `project-state + DESIGN` for Developer intake (design-brief dropped); rings 2–4 unchanged. design-brief is still validated _if present_.
+- **Goal**: cut the ring 1 clarify loop from ~7 min to ~2 min by removing dual-doc writes, parallel process-log discipline, and premature research.
+
+- `init-template` refuses to wipe user `game/` unless `--force`, scaffold manifest, or pending placeholder.
+- `playcraft create` base template: no `.playcraft-engine`, placeholder `game/` until init-template.
+
+### 2026-06-15 — engine-neutral scaffold (`0.3.1-alpha.0`)
+
+- **Engine scaffold is explicit**: `playcraft remix init-template --from-atom-tree` applies `meta.engineDecision.adapter` to `game/` + `.playcraft-engine`. `init-atom-tree` only writes metadata and prints the next command.
+- **Supported adapters (v1)**: `phaser`, `threejs` — unified at `window.__playable` + shared verifiers.
+- **Orchestrator ring 1 build gate**: init-template + `npm run verify:contract` before `@developer` when `iteration: 1` + `loop: build`.
+- **workflow-doctor**: errors on adapter / marker mismatch; errors on missing marker during ring 1 build.
+
+### Summary (growth-rings-v1 baseline)
+
+- **Four growth rings** climb the atom-tree from engine root upward: (1) engine-root + core gameplay, (2) gameplay + periphery, (3) playable ad hook/CTA, (4) production + architecture.
+- **Inner loops per ring**: `clarify` → `build` → `verify` → **Ring Gate** (user acceptance). All roles collaborate each ring; depth increases per iteration.
+- **Objective DoD**: `npm run ring:gate -- --iteration N` runs verifiers (`verify:contract`, `record:mp4`, `verify:ui`, etc.) instead of pre-development document packages.
+- **Non-regression**: `archivedRings` in handoff YAML; prior ring DoD must stay green.
+- **assetMapping freeze** moved to ring 4 only (was Gate #exec in convergence-v1).
+- **Replaced**: waterfall stages (`pm → storyboard → planning → development → ...`) and six gates (`#1`, `#2a`, `#exec`, `#dev`, `#2b`, `#3`).
+
+## convergence-v2 (superseded by growth-rings-v1)
 
 **Effective**: project-template default for new playable-ad projects.
 
 ### Summary
 
-- **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).
+- **Three convergence loops**: (1) scripted package checks for Gate #1 / #exec, plus Reviewer `design_check` before Gate #2b; (2) `pm → storyboard → planning → development → style_exploration → production → ui_review ⇄ ui_rework → done`; (3) Reviewer `gameplay_conformance` + `load_check` before Gate #dev → user gameplay acceptance; Reviewer `ui_diff` (browser screenshots vs MC, max 5 rounds) → Gate #3 visual acceptance.
+- **Single Developer model**: `developer` owns the full `development` stage — upstream intake, spec quick-check, read/load of existing code + Skill refs, implementation, integration, feature-checklist review, `devStatus: ready`, `devUrl`, and blockers. `developer-lead` is retained only as a compatibility alias.
+- **Removed**: internal `developer-lead → developer` batch dispatch as the default development pattern, `integration`, `review`, `rework` (replaced by `ui_rework`), six-dimension final review, AI gameplay walkthrough.
+- **Production orchestration**: after Gate #2b, **strict serial** — Artist Ph.2 → TA → `ui_review`.
+- Visual delivery unchanged from **artist-handoff-v2** (MC + ASR, Handoff Pack, Phase 2 audio/digit 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
+pm → storyboard → development → style_exploration → production → ui_review ⇄ ui_rework → 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        | `ui_pass`    | `@developer` after Wave 2 `done` + Compliance green |
+| Wave | Agent            | Stage        | Orchestrator invoke                     |
+| ---- | ---------------- | ------------ | --------------------------------------- |
+| 1    | Artist           | `production` | `@artist` Ph.2 only after Gate #2b      |
+| 2    | Technical Artist | `production` | `@technical-artist` after Wave 1 `done` |
 
 ### Trade-offs
 
-| 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 |
+| Benefit                                                                 | Cost                                              |
+| ----------------------------------------------------------------------- | ------------------------------------------------- |
+| More context preserved inside one development owner                     | Developer role must carry more reading discipline |
+| Existing code and Skill refs less likely to be dropped between handoffs | Less parallelism by default inside development    |
+| Read/load + checklist review become explicit readiness criteria         | Development logs must be more structured          |
+
+---
+
+## convergence-v1
+
+**Superseded by** `convergence-v2`.
+
+### Summary
+
+- **Three convergence loops**: (1) scripted package checks for Gate #1 / #exec, plus Reviewer `design_check` before Gate #2b; (2) `pm → storyboard → planning → development → style_exploration → production → ui_review ⇄ ui_rework → done`; (3) Reviewer `gameplay_conformance` + `load_check` before Gate #dev → user gameplay acceptance; Reviewer `ui_diff` (browser screenshots vs MC, max 5 rounds) → Gate #3 visual acceptance.
+- **Historical Developer Lead / Developer split**: this was the old model. Current workflow uses the single `developer` role for scoped runtime implementation tasks, with `developer-lead` retained only as a compatibility alias.
+- **Removed**: `integration`, `review`, `rework` (replaced by `ui_rework`), six-dimension final review, AI gameplay walkthrough.
+- **Production orchestration**: after Gate #2b, **strict serial** — Artist Ph.2 → TA → `ui_review`.
+- Visual delivery unchanged from **artist-handoff-v2** (MC + ASR, Handoff Pack, Phase 2 audio/digit only).
+- **Reviewer tooling**: `playwright-cli` skill for browser automation (screenshot, console, resize).
 
 ---
 
 ## production-serial-v1
 
-**Superseded by** `convergence-v1` for orchestration; serial production waves below still apply within `production` stage.
+**Superseded by** `convergence-v2` for orchestration; serial production waves below still apply within `production` stage.
 
 ---
 
-## designer-handoff-v2
+## artist-handoff-v2
 
 **Superseded by** `production-serial-v1` for orchestration; visual rules below still apply.
 
 ### Summary
 
 - Visual baseline locked in **Phase 1**: Master Composite (MC) + **ASR** dual sheets (UI + element state reference).
-- **Phase 2 Designer**: BGM, SFX, digit strip only; `assignTo: Designer` VisualAtoms marked `done` when covered by ASR (not separate `tile_sample_*.png` batch).
-- **Gate #2b Handoff Pack**: ASR Coverage Matrix, Palette Locked, Motion Notes in `designer-log` / `style-exploration`.
+- **Phase 2 Artist**: BGM, SFX, digit strip only; visual coverage stays in ASR / artist-log, not a separate `VisualAtom done` status pass (not separate `tile_sample_*.png` batch).
+- **Gate #2b Handoff Pack**: ASR Coverage Matrix, Palette Locked, Motion Notes in `artist-log` / `style-exploration`.
 - Retired paths: `exploded_view_*.png`, `concept_selected.png`, per-frame `concept_*.png` / `hook_*.png` deliverable tables.
 
 ---
 
-## designer-handoff-v1 (legacy)
+## artist-handoff-v1 (legacy)
 
 - Single **Exploded View** (or scattered concept/storyboard PNGs) as TA extract source.
-- Phase 2 sometimes assumed Designer outputs `tile_sample_*.png` at `assetMapping` paths.
+- Phase 2 sometimes assumed Artist outputs `tile_sample_*.png` at `assetMapping` paths.
 - `playcraft-exploded-view` skill id (removed in v2).