# AUDIT — ADR-0.0.27 Exemplar-Corpus Doctrine

| Field | Value |
|-------|-------|
| ADR ID | ADR-0.0.27-exemplar-corpus-doctrine |
| ADR Title | Exemplar-Corpus Doctrine |
| Kind / Lane | foundation / heavy |
| ADR Dir | docs/design/adr/foundation/ADR-0.0.27-exemplar-corpus-doctrine |
| Audit Date | 2026-05-05 |
| Auditor(s) | agent (Claude Opus 4.7) drafting; operator attesting |

## Feature Demonstration (Step 3 — MANDATORY)

**What does ADR-0.0.27 deliver?**

- A binding selection methodology for the exemplar corpus and its mechanical scorecard entry (rule + advisory-rules-audit) — empirical grounding for downstream complexity doctrine, not authority-citation alone.
- An operator-pinned 13-project corpus across all ten archetypal cells, SHA-frozen and Pydantic-validated; corpus inclusion is a *learning relationship*, not a dependency adoption.
- A reproducible measurement pipeline producing a dated, byte-deterministic baseline artifact under `docs/governance/complexity/baselines/{date}/`.
- A first dated distilled-characteristics document (`2026-05-04`) that downstream foundation ADRs cite — the doctrine that *ships*, not the corpus or raw distributions.
- A frozen citation contract (`Citation` Pydantic model + JSON schema mirror) with the percentile + absolute-number pairing rule that makes citations refresh-portable.
- A canonical `gz-complexity-distill` skill carrying the corpus list, methodology rationale, and the three trigger types (annual / drift > 25% / operator judgment).
- A fail-closed `gz validate --complexity-doctrine-links` validator scope that closes the 2am-Scenario-2 failure mode (advisor diagnosis pointing at a missing or stale citation).

### Capability 1: Link-integrity validator runs fail-closed (OBPI-07)

```bash
$ uv run gz validate --complexity-doctrine-links
Validated: complexity_doctrine_links

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

**Why it matters:** The validator is the load-bearing structural guard against the 2am-Scenario-2 failure mode — an operator following an advisor diagnosis to a referenced doctrine document that no longer exists. Today (no citing ADRs landed yet) it runs clean; the moment ADR-0.0.28 / 0.0.29 / 0.0.30 cite a missing or stale distilled-characteristics file, the validator exits 3 and surfaces the defect at next operator session. This is the doctrine's mechanical defense, not just its prose.

### Capability 2: Layer-2 ledger proof aggregates 7/7 OBPIs at 100% REQ coverage (audit-check)

```bash
$ uv run gz adr audit-check ADR-0.0.27
ADR audit-check: ADR-0.0.27-exemplar-corpus-doctrine
PASS All linked OBPIs are completed with evidence.
  - OBPI-0.0.27-01-selection-methodology
  - OBPI-0.0.27-02-initial-corpus-authoring
  - OBPI-0.0.27-03-measurement-pipeline
  - OBPI-0.0.27-04-distillation-pass
  - OBPI-0.0.27-05-citation-contract
  - OBPI-0.0.27-06-distill-skill
  - OBPI-0.0.27-07-link-integrity-validator

Coverage: 50/50 REQs covered (100.0%)
```

**Why it matters:** This is the Layer-2 trust contract working: every REQ enumerated across the 7 briefs has a covering test, every brief has agent-relayed-operator-attestation Layer-1 proof in `obpi-audit.jsonl`, and the audit-check aggregator confirms the chain at the ADR level without re-running unit verification. The ledger is the source of truth, not the YAML frontmatter.

### Capability 3: Corpus is operator-pinned, SHA-frozen, and diverse (OBPI-02)

```bash
$ uv run python -c "import json,pathlib;\
  p=json.loads(pathlib.Path('data/exemplar_corpus.json').read_text())['projects'];\
  print(f'Projects: {len(p)}');\
  print(f'Cells covered: {sorted({x[chr(34)+chr(97)+chr(114)+chr(99)+chr(104)+chr(101)+chr(116)+chr(121)+chr(112)+chr(97)+chr(108)+chr(95)+chr(99)+chr(101)+chr(108)+chr(108)+chr(34)] for x in p})}');\
  print(f'All SHAs are 40-char hex: {all(len(x[chr(34)+chr(99)+chr(111)+chr(109)+chr(109)+chr(105)+chr(116)+chr(95)+chr(115)+chr(104)+chr(97)+chr(34)])==40 for x in p)}')"
Projects: 13
Archetypal cells covered: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
All SHAs are 40-char hex: True
```

**Why it matters:** The corpus is what the methodology is *for*. Thirteen projects covering every archetypal cell, every project pinned to a 40-character commit SHA — the doctrine is calibrated against an empirical anchor, not training-corpus pattern-matching. The 13/15 size sits inside the methodology's stated 12-15 target with two cells available for amendment under OBPI-01 protocol.

### Capability 4: Measurement pipeline produced a dated baseline (OBPI-03) and distilled-characteristics document (OBPI-04)

```bash
$ ls docs/governance/complexity/baselines/2026-05-04/
baseline.json
baseline.summary.md

$ ls docs/governance/complexity/distilled-characteristics-2026-05-04.md
docs/governance/complexity/distilled-characteristics-2026-05-04.md
```

**Why it matters:** The distilled-characteristics document is what downstream foundation ADRs (0.0.28 threshold, 0.0.29 advisor, 0.0.30 authoring guidance) will *cite*. Raw distributions live in `baselines/{date}/`; the doctrine ships in the dated `distilled-characteristics-{date}.md`. Previous documents are preserved (never overwritten) so doctrine evolution has a permanent audit trail. The 2026-05-04 file establishes the baseline; first-run cold-start has no prior-distillation diff, by design.

### Capability 5: Distill skill is canonical and vendor-mirrored (OBPI-06)

```bash
$ ls .gzkit/skills/gz-complexity-distill/ .claude/skills/gz-complexity-distill/
.gzkit/skills/gz-complexity-distill/:  SKILL.md
.claude/skills/gz-complexity-distill/: SKILL.md
```

**Why it matters:** The skill is the operator's surface for ad-hoc, calendar-triggered, and signal-triggered re-distillation. Canonical edit lives at `.gzkit/skills/`; vendor mirrors are sync outputs per `skill-surface-sync.md` Rule #4 (the GHI #400 amendment that landed in OBPI-06). Three trigger types (annual, drift > 25% with 6-month minimum, operator judgment for ground-breaking projects) are documented in the skill body.

### Capability 6: Advisory scorecard recognizes the new rule as Mechanical (OBPI-01)

```bash
$ uv run gz validate --advisory-scorecard
Validated: advisory_scorecard
✓ All validations passed (1 scopes).
```

**Why it matters:** The new `.gzkit/rules/complexity-doctrine.md` was added to `docs/governance/advisory-rules-audit.md` and classified Mechanical at scorecard authoring time. The validator confirms the scorecard surface is intact — every rule under `.gzkit/rules/` has a scorecard entry. This is the rule-discoverability invariant working.

### Value Summary

Before ADR-0.0.27, gzkit had no empirical anchor for the numeric thresholds, classifier boundaries, and refactor recommendations its complexity advisor cluster (ADRs 0.0.28/0.0.29/0.0.30) is going to ship — pattern-matching from training memory was the only path. After ADR-0.0.27: an operator-curated 13-project corpus, a deterministic measurement pipeline, a dated distilled-characteristics document downstream ADRs cite, a frozen citation contract, an operator-runnable distill skill on three trigger types, and a fail-closed link-integrity validator. The MAKE LLM STOCHASTIC VIBES INERT mantra now has its meta-foundation.

---

## Execution Log

| Check | Command / Method | Result | Notes |
|-------|------------------|--------|-------|
| Layer-2 ledger proof aggregation | `uv run gz adr audit-check ADR-0.0.27 --json` | ✓ | `passed: true`; 7/7 OBPIs; 50/50 REQs; `audit/proofs/audit-check.json` |
| New validator scope wired | `uv run gz validate --complexity-doctrine-links` | ✓ | Exit 0; `audit/proofs/validate-complexity-doctrine-links.txt` |
| Advisory scorecard entry honored | `uv run gz validate --advisory-scorecard` | ✓ | Exit 0; `audit/proofs/advisory-scorecard.txt` |
| Pinned corpus shape | `python` inspector against `data/exemplar_corpus.json` | ✓ | 13 projects; all 10 cells covered; all SHAs 40-char hex; `audit/proofs/corpus-shape.txt`, `audit/proofs/corpus-summary.txt` |
| Baseline artifacts present | `ls docs/governance/complexity/baselines/2026-05-04/` | ✓ | `baseline.json`, `baseline.summary.md`; `audit/proofs/baseline-listing.txt` |
| Distilled-characteristics document present | `ls docs/governance/complexity/` | ✓ | `distilled-characteristics-2026-05-04.md` present; `audit/proofs/governance-complexity-tree.txt` |
| Distill skill present + synced | `ls .gzkit/skills/gz-complexity-distill/` + `.claude/skills/gz-complexity-distill/` | ✓ | `SKILL.md` in both; canonical-and-mirror discipline; `audit/proofs/distill-skill-listing.txt` |
| Heavy-lane gate aggregate | `uv run gz gates --adr ADR-0.0.27` | ✓ | Gate 1 ADR PASS, Gate 4 BDD PASS (29 features / 200 scenarios / 1058 steps), Gate 5 PENDING manual; `audit/proofs/gates.txt` |
| CLI cross-coverage | `uv run gz cli audit` | ✓ | "CLI audit passed. Cross-coverage: 91/91 commands fully covered." |
| Closeout readiness preview | `uv run gz closeout ADR-0.0.27 --dry-run` | ✓ | 7/7 OBPI complete; proof FOUND for every brief; defense-brief preview rendered; `audit/proofs/closeout-dry-run.txt` |
| Pre-attestation lifecycle | `uv run gz adr report 0.0.27` | ✓ | Lifecycle: Pending; Closeout: READY; QC: PENDING (Gate 5); `audit/proofs/adr-report-pre.txt` |
| Post-attestation lifecycle | `uv run gz adr report 0.0.27` after receipt emit | ✓ | Lifecycle: Validated; Closeout: READY; QC: READY; `audit/proofs/adr-report-post.txt` |

## Dataset Spot Examples

```text
# audit-check.json (excerpt)
{
  "adr": "ADR-0.0.27-exemplar-corpus-doctrine",
  "passed": true,
  "checked_obpis": [<7 items>],
  "complete_obpis": [<7 items>],
  "findings": [],
  "coverage": {
    "total_reqs": 50,
    "covered_reqs": 50,
    "uncovered_reqs": 0,
    "coverage_percent": 100.0
  }
}
```

```text
# Pre-attestation lifecycle table
ADR-0.0.27 │ heavy │ Pending │ pre_closeout │ 7/7 │ READY │ PENDING
```

## Summary Table

| Aspect | Status |
|--------|--------|
| Implementation Completeness | ✓ All 7 OBPIs attested-completed; 1:1 with ADR Feature Checklist |
| Data Integrity | ✓ Corpus 13/13 SHA-pinned; ledger proof intact; coverage 50/50 |
| Performance Stability | ✓ Measurement pipeline byte-deterministic per OBPI-03 attestation |
| Documentation Alignment | ✓ Rule, scorecard, skill, AGENTS notes, mkdocs strict clean |
| Risk Items Resolved | ✓ Demerit-lesson, contamination, cold-start, vendor-mirror drift each addressed in OBPI attestations |

## Evidence Index

Proof logs co-located under `audit/proofs/`:

- `audit/proofs/audit-check.json` — Layer-2 ledger-proof aggregator JSON
- `audit/proofs/validate-complexity-doctrine-links.txt` — OBPI-07 validator scope
- `audit/proofs/advisory-scorecard.txt` — OBPI-01 scorecard entry
- `audit/proofs/corpus-summary.txt` — OBPI-02 corpus name + SHA spot-sample
- `audit/proofs/corpus-shape.txt` — OBPI-02 cell-coverage + SHA-shape proof
- `audit/proofs/baseline-listing.txt` — OBPI-03 baseline artifacts
- `audit/proofs/governance-complexity-tree.txt` — OBPI-02/03/04 governance/complexity tree
- `audit/proofs/distill-skill-listing.txt` — OBPI-06 skill canonical listing
- `audit/proofs/gates.txt` — Heavy-lane gate aggregate
- `audit/proofs/closeout-dry-run.txt` — Closeout-readiness preview
- `audit/proofs/adr-report-pre.txt` — Pre-attestation lifecycle table

Layer-1 OBPI proof (inherited, not re-captured): `docs/design/adr/foundation/ADR-0.0.27-exemplar-corpus-doctrine/logs/obpi-audit.jsonl` (7 attestation records, ARB receipts cited inline per record).

## Recommendations

- **No blocking issues found.** All planned checks passed; defense-brief preview shows proof FOUND for every brief; CLI cross-coverage 91/91; lifecycle ready for the agent-relayed Gate-5 receipt.
- **Non-blocking finding (post-attestation follow-up):** `uv run gz arb step --name mkdocs -- uv run mkdocs build --strict` surfaces an INFO-level anchor miss — `docs/user/runbook.md` links to `commands/validate.md#--complexity-doctrine-links` but `docs/user/commands/validate.md` lacks that anchor. Strict build still exits 0 (mkdocs downgrades anchor-miss to INFO), so this does not block the Gate-5 receipt, but it is a real coupled-surface defect from OBPI-07's `--complexity-doctrine-links` flag landing without the corresponding anchor in command docs. Routes to direct-fix per AGENTS.md § Defect-fix routing (≤10-line, single-file, high `fix(...)` precedent). Tracked as immediate post-ceremony follow-up.
- **Forward-watch:** when ADRs 0.0.28 / 0.0.29 / 0.0.30 land and begin citing the `2026-05-04` distilled-characteristics document, re-run `gz validate --complexity-doctrine-links` to confirm exit-3 contract still fires fail-closed against any future drift. Tracked structurally by the validator scope itself; not an action item for this audit.

## Attestation

I/we attest that ADR-0.0.27 (Exemplar-Corpus Doctrine) is implemented as intended, evidence is reproducible, and no blocking discrepancies remain.

Operator verbal ack relayed into the ledger receipt under the agent-relayed-operator-attestation branch (GHI #292):

- **Operator's verbatim phrase:** `audit accepted`
- **Agent enrichment (relayed into ledger `attestation_text`):** ADR-0.0.27 Exemplar-Corpus Doctrine validated at Gate 5 — 7/7 OBPIs attested-completed with Layer-1 ARB-receipt-cited proof in `obpi-audit.jsonl`, 50/50 REQs covered (100.0%); `gz validate --complexity-doctrine-links` exit 0 (OBPI-07 fail-closed contract intact); `gz validate --advisory-scorecard` exit 0 (rule registered Mechanical); 13-project corpus pinned at 40-char-hex SHAs across all 10 archetypal cells (OBPI-02); dated baseline + `distilled-characteristics-2026-05-04.md` landed (OBPI-03/04); citation-contract Pydantic + JSON-schema mirror in place (OBPI-05); `gz-complexity-distill` skill canonical+mirror synced (OBPI-06).
- **Audit-time ARB receipts (heavy-lane policy):**
  - lint: `arb-ruff-afabd3a130de4b7d9d2fa63bfe1b0d9c`
  - typecheck: `arb-step-typecheck-b65091732f844814938ec390f829e681`
  - unittest: `arb-step-unittest-ea8e973199dc4cb0a5896c0ae47b2611`
  - mkdocs --strict: `arb-step-mkdocs-5b99d069649b45028392514a4d9fee10`
- **Co-presence proof:** per-ADR marker at `.claude/plans/.pipeline-active-ADR-0.0.27-exemplar-corpus-doctrine.json` written by `gz adr audit-begin ADR-0.0.27` from this slash-command chain; removed by `gz adr audit-end ADR-0.0.27` post-emit.
- **Lifecycle propagation verified:** `uv run gz adr report 0.0.27` shows Lifecycle: **Validated**, Closeout: READY, QC: READY (`audit/proofs/adr-report-post.txt`).

Signed: Jeffry Babb — 2026-05-05
