@playcraft/cli 0.0.41 → 0.0.43

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,57 @@
 - **Designer samples received**: {{designer_sample_count}} files
 - **TA-completed elements**: {{ta_completed_count}} files
 
+---
+
+## mediaGroups Reuse
+
+> **Step 0 Pre — mandatory before Skill Discovery.** Filter `atom-plan.json` → `skillsMatch.mediaGroups` by `extension`; TA is responsible for **`.aiimage` + `.aisprite`** (Designer handles `.aiaudio`).
+
+| mediaGroup atomId | extension          | Matches TA atom? | Disposition   | Reason (if skipped)             | Output path (if linked) |
+| ----------------- | ------------------ | ---------------- | ------------- | ------------------------------- | ----------------------- |
+| {{mg_atomId}}     | .aiimage/.aisprite | {{atom_id / —}}  | linked / skip | {{style mismatch / wrong dims}} | {{path / —}}            |
+
+<!--
+  TA scope (this table):
+    .aiimage  — single-shot image bundles (bg, single ui element, single tile)
+    .aisprite — sprite-sheet bundles (multi-frame: tile sets, vfx, animations)
+
+  Out of TA scope (do NOT fill rows for these — Designer owns them):
+    .aiaudio — BGM / SFX → see designer-log.md § mediaGroups Reuse
+
+  Filter command:
+    cat docs/atom-plan.json | jq '.skillsMatch.mediaGroups[] | select(.extension == ".aiimage" or .extension == ".aisprite")'
+
+  Disposition rules:
+    linked → playcraft skills link → post-process (resize/convert/transparency) → status=done
+    skip   → quality / style / wrong dimensions → 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.**
@@ -40,14 +91,106 @@
 | {{n}} | "{{designer_quote}}"                         | {{my_interpretation}} | high/medium/low | proceed / clarify |
 
 <!--
-Confidence rules:
+Confidence rules (atom-granularity — hold only the affected asset type, not the whole Wave 2):
   high    → proceed with completion
   medium  → proceed, but include style interpretation in --reference-image prompt
-  low     → MUST write question to docs/intent-clarifications.md before proceeding
+  low     → HOLD that asset type only: write question to docs/intent-clarifications.md
+           (routeTo: designer if style ambiguity; routeTo: pm if contract ambiguity)
+           → continue producing OTHER asset types where confidence ≥ medium
+           → resume the held type only after ICP answer (or Designer supplementary PNG per
+             designer-deliverable-spec.md § "ICP supplementary PNG — when (and only when)")
+
+You may STOP only when EVERY remaining asset type is held at confidence=low — otherwise keep
+making progress on the producible ones in parallel with the ICP wait.
+-->
+
+## 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}} |
 
-Do NOT proceed with any asset type where confidence = low.
+<!--
+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`
@@ -162,17 +305,40 @@ Every row must be PASS before advancing to integration.
 
 ### Spec Compliance Summary
 
-| Check                    | Target                     | Actual     | Result        |
-| ------------------------ | -------------------------- | ---------- | ------------- |
-| Background dimensions    | {{assetSpec}}              | {{actual}} | {{PASS/FAIL}} |
-| Tile dimensions          | {{assetSpec}}              | {{actual}} | {{PASS/FAIL}} |
-| UI element dimensions    | {{assetSpec}}              | {{actual}} | {{PASS/FAIL}} |
-| Background file size     | < 500KB                    | {{actual}} | {{PASS/FAIL}} |
-| Tile file size           | < 100KB per tile           | {{actual}} | {{PASS/FAIL}} |
-| BGM file size            | < 300KB                    | {{actual}} | {{PASS/FAIL}} |
-| SFX file size            | < 50KB per SFX             | {{actual}} | {{PASS/FAIL}} |
-| Total assets size        | ≤ 2-3MB                    | {{actual}} | {{PASS/FAIL}} |
-| Sprite sheet JSON paired | Every .png sheet has .json | {{yes/no}} | {{PASS/FAIL}} |
+| Check                      | Target                                                     | Actual     | Result        |
+| -------------------------- | ---------------------------------------------------------- | ---------- | ------------- |
+| Background dimensions      | {{assetSpec}}                                              | {{actual}} | {{PASS/FAIL}} |
+| Tile dimensions            | {{assetSpec}}                                              | {{actual}} | {{PASS/FAIL}} |
+| UI element dimensions      | {{assetSpec}}                                              | {{actual}} | {{PASS/FAIL}} |
+| **Text dimensions**        | `images/txt/*` per `layout-spec` text spec (W×H per label) | {{actual}} | {{PASS/FAIL}} |
+| **Digit Strip dimensions** | `images/txt/digits*` cellW × cellH × frameCount (0–9 = 10) | {{actual}} | {{PASS/FAIL}} |
+| Background file size       | < 500KB                                                    | {{actual}} | {{PASS/FAIL}} |
+| Tile file size             | < 100KB per tile                                           | {{actual}} | {{PASS/FAIL}} |
+| BGM file size              | < 300KB                                                    | {{actual}} | {{PASS/FAIL}} |
+| SFX file size              | < 50KB per SFX                                             | {{actual}} | {{PASS/FAIL}} |
+| Total assets size          | ≤ 2-3MB                                                    | {{actual}} | {{PASS/FAIL}} |
+| Sprite sheet JSON paired   | Every .png sheet has .json                                 | {{yes/no}} | {{PASS/FAIL}} |
+
+<!--
+  Text dimensions: every `images/txt/*` asset must match per-label W×H from layout-spec § Static text (or atlas grouping for text atlas).
+  Digit Strip dimensions: digit sprite (typically `images/txt/digits.webp` or `images/ui/digits.webp`) must satisfy:
+    - frameCount = 10 (0–9) — for score / countdown / level display
+    - width  == cellW × frameCount (when laid out as a single row)
+    - height == cellH (single-row strip)  OR  width × height matches multi-row grid in JSON sidecar
+    - channels = 4 (alpha for overlay)
+  If digit strip is split across multiple paths (e.g. small + large) each needs its own row.
+-->
+
+### 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