@playcraft/cli 0.0.43 → 0.0.46

package/project-templates/threejs/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-templates/threejs/docs/team/platform-capabilities.md

@@ -0,0 +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 *` (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-templates/threejs/docs/team/workflow-changelog.md

@@ -0,0 +1,137 @@
+# Workflow Changelog
+
+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.
+
+## 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) 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 → storyboard → development → style_exploration → production → ui_review ⇄ ui_rework → done
+```
+
+### Production waves (serial)
+
+| 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                                              |
+| ----------------------------------------------------------------------- | ------------------------------------------------- |
+| 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-v2` for orchestration; serial production waves below still apply within `production` stage.
+
+---
+
+## 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 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.
+
+---
+
+## artist-handoff-v1 (legacy)
+
+- Single **Exploded View** (or scattered concept/storyboard PNGs) as TA extract source.
+- Phase 2 sometimes assumed Artist outputs `tile_sample_*.png` at `assetMapping` paths.
+- `playcraft-exploded-view` skill id (removed in v2).

package/project-templates/threejs/docs/team/workflow-consistency-checklist.md

@@ -0,0 +1,240 @@
+# Workflow Consistency Checklist
+
+Maintenance checklist after editing `packages/cli/project-template`. Run before merging doc changes.
+
+## Phase A — Invoke protocol
+
+- [x] `agent-conduct.md`: § Invoke protocol (all sub-agents)
+- [x] All five agents: First Step = handoff → Runtime → conditional refs
+- [x] Checkpoint documented as human log only (collaboration § STOP sync)
+
+## Phase B — Track done & stage sync
+
+- [x] Each agent Runtime has **Track done** note
+- [x] `CLAUDE.md` + `playcraft-orchestrator.mdc`: § Stage sync on handoff
+- [x] `project-state.template.md`: handoff Examples comment block
+
+## Phase C — STOP sync
+
+- [x] `collaboration.md`: § STOP sync checklist (4 steps)
+- [x] `agent-conduct.md`: sub-agents MUST complete STOP sync
+
+## Phase D — L1 < 220 lines
+
+- [x] `game-designer.md`, `artist.md`, `developer.md`, `reviewer.md`, `technical-artist.md` each **< 220** lines
+- [x] New refs registered in `refs/README.md` with L1 back-links
+- [x] `artist-deliverable-spec.md`, `artist-style-exploration-flow.md`, `developer-phase1-flow.md` exist
+
+## Phase F — TA atlas / WebP / MP3
+
+- [x] `ta-atlas-deliverable-standard.md` exists; TA L1 + Runtime reference it
+- [x] `layout-spec.template.md`: atlas grouping table, webp defaults, frameId column
+- [x] `collaboration.md` § Asset Contract: WebP atlas + MP3
+- [x] Game Designer `game-designer-workflow-detail.md`: Atlas grouping at Gate #1
+- [x] Developer cookbook: atlasPath + frameId binding
+
+## Round 3 — Invoke 体感打磨
+
+### Phase A — Runtime 入口微调
+
+- [x] Artist Runtime: Phase 1 Skill Discovery → style-exploration-flow (one line)
+- [x] Developer Runtime: Spec Quick-Check (30s, MUST) on production branch
+- [x] Developer Ph.1 STOP: `next_orchestrator_action` = single value `Wait for parallel tracks`
+- [x] TA Step 0: verb pipeline (no E→A→B→C→D shorthand in L1)
+- [x] TA Compliance: atlas grouping table check + spec-gap routeTo Game Designer
+
+### Phase B — L1 术语显式化
+
+- [x] Game Designer Runtime: 四件套 list + atlas groups + Style Direction in Track done
+- [x] Reviewer Goals: six dimension names + Vetoes listed
+- [x] Artist Track done: MC 5×9:16 ratio (≈ 2.81)
+
+### Phase C — 跨 Agent 同步
+
+- [x] `collaboration.md` § STOP sync: Parallel Tracking table example
+- [x] `CLAUDE.md` + `playcraft-orchestrator.mdc`: Stage sync includes `Run Gate #2a`
+- [x] All five L1 Mission: link to CLAUDE § Stage Model
+- [x] `developer-phase1-flow.md`: linear Step 1–8 ordering
+
+### Phase D — 重复段清理
+
+- [x] Developer L1: no separate `## Phase 1` / `## Phase 2` headings (Execute L2 under Runtime)
+- [x] Artist Phase 2: skills/refs/output only (no duplicate Trigger)
+- [x] Developer Important Rules: Test-first + Atlas binding split (#5 / #6)
+- [x] Reviewer Output: sync `handoff.rework_round` on fail
+
+## Gate & orchestration (baseline)
+
+- [x] Gate Protocol matches CLAUDE Orchestration table
+- [x] All five agents: Runtime + PLAYCRAFT_STOP
+- [x] Game Designer Gate #1 four docs; Reviewer no `stage: rework`; Developer handoff Invoke @reviewer
+
+## Polish pass (Glossary / deliverable cards / TA Step naming)
+
+- [x] `collaboration.md`: § Glossary (canonical terms)
+- [x] `game-designer.md`: § Gate #1 Deliverable Card
+- [x] Reviewer: `rework_round` failure budget explicit in L1 + `reviewer-six-dimension-eval.md`
+- [x] `refs/README.md`: § 按 invoke 场景反查
+- [x] `ta-pipeline-cookbook.md`: Step 0/1/2 (not Phase 0/1/2)
+- [x] `CLAUDE.md`: Single-Agent Fallback removed; sub-agent invoke required
+
+## Phase G — Artist Handoff v2
+
+- [x] `docs/team/workflow-changelog.md` documents `artist-handoff-v2`
+- [x] `templates/project-state.template.md` § Workflow spec + Parallel Tracking (audio + digit + artist wave notes)
+- [x] `artist-deliverable-spec.md`: Handoff Pack, Phase 2 VisualAtom rules; no legacy Phase 2 visual-only-TA sentence
+- [x] `artist-handoff-v2-checklist.md` linked from `artist-style-exploration-flow.md` Step 5
+- [x] `templates/style-exploration.template.md` uses MC + ASR (no `concept_{{a}}.png`)
+- [x] `templates/artist-log.template.md`: ASR Coverage Matrix + Palette Locked
+- [x] `playcraft-style-qa` uses MC path; no `concept_selected.png`
+- [x] `playcraft-asset-state-sheet` skill exists; `playcraft-exploded-view` removed
+- [x] `core-model.md` + `atom-tree.template.json` v2 VisualAtom baseline
+- [x] Vitest `designer-handoff-v2` cases pass
+
+## Phase J — atom-tree simplified manifest
+
+- [x] `docs/team/atom-tree-format.md` — JSON + MD split rewritten as selection manifest + reference guide
+- [x] `templates/atom-tree.template.json` aligned to `meta.skillsMatch` / `meta.selectedAtoms` / `selectionRevisions[]`
+- [ ] ref-flow runtime / refs fully aligned to the simplified atom-tree model
+- [ ] CLI-side validation / hook story updated for the new schema
+- [x] `playcraft-workflow` core docs (`collaboration.md` / `agent-conduct.md` / `pipeline-overview.md` / `CLAUDE.md`) aligned to the new atom-tree positioning
+- [ ] tests / hooks that still assume old `selectedSkills`-style schema audited and updated
+
+## Phase I — Upstream intake + four-doc discipline + hooks
+
+- [x] `agent-conduct.md`: Game Designer/Artist four-doc discipline; TA/Developer Upstream Intake MUST
+- [x] `ta-pipeline-cookbook.md` Step 0a + `developer-phase1-flow.md` Step 0
+- [x] `ta-log.template.md` + `developer-log.template.md` § Upstream Intake
+- [x] `game-designer.md` + `game-designer-workflow-detail.md` + `artist.md` + `collaboration.md` § Four-doc discipline
+- [x] `.claude/settings.json` + `.cursor/hooks.json` → `validate-workflow-stop.mjs`
+- [x] Vitest `upstream-intake` + `validate-workflow-stop.test.ts` pass
+
+## Phase H — Production serial v1
+
+- [x] `workflow-changelog.md`: `production-serial-v1` current; no Migration section
+- [x] `templates/project-state.template.md`: `workflowSpecVersion` = `production-serial-v1`; § Production Pipeline (no Parallel Tracking / THREE-WAY)
+- [x] Gate #2b: orchestrator invokes `@artist` only; serial `@technical-artist` → `integration` `@developer`
+- [x] `artist.md` STOP: `Invoke @technical-artist`; `technical-artist.md`: `Set stage=integration, invoke @developer`
+- [x] `developer.md` Runtime: no `stage: production` row; single `integration` branch
+- [x] `developer-phase1-flow.md`: trigger `integration`; no assets-not-required / Parallel with
+- [x] `CLAUDE.md` + `playcraft-orchestrator.mdc` + `collaboration.md` + `agent-conduct.md` + `agent-runtime-matrix.md` aligned
+- [x] Vitest `production-serial-v1` cases pass
+
+## Phase K — Plan convergence (TA + Developer)
+
+- [x] `templates/ta-log.template.md`: § Production Plan (Coverage / Atlas / Pipeline Order / Risk)
+- [x] `templates/developer-log.template.md`: § Implementation Plan (Architecture / Scene-Asset / PGS / Risk)
+- [x] `validate-workflow-stop.mjs`: validates Plan section + Risk Checklist + no placeholders
+- [x] `.claude/hooks/README.md`: documents Plan validation on STOP
+- [x] `technical-artist.md` + `developer.md`: Runtime + Track done + Important Rules reference Plan
+- [x] `ta-pipeline-cookbook.md` Step 0d + `developer-phase1-flow.md` Step 3b
+- [x] `agent-conduct.md`: TA/Developer MUST/MUST NOT for Plan before production/code
+- [x] `collaboration.md` § STOP sync checklist step 5 (Plan convergence)
+- [x] Vitest `validate-workflow-stop.test.ts` covers `validatePlan`
+
+## Phase M — Developer role / flow split
+
+- [x] `developer.md` rewritten around role perspective (architecture / project state / requirement implementation / boundaries)
+- [x] Shared docs (`CLAUDE.md`, `agent-conduct`, `agent-runtime-matrix`, `pipeline-overview`) state that Skill literacy belongs to Developer cognition; flow docs only project it onto the current atom-tree
+- [x] `developer-phase1-flow.md` explicitly scoped to execution sequence, not role ownership
+- [x] `developer-dev-handoff.md` and `developer-impl-cookbook.md` marked as verification / pattern refs, not runtime authority
+- [x] `refs/README.md` clarified L1 vs L2 expectation for Developer docs
+- [x] `docs/role-analysis/04-developer-agent.md` updated to reflect role card vs flow split
+
+## Phase L — convergence-v1 doc alignment audit (2026-05)
+
+Documents missed during the `production-serial-v1` → `convergence-v1` upgrade (commit `9fdc39a06`). Each item below has a [W#] tag indicating which audit wave applied the fix.
+
+> **⚠️ Critical finding** — commit `9fdc39a06` introduced `convergence-v1` but did **not modify any vitest test files**. Result: 23 tests under `packages/cli/test/project-template-workflow.test.ts` + `validate-workflow-stop.test.ts` are pre-existing failures against the new spec. Audit Wave W4 includes the full test suite re-alignment.
+
+### W1 — Doc alignment
+
+- [x] `agent-runtime-matrix.md`: rewritten — replaced `integration` / `review` / `rework` with `ui_pass` / `ui_review` / `ui_rework` / `gameplay_pass`; `reworkRound` → `uiReworkRound`; added `devStatus` / `loadCheck` columns; added Post-STOP verification table
+- [x] All five agent L1 files (`game-designer.md`, `artist.md`, `technical-artist.md`, `developer.md`, `reviewer.md`): added `> **Workflow spec**: convergence-v1` declaration line at top
+- [x] `refs/game-designer-workflow-detail.md`: `integration` → `ui_pass` (lines 144, 247)
+- [x] `developer-dev-handoff.md`: `stage → review` → `devStatus: ui_ready` / `ready` + handoff `Invoke @reviewer ui_diff/load_check` (line 99)
+
+### W2 — Term alignment (ASR)
+
+- [ ] `playcraft-asset-state-sheet` Skill: "ASR State Inventory" → "ASR Coverage Matrix" (artist-log only has Coverage Matrix)
+- [ ] `artist-log.template.md` § ASR Coverage Matrix: add "Sheet grid" metadata (rows × cols + cell width × height + cell padding)
+- [ ] `ta-pipeline-cookbook.md` Step 0a + ASR extraction: aligned references
+
+### W3 — Machine-readable ASR binding
+
+- [ ] superseded under the simplified atom-tree manifest model; ASR coverage remains in `artist-log.template.md` and downstream logs instead of `atom-tree.json`
+
+### W4 — Hook hardening + test suite re-alignment
+
+- [ ] `validate-workflow-stop.mjs`: add `artist` branch validating `artist-log.md § Skill Preflight`
+- [x] `validate-workflow-stop.mjs`: `readStage()` regex accepts current stage names (`pm`, `storyboard`, `development`, `style_exploration`, `production`, `ui_review`, `ui_rework`, `done`)
+- [ ] `packages/cli/test/validate-workflow-stop.test.ts`: add designer + YAML stage test cases; rewrite `Developer Implementation Plan sample` → use `UI Pass Plan` / `Gameplay Pass Plan`
+- [ ] `packages/cli/test/project-template-workflow.test.ts`: rewrite stale describes (originally pre-existing failures from commit `9fdc39a06`):
+  - `workflow-docs` (9 tests): replace six-dimension scoring / `rework_round` / `stage: review` assertions with `convergence-v1` equivalents (`uiReworkRound`, `ui_diff`, `load_check`)
+  - `production-serial-v1` (6 tests): delete or migrate to `convergence-v1` describe
+  - `upstream-intake-four-doc-discipline` (1 test): align with current `developer-phase1-flow.md`
+  - `plan-convergence-ta-developer` (6 tests): "Implementation Plan" → "UI Pass Plan" / "Gameplay Pass Plan"
+  - hooks README test: same alignment
+
+### W5 — TA Compliance Gate coverage
+
+- [x] `ta-log.template.md` § Compliance Gate: add `Text dimensions` row (for `images/txt/*`)
+- [x] `ta-log.template.md` § Compliance Gate: add `Digit Strip dimensions` row (separate from UI)
+- [x] `layout-spec.template.md` Digit Sprite Strip section: recommend `images/txt/digits.webp` path
+- [x] `ta-pipeline-cookbook.md` § Transparency Classification example table: align digit path with `images/txt/` recommendation
+
+### W6 — Interface polish
+
+- [x] `artist-deliverable-spec.md` § Phase 2: clarify ICP supplementary PNG trigger condition (only when TA Step 0c confidence=low **and** crop/segment failed)
+- [x] `ta-log.template.md` Style Interpretation: change "Do NOT proceed with any asset type where confidence = low" → atom-granularity ("hold that asset type; other types continue")
+- [x] `artist-log.template.md` + `ta-log.template.md` § mediaGroups Reuse: add `extension` column + filter note (Artist: `.aiaudio` only; TA: `.aiimage` + `.aisprite`)
+
+## Phase GR — growth-rings-v1 alignment (2026-06)
+
+- [x] `collaboration.md` rewritten: Ring Gate Protocol + Iteration field ownership anchors
+- [x] `.cursor/rules/playcraft-orchestrator.mdc` — iteration×loop matrix (no waterfall Gates)
+- [x] `.cursor/rules/playcraft-subagent-boundary.mdc` — ring/loop boundaries
+- [x] Role cards + key refs updated to growth-rings vocabulary
+- [x] `validate-workflow-stop.mjs` — validatePlan uses `loop` not `stage`
+- [x] `verify:visual` + `verify:atom-conformance` + `workflow-doctor --strict`
+- [x] `validate-workflow-stop` invokes `workflow-doctor` `strict: 'stop'` on every gated STOP
+- [x] `ring:gate` passes `--strict-if-references` to `verify:visual` when ASR is locked
+- [x] `pipeline-overview.md` + `docs/harness/playcraft-harness-overview.md` updated
+- [x] Vitest: project-template-workflow, validate-workflow-stop, workflow-doctor
+
+> Phases A–N above describe **superseded** `convergence-v1` / `planning-stage-v1` history — do not use for new edits.
+
+## Phase O — engine-neutral scaffold (growth-rings + init-template, template `0.3.1-alpha.0`)
+
+- [x] `playcraft remix init-template` (`--engine`, `--from-atom-tree`, `--bake`, `--all-engines`)
+- [x] `engine-packs/{phaser,threejs}` + `compose.ts` (project-template ⊕ pack)
+- [x] `game/contract/` + `publishPlayableRuntime()` + Phaser adapter
+- [x] `workflow-doctor`: `.playcraft-engine` vs `meta.engineDecision.adapter`
+- [x] Ring 1 build gate in `playcraft-orchestrator.mdc`
+- [x] `CLAUDE.md` + `collaboration.md` + `pipeline-overview.md` — Ring 1 init-template chain
+- [x] `developer.md` / `skill-selector-guide.md` / `game-designer-workflow-detail.md` — engine vs atom scaffold
+- [x] `playable-record` / `playable-debug` / `playable-validate` / `playcraft-playable-optimization` SKILL — `window.__playable`
+- [x] `docs/harness/playcraft-harness-overview.md` (monorepo meta) — phaser/threejs + init-template
+- [x] Vitest: `scaffold-compose.test.ts`, workflow-doctor engine checks, verify-contract legacy warn
+
+```bash
+cd packages/cli && pnpm exec vitest run test/scaffold-compose.test.ts test/workflow-doctor.test.ts test/verify-contract.test.ts test/harness-contract.test.ts
+```
+
+## Phase N — planning-stage-v1 (Gate #1 slim + planning stage + Gate #exec)
+
+Flow change: Gate #1 only requires design-brief + DESIGN.md. After Gate #2a (MC selection), a new `planning` stage produces layout-spec (via sendMessage to Game Designer) → atom-tree (ref-flow) → implementation-plan (plan-writer). Gate #exec confirms the execution plan before development.
+
+- [x] `CLAUDE.md`: Stage Model string includes `planning`; Gates include `#exec`; Stage sync table updated; Stage transition table updated; Asset Contract locked after Gate #exec (not #1); Post-STOP verification includes planning docs
+- [x] `docs/team/collaboration.md`: Gate Protocol table includes `#exec`; Gate #1 section rewritten (2 deliverables only); Gate #exec section added; Stage field ownership includes `planning`; Four-doc discipline updated; Glossary updated (两件套)
+- [x] `docs/pipeline-overview.md`: 全景矩阵 includes `planning`; Gate 节点一览 includes `#exec`; Stage 1 pm 产出缩减; Stage 2.5 `planning` added; Stage 3 development adjusted; Orchestrator 决策速查 updated
+- [x] `docs/team/agent-runtime-matrix.md`: Game Designer row updated (planning stage sendMessage); Orchestrator row updated (planning + #exec); Reviewer row updated (execution_plan_check)
+- [x] `docs/team/agent-conduct.md`: Orchestrator MUST includes #exec; Reviewer MUST includes execution_plan_check; Asset Contract locked after Gate #exec; Gate #1 design_check simplified
+- [x] `templates/project-state.template.md`: Stage string includes `planning`; Gates table includes `#exec`; Handoff examples updated; File Index split (Gate #1 vs Planning)
+- [x] `.claude/agents/reviewer.md`: Runtime table includes `execution_plan_check`; Goals table includes new mode; Review flow summary updated
+- [x] `.claude/agents/game-designer.md`: Outputs section mentions layout-spec in planning stage via sendMessage
+- [x] `.claude/agents/refs/skill-selector-guide.md`: temporary ref-flow atom selection runs in ring 1 after Game Designer; ref-flow deepening remains ring 2+
+- [ ] `.claude/agents/refs/implementation-plan-guide.md`: Note that plan-writer runs in `planning` stage
+- [ ] `.claude/agents/refs/storyboard-generation-guide.md`: Confirm no layout-spec dependency (storyboard reads design-brief only)
+- [ ] `docs/team/workflow-changelog.md`: Document `planning-stage-v1` change
+- [ ] Tests updated for new stage/gate sequence

package/project-templates/threejs/game/config/game-config.ts

@@ -0,0 +1,46 @@
+/**
+ * GAME_CONFIG — single source of truth for layout + runtime switches.
+ *
+ * Both the running game (TypeScript) and the verification harness
+ * (`verify:ui` loads this file directly via esbuild) read THIS file.
+ * There is no generated copy, so the values verify against can never drift
+ * from the values the game runs with.
+ */
+
+export interface GameConfig {
+  /** Design-space canvas width in px (portrait playable). */
+  DESIGN_WIDTH: number;
+  /** Design-space canvas height in px. */
+  DESIGN_HEIGHT: number;
+
+  /** CTA band vertical center / height / width in design space. */
+  CTA_Y: number;
+  CTA_H: number;
+  CTA_W: number;
+
+  /** Safe-area insets in px. */
+  SAFE_TOP: number;
+  SAFE_BOTTOM: number;
+  SAFE_SIDE: number;
+
+  /** Dev/record switch: show the one-click auto-play debug button. */
+  SHOW_DEBUG_BUTTON: boolean;
+  /** Dev/record switch: skip transitions to speed up capture. */
+  SKIP_TRANSITIONS: boolean;
+}
+
+export const GAME_CONFIG: GameConfig = {
+  DESIGN_WIDTH: 1080,
+  DESIGN_HEIGHT: 1920,
+
+  CTA_Y: 1620,
+  CTA_H: 300,
+  CTA_W: 1080,
+
+  SAFE_TOP: 48,
+  SAFE_BOTTOM: 48,
+  SAFE_SIDE: 16,
+
+  SHOW_DEBUG_BUTTON: true,
+  SKIP_TRANSITIONS: false,
+};

package/project-templates/threejs/game/contract/publish.ts

@@ -0,0 +1,141 @@
+import type { PlayablePhase, PlayableRuntimeContract, SceneManagerContract } from "./types.js";
+
+export type PublishPlayableBinding = {
+  engine?: string;
+  engineHandle?: unknown;
+  sceneManager: SceneManagerContract;
+  onDebugAutoPlay: () => void;
+  hideDebugUi?: () => void;
+  getCanvas?: () => HTMLCanvasElement | null;
+  getCaptureFps?: () => number;
+};
+
+/** DOM id for the on-screen one-click clear (debug auto-play) button. */
+export const DEBUG_CLEAR_BUTTON_ID = "playable-debug-clear";
+
+/** True when the page was opened with the `?debug=1` URL flag. */
+export function isDebugMode(): boolean {
+  try {
+    return new URLSearchParams(window.location.search).get("debug") === "1";
+  } catch {
+    return false;
+  }
+}
+
+/** Remove the on-screen one-click clear button (e.g. before MP4 capture). */
+export function removeDebugClearButton(): void {
+  if (typeof document === "undefined") return;
+  document.getElementById(DEBUG_CLEAR_BUTTON_ID)?.remove();
+}
+
+/**
+ * Mount a fixed, on-screen "一键通关 (one-click clear)" debug button that calls
+ * window.__playable.autoPlay(). Rendered ONLY when the page is opened with
+ * `?debug=1`, so production / capture stays clean. Idempotent.
+ *
+ * Ring 1 onward this button is a hard requirement (verified by verify:firstwin):
+ * every playable must expose a debug-gated one-click clear from the first ring.
+ */
+export function mountDebugClearButton(contract: PlayableRuntimeContract): void {
+  if (typeof document === "undefined" || !isDebugMode()) return;
+  if (document.getElementById(DEBUG_CLEAR_BUTTON_ID)) return;
+
+  const btn = document.createElement("button");
+  btn.id = DEBUG_CLEAR_BUTTON_ID;
+  btn.type = "button";
+  btn.textContent = "🐞 一键通关";
+  btn.setAttribute("data-debug", "1");
+  Object.assign(btn.style, {
+    position: "fixed",
+    left: "50%",
+    bottom: "16px",
+    transform: "translateX(-50%)",
+    zIndex: "999999",
+    padding: "10px 18px",
+    fontSize: "16px",
+    fontFamily: "system-ui, sans-serif",
+    color: "#1a1a1a",
+    background: "#FFD54A",
+    border: "2px solid #1a1a1a",
+    borderRadius: "10px",
+    boxShadow: "0 2px 8px rgba(0,0,0,0.35)",
+    cursor: "pointer",
+  } as Partial<CSSStyleDeclaration>);
+  btn.addEventListener("click", (e) => {
+    e.preventDefault();
+    try {
+      contract.autoPlay();
+    } catch (err) {
+      console.error("[playable-debug] one-click clear failed", err);
+    }
+  });
+
+  const mount = () => document.body.appendChild(btn);
+  if (document.body) mount();
+  else window.addEventListener("DOMContentLoaded", mount, { once: true });
+}
+
+/** Publish the neutral recorder/debug entry point after the main scene is ready. */
+export function publishPlayableRuntime(binding: PublishPlayableBinding): PlayableRuntimeContract {
+  const contract: PlayableRuntimeContract = {
+    engine: binding.engine ?? "unknown",
+    engineHandle: binding.engineHandle,
+    sceneManager: binding.sceneManager,
+    getState: () => ({
+      currentPhase: binding.sceneManager.currentPhase,
+      isGameOver: binding.sceneManager.isGameOver(),
+    }),
+    autoPlay: binding.onDebugAutoPlay,
+    start: binding.onDebugAutoPlay,
+  };
+  // Always provide hideDebugUi: it removes the on-screen debug button (for clean
+  // capture) and delegates to any engine-specific cleanup the binding supplied.
+  contract.hideDebugUi = () => {
+    removeDebugClearButton();
+    binding.hideDebugUi?.();
+  };
+  if (binding.getCanvas) contract.getCanvas = binding.getCanvas;
+  if (binding.getCaptureFps) contract.getCaptureFps = binding.getCaptureFps;
+  window.__playable = contract;
+  mountDebugClearButton(contract);
+  return contract;
+}
+
+/** Legacy Phaser MainScene shape — prefer window.__playable for new engines. */
+export interface PlayableMainSceneLike {
+  sceneManager?: SceneManagerContract;
+  _onDebugAutoPlay?(): void;
+}
+
+/**
+ * Validate that a scene satisfies the legacy Phaser harness contract.
+ * Neutral engines should rely on publishPlayableRuntime only.
+ */
+export function assertPlayableSceneContract(scene: PlayableMainSceneLike): void {
+  const problems: string[] = [];
+
+  if (!scene.sceneManager) {
+    problems.push("scene.sceneManager is missing");
+  } else {
+    if (typeof scene.sceneManager.currentPhase !== "string") {
+      problems.push("sceneManager.currentPhase must be a PlayablePhase string");
+    }
+    if (typeof scene.sceneManager.isGameOver !== "function") {
+      problems.push("sceneManager.isGameOver() must be a function");
+    }
+  }
+  if (typeof scene._onDebugAutoPlay !== "function") {
+    problems.push("scene._onDebugAutoPlay() must be a function");
+  }
+
+  if (problems.length > 0) {
+    const msg =
+      "[playable-contract] MainScene violates the recording/debug harness contract:\n" +
+      problems.map((p) => `  - ${p}`).join("\n") +
+      "\nSee game/runtime-contract.ts — record:mp4 and one-click clear depend on these hooks.";
+    console.error(msg);
+    throw new Error(msg);
+  }
+}
+
+export type { PlayablePhase, PlayableRuntimeContract, SceneManagerContract };

package/project-templates/threejs/game/contract/types.ts

@@ -0,0 +1,34 @@
+/** Lifecycle phases the recorder waits on (HOOK → … → ENDCARD). */
+export type PlayablePhase = "HOOK" | "TUTORIAL" | "GAMEPLAY" | "ENDCARD";
+
+/** Minimal scene-state surface the harness reads. */
+export interface SceneManagerContract {
+  currentPhase: PlayablePhase;
+  isGameOver(): boolean;
+}
+
+/** Engine-neutral recorder/debug surface. Do not attach harness methods to the engine object. */
+export interface PlayableRuntimeContract {
+  engine: string;
+  /** Opaque engine handle (Phaser.Game, THREE.WebGLRenderer context owner, etc.). */
+  engineHandle?: unknown;
+  sceneManager: SceneManagerContract;
+  getState(): { currentPhase: PlayablePhase; isGameOver: boolean };
+  autoPlay(): void;
+  start(): void;
+  /** Optional: hide debug UI before capture. */
+  hideDebugUi?(): void;
+  /** Optional: canvas for record bridge when engine handle is opaque. */
+  getCanvas?(): HTMLCanvasElement | null;
+  /** Optional: target capture FPS hint for record bridge. */
+  getCaptureFps?(): number;
+}
+
+declare global {
+  interface Window {
+    __playable?: PlayableRuntimeContract;
+    __game?: unknown;
+  }
+}
+
+export {};