---
mode: CREATE
adr_id: ADR-0.0.37
branch: main
timestamp: "2026-06-06T12:30:00Z"
agent: claude-code
obpi_id: OBPI-0.0.37-20
session_id: finish-adr0037-cms
continues_from:
---

<!-- Handoff for ADR-0.0.37 — created by claude-code at 2026-06-06T12:30:00Z -->

## This handoff ADVISES next moves — it is NOT authorization to execute them

On resume you MUST (1) present the advised steps to the operator, (2) obtain
explicit authorization before any file mutation, `gz` ceremony, or pipeline run,
and (3) treat human-as-final-witness as binding. You advise; the operator rules.
Every OBPI below is foundation/heavy — Gate 5 human attestation is mandatory and
cannot be self-closed.

## Current State Summary

Session began as a `gz git-sync` (clone was 61 commits behind after cross-machine
macOS work; pulled clean). `gz check` was then measured RED **twice** and restored:

- **Typecheck red** (`src/gzkit/complexity/advisor/timeout.py`): POSIX-only
  `signal.SIGALRM`/`setitimer`/`ITIMER_REAL` flagged by `ty` on Windows (runtime is
  already guarded by `os.name == "nt"`; cross-machine false-red). Fixed `14dec36c`.
- **Behave red** (8 scenarios): OBPI-0.0.37-08's Stage-5 reconcile-receipt gate broke
  stale completion BDD fixtures. Fixed `f7428b2b` (fixtures seed a real
  `brief_reconciled` receipt via the production factory).
- Plan made true + dieted: `46be55ba` (Snapshot K), `2dd9439c` (header 48->10 lines,
  snapshot prose A-J collapsed to a table; net -89 lines).

`gz check` is **26/26 GREEN**, tree clean, synced `0/0` with `origin/main`.

Then: **attack #519 via ADR-0.0.37.** Confirmed the chain `#519 -> ADR-0.0.37 -> #533`.
The work for this handoff is to **finish ADR-0.0.37** (the durable <15k cure). No code
was written for the cure this session — the next-OBPI brief (OBPI-0.0.37-20) was fully
authored *in this document* (see Decisions / Next Steps) but not yet saved, because the
operator chose to capture the plan as a handoff rather than grind the marathon in-session.

## Important Context

**The bill (measured, not estimated):** The real always-loaded context surface is
**128,627 bytes (~32k tokens)**: `.claude/rules/*.md` = **93,671 B (73%, 21 files)**,
`AGENTS.md` = 28,489 B (22%), `.gzkit/agents.local.md` = 4,997 B, `CLAUDE.md` = 1,470 B.
**ADR-0.0.37's CMS targets only AGENTS.md (the 22%).** The rules files (the 73%) are NOT
in its scope and need their own CMS ADR (operator: "if there is not an ADR for that, then
we'll need more" — deferred, future work, not now).

**ADR-0.0.37 is 11/19 attested, 8 pending, BLOCKED.** Of the 8 pending, **7 are
unauthored scaffolds** (scaffold-default REQs, allowed-paths that cannot touch `src/`): items
20, 21, 22, 23, 24, 25, 27. Only item 10 (doctrine-refresh) is authored. The substrate is
hollow: the append-only corpus `.gzkit/corpus/AGENTS.md.jsonl` is **895 bytes**; the
invariant registry `.gzkit/invariants/` has **4 entries** (CIC-1, CIC-2,
foundation-adr-registers, skill-first) versus the **~60** that #533 says the cure needs.
Pipelining a scaffold OBPI over an empty corpus would be exactly the "vibe-coded slop"
the operator flagged — author first, never pipeline a scaffold-default.

**Build order (dependency-first):** `20 (setpoint) -> 23 (invariant tier) -> 21 (composer)
-> 22 (rendition store + playback) -> 24 (advisor QC) -> 25 (bullet-retention tier-aware)
-> 27 (migration/disposition) -> 10 (doctrine)`. Each is heavy/foundation + Gate 5; this
is a multi-session marathon.

**The setpoint substrate already exists** (re-homed, not built fresh):
`data/vendor-manifest.json` has `content_type_temperatures = {AgentContract: {codex: lite,
claude: heavy}}` plus a `content_type_routes` key; `src/gzkit/content/vendors.py`
`temperature_for(content_type, vendor, *, project_root)` (line 119) already raises
(fail-closed) on an undeclared pair. Validator scopes live one-per-module under
`src/gzkit/governance/trust_audits/`; scope args register in
`src/gzkit/cli/parser_maintenance.py`; dispatch is in
`src/gzkit/commands/validate_cmd.py`; the manpage is `docs/user/manpages/validate.md`.

**Acute #519 is already relieved** (root AGENTS.md 28k < Codex 32,768 B cap). What remains
is the durable <15k optimization (#533). The operator chose to build it rather than
re-scope the emergency label.

## Decisions Made

- **Decision:** Finish ADR-0.0.37 (build the durable cure) rather than re-scope #519 to a
  tracked optimization. **Rationale:** operator directive "for now, let's finish 0.0.37."
  **Rejected:** downgrade #519 emergency -> optimization (offered; operator chose build).
- **Decision:** The rules files (73% of the surface) need a SEPARATE CMS ADR; not folded
  into 0.0.37. **Rationale:** operator "we'll need more" — future scope.
- **Decision:** Author each scaffold OBPI before building it; never pipeline a scaffold-default
  brief. **Rationale:** the scaffolds have scaffold-default REQs and wrong allowed-paths;
  building from them is the slop class the operator rejected.
- **Decision:** `gz validate --setpoint-coherence` (OBPI-20) is NOT added to the default
  `gz check` scope. **Rationale:** a new always-on gate during recovery is a Tier-0-reopen
  surface; default-scope inclusion is a separate operator decision.
- **Decision (authored spec for OBPI-0.0.37-20, ready to write):** A Heavy-lane brief that
  delivers (a) a declared-setpoint accessor formalized on `vendors.py` (re-home
  `temperature_for`), and (b) a new fail-closed `gz validate --setpoint-coherence` scope.
  - **Allowed Paths:** `src/gzkit/content/vendors.py`;
    `src/gzkit/governance/trust_audits/setpoint_coherence.py` (NEW);
    `src/gzkit/cli/parser_maintenance.py`; `src/gzkit/commands/validate_cmd.py`;
    `data/vendor-manifest.json`; `tests/governance/test_setpoint_coherence.py` (NEW);
    `tests/content/test_vendors.py`; `features/setpoint_coherence.feature` (NEW) +
    `features/steps/setpoint_coherence_steps.py` (NEW); `docs/user/manpages/validate.md`;
    parent ADR package (evidence).
  - **REQs (with kind tags):**
    REQ-0.0.37-20-01 [BEHAVIOR] exit 3 when a `content_type_routes` (surface x consumer)
    pair has no setpoint in `content_type_temperatures`;
    REQ-0.0.37-20-02 [BEHAVIOR] exit 3 on an illegal setpoint token;
    REQ-0.0.37-20-03 [BEHAVIOR] exit 0 on a coherent manifest;
    REQ-0.0.37-20-04 [BEHAVIOR] the declared-setpoint accessor raises (fail-closed) on an
    undeclared pair;
    REQ-0.0.37-20-05 [SUPPORT] `docs/user/manpages/validate.md` documents the scope and it
    resolves — proof `gz validate --cli-alignment` + `artifact_edited` event.
  - **Coherence rule:** every (content_type x consumer) present in `content_type_routes`
    MUST have a legal setpoint in `content_type_temperatures`.
- **Decision:** Handoffs are audit artifacts, not scratch — do NOT bulk-delete (see
  Pending Work for the mechanical reasons + the recommended governed fix).

## Immediate Next Steps

Advisory only — present and obtain authorization before acting.

1. **Write OBPI-0.0.37-20's brief** from the authored spec in Decisions above, replacing
   the scaffold at
   `docs/design/adr/foundation/ADR-0.0.37-constitutional-invariant-composition/obpis/OBPI-0.0.37-20-setpoint-declaration-coherence-validator.md`.
   Read the file first (the Write tool requires it), quote the parent ADR Decision item
   verbatim in Implementation Summary (Discovery Order Pin), then run
   `uv run gz obpi validate --adr ADR-0.0.37 --authored` until it passes.
2. **Plan-audit then pipeline OBPI-20:** `uv run gz plan audit OBPI-0.0.37-20`, then
   `uv run gz obpi pipeline OBPI-0.0.37-20` (heavy -> BDD + docs + Gate 5 attestation by
   the operator). Build TDD: validator module + accessor + parser/dispatch wiring +
   manpage + behave scenario.
3. **Continue the chain** in order 23 -> 21 -> 22 -> 24 -> 25 -> 27 -> 10, authoring each
   scaffold before building (item 10 is already authored).
4. **Plan the corpus migration** (the hidden content work behind 21/22): extract the ~60
   binding rules into `.gzkit/invariants/` + populate the append-only corpus; this is what
   actually shrinks the surface once the composer (21) and playback (22) land.
5. **Decide the handoff-retention mechanism** (operator's second question) — see Pending
   Work; recommend a governed `gz` retention path rather than ad-hoc deletion.

## Pending Work / Open Loops

- **Hollow substrate:** corpus 895 B, registry 4/~60 entries. The composer (21) and
  playback (22) have nothing substantial to compress until the corpus migration runs.
- **CMS scope gap:** ADR-0.0.37 addresses AGENTS.md (22%) only; the `.claude/rules/*.md`
  surface (93,671 B, 73%) needs its own CMS ADR. Operator-acknowledged future work.
- **#519 framing:** acute exhaustion relieved (28k < 32k cap); the emergency label vs
  tracked-<15k-optimization question is deferred — operator chose to build the cure.
- **Handoff retention is unmanaged (operator's question).** Current count: **44** under
  `.gzkit/handoffs/` — adding is free. `tests/governance/test_handoff_migration.py`
  enforces a FLOOR (`_MIGRATION_BASELINE_FLOOR = 34`, `assertGreaterEqual`), NOT an exact
  count, so the store grows freely but cannot be deleted below 34 (loss of a migrated
  handoff is the regression it guards; the Snapshot-G exact-count pain drove this refactor).
  Two further delete-guards: `test_continues_from_chains_resolve` (cannot delete a handoff
  another's `continues_from` points to) and lock-handoff coupling (handoffs referenced by
  `obpi_lock_released` ledger events via `handoff_path` must persist — token-block-discipline
  / ADR-0.0.41). There is NO archive/retention command. Handoffs are NOT always-loaded
  context (they do not contribute to #519); stale ones are disk/ls clutter, not a context
  cost. **Recommendation:** do not bulk-delete or hand-move; author a governed retention
  mechanism (a `gz handoff archive` verb moving non-coupled, non-chain-referenced, older-
  than-N-day handoffs into `.gzkit/handoffs/archive/`, counting the archive toward the
  floor, preserving the audit trail) as its own GHI/OBPI.
- **Recurring Tier-0 offenders** (flagged in the dieted plan): Preflight orphan receipts
  and Task-envelope ceremony artifacts reopen Tier 0 most; fix-or-retire is a separate
  subtraction track.

## Verification Checklist

- [ ] Branch is `main`: `git branch --show-current`
- [ ] Tree clean + synced: `git status --short --branch` shows no ahead/behind
- [ ] Harness green: `uv run gz check` exits 0 (26/26)
- [ ] ADR state holds: `uv run gz adr status ADR-0.0.37` shows 11/19, item 20 pending/draft
- [ ] Reproduce the bill: `.claude/rules/*.md` total ~93.7k; `AGENTS.md` ~28.5k
- [ ] Substrate still hollow: `.gzkit/corpus/AGENTS.md.jsonl` ~895 B; `ls .gzkit/invariants/*.json` = 4
- [ ] Setpoint surface present: `content_type_temperatures` + `content_type_routes` in `data/vendor-manifest.json`

## Evidence / Artifacts

- `docs/governance/return-to-health-plan-2026-05-30.md` — dieted plan; Snapshot K; recurring-offender note
- `docs/design/adr/foundation/ADR-0.0.37-constitutional-invariant-composition/ADR-0.0.37-constitutional-invariant-composition.md` — parent ADR; Decision Re-Alignment point 2 (setpoint thermostat) is the OBPI-20 contract
- `docs/design/adr/foundation/ADR-0.0.37-constitutional-invariant-composition/obpis/OBPI-0.0.37-20-setpoint-declaration-coherence-validator.md` — the scaffold to author from the spec above
- `data/vendor-manifest.json` — `content_type_temperatures` setpoint store + `content_type_routes`
- `src/gzkit/content/vendors.py` — `temperature_for` accessor to re-home (fail-closed on undeclared)
- `src/gzkit/cli/parser_maintenance.py` — where `--setpoint-coherence` registers
- `src/gzkit/commands/validate_cmd.py` — scope -> audit-function dispatch
- `docs/user/manpages/validate.md` — manpage to extend (Gate 3)
- `tests/governance/test_handoff_migration.py` — the handoff-count tripwire (relevant to the retention question)
- `.claude/rules/token-block-discipline.md` — why lock-coupled handoffs are non-deletable audit artifacts
- `.gzkit/skills/gz-session-handoff/SKILL.md` — handoff CREATE/RESUME contract (programmatic API not yet implemented; author manually and gate via the handoff_validation module before committing)

## Environment State

Windows + Python 3.13 via `uv` (this clone); prior cross-machine work on macOS (the 61-commit
gap + the typecheck cross-platform false-red). `uv run gz check` is multi-minute (Test gate
dominates). Operator attribution: use the name `Jeffry Babb` only; never the personal email.
