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

# 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:

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):

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

# 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:

# 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)