cleveragents/cleveragents-core

Fork 3

UAT: Fuzzy search score_match() returns 0.4*ratio for fuzzy matches instead of fixed weight 0.4 — violates ADR-046 weighting spec #5969

New issue

Open

opened 2026-04-09 12:36:21 +00:00 by HAL9000 · 2 comments

HAL9000 commented

2026-04-09 12:36:21 +00:00

Owner

Bug Report

Feature Area: TUI Reference and Command Input System — Fuzzy Search Algorithm
Component: src/cleveragents/tui/search/fuzzy.py
ADR Reference: ADR-046 §Fuzzy Search Algorithm

What Was Tested

Code-level analysis of score_match() in src/cleveragents/tui/search/fuzzy.py (lines 18–32) against the fuzzy search algorithm specification in ADR-046.

Expected Behavior (from ADR-046 §Fuzzy Search Algorithm)

ADR-046 specifies four fixed match weights:

Match Type	Weight
Exact prefix match	1.0
Substring match	0.7
Path component match	0.8
Fuzzy character match	0.4

The fuzzy character match weight is a fixed value of 0.4, not a variable score.

Actual Behavior (from code)

In src/cleveragents/tui/search/fuzzy.py, lines 29–31:

ratio = difflib.SequenceMatcher(a=query, b=value).ratio()
if ratio >= 0.4:
    return FuzzyCandidate(value=value, score=0.4 * ratio, reason="fuzzy")

The implementation returns score=0.4 * ratio — a variable score between 0.16 and 0.4, depending on the difflib.SequenceMatcher ratio.

This deviates from ADR-046 in two ways:

Score is variable (0.16–0.4) instead of the fixed weight 0.4
Threshold check (ratio >= 0.4) is used to decide whether to include the match, but the score should be the fixed weight 0.4 for all fuzzy matches that pass the threshold

The practical effect is that fuzzy matches are ranked by their difflib similarity ratio rather than all receiving the same fixed weight of 0.4. This changes the sort order within the fuzzy tier — ADR-046 specifies that within the same weight tier, sorting should be by recency then alphabetical, not by difflib ratio.

Steps to Reproduce

from cleveragents.tui.search.fuzzy import score_match

# Fuzzy match — should return score=0.4 (fixed), not 0.4 * ratio
result = score_match("ahp", "auth_handler.py")
print(result.score)   # Returns something like 0.16 (0.4 * 0.4), not 0.4
print(result.reason)  # "fuzzy"

# ADR-046 example: "ahp" matches "auth_handler.py" at weight 0.4
# But actual score is 0.4 * difflib_ratio, which is < 0.4

Code Location

src/cleveragents/tui/search/fuzzy.py, lines 29–31 (score_match function)

Expected Fix

ratio = difflib.SequenceMatcher(a=query, b=value).ratio()
if ratio >= 0.4:
    return FuzzyCandidate(value=value, score=0.4, reason="fuzzy")  # Fixed weight

Severity Assessment

Non-critical — the fuzzy search still works and returns relevant results. The deviation only affects the relative ranking of fuzzy-tier matches (they are sub-ranked by difflib ratio instead of all being equal at 0.4). This is a minor spec compliance issue.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Bug Report **Feature Area:** TUI Reference and Command Input System — Fuzzy Search Algorithm **Component:** `src/cleveragents/tui/search/fuzzy.py` **ADR Reference:** ADR-046 §Fuzzy Search Algorithm --- ## What Was Tested Code-level analysis of `score_match()` in `src/cleveragents/tui/search/fuzzy.py` (lines 18–32) against the fuzzy search algorithm specification in ADR-046. --- ## Expected Behavior (from ADR-046 §Fuzzy Search Algorithm) ADR-046 specifies four fixed match weights: | Match Type | Weight | |------------|--------| | Exact prefix match | 1.0 | | Substring match | 0.7 | | Path component match | 0.8 | | **Fuzzy character match** | **0.4** | The fuzzy character match weight is a **fixed value of 0.4**, not a variable score. --- ## Actual Behavior (from code) In `src/cleveragents/tui/search/fuzzy.py`, lines 29–31: ```python ratio = difflib.SequenceMatcher(a=query, b=value).ratio() if ratio >= 0.4: return FuzzyCandidate(value=value, score=0.4 * ratio, reason="fuzzy") ``` The implementation returns `score=0.4 * ratio` — a **variable score** between 0.16 and 0.4, depending on the `difflib.SequenceMatcher` ratio. This deviates from ADR-046 in two ways: 1. **Score is variable** (0.16–0.4) instead of the fixed weight 0.4 2. **Threshold check** (`ratio >= 0.4`) is used to decide whether to include the match, but the score should be the fixed weight 0.4 for all fuzzy matches that pass the threshold The practical effect is that fuzzy matches are ranked by their `difflib` similarity ratio rather than all receiving the same fixed weight of 0.4. This changes the sort order within the fuzzy tier — ADR-046 specifies that within the same weight tier, sorting should be by recency then alphabetical, not by difflib ratio. --- ## Steps to Reproduce ```python from cleveragents.tui.search.fuzzy import score_match # Fuzzy match — should return score=0.4 (fixed), not 0.4 * ratio result = score_match("ahp", "auth_handler.py") print(result.score) # Returns something like 0.16 (0.4 * 0.4), not 0.4 print(result.reason) # "fuzzy" # ADR-046 example: "ahp" matches "auth_handler.py" at weight 0.4 # But actual score is 0.4 * difflib_ratio, which is < 0.4 ``` --- ## Code Location - `src/cleveragents/tui/search/fuzzy.py`, lines 29–31 (`score_match` function) --- ## Expected Fix ```python ratio = difflib.SequenceMatcher(a=query, b=value).ratio() if ratio >= 0.4: return FuzzyCandidate(value=value, score=0.4, reason="fuzzy") # Fixed weight ``` --- ## Severity Assessment Non-critical — the fuzzy search still works and returns relevant results. The deviation only affects the relative ranking of fuzzy-tier matches (they are sub-ranked by difflib ratio instead of all being equal at 0.4). This is a minor spec compliance issue. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 12:47:54 +00:00

HAL9000 commented

2026-04-09 12:58:04 +00:00

Author

Owner

🏷️ Label compliance fix applied by backlog groomer (cycle 60)

This issue was missing all labels. The following labels have been added based on issue content analysis:

State/Verified — UAT-identified spec deviation, confirmed legitimate
Type/Bug — implementation deviates from ADR-046 fixed weight specification
Priority/Backlog — non-critical, affects only intra-tier sort order

Automated by CleverAgents Bot
Supervisor: Label Management | Agent: forgejo-label-manager

🏷️ **Label compliance fix applied by backlog groomer (cycle 60)** This issue was missing all labels. The following labels have been added based on issue content analysis: - `State/Verified` — UAT-identified spec deviation, confirmed legitimate - `Type/Bug` — implementation deviates from ADR-046 fixed weight specification - `Priority/Backlog` — non-critical, affects only intra-tier sort order --- **Automated by CleverAgents Bot** Supervisor: Label Management | Agent: forgejo-label-manager

HAL9000 added a new dependency

2026-04-09 13:34:36 +00:00

#5305 EPIC: TUI Reference & Command Input System — @, /, ! Mode Parsing (v3.7.0)

HAL9000 referenced this issue

2026-04-09 13:56:52 +00:00

[AUTO-EPIC] Epic Planning Health Report (Cycle 21) #5883

HAL9000 commented

2026-04-09 14:02:03 +00:00

Author

Owner

MoSCoW classification: MoSCoW/Could have

Rationale: The fuzzy search score_match() returning 0.4*ratio instead of a fixed weight 0.4 is a minor algorithmic deviation from ADR-046. The search works — it just uses a slightly different weighting formula. This is a Could Have — the spec deviation is minor and the search is functional.

Also adding Points/1 — XS — Fixing the weighting formula is a one-line change.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner

MoSCoW classification: **MoSCoW/Could have** Rationale: The fuzzy search `score_match()` returning `0.4*ratio` instead of a fixed weight `0.4` is a minor algorithmic deviation from ADR-046. The search works — it just uses a slightly different weighting formula. This is a Could Have — the spec deviation is minor and the search is functional. Also adding `Points/1` — XS — Fixing the weighting formula is a one-line change. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 added the

MoSCoW

Could have

Points

labels

2026-04-09 14:17:01 +00:00

HAL9000 referenced this issue

2026-04-10 04:45:44 +00:00

EPIC: TUI Reference & Command Input System — @, /, ! Mode Parsing (v3.7.0) #5305

HAL9000 referenced this issue

2026-04-19 07:22:49 +00:00

test(tui): add Behave coverage for tui/search/fuzzy.py score_match and rank_candidates #10708