@playcraft/cli 0.0.41 → 0.0.42

package/project-template/.claude/agents/refs/reviewer-six-dimension-eval.md

@@ -1,286 +1,6 @@
-# Reviewer: Six-Dimension Evaluation & Scoring
+# Reviewer: Six-Dimension Evaluation (deprecated)
 
-> **Read before scoring and for the full audit loop.** Contains: Dev walkthrough; **Steps 0–0b + Phases 1–5** (DAG, layout, TA log, psychology, technical checks, six dimensions, DAG revisions); **scoring + veto**; **Rework mechanism** (rounds, severity, routing).
+> **Superseded by [`reviewer-convergence-eval.md`](./reviewer-convergence-eval.md)** in `convergence-v1`.
+> Do not use six-dimension scoring or final `review`/`rework` stages.
 
-**Developer alignment**: Style Consistency + Intent Fidelity → **Dev UI match**; Experience Flow + Difficulty Balance → **Dev gameplay match**; technical checks + veto items → runtime in Dev. **Dev walkthrough pass ≠ optional.** Build is not required for review pass.
-
----
-
-## Dev walkthrough (before six-dimension scoring)
-
-Perform in browser at **devUrl** from `project-state.md` (start with `npm run dev` if down).
-
-### UI match (maps to Style Consistency + Intent Fidelity)
-
-| Check                       | Compare against                                                 |
-| --------------------------- | --------------------------------------------------------------- |
-| Layout / zones / hierarchy  | `layout-spec.md`                                                |
-| Color, mood, MC fidelity    | `style-exploration.md`, Gate #2 MC (concept panel + storyboard) |
-| Per-stage visual intent     | Storyboard panels 2–5 in style-exploration                      |
-| Text-as-image, sprites, VFX | Live Dev vs approved design                                     |
-
-### Gameplay match (maps to Experience Flow + Difficulty Balance)
-
-| Check                                 | Compare against                    |
-| ------------------------------------- | ---------------------------------- |
-| Hook → Tutorial → Gameplay → End Card | `design-brief.md` experience flow  |
-| First level guaranteed success        | PGS / atom-plan (**veto** if fail) |
-| Near-Win, difficulty, CTA timing      | design-brief + Dev playthrough     |
-
-Record pass/fail summary in `project-state.reviewerDevNotes` and `reviewerDevCheck`.
-
----
-
-## Phase 4: Six-Dimension Experience Evaluation
-
-Simulate the player walking through Hook → Tutorial → Gameplay → End Card:
-
-### 1. Experience Flow (experienceFlow)
-
-| Checkpoint          | Criteria                                                                                                                                              |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Hook (0-3s)         | Immediate visual/interactive hook? Attention captured in 3s? Does it match the Hook frame in `style-exploration.md` storyboard?                       |
-| Tutorial (3-10s)    | Clear? Player understands core mechanic in 2-3 steps? Does it align with the Tutorial storyboard frame intent (low-pressure, guide elements visible)? |
-| Gameplay (10-25s)   | Smooth loop? Good pacing? No dead ends? Is Near-Win designed as specified in design-brief — with a visible solution?                                  |
-| End Card (25-30s)   | Natural CTA transition? Button visible and clickable? Does it create sequel feeling (not closure) as designed in EndCard storyboard frame?            |
-| Total duration      | Fits within 15-30 seconds?                                                                                                                            |
-| Storyboard fidelity | Does the final playable match the emotional arc and visual composition described in the Experience Flow Design section of `style-exploration.md`?     |
-
-### 2. Creative Appeal (creativeAppeal)
-
-| Checkpoint           | Criteria                                          |
-| -------------------- | ------------------------------------------------- |
-| Hook strength        | Does opening visual stop the user from scrolling? |
-| Freshness            | Differentiated or template-feeling?               |
-| Emotional connection | Curiosity/excitement/satisfaction triggered?      |
-| Memorability         | What sticks after playing?                        |
-
-### 3. Style Consistency (styleConsistency)
-
-| Checkpoint          | Criteria                                                                                         |
-| ------------------- | ------------------------------------------------------------------------------------------------ |
-| Concept fidelity    | Do final assets match the approved **concept panel** (Panel 1) from style-exploration.md?        |
-| Storyboard fidelity | Do Hook/Tutorial/Gameplay/EndCard stages visually match storyboard panels 2–5?                   |
-| Visual internal     | Background, characters, UI belong to same style? Colors unified?                                 |
-| Audio internal      | BGM and SFX harmonious?                                                                          |
-| Cross-media         | Visual style and audio atmosphere match? Does audio-emotion rhythm match Experience Flow Design? |
-| Gameplay-style      | Gameplay pacing matches visual/audio rhythm?                                                     |
-
-### 4. Intent Fidelity (intentFidelity)
-
-| Checkpoint      | Criteria                                            |
-| --------------- | --------------------------------------------------- |
-| Gameplay type   | Actual gameplay matches design-brief selection?     |
-| Visual style    | Matches intentTags?                                 |
-| Experience flow | Follows design-brief experienceFlow?                |
-| Level config    | Matches levelConfig (number of levels, difficulty)? |
-| Atom coverage   | Every atom in plan is implemented?                  |
-
-### 5. Difficulty Balance (difficultyBalance)
-
-| Checkpoint          | Criteria                                                     |
-| ------------------- | ------------------------------------------------------------ |
-| First level success | **GUARANTEED?** (veto item — automatic fail if not)          |
-| Difficulty curve    | Progressive? No sudden spikes?                               |
-| Frustration control | Failure gives positive feedback ("try again" not "give up")? |
-| Completability      | Can finish within time limit?                                |
-
-### 6. Intent Transmission (intentTransmission)
-
-**Check `docs/intent-clarifications.md`:**
-
-- Any unresolved Open Questions? (deduct 1 point per unresolved question)
-- Any Agent received >3 questions? (intent transmission fault)
-
-**Check `logs/ta-log.md`:**
-
-- Style Interpretation table exists?
-- Any low-confidence items without corresponding clarifications?
-- Micro-Batch Validation scores all >= 3?
-
-**Check `logs/developer-log.md`:**
-
-- Experience Flow → Code Mapping exists?
-- All scenes have storyboard frame references?
-- Code visual implementation matches storyboard intent?
-
-**Scoring calibration (1–5):**
-
-- 5: Zero open clarifications, TA self-check all pass, Developer mapping complete
-- 4: 1–2 resolved clarifications, no quality impact
-- 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
-
----
-
-## Scoring
-
-Each dimension: 1–5 points. **Maximum total: 30** (6 × 5).
-
-| Score | Meaning                                                | Calibration Example                             |
-| ----- | ------------------------------------------------------ | ----------------------------------------------- |
-| 5     | Excellent — exceeds expectations, ready to ship        | Polished feel, strong hook, perfect consistency |
-| 4     | Good — meets standard, minor tweaks then ship          | Solid execution, one small inconsistency        |
-| 3     | Acceptable — basically works, needs improvement        | Functional but generic                          |
-| 2     | Below standard — obvious problems, partial redo needed | Major style clash or broken flow                |
-| 1     | Seriously deficient — directional error, full redo     | Wrong gameplay, broken entry, no CTA            |
-
-**Total ≥ 24**: Pass — proceed to Gate #3 (orchestrator)
-**Total 18–23**: Conditional pass — fix issues then re-review
-**Total < 18**: Fail — route back to responsible agent(s)
-
-**VETO ITEMS (automatic fail regardless of score):**
-
-- First level does NOT guarantee success
-- Zero CTA implementation
-- External network requests present
-- Entry file (index.html) missing
-
----
-
-## Full review process (L2)
-
-> Invoked from `agents/reviewer.md` — execute in order before final verdict.
-
-### Step 0: Dev preview (mandatory)
-
-1. Read `docs/project-state.md` → **Dev Preview**: `devUrl`, `devStatus`.
-2. If `devStatus` ≠ `ready` → **fail fast** (route Developer; do not score experience).
-3. If Dev server not reachable → run `npm run dev`, refresh `devUrl` in project-state.
-4. Open **devUrl** in browser; complete **UI match** + **gameplay match** (checklists in § Dev walkthrough above).
-5. Record summary in `project-state.md`: `reviewerDevCheck` (`passed` / `failed`), `reviewerDevNotes`.
-
-**Do not** require `playcraft build`. **Do not** ask the user to run terminal commands.
-
-### Step 0b: Validator Skill Discovery
-
-```bash
-playcraft skills list --category validator --json
-playcraft skills match --intent "validator,balance,quality" --json
-```
-
-For matched Validator Skills: read the SKILL.md, apply its checklist, record results in `review-report.md` per its format.
-
-### Phase 1: DAG Completeness Audit
-
-For each atom in `docs/atom-plan.md`:
-
-- `done` → verify `actualOutput` file exists on disk
-- `skipped` → verify reason is documented
-- `blocked` → verify blocker is documented
-
-### Phase 2: Layout Spec Compliance
-
-**Layout Spec is the shared contract. Verify ALL THREE production agents comply.**
-
-| Check                                                    | Route Issue To                        |
-| -------------------------------------------------------- | ------------------------------------- |
-| Asset sizes match `assetSpec`                            | TA (completions) / Designer (samples) |
-| Filenames match `assetMapping`                           | TA (completions) / Designer (samples) |
-| All assetMapping entries have files                      | **TA** (compliance gate)              |
-| Sprite sheet JSON paired with every atlas / sheet        | **TA**                                |
-| Element IDs in code match `colorPalette.tileColors[].id` | Developer                             |
-| Zone coordinates in scene match `zones[].rect`           | Developer                             |
-| Every asset is used; every code reference has a file     | TA + Developer                        |
-
-### Phase 2.5: TA Compliance Report Audit
-
-Read `logs/ta-log.md` and verify: log exists and complete, Asset Coverage table fully filled and all PASS, Spec Compliance Summary passes, Compliance Verdict is PASS. (Note: file size is NOT a TA compliance concern — size optimization happens at build time.)
-
-### Phase 2.6: Ad Psychology Audit
-
-> **Invoke the `playcraft-ad-psychology` skill** and use its four psychological hooks, 60-30-10 color rule, and CTA specs as evaluation criteria for Creative Appeal and Experience Flow dimensions.
-
-Key checks against ad-psychology principles:
-
-- Hook frame uses highest contrast + dynamic composition (Curiosity Gap)?
-- Tutorial uses simplified layout + warm tone + large gesture icons (Instant Gratification)?
-- Gameplay shows Near-Win state, NOT victory state (Progress Illusion)?
-- EndCard shows unresolved reward + prominent CTA, NOT satisfaction (FOMO)?
-- CTA button color is the ONLY accent color in the scene (60-30-10 rule)?
-- CTA touch target ≥ 48×48 px, contrast ratio ≥ 4.5:1?
-
-### Phase 3: Automated Technical Checks
-
-> **Invoke the `playcraft-build-optimizer` skill** for the compliance verification checklist (file size limits, external request detection, CTA API implementation, audio autoplay rules) and platform-specific requirements.
-
-```bash
-# Total project size
-du -sh .
-
-# Asset samples (adjust globs to project)
-playcraft image info assets/images/bg/*.webp
-playcraft image info assets/images/tiles/*.webp
-playcraft audio info --input assets/audio/bgm/*.mp3
-playcraft audio info --input assets/audio/sfx/*.mp3
-
-# Entry file exists
-ls game/index.html
-
-# Check for external requests
-grep -r "http://" game/ || echo "No http:// found"
-grep -r "https://" game/ || echo "No https:// found"
-grep -r "fetch(" game/ || echo "No fetch() found"
-
-# CTA implementation
-grep -r "onCTAClick\|mraid\|FbPlayableAd\|ExitApi" game/
-```
-
-### Phase 4: Six-Dimension Experience Evaluation
-
-> **Before starting Phase 4, read from the top of this document** (all six dimensions including Intent Transmission + scoring thresholds).
-
-Six dimensions: **Experience Flow** / **Creative Appeal** / **Style Consistency** / **Intent Fidelity** / **Difficulty Balance** / **Intent Transmission** — each scored 1–5. **Total ≥ 24/30 = pass**; 18–23 conditional; &lt; 18 fail.
-
-**Veto items (automatic fail)**: first level not guaranteed success / no CTA / external requests / missing index.html.
-
-### Phase 5: DAG Revision Audit
-
-For each entry in DAG Revisions: is the modification reasonable? properly documented? did it deviate from original intent?
-
----
-
-## Rework mechanism
-
-### Rework rules
-
-| Rule               | Detail                                                                                                                                      |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Failure budget** | `rework_round` in `{0, 1}` → allow rework (+1 on fail). `rework_round == 2` on fail → **forced Gate #3** (3rd review failure; user decides) |
-| **Parallel fixes** | If multiple agents have issues, route to all in parallel                                                                                    |
-| **Incremental**    | Fix only the problem parts, not redo everything                                                                                             |
-| **No re-gating**   | Rework goes directly back to Reviewer, no Gate #1/#2 re-approval                                                                            |
-
-### Severity levels
-
-| Severity   | Definition                            | Handling                     |
-| ---------- | ------------------------------------- | ---------------------------- |
-| `critical` | Non-functional / white screen / crash | Must fix, cannot skip        |
-| `major`    | Noticeable experience defect but runs | Rework fix, max 1 round      |
-| `minor`    | Aesthetic suggestion / tweak          | Log but do not block Gate #3 |
-
-### Feedback routing
-
-| Issue Type                                     | Route To             |
-| ---------------------------------------------- | -------------------- |
-| Direction / experience flow issues             | PM                   |
-| Creative sample quality                        | Designer             |
-| Asset completeness / compliance / sprite sheet | **Technical Artist** |
-| Gameplay logic bug / parameter imbalance       | Developer            |
-| Dev runtime / integration technical issue      | Developer            |
-
-### Rework flow
-
-```
-Issues found → review-report.md with severity + target + specific fix instructions
-    │
-    ├──→ Routed agents fix in parallel (incremental)
-    │
-    └──→ Developer Ph.2 fixes + Dev re-check
-              │
-              └──→ Reviewer re-checks
-                        │
-                   ┌────┴────┐
-                   Pass    Fail → round 2 or forced Gate #3
-```
+See `agents/reviewer.md` for the three modes: `design_check`, `ui_diff`, `load_check`.

package/project-template/.claude/agents/refs/ta-atlas-deliverable-standard.md

@@ -30,14 +30,35 @@
 3. Validate sidecar JSON: frame count = element count in group; grid params in `ta-log.md`.
 4. Audio: Designer MP3 → `playcraft audio compress/trim/loop/fade` → output **MP3**; verify with `playcraft audio info`.
 
+## Transparency requirements
+
+| Asset category                | Alpha required | Chroma key strategy                                  | Post-verify                               |
+| ----------------------------- | -------------- | ---------------------------------------------------- | ----------------------------------------- |
+| UI overlay (icons, text, HUD) | ✅ channels=4  | Per color conflict matrix (see ta-pipeline-cookbook) | Dark-bg overlay verify (no white/residue) |
+| VFX atlas (glow, particles)   | ✅ channels=4  | Blue screen #0000FF (VFX常含金/橙色)                 | Per-frame dark-bg verify                  |
+| Game element atlas (tiles)    | ✅ channels=4  | Per color conflict matrix                            | Dark-bg overlay verify                    |
+| Card/board piece (rect body)  | ❌ opaque OK   | N/A (white bg is part of the asset)                  | N/A                                       |
+| Full-screen background        | ❌ opaque OK   | N/A                                                  | Edge-to-edge full-coverage check          |
+| Digit strip                   | ✅ channels=4  | Blue screen #0000FF (digits often gold/white)        | Dark-bg overlay verify                    |
+
+**Color conflict matrix** — choose chroma key color to avoid edge residue:
+
+- Gold/yellow/orange/green assets → **blue screen #0000FF** (never green)
+- Blue/purple assets → **green screen #00FF00** (never blue)
+- Multi-color/rainbow → **magenta #FF00FF** (last resort)
+- All others → green screen #00FF00 (default)
+
 ## Compliance (TA)
 
-| Check          | Pass criteria                                                                 |
-| -------------- | ----------------------------------------------------------------------------- |
-| Atlas coverage | Every runtime element resolves to atlas+frame or single webp path             |
-| Sidecar        | `.json` exists beside each multi-element atlas                                |
-| Format         | WebP for images; MP3 for audio (unless layout-spec explicit exception)        |
-| ta-log         | One manifest row per atlas group: path, frames, cols/frameW/frameH/frameCount |
+| Check           | Pass criteria                                                                  |
+| --------------- | ------------------------------------------------------------------------------ |
+| Atlas coverage  | Every runtime element resolves to atlas+frame or single webp path              |
+| Sidecar         | `.json` exists beside each multi-element atlas                                 |
+| Format          | WebP for images; MP3 for audio (unless layout-spec explicit exception)         |
+| ta-log          | One manifest row per atlas group: path, frames, cols/frameW/frameH/frameCount  |
+| **Alpha check** | All transparent assets have `channels=4` (verified via `playcraft image info`) |
+| **Dark-bg OK**  | All transparent assets pass dark-background (#1A1A2E) overlay — no residue     |
+| **BG coverage** | Full-screen backgrounds: edge-to-edge, no fade/vignette/white corners          |
 
 ## Developer handoff