diff --git a/conductor/directives/cache_stable_to_volatile/v1.md b/conductor/directives/cache_stable_to_volatile/v1.md index 90f08bd6..1b11810b 100644 --- a/conductor/directives/cache_stable_to_volatile/v1.md +++ b/conductor/directives/cache_stable_to_volatile/v1.md @@ -1,3 +1,5 @@ +# Context must be ordered stable-to-volatile — the stable prefix (layers 1-7) gets cached, the volatile suffix (layers 8-12) never does + ## 1. The 12-layer model (the stable-to-volatile ordering) | # | Layer | Stable across turns? | Source | SSDL | diff --git a/conductor/directives/comprehensive_logging/v1.md b/conductor/directives/comprehensive_logging/v1.md index 516afcbd..1d78ad5c 100644 --- a/conductor/directives/comprehensive_logging/v1.md +++ b/conductor/directives/comprehensive_logging/v1.md @@ -1,2 +1,4 @@ +# All actions, API payloads, tool calls, and executed scripts must be comprehensively logged + From `conductor/product-guidelines.md` §"Code Standards & Architecture": - **Comprehensive Logging:** Aggressively log all actions, API payloads, tool calls, and executed scripts. Maintain timestamped JSON-L and markdown logs to ensure total transparency and debuggability. \ No newline at end of file diff --git a/conductor/directives/contract_change_audit/v1.md b/conductor/directives/contract_change_audit/v1.md index ff156c00..02d7e876 100644 --- a/conductor/directives/contract_change_audit/v1.md +++ b/conductor/directives/contract_change_audit/v1.md @@ -1,3 +1,5 @@ +# When changing a public interface, all callers must be updated in the same atomic commit + ### The contract-change check (mandatory for any edit that changes a public interface) Before any edit, search the codebase for callers of the function/symbol/yield shape you're changing. If your edit changes: diff --git a/conductor/directives/convention_enforcement_4_mechanisms/v1.md b/conductor/directives/convention_enforcement_4_mechanisms/v1.md index 550a2fad..034f93ba 100644 --- a/conductor/directives/convention_enforcement_4_mechanisms/v1.md +++ b/conductor/directives/convention_enforcement_4_mechanisms/v1.md @@ -1,3 +1,5 @@ +# Conventions are enforced via 4 mechanisms: styleguide, checklist, audit script, CI gate + ## 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. diff --git a/conductor/directives/core_value_read_first/v1.md b/conductor/directives/core_value_read_first/v1.md index 1674ac0f..2cbe5259 100644 --- a/conductor/directives/core_value_read_first/v1.md +++ b/conductor/directives/core_value_read_first/v1.md @@ -1,3 +1,5 @@ +# Before any action, read the core convention docs first (AGENTS.md, workflow.md, product-guidelines.md, code_styleguides/python.md §17) + ### 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. diff --git a/conductor/directives/decorator_orphan_pitfall/v1.md b/conductor/directives/decorator_orphan_pitfall/v1.md index 746abc4b..04440b86 100644 --- a/conductor/directives/decorator_orphan_pitfall/v1.md +++ b/conductor/directives/decorator_orphan_pitfall/v1.md @@ -1,3 +1,5 @@ +# When inserting code above a `@property` def, the @property decorator must stay attached to the original def + ### Rule 6. The Decorator-Orphan Pitfall When inserting new methods **before an existing `@property` def**: diff --git a/conductor/directives/deduction_loop_limit/v1.md b/conductor/directives/deduction_loop_limit/v1.md index c0f9fdad..b3eb5c86 100644 --- a/conductor/directives/deduction_loop_limit/v1.md +++ b/conductor/directives/deduction_loop_limit/v1.md @@ -1,3 +1,5 @@ +# Test failures must not be re-run more than twice in a single investigation + ### 1. The Deduction Loop (kill it) **Symptom:** Run test → fail → read log → form hypothesis → run again → fail differently → add diag → run again → fail again → loop. You end up running the same test 4+ times in one session, each run reading partial log output. diff --git a/conductor/directives/defer_not_catch_for_native_crashes/v1.md b/conductor/directives/defer_not_catch_for_native_crashes/v1.md index 182e4354..2ef191c5 100644 --- a/conductor/directives/defer_not_catch_for_native_crashes/v1.md +++ b/conductor/directives/defer_not_catch_for_native_crashes/v1.md @@ -1,3 +1,5 @@ +# Native crashes (Windows access violations, Linux SIGSEGV) cannot be caught — use the defer-not-catch pattern + ## Defer-Not-Catch Pattern for Native Crashes `imgui-bundle` (and similar native extension libraries) expose C-level functions that can crash the Python process with a Windows access violation (`0xc0000005`) or a SIGSEGV on Linux. **These crashes are not catchable from Python** — `try/except Exception` does not intercept native access violations, only Python exceptions.