ROOT CAUSE: Each _push_em/_push_strong/_push_bold/etc. method called
imgui.push_style_color TWICE in a row with the same color. Then
_emit_styled_text's pop loop did 'for _ in range(pushed):
imgui.pop_style_color(); imgui.pop_style_color()' — popping 2x per
count. Net effect: 2 pushes canceled by 2 pops. The dim color for
em/code/strong was never actually applied to any text.
This is why 'table isn't properly rendering text based on annotation
syntax' — backticks were stripped by MD4C, the inline code was
emitted via text_wrapped, but the dim color was never pushed (push
canceled by pop), so the rendered text looked identical to body text.
FIX: Each _push_* method now pushes 1 style color. The pop loop now
pops 1 per count. Net: 1 push, 1 pop. The dim color is actually
applied to the text.
43/43 tests pass.
ROOT CAUSE: imgui.small_button(text) uses the text as the widget ID.
When the same inline code text appears multiple times in a rendered
markdown (e.g., the same function name in a table), imgui triggers
'3 visible items with conflicting ID' warning.
The C++ imgui-md SPAN_CODE callback is empty (renders as plain text).
Match that behavior: use text_wrapped with a slightly dimmed color
to indicate code spans. No widget ID, no conflicts.
ALSO: Added token cache to avoid re-parsing markdown every frame.
Each markdown-it-py parse is ~1ms; for static content re-rendered
every frame during scroll, the cache is the difference between smooth
and choppy. Cache is bounded to 64 entries (LRU-ish clear when full).
TESTS:
- test_renderer_renders_inline_code_with_button -> renamed intent,
now asserts text_wrapped is called and a dimmed color is pushed
- test_render_handles_inline_code -> same update
- 2 new tests: test_renderer_caches_parsed_tokens, test_renderer_cache_invalidates_on_text_change
43/43 markdown tests pass.
The imgui-bundle 1.92.5 API changed:
OLD: imgui.get_style().colors[imgui.Col_.text]
NEW: imgui.get_style().color_(imgui.Col_.text)
The Style object no longer has a 'colors' dict; it has a 'color_'
method that takes a Col_ enum and returns the ImVec4 color.
Updated all 9 call sites in md_renderer_py.py and the test mocks
in test_md_renderer_py.py, test_markdown_helper_bullets.py, and
test_markdown_render_robust.py.
42/42 tests pass.
The imgui_bundle imgui.push_font() signature is:
push_font(font: ImFont | None, font_size_base_unscaled: float) -> None
We were calling it with one arg (the font). This crashed imgui at
runtime, leaving imscope in a broken state and cascading to
subsequent scope errors (Missing EndGroup, PopID too many times,
Size > 0).
Since we don't have a separate heading font configured, just skip
the font push for headings. Headings render at the default font size
and use a separator (for h1/h2) to look distinct. User can subclass
MarkdownRenderer and override _handle_heading_open to add a custom
font later.
REMOVED: _get_heading_font method (no longer needed)
The C++ imgui_md.MarkdownOptions is still needed by
immapp.AddOnsParams(with_markdown_options=...) which is passed to
immapp.run() in src/gui_2.py:430. The Python port in src/md_renderer_py
is for OUR renderer; the immapp markdown viewer is a separate thing
that uses the C++ library internally.
Both are wired:
- self.options: C++ imgui_md.MarkdownOptions for immapp.AddOnsParams
- self._py_renderer: Python port for our body content rendering
- Both share the on_open_link callback (webbrowser.open / IDE)
This fix unblocks 'uv run sloppy.py' which was crashing on
'MarkdownRenderer' object has no attribute 'options'
ADD src/md_renderer_py.py: Full port of mekhontsev/imgui_md to pure Python.
- Uses markdown-it-py (already a transitive dep) for AST parsing.
- Walks the token tree, calling imgui primitives directly.
- Mirrors the C++ API surface: MarkdownOptions, MarkdownCallbacks,
MarkdownRenderer.render(), render_unindented().
- Code blocks delegated via set_external_code_block_handler callback.
- All other content (paragraphs, headings, lists, code, tables, hr,
emphasis, strong, links, blockquotes) rendered natively.
ROOT CAUSE OF BULLET OVERLAP (now fixed at the source):
imgui-md C++ BLOCK_P guards NewLine() behind 'if (!m_list_stack.empty())'
(imgui_md.cpp line ~145). Inside lists, paragraph transitions don't
advance the cursor Y. The Python port calls imgui.new_line() explicitly
between paragraphs in a list item, eliminating the overlap.
ROOT CAUSE OF '*' BULLET Y-OVERLAP (now fixed at the source):
imgui-md C++ BLOCK_LI for '*' delim calls ImGui::Bullet() without
ImGui::SameLine() (imgui_md.cpp line ~95). The Python port calls
imgui.bullet() + imgui.same_line() for all markers uniformly.
REMOVED in src/markdown_helper.py:
- _normalize_bullet_delimiters (no longer needed)
- _normalize_nested_list_endings (no longer needed)
- _normalize_list_continuations (no longer needed)
- parse_tables / render_table (renderer handles tables natively)
- All 'imgui_md' body rendering (replaced by Python port)
TESTS:
- tests/test_md_renderer_py.py (new): 16 unit tests for the Python port
covering paragraphs, headings, lists, nested lists, emphasis, strong,
code, links, tables, hr, unindented.
- tests/test_markdown_helper_bullets.py (rewritten): 13 tests for the
integration with the public MarkdownRenderer class.
- tests/test_markdown_render_robust.py (updated): 2 tests verifying
table content is routed through the new Python renderer (not imgui_md).
- tests/test_markdown_table.py / _render.py / _columns.py / _wrapped.py:
unchanged (test the standalone render_table which is still used by
the new renderer as a fallback for any unhandled cases).
42/42 markdown tests pass. 1-space indentation. 1 C++ dependency
removed (imgui_md is no longer used at runtime).
NOT FIXED (known limitations of the new renderer):
- Inline code rendering uses a tinted small_button (not monospace)
- Heading fonts use the default font (no separate bold/large fonts)
- Image rendering shows a placeholder text
- These can be improved by subclassing MarkdownRenderer
ROOT CAUSE: imgui_md (mekhontsev/imgui_md) BLOCK_P does NOT call ImGui::NewLine()
when m_list_stack is non-empty (verified in imgui_md.cpp). So a multi-paragraph
list item like:
- bullet text (long, wraps to 2 lines)
continuation paragraph
renders BOTH paragraphs at the same Y because the second BLOCK_P enters/exits
without advancing the cursor. The continuation crashes into the previous
paragraph's last wrapped line.
FIX: Add MarkdownRenderer._normalize_list_continuations preprocessor that
strips blank lines between a list item and its indented continuation. The
continuation then becomes a lazy continuation of the first paragraph (single
BLOCK_P in imgui_md, proper text wrapping, no overlap). Trade-off: users
cannot have separate paragraphs within a single list item. Acceptable.
Also: fixed a pre-existing bug in _normalize_nested_list_endings where a
duplicate conditional caused the function to return empty string (the
out.append(line) was inside the wrong scope). It was silently corrupting
all list content since fd5f4d0e.
TESTS: 23/23 markdown unit tests pass. 3 new tests for the new preprocessor
covering: blank-strip case, blank-preservation case, simple-list passthrough.
FIX 1 (src/markdown_table.py): Cells now use imgui_md.render(c) instead of
imgui.text_wrapped(c). imgui_md uses MD4C which strips backtick-delimited
inline code spans BEFORE rendering, so backticks no longer appear as
literal characters in cell content. Side benefit: inline emphasis
(*foo*, **bar**) now renders in cells too.
FIX 2 (src/markdown_helper.py): Added MarkdownRenderer._normalize_nested_list_endings.
Upstream imgui_md (mekhontsev/imgui_md) BLOCK_UL exit only calls
ImGui::NewLine() for top-level list endings. For nested list endings, no
NewLine is emitted, so the next text starts at the same Y as the last
list item, causing visual overlap. The preprocessor inserts a blank
line before any line that follows a list item with MORE indent than
itself, forcing a paragraph break. Cannot fix the C++ from Python.
Tests:
- test_markdown_table_wrapped.py: updated to assert imgui_md.render is
called for cell content (not imgui.text_wrapped).
- test_markdown_helper_bullets.py: added 4 tests for the new preprocessors
(nested-list blank insertion + bullet delimiter conversion + edge cases).
20/20 markdown unit tests pass. 1-space indentation throughout.
KNOWN LIMITATIONS (cannot fix without forking imgui_md C++):
- Inline code spans render as plain text (no monospace font in cells)
- The ' * ' bullet delimiter has a Y-overlap bug upstream
(workaround: pre-convert to '- ' via _normalize_bullet_delimiters)
- Nested list ending overlap (workaround: insert blank line via
_normalize_nested_list_endings)
Table fix (src/markdown_table.py):
- Add TableColumnFlags_.width_stretch to each table_setup_column call
(was missing — columns had no width to wrap against, so text_wrapped
couldn't grow row height → all rows squished together)
- Remove the explicit for-h-in-headers: table_next_column + text_wrapped(h)
loop. table_headers_row() already renders the header from the
table_setup_column() names; the explicit loop was drawing it AGAIN on
top → double-rendered header rows.
Bullet fix (src/markdown_helper.py):
- Revert _render_md_no_bullet_overlap → simple imgui_md.render(chunk);
imgui.spacing() (the original af0bbe97 approach). The complex
workaround was stripping '- ' and rendering stripped text to imgui_md,
which double-rendered '- 1. ...' content (imgui.bullet from my code +
numbered list marker from imgui_md).
- Add MarkdownRenderer._normalize_bullet_delimiters: regex-converts
'* ' markers to '- ' before passing to imgui_md. This works around
the upstream bug in mekhontsev/imgui_md BLOCK_LI where the '*' case
calls ImGui::Bullet() without ImGui::SameLine(), causing the bullet
to render on its own Y with the text on the next Y. The '-' case
uses Text+SameLine which is correct. Cannot fix from Python (we
can't subclass the C++ class) — pre-conversion is the cheapest fix.
Tests:
- test_markdown_table_wrapped.py: updated to assert new behavior
(text_wrapped count == cell count, not header+cell).
- test_markdown_table_columns.py: updated to assert exactly 6
table_next_column calls (cells only, not 9).
- test_markdown_helper_bullets.py: rewrote for new public-API behavior
(imgui_md.render called with the unstripped chunk).
16/16 markdown unit tests pass.
User reported that nested list items in the Discussion Hub's read_mode
entries were overlapping with adjacent text (e.g., '- gte_lw(...)'
overlapping with 'These are different things...' below it). This is
the imgui_md library's known issue with list item line height.
FIX: Add an imgui.spacing() call after each imgui_md.render() to force
a small vertical gap between chunks. This prevents adjacent list items
from rendering at overlapping Y positions.
Tests: 16/16 broad regression pass
ROOT CAUSE: src/markdown_table.py:render_table was missing
imgui.table_setup_column() calls. In ImGui, columns MUST be
configured via table_setup_column before table_headers_row is called.
Without it, the table has no defined columns, causing cells to
render at overlapping Y positions. This manifested as text overlap
in the Discussion Hub's read_mode entries (e.g., 'swc2 -> gte_sw'
overlapping the line above it).
FIX: Call imgui.table_setup_column(h, TableColumnFlags_.width_stretch)
for each header BEFORE table_headers_row(). Each column now has a
defined width (stretch = fills available space) and cells render
correctly without overlap.
Tests:
- New test_markdown_table_columns.py asserts setup_column is called
once per column and table_next_column is called for each cell.
- 16/16 broad regression pass (test_markdown_table,
test_markdown_table_render, test_markdown_render_robust,
test_gen_send_empty_context, test_gui_fast_render)
ROOT CAUSE: The ListClipper in render_prior_session_view was being
tripped up by the variable heights of discussion entries (huge system
prompts vs small tool results). When the first entry was very tall
(system prompt), the clipper would compute the visible range assuming
uniform item heights, leading to underflow/overflow on subsequent
items. The user saw only the first ~8 entries with massive empty
space below ('early clipping').
FIX: Replace the ListClipper with a direct for loop over
app.prior_disc_entries. With 233 entries, performance is acceptable
and each entry renders correctly. The user can still scroll the
parent imscope.child window if content overflows.
Tests:
- Updated test_prior_session_no_clipping.py to set entries on
app_instance.controller.prior_disc_entries (the App's __getattr__
proxies attribute reads to the controller, so the set must go to
the controller directly).
- 28/28 broad regression pass
ROOT CAUSE: During a previous indentation fix, the 'while clipper.step():'
line was accidentally removed from render_prior_session_view. Without
the step() loop, the ListClipper's display_start/display_end stay at
their initial values (0/0 or similar), so NO discussion entries
were rendered even though 233 entries were present in
app.prior_disc_entries. The user saw only a single entry because the
list clipper was never advanced.
FIX: Restore the 'while clipper.step():' line. Re-indent the entire
prior_scroll block to consistent 1-space (function), 2-space (inside
style_color), 3-space (inside child + while), 4-space (inside for)
indentation. Now all 233 entries will render through the list clipper.
Tests:
- 28/28 broad regression pass
ROOT CAUSE: render_comms_history_panel had imgui.end_child() nested INSIDE
an 'if app._scroll_comms_to_bottom:' block at line 3758. When
_scroll_comms_to_bottom was False (the common case), end_child was
NOT called, leaving the comms_scroll child window open. This caused
the imGui state to corrupt: tab_item.end_tab_item, tab_bar.end_tab_bar,
and the outer window.end all saw that the child was still open
(WithinEndChildID was set), triggering 'Must call EndChild() and not
End()!' assertion.
FIX: Convert the entire comms_scroll block to imscope.child (which uses
Python's with statement for exception-safe end_child). The scroll-to-bottom
logic is now correctly nested INSIDE the with block, and there's no
manual end_child to forget.
Tests:
- Updated test_comms_scroll_no_clipping.py to check imscope.child
instead of begin_child
- 28/28 broad regression pass
ROOT CAUSE: render_heavy_text (called per comms panel entry) had
manual begin_child/end_child pairs. If anything inside the child
(especially markdown_helper.render) raised, end_child was skipped.
The child window was left open, corrupting the imGui state. The
corruption cascaded through tab_item.end_tab_item -> tab_bar.end_tab_bar
-> window.end, triggering 'Must call EndChild() and not End()!' assertion.
FIX: Convert the inner begin_child/end_child pair to imscope.child so
the end_child is automatically called by Python's with statement, even
on exception. Also convert prior_scroll to imscope.child for consistency.
TESTS:
- Existing test_comms_no_extraneous_pop.py: push/pop balance check
- Updated test_prior_session_no_clipping.py to match new imscope.child
signature
- 28/28 broad regression pass
ROOT CAUSE: In a previous fix (df7bda6e 'explicit child size for
comms_scroll and prior_scroll'), the code that pushed a child_bg style
color at the start of render_comms_history_panel was removed when the
section was rewritten to use imgui.get_content_region_avail() for
explicit child sizing. However, the matching pop_style_color at the end
of the function (guarded by 'if app.is_viewing_prior_session') was left
in place.
RESULT: When viewing a prior session, the imscope.style_color in
_gui_func pushes 1 color at the start of the frame, then the orphaned
pop in render_comms_history_panel decrements the imGui style counter
by 1, then _gui_func's imscope __exit__ tries to pop again — triggering
IM_ASSERT 'PopStyleColor() too many times!'.
This caused a cascade of imGui state corruption on every frame after
loading a prior session log, manifesting as 'too many times' assertions
on the next frame and 'Must call EndChild() and not End()' once the
style stack underflowed.
FIX: Remove the orphan pop_style_color at gui_2.py:3761. No matching
push exists, so the pop is unconditionally wrong.
TESTS:
- New test_comms_no_extraneous_pop.py asserts push/pop balance in
render_comms_history_panel when is_viewing_prior_session is True
- 43/43 broad regression pass
Convert manual push_style_color / pop_style_color in _gui_func to use the
imscope context manager so the pop is exception-safe via Python's with
statement. Manual push/pop can desync if render_main_interface raises
mid-render, causing 'PopStyleColor() too many times!' imGui assertion
on subsequent frames.
The try/except around render_main_interface was already there but the
pop was outside it, so the pop count could exceed the push count when
an exception short-circuited the render.
ROOT CAUSE: When child windows used ImVec2(0, 0) for auto-fill, the
child's reported height was unstable inside tab items (especially when
the parent tab was inside a tab_bar inside a window). Result: the
scrollable child rendered with a fixed smaller height, showing only the
first half of the content, with empty space below.
FIX: Use imgui.get_content_region_avail() to compute explicit dimensions
and pass them to begin_child. Now the child fills the full available area
inside the tab content.
- render_comms_history_panel: avail.x, avail.y
- render_prior_session_view: same, plus added entry count indicator next
to the Exit Prior Session button ({N} entries) for at-a-glance info
Tests:
- test_comms_scroll_no_clipping.py: verifies comms_scroll child uses
explicit (non-zero) size
- test_prior_session_no_clipping.py: same for prior_scroll child
- test_log_management_first_open.py: minor cleanup
- 42/42 broad regression pass
ROOT CAUSE: src/markdown_helper.py:render() used a 'mask text with placeholders
then re.split' approach that failed when AI responses contained CRLF or when
the same table content appeared twice. The replace() either didn't match
(CRLF mismatch) or only replaced the first occurrence, leaving the second
table as raw markdown for imgui_md to render badly. Result: the same table
appeared twice (bad rendering via imgui_md, good rendering via my new code).
FIX: rewrite render() to walk lines directly. Per-line, decide whether to
buffer for imgui_md, skip into a table renderer, or accumulate into a
code-block renderer. No text replacement needed.
- src/markdown_helper.py: new render() walks lines, handles code fences
and table intervals inline via lookup dicts.
- src/gui_2.py: render_log_management now calls load_registry() on the
newly-created LogRegistry when _log_registry was None. Previously the
initial construction populated an empty table, AND the 'Refresh Registry'
button was inside the else branch, so users had no way to load data.
User re-indented the surrounding block during debugging.
Tests:
- test_markdown_render_robust.py: 2 tests (CRLF text, duplicate content)
- test_log_management_first_open.py: 1 test (registry populated on open)
40/40 broad regression pass.
ROOT CAUSE: 3 mismatched names in the empty-context warning path:
1. _handle_generate_send set self.show_empty_context_warning_modal = True
but render_empty_context_modal checks self.show_empty_context_modal.
The modal never opened.
2. _handle_generate_send / _handle_md_only never set
self._pending_generation_action, so the modal's 'Proceed Anyway'
button always saw None and dispatched nothing.
3. After Proceed Anyway, _pending_generation_action was never reset,
so subsequent empty-context calls would dispatch the wrong action.
FIX:
- gui_2.py:494,501: show_empty_context_warning_modal -> show_empty_context_modal
- gui_2.py:494,501: set _pending_generation_action before showing modal
- gui_2.py:5385: reset _pending_generation_action = None after dispatch
Tests: tests/test_gen_send_empty_context.py (5 cases) covers all 4 dispatch
paths (generate/md_only x proceed/skip) plus the happy path with context.
37/37 regression pass. No new ImGui scope errors (2 pre-existing unrelated).
- render_files_and_media now wraps the per-file loop in directory groups
via aggregate.group_files_by_dir + imscope.tree_node_ex (mirrors the
Context Composition visual style at gui_2.py:3114)
- New 'Add Directory' button next to 'Add Files to Inventory':
uses filedialog.askdirectory() + os.walk to bulk-import a folder tree
- Button IDs (i, add_f_{i}, rem_f_{i}) preserve global uniqueness via
file_indices map (regression-safe across the directory wrap)
- Test uses mock button=False, mock filedialog.askopenfilenames/askdirectory
to avoid opening a real Tk dialog during test run
- New module-level render_vendor_state(app) in gui_2.py
- New 'Vendor State' tab in render_operations_hub tab_bar
- Renders 5 stable metrics: provider_model, context_window, cache, quota, last_error
- Each row: Metric label | Value | State (colored ok/warn/error/info)
- Tooltips via imgui.set_tooltip on the value cell
ImGui scope linter: render_vendor_state OK. Pre-existing 2 errors at lines
2684 and 4994 unrelated to this commit.
- AppController.__init__: public vendor_quota: Dict[str,Any], last_error: Optional[Dict[str,str]], token_tracker: Dict[str,Any]
- set_vendor_quota(provider, remaining_pct, reset_at): public API for ai_client quota paths
- clear_last_error(): reset hook
- _refresh_api_metrics: read vendor_quota and error from payload, populate state
ai_client per-provider quota wire-up deferred to a future track (per-provider
signals differ; this commit establishes the state shape and read path).
ROOT CAUSE: gui_2.py:1675 re-instantiated LogRegistry() which opens the TOML
but never called .load_registry() so the table stayed empty.
FIX: in-place load_registry() on the existing instance — preserves in-memory
state (any pending update_session_metadata call) and matches the user's intent
of 'refresh from disk'.
Comprehensive guide covering the 251-test-file suite:
- Test file layout and naming conventions
- 7 conftest.py fixtures (isolate_workspace, reset_paths, reset_ai_client, vlogger, kill_process_tree, mock_app, app_instance, live_gui) with their mechanisms
- 5 test categories (unit, integration, mock app, headless, opt-in)
- Markers (integration, clean_install, docker) and how to filter by them
- Hook API for integration tests (ApiHookClient methods, predefined_callbacks pattern)
- Common test patterns (pure function, mock, live_gui, exception, parametrized)
- Test configuration in pyproject.toml
- Running tests (all, by file, by marker, with timeout, etc.)
- Adding new tests (pure, integration, opt-in)
- Debugging failed tests (common failure modes and fixes)
- The check_test_toml_paths.py audit script
- Test data flow diagram
Added commands focused on ergonomics and mouse-free operation:
View (window toggles, 12 new): toggle_text_viewer, toggle_diagnostics, toggle_usage_analytics, toggle_context_preview, toggle_tier1_strategy, toggle_tier2_tech_lead, toggle_tier3_workers, toggle_tier4_qa, toggle_external_tools, toggle_shader_editor, toggle_undo_redo_history, toggle_command_palette
Layout (3 new): show_all_panels, hide_all_panels, save_workspace_profile, show_workspace_manager
Theme (1 new): cycle_theme (Dark -> Light -> NERV cycle)
Tools (2 new): undo, redo
Project (1 new): save_all (flush to project + config + global config)
Help (1 new): show_command_palette_help (opens docs/Readme.md in Text Viewer)
Refactored: extracted _toggle_window and _toggle_attr helpers to reduce duplication and make commands safer (no-op if state is missing).
Reset session now also clears comms and tool logs (matches the menu item behavior).
Added 7 new unit tests for the expanded command library.
- Updated to reflect 13 tests (6 unit + 7 live_gui) instead of hypothetical async test
- Removed Everything mode and async context preview sections (not yet implemented; marked as future work)
- Updated Commands Registry section to reference actual src/commands.py file
- Added Implementation section with file layout and Command/CommandRegistry/CommandModal reference
- Added Built-in Commands table reflecting the actual 11 commands shipped
- Added Adding Custom Commands section with decorator and explicit-Command patterns
- Added Keyboard Reference table
- Updated Testing section with accurate coverage and test pattern
- Moved unimplemented features (Everything mode, user-defined commands, plugin system) to Future Work
- Process arrow keys BEFORE input_text so the input field does not consume them
- Up/Down arrow keys navigate the result list (clamped to bounds)
- Enter and KeypadEnter execute the currently selected command
- Refactored _close_palette and _execute helpers (action call is now wrapped in try/except via _execute)
- Added 3 new tests: close helper resets state, execute runs and catches exceptions, top_n is meaningful for navigation
Added imgui.set_next_window_focus() on open so the palette window itself gets focus. The input field then gets focus on the next drawn widget. Wrapped action calls in try/except so a buggy command does not break the imgui.end_child/end pairing (was causing IM_ASSERT crash). Fixed theme_2 calls: apply_dark_theme and apply_light_theme do not exist; use theme_2.apply(palette_name). switch_to_dark_theme uses apply 10x Dark. switch_to_light_theme uses apply ImGui Light. switch_to_nerv_theme uses apply NERV instead of apply_nerv() from src.theme_nerv.
- set_keyboard_focus_here() now called BEFORE input_text (was after, so focus went to wrong widget)
- Only call set_keyboard_focus_here ONCE per open (via _command_palette_focused flag) so focus isn't stolen on subsequent frames
- Added imgui.Cond_.always to window pos/size so it stays centered on re-render
- Click on a result now immediately executes the command (was: only on Enter key, which wasn't reaching the modal)
- Reset _command_palette_focused on close so next open gets focus again
- Restore monolithic architecture in gui_2.py to fix test compatibility.
- Implement full-width horizontal expansion for Markdown tables in discussion entries.
- Re-implement layered role-based tints using draw_list channels.
- Standardize Text Viewer docking ID to '###Text_Viewer_Unified'.
- Fix MiniMax compression routing and base URL.
- Fully restore missing theme_2.py definitions.
- Restore monolithic architecture in gui_2.py to fix test breakages and circular imports.
- Update Text Viewer stable ID to '###Text_Viewer_Unified' to definitively fix docking conflicts.
- Refactor discussion entry renderer to force full-width horizontal expansion for Markdown.
- Fully restore theme_2.py definitions (palettes, fonts, scale) while retaining role-tint logic.
- Robustify ImGui ID stack in imgui_scopes.py to prevent access violations.
- Verify all fixes with the comprehensive unit and visual test suite.
- Restore all rendering logic to gui_2.py to maintain monolithic architecture and test compatibility.
- Fix horizontal squashing of Markdown tables by ensuring full panel width in entry groups.
- Resolve Text Viewer docking conflicts by standardizing on a stable window ID ('###Text_Viewer_Unified').
- Fix theme initialization by restoring missing load/save functions in theme_2.py.
- Prevent ImGui access violations by ensuring ID stack always receives strings in imgui_scopes.py.
- Successfully verified all UI regressions with a passing unit test suite.
- Update Text Viewer window ID to '###Text_Viewer_Unified'.
- Ensures ImGui treats the window as a single stable entity across title changes.
- Prevents docking loop glitches.
- Insert imgui.new_line() before rendering discussion content.
- Ensures the Markdown renderer inherits the full horizontal width of the panel.
- Definitively fixes vertical squashing of tables and long text blocks.
- Update Text Viewer stable ID to match registry key exactly ('###Text Viewer') for stable docking.
- Ensure imgui.push_id always receives a string in imgui_scopes.py to prevent low-level access violations.
- Resolve ImportError by correctly prefixing 'src' in modular renderers.
- Fix ImGui access violation by ensuring push_id always receives string IDs.
- Restore visible role-based background tints using layered rendering (channels).
- Definitively fix horizontal Markdown table widths by forcing group expansion.
- Centralize color management in theme_2.py and ui_shared.py.
- Standardize Files & Media inventory layout and remove legacy controls.
- Update test mocks to support modular UI and theme-driven styling.
- Implement layered tinting using draw_list channels in modular discussion renderer.
- Fix vertical squashing of Markdown tables by forcing full group width with a dummy.
- Consolidate color constants into src/ui_shared.py to prevent circular imports.
- Update src/theme_2.py with role-based tint helpers.
- Successfully verified imports and layout logic.
- Modularize discussion entry rendering to src/discussion_entry_renderer.py to fix layout squashing.
- Fix MiniMax compression routing with robust case-insensitive check and synced base URL.
- Implement src/ui_shared.py to resolve circular imports and consolidate shared UI helpers.
- Finalize Structural File Editor integration and state unification.
- Correctly route 'minimax' provider in run_discussion_compression.
- Fix MiniMax base URL to api.minimax.io to match main sender.
- Refactor read-mode discussion entries to always use a scrollable child with auto-resize.
- Remove redundant text wrapping that caused Markdown tables to squash vertically.
- Clean up duplicate separators in discussion hub.
- Update test_gui_symbol_navigation.py and test_gui_text_viewer.py to assert against show_windows['Text Viewer'] instead of the deprecated show_text_viewer attribute.
- Increase synchronization wait time in test_visual_sim_gui_ux.py to ensure the GUI loop accurately reflects the mocked MMA status.
- Update _trim_minimax_history to drop dangling 'tool' messages if their parent 'assistant' message is removed.
- Fixes 'invalid params, tool call result does not follow tool call (2013)' error when token limit is hit.
- Add tests/test_discussion_compression.py to verify AI sub-agent compression logic across Gemini, Anthropic, DeepSeek, and Gemini CLI providers.
- Add tests/test_discussion_metrics.py to verify AppController correctly extracts and accumulates token usage (input/output/cache) and logs token history.
- Display token metrics (input/output/cache) per response in Discussion Hub.
- Add total Discussion Token usage in the panel header.
- Implement 'Compress' feature to intelligently summarize and replace exhausted discussion histories using an AI subagent.
- Add isolate_workspace autouse fixture in conftest.py.
- Monkeypatch SLOP_CONFIG and preset paths to point to a temporary test directory.
- Update test_history_management.py to use dynamic paths.get_config_path().
- Prevents tests from accidentally reading or modifying the active project.toml or config.toml.
- Add _repair_minimax_history to close dangling tool calls from interrupted sessions.
- Add _trim_minimax_history to manage token limits and intelligently prune history.
- Integrate repair and trimming into _send_minimax loop.
- Resolves MiniMax error 2013 (tool call result does not follow tool call).
- Implement [Pure]/[Read] toggle for AI thinking monologues to allow text selection/copying.
- Fix TypeError: render_thinking_trace() missing 'entry_index' argument.
- Fix [+] buttons in Discussion and Comms history by correctly updating window state registry.
- Remove ListClipper from Discussion and Comms panels to fix variable-height clipping issues.
- Increase clipping heights for large entries to improve visibility.
- Fix code block scroll snapping in Markdown helper by robustifying text synchronization.
- Improved AppController.ai_status to prevent overwriting 'sending...' with 'models loaded'.
- Enhanced est_rag_phase4_stress.py with robust polling and increased timeout.
- Synchronized App and AppController history objects to ensure consistent view.
- Added import sys to src/api_hook_client.py.
- Fixed App.__getattr__ to use direct attribute access on controller to avoid recursion.
- Simplified _get_app_attr and _has_app_attr in src/api_hooks.py.
- Centralized RAG and symbol enrichment in AppController._handle_request_event.
- Updated ests/test_symbol_parsing.py to match the new enrichment flow.
- Removed redundant task appending from i_status and mma_status setters.
- Improved _sync_rag_engine to only set 'ready' status after indexing is confirmed.
- Updated est_status_encapsulation.py to reflect setter changes.
- Corrected GeminiEmbeddingProvider model name to gemini-embedding-001.
- Prevented _fetch_models from overwriting active i_status (sending/done/error).
- Updated est_rag_engine.py to correctly patch the lazy-loaded chromadb getter.
- Adjusted RAG simulation tests to account for the new initializing... status and automatic initial indexing.
- Fixed typo in est_z_negative_flows.py.
- Fixed
ullcontext NameError in gui_2.py.
- Corrected TestMMAApprovalIndicators to call real rendering methods on mock app.
- Updated est_history_manager.py to provide required context_files argument to UISnapshot.
- Stabilized est_z_negative_flows.py with robust polling for terminal response status and corrected field names.
- Cleaned up debug logging in
ag_engine.py and pp_controller.py.
- Fixed circular import in chromadb by using lazy imports in
ag_engine.py.
- Moved RAG engine initialization to background threads in AppController to avoid blocking UI.
- Added _rag_engine_lock to prevent race conditions during engine re-initialization.
- Updated Gemini embedding model to gemini-embedding-001 (available) from ext-embedding-004 (not found).
- Fixed _rebuild_rag_index to use fresh
ag_engine instance from self in every iteration.
- Optimized est_rag_phase4_final_verify.py and est_rag_phase4_stress.py to wait for RAG sync before continuing.
- Added dummy embedding fallback in LocalEmbeddingProvider if sentence-transformers fails to load.
In ImGui, EndChild() MUST be called even if BeginChild() returns False (meaning the child is clipped). Using if imgui.begin_child(...): caused EndChild() to be skipped, unbalancing the stack and causing sloppy.py to crash when certain UI panels were off-screen or collapsed.
The AI client decoupling was never properly implemented and added
unnecessary complexity. The actual startup bottleneck was RAG initialization
which is now handled via async initialization.
Report written to docs/reports/ai_decoupling_revert_report.md
RAG engine initialization (including chromadb import and index loading)
now happens in a background thread, allowing the GUI to show immediately.
The app was blocking for 5+ seconds during init_state() because RAG was
enabled in config. Now RAG loads asynchronously.
Before this change, app_controller imported rag_engine at module level which
pulled in chromadb (~0.45s). Now rag_engine is only imported when RAG is
actually enabled and needed. This improves startup time significantly.
The class was only accessible inside function scopes, causing
AttributeError when app_controller tried to instantiate it
at module level via ai_client.GeminiCliAdapter().
- Add section 10 (Anti-OOP Conventions) to python.md with hard rules,
class justification requirements, and Strangler Fig refactoring pattern
- Create conductor/refactor_oop.md tracker with 4 phases for class elimination
- Add ruff PLR rules (PLR0912, PLR6301, PLR0206) to pyproject.toml for
OOP anti-patterns
Addresses AI agent scope misinterpretation issues by enforcing flat
function-call graphs over deep class hierarchies.
- Wrap discussions.items() with list() in takes_panel to prevent
RuntimeError when dictionary changes during iteration
- This was causing crashes when switching discussions
_load_active_project() was calling _configure_mcp_for_project() BEFORE
_refresh_from_project() which populates self.files. Now it calls
_refresh_from_project() first so mcp_client gets configured with the
actual file list that includes gencpp paths.
- Add _show_ast_inspector flag to track when popup should open
- Use same pattern as other modals (_show_* flag + open_popup)
- Restructure if/else to properly handle end_popup paths
- This fixes the Inspect button not opening the modal
- Add _configure_mcp_for_project() helper method
- Call it at end of _load_active_project() to configure mcp_client on startup
- _switch_project() calls it after _refresh_from_project()
- This ensures mcp_client._base_dirs is populated before GUI buttons try to read files
Previously mcp_client.configure() was only called during ai_client.send()
which meant GUI buttons (Slices/Inspect) couldn't access files when
project was switched to an external project like gencpp. Now _switch_project
reconfigures mcp_client with the new project's root and file_items.
- Calculate avail at window level, divide by num_open sections
- Pass height_override to _render_files_panel and _render_screenshots_panel
- When both open: each gets equal share of available space
- When one open: it gets full available space
- Calculate available space from get_content_region_avail().y
- Divide by number of open sections (1 or 2)
- Each section gets equal height (section_h)
- Content scrolls internally if it exceeds allocated space
- When both collapsed, shows minimal placeholder
- Track section open state via _files_section_open, _shots_section_open
- Calculate available space, divide by number of open sections
- Each section gets equal height when both open
- Content scrolls internally if it exceeds allocated space
- Removed unused _render_files_panel and _render_screenshots_panel methods
- Files: child_h = min(max(len(files),1) * 28 + 40, 400) - 28px per row, 40px header, 400px max
- Screenshots: shot_h = min(max(len(shots),1) * 28 + 40, 300) - same pattern with 300px max
Replaces hacky (0, -40) which stretched to fill available space regardless of content.
Added:
- _files_split_v state (0.5 default) for split ratio
- _files_open and _shots_open tracking for collapse state
- Splitter bar between collapsing headers when both open
- Splitter updates _files_split_v based on mouse drag
- Persona editor: splitter shown when BOTH models and prompt open (not just prompt)
- Bias profiles: move splitter OUTSIDE btool_scroll child, between both sections
- Fixed nesting issues causing EndTable/EndChild errors
- When both sections open: use min(h, max(200, rem_y*0.3)) for tools, min(h, max(150, rem_y*0.5)) for bias
- Single section open: cap at 400px instead of hard small values
- This preserves split ratio while ensuring minimum readable sizes
The begin_child() was using (0, -40) which made it stretch to fill parent.
Changed to (0, min(len(items) * 30 + 50, 300)) so it:
- Sizes to content (30px per row + 50px header)
- Caps at 300px max height
- Allows scrolling when content overflows
The main_context field in Project Settings was stored but never used.
Nothing reads it to inject into AI context. System Prompt in AI Settings
already serves this purpose.
Removed:
- app_controller.py: ui_project_main_context state variable and all refs
- gui_2.py: Main Context File UI section from Projects panel
- project_manager.py: main_context from default_project()
- project.toml, manual_slop.toml, gencpp_manual_slop_template.toml: main_context entries
- Copied 58 files from C:\projects\gencpp\base\ to tests/assets/gencpp_samples
- Added test_gencpp_full_suite.py that validates:
- Skeleton generation for all .hpp files
- Code outline generation
- get_definition for key symbols
- AST masking with aggregation
- All 25 tests pass
- Store _vscode_diff_process after launching external editor
- Add _close_vscode_diff() helper to terminate the process
- Call _close_vscode_diff() when Apply Patch or Reject is clicked
- conftest.py: Include tools.text_editors.vscode in live_gui workspace config
- gui_2.py: Add btn_open_external_editor to _clickable_actions
- test_external_editor_gui.py: Tests for external editor GUI integration
Note: Due to process boundaries (GUI runs in subprocess), full VSCode launch
verification requires manual testing. The test infrastructure verifies config,
command format, and button wiring. Manual verification recommended.
Note: Due to process boundaries (GUI runs in subprocess), monkeypatch doesn't
cross to GUI subprocess. Manual verification requires configuring
config.toml in project root with VSCode path.
- Add dropdown combo to select default editor
- Add _set_external_editor_default method to save selection to config
- Clean up layout and improve visual hierarchy
- Add better color coding for configured vs default editors
- TextEditorConfig.from_dict no longer requires 'name' field since name comes from dict key
- Added try/except around _render_external_editor_panel to prevent tab bar mismatch
- Moved External Editor panel from AI Settings to External Tools tab in Operations Hub
- Fixed default_editor lookup to use nested [tools.default_editor] structure
- Added example entries for vscode, notepadpp, 10xEditor, rider, sublime
- Improved panel UI with section header and clearer formatting
- Added _render_external_editor_panel method to display configured editors
- Shows default editor marker and diff args
- Displays config file locations for user reference
- Integrated as 'External Editor' section in AI Settings
- Added button to launch external editor for reviewing agent proposed changes
- Added _open_patch_in_external_editor method to handle the launch logic
- Integrated with ExternalEditorLauncher and create_temp_modified_file
- Add TextEditorConfig and ExternalEditorConfig dataclasses to models.py
- Create src/external_editor.py with ExternalEditorLauncher class
- Add tests for configuration and launcher functionality
- Support for config.toml [tools.text_editors] and manual_slop.toml default_editor
This fixes the 'stuck' behavior in concurrent tests by ensuring the tests look for standard completion markers and don't wait for unnecessary timeouts.
The test clicks btn_mma_start_track twice with different track_ids.
When _cb_load_track fails for track_a, self.active_track remains None or wrong.
Then track_b loads but we can't distinguish if a later call is for track_a retry
or track_b (which already has an engine). This adds an explicit reload path
when loaded track doesn't match requested track.
active_track was None when _start_track_logic was called from _cb_accept_tracks
because active_track is only set when loading a track via _cb_load_track.
_start_track_logic creates a new track locally and should use that track's id.
The AppController.__getattr__ delegation was returning controller.active_tickets
but init_state() never initialized self.active_tickets, causing an
AttributeError when gui_2.py tried to access self.active_tickets before
controller state was fully loaded.
Fixes live_gui fixture crash in test_mma_concurrent_tracks_stress_sim.py
- self.engine was a single ConductorEngine reference that got overwritten
when multiple tracks ran concurrently, orphaning the first track's engine
- Now uses self.engines: Dict[str, ConductorEngine] keyed by track.id
- Updated _spawn_worker, kill_worker, pause_mma, resume_mma, approve_ticket,
_load_active_tickets, and _update_ticket_depends_on to use engines.get(track_id)
Fixes concurrent MMA track execution bug where only one worker ever appeared.
The code after the 'prior session' return block was incorrectly indented
at 1 space, placing it inside the 'if is_viewing_prior_session' block
instead of after it. This caused 'total_cost' and 'perc' to be undefined
when viewing an active session, triggering an IM_ASSERT error.
Fix: Moved 'track_name', 'track_stats', and 'total_cost' to the
correct 2-space indentation (method body level).
Takes panel implemented:
- List of takes with entry count
- Switch/delete actions per take
- Synthesis UI with take selection
- Uses existing synthesis_formatter
- Replaced _render_takes_placeholder with _render_takes_panel
- Shows list of takes with entry count and switch/delete actions
- Includes synthesis UI with take selection and prompt
- Uses existing synthesis_formatter for diff generation
- Replaced placeholder with actual _render_context_composition_panel
- Shows current files with Auto-Aggregate and Force Full flags
- Shows current screenshots
- Preset dropdown to load existing presets
- Save as Preset / Delete Preset buttons
- Uses existing save_context_preset/load_context_preset methods
Context Presets tab removed from Project Settings panel.
The _render_context_presets_panel method call is removed from the tab bar.
Context presets functionality will be re-introduced in Discussion Hub -> Context Composition tab.
The ui_summary_only global aggregation toggle was redundant with per-file flags
(auto_aggregate, force_full). Removed:
- Checkbox from Projects panel (gui_2.py)
- State variable and project load/save (app_controller.py)
Per-file flags remain the intended mechanism for controlling aggregation.
Tests added to verify removal and per-file flag functionality.
This track addresses the fragmented implementation of Session Context Snapshots
and Discussion Takes & Timeline Branching tracks (2026-03-11) which were
marked complete but the UI panel layout was not properly reorganized.
New track structure:
- Phase 1: Remove ui_summary_only, rename Context Hub to Project Settings
- Phase 2: Merge Session Hub into Discussion Hub (4 tabs)
- Phase 3: Context Composition tab (per-discussion file filter)
- Phase 4: DAW-style Takes timeline integration
- Phase 5: Final integration and cleanup
Also archives the two botched tracks and updates tracks.md.
Empty strings in bias_profiles.keys() and personas.keys() caused
imgui.selectable() to fail with 'Cannot have an empty ID at root of
window' assertion error. Added guards to skip empty names.
description: Enforces the 4-Tier Hierarchical Multi-Model Architecture (MMA) within Gemini CLI using Token Firewalling and sub-agent task delegation.
---
# MMA Token Firewall & Tiered Delegation Protocol
You are operating within the MMA Framework, acting as either the **Tier 1 Orchestrator** (for setup/init) or the **Tier 2 Tech Lead** (for execution). Your context window is extremely valuable and must be protected from token bloat (such as raw, repetitive code edits, trial-and-error histories, or massive stack traces).
To accomplish this, you MUST delegate token-heavy or stateless tasks to **Tier 3 Workers** or **Tier 4 QA Agents** by spawning secondary Gemini CLI instances via `run_shell_command`.
**CRITICAL Prerequisite:**
To ensure proper environment handling and logging, you MUST NOT call the `gemini` command directly for sub-tasks. Instead, use the wrapper script:
`uv run python scripts/mma_exec.py --role <Role> "..."`
-`docs/guide_meta_boundary.md`: Clarification of ai agent tools making the application vs the application itself.
### The Surgical Spec Protocol (MANDATORY for track creation)
When creating tracks (`activate_skill mma-tier1-orchestrator`), follow this protocol:
1.**AUDIT BEFORE SPECIFYING**: Use `get_code_outline`, `py_get_definition`, `grep_search`, and `get_git_diff` to map what already exists. Previous track specs asked to re-implement existing features (Track Browser, DAG tree, approval dialogs) because no audit was done. Document findings in a "Current State Audit" section with file:line references.
2.**GAPS, NOT FEATURES**: Frame requirements as what's MISSING relative to what exists.
- GOOD: "The existing `_render_mma_dashboard` (gui_2.py:2633-2724) has a token usage table but no cost column."
- BAD: "Build a metrics dashboard with token and cost tracking."
3.**WORKER-READY TASKS**: Each plan task must specify:
- **WHERE**: Exact file and line range (`gui_2.py:2700-2701`)
- **WHAT**: The specific change (add function, modify dict, extend table)
- **HOW**: Which API calls (`imgui.progress_bar(...)`, `imgui.collapsing_header(...)`)
- **SAFETY**: Thread-safety constraints if cross-thread data is involved
4.**ROOT CAUSE ANALYSIS** (for fix tracks): Don't write "investigate and fix." List specific candidates with code-level reasoning.
5.**REFERENCE DOCS**: Link to relevant `docs/guide_*.md` sections in every spec.
6.**MAP DEPENDENCIES**: State execution order and blockers between tracks.
## 1. The Tier 3 Worker (Execution)
When performing code modifications or implementing specific requirements:
1.**Pre-Delegation Checkpoint:** For dangerous or non-trivial changes, ALWAYS stage your changes (`git add .`) or commit before delegating to a Tier 3 Worker. If the worker fails or runs `git restore`, you will lose all prior AI iterations for that file if it wasn't staged/committed.
2.**Code Style Enforcement:** You MUST explicitly remind the worker to "use exactly 1-space indentation for Python code" in your prompt to prevent them from breaking the established codebase style.
3.**DO NOT** perform large code writes yourself.
4.**DO** construct a single, highly specific prompt with a clear objective. Include exact file:line references and the specific API calls to use (from your audit or the architecture docs).
5.**DO** spawn a Tier 3 Worker.
*Command:*`uv run python scripts/mma_exec.py --role tier3-worker "Implement [SPECIFIC_INSTRUCTION] in [FILE_PATH] at lines [N-M]. Use [SPECIFIC_API_CALL]. Use 1-space indentation."`
6.**Handling Repeated Failures:** If a Tier 3 Worker fails multiple times on the same task, it may lack the necessary capability. You must track failures and retry with `--failure-count <N>` (e.g., `--failure-count 2`). This tells `mma_exec.py` to escalate the sub-agent to a more powerful reasoning model (like `gemini-3-flash`).
7. The Tier 3 Worker is stateless and has tool access for file I/O.
## 2. The Tier 4 QA Agent (Diagnostics)
If you run a test or command that fails with a significant error or large traceback:
1.**DO NOT** analyze the raw logs in your own context window.
2.**DO** spawn a stateless Tier 4 agent to diagnose the failure.
3.*Command:*`uv run python scripts/mma_exec.py --role tier4-qa "Analyze this failure and summarize the root cause: [LOG_DATA]"`
4.**Mandatory Research-First Protocol:** Avoid direct `read_file` calls for any file over 50 lines. Use `get_file_summary`, `py_get_skeleton`, or `py_get_code_outline` first to identify relevant sections. Use `git diff` to understand changes.
## 3. Persistent Tech Lead Memory (Tier 2)
Unlike the stateless sub-agents (Tiers 3 & 4), the **Tier 2 Tech Lead** maintains persistent context throughout the implementation of a track. Do NOT apply "Context Amnesia" to your own session during track implementation. You are responsible for the continuity of the technical strategy.
## 4. AST Skeleton & Outline Views
To minimize context bloat for Tier 2 & 3:
1. Use `py_get_code_outline` or `get_tree` to map out the structure of a file or project.
2. Use `py_get_skeleton` and `py_get_imports` to understand the interface, docstrings, and dependencies of modules.
3. Use `py_get_definition` to read specific functions/classes by name without loading entire files.
4. Use `py_find_usages` to pinpoint where a function or class is called instead of searching the whole codebase.
5. Use `py_check_syntax` after making string replacements to ensure the file is still syntactically valid.
6. Only use `read_file` with `start_line` and `end_line` for specific implementation details once target areas are identified.
7. Tier 3 workers MUST NOT read the full content of unrelated files.
## 5. Cross-Skill Activation
When your current role requires capabilities from another tier, use `activate_skill`:
- **Quick code task**: Spawn via `mma_exec.py --role tier3-worker` (stateless, no skill activation needed)
- **Error analysis**: Spawn via `mma_exec.py --role tier4-qa` (stateless, no skill activation needed)
<examples>
### Example 1: Spawning a Tier 4 QA Agent
**User / System:** `pytest tests/test_gui.py` failed with 400 lines of output.
**Agent (You):**
```json
{
"command":"python scripts/mma_exec.py --role tier4-qa \"Summarize this stack trace into a 20-word fix: [snip first 30 lines...]\"",
"description":"Spawning Tier 4 QA to compress error trace statelessly."
}
```
### Example 2: Spawning a Tier 3 Worker with Surgical Prompt
**User:** Please implement the cost tracking column in the token usage table.
**Agent (You):**
```json
{
"command":"python scripts/mma_exec.py --role tier3-worker \"In gui_2.py, modify _render_mma_dashboard (lines 2685-2699). Extend the token usage table from 3 columns to 5 by adding 'Model' and 'Est. Cost' columns. Use imgui.table_setup_column() for the new columns. Import cost_tracker and call cost_tracker.estimate_cost(model, input_tokens, output_tokens) for each tier row. Add a total row at the bottom. Use 1-space indentation.\"",
"description":"Delegating surgical implementation to Tier 3 Worker with exact line refs."
}
```
### Example 3: Creating a Track with Audit
**User:** Create a track for adding dark mode support.
-`docs/guide_meta_boundary.md`: Clarification of ai agent tools making the application vs the application itself.
## Responsibilities
- Maintain alignment with the product guidelines and definition.
- Define track boundaries and initialize new tracks (`/conductor:newTrack`).
- Set up the project environment (`/conductor:setup`).
- Delegate track execution to the Tier 2 Tech Lead.
## Surgical Spec Protocol (MANDATORY)
When creating or refining tracks, you MUST:
1.**Audit** the codebase with `get_code_outline`, `py_get_definition`, `grep_search` before writing any spec. Document what exists with file:line refs.
2.**Spec gaps, not features** — frame requirements relative to what already exists.
3.**Write worker-ready tasks** — each specifies WHERE (file:line), WHAT (change), HOW (API call), SAFETY (thread constraints).
4.**For fix tracks** — list root cause candidates with code-level reasoning.
5.**Reference architecture docs** — link to relevant `docs/guide_*.md` sections.
6.**Map dependencies** — state execution order and blockers between tracks.
See `activate_skill mma-orchestrator` for the full protocol and examples.
## Limitations
- Do not execute tracks or implement features.
- Do not write code or perform low-level bug fixing.
- Keep context strictly focused on product definitions and high-level strategy.
description: Focused on track execution, architectural design, and implementation oversight.
---
# MMA Tier 2: Tech Lead
You are the Tier 2 Tech Lead. Your role is to manage the implementation of tracks (`/conductor:implement`), ensure architectural integrity, and oversee the work of Tier 3 and 4 sub-agents.
## Architecture
YOU MUST READ THE FOLLOWING BEFORE IMPLEMENTING TRACKS:
-`docs/guide_meta_boundary.md`: Clarification of ai agent tools making the application vs the application itself.
## Responsibilities
- Manage the execution of implementation tracks.
- Ensure alignment with `tech-stack.md` and project architecture.
- Break down tasks into specific technical steps for Tier 3 Workers.
- Maintain persistent context throughout a track's implementation phase (No Context Amnesia).
- Review implementations and coordinate bug fixes via Tier 4 QA.
- **CRITICAL: ATOMIC PER-TASK COMMITS**: You MUST commit your progress on a per-task basis. Immediately after a task is verified successfully, you must stage the changes, commit them, attach the git note summary, and update `plan.md` before moving to the next task. Do NOT batch multiple tasks into a single commit.
- **Meta-Level Sanity Check**: After completing a track (or upon explicit request), perform a codebase sanity check. Run `uv run ruff check .` and `uv run mypy --explicit-package-bases .` to ensure Tier 3 Workers haven't degraded static analysis constraints. Identify broken simulation tests and append them to a tech debt track or fix them immediately.
## Anti-Entropy Protocol
- **State Auditing**: Before adding new state variables to a class, you MUST use `py_get_code_outline` or `py_get_definition` on the target class's `__init__` method (and any relevant configuration loading methods) to check for existing, unused, or duplicate state variables. DO NOT create redundant state if an existing variable can be repurposed or extended.
- **TDD Enforcement**: You MUST ensure that failing tests (the "Red" phase) are written and executed successfully BEFORE delegating implementation tasks to Tier 3 Workers. Do NOT accept an implementation from a worker if you haven't first verified the failure of the corresponding test case.
## Surgical Delegation Protocol
When delegating to Tier 3 workers, construct prompts that specify:
- **WHERE**: Exact file and line range to modify
- **WHAT**: The specific change (add function, modify dict, extend table)
- **HOW**: Which API calls, data structures, or patterns to use
- **SAFETY**: Thread-safety constraints (e.g., "push via `_pending_gui_tasks` with lock")
Example prompt: `"In gui_2.py, modify _render_mma_dashboard (lines 2685-2699). Extend the token usage table from 3 to 5 columns by adding 'Model' and 'Est. Cost'. Use imgui.table_setup_column(). Import cost_tracker. Use 1-space indentation."`
## Limitations
- Do not perform heavy implementation work directly; delegate to Tier 3.
- Delegate implementation tasks to Tier 3 Workers using `uv run python scripts/mma_exec.py --role tier3-worker "[PROMPT]"`.
- For error analysis of large logs, use `uv run python scripts/mma_exec.py --role tier4-qa "[PROMPT]"`.
- Minimize full file reads for large modules; rely on "Skeleton Views" and git diffs.
description: Focused on TDD implementation, surgical code changes, and following specific specs.
---
# MMA Tier 3: Worker
You are the Tier 3 Worker. Your role is to implement specific, scoped technical requirements, follow Test-Driven Development (TDD), and make surgical code modifications. You operate in a stateless manner (Context Amnesia).
## Responsibilities
- Implement code strictly according to the provided prompt and specifications.
- **TDD Mandatory Enforcement**: You MUST write a failing test and verify it fails (the "Red" phase) BEFORE writing any implementation code. Do NOT write tests that contain only `pass` or lack meaningful assertions. A test is only valid if it accurately reflects the intended behavioral change and fails in the absence of the implementation.
- Write failing tests first, then implement the code to pass them.
- Ensure all changes are minimal, functional, and conform to the requested standards.
- Utilize provided tool access (read_file, write_file, etc.) to perform implementation and verification.
## Limitations
- Do not make architectural decisions.
- Do not modify unrelated files beyond the immediate task scope.
- Always operate statelessly; assume each task starts with a clean context.
- Rely on "Skeleton Views" provided by Tier 2/Orchestrator for understanding dependencies.
description: Focused on test analysis, error summarization, and bug reproduction.
---
# MMA Tier 4: QA Agent
You are the Tier 4 QA Agent. Your role is to analyze error logs, summarize tracebacks, and help diagnose issues efficiently. You operate in a stateless manner (Context Amnesia).
## Responsibilities
- Compress large stack traces or log files into concise, actionable summaries.
- Identify the root cause of test failures or runtime errors.
- Provide a brief, technical description of the required fix.
- Utilize provided diagnostic and exploration tools to verify failures.
## Limitations
- Do not implement the fix directly.
- Ensure your output is extremely brief and focused.
- Always operate statelessly; assume each analysis starts with a clean context.
"description":"Get a compact heuristic summary of a file without reading its full content. For Python: imports, classes, methods, functions, constants. For TOML: table keys. For Markdown: headings. Others: line count + preview. Use this before read_file to decide if you need the full content.",
"parameters":{
"type":"object",
"properties":{
"path":{
"type":"string",
"description":"Absolute or relative path to the file to summarise."
"description":"Get a hierarchical outline of a code file. This returns classes, functions, and methods with their line ranges and brief docstrings. Use this to quickly map out a file's structure before reading specific sections.",
"parameters":{
"type":"object",
"properties":{
"path":{
"type":"string",
"description":"Path to the code file (currently supports .py)."
"description":"Get a skeleton view of a Python file. This returns all classes and function signatures with their docstrings, but replaces function bodies with '...'. Use this to understand module interfaces without reading the full implementation.",
"description":"Run a PowerShell script within the project base_dir. Use this to create, edit, rename, or delete files and directories. stdout and stderr are returned to you as the result.",
"description":"Search for files matching a glob pattern within an allowed directory. Supports recursive patterns like '**/*.py'. Use this to find files by extension or name pattern.",
"parameters":{
"type":"object",
"properties":{
"path":{
"type":"string",
"description":"Absolute path to the directory to search within."
},
"pattern":{
"type":"string",
"description":"Glob pattern, e.g. '*.py', '**/*.toml', 'src/**/*.rs'."
- **ALWAYS use snake_case**: `old_string`, `new_string`, `replace_all`
- **NEVER use camelCase**: `oldString`, `newString`, `replaceAll`
## What This Is
## Project Overview
Manual Slop is a local GUI orchestrator for LLM-driven coding sessions. It bridges high-latency AI reasoning with a low-latency ImGui render loop via a thread-safe async pipeline; every AI-generated payload passes through a human-auditable gate before execution.
**Manual Slop** is a local GUI application designed as an experimental, "manual" AI coding assistant. It allows users to curate and send context (files, screenshots, and discussion history) to AI APIs (Gemini and Anthropic). The AI can then execute PowerShell scripts within the project directory to modify files, requiring explicit user confirmation before execution.
## The Conductor Convention
## Main Technologies
All AI agents consuming this project must read `./conductor/workflow.md` and treat `./conductor/tracks.md` as the task registry. Track implementation follows the TDD protocol documented in `conductor/workflow.md` with per-file atomic commits and git notes.
- **Platform Support**: Windows (PowerShell) — single developer, local use
- **DO NOT**: Read full files >50 lines without using `py_get_skeleton` or `get_file_summary` first. Do NOT perform heavy implementation directly — delegate to Tier 3 Workers.
## Environment
- Shell: PowerShell (pwsh) on Windows
- Do NOT use bash-specific syntax (use PowerShell equivalents)
- Use `uv run` for all Python execution
- Path separators: forward slashes work in PowerShell
- **Shell execution in Claude Code**: The `Bash` tool runs in a mingw sandbox on Windows and produces unreliable/empty output. Use `run_powershell` MCP tool for ALL shell commands (git, tests, scans). Bash is last-resort only when MCP server is not running.
## Session Startup Checklist
**IMPORTANT**: At the start of each session:
1.**Check TASKS.md** — look for IN_PROGRESS or BLOCKED tracks
2.**Review recent JOURNAL.md entries** — scan last 2-3 entries for context
3.**If resuming work**: run `/conductor-setup` to load full context
4.**If starting fresh**: run `/conductor-status` for overview
- **conductor/tracks.md**: Quick-read pointer to active conductor tracks
- **conductor/tracks/*/plan.md**: Detailed task state (source of truth)
- **JOURNAL.md**: Completed work history with `|TASK:ID|` tags
- **ERRORS.md**: P0/P1 error tracking
This project is no longer actively used with Claude Code. For project context, see `AGENTS.md`. The conductor system in `./conductor/` is the cross-tool abstraction and works with any agent toolchain.
**Manual Slop** is a local GUI application designed as an experimental, "manual" AI coding assistant. It allows users to curate and send context (files, screenshots, and discussion history) to AI APIs (Gemini and Anthropic). The AI can then execute PowerShell scripts within the project directory to modify files, requiring explicit user confirmation before execution.
This file covers Gemini-CLI-specific operational notes for the Manual Slop project. The primary toolchain is Gemini CLI; for general agent orientation, see `AGENTS.md`.
## Project Overview
**Manual Slop** is a local GUI orchestrator for LLM-driven coding sessions. It bridges high-latency AI reasoning with a low-latency ImGui render loop via a thread-safe async pipeline; every AI-generated payload passes through a human-auditable gate before execution.
***`gui_legacy.py`:** The main entry point and Dear PyGui application logic. Handles all panels, layouts, user input, and confirmation dialogs.
***`ai_client.py`:** A unified wrapper for both Gemini and Anthropic APIs. Manages sessions, tool/function-call loops, token estimation, and context history management.
***`aggregate.py`:** Responsible for building the `file_items` context. It reads project configurations, collects files and screenshots, and builds the context into markdown format to send to the AI.
***`mcp_client.py`:** Implements MCP-like tools (e.g., `read_file`, `list_directory`, `search_files`, `web_search`) as native functions that the AI can call. Enforces a strict allowlist for file access.
***`shell_runner.py`:** A sandboxed subprocess wrapper that executes PowerShell scripts (`powershell -NoProfile -NonInteractive -Command`) provided by the AI.
***`project_manager.py`:** Manages per-project TOML configurations (`manual_slop.toml`), serializes discussion entries, and integrates with git (e.g., fetching current commit).
***`session_logger.py`:** Handles timestamped logging of communication history (JSON-L) and tool calls (saving generated `.ps1` files).
Full module list: `src/*.py`. See `docs/guide_architecture.md` for the threading model and event system.
# Building and Running
@@ -27,21 +47,33 @@
api_key = "****"
[anthropic]
api_key = "****"
[deepseek]
api_key = "****"
[minimax]
api_key = "****"
```
The `credentials.toml` is **blacklisted** by the MCP allowlist — AI tools cannot read it.
* **Run the Application:**
```powershell
uv run .\gui_2.py
uv run sloppy.py # Normal mode
uv run sloppy.py --enable-test-hooks # With Hook API on :8999
```
# Development Conventions
# Gemini-CLI-Specific Conventions
* **Configuration Management:** The application uses two tiers of configuration:
* `config.toml`: Global settings (UI theme, active provider, list of project paths).
* `manual_slop.toml`: Per-project settings (files to track, discussion history, specific system prompts).
* **Tool Execution:** The AI acts primarily by generating PowerShell scripts. These scripts MUST be confirmed by the user via a GUI modal before execution. The AI also has access to read-only MCP-style file exploration tools and web search capabilities.
* **Context Refresh:** After every tool call that modifies the file system, the application automatically refreshes the file contents in the context using the files' `mtime` to optimize reads.
* **UI State Persistence:** Window layouts and docking arrangements are automatically saved to and loaded from `dpg_layout.ini`.
* **Conductor Extension:** Gemini CLI uses the conductor extension, which reads `./conductor/` for task tracking, workflow, and product context. Tracks live in `conductor/tracks/<name>_<YYYYMMDD>/` with `spec.md`, `plan.md`, and `metadata.json`.
***Skill Activation:** Use `activate_skill mma-orchestrator` to load the orchestrator skill, then activate the tier-specific skill (e.g., `activate_skill mma-tier1-orchestrator`).
* **The Conductor Convention:** Read `conductor/workflow.md` for the TDD protocol. Treat `conductor/tracks.md` as the task registry. Track implementation follows per-file atomic commits with git notes.
* **Tool Execution:** AI-generated PowerShell scripts and tool calls pass through the Execution Clutch (HITL). Scripts are saved to `scripts/generated/<ts>_<seq>.ps1`.
* **Context Refresh:** After every tool call that modifies the file system, the application automatically refreshes file contents in the context using `mtime` checks.
* **Fuzzy Anchor Resilience:** Line-based operations (`get_file_slice`, `set_file_slice`, `py_update_definition`, fuzzy anchor slices) use FuzzyAnchor to survive file modifications. They can be batched in a single turn without line drift.
* **Layout Persistence:** Window layouts are saved to `manualslop_layout.ini` (was `dpg_layout.ini`).
* **Logging:** All API communications are logged to `logs/sessions/<id>/comms.log`. Tool calls to `toolcalls.log`. Generated scripts to `scripts/generated/`.
* **Code Style:**
* Use type hints where appropriate.
* Internal methods and variables are generally prefixed with an underscore (e.g., `_flush_to_project`, `_do_generate`).
***Logging:** All API communications are logged to `logs/comms_<ts>.log`. All executed scripts are saved to `scripts/generated/`.
* Use exactly 1-space indentation for Python (NO EXCEPTIONS). See `conductor/product-guidelines.md`.
* Use the manual-slop MCP tools (`manual-slop_edit_file`, `manual-slop_py_update_definition`) for surgical edits — native edit tools destroy indentation.
* Internal methods and variables are prefixed with an underscore (e.g., `_flush_to_project`, `_do_generate`).
# Human-Facing Documentation
For understanding, using, and maintaining the tool, see `docs/Readme.md` and the 14 deep-dive guides it indexes. See `conductor/product.md` for the product vision.
@@ -6,7 +6,7 @@ A high-density GUI orchestrator for local LLM-driven coding sessions. Manual Slo
**Design Philosophy**: Full manual control over vendor API metrics, agent capabilities, and context memory usage. High information density, tactile interactions, and explicit confirmation for destructive actions.
| [MMA Orchestration](./docs/guide_mma.md) | 4-tier hierarchy, Ticket/Track/WorkerContext data structures, DAG engine, ConductorEngine, worker lifecycle, persona application, abort propagation |
| [Simulations](./docs/guide_simulations.md) | `live_gui` fixture, Puppeteer pattern, mock provider, visual verification, test areas by subsystem, headless service |
Subsystems marked "dedicated guide pending" are slated for dedicated `docs/guide_*.md` files in upcoming docs work. For now, their details live inline in the guides listed under [Documentation](#documentation) above.
---
@@ -105,8 +145,13 @@ api_key = "YOUR_KEY"
[deepseek]
api_key="YOUR_KEY"
[minimax]
api_key="YOUR_KEY"
```
Each provider's key is loaded by the corresponding `_ensure_<provider>_client()` in `src/ai_client.py`. The `credentials.toml` is **blacklisted** by the MCP allowlist — AI tools cannot read it under any circumstance.
### Running
```powershell
@@ -145,34 +190,59 @@ The Multi-Model Agent system uses hierarchical task decomposition with specializ
# Specification: Smarter Aggregation with Sub-Agent Summarization
## 1. Overview
This track improves the context aggregation system to use sub-agent passes for intelligent summarization and hash-based caching to avoid redundant work.
**Current Problem:**
- Aggregation is a simple pass that either injects full file content or a basic skeleton
- No intelligence applied to determine what level of detail is needed
- Same files get re-summarized on every discussion start even if unchanged
**Goal:**
- Use a sub-agent during aggregation pass for high-tier agents to generate succinct summaries
- Cache summaries based on file hash - only re-summarize if file changed
- Smart outline generation for code files, summary for text files
## 2. Current State Audit
### Existing Aggregation Behavior
-`aggregate.py` handles context aggregation
-`file_cache.py` provides AST parsing and skeleton generation
Based on the technical trace and sequence mapping of the AI interaction loop, the following areas are identified as primary targets for "Heavy Curation".
### 1. Unified Provider Loop (`ai_client.py`)
- **Observation:** `_send_anthropic`, `_send_gemini`, and `_send_gemini_cli` all implement their own `for r_idx in range(MAX_TOOL_ROUNDS + 2)` loops.
- **Problem:** Significant boilerplate duplication for tool execution, error handling, and file re-reading.
- **Curation Goal:** Refactor the multi-turn recursion into a single `_base_send_loop` method that takes a provider-specific `generate_turn` callback.
### 2. Threading Model Management (`app_controller.py`)
- **Observation:** `_process_event_queue` spawns a new `threading.Thread` for every `user_request`.
- **Problem:** Potential for thread explosion if multiple asynchronous requests are triggered rapidly (though rare in typical usage).
- **Curation Goal:** Consolidate into a single dedicated "AI Worker" thread with a task queue, or use a small `ThreadPoolExecutor` to manage background lifetimes.
### 3. Redundant Context Markers
- **Observation:** `_FILE_REFRESH_MARKER` and `_get_context_marker()` are used in multiple places to inject diffs.
- **Problem:** String duplication and fragmented logic for deciding when to "refresh" the AI's file context.
- **Curation Goal:** Centralize the context-refresh injection logic within the `aggregate` module or a dedicated `ContextRefresher` class.
### 4. Blocking Call Audit
- **Observation:** `asyncio.run_coroutine_threadsafe(...).result()` is used to call async tool logic from the sync worker thread.
- **Problem:** This bridge is technically correct but adds complexity.
- **Curation Goal:** If possible, move more of the AI loop logic into a proper `async` context to avoid the `.result()` blocking pattern.
# AI Interaction Pipeline: Intensive Technical Trace
This document provides a low-level technical trace of the AI interaction loop, following a pipeline-oriented architectural model. It identifies thread context switches, data transformation overhead, and synchronization bottlenecks.
Note right of AI: Perf: IO Bound (File MTime Scans)
AI->>Vendor: Follow-up Prompt (with Tool Result)
else Terminal Text
AI-->>WK: Final AI Response Text
end
end
Note over WK, UI: [Phase D: Result Synchronization]
WK->>EV: SyncEventQueue.put("response", result)
EV->>EV: _pending_gui_tasks.append(response_obj)
loop Every Frame (~16.6ms)
UI->>EV: _process_pending_gui_tasks()
Note right of UI: Data Copy: Controller State -> UI History Buffer
UI->>UI: Update Rendering State (Markdown/Syntax Highlight)
end
```
## 2. Technical Performance Audit
### 2.1 Threading & Synchronization
- **Context Switches:** The pipeline traverses four distinct execution contexts: Main Thread -> Event Thread -> Daemon Worker -> Subprocess.
- **Lock Contention:** `_pending_gui_tasks_lock` is acquired twice per AI response turn (once by background thread to append, once by UI thread to process).
- **Blocking Sites:** `ai_client.send` blocks the dedicated `WK` thread. `_confirm_and_run` blocks the `WK` thread using a `Condition` variable waiting on UI input.
### 2.2 Data Transformation Costs
- **Context Bloat:** `md_content` is a monolithic string. During synthesis, this string is often copied or chunked (`_chunk_text`), increasing memory pressure on the Python heap.
1.**Reduce Memory Copies:** The monolithic Markdown context should be handled as a stream or a shared buffer to avoid redundant copies between `aggregate` and `ai_client`.
2.**Deterministic Status Polling:** Replace string-based status polling (`ai_status`) with an enum-based state machine to reduce regex comparisons in the simulator and UI.
3.**Subprocess Pooling:**`shell_runner` spawns a new process for every script. For high-frequency tool use, a persistent PowerShell session could reduce overhead.
# Specification: AI Interaction Call Graph (ai_interaction_call_graph_20260507)
## Overview
A low-level technical trace of the AI interaction loop. The goal is to map every single function call and data hand-off from the moment a user message is sent to the final terminal execution of a PowerShell script or tool result.
Following the successful cleanup and refactoring of `gui_2.py`, the same organizational patterns and AI-optimized coding conventions must be applied to `src/app_controller.py`. This module is a critical part of the Manual Slop architecture, acting as the bridge between the GUI and the underlying AI/MCP systems.
## Goals
1.**Structural Parity:** Reorganize `src/app_controller.py` to match the structure and quality of `gui_2.py`.
2.**Standardization:** Enforce the AI-Optimized Python Style Guide (1-space indent, minimal blank lines, type hints, SDM tags).
3.**Refactoring:** Identify and extract logic that violates the 5-level nesting limit or is better suited as module-level functions.
4.**Validation:** Ensure full system integrity via the comprehensive test suite, run in batches of 4.
## Scope
-`src/app_controller.py`: Primary target for refactoring and curation.
-`conductor/code_styleguides/python.md`: Potential updates if new nuances are found.
-`conductor/product-guidelines.md`: Potential updates based on structural findings.
## Constraints
- **Indentation:** Must be exactly 1 space.
- **Scoping:** Use `imscope` for any ImGui-related calls if present (though `app_controller` should ideally be logic-focused, some status rendering might exist).
- **Anti-OOP:** Move state-independent methods to module level.
- **Type Safety:** 100% type hint coverage for all modified sections.
The "Approve PowerShell Command" modal is currently too small and cannot be resized. Additionally, the "Show Full Preview" option triggers the external "Text Viewer" window, which cannot be interacted with because the modal blocks all background UI inputs.
## 2. Functional Requirements
***Resizable Modal:** The modal must allow user resizing and should have a larger default minimum size.
***Inline Preview:** The "Show Full Preview" option must render the full script *inside* the modal itself (e.g., as a read-only scrollable child or markdown block), rather than triggering an external window.
***Responsive Input:** The script input text area should expand to fill the available vertical space of the modal, rather than being fixed to 200px.
## 3. Non-Functional Requirements
* The modal must continue to reliably block the execution thread until the user approves or rejects the script.
## 4. Acceptance Criteria
* The modal can be resized by dragging the corners.
* Clicking "Show Full Preview" toggles an inline preview without locking the UI.
# Specification: Code Path & Data Pipeline Analysis (code_path_analysis_20260507)
## Overview
A deep architectural audit focused on mapping the "processing routes" and "data pipelines" of the Manual Slop codebase. This analysis will treat the program as a series of data-driven pipelines (similar to Ryan Fleury's model), identifying exactly how data flows through `./src` and `./simulation`.
## Scope
- **Core Codebase:** `./src`
- **Simulation Infrastructure:** `./simulation`
- **Granularity:** Both high-level module interactions and detailed function-to-function execution flows.
## Functional Requirements
1.**Pipeline Mapping:**
- Identify major execution "routes" (e.g., UI Event Loop, AI Tool-Call Loop, Context Aggregation Pipeline).
- Map these routes from entry point to terminal state.
2.**Data Responsibility Audit:**
- For every major path, define which data structures it owns, modifies, or depends upon.
- Identify state boundaries and potential "data leaks" or redundant processing.
3.**Simulation Pipeline Audit:**
- Fully map the lifecycle of a simulation: State Setup -> Agent Injection -> Execution Loop -> Verification -> Cleanup.
4.**Automated Extraction:**
- Utilize MCP tools and potentially custom `tree-sitter` scripts to verify call graphs and data dependencies.
## Acceptance Criteria
- [ ] Comprehensive `PIPELINE_ANALYSIS.md` report created in the root.
- [ ] Mermaid flowcharts documenting every major processing route.
- [ ] Data responsibility table for all mapped paths.
- [ ] Full mapping of the `./simulation` pipeline.
This report summarizes the findings of the codebase audit performed on the `./src` directory. The audit focused on human readability, maintainability, and identifying architectural redundancies.
## Key Findings: Architectural Redundancies
### 1. AI Client Provider Proliferation (`src/ai_client.py`)
**Observation:** The `ai_client.py` module contains significantly redundant code paths for each supported LLM provider (Gemini, Anthropic, DeepSeek, MiniMax). Specifically:
- **Send Methods:** Each provider has its own `_send_<provider>` method with nearly identical structure for tool handling and response parsing.
- **Error Classification:** Multiple `_classify_<provider>_error` functions perform similar mappings of vendor exceptions to internal `ProviderError`.
- **History Management:** Separate locks and list structures for each provider's history.
**Recommendation:** Abstract the provider logic into a base `AIProvider` class or interface. Each vendor (Gemini, Anthropic, etc.) should implement this interface, allowing `ai_client.py` to dispatch calls polymorphically.
### 2. Tool Name Redundancy (`src/mcp_client.py` & `src/models.py`)
**Observation:** The list of available agent tools was defined in multiple places:
-`mcp_client.TOOL_NAMES` (Hardcoded set)
-`models.AGENT_TOOL_NAMES` (Hardcoded list)
-`mcp_client.MCP_TOOL_SPECS` (Canonical source for tool definitions)
**Action Taken:**`mcp_client.TOOL_NAMES` was refactored to be dynamically generated from `MCP_TOOL_SPECS`.
**Recommendation:** Consolidate `models.AGENT_TOOL_NAMES` to also derive from `mcp_client` or a shared tool registry to ensure synchronization when new tools are added.
**Observation:** The `NativeOrchestrator` class methods (e.g., `load_plan`, `save_track`) were found to be thin wrappers around module-level helper functions.
**Action Taken:** Replaced hardcoded paths in these helpers with calls to the standardized `src.paths` module.
**Recommendation:** Evaluate if the `NativeOrchestrator` class is necessary if it remains state-free, or move the helper logic entirely into class methods.
## Documentation Improvements
- Added missing docstrings to critical public functions in `ai_client.py`, `mcp_client.py`, `native_orchestrator.py`, `api_hook_client.py`, and `api_hooks.py`.
- Consolidated module-level docstrings in `multi_agent_conductor.py`.
- Ensured consistent 1-space indentation and CRLF line endings across all modified files.
## Conclusion
The core orchestration and AI client layers are functionally robust but would benefit from an abstraction pass to reduce the maintenance burden of adding new providers or tools.
This protocol defines the mandatory procedure for auditing and modifying files during the Phase 5 Heavy Curation. It is designed to minimize entropy and prevent regression propagation.
## 1. File-by-File Audit Cycle
For every `.py` file identified for curation:
1.**Dependency Check:** Use `derive_code_path` and `py_get_imports` to identify all upstream and downstream dependencies.
2.**State Verification:** Consult the `MUTATION_MATRIX_PHASE5.md` to identify any global state modifications performed by the file.
3.**Redundancy Identification:** Cross-reference the file against `CULLING_CANDIDATES_PHASE5.md`.
4.**Proposed Change Log:** Before editing, document the specific lines/symbols to be removed or refactored and the technical justification (e.g., "Superseded by theme_2.py").
5.**Surgical Edit:** Use the `replace` tool for targeted deletions. Avoid bulk file overwrites.
## 2. Regression Guardrails
- **Functional Parity:** After every major deletion (e.g., removing a redundant module), run the associated unit tests (if any).
- **Simulation Verification:** For changes to core pipelines (AI loop, Aggregation), run at least one relevant simulation (e.g., `simulation/ping_pong.py`) to verify end-to-end behavior.
- **Human-in-the-Loop:** Significant refactors (e.g., the `aggregate.py` rework) MUST be presented to the user with a detailed diff before final commitment.
## 3. Culling Justification Standards
- **"Unused"**: Symbol has 0 project-wide references in the audit.
- **"Redundant"**: Logic exists in a superior or more modern form elsewhere (e.g., `theme.py`).
- **"Slop"**: Code that adds complexity without contributing to performance, configuration, or a specified feature.
"description":"Exhaustive review of all .py files. Remove redundancies, eliminate unnecessary code/data/processing, and strictly align with project standards."
Aggressive pruning, optimization, and standardization of the codebase. This track uses the findings from the Code Path Analysis and other Phase 5 audits to trim away non-essential logic, data, and processing while strictly enforcing the project's technical integrity standards.
## Foundational Context (MANDATORY REVIEW)
All curation efforts MUST be informed by the following Phase 5 analysis reports:
-`docs/PIPELINE_ANALYSIS_PHASE5_INIT.md`: Processing route and pipeline mapping.
-`docs/STATE_INVENTORY_PHASE5.md`: Core data structure and property inventory.
-`docs/MUTATION_MATRIX_PHASE5.md`: Thread-safe state modification and lock map.
-`docs/CULLING_CANDIDATES_PHASE5.md`: Identified redundant symbols, modules, and structures.
## Granular Care & Regression Guardrails
- **Surgical Execution:** Changes must be applied file-by-file with extreme granularity. No bulk culling without individual justification.
- **Regression Monitoring:** Continuous verification of behavioral integrity. Any unintended entropy or performance degradation must trigger an immediate halt and review.
- **Traceability:** Every removed line must be cross-referenced against the culling audit or pipeline map.
## Scope
- **Target Files:** All `.py` files in `./src` and `./simulation`.
- **Primary Goal:** Trimming the "slop" (redundancies, dead code, excessive complexity).
## Functional Requirements
1.**Redundancy Pruning:** Eliminate duplicate logic across different data pipelines.
2.**Dead Code Removal:** Strip out legacy "just-in-case" code and unused processing paths.
3.**Strict Style Enforcement:**
- Universal 1-space indentation.
- CRLF line endings.
- Standardized type hinting.
4.**Guideline Alignment:** Refactor any code that deviates from `product-guidelines.md` (e.g., ensuring explicit composition over complex inheritance).
5.**Validation:** Ensure no loss of functionality or performance degradation.
## Acceptance Criteria
- [ ] Significant reduction in total codebase line count (where applicable).
- [ ] 100% pass on style audit (`scripts/ai_style_formatter.py`).
- [ ] All remaining code is mapped to a necessary functional requirement or performance goal.
This track addresses two distinct but critical areas:
1.**UI Performance (Fix):** The application currently hangs when users adjust AST or slice configurations. This is because the context preview is regenerated synchronously on the GUI thread, blocking all interactions.
2.**Command Palette (Feature):** A central, keyboard-driven interface for all application actions, similar to professional editors like VSCode or Sublime Text.
## 2. Functional Requirements
### 2.1 Async Context Preview
***Background Generation:** The `_do_generate` call within `_check_auto_refresh_context_preview` must be offloaded to an asynchronous worker thread.
***State Locking:** Prevent multiple concurrent generation threads from running if a preview refresh is already in progress.
***Incremental Signaling:** (Optional future goal) Investigate ways to only re-parse the affected file, but offloading is the immediate priority.
### 2.2 Everything Command Palette
***Shortcut Trigger:** Triggered by `Ctrl+P` (global project context).
***Fuzzy Search:** An input field that filters a global list of available commands.
***Action Mapping:** Includes actions like "Generate Response", "Clear Discussion", "Toggle Diagnostics", "Add All Files to Context", etc.
***Keyboard Navigation:** Use Up/Down arrows to navigate results and Enter to select/execute.
***Modal UX:** A centered, floating popup that dismisses on selection or Escape.
## 3. Non-Functional Requirements
***Smooth GUI Loop:** Offloading the generation must eliminate the UI hang.
***Low Latency Palette:** Search and filtering must feel instantaneous.
## 4. Acceptance Criteria
* Toggling "Def", "Sig", or "Hide" on an AST node no longer causes the GUI to stutter or hang.
* Pressing `Ctrl+P` opens the Command Palette.
* Typing "Reset" shows "Reset Session" and executing it successfully resets the discussion.
Add multi-select and batch state modification capabilities to the Context Panel to allow rapid wrangling of large numbers of files (e.g., setting 20 C++ files to 'AST Signatures' at once).
Decouple Files & Media from Context Composition, add directory grouping, file stats, and view mode selection per file. This is Phase 1 of the Context Composition Redesign per spec at `docs/superpowers/specs/2026-05-10-context-composition-redesign-design.md`.
## Current State Audit (as of 2026-05-10)
### Already Implemented
- Files & Media panel lists project files with wildcards
- Context Composition panel inherits files from Files & Media
- View flags (agg/full/sig/def) sync visually between panels
-`_render_context_composition_panel()` in gui_2.py:2794-2964
### Gaps to Fill (This Track's Scope)
- Files & Media populates Context Composition automatically (coupled)
- No directory grouping in file listings
- No file stats (line count, AST element count)
- View mode selection is limited (no custom view presets)
- Context Composition is NOT independent selection - it's derived from Files & Media
## Goals
1. Make Files & Media and Context Composition independent data sources
2. Add directory grouping to file listings for compact display
Implement Context Preset save/load with validation, and Context Preview before sending to agent. This is Phase 3 of the Context Composition Redesign per spec at `docs/superpowers/specs/2026-05-10-context-composition-redesign-design.md`.
## Current State Audit (as of 2026-05-10)
### Already Implemented
- Preset system exists for system prompts, tool presets, personas
- ProjectManager handles TOML save/load
- Context Composition stores FileItem entries with flags
### Gaps to Fill (This Track's Scope)
- No Context Preset model for saving file+view+slices compositions
- No save/load UI for Context Presets in Context Composition panel
- No validation when loading preset (missing files warn user)
- No Context Preview showing what will be sent to agent
## Goals
1. Context Preset model with name, description, files list
Enhance slice visualization with visual editor, annotation support (tags/comments), and view presets. This is Phase 2 of the Context Composition Redesign per spec at `docs/superpowers/specs/2026-05-10-context-composition-redesign-design.md`.
## Current State Audit (as of 2026-05-10)
### Already Implemented
- [Inspect] button opens AST inspector modal showing AST tree with Def/Sig/Hide toggles
- [Slices] button opens Text Viewer with file content for slice management
- FileItem.ast_mask stores mask per AST path (Def/Sig/Hide)
- FileItem.custom_slices stores user-defined slices with line ranges
### Gaps to Fill (This Track's Scope)
- Inspect popup shows AST but doesn't show file content with highlighted slices
- Slices editor is just a list of line ranges - no visual representation
- No annotation support (tags/comments) for custom slices
- No view presets (named combinations of view settings)
- AST-derived slices not shown before user creates custom slice
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Conductor
ed