feat(directives): scavenge sweep 4/5 (tracks + commands + styleguides + todos): 18 batch-4 directives + concurrent worker batches

2026-07-04 02:00:42 -04:00
parent e8d3578f2e
commit 79124774ec
82 changed files with 2430 additions and 0 deletions
@@ -0,0 +1,7 @@
+# meta_tooling_app_boundary_check
+
+## v1
+
+**Why this iteration:** Lifted verbatim from `docs/guide_meta_boundary.md` §"The Overlap & Entropy Vector: `mcp_client.py`" (lines 44-49) and §"Guidelines for Future Tiers" §1 (line 55-56). This is the canonical safety-boundary rule for the shared `mcp_client.py` / `mcp_tool_specs.py` bridge; it is not currently encoded as a directive.
+**Source:** `docs/guide_meta_boundary.md:44-49,55-56`
+**Lifted:** 2026-07-03 scavenge sweep batch 5/5: guides + role prompts + transcripts
@@ -0,0 +1,61 @@
+# When modifying mcp_client.py, classify each new tool by domain (Application vs Meta-Tooling) before merging
+
+From `docs/guide_meta_boundary.md` §"The Overlap & Entropy Vector: `mcp_client.py`" (lines 44-49)
+and §"Guidelines for Future Tiers" §1 (lines 55-56):
+
+> 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.
+
+> 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.
+
+## The two domains
+
+- **Application** — `gui_2.py`, `ai_client.py`, `multi_agent_conductor.py`. The product.
+  Uses Strict HITL. Its AI is exposed to tools defined by `manual_slop.toml`
+  (`[agent.tools]`); every script/mutating tool call MUST pass through the GUI's
+  `pre_tool_callback` approval modal.
+- **Meta-Tooling** — `.opencode/`, `.agents/`, `mma-orchestrator/`, the bridge scripts.
+  The external AI agents (the agents writing this code). Not bound by the Application's
+  GUI; uses its own framework's safety model.
+
+## The entropy vector
+
+`mcp_client.py` is the shared bridge. It was originally written to give the
+Application's internal AI file I/O tools. It was later expanded with AST mutation
+tools (`py_update_definition`, `set_file_slice`, etc.) specifically so the
+**Meta-Tooling** (the agent building this code) could perform surgical edits.
+
+Because the file is shared, a Meta-Tooling-only mutation tool can accidentally be
+exposed to the Application's internal AI. That bypasses the GUI's approval gate
+and lets the Application silently mutate the user's files.
+
+## The protocol
+
+Before merging any change to `mcp_client.py` (or any file that imports/dispatches
+through it):
+
+1. **Classify the new tool or change** by domain: is it for the Application's
+   internal AI, or only for the Meta-Tooling agents building this code?
+2. **If Application**, ensure the tool is:
+   - Listed in `manual_slop.toml` (`[agent.tools]` or equivalent toggle)
+   - Wired through `pre_tool_callback` so every invocation triggers the GUI
+     approval modal
+   - NOT silently invocable from the Application's AI
+3. **If Meta-Tooling only**, ensure the tool is NOT auto-exposed to the
+   Application's AI under any default config; it must require an explicit opt-in.
+4. **If a tool crosses both domains**, split it into two functions with two
+   different registration paths — never let one tool body satisfy both.
+
+The same protocol applies to any tool added in `src/mcp_tool_specs.py` (which is
+now the canonical typed registry; `mcp_client.py` re-exports `TOOL_NAMES`).
+
+## See also
+
+- `docs/guide_meta_boundary.md` — Application vs Meta-Tooling split
+- `conductor/directives/ban_arbitrary_core_mocking` — no skipping the GUI test infrastructure
+- `conductor/directives/ban_local_imports` — the cross-domain import order matters