stage-assemble

# stage-assemble

How to execute a validated, currently authorized `project/plan.json` into one finished file. Start/resume with `production.status`; if `plan_approval_current` is false, pass the state to `gate-control` and stop instead of producing or opening child gates. Walk the signed EDL; do not re-plan. Host-neutral: VideoStudio-specific edit/plan work runs through skill scripts (`stage-edit edit_video`, `stage-plan video_plan` via `bin/run-skill.cjs`), while authorization state, composition, and transcription run through the required built-in `video_studio` runtime; generic built-in capabilities remain `generate_video` / `generate_image` / `generate_speech`.

## Script calls used here

```bash
"$ORKAS_NODE" "$ORKAS_PC_DIR/bin/run-skill.cjs" stage-edit edit_video -- --op concat --inputs project/parts/a.mp4,project/parts/b.mp4 --output project/render/primary.mp4
"$ORKAS_NODE" "$ORKAS_PC_DIR/bin/run-skill.cjs" stage-edit edit_video -- --op mix --input project/render/primary.mp4 --audio-segments @project/audio_segments.json --output project/render/mixed.mp4
"$ORKAS_NODE" "$ORKAS_PC_DIR/bin/run-skill.cjs" stage-edit edit_video -- --op normalize_loudness --input project/render/draft.mp4 --output project/render/video.mp4
```

When this document says `stage-edit edit_video --op ...`, call the matching `bin/run-skill.cjs` command above with the relevant paths. For compose/transcription work, call `video_studio` directly. Do not call deprecated direct tools.

## Step 1 — Produce each segment (delegate by source)

Iterate segments in `order`. For each, produce its `produced_path` according to `source`, then write that path + `status:"done"` back into the segment so a resume never re-produces it:

- **edit** → `stage-edit`: cut the segment's `input_id` to its `[in_sec, out_sec]` window → `project/cuts/<id>.mp4`. Those are the EDL's field names, not flags: the command is `stage-edit edit_video --op trim --input <file> --start <in_sec> --duration <out_sec - in_sec> --output project/cuts/<id>.mp4`.
- **compose** → `stage-compose`: the host derives this child's `composition-manifest.json` from the signed segment's `spec.composition_plan` when the plan is inherited — do not hand-author it, and author only `index.html`. Keep it silent: no tracks and no `narration_intent` (the voice is signed once on the parent EDL). Set `audio.owner:"assembler"` whenever any scene carries `narration_text` — it renders silent exactly like `"none"` while naming the real owner, so the host stops asking this segment for its own narration audio. Use `"none"` only for a segment with no narration at all. Ask `gate-control` to resolve parent Gate B inheritance for the owning plan/segment, then follow the returned doctor/prepare path without creating a child user gate. Continue with visual authoring, native-required inspect/snapshot, and draft to `project/parts/<id>.mp4` only while the binding stays current. Run the QA phases for compose segments as ONE batched call per phase across the production rather than one call per segment: the batched path defaults its scope to the segments with no current frames, returns full findings only for the failures, and returns the production state once instead of repeating it per segment. Use a single-composition QA call only to re-check one named segment. Only `compose` segments need snapshot evidence, because their artifact is HTML; an `edit`/`generate`/`provided` segment is captured by its own `produced_path` file the moment that file exists, so never run a QA phase on one and never treat it as unfinished work. When every segment is captured (`production.status` reports no `uncaptured_segment_ids`), stop at the keyframe preview. The batched snapshot phase returns `production_contact_sheet`: ONE image of the whole video, segments in playback order, media segments included as an extracted still. Lead the stop with it — it is the artifact the user judges the video from. Then list each segment's own locators **in playback order, one row per segment including the media-backed ones** (a cut or generated shot has no snapshot — carry its `produced_path` so the user can play it), one line inviting changes, and `<plan-interaction status="open" />` — no form, no per-segment approvals. Never present a per-segment contact sheet as the production preview: four links to four children is not a look at the video. Assembly starts only from the user's reply; a reply that names no change is the go-ahead, while a named change is applied without asking the user to approve their own instruction. Re-capture the resulting complete production preview and return it in the next preview message — the message that ENDS the turn. A completed turn keeps only your final message, so frames posted mid-turn were never seen by the user. Put the updated contact sheet and locators in the turn's last message itself. The stop happens once per complete production visual identity: narration/audio-only work inherits it when every visible segment stays byte-identical; changing any composed frame or media-backed segment creates a new aggregate identity and the changed whole-video preview stops once before assembly. There are still no per-segment approvals.
- **generate** → `stage-generate` (+ `stage-consistency` for recurring characters): proceed only while `production.status` reports the current paid-generation signature. Call `generate_video` or `generate_image` with `production_plan_path:"project/plan.json"` and `production_segment_id:<id>` → `project/assets/<id>.<ext>`. When the segment has `operation:"edit"`, treat it as the bounded semantic-edit executor for the EDIT/AUTO workflow: pass the exact original reference video and obey top-level `references` + `edit_strategy`; never widen it into regeneration. Every auxiliary portrait/keyframe is already its own signed generate segment; do not create unplanned billable calls. The host transaction reuses a completed artifact and blocks an interrupted/failed duplicate. Pass pending/