From 2226f5805fe68bdd735e5013dae178806d0d9a49 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Thu, 25 Jun 2026 20:56:41 -0400 Subject: [PATCH] docs(agents): add HARD BAN (opaque types in non-boundary code) to Critical Anti-Patterns --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index d473ea45..84a9fd7f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -58,6 +58,7 @@ The 14 deep-dive guides under `docs/` (`guide_architecture.md`, `guide_ai_client - Do not use `git restore` while a user is mid-conversation without first confirming the desired state - HARD BAN: `git restore`, `git checkout -- `, `git reset` are FORBIDDEN without explicit user permission in the same message. They destroyed user in-progress src/* edits twice in one session (2026-06-07). If you think you need one, ASK FIRST. - **HARD BAN: Day estimates in track artifacts (Tier 1).** Do NOT include day / hour / minute estimates in spec.md, plan.md, metadata.json, or any other track artifact. Day estimates are inaccurate noise; Tier 2 capacity is bounded by attention, not time. Measure effort by **scope** (N files, M sites, N tasks). The user / Tier 2 agent decides the actual pacing. See `conductor/workflow.md` §"Tier 1 Track Initialization Rules" for the full rule, replacement patterns, and rationale. (Added 2026-06-16 per user feedback: "Day estimates are inaccurate. Tier-2s can only do so much in a single track and there is no way in hell its going to be 'DAYS'.") +- **HARD BAN: Opaque types in non-boundary code (added 2026-06-25).** LLMs default to `dict[str, Any]`, `Any`, `Optional[T]`, `hasattr()` polymorphism, and `.get('field', default)` because that's idiomatic Python training data. **All of these are BANNED in non-boundary code.** Use typed `@dataclass(frozen=True, slots=True)` with explicit fields; use `Result[T]` + `NIL_T` sentinels instead of `Optional[T]`; use direct attribute access instead of `.get()`. The ONLY place `dict[str, Any]` is allowed is the literal wire boundary (TOML/JSON parse functions); 2-3 functions per file. See `conductor/product-guidelines.md` "Core Value", `conductor/code_styleguides/data_oriented_design.md` §8.5 (The Python Type Promotion Mandate), `conductor/code_styleguides/python.md` §17 (LLM Default Anti-Patterns), and `conductor/code_styleguides/type_aliases.md` for the canonical mandates. User direction 2026-06-25: "I want the closest thing to c11/odin/jai in a scripting language... metadata should not be a dict[str, any]." ## File Size and Naming Convention (HARD RULE — added 2026-06-11)