refactor: extract tool definitions into modular structure (BL-041)

docs/backlog.md

@@ -103,7 +103,7 @@
 
 | BL-ID | Title | Priority | Status | OpenSpec Change ID | Spec Path | Notes |
 |---|---|---|---|---|---|---|
-| BL-041 | Tool registration 模組化拆分 | P1 | planned | TBD | TBD | `src/index.ts` 目前含 26 個 tool 定義；先拆 `tools/memory.ts`、`tools/feedback.ts`、`tools/episodic.ts` 降低耦合 [Surface: Plugin] |
+| BL-041 | Tool registration 模組化拆分 | P1 | **done** | bl-041-tool-registration-modularization | openspec/changes/bl-041-tool-registration-modularization/ | 將 26 個 tool 定義從 index.ts 拆分至 `tools/memory.ts`、`tools/feedback.ts`、`tools/episodic.ts` 降低耦合 [Surface: Plugin] |
 | BL-042 | Store repository 職責分離 | P2 | planned | TBD | TBD | 將 `MemoryStore` 逐步拆為 `MemoryRepository` / `EventRepository` / `EpisodicTaskRepository`，由 provider 統一連線管理 [Surface: Plugin] |
 | BL-043 | Episodic 更新流程 DRY 化 | P1 | **done** | episodic-update-dry | `openspec/changes/episodic-update-dry/` | `addCommandToEpisode`、`addValidationOutcome`、`addSuccessPatterns`、`addRetryAttempt`、`addRecoveryStrategy` 以共用 updater 模板收斂 [Surface: Plugin] |
 | BL-044 | Duplicate consolidation 擴充性重構 | P1 | **done** | bl-044-duplicate-consolidation-ann-chunking | `openspec/changes/archive/2026-03-31-bl-044-duplicate-consolidation-ann-chunking/` | 以 ANN top-k / chunking 取代全表 O(N²) 比對，避免 `consolidateDuplicates` 在大 scope 阻塞 event loop [Surface: Plugin] |

docs/roadmap.md

@@ -402,7 +402,7 @@ OpenCode 要從「有長期記憶的工具」進化成「會累積團隊工作
 8. `effectiveness_events` TTL / archival（Surface: Plugin）→ BL-037
 9. backoff / cooldown signal ingestion（Surface: Plugin；**blocked by upstream events**）→ BL-021
 10. 條件式 user/team precedence（僅在多使用者需求成立時）
-11. Tool registration 模組化拆分（Surface: Plugin）→ BL-041
+11. Tool registration 模組化拆分（Surface: Plugin）→ BL-041 ✅ DONE
 12. Episodic 更新流程 DRY 化（Surface: Plugin）→ BL-043
 13. Duplicate consolidation 擴充性重構（Surface: Plugin）→ BL-044 ✅ DONE
 14. Scope cache 記憶體治理（Surface: Plugin）→ BL-045 ✅ DONE

openspec/changes/archive/2026-03-31-bl-041-tool-registration-modularization/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-31

openspec/changes/archive/2026-03-31-bl-041-tool-registration-modularization/design.md

@@ -0,0 +1,85 @@
+# Design: BL-041 Tool Registration Modularization
+
+> **Backlog ID**: BL-041  
+> **Runtime Surface**: internal-api (code refactoring)
+
+---
+
+## Decision Table
+
+| Decision | Choice | Why | Trade-off |
+|---|---|---|---|
+| Directory structure | `src/tools/` with domain-based files | Aligns with proposed split: memory/feedback/episodic | Requires updating imports across the codebase |
+| Tool grouping | By functional domain | memory: search, stats, remember, forget, citation, etc.<br>feedback: missing, wrong, useful<br>episodic: task_episode_*, similar_task_recall, retry/recovery | Some tools span domains - will colocate by primary purpose |
+| Export strategy | Factory functions returning tool definitions | Allows state injection while keeping tool definitions modular | Slight indirection vs direct export |
+| Backward compatibility | Re-export all tools from index.ts | Existing integration points remain unchanged | index.ts remains as thin facade |
+
+---
+
+## Architecture
+
+```
+src/
+  index.ts           # Plugin entry, hooks, state management
+  tools/
+    memory.ts        # Tool definitions: search, stats, remember, forget, citation, etc.
+    feedback.ts      # Tool definitions: feedback_missing, feedback_wrong, feedback_useful, etc.
+    episodic.ts      # Tool definitions: task_episode_*, similar_task_recall, retry/recovery
+    index.ts         # Re-exports all tools for compatibility
+```
+
+### Tool Groupings
+
+**memory.ts** - Memory management tools:
+- memory_search, memory_delete, memory_clear, memory_stats
+- memory_remember, memory_forget
+- memory_citation, memory_validate_citation
+- memory_what_did_you_learn, memory_why, memory_explain_recall
+- memory_scope_promote, memory_scope_demote, memory_global_list
+- memory_consolidate, memory_consolidate_all
+- memory_port_plan
+- memory_dashboard, memory_kpi
+
+**feedback.ts** - Feedback-related tools:
+- memory_feedback_missing
+- memory_feedback_wrong
+- memory_feedback_useful
+- memory_effectiveness
+
+**episodic.ts** - Task/episode learning tools:
+- task_episode_create
+- task_episode_query
+- similar_task_recall
+- retry_budget_suggest
+- recovery_strategy_suggest
+
+---
+
+## Operability
+
+### Trigger Path
+- This is an internal refactoring; no runtime behavior changes
+- All existing tool names and schemas remain identical
+
+### Expected Behavior
+- All 26 tools should function identically before and after refactoring
+- No changes to hook wiring, config, or runtime state
+
+### Misconfiguration Behavior
+- If imports are broken, TypeScript compilation will fail
+- If tool exports are missing, runtime will fail to register tools
+
+---
+
+## Verification
+
+### Unit Tests
+- Each tool file should have unit tests for tool definitions
+- Verify tool names, descriptions, and schemas are preserved
+
+### Integration Tests
+- Plugin loads and registers all tools successfully
+- All tool execute functions work with mock state
+
+### E2E
+- Not required (internal-only refactoring)

openspec/changes/archive/2026-03-31-bl-041-tool-registration-modularization/proposal.md

@@ -0,0 +1,65 @@
+# Proposal: BL-041 Tool Registration Modularization
+
+> **Backlog ID**: BL-041  
+> **Status**: planned  
+> **Surface**: Plugin (internal refactoring)  
+> **Release Impact**: internal-only
+
+---
+
+## Problem Statement
+
+`src/index.ts` currently contains 26 tool definitions along with hooks, injection logic, and core business logic. This creates several issues:
+
+1. **High coupling**: Changing one tool's implementation risks breaking others
+2. **Hard to test**: Large monolithic file makes unit testing difficult
+3. **Code review friction**: 1626 lines in one file is hard to review thoroughly
+4. **Slow iteration**: Any change requires understanding the entire file
+
+The roadmap explicitly calls for modularization: "先拆 `tools/memory.ts`、`tools/feedback.ts`、`tools/episodic.ts` 降低耦合"
+
+## What Changes
+
+- Extract 26 tool definitions from `src/index.ts` into modular files in `src/tools/`
+- Create `src/tools/memory.ts`, `src/tools/feedback.ts`, `src/tools/episodic.ts`
+- Add `src/tools/index.ts` for re-exports
+- Update imports in `src/index.ts`
+
+## Why
+
+- Reduce file size and complexity in index.ts
+- Improve maintainability and testability
+- Enable future feature additions without further growth
+
+## Why Now
+
+- The plugin has matured with 26 stable tools
+- Future features (BL-040 playbook, BL-037 TTL) will add more tools
+- Without modularization, the file will continue to grow, making maintenance increasingly difficult
+
+## Scope
+
+### In Scope
+- Split tool definitions into separate modules under `src/tools/`
+- Maintain backward compatibility for all tool names and interfaces
+- Ensure all existing functionality works identically after refactoring
+
+### Out of Scope
+- No changes to tool behavior or schema
+- No changes to hook wiring (these can stay in index.ts)
+- No new features
+
+## Impacted Modules
+
+- `src/index.ts` → `src/tools/memory.ts`, `src/tools/feedback.ts`, `src/tools/episodic.ts`
+- Export interfaces must remain compatible
+
+## Changelog Wording Class
+
+`internal-only` - No user-facing changes. This is purely a refactoring to improve maintainability.
+
+---
+
+## Risk Level
+
+**Low** - This is a refactoring task with no behavioral changes. The primary risk is breaking existing tool exports, which can be caught by the test suite.

openspec/changes/archive/2026-03-31-bl-041-tool-registration-modularization/specs/tool-registration/spec.md

@@ -0,0 +1,129 @@
+# Spec: Tool Registration Modularization
+
+> **Change ID**: bl-041-tool-registration-modularization  
+> **Runtime Surface**: internal-api  
+> **Entrypoint**: `src/tools/*.ts`, `src/index.ts` re-exports
+
+---
+
+## Requirement: Tool Definitions Preserved
+
+The system SHALL preserve all existing tool definitions with identical names, descriptions, and schemas.
+
+Runtime Surface: internal-api  
+Entrypoint: `src/tools/memory.ts`, `src/tools/feedback.ts`, `src/tools/episodic.ts`
+
+### Scenario: All memory tools exist
+- WHEN the plugin is loaded
+- THEN all memory-related tools are registered:
+  - memory_search, memory_delete, memory_clear, memory_stats
+  - memory_remember, memory_forget
+  - memory_citation, memory_validate_citation
+  - memory_what_did_you_learn, memory_why, memory_explain_recall
+  - memory_scope_promote, memory_scope_demote, memory_global_list
+  - memory_consolidate, memory_consolidate_all
+  - memory_port_plan
+  - memory_dashboard, memory_kpi
+
+### Scenario: All feedback tools exist
+- WHEN the plugin is loaded
+- THEN all feedback tools are registered:
+  - memory_feedback_missing
+  - memory_feedback_wrong
+  - memory_feedback_useful
+  - memory_effectiveness
+
+### Scenario: All episodic tools exist
+- WHEN the plugin is loaded
+- THEN all episodic/task tools are registered:
+  - task_episode_create
+  - task_episode_query
+  - similar_task_recall
+  - retry_budget_suggest
+  - recovery_strategy_suggest
+
+---
+
+## Requirement: Tool Schemas Unchanged
+
+The system SHALL maintain identical tool argument schemas after modularization.
+
+Runtime Surface: internal-api  
+Entrypoint: `src/tools/*.ts`
+
+### Scenario: Schema compatibility
+- GIVEN existing tool definitions in production
+- WHEN comparing old and new tool schemas
+- THEN all tool.name, tool.description, and tool.args are identical
+
+---
+
+## Requirement: Tool Execution Works
+
+The system SHALL execute tool functions with the same behavior as before refactoring.
+
+Runtime Surface: internal-api  
+Entrypoint: `src/tools/*.ts` execute functions
+
+### Scenario: Tool execution with state
+- GIVEN initialized plugin state
+- WHEN executing a tool (e.g., memory_search)
+- THEN the tool executes successfully and returns expected output format
+
+### Scenario: Tool handles uninitialized state
+- GIVEN uninitialized plugin state
+- WHEN executing a tool
+- THEN the tool returns the unavailable message
+
+---
+
+## Requirement: Module Structure Valid
+
+The system SHALL have tools organized in domain-specific modules.
+
+Runtime Surface: internal-api  
+Entrypoint: `src/tools/index.ts` re-exports
+
+### Scenario: Module exports exist
+- WHEN importing from `src/tools/`
+- THEN all tools are exported from appropriate modules
+- AND all tools are re-exported from `src/tools/index.ts`
+
+### Scenario: Import paths work
+- WHEN TypeScript compiles the project
+- THEN all import paths resolve correctly
+- AND no circular dependency errors
+
+---
+
+## Observability
+
+### Inspection Points
+- TypeScript compilation success/failure
+- Plugin load success/failure
+- All 26 tools registered in plugin hooks
+
+---
+
+## Verification Matrix
+
+| Requirement | Unit | Integration | E2E | Required to release |
+|---|---|---|---|---|
+| Tool definitions preserved | ✅ | ✅ | n/a | yes |
+| Tool schemas unchanged | ✅ | n/a | n/a | yes |
+| Tool execution works | ✅ | ✅ | n/a | yes |
+| Module structure valid | ✅ | n/a | n/a | yes |
+
+---
+
+## ADDED
+
+- `src/tools/` directory with modular tool definitions
+- `src/tools/memory.ts` - 19 memory-related tools
+- `src/tools/feedback.ts` - 4 feedback tools
+- `src/tools/episodic.ts` - 5 episodic/task tools
+- `src/tools/index.ts` - re-exports for backward compatibility
+
+## MODIFIED
+
+- `src/index.ts` - reduced from 1626 to ~620 lines, imports tools from new modules

openspec/changes/archive/2026-03-31-bl-041-tool-registration-modularization/tasks.md

@@ -0,0 +1,76 @@
+# Tasks: BL-041 Tool Registration Modularization
+
+> **Change ID**: bl-041-tool-registration-modularization
+
+---
+
+## Implementation Tasks
+
+### Phase 1: Create tool module directory structure
+
+- [x] Create `src/tools/` directory
+- [x] Create `src/tools/index.ts` for re-exports
+
+### Phase 2: Extract memory tools
+
+- [x] Create `src/tools/memory.ts`
+- [x] Move memory_search tool definition to memory.ts
+- [x] Move memory_delete tool definition to memory.ts
+- [x] Move memory_clear tool definition to memory.ts
+- [x] Move memory_stats tool definition to memory.ts
+- [x] Move memory_remember tool definition to memory.ts
+- [x] Move memory_forget tool definition to memory.ts
+- [x] Move memory_citation tool definition to memory.ts
+- [x] Move memory_validate_citation tool definition to memory.ts
+- [x] Move memory_what_did_you_learn tool definition to memory.ts
+- [x] Move memory_why tool definition to memory.ts
+- [x] Move memory_explain_recall tool definition to memory.ts
+- [x] Move memory_scope_promote tool definition to memory.ts
+- [x] Move memory_scope_demote tool definition to memory.ts
+- [x] Move memory_global_list tool definition to memory.ts
+- [x] Move memory_consolidate tool definition to memory.ts
+- [x] Move memory_consolidate_all tool definition to memory.ts
+- [x] Move memory_port_plan tool definition to memory.ts
+- [x] Move memory_dashboard tool definition to memory.ts
+- [x] Move memory_kpi tool definition to memory.ts
+
+### Phase 3: Extract feedback tools
+
+- [x] Create `src/tools/feedback.ts`
+- [x] Move memory_feedback_missing tool definition to feedback.ts
+- [x] Move memory_feedback_wrong tool definition to feedback.ts
+- [x] Move memory_feedback_useful tool definition to feedback.ts
+- [x] Move memory_effectiveness tool definition to feedback.ts
+
+### Phase 4: Extract episodic tools
+
+- [x] Create `src/tools/episodic.ts`
+- [x] Move task_episode_create tool definition to episodic.ts
+- [x] Move task_episode_query tool definition to episodic.ts
+- [x] Move similar_task_recall tool definition to episodic.ts
+- [x] Move retry_budget_suggest tool definition to episodic.ts
+- [x] Move recovery_strategy_suggest tool definition to episodic.ts
+
+### Phase 5: Update index.ts imports and hooks
+
+- [x] Update `src/index.ts` imports to use new tool modules
+- [x] Wire up all tools from new modules in hooks.tool
+- [x] Verify TypeScript compilation succeeds
+
+### Phase 6: Verification
+
+- [x] Add unit tests for tool definitions in each module
+- [x] Add integration test to verify all 26 tools register successfully
+- [x] Run existing test suite to ensure no regressions
+- [x] Verify plugin loads correctly in test environment
+
+---
+
+## Verification Matrix
+
+| Requirement | Unit | Integration | E2E | Required to release |
+|---|---|---|---|---|
+| Tool definitions preserved | ✅ | ✅ | n/a | yes |
+| Tool schemas unchanged | ✅ | n/a | n/a | yes |
+| Tool execution works | ✅ | ✅ | n/a | yes |
+| Module structure valid | ✅ | n/a | n/a | yes |