Skip to content

AirlineOps GovZero Exploration — Verbatim

Date: 2026-01-22 Context: Raw output from exploring airlineops codebase to understand GovZero in practice

Summary: Governance Concepts from AirlineOps That gzkit Should Document

Based on my thorough search of the airlineops codebase, here are the key governance concepts and practices that gzkit should document:

1. OBPIs (Observable Behavioral Progress Indicators)

What they are: - OBPI = "One Brief Per Item" - Atomic implementation units that map 1:1 to ADR checklist items - Each OBPI is a single markdown brief document describing exactly one piece of work - Located in docs/design/adr/{adr-folder}/briefs/ or docs/design/briefs/{adr-path}/

Numbering discipline (mandatory): - Sequential, zero-gap numbering: OBPI-0.0.19-01, OBPI-0.0.19-02, OBPI-0.0.19-03 - If an ADR has 19 checklist items → OBPIs 01 through 19 (no gaps, no categorical grouping) - Pre-release identifier scheme: 0.1.15-obpi.03 (SemVer compliant)

OBPI anatomy: - Parent ADR reference and checklist item mapping - Objective statement - Lane designation (Lite/Heavy) - Allowed/Denied paths (scope boundaries) - Requirements (fail-closed) - Acceptance Criteria - Gate evidence (what commands/artifacts prove completion)

Example: /Users/jeff/Documents/Code/airlineops/docs/design/adr/adr-0.0.x/ADR-0.0.19-AIRAC-orchestrated-warehouse-pipeline/briefs/OBPI-0.0.19-01-canonicalize-librarian.md

2. Closeout Ceremonies (Hard-Mode Attestation Protocol)

What it is: - A mode transition where the agent yields interpretive authority to the human - Triggered by human invocation: "ADR closeout ceremony" (or equivalents: "begin closeout", "closeout ADR-X.Y.Z") - Ensures human attestation is grounded in direct observation, not mediated through agent claims

Why it matters (epistemic integrity): - Prevents "mediated observation" where humans see reality only through agent lens - Agent presents paths and commands, not conclusions and outcomes - Human executes and observes directly; agent is a "silent index" - Eliminates corruption risk from agent errors/bias

Attestation forms (canonical): The human MUST provide exactly one of these explicit forms: - "Completed" — All work finished; claims verified - "Completed — Partial: [reason]" — Subset accepted; remainder deferred with documented rationale - "Dropped — [reason]" — ADR rejected; clear rationale provided

Agent behavior during closeout (MUST): 1. Recognize the trigger phrase as mode transition 2. Immediately yield interpretive authority 3. Present raw artifact paths and commands for human execution, NOT summaries 4. Wait for explicit human attestation before recording 5. Run audit checks only after attestation (post-closeout) 6. Reference gates by number only; defer to charter for definitions 7. Surface audit-protocol.md for human reference

Agent behavior during closeout (MUST NOT): 1. Summarize or interpret evidence outcomes 2. Infer attestation from silence/continuation 3. Auto-close based on passing checks 4. Run audit during closeout mode 5. Present ledger entries as proof of completion 6. Redefine gate semantics 7. Offer to "check if requirements are met" (human checks; agent presents paths) 8. Proceed to post-closeout tasks until attestation recorded

Closeout Form template: - Located at ADR-CLOSEOUT-FORM.md in ADR folder - Optional workspace for collaboration during ceremony - Pre-attestation checklist, human attestation phase, post-attestation audit section - Phase markers: Phase 1 (COMPLETED) → Phase 2 (VALIDATED)

Example: /Users/jeff/Documents/Code/airlineops/docs/design/adr/adr-0.0.x/ADR-0.0.19-AIRAC-orchestrated-warehouse-pipeline/ADR-CLOSEOUT-FORM.md

3. Daily Workflow Patterns

Git Sync Ritual: - Mentioned in CLAUDE.md as part of standard workflow - Command: uv run -m opsdev git-sync --apply --lint --test - Workflow element that integrates governance checks into development flow

Gate Progression Pattern (Lite Lane): 1. Gate 1 (ADR): Record intent; checklist items → OBPI briefs 2. Gate 2 (TDD): Passing tests; coverage ≥40% 3. Lite lane complete; code merged

Gate Progression Pattern (Heavy Lane): 1. Gate 1 (ADR): Record intent; detailed Feature Checklist 2. Gate 2 (TDD): Passing tests; coverage ≥40% 3. Gate 3 (Docs): Documentation build passes; markdown lint clean; links valid 4. Gate 4 (BDD): Passing Behave scenarios for external contracts 5. Gate 5 (Human Attestation): Closeout ceremony; explicit human attestation 6. Post-Attestation: Audit run; ADR status → Validated

Documentation = Gate 5 Artifact (critical insight): - Gate 5 is NOT a separate deliverable; it's the result of comprehensive documentation updates - When code changes → operator documentation must reflect those changes - When workflows change → runbooks/walkthroughs must be updated - When contracts change → help text, CLI docs, user guides must be revised - Agents treat documentation updates as required, first-class delivery alongside code - No hand-holding; same rigor as Gates 1-4

Heavy Lane Documentation Obligation (no discretion): - Scan relevant docs BEFORE starting work - Update all affected documentation surfaces in the same PR/branch - Ensure docstrings match actual behavior - Ensure CLI help text is current - Ensure runbooks/walkthroughs have concrete, working examples - Ensure links/anchors are valid - Run markdown lint + mkdocs build to validate

4. ADR/OBPI/GHI/Audit Linkage and Topology

ADR structure (preferred modern layout):

Text Only
docs/design/adr/adr-X.Y.x/ADR-X.Y.Z-{slug}/
  ADR-X.Y.Z-{slug}.md           # Intent document
  ADR-CLOSEOUT-FORM.md          # Optional ceremony workspace
  briefs/
    OBPI-X.Y.Z-01-*.md          # Brief for checklist item 1
    OBPI-X.Y.Z-02-*.md          # Brief for checklist item 2
    ...                         # Sequential, no gaps
  audit/
    AUDIT_PLAN.md               # Pre-audit plan
    AUDIT.md                    # Post-attestation audit log
    proofs/                     # Optional command outputs, receipts
  logs/
    design-outcomes.jsonl       # Optional agent-facing metadata

ADR Lifecycle States (canonical, mutually exclusive): 1. Pool — Planned, lightweight intent only (pre-prioritization) 2. Draft — Being authored; not ready for review 3. Proposed — Submitted for review; awaiting acceptance 4. Accepted — Approved; implementation may begin 5. Completed — Implementation finished; Gate 5 attestation received 6. Validated — Post-attestation audit completed (Phase 2) 7. Superseded — Replaced by newer ADR 8. Abandoned — Work stopped; clear rationale

Pre-release identifier scheme (SemVer compliant): - Format: {major}.{minor}.{patch}[-{type}.{identifier}] - Types: - pool.{slug} — Planned ADR in pool (0.2.0-pool.forecaster-core) - obpi.{nn} — OBPI in progress (0.1.15-obpi.03) - ghi.{nn} — GitHub issue discovered during work (0.1.15-ghi.67)

OBPIs vs GHIs distinction: - OBPIs = planned work — scoped in advance, tied to ADR checklist items - GHIs = emergent work — bugs, surprises, asides discovered while fulfilling OBPI - GHIs are NOT OBPI-level work themselves; they're discovered needs surfaced during execution

5. Tooling and Commands for Managing ADRs/OBPIs

Core Skills (workflow automation):

Available as reusable procedures in .github/skills/:

  1. gz-adr-create (SKILL.md)
  2. Create/update ADR documents

  3. Structure ADR folder, initialize briefs, update registries

  4. gz-obpi-brief (SKILL.md)

  5. Generate compliant OBPI markdown brief
  6. Enforce One Brief Per Item discipline

  7. Template-driven with Heavy Lane mandatory planning template

  8. gz-adr-closeout-ceremony (SKILL.md)

  9. Execute closeout ceremony protocol
  10. Present artifact paths/commands-only summary

  11. Guide human through direct observation (no interpretation)

  12. gz-adr-audit (SKILL.md)

  13. Gate-5 audit templates and procedure

  14. Post-attestation reconciliation

  15. gz-adr-sync (SKILL.md)

  16. Sync ADR index and status tables from source files

  17. Detect and reconcile drift

  18. gz-obpi-sync (SKILL.md)

  19. Sync OBPI status in ADR table from brief sources

  20. Detect and reconcile drift

  21. gz-adr-verification (SKILL.md)

  22. Generate ADR→tests verification report
  23. Use @covers mappings to link ADR to test coverage

Governance Manifest: - Machine-readable governance config at config/governance_manifest.json - Canonical reference for verification commands, gate definitions, doctrine

Registries (must stay in sync): - docs/design/adr/adr_index.md - docs/design/adr/adr_status.md - docs/governance/GovZero/adr-status.md (canonical location)

6. Five Gates Framework

Gate definitions (sole authority: charter.md):

Gate Purpose Lane Artifact Authority
Gate 1 Record intent & tradeoffs Lite, Heavy ADR document with problem/decision/consequences ADR author
Gate 2 Verify implementation correctness Lite, Heavy Passing unit tests; coverage ≥40% CI/test results
Gate 3 Ensure docs describe behavior accurately Heavy only Clean markdown lint, mkdocs build passes, links/anchors valid Markdown validator + manual review
Gate 4 Verify external contract behavior Heavy only Passing Behave scenarios for CLI/API/schema contracts Behave test results
Gate 5 Human directly observes & attests Heavy only Explicit human attestation recorded with timestamp Human attestation only

Lane Selection: - Lite: Internal changes only (no external contract changes) - Heavy: External contract changes (CLI, API, schema, error messages)

7. Key Invariants and Governance Philosophy

Alignment Chain Covenant:

Text Only
Intent (ADR/OBPI) ↔ Code (behavior) ↔ Docs (claims)
All three links must hold. If any breaks, work isn't done.

Scope expansion is not scope creep: - Agents own work completely - Never defer or say "out of scope" - Fix everything broken/misaligned immediately

Documentation is not optional for Heavy lane: - Operator runbooks, walkthroughs, docstrings, mkdocs docs - All surfaces must form coherent public contract - No hand-holding; treat as first-class delivery

Human authority is singular: - Only humans can attest to ADR completion (Gate 5) - Agents present artifacts; humans observe and attest - Audit runs post-attestation for reconciliation only - Ledgers/logs are agent-facing, not proof

8. Referenced Key Documents

GovZero Canon (in docs/governance/GovZero/): - charter.md — Sole authority for gate definitions - adr-lifecycle.md — Lifecycle states, pre-release identifiers, status mapping - adr-obpi-ghi-audit-linkage.md — Canonical linkage rules, artifact placement - audit-protocol.md — Closeout ceremony behavior, agent scripts

Key Governance Files: - /AGENTS.md — AI agent contract; GovZero v6 multi-agent edition - docs/design/adr/CLAUDE.md — ADR governance rules for Claude Code - docs/governance/gate5_documentation_obligation.md — Gate 5 definitive rules - docs/governance/AGENTS_MD_BEHAVIORAL_INVENTORY.md — Behavioral checklist

Key Takeaways for gzkit Documentation

  1. OBPIs are the atomic unit of work — each maps to one checklist item; numbering must be sequential
  2. Closeout ceremony is a mode transition — agent yields authority; human observes directly (never through agent interpretation)
  3. Documentation IS the Gate 5 artifact — not a separate deliverable; comprehensive doc updates are required for Heavy lane
  4. Five Gates form an integrity chain — all must pass; ADR intent must align with code behavior and documentation claims
  5. Governance is executable — lives in markdown, validated by Python CLI (gzkit)
  6. Human attestation is the closure gate — agents present; humans attest; audit reconciles post-attestation
  7. Skills provide reusable procedures — ADR creation, OBPI generation, closeout ceremony, audit, sync/verification

Files for Reference

Absolute paths to key documents: - /Users/jeff/Documents/Code/airlineops/docs/governance/GovZero/charter.md - /Users/jeff/Documents/Code/airlineops/docs/governance/GovZero/adr-lifecycle.md - /Users/jeff/Documents/Code/airlineops/docs/governance/GovZero/adr-obpi-ghi-audit-linkage.md - /Users/jeff/Documents/Code/airlineops/docs/governance/GovZero/audit-protocol.md - /Users/jeff/Documents/Code/airlineops/AGENTS.md - /Users/jeff/Documents/Code/airlineops/docs/design/adr/CLAUDE.md - /Users/jeff/Documents/Code/airlineops/docs/governance/gate5_documentation_obligation.md - /Users/jeff/Documents/Code/airlineops/.github/skills/gz-adr-* (suite of skills)