@playcraft/cli 0.0.44 → 0.0.46

package/project-template/templates/developer-log.template.md

@@ -4,84 +4,183 @@
 
 > **Step 0 — mandatory before Spec Quick-Check or any `game/` edit.**
 
-| Doc                         | Read ✓ | One-line takeaway                         |
-| --------------------------- | ------ | ----------------------------------------- |
-| `docs/project-state.md`     | ☐      | {{e.g. ui_pass, Wave 2 done}}             |
-| `docs/design-brief.md`      | ☐      | {{e.g. flow scenes for navigation}}       |
-| `docs/layout-spec.md`       | ☐      | {{e.g. zones, assetMapping, atlas paths}} |
-| `docs/atom-plan.json`       | ☐      | {{e.g. Developer atoms + skillRefs}}      |
-| `docs/atom-plan.md`         | ☐      | Impl Skill Context + acceptance           |
-| `docs/style-exploration.md` | ☐      | {{e.g. MC panel layout per scene}}        |
-| `logs/designer-log.md`      | ☐      | {{e.g. palette locked, motion notes}}     |
-| `logs/ta-log.md`            | ☐      | {{e.g. compliance green, atlas params}}   |
+| Doc                           | Read ✓  | One-line takeaway                                                           |
+| ----------------------------- | ------- | --------------------------------------------------------------------------- |
+| `docs/project-state.md`       | ☐       | {{stage, gates, devStatus}}                                                 |
+| `docs/implementation-plan.md` | ☐       | {{Feature 列表 + 依赖图 + 首关策略}}                                        |
+| `docs/design-brief.md`        | ☐       | {{rings 2+ only — ring 1 reads DESIGN.md instead}}                          |
+| `docs/layout-spec.md`         | ☐       | {{zones, assetMapping, atlas paths}}                                        |
+| `docs/atom-tree.json`         | ☐       | {{selected atom refs in meta.selectedAtoms + mediaGroups + revision trail}} |
+| `docs/atom-tree.md`           | ☐       | `Selected Atoms Summary` / `Selected Skill Notes` + acceptance              |
+| `docs/DESIGN.md`              | ☐       | {{player goal, core loop, fun source}}                                      |
+| `docs/style-exploration.md`   | ☐       | {{MC panel layout per scene}}                                               |
+| `docs/scaffold-manifest.md`   | ☐ / n/a | {{scaffold file → atom source mapping}}                                     |
+
+---
+
+## Spec Quick-Check
+
+> **Before coding**, confirm the spec is actually implementable in the current project.
+
+- **Required gameplay / UI contract paths complete**: {{yes/no}}
+- **Feature list can map onto current project structure**: {{yes/no}}
+- **Current blockers**: {{none / list}}
+- **If blocked, routeTo**: {{Game Designer / Artist / TA / none}}
 
 ---
 
 ## Skill Preflight
 
-> **Before any `game/` edits (ui_pass).** See `refs/developer-phase1-flow.md` Step 3.
+> **Before coding**, read the Skills referenced in your atoms and record what they contribute.
+
+| selectedAtomRef        | Read path / source                     | 提供了什么               | 怎么用                                    | 注意         |
+| ---------------------- | -------------------------------------- | ------------------------ | ----------------------------------------- | ------------ |
+| {{selectedAtomRef}}    | {{SKILL / ref}}                        | {{一句话}}               | {{scaffold import / 参考设计 / 参考配置}} | {{关键约束}} |
+| `playable-placeholder` | `skills/playable-placeholder/SKILL.md` | Tier 2 图片/音频批量占位 | batch 生成 + sidecar                      | build 环必载 |
+
+### Fusion wiring (≥2 gameplay atoms only)
+
+> When `meta.selectedAtoms` includes **2+ `*.aigameplay` refs**, record how each mechanic is wired and how `autoPlay()` reaches both.
 
-| skillRef     | access                | `ref/` files read (paths) | `scaffold` included |
-| ------------ | --------------------- | ------------------------- | ------------------- |
-| {{skillRef}} | linked / cli-fallback | {{paths}}                 | yes / no            |
+| Gameplay atom | Wiring evidence (file / symbol)             | autoPlay touchpoint               |
+| ------------- | ------------------------------------------- | --------------------------------- |
+| {{atomA}}     | {{e.g. game/gameplay/match3.ts → trySwap}}  | {{e.g. publish autoPlay phase 1}} |
+| {{atomB}}     | {{e.g. game/gameplay/memory.ts → flipCard}} | {{e.g. publish autoPlay phase 2}} |
 
 ---
 
-## UI Pass Plan
+## Read / Load Log
 
-> **ui_pass only — mandatory before UI implementation.** Hook enforces on STOP.
+> **有代码也必须先读。** Record the actual files, skills, and runtime inputs you loaded before editing.
 
-### Architecture
+| Type  | Path / Item | Why relevant | Read / Loaded ✓ | One-line takeaway |
+| ----- | ----------- | ------------ | --------------- | ----------------- |
+| code  | {{path}}    | {{reason}}   | ☐               | {{what matters}}  |
+| skill | {{skill}}   | {{reason}}   | ☐               | {{what matters}}  |
+| asset | {{path}}    | {{reason}}   | ☐               | {{what matters}}  |
 
-- **Engine**: {{engine}}
-- **Entry**: `game/index.html`
-- **Scene flow**: Hook → Tutorial → EndCard → CTA (navigation only in ui_pass)
+---
+
+## Skill-to-Prototype Assembly (Project Assembly Checkpoint)
+
+> **Mandatory before feature logic implementation.** Convert adopted Skill decisions into the smallest local playable spine before expanding features. This is a rework-prevention tool, not an audit form.
+
+### Assembly thinking
 
-### Scene-Asset Binding Plan
+#### What skill decisions am I inheriting?
 
-| Scene    | Assets (assetMapping) | Atlas/Frame | On disk? |
-| -------- | --------------------- | ----------- | -------- |
-| hook     | {{paths}}             | {{json}}    | {{y/n}}  |
-| tutorial | {{paths}}             | {{json}}    | {{y/n}}  |
-| endcard  | {{paths}}             | {{json}}    | {{y/n}}  |
+- {{object model / rule location / state flow / interaction boundary / asset organization}}
 
-### Scene navigation (for Reviewer ui_diff)
+#### What project-specific changes are required?
 
-| MC panel   | Scene key   | How to reach (URL param / button)  |
-| ---------- | ----------- | ---------------------------------- |
-| Concept    | {{initial}} | {{e.g. ?scene=main or default}}    |
-| Hook       | hook        | {{e.g. ?scene=hook}}               |
-| Onboarding | tutorial    | {{e.g. button or ?scene=tutorial}} |
-| EndCard    | endcard     | {{...}}                            |
-| CTA        | cta         | {{...}}                            |
+- {{game size / contract paths / first-level requirement / UI states / runtime constraints}}
 
-### Risk Checklist (ui_pass)
+#### What is the smallest playable spine before feature expansion?
 
-- [ ] Every assetMapping path verified on disk
-- [ ] Scene navigation documented for all 5 MC panels
-- [ ] No core gameplay rules in ui_pass scope
-- [ ] No external network dependencies
+- {{load setup → render core objects → player action → feedback → rule resolution}}
+
+### Scaffold adoption
+
+| Scaffold / existing file | Atom / source | Skill decision carried by this file | Used by feature | Adopt / ignore-with-reason | Notes                            |
+| ------------------------ | ------------- | ----------------------------------- | --------------- | -------------------------- | -------------------------------- |
+| {{path}}                 | {{skillRef}}  | {{decision}}                        | {{feature}}     | {{adopt / reason}}         | {{how it shapes implementation}} |
+
+### Placeholder materialization
+
+> **Policy**: Tier 1 link → Tier 2 `placeholder:gen` (image) / `placeholder:gen-audio` (loaded MP3) → Tier 3 code-draw or event hook only. Load **`playable-placeholder`** skill before materialization.
+
+| Asset contract path | Tier / Source                                     | Size    | Generated / verified | Used by scene / feature | Notes                        |
+| ------------------- | ------------------------------------------------- | ------- | -------------------- | ----------------------- | ---------------------------- |
+| {{path}}            | {{Tier 1/2/3 — linked / placeholder / code-draw}} | {{WxH}} | ☐                    | {{scene / feature}}     | {{label / reason if Tier 3}} |
+
+- **Placeholder script**: `ta-workspace/scripts/gen-placeholders.mjs` {{created / updated / n/a}}
+- **Audio placeholder script**: `ta-workspace/scripts/gen-placeholder-audio.mjs` {{created / updated / n/a}}
+- **Placeholder run result**: {{success / partial / failed + reason}}
+- **Tier 3 code-draw exceptions**: {{list each with one-line why placeholder file was not viable, or "none"}}
+- **No runtime remote image URLs**: {{yes/no}}
+- **No code-draw substituting Tier 2 paths**: {{yes/no}}
+
+### Minimal prototype wiring baseline
+
+| Feature     | Skill / ref basis  | Skill-defined loop step                                     | Code entry / scaffold file | Asset paths | Baseline status     |
+| ----------- | ------------------ | ----------------------------------------------------------- | -------------------------- | ----------- | ------------------- |
+| {{feature}} | {{skillRef / ref}} | {{e.g. setup / player action / feedback / rule resolution}} | {{path}}                   | {{paths}}   | {{ready / blocked}} |
+
+- **Skill-defined minimal loop**: {{describe the smallest playable loop from the adopted Skill/ref; not necessarily full ad flow}}
+- **Closed-loop path ready for implementation**: {{yes/no}}
+- **Open blockers before coding**: {{none / list}}
+- **If I am about to rewrite scaffold from scratch, why is adaptation insufficient?** {{reason / n/a}}
 
 ---
 
-## Gameplay Pass Plan
+## Implementation Plan
 
-> **gameplay_pass only — mandatory before PGS / rules implementation.**
+> **development stage — mandatory before any `game/` edit.** Hook enforces on STOP.
+>
+> This section captures the Developer execution plan for the current run. Developer role ownership and boundaries live in `.claude/agents/developer.md`.
+
+### Architecture
+
+- **Engine**: {{engine}}
+- **Entry**: `game/index.html`
+- **Skill-defined minimal loop**: {{setup → player action → feedback → rule resolution, or the loop defined by adopted Skill/ref}}
+- **Ad experience flow**: {{Hook / Tutorial / Gameplay / EndCard / CTA if required by plan, otherwise list required scenes/states}}
+
+### Scene / Loop Asset Binding Plan
+
+| Scene / loop step            | Assets (assetMapping) | Atlas/Frame | Placeholder strategy                |
+| ---------------------------- | --------------------- | ----------- | ----------------------------------- |
+| {{scene or skill loop step}} | {{paths}}             | {{json}}    | {{Skill asset / placeholder color}} |
+
+### Scene navigation (for Reviewer ui_diff, if required by plan)
+
+| Required panel / state | Scene key | How to reach (URL param / button) |
+| ---------------------- | --------- | --------------------------------- |
+| {{panel/state}}        | {{key}}   | {{e.g. ?scene=main or button}}    |
 
 ### PGS Strategy
 
-- **Gameplay type**: {{from design-brief}}
-- **Core rules**: {{from Skill recipe}}
-- **First level guarantee**: {{how tutorial ensures win}}
+- **Gameplay type**: {{from DESIGN.md (+ design-brief in rings 2+) / adopted Skill}}
+- **Core rules**: {{from Skill recipe / ref source}}
+- **Minimal loop guarantee**: {{how the skill-defined loop can be completed locally}}
+- **First level guarantee**: {{if required by plan}}
 - **State machine**: {{states and transitions}}
 
-### Risk Checklist (gameplay_pass)
+### Risk Checklist
 
-- [ ] UI shell unchanged unless open UI Diff items
-- [ ] testCases written before rule implementation
-- [ ] First level guarantees player success
-- [ ] CTA handler with platform fallbacks
+- [ ] Every assetMapping path used by current features is accounted for (Skill asset / placeholder noted)
+- [ ] Skill-defined minimal loop can run locally
+- [ ] Required scene navigation documented for all plan-required panels / states
+- [ ] First level guarantee covered if required by plan
+- [ ] CTA handler with platform fallbacks if required by plan
 - [ ] Zero external network requests
+- [ ] No open unexplained blockers
+
+---
+
+## Feature Checklist
+
+> Convert `docs/implementation-plan.md` into the real execution and acceptance checklist.
+
+| Order | Feature     | Source refs           | Dependencies | Existing code read? | Done when             | Status                                  |
+| ----- | ----------- | --------------------- | ------------ | ------------------- | --------------------- | --------------------------------------- |
+| 1     | {{feature}} | {{plan/design/skill}} | {{deps}}     | yes / no            | {{completion signal}} | todo / doing / done / partial / blocked |
+
+---
+
+## Feature Review
+
+> **Ready 判断前必须逐项 review。**
+
+| Feature     | Status                   | Verification         | Review notes                                                          | Remaining risk / blocker |
+| ----------- | ------------------------ | -------------------- | --------------------------------------------------------------------- | ------------------------ |
+| {{feature}} | {{done/partial/blocked}} | {{what was checked}} | {{did existing code + skill reading actually inform implementation?}} | {{none / issue}}         |
+
+### Review decision
+
+- **Checklist complete**: {{yes/no}}
+- **Unexplained partial / blocked items**: {{none / list}}
+- **Can enter ready check**: {{yes/no}}
 
 ---
 
@@ -98,29 +197,54 @@
 
 ## Dev self-check
 
-### ui_pass completion
+### development completion
 
-- **devUrl**: {{http://localhost:...}}
-- **devStatus**: ui_ready
+- **devUrl**: {{http://localhost:.../?debug=1}} ← always include `?debug=1` (shows the one-click clear debug button)
+- **devStatus**: {{ready / blocked_upstream / in_progress}}
 - **UI vs MC + layout-spec**: {{pass/fail — notes}}
 - **Scene navigation works**: {{yes/no}}
-- **Ready for Reviewer ui_diff**: {{yes/no}}
+- **Gameplay vs DESIGN.md + PGS**: {{pass/fail — notes}}
+- **Runtime** (CTA, audio, state machine): {{pass/fail — notes}}
+- **Feature checklist reviewed**: {{yes/no}}
+- **verify:contract**: {{pass/fail — log OK line}}
+- **verify:lifecycle** (ring 1 STOP required): {{pass/fail — phase path}}
+- **verify:firstwin** (ring 1 STOP required): {{pass/fail — log OK line}}
+- **verify:placeholders** (ring 1 STOP required): {{pass/fail — loaded asset paths exist}}
+- **Ready for ring:gate** (ring 1) / **Ready for Reviewer gameplay_conformance** (ring 2+): {{yes/no}}
 
-### gameplay_pass completion
+---
 
-- **devUrl**: {{http://localhost:...}}
-- **devStatus**: ready
-- **Gameplay vs design-brief + PGS**: {{pass/fail — notes}}
-- **Runtime** (CTA, audio, state machine): {{pass/fail — notes}}
-- **Ready for Reviewer load_check**: {{yes/no}}
+## Skill Leverage
+
+> **STOP 前回顾**。说明哪些 Skill 参考真实影响了实现与判断。
+
+- 哪些 selected / additional Skill 在本轮真正被参考？{{列出 skillRef，如无则说明为何}}
+- 它们分别帮助了什么判断或实现？{{简述}}
+- 哪些 shortlisted Skill 最终未采用？{{是/否 + 原因}}
 
 ---
 
 ## Upstream blockers
 
-| Path     | Issue     | Expected       | routeTo            | Status          |
-| -------- | --------- | -------------- | ------------------ | --------------- |
-| {{path}} | {{issue}} | {{acceptance}} | TA / Designer / PM | open / resolved |
+| Path     | Issue     | Resolution                               | routeTo                     | Status          |
+| -------- | --------- | ---------------------------------------- | --------------------------- | --------------- |
+| {{path}} | {{issue}} | fixed / replaced(reason) / escalated / — | TA / Artist / Game Designer | open / resolved |
+
+---
+
+## UI Rework Log
+
+> **ui_rework stage only.** 每轮只修 `logs/review-report.md` 中 `routeTo: Developer` 的 Action Items；不改游戏逻辑。
+
+### Round {{N}}
+
+| Action Item | Severity  | Fix applied                      | npm run dev result |
+| ----------- | --------- | -------------------------------- | ------------------ |
+| {{item}}    | {{level}} | {{what was changed + file/line}} | {{pass/fail}}      |
+
+- **Remaining open items**: {{count or "none"}}
+- **devUrl after fix**: {{http://localhost:.../?debug=1}}
+- **Handoff**: `Invoke @reviewer ui_diff`
 
 ---
 
@@ -129,6 +253,6 @@
 ### {{atom_id}} — {{slot_name}}
 
 - **Status**: {{status}}
-- **Phase**: ui_pass / gameplay_pass
+- **Phase**: development / ui_rework
 - **Output path**: {{file_path}}
 - **Notes**: {{notes}}

package/project-template/templates/five-axis-framework.md

@@ -1,27 +1,70 @@
 # Five-Axis Analysis Framework
 
-> **When to read**: PM reads this during Step 4 (Five-Axis Evaluation).
-> Every playable ad request must be classified along all five orthogonal axes before generating options.
+> **When to read**: Game Designer may consult this as an **optional analytical tool** during design work. It is NOT a mandatory step-by-step checklist.
+>
+> **Stage relevance**:
+>
+> - **ring 1 `loop: clarify`**: Only **Axis 1 (Mechanic)** and **Axis 3 (Interaction Modality)** must be resolved — they define core playability (可解性) and time/operation budget. The other axes only need a rough direction signal (e.g. "2D", "L1 character present", "Competence arc").
+> - **ring 2 `loop: clarify` (after MC (Master Composite, 主合成图))**: Axis 2 (Dimension), Axis 4 (Narrative Level), and Axis 5 (Emotional Arc) get their full specification when visual direction is confirmed by MC selection.
+>
+> **This framework is a thinking aid, not a production template.** Game Designer should focus on gameplay first; use these axes to check coverage, not to fill out forms.
+
+The five axes are **orthogonal** — each is an independent decision. The same Match-3 game can be Flat 2D or 2.5D, Tap-only or Drag, L0 or L1, Competence Arc or Challenge Arc. Game Designer evaluates all five internally, then presents 2-3 complete options (covering all axes) for the user to choose from.
+
+## Playable-Ad First Principle
+
+The five axes are not a recipe for adding more ideas. They are a filter for one short playable-ad delight loop:
+
+```text
+Hook Conflict
+→ First Action
+→ Instant Feedback
+→ Escalating Decision
+→ Payoff Release
+→ Install Curiosity
+```
+
+Before applying any axis, Game Designer must know the primary player desire:
+
+- What makes the user stop?
+- What makes the first action obvious and tempting?
+- What feedback makes the player feel in control?
+- What payoff happens within 3-5 actions?
+- What unfinished promise carries the CTA (Call To Action, 行动号召)?
 
-The five axes are **orthogonal** — each is an independent decision. The same Match-3 game can be Flat 2D or 2.5D, Tap-only or Drag, L0 or L1, Competence Arc or Challenge Arc. PM evaluates all five internally, then presents 2-3 complete options (covering all axes) for the user to choose from.
+Any axis choice or fusion idea is valid only if it strengthens at least one part of this loop. If a secondary mechanic only makes the concept sound richer, but does not improve hook, first action, feedback, payoff, or install curiosity, downgrade it to visual dressing or pseudo-fusion.
 
 ---
 
 ## Axis 1 — Mechanic (Gameplay Fusion Types)
 
-| Type | Definition | Tutorial Overhead | Risk |
-|------|-----------|-------------------|------|
-| **Single** | One mechanic, no fusion | Baseline | None |
-| **Type A — Visual Fusion** | Mechanics unchanged; elements re-skinned to another game's visual language | None | Very Low |
-| **Type B1 — Passive Borrowing** | Primary mechanic + secondary mechanic auto-triggers (no extra user gesture) | Minimal | Low |
-| **Type B2 — Active Borrowing** | Primary mechanic + secondary mechanic requires user activation (1.5 core gestures) | Slight increase | Medium |
-| **Type C — Sequential Fusion** | Two mechanic sets appear in sequence (includes rotation/alternating mode) | High | High |
-| **Type D — Parallel Fusion** | Two mechanic sets active simultaneously, sharing the screen | Extreme | Extreme (almost never viable for ads) |
+| Type                            | Definition                                                                         | Tutorial Overhead | Risk                                  |
+| ------------------------------- | ---------------------------------------------------------------------------------- | ----------------- | ------------------------------------- |
+| **Single**                      | One mechanic, no fusion                                                            | Baseline          | None                                  |
+| **Type A — Visual Fusion**      | Mechanics unchanged; elements re-skinned to another game's visual language         | None              | Very Low                              |
+| **Type B1 — Passive Borrowing** | Primary mechanic + secondary mechanic auto-triggers (no extra user gesture)        | Minimal           | Low                                   |
+| **Type B2 — Active Borrowing**  | Primary mechanic + secondary mechanic requires user activation (1.5 core gestures) | Slight increase   | Medium                                |
+| **Type C — Sequential Fusion**  | Two mechanic sets appear in sequence (includes rotation/alternating mode)          | High              | High                                  |
+| **Type D — Parallel Fusion**    | Two mechanic sets active simultaneously, sharing the screen                        | Extreme           | Extreme (almost never viable for ads) |
 
 ### Pseudo-Fusion Technique
 
 When the user insists on Type C/D, recommend pseudo-fusion: **visually appear as two systems, but the underlying mechanic is single**. Example: Match-3 elimination count drives a monster HP bar — the user only performs match-3 the entire time, but perceives "elimination + combat."
 
+### Fusion Quality Bar
+
+For every non-`Single` option, answer:
+
+| Question                                                    | Pass Signal                                                      |
+| ----------------------------------------------------------- | ---------------------------------------------------------------- |
+| What is the primary joy?                                    | One clear emotion source, not a list of features                 |
+| Which loop stage does the secondary mechanic strengthen?    | Hook, first action, feedback, payoff, or install curiosity       |
+| Does the secondary mechanic require a new tutorial gesture? | No, or the cost is explicitly justified                          |
+| Does the payoff become stronger?                            | The player sees a bigger release than the primary mechanic alone |
+| Can it be understood in the ad timeline?                    | The user can grasp it without reading a rules paragraph          |
+
+If these answers are weak, the fusion is probably decorative complexity.
+
 ### Decision Rules
 
 ```
@@ -38,28 +81,30 @@ User prompt contains fusion intent?
 
 ## Axis 2 — Dimension (Gameplay Dimension Spectrum)
 
-| Dimension | Description | Designer Impact | Developer Impact | Risk Delta |
-|-----------|------------|----------------|-----------------|------------|
-| **Flat 2D** | Pure 2D sprites, no depth | Standard 2D illustration assets | Standard 2D logic | None |
-| **2.5D Visual** | 3D rendered look, but game logic remains 2D grid (depth is decorative) | 3D-feel rendering / model textures, ~3x cost | Logic stays 2D, add depth rendering | +Medium |
-| **Isometric** | Fixed 45° angle, depth is aesthetic not mechanic | Isometric assets, strict pixel alignment required | Isometric coordinate transforms | +Low |
-| **True 3D** | Z-axis is a live mechanic (rotation/depth participates in interaction) | Full 3D models via AI (`generate-3d`) or white model + texture pipeline; 3–5x cost | 3D engine, physics, camera management; all existing PGS invalidated | +High (tool support available, not BLOCKED) |
+| Dimension       | Description                                                            | Artist Impact                                                                      | Developer Impact                                                    | Risk Delta                                  |
+| --------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------- |
+| **Flat 2D**     | Pure 2D sprites, no depth                                              | Standard 2D illustration assets                                                    | Standard 2D logic                                                   | None                                        |
+| **2.5D Visual** | 3D rendered look, but game logic remains 2D grid (depth is decorative) | 3D-feel rendering / model textures, ~3x cost                                       | Logic stays 2D, add depth rendering                                 | +Medium                                     |
+| **Isometric**   | Fixed 45° angle, depth is aesthetic not mechanic                       | Isometric assets, strict pixel alignment required                                  | Isometric coordinate transforms                                     | +Low                                        |
+| **True 3D**     | Z-axis is a live mechanic (rotation/depth participates in interaction) | Full 3D models via AI (`generate-3d`) or white model + texture pipeline; 3–5x cost | 3D engine, physics, camera management; all existing PGS invalidated | +High (tool support available, not BLOCKED) |
 
 ### Key Judgment
 
-Is the dimension upgrade "purely visual decoration" (2.5D Visual) or "Z-axis participates in mechanics" (True 3D)? The former only affects Designer asset cost; the latter requires entirely new PGS — fundamentally different risk profiles.
+Is the dimension upgrade "purely visual decoration" (2.5D Visual) or "Z-axis participates in mechanics" (True 3D)? The former only affects Artist asset cost; the latter requires entirely new PGS — fundamentally different risk profiles.
 
 ### True 3D Tool Support (Available as of 2026-05)
 
-True 3D is **High Risk** but no longer blocked. Designer has two asset pipelines:
+True 3D is **High Risk** but no longer blocked. Artist has two asset pipelines:
 
 **Pipeline A — AI Generation (best quality, ~1–5 min per model)**
+
 ```bash
 playcraft tools generate-3d --prompt "low-poly wooden crate" --output assets/models/crate.glb
 playcraft 3d optimize --input crate.glb --output crate_opt.glb
 ```
 
 **Pipeline B — White Model + Texture (fastest, predictable UV)**
+
 ```bash
 playcraft 3d list-models                             # sphere, cube, cylinder, cone, torus, plane, capsule
 playcraft tools generate-image --prompt "texture" --output tex.png
@@ -73,7 +118,7 @@ Z-axis is a live mechanic (rotation/depth affects gameplay)?
   → True 3D — tool pipeline available (Pipeline A or B above)
               still recommend generating 2.5D Visual option as fallback
 3D visual feel but 2D interaction grid?
-  → 2.5D Visual (Designer cost ~3x, Developer logic unchanged)
+  → 2.5D Visual (Artist cost ~3x, Developer logic unchanged)
 Fixed isometric perspective?
   → Isometric
 Otherwise → Flat 2D (default, zero additional risk)
@@ -83,13 +128,13 @@ Otherwise → Flat 2D (default, zero additional risk)
 
 ## Axis 3 — Interaction Modality
 
-| Modality | Description | Tutorial Time | Audience Width | Risk Delta |
-|----------|------------|--------------|---------------|------------|
-| **Tap Only** | Single-finger single-tap | ≤1s | Broadest (includes elderly, children) | None |
-| **Tap + Swipe** | Tap + directional swipe | ~3s | Broad | +Low |
-| **Drag** | Press-hold and drag to target | ~5s | Medium | +Low |
-| **Tap + Hold** | Tap + long-press with timing | ~5s | Medium | +Medium |
-| **Multi-touch** | Two or more fingers simultaneously | ≥10s | Very narrow | +Extreme (almost never viable for ads) |
+| Modality        | Description                        | Tutorial Time | Audience Width                        | Risk Delta                             |
+| --------------- | ---------------------------------- | ------------- | ------------------------------------- | -------------------------------------- |
+| **Tap Only**    | Single-finger single-tap           | ≤1s           | Broadest (includes elderly, children) | None                                   |
+| **Tap + Swipe** | Tap + directional swipe            | ~3s           | Broad                                 | +Low                                   |
+| **Drag**        | Press-hold and drag to target      | ~5s           | Medium                                | +Low                                   |
+| **Tap + Hold**  | Tap + long-press with timing       | ~5s           | Medium                                | +Medium                                |
+| **Multi-touch** | Two or more fingers simultaneously | ≥10s          | Very narrow                           | +Extreme (almost never viable for ads) |
 
 ### Key Insight
 
@@ -111,17 +156,17 @@ Note tutorial time budget: Tap=1s / Tap+Swipe=3s / Drag=5s / Tap+Hold=5s
 
 ## Axis 4 — Narrative Level
 
-| Level | Definition | Designer Impact | Tutorial Method | 30s Fitness |
-|-------|-----------|----------------|----------------|------------|
-| **L0 Pure Mechanic** | No character, no story, pure gameplay showcase | No character assets | Highlight hints + text | High (concise) |
-| **L1 Character Present** | Protagonist exists but no plot ("help the kitten match!") | 1 character sprite set needed | Character performs demo action | **Highest (recommended)** |
-| **L2 Scenario Wrapper** | Character + problem scenario ("princess trapped, clear obstacles") | Protagonist + scenario narrative assets | Character dialogue + demo | Medium (must be tight) |
-| **L3 Story-Driven** | Narrative is core, mechanics serve the story | Heavy story assets + storyboards | Cinematic storytelling | Low (almost never fits 30s) |
+| Level                    | Definition                                                         | Artist Impact                           | Tutorial Method                | 30s Fitness                 |
+| ------------------------ | ------------------------------------------------------------------ | --------------------------------------- | ------------------------------ | --------------------------- |
+| **L0 Pure Mechanic**     | No character, no story, pure gameplay showcase                     | No character assets                     | Highlight hints + text         | High (concise)              |
+| **L1 Character Present** | Protagonist exists but no plot ("help the kitten match!")          | 1 character sprite set needed           | Character performs demo action | **Highest (recommended)**   |
+| **L2 Scenario Wrapper**  | Character + problem scenario ("princess trapped, clear obstacles") | Protagonist + scenario narrative assets | Character dialogue + demo      | Medium (must be tight)      |
+| **L3 Story-Driven**      | Narrative is core, mechanics serve the story                       | Heavy story assets + storyboards        | Cinematic storytelling         | Low (almost never fits 30s) |
 
 ### Key Insights
 
 - **L1 is the sweet spot for playable ads** — emotional connection without time overhead.
-- L1+ means Designer needs character assets; PM must define character concept.
+- L1+ means Artist needs character assets; Game Designer must define character concept.
 - L3 is **incompatible with 30s format** — auto-downgrade to L2 with explanation.
 
 ### Decision Rules
@@ -131,7 +176,7 @@ User mentions character / hero / story? → L1 or L2
 Game genre typically story-heavy (RPG, adventure)? → L2 recommended
 No character signal, generic product? → L0 or L1
 Default for playable ads: L1
-L2+: flag that Designer needs character asset set
+L2+: flag that Artist needs character asset set
 L3: auto-downgrade to L2 — incompatible with 30s format
 ```
 
@@ -139,17 +184,17 @@ L3: auto-downgrade to L2 — incompatible with 30s format
 
 ## Axis 5 — Emotional Arc
 
-| Arc Type | Player Journey | Hook Design | Gameplay Feel | EndCard Tone |
-|----------|---------------|-------------|--------------|-------------|
-| **Competence** | Confused → Learned → "I'm smart!" | Show "looks hard but has a pattern" | Generous, guarantee success | "Easy and fun, keep playing" |
-| **Challenge** | Looks hard → All-out effort → Achievement | Create difficult scenario | Difficulty ramp, allow failure | "Think you can beat it?" |
-| **Curiosity** | What is this? → Aha! → Surprise | Show counter-intuitive mechanic | Full of surprises | "More to explore" |
-| **Relaxation** | Enter flow → Enjoy rhythm → Satisfaction | Serene, beautiful imagery | Steady pace, low pressure | "Come relax anytime" |
-| **Urgency** | Crisis → Frantic action → Narrow escape | Emergency scene, countdown | High pressure, fast pace | "One more round!" |
+| Arc Type       | Player Journey                            | Hook Design                         | Gameplay Feel                  | EndCard Tone                 |
+| -------------- | ----------------------------------------- | ----------------------------------- | ------------------------------ | ---------------------------- |
+| **Competence** | Confused → Learned → "I'm smart!"         | Show "looks hard but has a pattern" | Generous, guarantee success    | "Easy and fun, keep playing" |
+| **Challenge**  | Looks hard → All-out effort → Achievement | Create difficult scenario           | Difficulty ramp, allow failure | "Think you can beat it?"     |
+| **Curiosity**  | What is this? → Aha! → Surprise           | Show counter-intuitive mechanic     | Full of surprises              | "More to explore"            |
+| **Relaxation** | Enter flow → Enjoy rhythm → Satisfaction  | Serene, beautiful imagery           | Steady pace, low pressure      | "Come relax anytime"         |
+| **Urgency**    | Crisis → Frantic action → Narrow escape   | Emergency scene, countdown          | High pressure, fast pace       | "One more round!"            |
 
 ### Key Principle
 
-The Emotional Arc is the **unified throughline** across Hook → Tutorial → Gameplay → EndCard. If the Hook creates curiosity but Gameplay delivers relaxation, the experience fractures. The arc must be locked at the PM stage; all downstream Agents execute along this arc.
+The Emotional Arc is the **unified throughline** across Hook → Tutorial → Gameplay → EndCard. If the Hook creates curiosity but Gameplay delivers relaxation, the experience fractures. The arc must be locked at the Game Designer stage; all downstream Agents execute along this arc.
 
 ### Decision Rules
 
@@ -172,7 +217,7 @@ After completing all five internal classifications, generate 2-3 complete option
 ```
 Each option includes:
   - Mechanic Axis (type + PGS coverage)
-  - Dimension Axis (type + Designer impact)
+  - Dimension Axis (type + Artist impact)
   - Interaction Modality (modality + tutorial time estimate)
   - Narrative Level (level + asset impact)
   - Emotional Arc (arc type + Hook/EndCard tone)

package/project-template/templates/gen-placeholder-audio.template.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * Batch spectral-audio placeholder generator for develop-stage asset materialization.
+ * Outputs per row: <stem>.mp3 + <stem>.json (+ <stem>.spectrogram.png in spectral mode).
+ * See skills/playable-placeholder/SKILL.md for full Developer workflow.
+ *
+ * Setup:
+ *   cp templates/gen-placeholder-audio.template.mjs ta-workspace/scripts/gen-placeholder-audio.mjs
+ *
+ * Run:
+ *   node ta-workspace/scripts/gen-placeholder-audio.mjs
+ *   # or: npm run placeholder:gen-audio -- --batch ta-workspace/tmp/placeholders.audio.batch.json
+ *
+ * Use when Preloader / load.audio already references contract MP3 paths but Artist has not delivered yet.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = process.cwd();
+const GEN_SCRIPT = join(ROOT, 'skills/_shared/scripts/gen-placeholder-audio.py');
+const BATCH_JSON = join(ROOT, 'ta-workspace/tmp/placeholders.audio.batch.json');
+
+// Derive from layout-spec.md → assetMapping audio rows + Preloader keys.
+const PLACEHOLDER_AUDIO = [
+  {
+    path: 'assets/audio/bgm/bgm_main.mp3',
+    label: 'bgm_main',
+    type: 'bgm',
+    role: 'bgm · 主背景音乐',
+  },
+  {
+    path: 'assets/audio/sfx/sfx_match.mp3',
+    label: 'sfx_match',
+    type: 'sfx',
+    role: 'sfx · 消除音效',
+  },
+  {
+    path: 'assets/audio/sfx/sfx_click.mp3',
+    label: 'sfx_click',
+    type: 'sfx',
+    role: 'ui sfx · 点击',
+  },
+  // Add one row per contract MP3 path the minimal prototype loads.
+];
+
+function runBatch() {
+  mkdirSync(dirname(BATCH_JSON), { recursive: true });
+  writeFileSync(BATCH_JSON, `${JSON.stringify(PLACEHOLDER_AUDIO, null, 2)}\n`, 'utf8');
+
+  const proc = spawnSync('python3', [GEN_SCRIPT, '--batch', BATCH_JSON], {
+    cwd: ROOT,
+    stdio: 'inherit',
+    encoding: 'utf8',
+  });
+  if (proc.status !== 0) {
+    process.exit(proc.status ?? 1);
+  }
+}
+
+runBatch();