---
mode: CREATE
adr_id: ADR-0.0.37-constitutional-invariant-composition
branch: main
timestamp: "2026-05-20T08:12:29Z"
agent: claude-code
obpi_id: OBPI-0.0.37-05-brief-reconcile-engine
session_id:
continues_from:
---

<!-- Handoff document for ADR-0.0.37 — OBPI-05 complete; OBPI-06 through -10 remain -->

## Current State Summary

OBPI-0.0.37-05 (brief reconciliation engine) pipeline is **fully complete**. All 6
Completion Contract items satisfied: brief Completed + attested, lock released,
markers cleaned, git-sync #1 committed (SHA: `b316e52cea5a4789d433fe5e7719a5c88d226e63`,
pushed to origin/main), `gz obpi reconcile` PASS, git-sync #2 clean. The brief is now
`status: Completed` / `attested_completed`.

ADR-0.0.37 overall: OBPI-01/02/03/04/05 are Completed. OBPI-06 through -10 remain.

**Commit in scope** (`b316e52`): OBPI-05 implementation + GHI #503 skill-staleness fix
(10 skills `last_reviewed` bumped 2026-02-18→2026-05-20 after genuine re-review, all verbs confirmed) +
AGENTS.md bullet-retention fix (#58 invariant-coherence bullet + #59 brief-reconcile bullet added
to "### Mechanical scopes that bind here").

## Important Context

**Option B escalation policy (ADR-0.0.37-05 design decision):** `validate_brief_reconcile`
escalates drift to ERROR only for structured `BriefStructure` briefs. The 700 legacy briefs
(701 total) are walked but not escalated — honoring OBPI-04's permissive-mode deprecation
window. This narrows REQ-07's literal "any brief" to "any structured brief." Implementation
Summary in the OBPI-05 brief records this; no GHI filed for REQ-07 text (documented in Layer-1).

**GHI #504 (open blocker — unrelated to OBPI-05):** `gz governance render --target agents-md`
emits unsubstituted `{project_name}` / `{project_purpose}` / `{tech_stack}` placeholders.
This causes `gz validate --invariant-coherence` to exit 3 → `gz check` repo-wide red.
Root: OBPI-0.0.37-02 composition renderer template-variable substitution broken.
Fix: examine `src/gzkit/governance/compose.py` variable-binding; direct-fix candidate (≤10 lines).
GHI #504 is open with a blocker comment naming the fix path.

**GHI #503 (closed, fixed):** 10 skills hit 90-day `last_reviewed` calendar staleness on
2026-05-20 tick. Fixed in commit `b316e52` — `last_reviewed` bumped after genuine re-review;
all verbs confirmed. Closed citing the commit SHA.

**OBPI-05 `missing_in_brief` neighborhood filter:** The engine only reports `missing_in_brief`
for src/ files sharing a parent directory with an allowlisted src/ path, excluding cross-cutting
test-utility imports. Documented in `src/gzkit/governance/brief_reconcile.py` docstring.

**bullet-retention #58 was pre-existing drift** from OBPI-03 (the invariant-coherence Mechanical
bullet was never added to AGENTS.md). Fixed in-session by adding both #58 and #59 bullets to
AGENTS.md "### Mechanical scopes that bind here".

**`@covers` decorators must be at METHOD level**, not class level — the `_iter_test_functions`
AST scanner only maps class-level decorators to the file path (not `ClassName.method`), producing
a garbage unittest target that fails the REQ-coverage gate in `gz obpi complete`.

## Decisions Made

- **Option B validator escalation:** `validate_brief_reconcile` only escalates structured `BriefStructure`
  briefs; legacy LegacyBriefShape briefs skipped. **Rationale:** 701 briefs, only 1 structured;
  legacy corpus produces ~950 raw delta false-positives; honor OBPI-04 permissive mode.
  **Alternatives rejected:** status-gate `missing_on_disk` only (still left 600 non-allowlist drifts);
  walk-all-enforce-all (irreconcilable with "REQ-07 OK on clean tree" Verification command).

- **`missing_in_brief` neighborhood filter:** Only report src/ files in the same parent-dir neighborhood
  as an allowlisted src/ path. **Rationale:** literal "any imported src/ file" flags `gzkit.traceability.covers`
  (universal test-utility import) as a false positive. **Alternative rejected:** hardcoded exclusion of
  specific modules (arbitrary).

- **GHI #503 resolved in-session by genuine re-review:** operator chose "Fix #503 now, then finish OBPI-05."
  10 skills re-reviewed (verbs confirmed, workflows coherent), `last_reviewed` bumped, `gz agent sync`
  run. The OBPI-05 + skill-fix changes landed in the same commit.

- **GHI #504 deferred:** invariant-coherence renderer placeholder bug is in OBPI-02 scope and requires
  separate investigation of `src/gzkit/governance/compose.py`. Not fixed in-session.

## Immediate Next Steps

1. **Fix GHI #504 first** — examine `src/gzkit/governance/compose.py` template variable-binding.
   The renderer emits literal `{project_name}` etc. tokens. `fix(compose): populate template variables
   in governance render (GHI #504)`. This unblocks `gz check` and `gz validate --invariant-coherence`.

2. **Begin OBPI-0.0.37-06** (`gz brief reconcile` CLI verb) — run `/gz-obpi-pipeline OBPI-0.0.37-06`.
   The brief is at `docs/design/adr/foundation/ADR-0.0.37-constitutional-invariant-composition/obpis/OBPI-0.0.37-06-brief-reconcile-cli.md`.
   The engine (`reconcile_brief`) is already implemented; OBPI-06 adds the operator-runnable CLI surface
   and the ledger event emission (`brief_reconciled`, `brief_reconcile_drift_detected`).

3. **Check OBPI-06 brief status** — run `uv run gz obpi validate --authored ...OBPI-0.0.37-06-brief-reconcile-cli.md`
   to confirm it passes authored-readiness before starting the pipeline.

4. After OBPI-06: run OBPI-07 (pipeline Stage 1 fail-close gate) and OBPI-08 (`gz obpi complete`
   fail-close gate) — these depend on OBPI-05's `reconcile_brief` and OBPI-06's `brief_reconciled`
   ledger event.

5. After OBPI-07/08: OBPI-09 (AGENTS.md migration) and OBPI-10 (doctrine refresh) — OBPI-09
   depends on OBPI-03's composition renderer being fixed (GHI #504 must be resolved first).

## Pending Work / Open Loops

- **GHI #504** (OPEN): `gz governance render` placeholder bug → `gz check` exit 3. Must be fixed
  before OBPI-09 (AGENTS.md migration) can run successfully. Direct-fix candidate in
  `src/gzkit/governance/compose.py`.

- **REQ-07 wording refinement** (deferred, documented only): OBPI-05 brief REQ-07 says "walks all
  OBPI briefs" but the implementation is structured-briefs-only (Option B). Documented in
  OBPI-05 Implementation Summary. No GHI filed; operator attested seeing the deviation.

- **Legacy-brief migration** (no OBPI yet): The 700 legacy briefs need `allowlist/reqs/verification`
  structured frontmatter for `validate_brief_reconcile` to enforce on them. Not tracked in any
  OBPI — forward dependency noted in OBPI-05 Implementation Summary and advisory-rules-audit
  scorecard #59.

- **OBPI-06 through -10** (planned): see sequencing in ADR-0.0.37 Decision section.

## Verification Checklist

- [ ] `uv run -m unittest -q` passes (5394 tests, no failures)
- [ ] `uv run gz validate --brief-reconcile` exits 0
- [ ] `uv run gz validate --bullet-retention` exits 0
- [ ] `git status --short | wc -l` → 0 (clean working tree)
- [ ] `git log -1 --format="%H %s"` → `b316e52` (OBPI-05 sync commit)
- [ ] `git rev-list --count origin/main..main` → 0 (fully pushed)
- [ ] `uv run gz obpi reconcile OBPI-0.0.37-05-brief-reconcile-engine` → PASS
- [ ] `uv run gz validate --invariant-coherence` exits 3 (GHI #504 pre-existing renderer bug — expected until fixed)

## Evidence / Artifacts

- `src/gzkit/governance/brief_reconcile.py` — pure reconcile engine (363 lines; ReconcileResult, 5 delta models, reconcile_brief, neighborhood-filtered missing_in_brief)
- `src/gzkit/governance/trust_audits/brief_reconcile.py` — validate_brief_reconcile validator wrapper (structured-brief-only escalation)
- `src/gzkit/governance/trust_audits/__init__.py` — validate_brief_reconcile imported + re-exported
- `tests/governance/test_brief_reconcile.py` — 17 REQ-derived tests (method-level @covers; 7/7 REQs covered)
- `tests/fixtures/brief_reconcile/` — 6 fixture briefs (passing, allowlist_drift, discovery_drift, verb_drift, req_count_drift, citation_drift)
- `features/brief_reconcile.feature` — 16 @wip BDD scenarios tagged @REQ-0.0.37-05-*
- `src/gzkit/cli/parser_maintenance.py` — --brief-reconcile flag added
- `src/gzkit/commands/validate_cmd.py` — brief_reconcile scope wired + in _POLICY_BREACH_ERROR_TYPES
- `docs/governance/advisory-rules-audit.md` — scorecard #59 (Mechanical); Mechanical 40→41
- `docs/design/adr/foundation/ADR-0.0.37-constitutional-invariant-composition/obpis/OBPI-0.0.37-05-brief-reconcile-engine.md` — status: Completed, attested 2026-05-20
- `.gzkit/skills/gz-adr-map/SKILL.md` — last_reviewed bumped (GHI #503, re-reviewed 2026-05-20)
- `.gzkit/skills/gz-check-config-paths/SKILL.md` — last_reviewed bumped (GHI #503)
- `.gzkit/skills/gz-cli-audit/SKILL.md` — last_reviewed bumped (GHI #503)
- `.gzkit/skills/gz-constitute/SKILL.md` — last_reviewed bumped (GHI #503)
- `.gzkit/skills/gz-implement/SKILL.md` — last_reviewed bumped (GHI #503)
- `.gzkit/skills/gz-migrate-semver/SKILL.md` — last_reviewed bumped (GHI #503)
- `.gzkit/skills/gz-prd/SKILL.md` — last_reviewed bumped (GHI #503)
- `.gzkit/skills/gz-state/SKILL.md` — last_reviewed bumped (GHI #503)
- `.gzkit/skills/gz-status/SKILL.md` — last_reviewed bumped (GHI #503)
- `.gzkit/skills/gz-validate/SKILL.md` — last_reviewed bumped (GHI #503)
