How Human Approval Gates Are Implemented in OpenMontage Pipeline Stages

OpenMontage enforces human approval gates through a combination of manifest-driven YAML configuration and runtime checkpoint validation that prevents stage completion without explicit human sign-off.

OpenMontage is an open-source framework for orchestrating video production pipelines that require manual review at critical decision points. The system implements human approval gates using a three-layer architecture: declarative pipeline manifests define which stages require oversight, runtime functions resolve these requirements, and the checkpoint writer enforces compliance by validating approval status before permitting stage completion or downstream progression.

Manifest-Driven Gate Configuration

The authoritative source for approval requirements resides in pipeline YAML definitions stored in pipeline_defs/. Each stage declares its gating policy through the human_approval_default boolean flag.

Pipeline YAML Definitions

In the talking-head pipeline configuration (pipeline_defs/talking-head.yaml), early creative stages explicitly require human validation while later technical stages proceed automatically:

- name: idea
  …
  human_approval_default: true
- name: edit
  …
  human_approval_default: false

This declaration establishes that the idea stage cannot transition to completed status without explicit human approval, whereas the edit stage may complete automatically. According to the OpenMontage source code, this manifest serves as the single source of truth for gate policies across the system.

Runtime Gate Resolution

When the checkpoint system evaluates whether a specific stage requires approval, it queries the manifest layers through dedicated loader functions.

The _stage_requires_approval Function

Located in lib/checkpoint.py (lines 51-61), the _stage_requires_approval function performs the runtime lookup:

• It accepts pipeline_type and stage parameters
• It queries the manifest via get_stage_human_approval_default from lib/pipeline_loader.py (lines 73-82)
• Returns the boolean value of human_approval_default if the stage is declared
• Returns None if the pipeline type is unknown or the stage is undeclared, allowing the caller's explicit human_approval_required flag to take precedence

This design ensures that manifest configurations act as defaults while preserving flexibility for programmatic overrides when necessary.

Checkpoint Enforcement Logic

The actual gate enforcement occurs within the checkpoint writing mechanism, which validates approval status before persisting stage state.

Validating Approval Status

The write_checkpoint function in lib/checkpoint.py (lines 66-82) implements the enforcement protocol:

1. Gate Resolution: Calls _stage_requires_approval to determine the manifest-specified policy
2. Gate Aggregation: Computes gated = bool(manifest_gate) or human_approval_required to combine manifest and runtime flags
3. Completion Validation: If status="completed" is requested but human_approved=True is absent, the function raises CheckpointValidationError

manifest_gate = _stage_requires_approval(pipeline_type, stage)
gated = bool(manifest_gate) or human_approval_required
if gated:
    human_approval_required = True
    if status == "completed" and not human_approved:
        raise CheckpointValidationError(
            f"GATE VIOLATION: stage {stage!r} requires human approval …"
        )

This mechanism ensures that runtime code cannot silently bypass a gate; the checkpoint writer aborts the transaction if approval requirements are violated.

Stage Progression Protection

Beyond individual stage validation, OpenMontage prevents downstream execution when predecessor gates remain unapproved.

Prerequisite Validation

The _enforce_stage_prerequisites function in lib/checkpoint.py (lines 84-92) walks the ordered stage list derived from get_pipeline_stages and verifies that every predecessor meets two criteria:

1. Completion Status: The stage must have status="completed"
2. Approval Status: If the predecessor is a gated stage, it must have human_approved=True

Missing or unapproved predecessors trigger a CheckpointValidationError, creating a strict audit trail that ensures costly downstream processing (such as video rendering) cannot commence until all required human reviews are finalized.

Practical Implementation Examples

The following examples demonstrate the complete lifecycle of gated checkpoints in OpenMontage.

Writing a Gated Checkpoint (Idea Stage)

This example shows the two-phase write pattern required for gated stages: first marking awaiting_human status, then completing with approval:

from pathlib import Path
from lib.checkpoint import write_checkpoint

pipeline_dir = Path("/projects")
project_id   = "demo123"
stage        = "idea"
artifacts    = {"brief": {...}, "decision_log": {...}}

# Phase 1: Present to user for review

write_checkpoint(
    pipeline_dir,
    project_id,
    stage,
    status="awaiting_human",
    artifacts=artifacts,
    pipeline_type="talking-head",
)

# Phase 2: Complete after human approval

write_checkpoint(
    pipeline_dir,
    project_id,
    stage,
    status="completed",
    artifacts=artifacts,
    pipeline_type="talking-head",
    human_approved=True,
)

Attempting to Skip Approval (Error Scenario)

The following call raises CheckpointValidationError because the manifest declares human_approval_default: true for the idea stage, but the write operation attempts completion without the approval flag:

write_checkpoint(
    pipeline_dir,
    project_id,
    "idea",
    status="completed",
    artifacts=artifacts,
    pipeline_type="talking-head",
    human_approved=False,
)

# → GATE VIOLATION error

Enforcing Predecessor Approvals

Attempting to start the scene_plan stage (which follows idea) without approval of the predecessor triggers a prerequisite violation:

write_checkpoint(
    pipeline_dir,
    project_id,
    "scene_plan",
    status="awaiting_human",
    artifacts={...},
    pipeline_type="talking-head",
)

# → CheckpointValidationError: "completed without required approval: ['idea']"

Summary

OpenMontage implements human approval gates through a robust, layered architecture:

• Manifest Authority: Pipeline YAML files in pipeline_defs/ declare human_approval_default flags that serve as the source of truth for stage gating
• Runtime Resolution: The _stage_requires_approval function in lib/checkpoint.py queries these manifests via get_stage_human_approval_default from lib/pipeline_loader.py
• Strict Enforcement: The write_checkpoint function raises CheckpointValidationError if gated stages attempt completion without human_approved=True
• Dependency Protection: The _enforce_stage_prerequisites function ensures downstream stages cannot progress until all gated predecessors receive explicit human sign-off

Frequently Asked Questions

What happens if a stage requires human approval but the human_approved flag is omitted?

The checkpoint writer raises CheckpointValidationError with a "GATE VIOLATION" message. According to the implementation in lib/checkpoint.py, the system explicitly checks if status == "completed" and not human_approved and aborts the write operation, preventing silent bypass of approval requirements.

Can runtime code override the manifest approval settings?

Yes, but only to tighten restrictions, not loosen them. The write_checkpoint function accepts an explicit human_approval_required parameter that is OR-combined with the manifest setting (gated = bool(manifest_gate) or human_approval_required). However, if the manifest declares human_approval_default: true, the stage remains gated regardless of runtime parameters.

How does OpenMontage prevent downstream stages from running before approval?

The _enforce_stage_prerequisites function validates the entire predecessor chain before permitting new checkpoints. It checks that every prior stage is both completed and, if gated, explicitly approved. If any gated predecessor lacks human_approved=True, the function raises CheckpointValidationError listing the unapproved stages.

Where are the human approval settings defined for each pipeline?

Approval gates are declared in the pipeline-specific YAML manifests within the pipeline_defs/ directory. For example, pipeline_defs/talking-head.yaml contains the human_approval_default boolean for each stage. The lib/pipeline_loader.py module provides the get_stage_human_approval_default function to query these settings at runtime.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}