@playcraft/cli 0.0.41 → 0.0.42

package/project-template/templates/layout-spec.template.md

@@ -88,6 +88,9 @@ Each elementId in assetMapping uses atlasPath + frameId OR single visualAsset pa
 | -------------- | ------------------------------------- | ------- | ------------------------------------- |
 | {{element_id}} | assets/images/tiles/tiles_atlas.webp  | tile_01 | {{sfx_path_or_dash}}                  |
 | —              | assets/images/bg/{{bg_filename}}.webp | —       | —                                     |
+| —              | assets/images/ui/{{ui_element}}.webp  | —       | —                                     |
+| —              | assets/images/txt/{{text}}.webp       | —       | —                                     |
+| —              | assets/images/vfx/{{vfx}}.webp        | —       | —                                     |
 | —              | —                                     | —       | assets/audio/sfx/{{sfx_filename}}.mp3 |
 | —              | —                                     | —       | assets/audio/bgm/{{bgm_filename}}.mp3 |
 
@@ -97,6 +100,17 @@ CRITICAL: This mapping is the integration contract!
 - Developer references EXACTLY these paths in code
 - Path mismatch = integration failure
 - Use "—" for cells that don't apply
+
+Transparency convention (TA auto-derives from path — PM does NOT define):
+  assets/images/bg/   → opaque, full-screen background (TA verifies edge-to-edge)
+  assets/images/ui/   → needs alpha (TA applies chroma key + remove-background)
+  assets/images/txt/  → needs alpha (TA applies chroma key + remove-background)
+  assets/images/vfx/  → needs alpha (TA applies chroma key + remove-background)
+  assets/images/tiles/ → needs alpha by default (except card faces / board pieces)
+  assets/audio/       → N/A (not image)
+
+TA determines chroma key color (green/blue/magenta) based on element color palette
+and color conflict rules — see ta-pipeline-cookbook.md Step 0e.
 -->
 
 ## Text Assets

package/project-template/templates/project-state.template.md

@@ -4,11 +4,11 @@
 
 | Field                   | Value                                                                 |
 | ----------------------- | --------------------------------------------------------------------- |
-| **workflowSpecVersion** | `production-serial-v1`                                                |
+| **workflowSpecVersion** | `convergence-v1`                                                      |
 | **Changelog**           | [docs/team/workflow-changelog.md](../docs/team/workflow-changelog.md) |
 
 <!--
-  production-serial-v1: Gate #2b → production Wave 1 Designer Ph.2 → Wave 2 TA → integration Developer.
+  convergence-v1: Three convergence loops — design_check (Gate #1/#2b) → ui_pass/ui_review/ui_rework → gameplay_pass/load_check → Gate #3.
   Visual baseline (designer-handoff-v2): Phase 1 = MC + ASR; Phase 2 Designer = audio + digit strip + VisualAtom status only.
 -->
 
@@ -32,7 +32,7 @@
 
 **{{current_stage}}** — {{stage_description}}
 
-`pm` → `style_exploration` → `production` → `integration` → `review` ⇄ `rework` → `done`
+`pm` → `style_exploration` → `production` → `ui_pass` → `ui_review` ⇄ `ui_rework` → `gameplay_pass` → `done`
 
 <!-- Stage definitions: see CLAUDE.md § Stage Model -->
 
@@ -40,12 +40,12 @@
 
 > Only the **orchestrator** runs `AskUserQuestion` toward the user. Sub-agents set `pending` and STOP.
 
-| Gate               | Status             | Notes                                                                           |
-| ------------------ | ------------------ | ------------------------------------------------------------------------------- |
-| #1 Direction       | {{passed/pending}} | Orchestrator confirms after PM four docs + STOP                                 |
-| #2a MC selection   | {{passed/pending}} | Orchestrator picks A/B/C → sets `selectedMcOption` below                        |
-| #2b MC + ASR final | {{passed/pending}} | Orchestrator confirms MC + ASR sheets (UI + element) → then `stage: production` |
-| #3 Dev acceptance  | {{passed/pending}} | User opens devUrl (orchestrator link only)                                      |
+| Gate               | Status             | Notes                                                                        |
+| ------------------ | ------------------ | ---------------------------------------------------------------------------- |
+| #1 Direction       | {{passed/pending}} | Orchestrator confirms after PM four docs + Reviewer design_check + STOP      |
+| #2a MC selection   | {{passed/pending}} | Orchestrator picks A/B/C → sets `selectedMcOption` below                     |
+| #2b MC + ASR final | {{passed/pending}} | Reviewer design_check → Orchestrator confirms MC + ASR → `stage: production` |
+| #3 Dev acceptance  | {{passed/pending}} | Reviewer load_check pass → user opens devUrl (orchestrator link only)        |
 
 ## Agent handoff
 
@@ -82,13 +82,21 @@ Designer Gate #2a STOP:
   next_orchestrator_action: "Run Gate #2a"
   last_completed_by: designer
 
-Developer integration STOP:
+Developer ui_pass STOP:
   subagent: developer
   subagent_stop: true
   waiting_for: orchestrator
   gate_pending: null
-  next_orchestrator_action: "Invoke @reviewer"
+  next_orchestrator_action: "Invoke @reviewer ui_diff"
   last_completed_by: developer
+
+Reviewer ui_diff pass STOP:
+  subagent: reviewer
+  subagent_stop: true
+  waiting_for: orchestrator
+  gate_pending: null
+  next_orchestrator_action: "Set stage=gameplay_pass, invoke @developer"
+  last_completed_by: reviewer
 -->
 
 ## Gate resume fields
@@ -96,30 +104,40 @@ Developer integration STOP:
 | Field            | Value                                              |
 | ---------------- | -------------------------------------------------- |
 | selectedMcOption | {{A / B / C — set by orchestrator after Gate #2a}} |
-| reworkRound      | {{0 / 1 / 2 — incremented by Reviewer on fail}}    |
+| uiReworkRound    | {{0–5 — incremented by Reviewer on ui_diff fail}}  |
 
 ## Dev Preview
 
-| Field            | Value                                                                        |
-| ---------------- | ---------------------------------------------------------------------------- |
-| devCommand       | npm run dev                                                                  |
-| devScript        | {{from package.json scripts.dev}}                                            |
-| devUrl           | {{http://... — Developer records when ready; orchestrator uses for Gate #3}} |
-| devStatus        | pending / ready / blocked_upstream / failed                                  |
-| devBlockers      | {{list: assetPath, issue, routeTo (TA/Designer/PM), status}}                 |
-| devStartedBy     | developer / reviewer / orchestrator                                          |
-| devLastChecked   | {{ISO timestamp}}                                                            |
-| reviewerDevCheck | pending / passed / failed                                                    |
-| reviewerDevNotes | {{UI + gameplay check summary}}                                              |
+| Field          | Value                                                                        |
+| -------------- | ---------------------------------------------------------------------------- |
+| devCommand     | npm run dev                                                                  |
+| devScript      | {{from package.json scripts.dev}}                                            |
+| devUrl         | {{http://... — Developer records when ready; orchestrator uses for Gate #3}} |
+| devStatus      | pending / ui_ready / ready / blocked_upstream / failed                       |
+| devBlockers    | {{list: assetPath, issue, routeTo (TA/Designer/PM), status}}                 |
+| devStartedBy   | developer / reviewer / orchestrator                                          |
+| devLastChecked | {{ISO timestamp}}                                                            |
+| loadCheck      | pending / passed / failed                                                    |
+| loadCheckNotes | {{console errors, white screen, load time}}                                  |
+
+## UI Review
+
+| Field            | Value                                      |
+| ---------------- | ------------------------------------------ |
+| uiReviewStatus   | pending / passed / failed                  |
+| uiReworkRound    | {{0–5}}                                    |
+| uiDiffReportPath | logs/review-report.md                      |
+| uiDiffNotes      | {{summary of MC vs screenshot comparison}} |
 
 <!--
 devStatus:
-  pending           — integration not finished
-  ready             — Developer self-check passed, no open blockers; safe to invoke Reviewer
+  pending           — ui_pass or gameplay_pass not finished
+  ui_ready          — UI shell complete (scene switch, layout, simple states); safe to invoke Reviewer ui_diff
+  ready             — gameplay_pass complete; safe to invoke Reviewer load_check
   blocked_upstream  — Developer waiting on TA/Designer rework (orchestrator re-invokes)
   failed            — dev server could not start; document error
 
-Developer MUST NOT set ready while devBlockers has open items.
+Developer MUST NOT set ui_ready/ready while devBlockers has open items.
 -->
 
 ## File Index
@@ -164,21 +182,21 @@ Developer MUST NOT set ready while devBlockers has open items.
 
 ### Reviewer Output
 
-| File                                                      | Description                                      | Status     |
-| --------------------------------------------------------- | ------------------------------------------------ | ---------- |
-| [review-report.md](logs/review-report.md)                 | Six-dimension evaluation + Dev walkthrough notes | {{status}} |
-| [intent-clarifications.md](docs/intent-clarifications.md) | Agent-to-agent Q&A (ICP)                         | {{status}} |
+| File                                                      | Description                                 | Status     |
+| --------------------------------------------------------- | ------------------------------------------- | ---------- |
+| [review-report.md](logs/review-report.md)                 | design_check / ui_diff / load_check reports | {{status}} |
+| [intent-clarifications.md](docs/intent-clarifications.md) | Agent-to-agent Q&A (ICP)                    | {{status}} |
 
 ## Production Pipeline (Serial)
 
-<!-- Only relevant when stage = production or transitioning to integration -->
+<!-- Only relevant when stage = production or transitioning to ui_pass -->
 
 | Wave | Agent            | Status     | Notes                                      |
 | ---- | ---------------- | ---------- | ------------------------------------------ |
 | 1    | Designer         | {{status}} | Ph.2: audio + digit + VisualAtom status    |
 | 2    | Technical Artist | {{status}} | Spec Quick-Check → bulk → Compliance green |
 
-<!-- Wave 3 Developer runs in stage = integration only — not tracked here -->
+<!-- Wave 3 Developer runs in stage = ui_pass — not tracked here -->
 
 ## Intent Clarification Tracking
 
@@ -203,7 +221,7 @@ PM monitors this table:
 Orchestrator serial rules:
   - Gate #2b passed → invoke @designer only (Wave 1)
   - Wave 1 = done → invoke @technical-artist (Wave 2)
-  - Wave 2 = done → stage: integration → invoke @developer
+  - Wave 2 = done → stage: ui_pass → invoke @developer
   - Optional: 30s spot-check ta-log Compliance + contract paths exist before @developer
 -->
 

package/project-template/templates/review-report.template.md

@@ -1,166 +1,91 @@
 # Review Report
 
+> Fill **one section** matching the review mode orchestrator invoked: `design_check` | `ui_diff` | `load_check`.
+
+## Review Mode
+
+**{{design_check / ui_diff / load_check}}** — {{ISO timestamp}}
+
 ## Verdict
 
-**{{pass/conditional-pass/fail}}** — Total Score: {{total}}/30
-
-## Six-Dimension Scores
-
-| Dimension               | Score     | Details                 |
-| ----------------------- | --------- | ----------------------- |
-| Experience Flow         | {{1-5}}/5 | {{specific_evaluation}} |
-| Creative Appeal         | {{1-5}}/5 | {{specific_evaluation}} |
-| Style Consistency       | {{1-5}}/5 | {{specific_evaluation}} |
-| Intent Fidelity         | {{1-5}}/5 | {{specific_evaluation}} |
-| Difficulty Balance      | {{1-5}}/5 | {{specific_evaluation}} |
-| **Intent Transmission** | {{1-5}}/5 | {{specific_evaluation}} |
-
-<!--
-Scoring guide:
-5 — Excellent: exceeds expectations, ready to ship
-4 — Good: meets standard, minor tweaks then ship
-3 — Acceptable: basically works, needs improvement
-2 — Below standard: obvious problems, partial redo
-1 — Seriously deficient: directional error, full redo
-
-Pass thresholds (6 dimensions × 5 max = 30):
->= 24: Pass (avg 4.0 per dimension)
-18-23: Conditional pass (fix issues then re-review)
-< 18: Fail (route back to responsible agents)
-
-Intent Transmission scoring:
-5 — Zero open clarifications, TA self-check all pass, Developer mapping complete
-4 — 1-2 resolved clarifications, no impact on quality
-3 — Unresolved clarifications exist, or TA has low-confidence items
-2 — Multiple unresolved clarifications, or Developer missing visual mapping
-1 — Severe intent transmission failure, downstream agents made major wrong assumptions
--->
-
-## DAG Coverage
-
-| Metric                              | Value                    |
-| ----------------------------------- | ------------------------ |
-| Total atoms                         | {{total}}                |
-| Completed                           | {{completed}}            |
-| Skipped                             | {{skipped}}              |
-| Blocked                             | {{blocked}}              |
-| Missing (not in plan but should be) | {{missing_list_or_none}} |
-
-## DAG Revision Audit
-
-| Revision            | Agent     | Type                  | Reasonable?             | Notes          |
-| ------------------- | --------- | --------------------- | ----------------------- | -------------- |
-| {{revision_number}} | {{agent}} | {{add/remove/modify}} | {{yes/no/questionable}} | {{assessment}} |
-
-<!--
-Assess each revision:
-- Was the change necessary?
-- Was the reason documented?
-- Did it deviate from original intent?
-- Would it have been better to escalate?
--->
-
-## Layout Spec Compliance
-
-| Check                             | Pass?      | Details     |
-| --------------------------------- | ---------- | ----------- |
-| Asset sizes match `assetSpec`     | {{yes/no}} | {{details}} |
-| Filenames match `assetMapping`    | {{yes/no}} | {{details}} |
-| Color palette followed            | {{yes/no}} | {{details}} |
-| Element IDs aligned in code       | {{yes/no}} | {{details}} |
-| Grid config matches zones         | {{yes/no}} | {{details}} |
-| Zone coordinates in scene correct | {{yes/no}} | {{details}} |
-| Binding completeness              | {{yes/no}} | {{details}} |
-| Bidirectional closure             | {{yes/no}} | {{details}} |
-
-## Technical Checks
-
-| Check               | Pass?      | Value           | Standard                     |
-| ------------------- | ---------- | --------------- | ---------------------------- |
-| Total file size     | {{yes/no}} | {{actual_size}} | <= 5MB (ideal <= 2MB)        |
-| External requests   | {{yes/no}} | {{count}}       | 0                            |
-| CTA implementation  | {{yes/no}} | —               | Click triggers store/install |
-| Entry file exists   | {{yes/no}} | —               | game/index.html present      |
-| Viewport meta       | {{yes/no}} | —               | user-scalable=no             |
-| Orientation support | {{yes/no}} | —               | At least portrait            |
-
-## Veto Items
-
-<!-- These cause automatic FAIL regardless of score -->
-
-- [ ] First level guarantees player success
-- [ ] CTA is implemented and functional
-- [ ] Zero external network requests
-- [ ] Entry file (game/index.html) exists
-
-## Issues
-
-| #     | Severity                 | Dimension     | Description       | Suggestion     | Route To                     |
-| ----- | ------------------------ | ------------- | ----------------- | -------------- | ---------------------------- |
-| {{n}} | {{critical/major/minor}} | {{dimension}} | {{what_is_wrong}} | {{how_to_fix}} | {{PM/Designer/TA/Developer}} |
-
-<!--
-Severity levels:
-- critical: Blocks delivery, must fix
-- major: Significantly impacts quality, should fix
-- minor: Polish item, nice to fix
-
-Every issue MUST have:
-1. Specific description (not vague)
-2. Actionable fix suggestion
-3. Clear routing to responsible agent
--->
-
-## Action Items
-
-<!--
-Aggregated from Issues table above.
-Grouped by target agent for easy handoff.
--->
-
-### For PM
-
-| #     | Issue Ref      | Action Required     | Priority            |
-| ----- | -------------- | ------------------- | ------------------- |
-| {{n}} | Issue #{{ref}} | {{specific_action}} | {{high/medium/low}} |
-
-### For Designer
+**{{pass / fail}}**
 
-| #     | Issue Ref      | Action Required     | Priority            |
-| ----- | -------------- | ------------------- | ------------------- |
-| {{n}} | Issue #{{ref}} | {{specific_action}} | {{high/medium/low}} |
+---
 
-### For Technical Artist
+## design_check (Gate #1 / #2b)
 
-| #     | Issue Ref      | Action Required     | Priority            |
-| ----- | -------------- | ------------------- | ------------------- |
-| {{n}} | Issue #{{ref}} | {{specific_action}} | {{high/medium/low}} |
+### Gate
 
-### For Developer
+**{{#1 / #2b}}**
 
-| #     | Issue Ref      | Action Required     | Priority            |
-| ----- | -------------- | ------------------- | ------------------- |
-| {{n}} | Issue #{{ref}} | {{specific_action}} | {{high/medium/low}} |
+### Checklist
 
-## Rework Status
+| Item               | Pass?      | Notes       |
+| ------------------ | ---------- | ----------- |
+| {{checklist item}} | {{yes/no}} | {{details}} |
 
-<!-- Only fill if verdict is not "pass" -->
+### Missing / defects
 
-| Field                    | Value                             |
-| ------------------------ | --------------------------------- |
-| Rework round             | {{1st / 2nd / N/A}}               |
-| Force Gate #3?           | {{yes (2nd round exceeded) / no}} |
-| Previous issues resolved | {{list resolved issue #s}}        |
+| #     | Issue           | routeTo       |
+| ----- | --------------- | ------------- |
+| {{n}} | {{description}} | pm / designer |
 
-## Summary
+### Outcome
+
+{{pass → Run Gate / fail → re-invoke agent}}
+
+---
+
+## ui_diff (MC screenshot comparison)
+
+### devUrl
+
+{{http://...}}
+
+### Scene comparisons
+
+| Scene | Screenshot            | MC reference | Severity                 | Match?     | routeTo                   | Fix suggestion |
+| ----- | --------------------- | ------------ | ------------------------ | ---------- | ------------------------- | -------------- |
+| hook  | logs/ui-diff-hook.png | {{mc path}}  | {{critical/major/minor}} | {{yes/no}} | {{developer/ta/designer}} | {{fix}}        |
+
+### Summary
+
+- **uiReworkRound**: {{0–5}}
+- **Blocking issues**: {{count critical + major}}
+- **Minor only**: {{yes/no — does not block pass}}
+
+### Action Items
 
-{{overall_assessment_paragraph}}
+| #     | Severity     | routeTo   | Action           |
+| ----- | ------------ | --------- | ---------------- |
+| {{n}} | {{severity}} | {{agent}} | {{specific fix}} |
+
+---
+
+## load_check (pre-Gate #3)
+
+### devUrl
+
+{{http://...}}
+
+### Checks
+
+| Check                  | Pass?      | Notes                     |
+| ---------------------- | ---------- | ------------------------- |
+| Page loads ≤10s        | {{yes/no}} | {{load time}}             |
+| No console Error logs  | {{yes/no}} | {{error summary or none}} |
+| game/index.html exists | {{yes/no}} | —                         |
+
+### Screenshot
+
+`logs/load-check.png`
+
+### Outcome
+
+{{pass → Run Gate #3 / fail → route Developer}}
+
+---
+
+## Summary
 
-<!--
-Include:
-- Overall impression from player perspective
-- Strongest dimension
-- Weakest dimension
-- Key recommendation for next iteration
-- Whether re-review is needed after fixes
--->
+{{one paragraph overall assessment for this review mode}}

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

@@ -30,6 +30,46 @@
 - **Designer samples received**: {{designer_sample_count}} files
 - **TA-completed elements**: {{ta_completed_count}} files
 
+---
+
+## mediaGroups Reuse
+
+> **Step 0 Pre — mandatory before Skill Discovery.** Check `atom-plan.json` → `skillsMatch.mediaGroups` for pre-matched reusable assets.
+
+| mediaGroup atomId | Matches TA atom? | Disposition   | Reason (if skipped)      | Output path (if linked) |
+| ----------------- | ---------------- | ------------- | ------------------------ | ----------------------- |
+| {{mg_atomId}}     | {{atom_id / —}}  | linked / skip | {{style mismatch / N/A}} | {{path / —}}            |
+
+<!--
+  For each mediaGroup entry:
+    - "linked" = used the pre-matched asset → playcraft skills link → post-process → status=done
+    - "skip" = quality/style mismatch → document reason → generate from scratch
+  This section MUST be filled before proceeding to Step 0 Skill Discovery.
+-->
+
+---
+
+## Skill Preflight
+
+> **Step 0 Part C — mandatory before production.** Read all relevant playcraft pipeline Skills.
+
+| Skill                       | 已读 | 关键决策摘要                                              |
+| --------------------------- | ---- | --------------------------------------------------------- |
+| playcraft-image-generation  | ☐    | {{model choice, reference-image strategy, background}}    |
+| playcraft-masking           | ☐    | {{floodfill tolerance, segment fallback, method-ai case}} |
+| playcraft-sprite-generation | ☐    | {{single-frame→merge workflow, batch threshold}}          |
+| playcraft-text-rendering    | ☐    | {{blue screen for text, stroke protection}}               |
+| playcraft-vfx-animation     | ☐    | {{per-frame generation, blue screen for VFX}}             |
+| playcraft-batch-pipeline    | ☐    | {{>5 elements → script, reference anchoring}}             |
+| playcraft-style-qa          | ☐    | {{dark-bg verify, MC consistency check}}                  |
+
+<!--
+  MUST be filled before Step 1 bulk generation. Each row: ✅ after reading + one-line decision summary.
+  Without this table → no bulk generation → no STOP.
+-->
+
+---
+
 ## Style Interpretation
 
 > **Step 0c — Mandatory before any completion work.**
@@ -48,6 +88,93 @@ Confidence rules:
 Do NOT proceed with any asset type where confidence = low.
 -->
 
+## Production Plan
+
+> **Step 0d — mandatory before any asset generation.** Plan WHAT to produce, in WHAT order, using WHAT pipeline.
+
+### Coverage Plan
+
+| assetMapping id | Contract path             | Pipeline               | Reference source  | Priority        |
+| --------------- | ------------------------- | ---------------------- | ----------------- | --------------- |
+| {{elementId}}   | {{path from layout-spec}} | {{extract/generate/…}} | {{MC/ASR/sample}} | {{high/normal}} |
+
+<!--
+One row per layout-spec assetMapping entry. Row count must match assetMapping count (no gaps).
+-->
+
+### Atlas Assembly Plan
+
+| Atlas group | Output path (.webp + .json)     | Elements (frameIds)  | Layout       |
+| ----------- | ------------------------------- | -------------------- | ------------ |
+| {{tiles}}   | {{assets/images/tiles/…_atlas}} | {{tile_01..tile_06}} | {{3x2 grid}} |
+
+<!--
+Must match layout-spec § atlas grouping table.
+-->
+
+### Pipeline Order
+
+1. Extract: crop MC/ASR reference elements (Stage E)
+2. Complete: batch generate remaining elements (Stage A)
+3. Process: resize + format convert to WebP (Stage B)
+4. Assemble: build atlases with JSON sidecars (Stage C)
+5. Verify: Compliance Gate on all paths
+
+### Risk Checklist
+
+- [ ] Every assetMapping entry in Coverage Plan (no gaps)
+- [ ] Atlas groups match layout-spec grouping table
+- [ ] MC + ASR reference images accessible
+- [ ] Style Interpretation confidence ≥ medium for all asset types
+- [ ] Transparency Classification table complete (Step 0e below)
+
+**MUST NOT** start bulk generation until every Risk Checklist item is checked `[x]`.
+
+---
+
+## Transparency Classification
+
+> **Step 0e — mandatory before any generation.** TA auto-derives `needsAlpha` from path convention + `bgStrategy` from element color palette. See `ta-pipeline-cookbook.md` Step 0e for full rules.
+
+| #     | assetMapping path | needsAlpha     | bgStrategy                                                      | 推导依据                          | 去背工具                                             | 回退工具                                  | 验证结果    |
+| ----- | ----------------- | -------------- | --------------------------------------------------------------- | --------------------------------- | ---------------------------------------------------- | ----------------------------------------- | ----------- |
+| {{n}} | {{path}}          | {{true/false}} | {{greenscreen/bluescreen/magenta/extract/full-coverage/opaque}} | {{路径: ui/ + 色彩: 红色系→绿幕}} | {{remove-bg floodfill t=25 / segment --boxes / N/A}} | {{segment / remove-bg --method ai / N/A}} | {{✅ / ❓}} |
+
+<!--
+TA auto-derives transparency — does NOT depend on PM fields.
+
+needsAlpha derivation (from assetMapping path):
+  images/bg/    → false (full-screen background)
+  images/ui/    → true  (UI overlay)
+  images/txt/   → true  (text image)
+  images/vfx/   → true  (VFX sprite)
+  images/tiles/ → true  (default; unless card/board rect body → false)
+
+bgStrategy derivation (from element color palette):
+  Gold/yellow/orange/amber   → bluescreen (NEVER green — color bleed)
+  Green/teal/cyan            → bluescreen (NEVER green — same family)
+  Blue/indigo/purple         → greenscreen (NEVER blue — same family)
+  VFX glow/particle          → bluescreen (warm tones common)
+  Text/digit images          → bluescreen (often gold/white)
+  Multi-color/rainbow        → magenta (last resort)
+  Red/pink/white/black       → greenscreen or bluescreen (both safe)
+
+TA tool chain (must use, never skip):
+  1st: playcraft image remove-background --method floodfill --tolerance 25
+  2nd: playcraft image segment --boxes (complex edges, known position)
+  3rd: playcraft image remove-background --method ai (hair/transparency)
+  4th: playcraft image segment --text (unknown position, last resort)
+  Extract: playcraft image crop (grid) or decompose-layers (multi-layer MC)
+
+Post-verify: overlay on #1A1A2E dark bg to check:
+  ✅ No white edges, no chroma residue, no black blocks, clean edges
+  ❌ If any issue → escalate through fallback tool chain
+-->
+
+**MUST NOT** proceed to Step 1 bulk generation if any row has `❓ pending` in 验证结果.
+
+---
+
 ## Style Reference
 
 - **Master reference (MC)**: `assets/images/storyboard/master_composite_option_{{selectedMcOption}}.png`
@@ -174,6 +301,17 @@ Every row must be PASS before advancing to integration.
 | Total assets size        | ≤ 2-3MB                    | {{actual}} | {{PASS/FAIL}} |
 | Sprite sheet JSON paired | Every .png sheet has .json | {{yes/no}} | {{PASS/FAIL}} |
 
+### Transparency Compliance
+
+| Check                        | Target                                             | Actual     | Result        |
+| ---------------------------- | -------------------------------------------------- | ---------- | ------------- |
+| Classification table         | All rows filled, no ❓ pending                     | {{status}} | {{PASS/FAIL}} |
+| Alpha channels (transparent) | All transparent assets channels=4                  | {{count}}  | {{PASS/FAIL}} |
+| Dark-bg verify (transparent) | All transparent assets clean on #1A1A2E overlay    | {{count}}  | {{PASS/FAIL}} |
+| BG full-coverage             | All backgrounds edge-to-edge, no fade/white corner | {{status}} | {{PASS/FAIL}} |
+| Atlas per-frame verify       | VFX/atlas each frame verified on dark bg           | {{status}} | {{PASS/FAIL}} |
+| Chroma residue               | Zero color residue from chroma key removal         | {{status}} | {{PASS/FAIL}} |
+
 ### Compliance Verdict
 
 - **Overall**: {{PASS / FAIL}}