conductor: Refine GUI UX track with full codebase knowledge, add doc references

Rewrites comprehensive_gui_ux_20260228 spec and plan using deep analysis of
the actual gui_2.py implementation (3078 lines). The previous spec asked to
implement features that already exist (Track Browser, DAG tree, epic planning,
approval dialogs, token table, performance monitor). The new spec:

- Documents 15 already-implemented features with exact line references
- Identifies 8 actual gaps (tier stream panels, DAG editing, cost tracking,
  conductor lifecycle forms, track-scoped discussions, approval indicators,
  track proposal editing, stream scrollability)
- Rewrites all 5 phases with surgical task descriptions referencing exact
  gui_2.py line ranges, function names, and data structures
- Each task specifies the precise imgui API calls to use
- References docs/guide_architecture.md for threading constraints
- References docs/guide_mma.md for Ticket/Track data structures

Also adds architecture documentation fallback references to:
- conductor/workflow.md (new principle #9)
- conductor/product.md (new Architecture Reference section)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

conductor/product.md

@@ -1,7 +1,14 @@
 # Product Guide: Manual Slop
 
 ## Vision
-To serve as an expert-level utility for personal developer use on small projects, providing full, manual control over vendor API metrics, agent capabilities, and context memory usage. 
+To serve as an expert-level utility for personal developer use on small projects, providing full, manual control over vendor API metrics, agent capabilities, and context memory usage.
+
+## Architecture Reference
+For deep implementation details when planning or implementing tracks, consult `docs/` (last updated: 08e003a):
+- **[docs/guide_architecture.md](../docs/guide_architecture.md):** Threading model, event system, AI client, HITL mechanism
+- **[docs/guide_tools.md](../docs/guide_tools.md):** MCP Bridge, Hook API, ApiHookClient, shell runner
+- **[docs/guide_mma.md](../docs/guide_mma.md):** 4-tier orchestration, DAG engine, worker lifecycle
+- **[docs/guide_simulations.md](../docs/guide_simulations.md):** Test framework, mock provider, verification patterns
 
 ## Primary Use Cases
 - **Full Control over Vendor APIs:** Exposing detailed API metrics and configuring deep agent capabilities directly within the GUI.

conductor/tracks/comprehensive_gui_ux_20260228/metadata.json

@@ -1,8 +1,10 @@
 {
-    "description":  "Implmeent missing GUI UX for controlling all aspects of the conductor and mma feature set.",
+    "description":  "Enhance existing MMA orchestration GUI: tier stream panels, DAG editing, cost tracking, conductor lifecycle forms, track-scoped discussions, approval indicators, visual polish.",
     "track_id":  "comprehensive_gui_ux_20260228",
     "type":  "feature",
     "created_at":  "2026-03-01T08:42:57Z",
-    "status":  "new",
+    "status":  "refined",
-    "updated_at":  "2026-03-01T08:42:57Z"
+    "updated_at":  "2026-03-01T15:30:00Z",
+    "refined_by":  "claude-opus-4-6 (1M context)",
+    "refined_from_commit":  "08e003a"
 }

conductor/tracks/comprehensive_gui_ux_20260228/plan.md

@@ -1,37 +1,47 @@
 # Implementation Plan: Comprehensive Conductor & MMA GUI UX
 
-## Phase 1: Track Lifecycle & Management UI
+Architecture reference: [docs/guide_architecture.md](../../docs/guide_architecture.md), [docs/guide_mma.md](../../docs/guide_mma.md)
-- [ ] Task: Implement the Track Browser panel.
-- [ ] Task: Add GUI forms for `/conductor:setup` and `/conductor:newTrack`.
-- [ ] Task: Create a visual indicator for "Active Track" and its status.
-- [ ] Task: Write tests for Track initialization via GUI.
-- [ ] Task: Conductor - User Manual Verification 'Phase 1: Track Lifecycle & Management UI' (Protocol in workflow.md)
 
-## Phase 2: MMA Orchestration Dashboard & History
+## Phase 1: Tier Stream Panels & Approval Indicators
-- [ ] Task: Implement a multi-viewport docking system for MMA panels.
+Focus: Make all 4 tier output streams visible and indicate pending approvals.
-- [ ] Task: Create dedicated view panels for each Tier (Orchestrator, Tech Lead, Worker, QA).
-- [ ] Task: Implement real-time streaming for each tier's discussion history.
-- [ ] Task: Apply arcade-style "blinking" and color-coded status indicators.
-- [ ] Task: Write tests for asynchronous log streaming and UI updates.
-- [ ] Task: Conductor - User Manual Verification 'Phase 2: MMA Orchestration Dashboard & History' (Protocol in workflow.md)
 
-## Phase 3: Interactive Task DAG
+- [ ] Task 1.1: Replace the single Tier 1 strategy text box in `_render_mma_dashboard` (gui_2.py:2700-2701) with four collapsible sections — one per tier. Each section uses `imgui.collapsing_header(f"Tier {N}: {label}")` wrapping a `begin_child` scrollable region (200px height). Tier 1 = "Strategy", Tier 2 = "Tech Lead", Tier 3 = "Workers", Tier 4 = "QA". Tier 3 should aggregate all `mma_streams` keys containing "Tier 3" with ticket ID sub-headers. Each section auto-scrolls to bottom when new content arrives (track previous scroll position, scroll only if user was at bottom).
-- [ ] Task: Build the interactive DAG visualizer using Dear PyGui nodes.
+- [ ] Task 1.2: Add approval state indicators to the MMA dashboard. After the "Status:" line in `_render_mma_dashboard` (gui_2.py:2672-2676), check `self._pending_mma_spawn`, `self._pending_mma_approval`, and `self._pending_ask_dialog`. When any is active, render a colored blinking badge: `imgui.text_colored(ImVec4(1,0.3,0.3,1), "APPROVAL PENDING")` using `sin(time.time()*5)` for alpha pulse. Also add a `imgui.same_line()` button "Go to Approval" that scrolls/focuses the relevant dialog.
-- [ ] Task: Implement logic for node state visualization (Ready, Running, Blocked, Done).
+- [ ] Task 1.3: Write unit tests verifying: (a) `mma_streams` with keys "Tier 1", "Tier 2 (Tech Lead)", "Tier 3: T-001", "Tier 4 (QA)" are all rendered (check by mocking `imgui.collapsing_header` calls); (b) approval indicators appear when `_pending_mma_spawn is not None`.
-- [ ] Task: Add functionality for manual DAG editing (reorder, insert, delete tasks).
+- [ ] Task 1.4: Conductor - User Manual Verification 'Phase 1: Tier Stream Panels & Approval Indicators' (Protocol in workflow.md)
-- [ ] Task: Write tests for manual DAG manipulation and synchronization.
-- [ ] Task: Conductor - User Manual Verification 'Phase 3: Interactive Task DAG' (Protocol in workflow.md)
 
-## Phase 4: Execution Clutch & Spawn Interceptor
+## Phase 2: Cost Tracking & Enhanced Token Table
-- [ ] Task: Implement the global "Execution Clutch" (Step Mode vs. Auto-Queue).
+Focus: Add cost estimation to the existing token usage display.
-- [ ] Task: Build the "Approve Worker Spawn" modal with prompt and context editing.
-- [ ] Task: Add explicit "Accept" buttons for all major orchestration transitions.
-- [ ] Task: Write tests for "Human-in-the-Loop" flow and blocking behaviors.
-- [ ] Task: Conductor - User Manual Verification 'Phase 4: Execution Clutch & Spawn Interceptor' (Protocol in workflow.md)
 
-## Phase 5: Metrics & Observability
+- [ ] Task 2.1: Create a new module `cost_tracker.py` with a `MODEL_PRICING` dict mapping model name patterns to `{"input_per_mtok": float, "output_per_mtok": float}`. Include entries for: `gemini-2.5-flash-lite` ($0.075/$0.30), `gemini-2.5-flash` ($0.15/$0.60), `gemini-3-flash-preview` ($0.15/$0.60), `gemini-3.1-pro-preview` ($3.50/$10.50), `claude-*-sonnet` ($3/$15), `claude-*-opus` ($15/$75), `deepseek-v3` ($0.27/$1.10). Function: `estimate_cost(model: str, input_tokens: int, output_tokens: int) -> float` that does pattern matching on model name and returns dollar cost.
-- [ ] Task: Implement high-density telemetry widgets (FPS, CPU, latency).
+- [ ] Task 2.2: Extend the token usage table in `_render_mma_dashboard` (gui_2.py:2685-2699) from 3 columns to 5: add "Est. Cost" and "Model". Populate using `cost_tracker.estimate_cost()` with the model name from `self.mma_tier_usage` (need to extend `tier_usage` dict in `ConductorEngine._push_state` to include model name per tier, or use a default mapping: Tier 1 → `gemini-3.1-pro-preview`, Tier 2 → `gemini-3-flash-preview`, Tier 3 → `gemini-2.5-flash-lite`, Tier 4 → `gemini-2.5-flash-lite`). Show total cost row at bottom.
-- [ ] Task: Add real-time token and cost tracking per tier/track.
+- [ ] Task 2.3: Write tests for `cost_tracker.estimate_cost()` covering all model patterns and edge cases (unknown model returns 0).
-- [ ] Task: Integrate API metrics into the Hub/Operations view.
+- [ ] Task 2.4: Conductor - User Manual Verification 'Phase 2: Cost Tracking & Enhanced Token Table' (Protocol in workflow.md)
-- [ ] Task: Write tests for data aggregation and real-time visualization.
+
-- [ ] Task: Conductor - User Manual Verification 'Phase 5: Metrics & Observability' (Protocol in workflow.md)
+## Phase 3: Track Proposal Editing & Conductor Lifecycle Forms
+Focus: Make track proposals editable and add conductor setup/newTrack GUI forms.
+
+- [ ] Task 3.1: Enhance `_render_track_proposal_modal` (gui_2.py:2146-2173) to make track titles and goals editable. Replace `imgui.text_colored` for title with `imgui.input_text(f"##track_title_{idx}", track['title'])`. Replace `imgui.text_wrapped` for goal with `imgui.input_text_multiline(f"##track_goal_{idx}", track['goal'], ImVec2(-1, 60))`. Add a "Remove" button per track (`imgui.button(f"Remove##{idx}")`) that pops from `self.proposed_tracks`. Edited values must be written back to `self.proposed_tracks[idx]`.
+- [ ] Task 3.2: Add a "Conductor Setup" collapsible section at the top of the MMA dashboard (before the Track Browser). Contains a "Run Setup" button. On click, reads `conductor/workflow.md`, `conductor/tech-stack.md`, `conductor/product.md` using `Path.read_text()`, computes a readiness summary (files found, line counts, track count via `project_manager.get_all_tracks()`), and displays it in a read-only text region. This is informational only — no backend changes.
+- [ ] Task 3.3: Add a "New Track" form below the Track Browser. Fields: track name (input_text), description (input_text_multiline), type dropdown (feature/chore/fix via `imgui.combo`). "Create" button calls a new helper `_cb_create_track(name, desc, type)` that: creates `conductor/tracks/{name}_{date}/` directory, writes a minimal `spec.md` from the description, writes an empty `plan.md` template, writes `metadata.json` with the track ID/type/status="new", then refreshes `self.tracks` via `project_manager.get_all_tracks()`.
+- [ ] Task 3.4: Write tests for track creation helper: verify directory structure, file contents, and metadata.json format. Test proposal modal editing by verifying `proposed_tracks` list is mutated correctly.
+- [ ] Task 3.5: Conductor - User Manual Verification 'Phase 3: Track Proposal Editing & Conductor Lifecycle Forms' (Protocol in workflow.md)
+
+## Phase 4: DAG Editing & Track-Scoped Discussion
+Focus: Allow GUI-based ticket manipulation and track-specific discussion history.
+
+- [ ] Task 4.1: Add an "Add Ticket" button below the Task DAG section in `_render_mma_dashboard`. On click, show an inline form: ticket ID (input_text, default auto-increment like "T-NNN"), description (input_text_multiline), target_file (input_text), depends_on (multi-select or comma-separated input of existing ticket IDs). "Create" button appends a new `Ticket` dict to `self.active_tickets` with `status="todo"` and triggers `_push_mma_state_update()` to synchronize the ConductorEngine. Cancel hides the form. Store the form visibility in `self._show_add_ticket_form: bool`.
+- [ ] Task 4.2: Add a "Delete" button to each DAG node in `_render_ticket_dag_node` (gui_2.py:2770-2773, after the Skip button). On click, show a confirmation popup. On confirm, remove the ticket from `self.active_tickets`, remove it from all other tickets' `depends_on` lists, and push state update. Only allow deletion of `todo` or `blocked` tickets (not `in_progress` or `completed`).
+- [ ] Task 4.3: Add track-scoped discussion support. In `_render_discussion_panel` (gui_2.py:2295-2483), add a toggle checkbox "Track Discussion" (visible only when `self.active_track` is set). When toggled ON: load history via `project_manager.load_track_history(self.active_track.id, base_dir)` into `self.disc_entries`, set a flag `self._track_discussion_active = True`. When toggled OFF or track changes: restore project discussion. On save/flush, if `_track_discussion_active`, write to track history file instead of project history.
+- [ ] Task 4.4: Write tests for: (a) adding a ticket updates `active_tickets` and has correct default fields; (b) deleting a ticket removes it from all `depends_on` references; (c) track discussion toggle switches `disc_entries` source.
+- [ ] Task 4.5: Conductor - User Manual Verification 'Phase 4: DAG Editing & Track-Scoped Discussion' (Protocol in workflow.md)
+
+## Phase 5: Visual Polish & Integration Testing
+Focus: Dense, responsive dashboard with arcade aesthetics and end-to-end verification.
+
+- [ ] Task 5.1: Add color-coded styling to the Track Browser table. Status column uses colored text: "new" = gray, "active" = yellow, "done" = green, "blocked" = red. Progress bar uses `imgui.push_style_color` to tint: <33% red, 33-66% yellow, >66% green.
+- [ ] Task 5.2: Improve the DAG tree nodes with status-colored left borders. Use `imgui.get_cursor_screen_pos()` and `imgui.get_window_draw_list().add_rect_filled()` to draw a 4px colored strip to the left of each tree node matching its status color.
+- [ ] Task 5.3: Add a "Dashboard Summary" header line at the top of `_render_mma_dashboard` showing: `Track: {name} | Tickets: {done}/{total} | Cost: ${total_cost:.4f} | Status: {mma_status}` in a single dense line with colored segments.
+- [ ] Task 5.4: Write an end-to-end integration test (extending `tests/visual_sim_mma_v2.py` or creating `tests/visual_sim_gui_ux.py`) that verifies via `ApiHookClient`: (a) track creation form produces correct directory structure; (b) tier streams are populated during MMA execution; (c) approval indicators appear when expected; (d) cost tracking shows non-zero values after execution.
+- [ ] Task 5.5: Verify all new UI elements maintain >30 FPS via `get_ui_performance` during a full MMA simulation run.
+- [ ] Task 5.6: Conductor - User Manual Verification 'Phase 5: Visual Polish & Integration Testing' (Protocol in workflow.md)

conductor/tracks/comprehensive_gui_ux_20260228/spec.md

@@ -1,36 +1,99 @@
 # Track Specification: Comprehensive Conductor & MMA GUI UX
 
 ## Overview
-This track aims to implement a comprehensive, high-density, and tactile GUI for controlling all aspects of the Conductor orchestration and the 4-Tier Hierarchical Multi-Model Architecture (MMA). The focus is on providing the user with explicit, granular control over the entire lifecycle of a track, from initialization to task execution, with a "Manual First" philosophy.
+
+This track enhances the existing MMA orchestration GUI from its current functional-but-minimal state to a production-quality control surface. The existing implementation already has a working Track Browser, DAG tree visualizer, epic planning flow, approval dialogs, and token usage table. This track focuses on the **gaps**: dedicated tier stream panels, DAG editing, track-scoped discussions, conductor lifecycle GUI forms, cost tracking, and visual polish.
+
+## Current State Audit (as of 08e003a)
+
+### Already Implemented (DO NOT re-implement)
+- **Track Browser table** (`_render_mma_dashboard`, lines 2633-2660): Title, status, progress bar, Load button per track.
+- **Epic Planning** (`_render_projects_panel`, lines 1968-1983 + `_cb_plan_epic`): Input field + "Plan Epic (Tier 1)" button, background thread orchestration.
+- **Track Proposal Modal** (`_render_track_proposal_modal`, lines 2146-2173): Shows proposed tracks, Start/Accept/Cancel.
+- **Step Mode toggle**: Checkbox for "Step Mode (HITL)" with `self.mma_step_mode`.
+- **Active Track Info**: Description + ticket progress bar.
+- **Token Usage Table**: Per-tier input/output display in a 3-column ImGui table.
+- **Tier 1 Strategy Stream**: `mma_streams.get("Tier 1")` rendered as read-only multiline (150px).
+- **Task DAG Tree** (`_render_ticket_dag_node`, lines 2726-2785): Recursive tree with color-coded status (gray/yellow/green/red/orange), tooltips showing ID/target/description/dependencies/worker-stream, Retry/Skip buttons.
+- **Spawn Interceptor** (`MMASpawnApprovalDialog`): Editable prompt, context_md, abort capability.
+- **MMA Step Approval** (`MMAApprovalDialog`): Editable payload, approve/reject.
+- **Script Confirmation** (`ConfirmDialog`): Editable script, approve/reject.
+- **Comms History Panel** (`_render_comms_history_panel`, lines 2859-2984).
+- **Tool Calls Panel** (`_render_tool_calls_panel`, lines 2787-2857).
+- **Performance Monitor**: FPS, Frame Time, CPU, Input Lag via `perf_monitor`.
+
+### Gaps to Fill (This Track's Scope)
+
+1. **Tier Stream Panels**: Only Tier 1 gets a dedicated text box. Tier 2/3/4 streams exist in `mma_streams` dict but have no dedicated UI. Tier 3 output is tooltip-only on DAG nodes. No Tier 2 (Tech Lead) or Tier 4 (QA) visibility at all.
+2. **DAG Editing**: Can Retry/Skip tickets but cannot reorder, insert, or delete tasks from the GUI.
+3. **Conductor Lifecycle Forms**: `/conductor:setup` and `/conductor:newTrack` have no GUI equivalents — they're CLI-only. Users must use slash commands or the epic planning flow.
+4. **Track-Scoped Discussion**: Discussions are global. When a track is active, the discussion panel should optionally isolate to that track's context. `project_manager.load_track_history()` exists but isn't wired to the GUI.
+5. **Cost Estimation**: Token counts are displayed but not converted to estimated cost per tier or per track.
+6. **Approval State Indicators**: The dashboard doesn't visually indicate when a spawn/step/tool approval is pending. `pending_mma_spawn_approval`, `pending_mma_step_approval`, `pending_tool_approval` are tracked but not rendered.
+7. **Track Proposal Editing**: The modal shows proposed tracks read-only. No ability to edit track titles, goals, or remove unwanted tracks before accepting.
+8. **Stream Scrollability**: Tier 1 stream is a 150px non-scrolling text box. Needs proper scrollable, resizable panels for all tier streams.
 
 ## Goals
-1.  **Conductor Lifecycle Management:** Implement UI components for `/conductor:setup`, `/conductor:newTrack`, and a robust Track Browser.
+
-2.  **MMA Orchestration Dashboard:** Create a multi-viewport modular system for monitoring and managing the 4-Tier hierarchy.
+1. **Tier Stream Visibility**: Dedicated, scrollable panels for all 4 tier output streams (Tier 1 Strategy, Tier 2 Tech Lead, Tier 3 Worker, Tier 4 QA) with auto-scroll and copy support.
-3.  **Task DAG Management:** Implement an interactive DAG visualizer that allows the user to reorder, insert, and delete tasks/tickets incrementally.
+2. **DAG Manipulation**: Add/remove tickets from the active track's DAG via the GUI, with dependency validation.
-4.  **Tier-Specific Discussion History:** Provide dedicated visual panels for each tier agent's (Orchestrator, Tech Lead, Worker, QA) discussion history and streaming output.
+3. **Conductor GUI Forms**: Setup and track creation forms that invoke the same logic as the CLI slash commands.
-5.  **Manual Execution Control:** Ensure every event, task transition, and sub-agent spawn requires manual user acceptance by default, with opt-in automation.
+4. **Track-Scoped Discussions**: Switch the discussion panel to track-specific history when a track is active.
-6.  **Metrics & Observability:** Integrate real-time telemetry, token usage, and cost tracking for each tier and track.
+5. **Cost Tracking**: Per-tier and per-track cost estimation based on model pricing.
+6. **Approval Indicators**: Clear visual cues (blinking, color changes) when any approval gate is pending.
+7. **Track Proposal Editing**: Allow editing/removing proposed tracks before acceptance.
+8. **Polish & Density**: Make the dashboard information-dense and responsive to the MMA engine's state.
 
 ## Functional Requirements
--   **Track Browser:** A central hub for viewing, selecting, and managing implementation tracks.
+
--   **Interactive Task DAG:** A node-based UI (using Dear PyGui) for visualizing task dependencies. Users can manually manipulate the graph (reorder, add, remove nodes).
+### Tier Stream Panels
--   **Tier History Panels:** Separate viewing modes for the logs/discussions of each tier agent.
+- Four collapsible/expandable text regions in the MMA dashboard, one per tier.
--   **Execution Clutch:** A global toggle for "Step Mode" vs. "Auto-Queue", with the default being manual step-through.
+- Auto-scroll to bottom on new content. Toggle for manual scroll lock.
--   **Spawn Interceptor:** An improved modal for reviewing and editing worker prompts/context before they are dispatched.
+- Each stream populated from `self.mma_streams` keyed by tier prefix.
--   **Observability Widgets:** High-density monitors for FPS, CPU, and API metrics (latency, token burn, cost).
+- Tier 3 streams: aggregate all `"Tier 3: T-xxx"` keyed entries, render with ticket ID headers.
+
+### DAG Editing
+- "Add Ticket" button: opens an inline form (ID, description, target_file, depends_on dropdown).
+- "Remove Ticket" button on each DAG node (with confirmation).
+- Changes must update `self.active_tickets`, rebuild the ConductorEngine's `TrackDAG`, and push state via `_push_state`.
+
+### Conductor Lifecycle Forms
+- "Setup Conductor" button that reads `conductor/workflow.md`, `conductor/tech-stack.md`, `conductor/product.md` and displays a readiness summary.
+- "New Track" form: name, description, type dropdown. Creates the track directory structure under `conductor/tracks/`.
+
+### Track-Scoped Discussion
+- When `self.active_track` is set, add a toggle "Track Discussion" that switches to `project_manager.load_track_history(track_id)`.
+- Saving flushes to the track's history file instead of the project's.
+
+### Cost Tracking
+- Model pricing table (configurable or hardcoded initial version).
+- Compute `cost = (input_tokens / 1M) * input_price + (output_tokens / 1M) * output_price` per tier.
+- Display as additional column in the existing token usage table.
+
+### Approval Indicators
+- When `_pending_mma_spawn` is not None: flash the "MMA Dashboard" tab header or show a blinking indicator.
+- When `_pending_mma_approval` is not None: similar.
+- When `_pending_ask_dialog` is True: similar.
+- Use `imgui.push_style_color` to tint the relevant UI region.
+
+### Track Proposal Editing
+- Make track titles and goals editable in the proposal modal.
+- Add a "Remove" button per proposed track.
+- Edited data flows back to `self.proposed_tracks` before acceptance.
 
 ## Non-Functional Requirements
--   **Arcade Aesthetics:** Use blinking notifications, visceral color-coded feedback (Ready, Running, Blocked, Done), and high-contrast visuals (USA Graphics style).
+- **Thread Safety**: All new data mutations from background threads must go through `_pending_gui_tasks`. No direct GUI state writes from non-main threads.
--   **Asynchronous Responsibility:** The UI must remain responsive during multi-model generation using the `AsyncEventQueue`.
+- **No New Dependencies**: Use only existing Dear PyGui / imgui-bundle APIs.
--   **Modular Layout:** Support for docking, floating, and rearranging all Conductor/MMA windows.
+- **Performance**: New panels must not degrade FPS below 30 under normal operation. Verify via `get_ui_performance`.
 
-## Acceptance Criteria
+## Architecture Reference
--   Users can initialize and manage tracks entirely through the GUI.
+- Threading model and `_process_pending_gui_tasks` action catalog: [docs/guide_architecture.md](../../docs/guide_architecture.md)
--   The Task DAG accurately reflects the state of the active track and allows manual editing.
+- MMA data structures (Ticket, Track, WorkerContext): [docs/guide_mma.md](../../docs/guide_mma.md)
--   Each tier agent's history is viewable in a dedicated panel.
+- Hook API for testing: [docs/guide_tools.md](../../docs/guide_tools.md)
--   The "Manual Acceptance" flow is enforced for all MMA actions by default.
+- Simulation patterns: [docs/guide_simulations.md](../../docs/guide_simulations.md)
--   API metrics and telemetry are visible and update in real-time.
 
 ## Out of Scope
--   Automated "Auto-Fix" loops without user intervention.
+- Automated "Auto-Fix" loops without user intervention.
--   Remote management via web browser (staying local GUI for now).
+- Remote management via web browser.
+- Visual diagram generation (Dear PyGui node editor for DAG — future track).
+- Docking/floating multi-viewport layout (requires imgui docking branch investigation — future track).

conductor/workflow.md

@@ -10,6 +10,11 @@
 6. **Non-Interactive & CI-Aware:** Prefer non-interactive commands. Use `CI=true` for watch-mode tools (tests, linters) to ensure single execution.
 7. **MMA Tiered Delegation is Mandatory:** The Conductor acts as a Tier 1/2 Orchestrator. You MUST delegate all non-trivial coding to Tier 3 Workers and all error analysis to Tier 4 QA Agents. Do NOT perform large file writes directly.
 8. **Mandatory Research-First Protocol:** Before reading the full content of any file over 50 lines, you MUST use `get_file_summary`, `py_get_skeleton`, `py_get_code_outline`, or `py_get_docstring` to map the architecture and identify specific target ranges. Use `get_git_diff` to understand recent changes. Use `py_find_usages` to locate where symbols are used.
+9. **Architecture Documentation Fallback:** When uncertain about threading, event flow, data structures, or module interactions, consult the deep-dive docs in `docs/` (last updated: 08e003a):
+   - **[docs/guide_architecture.md](../docs/guide_architecture.md):** Thread domains, cross-thread patterns (AsyncEventQueue, guarded lists, Condition dialogs), frame-sync mechanism (`_process_pending_gui_tasks` action catalog), AI client multi-provider architecture, HITL Execution Clutch blocking flow.
+   - **[docs/guide_tools.md](../docs/guide_tools.md):** MCP Bridge 3-layer security model, full 26-tool inventory with parameters, Hook API endpoint reference (GET/POST), ApiHookClient method reference, `/api/ask` synchronous HITL protocol.
+   - **[docs/guide_mma.md](../docs/guide_mma.md):** Ticket/Track/WorkerContext data structures, DAG engine algorithms, ConductorEngine execution loop, Tier 2 ticket generation, Tier 3 worker lifecycle with context amnesia.
+   - **[docs/guide_simulations.md](../docs/guide_simulations.md):** `live_gui` fixture, Puppeteer pattern, mock provider protocol, visual verification patterns.
 
 ## Task Workflow