---
paths:
  - "AGENTS.md"
  - "CLAUDE.md"
  - ".claude/rules/*.md"
---
<!-- Generated by gz agent sync — do not edit -->

<!-- rule-version: 0.1.0 -->

# Map-Not-Encyclopedia Doctrine (gzkit)

> **Rule version:** `0.1.0` — authored under OBPI-0.0.54-01; establishes the shape invariant and budget contract. OBPI-0.0.54-02 lifts AGENTS.md sections. OBPI-0.0.54-03 ships `gz validate --agents-md-map-conformance`.

## Invariant

AGENTS.md MUST contain only (a) binding bullet rules (one bullet = one rule, ≤ 3 lines per bullet), (b) structured tables (Persona, Gate Covenant, OBPI kinds, canonical-invocations, defect-fix routing thresholds), and (c) canonical-link references to deeper documentation at stable URLs under `docs/governance/`. AGENTS.md MUST NOT contain (i) multi-paragraph rationale prose (paragraph > 5 lines without a binding-bullet anchor), (ii) worked examples or anti-pattern catalogs, (iii) "Why this is canon" / "Why X" coda blockquotes, (iv) narrative pedagogical sections, or (v) operative-claims expansions whose binding-bullet form already states the rule. CLAUDE.md inherits the same shape contract. `.claude/rules/*.md` files inherit the same shape with their existing 16k per-file budget.

## Five prohibited shapes

1. **Multi-paragraph rationale prose** — paragraph longer than 5 lines without a binding-bullet anchor. The rationale belongs in `docs/governance/`; the bullet states the rule.
2. **Worked examples or anti-pattern catalogs** — subsections titled "Worked example", "Anti-patterns", "Example", or equivalent. These belong in the canonical doctrine doc at a stable URL.
3. **"Why this is canon" / "Why X" coda blockquotes** — blockquote paragraphs that explain why a rule was chosen. These are encyclopedic; the bullet is the rule.
4. **Narrative pedagogical sections** — multi-paragraph explanations of how a rule works, its history, or its relationship to other rules. Route to `docs/governance/agent-contract-rationale.md`.
5. **Operative-claims expansions** — prose blocks restating operative claims whose binding-bullet form already states the rule fully. The binding bullet is sufficient; the expansion is accretion.

## Budget

| File | Old budget | New budget | Enforced by |
|------|-----------|-----------|-------------|
| `AGENTS.md` | 40000 chars | 15000 chars | `gz validate --instructions-files-budget` |
| `CLAUDE.md` | 40000 chars | 4000 chars | `gz validate --instructions-files-budget` |
| `.claude/rules/*.md` | 16000 chars/file | 16000 chars/file | `gz validate --instructions-files-budget` (unchanged) |

The transitional window where AGENTS.md exceeds 15000 is closed by OBPI-0.0.54-02 (the lift). Until OBPI-02 completes, `gz validate --instructions-files-budget` will report a budget overrun that is expected and documented.

## Shape enforcement

`gz validate --agents-md-map-conformance` (OBPI-0.0.54-03, forthcoming) asserts:
- No paragraph in AGENTS.md is > 5 lines without a binding-bullet anchor
- No subsection title is in the prohibited set
- Every `See [text](path)` link resolves to an existing file
- File size is within the budget in `data/instructions_files_budget.json`

Validator emits `RemediationPayload` with `recovery: /gz-context-diet` on any violation.

## Related

- `docs/governance/agents-md-doctrine.md` — canonical expansion; the encyclopedia entry this rule points to
- `docs/governance/agent-contract-rationale.md` — existing lift target with six prior lifted sections
- `.gzkit/skills/gz-context-diet/SKILL.md` — the operator-facing procedure this rule makes the mechanical default
- `data/instructions_files_budget.json` — the budget values this rule's enforcement reads
- `ADR-0.0.54-agents-md-map-not-encyclopedia-doctrine` — parent ADR with TOC table of per-section targets
