feat(directives): scavenge from docs/MMA_Support/: 5 directives

This commit is contained in:
ed
2026-07-04 00:11:15 -04:00
parent 3155518305
commit bea5d6b151
10 changed files with 165 additions and 0 deletions
@@ -0,0 +1,9 @@
# token_firewall_prevents_bloat
## v1
**Why this iteration:** Lifted from `docs/MMA_Support/Overview.md:15` (the "Token Firewalling" core paradigm bullet) + the 4-view abstraction table in `docs/MMA_Support/Data_Pipelines_and_Config.md:6-17`. The combination encodes: each tier's input is an *abstraction* of the tier below, so raw implementation noise never reaches the high-tier models.
**Source:** `docs/MMA_Support/Overview.md:15` + `docs/MMA_Support/Data_Pipelines_and_Config.md:6-17`
---
**Lifted:** 2026-07-02 (scavenge pass — directive library expansion from unread markdown in `docs/MMA_Support/`)
@@ -0,0 +1,28 @@
# Token firewalling is mandatory — error logs and deep history never bubble up to high-tier models
## The firewall
The 4-tier MMA is built around a sharp boundary: each tier's input is *abstracted* relative to the tier above it. Per `docs/MMA_Support/Overview.md:15`:
> "Token Firewalling: Error logs and deep history are never allowed to bubble up to high-tier models. The system relies heavily on abstracted AST views (Skeleton, Curated) rather than raw code when context allows."
The four abstraction layers, in increasing detail:
| Tier | View | What it contains |
|---|---|---|
| 1 (Orchestrator) | Directory map | file names + nested paths only |
| 2 (Tech Lead) | Skeleton View | class/def signatures, params, type hints (no docstrings, no bodies) |
| 2 (Tech Lead) | Curated View | class definitions, docstrings, `# [HOT]` / `@core_logic` bodies; standard bodies replaced with `... # Hidden` |
| 3 (Worker) | Raw View | unredacted, line-by-line source code of the single target file only |
## Why
- The most expensive models (Tier 1, Tier 2) burn context on architectural reasoning. They do not need (and should not receive) raw implementation noise.
- The cheapest models (Tier 3) can read raw code because they only read one file at a time.
## What this means in practice
- A Tier 2 agent reading foreign modules sees Skeleton View, not Raw View.
- A Tier 1 agent does not see code at all — only directory trees + architecture docs.
- AST view generation is the responsibility of `file_cache.py` (or equivalent) — never an LLM call.
- The boundary is enforced by the tool dispatcher, not by prompt instructions.