Skip to content

gz obpi pipeline

Launch the OBPI pipeline runtime surface for one OBPI.

Usage

Bash
gz obpi pipeline <OBPI-ID> [--from {verify,ceremony,sync}] [--attestor NAME]
                           [--evidence-json JSON] [--clear-stale]

<OBPI-ID> accepts the full canonical identifier or the same identifier without the OBPI- prefix.

Options

Option Description
--from {verify,ceremony,sync} Resume the pipeline from the named stage (default: full launch)
--attestor NAME Attestor identity for Stage 5 (e.g. g0 or agent:<name>); used by ceremony and sync stages when relaying the human attestation. Defaults to authorship.attestor_handle in .gzkit.json when set (GHI #1036)
--evidence-json JSON Inline evidence payload for Stage 5. Required key: attestation_text (forwarded to gz obpi complete --attestation-text). Optional keys: implementation_summary, key_proof, value_narrative, paired accept_uncovered + accept_uncovered_reason arrays for REQ waivers. The pipeline translates the JSON into the discrete flags gz obpi complete consumes; a missing attestation_text fails closed at the pipeline boundary (GHI #435).
--clear-stale Remove pipeline markers older than 24 hours before launching (recovery path for crashed sessions)

Runtime Behavior

gz obpi pipeline is the canonical CLI launch surface for the governance pipeline. The gz-obpi-pipeline skill remains available as a thin alias for agent UX, but it must not redefine stage sequencing or closeout semantics.

src/gzkit/pipeline_runtime.py is the shared runtime engine behind the CLI and the generated Claude pipeline hooks.

Current command contract:

  • every launch records the parent ADR as Accepted before writing markers: a Proposed ADR transitions Proposed -> Accepted, and a Draft ADR walks Draft -> Proposed -> Accepted through the lifecycle state machine, whose evaluation-justify-binding gate on Draft -> Proposed can refuse the launch (exit 3, nothing written). The ADR's frontmatter status: follows the ledger. An ADR already Accepted or later is left alone (GHI #1014)
  • full launch creates the active pipeline markers, reads the plan-audit receipt when present, advances the brief's frontmatter status: out of Draft to Active, and prints the implementation handoff with the follow-up --from=verify command
  • --from=verify reruns Stage 1, executes verification commands from the OBPI brief, adds Heavy-lane docs/BDD checks, clears active markers on success, and prints the follow-up --from=ceremony command
  • --from=ceremony reruns Stage 1, prints the ceremony/accounting checklist, requires explicit human attestation for heavy-lane completion paths (any kind) and for foundation-kind completion paths (any lane), and clears active markers on exit

The active marker files are also the machine-readable stage-state contract while the pipeline is running. They are runtime-managed and should not be edited or cleared manually:

  • .claude/plans/.pipeline-active-<OBPI-ID>.json
  • .claude/plans/.pipeline-active.json

Those marker payloads now persist:

  • obpi_id
  • parent_adr
  • lane
  • entry
  • execution_mode
  • current_stage
  • started_at
  • updated_at
  • receipt_state
  • blockers
  • required_human_action
  • next_command
  • resume_point

blockers is a list of active stage blockers. required_human_action is either null or a concise summary of the current required human action. Lite-lane ceremony state keeps this field null because human attestation is optional there. next_command is either null or the next canonical operator command. resume_point is either null or the stage label the operator should resume from.

The marker payload is active-state only. It is not authoritative completion history.

Claude hook surfaces and generated control surfaces should point operators back to this command contract instead of re-explaining the stage engine in prose.

Failure Modes

The command exits non-zero and prints BLOCKERS: when:

  • the OBPI brief cannot be resolved
  • the OBPI brief is already completed
  • the OBPI brief fails authored-readiness validation (including scaffold placeholders) before execution
  • the parent ADR evaluation scorecard has a NO GO verdict (detected by check_adr_evaluation_verdict)
  • the matching plan-audit receipt verdict is FAIL
  • another OBPI is already active in the pipeline markers
  • any verification command fails in --from=verify

Missing or unreadable plan-audit receipts are warnings, not blockers. Missing evaluation scorecards are not blockers (evaluation is advisory until run).

Examples

Bash
uv run gz obpi pipeline OBPI-0.13.0-01-runtime-command-contract
Text Only
OBPI pipeline: OBPI-0.13.0-01-runtime-command-contract
  Parent ADR: ADR-0.13.0-obpi-pipeline-runtime-surface
  Brief: docs/design/adr/pre-release/ADR-0.13.0-obpi-pipeline-runtime-surface/obpis/OBPI-0.13.0-01-runtime-command-contract.md
  Lane: heavy
  Entry: full
  Receipt: MISSING
  Stages: 1. Load Context -> 2. Implement -> 3. Verify -> 4. Present Evidence -> 5. Sync And Account
  Marker: .claude/plans/.pipeline-active-OBPI-0.13.0-01-runtime-command-contract.json
  Legacy Marker: .claude/plans/.pipeline-active.json
  Warning: plan-audit receipt is missing; proceeding with an explicit gap

Next:
- Implement the approved OBPI within the brief allowlist.
- When implementation is ready, run: uv run gz obpi pipeline OBPI-0.13.0-01-runtime-command-contract --from=verify
- Keep the active pipeline markers in place during implementation.
Bash
uv run gz obpi pipeline OBPI-0.13.0-01-runtime-command-contract --from=verify
uv run gz obpi pipeline 0.13.0-01-runtime-command-contract --from=ceremony