# Specification: AI-Optimized Python Style Refactor

## 1. Overview
Refactor the Python codebase to a "Single-Space, Ultra-Compact" style specifically designed to minimize token consumption for AI agents. This involves reducing whitespace and blank lines while enhancing structural metadata (type hints) for better agent comprehension.

## 2. Functional Requirements
- **Indentation:** All 4-space indentations must be converted to **exactly 1 space** per level. This includes hanging indents and line continuations.
- **Newlines (Ultra-Compact):**
  - Maximum **one (1)** blank line between top-level definitions (classes, functions).
  - **Zero (0)** blank lines inside function or method bodies.
- **Typing (Strict):** Ensure all function and method signatures include strict type hints for `Args` and `Returns`.
- **Scope:**
  - Target: All `.py` files in the project root and subdirectories.
  - Exclusions: `.venv/`, `__pycache__/`, and third-party package code.

## 3. Non-Functional Requirements
- **Valid Python:** The resulting code MUST remain syntactically valid and executable Python 3.11+.
- **AST Compatibility:** The style must not interfere with existing AST tools (`ast`, `tree-sitter`) used for interface extraction and code outlines.
- **Token Efficiency:** The primary goal is to reduce the total token count of the codebase.

## 4. Current Status (Progress Checkpoint)
- **Phase 1: Completed.** Tooling developed (`scripts/ai_style_formatter.py`) and verified.
- **Phase 2: Completed.** Global codebase refactor for indentation and ultra-compact newlines (including 1-line gap before definitions) applied to all Python files.
- **Phase 3: In Progress.**
  - **Surgical Tooling:** New tools added to `mcp_client.py` and `.gemini/tools.json`: `get_file_slice`, `set_file_slice`, `py_update_definition`, `py_get_signature`, `py_set_signature`, `py_get_class_summary`, `py_get_var_declaration`, `py_set_var_declaration`.
  - **Core Typing:** `ai_client.py`, `mcp_client.py`, `aggregate.py`, `shell_runner.py` fully updated with strict type hints.
  - **Remaining:** `project_manager.py`, `session_logger.py`, `gui_2.py`, `gui_legacy.py` need strict typing.

## 5. Acceptance Criteria
- [x] Codebase indentation is uniformly 1 space.
- [x] No `.py` file contains consecutive blank lines.
- [x] No `.py` file contains blank lines within function or method bodies.
- [~] All functions/methods have complete type hints (Core Engine complete, UI/Manager pending).
- [x] Application remains functional and passes existing tests.

## 6. Out of Scope
- Architectural changes or logic refactoring.
- Modification of non-Python files (e.g., `.md`, `.toml`, `.ps1`).
- Import compaction (discarded per user request).
