@playcraft/cli 0.0.44 → 0.0.46

package/project-templates/threejs/.claude/snapshot.mjs

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+/**
+ * snapshot.mjs — Archive current project state + all AI sessions into a zip
+ *
+ * Usage:
+ *   node snapshot.mjs                              # snapshot cwd project
+ *   node snapshot.mjs <project-path>              # snapshot a specific project (absolute or relative)
+ *   node snapshot.mjs --project <path>            # same as above, explicit flag
+ *   node snapshot.mjs --out <dir>                 # custom output directory (default: where you run the command)
+ *   node snapshot.mjs --name <label>              # custom label appended to zip name
+ *
+ * What gets archived:
+ *   project/   — all project files (excludes node_modules, dist, .git, ta-workspace/logs, ta-workspace/tmp)
+ *   sessions/  — all JSONL session files (main + subagents) from all three stores
+ *               (Claude Code / Claude Internal / CodeBuddy) matching the project path
+ *
+ * Output: {projectName}_{label_}YYYYMMDD_HHmmss.zip  in --out dir
+ */
+
+import { execSync, spawnSync } from 'child_process';
+import { existsSync, readdirSync, statSync, lstatSync, realpathSync, mkdirSync, writeFileSync, rmSync, cpSync } from 'fs';
+import { join, basename, resolve } from 'path';
+import { homedir, tmpdir } from 'os';
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const opts = { project: null, out: null, name: null };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--project' && args[i + 1]) opts.project = args[++i];
+    else if (args[i] === '--out' && args[i + 1]) opts.out = args[++i];
+    else if (args[i] === '--name' && args[i + 1]) opts.name = args[++i];
+    // first positional arg (not a flag) is treated as project path
+    else if (!args[i].startsWith('--') && !opts.project) opts.project = args[i];
+  }
+  return opts;
+}
+
+function timestamp() {
+  const d = new Date();
+  const pad = n => String(n).padStart(2, '0');
+  return `${pad(d.getMonth() + 1)}${pad(d.getDate())}${pad(d.getHours())}${pad(d.getMinutes())}`;
+}
+
+/** Copy a directory tree, skipping excluded patterns.
+ *  Symlinks are followed (resolved to real path) so the archive contains actual content. */
+function copyDir(src, dest, excludes = []) {
+  if (!existsSync(src)) return;
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    if (excludes.some(ex => entry === ex || entry.startsWith(ex))) continue;
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    let stat;
+    try {
+      stat = lstatSync(srcPath);
+    } catch {
+      continue; // can't stat, skip
+    }
+    if (stat.isSymbolicLink()) {
+      // Resolve the symlink to its real target and copy that
+      let realSrc;
+      try {
+        realSrc = realpathSync(srcPath);
+      } catch {
+        console.warn(`   ⚠  Skipping dangling symlink: ${srcPath}`);
+        continue;
+      }
+      let realStat;
+      try {
+        realStat = statSync(realSrc);
+      } catch {
+        console.warn(`   ⚠  Skipping unresolvable symlink: ${srcPath} → ${realSrc}`);
+        continue;
+      }
+      if (realStat.isDirectory()) {
+        copyDir(realSrc, destPath, excludes);
+      } else {
+        cpSync(realSrc, destPath);
+      }
+    } else if (stat.isDirectory()) {
+      copyDir(srcPath, destPath, excludes);
+    } else {
+      cpSync(srcPath, destPath);
+    }
+  }
+}
+
+/** Find all session files for a project across all three stores */
+function findSessions(projectCwd) {
+  const home = homedir();
+  const stores = [
+    { name: 'claude-code',     path: join(home, '.claude', 'projects') },
+    { name: 'claude-internal', path: join(home, '.claude-internal', 'projects') },
+    { name: 'codebuddy',       path: join(home, '.codebuddy', 'projects') },
+  ];
+
+  // Convert project path to the slug format used by Claude (replace path separators with --)
+  // e.g. D:\project\foo  →  D--project-foo  (Claude Code style)
+  const normalizedCwd = resolve(projectCwd).replace(/\\/g, '/');
+  // Build multiple candidate slugs to match different encoding styles
+  const slugVariants = [
+    normalizedCwd.replace(/[:/]/g, '-').replace(/\//g, '-'),   // D--project-foo
+    normalizedCwd.replace(/\\/g, '-').replace(/:/g, '-'),
+    // Also try just the last two path segments as a loose keyword
+  ];
+  const projectName = basename(normalizedCwd);
+
+  const found = [];
+
+  for (const store of stores) {
+    if (!existsSync(store.path)) continue;
+    let projects;
+    try { projects = readdirSync(store.path); } catch { continue; }
+
+    for (const proj of projects) {
+      // Match by: slug contains project name, or slug loosely matches cwd
+      const projLower = proj.toLowerCase();
+      const matches =
+        projLower.includes(projectName.toLowerCase()) ||
+        slugVariants.some(s => projLower.includes(s.toLowerCase().slice(-30)));
+
+      if (!matches) continue;
+
+      const projPath = join(store.path, proj);
+      let stat;
+      try { stat = statSync(projPath); } catch { continue; }
+      if (!stat.isDirectory()) continue;
+
+      // Collect all session JSONL files
+      let files;
+      try { files = readdirSync(projPath).filter(f => f.endsWith('.jsonl')); } catch { continue; }
+
+      for (const f of files) {
+        const sessionId = f.replace('.jsonl', '');
+        const sessionFile = join(projPath, f);
+        const subagentsDir = join(projPath, sessionId, 'subagents');
+        found.push({
+          store: store.name,
+          project: proj,
+          sessionId,
+          sessionFile,
+          subagentsDir: existsSync(subagentsDir) ? subagentsDir : null,
+        });
+      }
+    }
+  }
+
+  return found;
+}
+
+/** Create zip using PowerShell on Windows, zip command on Unix */
+function createZip(sourceDir, zipPath) {
+  const isWin = process.platform === 'win32';
+  if (isWin) {
+    const ps = `Compress-Archive -Path "${sourceDir}\\*" -DestinationPath "${zipPath}" -Force`;
+    const result = spawnSync('powershell', ['-NoProfile', '-Command', ps], { encoding: 'utf8' });
+    if (result.status !== 0) throw new Error(`PowerShell zip failed:\n${result.stderr}`);
+  } else {
+    const result = spawnSync('zip', ['-r', zipPath, '.'], { cwd: sourceDir, encoding: 'utf8' });
+    if (result.status !== 0) throw new Error(`zip failed:\n${result.stderr}`);
+  }
+}
+
+// ── main ─────────────────────────────────────────────────────────────────────
+
+const opts = parseArgs();
+// Project dir: explicit --project / positional arg (resolved relative to cwd), or cwd itself
+const executionCwd = process.cwd();  // where the user ran the command
+const projectDir = opts.project ? resolve(executionCwd, opts.project) : executionCwd;
+const projectName = basename(projectDir);
+const ts = timestamp();
+const label = opts.name ? `_${opts.name}` : '';
+const zipName = `${projectName}${label}_${ts}.zip`;
+// Output dir defaults to where the command was executed (not the project dir)
+const outDir = opts.out ? resolve(executionCwd, opts.out) : executionCwd;
+const zipPath = join(outDir, zipName);
+
+// Staging directory in system temp
+const stageDir = join(tmpdir(), `playcraft-snapshot-${ts}`);
+const projectStage = join(stageDir, 'project');
+const sessionsStage = join(stageDir, 'sessions');
+
+console.log(`\n📦 Snapshotting project: ${projectName}`);
+console.log(`   Source: ${projectDir}`);
+console.log(`   Output: ${zipPath}\n`);
+
+// 1. Copy project files (exclude heavy/generated dirs)
+const PROJECT_EXCLUDES = [
+  'node_modules',
+  'dist',
+  '.git',
+  'ta-workspace',   // logs/tmp inside are gitignored anyway; skip whole dir to keep zip small
+];
+
+console.log('📁 Copying project files...');
+copyDir(projectDir, projectStage, PROJECT_EXCLUDES);
+console.log(`   ✓ Project files copied`);
+
+// 2. Find and copy sessions
+console.log('\n🗂  Finding sessions...');
+const sessions = findSessions(projectDir);
+
+if (sessions.length === 0) {
+  console.log('   ⚠  No sessions found for this project path');
+} else {
+  console.log(`   Found ${sessions.length} session(s):`);
+  for (const s of sessions) {
+    const sessionDest = join(sessionsStage, s.store, s.project, `${s.sessionId}.jsonl`);
+    mkdirSync(join(sessionsStage, s.store, s.project), { recursive: true });
+    cpSync(s.sessionFile, sessionDest);
+
+    let subCount = 0;
+    if (s.subagentsDir) {
+      const subDest = join(sessionsStage, s.store, s.project, s.sessionId, 'subagents');
+      mkdirSync(subDest, { recursive: true });
+      const subFiles = readdirSync(s.subagentsDir).filter(f => f.endsWith('.jsonl'));
+      for (const sf of subFiles) {
+        cpSync(join(s.subagentsDir, sf), join(subDest, sf));
+        subCount++;
+      }
+    }
+
+    const sizeMB = (statSync(s.sessionFile).size / 1024 / 1024).toFixed(2);
+    console.log(`   ✓ [${s.store}] ${s.sessionId.slice(0, 8)}… (${sizeMB}MB, ${subCount} subagents)`);
+  }
+}
+
+// 3. Write a manifest
+const manifest = {
+  createdAt: new Date().toISOString(),
+  projectName,
+  projectPath: projectDir,
+  label: opts.name || null,
+  sessionCount: sessions.length,
+  sessions: sessions.map(s => ({
+    store: s.store,
+    project: s.project,
+    sessionId: s.sessionId,
+    hasSubagents: !!s.subagentsDir,
+  })),
+};
+writeFileSync(join(stageDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+
+// 4. Create zip
+console.log('\n🗜  Creating zip...');
+mkdirSync(outDir, { recursive: true });
+createZip(stageDir, zipPath);
+
+// 5. Cleanup staging
+rmSync(stageDir, { recursive: true, force: true });
+
+const zipSizeMB = (statSync(zipPath).size / 1024 / 1024).toFixed(2);
+console.log(`\n✅ Snapshot complete!`);
+console.log(`   ${zipName}  (${zipSizeMB} MB)`);
+console.log(`   Path: ${zipPath}\n`);

package/project-templates/threejs/.cursor/hooks.json

@@ -0,0 +1,17 @@
+{
+  "version": 1,
+  "hooks": {
+    "subagentStop": [
+      {
+        "command": "node .claude/hooks/validate-atom-tree-selection.mjs",
+        "timeout": 30,
+        "failClosed": false
+      },
+      {
+        "command": "node .claude/hooks/validate-workflow-stop.mjs",
+        "timeout": 30,
+        "failClosed": false
+      }
+    ]
+  }
+}

package/project-templates/threejs/.cursor/rules/playcraft-orchestrator.mdc

@@ -0,0 +1,142 @@
+---
+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 Game Designer, Artist, TA, Developer, and Reviewer in one session when `@agent` invoke is available.
+
+## Slice-axis dispatch (primary when `dispatchPacket` exists)
+
+When `npm run state:get -- --json dispatchPacket currentAction recommendedNextAction dispatchMode` returns **`dispatchPacket` non-null** (`dispatchMode: true`):
+
+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.
+
+When **`dispatchPacket` is null** (`dispatchMode: false`): use the growth-ring handoff matrix below (legacy fallback until slice queue is seeded).
+
+## Growth-ring model (growth-rings-v1)
+
+Four iterations (growth rings), each with inner loops: `clarify → build → verify → Ring Gate`.
+
+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`
+
+## Invoke `@developer`
+
+Developer owns every ring's **`build` loop**. Also re-enters during ring 4 **UI rework** (post-`ui_diff` fixes).
+
+**`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
+2. **关键约束/提醒**：如 `mediaGroups` 中有可复用资产
+3. **上游依赖状态**：哪些 Wave 已完成
+
+**禁止调度时：**
+- 写出详细生产步骤（agent 自己读 refs/ 和 Skills）
+- 越俎代庖选择 prompt/model/工具（agent 按 Skill Preflight 决定）
+- 跳过 agent 自身的 Step 0 流程
+
+## Post-STOP 验证（必须，在阶段转换前）
+
+Sub-agent STOP 返回后，orchestrator **必须验证** 再转 loop/iteration：
+
+| 验证项 | 方法 | 失败处理 |
+| --- | --- | --- |
+| 当前 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. 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)
+
+One Ring Gate per iteration replaces the old six waterfall gates.
+
+| 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 advance `iteration` / `loop`. See `docs/team/agent-conduct.md`.
+
+## Workflow STOP hooks (Claude Code + Cursor)
+
+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 hook validation fails, the subagent **cannot stop** until required log evidence exists. Do **not** invoke the next role until handoff shows a successful STOP.
+
+**Ring 4 serial spawn:** `@artist` Wave 1 → `@technical-artist` Wave 2 → `@developer` integration → `@reviewer ui_diff`. Never spawn TA before Artist Wave 1 `done`.
+
+## Iteration sync on handoff
+
+When executing `next_orchestrator_action`, **also** update `iteration` / `loop` / `ringGate` / `ringDoD`:
+
+| Action substring | Must write |
+| ---- | ---- |
+| `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-templates/threejs/.cursor/rules/playcraft-subagent-boundary.mdc

@@ -0,0 +1,29 @@
+---
+description: PlayCraft sub-agent file boundaries — no user gates, STOP protocol
+globs: .claude/agents/**,docs/**,logs/**,assets/**,game/**
+alwaysApply: false
+---
+
+# Sub-Agent Boundary
+
+When editing project outputs as a **sub-agent** (Game Designer / Artist / TA / Developer / Reviewer):
+
+## 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 `iteration` or `loop` — use `next_orchestrator_action` in handoff.
+- R/W matrix: `docs/team/collaboration.md`.
+
+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-templates/threejs/.playcraft-engine

@@ -0,0 +1 @@
+threejs

package/project-templates/threejs/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.

package/project-templates/threejs/CLAUDE.md

@@ -0,0 +1,84 @@
+# PlayCraft Playable Ads Project
+
+## L0 Quickstart
+
+You are building a playable ad: a self-contained HTML5 mini-game. Daily work is driven by a **slice queue** (`dispatchPacket`); **growth rings** are the outer budget, convergence boundary, and user Ring Gate.
+
+Start every turn with the smallest possible context:
+
+```bash
+npm run workflow:doctor
+npm run state:get
+```
+
+`state:get` tells you the current `iteration`, `loop`, `currentAction`, `next_orchestrator_action`, `contextPacket`, current required files, allowed tasks, forbidden tasks, current verifiers, and next commands. **Use `state:get` as your handoff summary — never open or hand-edit `docs/project-state.md`.** Read `contextPacket` first, then only the files `state:get` lists as required. Pull deeper docs only when the current action names them.
+
+> **State is programmatic.** `docs/project-state.json` is the machine source of truth, including `handoffContext` shared working memory; `docs/project-state.md` is a GENERATED, read-only view re-rendered after every write. **Read state with `npm run state:get`; write state with `npm run state:set` (or `npm run ring:gate` / STOP hooks).** Do not edit the markdown by hand — your edits will be overwritten on the next write, and the tables you need always exist because the renderer emits them.
+
+## Non-Negotiables
+
+- First level must guarantee player success.
+- Runtime must start at `HOOK`.
+- `autoPlay()` must progress from player-reachable actions to `ENDCARD`; do not fake victory by directly setting `ENDCARD`, repainting the whole board into a win, or calling a win screen directly.
+- For Ring 1, do not create internal Task lists (`TaskCreate` / `TaskUpdate` / …). **You are the orchestrator** — dispatch role subagents via `Task` / `@game-designer` / temporary ref-flow atom-selection subagent / `@developer`; do **not** role-play Designer, atom selector, or Developer inline in one session.
+- Use project scripts only: `npm run ...` or repository-provided `playcraft ...`; never use `npx`.
+- Typecheck with `npm run typecheck`.
+- Harness pass standard is `window.__playable`; legacy `window.__game` scene hooks are migration-only.
+- User Ring Gate is orchestrator-only.
+- Follow `state:get` output, not remembered Ring instructions.
+
+## Slice-axis dispatch (primary — orchestrator)
+
+When `npm run state:get -- --json dispatchPacket dispatchMode recommendedNextAction` returns **`dispatchMode: true`**:
+
+1. **Dispatch unit** = `role + doWhat + flow + sliceId` from `dispatchPacket` — not ring loop names.
+2. Invoke subagents with **packet scope only**; never say "Ring 1 build" or ask them to self-identify Ring / Gate / Loop.
+3. After STOP: trust **`sliceState`** + STOP hook (`verify:slice` / `verify:slice-artist` / `verify:slice-ta`, then `slice:set`) — not handoff markdown as authority.
+4. **`ring:gate`** still runs for objective DoD and user Ring Gate; it aggregates slice queue terminal state but does **not** replace per-slice verify on STOP.
+
+When **`dispatchPacket` is null** (`dispatchMode: false`): use the legacy growth-ring path below until Designer seeds `sliceState`.
+
+## Current Workflow
+
+1. Read state with `npm run state:get` (never open the generated `docs/project-state.md`).
+2. If `dispatchMode: true` → follow `recommendedNextAction` / `dispatchPacket`; else follow `next_orchestrator_action`.
+3. Keep work inside the current slice (dispatch mode) or current ring (legacy).
+4. After a sub-agent stops, run verifiers from `state:get` (per-slice verify before ring gate when slices are active).
+5. When `ring:gate` says `canAskUser: yes`, the orchestrator asks the user to accept the dev URL.
+
+## Ring 1 Dispatch Path (legacy growth-rings — orchestrator)
+
+When `state:get` reports `iteration: 1`, **stay orchestrator** — invoke role subagents; do not inline their work.
+
+| `loop`                | Orchestrator does                                                                                                                                                                                                                                                                  |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `clarify`             | **Invoke `@game-designer`** — ring 1 clarify (single concise `docs/DESIGN.md`). Do not write `DESIGN.md` yourself.                                                                                                                                                                 |
+| (after GD STOP)       | **Spawn a temporary ref-flow atom-selection subagent** — create the minimal ring 1 atom-tree package: engine decision, compact gameplay trunk, selected atoms, and ring 1 verifier metadata. Do not make main orchestrator select atoms inline.                                    |
+| (after selector STOP) | Run scaffold gate: `validate-atom-tree-selection` → `init-template --from-atom-tree` → `npm install` → `npm run verify:contract` → `npm run verify:lifecycle`. Set `loop: build`, then **Invoke `@developer`**.                                                                    |
+| `build`               | **Invoke `@developer`** — ring 1 build only the smallest verifiable playable spine (placeholder art, one player-reachable action loop, `window.__playable`). Developer self-gates with `verify:contract` + `verify:lifecycle` + `verify:firstwin` + `verify:placeholders` on STOP. |
+| `verify`              | Run `npm run ring:gate -- --iteration 1` (no `@reviewer` in ring 1).                                                                                                                                                                                                               |
+
+Follow `next_orchestrator_action` from handoff when `subagent_stop: true`. See `docs/team/collaboration.md` § Ring 1 engine scaffold.
+
+## Deeper References
+
+Use these only when the current action needs them:
+
+| Need                                           | Read                                      |
+| ---------------------------------------------- | ----------------------------------------- |
+| Full collaboration and Ring Gate protocol      | `docs/team/collaboration.md`              |
+| Role conduct and MUST/NEVER rules              | `docs/team/agent-conduct.md`              |
+| Runtime model and `window.__playable` boundary | `docs/team/core-model.md`                 |
+| Post-stop verification matrix                  | `docs/team/agent-runtime-matrix.md`       |
+| Atom-tree schema and Skill selection           | `docs/team/atom-tree-format.md`           |
+| Legacy harness migration                       | `docs/team/harness-legacy-deprecation.md` |
+
+## Directory Map
+
+```text
+docs/      project-state, DESIGN, ring-specific specs
+game/      runtime implementation
+logs/      developer/reviewer/artist/TA logs
+assets/    placeholder and production media
+skills/    local verifier, record, art, and workflow scripts
+```