# AUDIT — ADR-0.0.17 (ADR Taxonomy — Mechanical)

**Date:** 2026-04-21
**Auditor:** agent:claude-haiku-4-5
**Phase:** Completed → Validated

---

## Feature Demonstration

ADR-0.0.17 delivers mechanical enforcement of the `kind` (pool/foundation/feature) taxonomy across six surfaces. Each capability below was run against the live tree and the representative output is captured.

### 1. Schema-enforced `kind:` frontmatter on non-pool ADRs

**Command:**

```bash
head -9 docs/design/adr/foundation/ADR-0.0.17-adr-taxonomy-mechanical/ADR-0.0.17-adr-taxonomy-mechanical.md
```

**Observed:**

```text
---
id: ADR-0.0.17-adr-taxonomy-mechanical
status: Completed
semver: 0.0.17
lane: heavy
parent: GHI-218
date: 2026-04-18
kind: foundation
---
```

**Value:** The ADR's own frontmatter dogfoods the rule it introduced — `kind: foundation` is schema-validated on every non-pool ADR and round-trips cleanly under `validate_document`.

### 2. `gz plan create --kind` scaffolds by taxonomy

**Command:** `uv run gz plan create --help`

**Observed:**

```text
[--kind {pool,foundation,feature}] [--dry-run]
  --kind {pool,foundation,feature}
                        ADR taxonomy (required)
```

**Value:** Authoring-time guard. An operator scaffolding an ADR must declare taxonomy up front; the template writes the correct shape (foundation ⇒ `0.0.x` semver, feature ⇒ non-`0.0.x`, pool ⇒ no kind/semver frontmatter).

### 3. `gz adr promote --kind` gates pool → canonical

**Command:** `uv run gz adr promote --help`

**Observed:**

```text
--kind {pool,foundation,feature}
                        Target taxonomy: foundation (0.0.x) or feature
                        (0.y.z). pool rejected.
```

**Value:** Promotion from pool backlog is an explicit taxonomy commitment. Pool rejected as a target — once promoted, an ADR must be foundation or feature.

### 4. `gz validate --taxonomy` enforces kind/semver binding on the whole tree

**Command:** `uv run gz validate --taxonomy`

**Observed:**

```text
Validated: taxonomy

✓ All validations passed (1 scopes).
```

**Exit code:** 0 against the full canonical `docs/design/adr/**` tree (47 foundation ADRs, 43 feature ADRs, 66 pool ADRs).

**Value:** Every existing ADR in the repository satisfies the kind/semver binding (foundation ⇒ `0.0.x`, feature ⇒ non-`0.0.x`, pool ⇒ no kind/semver frontmatter) mechanically, not by hand-check.

### 5. AGENTS.md § Kinds documents the taxonomy (OBPI-06)

**Command:** `grep -n "^### Kinds" AGENTS.md`

**Observed:**

```text
220:### Kinds (pool, foundation, feature)
```

**Value:** The operator contract names all three kinds and cites the four mechanical enforcement surfaces above. Attestation rigor is keyed on `lane` (heavy ⇒ Gate 5), with foundation-kind ADRs following ADR-0.0.18 doctrine regardless of lane.

---

## Execution Log

| Check | Result | Evidence |
|---|---|---|
| C1 — audit-check ledger proof | ⚠ advisory gaps (tracked GHI #268) | `proofs/audit-check.txt`; coverage 40/47 (85.1%), 7 remaining all `severity: advisory` under OBPI-06 docs-only |
| C2 — `kind:` frontmatter | ✓ | `proofs/demo-kind-frontmatter.txt` |
| C3 — `plan create --kind` | ✓ | `proofs/demo-plan-create-help.txt` |
| C4 — `adr promote --kind` | ✓ | `proofs/demo-adr-promote-help.txt` |
| C5 — `validate --taxonomy` clean | ✓ exit 0 | `proofs/demo-validate-taxonomy.txt` |
| C6 — AGENTS.md § Kinds | ✓ line 220 | grep in this document |
| C7 — Unit tests | ✓ 3284 tests OK | receipt `arb-step-unittest-f70e17c0e19246a19100f85d0afdcc76` |
| C8 — Lint | ✓ | receipt `arb-ruff-2cf9c101520d4bd5985efac7a0ccf491` |
| C9 — Typecheck | ✓ | receipt `arb-step-typecheck-88d5f14ab11c440b90d0949580b7397a` |
| C10 — mkdocs --strict | ✓ | receipt `arb-step-mkdocs-3e1b2b3d9f444f809bcedcabe05be4a3` |
| C11 — Gates 1–5 | ✓ Gates 1–4 PASS; Gate 5 attested in ledger by Jeffry Babb 2026-04-20 | `proofs/gates.txt`; `.gzkit/ledger.jsonl` event `attested` |

---

## Evidence Index

- `proofs/audit-check.txt` — `gz adr audit-check` output
- `proofs/arb-ruff.txt`, `arb-typecheck.txt`, `arb-unittest.txt`, `arb-mkdocs.txt` — ARB receipt pointers
- `proofs/gates.txt` — Gate 1–5 summary
- `proofs/demo-*.txt` — Feature Demonstration captures

---

## Summary Table

| Dimension | Status | Note |
|---|---|---|
| Completeness | ✓ | 6/6 OBPIs attested_completed |
| Integrity | ✓ | All code-layer REQs covered; OBPI-06 docs-only gap tracked under GHI #268 |
| Alignment | ✓ | Code, schema, CLI, docs, and AGENTS.md all reference the same taxonomy contract |
| Value demonstrated | ✓ | All five mechanical surfaces run live with representative output above |

---

## Shortfalls

1. **Advisory `@covers` gap on OBPI-06 docs-only REQs (non-blocking).** Filed GHI #268 proposing severity-aware exit codes or a brief-level `tdd_derivation: n/a` marker. OBPI-06's brief explicitly declared "N/A for TDD"; evidence was grep + mkdocs --strict + sync-drift per the brief's declared verification model. Not a functional defect; a tooling-doctrine tension.

2. **REQ-0.0.17-05-07 undecorated (resolved in this audit).** Added `@covers("REQ-0.0.17-05-07")` to `test_validate_taxonomy_flag_clean_on_empty_tree` in `tests/commands/test_validate_cmds.py:450-451`. Coverage now 40/47 (85.1%).

No blocking shortfalls remain.

---

## Attestation

Agent signs: the audit above was executed against the live tree on 2026-04-21. All proof files are present under `proofs/`. Human attestation (Gate 5) was previously recorded in the ledger by Jeffry Babb on 2026-04-20 at OBPI closeout.

Per Layer 2 trust model, this audit consumed ledger proof from `attested` and `closeout_initiated` events rather than re-executing the human walkthrough.

---

## Receipts

- Lint: `arb-ruff-2cf9c101520d4bd5985efac7a0ccf491`
- Typecheck: `arb-step-typecheck-88d5f14ab11c440b90d0949580b7397a`
- Tests: `arb-step-unittest-f70e17c0e19246a19100f85d0afdcc76`
- Docs: `arb-step-mkdocs-3e1b2b3d9f444f809bcedcabe05be4a3`
- Ledger attestation: `.gzkit/ledger.jsonl` event `attested` ts `2026-04-20T00:39:27.482394+00:00`
