Skip to content

OBPI Transaction Contract

Status: Active Last reviewed: 2026-03-11 Parent ADR: ADR-0.11.0-airlineops-obpi-completion-pipeline-parity

Overview

The OBPI transaction contract defines the fail-closed execution boundary for one OBPI increment.

An OBPI is not just a brief file or checklist row. It is a bounded transaction with an explicit scope contract, required evidence, and a human authority boundary for Heavy and Foundation work.

This contract governs what later runtime validators and operator workflows must enforce. Machine-readable runtime state remains defined in OBPI Runtime Contract.

Context Loading

Every OBPI transaction begins by loading the execution context that justifies the work.

Minimum context inputs are:

  • the OBPI brief
  • the parent ADR
  • the active allowlist and denied-path contract
  • prior handoff context when the session is resumed

When a plan-audit receipt exists, it becomes part of the transaction context and must be read before implementation begins. Until receipt-generation parity lands in gzkit, missing receipt files are a compatibility gap, not permission to skip scope review or improvise the plan.

Core Rules

  1. Every OBPI MUST declare Allowed Paths as an explicit allowlist contract.
  2. Any file outside Allowed Paths is denied unless the OBPI is amended or a replacement OBPI is created.
  3. Completion MUST fail closed when the changed-files audit shows a path outside the allowlist.
  4. Missing orchestration primitives MUST be treated as blockers or explicit compatibility constraints, never silently ignored.
  5. Heavy and Foundation work MUST preserve Gate 5 human attestation as the completion authority boundary.
  6. If prerequisites, evidence, or scope conditions are missing, the workflow MUST STOP and emit BLOCKERS.

Advisory wording is not sufficient. Scope isolation is law, not guidance.

Scope Isolation

Allowed Paths define the full write surface for an OBPI transaction.

Required implications:

  • listed paths are in scope
  • unlisted paths are out of scope
  • widening scope requires governance action, not silent expansion
  • "related cleanup" is not a valid justification for touching denied surfaces

The minimum audit is the repository changed-files set:

Bash
git diff --name-only

If the changed-files set contains an unallowlisted path, the OBPI must halt with BLOCKERS before completion can proceed.

Spine Surfaces

Some repository surfaces create cross-OBPI merge and authority risk and must be treated as spine surfaces.

Spine surfaces include:

  • dependency and lock files
  • CI and automation configuration
  • global registries, manifests, and routing tables
  • repository-wide governance doctrine that changes multiple downstream surfaces
  • build, release, or ingest facades that affect unrelated workstreams

An OBPI that touches a spine surface MUST say so explicitly in its allowlist. Only one spine-touch OBPI may be active at a time unless a stricter local rule already exists.

Parallel Execution

Parallel OBPI execution is allowed only when all of the following are true:

  • the active OBPIs have disjoint allowlists
  • none of the active OBPIs touches a shared spine surface
  • blocker-producing prerequisites are already satisfied for each OBPI
  • evidence and attestation ownership remain independent per OBPI

Parallel execution must stop with BLOCKERS when:

  • allowlists overlap in a way that can produce semantic conflicts
  • one OBPI needs scope expansion into another OBPI's surface
  • a spine surface is shared
  • prerequisite evidence or human review for the lane is missing

Disjointness must be reasoned from the allowlists, not from agent confidence.

Compatibility Constraints

The transaction contract must stay honest about current repository capability.

Current gzkit compatibility rules:

  • if a plan-audit receipt exists, consume it during context loading
  • if no receipt exists, record that absence as a governance gap and continue only with explicit brief-grounded scope review
  • until gz-obpi-lock parity exists, any shared-scope or spine-touch work must run as a single active OBPI
  • if concurrent execution is needed and no lock surface exists, stop with BLOCKERS

Compatibility notes narrow behavior. They do not relax the contract.

Evidence and Authority

Every OBPI transaction must produce enough evidence for a human reviewer to inspect what changed and why the change is valid.

Minimum evidence expectations:

  • changed-files audit against Allowed Paths
  • verification command list and outcomes
  • value narrative and key proof
  • lane-appropriate attestation evidence

For gzkit pipeline-driven closeout, final completed-receipt accounting must run only after the guarded sync ritual (uv run gz git-sync --apply --lint --test) has succeeded. If the repo is still dirty, diverged, or otherwise unsynced at that point, the workflow must stop before final completion accounting.

Agents may prepare and summarize this evidence. They may not replace human attestation for heavy-lane work (any kind) or foundation-kind work (any lane).

BLOCKERS Output

When work cannot continue, emit BLOCKERS: followed by one blocker per line.

Typical blocker causes:

  • prerequisite file or directory missing
  • plan-audit receipt exists but fails alignment or references the wrong OBPI
  • changed-files audit includes a denied path
  • required evidence is absent or placeholder-only
  • heavy-lane or foundation-kind completion lacks human attestation evidence
  • parallel execution would overlap or share a spine surface
  • concurrent/shared-scope execution is needed but no lock surface exists