manual_slop/docs/guide_meta_boundary.md

Meta-Boundary & Tooling Architecture

The Core Confusion

This repository contains two distinct architectural domains that share similar concepts. It is very easy for an AI agent (or human) to confuse the two and cause "feature bleed" or safety bypasses.

1. The Application (manual_slop): The Dear PyGui application being developed. This is the product.
2. The Meta-Tooling: The scripts, CLI wrappers, and MCP servers used by the human developer (and their external AI assistants like Gemini CLI or Claude Code) to build the Application.

Domain 1: The Application (manual_slop)

• Primary Files: gui_2.py, ai_client.py, multi_agent_conductor.py, dag_engine.py.
• Purpose: A local GUI for orchestrating AI. It manages its own internal AI sessions, tracks, and tickets.
• Safety Model: Strict Human-In-The-Loop (HITL). Any script or mutating action generated by the Application's internal AI must be approved by the human via a GUI modal (pre_tool_callback).
• Internal Tooling Control: The tools available to the Application's internal AI are defined strictly by manual_slop.toml ([agent.tools]).

Domain 2: The Meta-Tooling

• Primary Files: scripts/mma_exec.py, scripts/tool_call.py, scripts/mcp_server.py, .gemini/, .claude/.
• Purpose: The external AI agents (you, reading this) used to write the code for the Application.
• Safety Model: Driven by the external agent's own framework (e.g., Gemini CLI's auto-approval policies or Claude Code's permissions). These agents have their own sandboxing and do not use the Application's GUI for approval.
• Tooling Control: These external agents use mcp_client.py natively to investigate and modify the manual_slop codebase (e.g., using set_file_slice to fix a bug).

The Overlap & Entropy Vector: mcp_client.py

mcp_client.py is the shared bridge.

• It was originally written to give the Application's internal AI some read-only file context tools.
• It was later expanded heavily with AST mutation tools (py_update_definition, set_file_slice) specifically so the Meta-Tooling (Gemini CLI) could perform surgical edits on the codebase.

The Danger: Because mcp_client.py is shared, an AI working on the Application might accidentally expose these new Meta-Tooling mutation tools to the Application's internal AI without wiring them into the Application's strict GUI approval modal. This causes a critical safety bypass where the Application's AI can silently mutate files.

Guidelines for Future Tiers

When you are implementing a Track, you must ask yourself:

"Am I modifying the Application's behavior, or am I modifying the Meta-Tooling used to build it?"

1. If adding a tool to mcp_client.py: You must clarify if it is for the Meta-Tooling (us) or the Application (them). If it is for the Application, it MUST be gated behind manual_slop.toml toggles and wired to the GUI's pre_tool_callback for approval.
2. If editing mma_exec.py: You are modifying the Meta-Tooling. The changes here affect how you (or your Tier 3 workers) operate. Ensure you respect token limits (Context Amnesia) and do not leak massive Application files into your own context window.
3. If editing gui_2.py or ai_client.py: You are modifying the Application. Do not assume your external tool capabilities (like automatic file modification) apply here. Follow the Application's strict UX rules.