claude_memory 0.7.1 → 0.9.0

data/docs/quality_review.md

@@ -1,18 +1,20 @@
 # Code Quality Review - Ruby Best Practices
 
-**Review Date:** 2026-03-09
-**Previous Review:** 2026-02-04
-**Last Quality Update:** 2026-02-04 (21/24 items completed)
+**Review Date:** 2026-03-19
+**Previous Review:** 2026-03-09
+**Last Quality Update:** 2026-03-20 (13 items completed)
 
 ---
 
 ## Executive Summary
 
-The codebase has grown from 9,982 to 11,392 LOC since the Feb 4 review. Core architecture remains solid — functional core, proper layering, zero bare rescues, zero N+1 queries in hot paths. The 3 files on the previous watch list have all grown: `tools.rb` (610→728), `recall.rb` (608→681), `sqlite_store.rb` (481→547). All three now exceed 500 lines.
+The codebase has grown from 11,392 to 12,239 LOC since the Mar 9 review. A configurable embedding provider system was added (+847 LOC across 5 new files and 8 modified files). The three watch-list files have grown further: `tools.rb` (728→745), `recall.rb` (681→727), `sqlite_store.rb` (547→547, unchanged). All three remain above 500 lines.
 
-**New issues found:** 18 items (2 critical, 4 high, 7 medium, 5 low)
-**Carried forward:** 9 items from previous review (1 medium, 8 low)
-**Total remaining:** 27 items
+Five items were resolved in the Mar 19 quality update session: the Shortcuts scope bug (correctness), ApiAdapter exception typing, silent exception logging (3 locations), dead Configuration accessors removed, and `index_database` decomposed into focused methods. No known correctness bugs remain.
+
+**Resolved this session:** 13 items (#1 Tools god object, #2 Recall legacy/dual strategy, #3 Shortcuts scope, #4 SQLiteStore extraction, #9 test coverage for critical files, NEW-1 ApiError, NEW-2 dead accessors, NEW-3 silent rescues, #5 index_database decomposition, #6 promote_fact transaction, #7 provenance nil content_item_id, #12 Resolver mutable state, #19 SnippetExtractor DRY)
+**Resolved since last review:** 3 additional items (ExportCommand N+1, `discover_other_projects` bare rescue, embedding test coverage)
+**Total remaining:** 12 items (0 high, 5 medium, 4 low, 5 carried forward — all structural work complete)
 
 ### Current Strengths
 
@@ -20,70 +22,36 @@ The codebase has grown from 9,982 to 11,392 LOC since the Feb 4 review. Core arc
 - Domain objects: properly frozen and self-validating
 - Null object pattern: NullFact, NullExplanation
 - Result monad: Core::Result for Success/Failure
-- 100% frozen_string_literal compliance (112 files)
-- 1.90:1 test-to-code ratio (21,632 spec : 11,392 lib)
-- Zero bare rescues in hot paths, zero N+1 in query paths
-- Well-structured batch loading via FactQueryBuilder
+- 100% frozen_string_literal compliance (117 files)
+- 1.84:1 test-to-code ratio (22,563 spec : 12,239 lib)
+- New embedding subsystem: shared RSpec examples, duck-typed providers, Data.define value object
+- Zero N+1 patterns in hot paths
+- Proper batch loading via FactQueryBuilder
+- Content-addressed dedup in IndexCommand
+- DimensionCheck value object (functional core, no side effects)
+- Zero known correctness bugs
 
 ---
 
 ## 1. Sandi Metz Perspective
 
 ### What's Been Fixed ✅
-- N+1 queries eliminated in prior review
-- Long methods decomposed (resolve_fact, detailed_stats, check_setup)
-- Classes extracted (SchemaValidator, OperationTracker)
+- New embedding providers follow duck typing contract (no base class inheritance)
+- Shared RSpec examples verify provider contract (`spec/support/shared_examples/embedding_provider.rb`)
+- `set_meta`/`get_meta` promoted to public API (needed by DimensionCheck, VectorIndex)
+- ExportCommand N+1 eliminated with batch loading
+- **Shortcuts scope bug fixed** — scopes changed from symbols to strings to match DualQueryTemplate comparisons
+- **`index_database` decomposed** — split 130-line method into 5 focused methods: `index_database` (orchestrator), `handle_dimension_mismatch`, `find_facts_to_index`, `run_indexing`, `process_batch`, `report_dedup_stats`
+- **Tools god object eliminated** — split 745-line `Tools` class into thin 104-line dispatcher + 6 handler modules: `QueryHandlers` (90), `ShortcutHandlers` (37), `ContextHandlers` (38), `ManagementHandlers` (124), `StatsHandlers` (188), `SetupHandlers` (211). No file exceeds 211 lines. Public API unchanged.
+- **Recall legacy/dual duplication eliminated** — split 727-line `Recall` into thin 94-line facade + strategy engines: `DualEngine` (101), `LegacyEngine` (134), shared `QueryCore` module (357). The `if @legacy_mode` branching in every public method is replaced by engine delegation. Public API unchanged.
 
 ### Critical Issues 🔴
 
-| # | Issue | File:Line | Effort |
-|---|-------|-----------|--------|
-| 1 | **Tools god object (728 lines, 48 methods)** | `mcp/tools.rb:1-728` | 2-3 days |
-
-The `Tools` class handles all 21 MCP tool implementations in a single file. The `call` dispatcher (lines 29-76) is a 21-branch case statement. Each handler mixes parameter extraction, domain logic, and response formatting. Individual tool handlers like `store_extraction` (lines 221-262, 41 lines) and `discover_other_projects` (lines 565-614, 50 lines) violate the 15-line method limit.
-
-**Fix:** Extract each tool handler into its own class (e.g., `RecallHandler`, `StoreExtractionHandler`) with a common interface, registered via a handler registry.
-
-| # | Issue | File:Line | Effort |
-|---|-------|-----------|--------|
-| 2 | **Recall class too large (681 lines, 74 methods)** | `recall.rb:1-681` | 2 days |
-
-Every public method branches on `@legacy_mode` with parallel `_legacy` / `_dual` implementations (lines 42-56, 58-66, etc.). ~150+ lines of duplicated branching logic. The class has 74 methods — far beyond single responsibility.
-
-**Fix:** Extract `LegacyQueryEngine` and `DualQueryEngine` classes implementing a common `QueryEngine` interface. Inject the appropriate engine at initialization based on `store_or_manager` type.
+None remaining.
 
 ### High Priority Issues
 
-| # | Issue | File:Line | Effort |
-|---|-------|-----------|--------|
-| 3 | **ExportCommand N+1 queries** | `commands/export_command.rb:83-85` | 30 min |
-
-Inside the `collect_from_store` loop, each fact triggers 2 individual queries — one for the subject entity (line 84) and one for provenance records (line 85). With 100+ facts this becomes 200+ queries.
-
-```ruby
-# Current (N+1):
-facts_ds.each do |fact|
-  subject = store.entities.where(id: fact[:subject_entity_id]).first
-  receipts = store.provenance.where(fact_id: fact[:id]).all
-end
-
-# Fix (batch):
-all_facts = facts_ds.all
-entity_ids = all_facts.map { |f| f[:subject_entity_id] }.compact.uniq
-entities_by_id = store.entities.where(id: entity_ids).all
-  .each_with_object({}) { |e, h| h[e[:id]] = e }
-fact_ids = all_facts.map { |f| f[:id] }
-provenance_by_fact = store.provenance.where(fact_id: fact_ids).all
-  .group_by { |p| p[:fact_id] }
-```
-
-| # | Issue | File:Line | Effort |
-|---|-------|-----------|--------|
-| 4 | **SQLiteStore exceeds 500 lines (547)** | `store/sqlite_store.rb:1-547` | 1 day |
-
-The file combines database connection, retry logic, schema management, migrations, and all CRUD operations. Schema migrations alone account for ~100 lines.
-
-**Fix:** Extract `SchemaManager` module for migration methods, and consider a `RetryHandler` module for retry logic (lines 24-60).
+None remaining. All >500-line files have been decomposed.
 
 ---
 
@@ -92,88 +60,46 @@ The file combines database connection, retry logic, schema management, migration
 ### What's Been Fixed ✅
 - Batch queries in Recall pipeline (FactQueryBuilder)
 - Transaction wrapping in Resolver
-- Proper Sequel DSL usage throughout
-
-### Critical Issues 🔴
-
-| # | Issue | File:Line | Effort |
-|---|-------|-----------|--------|
-| 5 | **Bare rescue in discover_other_projects** | `mcp/tools.rb:607` | 10 min |
-
-```ruby
-rescue => _e
-  entry[:error] = "Could not read database"
-end
-```
-
-This catches *all* exceptions including `NoMemoryError`, `SystemExit`, `Interrupt`. Should use specific exception types.
-
-**Fix:** `rescue Sequel::DatabaseError, Extralite::Error, IOError => _e`
+- ExportCommand N+1 eliminated
+- `discover_other_projects` now catches specific exception types (`Sequel::DatabaseError, Extralite::Error, IOError`)
+- **promote_fact transaction boundary fixed** — project data read before global transaction (already correct in code; verified and confirmed)
+- **Provenance nil content_item_id fixed** — removed mandatory `content_item_id` validation from `Domain::Provenance`, allowing nil for promoted facts
 
 ### Medium Issues 🟡
 
-| # | Issue | File:Line | Effort |
-|---|-------|-----------|--------|
-| 6 | **Transaction boundary mismatch in promote_fact** | `store/store_manager.rb:89-124` | 30 min |
-
-The transaction wraps `@global_store.db.transaction` but `copy_provenance` (line 121) reads from `@project_store` inside the global transaction. If `@project_store` fails mid-read after global writes, the global transaction still commits (autocommit on the project side). Not a data loss risk but a consistency concern.
-
-**Fix:** Read all provenance records from project store *before* the global transaction:
-
-```ruby
-provenance_records = @project_store.provenance.where(fact_id: fact_id).all
-@global_store.db.transaction do
-  # ... create entities and fact ...
-  provenance_records.each { |prov| @global_store.insert_provenance(...) }
-end
-```
-
-| # | Issue | File:Line | Effort |
-|---|-------|-----------|--------|
-| 7 | **Provenance insert with nil content_item_id** | `store/store_manager.rb:133` | 20 min |
-
-`copy_provenance` passes `content_item_id: nil` when promoting facts. If `insert_provenance` in SQLiteStore validates this field, it will fail silently or raise. The Domain `Provenance` class validates non-nil `content_item_id`.
-
-**Fix:** Use a sentinel value like `"promoted"` or make `content_item_id` nullable in the provenance domain model for promoted facts.
-
 | # | Issue | File:Line | Effort |
 |---|-------|-----------|--------|
 | 8 | **upsert_content_item has 11 keyword parameters** | `store/sqlite_store.rb:158-184` | 1 hour |
 
-Exceeds the 5-parameter guideline significantly. Suggests the method is doing too much.
+Exceeds the 5-parameter guideline. Suggests the method is doing too much.
 
-**Fix:** Introduce a `ContentItemAttributes` value object:
-
-```ruby
-attrs = ContentItemAttributes.new(source:, session_id:, text_hash:, byte_len:, ...)
-store.upsert_content_item(attrs)
-```
+**Fix:** Introduce a `ContentItemAttributes` value object.
 
 ---
 
 ## 3. Kent Beck Perspective
 
 ### What's Been Fixed ✅
-- Test-to-code ratio improved to 1.90:1
-- Clear boundaries between layers
+- New embedding subsystem has full test coverage (4 spec files, shared examples)
+- `generator_spec.rb` now tests `name`/`dimensions` contract
+- DimensionCheck tested for all 3 states (`:fresh`, `:match`, `:mismatch`)
+- ApiAdapter tested with HTTP mocks (no WebMock dependency)
+- **5 critical untested files now have specs** — `similarity.rb` (10 tests), `metadata_extractor.rb` (9 tests), `tool_extractor.rb` (7 tests), `recover_command.rb` (3 tests), `schema_validator.rb` (6 tests). Total: +36 specs, suite now at 1444.
 
 ### High Priority Issues
 
-| # | Issue | File:Line | Effort |
-|---|-------|-----------|--------|
-| 9 | **16 lib files without tests** | Multiple | 2-3 days |
+None remaining. All high-priority items are resolved.
 
-Critical untested files:
-- `embeddings/generator.rb` (161 lines of math/algorithm code)
-- `embeddings/similarity.rb`
-- `embeddings/fastembed_adapter.rb`
-- `commands/stats_command.rb` (239 lines)
-- `commands/export_command.rb` (108 lines)
-- `commands/recover_command.rb` (75 lines)
-- `infrastructure/schema_validator.rb` (215 lines)
-- `ingest/metadata_extractor.rb`, `ingest/tool_extractor.rb`
+### Remaining Untested Files (lower priority)
 
-Database migrations 8-11 also lack migration-specific tests.
+Thin CLI wrappers that delegate to already-tested classes:
+- `commands/stats_command.rb`, `commands/export_command.rb`
+- `commands/changes_command.rb`, `commands/conflicts_command.rb`, `commands/explain_command.rb`
+- `commands/recall_command.rb`, `commands/search_command.rb`
+- `commands/sweep_command.rb`, `commands/publish_command.rb`, `commands/ingest_command.rb`
+- `commands/db_init_command.rb`
+- `commands/checks/` (6 files), `commands/initializers/` (5 files)
+- `mcp/tool_helpers.rb`, `embeddings/fastembed_adapter.rb`, `distill/distiller.rb`
 
 ### Medium Issues 🟡
 
@@ -198,78 +124,65 @@ Three `sleep 1.01` calls wait for filesystem mtime changes. `publish_spec.rb:189
 ## 4. Avdi Grimm Perspective
 
 ### What's Been Fixed ✅
-- Null objects used properly (NullFact, NullExplanation)
-- Result monad for Success/Failure
-- Domain objects frozen and self-validating
+- DimensionCheck returns a Result value object — no exceptions, no side effects
+- `Embeddings.resolve` raises `ArgumentError` with clear message for unknown providers
+- ApiAdapter raises with descriptive messages for missing API keys
+- Duck typing for embedding providers (no base class)
+- **ApiAdapter now uses typed `ApiError < StandardError`** instead of bare `raise "message"`
+- **Resolver mutable state resolved** — verified that `project_path` and `scope` are already threaded as parameters through the entire method chain; no mutable instance state exists
 
-### Medium Issues 🟡
-
-| # | Issue | File:Line | Effort |
-|---|-------|-----------|--------|
-| 12 | **Resolver mutable state after init** | `resolve/resolver.rb:12-13` | 30 min |
-
-`@current_project_path` and `@current_scope` are set in `apply()` (line 12-13) rather than threaded as parameters through the method chain. This makes the Resolver stateful between calls.
-
-**Fix:** Pass `project_path` and `scope` as explicit parameters to `resolve_fact`, `create_conflict`, etc.
-
-*(Carried forward from previous review as #16)*
+### Carried Forward Issues 🟡
 
 | # | Issue | File:Line | Effort |
 |---|-------|-----------|--------|
 | 13 | **Inconsistent payload validation in hooks** | `hook/handler.rb:17-53` | 30 min |
 
-`ingest` uses `.fetch("field")` with fallback, `sweep` uses `.fetch("budget", default)`, `publish` uses `.fetch("mode", "shared")`. No consistent schema validation pattern.
-
-**Fix:** Create a `PayloadValidator` or use a simple schema hash to validate required/optional fields uniformly.
+`ingest` uses `.fetch("field")` with fallback, `sweep` uses `.fetch("budget", default)`, `publish` uses `.fetch("mode", "shared")`. No consistent validation pattern.
 
 ---
 
 ## 5. Gary Bernhardt Perspective
 
 ### What's Been Fixed ✅
-- Strong functional core / imperative shell separation
-- Value objects (FactId, SessionId, TranscriptPath) are immutable
-- Pure logic in FactRanker, ConceptRanker, SnippetExtractor
+- DimensionCheck is pure: takes store + provider, returns immutable Result. No hidden side effects.
+- `clear_stale_embeddings` was moved from hidden infrastructure setup to explicit command-level call.
+- VectorIndex#clear! encapsulates vec0 table knowledge (no raw SQL in command).
+- **Dead Configuration embedding accessors removed** — resolver and ApiAdapter read ENV directly, no unused indirection.
 
-### High Priority Issues
+### Carried Forward Issues 🟡
 
 | # | Issue | File:Line | Effort |
 |---|-------|-----------|--------|
 | 14 | **I/O mixed with logic in discover_other_projects** | `mcp/tools.rb:565-614` | 1 hour |
 
-This method performs: SQL queries (lines 572-590), filesystem checks (line 598: `File.exist?`), database connections in a loop (lines 602-606), and error handling. Pure imperative shell with no separation.
-
-**Fix:** Extract database discovery to a pure function that returns paths, and filesystem/DB checks to an imperative wrapper.
-
-### Medium Issues 🟡
+SQL queries, filesystem checks, database connections in a loop, and error handling all mixed together.
 
 | # | Issue | File:Line | Effort |
 |---|-------|-----------|--------|
 | 15 | **Sweeper mutable state** | `sweep/sweeper.rb:16-17` | 20 min |
 
-*(Carried forward from previous review as #21)*
-
 | # | Issue | File:Line | Effort |
 |---|-------|-----------|--------|
 | 16 | **Dir.chdir in publish tests** | `spec/publish_spec.rb:14` | 15 min |
 
-Tests use `Dir.chdir(test_dir)` which modifies global state. Fragile if tests ever run in parallel.
-
-**Fix:** Use `Dir.chdir(test_dir) { ... }` block form or inject working directory.
-
 ---
 
 ## 6. General Ruby Idioms
 
+### What's Been Fixed ✅
+- **Silent exception swallowing resolved** — 3 bare rescue blocks now log via `ClaudeMemory.logger.debug(...)`:
+  - `mcp/instructions_builder.rb:29`
+  - `hook/context_injector.rb:47`
+  - `commands/checks/vec_check.rb:55`
+
+- **SnippetExtractor range calculation DRY** — extracted `snippet_range` method to eliminate duplicated start/end index computation between `extract_with_lines` and `build_snippet`
+
+### Carried Forward Issues
+
 | # | Issue | File:Line | Severity | Effort |
 |---|-------|-----------|----------|--------|
 | 17 | **ResponseFormatter duplication** | `mcp/response_formatter.rb:27-280` | 🟡 Medium | 1 hour |
 | 18 | **Publish section generator repetition** | `publish.rb:100-154` | Low | 30 min |
-| 19 | **SnippetExtractor validation duplication** | `core/snippet_extractor.rb:18-31` | Low | 10 min |
-
-`ResponseFormatter` has 4 nearly identical `format_*_fact` methods (`format_recall_fact`, `format_semantic_fact`, `format_concept_fact`, etc.) sharing ~80% of code. Extract a base `format_fact` method with field selection.
-
-`Publish` has 4 similar section generators (decisions, conventions, constraints, conflicts) each filtering facts by predicate and building markdown. Extract a `SectionBuilder`.
 
 ---
 
@@ -281,37 +194,26 @@ Tests use `Dir.chdir(test_dir)` which modifies global state. Fragile if tests ev
 - **Proper Sequel usage**: Datasets used consistently, raw SQL avoided almost entirely
 - **Excellent domain modeling**: Fact, Entity, Provenance are immutable value objects with validation
 - **Good file organization**: ~1 class per file, consistent naming, clear module nesting
-- **Strong test culture**: 1.90:1 test-to-code ratio, behavior-focused tests
+- **Strong test culture**: 1.84:1 test-to-code ratio, behavior-focused tests
 - **Infrastructure abstractions**: `FileSystem`, `InMemoryFileSystem` enable fast tests
 - **Core::Result monad**: Consistent Success/Failure pattern throughout
+- **New embedding subsystem**: Clean duck typing with shared RSpec examples verifying provider contract. DimensionCheck is a textbook value object — pure function, immutable result, no side effects. The resolver uses simple case/when (no over-engineered factory/registry).
+- **VectorIndex#clear!**: Properly encapsulates destructive vec0 operation behind the abstraction boundary
 
 ---
 
 ## 8. Priority Refactoring Recommendations
 
-### Critical (This Week)
-| # | Item | Effort | Impact |
-|---|------|--------|--------|
-| 5 | Fix bare rescue in `discover_other_projects` | 10 min | Correctness |
-| 3 | Fix ExportCommand N+1 queries | 30 min | Performance |
-
 ### High Priority (Next Week)
-| # | Item | Effort | Impact |
-|---|------|--------|--------|
-| 1 | Extract Tools into handler classes | 2-3 days | Maintainability |
-| 2 | Extract Recall legacy/dual into strategy | 2 days | Maintainability |
-| 9 | Add tests for untested critical files | 2-3 days | Coverage |
-| 4 | Extract SQLiteStore schema/retry modules | 1 day | Maintainability |
+
+None remaining. All high-priority items are resolved.
 
 ### Medium Priority (Next Sprint)
 | # | Item | Effort | Impact |
 |---|------|--------|--------|
-| 6 | Fix promote_fact transaction boundary | 30 min | Consistency |
-| 7 | Fix provenance nil content_item_id | 20 min | Correctness |
 | 8 | ContentItemAttributes value object | 1 hour | Readability |
 | 10 | Replace sleep-based tests with mocks | 1 hour | Test speed |
 | 11 | Shared test factory | 1 hour | DRY |
-| 12 | Thread Resolver state as params | 30 min | Immutability |
 | 17 | ResponseFormatter base method | 1 hour | DRY |
 | 14 | Separate I/O in discover_other_projects | 1 hour | Boundaries |
 
@@ -322,69 +224,62 @@ Tests use `Dir.chdir(test_dir)` which modifies global state. Fragile if tests ev
 | 15 | Sweeper mutable state | 20 min | Immutability |
 | 16 | Dir.chdir in tests | 15 min | Test isolation |
 | 18 | Publish section builder | 30 min | DRY |
-| 19 | SnippetExtractor validation DRY | 10 min | DRY |
 
-### Carried Forward (Low Priority from Feb 4)
+### Carried Forward (Low Priority from Earlier Reviews)
 | # | Item | Original # |
 |---|------|-----------|
-| 20 | DateTime migration (string timestamps) | #17 |
-| 21 | Command manager helper (`with_manager`) | #19 |
-| 22 | release_connections polymorphism | #20 |
-| 23 | Provenance batch insert (`multi_insert`) | #22 |
-| 24 | Individual MCP tool classes | #23 (subsumed by #1) |
-| 25 | Result objects for all queries | #24 |
+| 20 | DateTime migration (string timestamps) | Feb 4 #17 |
+| 21 | Command manager helper (`with_manager`) | Feb 4 #19 |
+| 22 | release_connections polymorphism | Feb 4 #20 |
+| 23 | Provenance batch insert (`multi_insert`) | Feb 4 #22 |
+| 25 | Result objects for all queries | Feb 4 #24 |
 
 ---
 
 ## 9. Conclusion
 
-The codebase maintains its strong architectural foundation but the three largest files have continued growing and now all exceed 500 lines. The most impactful improvements are: (1) fixing the bare rescue and N+1 in export (quick wins), (2) splitting `Tools` and `Recall` into focused classes (structural), and (3) adding tests for the 16 untested files (coverage).
+The codebase maintains its strong architectural foundation. Nine quality items were resolved this session across two passes: the Shortcuts scope correctness bug, ApiAdapter exception typing, silent exception logging, dead code removal, method decomposition, promote_fact transaction verification, provenance nil validation fix, Resolver state verification, and SnippetExtractor DRY extraction.
 
-No correctness regressions found. The batch loading patterns, domain modeling, and test culture remain excellent. The main risk is the growing complexity of `tools.rb` and `recall.rb` making future changes harder.
+No known correctness bugs remain. All three >500-line god objects have been eliminated: `Tools` (745→104), `Recall` (727→94), `SQLiteStore` (547→386). Zero critical or high-priority issues remain. All critical untested files now have specs (+36 tests). The remaining 12 items are medium/low priority (thin CLI wrappers, DRY improvements, carried-forward items).
 
 ---
 
 ## Appendix A: Metrics Comparison
 
-| Metric | Jan 29 | Feb 4 | Mar 9 |
-|--------|--------|-------|-------|
-| Ruby files (lib) | ~85 | 104 | 112 |
-| LOC (lib) | ~8,000 | 9,982 | 11,392 |
-| LOC (spec) | — | 17,693 | 21,632 |
-| Pure logic classes | 17+ | 20+ | 20+ |
-| Test files | 74+ | 98 | 128 |
-| Test-to-code ratio | ~1.5:1 | 1.77:1 | 1.90:1 |
-| Files >500 lines | 0 | 2 | **3** 🔴 |
-| Bare rescues | 0 | 0 | **1** 🔴 |
-| N+1 patterns (hot paths) | 0 | 0 | 0 ✅ |
-| N+1 patterns (cold paths) | — | — | **1** 🟡 |
-| Untested lib files | — | — | **16** 🟡 |
-
-## Appendix B: Quick Wins
-
-These can be done immediately (< 30 min total):
-
-1. **Fix bare rescue** (`mcp/tools.rb:607`): Change `rescue => _e` to `rescue Sequel::DatabaseError, Extralite::Error, IOError => _e`
-2. **SnippetExtractor DRY** (`core/snippet_extractor.rb:18-31`): Extract shared validation to private method
-3. **Dir.chdir block form** (`spec/publish_spec.rb:14`): Use `Dir.chdir(dir) { ... }` instead of global chdir
-
-## Appendix C: File Size Report
-
-| File | Feb 4 | Mar 9 | Trend |
-|------|-------|-------|-------|
-| `mcp/tools.rb` | ~610 | 728 | ⬆️ +118 |
-| `recall.rb` | ~608 | 681 | ⬆️ +73 |
-| `store/sqlite_store.rb` | 481 | 547 | ⬆️ +66 |
-| `mcp/response_formatter.rb` | — | 394 | new to watch |
-| `mcp/tool_definitions.rb` | — | 303 | new to watch |
-| `mcp/text_summary.rb` | — | 257 | new to watch |
-| `commands/stats_command.rb` | — | 239 | — |
-| `commands/uninstall_command.rb` | — | 226 | — |
-| `commands/index_command.rb` | — | 224 | — |
-| `publish.rb` | — | 221 | — |
-| `infrastructure/schema_validator.rb` | — | 215 | — |
-| `commands/hook_command.rb` | — | 214 | — |
+| Metric | Jan 29 | Feb 4 | Mar 9 | Mar 19 |
+|--------|--------|-------|-------|--------|
+| Ruby files (lib) | ~85 | 104 | 112 | **117** |
+| LOC (lib) | ~8,000 | 9,982 | 11,392 | **12,239** |
+| LOC (spec) | — | 17,693 | 21,632 | **22,563** |
+| Pure logic classes | 17+ | 20+ | 20+ | **22+** |
+| Test files | 74+ | 98 | 128 | **122** |
+| Test-to-code ratio | ~1.5:1 | 1.77:1 | 1.90:1 | **1.84:1** |
+| Files >500 lines | 0 | 2 | 3 | **0** ✅ |
+| Bare rescues (silent) | 0 | 0 | 1 | **0** ✅ |
+| N+1 patterns (hot paths) | 0 | 0 | 0 | **0** ✅ |
+| N+1 patterns (cold paths) | — | — | 1 | **0** ✅ |
+| Untested lib files | — | — | 16 | **~7 critical** ✅ |
+| Known correctness bugs | — | — | — | **0** ✅ |
+
+## Appendix B: File Size Report
+
+| File | Mar 9 | Mar 19 | Trend |
+|------|-------|--------|-------|
+| `mcp/tools.rb` | 728 | **104** | ⬇️ -624 (extracted to 6 handler modules) |
+| `recall.rb` | 681 | **94** | ⬇️ -587 (extracted to engine + query_core) |
+| `store/sqlite_store.rb` | 547 | **386** | ⬇️ -161 (extracted retry_handler + schema_manager) |
+| `mcp/response_formatter.rb` | 394 | 396 | ⬆️ +2 |
+| `mcp/tool_definitions.rb` | 303 | 334 | ⬆️ +31 |
+| `commands/index_command.rb` | 224 | 272 | ⬆️ +48 |
+| `mcp/text_summary.rb` | 257 | 258 | ⬆️ +1 |
+| `commands/stats_command.rb` | 239 | 250 | ⬆️ +11 |
+| `commands/uninstall_command.rb` | 226 | 226 | — |
+| `publish.rb` | 221 | 221 | — |
+| `infrastructure/schema_validator.rb` | 215 | 215 | — |
+| `commands/hook_command.rb` | 214 | 214 | — |
+| `resolve/resolver.rb` | — | 195 | new to watch |
+| `index/vector_index.rb` | — | 184 | new to watch |
 
 ---
 
-**Next review:** After Tools extraction or Recall strategy pattern refactoring
+**Next review:** After Recall strategy pattern refactoring or SQLiteStore extraction

data/hooks/hooks.json

@@ -6,7 +6,20 @@
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hook-runner.sh ingest",
-            "timeout": 10
+            "timeout": 10,
+            "statusMessage": "Saving memory..."
+          }
+        ]
+      }
+    ],
+    "StopFailure": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hook-runner.sh ingest",
+            "timeout": 10,
+            "statusMessage": "Saving memory..."
           }
         ]
       }
@@ -17,12 +30,14 @@
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hook-runner.sh ingest",
-            "timeout": 10
+            "timeout": 10,
+            "statusMessage": "Saving memory..."
           },
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hook-runner.sh context",
-            "timeout": 5
+            "timeout": 5,
+            "statusMessage": "Loading memory..."
           }
         ]
       }
@@ -33,12 +48,14 @@
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hook-runner.sh ingest",
-            "timeout": 30
+            "timeout": 30,
+            "statusMessage": "Saving memory..."
           },
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hook-runner.sh sweep",
-            "timeout": 30
+            "timeout": 30,
+            "statusMessage": "Sweeping memory..."
           }
         ]
       }
@@ -49,12 +66,27 @@
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hook-runner.sh ingest",
-            "timeout": 30
+            "timeout": 30,
+            "statusMessage": "Saving memory..."
           },
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hook-runner.sh sweep",
-            "timeout": 30
+            "timeout": 30,
+            "statusMessage": "Sweeping memory..."
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "idle_prompt",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hook-runner.sh sweep",
+            "timeout": 10,
+            "statusMessage": "Sweeping memory..."
           }
         ]
       }

data/lib/claude_memory/commands/checks/distill_check.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Commands
+    module Checks
+      # Checks for content items missing distillation metrics
+      class DistillCheck
+        def initialize(db_path, label)
+          @db_path = db_path
+          @label = label
+        end
+
+        def call
+          unless File.exist?(@db_path)
+            return {
+              status: :ok,
+              label: "#{@label}_distill",
+              message: "#{@label.capitalize} database not found (skipping distill check)",
+              details: {}
+            }
+          end
+
+          check_undistilled_content
+        rescue => e
+          {
+            status: :error,
+            label: "#{@label}_distill",
+            message: "#{@label.capitalize} distill check error: #{e.message}",
+            details: {}
+          }
+        end
+
+        private
+
+        def check_undistilled_content
+          store = ClaudeMemory::Store::SQLiteStore.new(@db_path)
+
+          undistilled_count = store.content_items
+            .left_join(:ingestion_metrics, content_item_id: :id)
+            .where(Sequel[:ingestion_metrics][:id] => nil)
+            .count
+
+          store.close
+
+          warnings = []
+          if undistilled_count > 0
+            warnings << "#{undistilled_count} content items have no distillation metrics. Run 'claude-memory init' to migrate."
+          end
+
+          {
+            status: warnings.any? ? :warning : :ok,
+            label: "#{@label}_distill",
+            message: "#{@label.capitalize} distillation metrics: #{(undistilled_count == 0) ? "all tracked" : "#{undistilled_count} untracked"}",
+            details: {undistilled_count: undistilled_count},
+            warnings: warnings
+          }
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/checks/hooks_check.rb

@@ -8,7 +8,7 @@ module ClaudeMemory
       # Checks hooks configuration in settings files
       class HooksCheck
         SETTINGS_PATHS = [".claude/settings.json", ".claude/settings.local.json"].freeze
-        EXPECTED_HOOKS = %w[Stop SessionStart PreCompact SessionEnd].freeze
+        EXPECTED_HOOKS = %w[Stop StopFailure SessionStart PreCompact SessionEnd].freeze
 
         def call
           hooks_found = false
@@ -86,7 +86,7 @@ module ClaudeMemory
             # Check for missing recommended hooks
             missing = EXPECTED_HOOKS - config["hooks"].keys
             if missing.any?
-              warnings << "Missing recommended hooks in #{path}: #{missing.join(", ")}"
+              warnings << "Missing recommended hooks in #{path}: #{missing.join(", ")}. Run 'claude-memory init' to add them"
             end
 
             {has_hooks: true, warnings: warnings}