diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 5f8842f9..f917a25c 100644 --- a/docs/AGENTS.md +++ b/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.