# 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/claude_mma_exec.py`, `scripts/tool_call.py`, `scripts/mcp_server.py`, `mma-orchestrator/SKILL.md`, `.agents/skills/*/SKILL.md`, `.gemini/`, `.claude/`, `.opencode/`.
- **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, Claude Code's permissions, or OpenCode's hook system). These agents have their own sandboxing and do *not* use the Application's GUI for approval unless explicitly hooked.
- **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 Cross-Tool Abstractions

The Meta-Tooling domain is itself split by which external agent consumes it:

- **Gemini CLI** (the primary toolchain as of 2026-06-02): Uses the **conductor extension** which reads `./conductor/` for task tracking, workflow, and product context. Skills are activated via `activate_skill`.
- **OpenCode** (secondary): Uses **superpowers** or the conductor convention directly. Skills live in `.agents/skills/` and are activated by name.
- **Claude Code** (legacy, no longer primary): Uses the original `.claude/commands/*.md` slash command inventory. The `claude_mma_exec.py` script may be vestigial.

**The conductor system in `./conductor/` is the cross-tool abstraction.** Both Gemini CLI and OpenCode consume `conductor/workflow.md`, `conductor/product.md`, `conductor/tech-stack.md`, and `conductor/tracks.md`. Track implementation follows the TDD protocol documented in `conductor/workflow.md` regardless of which external agent is doing the work.

## The Inter-Domain Bridges: `cli_tool_bridge.py` & `claude_tool_bridge.py`
To achieve true Human-In-The-Loop (HITL) safety while developing the app *with* external AI tools, the project provides "Bridge" scripts.
- **How they work**: These scripts (`cli_tool_bridge.py` for Gemini CLI, `claude_tool_bridge.py` for Claude) intercept the tool execution requests from the external AI.
- **The Hook Server**: They instantiate an `ApiHookClient` and send an HTTP request to `http://127.0.0.1:8999` (the Application's local API Hook Server).
- **The Result**: The `manual_slop` GUI intercepts this network request and pops open a modal asking the human developer if they approve the action requested by the *external* Meta-Tooling agent.
- **Environment Context**: These bridges check the `GEMINI_CLI_HOOK_CONTEXT` or `CLAUDE_CLI_HOOK_CONTEXT` environment variables. If the variable is set to `mma_headless` (which happens during `mma_exec.py` sub-agent execution), the bridge automatically **allows** the execution to prevent sub-agents from blocking the main thread waiting for human GUI clicks.

### Bridge Status (as of 2026-06-02)

- `cli_tool_bridge.py` — **Active.** Primary toolchain is Gemini CLI.
- `claude_tool_bridge.py` — **Vestigial.** The project no longer uses Claude Code as a primary toolchain. The file is kept for backward compatibility with any external tooling that may still reference it. New meta-tooling work should target Gemini CLI (or OpenCode via the conductor convention), not Claude.
- An `opencode_bridge.py` is **not** present. OpenCode uses its own hook system (`.opencode/hooks.json`) and does not require an explicit bridge — the conductor convention is the bridge.

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