docs(style): update python styleguide to AI-optimized standard

Replaces Google Python Style Guide with project-specific conventions:
1-space indentation, strict type hints on all signatures/vars,
minimal blank lines, 120-char soft limit, AI-agent conventions.

Also marks type hinting task complete in plan.md.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

conductor/code_styleguides/python.md

@@ -1,37 +1,64 @@
-# Google Python Style Guide Summary
+# AI-Optimized Python Style Guide
 
-This document summarizes key rules and best practices from the Google Python Style Guide.
+This document defines the Python style conventions for the Manual Slop codebase.
+These deviate from PEP 8 / Google style to minimize token consumption when code
+is processed by AI agents, while preserving readability for human review.
 
-## 1. Python Language Rules
+## 1. Indentation and Whitespace
-- **Linting:** Run `pylint` on your code to catch bugs and style issues.
+- **Indentation:** 1 space per level. No tabs.
-- **Imports:** Use `import x` for packages/modules. Use `from x import y` only when `y` is a submodule.
+- **Continuation lines:** 1 space relative to the opening construct.
-- **Exceptions:** Use built-in exception classes. Do not use bare `except:` clauses.
+- **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.
-- **Global State:** Avoid mutable global state. Module-level constants are okay and should be `ALL_CAPS_WITH_UNDERSCORES`.
+- **Trailing whitespace:** None.
-- **Comprehensions:** Use for simple cases. Avoid for complex logic where a full loop is more readable.
+- **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.
-- **Default Argument Values:** Do not use mutable objects (like `[]` or `{}`) as default values.
-- **True/False Evaluations:** Use implicit false (e.g., `if not my_list:`). Use `if foo is None:` to check for `None`.
-- **Type Annotations:** Strongly encouraged for all public APIs.
 
-## 2. Python Style Rules
+## 2. Type Annotations
-- **Line Length:** Maximum 80 characters.
+- **All functions and methods** must have return type annotations.
-- **Indentation:** 4 spaces per indentation level. Never use tabs.
+- **All parameters** (except `self`/`cls`) must have type annotations.
-- **Blank Lines:** Two blank lines between top-level definitions (classes, functions). One blank line between method definitions.
+- **Module-level and class-level variables** must have type annotations.
-- **Whitespace:** Avoid extraneous whitespace. Surround binary operators with single spaces.
+- **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.
-- **Docstrings:** Use `"""triple double quotes"""`. Every public module, function, class, and method must have a docstring.
+- **Callable:** Use bare `Callable` for callback factories. Use `Callable[[ArgTypes], ReturnType]` when the signature is known and stable.
-  - **Format:** Start with a one-line summary. Include `Args:`, `Returns:`, and `Raises:` sections.
+- **DearPyGui / ImGui callbacks:** Use `sender: Any, app_data: Any` for framework callbacks where the types are runtime-determined.
-- **Strings:** Use f-strings for formatting. Be consistent with single (`'`) or double (`"`) quotes.
-- **`TODO` Comments:** Use `TODO(username): Fix this.` format.
-- **Imports Formatting:** Imports should be on separate lines and grouped: standard library, third-party, and your own application's imports.
 
-## 3. Naming
+## 3. Imports
-- **General:** `snake_case` for modules, functions, methods, and variables.
+- Use `from __future__ import annotations` at the top of every module.
-- **Classes:** `PascalCase`.
+- Group imports: stdlib, third-party, local — separated by a blank line.
-- **Constants:** `ALL_CAPS_WITH_UNDERSCORES`.
+- Use `from typing import Any, Optional, Callable` etc. for type-only imports.
-- **Internal Use:** Use a single leading underscore (`_internal_variable`) for internal module/class members.
+- Prefer `from x import Y` for specific symbols over `import x` when only one or two names are used.
 
-## 4. Main
+## 4. Naming
-- All executable files should have a `main()` function that contains the main logic, called from a `if __name__ == '__main__':` block.
+- **snake_case** for modules, functions, methods, variables.
+- **PascalCase** for classes.
+- **ALL_CAPS** for module-level constants.
+- **Single leading underscore** (`_name`) for internal/private members.
 
-**BE CONSISTENT.** When editing code, match the existing style.
+## 5. Docstrings
+- Required on classes and non-trivial public functions.
+- Use `"""triple double quotes"""`.
+- One-line summary is sufficient for simple methods.
+- Omit docstrings on obvious internal methods (e.g., `_cb_*` callbacks, `_render_*` UI methods) where the name is self-documenting.
 
-*Source: [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)*
+## 6. String Formatting
+- Prefer f-strings.
+- Use double quotes (`"`) for strings by default.
+- Use single quotes when the string contains double quotes.
+
+## 7. Error Handling
+- Never use bare `except:`.
+- Use specific exception types.
+- Prefer `if x is None:` over `if not x:` when testing for None specifically.
+
+## 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.
+- **No empty `__init__.py` files.**
+- **Minimal blank lines.** Token-efficient density is preferred over visual padding.
+- **Short variable names are acceptable** in tight scopes (loop vars, lambdas). Use descriptive names for module-level and class attributes.
+
+## 9. Line Length
+- Soft limit: 120 characters.
+- Hard limit: None — let the formatter handle wrapping if needed.
+- Rationale: 80-char limits cause excessive line continuations that waste tokens.
+
+## 10. Main Guard
+- All executable files should have `if __name__ == "__main__":` calling `main()`.
+
+**BE CONSISTENT.** When editing existing code, match the style already present in the file.

conductor/tracks/python_style_refactor_20260227/plan.md

@@ -13,12 +13,12 @@
 - [x] Task: Conductor - User Manual Verification 'Phase 2: Indentation and Newline Refactor' (Protocol in workflow.md) [checkpoint: Phase2]
 
 ## Phase 3: AI-Optimized Metadata and Final Cleanup
-- [~] Task: Conductor - Implement Strict Type Hinting across the Entire Codebase.
+- [x] Task: Conductor - Implement Strict Type Hinting across the Entire Codebase. [c816f65]
     - [x] Engine Core (`ai_client.py`, `mcp_client.py`, `aggregate.py`, `shell_runner.py`)
     - [x] Develop/Integrate Surgical AST Tools in `mcp_client.py` and `tools.json`.
     - [x] Management Modules (project_manager.py, session_logger.py) [19c28a1]
-    - [~] UI Modules (`gui_2.py`, `gui_legacy.py`)
+    - [x] UI Modules (`gui_2.py`, `gui_legacy.py`) [c816f65]
-- [ ] Task: Conductor - Update `conductor/code_styleguides/python.md` with the new AI-optimized standard.
+- [~] Task: Conductor - Update `conductor/code_styleguides/python.md` with the new AI-optimized standard.
 - [ ] Task: Conductor - User Manual Verification 'Phase 3: Metadata and Final Documentation' (Protocol in workflow.md)
 
 ---