---
mode: CREATE
adr_id: ADR-0.0.63
branch: main
timestamp: "2026-05-29T07:10:16Z"
agent: claude-code
obpi_id: OBPI-0.0.63-07
session_id: salvation-phase-i-adr-0.0.63
continues_from: 20260529T061728Z-pause-obpi02-done-obpi07-authored.md
---

<!-- Token-block register fields (HandoffFrontmatter forbids them as keys; kept in body per
     token-block-discipline § Register-Entry Minimum-Information Rule "in frontmatter or body"):
     last lock-event timestamp: 2026-05-29T06:23:53Z (OBPI-0.0.63-07 lock claim) ;
     last commit SHA at handoff: 846c1737 ; branch state: main, synced with origin/main. -->

## ADR / OBPI (full identifiers)

- Parent ADR package: `ADR-0.0.63-closeout-ceremony-runtime-engine-parity`
- This OBPI: `OBPI-0.0.63-07-verify-stage-command-shape-gate`

## Current State Summary

Continuing the June 2026 Road-to-Salvation Phase I (full ADR-0.0.63). **OBPI-0.0.63-07 is COMPLETE — attested_completed, committed, pushed.** ADR-0.0.63 is now **2/7 OBPIs done** (02 + 07). Paused for a fresh-context checkpoint.

Progress this session:
- **OBPI-0.0.63-07 (verify-stage-command-shape-gate): COMPLETE.** Closes GHI #550 at the authoring-gate level. Shipped `gz validate --brief-command-shape` (parser flag + validate_cmd dispatch + `audit_brief_command_shape` in `trust_audits/briefs.py` + `__init__` re-export) AND verify-stage classify-before-dispatch in `obpi_stages.py::_pipeline_verification_commands` (raises SystemExit(1) on non-shell-less commands). Both consume the BI-1 classifier `brief_commands.is_shell_less_executable` — no fork (REQ-04). Template + manpage document the single-program contract. 11 OBPI tests + 5732 full suite GREEN; ruff/ty/mkdocs clean. Attested by Jeffry Babb (operator-verbatim "attest completed", agent-relayed under active pipeline marker). REQ-03 accepted-uncovered as SUPPORT.
- **GHI #565 filed** (sibling of #550): 40 pre-existing active-brief Verification compound-command violations the new gate surfaces. Cross-linked on #550.
- **Direct-fix:** 2 completed ADR-0.9.0 briefs (OBPI-0.9.0-04 heredoc, -05 `&&`) rewritten shell-less in flight.

Last action succeeded: final `gz git-sync --apply` pushed; tree clean.

## Important Context

- **Use the skills, do not improvise the pipeline.** Author briefs via `gz-obpi-specify`, run via `gz-obpi-pipeline`, close the ADR via `gz-adr-closeout-ceremony`.
- **DESIGN DECISION (terminal-status skip) — `_BRIEF_TERMINAL_STATUSES` in `briefs.py`.** `audit_brief_command_shape` skips briefs whose frontmatter status is Completed/attested_completed/Validated/Superseded/archived/Promoted. Rationale: the gate is authoring-time only (#550 objective: "fails closed at authoring time"); terminal-status briefs are historical records, not active authoring surfaces. **This carve-out is NOT described by REQ-01/02** — it was an in-flight decision when the unscoped scan surfaced 207 violations (vs. 40 active). It is defensible but is spec-vs-implementation drift the ADR-0.0.63 closeout auditor should be aware of. Consider documenting it in REQ-02 or a brief note at closeout. It silently *allows* a Completed brief with a compound command — acceptable because completed briefs are never re-executed at verify, only at closeout demo re-execution (and the gate is not the closeout demo path).
- **`--brief-command-shape` is OPT-IN (`explicit_scopes`, `default=False`)** — NOT in the default `gz check` scope. This is deliberate: the 40 pre-existing violations (GHI #565) would break default `gz check` otherwise. Promoting to default scope is gated on draining #565.
- **OBPI-07 Demo section fixed for closeout binding.** The Demo was `uv run gz validate --brief-command-shape` (exits 3 on the 40 violations). At ADR-0.0.63 closeout, OBPI-02's demo re-execution (`reexecute_demo`, `expected_returncode=0`) would bind `mismatch=True` and break closeout. Changed to `uv run -m unittest tests.governance.test_brief_command_shape` (shell-less, exit 0, exercises both pass+fail paths). **Audit every remaining OBPI's `## Demo` against this same constraint before closeout.**
- **`gz obpi complete` on heavy/foundation needs `--attestor-present`** (agent-relayed, gated on active pipeline marker, GHI #292) when run headless with `--accept-uncovered`. The runtime `gz obpi pipeline --from=sync` passes it automatically and translates `accept_uncovered`/`accept_uncovered_reason` from `--evidence-json`. SUPPORT/STRUCTURAL-FENCE REQs are `covered=False` in `gz covers` by design.
- **Pre-commit src/tests with a `Task:` trailer BEFORE Stage 5 git-sync** (operator's booked decision). `gz git-sync` Ceremony commits lack `Task:` trailers, which GHI #552 strict mode flags for src/tests scope. This session: code landed in commit `6b85ebbc` with `Task: TASK-0.0.63-07-01-01`; git-sync ceremony-committed only non-src/tests artifacts.
- **`gz git-sync` first attempt may fail transiently** (fetch/push); re-running succeeded. If the sync stage aborts mid-Stage-5, the lock + markers are NOT auto-cleaned — release lock + `rm` markers manually, then reconcile + adr status + final git-sync.
- **OBPI-06 is BLOCKED**: consumes a `req_evidence:` field absent from `src/gzkit/schemas/obpi_brief_structure.json`; owning `ADR-pool.obpi-authoring-mechanical-floor` still Pool. Operator-approved resolution: land a minimal `req_evidence` schema field within OBPI-06 itself; flag the pool-ADR relationship for later narrowing.
- **ADR's absorbed-findings line numbers are stale** (cited 2026-05-26): re-anchor each brief's line citations against current code before implementing.
- **`_extract_gz_verb_chain` (ceremony_data.py) positional-capture demo-loss bug** — tracked in agent-insights.jsonl; route at closeout.

## Decisions Made

- **Decision:** Skip terminal-status briefs in `audit_brief_command_shape`. **Rationale:** authoring-time gate; completed briefs are historical. **Alternative rejected:** scan all briefs (207 violations, would block on closed history). See Important Context for the spec-drift caveat.
- **Decision:** OBPI-07 Demo = unittest invocation, not the bare validator scan. **Rationale:** closeout demo re-execution requires exit 0; the bare scan exits 3 on #565 debt. **Alternative rejected:** fix all 40 violations inline (out of OBPI-07 scope; routed to #565).
- **Decision:** Validator is opt-in, not default `gz check`. **Rationale:** 40 pre-existing violations would break default pipeline; promotion gated on #565.

## Immediate Next Steps

1. **OBPI-0.0.63-01 (step-advance-gate-5-enforcement)** — next in order. Owns `closeout_ceremony.py` (the state machine, BI-3 anchor). Wire OBPI-02's demo-receipt binding here. Run `/gz-plan-audit OBPI-0.0.63-01` then `gz-obpi-pipeline`.
2. **Then in order:** 03 (proof-binding validator) -> 05 (dual-runtime collapse) -> 06 (req-evidence schema — resolve blocker) -> 04 (wording fix). Finally `gz-adr-closeout-ceremony` for ADR-0.0.63.
3. **Before each Stage 5:** pre-commit src/tests with `Task:` trailer, then `gz git-sync --apply`; complete via `gz obpi pipeline <id> --from=sync --attestor "Jeffry Babb" --evidence-json '<json with accept_uncovered for non-BEHAVIOR REQs>'`.

## Pending Work / Open Loops

- **5 OBPIs remain:** 01, 03, 05, 06 (blocked on req_evidence schema), 04.
- **GHI #565** — drain 40 pre-existing brief Verification compound commands (precondition for promoting `--brief-command-shape` to default scope).
- **OBPI-06 schema blocker** — land minimal `req_evidence` field in OBPI-06.
- **Pre-existing repo-wide `gz check` failure (NOT this ADR):** `ADR-0.0.64`'s `REQ-0.0.64-05-06` lacks a `gz validate --<scope>` citation → `gz validate --req-kind-discipline` fails (now tracked as GHI #561). Will block ADR-0.0.63 closeout's quality pipeline. Do NOT blind-fix; needs the 0.0.64 owner.
- **GHIs to close at ADR-0.0.63 closeout:** #539, #540 (OBPI-02), #550 (OBPI-07 — verify the authoring-gate close satisfies it), #516 (relabel/close per OBPI-01/03), #565 (only when drained).
- **`_extract_gz_verb_chain` positional-capture demo-loss bug** — route at closeout.
- **Audit every remaining OBPI `## Demo` for exit-0 closeout-binding safety** (see Important Context).

## Verification Checklist

- [ ] `git branch --show-current` returns `main`; tree clean
- [ ] `uv run gz adr status ADR-0.0.63-closeout-ceremony-runtime-engine-parity` shows 02 + 07 `attested_completed`, others `pending`/`draft`
- [ ] `uv run -m unittest tests.governance.test_brief_command_shape tests.commands.test_obpi_stages` -> 11 pass
- [ ] `uv run gz validate --brief-command-shape` exits 3 with 40 violations (the #565 debt; opt-in scope, does not block `gz check`)
- [ ] `python -c "from gzkit.governance.trust_audits import audit_brief_command_shape"` imports cleanly
- [ ] `gh issue view 565` open; `gh issue view 550` carries the #565 cross-link comment

## Evidence / Artifacts

- `src/gzkit/governance/trust_audits/briefs.py` — `audit_brief_command_shape` + `_BRIEF_TERMINAL_STATUSES`
- `src/gzkit/governance/trust_audits/__init__.py` — re-export
- `src/gzkit/commands/obpi_stages.py` — classify-before-dispatch in `_pipeline_verification_commands`
- `src/gzkit/cli/parser_maintenance.py` — `--brief-command-shape` flag
- `src/gzkit/commands/validate_cmd.py` — scope wiring (6 sites)
- `docs/user/manpages/validate.md` — `--brief-command-shape` section
- `.gzkit/templates/obpi.md` (+ `src/gzkit/templates/obpi.md` mirror) — Verification authoring contract
- `tests/governance/test_brief_command_shape.py` (8 tests), `tests/commands/test_obpi_stages.py` (3 tests)
- `data/behave_coverage_waivers.json` — OBPI-07 waiver
- `.claude/plans/verify-stage-command-shape-gate-OBPI-0.0.63-07.md` — heavy-lane plan
- `.gzkit/insights/agent-insights.jsonl` — OBPI-07 session entry (40-violation finding)
- Commits: `6b85ebbc` (feat code, Task: trailer), `1e820494` + `846c1737` (git-sync ceremony)

## Environment State

Python 3.13 / uv. Model: Opus 4.8 (Phase-I engineering needs Opus per Road-to-Salvation). No feature branch — work lands on `main` via `gz git-sync`.
