From 013bc3541d90f1c14b51c40b4ccb0b97697cca73 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Thu, 25 Jun 2026 20:57:19 -0400 Subject: [PATCH] =?UTF-8?q?docs(agents):=20update=20docs/AGENTS.md=20?= =?UTF-8?q?=C2=A7Convention=20Enforcement=20with=20Core=20Value=20+=205=20?= =?UTF-8?q?audit=20scripts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/AGENTS.md | 50 +++++++++++++++++++++++++++++--------------------- 1 file changed, 29 insertions(+), 21 deletions(-) diff --git a/docs/AGENTS.md b/docs/AGENTS.md index f917a25c..686578d5 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -10,48 +10,56 @@ --- -## Convention Enforcement (Added 2026-06-16) +## Convention Enforcement (Added 2026-06-16; updated 2026-06-25 with §"Core Value") -**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." +**READ THIS BEFORE WRITING ANY PYTHON IN THIS REPO.** -**The 4 enforcement mechanisms (defense-in-depth):** +### Core Value (Added 2026-06-25) -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. +**C11/Odin/Jai semantics in a Python runtime.** The project is written in Python because of practical constraints (time, dependencies, LLM codegen ability), but the convention is to make Python behave as close to a statically-typed value-typed language as the runtime allows. -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. +LLMs default to opaque types (`dict[str, Any]`, `Any`, `Optional[T]`, `hasattr()` polymorphism) because that's what idiomatic Python training data looks like. **That defaults to mediocrity. This rule overrides it.** -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. +The canonical mandate is in [`conductor/code_styleguides/data_oriented_design.md` §8.5](../conductor/code_styleguides/data_oriented_design.md#85-the-python-type-promotion-mandate-added-2026-06-25). The banned patterns are in [`conductor/code_styleguides/python.md` §17](../conductor/code_styleguides/python.md#17-banned-patterns-llm-default-anti-patterns-added-2026-06-25). The boundary-layer concept is in [`conductor/code_styleguides/type_aliases.md`](../conductor/code_styleguides/type_aliases.md). -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) +**Every section of this document, every styleguide in `conductor/code_styleguides/`, and every deep-dive guide in `docs/guide_*.md` MUST be read through the lens of this Core Value.** If a section suggests `dict[str, Any]`, `Any`, `Optional[T]`, or `hasattr()` for entity dispatch in non-boundary code, that's an anti-pattern; flag it and ask. + +### The 4 enforcement mechanisms (defense-in-depth) + +1. **[`conductor/code_styleguides/data_oriented_design.md`](../conductor/code_styleguides/data_oriented_design.md) §8.5 (The Python Type Promotion Mandate)** — the canonical mandate. Banned patterns: `dict[str, Any]`, `Any`, `Optional[T]`, `hasattr()` for entity dispatch, `getattr()` for type-dispatch, `.get()` on known fields. + +2. **[`conductor/code_styleguides/python.md`](../conductor/code_styleguides/python.md) §17 (LLM Default Anti-Patterns)** — the explicit cheatsheet. Each banned pattern has a before/after example. + +3. **[`conductor/code_styleguides/error_handling.md`](../conductor/code_styleguides/error_handling.md)** — the `Result[T]` + `NIL_T` convention. Replaces `Optional[T]` returns. + +4. **The enforcement audit scripts** — the project-level enforcement set: + - `scripts/audit_weak_types.py --strict` — flags `dict[str, Any]`, `Any`, anonymous tuples + - `scripts/audit_optional_in_3_files.py --strict` — flags `Optional[T]` (extended to all `src/*.py` per the c11_python track) + - `scripts/audit_exception_handling.py --strict` — the data-oriented error handling 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 + - The boundary-layer audit (planned in `conductor/tracks/cruft_elimination_20260627/spec.md`) — documents every `Metadata` usage **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_optional_in_3_files.py +uv run python scripts/audit_exception_handling.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 +revert to idiomatic patterns (`dict[str, Any]`, `Any`, `Optional[T]`, +`hasattr()`) — exactly the "tech rot" the user is preventing. The +5+ mechanisms (Core Value + 3 styleguides + 5 audit scripts) 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. +"Core Value" for the canonical reference. ---