Find Implementation Audit

1. Locations

All four are lambdas passed as the ToolRunner parameter to ExecutionEngine::execute(). Each lives inside its own translation unit, capturing different local state.

2. Behavior Differences

2.1 Filesystem scan (same across all four)

recursive_directory_iterator(current_path())
skip . files, build/_deps (B also skips nothing extra)
              (A,D also skip node_modules)

2.2 Extension filter

B (diagnostics) also skips p.find("/scenarios/") and p.find("/data/") in its grep handler (lines 336–347) but NOT in its find handler.

C (validation) and D (benchmark) filter out benchmark_suite.json and tests/ and scenarios/ in their grep handler, not in find.

2.3 Input normalization

A produces term_normalized (e.g., CommandRouter → command_router) and term_words (e.g., cursor[ _-]?binary → ["cursor","binary"]). The other three only have term_lower.

2.4 Matching and scoring

2.5 Output format

B outputs only bare relative paths, one per line, with exact matches inserted at front (found.insert(found.begin(), ...)).

2.6 Read-tool coupling

A populates a vector of up to 5 paths. The read handler iterates all of them (line 426). C and D store a single path string; the read handler reads exactly that one file.

2.7 Execution engine metrics consumption

The execution engine at execution_engine.cpp:1053–1077 parses the find tool’s stdout for CANDIDATE:, SELECTED:, and REASON: lines to populate retrieval_metrics. This means:

• A, C, D: output parsed correctly → metrics populated.
• B: bare paths only → CANDIDATE: lines not found → trace_candidates stays empty, filename_hits/symbol_hits/etc. not incremented correctly.

3. Reuse Feasibility

3.1 What can be shared

The filesystem-scan + scoring + ranking logic is pure computation:

input:  term, impl_flag
output: vector<{path, score, reason}>

It has no dependencies on:

• the local last_find_results / last_find state
• the output format (CANDIDATE vs bare paths)
• the read handler

This can be extracted to a free function in a shared header:

// include/services/find_service.h
struct FindCandidate { std::string path; int score; std::string reason; };
std::vector<FindCandidate> directory_aware_find(const std::string &term,
                                                  bool impl_query);

3.2 What cannot be shared

3.3 Breaking the coupling

The read-tool coupling is the real obstacle. A shares a captured vector between find and read. To share the find function, the tool runner lambda must still own the vector. This is fine – the shared function returns candidates, the lambda selects top-N and stores them locally.

The output format difference means each caller would wrap the shared function with its own formatting loop. That is a 3–5 line wrapper per caller.

4. Recommendation

Share the find logic as a free function; keep the tool runners independent.

Why

1. Single source of truth for ranking. The scoring rules (exact=20, partial=10, directory=5, word-level=12, symbol up to 18, impl boost=8) and the ranking logic (descending score, ascending path for ties) would live in one place. Currently each copy can drift independently – they already have different extension filters and A has features the other three lack.

2. The lambdas are thin wrappers. Each tool runner’s remaining work is:
   • call the shared function
   • output format (6 lines for A/C/D, 2 lines for B)
   • write to state vector (1 line for A, 1 line for C/D, 0 for B) Compared to the current 60–90 lines of duplicated scan logic.
3. The read-tool coupling is not a problem. The lambda still owns the state (vector or string). The shared function doesn’t touch it.

Alternative: keep separate

If the four extension filters genuinely need to stay different (e.g., diagnostics truly never needs .yml files), then keeping them separate is acceptable, but B and C/D should at minimum adopt A’s CamelCase normalization, symbol scanning, and word-level matching – since those features are bug fixes, not configuration preferences.

Proposed scope for sharing

FindService::directory_aware_find(term, impl_flag)
         ↓
   vector<FindCandidate>   ← pure, testable
         ↓
   caller formats output + manages state

No code changes yet.