boost-skill-cli 1.0.421__tar.gz → 1.0.423__tar.gz

{boost_skill_cli-1.0.421/boost_skill_cli.egg-info → boost_skill_cli-1.0.423}/PKG-INFO

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

{boost_skill_cli-1.0.421 → boost_skill_cli-1.0.423}/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.421'
-__version_tuple__ = version_tuple = (1, 0, 421)
+__version__ = version = '1.0.423'
+__version_tuple__ = version_tuple = (1, 0, 423)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.421 → boost_skill_cli-1.0.423}/boost_cli/commands/configuration.py

@@ -11,12 +11,14 @@ import subprocess
 import sys
 import time
 from datetime import datetime, timedelta
+from itertools import chain
 from pathlib import Path
 
 from .. import __version__, cliparse
 from ..core import (
     agents,
     bootstrap,
+    builtin,
     catalog,
     complete,
     config,
@@ -32,6 +34,7 @@ from ..core import (
     policy,
     rag,
     registry,
+    rules,
     selfupdate,
     serve,
     store,
@@ -862,6 +865,15 @@ def _ranking_note(ranker: str) -> str:
             "enable it.)" % ranker)
 
 
+# The label for the pre-RAG fallback below. `_ranking_note` needs a name for
+# whatever produced the order, and this branch is neither engine it knows
+# about: `catalog.search` scores names and descriptions from the tap caches
+# because no index exists yet. `rag.rerank`'s own comment is the rule being
+# followed — naming a specific wrong engine is worse than naming none, since
+# the label is the only signal about which retrieval answered.
+FRONTMATTER_RANKER = "frontmatter match, no index built yet"
+
+
 def _tool_search(args: dict):
     query = str(args.get("query", ""))
     rag.ensure()  # build the full-content index on first use (BM25 by default)
@@ -882,27 +894,54 @@ def _tool_search(args: dict):
     # miss apart from a machine that has never been tapped — the two used to
     # share one sentence, and the fresh-install case is the one an agent reads
     # first and learns the most from.
-    tapped = len(registry.list_taps())
+    tapped = builtin.configured_tap_count()
+    # The two retrieval branches converge on ONE render. They used to diverge:
+    # the RAG branch appended `_ranking_note`, and the frontmatter fallback
+    # appended nothing at all — so an agent on that path got ten lines with the
+    # exact shape of a reranked ten, and no way to tell. Both now carry the
+    # kind marker, the [installed] marker, the overlap note and a ranking note.
     if rag_result is not None:  # full-content index is built
         hits, ranker = rag_result
-        if not hits:
-            return mcp.no_results(query, tapped=tapped), False
-        lines = [mcp.hit_line(h["entry"]) for h in hits]
-        lines.append(_ranking_note(ranker))
-        return "\n".join(lines), False
-    # no index yet -> keep today's frontmatter search so nothing regresses
-    scored = catalog.search(query)[:10]
-    if not scored:
+        entries = [h["entry"] for h in hits]
+    else:  # no index yet -> today's frontmatter search, so nothing regresses
+        entries = [e for e, _score in catalog.search(query)[:10]]
+        ranker = FRONTMATTER_RANKER
+    if not entries:
+        # mcp.no_results owns the empty reply on both paths, including the
+        # untapped-machine branch that must not read as a genuine miss.
         return mcp.no_results(query, tapped=tapped), False
-    return "\n".join(mcp.hit_line(e) for e, _score in scored), False
+    # Name-keyed, the same test `lockfile.find_any` and `store.install` apply —
+    # those are the tools this marker is advising about. mcp.hit_line's
+    # docstring records why the imprecision is disclosed rather than removed,
+    # and mcp.overlap_note is where the agent is told.
+    #
+    # One lock read for the whole reply, not one per hit: `find_any` re-reads
+    # and re-parses the file on every call, so the obvious `find_any(name)`
+    # inside this comprehension is ten reads of the same bytes. The union of
+    # the three sections is that same predicate, once.
+    installed_names = set(chain.from_iterable(lockfile.all_installed().values()))
+    marks = [e.get("name", "") in installed_names for e in entries]
+    lines = [mcp.hit_line(e, installed=m)
+             for e, m in zip(entries, marks, strict=True)]
+    note = mcp.overlap_note(sum(marks), len(entries))
+    if note:
+        lines.append(note)
+    lines.append(_ranking_note(ranker))
+    return "\n".join(lines), False
 
 
 def _tool_list(args: dict):
     # All three lock sections: "no skills installed" while `boost list` shows
     # a rule is the exact disagreement this surface must not have.
     everything = lockfile.all_installed()
+    # The footer reads the lock file and the tap list and nothing else — no
+    # catalog scan — so boost_list stays the instant, threshold-free tool that
+    # INSTRUCTIONS and its own description both promise. It lands in the empty
+    # state too: a machine with nothing installed is exactly where "what do I
+    # have" is least useful on its own.
+    footer = mcp.coverage_line(everything, tapped=builtin.configured_tap_count())
     if not any(everything.values()):
-        return "nothing installed", False
+        return "nothing installed\n" + footer, False
     lines = []
     for kind, section in everything.items():
         for n, e in sorted(section.items()):
@@ -910,6 +949,7 @@ def _tool_list(args: dict):
                          % (n, e.get("version", "?"), e.get("tap", "?"),
                             "" if kind == "skill" else " [%s]" % kind,
                             " [pinned]" if e.get("pinned") else ""))
+    lines.append(footer)
     return "\n".join(lines), False
 
 
@@ -991,7 +1031,13 @@ def _tool_doctor(args: dict):
              # "items", not "skills": the default taps now carry rules and
              # workflows too, so counting all of them as skills overstates one
              # kind and hides the other two in the same breath.
-             "taps: %d (%d items available)" % (len(taps), len(catalog.all_entries()))]
+             #
+             # Counted rather than measured off a list. `len(all_entries())`
+             # concatenated every tap's cache — 71,655 entries on a real
+             # install — to produce this one integer; `kind_counts` does the
+             # same reads without the accumulation.
+             "taps: %d (%d items available)"
+             % (len(taps), sum(catalog.kind_counts().values()))]
     for key, vals in plan.items():
         if vals:
             lines.append("%s: %s" % (key, ", ".join(str(v) for v in vals)))
@@ -1080,7 +1126,21 @@ REGISTRY.register(
     "locked in for everything after it: a new project or subsystem, an "
     "architecture decision, environment and tooling config, a linter or "
     "formatter, tests, CI. Also before writing a skill, subagent, "
-    "slash-command or rule from scratch. Read-only where it counts: it "
+    "slash-command or rule from scratch. "
+    # The defeater, sitting against the trigger list it defends rather than in
+    # a paragraph of its own. A Gemini CLI session paraphrased that list back
+    # — "a new project or subsystem, an architecture decision, environment and
+    # tooling config" — and had still skipped the call, because two
+    # pre-installed skills had already activated. The trigger fired and lost to
+    # a predicate over the model's own context that boost had never written
+    # down. It is a description, not a denial: an agent told "an active skill
+    # is never enough" has been handed a standing order to search, which is the
+    # capture the skip list and the stated cost exist to prevent.
+    "What is already loaded is a different question: "
+    "a skill that activated here was installed before this request existed, "
+    "matched on its own description, and is one kind of three. Hits you "
+    "already have come back marked [installed], so the reply keeps the two "
+    "apart. Read-only where it counts: it "
     "installs nothing and touches nothing you are working on, though the first "
     "search builds a local index under ~/.boost. A hit commits you to nothing "
     "either: take what fits, discard the rest, the task stays yours. It costs "
@@ -1103,7 +1163,11 @@ REGISTRY.register(
     "The skills, rules and workflows already installed on this machine and "
     "usable this second — capability you own and may not know you own. "
     "Returns one line each: name, version, tap, a [rule] or [workflow] marker "
-    "where it is not a skill, and [pinned] where the version is held. "
+    "where it is not a skill, and [pinned] where the version is held, then a "
+    "closing count per kind. That count is the other half of the answer: it is "
+    "what this machine holds, not what exists, and a kind sitting at zero is a "
+    "kind nothing here could have loaded. boost_search is what reads the "
+    "registries themselves. "
     "Read-only, instant, installs nothing — so unlike boost_search there is "
     "no threshold worth applying: call it whenever you are about to plan "
     "something. Planning from memory while "
@@ -1250,6 +1314,78 @@ def _seed_catalog_for_mcp(force: bool) -> None:
         out.warn(res.summary())
 
 
+#: Escape hatch, same shape as BOOST_NO_MCP_OFFER and BOOST_NO_SEED. It is
+#: checked BEFORE `out.confirm`, which is load-bearing: confirm returns True
+#: under BOOST_ASSUME_YES or a bare `--yes` anywhere in argv, and the test
+#: fixtures set BOOST_ASSUME_YES=1 — so without this guard every existing
+#: `boost mcp register` test, and every provisioning script, would silently
+#: write a standing block into a real CLAUDE.md.
+NO_RULE_ENV = "BOOST_NO_RULE"
+
+
+def _offer_boost_first(hosts: list[str]) -> None:
+    """Offer to install boost's own rule into the agent's standing instructions.
+
+    This is the most invasive thing boost can propose, and the only text it
+    asks to put in a file the user reads every session, in every project — so
+    the consent has to be real rather than procedural. The body is printed in
+    full BEFORE the question, the target paths are named, the answer defaults
+    to NO, and the reversal command is shown whether or not they accept.
+
+    Why it exists at all: Gemini never delivers MCP server `instructions` in
+    interactive mode, and in an untrusted folder — which a brand-new project
+    directory is by default — it does not start the server, so boost has no
+    tools there either. `~/.gemini/GEMINI.md` is loaded unconditionally and is
+    the only boost surface that survives both. Declining is a perfectly good
+    answer; the tool descriptions still carry the trigger on every host that
+    delivers them.
+
+    Non-fatal by construction. The user asked to register an MCP server; a
+    failure to materialise an optional rule must never turn that into an
+    error, so everything below degrades to a warning.
+    """
+    from ..core import builtin
+
+    if os.environ.get(NO_RULE_ENV):
+        return
+    # Scoped to hosts where boost actually registered a server. Offering it for
+    # an agent with no boost tools would install standing text naming
+    # `boost_search` to an agent that does not have it.
+    if not hosts or not builtin.rule_is_available():
+        return
+    if lockfile.get_rule(builtin.BUILTIN_RULES[0]):
+        return                      # already installed; do not re-ask
+    body = (builtin.source_dir() / (builtin.BUILTIN_RULES[0] + ".mdc"))
+    targets = [str(rules.rule_target(agent, skills_dir,
+                                     builtin.BUILTIN_RULES[0])[1])
+               for agent, skills_dir in agents.enabled_agents().items()
+               if agent in {builtin.AGENT_FOR_HOST.get(h) for h in hosts}]
+    if not targets:
+        return
+    out.info("")
+    out.info("boost can also add its own rule, `%s`, to your agents' standing "
+             "instructions:" % builtin.BUILTIN_RULES[0])
+    for target in targets:
+        out.info("  %s" % target)
+    out.info("")
+    for line in body.read_text(encoding="utf-8").splitlines():
+        out.info("  | %s" % line)
+    out.info("")
+    if not out.confirm("Install it?", default=False):
+        out.info("Not installed. `boost install %s` any time."
+                 % builtin.BUILTIN_RULES[0])
+        return
+    try:
+        builtin.ensure_tap()
+        catalog.rebuild_tap(registry.get(builtin.BUILTIN_TAP))
+        store.install(catalog.resolve_one(builtin.BUILTIN_RULES[0]))
+    except (BoostError, OSError) as exc:
+        out.warn("could not install %s: %s" % (builtin.BUILTIN_RULES[0], exc))
+        return
+    out.ok("installed %s — remove it with `boost uninstall %s`"
+           % (builtin.BUILTIN_RULES[0], builtin.BUILTIN_RULES[0]))
+
+
 def cmd_mcp(argv) -> int:
     """boost mcp [register|unregister] [--host H] [--stdio] [--seed|--no-seed]"""
     p = cliparse.parser(
@@ -1324,6 +1460,8 @@ def cmd_mcp(argv) -> int:
                 out.info(" ".join(mcphost.argv(host, args.action, shim)))
         journal.log("mcp", args.action, hosts="")
         return 0
+    if args.action == "register":
+        _offer_boost_first(done)
     journal.log("mcp", args.action, hosts=",".join(done))
     return 0
 

boost_skill_cli-1.0.423/boost_cli/core/builtin.py

@@ -0,0 +1,114 @@
+"""The one tap boost ships itself, and the rule inside it.
+
+boost's whole product is asking a user to accept standing text written by
+strangers, under ``boost install`` and reversible with ``boost uninstall``. Its
+OWN standing text has to be the same kind of thing, subject to the same
+commands — a privileged block that ``boost list`` cannot see and
+``boost uninstall`` cannot remove is exactly the asymmetry a user is entitled
+to resent. So ``boost-first`` is not a special case bolted onto the register
+path: it is an ordinary rule, in an ordinary tap, that happens to arrive with
+the wheel instead of over the network.
+
+**The tap directory is under ``~/.boost/repos/`` and never inside the wheel.**
+That is not an implementation detail, it is the whole safety argument. A
+``Tap`` whose ``path`` pointed at package data would sit one ``boost untap``
+away from :func:`registry.remove`, which ends in ``util.rmtree(tap.path)`` —
+deleting part of the user's installed package. Here the worst case is that a
+recreatable directory goes away and :func:`ensure_tap` rebuilds it.
+
+The shipped files are therefore *copied out* of the wheel on first use, and the
+copy is what everything else — catalog scan, install, lock file, uninstall —
+sees. Nothing in ``core/`` needs to know this tap is different.
+"""
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from . import config, paths, registry
+
+#: The tap name. Contains a ``/`` like any other, so ``Tap.safe_name`` maps it
+#: to ``boost__builtin`` under ``~/.boost/repos/``.
+BUILTIN_TAP = "boost/builtin"
+
+#: A sentinel URL rather than a real one. ``boost update`` must not try to
+#: fetch this tap: its source of truth is the installed wheel, so it refreshes
+#: when boost itself does. The scheme is deliberately not ``https`` so any code
+#: that hands it to git fails loudly instead of reaching the network.
+BUILTIN_URL = "builtin:boost"
+
+#: The rule boost authors. One entry today; the list is what makes adding a
+#: second a data change rather than a code change.
+BUILTIN_RULES = ("boost-first",)
+
+#: MCP host id -> boost agent id. The two vocabularies genuinely differ
+#: (``mcphost.CLAUDE`` is ``"claude"``; the agent is ``"claude-code"``), and
+#: the offer is scoped through this so standing text naming ``boost_search``
+#: only reaches an agent boost actually registered a server with. Cursor and
+#: Windsurf are absent on purpose: boost registers no MCP server for them, so
+#: the rule would advertise tools they do not have.
+AGENT_FOR_HOST = {"claude": "claude-code", "gemini": "gemini"}
+
+
+def source_dir() -> Path:
+    """The shipped rules inside the installed package. **Read-only.**
+
+    Never returned as a ``Tap.path`` and never written to — a wheel is not
+    guaranteed writable, and on a system install it is not guaranteed to be
+    the user's to modify.
+    """
+    return Path(__file__).resolve().parent.parent / "data" / "rules"
+
+
+def is_builtin(tap_name: str) -> bool:
+    """Whether ``tap_name`` is boost's own tap rather than a user's."""
+    return tap_name == BUILTIN_TAP
+
+
+def configured_tap_count() -> int:
+    """Taps the USER configured — the builtin does not count.
+
+    ``mcp.no_results`` and ``boost_doctor`` both ask "has this user configured
+    anything yet" by counting taps, and print the one-command setup path when
+    the answer is zero. boost's own tap must not answer that question for
+    them: a machine holding nothing but ``boost-first`` has an effectively
+    empty catalog, and suppressing the setup message there would strand a new
+    user with a search that can never match.
+    """
+    return sum(1 for tap in registry.list_taps() if not is_builtin(tap.name))
+
+
+def ensure_tap() -> registry.Tap:
+    """Materialize the shipped rules on disk and register the tap. Idempotent.
+
+    Copies each shipped ``.mdc`` into ``~/.boost/repos/boost__builtin/`` and
+    appends the config row if it is not already there. Safe to call on every
+    install: an existing file is overwritten from the wheel, which is what
+    makes the rule track boost's own version rather than drifting once written.
+    """
+    tap = registry.Tap(name=BUILTIN_TAP, url=BUILTIN_URL, curated=True)
+    paths.ensure_dirs()
+    tap.path.mkdir(parents=True, exist_ok=True)
+    src = source_dir()
+    for rule in BUILTIN_RULES:
+        origin = src / (rule + ".mdc")
+        if origin.is_file():
+            shutil.copyfile(origin, tap.path / (rule + ".mdc"))
+    cfg = config.load()
+    rows = cfg.setdefault("taps", [])
+    if not any(str(row.get("name")) == BUILTIN_TAP for row in rows):
+        rows.append({"name": BUILTIN_TAP, "url": BUILTIN_URL, "curated": True})
+        config.save(cfg)
+    return tap
+
+
+def rule_is_available() -> bool:
+    """Whether the wheel actually carries the rule.
+
+    Package data is a packaging decision that can regress silently — a missing
+    ``package-data`` entry makes this a dev-checkout-only feature that is
+    simply absent for every pip and pipx user. The offer checks this rather
+    than assuming, so a packaging mistake degrades to "no offer" instead of a
+    traceback on the one command new users are told to run.
+    """
+    return (source_dir() / (BUILTIN_RULES[0] + ".mdc")).is_file()

{boost_skill_cli-1.0.421 → boost_skill_cli-1.0.423}/boost_cli/core/catalog.py

@@ -270,6 +270,28 @@ def all_entries() -> list[dict]:
     return out
 
 
+def kind_counts() -> dict[str, int]:
+    """Per-kind entry counts across every configured tap.
+
+    The same reads :func:`all_entries` does, one tap's cache at a time, without
+    the concatenation. A caller that only wants the size of the corpus should
+    not have to materialise it: the MCP ``boost_doctor`` handler took
+    ``len(all_entries())``, which builds a 71,655-element list on a real
+    install to produce one integer.
+
+    An entry with no ``kind`` counts as a skill, the way it renders everywhere
+    else. An unrecognised kind gets its own key rather than being dropped, so
+    ``sum(kind_counts().values())`` equals ``len(all_entries())`` for any cache
+    — including one written before a kind existed.
+    """
+    counts: dict[str, int] = {KIND_SKILL: 0, KIND_RULE: 0, KIND_WORKFLOW: 0}
+    for tap in registry.list_taps():
+        for entry in load_tap(tap):
+            kind = entry.get("kind") or KIND_SKILL
+            counts[kind] = counts.get(kind, 0) + 1
+    return counts
+
+
 def split_name(name: str) -> tuple[str | None, str]:
     """Split a possibly tap-qualified name into ``(tap, bare_name)``.
 

{boost_skill_cli-1.0.421 → boost_skill_cli-1.0.423}/boost_cli/core/mcp.py

@@ -145,6 +145,33 @@ PROTOCOL_VERSION = "2024-11-05"
 # capture this whole surface is written to avoid. The nameable-task trigger
 # stays as the cheapest test of all.
 #
+# THE DEFEATER, and it is the one clause here that is not a trigger. Forensics
+# on a Gemini CLI session: asked to build a RAG app with LangGraph, LangChain
+# and LangSmith, the agent shipped it without calling a single boost tool, and
+# explained afterwards that it had "immediately activated the pre-installed
+# local skills — langchain-rag and rag-engineer" and "overlooked calling
+# mcp_boost_boost_search". boost_search's description already named that exact
+# moment — "a new project or subsystem, an architecture decision, environment
+# and tooling config" — and the agent paraphrased the list back when asked.
+#
+# So the trigger did not fail to fire. It fired and was overruled. Every
+# trigger boost ships is a predicate over the REQUEST; the gate the model
+# actually applied was a predicate over its OWN CONTEXT — something already
+# matched, so I am covered. That proposition appears nowhere in boost's
+# agent-facing text ('already loaded' 0 hits, 'already matched' 0, 'even if' 0,
+# 'enough' 0, 'sufficient' 0, 'covered' 0, 'active skill' 0 across INSTRUCTIONS
+# and all six tool descriptions), and a clause that does not exist cannot have
+# failed. This paragraph adds it.
+#
+# It is placed DOWNSTREAM of the two signals rather than beside them, because a
+# fourth signal would widen the gate and this narrows an exception to it. And
+# it is written as a description rather than a denial. An earlier draft said
+# "an active skill does not answer this question", which compresses to "an
+# active skill is never enough" — a standing order to search, i.e. the same
+# capture the skip list and the stated cost exist to prevent. What ships says
+# what an active skill IS (installed earlier, matched on its own description,
+# one kind of three) and leaves the conclusion to the reader.
+#
 # NON-CAPTURING, and this is a measured knife edge rather than a manner.
 # Editing only a tool's description moves how often a model calls it by more
 # than 10x ("Tool Preferences in Agentic LLMs are Unreliable", EMNLP 2025),
@@ -178,6 +205,14 @@ INSTRUCTIONS = (
     "recognized at the time, and a question that became an investigation "
     "never got one.\n"
     "\n"
+    "ALREADY HOLDING A MATCH is not one of those two signals, though it reads "
+    "like an answer to the same question. A skill that activated here was "
+    "installed on an earlier day and matched on its own description — what it "
+    "covers, not what this request needs — and it is one kind of three: a rule "
+    "you never installed cannot activate, and a workflow waits to be called by "
+    "name. The two signals stay properties of the request, and an active skill "
+    "leaves them as it found them.\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 "
     "something is a head start, not an instruction — read it, take what fits, "
@@ -188,7 +223,7 @@ INSTRUCTIONS = (
 )
 
 
-def hit_line(entry: dict) -> str:
+def hit_line(entry: dict, *, installed: bool = False) -> str:
     """One search hit rendered for an agent: name, kind, description, tap.
 
     The kind marker is the load-bearing part. ``boost_install``'s description
@@ -202,14 +237,106 @@ def hit_line(entry: dict) -> str:
     line would spend a token per hit to say "nothing unusual here". A missing
     ``kind`` reads as a skill for the same reason it does everywhere else in
     the catalog — thin scanner output must not surface ``[None]`` to an agent.
+
+    ``installed`` adds a second marker after the kind, and is keyword-only with
+    a False default so every existing caller and assertion renders byte-for-byte
+    what it did before. It is **name-keyed** — the caller tests the name against
+    the lock file — which means a hit from a *different tap* that happens to
+    share a name is marked. That is a real false-positive rate (the corpus holds
+    13 distinct skills called ``code-reviewer``) and it errs toward suppressing
+    a search, so it is disclosed rather than hidden: :func:`overlap_note` says
+    so in the reply itself, and every hit line names its own tap.
+
+    Keying it more precisely was the alternative and was rejected. The lock file
+    IS name-keyed (``lockfile.find_any``), and so is ``store.install``, so a
+    tap-qualified marker would disagree with the tool it is advising about — a
+    hit marked "not installed" that ``boost_install <name>`` then resolves to
+    the item already in the lock. One notion of identity per reply, plus the
+    field that resolves it, beats two that contradict each other.
     """
     kind = entry.get("kind") or "skill"
     marker = "" if kind == "skill" else " [%s]" % kind
+    if installed:
+        marker += " [installed]"
     return "%s%s — %s (%s)" % (entry.get("name", "?"), marker,
                                entry.get("description", ""),
                                entry.get("tap", "?"))
 
 
+# The lock sections, in the order every boost surface names them. Fixed here
+# rather than read off the caller's dict, so the footer's column order cannot
+# drift between a machine that has rules and one that does not.
+_KINDS = ("skill", "rule", "workflow")
+
+
+def coverage_line(installed: dict, *, tapped: int) -> str:
+    """``boost_list``'s closing footer: what this machine holds, per kind.
+
+    ``installed`` is the ``lockfile.all_installed()`` shape — ``{kind: {name:
+    entry}}`` — and a missing section counts as zero.
+
+    boost_list used to answer "what do I have" and nothing else, which made it
+    the amplifier for the failure this footer exists to defeat: an agent that
+    stopped because something had already matched would, on calling the one
+    free tool, have been told only about the things it already had. This is the
+    other half — a kind sitting at zero is a kind nothing on this machine could
+    have loaded, and boost_search is what reads the registries themselves.
+
+    Only INSTALLED counts appear. An earlier draft closed with the size of the
+    tapped catalog, and that number cannot be substantiated: those are
+    un-de-duplicated index entries, and boost's own ranked list de-duplicates
+    on the content hash precisely because 13 distinct skills named
+    ``code-reviewer`` collapsing into one slot credited the ranker with a
+    compression that existed only in the scoring code. Printing the raw total
+    as the size of what the user is missing would be the only claim in this
+    surface an agent cannot check. Dropping it also keeps the tool honest about
+    its cost: with no catalog read, boost_list stays the "instant" tool
+    INSTRUCTIONS advertises.
+
+    ``tapped`` selects the closing sentence, keyed the way :func:`no_results`
+    and ``boost_doctor`` key theirs and naming the same one command in the same
+    order — an agent that calls two of these in one session must not see the
+    recommendation flip and read it as two different fixes.
+    """
+    body = " · ".join(
+        "%d %s%s" % (n, kind, "" if n == 1 else "s")
+        for kind, n in ((k, len(installed.get(k) or {})) for k in _KINDS))
+    if tapped > 0:
+        return ("%s installed here — what this machine holds, not what exists. "
+                "boost_search reads the tapped registries themselves, across "
+                "all three kinds." % body)
+    return ("%s installed here. Nothing is tapped yet, so there is no catalog "
+            "behind boost_search either — ask the user to run `boost tap "
+            "--defaults` to add the recommended registries." % body)
+
+
+def overlap_note(installed_hits: int, total_hits: int) -> str:
+    """How much of a search reply this machine already has. ``""`` for no hits.
+
+    The counterpart to :func:`hit_line`'s ``[installed]`` marker: the marker
+    says which line, this says how many, and it is the only agent-facing place
+    the marker's name-keying is disclosed. Both serve one decision — "I already
+    have something" is a claim about the machine, and until the reply separated
+    the two halves it was a guess.
+
+    Zero overlap gets its own sentence rather than silence. It is the plainest
+    available answer to "something already matched, so I am covered", and
+    silence would read as absence of information rather than as the answer.
+
+    The empty reply belongs to :func:`no_results` — including its
+    untapped-machine branch — so nothing bolts onto it here.
+    """
+    if total_hits <= 0:
+        return ""
+    if installed_hits <= 0:
+        return "\n(none of these are installed on this machine.)"
+    return ("\n(%d of %d already installed here, marked [installed]. The match "
+            "is on the name alone — the same test boost_install and boost_info "
+            "use — so an item from a different tap that shares a name is "
+            "marked too; each line names its tap.)"
+            % (installed_hits, total_hits))
+
+
 def no_results(query: str, *, tapped: int) -> str:
     """The reply for a search that returned nothing.
 

boost_skill_cli-1.0.423/boost_cli/data/rules/boost-first.mdc

@@ -0,0 +1,35 @@
+---
+name: boost-first
+description: Check the boost shelf before a choice gets locked in — including when a skill has already matched.
+alwaysApply: true
+globs: "**"
+---
+
+boost is a shelf of procedures other people already wrote and debugged, in
+three kinds: skills, rules and workflows. Two read-only tools reach it —
+`boost_list` for what is installed on this machine, `boost_search` for what
+exists across the registries you have tapped. Some hosts prefix the names, so
+they may appear as `mcp_boost_boost_search`. Neither installs anything. If
+neither tool is present in this session, `boost search "<what you are trying
+to do>"` in the shell asks the same question.
+
+`boost_list` is a local file read. `boost_search` takes longer because it
+retrieves and then reranks, which is what makes its top result worth acting on
+rather than skimming ten.
+
+Reach for the shelf when the request would lock something in for everything
+after it: a new project or subsystem, an architecture or dependency choice,
+environment and tooling config, a linter, tests, CI.
+
+What is already loaded is a different question. A skill that activated here was
+installed before this request existed and matched on its own description — what
+it covers, not what this request needs — and it is one kind of three: a rule you
+never installed cannot activate, and a workflow waits to be called by name. So
+an active skill leaves the question of what exists exactly where it found it.
+
+Coming back empty is a real answer: build it yourself, now knowing nothing
+already covers it. Coming back with something is a head start, not an
+instruction — read it, take what fits, discard the rest. The task stays yours.
+
+Not for: a question, a one-line edit, a command you were just handed, or a
+change that follows conventions already visible in this repo.

{boost_skill_cli-1.0.421 → boost_skill_cli-1.0.423/boost_skill_cli.egg-info}/PKG-INFO

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

{boost_skill_cli-1.0.421 → boost_skill_cli-1.0.423}/boost_skill_cli.egg-info/SOURCES.txt

@@ -53,6 +53,7 @@ boost_cli/core/agents.py
 boost_cli/core/ai.py
 boost_cli/core/bmad.py
 boost_cli/core/bootstrap.py
+boost_cli/core/builtin.py
 boost_cli/core/capabilities.py
 boost_cli/core/catalog.py
 boost_cli/core/chat.py
@@ -100,6 +101,7 @@ boost_cli/core/updatediff.py
 boost_cli/core/util.py
 boost_cli/core/workflows.py
 boost_cli/data/registries.json
+boost_cli/data/rules/boost-first.mdc
 boost_langchain/__init__.py
 boost_langchain/_compat.py
 boost_langchain/graph.py
@@ -189,6 +191,7 @@ docs/roadmap/items/atomic-skill-install-temp-dir-swap.md
 docs/roadmap/items/autonomous-ship-workflow-and-isolated-worktree.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-rule.md
 docs/roadmap/items/boost-langchain-publishing.md
 docs/roadmap/items/boost-run-live-agents.md
 docs/roadmap/items/bring-commands-under-mutation-testing.md
@@ -282,6 +285,7 @@ docs/roadmap/items/make-lint-masks-actionlint-failures.md
 docs/roadmap/items/make-the-roadmaps-discoverable.md
 docs/roadmap/items/markdown-consistency-markdownlint-cli2.md
 docs/roadmap/items/markdownlint-lints-the-fuzz-corpus.md
+docs/roadmap/items/mcp-already-covered-defeater.md
 docs/roadmap/items/mcp-aware-skills.md
 docs/roadmap/items/mcp-check-skills-before-starting-a-task.md
 docs/roadmap/items/mcp-hub-diagram-node-text-overflow.md
@@ -541,7 +545,9 @@ tests/unit/test_adapters_runner.py
 tests/unit/test_agents.py
 tests/unit/test_ai.py
 tests/unit/test_bmad_core.py
+tests/unit/test_boost_first_offer.py
 tests/unit/test_bootstrap.py
+tests/unit/test_builtin.py
 tests/unit/test_capabilities.py
 tests/unit/test_catalog.py
 tests/unit/test_chat.py