kenaz 0.0.0-stage → 0.3.2

package/core/dev/archive/ansuz/designs/refactor_mcp_tools_synapse.md

@@ -0,0 +1,490 @@
+# Refactor: `mcp_tools/synapse.rs` — Three-Stage Decomposition
+
+**Target file**: `dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/synapse.rs`
+**Current size**: 9 703 LOC / 370 KB
+**Method**: build-map → plan-split → minimal-patch, verify wire + `cargo check` between every step (see memory `feedback_large_file_three_stage_refactor.md`)
+
+---
+
+## Stage 1 — Map (this document)
+
+Produced 2026-04-21 via Explore subagent. Read-only analysis; no code changes.
+
+### 1.1 Public API inventory (45 handlers + 3 utility fns)
+
+**Thought Stack (l.65-188, ~180 LOC):**
+- `tool_synapse_thought_push` (l.65) · `tool_synapse_thought_pop` (l.126) · `tool_synapse_thought_stack_list` (l.163)
+
+**Core Synapse query (l.701-4063):**
+- `tool_synapse_status` (l.701) · `tool_synapse_cypher` (l.794) · `tool_synapse_index` (l.899) · `tool_synapse_search` (l.959) · `tool_synapse_context` (l.1607) · `tool_synapse_impact` (l.2020) · `tool_synapse_detect_changes` (l.2223)
+
+**Cognitive layer (l.2401-4063):**
+- `tool_synapse_inscribe` (l.2401) · `tool_synapse_backfill_trigger_embeddings` (l.2714) · `tool_synapse_forge` (l.2742) · `tool_synapse_declare` (l.3055) · `tool_synapse_proposed_connections` (l.3324) · `tool_synapse_verify` (l.3406) · `tool_synapse_recall` (l.3571) · `tool_synapse_sigils` (l.3991) · `tool_synapse_trace_route` (l.4063)
+
+**Architectural analysis (l.4344-5069):**
+- `tool_synapse_map` (l.4344) · `tool_synapse_pulse` (l.4671) · `tool_synapse_imagine` (l.4933) · `tool_synapse_rune_conflicts` (l.4971) · `tool_synapse_pain_paths` (l.5069)
+
+**Code hygiene (l.5484-7575):**
+- `tool_synapse_orphans` (l.5484) · `tool_synapse_health` (l.5859) · `tool_synapse_debug_pool` (l.6322) · `tool_synapse_knowledge_gaps` (l.6345) · `tool_synapse_audit` (l.6402) · `tool_synapse_clustering_log` (l.6472) · `tool_synapse_scan_stale_runes` (l.7217) · `tool_synapse_maintain` (l.7249) · `tool_synapse_associate` (l.7285) · `tool_synapse_apply_usage_boosts` (l.7523) · `tool_synapse_preamble` (l.7575) · `tool_synapse_attention` (l.7629)
+- Helpers: `is_cli_entry_symbol` (l.5545) · `orphan_cypher_query` (l.5581)
+
+**Thalamus SNN (l.7874-8196):**
+- `tool_thalamus_status` (l.7874) · `tool_thalamus_history` (l.7953) · `tool_thalamus_stimulate` (l.8011) · `tool_spike_bus_send` (l.8100) · `tool_spike_bus_poll` (l.8142) · `tool_thalamus_context` (l.8196)
+
+**Advanced synthesis (l.8298-9357):**
+- `tool_muninn_sense` (l.8298) · `tool_synapse_efe` (l.8379) · `tool_synapse_efe_feedback` (l.8444) · `tool_synapse_think` (l.8787) · `tool_synapse_link_cognitive` (l.9173) · `tool_reflex_query` (l.9357)
+
+### 1.2 First-class data structures
+
+| struct | line | field count | serde | purpose |
+|---|---|---|---|---|
+| `ThoughtStackThought` | 201 | 6 | ✓ | Ansuz tactical thought record |
+| `ThoughtStackFile` | 215 | 3 | ✓ | Thought stack container + versioning |
+| `PainPath` | 5129 | 5 | — | Cross-boundary call-chain representation |
+| `PainPathNode` | 5137 | 5 | — | Node within a chain |
+| `BoundaryJump` | 5145 | 5 | — | Community-boundary crossing |
+| `HealthDashboardSection` | 6744 | 8 | ✓ | Single health-metric section |
+| `HealthDashboard` | 6756 | 9 | ✓ | Unified 7-section health report |
+| `AttentionAccum` | 7862 | 3 | — | Heat / curiosity / risk accumulator |
+| `QueryIntent` (enum) | 8523 | 5 | — | Query-routing intent classification |
+| `SubsystemQuery` | 8545 | 3 | — | Planned subsystem query |
+| `RoutingMetrics` | 8780 | multi | — | MAGMA routing observability |
+
+### 1.3 Logical sub-modules already present
+
+| tag | line range | responsibility | primary symbols |
+|---|---|---|---|
+| A. Thought Stack | 190-340 | JSON-backed tactical thought LIFO | `ThoughtStackFile`, `ThoughtStackThought`, 3 handlers, `load_thought_stack`, `persist_thought_stack`, `sweep_expired_thoughts` |
+| B. Response compression | 18-64 + 1341-1544 | Adaptive token-budget reduction | `estimate_tokens*`, `parse_detail_level`, `compress_search_response`, `strip_snippets_from_search`, `compress_context_response`, `strip_context_to_summary`, `build_*_overview` |
+| C. Rune + graph context | 359-677 + 1915-1990 | memory.db ↔ KuzuDB fusion | `query_runes_with_verified`, `query_sigil_memberships`, `log_symbol_access`, `rune_to_json`, `enrich_search_with_runes`, `query_cognitive_applies_to`, `query_1hop_neighbors` |
+| D. Cypher / graph traversal | 794-900 + 4099-4633 | Raw + derived graph queries | `tool_synapse_cypher`, `tool_synapse_impact`, `tool_synapse_context`, `tool_synapse_trace_route`, `tool_synapse_map`, `bfs_calls_chain`, `kuzu_value_to_json`, `query_communities`, `query_call_hotspots` |
+| E. Large analytics (Health / Pain) | 5069-6230 + 5855-6320 | Multi-metric synthesis reports | `tool_synapse_health`, `tool_synapse_pain_paths`, `tool_synapse_orphans`, `tool_synapse_knowledge_gaps`, `pain_paths_impl`, `orphans_impl`, `compute_gini`, `count_pain_paths` |
+| F. Cognitive integration | 2401-4344 + 7217-7575 | rune ↔ symbol bridges | `tool_synapse_inscribe`, `tool_synapse_recall`, `tool_synapse_forge`, `tool_synapse_declare`, `tool_synapse_verify`, `tool_synapse_scan_stale_runes`, `tool_synapse_maintain`, `tool_synapse_associate` |
+| G. Thalamus + Spike Bus | 7868-8290 + 8092-8190 | Real-time neuronal potential | 6 thalamus/spike-bus handlers |
+| H. Advanced routing / EFE | 8516-9360 | Unified cognitive router + EFE learning | `tool_synapse_think`, `tool_synapse_efe`, `tool_synapse_efe_feedback`, `tool_muninn_sense`, `classify_query_intent`, `build_query_plans` |
+
+### 1.4 Top 3 low-risk split candidates (Stage 2 inputs)
+
+| # | proposed file | symbols | LOC | why low-risk |
+|---|---|---|---|---|
+| **1** | `handlers/thought_stack.rs` | `ThoughtStackThought`, `ThoughtStackFile`, 3 handlers (`push`/`pop`/`list`), `load_thought_stack`, `persist_thought_stack`, `sweep_expired_thoughts`, `thought_stack_path`, `generate_thought_id`, `infer_project_name` | ~180 | Fully independent JSON I/O subsystem. Deps: `chrono`, `serde`, `std::path` only. No Synapse graph / memory.db access. Zero cross-references from other handlers (grep-verified). |
+| **2** | `handlers/response_compression.rs` | `estimate_tokens`, `estimate_tokens_json`, `parse_detail_level`, `parse_token_threshold`, `compress_search_response`, `strip_snippets_from_search`, `build_search_overview`, `compress_context_response`, `strip_context_to_summary`, `build_context_overview` | ~220 | Pure `serde_json::Value` operations, no DB access. 4 call sites (l.973-974, 1350, 1472) — all re-wire by `use`. Single responsibility. |
+| **3** | `handlers/health_dashboard.rs` | `HealthDashboard`, `HealthDashboardSection`, `tool_synapse_maintain` + aggregation layer (`maintain_item_list`, `maintain_failure_section`, `maintain_guard`, `maintain_count_to_severity`, `build_orphans_section`, `build_stale_runes_section`, `build_conflicts_section`, `build_gaps_section`, `build_pain_paths_section`, `build_overdue_episodes_section`, `build_audit_summary_section`, `synapse_maintain`) | ~520 | Coordinator layer — `synapse_maintain` calls 7 existing public handlers (orphans / stale / conflicts / gaps / pain_paths / episodes / audit); those handlers themselves STAY in main file. Aggregation uses `maintain_guard` macro. High internal cohesion, low external coupling. |
+
+**Combined first-pass reduction**: ~920 LOC → 8 783 LOC after Stage 3 of all three candidates. ~10% trim with zero cross-cutting refactor.
+
+**Recommended Stage 2 target**: **Thought Stack** (candidate #1). Zero cross-dependencies is the textbook "好驗證" property — wire verification is: (a) `cargo check` passes, (b) `synapse_thought_push` + `pop` + `stack_list` still dispatch via MCP. Failure modes are few and visible.
+
+---
+
+## Stage 2 — Split plan (candidate #1: Thought Stack)
+
+Produced 2026-04-21. Stage 2 is still read-only. Target locked: **Thought Stack** only.
+
+### 2.1 New file
+
+**Path**: `dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/thought_stack.rs`
+**Layout rationale**: sibling to `synapse.rs` (matches existing per-domain layout: `cortex.rs / hippocampus.rs / kenaz.rs / prefrontal.rs / synapse.rs`). `super::super::*` paths stay identical to synapse.rs — no path rewiring needed.
+
+### 2.2 Symbols to move (in source order)
+
+| lines in synapse.rs | symbol | kind | visibility |
+|---|---|---|---|
+| 65-124 | `tool_synapse_thought_push` | async fn | `pub(crate)` (unchanged) |
+| 126-161 | `tool_synapse_thought_pop` | async fn | `pub(crate)` |
+| 163-188 | `tool_synapse_thought_stack_list` | async fn | `pub(crate)` |
+| 194-198 | `THOUGHT_STACK_SCHEMA_VERSION` / `MAX_DEPTH` / `TTL_DAYS` / `MAX_TEXT_CHARS` / `FILE` | const | private (module-local) |
+| 200-212 | `ThoughtStackThought` | struct | private |
+| 214-229 | `ThoughtStackFile` + `Default` impl | struct + impl | private |
+| 231-236 | `thought_stack_path` | fn | private |
+| 238-263 | `load_thought_stack` | fn | private |
+| 265-282 | `persist_thought_stack` | fn | private |
+| 284-303 | `sweep_expired_thoughts` | fn | private |
+| 305-314 | `infer_project_name` | fn | private |
+| 316-322 | `normalize_optional_text` | fn | private |
+| 324-336 | `generate_thought_id` | fn | private |
+
+Also move the `// ===== Thought Stack =====` section header at l.190-192.
+
+**Total move**: ~207 LOC (slightly larger than Stage 1 estimate of ~180).
+
+### 2.3 Imports for the new file
+
+```rust
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+use super::super::{resolve_project, McpToolResult, ProjectInfo};
+use super::get_str;
+```
+
+No new dependencies. `chrono` and `std::path` are already used fully-qualified inline in the moved code.
+
+### 2.4 Other-file touches
+
+| file | change | scope |
+|---|---|---|
+| `mcp_tools/mod.rs` | add `pub mod thought_stack;` after `pub mod synapse;` | 1 line |
+| `routes/mcp.rs` | rewrite l.377 / l.378 / l.380: `mcp_tools::synapse::tool_synapse_thought_*` → `mcp_tools::thought_stack::tool_synapse_thought_*` | 3 lines |
+| `mcp_tools/synapse.rs` | delete l.65-336 (all Thought Stack block) | -272 lines |
+
+After patch:
+- `synapse.rs` 9 703 → ~9 431 LOC
+- new `thought_stack.rs` ~207 LOC
+- Net: same total (−0 LOC) but scope-separated
+
+### 2.5 Dependency risks
+
+| risk | severity | mitigation |
+|---|---|---|
+| `ProjectInfo` path (`super::super::`) in new file | LOW | Same super-path works because sibling placement. Verified by tracing. |
+| External symbol leak (some other module references moved fn) | LOW | Grep across `dashboard/src-tauri/src/` returned only synapse.rs + definitions.rs (strings) + mcp.rs (dispatch). No other callers. |
+| `definitions.rs` tool-name strings | NIL | `definitions.rs` references `"synapse_thought_push"` as a string literal (MCP tool advertisement) — no symbol-level dependency. |
+| `chrono::Duration` / `chrono::Utc` fully-qualified | NIL | Already fully-qualified at usage site; no import needed. |
+| `serde_json::json!` macro inside handlers | NIL | Macro resolves via `serde_json` crate import at file top. |
+
+### 2.6 Move order (single atomic commit)
+
+Execute as ONE commit so either everything lands or nothing does:
+
+1. Create `mcp_tools/thought_stack.rs` with moved symbols + new imports
+2. Add `pub mod thought_stack;` in `mcp_tools/mod.rs`
+3. Delete l.65-336 from `mcp_tools/synapse.rs`
+4. Update 3 dispatch arms in `routes/mcp.rs` (l.377, 378, 380)
+5. `cargo check -p kenaz-dashboard` — must pass with no new errors
+6. Post-merge: restart Dashboard, call `synapse_thought_push` → `synapse_thought_stack_list` → `synapse_thought_pop` via MCP; each must return expected JSON structure
+
+### 2.7 Section markers in synapse.rs (added 2026-04-21)
+
+Before Stage 3, the move region is explicitly fenced in `synapse.rs` with grep-anchorable markers:
+
+- `// BEGIN: Thought Stack — Ansuz tactical thought LIFO` (l.66, inside a 29-line marker block with full move inventory)
+- `// END: Thought Stack` (l.366, exact-match line)
+
+Stage 3 agent should move **everything between these two markers, inclusive of the markers themselves**, into `mcp_tools/thought_stack.rs`. The markers then become the file-header comment in the new file, preserving the inventory for future readers.
+
+### 2.8 Acceptance criteria (for Stage 3 task spec)
+
+- `test -f dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/thought_stack.rs` returns present
+- `grep -Fxc "// END: Thought Stack" dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/synapse.rs` returns 0 (marker fully removed from old home — use `-Fx` for exact-line match to avoid false positives from marker-referencing body text)
+- `grep -Fxc "// END: Thought Stack" dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/thought_stack.rs` returns 1 (marker preserved in new home)
+- `grep -n "pub mod thought_stack" dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/mod.rs` returns non-empty
+- `grep -n "mcp_tools::thought_stack::tool_synapse_thought" dashboard/src-tauri/src/infrastructure/http_server/routes/mcp.rs` returns 3 lines
+- `grep -c "fn tool_synapse_thought" dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/synapse.rs` returns 0 (handlers fully removed)
+- `grep -c "fn tool_synapse_thought" dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/thought_stack.rs` returns 3
+- `cargo check -p kenaz-dashboard 2>&1 | grep -c "^error"` returns 0
+- `wc -l dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/synapse.rs` returns ≤ 9 500
+
+### 2.8 Constraint clause (must appear in dispatch prompt)
+
+> 除非與本任務直接相關，否則不要修改其他函式、命名或檔案結構。不改 public API，不改 `pub(crate)` 可見性，不重命名任何符號，不 reformat 未移動的代碼。
+
+---
+
+## Stage 3 — Minimal patch (Thought Stack)
+
+Landed 2026-04-21 via TASK_1348. Thought Stack block (3 handlers + 2 structs + 6 helpers + 5 consts, 272 LOC) moved to `mcp_tools/thought_stack.rs` (309 LOC incl. marker header). `mcp.rs` dispatch rewired to `mcp_tools::thought_stack::tool_synapse_thought_*`. `cargo check -p kenaz-dashboard` passes 0 errors. Live MCP smoke test (push / pop / stack_list) deferred to next Dashboard restart — known caveat, not an AC blocker.
+
+Post-Stage-3 #1 file size: `synapse.rs` 9 703 → 9 431 LOC.
+
+---
+
+## Stage 2 — Split plan (candidate #2: Response Compression)
+
+Produced 2026-04-21. Stage 2 is still read-only. Target locked: **Response Compression**.
+
+### 3.1 Why now
+
+Stage 1 map ranked #2 the second-lowest risk. Current file still 9 431 LOC. Extracting response compression:
+
+- Clean dependency inversion: `tool_synapse_search` / `tool_synapse_context` become consumers of a sibling utility module, mirroring the `thought_stack` pattern.
+- Pure `serde_json::Value` operations — no DB, no macro, no async, no lock.
+- Fan-in is narrow: 6 call sites, all inside 2 handlers (`tool_synapse_search` l.990, `tool_synapse_context` l.1335).
+- Re-proves the sibling-file pattern (`mcp_tools/<name>.rs`) on a pure-utility split before the coordinator-layer #3 move.
+
+### 3.2 New file
+
+**Path**: `dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/response_compression.rs`
+**Layout rationale**: sibling to `synapse.rs` and `thought_stack.rs`. Same `super::super::*` import surface — zero path rewiring.
+
+### 3.3 Symbols to move (source-order, current line numbers)
+
+The move is **4 non-contiguous regions** — Stage 3 agent must handle each separately.
+
+| region | lines in synapse.rs | symbol | kind | visibility after move |
+|---|---|---|---|---|
+| A | 18-20 | `// ==== Detail Level Compression ====` header | comment | moves |
+| A | 22-25 | `estimate_tokens` | fn | private |
+| A | 27-33 | `estimate_tokens_json` | fn | private |
+| A | 35-41 | `parse_detail_level` | fn | `pub(super)` (needed by synapse.rs) |
+| A | 43-48 | `parse_token_threshold` | fn | `pub(super)` |
+| B | 66-85 | `build_overview_file_groups` | fn | private |
+| C | 1069-1071 | `// ==== Search Response Compression ====` header | comment | moves |
+| C | 1073-1127 | `compress_search_response` | fn | `pub(super)` |
+| C | 1129-1170 | `strip_snippets_from_search` | fn | private |
+| C | 1172-1193 | `build_search_overview` | fn | private |
+| D | 1195-1197 | `// ==== Context Response Compression ====` header | comment | moves |
+| D | 1199-1244 | `compress_context_response` | fn | `pub(super)` |
+| D | 1246-1269 | `strip_context_to_summary` | fn | private |
+| D | 1271-1333 | `build_context_overview` | fn | private |
+
+**Stays in synapse.rs (between regions A and B)**: `has_canonical_symbol_id_prefix` (l.50), `called_by_format_warning` (l.54). Unrelated edge-validation helpers — do NOT touch.
+
+**Total move**: ~285 LOC (design doc Stage 1 estimated 220; delta = 65 LOC, primarily `build_overview_file_groups` (20 LOC) missed in map + Region A/C/D blank lines + doc-comments).
+
+### 3.4 Imports for the new file
+
+```rust
+use serde_json::Value;
+
+use crate::features::synapse::search::HybridSearchResult;
+```
+
+No `serde::{Deserialize, Serialize}` (no structs moved). No `super::super::` imports (none needed — move scope is self-contained utility logic).
+
+### 3.5 Other-file touches
+
+| file | change | scope |
+|---|---|---|
+| `mcp_tools/mod.rs` | add `pub(crate) mod response_compression;` after `pub mod thought_stack;` | 1 line |
+| `mcp_tools/synapse.rs` | add near top: `use super::response_compression::{compress_context_response, compress_search_response, parse_detail_level, parse_token_threshold};` | 1 line (import) |
+| `mcp_tools/synapse.rs` | delete l.18-48 (region A), l.66-85 (region B), l.1069-1193 (region C), l.1195-1333 (region D) | ≈ -285 lines |
+
+No changes to `routes/mcp.rs` — none of the moved fns are dispatch targets (all are internal helpers).
+
+After patch:
+- `synapse.rs` 9 431 → ~9 150 LOC
+- new `response_compression.rs` ~290 LOC
+- Net: same total (−0 LOC) but scope-separated
+
+### 3.6 Call-site re-wire inventory
+
+Only the 6 call sites need to resolve through the new `use` import. All are inside 2 handlers:
+
+| call site | handler | symbol |
+|---|---|---|
+| l.701 | `tool_synapse_search` | `parse_detail_level` |
+| l.702 | `tool_synapse_search` | `parse_token_threshold` |
+| l.1057 | `tool_synapse_search` | `compress_search_response` |
+| l.1346 | `tool_synapse_context` | `parse_detail_level` |
+| l.1347 | `tool_synapse_context` | `parse_token_threshold` |
+| l.1629 | `tool_synapse_context` | `compress_context_response` |
+
+After the top-of-file `use` import lands, none of the call-site expressions need to change (bare names still resolve).
+
+### 3.7 Dependency risks
+
+| risk | severity | mitigation |
+|---|---|---|
+| `HybridSearchResult` path from new file | LOW | Fully-qualified path already used in original (`crate::features::synapse::search::HybridSearchResult`). Can collapse to `use` in new file. |
+| Visibility elevation of 4 fns to `pub(super)` | NIL | `pub(super)` grants visibility only within the `mcp_tools` module — still private to the crate. No external API change. |
+| `serde_json::json!` macro inside compress/build fns | NIL | `serde_json` is already a direct dep; macro resolves via crate import. |
+| Preamble has its own private `estimate_tokens` (`preamble.rs:1454`) | NIL | Different module (`crate::features::synapse::preamble`). No name collision at visibility boundary. |
+| Non-contiguous move (4 regions, not 1 block) | LOW-MEDIUM | Stage 3 agent must delete from **bottom up** (region D → C → B → A) to preserve line numbers in earlier deletions. Explicit order in move-order section below. |
+
+### 3.8 Move order (single atomic commit)
+
+Execute as ONE commit so either everything lands or nothing does:
+
+1. Create `mcp_tools/response_compression.rs` with all 10 moved fns (regions A+B+C+D concatenated, A→B→C→D order for readability) + imports.
+2. Add `pub(crate) mod response_compression;` in `mcp_tools/mod.rs`.
+3. Add `use super::response_compression::{...};` near top of `mcp_tools/synapse.rs` (after existing `use super::get_str;` line).
+4. Delete region D (l.1195-1333) from `mcp_tools/synapse.rs`.
+5. Delete region C (l.1069-1193) from `mcp_tools/synapse.rs`.
+6. Delete region B (l.66-85) from `mcp_tools/synapse.rs`.
+7. Delete region A (l.18-48) from `mcp_tools/synapse.rs`.
+8. `cargo check -p kenaz-dashboard` — must pass with 0 new errors.
+9. Post-merge: smoke test via MCP is optional — restart Dashboard and call `synapse_search` with `detail_level=summary` then `detail_level=overview`; call `synapse_context` with same. Expect identical JSON structure to pre-refactor. **Deferred — Dashboard restart caveat.**
+
+### 3.9 Acceptance criteria (grep-verifiable)
+
+- `test -f dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/response_compression.rs` returns present
+- `grep -cE "^fn (compress_search_response|compress_context_response|parse_detail_level|parse_token_threshold|estimate_tokens|estimate_tokens_json|strip_snippets_from_search|strip_context_to_summary|build_search_overview|build_context_overview|build_overview_file_groups)" dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/synapse.rs` returns 0 (all 10 handlers fully removed — note `pub(super)` fns in new file will have different prefix)
+- `grep -cE "fn (compress_search_response|compress_context_response|parse_detail_level|parse_token_threshold|estimate_tokens|estimate_tokens_json|strip_snippets_from_search|strip_context_to_summary|build_search_overview|build_context_overview|build_overview_file_groups)" dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/response_compression.rs` returns 10
+- `grep -n "pub(crate) mod response_compression" dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/mod.rs` returns non-empty
+- `grep -n "use super::response_compression::" dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/synapse.rs` returns non-empty
+- `cargo check -p kenaz-dashboard 2>&1 | grep -c "^error"` returns 0
+- `wc -l dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/synapse.rs` returns ≤ 9 200
+
+### 3.10 Constraint clause (must appear in dispatch prompt)
+
+> 除非與本任務直接相關，否則不要修改其他函式、命名或檔案結構。不改 public API。四個呼叫站點（`parse_detail_level`、`parse_token_threshold`、`compress_search_response`、`compress_context_response`）可見性提升到 `pub(super)` 即可；其餘 6 個（`estimate_tokens`、`estimate_tokens_json`、`strip_snippets_from_search`、`build_search_overview`、`strip_context_to_summary`、`build_context_overview`、`build_overview_file_groups`）保持 private。不重命名任何符號，不 reformat 未移動的代碼。不修改 `has_canonical_symbol_id_prefix` / `called_by_format_warning`（位於移除區間 A 與 B 之間，屬於 unrelated edge-validation helpers，必須原地保留）。
+
+---
+
+## Stage 3 — Minimal patch (Response Compression)
+
+_TBD — after Stage 2 §3 approval. Will become a task card (TASK_1350) with the acceptance criteria above + constraint clause, dispatched via Formation unit._
+
+<!-- TASK_1359 pre-flight guard: ran `grep -cE "^## (Stage|Stage 1)" .specialist/Ansuz/designs/refactor_mcp_tools_synapse.md` before editing; result = 5, so this append is based on the expected post-TASK_1350 document shape. -->
+
+## Stage 2 — Split plan (candidate #3: Health Dashboard)
+
+Produced 2026-04-22 via TASK_1359. Stage 2 is still read-only. Target locked: **Health Dashboard** only.
+
+This section intentionally starts at 4.x so it cannot collide with the earlier candidate #1 2.x plan or candidate #2 3.x plan. The existing sections above are source material and must remain untouched.
+
+### 4.1 New file
+
+**Path**: `dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/health_dashboard.rs`
+
+**Layout rationale**: sibling to `synapse.rs`, `thought_stack.rs`, and planned `response_compression.rs`. The Health Dashboard is a coordinator layer, not a primitive analytics engine:
+
+- It owns `HealthDashboard` / `HealthDashboardSection` response composition.
+- It calls existing health-related MCP handlers and normalizes their responses into a single report.
+- It should not absorb the implementation of orphan detection, stale-rune scanning, rune conflicts, knowledge gaps, pain paths, overdue episodes, or audit rules.
+- It should keep the same MCP tool name, `synapse_maintain`, with the dispatcher rewired to `mcp_tools::health_dashboard::tool_synapse_maintain`.
+
+The new file should expose only the handler needed by dispatch plus any minimal test-visible function if the existing tests require it. Private helper visibility should stay private unless compiler errors prove otherwise.
+
+### 4.2 Symbols to move (source-order, current line numbers)
+
+Current grep verification in this worktree places the block at `synapse.rs` l.6155-l.6677, with tests referencing `synapse_maintain` at l.8837 and l.8958. Stage 1's map came from an older line map, so the l.6744 / l.6756 references below are the original Stage 1 anchors, while the current execution agent must trust grep over stale line numbers.
+
+| Stage 1 anchor | current grep line | symbol | kind | visibility after move |
+|---|---:|---|---|---|
+| l.6744 | l.6155 | `HealthDashboardSection` | struct | private unless tests require `pub(super)` |
+| l.6756 | l.6167 | `HealthDashboard` | struct | private unless tests require `pub(super)` |
+| n/a | l.6179 | `maintain_item_list` | fn | private |
+| n/a | l.6187 | `maintain_failure_section` | fn | private |
+| n/a | l.6206 | `maintain_guard` | fn | private |
+| n/a | l.6229 | `maintain_count_to_severity` | fn | private |
+| n/a | l.6239 | `build_orphans_section` | fn | private |
+| n/a | l.6277 | `build_stale_runes_section` | fn | private |
+| n/a | l.6346 | `build_conflicts_section` | fn | private |
+| n/a | l.6394 | `build_gaps_section` | fn | private |
+| n/a | l.6440 | `build_pain_paths_section` | fn | private |
+| n/a | l.6488 | `build_overdue_episodes_section` | fn | private |
+| n/a | l.6540 | `build_audit_summary_section` | fn | private |
+| n/a | l.6594 | `synapse_maintain` | fn | private or `pub(super)` only if tests remain outside module |
+| n/a | l.6659 | `tool_synapse_maintain` | async fn | `pub(crate)` unchanged |
+
+**Expected move size**: ~740 LOC, not the Stage 1 estimate of ~520 LOC.
+
+Delta reconciliation:
+
+- `maintain_guard` is not just a trivial wrapper; it carries async/blocking failure normalization and repeated fallback-section shaping.
+- Stage 1 under-enumerated the seven `build_*_section` functions and their local JSON-shaping logic.
+- The move also includes inter-section whitespace, section comments, doc comments, and response-field normalization that were not counted in the initial rough map.
+- The current file has tests later in `synapse.rs` that reference `synapse_maintain`; Stage 3 must either move the relevant tests with the module or keep a narrow `pub(super)` seam so tests compile.
+- If the actual extracted region exceeds 900 LOC after including tests, Stage 3 should split execution into two atomic commits: first move production code and dispatch wiring, then move or rewire tests. If it remains under 900 LOC, one atomic commit is acceptable.
+
+### 4.3 Imports for the new file
+
+Start with the smallest import surface and let `cargo check` identify any missing items:
+
+```rust
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+
+use super::super::{resolve_project, McpToolResult};
+use super::get_usize;
+```
+
+Expected cross-module handler imports:
+
+```rust
+use super::hippocampus::tool_hippocampus_due_episodes;
+use super::synapse::{
+    tool_synapse_audit,
+    tool_synapse_knowledge_gaps,
+    tool_synapse_orphans,
+    tool_synapse_pain_paths,
+    tool_synapse_rune_conflicts,
+    tool_synapse_scan_stale_runes,
+};
+```
+
+Do **not** move the callee implementations listed above into `health_dashboard.rs`. They are existing public handlers with independent callers and dispatcher entries.
+
+If the extracted code currently relies on fully-qualified `tokio::task::spawn_blocking`, keep that style rather than adding an import. If it uses `chrono::Utc` fully qualified, keep it fully qualified.
+
+### 4.4 Other-file touches
+
+| file | change | scope |
+|---|---|---|
+| `mcp_tools/mod.rs` | add `pub mod health_dashboard;` near the other `mcp_tools` modules | 1 line |
+| `routes/mcp.rs` | rewrite the `synapse_maintain` arm from `mcp_tools::synapse::tool_synapse_maintain(args).await` to `mcp_tools::health_dashboard::tool_synapse_maintain(args).await` | 1 dispatch arm |
+| `mcp_tools/synapse.rs` | delete only the Health Dashboard coordinator block after it is copied into the new file | ~740 LOC |
+| `mcp_tools/synapse.rs` tests | either move `synapse_maintain` tests into `health_dashboard.rs` or update the test path narrowly | test-only touch, if compiler requires |
+
+No changes to the seven callee handler bodies. No changes to tool definitions or public MCP names.
+
+After patch, expected shape:
+
+- `synapse.rs` shrinks by roughly 700-800 LOC.
+- `health_dashboard.rs` contains the dashboard structs, helper functions, coordinator, handler, and any moved tests.
+- Net repository LOC should stay roughly neutral; this is a file-boundary refactor, not a behavior change.
+
+### 4.5 Dependency risks
+
+The coordinator calls seven existing public handlers. Verification in this worktree used exact grep fallback because Synapse indexing was empty. The callee functions are plain `pub(crate) async fn` handlers and must stay in their current modules.
+
+| callee / tool | grep result | current home | move? | risk | mitigation |
+|---|---|---|---|---|---|
+| `tool_synapse_orphans` | `pub(crate) async fn`, `synapse.rs:4895` | `mcp_tools/synapse.rs` | no | LOW | Import and call it from `health_dashboard.rs`; leave dispatcher entry unchanged. |
+| `tool_synapse_scan_stale_runes` | `pub(crate) async fn`, `synapse.rs:6628` | `mcp_tools/synapse.rs` | no | MEDIUM | It sits adjacent to the Health Dashboard block. Stage 3 must avoid over-deleting into this handler. |
+| `tool_synapse_rune_conflicts` | `pub(crate) async fn`, `synapse.rs:4382` | `mcp_tools/synapse.rs` | no | LOW | Import only; no helper inlining. |
+| `tool_synapse_knowledge_gaps` | `pub(crate) async fn`, `synapse.rs:5756` | `mcp_tools/synapse.rs` | no | LOW | Import only; existing dispatcher remains in `synapse`. |
+| `tool_synapse_pain_paths` | `pub(crate) async fn`, `synapse.rs:4480` | `mcp_tools/synapse.rs` | no | LOW | Import only; no call-site behavior change. |
+| `tool_hippocampus_due_episodes` (`hippocampus_due_episodes` MCP tool) | `pub(crate) async fn`, `hippocampus.rs:758` | `mcp_tools/hippocampus.rs` | no | LOW-MEDIUM | The Rust symbol includes the `tool_` prefix; import `super::hippocampus::tool_hippocampus_due_episodes`. |
+| `tool_synapse_audit` | `pub(crate) async fn`, `synapse.rs:5813` | `mcp_tools/synapse.rs` | no | LOW | Import only; audit implementation stays with Synapse hygiene. |
+
+Additional risks:
+
+| risk | severity | mitigation |
+|---|---|---|
+| Accidental inlining of callees into the new module | HIGH | Forbidden. `health_dashboard.rs` is the aggregation layer only. |
+| Deleting `tool_synapse_scan_stale_runes` while removing the adjacent coordinator block | MEDIUM | Fence the exact block before deleting. Start at `struct HealthDashboardSection`; end after `tool_synapse_maintain`. |
+| Tests reference private `synapse_maintain` from the old module | MEDIUM | Prefer moving the tests with the implementation. If not practical, use the narrowest visibility needed. |
+| Circular module dependency from `health_dashboard` importing `synapse` handlers | LOW | Rust sibling modules can import each other through `super::synapse`; the existing handlers are `pub(crate)`. |
+| Handler result shape drift | MEDIUM | Preserve all JSON field names and generated section names exactly. This is a move-only refactor. |
+
+### 4.6 Move order (single atomic commit, cargo-check gated)
+
+Execute as one atomic commit when the extracted production block is under 900 LOC. If tests push the move over 900 LOC, use the two-commit split described in 4.2.
+
+1. Pre-flight: confirm the design doc already contains the five prior stage headers with `grep -cE "^## (Stage|Stage 1)" .specialist/Ansuz/designs/refactor_mcp_tools_synapse.md`; expected result is `5`.
+2. In `synapse.rs`, locate the exact current Health Dashboard region with `rg -n "HealthDashboardSection|tool_synapse_maintain|synapse_maintain"`.
+3. Create `mcp_tools/health_dashboard.rs` with the moved structs, helper functions, `synapse_maintain`, and `tool_synapse_maintain`.
+4. Add `pub mod health_dashboard;` in `mcp_tools/mod.rs`.
+5. Rewire only the `synapse_maintain` dispatch arm in `routes/mcp.rs`.
+6. Delete the old Health Dashboard coordinator block from `mcp_tools/synapse.rs`.
+7. Move or narrowly rewire the `synapse_maintain` tests if `cargo check` or test compilation requires it.
+8. Run `cargo check -p kenaz-dashboard`; result must have 0 new errors.
+9. If available after Dashboard restart, smoke test `synapse_maintain` through MCP with a small `top_n` and confirm all seven sections are present.
+
+Deletion order in Stage 3 should be conservative:
+
+- Copy first.
+- Compile to expose missing imports while both copies still exist only if symbol duplication is avoided by temporary names or a staged patch; otherwise skip this compile.
+- Delete old block in one bounded hunk.
+- Compile immediately.
+
+### 4.7 Acceptance criteria (grep-verifiable)
+
+Stage 3 task spec should include these checks:
+
+- `test -f dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/health_dashboard.rs` returns present.
+- `grep -n "pub mod health_dashboard" dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/mod.rs` returns non-empty.
+- `grep -n "mcp_tools::health_dashboard::tool_synapse_maintain" dashboard/src-tauri/src/infrastructure/http_server/routes/mcp.rs` returns 1 line.
+- `grep -cE "struct HealthDashboard|fn maintain_item_list|fn maintain_failure_section|fn maintain_guard|fn maintain_count_to_severity|fn build_orphans_section|fn build_stale_runes_section|fn build_conflicts_section|fn build_gaps_section|fn build_pain_paths_section|fn build_overdue_episodes_section|fn build_audit_summary_section|fn synapse_maintain|fn tool_synapse_maintain" dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/synapse.rs` returns 0.
+- `grep -cE "struct HealthDashboard|fn maintain_item_list|fn maintain_failure_section|fn maintain_guard|fn maintain_count_to_severity|fn build_orphans_section|fn build_stale_runes_section|fn build_conflicts_section|fn build_gaps_section|fn build_pain_paths_section|fn build_overdue_episodes_section|fn build_audit_summary_section|fn synapse_maintain|fn tool_synapse_maintain" dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/health_dashboard.rs` returns at least 14.
+- `grep -cE "pub\\(crate\\) async fn (tool_synapse_orphans|tool_synapse_scan_stale_runes|tool_synapse_rune_conflicts|tool_synapse_knowledge_gaps|tool_synapse_pain_paths|tool_synapse_audit)" dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/synapse.rs` returns 6.
+- `grep -c "pub(crate) async fn tool_hippocampus_due_episodes" dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/hippocampus.rs` returns 1.
+- `grep -c "tool_synapse_maintain" dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/synapse.rs` returns 0, except test-module references if tests intentionally remain behind a `super::health_dashboard` path.
+- `cargo check -p kenaz-dashboard 2>&1 | grep -c "^error"` returns 0.
+- Optional smoke: `synapse_maintain` returns top-level keys `overall_score`, `generated_at`, `orphans`, `stale_runes`, `conflicts`, `gaps`, `pain_paths`, `overdue_episodes`, and `audit_summary`.
+
+### 4.8 Constraint clause (must appear in dispatch prompt)
+
+> 除非與本任務直接相關，否則不要修改其他函式、命名或檔案結構
+
+Stage 3 prompt must also preserve these operational constraints:
+
+- This is a move-only refactor. Do not rename `HealthDashboard`, `HealthDashboardSection`, `tool_synapse_maintain`, `maintain_item_list`, `maintain_failure_section`, `maintain_guard`, `maintain_count_to_severity`, any `build_*_section` function, or `synapse_maintain`.
+- Do not modify the seven callee handlers. They are verified existing `pub(crate) async fn` handlers and must stay in `synapse.rs` / `hippocampus.rs`.
+- Do not rewrite response schema field names or section names.
+- Do not expand the task into Health score internals, orphan detection internals, audit rule internals, or Hippocampus overdue episode logic.
+- Do not reformat unrelated regions in `synapse.rs`.
+- Keep public MCP tool names unchanged.