@playcraft/cli 0.0.41 → 0.0.43

package/project-template/.claude/agents/refs/ta-pipeline-cookbook.md

@@ -34,6 +34,48 @@ ls assets/audio/              # Designer Ph.2 raw audio (if present)
 
 ---
 
+## Step 0 Pre: mediaGroups Asset Reuse (mandatory, before any generation)
+
+> **Purpose:** `atom-plan.json` → `skillsMatch.mediaGroups` contains pre-matched reusable assets from the skills library. These assets have already been validated by PM's `playcraft skills match`. **TA MUST check and link available media assets before generating anything from scratch.**
+
+```bash
+# 1. Read mediaGroups from atom-plan.json
+cat docs/atom-plan.json | jq '.skillsMatch.mediaGroups'
+```
+
+For each mediaGroup entry:
+
+1. **Check if the mediaGroup matches a TA-assigned atom** — compare `atomId` / description with atoms in your production list
+2. **If matched → link the asset directly**:
+
+```bash
+# Link the pre-matched asset to the contract path
+playcraft skills link --atom <atomId> --output <assetMapping_path>
+# OR manually copy from skills library:
+cp $(playcraft skills read <mediaGroup_atomId> --path) <assetMapping_path>
+```
+
+3. **Post-process the linked asset** (resize, convert, transparency) — linked assets still need format compliance
+4. **Update atom status** immediately:
+
+```json
+{ "atomId": "<id>", "status": "done", "actualOutput": "<assetMapping_path>" }
+```
+
+5. **If NOT matched or quality insufficient** — proceed to Step 0 Skill Discovery + Step 1 generation as normal; document reason in `dagRevisions`:
+
+```markdown
+### mediaGroup Skip — {{atomId}}
+
+- **mediaGroup atomId**: {{mg_atomId}}
+- **reason**: {{quality issue / style mismatch / wrong dimensions}}
+- **action**: generate from scratch using Step 1 pipeline
+```
+
+**STOP gate**: `ta-log.md` must contain a "mediaGroups Reuse" section listing each mediaGroup's disposition (linked / skipped + reason) before proceeding to generation.
+
+---
+
 ## Step 0 (Skill Discovery) → Enrich TA Skill Context
 
 Before executing any atom, run two rounds of Skill Discovery:
@@ -113,6 +155,47 @@ If `skillRef` is `—` or empty for an atom, skip Part B for that atom and rely
 
 ---
 
+### Part C — Mandatory Skill Preflight（管线 Skill 读取）
+
+> **Purpose:** TA 在生产前必须阅读相关的 playcraft 管线 Skill，确保使用平台既定最佳实践而非"凭经验自由发挥"。
+
+**必读 Skills（按产出类型）：**
+
+| 产出类型        | 必读 Skill                                                               | 不读的后果                   |
+| --------------- | ------------------------------------------------------------------------ | ---------------------------- |
+| 任何图片生成    | `playcraft-image-generation`（§3 背景决策树、模型选择、reference-image） | 所有透明度问题               |
+| 需要透明的素材  | `playcraft-masking`（remove-background / segment / decompose-layers）    | 白底、黑块、色残留           |
+| 精灵图 / Atlas  | `playcraft-sprite-generation`（单帧生成→合并，非 AI 直出网格）           | 帧尺寸不均、无 alpha、帧出血 |
+| VFX 动画帧      | `playcraft-vfx-animation`                                                | 发光效果黑块                 |
+| 批量 (>5 元素)  | `playcraft-batch-pipeline`                                               | 风格不一致、参数丢失         |
+| 文字 / 数字渲染 | `playcraft-text-rendering`（绿幕策略 + 描边保护）                        | 文字白底、数字变绿           |
+| 风格一致性验证  | `playcraft-style-qa`                                                     | 风格偏离 MC / ASR            |
+
+**执行方式：**
+
+```bash
+# Read each relevant skill before production
+cat .claude/skills/playcraft-image-generation/SKILL.md
+cat .claude/skills/playcraft-masking/SKILL.md
+cat .claude/skills/playcraft-sprite-generation/SKILL.md
+# ... additional skills per atom type
+```
+
+**STOP 门槛**：`logs/ta-log.md` 的 **§ Skill Preflight** 必须列出每个已读 Skill + 关键决策摘要（一行）。未填则不得执行 Step 1 批量生成。
+
+```markdown
+## Skill Preflight
+
+| Skill                       | 已读 | 关键决策摘要                                          |
+| --------------------------- | ---- | ----------------------------------------------------- |
+| playcraft-image-generation  | ✅   | 使用 gpt-image-2；所有透明素材 chroma key + ref-image |
+| playcraft-masking           | ✅   | floodfill 优先 (tolerance=25)；复杂形状用 segment     |
+| playcraft-sprite-generation | ✅   | 单帧生成→去背→resize→合并；禁止 AI 直出网格           |
+| playcraft-text-rendering    | ✅   | 文字必须蓝幕；描边保护 + tolerance 降到 20            |
+```
+
+---
+
 ## Step 1 (Asset Completion)
 
 > **生图前请先阅读 `playcraft-image-generation` Skill**（包含模型选择决策树、reference-image 工作流和错误恢复策略）。
@@ -259,32 +342,134 @@ node ta-workspace/scripts/gen-<name>-variants.mjs
 
 ### Step 4: Process Assets（去背景 + resize + 验证）
 
-> **先判断素材类型，再决定是否需要去背景**（参见 playcraft-image-generation Skill 4.5 节背景处理决策树）
+> **必须先查阅 Step 0e Transparency Classification 表**，按 `bgStrategy` 列执行。不要凭直觉判断是否需要去背景。
+
+#### 处理管线总览
+
+```
+按 bgStrategy 分流：
+│
+├─ opaque → 直接 resize（skipRemoveBg = true）
+│
+├─ full-coverage → resize → 全覆盖验证（四角四边）
+│
+├─ greenscreen / bluescreen / magenta → 完整去背管线：
+│   1. playcraft image remove-background --method floodfill --tolerance 25
+│   2. playcraft image info --json → 确认 channels=4
+│   3. playcraft image overlay (深色背景验证)
+│   4. 验证失败? → 回退工具链（见下方）
+│   5. playcraft image resize → playcraft image convert --format webp
+│
+└─ segment → 提取管线：
+    1. playcraft image crop (已知坐标) 或 segment --boxes (需精确蒙版)
+    2. 若整图分层 → playcraft image decompose-layers
+    3. playcraft image info --json → 确认 channels=4
+    4. playcraft image overlay (深色背景验证)
+    5. playcraft image resize → playcraft image convert --format webp
+```
 
-**卡牌 / 棋子 / UI 面板（矩形本体，不需要透明背景）**：
+#### bgStrategy = opaque（卡牌/棋子/矩形实体）
 
 ```bash
-# 直接 resize，不做去背景（白色牌面就是牌的一部分！）
 playcraft image resize --input <file>.png --output <file>.png --width <W> --height <H> --fit contain
 ```
 
 批量处理使用 `process-batch.template.mjs` 并设置 `CONFIG.skipRemoveBg = true`。
 
-**独立元素（角色/道具/图标，需要透明背景）→ 绿幕策略**：
+#### bgStrategy = greenscreen / bluescreen / magenta（需要透明的元素）
+
+> ⚠️ **不要跳过去背景步骤！** 按 Step 0e 表中的 bgStrategy 选用正确的工具。
+
+**Step 4a — 去背景（第一选择：floodfill）**：
+
+```bash
+playcraft image remove-background \
+  --input <raw_asset>.png \
+  --output <processed_asset>.png \
+  --method floodfill \
+  --tolerance 25
+```
+
+**Step 4b — 验证 alpha 通道**：
+
+```bash
+playcraft image info --input <processed_asset>.png --json
+# 确认: channels == 4（若 channels == 3，说明输出格式错误，确保 .png 后缀）
+```
+
+**Step 4c — 深色背景渲染验证**：
+
+```bash
+playcraft image overlay \
+  --base ta-workspace/tmp/dark_verify_bg.png \
+  --overlay <processed_asset>.png \
+  --output ta-workspace/tmp/verify_<name>.png \
+  --gravity center
+# 目视确认：边缘干净、无色幕残留、无白色/黑色伪影
+```
 
-生图时 prompt 末尾加 `"on solid bright green #00FF00 background, isolated, centered"`（当前所有模型 ALPHA = no，无原生透明输出），然后：
+**Step 4d — 验证失败时的回退工具链**：
+
+| 验证失败现象               | 根因                           | 回退工具                                                                   |
+| -------------------------- | ------------------------------ | -------------------------------------------------------------------------- |
+| 色幕残留少量（边缘毛刺）   | tolerance 偏低                 | `remove-background --tolerance 40`（+15 递增重试）                         |
+| 色幕残留明显（大面积色块） | 素材色与色幕撞色               | **spec-gap** → PM 修改 bgStrategy → 用正确色幕重新生成                     |
+| 复杂边缘/不规则形状        | floodfill 无法处理复杂轮廓     | `playcraft image segment --boxes '[[x1,y1,x2,y2]]'`（精确框选，SAM3 分割） |
+| 毛发/半透明/渐变边缘       | floodfill 是硬边缘算法         | `playcraft image remove-background --method ai`（AI 语义去背景）           |
+| 去背过度（元素被挖掉）     | tolerance 过高或素材含近色区域 | 降低 tolerance 到 15-20 → 仍不行则 `segment --boxes`                       |
+| VFX 帧出现黑色不透明块     | 发光/粒子未用色幕生成          | 用蓝幕重新生成每一帧，然后 `remove-background`                             |
+| 白底/白边残留              | 未使用色幕策略直接白底生成     | 用正确色幕重新生成（不要试图在白底上去背景）                               |
+| 背景图四角褪色/白边        | prompt 未加 edge-to-edge       | 重新生成，prompt 加 `"full bleed, edge to edge, no vignette"`              |
+
+#### bgStrategy = segment（从 MC/ASR 提取）
+
+使用 PlayCraft CLI 提供的分割工具链提取，不做 AI 重新生成：
 
 ```bash
-# 绿幕抠图（tolerance=25 对绿色效果最好）
-playcraft image remove-background --input in.png --output out.png --tolerance 25
+# 方法 1: crop 直切（ASR 已知网格布局，最可靠）
+playcraft image crop \
+  --input assets/images/reference/element_state_sheet_X.png \
+  --x <x> --y <y> --width <w> --height <h> \
+  --output <extracted>.png
+
+# 方法 2: SAM3 语义分割（需精确蒙版时）
+playcraft image segment \
+  --input assets/images/storyboard/master_composite.png \
+  --boxes '[[x1,y1,x2,y2]]' \
+  --output-dir ta-workspace/tmp/seg/
+# → 使用 00_rgba.png（已带透明通道）
+
+# 方法 3: 整图分层（需要从 MC 拆出多个层）
+playcraft image decompose-layers \
+  --input assets/images/storyboard/master_composite.png \
+  --output-dir ta-workspace/tmp/layers \
+  --num-layers 4
+
+# 提取后仍需深色背景验证
+playcraft image overlay \
+  --base ta-workspace/tmp/dark_verify_bg.png \
+  --overlay <extracted>.png \
+  --output ta-workspace/tmp/verify_<name>.png \
+  --gravity center
 ```
 
-**批量处理 → ta-workspace 脚本模板**：
+#### bgStrategy = full-coverage（全屏背景）
+
+```bash
+playcraft image info --input <bg_asset>.png --json
+# 验证：尺寸精确匹配 layout-spec 要求
+# 目视检查：四角四边颜色一致，无褪色/渐变/白色边缘/暗角
+```
+
+#### 批量处理
 
 ```bash
 cp .claude/skills/playcraft-image-generation/reference/process-batch.template.mjs \
    ta-workspace/scripts/process-<name>.mjs
-# 修改 CONFIG（特别是 skipRemoveBg 和 removeBgTolerance）后运行
+# 修改 CONFIG：
+#   skipRemoveBg = true  (bgStrategy=opaque/full-coverage)
+#   skipRemoveBg = false (bgStrategy=greenscreen/bluescreen/magenta)
+#   removeBgTolerance = 25
 node ta-workspace/scripts/process-<name>.mjs
 ```
 
@@ -557,21 +742,55 @@ Designer's **ASR sheets** (UI + element state reference) contain **representativ
 
 1. From **ASR** (preferred): `crop` each state slot → `resize` to spec → these become your `--reference-image` for Stage A batch generation
 2. From **Master Composite** (fallback): extract elements not covered in ASR
-3. Check `designer-log.md` **ASR State Inventory** — note which states are covered vs which need expansion
+3. Check `designer-log.md` § **ASR Coverage Matrix** — note which states are covered vs which need expansion; Sheet grid metadata table at the top has `rows × cols + cell W×H + padding` for pixel-coordinate computation
 4. Background: generate clean bg using composite as `--reference-image`
 5. Text assets: → **invoke `playcraft-text-rendering` skill**
 6. Representative quality insufficient → ICP request to Designer for supplementary samples
 
+**若 ASR crop 后不可抠**（白边/色幕残留/元素截断/格内场景底）→ **`routeTo: designer`** 重生成 ASR 对应格；**不要** TA 自行用 AI 重画整张 ASR。
+
 **ASR 提取方法（按优先级）**：
 
 > ⚠️ **严禁对 ASR 网格布局图使用纯 text prompt 的 segment！** 使用 `designer-log` 中的槽位坐标 + `crop`。
 
+**优先路径：直接读 `atom-plan.json` → `atoms[].asrSlot`（最高优先级）**
+
+Designer 在 Phase 1 完成 ASR 后会把每个 VisualAtom 的网格坐标写到 `atom-plan.json` → `atoms[i].asrSlot: { sheet, row, col }`（详见 [`docs/team/atom-plan-format.md` § `asrSlot`](../../../docs/team/atom-plan-format.md#asrslot-字段可选--visualatom-基线绑定)）。TA 直接用这个字段 + `designer-log` § Sheet grid metadata，省去手翻 Coverage Matrix 的步骤：
+
+```bash
+# 1) 从 atom-plan.json 读取所有有 asrSlot 的 VisualAtom
+cat docs/atom-plan.json | jq -r '
+  .atoms[]
+  | select(.asrSlot != null)
+  | "\(.atomId)\t\(.asrSlot.sheet)\t\(.asrSlot.row)\t\(.asrSlot.col)"
+'
+# 输出格式: <atomId>\t<sheet>\t<row>\t<col>
+
+# 2) 从 designer-log.md § ASR Coverage Matrix § Sheet grid metadata 读 cellW / cellH / padding
+#    (单独读一次，缓存到 ta-log 备查)
+
+# 3) 计算像素坐标并 crop（脚本化 — ta-workspace/scripts/asr-extract.mjs）
+#    x = (col - 1) * (cellW + padding) + padding
+#    y = (row - 1) * (cellH + padding) + padding
+#    sheetPath 映射:
+#      ui       → assets/images/reference/ui_state_sheet_<selectedMcOption>.png
+#      element  → assets/images/reference/element_state_sheet_<selectedMcOption>.png
+#      element_2 → assets/images/reference/element_state_sheet_<selectedMcOption>_2.png
+#    contractPath 从 layout-spec assetMapping 中按 atom slot 反查
+#
+#    playcraft image crop --input <sheetPath> --x <x> --y <y> --width <cellW> --height <cellH> --output <contractPath>
 ```
-ASR 是已知网格布局？（ui_state_sheet / element_state_sheet，行列分明）
-├─ 是 → 方法 1: crop 直切（最可靠，零歧义）
+
+```
+ASR 是已知网格布局？（ui_state_sheet / element_state_sheet / element_state_sheet_*_2，行列分明）
+├─ atom-plan.json 有 asrSlot 字段 → 方法 0（推荐）: 上面脚本化批量 crop
+│
+├─ 是但 asrSlot 缺失 → 方法 1: crop 直切（手动查 Coverage Matrix R#C#）
 │        1. playcraft image info --input assets/images/reference/ui_state_sheet_<X>.png  → 获取尺寸
-│        2. 从 designer-log ASR State Inventory 读取行列与 bbox
-│        3. playcraft image crop --input <asr_sheet> --x <x> --y <y> --width <w> --height <h> --output <out>
+│        2. 从 designer-log § ASR Coverage Matrix 读取 Sheet grid 元数据 + 目标行列 (R#C#)
+│           pixel coords:  x = (C-1) × (cellW + padding) + padding
+│                          y = (R-1) × (cellH + padding) + padding
+│        3. playcraft image crop --input <asr_sheet> --x <x> --y <y> --width <cellW> --height <cellH> --output <out>
 │        4. 对有背景底色的元素：crop 后再 remove-background --method floodfill
 │
 ├─ 元素位置不规则但 bbox 已知 → 方法 2: segment --boxes（精确框选）
@@ -580,6 +799,8 @@ ASR 是已知网格布局？（ui_state_sheet / element_state_sheet，行列分
 └─ 仅 MC 有该类型 → 方法 3: decompose-layers 或 segment --text（最后手段，见 playcraft-masking）
 ```
 
+> **若 Designer 没有填 `asrSlot`** — 不需要重新 invoke Designer，TA 可以手动从 `designer-log § ASR Coverage Matrix § Coverage` 反查 R#C# 并继续。在 ICP 中提示 PM/Designer 下次预填可加速。
+
 **常见踩坑**：
 
 - ❌ `segment --text "apple tile icon"` → SAM3 可能只切出苹果图案，丢失 tile 方块底板
@@ -593,31 +814,239 @@ ASR 是已知网格布局？（ui_state_sheet / element_state_sheet，行列分
 
 Read designer-log Style Intent Notes → write interpretation table to `ta-log.md` → confidence low = blocked, medium = proceed with caution, high = proceed.
 
+### Step 0d: Production Plan (mandatory, before any generation)
+
+> **Purpose:** Converge on full asset coverage and pipeline order before bulk production.
+
+Write `logs/ta-log.md` § **Production Plan** with:
+
+1. **Coverage Plan** — one row per `layout-spec` `assetMapping` entry (contract path, pipeline type, reference source, priority)
+2. **Atlas Assembly Plan** — one row per atlas group from layout-spec grouping table (output `.webp` + `.json`, frameIds, grid layout)
+3. **Pipeline Order** — numbered steps (Extract → Complete → Process → Assemble → Verify)
+4. **Risk Checklist** — all items checked `[x]`
+
+**Rules:**
+
+- Coverage Plan row count must equal `assetMapping` entry count (no gaps)
+- Atlas groups must match layout-spec § atlas grouping table
+- **MUST NOT** start Step 1 bulk generation until Risk Checklist is fully checked
+- `validate-workflow-stop.mjs` blocks STOP if Plan is incomplete
+
+---
+
+### Step 0e: Asset Transparency Classification (mandatory, before any generation)
+
+> **Purpose:** 根据 `layout-spec.md` 的 `assetMapping` 路径约定 + 元素色彩分析，自动推导每个资产的透明度需求和色幕策略，确定完整的处理管线。**此步骤在 Production Plan 完成后、Step 1 批量生成前执行。**
+
+**根因认知**：当前所有 AI 模型均不支持原生透明 PNG（`ALPHA = no`）。不做透明度处理 → 所有素材"生成就完事" → UI 叠加元素白底、VFX 黑块、HUD 数字白底、图标白底等系统性问题。**PlayCraft CLI 提供了完整的透明度工具链（`remove-background` / `segment` / `decompose-layers`），TA 必须显式使用。**
+
+#### 1. 从路径约定推导 needsAlpha
+
+遍历 `layout-spec.md` 的 `assetMapping`，根据**路径目录**自动判断每个资产是否需要透明背景：
+
+```
+assetMapping 路径所在目录？
+│
+├─ assets/images/bg/     → needsAlpha = false（全屏背景，不透明）
+├─ assets/images/ui/     → needsAlpha = true （UI 叠加层，必须透明）
+├─ assets/images/txt/    → needsAlpha = true （文字图片，必须透明）
+├─ assets/images/vfx/    → needsAlpha = true （特效精灵图，必须透明）
+├─ assets/images/tiles/  → needsAlpha = true （默认；除非是卡牌/棋子矩形实体）
+├─ assets/audio/         → N/A（非图片）
+└─ 其他路径              → 按素材用途判断：叠加在其他图层上 = true，独立全屏 = false
+```
+
+**卡牌/棋子等矩形实体例外**：虽然路径在 `tiles/`，但白色牌面是资产本体的一部分，不需要透明。TA 根据 `design-brief` 的 Style Direction + `designer-log` 的样本判断。
+
+#### 2. 从元素色彩推导 bgStrategy（色幕选型）
+
+对每个 `needsAlpha = true` 的资产，根据元素主色调选择色幕颜色。色调信息来源：
+
+- `layout-spec.md` 的 Color Palette（elementId → hex color）
+- `design-brief.md` 的 Style Direction（整体色温描述）
+- `designer-log.md` 的样本（实际视觉参考）
+
+**色幕选型矩阵**：
+
+| 元素主色调            | ❌ 禁用色幕  | ✅ 推荐色幕      | 原因                                                 |
+| --------------------- | ------------ | ---------------- | ---------------------------------------------------- |
+| 金色/黄色/橙色/琥珀色 | 绿幕 #00FF00 | **蓝幕 #0000FF** | 金色与绿色色相接近（黄绿区），floodfill 残留绿色边缘 |
+| 绿色/翠绿/青色        | 绿幕 #00FF00 | **蓝幕 #0000FF** | 同色系，floodfill 无法区分边界                       |
+| 蓝色/靛蓝/紫色        | 蓝幕 #0000FF | **绿幕 #00FF00** | 同色系冲突                                           |
+| 红色/粉色/白色/黑色   | —            | 绿幕或蓝幕均可   | 与两者色相距离都大                                   |
+| 多色/彩虹             | —            | **品红 #FF00FF** | 品红在自然素材中最少出现（最后手段）                 |
+
+**特殊规则**（不按元素色彩，按资产类型固定）：
+
+| 资产类型               | 固定色幕         | 原因                                                 |
+| ---------------------- | ---------------- | ---------------------------------------------------- |
+| VFX 发光/粒子/选中高亮 | **蓝幕 #0000FF** | VFX 普遍含暖色调（金色火焰、橙色爆炸），绿幕必出残留 |
+| 文字/数字图片          | **蓝幕 #0000FF** | 文字常为金色/白色/浅色，绿幕边缘污染                 |
+| 全屏背景               | N/A（不去背景）  | prompt 加 `"full bleed, edge to edge, no vignette"`  |
+| 矩形实体（卡牌/棋子）  | N/A（不去背景）  | 白底是资产本身，skipRemoveBg = true                  |
+
+#### 3. 填写 Transparency Classification 表
+
+```markdown
+## Transparency Classification
+
+| assetMapping path             | needsAlpha | bgStrategy    | 去背工具（第一选择）                  | 回退工具                                    | 验证方法             | 验证结果 |
+| ----------------------------- | ---------- | ------------- | ------------------------------------- | ------------------------------------------- | -------------------- | -------- |
+| assets/images/bg/bg_main.webp | false      | full-coverage | N/A                                   | N/A                                         | 边缘全覆盖检查       | ❓       |
+| assets/images/ui/btn_cta.webp | true       | greenscreen   | `remove-background --floodfill -t 25` | `segment --boxes` / `remove-bg --method ai` | 深色背景 overlay     | ❓       |
+| assets/images/txt/digits.webp | true       | bluescreen    | `remove-background --floodfill -t 25` | `segment --boxes` / `remove-bg --method ai` | 深色背景 overlay     | ❓       |
+| assets/images/vfx/glow.webp   | true       | bluescreen    | `remove-background --floodfill -t 25` | `segment --boxes`                           | 逐帧深色背景 overlay | ❓       |
+| assets/images/tiles/tile.webp | true       | greenscreen   | `remove-background --floodfill -t 25` | `segment --boxes` / `remove-bg --method ai` | 深色背景 overlay     | ❓       |
+| assets/images/txt/title.webp  | true       | bluescreen    | `remove-background --floodfill -t 25` | `remove-bg --method ai`                     | 深色背景 overlay     | ❓       |
+```
+
+#### 4. 去背工具链（按 bgStrategy 执行）
+
+> **PlayCraft CLI 提供了完整的透明度处理工具链，TA 必须按决策树显式使用，不能跳过去背景步骤。**
+
+| bgStrategy    | 生成 prompt 后缀                                                    | 第一选择去背工具                                   | 回退工具（第一选择效果不好时）                     |
+| ------------- | ------------------------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------- |
+| greenscreen   | `"on solid bright green #00FF00 background, isolated, centered"`    | `playcraft image remove-background --tolerance 25` | `playcraft image segment --boxes` 或 `--method ai` |
+| bluescreen    | `"on solid bright blue #0000FF background, isolated, centered"`     | `playcraft image remove-background --tolerance 25` | `playcraft image segment --boxes` 或 `--method ai` |
+| magenta       | `"on solid bright magenta #FF00FF background, isolated, centered"`  | `playcraft image remove-background --tolerance 20` | `playcraft image remove-background --method ai`    |
+| extract       | 无特殊后缀（从 MC/ASR 提取）                                        | `playcraft image crop` 或 `segment --boxes`        | `playcraft image decompose-layers`（整图分层）     |
+| full-coverage | `"full scene, full bleed, edge to edge, no vignette, no fade"`      | N/A（不去背景）                                    | N/A                                                |
+| opaque        | `"flat 2D, no shadow, no 3D effect, clean edges, white background"` | N/A（不去背景）                                    | N/A                                                |
+
+**工具选型决策树**（TA 必须按此执行，不可跳步）：
+
+```
+needsAlpha = true?
+├─ 是 → 按色幕选型矩阵确定色幕颜色
+│       → Step A: 生成时 prompt 加色幕后缀
+│       → Step B: playcraft image remove-background --method floodfill --tolerance 25
+│       → Step C: playcraft image info --json → channels == 4?
+│           ├─ channels=4 → Step D: 深色背景 overlay 验证
+│           │   ├─ 通过 → ✅ 记录结果
+│           │   └─ 边缘有残留 → 回退工具链：
+│           │       ├─ 纯色残留少量 → 调高 tolerance (25→40→60) 重试
+│           │       ├─ 复杂边缘/不规则形状 → playcraft image segment --boxes (SAM3)
+│           │       ├─ 毛发/半透明/复杂背景 → playcraft image remove-background --method ai
+│           │       └─ 仍然不行 → playcraft image segment --text (最后手段)
+│           └─ channels=3 → 输出可能是 JPEG，确保 --output 为 .png 后缀
+│
+├─ needsAlpha = true 且从 MC/ASR 提取（非 AI 生成）?
+│   → 优先: playcraft image crop (已知网格布局/坐标)
+│   → 次选: playcraft image segment --boxes (已知大致位置，需精确蒙版)
+│   → 回退: playcraft image segment --text (位置未知，描述要极其具体)
+│   → 整图分层: playcraft image decompose-layers (需拆出多层时)
+│   → Step D: 深色背景 overlay 验证
+│
+├─ needsAlpha = false（full-coverage 全屏背景）?
+│   → 不做去背景
+│   → 验证：playcraft image info 确认尺寸 → 四角四边颜色一致，无褪色/白色/渐变
+│
+└─ needsAlpha = false（opaque 矩形实体）?
+    → 不做去背景，直接 resize（skipRemoveBg = true）
+```
+
+#### 4. 验证清单（生成后必做）
+
+**每个 `needsAlpha=true` 的资产，去背景后必须做以下验证：**
+
+```bash
+# A. Alpha 通道检查 — channels 必须 = 4
+playcraft image info --input <asset>.png --json
+# 验证: channels == 4 (若 channels == 3，说明没有 alpha 通道)
+
+# B. 深色背景渲染验证 — 在 #1A1A2E 深色底上叠合查看
+playcraft image overlay \
+  --base ta-workspace/tmp/dark_verify_bg.png \
+  --overlay <asset>.png \
+  --output ta-workspace/tmp/verify_<name>.png \
+  --gravity center
+# 目视检查：无白边、无色幕残留、无黑块、边缘干净
+
+# C. 背景图全覆盖检查（仅 bgStrategy=full-coverage）
+playcraft image info --input <bg_asset>.png --json
+# 验证：尺寸精确匹配 layout-spec 要求
+# 目视检查：四角四边颜色一致，无褪色/渐变/白色边缘
+```
+
+**验证用深色底图生成（一次即可，全项目复用）**：
+
+```bash
+# 生成 512x512 深色验证底图
+node -e "
+const sharp = require('sharp');
+sharp({ create: { width: 512, height: 512, channels: 4, background: { r: 26, g: 26, b: 46, alpha: 1 } } })
+  .png().toFile('ta-workspace/tmp/dark_verify_bg.png');
+"
+```
+
+**批量验证脚本（>5 个透明资产时推荐）**：
+
+```bash
+# 为每个需要透明的资产批量叠合验证
+for f in assets/images/ui/*.png assets/images/vfx/*.png assets/images/txt/*.png; do
+  name=$(basename "$f" .png)
+  playcraft image overlay \
+    --base ta-workspace/tmp/dark_verify_bg.png \
+    --overlay "$f" \
+    --output "ta-workspace/tmp/verify_${name}.png" \
+    --gravity center
+  echo "[VERIFY] $name → ta-workspace/tmp/verify_${name}.png"
+done
+# 逐张目视检查输出，发现问题立即记录到 ta-log
+```
+
+#### 5. 写入 ta-log.md
+
+在 `logs/ta-log.md` § Transparency Classification 表中填写验证结果：
+
+```markdown
+## Transparency Classification
+
+| #   | Contract Path                 | needsAlpha | bgStrategy    | 去背工具                         | 验证结果                    |
+| --- | ----------------------------- | ---------- | ------------- | -------------------------------- | --------------------------- |
+| 1   | assets/images/ui/btn_cta.webp | true       | greenscreen   | remove-background floodfill t=25 | ✅ channels=4, 深色验证通过 |
+| 2   | assets/images/txt/title.webp  | true       | bluescreen    | remove-background floodfill t=25 | ✅ channels=4, 深色验证通过 |
+| 3   | assets/images/ui/icons.webp   | true       | segment       | segment --boxes + crop           | ✅ channels=4, 深色验证通过 |
+| 4   | assets/images/bg/bg_main.webp | false      | full-coverage | N/A                              | ✅ 全覆盖检查通过           |
+```
+
+**MUST NOT** 进入 Step 1 批量生成，除非 Transparency Classification 表完成且无 `❓` 未决项。
+
+---
+
 ### Step 1: Skill Discovery
 
 - Part A: `playcraft skills list/match` → find pipeline Skills → write to atom-plan `## TA Skill Context`
 - Part B: `playcraft skills scaffold <skillRef> --dry-run` for each atom → extract prompt/model params  
   (See **Step 0** above for bash examples.)
 
-### Pipeline model (E → A → B → C → D)
+### Pipeline model (E → T → A → B → C → D)
 
 ```
 Gate #2 → TA starts
    │
-   ├─ E: Extract (Step 0b) — decompose-layers or segment references from composites
+   ├─ 0a: Upstream Intake
+   ├─ 0b: Extract (E) — decompose-layers or segment references from composites
+   ├─ 0c: Style Interpretation Check
+   ├─ 0d: Production Plan
+   ├─ 0e: Transparency Classification ← NEW (classify all assets, select chroma key per color matrix)
+   │
+   ├─ T: Transparency-aware generation (Step 1 with correct chroma key per 0e table)
    │    │
    │    ├─ C₁: generate-3d (if referenceSource="designer-sample")
    │    │
-   │    ├─ A: Batch Element Generation (sprite sheet per type)
+   │    ├─ A: Batch Element Generation (sprite sheet per type, chroma key per 0e)
    │    │    │
-   │    │    ├──→ B: animate / sprite-sheet / use-vfx
+   │    │    ├──→ B: animate / sprite-sheet / use-vfx (VFX always blue screen)
    │    │    └──→ C₂: apply-texture (if referenceSource="ta-completion")
    │    │
    │    └─ (extraction insufficient → ICP → Designer supplementary)
    │
+   ├─ Step 4: Process (remove-bg per chroma → dark-bg verify each asset)
+   │
    ├─ D: Audio post-processing (independent, waits for Designer Ph.2 audio)
    │
-   └─ All done → Compliance Gate
+   └─ All done → Compliance Gate (incl. Transparency checks)
 ```
 
 ### Pipeline selection (quick)
@@ -666,19 +1095,35 @@ Independent track, waits only for Designer Ph.2 audio delivery:
 
 ### Compliance Gate (full checklist)
 
-| Check                            | Criteria                                                                                                               |
-| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| All assetMapping files exist     | Zero missing                                                                                                           |
-| Image dimensions match assetSpec | Exact match                                                                                                            |
-| Image format                     | **WebP** for runtime deliverables per `ta-atlas-deliverable-standard`; PNG/JPG only if layout-spec explicitly requires |
-| Sprite / atlas grid params       | In ta-log.md (cols/frameW/frameH/frameCount); `.json` beside each atlas                                                |
-| Audio format                     | MP3 after TA post-process                                                                                              |
-| No external dependencies         | Standalone files                                                                                                       |
-| Style Interpretation completed   | ta-log.md has interpretation table                                                                                     |
-| No open TA questions             | intent-clarifications.md clear                                                                                         |
+| Check                                   | Criteria                                                                                                               |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| All assetMapping files exist            | Zero missing                                                                                                           |
+| Image dimensions match assetSpec        | Exact match                                                                                                            |
+| Image format                            | **WebP** for runtime deliverables per `ta-atlas-deliverable-standard`; PNG/JPG only if layout-spec explicitly requires |
+| Sprite / atlas grid params              | In ta-log.md (cols/frameW/frameH/frameCount); `.json` beside each atlas                                                |
+| **Transparency Classification**         | ta-log.md has Transparency Classification table; all rows have 验证结果 (no `❓`)                                      |
+| **Alpha channel (transparent)**         | All assets marked 需要透明=✅ have `channels=4` (`playcraft image info --json`)                                        |
+| **Dark-bg render verify (transparent)** | All transparent assets verified on #1A1A2E dark background — no white edge, no chroma residue, no black blocks         |
+| **Background full-coverage**            | All full-screen backgrounds: edges extend to all four sides, no fade/vignette/white corners                            |
+| **Atlas per-frame verify**              | Each frame in atlas verified individually on dark background (especially VFX glow/particle frames)                     |
+| Audio format                            | MP3 after TA post-process                                                                                              |
+| No external dependencies                | Standalone files                                                                                                       |
+| Style Interpretation completed          | ta-log.md has interpretation table                                                                                     |
+| No open TA questions                    | intent-clarifications.md clear                                                                                         |
 
 > **TA 阶段不管体积。** 品质和规格合规是唯一目标。体积优化在 Developer build 阶段。
 
+**Transparency compliance 不通过的常见原因及修复**：
+
+| 失败现象                | 根因                                 | 修复                                              |
+| ----------------------- | ------------------------------------ | ------------------------------------------------- |
+| channels=3（无 alpha）  | 去背景步骤遗漏，或输出为 JPEG        | 对原图执行 remove-background，确保输出 PNG        |
+| 深色验证见白边          | 生成时未用色幕，白底未完全去除       | 用正确色幕重新生成 + remove-background            |
+| 深色验证见绿色/蓝色残留 | 色幕选型错误（素材色与色幕撞色）     | 按色幕选型矩阵换用另一种色幕重新生成              |
+| VFX 帧出现黑色不透明块  | 发光/粒子生成时未加色幕              | 用蓝幕重新生成每一帧                              |
+| 背景图四角有白色/褪色   | prompt 未约束 edge-to-edge           | prompt 加 "full bleed, edge to edge, no vignette" |
+| 文字/数字图底色未去除   | 未分类为"需要透明"，直接 resize 交付 | 回查 Transparency Classification → 补做去背景流程 |
+
 **After compliance**: Write `logs/ta-log.md` manifest → mark atoms `✅ done` → update project-state.md.
 
 ### Reference image rules