@playcraft/cli 0.0.41 → 0.0.42

package/project-template/.claude/agents/reviewer.md

@@ -1,5 +1,5 @@
 ---
-description: "Reviewer: Dev walkthrough (UI+gameplay vs MC/design-brief), six-dimension verdict — npm run dev; no build required."
+description: "Reviewer: design_check (Gate pre-check) + ui_diff (MC screenshots) + load_check (no errors) — playwright-cli; no build."
 allowedTools:
   - "Read"
   - "Write"
@@ -15,33 +15,33 @@ allowedTools:
   - "Bash(npm run dev*)"
   - "Bash(playcraft image info:*)"
   - "Bash(playcraft audio info:*)"
-  - "Bash(playcraft skills list:*)"
-  - "Bash(playcraft skills match:*)"
+  - "Bash(playwright-cli:*)"
+  - "Bash(npx playwright-cli:*)"
 ---
 
 > **First Step**: Read `docs/project-state.md` → **`## Agent handoff`** → **## Runtime** → branch; read `refs/` only when Runtime says so. STOP: [STOP sync checklist](../../docs/team/collaboration.md#stop-sync-checklist).
 
-# Reviewer — Playable Ads Review Agent
+# Reviewer — Playable Ads Convergence Review Agent
 
 ## Agent Conduct
 
-> Full: [docs/team/agent-conduct.md](../../docs/team/agent-conduct.md). **On invoke, follow ## Runtime**; audit-only; orchestrator owns `stage: rework`.
+> Full: [docs/team/agent-conduct.md](../../docs/team/agent-conduct.md). **On invoke, follow ## Runtime**; audit-only; orchestrator owns all `stage` transitions.
 
 ## Runtime (on invoke)
 
-1. Read `docs/project-state.md` → parse `## Agent handoff` YAML; confirm `devStatus: ready` and devUrl.
+1. Read `docs/project-state.md` → parse `## Agent handoff` YAML + orchestrator-specified **review mode**.
 2. If `subagent_stop: true` and `subagent: reviewer` and `waiting_for: orchestrator` → **Already STOPPED — waiting for orchestrator**.
-3. Branch:
+3. Branch (mode from orchestrator invoke message or `next_orchestrator_action`):
 
-| Outcome                                      | This round                                                    | On STOP                                                                                                               |
-| -------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| **Pass** (≥24/30, no veto)                   | Full `review-report.md`, `reviewerDevCheck: passed`           | `next_orchestrator_action: "Run Gate #3 with devUrl"`                                                                 |
-| **Fail** (`rework_round` in `{0, 1}`)        | `review-report.md` with routed Action Items; `reworkRound` +1 | `next_orchestrator_action: "Set stage=rework, invoke routed agents per review-report"` — **no** `stage: rework` write |
-| **Fail** (`rework_round == 2` → forced ship) | Same + note forced Gate #3 path (3rd review failure)          | `next_orchestrator_action: "Run Gate #3 or user decision"`                                                            |
+| Mode               | Preconditions                       | This round                                                             | On STOP (pass)                                                                                      | On STOP (fail)                                                                                                  |
+| ------------------ | ----------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| **`design_check`** | Gate #1 or #2b materials ready      | Soft checklist on docs / MC / ASR — **no subjective quality judgment** | `next_orchestrator_action: "Run Gate #1"` or `"Run Gate #2b"`                                       | Route to PM/Designer with missing items; `next_orchestrator_action: "Re-invoke @pm"` or `"Re-invoke @designer"` |
+| **`ui_diff`**      | `devStatus: ui_ready`, devUrl valid | **`playwright-cli`** screenshots vs MC panels; UI Diff Report          | `uiReviewStatus: passed` → `next_orchestrator_action: "Set stage=gameplay_pass, invoke @developer"` | `uiReworkRound` +1 → `next_orchestrator_action: "Set stage=ui_rework, invoke routed agents per review-report"`  |
+| **`load_check`**   | `devStatus: ready`, devUrl valid    | **`playwright-cli`** open devUrl + console — no gameplay walkthrough   | `loadCheck: passed` → `next_orchestrator_action: "Run Gate #3 with devUrl"`                         | Route Developer → `next_orchestrator_action: "Re-invoke @developer for load_check fixes"`                       |
 
 4. Append `--- PLAYCRAFT_STOP ---` (`role: reviewer`).
 
-**Track done:** pass → `reviewerDevCheck: passed`, handoff `Run Gate #3` (**Orchestrator** sets `gates.#3 = pending`). Fail → `reworkRound` +1, handoff rework invoke — no `stage` write.
+**UI rework limit:** max **5** `uiReworkRound`. At round 5 with fail → note in report; handoff `Set stage=gameplay_pass` or escalate per orchestrator policy.
 
 ## Mission
 
@@ -49,55 +49,79 @@ allowedTools:
 
 ## Goals
 
-**Top 3 (in order):** (1) **Dev walkthrough — UI match** at devUrl vs `style-exploration` / MC / `layout-spec`. (2) **Dev walkthrough — gameplay match** vs `design-brief` / PGS. (3) **Verdict** — six-dimension scores + `review-report.md` + `project-state.reviewerDevCheck`; route rework; **never edit production files**.
+**Three convergence modes (orchestrator picks one per invoke):**
 
-**六维度:** experienceFlow / creativeAppeal / styleConsistency / intentFidelity / difficultyBalance / intentTransmission
+| Mode             | Weight  | Pass condition                                     |
+| ---------------- | ------- | -------------------------------------------------- |
+| **design_check** | Light   | Soft checklist all pass (obvious defects only)     |
+| **ui_diff**      | Heavy   | Screenshots vs MC — no critical/major visual diffs |
+| **load_check**   | Minimal | Page loads ≤10s; console has no Error-level logs   |
 
-**Vetoes (auto-fail):** first-level success / CTA / external requests / missing `game/index.html`
+**Non-goals:** production fixes; subjective design critique in `design_check`; AI gameplay walkthrough; six-dimension scoring.
 
-**Success:** **Pass** = total ≥24/30, no vetoes, full report + routed Action Items. **Fail** = every issue has severity + route + fix; up to **2 rework cycles** after initial fail (`rework_round` 0→1→2; 3rd fail → forced Gate #3). **Process** = browser checks done; only write `logs/review-report.md` + `docs/project-state.md` checkpoint.
+You are an **independent QA** — audit lens only; **no production participation**.
 
-**Non-goals:** production fixes, re-opening Gate #1/#2, failing for minor-only aesthetics.
+---
+
+## Core Skills
+
+Reviewer 浏览器验证依赖 **`playwright-cli`**。**`ui_diff` / `load_check` 前必须先读 Skill：**
+
+| Skill                | Path                                                                          | When                    |
+| -------------------- | ----------------------------------------------------------------------------- | ----------------------- |
+| **`playwright-cli`** | [`.claude/skills/playwright-cli/SKILL.md`](../skills/playwright-cli/SKILL.md) | `ui_diff`, `load_check` |
 
-You are an **independent QA** — player + creative director lens; **no production participation**.
+**典型流程（9:16 手机视口）：**
+
+```bash
+playwright-cli open <devUrl>
+playwright-cli resize 390 844
+playwright-cli screenshot --filename=logs/review-<scene>.png
+playwright-cli console
+playwright-cli close
+```
+
+`design_check` 不需要浏览器。MC 比例验证用 `playcraft image info`。
 
 ---
 
-## Five-step review (summary)
+## Review flow (summary)
 
-**Primary L2:** [`refs/reviewer-six-dimension-eval.md`](refs/reviewer-six-dimension-eval.md) — Dev walkthrough tables, **Steps 0–0b**, Phases **1–5**, **six-dimension rubric + scoring**, **veto list**, and **Rework mechanism** (rounds, severity, routing, flow).
+**Primary L2:** [`refs/reviewer-convergence-eval.md`](refs/reviewer-convergence-eval.md) — checklists + `ui_diff` / `load_check` procedures.
 
-| Step  | Scope                                                                                   |
-| ----- | --------------------------------------------------------------------------------------- |
-| **1** | Dev preview + validator skills (Step 0–0b in ref)                                       |
-| **2** | DAG completeness, layout compliance, TA log, ad psychology (Phases 1–2.6)               |
-| **3** | Automated technical checks + build-optimizer skill (Phase 3)                            |
-| **4** | Six-dimension scoring — read ref **from the top** for calibration (Phase 4 + § Scoring) |
-| **5** | DAG revision audit (Phase 5)                                                            |
+| Mode             | Steps                                                              |
+| ---------------- | ------------------------------------------------------------------ |
+| **design_check** | Gate #1 or #2b checklist → pass/fail + routeTo                     |
+| **ui_diff**      | MC paths → devUrl screenshots per scene → compare → UI Diff Report |
+| **load_check**   | devUrl load + console → one screenshot → pass/fail                 |
 
 ---
 
 ## File Access
 
-**Read:** `docs/project-state.md` (entry, Dev Preview, stage), `design-brief.md`, `layout-spec.md`, `atom-plan.json`, `atom-plan.md`, `style-exploration.md`, `logs/designer-log.md`, `logs/ta-log.md`, `logs/developer-log.md`, `assets/images/`, `assets/audio/`, `assets/bundles/` manifests, `game/`.
+**Read:** `docs/project-state.md`, `design-brief.md`, `layout-spec.md`, `atom-plan.json`, `atom-plan.md`, `style-exploration.md`, `logs/designer-log.md`, `logs/ta-log.md`, `logs/developer-log.md`, `assets/images/reference/`, `game/` (code audit only).
 
-**Write:** `logs/review-report.md` (**create**); `docs/project-state.md` (**Progress Checkpoint / handoff only**).
+**Write:** `logs/review-report.md`; `docs/project-state.md` (checkpoint: `uiReviewStatus`, `uiReworkRound`, `loadCheck`, handoff only).
 
 ## Tools
 
-`npm run dev` if needed · `playcraft image info` / `playcraft audio info` · `du` · `playcraft skills list|match` (validator). Details in ref Phase 3.
+**Browser (core):** **`playwright-cli`** — `open` / `resize` / `screenshot` / `console` / `close`. See [Core Skills](#core-skills).
+
+**Dev server:** `npm run dev` if devUrl unreachable.
+
+**Asset audit:** `playcraft image info` (MC ratio check in `design_check`).
 
 ## Output
 
-Use `templates/review-report.template.md`. Include: six-dimension scores + justification; DAG summary + revision audit; layout compliance matrix; technical checks; issues (**critical/major/minor**) with dimension + route; **Action Items** table; verdict; if fail — rework round / forced Gate #3; summary.
+Use `templates/review-report.template.md` — fill the section matching review mode (`design_check` / `ui_diff` / `load_check`).
 
-Afterward update handoff per **Runtime**. On fail: increment `reworkRound` (同步更新 `handoff.rework_round`) — **do not** write `stage` yourself. On pass: `reviewerDevCheck: passed`.
+Afterward update handoff per **Runtime**. **Never** write mainline `stage`.
 
 ## Important Rules
 
 1. **Never modify production files** — only `logs/review-report.md` and `docs/project-state.md` checkpoint.
-2. **Player + blueprint lens** — compare to `design-brief` / MC / layout-spec; not Dev self-check alone.
-3. **Dev walkthrough is mandatory** — `devUrl` UI + gameplay before Phase 4 scores; `devStatus` must be `ready`.
-4. **Actionable issues** — each needs severity, specific fix, and route target; check asset ↔ code closure both ways.
-5. **Vetoes = auto fail** — first-level success, CTA, external requests, missing `game/index.html`.
-6. **`reworkRound` counts review failures**, not "iterations" — fail at `{0,1}` → rework; fail at `2` → forced Gate #3; **minor** issues log only, do not fail on aesthetics alone.
+2. **`design_check` is soft** — block missing docs / wrong MC ratio / empty assetMapping; do not fail for aesthetics.
+3. **`ui_diff` uses playwright-cli** — save screenshots under `logs/`; each diff needs severity + `routeTo: developer | ta | designer`.
+4. **`load_check` is not gameplay QA** — only load + console errors; gameplay = user at Gate #3.
+5. **`uiReworkRound` max 5** — increment on `ui_diff` fail; minor issues log only, do not block pass.
+6. **Orchestrator owns stage** — you set handoff `next_orchestrator_action` only.

package/project-template/.claude/agents/technical-artist.md

@@ -36,15 +36,15 @@ allowedTools:
 2. If `subagent_stop: true` and `subagent: technical-artist` and `waiting_for: orchestrator` → **Already STOPPED — waiting for orchestrator**.
 3. Branch:
 
-| Condition                                 | This round only                                                                                                                                       | On STOP                                                                                          |
-| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `stage: production`, Wave 1 done          | Confirm Production Pipeline Wave 1 = done → Spec Quick-Check → Style Interpretation → bulk → Compliance; ≤5 files → CLI, >5 → `ta-workspace/scripts/` | When all TA atoms `done`: `next_orchestrator_action: "Set stage=integration, invoke @developer"` |
-| `devStatus: blocked_upstream`, routeTo TA | Fix listed paths only → ta-log                                                                                                                        | `next_orchestrator_action: "Re-invoke @developer"`                                               |
-| `stage: rework`, Action Items routeTo TA  | Fix report items at contract paths                                                                                                                    | `next_orchestrator_action: "Re-invoke @developer after integration"`                             |
+| Condition                                   | This round only                                                                                                                                         | On STOP                                                                                      |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `stage: production`, Wave 1 done            | Confirm Wave 1 = done → Spec Quick-Check → Style Interpretation → **Production Plan** → bulk → Compliance; ≤5 files → CLI, >5 → `ta-workspace/scripts/` | When all TA atoms `done`: `next_orchestrator_action: "Set stage=ui_pass, invoke @developer"` |
+| `devStatus: blocked_upstream`, routeTo TA   | Fix listed paths only → ta-log                                                                                                                          | `next_orchestrator_action: "Re-invoke @developer"`                                           |
+| `stage: ui_rework`, Action Items routeTo TA | Fix report items at contract paths                                                                                                                      | `next_orchestrator_action: "Re-invoke @developer after ui_pass/ui_rework"`                   |
 
 4. **Do not** change `stage`. Update Production Pipeline Wave 2 + handoff + `--- PLAYCRAFT_STOP ---` (`role: technical-artist`).
 
-**Track done:** all `assignTo: TA` atoms `done` + Compliance Gate green + atlas/WebP + sidecars per **`refs/ta-atlas-deliverable-standard.md`** + `ta-log.md` manifest complete.
+**Track done:** **Production Plan** complete (Coverage + Atlas Assembly + Risk Checklist all `[x]`); all `assignTo: TA` atoms `done` + Compliance Gate green + atlas/WebP + sidecars per **`refs/ta-atlas-deliverable-standard.md`** + `ta-log.md` manifest complete.
 
 ## Mission
 
@@ -54,13 +54,13 @@ allowedTools:
 
 **Top 3 (in order):** (1) **Style-faithful mass production** from MC / ASR — **do not redefine art direction**. (2) **100% `assetMapping`** — every path, dims/format per `layout-spec`. (3) **Production-grade handoff** — no placeholders; `ta-log.md` + sprite/atlas params complete.
 
-**Success:** Step 0 pass or `spec-gap` filed; Style Interpretation + micro-batch ≥3 before bulk; Compliance green; Developer can verify every path with `playcraft image|audio info`.
+**Success:** Step 0 pass or `spec-gap` filed; Style Interpretation + **Production Plan** (100% assetMapping coverage) before bulk; micro-batch ≥3 before bulk; Compliance green; Developer can verify every path with `playcraft image|audio info`.
 
 **Non-goals:** gameplay design, first-level tuning, **file-size optimization** (build stage), MC/storyboard (Designer), `npm run dev` (Developer).
 
 ## Step 0 (one-liner)
 
-Before generation: complete **`ta-log.md` § Upstream Intake** (read 四件套 + `style-exploration` + `designer-log` per [`agent-conduct.md`](../../docs/team/agent-conduct.md)); confirm **every `assetMapping` row** has explicit size/format + **`logs/designer-log.md`** has composite + Style Intent Notes — else `spec-gap` / `blocked`. Then execute **[`refs/ta-pipeline-cookbook.md`](refs/ta-pipeline-cookbook.md)** (**Step 0a → 0 → 1 → 2**).
+Before generation: complete **`ta-log.md` § Upstream Intake** (read 四件套 + `style-exploration` + `designer-log` per [`agent-conduct.md`](../../docs/team/agent-conduct.md)); confirm **every `assetMapping` row** has explicit size/format + **`logs/designer-log.md`** has composite + Style Intent Notes — else `spec-gap` / `blocked`. Then execute **[`refs/ta-pipeline-cookbook.md`](refs/ta-pipeline-cookbook.md)** (**Step 0 Pre → Step 0a → 0 → 0e → 1 → 2**). **Step 0 Pre (mediaGroups Reuse)** is mandatory — check `skillsMatch.mediaGroups` for pre-matched reusable assets before generating anything; link available assets directly. **Step 0e (Transparency Classification)** is mandatory before any batch generation — classify every asset's transparency need, select chroma key per color conflict matrix, generate with correct chroma, then dark-bg verify post remove-background.
 
 ## Execute (L2)
 
@@ -79,15 +79,19 @@ Before generation: complete **`ta-log.md` § Upstream Intake** (read 四件套 +
 
 ## Compliance Gate (condensed)
 
-| Check             | Pass                                                                                   |
-| ----------------- | -------------------------------------------------------------------------------------- |
-| Atlas group table | `layout-spec.md` atlas grouping table exists → else `spec-gap` routeTo PM              |
-| Coverage          | Every `assetMapping` path exists; dimensions match spec                                |
-| Format            | **WebP** for runtime images / atlases (see atlas ref); **MP3** after TA audio pipeline |
-| Atlases           | Per `layout-spec`: grouped assets → one `.webp` + `.json` where required               |
-| Params            | `ta-log.md` records cols, frameW, frameH, frameCount for every sheet/atlas             |
-| Process           | Style interpretation table in `ta-log.md`; no open TA questions in ICP                 |
-| Isolation         | No undeclared external deps on deliverables                                            |
+| Check              | Pass                                                                                   |
+| ------------------ | -------------------------------------------------------------------------------------- |
+| Atlas group table  | `layout-spec.md` atlas grouping table exists → else `spec-gap` routeTo PM              |
+| Coverage           | Every `assetMapping` path exists; dimensions match spec                                |
+| Format             | **WebP** for runtime images / atlases (see atlas ref); **MP3** after TA audio pipeline |
+| Atlases            | Per `layout-spec`: grouped assets → one `.webp` + `.json` where required               |
+| Params             | `ta-log.md` records cols, frameW, frameH, frameCount for every sheet/atlas             |
+| **Transparency**   | ta-log.md has Transparency Classification table (all rows verified, no `❓`)           |
+| **Alpha channel**  | All transparent assets have `channels=4`; no `channels=3` in transparent deliverables  |
+| **Dark-bg verify** | All transparent assets pass dark-background overlay check (no white/chroma residue)    |
+| **BG full-cover**  | All full-screen backgrounds: edge-to-edge, no fade/vignette/white corners              |
+| Process            | Style interpretation table in `ta-log.md`; no open TA questions in ICP                 |
+| Isolation          | No undeclared external deps on deliverables                                            |
 
 > TA ignores playable **file-size budget**; optimize at Developer `playcraft build`.
 
@@ -101,11 +105,18 @@ When Developer blocks with `routeTo: TA` (or `devStatus: blocked_upstream`): rea
 
 ## Important Rules
 
-1. **Extract first** — Step 0b references before batch generation.
-2. **Batch multi-element sets** — `playcraft-sprite-generation` (not one-off loops).
-3. **`assetMapping` is law** — zero missing or off-path deliveries.
-4. **Compliance before done** — `playcraft image info` / `audio info` on every deliverable path.
-5. **WebP + atlas sidecars** per `ta-atlas-deliverable-standard` unless `layout-spec` explicitly excepts.
-6. **Never modify `game/`** — Developer's domain.
-7. **Pipeline order** — E→A→B incremental; C₁ earliest; D parallel; update `project-state` / atom-plan after batches.
-8. **Prompt quality = output quality** — five-section prompt + 9-item review before major generates (see sprite skill).
+1. **Production Plan before generation** — complete `logs/ta-log.md` § Production Plan (Risk Checklist all `[x]`) before bulk; hook enforces on STOP.
+2. **Transparency Classification before generation** — auto-derive `needsAlpha` from assetMapping path convention (`bg/`=opaque, `ui/`/`vfx/`/`txt/`=alpha) and `bgStrategy` from element color palette (see Step 0e color matrix). Complete Step 0e table before any batch generation. **Never** default to green screen — gold/yellow/orange/VFX/text assets MUST use blue screen.
+3. **Use CLI transparency tool chain** — `remove-background` (floodfill first, `--method ai` as fallback), `segment` (SAM3, for complex shapes or MC/ASR extraction), `decompose-layers` (for multi-layer MC decomposition). Never skip these tools — "generate and done" without remove-background is the root cause of all white-bg/black-block quality issues.
+4. **mediaGroups first, generate second** — read `atom-plan.json` → `skillsMatch.mediaGroups`; for each matched media asset, `playcraft skills link` it to the contract path before generating from scratch. Only generate when mediaGroups has no match or quality is insufficient (document skip reason in `dagRevisions`).
+5. **Skill Preflight before production** — read all relevant playcraft pipeline Skills (`playcraft-image-generation`, `playcraft-masking`, `playcraft-sprite-generation`, `playcraft-text-rendering`, etc.) BEFORE producing any asset. Fill `ta-log.md` § Skill Preflight table. Do not "freelance" — follow the platform's established best practices.
+6. **Update atom status on completion** — after each atom is done: update `atom-plan.json` → `atoms[].status = "done"` + `atoms[].actualOutput = "<path>"`. After writing TA Skill Context: update `atom-plan.md` § TA Skill Context. **Never** leave atoms at `pending` / `actualOutput: null` after delivery.
+7. **Extract first** — Step 0b references before batch generation.
+8. **Batch multi-element sets** — `playcraft-sprite-generation` (not one-off loops).
+9. **`assetMapping` is law** — zero missing or off-path deliveries.
+10. **Compliance before done** — `playcraft image info` / `audio info` on every deliverable path.
+11. **Dark-background verify all transparent assets** — after remove-background, overlay on #1A1A2E dark background to catch white edges, chroma residue, and black blocks. VFX atlas: verify **each frame** individually.
+12. **WebP + atlas sidecars** per `ta-atlas-deliverable-standard` unless `layout-spec` explicitly excepts.
+13. **Never modify `game/`** — Developer's domain.
+14. **Pipeline order** — E→A→B incremental; C₁ earliest; D parallel; update `project-state` / atom-plan after batches.
+15. **Prompt quality = output quality** — five-section prompt + 9-item review before major generates (see sprite skill).

package/project-template/.claude/hooks/README.md

@@ -16,11 +16,19 @@ On failure: exit `2` — PM must fix atom-plan before STOP.
 
 ## `validate-workflow-stop.mjs`
 
-When a **Technical Artist** or **Developer** subagent stops, checks `logs/ta-log.md` or `logs/developer-log.md` § **Upstream Intake**:
+When a **Technical Artist** or **Developer** subagent stops, checks `logs/ta-log.md` or `logs/developer-log.md`:
+
+**§ Upstream Intake**
 
 - Every required doc row has Read ✓
 - Every takeaway is filled (no `{{placeholders}}`, min 8 chars)
 
+**§ Production Plan** (TA) or **§ UI Pass Plan** / **§ Gameplay Pass Plan** (Developer — validated by `stage` in project-state)
+
+- Required subsections present (TA: Coverage / Atlas / Risk; Developer ui_pass: Scene-Asset / Scene navigation / Risk; gameplay_pass: PGS / Risk)
+- Risk Checklist fully checked `[x]`
+- No `{{placeholders}}` in plan section
+
 On failure:
 
 - **Claude Code**: exit `2` + JSON `{"decision":"block","reason":"..."}` — subagent must fix intake before stopping

package/project-template/.claude/hooks/validate-workflow-stop.mjs

@@ -15,6 +15,25 @@ import { fileURLToPath } from 'node:url';
 const __filename = fileURLToPath(import.meta.url);
 
 const INTAKE_HEADING = '## Upstream Intake';
+const PLAN_HEADING = {
+  'technical-artist': '## Production Plan',
+  developer: '## UI Pass Plan', // default; gameplay_pass uses ## Gameplay Pass Plan
+};
+const PLAN_HEADING_BY_STAGE = {
+  developer: {
+    ui_pass: '## UI Pass Plan',
+    ui_rework: '## UI Pass Plan',
+    gameplay_pass: '## Gameplay Pass Plan',
+  },
+};
+const PLAN_REQUIRED_SUBS = {
+  developer: {
+    ui_pass: ['### Scene-Asset Binding Plan', '### Scene navigation', '### Risk Checklist'],
+    ui_rework: ['### Scene-Asset Binding Plan', '### Scene navigation', '### Risk Checklist'],
+    gameplay_pass: ['### PGS Strategy', '### Risk Checklist'],
+  },
+  'technical-artist': ['### Coverage Plan', '### Atlas Assembly Plan', '### Risk Checklist'],
+};
 const PLACEHOLDER_RE = /\{\{[^}]+\}\}/;
 const MIN_TAKEAWAY_LEN = 8;
 
@@ -168,6 +187,65 @@ function validateIntakeContent(content, requiredDocs) {
   return errors;
 }
 
+/**
+ * @param {string} content
+ * @param {'technical-artist' | 'developer'} role
+ * @param {string} [stage]
+ */
+function validatePlan(content, role, stage) {
+  let heading = PLAN_HEADING[role];
+  /** @type {string[]} */
+  let requiredSubs = [];
+
+  if (role === 'developer') {
+    if (stage && PLAN_HEADING_BY_STAGE.developer[stage]) {
+      heading = PLAN_HEADING_BY_STAGE.developer[stage];
+      requiredSubs = PLAN_REQUIRED_SUBS.developer[stage] ?? [];
+    }
+  } else if (role === 'technical-artist') {
+    requiredSubs = PLAN_REQUIRED_SUBS['technical-artist'] ?? [];
+  }
+
+  const errors = [];
+  const start = content.indexOf(heading);
+  if (start === -1) {
+    return [`Missing "${heading}" section — write plan before STOP (stage: ${stage || 'unknown'})`];
+  }
+
+  const after = content.slice(start + heading.length);
+  const nextHeading = after.search(/\n##\s+/);
+  const section = nextHeading === -1 ? after : after.slice(0, nextHeading);
+
+  for (const sub of requiredSubs) {
+    if (!section.includes(sub)) {
+      errors.push(`${heading}: missing ${sub}`);
+    }
+  }
+
+  const checkboxes = section.match(/- \[[ xX]\]/gi) || [];
+  const unchecked = checkboxes.filter((c) => /\[ \]/i.test(c));
+  if (checkboxes.length > 0 && unchecked.length > 0) {
+    errors.push(`${heading} Risk Checklist: ${unchecked.length} unchecked item(s)`);
+  }
+
+  if (PLACEHOLDER_RE.test(section)) {
+    errors.push(`${heading}: contains {{placeholders}} — fill with real data`);
+  }
+
+  return errors;
+}
+
+/** @param {string} projectDir */
+function readStage(projectDir) {
+  const statePath = path.join(projectDir, 'docs/project-state.md');
+  if (!fs.existsSync(statePath)) return null;
+  const content = fs.readFileSync(statePath, 'utf8');
+  const m =
+    content.match(/\*\*(ui_pass|ui_rework|gameplay_pass|production|pm)\*\*/i) ||
+    content.match(/stage[=:\s]+`(ui_pass|ui_rework|gameplay_pass|production|pm)`/i);
+  return m ? m[1].toLowerCase() : null;
+}
+
 /**
  * @param {string} projectDir
  * @param {'technical-artist' | 'developer'} role
@@ -183,7 +261,10 @@ function validateRole(projectDir, role) {
   }
 
   const content = fs.readFileSync(logPath, 'utf8');
-  return validateIntakeContent(content, cfg.docs);
+  const intakeErrors = validateIntakeContent(content, cfg.docs);
+  const stage = role === 'developer' ? readStage(projectDir) : undefined;
+  const planErrors = validatePlan(content, role, stage ?? undefined);
+  return [...intakeErrors, ...planErrors];
 }
 
 /** @param {string} projectDir */
@@ -214,9 +295,13 @@ export {
   detectRole,
   parseUpstreamIntake,
   validateIntakeContent,
+  validatePlan,
   validateRole,
+  readStage,
   TA_REQUIRED_DOCS,
   DEV_REQUIRED_DOCS,
+  PLAN_HEADING,
+  PLAN_REQUIRED_SUBS,
 };
 
 async function main() {

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

@@ -1,4 +1,8 @@
 {
+  "defaultMode": "acceptEdits",
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  },
   "hooks": {
     "SubagentStop": [
       {

package/project-template/.claude/skills/playcraft-image-generation/SKILL.md

@@ -135,7 +135,18 @@ playcraft tools generate-image \
 
 > **IEGG LiteLLM** 在 fallback 链中排第一，但 Azure gpt-image 最大约 1536px 宽 — 达不到 5×9:16 横排。故事板请用 **`mulerouter/gpt-image-2`**（跳过 litellm）+ `--width 3600 --height 1280`（或 4096×1455）。
 
-**Phase 1（概念图）**：纯文生图，`--image-size 4K` + 优先 gpt-image-2 追求质量。
+### Master Composite（MC）模型白名单
+
+Designer 生成 MC 时**不得**套用上方通用决策树里的 gemini / flux / hy-image 等——MC 只允许：
+
+| 允许                       | 禁止（MC）                                          |
+| -------------------------- | --------------------------------------------------- |
+| `mulerouter/gpt-image-2`   | `gemini-*`、`flux-*`、`hy-image-*`、`wan*`、`qwen*` |
+| `mulerouter/nano-banana-2` | 裸 `gpt-image-2`（会走 iegg-litellm 压扁五格）      |
+
+完整 prompt / 尺寸规范见 **`playcraft-storyboard`** skill。ASR 双板 `--image-model` 须与已选 MC **完全一致**。
+
+**Phase 1（概念图）**：纯文生图，`--image-size 4K` + MC 白名单内模型。
 **Phase 2（批量生产）**：必须带 `--reference-image` 指向 Phase 1 确认的概念图，同一批次使用**相同模型 + 相同 reference image + 相同 image-size**。
 
 ### --reference-image 路径支持
@@ -172,17 +183,24 @@ playcraft image sprite-sheet \
 
 ## 3. 背景处理决策树
 
-> **核心原则**：先确定素材类型，再决定是否需要去背景，再决定 prompt 应该写什么。
+> **核心原则**：先确定素材类型，再决定是否需要去背景，再按素材主色调选择色幕颜色，最后做去背景 + 深色背景验证。
 
 ```
 生成的素材需要做什么？
 │
-├─ 需要透明背景的独立元素（角色、道具、图标）？
+├─ 需要透明背景的独立元素（角色、道具、图标、文字图片、HUD、VFX）？
 │   ├─ 检查模型 ALPHA 列（playcraft tools list-image-models）
 │   ├─ ALPHA = yes → prompt 加 "transparent background, PNG with alpha"
-│   └─ ALPHA = no  → 绿幕策略：
-│       ├─ prompt 末尾加 "on solid bright green #00FF00 background, isolated, centered"
-│       └─ 后处理：remove-background（floodfill，tolerance 25）
+│   └─ ALPHA = no  → 色幕策略（按素材主色调选择）：
+│       ├─ 素材为金色/黄色/橙色/绿色 → 蓝幕 #0000FF
+│       │   ├─ prompt 末尾加 "on solid bright blue #0000FF background, isolated, centered"
+│       │   └─ 后处理：remove-background（tolerance 25）→ 深色背景验证
+│       ├─ 素材为蓝色/紫色/靛蓝 → 绿幕 #00FF00
+│       │   ├─ prompt 末尾加 "on solid bright green #00FF00 background, isolated, centered"
+│       │   └─ 后处理：remove-background（tolerance 25）→ 深色背景验证
+│       └─ 其他颜色 → 绿幕 #00FF00（默认）
+│           ├─ prompt 末尾加 "on solid bright green #00FF00 background, isolated, centered"
+│           └─ 后处理：remove-background（tolerance 25）→ 深色背景验证
 │
 ├─ 卡牌/棋盘格子/UI 面板（本身就是矩形有边框）？
 │   ├─ 不要去背景！白色牌面就是牌的一部分
@@ -190,21 +208,53 @@ playcraft image sprite-sheet \
 │   └─ 后处理：直接 resize（skipRemoveBg = true）
 │
 └─ 场景背景（天空、地面、全屏图）？
-    └─ 不做背景处理，直接 resize
+    ├─ 不做背景处理，直接 resize
+    └─ ⚠️ prompt 必须加 "full bleed, edge to edge, no vignette, no fade"
+       → 后处理验证：四角四边颜色一致，无褪色/白色
 ```
 
-### 为什么需要绿幕策略？
+### 为什么需要色幕策略？
+
+**当前所有已接入模型均不支持原生透明 PNG（ALPHA = no）**。白色背景 + 白色物体 = floodfill 无法区分边界。纯色背景 + 非撞色游戏素材 = 抠图几乎完美。与影视 chroma-key 原理相同。
+
+### 色幕选型矩阵（Color Conflict Avoidance）
+
+> ⚠️ **不要默认全用绿幕！** 金色素材 + 绿幕 = 绿色与金色色相接近，floodfill 会在边缘残留绿色，或误删金色像素。
 
-**当前所有已接入模型均不支持原生透明 PNG（ALPHA = no）**。白色背景 + 白色物体 = floodfill 无法区分边界。绿色背景 + 任何游戏素材 = 极少撞色，抠图几乎完美。与影视 chroma-key 原理相同。
+| 素材主色调            | ❌ 禁用 | ✅ 推荐          | 原因                                       |
+| --------------------- | ------- | ---------------- | ------------------------------------------ |
+| 金色/黄色/橙色/琥珀色 | 绿幕    | **蓝幕 #0000FF** | 金色与绿色色相接近（黄绿区），边缘残留绿色 |
+| 绿色/翠绿/青色        | 绿幕    | **蓝幕 #0000FF** | 同色系，无法区分边界                       |
+| 蓝色/靛蓝/紫色        | 蓝幕    | **绿幕 #00FF00** | 同色系冲突                                 |
+| 红色/粉色/白色/黑色   | —       | 绿幕或蓝幕均可   | 与两者色相距离都大                         |
+| 多色/彩虹             | —       | **品红 #FF00FF** | 品红在自然素材中最少出现（最后手段）       |
 
 ### Prompt 后缀速查表
 
-| 素材类型              | prompt 建议后缀                                                     | 后处理                           | skipRemoveBg |
-| --------------------- | ------------------------------------------------------------------- | -------------------------------- | ------------ |
-| 独立元素（需透明）    | `"on solid bright green #00FF00 background, isolated, centered"`    | remove-background (tolerance 25) | `false`      |
-| 卡牌/棋子（矩形本体） | `"flat 2D, no shadow, no 3D effect, clean edges, white background"` | 只做 resize                      | `true`       |
-| UI 按钮/面板          | `"flat UI element, no shadow, clean edges"`                         | trim + resize                    | `true`       |
-| 场景背景              | `"full scene, edge to edge"`                                        | 只做 resize                      | `true`       |
+| 素材类型                   | prompt 建议后缀                                                     | 后处理                                      | skipRemoveBg |
+| -------------------------- | ------------------------------------------------------------------- | ------------------------------------------- | ------------ |
+| 独立元素（需透明，非金色） | `"on solid bright green #00FF00 background, isolated, centered"`    | remove-background (tolerance 25) → 深色验证 | `false`      |
+| 独立元素（金/黄/橙/绿色）  | `"on solid bright blue #0000FF background, isolated, centered"`     | remove-background (tolerance 25) → 深色验证 | `false`      |
+| 独立元素（多色/彩虹）      | `"on solid bright magenta #FF00FF background, isolated, centered"`  | remove-background (tolerance 20) → 深色验证 | `false`      |
+| VFX 特效（发光/粒子）      | `"on solid bright blue #0000FF background, isolated, centered"`     | remove-background (tolerance 25) → 逐帧验证 | `false`      |
+| 卡牌/棋子（矩形本体）      | `"flat 2D, no shadow, no 3D effect, clean edges, white background"` | 只做 resize                                 | `true`       |
+| UI 按钮/面板               | `"flat UI element, no shadow, clean edges"`                         | trim + resize                               | `true`       |
+| 场景背景                   | `"full scene, full bleed, edge to edge, no vignette, no fade"`      | resize → 四角全覆盖检查                     | `true`       |
+
+### 去背景后必做：深色背景渲证
+
+> 每个需要透明的资产，去背景后**必须**在深色背景上叠合验证。这一步是防止白底/色幕残留/黑块的最后防线。
+
+```bash
+playcraft image overlay \
+  --base ta-workspace/tmp/dark_verify_bg.png \
+  --overlay <processed>.png \
+  --output ta-workspace/tmp/verify_<name>.png \
+  --gravity center
+# 目视检查：无白边、无色幕残留色、无黑色不透明块、边缘干净
+```
+
+**不通过时的修复**：见 `ta-pipeline-cookbook.md` Step 0e §3 及 Compliance Gate 失败修复表。
 
 ---
 

package/project-template/.claude/skills/playcraft-storyboard/SKILL.md

@@ -91,10 +91,23 @@ Total image exactly [3600] pixels wide by [1280] pixels tall (five 720x1280 cell
 
 ## 3. 生成命令
 
+### MC 模型白名单（强制）
+
+Master Composite **只允许**下列高质量模型（须带 **provider 前缀**，禁止裸模型名）：
+
+| 用途     | `--image-model`            | 说明                                              |
+| -------- | -------------------------- | ------------------------------------------------- |
+| **首选** | `mulerouter/gpt-image-2`   | 细节、光影、复杂 UI；默认 Option A                |
+| **备选** | `mulerouter/nano-banana-2` | Gemini 3.1 Flash Image；Option B/C 或需不同画风时 |
+
+**禁止**用于 MC：`gemini-*`、`flux-*`、`hy-image-*`、`wan*`、`qwen*`、裸 `gpt-image-2`、以及 `list-image-models` 中未列入上表的模型。
+
+多方案（A/B/C）应用 **不同 prompt / 美术方向** 探索，**不得**用低档模型换方案——质量门槛对所有 MC 选项相同。
+
 ```bash
 playcraft tools generate-image \
   --prompt "<Section 2>" \
-  --output assets/images/storyboard/master_composite_option_[N].png \
+  --output assets/images/storyboard/master_composite_option_A.png \
   --image-model mulerouter/gpt-image-2 \
   --aspect-ratio 45:16 \
   --image-size 2K \
@@ -102,15 +115,21 @@ playcraft tools generate-image \
   --height 1280
 ```
 
-> **必须**使用 `mulerouter/gpt-image-2`（或已配置的 `302/...`）。**禁止**裸 `gpt-image-2`——fallback 会先走 `iegg-litellm`，成功时只能出 **1536×1024**，五格竖屏会被压扁。CLI 会在保存后自动校验像素，不合格直接失败。
+Option B 示例（仍须白名单内）：
+
+```bash
+  --image-model mulerouter/nano-banana-2 \
+```
+
+> **必须**带 `mulerouter/` 前缀。**禁止**裸 `gpt-image-2`——fallback 会先走 `iegg-litellm`，成功时只能出 **1536×1024**，五格竖屏会被压扁。CLI 会在保存后自动校验像素，不合格直接失败。
 
 **4K 档**：`--image-size 4K --width 4096 --height 1455`
 
-| 参数                   | 要求                                                  |
-| ---------------------- | ----------------------------------------------------- |
-| `--aspect-ratio`       | **`45:16`**（5 个 9:16 横排）；**禁止 `1:1`、`10:3`** |
-| `--width` / `--height` | **3600×1280**（2K）或 **4096×1455**（4K）             |
-| `--image-model`        | **`mulerouter/gpt-image-2`**（强制，勿用裸模型名）    |
+| 参数                   | 要求                                                                                      |
+| ---------------------- | ----------------------------------------------------------------------------------------- |
+| `--aspect-ratio`       | **`45:16`**（5 个 9:16 横排）；**禁止 `1:1`、`10:3`**                                     |
+| `--width` / `--height` | **3600×1280**（2K）或 **4096×1455**（4K）                                                 |
+| `--image-model`        | **`mulerouter/gpt-image-2`** 或 **`mulerouter/nano-banana-2`** only（强制 provider 前缀） |
 
 ### 生成后验收（强制）