refactor: address 5-pass audit findings for antipatterns, bottlenecks, memory efficiency, and LLM handlers
This commit is contained in:
Riz Ashraf committed
1 parent
626403900f
commit
924b6d09fa
30 files changed
+1120
-503
No files matched your search
+40
-34
@@ -19,7 +19,7 @@ To prevent graph fragmentation and ensure seamless LLM context retrieval:
|
||||
|
||||
## 2. Consolidated Smart Tools Architecture
|
||||
|
||||
The server consolidates granular single-purpose tools into domain-named smart tools. Always prefer the consolidated tools over legacy aliases:
|
||||
The server consolidates granular single-purpose tools into domain-named smart tools. Always prefer the consolidated tools:
|
||||
|
||||
* **`tasks`**: Complete task lifecycle management.
|
||||
- `action: "add"`: Create a new task (requires `title`, optional `description`, `git_branch`, `parent_id`, `dependencies`).
|
||||
@@ -85,49 +85,55 @@ The server consolidates granular single-purpose tools into domain-named smart to
|
||||
- `action: "register"`: Register target environment (requires `name`).
|
||||
- `action: "get_details"`: Read full environment details.
|
||||
|
||||
* **`clipboard`**: OS Clipboard management.
|
||||
- `action: "read"`: Read OS clipboard.
|
||||
* **`clipboard`**: OS Clipboard management (native cross-platform support for Windows and Linux wl-paste/xclip).
|
||||
- `action: "read"`: Read OS clipboard text, HTML, file paths, or JPEG image.
|
||||
- `action: "write"`: Write text/html/files/image to clipboard.
|
||||
- `action: "toggle_watch"`: Toggle auto-clipboard watcher.
|
||||
|
||||
---
|
||||
* **`manage_subagent_namespace`**: Subagent memory isolation.
|
||||
- `action: "create"`: Create namespace.
|
||||
- `action: "purge"`: Purge namespace.
|
||||
- `action: "condense"`: Condense namespace.
|
||||
|
||||
## 3. Subgraph Expansion & Multi-Hop Navigation
|
||||
- **Tool:** `get_subgraph`
|
||||
- **When to use:** When you need to understand the complete architectural neighborhood surrounding a specific component, module, or database table.
|
||||
- **Behavior:** Performs a multi-hop Breadth-First Search (BFS) around a `root_node` (or `root_entity`) up to a requested `depth` (e.g. 1 to 3 hops) and returns all connected entities and relations. Pass `format: "markdown_tree"` to generate a compact, token-budgeted Markdown topology tree capped within a requested `max_tokens` budget.
|
||||
* **`manage_checkpoint`**: State snapshots and rollbacks.
|
||||
- `action: "checkpoint"` (or `"create_snapshot"`): Create state snapshot.
|
||||
- `action: "restore"` (or `"restore_snapshot"`): Restore point-in-time snapshot.
|
||||
|
||||
---
|
||||
|
||||
## 4. Automated Error Fix Auto-Matcher
|
||||
- **Tools:** `log_error_fix`, `search_error_fixes` (and alias `suggest_error_fix`)
|
||||
- **When to use:** When encountering a build error, test failure, or stack trace. Call `search_error_fixes` with either a text `query` or `stack_trace` before attempting a fix from scratch.
|
||||
- **Behavior:** Computes cosine similarity between error trace embeddings and past resolution logs when `stack_trace` is provided, or keyword filtering when `query` is provided, returning top matched solutions, modified files, and git commits.
|
||||
## 3. Knowledge Graph Operations & Multi-Hop Navigation
|
||||
* **`create_entities`**: Create entity nodes (`entity_type` PascalCase).
|
||||
* **`create_relations`**: Create relations (`relation_type` snake_case).
|
||||
* **`add_observations`**: Add new observations to existing entities.
|
||||
* **`delete_entities`**, **`delete_observations`**, **`delete_relations`**: Graph cleanup.
|
||||
* **`read_graph`**, **`search_nodes`**, **`open_nodes`**: Graph query and entity lookup.
|
||||
* **`visualize_graph`**: Generate graph visualizer output.
|
||||
* **`condense_entity`**, **`merge_entities`**, **`find_orphans`**: Graph maintenance.
|
||||
* **`get_subgraph`**: Perform multi-hop BFS neighborhood expansion tree around a root entity up to `depth` hops with token budget.
|
||||
* **`sweep_graph_health`**: Self-healing graph health auditor for near-duplicates and orphaned nodes.
|
||||
* **`resolve_stale_symbols`**, **`summarize_subgraph`**: Symbol resolution and subgraph summarization.
|
||||
|
||||
---
|
||||
|
||||
## 5. Memory State Checkpointing & Rollbacks
|
||||
- **Tool:** `checkpoint_state`, `restore_state` (or `create_snapshot`, `restore_snapshot`)
|
||||
- **When to use:** Before initiating a large refactor, running experimental subagent tasks, or executing destructive batch operations.
|
||||
- **Behavior:** Saves or restores a point-in-time snapshot of graph entities, active tasks, and tech debt backlogs.
|
||||
## 4. Search, Code & AST Intelligence
|
||||
* **`omni_search`**: High-performance unified search across tasks, code changes, ADRs, debt, and snippets.
|
||||
* **`semantic_code_search`**: Vector similarity search across indexing embeddings.
|
||||
* **`read_file_skeleton`**: Extract file declarations/skeletons using Tree-Sitter (Rust, Python, Go, Java, C, C++, JSX/TSX).
|
||||
* **`replace_ast_node`**: Structural AST node replacement across files.
|
||||
* **`find_symbol_references`**, **`get_callers`**, **`analyze_impact`**: Code dependency and blast radius analysis.
|
||||
* **`read_directory_architecture`**: Inspect directory structure and code organization.
|
||||
|
||||
---
|
||||
|
||||
## 6. Self-Healing Graph Health Sweeper
|
||||
- **Tool:** `sweep_graph_health`
|
||||
- **When to use:** Periodically or before committing major graph changes to audit entity consistency.
|
||||
- **Behavior:** Detects orphaned nodes (0 relations), computes name similarity to identify near-duplicates (e.g., `APIGateway` vs `ApiGateway`), and provides structured `merge_entities` recommendations or auto-prunes orphans.
|
||||
|
||||
---
|
||||
|
||||
## 7. Causal Lineage & Provenance Tracker
|
||||
- **Tool:** `query_lineage`
|
||||
- **When to use:** When asking *"Why was this component modified?"* or *"What task or ADR led to this code change?"*
|
||||
- **Behavior:** Searches across tasks, ADRs, audit ledger entries, and error fixes to assemble a unified chronological timeline explaining the provenance behind any file, symbol, or commit.
|
||||
|
||||
---
|
||||
|
||||
## 8. LLM Pre-Flight Context Bundle
|
||||
- **Tool:** `get_preflight_context`
|
||||
- **When to use:** At the start of a turn or subagent task to gain total situational awareness in 1 call.
|
||||
- **Behavior:** Aggregates current active branch, in-progress tasks with acceptance criteria, pinned files, top open tech debts, and active unverified hypotheses into a consolidated executive context bundle.
|
||||
## 5. Audit Logging, Diagnostics & Provenance
|
||||
* **`log_code_change`**, **`query_recent_changes`**: Audit trail of code edits, commits, and symbol modifications.
|
||||
* **`log_error_fix`**, **`search_error_fixes`**: Record error trace and verified fix; search past resolutions via vector similarity.
|
||||
* **`query_lineage`**: Reconstruct causal timeline explaining why a file/symbol/commit was modified.
|
||||
* **`log_hypothesis`**, **`query_hypotheses`**: Diagnostic hypothesis tracking during complex debugging.
|
||||
* **`get_preflight_context`**: Consolidated executive bundle (branch, active tasks, criteria, pinned files, tech debt) for instant context warmup.
|
||||
* **`learn_preference`**, **`read_preferences`**: Track user preferences and project conventions.
|
||||
* **`get_project_health`**: Health metrics, active task counts, debt backlog, and graph statistics.
|
||||
* **`broadcast_agent_signal`**, **`query_agent_signals`**: Inter-agent coordination signals.
|
||||
* **`auto_session_checkpoint`**: Auto-save session state checkpoint.
|
||||
* **`get_active_worktree_context`**, **`query_git_diffs`**: Git worktree status and diff inspection.
|
||||
* **`watch_process_logs`**, **`get_recent_logs`**: Process log monitoring and retrieval.
|
||||
Reference in new issue
Block a user