From 9a394926173cbdc346edbb6468b91a903a58313f Mon Sep 17 00:00:00 2001 From: Ed_ Date: Tue, 2 Jun 2026 23:13:50 -0400 Subject: [PATCH] docs(readme): update ASCII file tree visualizations to match current state docs/Readme.md: was showing 5 guides (architecture, tools, mma, simulations, meta_boundary); now shows all 14 current guides plus MMA_Support/, reports/, superpowers/. Also expanded src/ tree from 22 modules to 53 modules, added simulation/ sim_* files, tests/ test infrastructure, scripts/ audit + docker scripts, and corrected entry-point paths (sloppy.py, manual_slop.toml). Readme.md: 'Module by Domain' table was showing 22 src/ modules; now shows all 53 current modules. Updated MCP tool count from 26 to 45. Added all modules added since 2026-02 doc refresh: rag_engine, beads_client, hot_reloader, personas, presets, context_presets, tool_presets, tool_bias, command_palette, commands, workspace_manager, theme_2, theme_nerv, theme_nerv_fx, fuzzy_anchor, history, imgui_scopes, summary_cache, markdown_helper, patch_modal, diff_viewer, external_editor, orchestrator_pm, synthesis_formatter, thinking_parser. --- Readme.md | 71 +++++++++++++++++++---------- docs/Readme.md | 118 +++++++++++++++++++++++++++++++++---------------- 2 files changed, 128 insertions(+), 61 deletions(-) diff --git a/Readme.md b/Readme.md index dee91d07..b961cb2c 100644 --- a/Readme.md +++ b/Readme.md @@ -190,34 +190,59 @@ The Multi-Model Agent system uses hierarchical task decomposition with specializ ## Module by Domain -### src/ — Core implementation +### src/ — Core implementation (53 modules) | File | Role | |---|---| | `src/gui_2.py` | Primary ImGui interface — App class, frame-sync, HITL dialogs, event system | +| `src/app_controller.py` | Headless controller; bridges GUI and async AI workers | | `src/ai_client.py` | Multi-provider LLM abstraction (Gemini, Anthropic, DeepSeek, MiniMax) | -| `src/mcp_client.py` | 26 MCP tools with filesystem sandboxing and tool dispatch | -| `src/api_hooks.py` | HookServer — REST API on `127.0.0.1:8999 for external automation | -| `src/api_hook_client.py` | Python client for the Hook API (used by tests and external tooling) | -| `src/multi_agent_conductor.py` | ConductorEngine — Tier 2 orchestration loop with DAG execution | -| `src/conductor_tech_lead.py` | Tier 2 ticket generation from track briefs | -| `src/dag_engine.py` | TrackDAG (dependency graph) + ExecutionEngine (tick-based state machine) | -| `src/models.py` | Ticket, Track, WorkerContext, Metadata, Track state | -| `src/events.py` | EventEmitter, AsyncEventQueue, UserRequestEvent | -| `src/project_manager.py` | TOML config persistence, discussion management, track state | -| `src/session_logger.py` | JSON-L + markdown audit trails (comms, tools, CLI, hooks) | -| `src/shell_runner.py` | PowerShell execution with timeout, env config, QA callback | -| `src/file_cache.py` | ASTParser (tree-sitter) — skeleton, curated, and targeted views | -| `src/summarize.py` | Heuristic file summaries (imports, classes, functions) | -| `src/outline_tool.py` | Hierarchical code outline via stdlib `ast` | -| `src/performance_monitor.py` | FPS, frame time, CPU, input lag tracking | -| `src/log_registry.py` | Session metadata persistence | -| `src/log_pruner.py` | Automated log cleanup based on age and whitelist | -| `src/paths.py` | Centralized path resolution with environment variable overrides | -| `src/cost_tracker.py` | Token cost estimation for API calls | -| `src/gemini_cli_adapter.py` | CLI subprocess adapter with session management | -| `src/mma_prompts.py` | Tier-specific system prompts for MMA orchestration | -| `src/theme_*.py` | UI theming (dark, light modes) | +| `src/mcp_client.py` | 45 MCP tools with 3-layer filesystem security and tool dispatch | +| `src/api_hooks.py` | HookServer — REST API on `127.0.0.1:8999` for external automation | +| `src/api_hook_client.py` | Python client for the Hook API (used by tests and external tooling) | +| `src/multi_agent_conductor.py` | ConductorEngine — Tier 2 orchestration loop with DAG execution | +| `src/dag_engine.py` | TrackDAG (dependency graph) + ExecutionEngine (tick-based state machine) | +| `src/models.py` | Ticket, Track, WorkerContext, Metadata, Persona, WorkspaceProfile, etc. | +| `src/events.py` | EventEmitter, AsyncEventQueue, UserRequestEvent | +| `src/project_manager.py` | TOML config persistence, discussion management, track state | +| `src/session_logger.py` | JSON-L + markdown audit trails (comms, tools, CLI, hooks) | +| `src/rag_engine.py` | RAG subsystem (ChromaDB + embedding providers) | +| `src/beads_client.py` | Beads/Dolt-backed issue tracking client | +| `src/hot_reloader.py` | State-preserving module reloader | +| `src/personas.py` | Unified agent profile manager | +| `src/presets.py` | System prompt preset manager | +| `src/context_presets.py` | Context composition preset manager | +| `src/tool_presets.py` | Tool preset manager | +| `src/tool_bias.py` | Tool bias engine (semantic nudging + dynamic strategy) | +| `src/command_palette.py` | Command palette + fuzzy matcher + registry | +| `src/commands.py` | 32 registered commands (toggle, theme, layout, AI, project, tools) | +| `src/workspace_manager.py` | Workspace profile save/load with scope inheritance | +| `src/theme_2.py` | Theme system (palette/font/etc.) | +| `src/theme_nerv.py` | NERV Tactical Console theme | +| `src/theme_nerv_fx.py` | NERV FX (scanlines, flicker, alert) | +| `src/shell_runner.py` | PowerShell execution with timeout, env config, QA callback | +| `src/file_cache.py` | ASTParser (tree-sitter) — skeleton, curated, targeted views | +| `src/fuzzy_anchor.py` | Fuzzy anchor slice algorithm | +| `src/history.py` | Undo/redo HistoryManager with UISnapshot | +| `src/imgui_scopes.py` | ImGui context managers (imscope) for the UI delegation pattern | +| `src/performance_monitor.py` | FPS, frame time, CPU, input lag tracking | +| `src/log_registry.py` | Session metadata persistence | +| `src/log_pruner.py` | Automated log cleanup based on age and whitelist | +| `src/paths.py` | Centralized path resolution with environment variable overrides | +| `src/cost_tracker.py` | Token cost estimation for API calls | +| `src/gemini_cli_adapter.py` | CLI subprocess adapter with session management | +| `src/mma_prompts.py` | Tier-specific system prompts for MMA orchestration | +| `src/summarize.py` | Heuristic file summaries (imports, classes, functions) | +| `src/outline_tool.py` | Hierarchical code outline via stdlib `ast` | +| `src/summary_cache.py` | SHA256-keyed summary LRU cache | +| `src/markdown_helper.py` | Markdown rendering helpers | +| `src/patch_modal.py` | Patch approval modal | +| `src/diff_viewer.py` | Diff rendering | +| `src/external_editor.py` | External editor integration (VSCode, etc.) | +| `src/orchestrator_pm.py` | Orchestrator project manager | +| `src/conductor_tech_lead.py` | Tier 2 ticket generation from track briefs | +| `src/synthesis_formatter.py` | Multi-take synthesis | +| `src/thinking_parser.py` | AI thinking-trace extraction | Simulation modules in `simulation/`: | File | Role | diff --git a/docs/Readme.md b/docs/Readme.md index d68713ae..c0a79087 100644 --- a/docs/Readme.md +++ b/docs/Readme.md @@ -321,62 +321,104 @@ manual_slop/ │ ├── product.md # Product definition │ ├── product-guidelines.md │ ├── tech-stack.md -│ └── workflow.md -├── docs/ # Deep-dive documentation +│ ├── workflow.md +│ ├── index.md +│ └── edit_workflow.md +├── docs/ # Deep-dive documentation (14 guides + specs/plans) │ ├── guide_architecture.md -│ ├── guide_meta_boundary.md +│ ├── guide_tools.md │ ├── guide_mma.md │ ├── guide_simulations.md -│ └── guide_tools.md -├── logs/ # Runtime logs -│ ├── sessions/ # Session logs -│ │ └── / # Per-session files -│ │ ├── comms.log -│ │ ├── toolcalls.log -│ │ ├── apihooks.log -│ │ └── clicalls.log -│ ├── agents/ # Sub-agent logs -│ ├── errors/ # Error logs -│ └── test/ # Test logs -├── scripts/ # Utility scripts -│ ├── generated/ # AI-generated scripts -│ └── *.py # Build/execution scripts -├── src/ # Core implementation +│ ├── guide_context_curation.md +│ ├── guide_shaders_and_window.md +│ ├── guide_rag.md +│ ├── guide_beads.md +│ ├── guide_hot_reload.md +│ ├── guide_personas.md +│ ├── guide_nerv_theme.md +│ ├── guide_workspace_profiles.md +│ ├── guide_command_palette.md +│ ├── guide_testing.md +│ ├── guide_meta_boundary.md +│ ├── Readme.md +│ ├── MMA_Support/ # Legacy MMA reference (deprecated) +│ ├── reports/ # Phase 5 reports +│ └── superpowers/ # Specs and plans for design work +├── src/ # Core implementation (53 modules) │ ├── gui_2.py # Primary ImGui interface │ ├── app_controller.py # Headless controller -│ ├── ai_client.py # Multi-provider LLM abstraction -│ ├── mcp_client.py # 26 MCP tools -│ ├── api_hooks.py # HookServer REST API -│ ├── api_hook_client.py # Hook API client +│ ├── ai_client.py # Multi-provider LLM (Gemini, Anthropic, DeepSeek, MiniMax) +│ ├── mcp_client.py # 45 MCP tools with 3-layer security +│ ├── api_hooks.py # HookServer REST API on :8999 +│ ├── api_hook_client.py # Python client for the Hook API │ ├── multi_agent_conductor.py # ConductorEngine -│ ├── conductor_tech_lead.py # Tier 2 ticket generation │ ├── dag_engine.py # TrackDAG + ExecutionEngine -│ ├── models.py # Ticket, Track, WorkerContext +│ ├── models.py # Ticket, Track, WorkerContext, etc. │ ├── events.py # EventEmitter, SyncEventQueue -│ ├── project_manager.py # TOML persistence -│ ├── session_logger.py # JSON-L logging +│ ├── project_manager.py # TOML persistence, discussion management +│ ├── session_logger.py # JSON-L + markdown audit trails +│ ├── rag_engine.py # RAG (ChromaDB + embedding providers) +│ ├── beads_client.py # Beads/Dolt issue tracking client +│ ├── hot_reloader.py # State-preserving module reloader +│ ├── personas.py # Unified agent profile manager +│ ├── presets.py # System prompt preset manager +│ ├── context_presets.py # Context composition preset manager +│ ├── tool_presets.py # Tool preset manager +│ ├── tool_bias.py # Tool bias engine +│ ├── command_palette.py # Command palette + fuzzy matcher +│ ├── commands.py # 32 registered commands +│ ├── workspace_manager.py # Workspace profile save/load +│ ├── theme_2.py # Theme system (palette/font/etc.) +│ ├── theme_nerv.py # NERV Tactical Console theme +│ ├── theme_nerv_fx.py # NERV FX (scanlines, flicker, alert) │ ├── shell_runner.py # PowerShell execution │ ├── file_cache.py # ASTParser (tree-sitter) -│ ├── summarize.py # Heuristic summaries -│ ├── outline_tool.py # Code outlining +│ ├── summarize.py # Heuristic file summaries +│ ├── outline_tool.py # Hierarchical code outline +│ ├── fuzzy_anchor.py # Fuzzy anchor slice algorithm +│ ├── history.py # Undo/redo HistoryManager +│ ├── imgui_scopes.py # ImGui context managers │ ├── performance_monitor.py # FPS/CPU tracking │ ├── log_registry.py # Session metadata -│ ├── log_pruner.py # Log cleanup -│ ├── paths.py # Path resolution +│ ├── log_pruner.py # Automated log cleanup +│ ├── paths.py # Centralized path resolution │ ├── cost_tracker.py # Token cost estimation │ ├── gemini_cli_adapter.py # CLI subprocess adapter -│ ├── mma_prompts.py # Tier system prompts -│ └── theme*.py # UI theming +│ ├── mma_prompts.py # Tier-specific system prompts +│ ├── summary_cache.py # SHA256-keyed summary LRU cache +│ ├── markdown_helper.py # Markdown rendering helpers +│ ├── patch_modal.py # Patch approval modal +│ ├── diff_viewer.py # Diff rendering +│ ├── external_editor.py # External editor integration +│ ├── orchestrator_pm.py # Orchestrator project manager +│ ├── conductor_tech_lead.py # Tier 2 ticket generation +│ ├── synthesis_formatter.py # Multi-take synthesis +│ ├── thinking_parser.py # AI thinking-trace extraction +│ └── __init__.py ├── simulation/ # Test simulations │ ├── sim_base.py # BaseSimulation class │ ├── workflow_sim.py # WorkflowSimulator │ ├── user_agent.py # UserSimAgent -│ └── sim_*.py # Specific simulations -├── tests/ # Test suite -│ ├── conftest.py # Fixtures (live_gui) -│ ├── artifacts/ # Test outputs -│ └── test_*.py # Test files +│ ├── sim_context.py # ContextSimulation +│ ├── sim_execution.py # ExecutionSimulation +│ ├── sim_ai_settings.py # AISettingsSimulation +│ └── sim_tools.py # ToolsSimulation +├── tests/ # Test suite (251 files) +│ ├── conftest.py # Fixtures (live_gui, isolate_workspace, etc.) +│ ├── mock_gemini_cli.py # Mock provider for integration tests +│ ├── test_*.py # Unit tests +│ ├── *_sim.py # Integration tests using live_gui +│ ├── test_clean_install.py # Opt-in: clones repo and verifies hooks +│ ├── test_docker_build.py # Opt-in: builds Docker image +│ ├── artifacts/ # Git-ignored; test outputs +│ └── logs/ # Git-ignored; live_gui log files +├── scripts/ # Utility scripts +│ ├── generated/ # AI-generated scripts +│ ├── check_test_toml_paths.py # Audit script (CI gate) +│ ├── docker_build.sh +│ └── docker_run.sh ├── sloppy.py # Main entry point ├── config.toml # Global configuration -└── credentials.toml # API keys +├── manual_slop.toml # Active project config (current) +└── credentials.toml # API keys (gitignored) ```