---
id: OBPI-0.0.36-01-agents-md-matrix-collapse
parent: ADR-0.0.36-universal-obpi-attestation
item: 1
lane: Heavy
status: Completed
---

# OBPI-0.0.36-01-agents-md-matrix-collapse: AGENTS.md Matrix Collapse

## ADR Item

- **Source ADR:** `docs/design/adr/foundation/ADR-0.0.36-universal-obpi-attestation/ADR-0.0.36-universal-obpi-attestation.md`
- **Checklist Item:** #1 — "AGENTS.md matrix collapse — replace Lane & Kind Attestation Matrix with universal-attestation binding rule; preserve lane/kind axes for gate-firing scope only"

**Status:** Completed

## Objective

Replace the four-row Lane & Kind Attestation Matrix in `AGENTS.md` § OBPI Acceptance Protocol with a single binding rule that brief-level human attestation is required for every OBPI completion regardless of parent kind or lane, while explicitly preserving the lane and kind axes for *which gates fire* (Gate 3 docs, Gate 4 BDD).

## Lane

**Heavy** — amends a foundation surface (`AGENTS.md`) consumed by every agent on every turn; binding-rule change to the OBPI Acceptance Protocol. Heavy under both ADR parent lane and the doctrine surface contract this OBPI lands.

## Allowed Paths

- `AGENTS.md` — primary doctrine surface where the matrix lives
- `src/gzkit/templates/agents.md` — generator template; AGENTS.md is the rendered output but the template is the canonical source of any rendered preamble
- `docs/AGENTS.md`, `src/AGENTS.md`, `src/gzkit/AGENTS.md`, `src/gzkit/chores/AGENTS.md`, `src/gzkit/cli/AGENTS.md`, `src/gzkit/commands/AGENTS.md`, `tests/AGENTS.md`, `docs/design/adr/AGENTS.md` — directory AGENTS.md mirrors regenerated by `gz agent sync control-surfaces`
- `tests/governance/test_agents_md_matrix.py` — new test module asserting matrix-collapse semantics and universal-attestation rule presence

## Denied Paths

- `src/gzkit/commands/adr_audit.py` — runtime gate is OBPI-0.0.36-02
- `src/gzkit/governance/trust_audits.py`, `src/gzkit/validate_pkg/` — validator scope is OBPI-0.0.36-03
- `data/historical_self_close_waivers.json` — waiver list is OBPI-0.0.36-04
- `.gzkit/skills/**/SKILL.md`, `.claude/rules/**`, `.gzkit/rules/**` — skill/rule prose sweep is OBPI-0.0.36-05
- New runtime dependencies; CI files; lockfiles
- Receipt schema files (touched by OBPI-03)

## Requirements (FAIL-CLOSED)

1. REQUIREMENT: The "Lane & Kind Attestation Matrix" four-row table in `AGENTS.md` § OBPI Acceptance Protocol MUST be removed. The phrase "Self-closeable after evidence" MUST NOT appear anywhere in `AGENTS.md` or any `*/AGENTS.md` mirror after this OBPI.
2. REQUIREMENT: A single binding rule MUST be present stating that brief-level human attestation is required for every OBPI completion regardless of parent kind or lane. The rule MUST use NEVER/ALWAYS language (e.g. "MUST always include human attestation").
3. REQUIREMENT: The lane and kind axes MUST be explicitly retained for gate-firing scope (Gate 3 docs, Gate 4 BDD) — the binding rule narrows ONLY the Gate 5 brief-level attestation column to universal. A reader of the amended section MUST NOT mistake this collapse for a removal of the lane/kind taxonomy itself.
4. REQUIREMENT: The amendment MUST cite GHI #342 and ADR-0.0.36-universal-obpi-attestation inline so future agents tracing the doctrine reach the source ADR via grep, not via narrative recall.
5. REQUIREMENT: After running `uv run gz agent sync control-surfaces`, every directory-level `AGENTS.md` mirror MUST reflect the amended canon. Stale mirror = OBPI failure.
6. REQUIREMENT: `tests/governance/test_agents_md_matrix.py` MUST assert (a) the deprecated phrase "Self-closeable after evidence" is absent from `AGENTS.md`, (b) the universal-attestation binding rule is present, (c) the lane/kind axes language for gate-firing scope is retained. Tests assert REQ-derived semantics, not byte-level string shape per `.gzkit/rules/tests.md`.

> STOP-on-BLOCKERS: if `AGENTS.md` is open in another editor or has uncommitted unrelated changes, halt before modifying.

## Discovery Checklist

**Parent ADR (read first; order pinned — GHI #321):**

- [ ] **Parent ADR § Decision item #1 — quote verbatim into Implementation Summary** (the AGENTS.md matrix collapse binding rule). The Decision item is the contract.
- [ ] Parent ADR § Intent — operator's verbatim "ABANDON that idea" course correction context.
- [ ] Parent ADR file: `docs/design/adr/foundation/ADR-0.0.36-universal-obpi-attestation/ADR-0.0.36-universal-obpi-attestation.md`

> **STOP:** If you cannot quote the parent ADR § Decision item #1 that this OBPI implements, STOP and re-read.

**Governance (read once, cache):**

- [ ] `.gzkit/rules/skill-surface-sync.md` — version-bump discipline for any rule/canon change
- [ ] `.claude/rules/gate5-runbook-code-covenant.md` — runbook tracks behavior change

**Context:**

- [ ] `AGENTS.md` § OBPI Acceptance Protocol — current text including the matrix table (lines around the "Lane & Kind Attestation Matrix" heading)
- [ ] ADR-0.0.18 (`docs/design/adr/foundation/ADR-0.0.18-adr-taxonomy-doctrine/ADR-0.0.18-adr-taxonomy-doctrine.md`) — supplies the kind/lane taxonomy this collapse preserves for gate-firing scope
- [ ] GHI #332 audit findings — the deprecated state shapes that motivate the collapse

**Prerequisites (check existence, STOP if missing):**

- [ ] `AGENTS.md` exists
- [ ] `src/gzkit/templates/agents.md` exists (template generator)
- [ ] All directory AGENTS.md mirrors exist under their respective directories (regenerated by `gz agent sync control-surfaces`)
- [ ] Parent ADR file exists at the path above

**Existing Code (understand current state):**

- [ ] `tests/governance/` directory layout reviewed for adjacent test patterns (look at `tests/governance/test_advisory_scorecard.py` or similar for AGENTS.md-asserting tests)
- [ ] Sync flow reviewed: `src/gzkit/commands/sync.py` and `src/gzkit/sync_surfaces.py` to confirm AGENTS.md propagation path

## Quality Gates

### Gate 1: ADR

- [ ] Intent and scope recorded in this OBPI brief
- [ ] Parent ADR Decision item #1 quoted in Implementation Summary

### Gate 2: TDD (Red-Green-Refactor)

- [ ] RED: `tests/governance/test_agents_md_matrix.py::test_lane_and_kind_attestation_matrix_is_collapsed` fails before edit
- [ ] GREEN: same test passes after `AGENTS.md` edit + sync
- [ ] Tests pass: `uv run gz test`
- [ ] Validation commands recorded in evidence with real outputs

### Code Quality

- [ ] Lint clean: `uv run gz lint`
- [ ] Type check clean: `uv run gz typecheck`

### Gate 3: Docs (Heavy)

- [ ] Docs build: `uv run mkdocs build --strict`
- [ ] If runbook prescribes attestation flow, runbook updated to reflect universal attestation

### Gate 4: BDD (Heavy)

- [ ] Behave scenario tagged `@REQ-0.0.36-01-NN` asserting AGENTS.md doctrine surface absence of self-close language; scenarios pass: `uv run -m behave features/`

### Gate 5: Human (Universal under this very ADR)

- [ ] Human attestation recorded with TTY+ATTEST under `gz obpi complete`

## Verification

```bash
# Doctrine surface assertions (semantic, not string-shape)
uv run -m unittest tests/governance/test_agents_md_matrix.py -v

# Mirror propagation
uv run gz agent sync control-surfaces
git diff --name-only -- '*AGENTS.md' | sort

# Standard quality gates
uv run gz lint
uv run gz typecheck
uv run gz test
uv run mkdocs build --strict

# ARB receipts for Heavy-lane attestation
uv run gz arb ruff
uv run gz arb typecheck
uv run gz arb step --name unittest -- uv run -m unittest -q
uv run gz arb step --name mkdocs -- uv run mkdocs build --strict
```

## Acceptance Criteria

- [ ] REQ-0.0.36-01-01: Given `AGENTS.md` after this OBPI, when grep searches for "Self-closeable after evidence" or "Self-closeable", then zero matches are returned across `AGENTS.md` and every `**/AGENTS.md` mirror.
- [ ] REQ-0.0.36-01-02: Given `AGENTS.md` § OBPI Acceptance Protocol after this OBPI, when read, then a single binding rule MUST be present asserting universal brief-level human attestation regardless of parent kind or lane, with NEVER/ALWAYS language.
- [ ] REQ-0.0.36-01-03: Given `AGENTS.md` § OBPI Acceptance Protocol after this OBPI, when read, then the lane and kind axes are explicitly retained for gate-firing scope (Gate 3 docs, Gate 4 BDD) — the collapse narrows only the Gate 5 attestation column.
- [ ] REQ-0.0.36-01-04: Given the amended doctrine, when an agent traces backwards from the rule to its source, then GHI #342 and ADR-0.0.36-universal-obpi-attestation are cited inline.
- [ ] REQ-0.0.36-01-05: Given `tests/governance/test_agents_md_matrix.py`, when run, then it asserts the three semantics above (absence of deprecated phrase, presence of universal rule, retention of lane/kind axes) — not byte-level string shape.

## Completion Checklist

- [ ] **Gate 1 (ADR):** Intent recorded; Decision item #1 quoted in Implementation Summary
- [ ] **Gate 2 (TDD):** RGR cycle followed; tests assert REQ-derived semantics
- [ ] **Code Quality:** Lint, format, type checks clean
- [ ] **Gate 3 (Docs):** mkdocs --strict clean
- [ ] **Gate 4 (BDD):** behave scenarios tagged + passing
- [ ] **Gate 5 (Human):** TTY+ATTEST attestation recorded
- [ ] **Value Narrative:** Documented below
- [ ] **Key Proof:** Concrete grep + test output below

> Universal attestation rule applies under ADR-0.0.36; Gate 5 fires regardless of lane.

## Evidence

### Gate 1 (ADR)

- [ ] Intent and scope recorded

### Gate 2 (TDD — Red-Green-Refactor)

```text
# Paste RED + GREEN test output here
```

### Code Quality

```text
# Paste lint/format/type check output here
```

### Gate 3 (Docs)

```text
# Paste mkdocs --strict output here
```

### Gate 4 (BDD)

```text
# Paste behave output here
```

### Gate 5 (Human)

```text
# Record attestation text + TTY+ATTEST receipt here
```

### Value Narrative

Before this OBPI, `AGENTS.md` § OBPI Acceptance Protocol carried a four-row matrix one of whose cells permitted feature × lite OBPIs to self-close after evidence — the structural cause of the GHI #332 deprecated state shapes. After this OBPI, the matrix is replaced by a single binding rule asserting universal brief-level attestation; the doctrine surface no longer permits the cell that downstream surfaces rationalized into existence.

### Key Proof


```bash
# Before: deprecated matrix cell present
$ rg "Self-closeable after evidence" AGENTS.md
AGENTS.md:264:| `feature`    | `lite`  | absent     | Self-closeable after evidence | — |

# After: zero matches across all AGENTS.md files
$ rg "Self-closeable after evidence" --glob "**/AGENTS.md"
$ echo $?
1

# New universal binding rule present in AGENTS.md
$ rg "ALWAYS required for every OBPI completion" AGENTS.md
AGENTS.md:256:**Brief-level human attestation is ALWAYS required for every OBPI completion, regardless
```

ARB receipts:
- arb-ruff-d5242753decd4425a3b2891ef60c34d6 (lint clean)
- arb-step-typecheck-45e467920c454a42b44c417f8bced516 (typecheck clean)
- arb-step-unittest-2d8ae16947da4130889794edbb8c1864 (5260/5260 pass)
- arb-step-mkdocs-faf17a5646704eb8a5e6a21938a54fbd (docs build clean)

BDD: 5/5 scenarios pass on features/universal_obpi_attestation.feature (REQ-01..05)
@covers parity: 5/5 REQs covered (uncovered_reqs: 0 via `gz covers OBPI-0.0.36-01-agents-md-matrix-collapse --json`)

### Implementation Summary


- Files modified: `AGENTS.md` (matrix collapsed to Universal OBPI Attestation section), `src/gzkit/templates/agents.md` and `.gzkit/templates/agents.md` (canonical template aligned), all `**/AGENTS.md` directory mirrors (propagated by `gz agent sync control-surfaces`)
- Files created: `tests/governance/test_agents_md_matrix.py` (5 unit tests covering REQ-01..05), `features/universal_obpi_attestation.feature` (5 BDD scenarios tagged @REQ-0.0.36-01-01..05)
- Coupled-surface fixes: `tests/test_adr_audit_predicates.py` and `tests/governance/test_security_sensitivity_rule.py` (REQ-0.0.22-04-06, REQ-0.0.22-06-03 updated to assert the new Universal OBPI Attestation section instead of the collapsed matrix); `features/steps/gz_steps.py` (added `Then the file "{path}" does not contain "{text}"` step)
- Tests added: 5 unit + 5 BDD = 10 REQ-derived assertions; semantic checks, not byte-level
- Date completed: 2026-05-17
- Attestation status: operator-verbatim conversational attestation received Stage 4 (universal under ADR-0.0.36)
- Defects noted: none

## Tracked Defects

_No defects tracked._

## Human Attestation

- Attestor: `Jeffry Babb`
- Attestation: attest completed — matrix collapse landed: AGENTS.md § OBPI Acceptance Protocol replaces the eight-row Lane & Kind & Sensitivity Attestation Matrix with the Universal OBPI Attestation section binding human attestation for every OBPI completion regardless of kind or lane. Verified by 5 unit tests (test_agents_md_matrix.py, receipt arb-step-unittest-2d8ae16947da4130889794edbb8c1864 — 5260/5260 pass), 5 @REQ-0.0.36-01-01..05 BDD scenarios (features/universal_obpi_attestation.feature, 5/5 pass), GHI #342 and ADR-0.0.36 cited inline for grep traceability, all AGENTS.md mirrors propagated via `gz agent sync control-surfaces`. Receipts: arb-ruff-d5242753decd4425a3b2891ef60c34d6, arb-step-typecheck-45e467920c454a42b44c417f8bced516, arb-step-mkdocs-faf17a5646704eb8a5e6a21938a54fbd.
- Date: 2026-05-17

---

**Brief Status:** Draft

**Date Completed:** 2026-05-17

**Evidence Hash:** -
