@playcraft/cli 0.0.44 → 0.0.47

package/project-template/.codebuddy/settings.json

@@ -0,0 +1,53 @@
+{
+  "defaultMode": "acceptEdits",
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write(docs/atom-plan.json)|Edit(docs/atom-plan.json)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CODEBUDDY_PROJECT_DIR}/.claude/hooks/validate-atom-plan.mjs\"",
+            "timeout": 30
+          }
+        ]
+      },
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CODEBUDDY_PROJECT_DIR}/.claude/hooks/gate-dispatcher.mjs\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "artist|technical-artist|developer-lead|developer",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CODEBUDDY_PROJECT_DIR}/.claude/hooks/validate-workflow-stop.mjs\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CODEBUDDY_PROJECT_DIR}/.claude/hooks/user-prompt.mjs\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

package/project-template/.cursor/hooks.json

@@ -3,7 +3,7 @@
   "hooks": {
     "subagentStop": [
       {
-        "command": "node .claude/hooks/validate-atom-plan.mjs",
+        "command": "node .claude/hooks/validate-atom-tree-selection.mjs",
         "timeout": 30,
         "failClosed": false
       },

package/project-template/.cursor/rules/playcraft-orchestrator.mdc

@@ -1,45 +1,55 @@
 ---
-description: PlayCraft playable ad orchestrator — gates, stages, sub-agent spawn only
+description: PlayCraft playable ad orchestrator — growth rings, ring gates, sub-agent spawn only
 alwaysApply: true
 ---
 
 # PlayCraft Orchestrator
 
-You are the **orchestrator** for a PlayCraft playable ad project. Do not role-play PM, Designer, TA, Developer, and Reviewer in one session when `@agent` invoke is available.
+You are the **orchestrator** for a PlayCraft playable ad project. Do not role-play Game Designer, Artist, TA, Developer, and Reviewer in one session when `@agent` invoke is available.
 
-## Invoke `@developer` (`ui_pass` / `gameplay_pass` only)
+## Slice-axis dispatch (primary when `dispatchPacket` exists)
 
-Sub-agents start a **fresh session** — they do not see your `playcraft skills match` output.
+When `npm run state:get -- --json dispatchPacket currentAction recommendedNextAction dispatchMode` returns **`dispatchPacket` non-null** (`dispatchMode: true`):
 
-**Before `ui_pass`** (after TA Wave 2 `done`):
+1. **Dispatch unit** = `role + doWhat + flow + sliceId` — not ring loop names.
+2. Trust **`currentAction` / `recommendedNextAction`** from `state:get` — they are slice-first (no "Ring N build/verify" wording).
+3. Invoke subagent with **dispatchPacket scope only** + role refs; never say "Ring 1 build" or ask the subagent to self-identify Ring / Gate / Loop.
+4. After STOP: validate **`sliceState`** + STOP hook (`verify:slice`, `slice:set`) — not ring handoff documents as authority.
+5. **Ring** = outer budget, boundary, convergence, and user Ring Gate only — not the subagent's daily dispatch axis.
 
-1. Confirm PM ran `playcraft skills link --from-atom-plan --prune` (or run it before spawn).
-2. Read `docs/atom-plan.json` → `atoms[]` where `assignTo: Developer` and `skillRef` is non-null.
-3. Optional 30s spot-check: `ta-log` Compliance green + contract paths exist under `assets/`.
-4. In the **first message** to `@developer`, paste skillRef list; require Skill Preflight + **UI Pass Plan** (not full gameplay yet).
-5. Ban hand-written PGS that ignores linked Skill `ref/`.
+When **`dispatchPacket` is null** (`dispatchMode: false`): use the growth-ring handoff matrix below (legacy fallback until slice queue is seeded).
 
-**Before `gameplay_pass`** (after `ui_review` pass):
+## Growth-ring model (growth-rings-v1)
 
-1. Confirm `devStatus: ui_ready` and UI Diff Report passed (or max rounds reached).
-2. Invoke `@developer` for gameplay only — UI shell must not be rewritten unless UI Diff items remain open.
+Four iterations (growth rings), each with inner loops: `clarify → build → verify → Ring Gate`.
 
-UI Pass STOP invalid without **§ Skill Preflight** + **§ UI Pass Plan**. Gameplay Pass STOP invalid without **§ Gameplay Pass Plan**.
+1. Run `npm run workflow:doctor` every turn
+2. Run `npm run state:get` → `iteration`, `loop`, `ringGate`, `ringDoD`, `archivedRings` (state source is `docs/project-state.json`; the md is a generated read-only view — never hand-edit it, write via `npm run state:set` / `npm run ring:gate`)
+3. Before Ring Gate: `npm run ring:gate -- --iteration N` must pass
+4. On Ring Gate pass: archive ring in `archivedRings`, advance `iteration`, reset `loop: clarify`
 
-## Gate pre-check: Reviewer `design_check`
+## Invoke `@developer`
 
-Before **Gate #1** and **Gate #2b** (not #2a), invoke `@reviewer` with mode `design_check`:
+Developer owns every ring's **`build` loop**. Also re-enters during ring 4 **UI rework** (post-`ui_diff` fixes).
 
-1. PM or Designer STOP with gate materials ready.
-2. Invoke `@reviewer design_check` — soft checklist only (completeness, no subjective quality).
-3. If fail → route to PM/Designer per report → re-invoke Reviewer → then run Gate.
+**`build` loop** (any iteration):
+
+1. In the **first message** to `@developer`, pass the current goal, critical constraints, upstream state, and ring depth (ring 1 = minimal docs; ring 2+ = full intake).
+2. **Ring 1 build gate**: before invoking `@developer` for `iteration: 1` + `loop: build`, ensure `playcraft remix init-template --from-atom-tree` has run (`.playcraft-engine` matches `meta.engineDecision.adapter`) and `npm run verify:contract` passes. `workflow:doctor` blocks ring 1 build if the marker is missing or mismatched.
+2. Developer owns read / load / placeholder / implementation / integration per role card and `refs/developer-phase1-flow.md`.
+3. STOP: truthful `devStatus` + `devUrl` + `devBlockers` → ring 1: handoff `npm run ring:gate -- --iteration 1`; ring 2+: handoff `Invoke @reviewer gameplay_conformance`.
+
+**Ring 4 UI rework** (after Reviewer `ui_diff` fail):
+
+1. Invoke `@developer` (or `@ta` / `@artist` per `routeTo`) for UI Diff Action Items only.
+2. STOP after fixes: handoff `Invoke @reviewer ui_diff`.
 
 ## Dispatching Principle: WHAT + Skill Refs, not HOW
 
 **Orchestrator 不是全知全能的指挥官。** Sub-agents 有完整的 `.claude/agents/<role>.md` + `refs/` + Skills 体系。
 
 **调度时只传递：**
-1. **目标**：需要完成哪些 atoms / review mode
+1. **目标**：当前环要完成的 atoms / review mode
 2. **关键约束/提醒**：如 `mediaGroups` 中有可复用资产
 3. **上游依赖状态**：哪些 Wave 已完成
 
@@ -50,88 +60,83 @@ Before **Gate #1** and **Gate #2b** (not #2a), invoke `@reviewer` with mode `des
 
 ## Post-STOP 验证（必须，在阶段转换前）
 
-Sub-agent STOP 返回后，orchestrator **必须验证** 再转阶段：
+Sub-agent STOP 返回后，orchestrator **必须验证** 再转 loop/iteration：
 
-| 验证项                                    | 方法                                                                                 | 失败处理           |
-| ----------------------------------------- | ------------------------------------------------------------------------------------ | ------------------ |
-| Atom status 已全部更新                    | `atom-plan.json` → 该 agent 所有 atoms 的 `status ≠ pending`                         | 要求补全           |
-| actualOutput 非空且文件存在               | `atoms[].actualOutput` 对应文件在磁盘上存在                                          | 要求补全           |
-| Skill Context 已填写                      | `atom-plan.md` 对应区域不含 `"(Pending"`                                              | 要求回填           |
-| Skill Preflight 已完成                    | TA: `ta-log.md` § Skill Preflight; Developer: `developer-log.md` § Skill Preflight   | 拒绝 STOP，重新入 |
-| Plan section 已完成                       | `ui_pass`: § UI Pass Plan; `gameplay_pass`: § Gameplay Pass Plan                    | 拒绝 STOP，重新入 |
-| mediaGroups 处置已记录（Designer/TA）     | `ta-log.md` § mediaGroups Reuse 或 `designer-log` 有处置记录                         | 要求补充           |
+| 验证项 | 方法 | 失败处理 |
+| --- | --- | --- |
+| 当前 loop 所需交付包完整 | 检查 `next_orchestrator_action` 依赖的核心文件/状态已存在 | 要求补全 |
+| 必要日志证据存在 | intake / preflight / review / reusable-media 证据可追踪 | 要求补全 |
+| 状态字段自洽 | `devStatus: ready` 时 `devUrl` 已存在、`devBlockers` 无未解释阻塞 | 拒绝转 loop |
+| Ring DoD（verify 后） | `npm run ring:gate -- --iteration N` exit 0 | 路由回 owning agent |
 
 ## Before every decision
 
-1. Read `docs/project-state.md` → parse **`## Agent handoff`** YAML + Gates table + **Production Pipeline** waves.
-2. If `gate_pending` non-null and `waiting_for: user_gate` → **Gate only** — do **not** invoke sub-agents.
-3. If `subagent_stop: true` and `waiting_for: orchestrator` → execute **only** `next_orchestrator_action`.
-4. Follow `CLAUDE.md` Orchestration Protocol and `docs/team/collaboration.md` § Gate Protocol, § Agent Handoff.
-5. Before invoke: reset handoff (`subagent_stop: false`, `waiting_for: none`, `subagent: <target>`).
+1. Run `npm run workflow:doctor`. New projects from `playcraft create` are already initialized.
+2. If doctor reports missing workflow files, run `npm run ensure:project -- --no-install`, then run doctor again.
+3. If doctor still reports `BLOCKED`, fix workflow state before invoking any sub-agent.
+4. Run `npm run state:get` → read **handoff** + **`dispatchPacket` / `dispatchMode` / `sliceState`** + Ring DoD + Production Pipeline waves (do not open the generated md).
+5. If `dispatchMode: true` → invoke **only** per `recommendedNextAction` / `dispatchPacket`; do not re-dispatch by ring loop name.
+6. If `waiting_for: user_gate` and `subagent_stop: true` and `ringGateCanAskUser: yes` → **Ring Gate only** — do **not** invoke sub-agents.
+7. If `subagent_stop: true` and `waiting_for: orchestrator` → execute **only** `next_orchestrator_action` (includes `npm run ring:gate` after Reviewer verify STOP when no active slice).
+8. Follow `CLAUDE.md` Orchestration Protocol and `docs/team/collaboration.md` § Ring Gate Protocol, § Agent Handoff.
+9. Before invoke: reset handoff (`subagent_stop: false`, `waiting_for: none`, `subagent: <target>`).
+
+## Ring Gate (only you ask the user)
 
-## Gates (only you ask the user)
+One Ring Gate per iteration replaces the old six waterfall gates.
 
-| Gate | When | Action |
-| ---- | ---- | ------ |
-| #1 | handoff `gate_pending: "1"` after Reviewer `design_check` pass | `AskUserQuestion` → pass → `stage: style_exploration` → `@designer` |
-| #2a | `gate_pending: "2a"` | `AskUserQuestion` → `selectedMcOption` → resume `@designer` (no Reviewer pre-check) |
-| #2b | `gate_pending: "2b"` after Reviewer `design_check` pass | Confirm MC+ASR → `stage: production` → invoke `@designer` Ph.2 **only** |
-| #3 | Reviewer `load_check` pass, `devStatus: ready` | Show **devUrl** via `AskUserQuestion` — user never runs `npm run dev` |
+| When | Preconditions | Action |
+| ---- | ------------- | ------ |
+| Ring N Gate | ring 1: Developer STOP + self-gate scripts pass + `ring:gate` pass; ring 2+: Reviewer verify STOP + `devStatus: ready` + `ring:gate` pass | Show **devUrl with `?debug=1`** via `AskUserQuestion` (debug=1 reveals the one-click clear button) — user never runs `npm run dev` |
+| Ring N pass | User accepts | Archive ring in `archivedRings`, `iteration+1` (or `done` after ring 4), `loop: clarify`, `ringGate: pending` |
+| Ring N fail (ring:gate) | Script exit 2 | Route to `ringGateRouteTo` agent — do **not** ask user |
 
-Sub-agents **must not** use `AskUserQuestion` or set mainline `stage`. See `docs/team/agent-conduct.md`.
+Sub-agents **must not** use `AskUserQuestion` or advance `iteration` / `loop`. See `docs/team/agent-conduct.md`.
 
 ## Workflow STOP hooks (Claude Code + Cursor)
 
-After **Technical Artist** or **Developer** subagent STOP, `.claude/hooks/validate-workflow-stop.mjs` runs automatically:
+After **Artist**, **Technical Artist**, **Developer**, **Reviewer**, or **Game Designer** subagent STOP, `.claude/hooks/validate-workflow-stop.mjs` runs automatically:
 
 - **Claude Code**: `.claude/settings.json` → `SubagentStop`
 - **Cursor**: `.cursor/hooks.json` → `subagentStop`
 
-If intake validation fails, the subagent **cannot stop** until `logs/ta-log.md` or `logs/developer-log.md` § **Upstream Intake** + correct Plan section is complete. Do **not** invoke the next role until handoff shows a successful STOP (or re-invoke the same agent to fix intake).
+If hook validation fails, the subagent **cannot stop** until required log evidence exists. Do **not** invoke the next role until handoff shows a successful STOP.
 
-**Serial spawn after Gate #2b:** `@designer` → (Wave 1 done) `@technical-artist` → (Wave 2 done) `stage: ui_pass` + `@developer`. **Never** spawn `@developer` during `production`.
+**Ring 4 serial spawn:** `@artist` Wave 1 → `@technical-artist` Wave 2 → `@developer` integration → `@reviewer ui_diff`. Never spawn TA before Artist Wave 1 `done`.
 
-## Stage sync on handoff
+## Iteration sync on handoff
 
-When executing `next_orchestrator_action`, **also** update `stage` / gates (sub-agents never do this):
+When executing `next_orchestrator_action`, **also** update `iteration` / `loop` / `ringGate` / `ringDoD`:
 
 | Action substring | Must write |
-| ---------------- | ---------- |
-| `Invoke @reviewer design_check Gate #1` | Stay `pm`; Reviewer audit only |
-| `Run Gate #1` | After pass: `stage: style_exploration`, `gates.#1 = passed` |
-| `Run Gate #2a` | `gates.#2a = passed`, set `selectedMcOption`, resume `@designer` |
-| `Invoke @reviewer design_check Gate #2b` | Stay `style_exploration`; Reviewer audit only |
-| `Run Gate #2b` | `stage: production`, `gates.#2b = passed`, invoke `@designer` Ph.2 only |
-| `Invoke @technical-artist` | Wave 1 `done` → invoke TA (stay `production`) |
-| `Set stage=ui_pass` / invoke `@developer` | Wave 2 `done` → `stage: ui_pass` |
-| `Invoke @reviewer ui_diff` | `stage: ui_review` |
-| `Set stage=ui_rework` | `stage: ui_rework` + invoke routed agents |
-| `Set stage=gameplay_pass` | UI convergence done → `stage: gameplay_pass` |
-| `Invoke @reviewer load_check` | Before Gate #3 |
-| `Run Gate #3` | `gates.#3 = pending` → accept → `stage: done` |
-
-## Handoff × stage matrix
-
-| stage | gate_pending | Typical `next_orchestrator_action` |
-| ----- | ------------ | ------------------------------------ |
-| `pm` | `"1"` | Invoke `@reviewer design_check Gate #1` → Run Gate #1 |
-| `style_exploration` | `"2a"` | Run Gate #2a |
-| `style_exploration` | `"2b"` | Invoke `@reviewer design_check Gate #2b` → Run Gate #2b → `stage: production` → `@designer` Ph.2 |
-| `production` | null, Wave 1 pending | `@designer` Ph.2 |
-| `production` | null, Wave 1 done | `Invoke @technical-artist` |
-| `production` | null, Wave 2 done | `Set stage=ui_pass, invoke @developer` |
-| `ui_pass` | null, `devStatus: ui_ready` | Invoke `@reviewer ui_diff` |
-| `ui_pass` | null, `blocked_upstream` | Re-invoke per `devBlockers.routeTo` → `@developer` |
-| `ui_review` | — (fail) | Set `stage: ui_rework`, invoke routed agents |
-| `ui_rework` | null | Fixes → `@developer` → `@reviewer ui_diff` |
-| `ui_review` | — (pass or 5 rounds) | Set `stage: gameplay_pass, invoke @developer` |
-| `gameplay_pass` | null, `devStatus: ready` | Invoke `@reviewer load_check` |
-| `gameplay_pass` | load_check fail | Re-invoke `@developer` → `@reviewer load_check` |
-| `gameplay_pass` | load_check pass | Gate #3 devUrl |
-
-## Stage shortcuts
-
-- Gate #2b → `@designer` only; Wave 1 done → `@technical-artist`; Wave 2 done → `ui_pass` + `@developer`
-- UI fail → **you** set `stage: ui_rework` (Reviewer does not)
-- `uiReworkRound` max 5 — then proceed to `gameplay_pass` or escalate to user
-- `done` = user accepts devUrl; **not** `playcraft build`
+| ---- | ---- |
+| `Invoke @game-designer` (clarify) | `loop: clarify`, keep `iteration` |
+| `Invoke @developer` (build) | `loop: build`, keep `iteration` |
+| `Invoke @reviewer` (verify) | `loop: verify` |
+| `npm run ring:gate` | Stay `loop: verify`; update `ringDoD`; if pass → `waiting_for: user_gate`, `next_orchestrator_action: Run Ring Gate AskUserQuestion` |
+| `Run Ring Gate AskUserQuestion` | After user pass: archive ring, `iteration+1`, `loop: clarify`, `ringGate: pending` |
+| Ring 4 Gate pass | Project complete — all rings archived, user accepted devUrl |
+
+## Handoff × iteration × loop matrix
+
+> **Superseded when `dispatchMode: true`:** use `dispatchPacket` + `recommendedNextAction` instead of this table.
+
+| iteration | loop | Typical `next_orchestrator_action` |
+| --------- | ---- | ---------------------------------- |
+| 1 | clarify | Invoke `@game-designer` — engine root + core loop spec |
+| 1 | build | Invoke `@developer` — engine boot + placeholder core gameplay |
+| 1 | verify | Developer self-gate → `npm run ring:gate -- --iteration 1` → Ring Gate (no `@reviewer`) |
+| 2 | clarify | `@game-designer` — periphery atoms (HUD / flow) |
+| 2 | build | `@developer` — enrich periphery |
+| 2 | verify | `@reviewer` → `ring:gate --iteration 2` → Ring Gate |
+| 3 | clarify/build/verify | Add hook/CTA + `@artist` style direction |
+| 4 | build | `@artist` Wave 1 → `@technical-artist` Wave 2 → `@developer` integration |
+| 4 | verify | `@reviewer ui_diff` → `ring:gate --iteration 4` → Ring Gate → done |
+
+## Iteration shortcuts
+
+- Ring 1 clarify needs only `design-brief` + `DESIGN.md` + growing `atom-tree.json` — not layout-spec / implementation-plan
+- Asset Contract (`assetMapping`) locks **only after ring 4** (`assetMappingLocked: true`)
+- UI fail during ring 4 verify → invoke routed agents → `@reviewer ui_diff` again (`uiReworkRound` max 5)
+- Optional optimization: `@reviewer playable_validate` before final ring 4 Ring Gate
+- `done` = user accepts devUrl at ring 4 Ring Gate; **not** `playcraft build`

package/project-template/.cursor/rules/playcraft-subagent-boundary.mdc

@@ -6,13 +6,24 @@ alwaysApply: false
 
 # Sub-Agent Boundary
 
-When editing project outputs as a **sub-agent** (PM / Designer / TA / Developer / Reviewer):
+When editing project outputs as a **sub-agent** (Game Designer / Artist / TA / Developer / Reviewer):
 
-- **Do not** `AskUserQuestion` or ask the user to choose Gate options.
-- On gate-ready work: update `## Agent handoff` YAML + `gates.#*` = `pending` + Progress Checkpoint → **STOP** (see `## Runtime` in your agent file).
+## Slice dispatch (dispatchPacket is authority)
+
+When orchestrator passes a **dispatchPacket** (see your agent §0):
+
+- Execute **only** `role + doWhat + flow + sliceId` — do not infer Ring / Gate / Loop from `iteration` / `loop` or read full pipeline docs to guess work.
+- Do **not** self-identify "Ring N build/verify" or advance workflow cursors yourself.
+- On STOP: run your slice verifier + `slice:set`; STOP hook validates **slice state**, not ring ceremony documents.
+
+When **no** active slice: follow legacy ring loop refs from orchestrator assignment.
+
+- **Do not** `AskUserQuestion` for Ring Gate choices, Ring Gate confirmations, or final approvals.
+- **Exception**: `Game Designer` may use `AskUserQuestion` during `loop: clarify` for gameplay brainstorm and clarification.
+- On verify-loop completion: update `## Agent handoff` YAML (`ringGate: pending`, `waiting_for: orchestrator`, `next_orchestrator_action` with `npm run ring:gate`) + Progress Checkpoint → **STOP** (see `## Runtime` in your agent file).
 - If `subagent_stop: true` for your role → do not duplicate work; wait for orchestrator.
 - Read `docs/team/agent-conduct.md` and your `.claude/agents/<role>.md` § Runtime + § Agent Conduct.
-- **Do not** change mainline `stage` — use `next_orchestrator_action` in handoff.
+- **Do not** change `iteration` or `loop` — use `next_orchestrator_action` in handoff.
 - R/W matrix: `docs/team/collaboration.md`.
 
-Designer: read `selectedMcOption` before ASR (UI + element state sheets). TA: only after Production Pipeline Wave 1 `done`. Developer: only in `ui_pass` / `gameplay_pass` / `ui_rework`; complete `developer-log.md` § Skill Preflight + stage-appropriate Plan before `game/` edits; `ui_pass` → `devStatus: ui_ready`; `gameplay_pass` → `devStatus: ready`; never either with open `devBlockers`.
+Artist: ring 3+ produces ASR + style direction; read `selectedMcOption` when set. TA: ring 4 build only, after Production Pipeline Wave 1 `done`. Developer: every ring's `build` loop; ring 4 UI rework for `ui_diff` fixes; complete `developer-log.md` § Skill Preflight before `game/` edits; ring 1 assumes orchestrator already ran `init-template` + `verify:contract`; `devStatus: ready` when done; never with open `devBlockers`.

package/project-template/CHANGELOG.md

@@ -0,0 +1,105 @@
+# PlayCraft Project Template Changelog
+
+This file tracks the playable-ad project template version. It is separate from `docs/team/workflow-changelog.md`, which tracks only workflow spec versions.
+
+## Unreleased
+
+### Changed (Ring 1 workflow speed — option C)
+
+- **Engine-neutral base dependencies** — base `project-template/package.json` no longer carries a default Phaser dependency; engine packs inject `phaser` or `three` during `init-template`.
+- **Three.js engine pack lifecycle** — `startGame()` now returns a harness-compatible handle with `destroy()`, cancels its render loop, disposes the renderer, removes the canvas, and clears `window.__playable` on resize/restart. The pack also injects `@types/three` for TypeScript projects.
+- **`verify:firstwin`** — headless script replaces Reviewer manual playwright for ring 1 `firstLevelWin` DoD; `firstLevelWin` moved from `REVIEW_VERIFIERS` to `SCRIPT_VERIFIERS` and now reports phase path / elapsed time / final state.
+- **`verify:lifecycle`** — new lightweight Ring 1 gate requires `HOOK → autoPlay → ENDCARD` without MP4 (MPEG-4 Part 14，数字多媒体容器格式) transcoding.
+- **Ring 1 DoD slimmed but hardened** — `oneClickEndcard` (`record:mp4`) deferred to ring 2; ring 1 = `contract` + `lifecycle` + `firstLevelWin`.
+- **Ring 1 verify path** — Developer self-gates with `verify:contract` + `verify:lifecycle` + `verify:firstwin` then routes orchestrator to `ring:gate` (no `@reviewer` invoke on ring 1).
+- **`npm run typecheck`** added; Golden Rule forbids `npx tsc`.
+- **`record-playable.mjs`** — fixed Playwright multi-arg `waitForFunction` / `evaluate` calls (L455, L565).
+- **Reviewer Check C** — batch via single `playwright-cli run-code` instead of atomic CLI steps.
+- **Developer ring 1** — module-split guidance (≤350 lines/file); slim intake table in `developer-phase1-flow.md`.
+
+## 0.3.2-alpha.0 - 2026-06-15
+
+### Fixed
+
+- **`init-template` no longer blindly deletes `game/`** — refuses overwrite when `game/` contains user implementation unless `--force`, or the tree is empty / scaffold-pending / still marked by `docs/scaffold-manifest.md` from a prior init-template apply.
+- **`playcraft create` is engine-neutral** — base template ships placeholder `game/` (`.playcraft-scaffold-pending`) without `.playcraft-engine`, so `init-template --from-atom-tree` works for both phaser and threejs without `--force`.
+
+## 0.3.1-alpha.0 - 2026-06-15
+
+### Added
+
+- **Engine-neutral scaffold**: `playcraft remix init-template` (`--engine`, `--from-atom-tree`, `--bake`, `--all-engines`) composes `project-template` ⊕ `engine-packs/{phaser,threejs}` into `game/`, `.playcraft-engine`, and `docs/scaffold-manifest.md`.
+- Three.js engine-pack minimal stub with the same `window.__playable` contract as Phaser.
+- `docs/team/harness-legacy-deprecation.md` — timeline for retiring legacy `MainScene._onDebugAutoPlay()` harness path (target 2026-Q3).
+
+### Changed
+
+- **Ring 1 agent chain** documented across `CLAUDE.md`, `core-model.md`, `collaboration.md`, orchestrator rules, and role cards: `init-atom-tree` → `init-template` → `verify:contract` → Developer build (init-atom-tree no longer silently overwrites `game/`).
+- `workflow-doctor` blocks when `.playcraft-engine` disagrees with `meta.engineDecision.adapter`, or when ring 1 `loop: build` starts without the engine marker.
+- Harness skills (`playable-record`, `playable-debug`, `playcraft-playable-optimization`) updated to **`window.__playable`** as pass standard; legacy scene hooks warn only.
+- `verify:contract` `evaluateContract()` returns legacy warnings when only Phaser scene hooks are present.
+
+### Unreleased (prior batch, still in flight)
+
+### Changed
+
+- **BREAKING**: Replaced waterfall `convergence-v1` workflow with **`growth-rings-v1`** — four growth rings climbing the atom-tree from engine root upward, each with inner loops `clarify → build → verify → Ring Gate`.
+- Replaced `stage` + six gates (`#1`, `#2a`, `#exec`, `#dev`, `#2b`, `#3`) with `iteration` (1..4) + `loop` + `ringGate` + `ringDoD` + `archivedRings` in `## Agent handoff` YAML.
+- Rewrote `gate-runner.mjs` as objective ring-gate runner (`npm run ring:gate -- --iteration N`) — spawns `verify:contract`, `record:mp4`, `verify:ui`, etc.
+- Rewrote `workflow-doctor.mjs` for iteration/loop parsing + non-regression invariant.
+- Updated `validate-workflow-stop.mjs` for iteration-aware required docs (ring 1 minimal: design-brief + DESIGN only).
+- `ensure:project` no longer scaffolds pre-development design docs at bootstrap (layout-spec, atom-tree, etc. created on demand in rings 2+).
+- Bumped `playcraftTemplateVersion` to `0.3.0-alpha.0`.
+
+- Aligned `collaboration.md`, orchestrator/subagent cursor rules, role cards, and `pipeline-overview.md` to growth-rings (removed waterfall stage/gate dead references and fixed anchor links).
+- `validate-workflow-stop.mjs` `validatePlan` now keys off `loop` (`build`) instead of legacy `stage` (`development`).
+- Added objective ring 4 verifiers: `verify:visual` (histogram score vs ASR reference) and `verify:atom-conformance` (atom-tree + assetMapping on-disk).
+- `workflow-doctor.mjs` supports `--strict` / `--enforce` (promotes warnings to errors for CI) and `strict: 'stop'` (illegal transitions only — used by `validate-workflow-stop` hook).
+
+### Added
+
+- `skills/_shared/scripts/ring-config.mjs` — shared ring DoD configuration for gate-runner and workflow-doctor.
+- `ring:gate` npm script.
+- `## Ring DoD Fields` section in `review-report.template.md`.
+- Made `game/config/game-config.ts` the single source of truth for layout/runtime config. `verify:ui` now loads the TypeScript config directly via esbuild (legacy `.js` still supported), so verification can no longer pass against stale, drifted config values. Removed the separate `game-config.js` stub.
+- Extended `globFiles` in the verify-ui toolkit to support `**/*.ts` / `**/*.tsx` glob patterns (previously only `**/*.js`), so layout antipattern scans actually cover TypeScript sources.
+- Made the `## Agent handoff` YAML block in `templates/project-state.template.md` the single machine-readable source of truth for workflow state.
+
+### Added
+
+- Added `verify:env`, an environment pre-flight (`skills/_shared/scripts/verify-env.mjs`): checks Node >= 20, `python3` (required for `verify:ui`), and Playwright's Chromium (optional, for `record:mp4`). Exits non-zero when a required tool is missing so the toolchain fails loudly. `ensure:project` now runs the env pre-flight and surfaces a missing `python3` as a `BLOCKING:` warning instead of letting it fail silently downstream. Declared `engines.node >= 20` in `package.json`.
+- Added `skills:check` (`skills/_shared/scripts/skills-check.mjs`): governs the `.claude/skills` platform-skill static copies that shadow `@playcraft/skills` (image/audio/sprite generation), flagging content drift so a deliberate fork does not silently rot. Advisory by default, `--strict` exits non-zero on drift. Documented `sync-template-skills.mjs` in `skills/README.md` as the single authoritative sync source for the local `skills/` set.
+- Made `ensure-project.mjs` `standardScripts` the single source of truth for managed npm scripts and added a consistency test asserting `package.json` matches it (prevents dual-write drift). Guarded `ensure-project.mjs`'s top-level `main()` behind an `isMain` check so it can be imported by tests without self-executing.
+- Added `harness:smoke`, the harness's own offline-first regression self-test: checks the runtime contract and single-source game-config load, with an opt-in `--full` that also runs the static `verify:ui` suite. Wired into `package.json` and `ensure:project` standard scripts.
+- Added `context:budget` (`skills/_shared/scripts/context-budget.mjs`): measures each agent role's always-loaded base context (L1 card + shared contract docs) in estimated tokens and audits the on-demand refs/skills pool, warning on per-role and per-file budget overruns so the layered "card = ownership, refs on demand" design keeps paying off. Honors optional `tokenCost:` / `readWhen:` frontmatter overrides. Wired into `package.json` and `ensure:project` standard scripts.
+- Added an explicit, typed Playable ⇄ Harness runtime contract (`game/runtime-contract.ts`): `registerPlayable`, `bindPlayableScene`, and an in-dev `assertPlayableSceneContract`. The stub now wires its recorder/debug hooks through it instead of loose `(this as any)` assignments.
+- Updated the runtime contract boundary: new projects expose recorder/debug hooks through `window.__playable`; `window.__game` remains only as a legacy Phaser engine handle. This prevents harness methods from shadowing Phaser internals such as `Game.start()`.
+- Added `verify_runtime_contract.js` (comment-aware, identifier-boundary static scan) to the verify-ui layout suite; it fails fast when `game/` drops a hook the recording/debug harness depends on, instead of letting `record:mp4` time out.
+- Added `verify:contract`, the live (dynamic) half of the runtime-contract check (`skills/playable-record/scripts/verify-contract.mjs`): it boots the game in headless Chromium and asserts within seconds that `window.__playable.autoPlay()`, `window.__playable.getState()`, and the `ENDCARD` phase are wired at runtime, with legacy `window.__game` scene hooks still supported — turning a 30s silent recorder timeout into a clear, fast failure. The validation rule (`evaluateContract`) is pure and unit-tested, and is reused by `record:mp4` to assert the contract on the already-loaded page before capture (no extra browser launch). Also surfaced as `harness:smoke --live`.
+- Added a feature-detected runtime-contract gate to the Developer `SubagentStop` validator: a Developer cannot STOP while the harness contract is broken (skipped silently when the harness scanner is absent).
+- Added `workflow:doctor`, a read-only orchestration consistency check for stage, Gate, and handoff state.
+- Wired `playcraft create` to run `ensure-project --no-install` before initial Git commit so new projects start with workflow docs and logs initialized.
+- Wired `workflow:doctor` into orchestrator startup instructions for Claude Code and Cursor.
+- Added CLI tests for `workflow:doctor` initial-state, invalid-stage, and missing-state diagnostics.
+- Clarified that `playcraft create` is the canonical bootstrap path; `ensure:project` remains an idempotent repair path for legacy or incomplete projects.
+
+## 0.2.0-alpha.0 - 2026-06-15
+
+### Added
+
+- Added `playcraftTemplateVersion` in `package.json` as the machine-readable template version.
+- Added this root `CHANGELOG.md` as the human-readable template release history.
+- Added a template version row to `templates/project-state.template.md` so generated projects can record which project-template version they started from.
+- Added first-run workflow bootstrap in `ensure:project`: missing `docs/` and `logs/` workflow files are created from templates without overwriting agent work.
+- Added clean JSON (JavaScript Object Notation, JavaScript 对象表示法) mode for `ensure:project --json` by silencing nested bootstrap output.
+- Added template copy filtering for runtime artifacts such as `node_modules`, `recordings`, `validate`, `playground`, generated profiles, and lockfiles.
+- Expanded SubagentStop validation coverage to Artist, Developer Lead, Developer, and Technical Artist.
+- Updated atom-tree validation to accept current schemaVersion 3 string-array atoms while keeping schemaVersion 1 compatibility.
+
+## 0.1.0 - 2026-06-12
+
+### Baseline
+
+- Initial Vite + Phaser playable template.
+- Included Claude Code agent-team instructions, role cards, hooks, workflow docs, and local playable skills.
+- Included validation, recording, playground, art import, atlas, and frame tooling npm (Node Package Manager, Node 包管理器) scripts.