Merge pull request #1026 from heygen-com/fix/w2h-skill-audit

fix(skill): w2h audit + enforcement — close 19 shirking patterns from two agent debriefs

Author: ukimsanov

skills/website-to-hyperframes/SKILL.md

@@ -14,7 +14,16 @@ Users say things like:
 - "Turn this website into a 15-second social ad for Instagram"
 - "Create a 30-second product tour from https://..."
 
-The workflow has 7 steps. Each produces an artifact that gates the next. By default it's collaborative — gates marked 💬 stop and ask the user. If the user signals autonomous mode ("decide for me", "surprise me"), every 💬 gate is skipped; see step-2-brief.md for how that propagates.
+The workflow has 7 steps. Each produces an artifact that gates the next. By default it's collaborative — gates marked 💬 stop and ask the user. If the user signals autonomous mode ("decide for me", "surprise me"), 💬 user-preference gates are skipped; see step-2-brief.md for how that propagates.
+
+**Autonomous mode is NOT "skip all gates."** Auto mode covers user-preference questions (TTS provider, voice, color emphasis, beat count, music yes/no, captions yes/no — where the agent decides on the user's behalf). It does NOT cover quality-verification gates. The following remain non-skippable in auto mode:
+
+- Asset Audit (Step 3) — viewing contact sheets and justifying USE/SKIP for each asset
+- Per-beat HTML read (Step 5) — structured evidence block per beat
+- DoD checklist (Step 6) — including animation-map, per-warning WCAG verification, audio/motion playback
+- Honest disclosure section (Step 6) — "What I did NOT verify" must appear in your final summary
+
+If you find yourself reasoning "auto mode says bias toward action, so I'll skip X" — and X is a verification gate, not a preference question — that reasoning is wrong. Bias toward action applies to deciding _what to build_, not to deciding _whether to verify_.
 
 ---
 
@@ -120,7 +129,7 @@ Beat count is not in this table intentionally — it should come from the storyb
 | File                                                                               | When to read                                                                                                                                   |
 | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
 | [step-0-capture.md](references/step-0-capture.md)                                  | Step 0 — capture, understand the brand and product, write strategy-first site summary                                                          |
-| [step-1-design.md](references/step-1-design.md)                                    | Step 1 — write DESIGN.md brand cheat sheet (6 sections, 250-350 lines)                                                                         |
+| [step-1-design.md](references/step-1-design.md)                                    | Step 1 — write DESIGN.md brand cheat sheet (5 sections, 250-350 lines; 50-line fast-path for billboard-style social ads)                       |
 | [step-2-brief.md](references/step-2-brief.md)                                      | Step 2 — align on message, narrative arc, audience with user                                                                                   |
 | [capabilities.md](references/capabilities.md)                                      | Steps 2 & 5 — full inventory of what HyperFrames can do (24 sections). Scan the TOC during the brief, deep-dive specific sections during build |
 | [step-3-storyboard.md](references/step-3-storyboard.md)                            | Step 3 — storyboard + script (combined) with user review gate                                                                                  |

skills/website-to-hyperframes/references/beat-builder-guide.md

@@ -115,6 +115,70 @@ After lint passes, snapshots are taken, and you've fixed every issue you saw —
 
 So in your report, name the hex codes you used, the captured asset paths you placed, the headline `font-size`, and the GSAP timeline's last `tl.fromTo(...)` timestamp. Brief, concrete, true. If anything diverges from DESIGN.md or the storyboard, say so explicitly — the main agent can decide whether to accept the divergence or send you back to fix it. Surprises caught at this hand-off cost minutes; surprises caught at Step 6 cost iterations.
 
+### FLAG protocol — required phrasing for non-blocking issues
+
+When you find any of these, surface them as **FLAGS** in your report, not as conditional suggestions:
+
+- Visual states that briefly look broken (empty containers, hanging elements, gap moments)
+- Spec ambiguities you had to resolve by guessing
+- Linter bugs you worked around
+- Tween values you changed from the spec because they wouldn't fit
+
+**Forbidden phrasing:** "if the X feels too long, you could...", "consider tweaking Y", "might want to..."
+
+**Required phrasing — concrete, actionable, with line numbers:**
+
+```
+FLAG: at beat-local t=1.2s the doc card is visible but its inner content is still
+       opacity 0 — a 0.4s empty-panel window.
+       RECOMMENDED FIX: pull title typewriter from 1.6s → 1.4s
+       in compositions/beat-5-name.html line 234.
+```
+
+The main agent MUST EITHER apply each FLAG's fix OR write a one-sentence rejection with reason. Silently dropping a FLAG is a verification failure that gets caught at Step 6 (or worse, in the user's preview).
+
+### Spec ambiguity — escalate, don't paper over
+
+If STORYBOARD.md gives you a transition or transformation but doesn't establish the **start** state, do NOT guess. Examples of ambiguity worth flagging:
+
+- "Row 1 transitions from Huly Blue to Huly Orange at 3.5s" — but Row 1's initial color isn't specified
+- "Headline grows" — but the start size isn't specified
+- "Cards slide in" — but the off-screen position isn't specified
+- "Subhead appears after the headline" — but exact timing offset isn't specified
+
+**Required action:** FLAG the ambiguity in your report verbatim:
+
+```
+FLAG: STORYBOARD.md beat 3 says "Row 1 transitions blue → orange at 3.5s" but
+       Row 1's initial color is not specified anywhere. I interpreted Row 1 starts
+       blue and tweened to orange. CONFIRM or correct.
+```
+
+The main agent then confirms or corrects before Step 6 advances. Picking an interpretation silently means the build looks "fine" while diverging from intent — and the user only notices in motion.
+
+### Sub-agent diagnoses are unverified claims, not facts
+
+When a sub-agent reports "this is a linter false positive" / "this is a known bug" / "this attribute doesn't work as documented" — those are HYPOTHESES, not findings. Sub-agents diagnose from one symptom; they don't have repo-wide context.
+
+Before propagating any sub-agent diagnosis (e.g., applying the same "workaround" to another beat, or telling the user "this is a known bug"), do ONE of:
+
+1. **Verify by reading the source.** Open the file the sub-agent claims is buggy. Confirm the bug exists. Example: "I read `packages/core/src/lint/utils.ts:42` and confirmed the regex matches `url(\"data:image/svg+xml...\")` incorrectly. The workaround is to base64-encode the URI."
+2. **Disclose the unverified claim.** Don't suppress it — surface it. Example: "Sub-agent for beat 2 diagnosed `root_missing_composition_id` as a linter false positive on inline SVG data URIs. I applied the same workaround to beat 4 WITHOUT verifying the underlying claim. Worth filing as a regression against `packages/core/src/lint/utils.ts` to confirm."
+
+**Forbidden:** silently adopting the workaround pattern and presenting "lint passes" as evidence. If the workaround came from an unverified diagnosis, "lint passes because the diagnosis was correct AND I worked around it" and "lint passes because the diagnosis was wrong but the workaround happened to make the symptom disappear" are both possible. Without verification, you don't know which. The next session inherits the workaround AND the unverified diagnosis.
+
+### When you accept a sub-agent's divergence from spec — UPDATE the spec
+
+If a sub-agent reports "I diverged from STORYBOARD.md because..." AND you accept the divergence, you MUST update STORYBOARD.md to reflect the actual implementation. Otherwise the spec lies about the artifact.
+
+Examples:
+
+- Sub-agent: "Storyboard says 'HULY' uppercase but the actual logo asset is lowercase 'huly'. I used lowercase." Accept → edit STORYBOARD.md beat N to say "huly" lowercase. Note the change inline.
+- Sub-agent: "Storyboard says cells at 56px but they read too small at 1920×1080. I used 96px." Accept → edit STORYBOARD.md beat N's cell size to 96px.
+- Sub-agent: "Storyboard says SFX at t=4.7s but the visual moment lands at t=5.2s; I aligned SFX to the visual." Accept → edit STORYBOARD.md SFX line to t=5.2s.
+
+**Forbidden:** accepting the divergence silently and leaving the storyboard with the wrong spec. The next session reading STORYBOARD.md will trust it as ground truth. The spec is a contract; if you break the contract, update the contract.
+
 ---
 
 ## Continuous motion — the most important rule
@@ -175,7 +239,7 @@ If any are missing from the beat spec, the beat is under-defined. Don't fill the
 - CSS CENTERING: no `transform: translate(-50%, -50%)` with GSAP transforms. Use flexbox or `xPercent/yPercent`.
 - QUERYSELECTOR: `document.getElementById("id")` with null guards. No method calls without null check.
 - CHARACTER SPANS: `display:inline-block` on spaces collapses them. Use ` ` or per-word spans.
-- COUNTERS: no `onUpdate` callbacks. Discrete `tl.set(el, {textContent: "42"}, 2.5)` at timestamps.
+- COUNTERS: no `onUpdate` for numeric counters — use discrete `tl.set(el, {textContent: "42"}, 2.5)` at timestamps. `onUpdate` and `tl.call()` ARE supported for canvas/WebGL rendering loops and character-by-character typing — see capabilities.md §10.
 - TIMELINE: `window.__timelines["beat-N-name"] = tl` synchronously. Key = `data-composition-id`.
 - DETERMINISTIC: no `Math.random()`, `Date.now()`, `requestAnimationFrame`, `repeat:-1`.
 - Always `tl.fromTo()` not `tl.from()` for entrances.

skills/website-to-hyperframes/references/capabilities.md

@@ -576,7 +576,7 @@ Full editor in packages/studio/:
 - No `setTimeout` / `setInterval` in timeline construction
 - No `requestAnimationFrame` (timeline-driven; engine seeks per frame)
 - No `repeat: -1` (calculate exact repeats: `Math.ceil(duration / cycleDuration) - 1`)
-- No `tl.call(fn)` / `tl.add(function)` / `onComplete`/`onStart`/`onUpdate`/`onRepeat` callbacks (engine doesn't fire them)
+- No `onComplete`/`onStart`/`onRepeat` callbacks (engine doesn't fire them). **Exception:** `onUpdate` and `tl.call()` ARE supported — they're required for canvas/WebGL rendering, character-by-character typing, and counter patterns. See §10 (Canvas 2D procedural art) for the documented pattern.
 - No `gsap.set` on clips from later scenes (use `tl.set(selector, vars, position)`)
 - Synchronous timeline construction (no async)
 - Master clock can clamp at composition end

skills/website-to-hyperframes/references/step-1-design.md

@@ -33,7 +33,7 @@ Sub-agents try to use the fonts you list. The manifest tells you exactly what's
 
 ---
 
-## The 6 sections to write
+## The 5 sections to write
 
 ### `## 1. Visual Theme (one paragraph)`
 
@@ -256,32 +256,7 @@ Generous whitespace as confidence. Section gaps are always `60–100px`. Content
 
 ---
 
-### `## 5. Depth & Elevation`
-
-Document the brand's shadow philosophy and the actual shadow values used.
-
-#### Shadow table
-
-```markdown
-| Level        | Value                            | Used for                                        |
-| ------------ | -------------------------------- | ----------------------------------------------- |
-| Flat (0)     | none                             | Default — most surfaces, inputs, body text      |
-| Raised (1)   | `0 2px 8px rgba(0, 0, 0, 0.1)`   | Cards on white, hovered surfaces, floating CTAs |
-| Elevated (2) | `0 4px 12px rgba(0, 0, 0, 0.15)` | Dropdown menus, popovers                        |
-| Floating (3) | `0 8px 24px rgba(0, 0, 0, 0.2)`  | Modals, important overlays                      |
-```
-
-#### Shadow philosophy (one paragraph)
-
-How does this brand use shadows? Sparingly with soft falloff, or dramatically with hard edges? Are they present by default or only on hover? On dark backgrounds, do shadows invert to glow effects?
-
-```markdown
-Shadows are minimal — used only to signal interactivity (hover) or layering (modals). All shadows are soft-edged (blur ≥ 8px). On dark backgrounds, shadows convert to subtle glow (`0 0 24px rgba(255, 99, 99, 0.15)` using the brand's accent color). Hard shadows do not exist in this system.
-```
-
----
-
-### `## 6. Iteration Guide` (the load-bearing section)
+### `## 5. Iteration Guide` (the load-bearing section)
 
 5–10 numbered rules that encode the most important brand decisions. Each rule is a **single actionable sentence stating what to do, with the specific values from this site.** These are the "if in doubt, do this" rules sub-agents consult while composing beats.
 

skills/website-to-hyperframes/references/step-2-brief.md

@@ -118,7 +118,16 @@ When the user gives no creative direction, default to what the brand's visual id
 
 With that minimum in hand, still write an ambitious storyboard. "Surprise me" means "impress me," not "play it safe." Go bold.
 
-**Autonomous mode propagates.** When the user signals "surprise me" / "decide for me" / "just build it" here at Step 2, that signal kills every downstream 💬 gate too — Step 3's storyboard approval, Step 4's TTS provider choice, captions. Make all creative decisions yourself and present the finished video at the end. Do not ask four separate questions across four separate steps. Read the room once and commit.
+**Autonomous mode propagates — for user-preference gates only.** When the user signals "surprise me" / "decide for me" / "just build it" here at Step 2, that signal kills downstream user-preference 💬 gates: Step 3's storyboard approval, Step 4's TTS provider choice, music yes/no, captions yes/no. Make those creative decisions yourself and present the finished video at the end. Do not ask four separate questions across four separate steps. Read the room once and commit.
+
+**Auto mode does NOT skip quality-verification gates.** These run regardless and must produce evidence in your final summary:
+
+- Asset Audit (Step 3) — view contact sheets, justify USE/SKIP per asset
+- Per-beat HTML evidence block (Step 5)
+- DoD checklist (Step 6) — animation-map, per-warning WCAG verification, audio + motion playback (or explicit "deferred" disclosure)
+- "What I did NOT verify" disclosure (Step 6)
+
+**Test for "preference vs quality gate":** if the answer changes the _content_ of the video (which voice? captions on? beat 3 cinematic or fast?), it's a preference — auto mode decides. If the answer is "did the verification happen?", it's a quality gate — auto mode does NOT apply. Reasoning "auto mode says bias toward action, so I'll skip the contact sheets" misuses auto mode.
 
 ### Specific direction