ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity

docs(guidelines): add AI Agent Obligations section with 4 enforcement audit scripts

Browse Source
This commit is contained in:
Edward R. Gonzalez
2026-06-16 10:35:55 -04:00
parent ef1b0a1c6d
commit 734840375f
1 changed files with 60 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
conductor/product-guidelines.md
+60
View File
@@ -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`,