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

conductor/directives/stub_before_implement/meta.md

@@ -0,0 +1,9 @@
+# stub_before_implement
+
+## v1
+
+**Why this iteration:** Lifted from `docs/MMA_Support/Tier2_TechLead.md:39-46` (the "Contract-First Delegation (Stub-and-Resolve)" section) — Tier 2 "splits requirement into a Stub Ticket, Consumer Ticket, and Implementation Ticket," spawns a cheap contract_stubber, regenerates the skeleton, then runs Consumer and Implementer in parallel. The principle name is "Force Interface-Driven Development (IDD) to prevent hallucination."
+**Source:** `docs/MMA_Support/Tier2_TechLead.md:39-46`
+
+---
+**Lifted:** 2026-07-02 (scavenge pass — directive library expansion from unread markdown in `docs/MMA_Support/`)

conductor/directives/stub_before_implement/v1.md

@@ -0,0 +1,26 @@
+# Generate stubs and contracts before implementation — Interface-Driven Development is mandatory for cross-module dependencies
+
+## The stub-and-resolve pattern
+
+When a Tier 2 Tech Lead detects a cross-module dependency (or a single massive refactor) requiring an undefined signature, the order of operations is:
+
+1. **Contract definition** — split the requirement into three tickets:
+   - A `Stub Ticket` (generates the empty function signature + type hints + docstrings)
+   - A `Consumer Ticket` (codes against the new interface)
+   - An `Implementation Ticket` (fills the stub logic)
+2. **Stub generation** — spawn a cheap Tier 3 worker (the `contract_stubber` archetype) to emit the empty signature.
+3. **Skeleton broadcast** — the stub merges, the AST immediately re-runs, and the global Skeleton View updates.
+4. **Parallel implementation** — the Consumer and the Implementer run in isolated contexts, coding against the same skeleton.
+
+Per `docs/MMA_Support/Tier2_TechLead.md:39-46`: "Force Interface-Driven Development (IDD) to prevent hallucination."
+
+## Why
+
+LLMs hallucinate function signatures they have never seen. By forcing a cheap worker to emit the contract first, every later worker (including future agents and humans) reads the same ground-truth signature. The skeleton becomes the single source of truth.
+
+## What this means in practice
+
+- A cross-module change is never implemented directly. The stub ticket lands first.
+- The skeleton view is regenerated automatically after the stub merges (no manual sync step).
+- Implementers and consumers run in parallel against the same skeleton — they cannot drift.
+- If the implementation changes the signature, the stub is regenerated and consumers are re-spawned (the skeleton is the contract).

conductor/directives/tier1_orchestrator_no_implementation/meta.md

@@ -0,0 +1,9 @@
+# tier1_orchestrator_no_implementation
+
+## v1
+
+**Why this iteration:** Lifted from `docs/MMA_Support/Tier1_Orchestrator.md:7,16` — the Tier 1 role definition states the orchestrator "operates strictly on metadata, summaries, and executive-level directives. It never sees raw implementation code" and the "What it Ignores" line lists source code + AST skeletons + previous micro-task histories.
+**Source:** `docs/MMA_Support/Tier1_Orchestrator.md:7-19`
+
+---
+**Lifted:** 2026-07-02 (scavenge pass — directive library expansion from unread markdown in `docs/MMA_Support/`)

conductor/directives/tier1_orchestrator_no_implementation/v1.md

@@ -0,0 +1,22 @@
+# Tier 1 orchestrators operate strictly on metadata and architectural summaries — they never read or write implementation code
+
+## What it sees (the contract)
+
+A Tier 1 (Orchestrator / Product Manager) agent receives only:
+
+- The user prompt (the raw feature request)
+- Project meta-state (project TOML, repo rules, allowed languages, dependencies)
+- A repository map (strict file-tree outline — names and paths only)
+- Global architecture docs (high-level markdown like `docs/guide_architecture.md`)
+
+A Tier 1 agent **never** sees raw implementation code, AST skeletons, or previous micro-task histories. Its output is structured metadata (a Track list, a severity tag, an executive summary).
+
+## Why
+
+The Tier 1 model is the most capable and most expensive in the hierarchy. Feeding it raw code burns context that should be reserved for architectural judgment. Per `docs/MMA_Support/Tier1_Orchestrator.md:7`: "It operates strictly on metadata, summaries, and executive-level directives. It **never** sees raw implementation code."
+
+## What this means in practice
+
+- Tier 1 reads `docs/`, `conductor/`, `README.md`, `*.toml` summaries — not `src/*.py` bodies.
+- Tier 1's outputs are JSON arrays (Tracks, Tickets, severity tags), not diffs.
+- If a task arrives that *requires* reading implementation to plan, Tier 1 delegates the read to a Tier 2 worker and waits for the abstract.

conductor/directives/tier3_worker_amnesia/meta.md

@@ -0,0 +1,9 @@
+# tier3_worker_amnesia
+
+## v1
+
+**Why this iteration:** Lifted from `docs/MMA_Support/Tier3_Workers.md:6-7` (the "Amnesiac Workers" framing) + `docs/MMA_Support/Tier3_Workers.md:34` (the "Before submission to Tier 2, the orchestrator wipes the messy trial-and-error history from the payload" rule). The two together encode the contract: workers iterate freely in their own context, but only the clean result is visible upstream.
+**Source:** `docs/MMA_Support/Tier3_Workers.md:6-7 + 34`
+
+---
+**Lifted:** 2026-07-02 (scavenge pass — directive library expansion from unread markdown in `docs/MMA_Support/`)

conductor/directives/tier3_worker_amnesia/v1.md

@@ -0,0 +1,21 @@
+# Tier 3 workers run with stateless context — their trial-and-error history is wiped before submission to prevent context ballooning
+
+## The amnesia contract
+
+A Tier 3 (Worker / Contributor) agent:
+
+- Receives only the ticket prompt + the raw view of the single target file + skeleton views of foreign interfaces.
+- Operates with a short rolling window of recent attempts (last 2-3 iterations) while iterating.
+- **Has its trial-and-error history wiped before the final submission to Tier 2.** The dirty history stays in the worker's memory during the loop; only the final clean diff + a concise completion message reaches the parent.
+
+Per `docs/MMA_Support/Tier3_Workers.md:6-7`: "They are 'Amnesiac Workers,' having their history wiped between tasks to prevent context ballooning."
+
+## Why
+
+LLM context windows have a hard ceiling. Trial-and-error retries (failed lints, wrong imports, off-by-one loops) accumulate fast and crowd out the high-signal "what was actually decided" content. Wiping them between tasks keeps the next worker spawn clean.
+
+## What this means in practice
+
+- The parent's `disc_entries` (or `Conversation` object) gets one new entry from the worker: the clean diff + summary, not the worker's scratch history.
+- Per `docs/MMA_Support/Tier3_Workers.md:34`: "Before submission to Tier 2, the orchestrator wipes the messy trial-and-error history from the payload."
+- The worker's internal retries are persisted to a separate log file for debugging, not into the parent's context.

conductor/directives/tier4_qa_compressed_fix/meta.md

@@ -0,0 +1,9 @@
+# tier4_qa_compressed_fix
+
+## v1
+
+**Why this iteration:** Lifted from `docs/MMA_Support/Tier4_Utility.md:6-7` (the "financial firewall" framing — Tier 4 solves the cost of feeding massive traces back into mid-tier models) + `docs/MMA_Support/Tier4_Utility.md:17` (the "20-50 token surgical string" output spec). Together: Tier 4 is a stateless translator, not a full diagnosis.
+**Source:** `docs/MMA_Support/Tier4_Utility.md:6-7 + 17`
+
+---
+**Lifted:** 2026-07-02 (scavenge pass — directive library expansion from unread markdown in `docs/MMA_Support/`)

conductor/directives/tier4_qa_compressed_fix/v1.md

@@ -0,0 +1,23 @@
+# Tier 4 QA returns a compressed 20-50 token fix — never a full stack trace, never a multi-paragraph diagnosis
+
+## The compression contract
+
+A Tier 4 (Utility / QA) agent:
+
+- Receives only the raw error output (a stack trace or a linter warning) and a 20-line block of the offending code.
+- Returns a single compressed string (20-50 tokens) describing the fix.
+- Wakes up, translates the error, and immediately dies — no persistent memory across calls.
+
+Per `docs/MMA_Support/Tier4_Utility.md:6-7`: "Tier 4 acts as the financial firewall. It solves the expensive problem of feeding massive (e.g., 3,000-token) stack traces back into a mid-tier LLM's context window."
+
+Per `docs/MMA_Support/Tier4_Utility.md:17`: the output is "a surgical, highly compressed string (20-50 tokens) passed back into the Tier 3 Contributor's working memory (e.g., 'Syntax Error on line 42: You missed a closing parenthesis. Add `]`')."
+
+## Why
+
+Massive stack traces (1,000-3,000 tokens of `stderr`) explode the mid-tier model's context window for very little signal. A cheap model can compress the same trace into one sentence that points the worker at the line + the fix.
+
+## What this means in practice
+
+- Tier 4 invocation prompts explicitly say "respond in <= 50 tokens" or "one sentence fix."
+- Tier 4 does not return the raw trace, the full file context, or a multi-paragraph diagnosis — only the fix.
+- Tier 4's full output is logged to `comms.log` for debugging but only the compressed fix enters the worker's working memory.

conductor/directives/token_firewall_prevents_bloat/meta.md

@@ -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/`)

conductor/directives/token_firewall_prevents_bloat/v1.md

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