ed
7bcb5a8c07
Eliminates 22 call sites that bypassed the AppController state owner
and read/wrote config.toml directly. AppController is now the single
source of truth for self.config; gui_2.py, commands.py, etc. go
through controller.save_config() / controller.load_config().
Production changes:
- src/models.py: rename load_config -> _load_config_from_disk,
save_config -> _save_config_to_disk (private I/O primitives)
- src/app_controller.py: add public load_config()/save_config() methods
that own the state. Update 3 internal call sites and 3 ConductorEngine
call sites to pass max_workers from self.config
- src/multi_agent_conductor.py: ConductorEngine.__init__ now takes
max_workers as a parameter (caller responsibility, not I/O primitive)
- src/external_editor.py: get_default_launcher() takes config as a
parameter; gui_2.py:1311,4776 pass app.config
- src/gui_2.py: 17 sites of models.save_config(X.config) replaced with
X.save_config() (delegates via __getattr__ to controller)
- src/commands.py: save_all() uses app.save_config()
Test changes (route through controller, not I/O primitive):
- tests/conftest.py: mock_app and app_instance fixtures now patch
AppController.load_config/save_config instead of models I/O primitives
- 18 other test files: patches renamed from models._save_config_to_disk
to AppController.save_config (and same for load_config)
- tests/test_app_controller_mcp.py: use SLOP_CONFIG env var instead of
patching removed CONFIG_PATH module constant
- tests/test_parallel_execution.py: pass max_workers=2 explicitly to
ConductorEngine (caller no longer reads config)
- tests/test_gui_paths.py: add save_config=MagicMock() to MockApp;
assert on controller method, not I/O primitive
- tests/test_models_no_top_level_tomli_w.py: still calls private
_save_config_to_disk directly (the only allowed exception; tests
the lazy-load behavior of the primitive itself)
New files:
- scripts/audit_no_models_config_io.py: enforces the rule (--strict,
--json modes; AST-based docstring detection to avoid false positives)
- conductor/code_styleguides/config_state_owner.md: documents the rule
Verification:
- 67 targeted tests pass
- scripts/audit_no_models_config_io.py --strict returns 0
This is the architectural cleanup that surfaced during the
audit_architectural_cheats_20260607 review. Closes the smoke-gun
CONFIG_PATH module constant (already done in 0c7ebf22) AND the
free-function models.load_config/save_config smell.
[conductor(checkpoint): config-iO-refactor-20260607]
60 lines
7.7 KiB
Markdown
60 lines
7.7 KiB
Markdown
# Product Guidelines: Manual Slop
|
|
|
|
## Documentation Style
|
|
|
|
- **Strict & In-Depth:** Documentation must follow an old-school, highly detailed technical breakdown style (similar to VEFontCache-Odin). Focus on architectural design, state management, algorithmic details, and structural formats rather than just surface-level usage.
|
|
|
|
## UX & UI Principles
|
|
|
|
- **USA Graphics Company Values:** Embrace high information density and tactile interactions.
|
|
- **Professional Arcade Aesthetics:** Balances high-energy "Arcade" feedback (blinking notifications, tactile updates) with a "Professional" visual discipline. Employs modern typography (Inter/Maple Mono), subtle rounded geometry, and soft shadows to ensure the tool feels like a sophisticated, expert utility. Includes a high-density **NERV Technical Console** theme option for maximum focus and CRT-inspired visual feedback.
|
|
- **Rich Text Readability:** Prioritizes legibility of AI communications and technical logs by utilizing GitHub-Flavored Markdown and integrated syntax highlighting. This ensures that complex code fragments and structured data are immediately accessible and professionally presented.
|
|
- **Explicit Control & Expert Focus:** The interface should not hold the user's hand. It must prioritize explicit manual confirmation for destructive actions while providing dense, unadulterated access to logs and context.
|
|
- **Multi-Viewport Capabilities:** Leverage dockable, floatable panels to allow users to build custom workspaces suitable for multi-monitor setups.
|
|
|
|
## Code Standards & Architecture
|
|
|
|
- **Data-Oriented & Immediate Mode Heuristics:** Align with the architectural values of engineers like Casey Muratori and Mike Acton.
|
|
- **The "Less Python Does, the Better" Rule:** Python should act primarily as a procedural semantic definer (similar to how ImGui defines a UI DAG), delegating heavy lifting to efficient data structures, vectorized operations, or lower-level primitives.
|
|
- Minimize Python JIT overhead by favoring bulk data processing over fine-grained object-oriented manipulation.
|
|
- The GUI (`gui_2.py`) must remain a pure visualization of application state. It should not *own* complex business logic or orchestrator hooks (strive to decouple the 'Application' controller from the 'View').
|
|
- Treat the UI as an immediate mode frame-by-frame projection of underlying data structures.
|
|
- Optimize for zero lag and never block the main render loop with heavy Python JIT work.
|
|
- Utilize proper asynchronous batching and queue-based pipelines for background AI work, ensuring a data-oriented flow rather than tangled object-oriented state graphs.
|
|
- **Strict State Management:** There must be a rigorous separation between the Main GUI rendering thread and daemon execution threads. The UI should *never* hang during AI communication or script execution. Use lock-protected queues and events for synchronization.
|
|
- **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.
|
|
- **Mandatory ImGui Verification:** All changes to the GUI (`gui_2.py`) MUST be verified using the custom AST linter (`scripts/check_imgui_scopes.py`) to ensure all ImGui scopes (begin/end, push/pop) are properly matched. Developers should prioritize the use of `src/imgui_scopes.py` context managers (`imscope`) over manual push/pop calls.
|
|
- **Modular Controller Pattern:** To prevent "God Object" bloat in core controllers (like `AppController`), all state-independent or utility logic must be moved to module-level functions. Functions requiring class state should accept the instance as an explicit dependency (`def logic(controller: AppController, ...)`). Massive `if/elif` dispatch blocks must be refactored into handler maps (dictionaries) of module-level functions.
|
|
- **UI Delegation for Hot-Reload:** All complex ImGui rendering logic must be extracted from the `App` class into module-level functions named `render_xxx(app: App)`. The `App` class should only contain thin delegation wrappers (`def _render_xxx(self): render_xxx(self)`). This architecture is mandatory for supporting state-preserving hot-reloads of the UI logic.
|
|
- **Dependency Minimalism:** Limit external dependencies where possible. For instance, prefer standard library modules (like `urllib` and `html.parser` for web tools) over heavy third-party packages.
|
|
|
|
## Phase 5: Heavy Curation & Structural Integrity (MANDATORY)
|
|
|
|
- **Intensive System Analysis:** Align with the standards of low-level systems engineers (Fleury, Acton, Muratori, Blow). Do not accept high-level abstractions as sufficient documentation.
|
|
- **Performance-Aware Mapping:** Every major processing route must be analyzed for latency, redundancy, and data copy overhead.
|
|
- **Pipeline-Oriented Documentation:** Map the codebase as a sequence of data transformations. Identify exactly where data enters, how it is mutated, and where it exits.
|
|
- **Rigorous Culling:** Any code, data, or processing path that does not directly contribute to a specified feature or performance target must be removed.
|
|
- **Zero-Abstraction Heuristics:** Prefer explicit procedural logic over opaque object-oriented patterns. Ensure state transitions are traceable and deterministic.
|
|
|
|
## AI-Optimized Compact Style
|
|
|
|
- **Indentation:** Exactly **1 space** per level. This minimizes token usage in nested structures.
|
|
- **Newlines:** Maximum **one (1)** blank line between top-level definitions. **Zero (0)** blank lines within function or method bodies.
|
|
- **Vertical Compaction:** Use single-line `if` statements, semicolon-separated framework calls (`imgui.same_line(); imgui.text(...)`), and aligned assignments to aggressively minimize vertical line counts. **Note:** Function and method definition signatures (`def ...:`) must ALWAYS remain on their own isolated lines.
|
|
- **Region Blocks:** Use `#region: Name` and `#endregion: Name` to logically organize massive files that cannot be easily broken apart without increasing context load.
|
|
- **Type Hinting:** Mandatory, strict type hints for all parameters, return types, and global variables to ensure high-signal context for AI agents.
|
|
- **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).
|
|
|
|
## See Also — Applied Conventions
|
|
|
|
The product guidelines are best understood alongside the per-source-file guides that demonstrate them:
|
|
|
|
- **[docs/guide_gui_2.md](../docs/guide_gui_2.md):** §"UI Delegation Pattern" + §"ImGuiScope context managers" — Data-Oriented / Immediate Mode heuristics in action.
|
|
- **[docs/guide_app_controller.md](../docs/guide_app_controller.md):** §"Modular Controller Pattern" + §"Hook API Surface" — handler maps for dispatch, not if/elif chains.
|
|
- **[docs/guide_multi_agent_conductor.md](../docs/guide_multi_agent_conductor.md):** §"Thread Safety" — `threading.local()` source tier tagging, lock-protected event queue.
|
|
- **[docs/guide_models.md](../docs/guide_models.md):** §"Design Principles" + §"SDM Tags" — centralized registry, pydantic validation, `[C: ...]` / `[M: ...]` tags in docstrings.
|
|
- **[docs/guide_testing.md](../docs/guide_testing.md):** §"Structural Testing Contract" — Ban on Arbitrary Core Mocking, `live_gui` Standard, Artifact Isolation.
|
|
- **[code_styleguides/config_state_owner.md](code_styleguides/config_state_owner.md):** Config I/O state ownership — `AppController` is the single source of truth; direct calls to `models.save_config`/`models.load_config` in `src/` are forbidden (enforced by `scripts/audit_no_models_config_io.py`).
|