@playcraft/cli 0.0.42 → 0.0.44

package/dist/atom-plan/validate-asr-coverage.js

@@ -0,0 +1,317 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const PLACEHOLDER_RE = /\{\{[^}]+\}\}/;
+const MIN_TAKEAWAY_LEN = 8;
+export const IMAGE_PRODUCTION_PREFLIGHT_HEADING = '## Image Production Preflight';
+export const ASR_COVERAGE_HEADING = '## ASR Coverage Matrix';
+export const REQUIRED_IMAGE_SKILLS = [
+    'playcraft-storyboard',
+    'playcraft-asset-state-sheet',
+    'playcraft-image-generation',
+];
+export function readSelectedMcOption(content) {
+    const m = content.match(/selectedMcOption:\s*["']?([ABC])["']?/i) ||
+        content.match(/selectedMcOption\s*=\s*([ABC])/i);
+    return m ? m[1].toUpperCase() : null;
+}
+function extractSection(content, heading) {
+    const start = content.indexOf(heading);
+    if (start === -1)
+        return '';
+    const after = content.slice(start + heading.length);
+    const next = after.search(/\n##\s+/);
+    return next === -1 ? after : after.slice(0, next);
+}
+export function parseLayoutSpecContractIds(layoutSpec) {
+    const elementIds = [];
+    const staticTextIds = [];
+    const assetSection = extractSection(layoutSpec, '## Asset Mapping');
+    for (const line of assetSection.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('|'))
+            continue;
+        if (/^\|\s*---/.test(trimmed))
+            continue;
+        if (/^\|\s*elementId/i.test(trimmed))
+            continue;
+        const parts = trimmed
+            .split('|')
+            .map((p) => p.trim())
+            .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+        if (parts.length < 1)
+            continue;
+        const id = parts[0].replace(/`/g, '');
+        if (!id || id === '—' || id === '-' || PLACEHOLDER_RE.test(id))
+            continue;
+        elementIds.push(id);
+    }
+    const textSection = extractSection(layoutSpec, '### Static Text');
+    for (const line of textSection.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('|'))
+            continue;
+        if (/^\|\s*---/.test(trimmed))
+            continue;
+        if (/^\|\s*id/i.test(trimmed))
+            continue;
+        const parts = trimmed
+            .split('|')
+            .map((p) => p.trim())
+            .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+        if (parts.length < 1)
+            continue;
+        const id = parts[0].replace(/`/g, '');
+        if (!id || id === '—' || PLACEHOLDER_RE.test(id))
+            continue;
+        staticTextIds.push(id);
+    }
+    return { elementIds, staticTextIds };
+}
+function isReadChecked(cell) {
+    const t = cell.trim();
+    if (/[✓✔☑]/.test(t))
+        return true;
+    if (/\[x\]/i.test(t))
+        return true;
+    if (/^(yes|done|true|read)$/i.test(t))
+        return true;
+    return false;
+}
+export function validateImageProductionPreflight(content) {
+    const errors = [];
+    const start = content.indexOf(IMAGE_PRODUCTION_PREFLIGHT_HEADING);
+    if (start === -1) {
+        return [`Missing "${IMAGE_PRODUCTION_PREFLIGHT_HEADING}" section`];
+    }
+    const after = content.slice(start + IMAGE_PRODUCTION_PREFLIGHT_HEADING.length);
+    const nextHeading = after.search(/\n##\s+/);
+    const section = nextHeading === -1 ? after : after.slice(0, nextHeading);
+    const rows = [];
+    for (const line of section.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('|'))
+            continue;
+        if (/^\|\s*---/.test(trimmed))
+            continue;
+        if (/^\|\s*Skill/i.test(trimmed))
+            continue;
+        const parts = trimmed
+            .split('|')
+            .map((p) => p.trim())
+            .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+        if (parts.length < 3)
+            continue;
+        rows.push({ skill: parts[0], read: parts[1], summary: parts[2] });
+    }
+    if (rows.length === 0) {
+        errors.push(`${IMAGE_PRODUCTION_PREFLIGHT_HEADING}: table has no data rows`);
+        return errors;
+    }
+    for (const required of REQUIRED_IMAGE_SKILLS) {
+        const row = rows.find((r) => r.skill.includes(required));
+        if (!row) {
+            errors.push(`${IMAGE_PRODUCTION_PREFLIGHT_HEADING}: missing row for ${required}`);
+            continue;
+        }
+        if (!isReadChecked(row.read)) {
+            errors.push(`${IMAGE_PRODUCTION_PREFLIGHT_HEADING}: "${required}" — mark 已读 (✓)`);
+        }
+        if (!row.summary || PLACEHOLDER_RE.test(row.summary) || row.summary.length < MIN_TAKEAWAY_LEN) {
+            errors.push(`${IMAGE_PRODUCTION_PREFLIGHT_HEADING}: "${required}" — add decision summary (≥${MIN_TAKEAWAY_LEN} chars)`);
+        }
+    }
+    return errors;
+}
+export function parseCoverageMatrixRows(content) {
+    const section = extractSection(content, ASR_COVERAGE_HEADING);
+    const coverageStart = section.indexOf('### Coverage');
+    const coverageBlock = coverageStart === -1 ? section : section.slice(coverageStart);
+    const rows = [];
+    for (const line of coverageBlock.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('|'))
+            continue;
+        if (/^\|\s*---/.test(trimmed))
+            continue;
+        if (/^\|\s*Contract id/i.test(trimmed))
+            continue;
+        const parts = trimmed
+            .split('|')
+            .map((p) => p.trim())
+            .filter((_, i, arr) => i > 0 && i < arr.length - 1);
+        if (parts.length < 4)
+            continue;
+        const contractId = parts[0].replace(/`/g, '');
+        if (!contractId || PLACEHOLDER_RE.test(contractId))
+            continue;
+        const typeValues = new Set(['visual', 'audio', 'text', 'digit', 'sfx']);
+        let elementType = '';
+        let coverageLayer = '';
+        if (parts.length >= 4 && typeValues.has(parts[2]?.toLowerCase())) {
+            // id | elementType | Type | CoverageLayer | ...
+            elementType = parts[1];
+            coverageLayer = parts[3];
+        }
+        else if (parts.length >= 3 && typeValues.has(parts[1]?.toLowerCase())) {
+            // Legacy: id | Type | CoverageLayer | ...
+            coverageLayer = parts[2];
+        }
+        else {
+            elementType = parts.length >= 6 ? parts[1] : '';
+            coverageLayer = parts.length >= 4 ? parts[3] : parts[1] || '';
+        }
+        rows.push({
+            contractId,
+            elementType: elementType.replace(/`/g, ''),
+            coverageLayer: coverageLayer.toLowerCase(),
+        });
+    }
+    return rows;
+}
+export function validateSheetGridMetadata(content) {
+    const errors = [];
+    const section = extractSection(content, ASR_COVERAGE_HEADING);
+    if (!section.includes('### Sheet grid metadata')) {
+        errors.push('ASR Coverage Matrix: missing ### Sheet grid metadata table');
+        return errors;
+    }
+    const gridStart = section.indexOf('### Sheet grid metadata');
+    const gridBlock = section.slice(gridStart);
+    const gridEnd = gridBlock.search(/\n###\s+/);
+    const gridSection = gridEnd === -1 ? gridBlock : gridBlock.slice(0, gridEnd);
+    if (PLACEHOLDER_RE.test(gridSection)) {
+        errors.push('Sheet grid metadata: contains {{placeholders}} — fill real rows/cols/cell dimensions');
+    }
+    let dataRows = 0;
+    for (const line of gridSection.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('|'))
+            continue;
+        if (/^\|\s*---/.test(trimmed))
+            continue;
+        if (/^\|\s*Sheet/i.test(trimmed))
+            continue;
+        dataRows++;
+    }
+    if (dataRows < 2) {
+        errors.push('Sheet grid metadata: need at least ui + element sheet rows');
+    }
+    return errors;
+}
+export function validateCoverageRowCount(designerLog, layoutSpec) {
+    const errors = [];
+    const { elementIds, staticTextIds } = parseLayoutSpecContractIds(layoutSpec);
+    const expected = elementIds.length + staticTextIds.length;
+    const matrixRows = parseCoverageMatrixRows(designerLog);
+    if (expected === 0) {
+        errors.push('layout-spec: could not parse assetMapping/static text ids — fill Asset Mapping table');
+        return errors;
+    }
+    if (matrixRows.length < expected) {
+        errors.push(`Coverage Matrix: ${matrixRows.length} rows but layout-spec expects ${expected} (assetMapping + static text)`);
+    }
+    const contractSet = new Set([...elementIds, ...staticTextIds]);
+    const matrixIds = new Set(matrixRows.map((r) => r.contractId));
+    for (const id of contractSet) {
+        if (!matrixIds.has(id)) {
+            errors.push(`Coverage Matrix: missing row for contract id "${id}"`);
+        }
+    }
+    return errors;
+}
+export function validateTypeRepresentatives(designerLog) {
+    const errors = [];
+    const rows = parseCoverageMatrixRows(designerLog);
+    const typeLayers = new Map();
+    for (const row of rows) {
+        const type = row.elementType && row.elementType !== '—' ? row.elementType : row.contractId.split('_')[0];
+        if (!type)
+            continue;
+        if (!typeLayers.has(type))
+            typeLayers.set(type, new Set());
+        typeLayers.get(type).add(row.coverageLayer);
+    }
+    for (const [type, layers] of typeLayers) {
+        const hasRep = [...layers].some((l) => l.includes('on-asr')) || [...layers].some((l) => l.includes('mc-crop'));
+        if (!hasRep && layers.size > 0) {
+            const allExtends = [...layers].every((l) => l.includes('ta-extends') || l.includes('ta extends'));
+            if (allExtends) {
+                errors.push(`Coverage Matrix: elementType "${type}" has no on-asr or mc-crop representative`);
+            }
+        }
+    }
+    return errors;
+}
+export function validateAsrPngFiles(projectDir, option, designerLog) {
+    const errors = [];
+    const ui = path.join(projectDir, `assets/images/reference/ui_state_sheet_${option}.png`);
+    const el = path.join(projectDir, `assets/images/reference/element_state_sheet_${option}.png`);
+    const mc = path.join(projectDir, `assets/images/storyboard/master_composite_option_${option}.png`);
+    if (!fs.existsSync(mc)) {
+        errors.push(`Missing MC: assets/images/storyboard/master_composite_option_${option}.png`);
+    }
+    if (!fs.existsSync(ui)) {
+        errors.push(`Missing ASR: assets/images/reference/ui_state_sheet_${option}.png`);
+    }
+    if (!fs.existsSync(el)) {
+        errors.push(`Missing ASR: assets/images/reference/element_state_sheet_${option}.png`);
+    }
+    if (designerLog && /element_2|element_state_sheet_\w+_2\.png/i.test(designerLog)) {
+        const el2 = path.join(projectDir, `assets/images/reference/element_state_sheet_${option}_2.png`);
+        if (!fs.existsSync(el2)) {
+            errors.push(`Missing ASR overflow board: assets/images/reference/element_state_sheet_${option}_2.png`);
+        }
+    }
+    return errors;
+}
+export function validateDesignerGate2b(projectDir) {
+    const errors = [];
+    const logPath = path.join(projectDir, 'logs/designer-log.md');
+    const layoutPath = path.join(projectDir, 'docs/layout-spec.md');
+    const statePath = path.join(projectDir, 'docs/project-state.md');
+    if (!fs.existsSync(logPath)) {
+        return ['Create logs/designer-log.md before Gate #2b STOP'];
+    }
+    if (!fs.existsSync(layoutPath)) {
+        return ['Missing docs/layout-spec.md'];
+    }
+    const designerLog = fs.readFileSync(logPath, 'utf8');
+    const layoutSpec = fs.readFileSync(layoutPath, 'utf8');
+    errors.push(...validateImageProductionPreflight(designerLog));
+    if (!designerLog.includes(ASR_COVERAGE_HEADING)) {
+        errors.push(`Missing "${ASR_COVERAGE_HEADING}" section`);
+    }
+    else {
+        errors.push(...validateSheetGridMetadata(designerLog));
+        errors.push(...validateCoverageRowCount(designerLog, layoutSpec));
+        errors.push(...validateTypeRepresentatives(designerLog));
+    }
+    let option = 'A';
+    if (fs.existsSync(statePath)) {
+        const opt = readSelectedMcOption(fs.readFileSync(statePath, 'utf8'));
+        if (opt)
+            option = opt;
+    }
+    errors.push(...validateAsrPngFiles(projectDir, option, designerLog));
+    return errors;
+}
+export function validateAsrCoverageProject(projectDir) {
+    const layoutPath = path.join(projectDir, 'docs/layout-spec.md');
+    const logPath = path.join(projectDir, 'logs/designer-log.md');
+    let expectedContractRows = 0;
+    let matrixRows = 0;
+    if (fs.existsSync(layoutPath)) {
+        const ids = parseLayoutSpecContractIds(fs.readFileSync(layoutPath, 'utf8'));
+        expectedContractRows = ids.elementIds.length + ids.staticTextIds.length;
+    }
+    if (fs.existsSync(logPath)) {
+        matrixRows = parseCoverageMatrixRows(fs.readFileSync(logPath, 'utf8')).length;
+    }
+    const errors = validateDesignerGate2b(projectDir);
+    return {
+        ok: errors.length === 0,
+        errors,
+        expectedContractRows,
+        matrixRows,
+    };
+}

package/dist/commands/build.js

@@ -466,8 +466,8 @@ export async function buildCommand(projectPath, options) {
         ];
         // 渠道输出格式配置（根据各渠道Playable规格对照表）
         // 只支持 HTML: applovin, ironsource, unity, moloco, adikteev, remerge
-        // 只支持 ZIP: tiktok, liftoff, bigo, snapchat, inmobi
-        // 支持两种: facebook, google
+        // 只支持 ZIP: bigo, snapchat
+        // 支持两种: facebook, google, tiktok, liftoff, inmobi, mintegral
         const platformFormatConfig = {
             facebook: {
                 formats: ['html', 'zip'],
@@ -485,12 +485,12 @@ export async function buildCommand(projectPath, options) {
                 default: 'html',
                 description: 'Google Ads 支持两种格式'
             },
-            tiktok: { formats: ['zip'], default: 'zip' },
-            liftoff: { formats: ['zip'], default: 'zip' },
+            tiktok: { formats: ['html', 'zip'], default: 'html' },
+            liftoff: { formats: ['html', 'zip'], default: 'html' },
             bigo: { formats: ['zip'], default: 'zip' },
             snapchat: { formats: ['zip'], default: 'zip' },
-            inmobi: { formats: ['zip'], default: 'zip' },
-            mintegral: { formats: ['zip'], default: 'zip' },
+            inmobi: { formats: ['html', 'zip'], default: 'html' },
+            mintegral: { formats: ['html', 'zip'], default: 'html' },
         };
         // 获取渠道支持的格式
         const getPlatformFormats = (platform) => {

package/dist/commands/remix.js

@@ -120,7 +120,8 @@ async function remixEnsureStream(options) {
                 throw new Error(event.message || 'ensure-stream 返回 error 事件');
             }
             else if (event.type === 'capacity_exceeded') {
-                if (!event.candidates.length) {
+                const selectableCandidates = event.candidates.filter((c) => c.evictable !== false);
+                if (!selectableCandidates.length) {
                     throw new Error(`容量已满 (${event.current}/${event.max})，但服务端未返回可驱逐候选`);
                 }
                 const selected = await inquirer.prompt([
@@ -129,8 +130,9 @@ async function remixEnsureStream(options) {
                         name: 'slotId',
                         message: `沙箱容量已满 (${event.current}/${event.max})，请选择一个候选项继续驱逐:`,
                         choices: event.candidates.map((c) => ({
-                            name: `${c.slotId} (${c.projectId}/${c.branchName}) idle=${formatIdleSec(c.idleSec)}${c.hasUnpushedChanges ? ' [unpushed]' : ''}`,
+                            name: `${c.slotId} (${c.projectId}/${c.branchName}) status=${c.agentStatus ?? 'unknown'} idle=${formatIdleSec(c.idleSec)}${c.hasUnpushedChanges ? ' [unpushed]' : ''}`,
                             value: c.slotId,
+                            disabled: c.evictable === false ? (c.disabledReason ?? 'not evictable') : false,
                         })),
                     },
                 ]);

package/dist/commands/skills.js

@@ -20,6 +20,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseSkillRefsFromAtomPlanProject, validateAtomPlanProject } from '../atom-plan/validate-atom-plan.js';
+import { validateAsrCoverageProject } from '../atom-plan/validate-asr-coverage.js';
 import { loadConfig } from '../config.js';
 const KNOWN_ENGINES = ['phaser', 'threejs'];
 const SCORE_THRESHOLD_FULL = 8;
@@ -1352,6 +1353,29 @@ export function registerSkillsCommands(program) {
         if (!result.ok)
             process.exit(1);
     });
+    // ── validate-asr-coverage ─────────────────────────────────────────────────
+    addSkillsDirOption(skills
+        .command('validate-asr-coverage')
+        .description('校验 Gate #2b ASR Coverage Matrix、Image Production Preflight 与 ASR/MC PNG 文件')
+        .option('--project-dir <path>', '项目根目录', process.cwd())
+        .option('--json', '输出 JSON 格式')).action(async (opts) => {
+        void opts.skillsDir;
+        const result = validateAsrCoverageProject(opts.projectDir);
+        if (opts.json) {
+            process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        }
+        else if (result.ok) {
+            console.log(`\n✓ ASR coverage 校验通过（${result.matrixRows}/${result.expectedContractRows} Matrix rows）\n`);
+        }
+        else {
+            console.error('\n✗ ASR coverage 校验失败\n');
+            for (const e of result.errors)
+                console.error(`  - ${e}`);
+            console.error();
+        }
+        if (!result.ok)
+            process.exit(1);
+    });
     // ── read ──────────────────────────────────────────────────────────────────
     addSkillsDirOption(skills
         .command('read <atomId>')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.0.42",
+  "version": "0.0.44",
   "private": false,
   "type": "module",
   "bin": {
@@ -27,8 +27,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "^0.0.43",
-    "@playcraft/common": "^0.0.31",
+    "@playcraft/build": "^0.0.45",
+    "@playcraft/common": "^0.0.33",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "cors": "^2.8.6",

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

@@ -1,5 +1,5 @@
 ---
-description: "Designer: (1) Gate #2 visual+narrative (MC = Developer UI spec), (2) TA-ready handoff, (3) audio + digit strip — not full asset production."
+description: "Designer: (1) Gate #2 image production (MC + ASR), (2) TA-ready handoff, (3) audio + digit strip after #2b — not TA mass production."
 allowedTools:
   - "Read"
   - "Grep"
@@ -25,6 +25,8 @@ allowedTools:
 ---
 
 > **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).
+>
+> **Workflow spec**: `convergence-v1` + `designer-handoff-v2` — stage chain `pm → style_exploration → production → ui_pass → ui_review ⇄ ui_rework → gameplay_pass → done`. See [workflow-changelog.md](../../docs/team/workflow-changelog.md).
 
 # Designer — Playable Ads Design Agent
 
@@ -60,16 +62,16 @@ allowedTools:
 
 When trade-offs arise, preserve **#1 over #2 over #3**.
 
-1. **Lock visual + narrative direction (Gate #2)** — Master Composite (concept + 4 storyboard panels) is the **UI design spec Developer must restore**; experience flow text defines per-stage intent.
-2. **Enable unambiguous TA mass-production** — concept panel shows every key element type; **ASR** (UI + element state reference sheets) only after user picks a MC option; `Style Intent Notes` / `Anti-Pattern Notes` in `designer-log.md`.
-3. **Deliver audio + digit strip in confirmed style** — BGM / SFX / digit sprite strip at contracted paths, mood-matched to the selected MC.
+1. **Image production (Gate #2)** — Master Composite (MC Panel 1 = all element types + UI) + **ASR** dual sheets with **isolated, crop-ready cells**; Coverage Matrix 100% rows with CoverageLayer (on-asr / mc-crop / ta-extends).
+2. **Lock visual + narrative direction** — MC storyboard panels + experience flow; MC is **Developer UI design spec**.
+3. **Deliver audio + digit strip after Gate #2b** — BGM / SFX / digit strip (Phase 2 `production` only); mood-matched to locked MC.
 
 ### Success criteria
 
-| Phase                             | You succeed when                                                                                      |
-| --------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| **Phase 1** (`style_exploration`) | ≥2 MC; ASR dual sheets; Handoff Pack (Coverage Matrix, Palette Locked, Motion Notes); MC ratio checks |
-| **Phase 2** (`production`)        | BGM/SFX/digit strip; VisualAtoms `done` per v2 rules; no open ICP for Designer                        |
+| Phase                             | You succeed when                                                                                                                                                             |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Phase 1** (`style_exploration`) | ≥2 MC; ASR dual sheets (cells isolated); Image Production Preflight; Handoff Pack (Coverage Matrix 100% rows + CoverageLayer, Palette Locked, Motion Notes); MC ratio checks |
+| **Phase 2** (`production`)        | BGM/SFX/digit strip; VisualAtoms `done` per v2 rules; no open ICP for Designer                                                                                               |
 
 ### Deprioritized / Non-goals (summary)
 
@@ -83,7 +85,7 @@ Full element sets & TA pipelines; single MC before Gate #2; audio before style l
 
 ## Identity
 
-**Art Director + Sound Designer** (designer-handoff-v2): you **生** direction — MC, ASR, audio. TA **产** — extract, atlases, completions. Ph.2: **no** batch `tile_sample_*.png`; visual baseline = ASR. TA tools **not yours**: `sprite-sheet`, `animate`, `use-vfx`, `segment`, `3d *`.
+**Art Director** (image-first, designer-handoff-v2): you **生** direction — **MC + ASR** (Phase 1), then audio (Phase 2). TA **产** — crop, remove-background, atlases. Ph.2: **no** batch `tile_sample_*.png`; visual baseline = MC + ASR. **Do not** run `remove-background` on ASR sheets — TA owns that. TA tools **not yours**: `sprite-sheet`, `animate`, `use-vfx`, `segment`, `3d *`.
 
 ## File Access
 
@@ -103,18 +105,20 @@ Full element sets & TA pipelines; single MC before Gate #2; audio before style l
 
 **Skills:** `playcraft-audio-generation`; `playcraft-style-qa` (ICP supplementary PNGs only) | **Refs:** `designer-color-audio-recipes.md`, `designer-deliverable-spec.md` § Phase 2 | Mark VisualAtoms `actualOutput: ASR:...` when covered.
 
-## DAG & critical rules (max 9)
+## DAG & critical rules
 
 0. **四件套纪律** — visual narrative / Handoff Pack / ASR tables live in **`style-exploration` + `designer-log`** only; do **not** bloat `design-brief` or `layout-spec` (PM owns contracts). Palette deltas → `designer-log` § Palette Locked.
-1. **DAG**: redundant atom → `⏭️ skipped`; missing asset → add row; direction changes → STOP; append **DAG Revisions**.
-2. MC concept panel = **real game**, not sketch — all key element types visible; storyboards mandatory for Gate #2 narrative lock.
-3. **≥2 MC options** before #2a unless user pre-locked reference; **ASR only after** `selectedMcOption`.
-4. MC = **5×完整 9:16 H5** (e.g. 3600×1280 or 4096×1455); never `1:1` / `10:3`; verify with `playcraft image info`.
-   4b. **MC models whitelist only** — `mulerouter/gpt-image-2` or `mulerouter/nano-banana-2` (provider prefix required); **never** gemini/flux/hy-image/wan/qwen or bare `gpt-image-2` for MC (see `playcraft-storyboard` §3).
-5. **ASR: zero overlap** — UI 板与元素板各自网格无接触；有重叠则重生成。
-6. **No audio** until style confirmed (#2b).
-7. **Layout Spec** binding — paths, palette, naming; Palette Locked documents MC vs spec delta.
-8. **English prompts**; **size gate** after every generation; **no VisualAtom `done` without ASR Coverage Matrix row**.
-9. **mediaGroups first for audio** — read `atom-plan.json` → `skillsMatch.mediaGroups` for AudioAtom matches (BGM/SFX); if a pre-matched audio exists, link it directly (`playcraft skills link`) instead of generating from scratch. Skip only when quality/mood mismatch (document reason in `dagRevisions`).
-10. **Skill Preflight before Phase 2** — before generating audio or digit strips, read relevant Skills: `playcraft-audio-generation`, `playcraft-text-rendering`, `playcraft-image-generation` (§ background). Fill `designer-log.md` § Skill Preflight table. Do not "freelance" — follow platform patterns.
-11. **Update atom status on completion** — after each atom is done: update `atom-plan.json` → `atoms[].status = "done"` + `atoms[].actualOutput = "<path>"` (or `"ASR:<sheet>:<region>"`). Write `atom-plan.md` § Asset Skill Context. **Never** leave atoms at `pending` after delivery.
+1. **Image Production Preflight (Phase 1)** — before MC/ASR: fill `designer-log.md` § **Image Production Preflight** (storyboard + asset-state-sheet + image-generation §3/§3.1).
+2. **DAG**: redundant atom → `⏭️ skipped`; missing asset → add row; direction changes → STOP; append **DAG Revisions**.
+3. MC concept panel = **real game**, not sketch — **all element types** visible; storyboards mandatory for Gate #2 narrative lock.
+4. **≥2 MC options** before #2a unless user pre-locked reference; **ASR only after** `selectedMcOption`.
+5. MC = **5×完整 9:16 H5** (e.g. 3600×1280 or 4096×1455); never `1:1` / `10:3`; verify with `playcraft image info`.
+   5b. **MC models whitelist only** — `mulerouter/gpt-image-2` or `mulerouter/nano-banana-2` (provider prefix required); **never** gemini/flux/hy-image/wan/qwen or bare `gpt-image-2` for MC (see `playcraft-storyboard` §3).
+6. **ASR: zero overlap + crop-ready cells** — grid cells non-overlapping; each cell **one isolated element**; sheet opaque OK; gold/orange cells use blue chroma per `playcraft-image-generation` §3; **never** remove-background on ASR.
+7. **Coverage Matrix** — 100% contract rows; each **elementType** ≥1 row with CoverageLayer `on-asr` or `mc-crop`; mirror `on-asr` → `atom-plan.json` `asrSlot`.
+8. **No audio** until Gate #2b passed (Phase 2 only).
+9. **Layout Spec** binding — paths, palette, naming; Palette Locked documents MC vs spec delta.
+10. **English prompts**; **size gate** after every image generation; **no VisualAtom `done` without Coverage Matrix row**.
+11. **mediaGroups first for audio (Phase 2)** — read `atom-plan.json` → `skillsMatch.mediaGroups` for AudioAtom matches; link before generate.
+12. **Skill Preflight before Phase 2** — audio/digit Skills in `designer-log.md` § Skill Preflight (Phase 2 section).
+13. **Update atom status on completion** — `atom-plan.json` status + `actualOutput` (`ASR:...` or path); **never** leave atoms `pending` after delivery.

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

@@ -19,6 +19,8 @@ allowedTools:
 ---
 
 > **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).
+>
+> **Workflow spec**: `convergence-v1` — Developer runs in `ui_pass` (devStatus `ui_ready`) then `gameplay_pass` (devStatus `ready`); never in `production`. See [workflow-changelog.md](../../docs/team/workflow-changelog.md).
 
 # Developer — Playable Ads Developer Agent
 

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

@@ -17,6 +17,8 @@ allowedTools:
 ---
 
 > **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).
+>
+> **Workflow spec**: `convergence-v1` — stage chain `pm → style_exploration → production → ui_pass → ui_review ⇄ ui_rework → gameplay_pass → done`. See [workflow-changelog.md](../../docs/team/workflow-changelog.md).
 
 # PM — Playable Ads Project Manager
 
@@ -102,7 +104,7 @@ Intent fidelity, spec completeness, schedule feasibility, Gate clarity.
 | --- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
 | 1   | `docs/project-state.md` | `stage: pm`, `gates.#1 = pending`, handoff STOP (`gate_pending: "1"`)                                                                |
 | 2   | `docs/design-brief.md`  | Style Direction: Dimension + Modality + Arc + 6 elements; experience flow                                                            |
-| 3   | `docs/layout-spec.md`   | `assetMapping` (locked paths) + atlas grouping table (tiles / ui / vfx)                                                              |
+| 3   | `docs/layout-spec.md`   | `assetMapping` + atlas groups + **Element Type Registry** (≤20 types)                                                                |
 | 4   | `docs/atom-plan.json`   | **`skillsMatch`** + **`atoms[]`** with `assignTo`/`dependsOn`; Gameplay/Config **`skillRef`** from snapshot — hook validates on STOP |
 | 5   | `docs/atom-plan.md`     | **Acceptance criteria only** at Gate #1 (no Atom List / DAG Order mirror)                                                            |
 

package/project-template/.claude/agents/refs/designer-deliverable-spec.md

@@ -29,10 +29,12 @@ All visible text is image assets — **zero font files**. Static text is baked i
 | Extract from MC concept panel         | TA → `layout-spec` bg path                                       |
 | 2.5D / hero bg needs dedicated sample | PM marks VisualAtom `assignTo: Designer` → ICP isolated PNG only |
 
-## Phase 1 Deliverables
+## Phase 1 Deliverables — Image production (MC + ASR)
 
 Gate #2a: **one MC per option** + Experience Flow text. Gate #2b (after `selectedMcOption`): **ASR dual sheets** + **Handoff Pack** (below).
 
+> **Phase 1 scope = images only.** Audio/digit strip is **Phase 2** after Gate #2b — see § Phase 2 Deliverables.
+
 | #   | Deliverable                       | Format | Spec                                                       |
 | --- | --------------------------------- | ------ | ---------------------------------------------------------- |
 | 1   | **Master Composite**              | PNG 4K | 5 panels: concept + 4 storyboard scenes                    |
@@ -67,15 +69,34 @@ Paths: `assets/images/storyboard/master_composite_option_[A|B|C].png`
 
 ### Deliverable 2: ASR
 
-> **Skill**: `playcraft-asset-state-sheet`
+> **Skill**: `playcraft-asset-state-sheet` + `playcraft-image-generation` §3.1 (ASR branch)
 
 Only after `selectedMcOption` is set. `--reference-image` = confirmed MC.
 
 ```
 assets/images/reference/ui_state_sheet_[X].png
 assets/images/reference/element_state_sheet_[X].png
+# optional when types > 12:
+assets/images/reference/element_state_sheet_[X]_2.png
 ```
 
+**ASR whole PNG is opaque by design** — TA crops cells then `remove-background`. Designer must deliver **isolated elements per cell** (no white box / scene inside cells).
+
+#### Three-layer coverage model
+
+| CoverageLayer  | Meaning                             | Matrix columns                              |
+| -------------- | ----------------------------------- | ------------------------------------------- |
+| **on-asr**     | Physical slot on ASR PNG (`R#C#`)   | `ASR sheet` + `Grid`                        |
+| **mc-crop**    | Visible in MC Panel 1, no ASR slot  | `ASR sheet` = `MC-crop` + note Panel region |
+| **ta-extends** | Color variant / extra states for TA | `TA extends? = yes` + Style Intent line     |
+
+**100% Matrix rows** = every `assetMapping` elementId + every static text id has **one row**.  
+**NOT** every row needs a physical ASR slot — use layers above.
+
+**Type representative rule**: each **element type** (from `layout-spec` § Element Type Registry or Matrix `elementType` column) must appear in **on-asr** or **mc-crop** at least once.
+
+Physical slot budget: **8–12 slots per sheet**; overflow → second element sheet or mc-crop + ta-extends.
+
 ---
 
 ### Gate #2b Handoff Pack (mandatory before `#2b` STOP)
@@ -86,12 +107,20 @@ assets/images/reference/element_state_sheet_[X].png
 
 One row per contract item from `layout-spec.md`:
 
-| Contract id                     | Type   | ASR sheet    | Grid    | State(s)     | TA extends? |
-| ------------------------------- | ------ | ------------ | ------- | ------------ | ----------- |
-| `elementId` from assetMapping   | visual | ui / element | row,col | e.g. default | yes/no      |
-| `staticTextId` from Text Assets | text   | ui / MC crop | —       | baked        | yes/no      |
+| Contract id                     | elementType | Type   | CoverageLayer                 | ASR sheet              | Grid | State(s)     | TA extends? |
+| ------------------------------- | ----------- | ------ | ----------------------------- | ---------------------- | ---- | ------------ | ----------- |
+| `elementId` from assetMapping   | `tile`      | visual | on-asr / mc-crop / ta-extends | ui / element / MC-crop | R1C1 | e.g. default | yes/no      |
+| `staticTextId` from Text Assets | —           | text   | mc-crop or on-asr             | ui / MC-crop           | —    | baked        | yes/no      |
 
-**100% rule**: every `elementId` in `assetMapping` and every static text id must have a row. Empty ASR slot → `TA extends? = yes` + note in Style Intent Notes.
+**100% rule**: every `elementId` in `assetMapping` and every static text id must have a row.
+
+**CoverageLayer rules**:
+
+- **on-asr**: must have valid `Grid` (R#C#) and matching PNG slot; mirror to `atom-plan.json` → `asrSlot`
+- **mc-crop**: MC Panel 1 shows type; document region in Style Intent Notes
+- **ta-extends**: color variants / full state sets; `TA extends? = yes` + one-line extension hint
+
+**Forbidden**: missing rows; all rows `ta-extends` with no on-asr/mc-crop type representative; overlapping ASR slots.
 
 #### 2. Palette Locked (`logs/designer-log.md`)
 
@@ -172,6 +201,16 @@ For each `assignTo: Designer` VisualAtom:
 
 **Forbidden**: mark VisualAtom `done` without ASR row or supplementary file.
 
+#### ICP supplementary PNG — when (and only when) to produce
+
+Designer Phase 2 supplementary PNGs are a **fallback path**, not a default. Produce one **only if all three** are true:
+
+1. **TA Step 0c Style Interpretation** marks that atom's `confidence = low` in `logs/ta-log.md` (i.e. Designer's MC/ASR didn't tell TA enough).
+2. **Crop / segment from ASR or MC failed** — TA tried `playcraft image crop` (grid coord from ASR Coverage Matrix) and `playcraft image segment --boxes` / `--text` on the MC concept panel, and the extracted region is unusable (chroma residue, partial element, wrong perspective).
+3. **TA opens an ICP entry** in `docs/intent-clarifications.md` with `routeTo: designer`, citing both ① the failed extraction command and ② the specific style ambiguity.
+
+If any of ①②③ is missing, the fix lives elsewhere (TA tool chain, Designer Style Intent Notes patch, or PM contract patch) — not a supplementary PNG. Document the chosen route in `designer-log.md`.
+
 Run **`playcraft-style-qa` §1** only for **ICP supplementary** image files (not for ASR sheets themselves).
 
 ### TA ownership in Phase 2 (not Designer)