manual_slop/conductor/product-guidelines.md

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).

Testing Requirements

These are the process standards the project's test infrastructure enforces. For the full implementation contract (fixture names, anti-patterns, audit scripts), see docs/guide_testing.md §Structural Testing Contract and the per-styleguide audit scripts in code_styleguides/.

• Structural Testing Contract: Ban on arbitrary core mocking with unittest.mock.patch (unless explicitly authorized for a specific boundary test). All integration and end-to-end testing must use the live_gui fixture to interact with a real instance of the application via the Hook API. Bypassing the hook server to directly mutate GUI state in tests is prohibited. All test-generated artifacts (logs, temporary workspaces, mock outputs) MUST be written to tests/artifacts/ or tests/logs/ (gitignored).
• Isolated-Pass Verification Fallacy (Added 2026-06-10): A test that "passes when run after test X but fails in isolation" is a fragile test, not a fragile fixture. The flip side is also true: a test that "passes in isolation but fails in batch" is failing — its failure is masked by isolation. The only verification that matters for live_gui tests (or any test that depends on shared subprocess state) is the batch run in the suite the test will ship in. Do NOT commit a fix that has only been verified in isolation. The 4-day test-hell saga of 2026-06-06 to 2026-06-10 was the result of agents committing fixes after isolated passes; the bisect required both directions and was only caught at the suite-level batch green on 2026-06-10. See docs/reports/test_infrastructure_hardening_batch_green_20260610.md for the full incident.
• Audit Scripts as CI Gates: The 4 audit scripts (check_test_toml_paths.py, audit_main_thread_imports.py, audit_weak_types.py, audit_no_models_config_io.py) enforce the conventions above. They run as pre-commit/CI gates and exit non-zero on regression. New conventions must be paired with a new audit script per conductor/workflow.md §Audit Script Policy.
• Skip Markers Are Documentation, Not Avoidance: @pytest.mark.skip(reason=...) is a record of a known failure, not an escape from fixing the underlying bug. Skip markers are valid for opt-in integration tests (require external resources, env-var-gated) or features behind a feature flag. They are NOT valid for pre-existing failing tests, tests the agent doesn't understand, or racy assertions the agent doesn't want to debug. When you add a skip, document the underlying issue in reason= and commit with a follow-up note. See conductor/workflow.md §Skip-Marker Policy.

See Also — Applied Conventions

The product guidelines are best understood alongside the per-source-file guides that demonstrate them:

• docs/guide_gui_2.md: §"UI Delegation Pattern" + §"ImGuiScope context managers" — Data-Oriented / Immediate Mode heuristics in action.
• 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: §"Thread Safety" — threading.local() source tier tagging, lock-protected event queue.
• docs/guide_models.md: §"Design Principles" + §"SDM Tags" — centralized registry, pydantic validation, [C: ...] / [M: ...] tags in docstrings.
• docs/guide_testing.md: §"Structural Testing Contract" — Ban on Arbitrary Core Mocking, live_gui Standard, Artifact Isolation.
• 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).