From 734840375f68fdbe5f2b6c2bd505332047d6c092 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Tue, 16 Jun 2026 10:35:55 -0400 Subject: [PATCH] docs(guidelines): add AI Agent Obligations section with 4 enforcement audit scripts --- conductor/product-guidelines.md | 60 +++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/conductor/product-guidelines.md b/conductor/product-guidelines.md index 848c0305..6df3603b 100644 --- a/conductor/product-guidelines.md +++ b/conductor/product-guidelines.md @@ -81,6 +81,66 @@ report or `--json` for machine-readable output. The audit classifies each violation + 1 suspicious + 1 unclear); see the styleguide's "Audit Script" section for the full taxonomy. +### AI Agent Obligations (Added 2026-06-16) + +AI agents writing code in this codebase MUST follow the data-oriented +convention. The convention is the OPPOSITE of idiomatic Python; LLMs +are trained on idiomatic Python and will revert to it without explicit +guidance. The project enforces the convention through 4 mechanisms: + +1. **`conductor/code_styleguides/error_handling.md`** — the canonical + styleguide. Has 5 patterns, 3 boundary types, 1 broad-except + distinction rule, 1 constructor-raise rule, 1 re-raise rule, and + the audit script reference. Read this before writing any code that + can fail at runtime. + +2. **`conductor/code_styleguides/error_handling.md` "AI Agent Checklist"** — + 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`** — the static analyzer + that catches violations before commit. The script classifies + `try/except/finally/raise` sites against 10 categories. Use it + pre-commit. + +4. **`scripts/audit_exception_handling.py --strict`** — the CI gate. + Exits 1 on any violation. Wire this into pre-commit hooks and CI. + +**The 4 enforcement audit scripts (the project-level enforcement set):** + +| Script | Purpose | Default mode | +|---|---|---| +| `audit_exception_handling.py` | Classifies `try/except/finally/raise` sites per the data-oriented convention | Informational (exits 0) | +| `audit_exception_handling.py --strict` | CI gate: exits 1 on any violation | CI gate (exits 1) | +| `audit_weak_types.py` | Identifies `dict[str, Any]` / `list[dict[...]]` / `Optional[Tuple]` / etc. | Informational (exits 0) | +| `audit_weak_types.py --strict` | CI gate for the type-strengthening convention | CI gate (exits 1) | +| `audit_main_thread_imports.py` | Enforces the main-thread import graph purity invariant | Always strict (exits 1) | +| `audit_no_models_config_io.py` | Enforces config-I/O ownership (AppController is the single source of truth) | Always strict (exits 1) | + +**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 + +# In CI / pre-commit hook (exits 1 on any violation) +uv run python scripts/audit_exception_handling.py --strict +uv run python scripts/audit_weak_types.py --strict +``` + +**Why this is enforced:** the convention prevents "tech rot with +idiomatic Python." LLMs writing new code in this codebase will revert +to idiomatic patterns (`try/except`, `Optional[T]`, `raise Exception`) +without explicit guidance. The 4 enforcement mechanisms (styleguide + +checklist + audit script + CI gate) are the defense-in-depth. See +[`docs/AGENTS.md`](../docs/AGENTS.md) §"Convention Enforcement" for the +project-level rules and [`AGENTS.md`](../AGENTS.md) "Critical +Anti-Patterns" for the HARD BAN entries. + ### `Optional[T]` ban (return types only) In the 3 refactored files (`src/mcp_client.py`, `src/ai_client.py`,