boost-skill-cli 1.0.339__tar.gz → 1.0.341__tar.gz

{boost_skill_cli-1.0.339/boost_skill_cli.egg-info → boost_skill_cli-1.0.341}/PKG-INFO

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

{boost_skill_cli-1.0.339 → boost_skill_cli-1.0.341}/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.339'
-__version_tuple__ = version_tuple = (1, 0, 339)
+__version__ = version = '1.0.341'
+__version_tuple__ = version_tuple = (1, 0, 341)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.339 → boost_skill_cli-1.0.341}/boost_cli/commands/configuration.py

@@ -816,7 +816,15 @@ REGISTRY = mcp.Registry()
 def _tool_search(args: dict):
     query = str(args.get("query", ""))
     rag.ensure()  # build the full-content index on first use (BM25 by default)
-    rag_result = rag.search(query, limit=10)
+    # smart=True is stated, not inherited. It is `rag.search`'s default, so this
+    # path was spending an LLM call per search by accident of a signature —
+    # while the CLI makes the user ask for it with `--smart`. Measured on the
+    # 91-query golden set, the rerank moves hit@1 from 0.791 to 0.945, and an
+    # agent acts on the top result rather than scanning ten, so it is the one
+    # caller for whom the seconds are clearly worth it. Written down here so
+    # the asymmetry with the CLI is a decision someone can revisit, not a
+    # default nobody chose. It degrades on its own when no AI is configured.
+    rag_result = rag.search(query, limit=10, smart=True)
     if rag_result is not None:  # full-content index is built
         hits, _ranker = rag_result
         if not hits:
@@ -953,8 +961,10 @@ REGISTRY.register(
     "in front of you has a name you could say out loud — \"set up code "
     "review\", \"add commit conventions\", \"debug flaky tests\" — and before "
     "writing a skill, subagent, slash-command or rule from scratch. Read-only, "
-    "no side effects, installs nothing. Returning nothing relevant is a fine "
-    "answer: it means build it yourself.",
+    "no side effects, installs nothing. Takes a few seconds because it ranks "
+    "the matches with an LLM, which is what makes the top result worth acting "
+    "on. Returning nothing relevant is a fine answer: it means build it "
+    "yourself.",
     {"type": "object",
      "properties": {"query": {"type": "string",
                               "description": "what the skill should do (a task, "

{boost_skill_cli-1.0.339 → boost_skill_cli-1.0.341}/boost_cli/core/mcp.py

@@ -113,8 +113,11 @@ INSTRUCTIONS = (
     "review\", \"add commit conventions\", \"write a migration\", \"debug "
     "flaky tests\" — someone has probably already written it down. Call "
     "boost_list for what is installed on this machine and boost_search for "
-    "what exists. Both are read-only, take about a second, and install "
-    "nothing.\n"
+    "what exists. Both are read-only and install nothing. boost_list is "
+    "instant. boost_search takes a few seconds: it retrieves, then ranks them "
+    "with an LLM, which is worth it because you act on the top result — "
+    "measured, that ranking puts the right skill first 95% of the time "
+    "against 79% without it.\n"
     "\n"
     "Finding nothing is a good outcome, not a wasted call: it tells you to "
     "build it yourself, now knowing that nothing already covers it. Finding "

{boost_skill_cli-1.0.339 → boost_skill_cli-1.0.341/boost_skill_cli.egg-info}/PKG-INFO

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

{boost_skill_cli-1.0.339 → boost_skill_cli-1.0.341}/boost_skill_cli.egg-info/SOURCES.txt

@@ -255,6 +255,7 @@ docs/roadmap/items/mcp-launch-objc-fork-safety.md
 docs/roadmap/items/mcp-one-benefit-nameable-task.md
 docs/roadmap/items/mcp-register-names-server-before-env.md
 docs/roadmap/items/mcp-search-before-reinventing.md
+docs/roadmap/items/mcp-search-cost-was-understated.md
 docs/roadmap/items/mcp-servers-ignore-install-scope.md
 docs/roadmap/items/mcp-startup-self-harden-fork-safety.md
 docs/roadmap/items/memoize-config-load-in-process.md

{boost_skill_cli-1.0.339 → boost_skill_cli-1.0.341}/docs/roadmap/items/keyless-semantic-search-for-everyone.md

@@ -331,3 +331,25 @@ both sides, and only the document half can be shipped ahead of time.
 <b>Still open in step 2:</b> the CI workflow that publishes shards as release artifacts, and the
 <code>boost tap</code> integration that fetches one automatically. Both are now plumbing on top of a
 verified mechanism rather than open questions. Steps 3 and 5 are untouched.
+
+<b>Step 3 works, and it did not need new code &mdash; it needed proving.</b> Local delta top-up falls
+out of the shard mechanism plus the commit-keyed reuse <code>build()</code> already had:
+<code>import_shard</code> records the tap's commit in the same <code>meta.commits</code> map
+<code>build()</code> consults, so an imported shard is indistinguishable from locally-built vectors
+as far as reuse is concerned.
+
+Measured end to end with a stubbed embedder, on a store holding an imported shard for
+<code>anthropics/skills</code> plus a freshly tapped <code>Aaronontheweb/dotnet-cursor-rules</code>:
+<b>158 chunks embedded &mdash; the new tap only &mdash; and the shard's 262 untouched</b>. The
+resulting store is one coherent embedding space: 420 vectors, both taps' commits recorded, single
+provider/model/dim. That is exactly the shape this step asks for &mdash; shards cover the popular
+registries, the local model makes the long tail self-serve, and cost scales with what a user taps
+rather than with the ecosystem.
+
+Two tests now pin it, because the coupling is the kind that breaks silently: an import that forgot to
+record the commit would still produce a <em>working</em> store, and the only symptom would be
+re-embedding the shard's chunks on every later build &mdash; minutes of wasted CPU that nothing
+reports.
+
+<b>Steps 1, 2, 3, 4 and 6 are now done; step 5 (a hosted demo) is the remainder</b>, along with the
+CI workflow that publishes shards as release artifacts, which is noted under step 2.

boost_skill_cli-1.0.341/docs/roadmap/items/mcp-search-cost-was-understated.md

@@ -0,0 +1,44 @@
+---
+id: mcp-search-cost-was-understated
+board: code
+section: dx
+status: inflight
+category: Interop · Adoption
+complexity: S
+impact: Medium
+wow: 2
+note: the instructions claimed a second; it is twelve
+order: 76
+owner: loop/mcp-true-cost
+pr: 
+title: The MCP instructions understated what a search costs by 100x
+---
+<a href="#mcp-one-benefit-nameable-task">The nameable-task rewrite</a> gave the MCP
+server a stated cost, on the reasoning that an unknown-price call with an unknown hit
+rate gets skipped. That reasoning still holds. The number was wrong: <em>"Both are
+read-only, take about a second, and install nothing."</em> Measured against the real
+path, <code>boost_list</code> is instant but <code>boost_search</code> runs
+<b>11.7&ndash;17.0&nbsp;s</b> (median ~12) against <b>0.10&nbsp;s</b> with the rerank
+off &mdash; because <code>rag.search</code> defaults <code>smart=True</code> and the MCP
+tool called it bare, so every agent search spends an LLM call while the CLI makes a
+human ask with <code>--smart</code>.
+<b>Ship the cost, not a smaller one.</b> The fix is not to hide the latency: the rerank
+is the largest measured quality lever in the retrieval stack. On the 91-query golden set
+it moves <code>hit@1</code> from <b>0.791 to 0.945</b> &mdash; +14 net queries, against
+the ~6-query floor for <em>p</em>&lt;0.05 at this <em>n</em>. For scale, full-content
+BM25 beat the old frontmatter search by +0.077, and dense retrieval tied BM25 exactly at
+0.000. An agent acts on the top result rather than scanning ten, so it is the caller for
+whom those seconds are most clearly worth paying. The instructions now separate the two
+tools (<code>boost_list</code> instant, <code>boost_search</code> a few seconds) and say
+what the seconds buy, because a wrong cost in the one paragraph whose job is to make the
+tool worth reaching for discredits everything around it &mdash; and an agent that
+budgeted a second gets a surprise instead of a decision.
+<b>The default is now written down.</b> <code>smart=True</code> is passed explicitly at
+the MCP call site with the measurement in a comment. It was previously inherited from
+<code>rag.search</code>'s signature, which meant the most expensive behaviour in the
+tool was an accident nobody had chosen and nobody could find. Same asymmetry as before,
+but now it is a decision someone can revisit.
+<b>What is still unmeasured:</b> the lift is over <em>raw BM25</em>, the pipeline that
+stopped shipping when RRF fusion landed. Whether it survives over the fused ranking
+needs the arm that
+<a href="#keyless-semantic-search-for-everyone">step 6</a> is already committed to.

{boost_skill_cli-1.0.339 → boost_skill_cli-1.0.341}/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>190</b><span>Loop finds</span></div>
+      <div class="stat"><b>191</b><span>Loop finds</span></div>
       <!-- /ROADMAP:stats -->
     </div>
   </section>
@@ -918,7 +918,29 @@ both sides, and only the document half can be shipped ahead of time.
 
 <b>Still open in step 2:</b> the CI workflow that publishes shards as release artifacts, and the
 <code>boost tap</code> integration that fetches one automatically. Both are now plumbing on top of a
-verified mechanism rather than open questions. Steps 3 and 5 are untouched.</p>
+verified mechanism rather than open questions. Steps 3 and 5 are untouched.
+
+<b>Step 3 works, and it did not need new code &mdash; it needed proving.</b> Local delta top-up falls
+out of the shard mechanism plus the commit-keyed reuse <code>build()</code> already had:
+<code>import_shard</code> records the tap's commit in the same <code>meta.commits</code> map
+<code>build()</code> consults, so an imported shard is indistinguishable from locally-built vectors
+as far as reuse is concerned.
+
+Measured end to end with a stubbed embedder, on a store holding an imported shard for
+<code>anthropics/skills</code> plus a freshly tapped <code>Aaronontheweb/dotnet-cursor-rules</code>:
+<b>158 chunks embedded &mdash; the new tap only &mdash; and the shard's 262 untouched</b>. The
+resulting store is one coherent embedding space: 420 vectors, both taps' commits recorded, single
+provider/model/dim. That is exactly the shape this step asks for &mdash; shards cover the popular
+registries, the local model makes the long tail self-serve, and cost scales with what a user taps
+rather than with the ecosystem.
+
+Two tests now pin it, because the coupling is the kind that breaks silently: an import that forgot to
+record the commit would still produce a <em>working</em> store, and the only symptom would be
+re-embedding the shard's chunks on every later build &mdash; minutes of wasted CPU that nothing
+reports.
+
+<b>Steps 1, 2, 3, 4 and 6 are now done; step 5 (a hosted demo) is the remainder</b>, along with the
+CI workflow that publishes shards as release artifacts, which is noted under step 2.</p>
         <div class="meta">
           <span class="m">Complexity <b>L</b></span>
           <span class="m hi">Impact <b>High</b></span>
@@ -4755,6 +4777,46 @@ with a negative assertion so the hop cannot creep back.</p>
           <span class="m">agent reflex</span>
         </div>
       </article>
+
+      <article class="cap rcard" id="mcp-search-cost-was-understated">
+        <div class="head"><span class="pill inflight">In flight</span><span class="cat">Interop · Adoption</span></div>
+        <h3>The MCP instructions understated what a search costs by 100x</h3>
+        <p><a href="#mcp-one-benefit-nameable-task">The nameable-task rewrite</a> gave the MCP
+server a stated cost, on the reasoning that an unknown-price call with an unknown hit
+rate gets skipped. That reasoning still holds. The number was wrong: <em>"Both are
+read-only, take about a second, and install nothing."</em> Measured against the real
+path, <code>boost_list</code> is instant but <code>boost_search</code> runs
+<b>11.7&ndash;17.0&nbsp;s</b> (median ~12) against <b>0.10&nbsp;s</b> with the rerank
+off &mdash; because <code>rag.search</code> defaults <code>smart=True</code> and the MCP
+tool called it bare, so every agent search spends an LLM call while the CLI makes a
+human ask with <code>--smart</code>.
+<b>Ship the cost, not a smaller one.</b> The fix is not to hide the latency: the rerank
+is the largest measured quality lever in the retrieval stack. On the 91-query golden set
+it moves <code>hit@1</code> from <b>0.791 to 0.945</b> &mdash; +14 net queries, against
+the ~6-query floor for <em>p</em>&lt;0.05 at this <em>n</em>. For scale, full-content
+BM25 beat the old frontmatter search by +0.077, and dense retrieval tied BM25 exactly at
+0.000. An agent acts on the top result rather than scanning ten, so it is the caller for
+whom those seconds are most clearly worth paying. The instructions now separate the two
+tools (<code>boost_list</code> instant, <code>boost_search</code> a few seconds) and say
+what the seconds buy, because a wrong cost in the one paragraph whose job is to make the
+tool worth reaching for discredits everything around it &mdash; and an agent that
+budgeted a second gets a surprise instead of a decision.
+<b>The default is now written down.</b> <code>smart=True</code> is passed explicitly at
+the MCP call site with the measurement in a comment. It was previously inherited from
+<code>rag.search</code>'s signature, which meant the most expensive behaviour in the
+tool was an accident nobody had chosen and nobody could find. Same asymmetry as before,
+but now it is a decision someone can revisit.
+<b>What is still unmeasured:</b> the lift is over <em>raw BM25</em>, the pipeline that
+stopped shipping when RRF fusion landed. Whether it survives over the fused ranking
+needs the arm that
+<a href="#keyless-semantic-search-for-everyone">step 6</a> is already committed to.</p>
+        <div class="meta">
+          <span class="m">Complexity <b>S</b></span>
+          <span class="m">Impact <b>Medium</b></span>
+          <span class="m">Wow <b class="wow">★★</b></span>
+          <span class="m">the instructions claimed a second; it is twelve</span>
+        </div>
+      </article>
       <!-- /ROADMAP:cards -->
 
     </div>

{boost_skill_cli-1.0.339 → boost_skill_cli-1.0.341}/tests/unit/test_dense_shards.py

@@ -96,7 +96,19 @@ def with_backend(monkeypatch):
     instead of exercising the check they are named for, which is how they
     passed locally and reddened three macOS legs plus the canary.
     """
-    monkeypatch.setattr(dense, "_load", lambda: object())
+    class _FakeVec:
+        """Enough of sqlite_vec for the paths under test.
+
+        `serialize_float32` is real: tests that WRITE vectors reach it, and a
+        bare object() stub only survived while every test stopped at validation.
+        """
+
+        @staticmethod
+        def serialize_float32(vec):
+            import struct
+            return struct.pack("%df" % len(vec), *vec)
+
+    monkeypatch.setattr(dense, "_load", lambda: _FakeVec)
     monkeypatch.setattr(dense, "_connect",
                         lambda: sqlite3.connect(str(dense.db_path())))
 
@@ -240,3 +252,66 @@ class TestWorksWithoutTheExtension:
                  "commit": "c1", "chunks": []}
         ok, reason = dense.import_shard(shard, commit="c1")
         assert ok is False and "backend" in reason
+
+
+class TestDeltaTopUp:
+    """An imported shard must make `build` skip that tap and embed only the rest.
+
+    This is step 3 of the keyless epic — "when a tap runs ahead of its published
+    shard, or is a registry CI has never seen, embed just those files on the
+    spot". It works because `import_shard` records the tap's commit in the same
+    `meta.commits` map that `build` consults, so a shard is indistinguishable
+    from locally-built vectors as far as reuse is concerned.
+
+    That coupling is easy to break silently: an import that forgot to record the
+    commit would still produce a working store, and the only symptom would be
+    re-embedding the shard's chunks on the next build — minutes of wasted CPU
+    that nothing reports. Hence a test.
+    """
+
+    def _tap_seen(self, monkeypatch, commits):
+        from boost_cli.core import rag
+        monkeypatch.setattr(rag, "_tap_commits", lambda: commits)
+        monkeypatch.setattr(rag, "_tap_paths", lambda: {})
+
+    def test_an_imported_shard_is_reused_not_re_embedded(self, sandbox,
+                                                         with_backend,
+                                                         monkeypatch):
+        from boost_cli.core import embed
+        _store(rows=(("a", "acme/skills"),))
+        embedded = []
+        monkeypatch.setattr(embed, "embed",
+                            lambda texts, **kw: embedded.extend(texts) or
+                            [[0.1, 0.2, 0.3] for _ in texts])
+        monkeypatch.setattr(embed, "available", lambda: True)
+        monkeypatch.setattr(embed, "dimension", lambda: 3)
+        monkeypatch.setattr(embed, "provider", lambda: "local")
+        monkeypatch.setattr(embed, "model", lambda: "bge")
+        self._tap_seen(monkeypatch, {"acme__skills": "c1"})
+        entries = [{"name": "a", "tap": "acme/skills", "kind": "skill",
+                    "skill_md": "a/SKILL.md", "_body": "text", "description": ""}]
+        stats = dense.build(entries=entries, force=False)
+        assert stats is not None
+        assert "acme__skills" in stats["reused"]
+        assert embedded == [], "re-embedded a tap the shard already covered"
+
+    def test_a_tap_the_shard_does_not_cover_is_still_embedded(self, sandbox,
+                                                              with_backend,
+                                                              monkeypatch):
+        # The other half: shards cover the popular registries, the local model
+        # makes the long tail self-serve. If this regressed, an uncatalogued
+        # registry would be a dead end for a keyless user.
+        from boost_cli.core import embed
+        _store(rows=(("a", "acme/skills"),))
+        monkeypatch.setattr(embed, "embed",
+                            lambda texts, **kw: [[0.1, 0.2, 0.3] for _ in texts])
+        monkeypatch.setattr(embed, "available", lambda: True)
+        monkeypatch.setattr(embed, "dimension", lambda: 3)
+        monkeypatch.setattr(embed, "provider", lambda: "local")
+        monkeypatch.setattr(embed, "model", lambda: "bge")
+        self._tap_seen(monkeypatch, {"acme__skills": "c1", "new__repo": "z9"})
+        entries = [{"name": "b", "tap": "new/repo", "kind": "skill",
+                    "skill_md": "b/SKILL.md", "_body": "text", "description": ""}]
+        stats = dense.build(entries=entries, force=False)
+        assert stats is not None
+        assert "new/repo" in stats["reindexed"]

{boost_skill_cli-1.0.339 → boost_skill_cli-1.0.341}/tests/unit/test_mcp.py

@@ -149,6 +149,28 @@ class TestHandleRequest:
         assert "before you write a new skill" not in low
         assert "authoring" not in low
 
+    def test_instructions_do_not_understate_what_a_search_costs(self):
+        # The first version of this block said both tools "take about a second".
+        # boost_list does; boost_search does NOT -- it reranks with an LLM by
+        # default, measured at ~12s median against 0.10s without. Shipping a
+        # false cost in the text whose whole job is making the tool worth
+        # reaching for is the one lie that discredits the rest of it, and an
+        # agent that budgeted a second gets a surprise instead of a decision.
+        low = mcp.INSTRUCTIONS.lower()
+        assert "about a second" not in low
+        # State it, and state why it is worth paying rather than just warning.
+        assert "seconds" in low
+        assert "ranks them with an llm" in low or "reranks" in low
+        assert "read-only" in low          # the part that WAS true stays
+
+    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
+        # number is what produced the wrong claim. Naming them separately is
+        # what lets an agent reach for the cheap one freely.
+        low = mcp.INSTRUCTIONS.lower()
+        assert "boost_list" in low and "boost_search" in low
+        assert "instant" in low
+
     def test_instructions_route_search_straight_to_install(self):
         # boost_info sat between search and install in the advertised flow, but
         # search already returns each hit's description — the only field that