boost-skill-cli 1.0.337__tar.gz → 1.0.338__tar.gz

{boost_skill_cli-1.0.337/boost_skill_cli.egg-info → boost_skill_cli-1.0.338}/PKG-INFO

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

{boost_skill_cli-1.0.337 → boost_skill_cli-1.0.338}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.337'
-__version_tuple__ = version_tuple = (1, 0, 337)
+__version__ = version = '1.0.338'
+__version_tuple__ = version_tuple = (1, 0, 338)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.337 → boost_skill_cli-1.0.338}/boost_cli/core/rag.py

@@ -674,11 +674,22 @@ def retrieve(query: str, k: int = 60, kind: Optional[str] = None,
     return dedupe_by_content(hits, k)
 
 
-def rerank(query: str, hits: List[Hit], limit: int = 10) -> Tuple[List[Hit], str]:
-    """Reorder the shortlist with the LLM bridge; degrade to BM25 order."""
+def rerank(query: str, hits: List[Hit], limit: int = 10,
+           engine: str = "BM25 full-content") -> Tuple[List[Hit], str]:
+    """Reorder the shortlist with the LLM bridge; degrade to ``engine`` order.
+
+    ``engine`` is the label from whichever retrieval actually produced ``hits``.
+    Both degrade paths below return it rather than a hard-coded string: this
+    function does not know how the shortlist was built, and guessing was wrong
+    for every user whose dense store worked. Naming a specific wrong engine is
+    worse than naming none — the label is the only signal about which engine
+    answered, so a confident "BM25 full-content" sent debugging somewhere else.
+
+    The default keeps direct callers unchanged; ``search`` passes the real one.
+    """
     top = hits[:max(limit, 15)]
     if not ai.available():
-        return hits[:limit], "BM25 full-content"
+        return hits[:limit], engine
     listing = "\n".join(
         "- %s [%s]: %s" % (h["entry"]["name"], h["entry"].get("kind", "skill"),
                            (h["snippet"] or h["entry"].get("description", ""))[:180])
@@ -691,7 +702,9 @@ def rerank(query: str, hits: List[Hit], limit: int = 10) -> Tuple[List[Hit], str
         max_tokens=400)
     order = _json_array(reply)
     if not order:
-        return hits[:limit], "BM25 full-content"
+        # 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
     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"]
@@ -832,7 +845,9 @@ def search(query: str, limit: int = 10, kind: Optional[str] = None,
     if hits is None:
         return None
     if smart:
-        return rerank(query, hits, limit)
+        # Hand the retrieval label down rather than dropping it: when the
+        # rerank degrades, this is the only thing that knows what actually ran.
+        return rerank(query, hits, limit, engine=engine)
     return hits[:limit], engine
 
 

{boost_skill_cli-1.0.337 → boost_skill_cli-1.0.338/boost_skill_cli.egg-info}/PKG-INFO

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

{boost_skill_cli-1.0.337 → boost_skill_cli-1.0.338}/boost_skill_cli.egg-info/SOURCES.txt

@@ -303,6 +303,7 @@ docs/roadmap/items/required-checks-config-drift.md
 docs/roadmap/items/retrieval-quality-eval-harness.md
 docs/roadmap/items/reuse-helpers-kill-minor-dead-work.md
 docs/roadmap/items/roadmap-html-goes-stale-on-every-rebase.md
+docs/roadmap/items/roadmap-page-weight-grows-without-bound.md
 docs/roadmap/items/robust-tag-argument-parsing.md
 docs/roadmap/items/ruff-016-widens-the-default-rule-set.md
 docs/roadmap/items/rule-install-native-materialization.md

boost_skill_cli-1.0.338/docs/roadmap/items/roadmap-page-weight-grows-without-bound.md

@@ -0,0 +1,49 @@
+---
+id: roadmap-page-weight-grows-without-bound
+board: code
+section: docsite
+status: planned
+category: Docs · Performance
+complexity: M
+impact: Med
+wow: 2
+note: 302 KB to 410 KB in one session; 164 shipped cards render in full
+order: 76
+owner:
+pr:
+title: <code>roadmap.html</code> grew 36% in one session and nothing bounds it
+---
+The generated board is <b>407.6&nbsp;KB, of which 404.7&nbsp;KB is markup</b> — 189
+<code>&lt;article&gt;</code> cards rendered eagerly into one DOM. Measured across this session's
+merges it went <b>301.6&nbsp;KB &rarr; 409.9&nbsp;KB, a 36% rise</b>, monotonically increasing with
+every card documented.
+
+<b>The mechanism is that shipped work never stops costing.</b> Sizing the sections: <code>shipped</code>
+17.6&nbsp;KB / 16 cards, <code>next</code> 1.1&nbsp;KB / 1, <code>planned</code>
+<b>383.0&nbsp;KB / 172</b> — but 164 of those 172 carry a <code>shipped</code> pill. They are finished
+items grouped under their original section, each still rendering its full body, and those bodies grow
+because closing an item well means recording what was measured and what turned out to be wrong. The
+board is now mostly an archive that every visitor downloads in full.
+
+<b>This is NOT what failed <code>lighthouse</code> on <code>#386</code>, and that is worth stating
+because the correlation is seductive.</b> <code>#388</code> passed the same gate at
+<b>409.9&nbsp;KB</b> — very slightly <em>larger</em> than <code>#386</code>'s 409.8&nbsp;KB, which
+failed. A bigger page scoring better rules out page weight as that failure's cause; it was runner
+variance, exactly as <code>lighthouse.yml</code>'s own comment predicts ("a single sample dips into
+the 80s under runner load, which the median absorbs"). The performance floor is
+<code>minScore 0.85</code> against a normal score of ~99–100, so there is real headroom today.
+
+<b>The case for doing it anyway is the trend, not the current number.</b> At roughly +6&nbsp;KB per
+merged card the page crosses 500&nbsp;KB within a few working sessions, and DOM size is precisely
+what Lighthouse's performance category penalises — so this becomes the cause eventually even though
+it is not the cause now.
+
+<b>Likely levers, cheapest first.</b> Collapse shipped card bodies behind
+<code>&lt;details&gt;</code> so the text ships but does not render — that alone addresses the
+383&nbsp;KB block and keeps every word searchable in the source. Failing that, render shipped items
+as one-line entries linking to their item file, or paginate by section. All three live in
+<code>scripts/build_roadmap.py</code>; none require touching an item file, which matters because the
+item files are the merge-conflict-free part of this design.
+
+<b>Do not raise the Lighthouse floor to fix this.</b> The floor is calibrated and honest; a page that
+outgrows it should be made smaller, not re-graded.

{boost_skill_cli-1.0.337 → boost_skill_cli-1.0.338}/docs/roadmap.html

@@ -111,7 +111,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>4</b><span>Planned</span></div>
-      <div class="stat"><b>189</b><span>Loop finds</span></div>
+      <div class="stat"><b>190</b><span>Loop finds</span></div>
       <!-- /ROADMAP:stats -->
     </div>
   </section>
@@ -5215,6 +5215,51 @@ so they were green on CI and red on any machine that had installed it.</p>
           <span class="m">silent BM25-only is the default outcome</span>
         </div>
       </article>
+
+      <article class="cap rcard" id="roadmap-page-weight-grows-without-bound">
+        <div class="head"><span class="pill planned">Planned</span><span class="cat">Docs · Performance</span></div>
+        <h3><code>roadmap.html</code> grew 36% in one session and nothing bounds it</h3>
+        <p>The generated board is <b>407.6&nbsp;KB, of which 404.7&nbsp;KB is markup</b> — 189
+<code>&lt;article&gt;</code> cards rendered eagerly into one DOM. Measured across this session's
+merges it went <b>301.6&nbsp;KB &rarr; 409.9&nbsp;KB, a 36% rise</b>, monotonically increasing with
+every card documented.
+
+<b>The mechanism is that shipped work never stops costing.</b> Sizing the sections: <code>shipped</code>
+17.6&nbsp;KB / 16 cards, <code>next</code> 1.1&nbsp;KB / 1, <code>planned</code>
+<b>383.0&nbsp;KB / 172</b> — but 164 of those 172 carry a <code>shipped</code> pill. They are finished
+items grouped under their original section, each still rendering its full body, and those bodies grow
+because closing an item well means recording what was measured and what turned out to be wrong. The
+board is now mostly an archive that every visitor downloads in full.
+
+<b>This is NOT what failed <code>lighthouse</code> on <code>#386</code>, and that is worth stating
+because the correlation is seductive.</b> <code>#388</code> passed the same gate at
+<b>409.9&nbsp;KB</b> — very slightly <em>larger</em> than <code>#386</code>'s 409.8&nbsp;KB, which
+failed. A bigger page scoring better rules out page weight as that failure's cause; it was runner
+variance, exactly as <code>lighthouse.yml</code>'s own comment predicts ("a single sample dips into
+the 80s under runner load, which the median absorbs"). The performance floor is
+<code>minScore 0.85</code> against a normal score of ~99–100, so there is real headroom today.
+
+<b>The case for doing it anyway is the trend, not the current number.</b> At roughly +6&nbsp;KB per
+merged card the page crosses 500&nbsp;KB within a few working sessions, and DOM size is precisely
+what Lighthouse's performance category penalises — so this becomes the cause eventually even though
+it is not the cause now.
+
+<b>Likely levers, cheapest first.</b> Collapse shipped card bodies behind
+<code>&lt;details&gt;</code> so the text ships but does not render — that alone addresses the
+383&nbsp;KB block and keeps every word searchable in the source. Failing that, render shipped items
+as one-line entries linking to their item file, or paginate by section. All three live in
+<code>scripts/build_roadmap.py</code>; none require touching an item file, which matters because the
+item files are the merge-conflict-free part of this design.
+
+<b>Do not raise the Lighthouse floor to fix this.</b> The floor is calibrated and honest; a page that
+outgrows it should be made smaller, not re-graded.</p>
+        <div class="meta">
+          <span class="m">Complexity <b>M</b></span>
+          <span class="m">Impact <b>Med</b></span>
+          <span class="m">Wow <b class="wow">★★</b></span>
+          <span class="m">302 KB to 410 KB in one session; 164 shipped cards render in full</span>
+        </div>
+      </article>
       <!-- /ROADMAP:cards -->
 
     </div>

{boost_skill_cli-1.0.337 → boost_skill_cli-1.0.338}/tests/unit/test_rag.py

@@ -965,18 +965,23 @@ class TestSearchForwarding:
         rag.search("q", limit=1, smart=False)
         assert cap["k"] == 60               # max(60, 4)
 
-    def test_forwards_query_and_limit_to_rerank(self, sandbox, monkeypatch):
+    def test_forwards_query_limit_and_engine_to_rerank(self, sandbox, monkeypatch):
+        # `engine` joined the signature so a degraded rerank can report what
+        # actually retrieved instead of assuming BM25; asserted here because
+        # dropping it again would be silent — search would still return a
+        # plausible label, just the wrong one.
         self._ready_index()
         monkeypatch.setattr(rag, "retrieve", lambda *a, **k: [_hit("a", 1.0)])
         cap = {}
 
-        def spyr(query, hits, limit=10):
-            cap.update(query=query, limit=limit)
+        def spyr(query, hits, limit=10, engine="BM25 full-content"):
+            cap.update(query=query, limit=limit, engine=engine)
             return ([], "x")
         monkeypatch.setattr(rag, "rerank", spyr)
         rag.search("theq", limit=5)         # smart defaults to True
         assert cap["query"] == "theq"
         assert cap["limit"] == 5
+        assert cap["engine"] == "BM25 full-content"   # what this index is
 
 
 class TestIndexPath:

{boost_skill_cli-1.0.337 → boost_skill_cli-1.0.338}/tests/unit/test_rag_fusion.py

@@ -209,3 +209,95 @@ class TestRetrieveAnyFuses:
         rag.retrieve_any("q", kind="rule", entries=ents)
         assert ("bm25", "rule", ents) in seen
         assert ("dense", "rule", ents) in seen
+
+
+class TestRerankPreservesTheEngineLabel:
+    """The engine that actually retrieved must survive the rerank stage.
+
+    ``rerank`` hard-coded ``"BM25 full-content"`` on both of its degrade paths,
+    and ``search`` discards ``retrieve_any``'s label whenever ``smart`` is on —
+    which is the default, and what the MCP ``boost_search`` tool uses. So a user
+    whose dense store and fusion were working perfectly, but who had no
+    ``ANTHROPIC_API_KEY``, was told they were on BM25.
+
+    That is the same class of silent misreport the dense-status work existed to
+    kill: the label is the only signal a user has about which engine answered,
+    and a wrong one sends the investigation somewhere else entirely. Worse here
+    than a missing label, because it names a specific wrong engine confidently.
+    """
+
+    @staticmethod
+    def _hits():
+        return [_hit("a", 2.0), _hit("b", 1.0)]
+
+    def test_no_ai_reports_the_engine_that_retrieved(self, monkeypatch):
+        # 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.
+        monkeypatch.setattr(rag.ai, "available", lambda: False)
+        _out, label = rag.rerank("q", self._hits(), limit=5,
+                                 engine="hybrid RRF (BM25 + dense)")
+        assert label == "hybrid RRF (BM25 + dense)"
+
+    def test_no_ai_reports_dense_when_dense_retrieved(self, monkeypatch):
+        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):
+        # 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)
+        monkeypatch.setattr(rag.ai, "ask", lambda *_a, **_k: "sorry, I can't")
+        _out, label = rag.rerank("q", self._hits(), limit=5,
+                                 engine="hybrid RRF (BM25 + dense)")
+        assert label == "hybrid RRF (BM25 + dense)"
+
+    def test_a_successful_rerank_still_says_claude(self, monkeypatch):
+        # 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)
+        monkeypatch.setattr(rag.ai, "ask", lambda *_a, **_k: '["b", "a"]')
+        out, label = rag.rerank("q", self._hits(), limit=5,
+                                engine="hybrid RRF (BM25 + dense)")
+        assert _names(out) == ["b", "a"]
+        assert label == "Claude relevance"
+
+    def test_the_default_keeps_existing_callers_honest(self, monkeypatch):
+        # Back-compat: an omitted engine still reads "BM25 full-content", so
+        # this is additive for anything that calls rerank directly.
+        monkeypatch.setattr(rag.ai, "available", lambda: False)
+        _out, label = rag.rerank("q", self._hits(), limit=5)
+        assert label == "BM25 full-content"
+
+
+class TestSearchReportsTheTruthEndToEnd:
+    """`search` is where the label is chosen, so the bug is only really fixed
+    if it survives the whole path an MCP call takes."""
+
+    @staticmethod
+    def _wire(monkeypatch, engine_hits, ai_ok):
+        from boost_cli.core import dense as dense_mod
+        monkeypatch.setattr(rag, "ready", lambda: True)
+        monkeypatch.setattr(rag, "retrieve", lambda *_a, **_k: list(engine_hits))
+        monkeypatch.setattr(dense_mod, "ready", lambda: True)
+        monkeypatch.setattr(dense_mod, "retrieve", lambda *_a, **_k: list(engine_hits))
+        monkeypatch.setattr(rag.ai, "available", lambda: ai_ok)
+
+    def test_fused_retrieval_without_a_key_is_not_called_bm25(self, monkeypatch):
+        # Exactly the MCP boost_search path: smart defaults on, no key.
+        self._wire(monkeypatch, [_hit("a"), _hit("b")], ai_ok=False)
+        result = rag.search("q", limit=5)
+        assert result is not None
+        _hits, label = result
+        assert label != "BM25 full-content"
+        assert "dense" in label, label
+
+    def test_smart_off_is_unaffected(self, monkeypatch):
+        self._wire(monkeypatch, [_hit("a")], ai_ok=True)
+        result = rag.search("q", limit=5, smart=False)
+        assert result is not None
+        _hits, label = result
+        assert "dense" in label, label