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

{boost_skill_cli-1.2.14 → boost_skill_cli-1.2.16}/.vale/styles/config/vocabularies/boost/accept.txt

@@ -25,6 +25,7 @@ dotfiles
 DSPy
 else's
 env
+eval
 evals
 freemium
 frontmatter

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

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

{boost_skill_cli-1.2.14 → 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.14'
-__version_tuple__ = version_tuple = (1, 2, 14)
+__version__ = version = '1.2.16'
+__version_tuple__ = version_tuple = (1, 2, 16)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.14 → 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.14 → boost_skill_cli-1.2.16}/boost_cli/core/dense.py

@@ -263,8 +263,16 @@ def status() -> dict:
 
 
 def ready() -> bool:
-    """True when a usable, provider-matched vector index exists on disk."""
-    if not have_backend() or not embed.available() or not db_path().exists():
+    """True when a usable, provider-matched vector index exists on disk.
+
+    The stat comes first, deliberately: on a machine with no vector store —
+    every BM25-only install — this must answer False without importing the
+    backend, because ``have_backend()`` drags in numpy via sqlite_vec
+    (~120 ms measured) and every cold ``boost search`` asks.
+    """
+    if not db_path().exists():
+        return False
+    if not have_backend() or not embed.available():
         return False
     con = _connect()
     if con is None:

{boost_skill_cli-1.2.14 → 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.14 → 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.14 → 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
@@ -445,12 +446,16 @@ def _load_raw() -> dict | None:
     p = index_path()
     key = str(p)
     try:
-        mtime = p.stat().st_mtime
+        st = p.stat()
     except OSError:
         _CACHE.pop(key, None)
         return None
+    # (mtime_ns, size), not bare mtime: a rewrite landing inside one mtime
+    # tick would otherwise serve the previous index from this cache forever —
+    # the same stamp `catalog._cached_tap` already uses, for the same reason.
+    stamp = (st.st_mtime_ns, st.st_size)
     cached = _CACHE.get(key)
-    if isinstance(cached, tuple) and cached[0] == mtime:
+    if isinstance(cached, tuple) and cached[0] == stamp:
         return cached[1]  # type: ignore[return-value]
     try:
         data = json.loads(p.read_text(encoding="utf-8"))
@@ -458,7 +463,7 @@ def _load_raw() -> dict | None:
         return None
     if not isinstance(data, dict) or data.get("version") != INDEX_VERSION:
         return None
-    _CACHE[key] = (mtime, data)
+    _CACHE[key] = (stamp, data)
     return data
 
 
@@ -699,16 +704,97 @@ def dedupe_by_content(hits: list[Hit], limit: int) -> list[Hit]:
         # Same body already shown. Keep its rank, but prefer a better source.
         kept = out[seen]
         if source_rank(hit["entry"]) < source_rank(kept["entry"]):
-            # cast, not a literal annotation: `Hit` is total=False for the
-            # optional `content` key, and NotRequired needs 3.11 while boost
-            # targets 3.9.
-            out[seen] = cast(Hit, {"entry": hit["entry"],
-                                   "score": kept["score"],
-                                   "snippet": kept["snippet"],
-                                   "content": digest})
+            # Copy the kept hit wholesale and swap only the entry: a literal
+            # rebuild here would silently drop anything else the caller
+            # carried on the hit (retrieve defers snippet windowing through
+            # this function, so the carry is load-bearing, not hygiene).
+            out[seen] = cast(Hit, {**kept, "entry": hit["entry"]})
     return out[:limit]
 
 
+def _windowed(hits: list[Hit], terms: Sequence[str]) -> list[Hit]:
+    """Window each hit's raw stored snip onto the query terms.
+
+    Deferred to the hits actually returned: ranking carries the raw ``snip``
+    through dedupe, and only the survivors pay ``_passage`` — the eager
+    version computed 39,726 windows on a real machine to display 60.
+    """
+    return [cast(Hit, {**h, "snippet": _passage(h["snippet"], terms)})
+            for h in hits]
+
+
+def _retrieve_from_index(docs: list[dict], scores: dict[int, float],
+                         terms: list[str], k: int, kind: str | None,
+                         ) -> list[Hit] | None:
+    """Rank from the index's own doc metadata — no full-catalogue parse.
+
+    The slow path builds a ``live`` map by parsing every tap cache on the
+    machine (458 files, ~100 MB, 0.32 s measured) to serve two needs: filter
+    docs whose entry is gone, and hand back real entry dicts. On a fresh index
+    both are answerable cheaper: every doc of a still-configured tap is live
+    by construction (``ensure()`` rebuilds on staleness), and only the final
+    ``k`` survivors need materialising — so only *their* taps' caches load.
+
+    Ranking, dedupe and tie-breaks use index-side values (``n``/``h``/``k``)
+    that ``build()`` copied from the same cache entries the slow path reads,
+    plus a shadow entry carrying the two fields ``source_rank`` consults
+    (``tap``, ``curated``) from one ``registry.list_taps()`` snapshot — never
+    a second config read, and never :func:`registry.get`, which raises for a
+    concurrently-untapped name.
+
+    Returns ``None`` when any survivor's entry cannot be materialised (a tap
+    cache vanished or moved under a stat-fresh index): the caller reruns the
+    query through the explicit-entries path, whose output is the contract.
+    Byte-identical-or-fall-back, never approximate.
+    """
+    taps = {t.name: t for t in registry.list_taps()}
+    best: dict[tuple[str, str], tuple[float, str, str, str]] = {}
+    for doc_id, score in scores.items():
+        d = docs[doc_id]
+        if kind is not None and d["k"] != kind:
+            continue
+        if d["t"] not in taps:      # untapped repos stop ranking, stale or not
+            continue
+        key = (d["t"], d["f"])
+        prev = best.get(key)
+        if prev is None or score > prev[0]:
+            best[key] = (score, d["snip"], d.get("h", ""), d["n"])
+    ranked = sorted(best.items(),
+                    key=lambda kv: (-kv[1][0], kv[1][3], kv[0]))
+    # The shadow entry carries exactly what downstream code reads before
+    # materialisation: `source_rank` consults tap + curated, and the loop
+    # below reads tap + skill_md. Nothing else — an extra field here would
+    # be dead weight pretending to be contract.
+    hits: list[Hit] = [
+        {"entry": {"tap": key[0], "skill_md": key[1],
+                   "curated": taps[key[0]].curated},
+         "score": score, "content": digest,
+         "snippet": snip}  # type: ignore[typeddict-item]
+        for key, (score, snip, digest, _name) in ranked]
+    # The FULL ranked list flows through dedupe, exactly as the slow path's
+    # does: a curated duplicate at rank 3,000 legally replaces the displayed
+    # source of survivor #1, so the promotion scan cannot be truncated.
+    survivors = dedupe_by_content(hits, len(hits))
+    loaded: dict[str, dict[tuple[str, str], dict]] = {}
+    out: list[Hit] = []
+    for hit in survivors:
+        if len(out) == k:
+            break
+        tap_name = hit["entry"]["tap"]
+        tap = taps.get(tap_name)
+        if tap is None:             # promoted source raced an untap
+            return None
+        if tap_name not in loaded:
+            loaded[tap_name] = {entry_key(e): e
+                                for e in catalog.load_tap(tap)}
+        entry = loaded[tap_name].get((tap_name, hit["entry"]["skill_md"]))
+        if entry is None:
+            return None
+        out.append(cast(Hit, {**hit, "entry": entry,
+                              "snippet": _passage(hit["snippet"], terms)}))
+    return out
+
+
 def retrieve(query: str, k: int = 60, kind: str | None = None,
              entries: list[dict] | None = None) -> list[Hit]:
     """Top-k full-content hits for ``query``. ``[]`` if the index is empty."""
@@ -718,11 +804,20 @@ def retrieve(query: str, k: int = 60, kind: str | None = None,
     terms = tokenize(query)
     if not terms:
         return []
-    entries = catalog.all_entries() if entries is None else entries
-    live = {entry_key(e): e for e in entries}
     docs = raw["docs"]
+    scores = _bm25(terms, raw, read_postings(terms))
+    if entries is None:
+        fast = _retrieve_from_index(docs, scores, terms, k, kind)
+        if fast is not None:
+            return fast
+        # An entry vanished between index and cache: answer from the full
+        # catalogue exactly as before the fast path existed. One side effect
+        # rides along only here now — load_tap's rescan of old-CACHE_FORMAT
+        # caches, which otherwise happens on tap operations and build().
+        entries = catalog.all_entries()
+    live = {entry_key(e): e for e in entries}
     best: dict[tuple[str, str], tuple[float, str, str]] = {}
-    for doc_id, score in _bm25(terms, raw, read_postings(terms)).items():
+    for doc_id, score in scores.items():
         d = docs[doc_id]
         if kind is not None and d["k"] != kind:
             continue
@@ -742,9 +837,52 @@ def retrieve(query: str, k: int = 60, kind: str | None = None,
     # or they still consume the slots they were removed from.
     hits: list[Hit] = [
         {"entry": live[key], "score": score, "content": digest,
-         "snippet": _passage(snip, terms)}  # type: ignore[typeddict-item]
+         "snippet": snip}  # type: ignore[typeddict-item]
         for key, (score, snip, digest) in ranked]
-    return dedupe_by_content(hits, k)
+    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
@@ -766,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():
@@ -774,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.14 → 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.14
+Version: 1.2.16
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

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

@@ -213,6 +213,7 @@ docs/roadmap/items/ci-time-is-now-runner-queueing.md
 docs/roadmap/items/clean-env-install-smoke-pip-and-pipx.md
 docs/roadmap/items/code-scanning-rule-can-be-restored.md
 docs/roadmap/items/codeql-job-rename-stranded-merge-protection.md
+docs/roadmap/items/cold-search-reads-the-whole-catalogue.md
 docs/roadmap/items/command-carousel-page.md
 docs/roadmap/items/command-reference-docs-site.md
 docs/roadmap/items/completions-complete-only-command-names.md
@@ -399,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
@@ -615,6 +617,7 @@ tests/unit/test_dense.py
 tests/unit/test_dense_embed_dedupe.py
 tests/unit/test_dense_fallback.py
 tests/unit/test_dense_fix_hint.py
+tests/unit/test_dense_ready_order.py
 tests/unit/test_dense_shard_real_schema.py
 tests/unit/test_dense_shard_unreadable_vectors.py
 tests/unit/test_dense_shards.py
@@ -684,6 +687,7 @@ tests/unit/test_projectlock.py
 tests/unit/test_provenance.py
 tests/unit/test_publish_golden_dataset.py
 tests/unit/test_rag.py
+tests/unit/test_rag_fastpath.py
 tests/unit/test_rag_fusion.py
 tests/unit/test_registries_fresh.py
 tests/unit/test_registry.py
@@ -692,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.14 → boost_skill_cli-1.2.16}/docs/rag-architecture.md

@@ -135,6 +135,21 @@ normalization, which matters when bodies vary from 3 lines to 300). Sparse term
 Scoring is standard BM25 (`k1≈1.2`, `b≈0.75`). At ~9k items / tens of thousands of chunks this is a
 dict-of-postings scan — comfortably sub-second per query in Python.
 
+**Query path as shipped** (post `cold-search-reads-the-whole-catalogue`): with
+`entries=None` — the CLI, MCP and eval path — `rag.retrieve` ranks straight off
+the index's own doc metadata and materialises real catalog entries only for the
+final `k` survivors, loading only *their* taps' caches (`_retrieve_from_index`).
+The previous shape parsed every tap cache on the machine per query
+(`catalog.all_entries()`: 458 files / ~100 MB / 0.32 s measured at 71.6k
+entries) and computed a display snippet for every scored doc (39,726 calls to
+serve 60). Snippet windowing now runs on returned hits only, on both paths.
+The contract is byte-identical-or-fall-back: any survivor whose entry cannot be
+materialised (a tap cache vanished under a stat-fresh index) reruns the query
+through the explicit-`entries` path rather than approximating. An explicit
+`entries=` list (the eval harness, `boost chat`) keeps today's exact path.
+`dense.ready()` stats the store before importing the backend for the same
+cold-path reason. Measured end to end: 0.94 s → 0.49 s cold at 458 taps.
+
 ### 6b. Two-stage pipeline — upgrade `boost_search` / `catalog.search` **in place**
 
 No parallel MCP tool (per decision). The upgraded flow:

boost_skill_cli-1.2.16/docs/roadmap/items/cold-search-reads-the-whole-catalogue.md

@@ -0,0 +1,49 @@
+---
+id: cold-search-reads-the-whole-catalogue
+board: code
+section: pipeline
+status: inflight
+category: Performance · Search
+complexity: M
+impact: High
+wow: 4
+note: 0.94 s cold search at 71.6k entries — ~0.5 s spent materialising data the top hits never use
+order: 122
+owner: loop/search-perf
+pr:
+title: A cold search materialises 71,600 entries to print five
+---
+Profiled cold <code>boost search</code> at real scale (458 taps, 71,600
+entries): 0.94 s, of which <b>0.32 s</b> is <code>catalog.all_entries()</code>
+parsing every tap cache on the machine (~100 MB of JSON) to build a
+<code>live</code> map whose entries are only <i>displayed</i> for the final k
+hits, <b>0.11 s</b> is <code>_passage</code> windowing a snippet for all
+39,726 scored docs to show 60, and <b>0.12 s</b> is <code>dense.ready()</code>
+importing numpy via sqlite_vec just to answer "no vector store". BM25 scoring
+itself: 18 ms. The engine was fine; the packaging around it was the cost.<br><br>
+Shipped: <code>rag.retrieve(entries=None)</code> now ranks off the index's own
+doc metadata (name/hash/kind/length all live there already), runs the full
+ranked list through <code>dedupe_by_content</code> with shadow entries carrying
+the two fields <code>source_rank</code> reads, and materialises real entries
+for just the survivors' taps — with a <b>byte-identical-or-fall-back</b>
+contract: any survivor that fails to materialise reruns the query through the
+explicit-<code>entries</code> path (the eval-gate path, unchanged). Snippets
+window on returned hits only, on both paths; <code>dense.ready()</code> stats
+before importing; <code>_load_raw</code> keys its cache on
+<code>(mtime_ns, size)</code>. Measured after: <b>0.94 s → 0.49 s cold</b>.
+Complement of the shipped <i>cache-the-catalog-entry-set-across-rag-queries</i>
+(PR 114), which memoised <code>all_entries</code> per process — warm repeats
+were already amortised; this removes the cold-start read entirely.<br><br>
+Analysed and deliberately <b>deferred</b>: moving the per-doc
+<code>snip</code> out of <code>rag_index.json</code> into the postings SQLite.
+<i>bm25-index-is-one-json-blob</i> declined it at 743 entries (14% of the
+JSON); at 71.6k the premise inverts — snips are ~76% (46 MB → 11.4 MB slim,
+103 ms → 37 ms parse) — but an adversarial design review found the v6→v7
+in-place migration can clobber a concurrently rebuilt pair without a
+build-id pairing token, and a mixed-version machine (pipx CLI + long-running
+MCP serve) thrashes full 71k-file reindexes across the version boundary.
+66 ms does not buy that; if the recorded (tap, skill_md)-keyed postings
+follow-up ever lands, fold the snip move into that single format bump.
+Residual known cost: the "semantic search is off" hint imports the backend
+(~0.1 s) on machines with the extra installed but no store built — the one
+state where that line is the advice.

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.14 → 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>260</b><span>Loop finds</span></div>
+      <div class="stat"><b>262</b><span>Loop finds</span></div>
       <!-- /ROADMAP:stats -->
     </div>
   </section>
@@ -6849,6 +6849,51 @@ was a comment. A comment cannot fail a build.</p>
           <span class="m">a comment in the sibling file predicted this exact failure</span>
         </div>
       </article>
+
+      <article class="cap rcard" id="cold-search-reads-the-whole-catalogue">
+        <div class="head"><span class="pill inflight">In flight</span><span class="cat">Performance · Search</span></div>
+        <h3>A cold search materialises 71,600 entries to print five</h3>
+        <p>Profiled cold <code>boost search</code> at real scale (458 taps, 71,600
+entries): 0.94 s, of which <b>0.32 s</b> is <code>catalog.all_entries()</code>
+parsing every tap cache on the machine (~100 MB of JSON) to build a
+<code>live</code> map whose entries are only <i>displayed</i> for the final k
+hits, <b>0.11 s</b> is <code>_passage</code> windowing a snippet for all
+39,726 scored docs to show 60, and <b>0.12 s</b> is <code>dense.ready()</code>
+importing numpy via sqlite_vec just to answer "no vector store". BM25 scoring
+itself: 18 ms. The engine was fine; the packaging around it was the cost.<br><br>
+Shipped: <code>rag.retrieve(entries=None)</code> now ranks off the index's own
+doc metadata (name/hash/kind/length all live there already), runs the full
+ranked list through <code>dedupe_by_content</code> with shadow entries carrying
+the two fields <code>source_rank</code> reads, and materialises real entries
+for just the survivors' taps — with a <b>byte-identical-or-fall-back</b>
+contract: any survivor that fails to materialise reruns the query through the
+explicit-<code>entries</code> path (the eval-gate path, unchanged). Snippets
+window on returned hits only, on both paths; <code>dense.ready()</code> stats
+before importing; <code>_load_raw</code> keys its cache on
+<code>(mtime_ns, size)</code>. Measured after: <b>0.94 s → 0.49 s cold</b>.
+Complement of the shipped <i>cache-the-catalog-entry-set-across-rag-queries</i>
+(PR 114), which memoised <code>all_entries</code> per process — warm repeats
+were already amortised; this removes the cold-start read entirely.<br><br>
+Analysed and deliberately <b>deferred</b>: moving the per-doc
+<code>snip</code> out of <code>rag_index.json</code> into the postings SQLite.
+<i>bm25-index-is-one-json-blob</i> declined it at 743 entries (14% of the
+JSON); at 71.6k the premise inverts — snips are ~76% (46 MB → 11.4 MB slim,
+103 ms → 37 ms parse) — but an adversarial design review found the v6→v7
+in-place migration can clobber a concurrently rebuilt pair without a
+build-id pairing token, and a mixed-version machine (pipx CLI + long-running
+MCP serve) thrashes full 71k-file reindexes across the version boundary.
+66 ms does not buy that; if the recorded (tap, skill_md)-keyed postings
+follow-up ever lands, fold the snip move into that single format bump.
+Residual known cost: the "semantic search is off" hint imports the backend
+(~0.1 s) on machines with the extra installed but no store built — the one
+state where that line is the advice.</p>
+        <div class="meta">
+          <span class="m">Complexity <b>M</b></span>
+          <span class="m hi">Impact <b>High</b></span>
+          <span class="m">Wow <b class="wow">★★★★</b></span>
+          <span class="m">0.94 s cold search at 71.6k entries — ~0.5 s spent materialising data the top hits never use</span>
+        </div>
+      </article>
       <!-- /ROADMAP:cards -->
 
     </div>
@@ -8772,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.14 → 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))