@playcraft/cli 0.0.53 → 0.0.56

package/project-templates/threejs/CLAUDE.md

@@ -1,84 +1,118 @@
-# PlayCraft Playable Ads Project
+# CLAUDE.md
 
-## L0 Quickstart
+This file provides guidance to Claude Code (claude.ai/code) when working in a PlayCraft generated playable-ad project.
 
-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.
+## Project Overview
 
-Start every turn with the smallest possible context:
+This repository is a **PlayCraft playable-ad project**: a mini-game plus the local scripts, docs, and agent tooling used to produce and verify it.
+
+**This file is an entry index, not the task spec.** What to do next — role, scope, required files, verifiers — comes from `npm run state:get` each turn. Product and workflow detail lives under `docs/` and `.cursor/rules/` when state or your current action points you there.
+
+## Start Every Turn
+
+Run the smallest possible context load first:
 
 ```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:get` exposes `iteration`, `loop`, `currentAction`, `next_orchestrator_action`, `contextPacket`, **required files**, allowed/forbidden tasks, active verifiers, and next commands.
 
-> **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.
+**Use `state:get` as your handoff summary.** Read `contextPacket` first, then only the files `state:get` lists as required. Do not open or hand-edit `docs/project-state.md`.
 
-## Non-Negotiables
+## State Files
 
-- 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.
+- `docs/project-state.json` — machine source of truth (`handoffContext`, `sliceState`, workflow cursor).
+- `docs/project-state.md` — generated read-only view; rewritten after every write.
+- Read: `npm run state:get`.
+- Write: `npm run state:set`, `npm run slice:set`, `npm run state:advance-ring`, or `npm run ring:gate`.
 
-## Slice-axis dispatch (primary — orchestrator)
+## Work Model
 
-When `npm run state:get -- --json dispatchPacket dispatchMode recommendedNextAction` returns **`dispatchMode: true`**:
+Two coordination layers:
 
-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.
+| Layer            | Role                                                                                                     |
+| ---------------- | -------------------------------------------------------------------------------------------------------- |
+| **Slice queue**  | Daily dispatch when `dispatchPacket` exists — unit of work = `role + doWhat + flow + sliceId`.           |
+| **Growth rings** | Outer budget, non-regression boundary, objective DoD (Definition of Done, 完成定义), user **Ring Gate**. |
 
-When **`dispatchPacket` is null** (`dispatchMode: false`): use the legacy growth-ring path below until Designer seeds `sliceState`.
+When `dispatchMode: true`, slice dispatch is primary:
 
-## Current Workflow
+```bash
+npm run state:get -- --json dispatchPacket dispatchMode recommendedNextAction
+```
 
-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.
+When `dispatchPacket` is null, follow `next_orchestrator_action` until Designer seeds `sliceState`.
 
-## Ring 1 Dispatch Path (legacy growth-rings — orchestrator)
+**Orchestrator protocol** (per-iteration dispatch, STOP hooks, Ring Gate, handoff matrix): `.cursor/rules/playcraft-orchestrator.mdc` and `docs/team/collaboration.md`. Do not duplicate those rules here.
 
-When `state:get` reports `iteration: 1`, **stay orchestrator** — invoke role subagents; do not inline their work.
+## Non-Negotiables
 
-| `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).                                                                                                                                                                                                               |
+- First level must guarantee player success.
+- Runtime must start at `HOOK`; `autoPlay()` must reach `ENDCARD` through player-reachable actions only.
+- Do not fake victory (direct `ENDCARD`, full-board repaint win, or calling a win screen directly).
+- Harness pass standard is `window.__playable`; legacy `window.__game` hooks are migration-only.
+- Use project scripts only: `npm run ...` or `playcraft ...`; do not use `npx`.
+- Typecheck with `npm run typecheck`.
+- **Ring Gate** is orchestrator-only — sub-agents must not ask the user to accept devUrl.
+- Follow `state:get` output, not remembered workflow instructions.
+- **Orchestrator**: do not create internal Task lists (`TaskCreate` / `TaskUpdate`); invoke role subagents when state directs.
 
-Follow `next_orchestrator_action` from handoff when `subagent_stop: true`. See `docs/team/collaboration.md` § Ring 1 engine scaffold.
+## Current Workflow
 
-## Deeper References
+1. `npm run workflow:doctor` → `npm run state:get`.
+2. Read `contextPacket`, then required files only.
+3. If `dispatchMode: true` → dispatch the current `dispatchPacket`; else follow `next_orchestrator_action`.
+4. After sub-agent STOP → run verifiers from `state:get`.
+5. When objective DoD is due → `npm run ring:gate -- --iteration N`; ask the user only when `ring:gate` reports `canAskUser: yes`.
+
+## Runtime Contract
+
+- Expose `window.__playable` with `autoPlay()` proving a reachable first-win path.
+- Lifecycle: `HOOK` → player actions → `ENDCARD`.
+- Verifier-facing behavior stays engine-neutral; keep asset paths in sync with code.
 
-Use these only when the current action needs them:
+## Common Commands
+
+```bash
+npm run dev
+npm run typecheck
+npm run build
+npm run verify:contract
+npm run verify:lifecycle
+npm run verify:firstwin
+npm run verify:placeholders
+npm run workflow:doctor
+npm run state:get
+npm run state:set
+npm run ring:gate -- --iteration N
+npm run record:mp4
+npm run verify:ui
+```
 
-| 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` |
+Full script list: `package.json` → `scripts`.
 
 ## 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
+docs/       project state, design contracts, team references
+game/       runtime (after engine scaffold)
+logs/       role logs and review reports
+assets/     placeholder and production media
+skills/     verifiers, record, art, workflow scripts
+templates/  source templates for workflow scripts
 ```
+
+## Deeper References
+
+Pull these only when the current action names them:
+
+| Need                                             | Read                                      |
+| ------------------------------------------------ | ----------------------------------------- |
+| Collaboration, per-iteration dispatch, Ring Gate | `docs/team/collaboration.md`              |
+| Role MUST/NEVER rules                            | `docs/team/agent-conduct.md`              |
+| `window.__playable` model                        | `docs/team/core-model.md`                 |
+| Post-STOP verification matrix                    | `docs/team/agent-runtime-matrix.md`       |
+| Atom-tree / Skill selection                      | `docs/team/atom-tree-format.md`           |
+| Legacy harness migration                         | `docs/team/harness-legacy-deprecation.md` |

package/project-templates/threejs/docs/DESIGN.md

@@ -63,3 +63,28 @@
 ## 5. Ring 1 HOOK Entry
 
 {Describe the starting HOOK state that is visible immediately when the game loads. It should be enough for `verify:lifecycle` to observe `HOOK`, then for `autoPlay()` to advance through player-reachable actions to `ENDCARD`.}
+
+---
+
+## 6. Gameplay Fusion
+
+- **Fusion type**: {Single | B1-Passive | B2-Active | C-Sequential | D-Parallel}
+- **Primary mechanic**: {main interaction}
+- **Secondary mechanic** (if fusion): {how it enhances payoff}
+- **Pseudo-fusion decision**: {downgrade reason, risk accepted, or n/a}
+
+---
+
+## 7. Gameplay Seed (Ring 1)
+
+### Player Fantasy
+
+{2–4 sentences: what the player sees in 30s, wants to tap, and why they continue.}
+
+### Decision Moment
+
+{One scene: the single aha or mis-tap moment — blocked feedback, unlock, or combo payoff.}
+
+### First Level Scenario
+
+{Describe opening board state as a **scenario** (not KPI numbers): which paths look free vs blocked, what the first correct tap teaches.}

package/project-templates/threejs/docs/project-state.md

@@ -55,7 +55,7 @@
 
 Each iteration runs inner loops: `clarify` → `build` → `verify` → **Ring Gate** (user acceptance) → next iteration.
 
-<!-- Iteration definitions: see CLAUDE.md § Growth-Ring Model -->
+<!-- Iteration definitions: see docs/team/collaboration.md (growth-rings-v1) -->
 
 ## Ring DoD (current iteration)
 

package/project-templates/threejs/docs/team/collaboration.md

@@ -90,12 +90,22 @@ See [core-model.md § Command Contract](core-model.md#command-contract) and [har
 
 ### Per-ring flow
 
-| Step | Loop    | Agent(s)                                        | STOP → next                                                                                                                                                                                           |
-| ---- | ------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 1    | clarify | `@game-designer` → temporary ref-flow selector  | Orchestrator → ring 1: context packet + compact atom selection → `init-template` + `verify:contract` first → `loop: build` → `@developer`                                                             |
-| 2    | build   | `@developer` (+ Artist/TA per ring)             | Ring 1: Developer self-gate (`verify:contract` + `verify:lifecycle` + `verify:firstwin` + `verify:placeholders`) → `loop: verify` → orchestrator `ring:gate`; ring 2+: → `loop: verify` → `@reviewer` |
-| 3    | verify  | ring 1: orchestrator only; ring 2+: `@reviewer` | Orchestrator → `npm run ring:gate -- --iteration N`                                                                                                                                                   |
-| 4    | —       | **Orchestrator only**                           | If pass → Ring Gate `AskUserQuestion` at devUrl → archive ring → `iteration+1`, `loop: clarify`                                                                                                       |
+| Step | Loop    | Agent(s)                                                                                                                | STOP → next                                                                                                                                                                      |
+| ---- | ------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | clarify | `@game-designer` mechanism lock → `@creative-director` (PGS wrap) → `@game-designer` spec → temporary ref-flow selector | Orchestrator → primaryGameplaySkill → north star → design spec (verbatim §0 + PGS) → compact atom selection → `init-template` + `verify:contract` → `loop: build` → `@developer` |
+
+#### Ring 1 clarify — `@creative-director` outputs (`CREATIVE_DIRECTOR_SPLIT=1`)
+
+| Artifact                   | Required fields                                                                                                                                        | Notes                                                                        |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| `docs/north-star.md`       | **Micro-Story Spine** (Narrative level, Who, Situation, Stakes, Payoff image, Emotional arc) + One-liner + System Dynamic + Why fusion + Rejected vibe | Creative source of truth; default L1/L2; L0 only when user opts out of story |
+| `docs/creative-process.md` | Phase 1 ≥3 candidates (each with Story hook) + Phase 3 Narrative level rationale + Phase 4 Design Intent                                               | L0 opt-out must cite user wording in Phase 3                                 |
+
+Orchestrator spawn brief: translate user mechanism seed → **Creative question** per `creative-director-kickoff-guide.md`. `@game-designer` spec copies §0 One-liner **verbatim** and Micro-Story Spine **field-value match** into `docs/DESIGN.md` §0.
+
+| 2 | build | `@developer` (+ Artist/TA per ring) | Ring 1: Developer self-gate (`verify:contract` + `verify:lifecycle` + `verify:firstwin` + `verify:placeholders`) → `loop: verify` → orchestrator `ring:gate`; ring 2+: → `loop: verify` → `@reviewer` |
+| 3 | verify | ring 1: orchestrator only; ring 2+: `@reviewer` | Orchestrator → `npm run ring:gate -- --iteration N` |
+| 4 | — | **Orchestrator only** | If pass → Ring Gate `AskUserQuestion` at devUrl → archive ring → `iteration+1`, `loop: clarify` |
 
 ### Ring DoD by iteration
 
@@ -312,7 +322,9 @@ Full detail: `.claude/agents/<role>.md` § Goals.
 │
 ├── docs/project-state.json         ⏳ state-store machine truth
 ├── docs/project-state.md           ⏳ generated read-only view
-├── docs/DESIGN.md                  ⏳ Ring 1 clarify（唯一交付物）
+├── docs/DESIGN.md                  ⏳ Ring 1 clarify（Game Designer spec 交付物）
+├── docs/north-star.md              ⏳ Ring 1 clarify（Creative Director 交付物）
+├── docs/creative-process.md        ⏳ Ring 1 clarify（Creative Director 交付物）
 ├── docs/design-brief.md            ⏳ Ring 2+ 过程日志（Ring 1 不创建）
 ├── docs/atom-tree.json             ⏳ 逐环增长
 ├── docs/layout-spec.md             ⏳ Ring 2+ clarify

package/project-templates/threejs/docs/team/workflow-changelog.md

@@ -6,6 +6,20 @@ Template workflow spec versions for `packages/cli/project-template`. New project
 
 **Effective**: project-template default for new playable-ad projects (template `0.3.2-alpha.0`).
 
+### 2026-06-28 — Creative Director v2 Micro-Story
+
+- **Enhancement**: Ring 1 creative discovery now defaults to **Micro-Story Spine** (Narrative level / Who / Situation / Stakes / Payoff image / Emotional arc) in `docs/north-star.md` § Micro-Story Spine; L1/L2 are default, L0 only on explicit user opt-out.
+- **Orchestrator kickoff**: read `creative-director-kickoff-guide.md` and inject **Creative question** (Hook frame / pressure meaning / first payoff) — do not forward mechanism spec verbatim to `@creative-director`.
+- **Methodology disclosure**: `disclosure-config` `1:creative` exposes `referenceReads` (five-axis-framework, design-methodology, creative-north-star-examples); agents read via `npm run state:get` summary.
+- **`verify:design`**: independent `validateStorySpine()` + `STORY_SPINE_MODE` (default `warn`); L0 exempts mechanism-chain heuristic; CD STOP hook requires Micro-Story Spine section.
+
+### 2026-06-25 — Creative Director split (Ring 1 creative isolation)
+
+- **Fix**: North Star v2 alone still produced mechanism-chain §0 when Game Designer optimized validators. Ring 1 clarify now routes `@creative-director` → `@game-designer` spec (default `CREATIVE_DIRECTOR_SPLIT=1`).
+- **Outputs**: `docs/north-star.md` (creative source of truth) + `docs/creative-process.md` before DESIGN / skills / verify.
+- **`disclosure-config`**: new `1:creative` and `1:spec` keys; monolithic `1:clarify` when `CREATIVE_DIRECTOR_SPLIT=0` (harness control arm).
+- **`verify:design`**: mechanism-chain heuristic + north-star ↔ DESIGN §0 verbatim sync when split enabled.
+
 ### 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`.

package/project-templates/threejs/fusion-patterns/catalog.json

@@ -0,0 +1,77 @@
+{
+  "schemaVersion": 2,
+  "patterns": [
+    {
+      "id": "arrow_pick_match_fusion",
+      "intentTags": ["arrow", "elimination", "fusion", "match-3", "消除", "箭头", "融合"],
+      "title": "Arrow slide-out + tray match-3",
+      "mechanics": "Paths slide into a tray; match-3 clears tray slots. Combines path puzzle dependency with elimination payoff.",
+      "playerFantasy": "Tap an arrow path — it slides out. Fill the tray strategically; match-3 clears space before overflow.",
+      "decisionMoment": "Choosing which blocked path to unlock first vs filling the tray for a combo clear.",
+      "skillRef": "arrow_pick_match_rules.aigameplay",
+      "recommendedProfile": "standard",
+      "depthHint": "不要写「箭头+三消」就停；写清：棋盘哪一块先解锁、托盘峰值如何迫使颜色顺序、blocked 误点教什么。",
+      "antiPatternRef": "8×8 but ≤4 paths or all-free opening — no puzzle identity"
+    },
+    {
+      "id": "path_elimination_puzzle",
+      "intentTags": ["arrow", "path", "puzzle", "elimination", "箭头", "路径"],
+      "title": "Pure path elimination puzzle",
+      "mechanics": "Click arrow heads; paths slide out when unobstructed. Order matters — blocked paths teach dependency.",
+      "playerFantasy": "Read arrow directions, find the unlock sequence, clear the board.",
+      "decisionMoment": "First tap on a blocked path — shake/highlight feedback — then finding the correct unlock order.",
+      "skillRef": "path_elimination_rules.aigameplay",
+      "recommendedProfile": "standard",
+      "depthHint": "用折线密度与依赖层数定难度，固定 8×8；至少 2 层解锁波次，禁止开局全部 FREE。",
+      "antiPatternRef": "All paths FREE at start — zero decision"
+    },
+    {
+      "id": "match3_board",
+      "intentTags": ["match-3", "match3", "swap", "三消", "消除"],
+      "title": "Classic match-3 board",
+      "mechanics": "Swap adjacent tiles; match-3 removes; gravity refills.",
+      "playerFantasy": "Swap to create matches; cascades and combos build excitement.",
+      "decisionMoment": "Choosing between an obvious match vs setting up a cascade.",
+      "skillRef": "match3_core.aigameplay",
+      "recommendedProfile": "standard",
+      "depthHint": "若与 path 融合，说明主手势是 swap 还是 tap-path，避免异基底双主手势。",
+      "antiPatternRef": "Auto-clear board with no player swap"
+    },
+    {
+      "id": "board_phase_unlock",
+      "intentTags": ["phase", "unlock", "mask", "分区", "解锁", "board", "fusion"],
+      "title": "Board phase unlock (same-grid mask)",
+      "mechanics": "Same 8×8 board; masked regions unlock after match clears or path milestones. New paths appear in unlocked zones — board changes via mask, not resize.",
+      "playerFantasy": "Clear the first zone to reveal more puzzle — the board grows in complexity without shrinking cells.",
+      "decisionMoment": "Spend a tray clear to unlock the next zone vs hoarding colors for a safer combo.",
+      "skillRef": "arrow_pick_match_rules.aigameplay",
+      "recommendedProfile": "standard",
+      "depthHint": "写清每 phase 解锁条件与新增 path 条数；难度靠追加折线而非缩小棋盘。",
+      "antiPatternRef": "Resize board to 4×4 for difficulty — use path count instead"
+    },
+    {
+      "id": "match3_tray_puzzle_hybrid",
+      "intentTags": ["tray", "match-3", "puzzle", "hybrid", "托盘", "三消", "拼图"],
+      "title": "Tray-only match-3 + board path puzzle",
+      "mechanics": "Primary gesture: path tap on board. Match-3 happens only inside the tray. Board side is pure dependency puzzle — no swap on grid.",
+      "playerFantasy": "Solve the arrow maze; the tray is your pressure valve — match-3 is the relief, not the main puzzle.",
+      "decisionMoment": "Push a risky color into a nearly-full tray hoping the next two paths complete the triple.",
+      "skillRef": "arrow_pick_match_rules.aigameplay",
+      "recommendedProfile": "ring1_min",
+      "depthHint": "声明三消仅在托盘；棋盘侧禁止 swap。写托盘峰值曲线与颜色推出顺序。",
+      "antiPatternRef": "Board swap match-3 + path tap without interaction contract"
+    },
+    {
+      "id": "match3_board_phase",
+      "intentTags": ["match3", "phase", "path", "hybrid", "sequential", "双区"],
+      "title": "Match-3 main + path lock zone (high risk)",
+      "mechanics": "Primary zone: swap match-3. Secondary zone: path puzzle locked until match milestone. C-Sequential — document pseudo-fusion reducer.",
+      "playerFantasy": "Clear tiles to unlock the arrow zone — two systems, one win condition.",
+      "decisionMoment": "Finish the match-3 objective vs peeking at the locked path zone.",
+      "skillRef": "match3_core.aigameplay",
+      "recommendedProfile": "hard",
+      "depthHint": "Ring 2+ only.必须写 pseudo-fusion 与单 reducer，避免双主手势抢输入。",
+      "antiPatternRef": "Two equal primary gestures with no documented interaction contract"
+    }
+  ]
+}

package/project-templates/threejs/package.json

@@ -64,7 +64,9 @@
     "verify:text-overlap": "python3 skills/playable-verify-ui/scripts/verify_text_overlap.py --root=.",
     "verify:vision": "python3 skills/playable-verify-ui/scripts/verify_vision_evidence.py --root=.",
     "verify:asset-code-sync": "node skills/_shared/scripts/verify-asset-code-sync.mjs --root=.",
-    "verify:atom-conformance": "node skills/_shared/scripts/verify-atom-conformance.mjs --project=."
+    "verify:atom-conformance": "node skills/_shared/scripts/verify-atom-conformance.mjs --project=.",
+    "verify:design": "node skills/_shared/scripts/verify-design-consistency.mjs --root=.",
+    "levels:validate": "node skills/_shared/scripts/validate-level-sketch.mjs --root=."
   },
   "engines": {
     "node": ">=20"

package/project-templates/threejs/skills/_shared/scripts/dev-start.mjs

@@ -3,7 +3,7 @@
  * Start (or stop) the persistent preview dev server and record the real devUrl.
  *
  * This removes the LLM from port handling entirely (docs/harness/experiment-lessons.md §9.2):
- * Vite runs with strictPort:false, so when 3000 is taken it auto-increments; this
+ * Vite runs with strictPort:false, so when 5173 is taken it auto-increments; this
  * script parses Vite's actual `Local:` URL from the log, appends `?debug=1`, and
  * writes it back to project-state via the same layer `state:set` uses. The agent
  * never reads or records a port by hand.
@@ -20,11 +20,11 @@ import { openSync, closeSync, existsSync, readFileSync, writeFileSync, rmSync }
 import { spawn } from 'node:child_process';
 import { join, resolve } from 'node:path';
 import { applyHandoffUpdates, resolveProjectStatePath } from './state-handoff.mjs';
-import { parseLocalUrl, waitForHttp } from '../../playable-record/scripts/lib/dev-server.mjs';
+import { parseLocalUrl, waitForHttp, DEFAULT_DEV_URL } from '../../playable-record/scripts/lib/dev-server.mjs';
 
 const PID_FILE = '.playcraft-dev.pid';
 const LOG_FILE = '.playcraft-dev.log';
-const PREFERRED_URL = 'http://127.0.0.1:3000/';
+const PREFERRED_URL = DEFAULT_DEV_URL;
 
 function parseArgs(argv) {
   const opts = { root: process.cwd(), stop: false, timeout: 30000 };

package/project-templates/threejs/skills/_shared/scripts/disclosure-config.mjs

@@ -7,6 +7,11 @@
  * for that surface.
  */
 
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { evaluateSliceQueueForRingGate } from './state-store.mjs';
+import { resolvePrimarySkillId } from './lib/skill-fidelity.mjs';
+
 const COMMON_REQUIRED = ['CLAUDE.md'];
 
 export const FUTURE_RING_FILES = [
@@ -22,51 +27,43 @@ export const FUTURE_RING_FILES = [
 const DISCLOSURE_BY_RING_LOOP = {
   '1:clarify': {
     currentAction:
-      'Orchestrator: invoke @game-designer for Ring 1 clarify — design-brief discovery + DESIGN seed + playcraft skills match compact refs + minimal developer slice queue (not layout/style/CTA/full plan).',
-    requiredFiles: [...COMMON_REQUIRED, 'docs/DESIGN.md'],
-    deferredFiles: FUTURE_RING_FILES.filter((f) => f !== 'docs/design-brief.md'),
+      'Orchestrator: invoke @game-designer with only the user\'s original intent. Do not add design decisions, engine hints, platform constraints, or workflow steps — designer reads its own role card.',
+    requiredFiles: [...COMMON_REQUIRED],
+    deferredFiles: FUTURE_RING_FILES,
     nextRole: 'game-designer',
-    artifactRefs: ['docs/DESIGN.md', 'docs/design-brief.md', 'docs/atom-tree.json', 'sliceState'],
-    requiredContextFields: ['ring.goal', 'lastRole.summary', 'sharedDecisions.coreAction', 'sharedDecisions.semanticPlaceholders'],
+    artifactRefs: [],
+    requiredContextFields: [],
     allowedTasks: [
-      'Invoke @game-designer for ring 1 clarify',
-      'Game Designer: design-brief discovery + DESIGN seed + playcraft skills match + sliceState queue',
-      'Game Designer: run playcraft skills match and write meta.skillsMatch + compact selectedAtoms',
-      'Record fromScratchReason when core mechanic is novel',
-      'Define first-level win strategy and semantic placeholders (Game Designer subagent)',
+      'Invoke @game-designer with user intent only',
     ],
     forbiddenTasks: [
       'Do not write docs/DESIGN.md as orchestrator',
       'Do not implement game/ as orchestrator during clarify',
-      'Do not require layout-spec or full implementation-plan in Ring 1',
-      'Do not build a full atom graph in Ring 1 clarify — compact skillsMatch refs only',
-      'Do not design CTA polish or production assets in Ring 1',
-      'Do not claim skillRefs implement core mechanic without skills read',
-      'Do not run standalone record:mp4 as a Ring 1 blocker',
-      'Do not run verify:ui as Ring 1 blockers',
+      'Do not add design decisions, engine hints, or workflow steps to the designer dispatch',
+      'Do not describe what designer should produce — its role card defines outputs',
+      'Do not list designer CLI commands — its role card defines the construction chain',
     ],
     nextCommands: [
-      'Invoke @game-designer — ring 1 clarify (skills match + design-brief + DESIGN seed + slice queue)',
+      'Invoke @game-designer — pass only the user\'s original intent, nothing more',
     ],
   },
   '1:select': {
-    currentAction: 'Orchestrator: after Game Designer STOP, spawn a temporary ref-flow atom-selection subagent for compact Ring 1 atom-tree selection.',
+    currentAction: 'Orchestrator: after Game Designer STOP, spawn a temporary ref-flow atom-selection subagent.',
     requiredFiles: [...COMMON_REQUIRED, 'docs/DESIGN.md'],
     deferredFiles: FUTURE_RING_FILES,
     nextRole: 'temporary-ref-flow',
     artifactRefs: ['docs/DESIGN.md', 'docs/atom-tree.json'],
-    requiredContextFields: ['lastRole.summary', 'lastRole.decisions', 'sharedDecisions.coreAction', 'sharedDecisions.semanticPlaceholders'],
+    requiredContextFields: ['lastRole.summary', 'sharedDecisions.coreAction'],
     allowedTasks: [
-      'Spawn temporary ref-flow atom-selection subagent for ring 1 atom-tree selection',
-      'Pass DESIGN.md gameplay keywords and constraints to the temporary selector',
+      'Spawn temporary ref-flow atom-selection subagent',
     ],
     forbiddenTasks: [
       'Do not select atoms inline as orchestrator',
       'Do not run init-template before atom-selection STOP',
-      'Do not implement gameplay logic as orchestrator',
+      'Do not add engine or gameplay-trunk hints to the selector dispatch',
     ],
     nextCommands: [
-      'Spawn temporary ref-flow atom-selection subagent — ring 1 atom-tree selection (engine + compact gameplay trunk)',
+      'Spawn temporary ref-flow atom-selection subagent — read docs/DESIGN.md and follow skill-selector-guide.md',
     ],
   },
   '1:scaffold': {
@@ -95,29 +92,21 @@ const DISCLOSURE_BY_RING_LOOP = {
     ],
   },
   '1:build': {
-    currentAction: 'Orchestrator: invoke @developer for Ring 1 build. Developer: implement playable spine to first-level win.',
+    currentAction: 'Orchestrator: invoke @developer for Ring 1 build.',
     requiredFiles: [...COMMON_REQUIRED, 'docs/DESIGN.md', 'docs/atom-tree.json', 'docs/scaffold-manifest.md', 'game/'],
     deferredFiles: FUTURE_RING_FILES.filter((file) => file !== 'logs/review-report.md'),
     nextRole: 'developer',
     artifactRefs: ['docs/DESIGN.md', 'docs/atom-tree.json', 'logs/developer-log.md', 'game/'],
-    requiredContextFields: ['lastRole.summary', 'lastRole.decisions', 'nextRole.mustKnow', 'sharedDecisions.engine', 'sharedDecisions.coreAction', 'sharedDecisions.semanticPlaceholders'],
+    requiredContextFields: ['lastRole.summary', 'sharedDecisions.engine', 'sharedDecisions.coreAction', 'sharedDecisions.semanticPlaceholders'],
     allowedTasks: [
       'Invoke @developer for ring 1 build',
-      'Apply engine scaffold if needed (orchestrator only, before developer)',
-      'Implement core gameplay loop (Developer subagent)',
-      'Wire window.__playable runtime contract (Developer subagent)',
-      'Make autoPlay follow player-reachable actions (Developer subagent)',
-      'Record devUrl when ready (Developer subagent)',
     ],
     forbiddenTasks: [
       'Do not implement game/ as orchestrator when @developer should own build',
-      'Do not polish HUD',
-      'Do not implement CTA fallback as a Ring 1 blocker',
-      'Do not run full MP4 as a Ring 1 blocker',
-      'Do not produce production assets',
+      'Do not add implementation hints to the developer dispatch — developer reads its dispatchPacket + role card',
     ],
     nextCommands: [
-      'Invoke @developer — ring 1 build (placeholder art + core loop)',
+      'Invoke @developer — pass the active slice from sliceState, nothing more',
       'npm run placeholder:gen',
       'npm run verify:contract',
       'npm run verify:lifecycle',
@@ -349,6 +338,21 @@ function normalizeIteration(iteration) {
   return Number.isFinite(n) && n >= 1 && n <= 4 ? n : 1;
 }
 
+/** Compatibility export for STOP hook mechanism-phase detection. */
+export function isMechanismLocked(projectRoot, handoffContext = {}) {
+  const skill = resolvePrimarySkillId(projectRoot, handoffContext);
+  if (!skill) return false;
+  const treePath = join(projectRoot, 'docs/atom-tree.json');
+  if (!existsSync(treePath)) return false;
+  try {
+    const tree = JSON.parse(readFileSync(treePath, 'utf8'));
+    const items = tree?.meta?.skillsMatch?.items ?? [];
+    return items.length > 0;
+  } catch {
+    return false;
+  }
+}
+
 function resolveDisclosureKey({ iteration = 1, loop = 'clarify', handoff = {} } = {}) {
   const ring = normalizeIteration(iteration);
   const normalizedLoop = normalizeLoop(loop);
@@ -407,6 +411,11 @@ export function disclosureForSlice(dispatchPacket, { iteration = 1 } = {}) {
   const status = String(dispatchPacket.status || 'pending').trim();
   const allowedFiles = Array.isArray(dispatchPacket.allowedFiles) ? dispatchPacket.allowedFiles : [];
   const packetForbidden = Array.isArray(dispatchPacket.forbiddenTasks) ? dispatchPacket.forbiddenTasks : [];
+  const packetRequired = Array.isArray(dispatchPacket.requiredContext?.mustRead)
+    ? dispatchPacket.requiredContext.mustRead
+    : Array.isArray(dispatchPacket.requiredContext)
+      ? dispatchPacket.requiredContext
+      : [];
 
   const currentAction =
     `Orchestrator: invoke @${role} for slice "${sliceId}" — ${doWhat} (flow: ${flow}). ` +
@@ -429,7 +438,7 @@ export function disclosureForSlice(dispatchPacket, { iteration = 1 } = {}) {
     ring,
     loop: flow,
     currentAction,
-    currentRingRequiredFiles: [...COMMON_REQUIRED, ...allowedFiles],
+    currentRingRequiredFiles: [...new Set([...COMMON_REQUIRED, ...packetRequired, ...allowedFiles])],
     deferredFiles: FUTURE_RING_FILES.filter((f) => !allowedFiles.includes(f)),
     allowedTasks: [
       `Invoke @${role} with dispatchPacket only (sliceId=${sliceId}, flow=${flow})`,
@@ -443,7 +452,7 @@ export function disclosureForSlice(dispatchPacket, { iteration = 1 } = {}) {
     ],
     nextCommands,
     nextRole: role,
-    artifactRefs: allowedFiles.length ? allowedFiles : ['dispatchPacket'],
+    artifactRefs: [...new Set(['dispatchPacket', ...packetRequired, ...allowedFiles])],
     requiredContextFields: [
       'dispatchPacket.sliceId',
       'dispatchPacket.role',
@@ -455,11 +464,28 @@ export function disclosureForSlice(dispatchPacket, { iteration = 1 } = {}) {
   };
 }
 
-/** Unified entry: active dispatchPacket wins; otherwise legacy ring:loop disclosure. */
-export function disclosureForProjectState({ iteration = 1, loop = 'clarify', handoff = {}, dispatchPacket = null } = {}) {
+/** Unified entry: active dispatchPacket wins; drained queue promotes to verify + ring:gate. */
+export function disclosureForProjectState({
+  iteration = 1,
+  loop = 'clarify',
+  handoff = {},
+  dispatchPacket = null,
+  sliceState = null,
+} = {}) {
   if (dispatchPacket) {
     return disclosureForSlice(dispatchPacket, { iteration });
   }
+  const ss = sliceState || {};
+  const gate = evaluateSliceQueueForRingGate(ss);
+  const ringGatePending = String(handoff.ringGate || 'pending').toLowerCase() !== 'passed';
+  if (
+    ss.activeSliceId === 'none'
+    && gate.applicable
+    && gate.ok
+    && ringGatePending
+  ) {
+    return disclosureForState({ iteration, loop: 'verify', handoff });
+  }
   return disclosureForState({ iteration, loop, handoff });
 }
 

package/project-templates/threejs/skills/_shared/scripts/harness-smoke.mjs

@@ -25,6 +25,8 @@ import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { DEFAULT_DEV_URL } from '../../playable-record/scripts/lib/dev-server.mjs';
+
 const require = createRequire(import.meta.url);
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SKILLS_ROOT = resolve(__dirname, '../..');
@@ -171,7 +173,7 @@ async function checkContractLive(projectRoot) {
     const { runContractProbe } = await import(pathToFileURL(probePath).href);
     const res = await runContractProbe({
       root: projectRoot,
-      url: isVite ? 'http://localhost:3000/' : null,
+      url: isVite ? DEFAULT_DEV_URL : null,
       useDev: isVite,
       port: 8080,
       scene: 'MainScene',