diff --git a/conductor/product-guidelines.md b/conductor/product-guidelines.md index e53f5306..a4e953cd 100644 --- a/conductor/product-guidelines.md +++ b/conductor/product-guidelines.md @@ -1,5 +1,18 @@ # Product Guidelines: Manual Slop +## Core Value (Added 2026-06-25) + +**C11/Odin/Jai semantics in a Python runtime.** This codebase 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. + +**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.** + +The canonical mandate is in `conductor/code_styleguides/data_oriented_design.md` §8.5 (The Python Type Promotion Mandate). The banned patterns are in `conductor/code_styleguides/python.md` §17 (LLM Default Anti-Patterns). The enforcement audits are: +- `scripts/audit_weak_types.py --strict` +- `scripts/audit_optional_in_3_files.py --strict` (extended to all `src/*.py`) +- The boundary-layer audit (planned in `conductor/tracks/cruft_elimination_20260627/spec.md`) + +**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. + ## Documentation Style - **Strict & In-Depth:** Documentation must follow an old-school, highly detailed technical breakdown style (similar to VEFontCache-Odin). Focus on architectural design, state management, algorithmic details, and structural formats rather than just surface-level usage.