From b5baaaaab7090e66ce57074684a35d0ecc50d752 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Thu, 2 Jul 2026 22:00:37 -0400 Subject: [PATCH] feat(directives): harvest 5 code style directives from python.md + workflow.md + product-guidelines.md + AGENTS.md --- .../directives/no_comments_in_body/v1.md | 16 ++++++++++++ .../directives/no_diagnostic_noise/v1.md | 16 ++++++++++++ conductor/directives/one_space_indent/v1.md | 23 +++++++++++++++++ .../directives/sdm_dependency_tags/v1.md | 25 +++++++++++++++++++ .../directives/type_hints_required/v1.md | 22 ++++++++++++++++ 5 files changed, 102 insertions(+) create mode 100644 conductor/directives/no_comments_in_body/v1.md create mode 100644 conductor/directives/no_diagnostic_noise/v1.md create mode 100644 conductor/directives/one_space_indent/v1.md create mode 100644 conductor/directives/sdm_dependency_tags/v1.md create mode 100644 conductor/directives/type_hints_required/v1.md diff --git a/conductor/directives/no_comments_in_body/v1.md b/conductor/directives/no_comments_in_body/v1.md new file mode 100644 index 00000000..fac30d37 --- /dev/null +++ b/conductor/directives/no_comments_in_body/v1.md @@ -0,0 +1,16 @@ +# no_comments_in_body — v1 + +**Why this iteration:** Lifted verbatim from `conductor/code_styleguides/python.md` §8 (lines 64-71) + `AGENTS.md` "Critical Anti-Patterns" (line 54). This is the baseline encoding — the imperative-bullet style currently in production. +Future variants will test alternative encodings (rationale-first, before/after) against this baseline. + +**Source:** `conductor/code_styleguides/python.md:64-71 + AGENTS.md:54` + +--- + +From `conductor/code_styleguides/python.md` §8 "AI-Agent Specific Conventions": +- **No redundant comments.** Do not add comments that restate what the code does. Only comment on *why* when non-obvious. + +--- + +From `AGENTS.md` "Critical Anti-Patterns": +- Do not add comments to source code; documentation lives in `/docs` \ No newline at end of file diff --git a/conductor/directives/no_diagnostic_noise/v1.md b/conductor/directives/no_diagnostic_noise/v1.md new file mode 100644 index 00000000..7c951df2 --- /dev/null +++ b/conductor/directives/no_diagnostic_noise/v1.md @@ -0,0 +1,16 @@ +# no_diagnostic_noise — v1 + +**Why this iteration:** Lifted verbatim from `conductor/code_styleguides/python.md` §8 (lines 68-70) + `AGENTS.md` "Session-Learned Anti-Patterns" §5. This is the baseline encoding — the imperative-bullet style currently in production. +Future variants will test alternative encodings (rationale-first, before/after) against this baseline. + +**Source:** `conductor/code_styleguides/python.md:68-70 + AGENTS.md:"Session-Learned Anti-Patterns" §5` + +--- + +From `conductor/code_styleguides/python.md` §8 "AI-Agent Specific Conventions": +- **No diagnostic noise in production code (Added 2026-06-09).** `sys.stderr.write(f"[XYZ_DIAG] ...")` lines added to `src/*.py` for one-time debugging are technical debt the moment they ship. The project's production code should not contain `[XYZ_DIAG]` markers, `print(...debug...)` calls, or any other ad-hoc debug instrumentation. The right place for diagnostic output during a one-time investigation is `tests/artifacts/.diag.log` (a log file) or a standalone `/tmp/diag_.py` script. If you must instrument a production function for a single test run, the diag lines are part of the same atomic commit as the fix — they do not live uncommitted in the working tree. If you "revert everything," that means the diag lines are also reverted. + +--- + +From `AGENTS.md` "No Diagnostic Noise in Production (kill it)": +- Diagnostic stderr goes to a log file (`tests/artifacts/.diag.log`) or to a temporary diagnostic script (`/tmp/diag_rag.py`), NOT to `src/*.py`. If you absolutely must instrument a production function for a single test run, the diag lines are part of the same atomic commit as the fix — they do not live uncommitted in the working tree. If you "revert everything," that means the diag lines are also reverted. \ No newline at end of file diff --git a/conductor/directives/one_space_indent/v1.md b/conductor/directives/one_space_indent/v1.md new file mode 100644 index 00000000..a606a61d --- /dev/null +++ b/conductor/directives/one_space_indent/v1.md @@ -0,0 +1,23 @@ +# one_space_indent — v1 + +**Why this iteration:** Lifted verbatim from `conductor/code_styleguides/python.md` §1 (lines 7-12) + `conductor/workflow.md` §"Code Style" line 7. This is the baseline encoding — the imperative-bullet style currently in production. +Future variants will test alternative encodings (rationale-first, tabular) against this baseline. + +**Source:** `conductor/code_styleguides/python.md:7-12 + workflow.md:7` + +--- + +## 1. Indentation and Whitespace + +- **Indentation:** 1 space per level. No tabs. +- **Continuation lines:** 1 space relative to the opening construct. +- **Blank lines:** Zero blank lines between function/method definitions within a class. One blank line between top-level definitions only when separating logically distinct sections. +- **Trailing whitespace:** None. +- **Rationale:** 1-space indentation reduces token count by ~40% compared to 4-space on deeply nested GUI code, with no loss of structural clarity for AST-based tools. + +--- + +From `conductor/workflow.md` "Code Style": +- **1-space indentation** for ALL Python code (NO EXCEPTIONS) +- **CRLF line endings** on Windows +- **NO COMMENTS** unless explicitly requested \ No newline at end of file diff --git a/conductor/directives/sdm_dependency_tags/v1.md b/conductor/directives/sdm_dependency_tags/v1.md new file mode 100644 index 00000000..50472660 --- /dev/null +++ b/conductor/directives/sdm_dependency_tags/v1.md @@ -0,0 +1,25 @@ +# sdm_dependency_tags — v1 + +**Why this iteration:** Lifted verbatim from `conductor/code_styleguides/python.md` §12 (lines 202-208) + `conductor/product-guidelines.md` §"AI-Optimized Compact Style" (lines 59-63). This is the baseline encoding — the imperative-bullet style currently in production. +Future variants will test alternative encodings (rationale-first, before/after) against this baseline. + +**Source:** `conductor/code_styleguides/python.md:202-208 + product-guidelines.md:59-63` + +--- + +## 12. Structural Dependency Mapping (SDM) + +To assist AI agents in evaluating refactoring impact across dynamic codebases, all major definitions SHOULD include terse SDM tags at the end of their docstrings. + +- **Format:** Tags are enclosed in square brackets at the end of the docstring body. +- **For Functions/Methods:** `[C: CallerA, CallerB]` — List of primary internal callers within the codebase. +- **For State Variables:** + - `[M: File:Line, Method]` — List of primary mutation points (where the value is assigned). + - `[U: File]` — Major codepaths of use (where the value is read but not changed). + +--- + +From `conductor/product-guidelines.md` "AI-Optimized Compact Style": +- **Structural Dependency Mapping (SDM):** All major state variables, methods, and functions MUST include terse dependency tags at the end of their docstrings for AI-assisted impact analysis. + - **Functions/Methods:** `[C: Caller1, Caller2]` (Primary callers). + - **State Variables:** `[M: File:Line, Method]` (Mutation points) and `[U: File]` (Major use paths). \ No newline at end of file diff --git a/conductor/directives/type_hints_required/v1.md b/conductor/directives/type_hints_required/v1.md new file mode 100644 index 00000000..b6cf722c --- /dev/null +++ b/conductor/directives/type_hints_required/v1.md @@ -0,0 +1,22 @@ +# type_hints_required — v1 + +**Why this iteration:** Lifted verbatim from `conductor/code_styleguides/python.md` §2 (lines 23-31) + `conductor/product-guidelines.md` §"AI-Optimized Compact Style" (line 58). This is the baseline encoding — the imperative-bullet style currently in production. +Future variants will test alternative encodings (rationale-first, before/after) against this baseline. + +**Source:** `conductor/code_styleguides/python.md:23-31 + product-guidelines.md:58` + +--- + +## 2. Type Annotations + +- **All functions and methods** must have return type annotations. +- **All parameters** (except `self`/`cls`) must have type annotations. +- **Module-level and class-level variables** must have type annotations. +- **Use modern syntax:** `list[str]`, `dict[str, Any]`, `X | None` over `Optional[X]` where Python 3.10+ is available. Use `from __future__ import annotations` if needed. +- **Callable:** Use bare `Callable` for callback factories. Use `Callable[[ArgTypes], ReturnType]` when the signature is known and stable. +- **DearPyGui / ImGui callbacks:** Use `sender: Any, app_data: Any` for framework callbacks where the types are runtime-determined. + +--- + +From `conductor/product-guidelines.md` "AI-Optimized Compact Style": +- **Type Hinting:** Mandatory, strict type hints for all parameters, return types, and global variables to ensure high-signal context for AI agents. \ No newline at end of file