diff --git a/conductor/product.md b/conductor/product.md index 1fce094..e8d3ce9 100644 --- a/conductor/product.md +++ b/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. diff --git a/conductor/tracks/comprehensive_gui_ux_20260228/metadata.json b/conductor/tracks/comprehensive_gui_ux_20260228/metadata.json index 72093ef..a06ef27 100644 --- a/conductor/tracks/comprehensive_gui_ux_20260228/metadata.json +++ b/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", - "updated_at": "2026-03-01T08:42:57Z" + "status": "refined", + "updated_at": "2026-03-01T15:30:00Z", + "refined_by": "claude-opus-4-6 (1M context)", + "refined_from_commit": "08e003a" } diff --git a/conductor/tracks/comprehensive_gui_ux_20260228/plan.md b/conductor/tracks/comprehensive_gui_ux_20260228/plan.md index 79166dd..6c9e021 100644 --- a/conductor/tracks/comprehensive_gui_ux_20260228/plan.md +++ b/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 -- [ ] 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) +Architecture reference: [docs/guide_architecture.md](../../docs/guide_architecture.md), [docs/guide_mma.md](../../docs/guide_mma.md) -## Phase 2: MMA Orchestration Dashboard & History -- [ ] Task: Implement a multi-viewport docking system for MMA panels. -- [ ] 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 1: Tier Stream Panels & Approval Indicators +Focus: Make all 4 tier output streams visible and indicate pending approvals. -## Phase 3: Interactive Task DAG -- [ ] Task: Build the interactive DAG visualizer using Dear PyGui nodes. -- [ ] Task: Implement logic for node state visualization (Ready, Running, Blocked, Done). -- [ ] Task: Add functionality for manual DAG editing (reorder, insert, delete tasks). -- [ ] Task: Write tests for manual DAG manipulation and synchronization. -- [ ] Task: Conductor - User Manual Verification 'Phase 3: Interactive Task DAG' (Protocol in workflow.md) +- [ ] 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 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 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 1.4: Conductor - User Manual Verification 'Phase 1: Tier Stream Panels & Approval Indicators' (Protocol in workflow.md) -## Phase 4: Execution Clutch & Spawn Interceptor -- [ ] Task: Implement the global "Execution Clutch" (Step Mode vs. Auto-Queue). -- [ ] 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 2: Cost Tracking & Enhanced Token Table +Focus: Add cost estimation to the existing token usage display. -## Phase 5: Metrics & Observability -- [ ] Task: Implement high-density telemetry widgets (FPS, CPU, latency). -- [ ] Task: Add real-time token and cost tracking per tier/track. -- [ ] Task: Integrate API metrics into the Hub/Operations view. -- [ ] Task: Write tests for data aggregation and real-time visualization. -- [ ] Task: Conductor - User Manual Verification 'Phase 5: Metrics & Observability' (Protocol in workflow.md) +- [ ] 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 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 2.3: Write tests for `cost_tracker.estimate_cost()` covering all model patterns and edge cases (unknown model returns 0). +- [ ] Task 2.4: Conductor - User Manual Verification 'Phase 2: Cost Tracking & Enhanced Token Table' (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) diff --git a/conductor/tracks/comprehensive_gui_ux_20260228/spec.md b/conductor/tracks/comprehensive_gui_ux_20260228/spec.md index def5b08..9718b29 100644 --- a/conductor/tracks/comprehensive_gui_ux_20260228/spec.md +++ b/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. -3. **Task DAG Management:** Implement an interactive DAG visualizer that allows the user to reorder, insert, and delete tasks/tickets incrementally. -4. **Tier-Specific Discussion History:** Provide dedicated visual panels for each tier agent's (Orchestrator, Tech Lead, Worker, QA) discussion history and streaming output. -5. **Manual Execution Control:** Ensure every event, task transition, and sub-agent spawn requires manual user acceptance by default, with opt-in automation. -6. **Metrics & Observability:** Integrate real-time telemetry, token usage, and cost tracking for each tier and track. + +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. +2. **DAG Manipulation**: Add/remove tickets from the active track's DAG via the GUI, with dependency validation. +3. **Conductor GUI Forms**: Setup and track creation forms that invoke the same logic as the CLI slash commands. +4. **Track-Scoped Discussions**: Switch the discussion panel to track-specific history when a track is active. +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 History Panels:** Separate viewing modes for the logs/discussions of each tier agent. -- **Execution Clutch:** A global toggle for "Step Mode" vs. "Auto-Queue", with the default being manual step-through. -- **Spawn Interceptor:** An improved modal for reviewing and editing worker prompts/context before they are dispatched. -- **Observability Widgets:** High-density monitors for FPS, CPU, and API metrics (latency, token burn, cost). + +### Tier Stream Panels +- Four collapsible/expandable text regions in the MMA dashboard, one per tier. +- Auto-scroll to bottom on new content. Toggle for manual scroll lock. +- Each stream populated from `self.mma_streams` keyed by tier prefix. +- 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). -- **Asynchronous Responsibility:** The UI must remain responsive during multi-model generation using the `AsyncEventQueue`. -- **Modular Layout:** Support for docking, floating, and rearranging all Conductor/MMA windows. +- **Thread Safety**: All new data mutations from background threads must go through `_pending_gui_tasks`. No direct GUI state writes from non-main threads. +- **No New Dependencies**: Use only existing Dear PyGui / imgui-bundle APIs. +- **Performance**: New panels must not degrade FPS below 30 under normal operation. Verify via `get_ui_performance`. -## Acceptance Criteria -- Users can initialize and manage tracks entirely through the GUI. -- The Task DAG accurately reflects the state of the active track and allows manual editing. -- Each tier agent's history is viewable in a dedicated panel. -- The "Manual Acceptance" flow is enforced for all MMA actions by default. -- API metrics and telemetry are visible and update in real-time. +## Architecture Reference +- Threading model and `_process_pending_gui_tasks` action catalog: [docs/guide_architecture.md](../../docs/guide_architecture.md) +- MMA data structures (Ticket, Track, WorkerContext): [docs/guide_mma.md](../../docs/guide_mma.md) +- Hook API for testing: [docs/guide_tools.md](../../docs/guide_tools.md) +- Simulation patterns: [docs/guide_simulations.md](../../docs/guide_simulations.md) ## Out of Scope -- Automated "Auto-Fix" loops without user intervention. -- Remote management via web browser (staying local GUI for now). +- Automated "Auto-Fix" loops without user intervention. +- 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). diff --git a/conductor/workflow.md b/conductor/workflow.md index 67fa752..5e012f6 100644 --- a/conductor/workflow.md +++ b/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