# Session Handoff — ADR-0.0.28 closeout + structural-fix backlog (2026-05-05)

## Status

- **ADR-0.0.28 (complexity-threshold-doctrine): Validated** — 3/3 OBPIs attested-completed, audit emitted, receipt landed.
- **Cluster deliverables:** `.gzkit/rules/complexity-thresholds.md` (rule body, 12 metrics × 3 bands, citation tuple at corpus_revision 1), `src/gzkit/complexity/thresholds.py` (frozen `ThresholdBand` + `ThresholdTable` + `load_threshold_table` + `band_for` + `bands_for_metric`), `src/gzkit/schemas/complexity_thresholds.json` (JSON Schema mirror), `src/gzkit/governance/trust_audits/complexity_thresholds.py` (validator), `gz validate --complexity-thresholds` flag + `gz check` step "Complexity-thresholds", `features/complexity_thresholds.feature` (7 scenarios), command-doc + runbook updates.
- **Receipt:** `arb-meta-receipt-bind-...` from `gz adr emit-receipt --event validated`.

## In-flight defects filed (5 GHIs — read these first next session)

| GHI | Class | Layer |
|---|---|---|
| **#403** | `gz plan audit` false-positives on create-new-file paths | runtime (validator logic) |
| **#404** | Measurement-pipeline parser produces all-zero baselines for `lizard_nesting_depth` and `cohesion_lcom4` | upstream (OBPI-0.0.27-03 pipeline) |
| **#405** | Polarity-aware threshold model for `radon_mi` (lower-is-worse) | model-layer (OBPI-0.0.28-02 amendment) |
| **#406** | Cluster brief-coherence checks at brief-authoring time | runtime / mechanical |
| **#407** | `gz-adr-evaluate` rubric extension for cross-OBPI coupled-surface coherence | evaluation-time / rubric |

## Operator critique (verbatim)

> *"every obpi is full of this jankiness now - all of them. DO IT RIGHT."*
> *"gzkit is becoming about as stable as Nitroglycerin"*
> *"cute read, but not helpful, I am looking for solutions"*

The cluster shipped via three improvised in-flight stability passes (each OBPI paying tax for predecessors' brief defects: vendor-mirror paths, Discovery Checklist subsections, schema coherence, stale CLI-package paths). The 5:1 governance-to-output ratio is supposed to be the deliverable; this session inverted it.

## Solution stack — concrete next-session work

### S1 — `gz validate --brief-paths` (4-6 hours; closes 3 of 4 defect classes)

One scope, three checks, wired into `gz check`:

- **`_check_no_vendor_mirror_paths`** — reject `.claude/rules/`, `.claude/skills/`, `.agents/`, `.github/instructions/`, `.github/skills/` from Allowed Paths.
- **`_check_discovery_checklist_subsections`** — port `gz obpi precomplete` Discovery Checklist check up from Stage 5 to brief-authoring time.
- **`_check_allowed_paths_resolve_or_declared_net_new`** — for each Allowed Path, verify it exists OR matches a "creates these files" line in the brief's plan file. Closes #403.

Files: 1 new module under `src/gzkit/governance/trust_audits/brief_paths.py` (~150 LOC); wiring lines in `validate_cmd.py` + `quality.py` + `parser_maintenance.py`. **Single OBPI of work.**

### S2 — `gz adr cluster-validate` (1-2 days; closes the 4th class — cross-OBPI schema coherence)

Walks every OBPI in `obpis/`. For each `(N, N+1)` sequential pair:

1. Parse REQ value-set constraints from OBPI-N+1.
2. Check OBPI-N's deliverable shape conforms.

The hard part is `extract_req_constraints`: parse REQ text like *"corpus_percentile (constrained to canonical percentile values from OBPI-0.0.27-04: 50, 75, 90, 95, 99)"* into a structured `EnumConstraint`. Two paths:
- **(a) Heuristic regex** on REQ text — works for canonical patterns, brittle.
- **(b) Schema-level constraint declaration** in brief frontmatter — see S4.

Wire into `gz adr create` (post-authoring) AND `gz check`. **One OBPI of work for heuristic version.**

### S3 — Strengthen `gz-adr-evaluate` (4-6 hours; evaluation-time backstop)

Add Dimension 9 + Red-team Challenge 11 to `.claude/skills/gz-adr-evaluate/assets/ADR_EVALUATION_FRAMEWORK.md`. CLI pre-screen `uv run gz adr evaluate` invokes `gz adr cluster-validate` and folds findings into Dimension 9 score.

Files: framework doc edit, `src/gzkit/commands/adr_evaluate_cmd.py` extension. **Half OBPI of work.**

### S4 — Brief-frontmatter `creates: / consumes: / produces:` (1-2 days; structural fix)

Right shape for cross-OBPI coherence is contract declarations in frontmatter, not REQ-prose parsing:

```yaml
---
id: OBPI-0.0.28-02-threshold-loader
creates:
  - src/gzkit/complexity/thresholds.py
consumes:
  - artifact: .gzkit/rules/complexity-thresholds.md
    produced_by: OBPI-0.0.28-01
    schema:
      corpus_percentile: {type: int, enum: [50, 75, 90, 95, 99]}
produces:
  - artifact: src/gzkit/complexity/thresholds.py:ThresholdTable
    consumed_by: [OBPI-0.0.28-03, ADR-0.0.29, ADR-0.0.30]
---
```

`gz adr cluster-validate` becomes mechanical: walk every brief's `consumes`, find producing brief's `produces`, structurally compare. No prose parsing.

Files: `OBPIBriefFrontmatter` Pydantic model extension, brief-template scaffold updates, cluster-validate rewrite. **One OBPI of work, load-bearing.**

## Recommended sequence

- **Tactical batch (1 ADR):** S1 + S3. Closes 3 of 4 defect classes + extends evaluation gate. ~10-12 hours.
- **Strategic batch (1 ADR):** S4 + S2. S4 first (cluster-validate depends on frontmatter contracts). ~3 days.

## Resume command

```bash
# Read this handoff
cat .gzkit/handoffs/2026-05-05-adr-0.0.28-complete-structural-fix-pending.md

# Verify ADR-0.0.28 state
uv run gz adr status ADR-0.0.28

# Inspect the 5 filed GHIs
gh issue list --repo tvproductions/gzkit --search "GHI #403 #404 #405 #406 #407" --state open

# Start the structural-fix ADR cluster (recommend S1 first)
uv run gz plan create --kind feature  # for the structural-fix ADR
# OR start with the cluster-validate prototype directly under a chore
```

## Context-window note

Session ended with full context window. The next session should re-orient via `scripts/session_orientation.py` (auto-runs at SessionStart) and read this handoff before continuing.
