# How Human Approval Gates Are Implemented in OpenMontage Pipeline Stages

> Learn how OpenMontage implements human approval gates using YAML configuration and runtime validation to ensure explicit sign-off before pipeline stage completion.

- Repository: [Calesthio/OpenMontage](https://github.com/calesthio/OpenMontage)
- Tags: how-to-guide
- Published: 2026-08-30

---

**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`](https://github.com/calesthio/OpenMontage/blob/main/pipeline_defs/talking-head.yaml)), early creative stages explicitly require human validation while later technical stages proceed automatically:

```yaml
- 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`](https://github.com/calesthio/OpenMontage/blob/main/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`](https://github.com/calesthio/OpenMontage/blob/main/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`](https://github.com/calesthio/OpenMontage/blob/main/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`

```python
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`](https://github.com/calesthio/OpenMontage/blob/main/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:

```python
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:

```python
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:

```python
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`](https://github.com/calesthio/OpenMontage/blob/main/lib/checkpoint.py) queries these manifests via `get_stage_human_approval_default` from [`lib/pipeline_loader.py`](https://github.com/calesthio/OpenMontage/blob/main/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`](https://github.com/calesthio/OpenMontage/blob/main/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`](https://github.com/calesthio/OpenMontage/blob/main/pipeline_defs/talking-head.yaml) contains the `human_approval_default` boolean for each stage. The [`lib/pipeline_loader.py`](https://github.com/calesthio/OpenMontage/blob/main/lib/pipeline_loader.py) module provides the `get_stage_human_approval_default` function to query these settings at runtime.