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

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

@@ -5,6 +5,8 @@ allowlisted
 argparse
 Arize
 Attio
+backtick
+backticks
 Bagisto
 bmad
 bookended
@@ -98,6 +100,8 @@ stderr
 Stdlib
 stdlib
 stdout
+stemmer
+stemming
 subagents
 subcommand
 tappable

{boost_skill_cli-1.2.20 → boost_skill_cli-1.2.22}/CLAUDE.md

@@ -212,6 +212,24 @@ line coverage. Target `boost_cli/core` behavior with assertions, not just import
   a workflow is rendered per agent (TOML for Gemini, see
   `workflows.TOML_COMMAND_AGENTS`). Installing a rule therefore edits a file the
   user reads every session — treat it as more invasive than a skill, not less.
+- **A long line is either chrome or data, and only chrome may be wrapped.**
+  `out.wrap()` folds prose to the pane, and the emitters take it opt-in —
+  `warn`/`info`/`dim`/`kv` accept `wrap=True` and each pays for its own prefix,
+  so continuations align under the message rather than folding to column zero.
+  It is opt-in because always-on wrapping would fold the lines that must stay
+  long: `pulse`'s `source=` paths and `fingerprint`'s 64-character hash are the
+  information the line exists to carry, and a hash split across two lines
+  cannot be compared by eye. **A backtick span is one atomic token**, spaces
+  and all — `doctor` and `search` both interpolate `dense.fix_hint()`, whose
+  answers end in `pip install 'boost-skill-cli[rag]'`, and a wrap that splits
+  that hands the user a command which does not run. A token wider than the pane
+  overflows whole rather than breaking. Wrap *before* adding color: `out.role`
+  brackets its argument with a start code and a reset, so coloring first and
+  splitting after leaves line one unterminated and line two plain. And
+  budget the emitter's own indent — wrapping to the full `term_width()` and
+  then letting `out.info` add two spaces is what put `boost search`'s hint one
+  column past the pane it had just been fitted to.
+
 - **Sub-actions of one action repo move in lockstep.** `github/codeql-action/{init,
   analyze,upload-sarif}` and `actions/cache{,/save,/restore}` are each *one repo at
   one commit*, but Dependabot tracks one `uses:` path as one dependency and raises a

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.20
+Version: 1.2.22
 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.22}/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.22'
+__version_tuple__ = version_tuple = (1, 2, 22)
 
 __commit_id__ = commit_id = None

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

@@ -12,7 +12,6 @@ import re
 import shutil
 import subprocess
 import sys
-import textwrap
 import threading
 import time
 import urllib.parse
@@ -152,7 +151,7 @@ def cmd_search(argv):
             if reranked:
                 scored, ranker = reranked, "Claude Haiku relevance"
         else:
-            out.warn(ai.fallback_note())
+            out.warn(ai.fallback_note(), wrap=True)
     shown = scored[:args.limit]
     # The dot marks "a skill by this name is installed" — a name match, with
     # the known homonym caveat (13 real skills share `code-reviewer`). A lock
@@ -176,10 +175,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.
 
@@ -209,8 +227,12 @@ def _hint_semantic_search(engine: str) -> None:
     # runnable — a copy-pasteable `pip install ...` matters more than a hard
     # clamp, and _FIX is tested to hold no token long enough to overflow.
     msg = "semantic search is off — %s" % dense.fix_hint(st.get("reason", ""), st)
-    for line in textwrap.wrap(msg, max(out.term_width(), 20),
-                              break_long_words=False, break_on_hyphens=False):
+    # `- 2` pays for the indent `out.info` adds: wrapping to the full width and
+    # then indenting is what put this hint one column over the pane. Wrap
+    # first, colour each line after — `out.role` brackets its argument with a
+    # start code and a reset, so colouring first and splitting after leaves the
+    # first line unterminated and the second uncoloured.
+    for line in out.wrap(msg, max(out.term_width() - 2, 20)):
         out.info(out.role(line, "muted"))
 
 
@@ -296,7 +318,8 @@ def cmd_reindex(argv):
                           ", ".join(stats["reindexed"]) or "none"), "muted"))
     if args.dense:
         if dense_stats is None:
-            out.warn("dense index skipped — %s" % embed.fallback_note())
+            out.warn("dense index skipped — %s" % embed.fallback_note(),
+                     wrap=True)
         else:
             failed = dense_stats.get("failed") or []
             if failed:

{boost_skill_cli-1.2.20 → boost_skill_cli-1.2.22}/boost_cli/commands/info.py

@@ -694,7 +694,7 @@ def cmd_explain(argv):
                      "extractive summary instead"
                      % ", ".join(faithfulness.ungrounded_terms(reply, text)[:4]))
     else:
-        out.warn(ai.fallback_note())
+        out.warn(ai.fallback_note(), wrap=True)
     meta, body = frontmatter.parse(text)
     desc = str(meta.get("description") or "").strip()
     if desc:

{boost_skill_cli-1.2.20 → boost_skill_cli-1.2.22}/boost_cli/commands/intelligence.py

@@ -46,7 +46,7 @@ def _note_fallback() -> None:
     """Warn once per invocation that the AI path is unavailable."""
     global _warned_fallback
     if not _warned_fallback:
-        out.warn(ai.fallback_note())
+        out.warn(ai.fallback_note(), wrap=True)
         _warned_fallback = True
 
 
@@ -279,8 +279,12 @@ def cmd_simulate(argv: list[str]) -> int:
         out.info("  • (no imperative rules found in the skill body)")
     desc = str(meta.get("description") or "").strip()
     if desc:
-        out.info(out.role('likely triggers when the task involves: "%s"'
-                       % desc[:100], "muted"))
+        # Clipped to 100 characters, which is a length and not a width: at
+        # 80 columns the quoted description ran seven past the pane. Wrapping
+        # shows the same clipped text and fits it.
+        trigger = 'likely triggers when the task involves: "%s"' % desc[:100]
+        for line in out.wrap(trigger, max(out.term_width() - 2, 20)):
+            out.info(out.role(line, "muted"))
     return 0
 
 
@@ -1191,8 +1195,10 @@ def _chat_session(args) -> int:
     if not ai.available():
         # Worth saying up front rather than letting every answer look terse for
         # an unexplained reason.
-        out.info(out.role("no AI configured — answers are the grounded matches "
-                          "themselves (%s)" % ai.fallback_note(), "muted"))
+        note = ("no AI configured — answers are the grounded matches "
+                "themselves (%s)" % ai.fallback_note())
+        for line in out.wrap(note, max(out.term_width() - 2, 20)):
+            out.info(out.role(line, "muted"))
     out.info(out.role("ask about skills; blank line or Ctrl-D to exit", "muted"))
     history: list[chat_engine.Turn] = []
     while True:

{boost_skill_cli-1.2.20 → boost_skill_cli-1.2.22}/boost_cli/commands/quality.py

@@ -364,10 +364,10 @@ def cmd_doctor(argv):
 
     out.heading("boost doctor")
 
-    def bad(msg):
+    def bad(msg, wrap=False):
         nonlocal issues
         issues += 1
-        out.warn(msg)
+        out.warn(msg, wrap=wrap)
 
     if gitutil.has_git():
         out.ok("git on PATH")
@@ -633,11 +633,12 @@ def _report_search_engine(bad) -> None:
         elif st["reason"] == "empty":
             detail += " but holds no vectors"
         bad("semantic search silently off — %d-chunk vector store %s; "
-            "searches are using BM25. %s" % (st["chunks"], detail, fix))
+            "searches are using BM25. %s" % (st["chunks"], detail, fix),
+            wrap=True)
         return
 
     out.info("semantic search not configured — using the full-content BM25 "
-             "engine (%s)" % fix)
+             "engine (%s)" % fix, wrap=True)
 
 
 def _print_skipped(skipped: list[dict]) -> None:
@@ -1010,7 +1011,7 @@ def cmd_conflict(argv):
                 if i in confirmed:
                     p["kind"] = "ai-confirmed"
     elif heuristic and not args.json:
-        out.warn(ai.fallback_note())
+        out.warn(ai.fallback_note(), wrap=True)
 
     if args.json:
         print(json.dumps({"pairs": pairs}))
@@ -1058,8 +1059,10 @@ def cmd_changelog(argv):
     if not lines:
         out.warn("no history found for %s in %s" % (rel, tap.name))
     if len(lines) < 3:
-        print(out.role("  (shallow clone: run `git -C %s fetch --unshallow` "
-                    "for full history)" % _tilde(tap.path), "muted"))
+        note = ("(shallow clone: run `git -C %s fetch --unshallow` "
+                "for full history)" % _tilde(tap.path))
+        for line in out.wrap(note, max(out.term_width() - 2, 20)):
+            print(out.role("  " + line, "muted"))
     return 0
 
 

{boost_skill_cli-1.2.20 → boost_skill_cli-1.2.22}/boost_cli/commands/team.py

@@ -481,8 +481,14 @@ def cmd_protocol(argv) -> int:
     if system == "Linux":
         out.kv("desktop", _tilde(_desktop_file())
                if _desktop_file().exists() else "not registered")
-    out.kv("URL forms", "boost://install/<skill> · boost://install/<tap>:<skill> "
-                        "· boost://tap/<owner>/<repo>")
+    # One form per row rather than a `·`-joined run: the run was 100 columns,
+    # and wrapping it strands a bare `·` at the start of a line, because the
+    # separator is a word to any wrapper. A form per row needs no separator and
+    # reads the same at every width.
+    for i, form in enumerate(("boost://install/<skill>",
+                              "boost://install/<tap>:<skill>",
+                              "boost://tap/<owner>/<repo>")):
+        out.kv("URL forms" if i == 0 else "", form)
     out.dim("  try it: boost protocol open boost://install/brainstorming")
     return 0
 
@@ -713,7 +719,7 @@ def cmd_who(argv) -> int:
         out.table(rows[:20], headers=("WHEN", "USER", "ACTION"))
         print()
         out.dim("based on the local journal — in a team setup, pulse feeds "
-                "aggregate via `boost onboard`")
+                "aggregate via `boost onboard`", wrap=True)
         return 0
 
     users: dict[str, dict] = {}
@@ -738,5 +744,5 @@ def cmd_who(argv) -> int:
     out.table(board, headers=("USER", "EVENTS", "SKILLS", "INSTALLS", "LAST ACTIVE"))
     print()
     out.dim("based on the local journal — in a team setup, pulse feeds aggregate "
-            "via `boost onboard`")
+            "via `boost onboard`", wrap=True)
     return 0

{boost_skill_cli-1.2.20 → boost_skill_cli-1.2.22}/boost_cli/core/output.py

@@ -200,20 +200,38 @@ def gradient(text: str, stream=None) -> str:
     return "".join(out)
 
 
+def _wrap_lines(msg: str, lead: int) -> list[str]:
+    """Wrap `msg` for an emitter whose own prefix costs `lead` columns.
+
+    Returns at least one line so an emitter never silently prints nothing for a
+    message it was given; the emitter decides what its prefix and continuation
+    padding look like.
+    """
+    return wrap(msg, term_width() - lead) or [msg]
+
+
 def ok(msg: str) -> None:
     """Print msg as an indented success line with a green check mark."""
     print("  " + role("✓", "success") + " " + msg)
 
 
-def warn(msg: str, stream=None) -> None:
+def warn(msg: str, stream=None, wrap: bool = False) -> None:
     """Print msg as an indented `!` warning line, all in the warn role.
 
     ``stream`` exists for the commands that also speak JSON on stdout: a notice
     about *which corpus answered* has to survive `--json`, and the old choice
     was between corrupting the JSON and suppressing the notice entirely. Passing
     ``sys.stderr`` keeps both.
+
+    ``wrap`` is opt-in per call site rather than always-on, because not every
+    long line is prose: `pulse`'s `source=` paths and `fingerprint`'s hash are
+    data, and folding those destroys the information the line exists to carry.
+    Prose hints pass it; data lines do not.
     """
-    print("  " + role("!", "warn") + " " + role(msg, "warn"), file=stream)
+    body = _wrap_lines(msg, 4) if wrap else [msg]
+    for i, line in enumerate(body):
+        lead = "  " + role("!", "warn") + " " if i == 0 else "    "
+        print(lead + role(line, "warn"), file=stream)
 
 
 def err(msg: str, hint: str | None = None) -> None:
@@ -223,11 +241,17 @@ def err(msg: str, hint: str | None = None) -> None:
         print(c("  hint: " + hint, DIM), file=sys.stderr)
 
 
-def info(msg: str = "", stream=None) -> None:
+def info(msg: str = "", stream=None, wrap: bool = False) -> None:
     """Print msg indented two spaces; a blank line when msg is empty.
 
     ``stream`` as in :func:`warn` — so a hint can accompany a stderr notice.
+    ``wrap`` as in :func:`warn`, and it never turns the empty message into no
+    output at all: a caller printing a blank spacer still gets its blank line.
     """
+    if wrap and msg:
+        for line in _wrap_lines(msg, 2):
+            print("  " + line, file=stream)
+        return
     print("  " + msg if msg else "", file=stream)
 
 
@@ -252,9 +276,14 @@ def plain(text: object) -> str:
     return _CONTROL_RE.sub("", str(text))
 
 
-def dim(msg: str) -> None:
-    """Print msg in the muted role (dim when color is on)."""
-    print(role(msg, "muted"))
+def dim(msg: str, wrap: bool = False) -> None:
+    """Print msg in the muted role (dim when color is on).
+
+    ``wrap`` as in :func:`warn`. `dim` prints flush left, so the wrapped
+    continuations are flush left too — there is no marker to align under.
+    """
+    for line in (_wrap_lines(msg, 0) if wrap else [msg]):
+        print(role(line, "muted"))
 
 
 def heading(msg: str) -> None:
@@ -310,6 +339,80 @@ def visible_len(s: str) -> int:
     return len(_ANSI_RE.sub("", s))
 
 
+_CODE_SPAN_RE = re.compile(r"`[^`]*`")
+
+
+def _wrap_tokens(text: str) -> list[str]:
+    """Split text into wrap units, keeping each `code span` whole.
+
+    A backtick span is one token even though it contains spaces, because the
+    spans in boost's hints are shell commands the user is meant to select and
+    paste — `pip install 'boost-skill-cli[rag]'`. Everything outside a span is
+    split on whitespace, which collapses runs and newlines the way
+    :func:`truncate` does; the span itself is copied verbatim, so a command
+    that legitimately holds two spaces survives.
+
+    An unterminated backtick simply never matches, and its text wraps as
+    ordinary words. That is the right failure: a half-open span is a typo in
+    the message, not a reason to refuse to render it.
+    """
+    parts: list[str] = []
+    pos = 0
+    for m in _CODE_SPAN_RE.finditer(text):
+        parts.extend(text[pos:m.start()].split())
+        parts.append(m.group(0))
+        pos = m.end()
+    parts.extend(text[pos:].split())
+    return parts
+
+
+def wrap(text: str, width: int | None = None, indent: str = "") -> list[str]:
+    """Greedy word-wrap to `width` visible columns, never splitting a code span.
+
+    Returns one string per line: the first bare, the rest prefixed with
+    `indent`, and every one measured with :func:`visible_len` so a coloured
+    message is bounded by what the pane shows rather than by its byte count.
+    ``width`` defaults to the live terminal.
+
+    **A token wider than the line is emitted whole and overflows.** That is
+    deliberate and it is the reason this is not `textwrap.wrap(break_long_words
+    =True)`: the tokens that hit this case are the backticked commands, and a
+    command chopped at column 80 is worse than useless — the user pastes it and
+    it fails. One long line the terminal soft-wraps still yields the right text
+    on a copy.
+
+    Empty (or all-whitespace) text wraps to no lines at all, so a caller can
+    tell "nothing to say" from "one blank line".
+    """
+    width = term_width() if width is None else width
+    tokens = _wrap_tokens(text)
+    if not tokens:
+        return []
+    pad = visible_len(indent)
+    lines: list[str] = []
+    cur = ""
+    for tok in tokens:
+        # The first line spends the full width; every later one pays for the
+        # indent. No floor under the subtraction: a pane narrower than its own
+        # indent yields a limit no token can meet, and each token lands on its
+        # own line — which is the same answer a floor of 1 gives, because the
+        # fit test below is never satisfiable below 3 columns anyway.
+        limit = width if not lines else width - pad
+        if cur and visible_len(cur) + 1 + visible_len(tok) <= limit:
+            cur += " " + tok
+        else:
+            if cur:
+                lines.append(cur)
+            cur = tok
+    lines.append(cur)
+    return [lines[0]] + [indent + ln for ln in lines[1:]]
+
+
+#: Alias for callers that take a ``wrap`` keyword argument of their own, which
+#: would otherwise shadow the function inside their own body.
+wrap_text = wrap
+
+
 def panel(lines, title: str | None = None, hue: str = "cyan") -> str:
     """A rounded box around one or more lines, with an Aurora-tinted border and
     an optional title set into the top rule — the terminal echo of the web
@@ -506,11 +609,23 @@ def format_search_row(name: str, desc: str, kind: str, tap: str, frac: float,
     return row.rstrip()
 
 
-def kv(key: str, value: str, width: int = 14) -> None:
-    """Print an indented key/value line: dim key padded to width, then value."""
+def kv(key: str, value: str, width: int = 14, wrap: bool = False) -> None:
+    """Print an indented key/value line: dim key padded to width, then value.
+
+    ``wrap`` as in :func:`warn`, and the continuations align under the *value*
+    rather than the key — a value folded back to column 0 reads as a new row.
+    """
     # The str() is NOT redundant despite the annotation: callers pass raw ints
     # (e.g. `boost impact` prints files_touched), which would raise TypeError.
-    print("  " + c(key.ljust(width), DIM) + str(value))  # noqa: FURB123
+    text = str(value)  # noqa: FURB123
+    if not wrap:
+        print("  " + c(key.ljust(width), DIM) + text)
+        return
+    lead = 2 + width
+    lines = wrap_text(text, term_width() - lead) or [text]
+    print("  " + c(key.ljust(width), DIM) + lines[0])
+    for line in lines[1:]:
+        print(" " * lead + line)
 
 
 def _pad(cell: str, width: int) -> str:

{boost_skill_cli-1.2.20 → boost_skill_cli-1.2.22}/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.22}/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.22
 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.22}/boost_skill_cli.egg-info/SOURCES.txt

@@ -543,6 +543,7 @@ tests/functional/test_cli_discovery.py
 tests/functional/test_cli_hooks.py
 tests/functional/test_cli_info.py
 tests/functional/test_cli_intelligence.py
+tests/functional/test_cli_pane_width.py
 tests/functional/test_cli_pkg.py
 tests/functional/test_cli_quality.py
 tests/functional/test_cli_taps.py

{boost_skill_cli-1.2.20 → boost_skill_cli-1.2.22}/docs/eval-latest.json

@@ -1,7 +1,7 @@
 {
   "schema": 1,
-  "generated": "2026-08-18T06:55:00Z",
-  "commit": "3a28b3f",
+  "generated": "2026-08-25T06:59:06Z",
+  "commit": "1167bcd",
   "engine": "bm25",
   "corpus": {
     "entries": 57,

{boost_skill_cli-1.2.20 → boost_skill_cli-1.2.22}/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.22}/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>.