boost-skill-cli 1.2.20__tar.gz → 1.2.21__tar.gz

{boost_skill_cli-1.2.20 → boost_skill_cli-1.2.21}/.vale/styles/config/vocabularies/boost/accept.txt

@@ -98,6 +98,8 @@ stderr
 Stdlib
 stdlib
 stdout
+stemmer
+stemming
 subagents
 subcommand
 tappable

{boost_skill_cli-1.2.20 → boost_skill_cli-1.2.21}/PKG-INFO

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

{boost_skill_cli-1.2.20 → boost_skill_cli-1.2.21}/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.20'
-__version_tuple__ = version_tuple = (1, 2, 20)
+__version__ = version = '1.2.21'
+__version_tuple__ = version_tuple = (1, 2, 21)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.20 → boost_skill_cli-1.2.21}/boost_cli/commands/discovery.py

@@ -176,10 +176,29 @@ def cmd_search(argv):
             installed=e["name"] in installed, lay=lay))
     out.info(out.role("%d match%s · ranked by %s"
                    % (len(scored), "" if len(scored) == 1 else "es", ranker), "muted"))
+    if use_rag:
+        _note_stem_expansions(query)
     _hint_semantic_search(engine)
     return 0
 
 
+def _note_stem_expansions(query: str) -> None:
+    """Say when a query term was widened to the word actually indexed.
+
+    Staying quiet would be a worse answer than the old empty one: the user
+    asked for `brainstorm` and is looking at results for `brainstorming`, and
+    only one of those is a word they typed.
+    """
+    subs = rag.stem_expansions(rag.tokenize(query))
+    if not subs:
+        return
+    said = ", ".join("%r" % term for term in subs)
+    shown = ", ".join("%r" % term for term in subs.values())
+    out.info(out.role(out.truncate(
+        "no exact match for %s — showing %s" % (said, shown),
+        max(0, out.term_width() - 2)), "muted"))
+
+
 def _hint_semantic_search(engine: str) -> None:
     """Say that a better engine exists, when BM25 answered alone.
 

{boost_skill_cli-1.2.20 → boost_skill_cli-1.2.21}/boost_cli/core/rag.py

@@ -383,6 +383,65 @@ def read_postings(terms: Sequence[str]) -> dict[str, list[list[int]]]:
     return dict(out)  # noqa: FURB123  out is a defaultdict; .copy() would keep the factory
 
 
+# A query term shorter than this expands to noise: `cal` prefixes `calendar`,
+# `calculate` and `callbacks` alike, and picking one of them for the user is a
+# guess rather than a correction.
+STEM_MIN_LEN = 4
+
+
+def stem_expansions(terms: Sequence[str]) -> dict[str, str]:
+    """Map each term that indexes *nothing* to the commonest term it prefixes.
+
+    `tokenize` is exact-match, so a query term and its own inflection are
+    unrelated strings: `boost search brainstorm` returned zero matches while
+    `brainstorming` returned the skill, and `boost chat` had the same hole.
+    Measured over the 461 tap caches on one real machine, 4,663 of 29,607 item
+    names (15.7%) were unreachable by an attested stem — `pattern` missed 474
+    names ending `-patterns`, `skill` missed 252 ending `-skills`.
+
+    **A term that has postings is never expanded.** That is the whole safety
+    argument: this can only ever add signal where `_bm25` scored exactly none
+    (it skips a term with no posting list), so a query whose terms all exist
+    ranks byte-identically and the retrieval floors cannot move. It is also why
+    this is a fallback rather than a stemmer — a real stemmer conflates terms
+    that both exist, which changes established rankings and needs an index
+    format bump and a regenerated baseline.
+
+    Returns ``{}`` — never raises — when the store is missing or unreadable,
+    matching :func:`read_postings`.
+    """
+    uniq = [t for t in dict.fromkeys(terms) if len(t) >= STEM_MIN_LEN]
+    if not uniq:
+        return {}
+    indexed = read_postings(uniq)
+    missing = [t for t in uniq if not indexed.get(t)]
+    if not missing:
+        return {}
+    try:
+        con = sqlite3.connect("file:%s?mode=ro" % postings_path(), uri=True)
+    except sqlite3.Error:
+        return {}
+    out: dict[str, str] = {}
+    try:
+        for term in missing:
+            # `tokenize` emits only [a-z0-9]+, and "~" sorts above every
+            # character it can produce — so this half-open range is exactly the
+            # terms beginning with `term`, and it rides the postings_term index
+            # instead of scanning. Ties break on the term itself so the choice
+            # is deterministic across machines.
+            row = con.execute(
+                "SELECT term FROM postings WHERE term > ? AND term < ? "
+                "GROUP BY term ORDER BY COUNT(*) DESC, term LIMIT 1",
+                (term, term + "~")).fetchone()
+            if row:
+                out[term] = row[0]
+    except sqlite3.Error:
+        return {}
+    finally:
+        con.close()
+    return out
+
+
 def _all_postings() -> dict[str, list[list[int]]]:
     """Every posting — only the incremental rebuild path needs this."""
     try:
@@ -804,6 +863,12 @@ def retrieve(query: str, k: int = 60, kind: str | None = None,
     terms = tokenize(query)
     if not terms:
         return []
+    # Substitute before scoring, not after: the expanded term has to reach the
+    # snippet windowing too, or the hit is highlighted on a word it does not
+    # contain.
+    substitutions = stem_expansions(terms)
+    if substitutions:
+        terms = [substitutions.get(t, t) for t in terms]
     docs = raw["docs"]
     scores = _bm25(terms, raw, read_postings(terms))
     if entries is None:

{boost_skill_cli-1.2.20 → boost_skill_cli-1.2.21}/boost_skill_cli.egg-info/PKG-INFO

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

{boost_skill_cli-1.2.20 → boost_skill_cli-1.2.21}/docs/rag-architecture.md

@@ -135,6 +135,20 @@ 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.
 
+**Tokenization is exact-match, and `stem_expansions` is the one concession to that.**
+A query term and its own inflection are unrelated strings, so `boost search brainstorm`
+returned nothing while `brainstorming` returned the skill. Measured over 461 tap caches,
+4,663 of 29,607 item names (15.7%) were unreachable by an attested stem — `pattern` missed
+474 names ending `-patterns`. Before scoring, any term with **no** posting list is replaced
+by the commonest term it prefixes, found with an index-backed range scan over the postings
+table. A term that *has* postings is never touched: expansion only ever adds signal where
+`_bm25` scored exactly none, so a query whose terms all exist ranks byte-identically and the
+retrieval floors cannot move. That is what makes it a fallback rather than a stemmer — a real
+stemmer conflates terms that both exist, which changes established rankings and would need an
+index-format bump and a regenerated baseline. Terms shorter than `STEM_MIN_LEN` (4) are left
+alone, because a three-letter prefix expands to a guess. `boost search` states the
+substitution rather than silently answering a different question.
+
 **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

{boost_skill_cli-1.2.20 → boost_skill_cli-1.2.21}/docs/roadmap/items/bm25-has-no-stemming.md

@@ -2,14 +2,14 @@
 id: bm25-has-no-stemming
 board: code
 section: pipeline
-status: next
+status: inflight
 category: Search · Retrieval
 complexity: M
 impact: High
 wow: 4
-note: boost search brainstorm finds nothing while brainstorming finds it; 15.7% of catalog names are unreachable by their own stem
+note: a term with no postings is now replaced by the commonest term it prefixes; a term that has postings is never touched, which is what keeps the eval floors still
 order: 127
-owner:
+owner: loop/bm25-stem-fallback
 pr:
 title: <code>boost search brainstorm</code> finds nothing, and <code>brainstorming</code> finds it
 ---
@@ -41,10 +41,28 @@ BM25 path — which is what every user without the extra runs, what
 <code>eval</code> gate floors. There is no <code>--engine</code> flag, so a maintainer cannot
 easily reproduce a plain user's result.
 
-<b>Two fixes, and they are not the same size.</b> A <b>zero-match prefix fallback</b> — on 0
-hits, retry against vocabulary tokens by prefix — touches no index format, needs no baseline
-regeneration, and fires only where BM25 currently returns nothing, so it cannot move a single
-eval metric; it fixes the exact observed symptom in both <code>search</code> and
-<code>chat</code>. A <b>real stemmer</b> is the better answer and costs an index-format bump plus
-a regenerated <code>tests/eval/baseline.json</code>, and would move all four floored metrics.
-Either lands in <code>core/rag.py</code>, so the tests must kill mutants, not merely cover lines.
+<b>What shipped: per-term expansion, not per-query.</b> The obvious design — widen only when the
+whole query returns zero hits — was drafted and rejected, because it does not fix the reported
+case. <code>boost chat &ldquo;what helps me brainstorm&rdquo;</code> already returns non-empty
+results from its other words, so a zero-hit trigger never fires and chat stays broken.
+Expansion is therefore per-term: a term with <b>no</b> posting list is replaced by the commonest
+term it prefixes, found by an index-backed range scan (<code>term &gt; ? AND term &lt; ?</code>,
+upper bound <code>term + "~"</code> because <code>~</code> outranks every character
+<code>tokenize</code> can emit — a bound of <code>"z"</code> silently loses
+<code>analy</code> &rarr; <code>analyze</code>). Measured after: <code>search brainstorm</code>
+returns the skill, and the chat question promotes it from <em>absent</em> to <b>rank 1</b>.
+
+<b>The invariant is the whole safety argument, and it is a test rather than a comment.</b>
+<em>A term that has postings is never expanded.</em> <code>_bm25</code> already skips a term with
+no posting list, so expansion can only add signal where there was exactly none — meaning any
+query whose terms all exist ranks byte-identically and the four retrieval floors cannot move.
+<code>test_a_term_that_has_postings_is_never_expanded</code> pins it against a corpus where
+<code>pattern</code> and <code>patterns</code> both exist, so a build that dropped the guard
+rewrites a query that already worked and fails. Nine hand-written mutants were run against the
+new lines and all nine died, including that one.
+
+<b>Still open: a real stemmer.</b> This fallback cannot help where a term exists but is the wrong
+inflection — a user typing <code>patterns</code> still will not reach an item named
+<code>pattern</code>, because <code>patterns</code> has postings of its own and is left alone.
+Closing that means conflating terms that both exist, which changes established rankings and costs
+an index-format bump plus a regenerated <code>tests/eval/baseline.json</code>.

{boost_skill_cli-1.2.20 → boost_skill_cli-1.2.21}/docs/roadmap.html

@@ -7055,7 +7055,7 @@ state where that line is the advice.</p>
       </article>
 
       <article class="cap rcard" id="bm25-has-no-stemming">
-        <div class="head"><span class="pill next">Next</span><span class="cat">Search · Retrieval</span></div>
+        <div class="head"><span class="pill inflight">In flight</span><span class="cat">Search · Retrieval</span></div>
         <h3><code>boost search brainstorm</code> finds nothing, and <code>brainstorming</code> finds it</h3>
         <p><b>The symptom, in two commands against the same five-skill tap.</b>
 <code>boost search brainstorming</code> returns the skill.
@@ -7085,18 +7085,36 @@ BM25 path — which is what every user without the extra runs, what
 <code>eval</code> gate floors. There is no <code>--engine</code> flag, so a maintainer cannot
 easily reproduce a plain user's result.
 
-<b>Two fixes, and they are not the same size.</b> A <b>zero-match prefix fallback</b> — on 0
-hits, retry against vocabulary tokens by prefix — touches no index format, needs no baseline
-regeneration, and fires only where BM25 currently returns nothing, so it cannot move a single
-eval metric; it fixes the exact observed symptom in both <code>search</code> and
-<code>chat</code>. A <b>real stemmer</b> is the better answer and costs an index-format bump plus
-a regenerated <code>tests/eval/baseline.json</code>, and would move all four floored metrics.
-Either lands in <code>core/rag.py</code>, so the tests must kill mutants, not merely cover lines.</p>
+<b>What shipped: per-term expansion, not per-query.</b> The obvious design — widen only when the
+whole query returns zero hits — was drafted and rejected, because it does not fix the reported
+case. <code>boost chat &ldquo;what helps me brainstorm&rdquo;</code> already returns non-empty
+results from its other words, so a zero-hit trigger never fires and chat stays broken.
+Expansion is therefore per-term: a term with <b>no</b> posting list is replaced by the commonest
+term it prefixes, found by an index-backed range scan (<code>term &gt; ? AND term &lt; ?</code>,
+upper bound <code>term + "~"</code> because <code>~</code> outranks every character
+<code>tokenize</code> can emit — a bound of <code>"z"</code> silently loses
+<code>analy</code> &rarr; <code>analyze</code>). Measured after: <code>search brainstorm</code>
+returns the skill, and the chat question promotes it from <em>absent</em> to <b>rank 1</b>.
+
+<b>The invariant is the whole safety argument, and it is a test rather than a comment.</b>
+<em>A term that has postings is never expanded.</em> <code>_bm25</code> already skips a term with
+no posting list, so expansion can only add signal where there was exactly none — meaning any
+query whose terms all exist ranks byte-identically and the four retrieval floors cannot move.
+<code>test_a_term_that_has_postings_is_never_expanded</code> pins it against a corpus where
+<code>pattern</code> and <code>patterns</code> both exist, so a build that dropped the guard
+rewrites a query that already worked and fails. Nine hand-written mutants were run against the
+new lines and all nine died, including that one.
+
+<b>Still open: a real stemmer.</b> This fallback cannot help where a term exists but is the wrong
+inflection — a user typing <code>patterns</code> still will not reach an item named
+<code>pattern</code>, because <code>patterns</code> has postings of its own and is left alone.
+Closing that means conflating terms that both exist, which changes established rankings and costs
+an index-format bump plus a regenerated <code>tests/eval/baseline.json</code>.</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">boost search brainstorm finds nothing while brainstorming finds it; 15.7% of catalog names are unreachable by their own stem</span>
+          <span class="m">a term with no postings is now replaced by the commonest term it prefixes; a term that has postings is never touched, which is what keeps the eval floors still</span>
         </div>
       </article>
       <!-- /ROADMAP:cards -->

{boost_skill_cli-1.2.20 → boost_skill_cli-1.2.21}/tests/functional/test_cli_discovery.py

@@ -128,6 +128,29 @@ class TestSearch:
         # integer heuristic score — assert the shape, not a magic constant.
         assert isinstance(data[0]["score"], float) and data[0]["score"] > 0
 
+    def test_a_stem_query_reaches_the_inflected_skill_and_says_so(
+            self, boost, tapped):
+        """`boost search brainstorm` used to return nothing at all while
+        `brainstorming` returned the skill, and send the user off to search the
+        whole of GitHub for something already in their catalogue."""
+        r = boost("search", "brainstorm")
+        assert "brainstorming" in r.out
+        assert "no matches" not in r.out
+        # The widening is stated, not silent — the user asked for one word and
+        # is being shown results for another.
+        assert "no exact match for 'brainstorm'" in r.out
+        assert "brainstorming" in r.out
+
+    def test_an_exact_query_is_not_annotated(self, boost, tapped):
+        r = boost("search", "brainstorming")
+        assert "brainstorming" in r.out
+        assert "no exact match" not in r.out
+
+    def test_a_query_matching_nothing_is_not_annotated_either(self, boost, tapped):
+        r = boost("search", "zzzznothing")
+        assert "no exact match" not in r.out
+        assert "no matches for 'zzzznothing'" in r.out
+
     def test_no_taps_fails_with_hint(self, boost):
         r = boost("search", "anything", expect=1)
         assert "no taps configured — nothing to search" in r.err

{boost_skill_cli-1.2.20 → boost_skill_cli-1.2.21}/tests/unit/test_rag.py

@@ -431,6 +431,129 @@ class TestBuildAndRetrieve:
         assert len(snip) <= rag.SNIP_WIDTH + 2        # windowed, not whole chunk
 
 
+@pytest.fixture()
+def stem_corpus(tmp_path, monkeypatch, sandbox):
+    """A corpus with deliberately paired singular/plural vocabulary.
+
+    `pattern` AND `patterns` both exist as terms, which is what lets the
+    never-expand-an-existing-token invariant be tested: a build that dropped
+    that guard would expand `pattern` to `patterns` and change a query that
+    already worked.
+    """
+    root = tmp_path / "stems"
+    items = {
+        "alpha": "pattern matching for structured logs.",
+        "beta": "patterns and antipatterns in distributed systems.",
+        "gamma": "webhook delivery retries.",
+        "delta": "webhooks and callbacks delivery.",
+        "epsilon": "delivered payloads and receipts to analyze.",
+    }
+    entries = []
+    for name, body in items.items():
+        (root / name).mkdir(parents=True)
+        (root / name / "SKILL.md").write_text(
+            "---\nname: %s\n---\n\n%s\n" % (name, body), encoding="utf-8")
+        entries.append(_entry(name, skill_md="%s/SKILL.md" % name))
+    monkeypatch.setattr(rag, "_tap_paths", lambda: {"acme/skills": root})
+    monkeypatch.setattr(rag, "_tap_commits", lambda: {"acme__skills": "c1"})
+    rag.build(entries=entries, force=True)
+    return entries
+
+
+class TestStemExpansions:
+    """`boost search brainstorm` found nothing while `brainstorming` found the
+    skill: `tokenize` is exact-match, so a query term and its own inflection are
+    unrelated strings. Measured over the 461 tap caches on one real machine,
+    4,663 of 29,607 item names (15.7%) were unreachable by an attested stem —
+    `pattern` missed 474 names ending `-patterns`, `skill` missed 252.
+    """
+
+    def test_a_term_that_has_postings_is_never_expanded(self, stem_corpus):
+        """The invariant the whole design rests on.
+
+        Expansion may only ever add signal where there was exactly none, which
+        is what makes it unable to move a ranking that already worked — and so
+        unable to move the eval floors. `pattern` and `patterns` both exist
+        here, so a build that dropped the guard would rewrite `pattern` into
+        `patterns` and this fails.
+        """
+        assert rag.stem_expansions(["pattern"]) == {}
+        assert rag.stem_expansions(["webhook"]) == {}
+        assert rag.stem_expansions(["pattern", "webhook", "delivery"]) == {}
+
+    def test_only_the_missing_term_of_a_mixed_query_is_expanded(self, stem_corpus):
+        assert rag.stem_expansions(["pattern", "callback"]) == {
+            "callback": "callbacks"}
+
+    def test_picks_the_commonest_expansion_not_the_first_alphabetically(
+            self, stem_corpus):
+        """`delivery` is in two documents and `delivered` in one, and
+        `delivered` sorts first — so ordering by document count is the only way
+        to land on `delivery`."""
+        assert rag.stem_expansions(["deliver"]) == {"deliver": "delivery"}
+
+    @pytest.mark.parametrize("term,expected", [
+        ("cal", {}),                       # 3 chars: below the floor
+        ("call", {"call": "callbacks"}),   # 4 chars: exactly at it
+        ("callb", {"callb": "callbacks"}),
+    ])
+    def test_the_minimum_term_length_boundary(self, stem_corpus, term, expected):
+        """Short prefixes expand to noise, so there is a floor; these pin it at
+        exactly 4, which a mutant moving it either way breaks."""
+        assert rag.stem_expansions([term]) == expected
+
+    def test_a_term_whose_next_character_is_z_is_still_found(self, stem_corpus):
+        """`z` is the highest character `tokenize` can emit, so an upper bound
+        of ``term + "z"`` silently excludes exactly the terms that continue
+        with one — `analy` would never reach `analyze`. The bound is `~`,
+        which sorts above every character a token can contain.
+        """
+        assert rag.stem_expansions(["analy"]) == {"analy": "analyze"}
+
+    def test_a_term_that_prefixes_nothing_stays_missing(self, stem_corpus):
+        assert rag.stem_expansions(["zzzznothing"]) == {}
+
+    def test_the_upper_bound_does_not_leak_past_the_prefix(self, stem_corpus):
+        """`camel` sorts after `call` but is not a `call`-prefixed term, so a
+        range whose upper bound is wrong would drag in neighbours."""
+        assert rag.stem_expansions(["calm"]) == {}
+
+    def test_no_postings_file_yields_no_expansions(self, sandbox):
+        assert rag.stem_expansions(["callback"]) == {}
+
+    def test_duplicate_terms_are_asked_once_and_answered_once(self, stem_corpus):
+        assert rag.stem_expansions(["callback", "callback"]) == {
+            "callback": "callbacks"}
+
+
+class TestRetrieveUsesStemExpansions:
+    def test_a_singular_query_reaches_the_plural_item(self, stem_corpus):
+        """The reported symptom, in miniature: `callbacks` is indexed, the user
+        types `callback`, and before this the answer was nothing at all."""
+        hits = rag.retrieve("callback", entries=stem_corpus)
+        assert [h["entry"]["name"] for h in hits] == ["delta"]
+
+    def test_the_snippet_highlights_the_term_that_actually_matched(
+            self, stem_corpus):
+        hits = rag.retrieve("callback", entries=stem_corpus)
+        assert "callbacks" in hits[0]["snippet"].lower()
+
+    def test_a_query_whose_terms_all_exist_is_untouched(self, stem_corpus):
+        names = [h["entry"]["name"]
+                 for h in rag.retrieve("pattern", entries=stem_corpus)]
+        assert names == ["alpha"]      # not beta, which owns `patterns`
+
+    def test_a_mixed_query_keeps_the_existing_term_and_fixes_the_other(
+            self, stem_corpus):
+        names = {h["entry"]["name"]
+                 for h in rag.retrieve("pattern callback", entries=stem_corpus)}
+        assert names == {"alpha", "delta"}
+
+    def test_a_query_that_matches_nothing_at_all_still_returns_nothing(
+            self, stem_corpus):
+        assert rag.retrieve("zzzznothing", entries=stem_corpus) == []
+
+
 class TestBm25Math:
     """Pin the exact BM25 arithmetic (k1=1.2, b=0.75) so formula mutants die."""