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

{boost_skill_cli-1.2.19 → 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.19 → boost_skill_cli-1.2.21}/PKG-INFO

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

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

{boost_skill_cli-1.2.19 → boost_skill_cli-1.2.21}/boost_cli/cli.py

@@ -155,20 +155,50 @@ _GROUP_HUES = ("cyan", "violet", "pink", "green", "yellow")
 
 
 def print_help() -> None:
-    print(out.gradient(PRODUCT) + " — Homebrew for AI coding skills"
-          + out.c("  (%s · v%s)" % (TAGLINE, __version__), out.DIM))
+    """The command index, fitted to the pane.
+
+    Every other screen in the CLI adapts — `search` drops the tap column and
+    truncates at 60 columns — while this one emitted a fixed 105-column banner
+    at every width and wrapped mid-word for anyone not running a wide
+    terminal. Names are never clipped, because the help's whole job is to be
+    an index you can copy a command out of; summaries are.
+    """
+    cols = out.term_width()
+
+    title_line = out.gradient(PRODUCT) + " — Homebrew for AI coding skills"
+    stamp = "%s · v%s" % (TAGLINE, __version__)
+    if out.visible_len(title_line) + out.visible_len(stamp) + 4 <= cols:
+        print(title_line + out.c("  (%s)" % stamp, out.DIM))
+    else:
+        print(title_line)
+        # The tagline is the first thing to go; the version never is, because
+        # it is what a bug report needs.
+        print(out.c(stamp if out.visible_len(stamp) <= cols
+                    else "v%s" % __version__, out.DIM))
     print()
-    print(out.c("Usage:", out.BOLD) + "  boost <command> [args]   "
-          + out.c("boost help <command> for details", out.DIM))
+
+    usage = out.c("Usage:", out.BOLD) + "  boost <command> [args]"
+    detail = out.c("boost help <command> for details", out.DIM)
+    if out.visible_len(usage) + out.visible_len(detail) + 3 <= cols:
+        print(usage + "   " + detail)
+    else:
+        print(usage)
+        print("  " + detail)
+
     width = max(len(n) for n, _, _, _ in COMMANDS)
     for idx, (gkey, (_icon, title, desc)) in enumerate(GROUPS.items()):
         cmds = [(n, s) for n, g, _m, s in COMMANDS if g == gkey]
         bullet = out.aurora("●", _GROUP_HUES[idx % len(_GROUP_HUES)])
         print()
-        print(bullet + " " + out.c(title, out.BOLD)
-              + out.c("  — %s" % desc, out.DIM))
+        head = bullet + " " + out.c(title, out.BOLD)
+        room = cols - len(title) - 6  # "● " + title + "  — "
+        if room >= 8:
+            print(head + out.c("  — %s" % out.truncate(desc, room), out.DIM))
+        else:
+            print(head)
         for n, s in cmds:
-            print("  " + out.c(n.ljust(width + 2), out.CYAN) + s)
+            print("  " + out.c(n.ljust(width + 2), out.CYAN)
+                  + out.truncate(s, max(0, cols - width - 4)))
     print()
     print(out.c("%d commands · %d groups" % (len(COMMANDS), len(GROUPS)), out.DIM))
 

{boost_skill_cli-1.2.19 → 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.19 → boost_skill_cli-1.2.21}/boost_cli/commands/team.py

@@ -69,7 +69,7 @@ def cmd_cohort(argv) -> int:
     p = cliparse.parser(
         prog="boost cohort",
         description="Controlled skill rollouts & team A/B testing",
-        epilog="Membership is a deterministic hash of user+cohort, so a 50%% "
+        epilog="Membership is a deterministic hash of user+cohort, so a 50% "
                "rollout lands on the same half of the team every time. "
                "This machine evaluates its own membership locally.")
     p.add_argument("action", nargs="?", default="list",
@@ -177,7 +177,7 @@ def cmd_cohort(argv) -> int:
         return 0
     out.table(rows, headers=("COHORT", "SKILLS", "ROLLOUT", "YOU"))
     print()
-    out.dim("membership = sha256(user:cohort) %% 100 < rollout · apply with `boost cohort apply`")
+    out.dim("membership = sha256(user:cohort) % 100 < rollout · apply with `boost cohort apply`")
     return 0
 
 

{boost_skill_cli-1.2.19 → boost_skill_cli-1.2.21}/boost_cli/core/output.py

@@ -317,9 +317,20 @@ def panel(lines, title: str | None = None, hue: str = "cyan") -> str:
     """
     if isinstance(lines, str):
         lines = [lines]
+    # The border costs four columns — "\u2502 " on the left, " \u2502" on the right —
+    # so that is what the content may not exceed. Without this the box sized
+    # itself to its content and sailed past the pane: `boost count` drew 108
+    # columns into an 80-column terminal, and a box whose border wraps is the
+    # worst-looking overflow the CLI has, because the shape itself breaks.
+    room = term_width() - 4
+    if title:
+        title = _clip_visible(title, room - 2)
+    lines = [_clip_visible(x, room) for x in lines]
     widths = [visible_len(x) for x in lines]
     tw = visible_len(title) if title else 0
-    inner = max([*widths, tw + 2])  # a titled rule needs a space each side
+    # A titled rule needs a space each side, hence the +2 / -2. Clipping above
+    # already bounds every width by `room`, so no second clamp is needed here.
+    inner = max([*widths, tw + 2])
 
     def b(s: str) -> str:
         return aurora(s, hue)

{boost_skill_cli-1.2.19 → 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.19 → 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.19
+Version: 1.2.21
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.2.19 → boost_skill_cli-1.2.21}/boost_skill_cli.egg-info/SOURCES.txt

@@ -191,6 +191,7 @@ docs/roadmap/items/ambiguous-tap-short-name-resolution.md
 docs/roadmap/items/atomic-corruption-safe-lock-file-writes.md
 docs/roadmap/items/atomic-skill-install-temp-dir-swap.md
 docs/roadmap/items/autonomous-ship-workflow-and-isolated-worktree.md
+docs/roadmap/items/bm25-has-no-stemming.md
 docs/roadmap/items/bm25-index-is-one-json-blob.md
 docs/roadmap/items/bmad-autopilot-one-command-persona-routing.md
 docs/roadmap/items/boost-first-carried-the-losing-trigger.md
@@ -211,6 +212,7 @@ docs/roadmap/items/ci-job-timeout-minutes.md
 docs/roadmap/items/ci-summary-step-fails-itself.md
 docs/roadmap/items/ci-time-is-now-runner-queueing.md
 docs/roadmap/items/clean-env-install-smoke-pip-and-pipx.md
+docs/roadmap/items/cli-output-ignored-the-terminal.md
 docs/roadmap/items/code-scanning-rule-can-be-restored.md
 docs/roadmap/items/codeql-job-rename-stranded-merge-protection.md
 docs/roadmap/items/cold-search-reads-the-whole-catalogue.md
@@ -296,6 +298,7 @@ docs/roadmap/items/localize-the-stored-bm25-snippet.md
 docs/roadmap/items/lock-invariant-cannot-parse-extras-pins.md
 docs/roadmap/items/lockfile-enforcement-and-commit-pinning.md
 docs/roadmap/items/log-timestamps-mislabeled-utc.md
+docs/roadmap/items/long-hints-overflow-narrow-panes.md
 docs/roadmap/items/lowest-version-resolution-uv-resolution-lowest-d.md
 docs/roadmap/items/main-has-no-branch-protection.md
 docs/roadmap/items/main-ruleset-ref-pattern-has-literal-quotes.md

{boost_skill_cli-1.2.19 → 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.21/docs/roadmap/items/bm25-has-no-stemming.md

@@ -0,0 +1,68 @@
+---
+id: bm25-has-no-stemming
+board: code
+section: pipeline
+status: inflight
+category: Search · Retrieval
+complexity: M
+impact: High
+wow: 4
+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: loop/bm25-stem-fallback
+pr:
+title: <code>boost search brainstorm</code> finds nothing, and <code>brainstorming</code> finds it
+---
+<b>The symptom, in two commands against the same five-skill tap.</b>
+<code>boost search brainstorming</code> returns the skill.
+<code>boost search brainstorm</code> returns <b>zero</b> matches and sends the user to
+<code>boost discover</code> to search all of GitHub for something already sitting in their
+catalogue. <code>boost chat "what helps me brainstorm"</code> has the same hole and answers with
+two unrelated skills. <code>core/rag.tokenize</code> lowercases, splits on non-alphanumerics and
+drops a small stopword list — there is no stemming and no prefix fallback, so
+<code>brainstorm</code> and <code>brainstorming</code> are simply different terms.
+
+<b>Measured on the 461 tap caches on this machine: 29,607 distinct item names, 9,739 distinct
+name tokens.</b> <b>4,663 of those names (15.7%)</b> carry a token whose stem finds nothing —
+counting only stems that appear at least five times elsewhere in the corpus, so each is
+demonstrably a word people type rather than an artefact of naive suffix stripping. The worst are
+not exotic: <code>pattern</code> misses <b>474</b> names ending <code>-patterns</code>,
+<code>skill</code> misses <b>252</b> ending <code>-skills</code>, <code>implement</code> misses
+161, <code>event</code> 115, <code>error</code> 112, <code>webhook</code> 109,
+<code>agent</code> 83, <code>market</code> 81 named <code>-marketing</code>. A user searching
+this catalogue for <code>skill</code> cannot reach a quarter of a thousand items named for it.
+
+<b>It is invisible from a developer install, which is why it survived.</b> This machine has the
+<code>[rag]</code> extra and a built dense store, so search reports <code>hybrid RRF (BM25 +
+dense)</code> and the embeddings absorb the morphology: <code>webhook</code> returns 51 matches
+and <code>webhooks</code> returns 47. The gap is only visible on the always-on, zero-dependency
+BM25 path — which is what every user without the extra runs, what
+<code>search</code> prints <code>semantic search is off</code> for, and what the required
+<code>eval</code> gate floors. There is no <code>--engine</code> flag, so a maintainer cannot
+easily reproduce a plain user's result.
+
+<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.21/docs/roadmap/items/cli-output-ignored-the-terminal.md

@@ -0,0 +1,56 @@
+---
+id: cli-output-ignored-the-terminal
+board: code
+section: dx
+status: inflight
+category: CLI · Output
+complexity: S
+impact: Med
+wow: 3
+note: an 80-command sweep found a box that drew wider than the pane, a help screen that never measured it, and a literal %% on screen
+order: 125
+owner: loop/cli-output-defects
+pr: 552
+title: The box drew 108 columns into an 80-column pane, and <code>--help</code> never asked how wide the pane was
+---
+<b>Every one of the 80 commands was run, not just read.</b> All 80 answered
+<code>--help</code> with exit 0 and no traceback; ~73 were then driven for their real effect
+against a disposable <code>HOME</code> — install, link, quarantine, focus, snapshot, replay,
+cohort, hooks and the rest, checking the filesystem after each rather than trusting the success
+line. <code>boost focus tdd-workflow</code> was confirmed by listing
+<code>~/.claude/skills</code> and finding the other two skills genuinely unlinked with the
+canonical store intact, and <code>focus --clear</code> by finding all three back. Seven commands
+could not run here and are recorded as blocked rather than passed: <code>serve</code> (the
+sandbox denies <code>socket.bind</code>), <code>discover</code> and <code>index</code> (no
+<code>gh</code> auth), <code>run</code> live (no Agents SDK — <code>--print</code> was verified
+instead), plus the interactive halves of <code>browse</code>, <code>chat</code> and
+<code>edit</code>, each of which degraded with a correct hint.
+
+<b>A literal <code>%%</code> was reaching the terminal.</b>
+<code>boost cohort</code> printed <code>sha256(user:cohort) %% 100 &lt; rollout</code> and its
+<code>--help</code> epilog offered <code>a 50%% rollout</code>. Both strings carry printf
+escaping and neither is ever <code>%</code>-formatted, so the escape survived to the screen. The
+existing test asserted <code>"membership = sha256(user:cohort)" in r.out</code> — it stops one
+character short of the defect, which is exactly how it survived. Four other <code>%%</code> in
+the same file are correct: they sit inside real <code>%</code>-format calls, including the
+<code>Exec=%s %%u</code> that a <code>.desktop</code> file requires.
+
+<b><code>panel()</code> sized itself to its content and never asked the terminal.</b> Measured:
+<code>boost count</code> drew <b>108 columns into an 80-column pane</b>. A box is the worst
+thing to overflow, because the border wraps and the shape itself breaks. It now clamps to
+<code>term_width() - 4</code> — the four columns the border costs — and clips over-long content,
+so every row stays the same width at any pane size.
+
+<b>The help screen was the one screen that never measured the pane.</b>
+<code>search</code> already adapts, dropping the tap column and truncating at 60 columns —
+<code>term_width()</code> existed and <code>discovery.py</code> was its only caller. Meanwhile
+<code>boost --help</code>, the first thing a new user sees, emitted a fixed <b>102-column</b>
+banner at every width. It now fits exactly at 60, 80 and 100. Command <em>names</em> are never
+clipped, because the help's whole job is to be an index you can copy a command out of; summaries
+and the tagline are. The version never is — it is what a bug report needs.
+
+<b>Two findings were measured and deliberately left for their own items.</b> Eleven commands
+still overflow 80 columns, but the remainder are prose hints, and the worst of them is one shared
+string that six test files and a BDD feature pin by substring — wrapping it is a cross-cutting
+output change, not a rider on this one. See <code>long-hints-overflow-narrow-panes</code> and
+<code>bm25-has-no-stemming</code>.

boost_skill_cli-1.2.21/docs/roadmap/items/long-hints-overflow-narrow-panes.md

@@ -0,0 +1,38 @@
+---
+id: long-hints-overflow-narrow-panes
+board: code
+section: dx
+status: next
+category: CLI · Output
+complexity: M
+impact: Low
+wow: 2
+note: 11 commands still emit prose hints past 80 columns; the worst is one string pinned by six test files
+order: 126
+owner:
+pr:
+title: The hints still run past the pane, and the worst one is pinned by six test files
+---
+<b>Measured, at <code>COLUMNS=80</code>, over 46 commands.</b> After the box and the help screen
+were fitted, <b>11</b> still emit a line past 80 columns. Ranked:
+<code>doctor</code>'s semantic-search hint at <b>127</b>; the AI-fallback notice at <b>101</b>,
+which is one shared string surfacing in <code>explain</code>, <code>impact</code> and
+<code>simulate</code>; <code>protocol</code>'s URL forms at 100; <code>changelog</code>'s
+unshallow hint at 93; <code>who</code>'s footer at 87; <code>search</code>'s extra hint at 82;
+<code>replay</code>'s footer at 81.
+
+<b>Two of the eleven must be left alone.</b> <code>pulse</code>'s <code>source=</code> paths and
+<code>fingerprint</code>'s hash are data, not chrome — clipping them destroys the information the
+line exists to carry. So a blanket "no line exceeds <code>term_width()</code>" assertion is the
+wrong gate: it would false-positive on exactly the lines that should be long. Pin the composed
+sites individually.
+
+<b>Why this is not a quick wrap.</b> The 101-column offender contains
+<code>using the heuristic fallback</code>, which is asserted by <b>six</b> test files plus
+<code>tests/bdd/features/explain.feature</code>. Wrapping inserts a newline mid-sentence and
+breaks every one of them; and under pytest <code>term_width()</code> falls back to 80, so the
+wrap fires in the suite rather than only on a narrow terminal. The change is a
+<code>wrap()</code> helper in <code>core/output.py</code> — mutation-gated, so boundary-width
+tests, not coverage — plus re-pinning those assertions. Shortening the strings instead is a
+smaller diff but a voice decision, and the substring pinned by the tests would have to survive
+either way.

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

@@ -133,7 +133,7 @@
       <div class="stat"><b>16</b><span>Shipped</span></div>
       <div class="stat"><b>1</b><span>Next up</span></div>
       <div class="stat"><b>7</b><span>Planned</span></div>
-      <div class="stat"><b>264</b><span>Loop finds</span></div>
+      <div class="stat"><b>267</b><span>Loop finds</span></div>
       <!-- /ROADMAP:stats -->
     </div>
   </section>
@@ -7053,6 +7053,70 @@ state where that line is the advice.</p>
           <span class="m">0.94 s cold search at 71.6k entries — ~0.5 s spent materialising data the top hits never use</span>
         </div>
       </article>
+
+      <article class="cap rcard" id="bm25-has-no-stemming">
+        <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.
+<code>boost search brainstorm</code> returns <b>zero</b> matches and sends the user to
+<code>boost discover</code> to search all of GitHub for something already sitting in their
+catalogue. <code>boost chat "what helps me brainstorm"</code> has the same hole and answers with
+two unrelated skills. <code>core/rag.tokenize</code> lowercases, splits on non-alphanumerics and
+drops a small stopword list — there is no stemming and no prefix fallback, so
+<code>brainstorm</code> and <code>brainstorming</code> are simply different terms.
+
+<b>Measured on the 461 tap caches on this machine: 29,607 distinct item names, 9,739 distinct
+name tokens.</b> <b>4,663 of those names (15.7%)</b> carry a token whose stem finds nothing —
+counting only stems that appear at least five times elsewhere in the corpus, so each is
+demonstrably a word people type rather than an artefact of naive suffix stripping. The worst are
+not exotic: <code>pattern</code> misses <b>474</b> names ending <code>-patterns</code>,
+<code>skill</code> misses <b>252</b> ending <code>-skills</code>, <code>implement</code> misses
+161, <code>event</code> 115, <code>error</code> 112, <code>webhook</code> 109,
+<code>agent</code> 83, <code>market</code> 81 named <code>-marketing</code>. A user searching
+this catalogue for <code>skill</code> cannot reach a quarter of a thousand items named for it.
+
+<b>It is invisible from a developer install, which is why it survived.</b> This machine has the
+<code>[rag]</code> extra and a built dense store, so search reports <code>hybrid RRF (BM25 +
+dense)</code> and the embeddings absorb the morphology: <code>webhook</code> returns 51 matches
+and <code>webhooks</code> returns 47. The gap is only visible on the always-on, zero-dependency
+BM25 path — which is what every user without the extra runs, what
+<code>search</code> prints <code>semantic search is off</code> for, and what the required
+<code>eval</code> gate floors. There is no <code>--engine</code> flag, so a maintainer cannot
+easily reproduce a plain user's result.
+
+<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">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 -->
 
     </div>
@@ -9009,6 +9073,92 @@ the same search from 0.94 s to 0.49 s.</p>
           <span class="m">MCP boost_search measured 11.7-17 s per call — every call, even a repeat of the last one</span>
         </div>
       </article>
+
+      <article class="cap rcard" id="cli-output-ignored-the-terminal">
+        <div class="head"><span class="pill inflight">In flight</span><span class="cat">CLI · Output</span></div>
+        <h3>The box drew 108 columns into an 80-column pane, and <code>--help</code> never asked how wide the pane was</h3>
+        <p><b>Every one of the 80 commands was run, not just read.</b> All 80 answered
+<code>--help</code> with exit 0 and no traceback; ~73 were then driven for their real effect
+against a disposable <code>HOME</code> — install, link, quarantine, focus, snapshot, replay,
+cohort, hooks and the rest, checking the filesystem after each rather than trusting the success
+line. <code>boost focus tdd-workflow</code> was confirmed by listing
+<code>~/.claude/skills</code> and finding the other two skills genuinely unlinked with the
+canonical store intact, and <code>focus --clear</code> by finding all three back. Seven commands
+could not run here and are recorded as blocked rather than passed: <code>serve</code> (the
+sandbox denies <code>socket.bind</code>), <code>discover</code> and <code>index</code> (no
+<code>gh</code> auth), <code>run</code> live (no Agents SDK — <code>--print</code> was verified
+instead), plus the interactive halves of <code>browse</code>, <code>chat</code> and
+<code>edit</code>, each of which degraded with a correct hint.
+
+<b>A literal <code>%%</code> was reaching the terminal.</b>
+<code>boost cohort</code> printed <code>sha256(user:cohort) %% 100 &lt; rollout</code> and its
+<code>--help</code> epilog offered <code>a 50%% rollout</code>. Both strings carry printf
+escaping and neither is ever <code>%</code>-formatted, so the escape survived to the screen. The
+existing test asserted <code>"membership = sha256(user:cohort)" in r.out</code> — it stops one
+character short of the defect, which is exactly how it survived. Four other <code>%%</code> in
+the same file are correct: they sit inside real <code>%</code>-format calls, including the
+<code>Exec=%s %%u</code> that a <code>.desktop</code> file requires.
+
+<b><code>panel()</code> sized itself to its content and never asked the terminal.</b> Measured:
+<code>boost count</code> drew <b>108 columns into an 80-column pane</b>. A box is the worst
+thing to overflow, because the border wraps and the shape itself breaks. It now clamps to
+<code>term_width() - 4</code> — the four columns the border costs — and clips over-long content,
+so every row stays the same width at any pane size.
+
+<b>The help screen was the one screen that never measured the pane.</b>
+<code>search</code> already adapts, dropping the tap column and truncating at 60 columns —
+<code>term_width()</code> existed and <code>discovery.py</code> was its only caller. Meanwhile
+<code>boost --help</code>, the first thing a new user sees, emitted a fixed <b>102-column</b>
+banner at every width. It now fits exactly at 60, 80 and 100. Command <em>names</em> are never
+clipped, because the help's whole job is to be an index you can copy a command out of; summaries
+and the tagline are. The version never is — it is what a bug report needs.
+
+<b>Two findings were measured and deliberately left for their own items.</b> Eleven commands
+still overflow 80 columns, but the remainder are prose hints, and the worst of them is one shared
+string that six test files and a BDD feature pin by substring — wrapping it is a cross-cutting
+output change, not a rider on this one. See <code>long-hints-overflow-narrow-panes</code> and
+<code>bm25-has-no-stemming</code>.</p>
+        <div class="meta">
+          <span class="m">Complexity <b>S</b></span>
+          <span class="m">Impact <b>Med</b></span>
+          <span class="m">Wow <b class="wow">★★★</b></span>
+          <span class="m">an 80-command sweep found a box that drew wider than the pane, a help screen that never measured it, and a literal %% on screen</span>
+        </div>
+      </article>
+
+      <article class="cap rcard" id="long-hints-overflow-narrow-panes">
+        <div class="head"><span class="pill next">Next</span><span class="cat">CLI · Output</span></div>
+        <h3>The hints still run past the pane, and the worst one is pinned by six test files</h3>
+        <p><b>Measured, at <code>COLUMNS=80</code>, over 46 commands.</b> After the box and the help screen
+were fitted, <b>11</b> still emit a line past 80 columns. Ranked:
+<code>doctor</code>'s semantic-search hint at <b>127</b>; the AI-fallback notice at <b>101</b>,
+which is one shared string surfacing in <code>explain</code>, <code>impact</code> and
+<code>simulate</code>; <code>protocol</code>'s URL forms at 100; <code>changelog</code>'s
+unshallow hint at 93; <code>who</code>'s footer at 87; <code>search</code>'s extra hint at 82;
+<code>replay</code>'s footer at 81.
+
+<b>Two of the eleven must be left alone.</b> <code>pulse</code>'s <code>source=</code> paths and
+<code>fingerprint</code>'s hash are data, not chrome — clipping them destroys the information the
+line exists to carry. So a blanket "no line exceeds <code>term_width()</code>" assertion is the
+wrong gate: it would false-positive on exactly the lines that should be long. Pin the composed
+sites individually.
+
+<b>Why this is not a quick wrap.</b> The 101-column offender contains
+<code>using the heuristic fallback</code>, which is asserted by <b>six</b> test files plus
+<code>tests/bdd/features/explain.feature</code>. Wrapping inserts a newline mid-sentence and
+breaks every one of them; and under pytest <code>term_width()</code> falls back to 80, so the
+wrap fires in the suite rather than only on a narrow terminal. The change is a
+<code>wrap()</code> helper in <code>core/output.py</code> — mutation-gated, so boundary-width
+tests, not coverage — plus re-pinning those assertions. Shortening the strings instead is a
+smaller diff but a voice decision, and the substring pinned by the tests would have to survive
+either way.</p>
+        <div class="meta">
+          <span class="m">Complexity <b>M</b></span>
+          <span class="m">Impact <b>Low</b></span>
+          <span class="m">Wow <b class="wow">★★</b></span>
+          <span class="m">11 commands still emit prose hints past 80 columns; the worst is one string pinned by six test files</span>
+        </div>
+      </article>
       <!-- /ROADMAP:cards -->
 
     </div>