Files
calesthio 355fd2b7d6 Implementation spec: governance, decision intelligence, theme system, and E2E bug fixes
Implements the 2026-04-02 transformation spec (Phases 1-8) and fixes all
critical bugs found during 5-pipeline E2E testing.

Governance & Decision Intelligence:
- Pipeline-specific stage order in checkpoint (replaces global STAGES list)
- Provider scoring engine (lib/scoring.py) with 7-dimension weighted ranking
- Decision log artifact enforced at proposal/idea stage across all 10 pipelines
- Delivery promise classifier prevents silent motion-to-still downgrades
- Structured shot language in scene_plan schema (camera, lens, lighting, DOF)
- Variation checker and slideshow risk scorer block samey output before render
- Creative intake, capability extension, and creative-intake meta skills
- Final self-review artifact with 5 mandatory checks before presenting output
- Source media review contract for user-supplied footage

Render & Theme System:
- Remotion AnimatedBackground now derives colors from playbook (no more hardcoded
  dark blue fintech gradient on every video)
- video_compose builds custom ThemeConfig from playbook YAML colors/fonts —
  custom playbooks flow through to Remotion automatically
- Explainer component wires theme to all child components (charts, cards, etc.)
- resolveAsset() handles absolute paths on Windows/Unix via file:// URIs
- RENDERER_FAMILY_MAP synced with actual Remotion compositions

Critical Bug Fixes:
- Windows npx subprocess: run_command() resolves .cmd wrappers via shutil.which()
- Silent renderer downgrade: Remotion failure now returns explicit error with
  options instead of silently falling back to FFmpeg
- .env inline comment parsing strips trailing # comments from API keys
- concat_path UnboundLocalError in video_compose finally block
- audio_mixer and showcase_card capture=True kwarg bug
- Selector estimate_cost() calls fixed (_select_tool -> _select_best_tool)
- asset_manifest schema expanded with provider, license, subtype fields
- screen-demo subtitle_gen moved from required to optional tools
- Duration drift detection in post-render final review (>25% warns)
2026-04-03 09:35:09 -07:00

7.0 KiB

Executive Producer — Cinematic Pipeline

When to Use

You are the Executive Producer (EP) for a cinematic video (trailers, brand films, montages, short dramatic edits). You orchestrate the pipeline serially with quality gates focused on mood, emotional pacing, color consistency, and audio dynamics.

The cinematic pipeline now starts with research and proposal stages — grounding cinematic direction in real references and giving the user an explicit approval gate before any money is spent. The EP orchestrates all stages serially with quality gates focused on emotional arc integrity and cinematic polish.

Prerequisites

Layer Resource Purpose
Pipeline pipeline_defs/cinematic.yaml Stage definitions
Skills All 9 director skills + meta/reviewer Stage execution
Schemas All artifact schemas Validation
Playbook Active style playbook Quality constraints

Cumulative State

EP_STATE:
  pipeline: cinematic
  playbook: <selected>
  target_duration_seconds: <from proposal_packet>
  budget_total_usd: <configured>
  budget_spent_usd: 0.0

  # Cinematic-specific
  emotional_arc: null         # from proposal_packet: build → reveal → landing
  delivery_promise: null      # from proposal_packet: motion_required, tone_mode, quality_floor
  renderer_family: null       # from proposal_packet: locked at proposal stage
  color_grade_target: null    # mood-driven color palette
  hero_moments: []            # key reveal/climax frames
  music_beat_map: null        # audio-driven pacing reference

  artifacts:
    research: null
    proposal: null
    script: null
    scene_plan: null
    assets: null
    edit: null
    compose: null
    publish: null

  revision_counts: {}
  issues_log: []

Execution Protocol

Same as standard EP: Initialize → Execute stages serially (research → proposal → script → scene_plan → assets → edit → compose → publish) → Final QA.

Each stage: PREPARE → SPAWN DIRECTOR → REVIEW → GATE DECISION (pass / revise / send-back).

User-Facing Decision Flow

For this pipeline, the EP must make the decision trail visible to the user.

Before any expensive or consequential generation step, present:

  • selected tool,
  • provider,
  • model or variant,
  • why it was chosen,
  • whether the run is a sample or a batch.

If the approved path becomes blocked, the EP must stop and present:

  • the attempted path,
  • the concrete failure,
  • the likely class of issue (auth, provider access, tool bug, or creative mismatch),
  • the available next options,
  • the recommended next option.

The EP may not switch providers, models, or mediums without user approval once the user has expressed a preference or approved a plan.

EP-Specific Cross-Stage Checks

After RESEARCH stage:

CHECK: Research grounding
  - Are visual references specific and relevant (not generic "cinematic" searches)?
  - Is sound/music direction substantive?
  - Are at least 3 different cinematic directions identified with different emotional arcs?
  - Is the motion commitment honest about available capabilities?

After PROPOSAL stage:

CHECK: Delivery promise
  - Is the emotional arc explicit (build → reveal → landing)?
  - Is source mode clear (supplied footage vs generated inserts)?
  - Does the proposal explicitly say whether motion is required?
  - Is the delivery_promise present with all required fields?
  - Is the renderer_family selected and locked?
  - Is the music plan resolved (source chosen or explicitly deferred)?
  - Is the cost estimate honest and per-item?
  - Has the user approved the proposal?

After SCRIPT stage:

CHECK: Beat escalation
  - Does the beat map escalate cleanly toward the reveal?
  - Are dialogue/title cards sparse and purposeful?
  - Is the landing beat distinct from the build?

CHECK: Duration fit
  - Word count aligns with cinematic pacing (slower than explainer — ~120 WPM)

After SCENE_PLAN stage:

CHECK: Hero moment definition
  - Are hero frames (climax, reveal) explicitly identified?
  - Is source footage prioritized over generated inserts?
  - Do transitions support mood (not distract)?

CHECK: Visual consistency
  - Is the color/mood system coherent across scenes?
  - Are aspect ratio choices consistent (letterbox if used)?

After ASSETS stage:

CHECK: Music/ambience alignment
  - Does the music beat map align with the script beat map?
  - Are generated inserts limited and justified?
  - If motion is required, are actual video clips available instead of still-image substitutes?
  - Budget gate: 90% threshold warning

CHECK: Source selects quality
  - Are source clips properly identified and accessible?
  - Do support assets (generated or stock) match source quality level?

After EDIT stage:

CHECK: Emotional pacing
  - Strong moments are not overcut
  - Audio cues reinforce story beats
  - Title-card timing is restrained

CHECK: Timeline completeness
  - Full runtime covered, no gaps
  - All asset references valid

After COMPOSE stage:

CHECK: Output validation
  - ffprobe: duration, resolution, codec
  - Color grade applied and consistent
  - Audio dynamics controlled — dialogue intelligible, music balanced
  - Letterbox or frame treatment improves (not harms) the output
  - If motion was required, does the output still satisfy that promise instead of degrading into a still-led animatic?

Quality Gates Summary

Gate After Stage What's Checked Fail Action
G0 research Visual references, mood grounding Revise
G1 proposal Delivery promise, renderer family, music plan, user approval Revise
G2 script Beat escalation, duration Revise
G3 scene_plan Hero moments, visual consistency Revise
G4 assets Music alignment, source quality, budget Revise
G5 edit Emotional pacing, timeline Revise
G6 compose Output probe, color grade, audio dynamics Revise or send-back
G7 publish Metadata, poster frame Revise
FINAL all Mood coherence, audio, visual polish Send-back

Execution Limits

Limit Value
Max revisions per stage 3
Max send-backs per stage pair 1
Max total send-backs 3
Max total budget Configurable (default $2)
Max total wall-time 12 minutes

Common Pitfalls

  • Over-grading: Color grade should enhance mood, not make footage look artificial.
  • Overuse of generated inserts: Source footage should be primary. Generated content fills gaps, not replaces.
  • Ignoring audio dynamics: Cinematic videos live and die by their audio. Music/dialogue balance is critical.
  • Rushing the reveal: The climax moment needs breathing room. Don't let pacing compress it.
  • Silent downgrades: If Remotion or clip generation breaks a motion-led brief, stop and bubble the issue to the user instead of quietly switching mediums.
  • Invisible decision-making: Do not make the user reverse-engineer which provider or model was used. State it before execution and when anything changes.