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)

pipeline_defs/animated-explainer.yaml

@@ -9,6 +9,12 @@ stability: production
 
 default_checkpoint_policy: guided
 
+extensions:
+  custom_scripts: true
+  custom_playbooks: true
+  custom_skills: true
+  custom_tools: false
+
 required_skills:
   - pipelines/explainer/executive-producer
   - pipelines/explainer/research-director
@@ -63,6 +69,7 @@ stages:
       - research_brief
     produces:
       - proposal_packet
+      - decision_log
     tools_available: []
     checkpoint_required: true
     human_approval_default: true
@@ -189,6 +196,7 @@ stages:
       - scene_plan
     produces:
       - render_report
+      - final_review
     required_tools:
       - video_compose
       - audio_mixer
@@ -212,6 +220,7 @@ stages:
     skill: pipelines/explainer/publish-director
     required_artifacts_in:
       - render_report
+      - final_review
     optional_artifacts_in:
       - proposal_packet
     produces:

pipeline_defs/animation.yaml

@@ -10,6 +10,12 @@ category: animation
 stability: production
 default_checkpoint_policy: guided
 
+extensions:
+  custom_scripts: true
+  custom_playbooks: true
+  custom_skills: true
+  custom_tools: false
+
 required_skills:
   - pipelines/animation/executive-producer
   - pipelines/animation/research-director
@@ -64,6 +70,7 @@ stages:
       - research_brief
     produces:
       - proposal_packet
+      - decision_log
     tools_available: []
     checkpoint_required: true
     human_approval_default: true
@@ -194,6 +201,7 @@ stages:
       - scene_plan
     produces:
       - render_report
+      - final_review
     required_tools:
       - video_compose
       - audio_mixer
@@ -218,6 +226,7 @@ stages:
     skill: pipelines/animation/publish-director
     required_artifacts_in:
       - render_report
+      - final_review
     optional_artifacts_in:
       - proposal_packet
       - script

pipeline_defs/avatar-spokesperson.yaml

@@ -17,6 +17,12 @@ orchestration:
   max_send_backs: 3
   max_wall_time_minutes: 12
 
+extensions:
+  custom_scripts: true
+  custom_playbooks: true
+  custom_skills: true
+  custom_tools: false
+
 required_skills:
   - pipelines/avatar-spokesperson/executive-producer
   - pipelines/avatar-spokesperson/idea-director
@@ -38,6 +44,7 @@ stages:
     skill: pipelines/avatar-spokesperson/idea-director
     produces:
       - brief
+      - decision_log
     tools_available: []
     checkpoint_required: true
     human_approval_default: true
@@ -152,6 +159,7 @@ stages:
       - scene_plan
     produces:
       - render_report
+      - final_review
     required_tools:
       - video_compose
       - audio_mixer
@@ -177,6 +185,7 @@ stages:
     skill: pipelines/avatar-spokesperson/publish-director
     required_artifacts_in:
       - render_report
+      - final_review
     optional_artifacts_in:
       - brief
       - script

pipeline_defs/cinematic.yaml

@@ -17,9 +17,16 @@ orchestration:
   max_send_backs: 3
   max_wall_time_minutes: 12
 
+extensions:
+  custom_scripts: true
+  custom_playbooks: true
+  custom_skills: true
+  custom_tools: false
+
 required_skills:
   - pipelines/cinematic/executive-producer
-  - pipelines/cinematic/idea-director
+  - pipelines/cinematic/research-director
+  - pipelines/cinematic/proposal-director
   - pipelines/cinematic/script-director
   - pipelines/cinematic/scene-director
   - pipelines/cinematic/asset-director
@@ -30,15 +37,41 @@ required_skills:
   - meta/checkpoint-protocol
 
 compatible_playbooks:
-  - clean-professional
-  - flat-motion-graphics
-  - minimalist-diagram
+  recommended:
+    - clean-professional
+    - flat-motion-graphics
+  also_works:
+    - minimalist-diagram
+  custom_allowed: true
 
 stages:
-  - name: idea
-    skill: pipelines/cinematic/idea-director
+  - name: research
+    skill: pipelines/cinematic/research-director
     produces:
-      - brief
+      - research_brief
+    tools_available:
+      - web_search
+    checkpoint_required: true
+    human_approval_default: false
+    review_focus:
+      - Visual references are specific and relevant to the mood
+      - Sound and music direction is substantive, not generic
+      - Motion commitment is honest about available capabilities
+      - At least 3 genuinely different cinematic directions identified
+    success_criteria:
+      - Schema-valid research_brief artifact
+      - At least 8 web searches executed
+      - Visual references include specific URLs and descriptions
+
+  - name: proposal
+    skill: pipelines/cinematic/proposal-director
+    required_artifacts_in:
+      - research_brief
+    optional_artifacts_in:
+      - source_media_review
+    produces:
+      - proposal_packet
+      - decision_log
     tools_available: []
     checkpoint_required: true
     human_approval_default: true
@@ -47,14 +80,19 @@ stages:
       - Motion-required delivery is explicitly identified when applicable
       - Delivery shape is realistic for available footage and assets
       - Cinematic treatment is justified rather than decorative
+      - Delivery promise is explicit and honest
+      - Renderer family is selected and locked
+      - Music plan is resolved
     success_criteria:
-      - Schema-valid brief artifact
-      - Brief records source reality and target output shape
+      - Schema-valid proposal_packet artifact
+      - At least 3 concept options with different emotional arcs
+      - Delivery promise present with motion_required flag
+      - Cost estimate includes per-item breakdown
 
   - name: script
     skill: pipelines/cinematic/script-director
     required_artifacts_in:
-      - brief
+      - proposal_packet
     produces:
       - script
     optional_tools:
@@ -78,7 +116,7 @@ stages:
     required_artifacts_in:
       - script
     optional_artifacts_in:
-      - brief
+      - proposal_packet
     produces:
       - scene_plan
     optional_tools:
@@ -158,6 +196,7 @@ stages:
       - scene_plan
     produces:
       - render_report
+      - final_review
     required_tools:
       - video_compose
       - audio_mixer
@@ -188,8 +227,9 @@ stages:
     skill: pipelines/cinematic/publish-director
     required_artifacts_in:
       - render_report
+      - final_review
     optional_artifacts_in:
-      - brief
+      - proposal_packet
       - script
     produces:
       - publish_log

pipeline_defs/clip-factory.yaml

@@ -17,6 +17,12 @@ orchestration:
   max_send_backs: 3
   max_wall_time_minutes: 12
 
+extensions:
+  custom_scripts: true
+  custom_playbooks: true
+  custom_skills: true
+  custom_tools: false
+
 required_skills:
   - pipelines/clip-factory/executive-producer
   - pipelines/clip-factory/idea-director
@@ -36,8 +42,11 @@ compatible_playbooks:
 stages:
   - name: idea
     skill: pipelines/clip-factory/idea-director
+    optional_artifacts_in:
+      - source_media_review
     produces:
       - brief
+      - decision_log
     tools_available: []
     checkpoint_required: true
     human_approval_default: true
@@ -149,6 +158,7 @@ stages:
       - scene_plan
     produces:
       - render_report
+      - final_review
     required_tools:
       - video_compose
       - video_trimmer
@@ -176,6 +186,7 @@ stages:
     skill: pipelines/clip-factory/publish-director
     required_artifacts_in:
       - render_report
+      - final_review
     optional_artifacts_in:
       - brief
     produces:

pipeline_defs/hybrid.yaml

@@ -17,6 +17,12 @@ orchestration:
   max_send_backs: 3
   max_wall_time_minutes: 12
 
+extensions:
+  custom_scripts: true
+  custom_playbooks: true
+  custom_skills: true
+  custom_tools: false
+
 required_skills:
   - pipelines/hybrid/executive-producer
   - pipelines/hybrid/idea-director
@@ -37,8 +43,11 @@ compatible_playbooks:
 stages:
   - name: idea
     skill: pipelines/hybrid/idea-director
+    optional_artifacts_in:
+      - source_media_review
     produces:
       - brief
+      - decision_log
     tools_available: []
     checkpoint_required: true
     human_approval_default: true
@@ -164,6 +173,7 @@ stages:
       - scene_plan
     produces:
       - render_report
+      - final_review
     required_tools:
       - video_compose
       - audio_mixer
@@ -193,6 +203,7 @@ stages:
     skill: pipelines/hybrid/publish-director
     required_artifacts_in:
       - render_report
+      - final_review
     optional_artifacts_in:
       - brief
       - script

pipeline_defs/localization-dub.yaml

@@ -16,6 +16,12 @@ orchestration:
   max_send_backs: 3
   max_wall_time_minutes: 15
 
+extensions:
+  custom_scripts: true
+  custom_playbooks: true
+  custom_skills: true
+  custom_tools: false
+
 required_skills:
   - pipelines/localization-dub/executive-producer
   - pipelines/localization-dub/idea-director
@@ -37,6 +43,7 @@ stages:
     skill: pipelines/localization-dub/idea-director
     produces:
       - brief
+      - decision_log
     tools_available: []
     checkpoint_required: true
     human_approval_default: true
@@ -52,6 +59,8 @@ stages:
     skill: pipelines/localization-dub/script-director
     required_artifacts_in:
       - brief
+    optional_artifacts_in:
+      - source_media_review
     produces:
       - script
     required_tools:
@@ -151,6 +160,7 @@ stages:
       - scene_plan
     produces:
       - render_report
+      - final_review
     required_tools:
       - video_compose
       - audio_mixer
@@ -176,6 +186,7 @@ stages:
     skill: pipelines/localization-dub/publish-director
     required_artifacts_in:
       - render_report
+      - final_review
     optional_artifacts_in:
       - brief
       - script

pipeline_defs/podcast-repurpose.yaml

@@ -18,6 +18,12 @@ orchestration:
   max_send_backs: 3
   max_wall_time_minutes: 12
 
+extensions:
+  custom_scripts: true
+  custom_playbooks: true
+  custom_skills: true
+  custom_tools: false
+
 required_skills:
   - pipelines/podcast-repurpose/executive-producer
   - pipelines/podcast-repurpose/idea-director
@@ -37,8 +43,11 @@ compatible_playbooks:
 stages:
   - name: idea
     skill: pipelines/podcast-repurpose/idea-director
+    optional_artifacts_in:
+      - source_media_review
     produces:
       - brief
+      - decision_log
     tools_available: []
     checkpoint_required: true
     human_approval_default: true
@@ -157,6 +166,7 @@ stages:
       - scene_plan
     produces:
       - render_report
+      - final_review
     required_tools:
       - video_compose
       - audio_mixer
@@ -182,6 +192,7 @@ stages:
     skill: pipelines/podcast-repurpose/publish-director
     required_artifacts_in:
       - render_report
+      - final_review
     optional_artifacts_in:
       - brief
     produces:

pipeline_defs/screen-demo.yaml

@@ -17,6 +17,12 @@ orchestration:
   max_send_backs: 3
   max_wall_time_minutes: 10
 
+extensions:
+  custom_scripts: true
+  custom_playbooks: true
+  custom_skills: true
+  custom_tools: false
+
 required_skills:
   - pipelines/screen-demo/executive-producer
   - pipelines/screen-demo/idea-director
@@ -38,6 +44,7 @@ stages:
     skill: pipelines/screen-demo/idea-director
     produces:
       - brief
+      - decision_log
     tools_available: []
     checkpoint_required: true
     human_approval_default: true
@@ -53,6 +60,8 @@ stages:
     skill: pipelines/screen-demo/script-director
     required_artifacts_in:
       - brief
+    optional_artifacts_in:
+      - source_media_review
     produces:
       - script
     required_tools:
@@ -104,9 +113,9 @@ stages:
       - script
     produces:
       - asset_manifest
-    required_tools:
-      - subtitle_gen
+    required_tools: []
     optional_tools:
+      - subtitle_gen
       - tts_selector
       - image_selector
       - diagram_gen
@@ -156,6 +165,7 @@ stages:
       - scene_plan
     produces:
       - render_report
+      - final_review
     required_tools:
       - video_compose
       - audio_mixer
@@ -181,6 +191,7 @@ stages:
     skill: pipelines/screen-demo/publish-director
     required_artifacts_in:
       - render_report
+      - final_review
     optional_artifacts_in:
       - brief
     produces:

pipeline_defs/talking-head.yaml

@@ -8,6 +8,12 @@ category: talking_head
 stability: beta
 default_checkpoint_policy: guided
 
+extensions:
+  custom_scripts: true
+  custom_playbooks: true
+  custom_skills: true
+  custom_tools: false
+
 required_skills:
   - pipelines/talking-head/executive-producer
   - pipelines/talking-head/idea-director
@@ -35,6 +41,7 @@ stages:
     skill: pipelines/talking-head/idea-director
     produces:
       - brief
+      - decision_log
     tools_available: []
     checkpoint_required: true
     human_approval_default: true
@@ -50,6 +57,8 @@ stages:
     skill: pipelines/talking-head/script-director
     required_artifacts_in:
       - brief
+    optional_artifacts_in:
+      - source_media_review
     produces:
       - script
     required_tools:
@@ -156,6 +165,7 @@ stages:
       - scene_plan
     produces:
       - render_report
+      - final_review
     required_tools:
       - video_compose    # rendering
       - audio_mixer      # audio layering + segmented music
@@ -201,6 +211,7 @@ stages:
     skill: pipelines/talking-head/publish-director
     required_artifacts_in:
       - render_report
+      - final_review
     produces:
       - publish_log
     tools_available: []