From bea5d6b151fca1ee90d8abb3adb1d4cbca3b0a36 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Sat, 4 Jul 2026 00:11:15 -0400 Subject: [PATCH] feat(directives): scavenge from docs/MMA_Support/: 5 directives --- .../directives/stub_before_implement/meta.md | 9 ++++++ .../directives/stub_before_implement/v1.md | 26 +++++++++++++++++ .../meta.md | 9 ++++++ .../v1.md | 22 +++++++++++++++ .../directives/tier3_worker_amnesia/meta.md | 9 ++++++ .../directives/tier3_worker_amnesia/v1.md | 21 ++++++++++++++ .../tier4_qa_compressed_fix/meta.md | 9 ++++++ .../directives/tier4_qa_compressed_fix/v1.md | 23 +++++++++++++++ .../token_firewall_prevents_bloat/meta.md | 9 ++++++ .../token_firewall_prevents_bloat/v1.md | 28 +++++++++++++++++++ 10 files changed, 165 insertions(+) create mode 100644 conductor/directives/stub_before_implement/meta.md create mode 100644 conductor/directives/stub_before_implement/v1.md create mode 100644 conductor/directives/tier1_orchestrator_no_implementation/meta.md create mode 100644 conductor/directives/tier1_orchestrator_no_implementation/v1.md create mode 100644 conductor/directives/tier3_worker_amnesia/meta.md create mode 100644 conductor/directives/tier3_worker_amnesia/v1.md create mode 100644 conductor/directives/tier4_qa_compressed_fix/meta.md create mode 100644 conductor/directives/tier4_qa_compressed_fix/v1.md create mode 100644 conductor/directives/token_firewall_prevents_bloat/meta.md create mode 100644 conductor/directives/token_firewall_prevents_bloat/v1.md diff --git a/conductor/directives/stub_before_implement/meta.md b/conductor/directives/stub_before_implement/meta.md new file mode 100644 index 00000000..50b01984 --- /dev/null +++ b/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/`) \ No newline at end of file diff --git a/conductor/directives/stub_before_implement/v1.md b/conductor/directives/stub_before_implement/v1.md new file mode 100644 index 00000000..58988096 --- /dev/null +++ b/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). \ No newline at end of file diff --git a/conductor/directives/tier1_orchestrator_no_implementation/meta.md b/conductor/directives/tier1_orchestrator_no_implementation/meta.md new file mode 100644 index 00000000..7a1f2cf5 --- /dev/null +++ b/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/`) \ No newline at end of file diff --git a/conductor/directives/tier1_orchestrator_no_implementation/v1.md b/conductor/directives/tier1_orchestrator_no_implementation/v1.md new file mode 100644 index 00000000..56307e14 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/conductor/directives/tier3_worker_amnesia/meta.md b/conductor/directives/tier3_worker_amnesia/meta.md new file mode 100644 index 00000000..5fa322fe --- /dev/null +++ b/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/`) \ No newline at end of file diff --git a/conductor/directives/tier3_worker_amnesia/v1.md b/conductor/directives/tier3_worker_amnesia/v1.md new file mode 100644 index 00000000..a8ce6a0d --- /dev/null +++ b/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. \ No newline at end of file diff --git a/conductor/directives/tier4_qa_compressed_fix/meta.md b/conductor/directives/tier4_qa_compressed_fix/meta.md new file mode 100644 index 00000000..8d2f516b --- /dev/null +++ b/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/`) \ No newline at end of file diff --git a/conductor/directives/tier4_qa_compressed_fix/v1.md b/conductor/directives/tier4_qa_compressed_fix/v1.md new file mode 100644 index 00000000..65b19f3b --- /dev/null +++ b/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. \ No newline at end of file diff --git a/conductor/directives/token_firewall_prevents_bloat/meta.md b/conductor/directives/token_firewall_prevents_bloat/meta.md new file mode 100644 index 00000000..f236f746 --- /dev/null +++ b/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/`) \ No newline at end of file diff --git a/conductor/directives/token_firewall_prevents_bloat/v1.md b/conductor/directives/token_firewall_prevents_bloat/v1.md new file mode 100644 index 00000000..51cee28f --- /dev/null +++ b/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. \ No newline at end of file