diff --git a/conductor/directives/convention_enforcement_4_mechanisms/meta.md b/conductor/directives/convention_enforcement_4_mechanisms/meta.md new file mode 100644 index 00000000..9209849a --- /dev/null +++ b/conductor/directives/convention_enforcement_4_mechanisms/meta.md @@ -0,0 +1,7 @@ +# convention_enforcement_4_mechanisms + +## v1 + +**Why this iteration:** Lifted verbatim from `docs/AGENTS.md:27-62 (Convention Enforcement §4 mechanisms)`. +**Source:** `docs/AGENTS.md:27-62 (Convention Enforcement §4 mechanisms)` +**Lifted:** 2026-07-02 (Phase A expansion harvest; user directive 2026-07-02) diff --git a/conductor/directives/convention_enforcement_4_mechanisms/v1.md b/conductor/directives/convention_enforcement_4_mechanisms/v1.md new file mode 100644 index 00000000..550a2fad --- /dev/null +++ b/conductor/directives/convention_enforcement_4_mechanisms/v1.md @@ -0,0 +1,27 @@ +## Convention Enforcement: the 4 mechanisms (defense-in-depth) + +1. **`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` §17 (LLM Default Anti-Patterns)** — the explicit cheatsheet. Each banned pattern has a before/after example. + +3. **`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]` return types in the baseline refactored files. An all-`src/*.py` successor (`audit_optional_returns.py`) is referenced in older planning docs but is NOT yet built — the live script today is `audit_optional_in_3_files.py`. + - `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 +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 — exactly the tech rot the user is preventing. The 5+ mechanisms (Core Value + 3 styleguides + 5 audit scripts) are the defense-in-depth. diff --git a/conductor/directives/core_value_read_first/meta.md b/conductor/directives/core_value_read_first/meta.md new file mode 100644 index 00000000..8c3afb8a --- /dev/null +++ b/conductor/directives/core_value_read_first/meta.md @@ -0,0 +1,7 @@ +# core_value_read_first + +## v1 + +**Why this iteration:** Lifted verbatim from `docs/AGENTS.md:17-25 (Convention Enforcement §Core Value)`. +**Source:** `docs/AGENTS.md:17-25 (Convention Enforcement §Core Value)` +**Lifted:** 2026-07-02 (Phase A expansion harvest; user directive 2026-07-02) diff --git a/conductor/directives/core_value_read_first/v1.md b/conductor/directives/core_value_read_first/v1.md new file mode 100644 index 00000000..1674ac0f --- /dev/null +++ b/conductor/directives/core_value_read_first/v1.md @@ -0,0 +1,11 @@ +### Core Value (Added 2026-06-25) + +**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. + +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 boundary-layer concept is in `conductor/code_styleguides/type_aliases.md`. + +**Every section of every styleguide and every deep-dive guide 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. + +**READ THIS BEFORE WRITING ANY PYTHON IN THIS REPO.**