Gz Obpi Specify

---
name: gz-obpi-specify
persona: main-session
description: Use to decompose an ADR item into an authored OBPI brief.
category: obpi-pipeline
lifecycle_state: active
owner: gzkit-governance
last_reviewed: 2026-10-17
metadata:
  skill-version: "1.9.4"
model: opus
---

# gz-obpi-specify

Decompose an ADR's Feature Checklist into implementable OBPI briefs. Each brief
inherits lane, objective, and scope from the parent ADR's WBS table — not from
hardcoded defaults.

---

## Rationale: Increment Size as a Safety Property

OBPI increment size is **not a process preference** — it is an architectural
safety property. The brief boundary is the only reliable firing point for
governance gates.

Interpretability research (Lindsey et al. 2025) shows that once a model is
committed mid-output, grammatical-coherence circuits hold it on-rails until
the current structural unit is finished, even when safety circuits would
otherwise want it to stop. The repo-level analog: once an agent is three
files deep in a multi-file edit, completion pressure holds it on-rails until
the edit is structurally complete — a gate that would otherwise block the
direction cannot fire cleanly mid-edit.

OBPI briefs function as the agent's "sentence boundaries": the gate can fire
between briefs, not inside one. Bundling two briefs' worth of work into one
implementation pass collapses that firing point, even when the two briefs
are related. Keep briefs narrow enough that the pipeline has somewhere to
stop you.

---

## Pre-Save Ground-Truth Check (GHI #190)

Before saving a brief, every path in the `Allowed Paths` and `Denied Paths`
sections MUST be verified against on-disk reality. LLM authoring routinely
imports model priors from adjacent projects and writes them as if they were
gzkit conventions. The OBPI-0.0.16-03 brief shipped with fabricated framework
paths (`config/chores/<slug>.toml`-style layouts); the gzkit chore framework
authors chores at `.gzkit/chores/<slug>/`, generates the package copy at
`src/gzkit/chores/<slug>/` and keeps a JSON registry at `.gzkit/chores/registry.json`,
and the implementer had to rewrite Allowed Paths as a scope amendment.

### Per-path verification — apply to every Allowed Paths and Denied Paths entry

For each path:

1. **Glob the path** — `Glob(pattern=<path>)`. If the path matches existing
   files, the path is grounded. Continue.
2. **Glob the parent directory** — `Glob(pattern=<parent>/*)`. If the parent
   exists, inspect its contents:
   - Confirm at least one file in the parent uses the same extension
     (`.py`, `.toml`, `.json`, `.md`) as the proposed path. The matching
     extension is your evidence that the file you propose to create is
     consistent with the convention of the directory.
   - If the parent exists but no file shares the extension, STOP — either
     the convention is different (verify by reading a sibling file) or the
     proposed path is fabricated. Do not save.
3. **If neither the path nor the parent exists** — the path is green-field.
   Mark it `**CREATE**` (or list it under a `Creates these files` heading):
   `gz obpi validate --authored` fails any other Allowed Path that does not
   exist on disk. Then verify the convention by:
   - Reading the parent ADR's Decision / Evidence sections for the
     intended layout, OR
   - Searching for adjacent precedents (`Grep`, `Glob`) that establish the
     intended convention, OR
   - Asking the human ("the brief proposes `<path>` but no precedent exists;
     is this a new convention?") before saving.

### Mandatory STOP conditions

Do NOT save a brief if any of the following is true:

- An Allowed Path references a directory tree that does not exist and has
  no precedent (e.g. `config/chores/<slug>.toml` when chores are authored in
  `.gzkit/chores/<slug>/` and generated to `src/gzkit/chores/<slug>/`, GHI #1044).
- An Allowed Path uses an extension that no sibling file uses
  (e.g. `.toml` when sibling files are `.json`).
- The author has not personally read at least one existing file in each
  parent directory of an Allowed Path before saving.

### Anti-pattern

| Thought | Reality |
|---------|---------|
| "The framework probably uses TOML for chores like airlineops does" | Verify it. `Glob("config/**/*.toml")` and `Glob("config/**/*.json")` will tell you in one call which convention this repo uses. |
| "I'll let the implementer correct the paths if they're wrong" | One Glob call before saving costs far less than an in-flight scope amendment and a context-burning rewrite (OBPI-0.0.16-03). |
| "The Allowed Paths look architecturally correct — that's enough" | Architectural plausibility is not ground truth. Run the Glob. Read a sibling file. Then save. |

### What is mechanical today

`gz obpi validate --authored` and `gz plan audit` fail closed on an Allowed Path
that does not exist on disk unless it carries a `**CREATE**` marker or sits under
a `Creates these files` heading; a vendor-mirror path fails regardless (GHI #393,
#403, #419; `src/gzkit/governance/brief_path_validity.py`). The convention check
for a green-field path — extension, sibling precedent — is still by hand, and
this section governs it.

---

## Discovery Order Pin (GHI #321)

When authoring a brief semantically, read the parent ADR's structured
input — § Decision item, then § Intent — **before** anything else (Allowed
Paths, Prerequisites, Existing Code). The OBPI brief template's Discovery
Checklist now pins this order: item #1 instructs the agent to **quote the
parent ADR § Decision item this OBPI implements** verbatim into the brief's
Implementation Summary, with a STOP guard below the pin: *"If you cannot
quote the parent ADR § Decision item that this OBPI implements, STOP and
re-read."*

The failure pattern it closes: an agent grepping backward from a keyword to a
code path rather than tracing forward from the parent ADR's Decision
(failure-mode taxonomy ADR-0.0.23 *Skipped cheap verification*; current-card
provenance is owned by `.gzkit/rules/agent-failure-modes.md`). When the first
authoring step is "quote the Decision item," drift between the ADR's Feature
Checklist line and the OBPI brief is structurally harder to introduce.

The pin lives in the rendered template (`src/gzkit/templates/obpi.md`).
A brief that drifts the pinned items out of order, deletes the STOP guard,
or omits the Decision quote in Implementation Summary is the same class of
defect as a thin Allowed Paths section: a brief that won't survive pipeline
execution.

## When to Use

- After an ADR is authored and its Decomposition Scorecard is valid
- When the Feature Checklist and WBS table are aligned (same count, same ordering)
- To create one OBPI brief per checklist item

## When NOT to Use

- For pool ADRs (they cannot receive OBPIs until promoted)
- If the ADR has no Feature Checklist or Decomposition Scorecard
- If the WBS table and Feature Checklist are misaligned (fix the ADR first)

---

## Invocation

```bash
# Create one OBPI brief (lane and objective from WBS table)
uv run gz specify my-feature-slug --parent ADR-0.0.11 --item 3

# One-shot fast path: fail-closed, and writes NO file if the authored pass fails
# (§ Skill Responsibility step 1). Not the standard route.
uv run gz specify my-feature-slug --parent ADR-0.0.11 --item 3 --author

# Override lane explicitly
uv run gz specify my-feature-slug --parent ADR-0.0.11 --item 3 --lane heavy

# Dry run (show what would be created)
uv run gz specify my-feature-slug --parent ADR-0.0.11 --item 3 --dry-run

# Create all OBPIs for an ADR (run once per checklist item)
for i in $(seq 1 6); do
  uv run gz specify slug-$i --parent ADR-0.0.11 --item $i
done
```

---

## What the Command Does

1. **Reads the parent ADR** — resolves file, parses Feature Checklist and Decomposition Scorecard
2. **Validates alignment** — checklist item count must match scorecard target
3. **Parses the WBS table** — extracts lane, specification summary, and status per row
4. **Resolves lane** — priority: explicit `--lane` CLI arg > WBS table row > fallback `lite`
5. **Resolves objective** — from WBS specification summary column (not "TBD")
6. **Creates the brief** — renders the OBPI template with populated frontmatter
7. **Records the ledger event** — appends `obpi_created` to the project ledger

---

## Lane Resolution

| Source | When Used |
|--------|-----------|
| `--lane heavy` (CLI) | Always wins when explicitly passed |
| WBS table row | Used when `--lane` is not passed and WBS table has a row for this item |
| Fallback `lite` | Used when neither CLI nor WBS provides a lane |

The command prints the lane source so the operator can verify:
```
Lane: heavy (source: WBS table)
```

---

## Authored-Readiness Contract

`gz specify` is the ADR-to-OBPI decomposition command, not a pseudo-authoring
shortcut. It fills the brief with deterministic ADR-derived content, but the
brief is only ready for pipeline execution when it passes authored validation:

```bash
uv run gz obpi validate --adr ADR-0.0.11 --authored
```

That gate requires each brief to have substantive:

- Objective
- Allowed Paths
- Denied Paths
- Requirements (FAIL-CLOSED)
- Discovery Checklist prerequisites and existing-code entries
- OBPI-specific verification commands
- REQ-backed acceptance criteria

## REQ Kind Authoring

Every REQ in an OBPI brief's `## Acceptance Criteria` MUST carry exactly one kind tag
between the REQ ID and the colon (ADR-0.0.59-02; enforced by `gz validate --req-kind-discipline`):

```text
REQ-X.Y.Z-NN-01 [BEHAVIOR]: the system does X when Y
REQ-X.Y.Z-NN-02 [SUPPORT]: the rule file carries subsection Z — gz validate --documents + artifact_edited event
REQ-X.Y.Z-NN-03 [STRUCTURAL-FENCE]: cross-OBPI boundary invariant P holds
```

### Choosing the kind

| Use [BEHAVIOR] when... | Use [SUPPORT] when... | Use [STRUCTURAL-FENCE] when... |
|----------------------|----------------------|-------------------------------|
| The REQ is about code behavior — a function produces output X, a CLI command exits Y, a state machine transitions Z | The REQ is about a governance artifact, doc, rule file, or data file that supports behavior but is not behavior itself | The REQ spans multiple OBPIs and can only be audited at ADR closeout, not per-OBPI |

### Per-kind requirements

**BEHAVIOR** — must include `tests/**` in Allowed Paths. The proof is a `@covers`-decorated test.

**SUPPORT** — must include BOTH in the REQ text:
- A `gz validate --` scope reference (e.g. `gz validate --documents`)
- A ledger event keyword (e.g. `artifact_edited`, `obpi_created`)

Example: `REQ-X.Y.Z-NN-02 [SUPPORT]: docs/governance/X.md gets Y section — gz validate --documents + artifact_edited event`

**STRUCTURAL-FENCE** — the parent ADR must have a `## Boundary Invariants` section naming this invariant.
Add it to the parent ADR before running `gz validate --req-kind-discipline`.

### Validator

```bash
# Fails closed (exit 3) on mixed-state or missing proof citations
uv run gz validate --req-kind-discipline
```

Also runs as part of `uv run gz check`.

---

## Skill Responsibility

The skill does not stop at `uv run gz specify`.

The intended workflow is:

1. Run `gz specify <slug> --parent ADR-<X.Y.Z>` to materialize the OBPI from the ADR/WBS contract.
   **Do not pass `--author` here.** `--author` runs the authored-validation pass and
   `raise SystemExit(1)` fires *before* `_write_specify_outputs`, so a failed authored
   pass leaves **no file on disk** — there would be nothing for steps 2-4 to author.
   And when it succeeds the brief has already passed `gz obpi validate --authored`,
   which is step 4's exit condition, so steps 2-4 are already discharged. The runtime
   says so itself: the non-`--author` path prints *"Review allowed paths, requirements,
   and acceptance criteria for OBPI-specific scoping"* followed by *"Validate with:
   uv run gz obpi validate --authored"* — steps 2, 3, and 4 — while the `--author`
   path prints *"validated for pipeline entry"* and returns with no authoring guidance.
   Treat `--author` as an optional one-shot fast path for an ADR rich enough to emit a
   compliant brief directly; it is fail-closed, not the standard route.
2. Read the parent ADR sections that govern the item: Feature Checklist, WBS row,
   Intent, Decision, Boundary Invariants, Evidence, and adjacent OBPIs when needed.
3. Author the brief semantically:
   - narrow Allowed Paths and Denied Paths to the real execution boundary
   - rewrite Requirements into OBPI-specific fail-closed rules
   - populate Discovery Checklist with real prerequisite and existing-code reads
   - replace generic verification with commands that prove this item specifically
   - ensure Acceptance Criteria are concrete and mapped to REQ IDs (with `[kind]` tags)
4. Run `uv run gz obpi validate --authored <path>` and keep authoring until it passes.

The CLI owns deterministic decomposition. The skill owns the semantic authoring
pass that turns the generated brief into an execution contract.

---

## Pre-Conditions

- Parent ADR must have a valid Decomposition Scorecard
- Feature Checklist item count must match scorecard `Final Target OBPI Count`
- Parent ADR must not be a pool ADR

## Post-Conditions

- OBPI brief file created at `{adr-dir}/obpis/OBPI-{version}-{NN}-{slug}.md`
- Lane matches WBS table (or CLI override)
- Objective derived from WBS specification summary
- `obpi_created` ledger event recorded

---

## Validation

After creating all briefs:

```bash
# Fail closed if any brief is still thin or pseudo-authored
uv run gz obpi validate --adr ADR-0.0.11 --authored

# Verify count matches
ls docs/design/adr/foundation/ADR-0.0.11-*/obpis/ | wc -l

# Verify lanes match WBS
grep "^lane:" docs/design/adr/foundation/ADR-0.0.11-*/obpis/*.md

# Register any unregistered OBPIs
uv run gz register-adrs ADR-0.0.11 --all
```

---

## Heavy Lane Requirements

When a brief's lane is Heavy (from WBS or CLI override):

1. **Read `assets/HEAVY_LANE_PLAN_TEMPLATE.md`** before authoring — this is mandatory
2. Heavy adds Gate 3 (docs) and Gate 4 (BDD) to Gates 1–2: BDD scenarios and
   docs/manpage updates are additional acceptance criteria
3. Gate 5 attestation is **universal** — required before closure of every OBPI
   in every lane (ADR-0.0.36), not a Heavy-lane extra

**Closure failure modes (every lane):**
- Marking OBPI closed before human attestation
- Skipping Gate 5 attestation step
- Not presenting CLI commands for human verification

---

## Common Rationalizations

These thoughts mean STOP — you are about to ship a thin or pseudo-authored brief:

| Thought | Reality |
|---------|---------|
| "The generated brief looks complete enough — ship it" | `gz specify` only fills ADR-derived defaults. The semantic authoring pass is mandatory. The authored validation gate exists because generated briefs are the start, not the end. |
| "The Allowed Paths from the template will work" | Template defaults are intentionally broad. Narrow them to the real execution boundary or the OBPI will sprawl during implementation. |
| "I can leave Discovery Checklist generic — the implementer will figure it out" | Generic checklists produce generic implementations. The checklist is where you record the prerequisite reads that prevent re-discovery on every pipeline run. |
| "REQ IDs are bookkeeping — I'll add them after the brief is approved" | Tests derive from REQ IDs. No REQ IDs means tests cannot be traced to acceptance criteria, which collapses the TDD discipline at Gate 2. |
| "Verification commands can be the same across all OBPIs in this ADR" | The point of OBPI-specific verification is that each brief proves *this* increment. Shared verification means you can't tell which brief broke. |
| "The WBS lane says lite but this is heavier than I thought — I'll just proceed lite" | The WBS lane is the canonical contract. If the work is heavier, fix the WBS first, then re-run specify. Silently proceeding lite skips Gates 3–4 (docs and BDD); Gate 5 applies either way. |
| "`gz obpi validate --authored` is failing on minor things — I'll dismiss them" | The authored gate is fail-closed for a reason. Each warning is a brief that won't survive pipeline execution. Fix every one. |

## Red Flags

- A brief whose Allowed Paths matches the parent ADR's full scope (no narrowing)
- Requirements section that copies the ADR's intent verbatim instead of OBPI-specific fail-closed rules
- Discovery Checklist with no concrete file paths or prerequisite reads
- Acceptance Criteria written in prose without REQ-XX identifiers
- Verification commands that don't actually exercise this OBPI's surface
- Heavy lane brief without `assets/HEAVY_LANE_PLAN_TEMPLATE.md` consulted
- Stopping at `gz specify` without running `gz obpi validate --authored`

## Related Skills

| Skill | Relationship |
|-------|--------------|
| `gz-adr-create` | Creates the parent ADR that specify decomposes |
| `gz-obpi-pipeline` | Executes briefs created by specify |
| `gz-adr-evaluate` | Evaluates ADR+OBPI quality (run after specify) |