boost-skill-cli 1.2.15__tar.gz → 1.2.16__tar.gz

{boost_skill_cli-1.2.15 → boost_skill_cli-1.2.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.15
+Version: 1.2.16
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.2.15 → boost_skill_cli-1.2.16}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.2.15'
-__version_tuple__ = version_tuple = (1, 2, 15)
+__version__ = version = '1.2.16'
+__version_tuple__ = version_tuple = (1, 2, 16)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.15 → boost_skill_cli-1.2.16}/boost_cli/commands/configuration.py

@@ -1305,7 +1305,9 @@ REGISTRY.register(
     "either: take what fits, discard the rest, the task stays yours. It costs "
     "10-15 seconds — an LLM reranks every match, which is what makes the top "
     "result worth acting on rather than skimming. Worth budgeting for, not a "
-    "surprise. Coming back empty is a real answer too, not a "
+    "surprise — and only a novel search pays it: repeating an identical "
+    "search skips the LLM and answers from a local cache. "
+    "Coming back empty is a real answer too, not a "
     "wasted turn: it means build it yourself, now knowing nothing already "
     "covers it — and on a machine with nothing tapped yet it says so and names "
     "the one command that fixes it, rather than reporting a miss.",

{boost_skill_cli-1.2.15 → boost_skill_cli-1.2.16}/boost_cli/core/mcp.py

@@ -194,7 +194,8 @@ INSTRUCTIONS = (
     "what exists. Both are read-only and install nothing. boost_list is "
     "instant. boost_search costs 10-15 seconds: it retrieves, then an LLM "
     "reranks every match, which is what makes the top result worth acting on "
-    "rather than skimming ten.\n"
+    "rather than skimming ten. Only a novel search pays it — repeating an "
+    "identical search skips the LLM and answers from a local cache.\n"
     "\n"
     "WORTH THE SECONDS (boost_search — boost_list is free, call it whenever). "
     "Two signals, both readable from the request itself rather than from work "

{boost_skill_cli-1.2.15 → boost_skill_cli-1.2.16}/boost_cli/core/paths.py

@@ -85,6 +85,7 @@ INTERNAL_CACHE_FILES = frozenset({
     "rag_index.json",       # rag.index_path()       — BM25 index
     "rag_postings.sqlite",  # rag.postings_path()    — BM25 postings
     "rag_vectors.sqlite",   # dense.db_path()        — dense vectors
+    "rerank_cache.json",    # rag.rerank_cache_path() — LLM rerank orders
     "discovery.json",       # discovery._discovery_path()
     "_names.txt",           # complete.names_file()  — shell completion
 })

{boost_skill_cli-1.2.15 → boost_skill_cli-1.2.16}/boost_cli/core/rag.py

@@ -19,6 +19,7 @@ import contextlib
 import hashlib
 import json
 import math
+import os
 import re
 import sqlite3
 from collections import defaultdict
@@ -841,6 +842,49 @@ def retrieve(query: str, k: int = 60, kind: str | None = None,
     return _windowed(dedupe_by_content(hits, k), terms)
 
 
+def rerank_cache_path() -> Path:
+    """Where cached rerank orders live; in ``paths.INTERNAL_CACHE_FILES``."""
+    return paths.cache_dir() / "rerank_cache.json"
+
+
+#: FIFO cap on cached rerank orders. 200 entries is a few days of real use at
+#: a few KB total; the point is bounding the file, not maximising hits.
+RERANK_CACHE_CAP = 200
+
+
+def _rerank_cache_load() -> dict:
+    """The cache as a dict, ``{}`` for missing/corrupt — never an error."""
+    try:
+        data = json.loads(rerank_cache_path().read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _rerank_cache_get(key: str) -> list | None:
+    """A cached name order for ``key``, or None on any doubt at all."""
+    order = _rerank_cache_load().get(key)
+    return order if isinstance(order, list) and order else None
+
+
+def _rerank_cache_put(key: str, order: list) -> None:
+    """Store ``order``, evicting oldest-inserted beyond the cap.
+
+    JSON objects round-trip in insertion order, so the dict itself is the
+    FIFO — no timestamps to tie-break. Best-effort on purpose: a read-only
+    cache dir loses the cache, never the search, and a concurrent writer
+    clobbering this write costs a future miss, not corruption.
+    """
+    cache = _rerank_cache_load()
+    cache.pop(key, None)
+    cache[key] = order
+    while len(cache) > RERANK_CACHE_CAP:
+        cache.pop(next(iter(cache)))
+    with contextlib.suppress(OSError):
+        paths.ensure_dirs()
+        util.atomic_write_text(rerank_cache_path(), json.dumps(cache))
+
+
 #: The label `rerank` returns when the LLM pass actually ran. Every other value
 #: is a retrieval engine's own name, i.e. "the rerank did not happen". Callers
 #: that quote what the rerank buys have to be able to tell those apart without
@@ -860,6 +904,15 @@ def rerank(query: str, hits: list[Hit], limit: int = 10,
     answered, so a confident "BM25 full-content" sent debugging somewhere else.
 
     The default keeps direct callers unchanged; ``search`` passes the real one.
+
+    Repeat calls answer from a small on-disk cache keyed on a hash of exactly
+    what the LLM would see — query, limit, and the candidate listing — so it
+    self-invalidates on any reindex, ranking drift, or snippet change without
+    ever inspecting why. Only the parsed name order is stored; a hit replays
+    through the same deterministic reorder below, and keeps the LLM_RANKER
+    label because it *is* the LLM's ordering. ``BOOST_NO_RERANK_CACHE=1``
+    bypasses both read and write (the Tier 2a eval sets it, so a graded
+    rerank is always live).
     """
     top = hits[:max(limit, 15)]
     if not ai.available():
@@ -868,17 +921,26 @@ def rerank(query: str, hits: list[Hit], limit: int = 10,
         "- %s [%s]: %s" % (h["entry"]["name"], h["entry"].get("kind", "skill"),
                            (h["snippet"] or h["entry"].get("description", ""))[:180])
         for h in top)
-    reply = ai.ask(
-        "Task: %s\n\nCandidate skills (name, kind, best matching text):\n%s\n\n"
-        "Order the skill names best-match-first for the task. "
-        "Reply with ONLY a JSON array of names." % (query, listing),
-        system="You rank AI coding skills by how well they fit a task.",
-        max_tokens=400)
-    order = _json_array(reply)
-    if not order:
-        # The model answered but not with a JSON array, so the ordering falls
-        # back to whatever retrieval produced — and so must the label.
-        return hits[:limit], engine
+    caching = not os.environ.get("BOOST_NO_RERANK_CACHE")
+    cache_key = hashlib.sha256(
+        ("%s\n%d\n%s" % (query, limit, listing)).encode("utf-8", "replace")
+    ).hexdigest()
+    order = _rerank_cache_get(cache_key) if caching else None
+    if order is None:
+        reply = ai.ask(
+            "Task: %s\n\nCandidate skills (name, kind, best matching text):\n%s\n\n"
+            "Order the skill names best-match-first for the task. "
+            "Reply with ONLY a JSON array of names." % (query, listing),
+            system="You rank AI coding skills by how well they fit a task.",
+            max_tokens=400)
+        order = _json_array(reply)
+        if not order:
+            # The model answered but not with a JSON array, so the ordering
+            # falls back to whatever retrieval produced — and so must the
+            # label. Not cached: a degrade reply is a retry, not an answer.
+            return hits[:limit], engine
+        if caching:
+            _rerank_cache_put(cache_key, [str(n) for n in order])
     by_name = {h["entry"]["name"]: h for h in hits}
     picked = [by_name[str(n)] for n in order if str(n) in by_name]
     rest = [h for h in hits if h["entry"]["name"]

{boost_skill_cli-1.2.15 → boost_skill_cli-1.2.16}/boost_skill_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.15
+Version: 1.2.16
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.2.15 → boost_skill_cli-1.2.16}/boost_skill_cli.egg-info/SOURCES.txt

@@ -400,6 +400,7 @@ docs/roadmap/items/shareable-catalogue-bundle.md
 docs/roadmap/items/shift-left-gate-pre-commit-pre-commit-ci.md
 docs/roadmap/items/single-imperative-rule-extractor.md
 docs/roadmap/items/single-tech-stack-prober.md
+docs/roadmap/items/smart-rerank-pays-per-novel-query.md
 docs/roadmap/items/split-oversized-command-modules.md
 docs/roadmap/items/startup-and-import-time-budget-x-importtime.md
 docs/roadmap/items/stop-re-serializing-entry-meta-on-every-search.md
@@ -695,6 +696,7 @@ tests/unit/test_registry_control_chars.py
 tests/unit/test_release_guard.py
 tests/unit/test_release_preflight.py
 tests/unit/test_required_checks.py
+tests/unit/test_rerank_cache.py
 tests/unit/test_resolve.py
 tests/unit/test_roadmap_fresh.py
 tests/unit/test_rules.py

boost_skill_cli-1.2.16/docs/roadmap/items/smart-rerank-pays-per-novel-query.md

@@ -0,0 +1,37 @@
+---
+id: smart-rerank-pays-per-novel-query
+board: code
+section: dx
+status: inflight
+category: Performance · MCP
+complexity: S
+impact: High
+wow: 3
+note: MCP boost_search measured 11.7-17 s per call — every call, even a repeat of the last one
+order: 123
+owner: loop/search-perf
+pr:
+title: The smart rerank pays the LLM again for a search it already answered
+---
+The MCP <code>boost_search</code> path passes <code>smart=True</code> on every
+call and <i>mcp-search-cost-was-understated</i> measured it at 11.7-17.0 s —
+nearly all of it the LLM rerank, paid again in full for a byte-identical
+repeat of the previous search. Agents retry searches constantly (a session
+restart, a re-planned task, a second agent asking the same question), so the
+honest "10-15 seconds" cost doctrine was billing every ask at first-ask
+prices.<br><br>
+Shipped: <code>rag.rerank</code> keeps a small FIFO cache
+(<code>~/.boost/cache/rerank_cache.json</code>, 200 entries, registered in
+<code>paths.INTERNAL_CACHE_FILES</code> so <code>boost clean</code> spares
+it) keyed on a sha256 of <b>exactly what the LLM sees</b> — query, limit, and
+the candidate listing — so it self-invalidates on any reindex, ranking drift,
+or snippet change without inspecting why. Only the parsed name order is
+stored; a hit replays through the same deterministic reorder as a live reply
+and keeps the <code>Claude relevance</code> label, because it is the LLM's
+ordering. Degrade replies are never cached. <code>BOOST_NO_RERANK_CACHE=1</code>
+bypasses read and write — the Tier 2a eval sets it, so a graded rerank is
+always live. Both MCP cost surfaces (server instructions and the
+<code>boost_search</code> description) now state the repeat-search cost, pinned
+by the same agreement test that keeps them from drifting apart. Sibling of
+<i>cold-search-reads-the-whole-catalogue</i>, which took the retrieval half of
+the same search from 0.94 s to 0.49 s.

{boost_skill_cli-1.2.15 → boost_skill_cli-1.2.16}/docs/roadmap.html

@@ -133,7 +133,7 @@
       <div class="stat"><b>16</b><span>Shipped</span></div>
       <div class="stat"><b>1</b><span>Next up</span></div>
       <div class="stat"><b>7</b><span>Planned</span></div>
-      <div class="stat"><b>261</b><span>Loop finds</span></div>
+      <div class="stat"><b>262</b><span>Loop finds</span></div>
       <!-- /ROADMAP:stats -->
     </div>
   </section>
@@ -8817,6 +8817,39 @@ fuzzy filter.</p>
           <span class="m">search rows learned kind/tap/installed with a stated drop order; browse got its gradient, an empty state, a badge rail, a list scrollbar and a session chip</span>
         </div>
       </article>
+
+      <article class="cap rcard" id="smart-rerank-pays-per-novel-query">
+        <div class="head"><span class="pill inflight">In flight</span><span class="cat">Performance · MCP</span></div>
+        <h3>The smart rerank pays the LLM again for a search it already answered</h3>
+        <p>The MCP <code>boost_search</code> path passes <code>smart=True</code> on every
+call and <i>mcp-search-cost-was-understated</i> measured it at 11.7-17.0 s —
+nearly all of it the LLM rerank, paid again in full for a byte-identical
+repeat of the previous search. Agents retry searches constantly (a session
+restart, a re-planned task, a second agent asking the same question), so the
+honest "10-15 seconds" cost doctrine was billing every ask at first-ask
+prices.<br><br>
+Shipped: <code>rag.rerank</code> keeps a small FIFO cache
+(<code>~/.boost/cache/rerank_cache.json</code>, 200 entries, registered in
+<code>paths.INTERNAL_CACHE_FILES</code> so <code>boost clean</code> spares
+it) keyed on a sha256 of <b>exactly what the LLM sees</b> — query, limit, and
+the candidate listing — so it self-invalidates on any reindex, ranking drift,
+or snippet change without inspecting why. Only the parsed name order is
+stored; a hit replays through the same deterministic reorder as a live reply
+and keeps the <code>Claude relevance</code> label, because it is the LLM's
+ordering. Degrade replies are never cached. <code>BOOST_NO_RERANK_CACHE=1</code>
+bypasses read and write — the Tier 2a eval sets it, so a graded rerank is
+always live. Both MCP cost surfaces (server instructions and the
+<code>boost_search</code> description) now state the repeat-search cost, pinned
+by the same agreement test that keeps them from drifting apart. Sibling of
+<i>cold-search-reads-the-whole-catalogue</i>, which took the retrieval half of
+the same search from 0.94 s to 0.49 s.</p>
+        <div class="meta">
+          <span class="m">Complexity <b>S</b></span>
+          <span class="m hi">Impact <b>High</b></span>
+          <span class="m">Wow <b class="wow">★★★</b></span>
+          <span class="m">MCP boost_search measured 11.7-17 s per call — every call, even a repeat of the last one</span>
+        </div>
+      </article>
       <!-- /ROADMAP:cards -->
 
     </div>

{boost_skill_cli-1.2.15 → boost_skill_cli-1.2.16}/scripts/eval_retrieval.py

@@ -50,6 +50,7 @@ import argparse
 import hashlib
 import json
 import math
+import os
 import sys
 from collections.abc import Callable, Iterable, Sequence
 from pathlib import Path
@@ -306,7 +307,12 @@ def hybrid_ranker(k: int) -> Ranker:
 
 
 def rerank_ranker(k: int) -> Ranker:
-    """BM25 shortlist reordered by the LLM rerank stage (Tier 2a)."""
+    """BM25 shortlist reordered by the LLM rerank stage (Tier 2a).
+
+    The rerank cache is disabled for the whole run: a graded rerank must be
+    live, or the eval silently measures a stale cached order.
+    """
+    os.environ["BOOST_NO_RERANK_CACHE"] = "1"
     def rank(q: str) -> list[str]:
         hits = rag.retrieve(q, k=max(k * 4, 60))
         reranked, _label = rag.rerank(q, hits, limit=max(k, 15))

{boost_skill_cli-1.2.15 → boost_skill_cli-1.2.16}/tests/functional/test_cli_configuration.py

@@ -1887,7 +1887,7 @@ class TestSearchNamesItsRanker:
         assert "did NOT run" not in text
 
     def test_rerank_returns_that_label_only_when_the_llm_answered(
-            self, monkeypatch):
+            self, monkeypatch, sandbox):
         """The producer and the consumer of the label must agree.
 
         `rag.LLM_RANKER` exists so this is impossible to drift rather than
@@ -1910,8 +1910,16 @@ class TestSearchNamesItsRanker:
         assert label == rag.LLM_RANKER
         assert [h["entry"]["name"] for h in order] == ["a", "b"]
 
+        # Repeating the SAME query now answers from the rerank cache: the
+        # order is still the LLM's, so the label stays with it — no new ask.
+        monkeypatch.setattr(ai, "ask",
+                            lambda *a, **k: pytest.fail("cache must answer"))
+        assert rag.rerank("q", hits, engine="BM25 full-content")[1] == \
+            rag.LLM_RANKER
+
         # The model replied, but not with an order — the label must fall back
         # with the ordering, or it claims a rerank that did not take effect.
+        # A fresh query, so the cache cannot answer for the degraded model.
         monkeypatch.setattr(ai, "ask", lambda *a, **k: "sorry, I cannot")
-        assert rag.rerank("q", hits, engine="BM25 full-content")[1] == \
+        assert rag.rerank("q2", hits, engine="BM25 full-content")[1] == \
             "BM25 full-content"

{boost_skill_cli-1.2.15 → boost_skill_cli-1.2.16}/tests/unit/test_clean_internal_cache.py

@@ -86,6 +86,7 @@ class TestInternalCacheRegistryHasNoDrift:
         owners = {
             "rag.index_path": rag.index_path,
             "rag.postings_path": rag.postings_path,
+            "rag.rerank_cache_path": rag.rerank_cache_path,
             "dense.db_path": dense.db_path,
             "discovery._discovery_path": discovery._discovery_path,
             "complete.names_file": complete.names_file,

{boost_skill_cli-1.2.15 → boost_skill_cli-1.2.16}/tests/unit/test_mcp.py

@@ -198,6 +198,11 @@ class TestHandleRequest:
         assert "10-15 seconds" in mcp.INSTRUCTIONS
         assert "10-15 seconds" in desc["boost_search"]
         assert "a few seconds" not in mcp.INSTRUCTIONS.lower()
+        # The repeat-search cost claim is backed by rag's rerank cache; both
+        # surfaces must state it, or an agent budgets 15 s for a lookup that
+        # would have been free.
+        assert "answers from a local cache" in mcp.INSTRUCTIONS
+        assert "answers from a local cache" in desc["boost_search"]
 
     def test_instructions_still_separate_the_free_tool_from_the_slow_one(self):
         # boost_list really is instant, and collapsing the two costs into one

{boost_skill_cli-1.2.15 → boost_skill_cli-1.2.16}/tests/unit/test_rag.py

@@ -523,14 +523,14 @@ def _hit(name, score, snippet="s", kind="skill", desc="d"):
 
 
 class TestRerank:
-    def test_no_ai_returns_bm25_order(self, monkeypatch):
+    def test_no_ai_returns_bm25_order(self, monkeypatch, sandbox):
         monkeypatch.setattr(rag.ai, "available", lambda: False)
         hits = [_hit("a", 2.0), _hit("b", 1.0)]
         out, label = rag.rerank("q", hits, limit=5)
         assert [h["entry"]["name"] for h in out] == ["a", "b"]
         assert label == "BM25 full-content"
 
-    def test_ai_reorders(self, monkeypatch):
+    def test_ai_reorders(self, monkeypatch, sandbox):
         monkeypatch.setattr(rag.ai, "available", lambda: True)
         monkeypatch.setattr(rag.ai, "ask", lambda *a, **k: '["b", "a"]')
         hits = [_hit("a", 2.0), _hit("b", 1.0)]
@@ -538,14 +538,14 @@ class TestRerank:
         assert [h["entry"]["name"] for h in out] == ["b", "a"]
         assert label == "Claude relevance"
 
-    def test_ai_partial_order_appends_rest(self, monkeypatch):
+    def test_ai_partial_order_appends_rest(self, monkeypatch, sandbox):
         monkeypatch.setattr(rag.ai, "available", lambda: True)
         monkeypatch.setattr(rag.ai, "ask", lambda *a, **k: '["b"]')
         hits = [_hit("a", 2.0), _hit("b", 1.0)]
         out, _label = rag.rerank("q", hits, limit=5)
         assert [h["entry"]["name"] for h in out] == ["b", "a"]
 
-    def test_ai_garbage_reply_degrades(self, monkeypatch):
+    def test_ai_garbage_reply_degrades(self, monkeypatch, sandbox):
         monkeypatch.setattr(rag.ai, "available", lambda: True)
         monkeypatch.setattr(rag.ai, "ask", lambda *a, **k: "no json here")
         hits = [_hit("a", 2.0), _hit("b", 1.0)]
@@ -553,13 +553,13 @@ class TestRerank:
         assert [h["entry"]["name"] for h in out] == ["a", "b"]
         assert label == "BM25 full-content"
 
-    def test_limit_truncates(self, monkeypatch):
+    def test_limit_truncates(self, monkeypatch, sandbox):
         monkeypatch.setattr(rag.ai, "available", lambda: False)
         hits = [_hit("a", 3.0), _hit("b", 2.0), _hit("c", 1.0)]
         out, _ = rag.rerank("q", hits, limit=2)
         assert len(out) == 2
 
-    def test_prompt_carries_task_and_candidate_snippets(self, monkeypatch):
+    def test_prompt_carries_task_and_candidate_snippets(self, monkeypatch, sandbox):
         captured = {}
         monkeypatch.setattr(rag.ai, "available", lambda: True)
 
@@ -1100,7 +1100,7 @@ class TestRetrieveInternals:
 
 
 class TestRerankExact:
-    def test_exact_prompt_and_kwargs(self, monkeypatch):
+    def test_exact_prompt_and_kwargs(self, monkeypatch, sandbox):
         cap = {}
         monkeypatch.setattr(rag.ai, "available", lambda: True)
 

{boost_skill_cli-1.2.15 → boost_skill_cli-1.2.16}/tests/unit/test_rag_fusion.py

@@ -230,7 +230,8 @@ class TestRerankPreservesTheEngineLabel:
     def _hits():
         return [_hit("a", 2.0), _hit("b", 1.0)]
 
-    def test_no_ai_reports_the_engine_that_retrieved(self, monkeypatch):
+    def test_no_ai_reports_the_engine_that_retrieved(self, monkeypatch,
+                                                     sandbox):
         # THE regression. Fusion ran, the LLM was absent, and the old code
         # answered "BM25 full-content" — naming an engine that did not rank
         # these hits alone.
@@ -239,14 +240,16 @@ class TestRerankPreservesTheEngineLabel:
                                  engine="hybrid RRF (BM25 + dense)")
         assert label == "hybrid RRF (BM25 + dense)"
 
-    def test_no_ai_reports_dense_when_dense_retrieved(self, monkeypatch):
+    def test_no_ai_reports_dense_when_dense_retrieved(self, monkeypatch,
+                                                      sandbox):
         monkeypatch.setattr(rag.ai, "available", lambda: True)
         monkeypatch.setattr(rag.ai, "ask", lambda *_a, **_k: "not json at all")
         _out, label = rag.rerank("q", self._hits(), limit=5,
                                  engine="dense vectors")
         assert label == "dense vectors"
 
-    def test_an_unparseable_reply_keeps_the_engine_too(self, monkeypatch):
+    def test_an_unparseable_reply_keeps_the_engine_too(self, monkeypatch,
+                                                       sandbox):
         # The second degrade path: the model answered, but not with a JSON
         # array. Ordering falls back, so the label must fall back with it.
         monkeypatch.setattr(rag.ai, "available", lambda: True)
@@ -255,7 +258,7 @@ class TestRerankPreservesTheEngineLabel:
                                  engine="hybrid RRF (BM25 + dense)")
         assert label == "hybrid RRF (BM25 + dense)"
 
-    def test_a_successful_rerank_still_says_claude(self, monkeypatch):
+    def test_a_successful_rerank_still_says_claude(self, monkeypatch, sandbox):
         # The LLM really did decide the order here, so crediting the retrieval
         # engine instead would be the same bug pointing the other way.
         monkeypatch.setattr(rag.ai, "available", lambda: True)

boost_skill_cli-1.2.16/tests/unit/test_rerank_cache.py

@@ -0,0 +1,128 @@
+"""The LLM rerank cache: repeat searches must not pay the LLM again.
+
+The MCP `boost_search` path passes ``smart=True`` on every call and measured
+11.7-17 s per search, nearly all of it the rerank. The cache keys on a hash of
+*exactly what the LLM sees* (query, limit, candidate listing), so it
+self-invalidates on any reindex, ranking change, snippet change or candidate
+drift — and stores only the parsed name order, so a hit replays through the
+same deterministic reorder code as a live reply.
+"""
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from boost_cli.core import ai, paths, rag
+
+
+def _hit(name, score, snippet=""):
+    return {"entry": {"name": name, "tap": "acme/skills",
+                      "skill_md": "%s/SKILL.md" % name},
+            "score": score, "snippet": snippet, "content": "h-" + name}
+
+
+@pytest.fixture()
+def asked(monkeypatch, sandbox):
+    """AI available; every ask recorded. Returns the call log."""
+    calls: list[str] = []
+
+    def fake_ask(prompt, *a, **k):
+        calls.append(prompt)
+        return '["beta", "alpha"]'
+
+    monkeypatch.setattr(ai, "available", lambda: True)
+    monkeypatch.setattr(ai, "ask", fake_ask)
+    return calls
+
+
+HITS = [_hit("alpha", 2.0, "alpha snippet"), _hit("beta", 1.0, "beta snippet")]
+
+
+class TestCacheHit:
+    def test_identical_rerank_answers_from_cache(self, asked):
+        first, label1 = rag.rerank("find the widget", list(HITS))
+        again, label2 = rag.rerank("find the widget", list(HITS))
+        assert len(asked) == 1                       # one LLM call, not two
+        assert label1 == label2 == rag.LLM_RANKER    # a hit IS the LLM's order
+        assert first == again
+        assert [h["entry"]["name"] for h in again][:2] == ["beta", "alpha"]
+
+    def test_cached_order_applies_to_the_hits_passed_now(self, asked):
+        """The cache stores the ORDER, not the hits: scores sit outside the
+        candidate listing, so rescored hits still key to the same entry and
+        get the cached order applied to their fresh values."""
+        rag.rerank("find the widget", list(HITS))
+        rescored = [_hit("alpha", 9.9, "alpha snippet"),
+                    _hit("beta", 8.8, "beta snippet")]
+        again, _ = rag.rerank("find the widget", rescored)
+        assert len(asked) == 1
+        assert [h["entry"]["name"] for h in again][:2] == ["beta", "alpha"]
+        assert again[0]["score"] == 8.8              # fresh hit, cached order
+
+
+class TestCacheKey:
+    def test_a_different_query_misses(self, asked):
+        rag.rerank("find the widget", list(HITS))
+        rag.rerank("find the gadget", list(HITS))
+        assert len(asked) == 2
+
+    def test_a_different_candidate_listing_misses(self, asked):
+        rag.rerank("find the widget", list(HITS))
+        changed = [_hit("alpha", 2.0, "reworded snippet"), HITS[1]]
+        rag.rerank("find the widget", changed)
+        assert len(asked) == 2
+
+    def test_a_different_limit_misses(self, asked):
+        rag.rerank("find the widget", list(HITS), limit=10)
+        rag.rerank("find the widget", list(HITS), limit=5)
+        assert len(asked) == 2
+
+
+class TestDegradation:
+    def test_a_non_array_reply_is_not_cached(self, asked, monkeypatch):
+        monkeypatch.setattr(ai, "ask", lambda *a, **k: (asked.append("x"),
+                                                        "no json here")[1])
+        _hits, label = rag.rerank("q", list(HITS), engine="BM25 full-content")
+        assert label == "BM25 full-content"          # degrade, as today
+        rag.rerank("q", list(HITS))
+        assert len(asked) == 2                       # second call asks again
+
+    def test_no_ai_means_no_cache_file(self, sandbox, monkeypatch):
+        monkeypatch.setattr(ai, "available", lambda: False)
+        _hits, label = rag.rerank("q", list(HITS), engine="dense vectors")
+        assert label == "dense vectors"
+        assert not rag.rerank_cache_path().exists()
+
+    def test_corrupt_cache_file_degrades_and_heals(self, asked):
+        paths.ensure_dirs()
+        rag.rerank_cache_path().write_text("not json{", encoding="utf-8")
+        rag.rerank("find the widget", list(HITS))
+        assert len(asked) == 1                       # worked, asked live
+        data = json.loads(rag.rerank_cache_path().read_text(encoding="utf-8"))
+        assert len(data) == 1                        # rewritten valid
+
+    def test_kill_switch_bypasses_read_and_write(self, asked, monkeypatch):
+        monkeypatch.setenv("BOOST_NO_RERANK_CACHE", "1")
+        rag.rerank("find the widget", list(HITS))
+        rag.rerank("find the widget", list(HITS))
+        assert len(asked) == 2
+        assert not rag.rerank_cache_path().exists()
+
+
+class TestEviction:
+    def test_cache_is_capped_fifo(self, asked, monkeypatch):
+        monkeypatch.setattr(rag, "RERANK_CACHE_CAP", 3)
+        for q in ("q1", "q2", "q3", "q4"):
+            rag.rerank(q, list(HITS))
+        data = json.loads(rag.rerank_cache_path().read_text(encoding="utf-8"))
+        assert len(data) == 3                        # capped
+        rag.rerank("q4", list(HITS))
+        assert len(asked) == 4                       # newest still cached
+        rag.rerank("q1", list(HITS))
+        assert len(asked) == 5                       # oldest was evicted
+
+
+class TestRegistration:
+    def test_registered_so_boost_clean_spares_it(self):
+        assert rag.rerank_cache_path().name in paths.INTERNAL_CACHE_FILES