109 lines
11 KiB
Markdown
109 lines
11 KiB
Markdown
# 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**: TASKS.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 `TASKS.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.
|