docs(agents): add Convention Enforcement section at the top (4 mechanisms)

docs/AGENTS.md

@@ -1,7 +1,7 @@
 # ./docs/AGENTS.md (the agent-facing mirror)
 
 **Status:** Agent-facing mirror of `docs/Readme.md` (the human-facing docs index, which is preserved as-is). For agents (any tier), this is the recommended first read for understanding the project's docs structure.
-**Date:** 2026-06-12
+**Date:** 2026-06-12 (updated 2026-06-16 with §"Convention Enforcement")
 **Cross-refs:** `docs/Readme.md` (human-facing); `AGENTS.md` (project root); the 6 styleguides in `conductor/code_styleguides/`.
 
 > **What this is.** `docs/Readme.md` is the human-facing docs index. *This* file is the agent-facing equivalent: it organizes the 14 deep-dive guides under `docs/` by MMA tier, and it cross-references the canonical styleguides. The 2 files cover the same docs but with different audiences and different reading paths.
@@ -10,6 +10,51 @@
 
 ---
 
+## Convention Enforcement (Added 2026-06-16)
+
+**READ THIS BEFORE WRITING ANY PYTHON IN THIS REPO.** The project follows the
+data-oriented error handling convention (Ryan Fleury's "errors are
+just cases" framework). The convention is the OPPOSITE of idiomatic
+Python; LLMs are trained on idiomatic Python and will revert to it
+without explicit guidance. The convention prevents "tech rot with
+idiomatic Python."
+
+**The 4 enforcement mechanisms (defense-in-depth):**
+
+1. **[`conductor/code_styleguides/error_handling.md`](../conductor/code_styleguides/error_handling.md)** — the canonical styleguide. 5 patterns, 3 boundary types, 1 broad-except distinction rule, 1 constructor-raise rule, 1 re-raise rule, and the audit script reference.
+
+2. **[`conductor/code_styleguides/error_handling.md` "AI Agent Checklist"](../conductor/code_styleguides/error_handling.md#ai-agent-checklist-added-2026-06-16)** — the explicit cheatsheet of 5 MUST-DO rules, 7 MUST-NOT-DO rules, and 3 boundary patterns. Run this checklist before claiming a task is done.
+
+3. **[`scripts/audit_exception_handling.py`](../../scripts/audit_exception_handling.py)** — the static analyzer. Catches violations before commit. Run it pre-commit. Has 3 output modes (human-readable, `--json`, `--by-size`) and a `--strict` CI-gate mode.
+
+4. **The 4 enforcement audit scripts** — the project-level enforcement set:
+   - `scripts/audit_exception_handling.py --strict` (the convention)
+   - `scripts/audit_weak_types.py --strict` (the type-strengthening convention)
+   - `scripts/audit_main_thread_imports.py` (always strict; the import graph gate)
+   - `scripts/audit_no_models_config_io.py` (the config-I/O ownership gate)
+
+**Pre-commit workflow (recommended):**
+
+```bash
+# Run before claiming "done"
+uv run python scripts/audit_exception_handling.py
+uv run python scripts/audit_weak_types.py
+uv run python scripts/audit_main_thread_imports.py
+uv run python scripts/audit_no_models_config_io.py
+```
+
+**Why this is enforced:** the convention prevents the LLM-training-data
+problem. Without these mechanisms, AI agents writing new code will
+revert to idiomatic patterns (`try/except`, `Optional[T]`, `raise
+Exception`) — exactly the "tech rot" the user is preventing. The
+4 mechanisms (styleguide + checklist + audit script + CI gate) are
+the defense-in-depth. See the project-level rules in
+[`AGENTS.md`](../AGENTS.md) "Critical Anti-Patterns" (top of file) and
+[`conductor/product-guidelines.md`](../conductor/product-guidelines.md)
+"Data-Oriented Error Handling" for the canonical reference.
+
+---
+
 ## 0. The 4 memory dimensions (the cross-cutting lens)
 
 The conversation data has 4 distinct memory dimensions (curation / discussion / RAG / knowledge). Most features touch 1-2; some touch 3. Use this lens to identify which dimension(s) your feature needs.