Checkpoint System

Checkpoints persist the complete state of a video production pipeline as JSON files. Because OpenMontage has no runtime Python orchestrator, the LLM coding assistant reads the latest checkpoint, follows the next stage-director skill, calls tools, and writes a new checkpoint. This design supports resumption after any failure or pause without re-executing completed work.

Persistence Location

Checkpoints live under pipeline/<project-id>/. Each stage writes its own file:

  • checkpoint_research.json
  • checkpoint_proposal.json
  • checkpoint_script.json
  • and so on

The same project also materializes standalone artifacts under projects/<kebab-name>/artifacts/. See Project Workspace for the full directory layout.

Checkpoint Structure

Every checkpoint contains these top-level fields:

{
  "version": "1.0",
  "project_id": "my-video",
  "stage": "script",
  "status": "completed",
  "timestamp": "2026-03-28T10:00:00Z",
  "checkpoint_policy": "guided",
  "human_approval_required": false,
  "human_approved": true,
  "artifacts": { "script": { ... } },
  "review": { ... },
  "cost_snapshot": { ... }
}

The artifacts map holds the canonical output for that stage. cost_snapshot records the current budget state. review stores self-review results from the meta/reviewer skill.

Status Values

A checkpoint uses one of these statuses:

  • pending
  • in_progress
  • awaiting_human
  • completed
  • failed

Only completed or awaiting_human checkpoints are considered valid for advancing the pipeline.

Checkpoint Policies

The policy is set in the pipeline manifest (default_checkpoint_policy) and can be overridden in config.yaml. The three supported policies are:

  • guided — writes checkpoints at key creative stages and auto-proceeds through mechanical stages.
  • manual_all — requires human approval before every stage transition.
  • auto_noncreative — auto-proceeds unless the stage is marked creative (assets, edit, etc.).

Per-stage checkpoint_required and human_approval_default values in the manifest combine with the policy to decide whether a gate appears. See Pipeline System for how manifests declare these values.

Canonical Artifacts

Eleven schema-validated artifacts are produced across the standard stage flow:

  • research_brief
  • proposal_packet
  • brief
  • script
  • scene_plan
  • asset_manifest
  • edit_decisions
  • render_report
  • publish_log
  • review
  • cost_log

Each artifact is validated against its JSON Schema before the checkpoint is written. The mapping from stage to primary artifact is enforced by the checkpoint system. Full schema definitions and field details are documented in Schemas and Artifacts.

Human Approval Gates

When human_approval_required is true and human_approved is false, the pipeline stops. The agent surfaces the current artifacts and review for your decision. Approval is recorded in the checkpoint and the pipeline continues from the next stage returned by get_next_stage().

Resumption

The agent uses get_latest_checkpoint() and get_completed_stages() to determine where to resume. Any stage that reached completed status is never re-run. This checkpoint-based approach is the primary mechanism for long-running or interrupted productions.

Updated June 24, 2026