@playcraft/cli 0.0.40 → 0.0.42

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

@@ -0,0 +1,343 @@
+# Technical Artist Log
+
+## Upstream Intake
+
+> **Step 0a — mandatory before Skill Discovery or any generation.** Read each doc; one-line takeaway proves you understood upstream work. PM/Designer keep **四件套** short — detail is in `style-exploration` + this project's `designer-log`.
+
+| Doc                         | Read ✓ | One-line takeaway (what matters for TA this round)      |
+| --------------------------- | ------ | ------------------------------------------------------- |
+| `docs/project-state.md`     | ☐      | {{e.g. Wave 1 done, selectedMcOption=B}}                |
+| `docs/design-brief.md`      | ☐      | {{e.g. Competence arc, match-3, Hook=wrong-move tease}} |
+| `docs/layout-spec.md`       | ☐      | {{e.g. 42 assetMapping rows, 3 atlas groups}}           |
+| `docs/atom-plan.json`       | ☐      | {{e.g. 18 TA atoms, C₁ refs designer-sample}}           |
+| `docs/atom-plan.md`         | ☐      | TA Skill Context                                        |
+| `docs/style-exploration.md` | ☐      | {{e.g. MC path + storyboard EndCard tone}}              |
+| `logs/designer-log.md`      | ☐      | {{e.g. Palette Locked delta, Style Intent Notes}}       |
+
+```bash
+# Optional paste: ls assets/images/reference/ + key contract dirs after read
+{{intake_ls_snippet}}
+```
+
+---
+
+## Delivery Summary
+
+- **Assigned atoms**: {{total_assigned}}
+- **Completed**: {{total_completed}}
+- **Skipped**: {{total_skipped}}
+- **Blocked**: {{total_blocked}}
+- **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.**
+> Read `logs/designer-log.md` Style Intent Notes, write your interpretation here.
+
+| #     | Designer Intent (Quote from designer-log.md) | My Interpretation     | Confidence      | Action            |
+| ----- | -------------------------------------------- | --------------------- | --------------- | ----------------- |
+| {{n}} | "{{designer_quote}}"                         | {{my_interpretation}} | high/medium/low | proceed / clarify |
+
+<!--
+Confidence rules:
+  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
+
+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`
+- **ASR references**: `ui_state_sheet_{{selectedMcOption}}.png`, `element_state_sheet_{{selectedMcOption}}.png`
+- **Designer samples used as reference**: {{designer_sample_paths}}
+- **Reference model used**: `{{model_name}}` (must be `google/` native for style-consistent completions)
+
+---
+
+## Asset Completion Log
+
+> Records all elements derived from Designer samples.
+
+### {{atom_id}} — {{slot_name}}
+
+- **Status**: {{status}}
+- **Completion type**: {{derived_from_sample | sprite_sheet | 3d_render | animation | vfx}}
+- **Source samples**: {{designer_sample_paths}}
+- **Elements completed**:
+  | File | Dimensions | Size | Notes |
+  |------|-----------|------|-------|
+  | {{path}} | {{WxH}} | {{size}} | {{notes}} |
+- **Pipeline**:
+  ```
+  {{step 1: e.g., generate-image --reference-image ...}}
+  {{step 2: e.g., image remove-background ...}}
+  {{step 3: e.g., image resize ...}}
+  ```
+- **Model used**: {{model_name}}
+- **Reference images**: {{reference_image_paths}}
+
+<!-- Repeat for each completion atom -->
+
+---
+
+## Technical Pipeline Log
+
+> Records all technical production work (sprite sheets, 3D, animation, VFX, post-processing).
+
+### {{atom_id}} — {{slot_name}}
+
+- **Status**: {{status}}
+- **Pipeline type**: {{sprite_sheet | 3d_model | animation_frames | vfx | image_processing | audio_processing}}
+- **Input**: {{input_files}}
+- **Output**: {{output_files}}
+- **Commands executed**:
+  ```bash
+  {{command 1}}
+  {{command 2}}
+  ```
+- **Result**:
+  | File | Format | Dimensions | Size | Frame Count |
+  |------|--------|-----------|------|-------------|
+  | {{path}} | {{format}} | {{WxH}} | {{size}} | {{N or —}} |
+
+<!--
+For sprite_sheet / animation_frames / vfx pipeline types, fill the Sprite Grid Params section below.
+JSON is only auto-generated by `sprite-sheet` command. `animate` and `use-vfx` produce PNG only.
+-->
+
+- **Sprite Grid Params** _(animation_frames / vfx 必填；sprite_sheet 填"见 JSON")_:
+  - columns: {{N or "见 JSON"}}
+  - frameWidth: {{W}}px _(or "见 JSON")_
+  - frameHeight: {{H}}px _(or "见 JSON")_
+  - frameCount: {{N or "见 JSON"}}
+  - padding: {{0 or N}}px
+  - JSON available: {{yes — `<path>.json` (sprite-sheet) / no — params above are source of truth (animate/use-vfx)}}
+  - Dimensions verified: {{width = cols×frameW ✅ / ❌ mismatch}} | {{channels = 4 ✅ / ❌ no alpha}}
+
+<!-- Repeat for each pipeline atom -->
+
+---
+
+## Micro-Batch Validation
+
+> **Per asset type — first 2 completions must pass validation before continuing batch production.**
+> Compare each completion side-by-side with the Designer sample.
+
+### {{asset_type}} (e.g., tiles / ui / bg / vfx)
+
+| Batch | Files         | Consistency Score (1-5) | Deviation Items    | Adjustments Made |
+| ----- | ------------- | ----------------------- | ------------------ | ---------------- |
+| {{n}} | {{file_list}} | {{score}}               | {{deviation_list}} | {{adjustments}}  |
+
+<!--
+Consistency Score criteria:
+  5 — Perfect match: could be mistaken for original designer sample
+  4 — Good match: minor differences only visible on close inspection
+  3 — Acceptable match: style is recognizable but some attributes drift
+  2 — Poor match: obvious style deviation, needs significant adjustment
+  1 — Mismatch: completely different style, STOP and ask Designer
+
+Score < 3 → STOP this asset type, write question to docs/intent-clarifications.md
+-->
+
+---
+
+## Compliance Gate Results
+
+> Completed after Designer Ph.2 is confirmed done. Verify all assetMapping entries.
+
+### Asset Coverage Check
+
+| assetMapping Entry | Expected Path        | File Exists? | Dimensions | Size     | Status        |
+| ------------------ | -------------------- | ------------ | ---------- | -------- | ------------- |
+| {{elementId}}      | {{visualAsset_path}} | {{Yes/No}}   | {{WxH}}    | {{size}} | {{PASS/FAIL}} |
+
+<!--
+Fill one row per entry in layout-spec.md assetMapping.
+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}} |
+
+### 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}}
+- **Blockers** (if any): {{list of FAIL items that block integration}}
+- **Ready for Developer Phase 2**: {{Yes / No — pending fixes}}
+
+---
+
+## Handoff to Developer
+
+Summary of what TA delivers to Developer:
+
+| Asset Type          | Count | Paths                  | Notes                 |
+| ------------------- | ----- | ---------------------- | --------------------- |
+| Background images   | {{N}} | `assets/images/bg/`    | {{notes}}             |
+| Tile/element images | {{N}} | `assets/images/tiles/` | {{notes}}             |
+| UI elements         | {{N}} | `assets/images/ui/`    | {{notes}}             |
+| Sprite sheet atlas  | {{N}} | `assets/images/*/`     | Each has paired .json |
+| Animation frames    | {{N}} | `assets/images/*/`     | {{notes}}             |
+| VFX sprite sheets   | {{N}} | `assets/images/vfx/`   | {{notes}}             |
+| 3D GLB models       | {{N}} | `assets/models/`       | {{notes}}             |
+| BGM audio           | {{N}} | `assets/audio/bgm/`    | {{notes}}             |
+| SFX audio           | {{N}} | `assets/audio/sfx/`    | {{notes}}             |
+
+**All files path-match `layout-spec.md` assetMapping**: {{Yes / No}}
+
+<!--
+If No, list discrepancies here so Developer knows to use alternate paths.
+-->