# Engineering Journal

## 2026-02-28 14:43

### Documentation Framework Implementation
- **What**: Implemented Claude Conductor modular documentation system
- **Why**: Improve AI navigation and code maintainability
- **How**: Used `npx claude-conductor` to initialize framework
- **Issues**: None - clean implementation
- **Result**: Documentation framework successfully initialized

---

---

## 2026-03-02

### Track: context_token_viz_20260301 — Completed |TASK:context_token_viz_20260301|
- **What**: Token budget visualization panel (all 3 phases)
- **Why**: Zero visibility into context window usage; `get_history_bleed_stats` existed but had no UI
- **How**: Extended `get_history_bleed_stats` with `_add_bleed_derived` helper (adds 8 derived fields); added `_render_token_budget_panel` with color-coded progress bar, breakdown table, trim warning, Gemini/Anthropic cache status; 3 auto-refresh triggers (`_token_stats_dirty` flag); `/api/gui/token_stats` endpoint; `--timeout` flag on `claude_mma_exec.py`
- **Issues**: `set_file_slice` dropped `def _render_message_panel` line — caught by outline check, fixed with 1-line insert. Tier 3 delegation via `run_powershell` hard-capped at 60s — implemented changes directly per user approval; added `--timeout` flag for future use.
- **Result**: 17 passing tests, all phases verified by user. Token panel visible in AI Settings under "Token Budget". Commits: 5bfb20f → d577457.

### Next: mma_agent_focus_ux (planned, not yet tracked)
- **What**: Per-agent filtering for MMA observability panels (comms, tool calls, discussion, token budget)
- **Why**: All panels are global/session-scoped; in MMA mode with 4 tiers, data from all agents mixes. No way to isolate what a specific tier is doing.
- **Gap**: `_comms_log` and `_tool_log` have no tier/agent tag. `mma_streams` stream_id is the only per-agent key that exists.
- **See**: conductor/tracks.md for full audit and implementation intent.

---

## 2026-03-02 (Session 2)

### Tracks Initialized: feature_bleed_cleanup + mma_agent_focus_ux |TASK:feature_bleed_cleanup_20260302| |TASK:mma_agent_focus_ux_20260302|
- **What**: Audited codebase for feature bleed; initialized 2 new conductor tracks
- **Why**: Entropy from Tier 2 track implementations — redundant code, dead methods, layout regressions, no tier context in observability
- **Bleed findings** (gui_2.py): Dead duplicate `_render_comms_history_panel` (3041-3073, stale `type` key, wrong method ref); dead `begin_main_menu_bar()` block (1680-1705, Quit has never worked); 4 duplicate `__init__` assignments; double "Token Budget" label with no collapsing header
- **Agent focus findings** (ai_client.py + conductors): No `current_tier` var; Tier 3 swaps callback but never stamps tier; Tier 2 doesn't swap at all; `_tool_log` is untagged tuple list
- **Result**: 2 tracks committed (4f11d1e, c1a86e2). Bleed cleanup is active; agent focus depends on it.

- **More Tracks**: Initialized 'tech_debt_and_test_cleanup_20260302' and 'conductor_workflow_improvements_20260302' to harden TDD discipline, resolve test tech debt (false-positives, dupes), and mandate AST-based codebase auditing.
- **Final Track**: Initialized 'architecture_boundary_hardening_20260302' to fix the GUI HITL bypass allowing direct AST mutations, patch token bloat in `mma_exec.py`, and implement cascading blockers in `dag_engine.py`.
- **Testing Consolidation**: Initialized 'testing_consolidation_20260302' track to standardize simulation testing workflows around the pytest `live_gui` fixture and eliminate redundant `subprocess.Popen` wrappers.
- **Dependency Order**: Added an explicit 'Track Dependency Order' execution guide to `conductor/tracks.md` to ensure safe progression through the accumulated tech debt.
- **Documentation**: Added guide_meta_boundary.md to explicitly clarify the difference between the Application's strict-HITL environment and the autonomous Meta-Tooling environment, helping future Tiers avoid feature bleed.
- **Heuristics & Backlog**: Added Data-Oriented Design and Immediate Mode architectural heuristics (inspired by Muratori/Acton) to product-guidelines.md. Logged future decoupling and robust parsing tracks to a 'Future Backlog' in TASKS.md.

---

## 2026-03-02 (Session 3)

### Track: feature_bleed_cleanup_20260302 — Completed |TASK:feature_bleed_cleanup_20260302|
- **What**: Removed all confirmed dead code and layout regressions from gui_2.py (3 phases)
- **Why**: Tier 3 workers had left behind dead duplicate methods, dead menu block, duplicate state vars, and a broken Token Budget layout that embedded the panel inside Provider & Model with double labels
- **How**:
  - Phase 1: Deleted dead `_render_comms_history_panel` duplicate (stale `type` key, nonexistent `_cb_load_prior_log`, `scroll_area` ID collision). Deleted 4 duplicate `__init__` assignments (ui_new_track_name etc.)
  - Phase 2: Deleted dead `begin_main_menu_bar()` block (24 lines, always-False in HelloImGui). Added working `Quit` to `_show_menus` via `runner_params.app_shall_exit = True`
  - Phase 3: Removed 4 redundant Token Budget labels/call from `_render_provider_panel`. Added `collapsing_header("Token Budget")` to AI Settings with proper `_render_token_budget_panel()` call
- **Issues**: Full test suite hangs (pre-existing — `test_suite_performance_and_flakiness` backlog). Ran targeted GUI/MMA subset (32 passed) as regression proxy. Meta-Level Sanity Check: 52 ruff errors in gui_2.py before and after — zero new violations introduced
- **Result**: All 3 phases verified by user. Checkpoints: be7174c (Phase 1), 15fd786 (Phase 2), 0d081a2 (Phase 3)

---

## 2026-03-02 (Session 4)

### Track: mma_agent_focus_ux_20260302 — Completed |TASK:mma_agent_focus_ux_20260302|
- **What**: Per-tier agent focus UX — source_tier tagging + Focus Agent filter UI (all 3 phases)
- **Why**: All MMA observability panels were global/session-scoped; traffic from Tier 2/3/4 was indistinguishable
- **How**:
  - Phase 1: Added `current_tier: str | None` module var to `ai_client.py`; `_append_comms` stamps `source_tier: current_tier` on every comms entry; `run_worker_lifecycle` sets `"Tier 3"` / `generate_tickets` sets `"Tier 2"` around `send()` calls, clears in `finally`; `_on_tool_log` captures `current_tier` at call time; `_append_tool_log` migrated from tuple to dict with `source_tier` field; `_pending_tool_calls` likewise. Checkpoint: bc1a570
  - Phase 2: `_render_tool_calls_panel` migrated from tuple destructure to dict access. Checkpoint: 865d8dd
  - Phase 3: `ui_focus_agent: str | None` state var added; Focus Agent combo (All/Tier2/3/4) + clear button above OperationsTabs; filter logic in `_render_comms_history_panel` and `_render_tool_calls_panel`; `[source_tier]` label per comms entry header. Checkpoint: b30e563
- **Issues**:
  - `claude_mma_exec.py` fails with nested session block — user authorized inline implementation for this track
  - Task 2.1 set_file_slice applied at shifted line, leaving stale tuple destructure + missing `i = i_minus_one + 1`; caught and fixed in Phase 3 Task 3.4
  - **Known limitation**: `current_tier` is a module-level `str | None` — safe only because MMA engine serializes `send()` calls. Concurrent Tier 3/4 agents (future) will require `threading.local()` or per-ticket context passing. Logged to backlog.
  - **Verification gap noted**: No API hook endpoints expose `ui_focus_agent` state for automated testing. Future tracks should wire widget state to `_settable_fields` for `live_gui` fixture verification. Logged to backlog.
- **Result**: 18 tests passing. Focus Agent combo visible in Operations Hub. Comms entries show `[main]`/`[Tier N]` labels. Meta-Level Sanity Check: 53 ruff errors in gui_2.py before and after — zero new violations.

---

## 2026-03-02 (Session 5)

### Track: tech_debt_and_test_cleanup_20260302 — Botched / Archived
- **What**: Attempted to centralize test fixtures and enforce test discipline. 
- **Issues**: Track was launched with a flawed specification that misidentified critical headless API endpoints as "dead code." While centralized `app_instance` fixtures were successfully deployed, it exposed several zero-assertion tests and exacerbated deep architectural issues with the `asyncio` loop lifecycle, causing widespread `RuntimeError: Event loop is closed` warnings and test hangs.
- **Result**: Track was aborted and archived. A post-mortem `DEBRIEF.md` was generated.

### Strategic Shift: The Strict Execution Queue
- **What**: Systematically audited the Future Backlog and converted all pending technical debt into a strict, 9-track, linearly ordered execution queue in `conductor/tracks.md`.
- **Why**: "Mock-Rot" and stateless Tier 3 entropy. Tier 3 workers were blindly using `unittest.mock.patch` to pass tests without testing integration realities, creating a false sense of security.
- **How**: 
  - Defined the "Surgical Spec Protocol" to force Tier 1/2 agents to map exact `WHERE/WHAT/HOW/SAFETY` targets for workers.
  - Initialized 7 new tracks: `test_stabilization_20260302`, `strict_static_analysis_and_typing_20260302`, `codebase_migration_20260302`, `gui_decoupling_controller_20260302`, `hook_api_ui_state_verification_20260302`, `robust_json_parsing_tech_lead_20260302`, `concurrent_tier_source_tier_20260302`, and `test_suite_performance_and_flakiness_20260302`.
  - Added a highly interactive `manual_ux_validation_20260302` track specifically for tuning GUI animations and structural layout using a slow-mode simulation harness.
- **Result**: The project now has a crystal-clear, heavily guarded roadmap to escape technical debt and transition to a robust, Data-Oriented, type-safe architecture.
## 2026-03-02: Test Suite Stabilization & Simulation Hardening
*   **Track:** Test Suite Stabilization & Consolidation
*   **Outcome:** Track Completed Successfully
*   **Key Accomplishments:**
    *   **Asyncio Lifecycle Fixes:** Eliminated pervasive Event loop is closed and coroutine was never awaited warnings in tests. Refactored conftest.py teardowns and test loop handling.
    *   **Legacy Cleanup:** Completely removed gui_legacy.py and updated all 16 referencing test files to target gui_2.py, consolidating the architecture.
    *   **Functional Assertions:** Replaced pytest.fail placeholders with actual functional assertions in pi_events, execution_engine, 	oken_usage, gent_capabilities, and gent_tools_wiring test suites.
    *   **Simulation Hardening:** Addressed flakiness in 	est_extended_sims.py. Fixed timeouts and entry count regressions by forcing explicit GUI states (uto_add_history=True) during setup, and refactoring wait_for_ai_response to intelligently detect turn completions and tool execution stalls based on status transitions rather than just counting messages.
    *   **Workflow Updates:** Updated conductor/workflow.md to establish a new rule forbidding full suite execution (pytest tests/) during verification to prevent long timeouts and threading access violations. Demanded batch-testing (max 4 files) instead.
    *   **New Track Proposed:** Created sync_tool_execution_20260303 track to introduce concurrent background tool execution, reducing latency during AI research phases.
*   **Challenges:** The extended simulation suite (	est_extended_sims.py) was highly sensitive to the exact transition timings of the mocked gemini_cli and the background threading of gui_2.py. Required multiple iterations of refinement to simulation/workflow_sim.py to achieve stable, deterministic execution. The full test suite run proved unstable due to accumulation of open threads/loops across 360+ tests, necessitating a shift to batch-testing.
