boost-skill-cli 1.2.147__tar.gz → 1.2.148__tar.gz

{boost_skill_cli-1.2.147 → boost_skill_cli-1.2.148}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.147
+Version: 1.2.148
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0

{boost_skill_cli-1.2.147 → boost_skill_cli-1.2.148}/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.147'
-__version_tuple__ = version_tuple = (1, 2, 147)
+__version__ = version = '1.2.148'
+__version_tuple__ = version_tuple = (1, 2, 148)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.147 → boost_skill_cli-1.2.148}/boost_cli/commands/pkg.py

@@ -25,6 +25,7 @@ from ..core import (
     catalog,
     complete,
     config,
+    deps,
     frontmatter,
     gitutil,
     installscan,
@@ -32,6 +33,7 @@ from ..core import (
     journal,
     lockfile,
     paths,
+    prereq,
     projectlock,
     rag,
     registry,
@@ -381,11 +383,55 @@ def _rel_list(meta: dict, key: str) -> list[str]:
 
 
 def _skill_relations(name: str, key: str) -> list[str]:
-    """`requires:`/`conflicts:` for a skill by name, from its catalog entry."""
+    """`requires:`/`conflicts:` for a skill by name, from its catalog entry.
+
+    ``requires:`` goes through :func:`deps.requirement_names`, the same
+    filter ``boost deps`` applies, so the two cannot disagree about what a
+    requirement *is*. Without it this path still fed prose and package
+    coordinates to the resolver: `requires: ["gh (GitHub CLI)", "python3"]`
+    printed "required skill 'gh (GitHub CLI)' is in no tap — skipped" while
+    `boost deps` on the same skill, post-filter, listed nothing. A qualified
+    `tap:name` survives the filter verbatim, because this feeds
+    ``catalog.find``.
+    """
     matches = catalog.find(name)
     if not matches:
         return []
-    return _rel_list(matches[0].get("meta") or {}, key)
+    meta = matches[0].get("meta") or {}
+    if key == "requires":
+        return deps.requirement_names(meta)
+    return _rel_list(meta, key)
+
+
+def _report_prerequisites(entries: list[dict], *, pbase=None,
+                          would: bool = False) -> None:
+    """Name the catalogued items an install's own frontmatter says it needs.
+
+    Advisory and after the fact: the ``requires:`` closure is installed for
+    you (above), and everything the wider spellings declare — ``skills:``,
+    ``dependencies:``, ``prerequisites:``, … — is reported here instead. See
+    :mod:`boost_cli.core.prereq` for why reporting rather than installing is
+    the answer, and for the census the key set comes from.
+
+    ``pbase`` is the project base for a ``--local`` install, so a sibling
+    installed into *this repo* counts as present. Without it every
+    project-scope user got a prerequisite line naming something already
+    beside it.
+    """
+    try:
+        rows = prereq.for_entries(entries, pbase=pbase)
+    except BoostError:
+        # A missing or unreadable catalog must not fail an install that has
+        # already happened; the prerequisite line is advice, not a step.
+        return
+    for row in rows:
+        out.warn("%s declares %s boost cannot see installed: %s"
+                 % (row.name, _plural(len(row.unmet), "prerequisite"),
+                    ", ".join("%s (%s)" % (m.name, m.tap) for m in row.unmet)),
+                 wrap=True)
+    if rows:
+        out.info(("would meet them with: %s" if would else "meet them with: %s")
+                 % prereq.install_hint(rows), wrap=True)
 
 
 def _expand_dependencies(entries: list[dict]) -> tuple[list[dict], resolve.Resolution]:
@@ -450,11 +496,17 @@ def cmd_install(argv: list[str]) -> int:
     ap.add_argument("--dry-run", action="store_true",
                     help="show what would happen without changing anything")
     ap.add_argument("--no-deps", action="store_true",
-                    help="install only the named skills, not their `requires:`")
+                    help="install only the named skills, not their `requires:` "
+                         "(the wider spellings are reported, never installed)")
     ap.add_argument("--no-mcp", action="store_true",
                     help="don't offer to register MCP servers a skill declares")
     args = ap.parse_args(argv)
     args.scope = args.scope or scopes.SCOPE_USER
+    # Resolved before the dry-run branch, because both sides need it and only
+    # one of them used to bind it: the preview returns early, so a `pbase`
+    # assigned inside `if args.dry_run:` is unbound by the time the run path
+    # reports prerequisites. `None` for every scope but `--local`.
+    pbase = scopes.resolve_base(args.scope)
     only = _check_agents(args.agent)
     multi = len(args.names) > 1
     entries, failed = [], 0
@@ -479,8 +531,30 @@ def cmd_install(argv: list[str]) -> int:
                      % (_plural(len(dep_res.added), "dependency"),
                         ", ".join(dep_res.added)))
         for name in dep_res.unresolved:
-            out.warn("required skill %r is in no tap — skipped "
-                     "(install it manually or `boost tap` its source)" % name)
+            # "in no tap" is only true when the catalog has no row for it.
+            # `_expand_dependencies` also lands here when `resolve_one`
+            # refuses a name *several* taps carry, and calling that absent
+            # contradicted the prerequisite line printed a few lines below,
+            # which names a tap and gives a command that works. 77% of the
+            # ambiguous values in the census resolve this way, so the
+            # contradiction was the common case, not the corner.
+            cands = catalog.distinct_candidates(catalog.find(name))
+            if not cands:
+                out.warn("required skill %r is in no tap — skipped "
+                         "(install it manually or `boost tap` its source)"
+                         % name)
+                continue
+            taps = sorted({str(e.get("tap") or "") for e in cands})
+            # Only offer `tap:name` when that would actually disambiguate:
+            # one tap vendoring the same name twice is ambiguous too, and
+            # there `tap:name` is as unresolvable as the bare name.
+            fix = ("name one of %s" % ", ".join("%s:%s" % (t, name)
+                                                for t in taps)
+                   if len(taps) == len(cands)
+                   else "`boost search %s` and install the one you want"
+                        % name)
+            out.warn("required skill %r matches %d catalog entries — "
+                     "skipped (%s)" % (name, len(cands), fix), wrap=True)
         for skill, clash in dep_res.conflicts:
             out.warn("%s declares a conflict with %s (also present)" % (skill, clash))
         # Pulling in dependencies can turn a single-name request into a multi-item
@@ -497,7 +571,6 @@ def cmd_install(argv: list[str]) -> int:
         # of `install x --agent cursor` drop the "available to … (reads the
         # store directly)" line the run then prints.
         native_targets = list(agents.native_store_agents())
-        pbase = scopes.resolve_base(args.scope)
         if args.scope == scopes.SCOPE_PROJECT and pbase is None:
             raise BoostError(
                 "there is no project here to install into",
@@ -619,6 +692,7 @@ def cmd_install(argv: list[str]) -> int:
                 out.warn("%s: %s" % (e["name"], err.message))
                 failed += 1
                 continue
+        _report_prerequisites(entries, pbase=pbase, would=True)
         out.info("dry run — nothing was changed")
         return 1 if failed else 0
 
@@ -637,6 +711,9 @@ def cmd_install(argv: list[str]) -> int:
         _report_result(res, no_mcp=args.no_mcp)
         results.append(res)
     if results:
+        _report_prerequisites([e for e in entries
+                               if e["name"] in {r.name for r in results}],
+                              pbase=pbase)
         kinds = {r.kind for r in results}
         noun = next(iter(kinds)) if len(kinds) == 1 else "item"
         new = sum(1 for r in results if not r.upgraded)

{boost_skill_cli-1.2.147 → boost_skill_cli-1.2.148}/boost_cli/commands/quality.py

@@ -37,6 +37,7 @@ from ..core import (
     lockfile,
     logs,
     paths,
+    prereq,
     provenance,
     registry,
     report,
@@ -729,6 +730,37 @@ def cmd_doctor(argv):
                  "(%s) — left alone; `boost hooks` only touches its own"
                  % (len(others), _s(len(others)), ", ".join(events)), wrap=True)
 
+    try:
+        prereq_rows = prereq.for_installed()
+    except BoostError:
+        # doctor's contract is to *report* problems, not to raise on one. A
+        # BoostError out of the catalog or the lock would otherwise abort the
+        # health report part-way through, and this check is the least
+        # important thing in it.
+        prereq_rows = []
+    if prereq_rows:
+        # Declared in the items' own frontmatter and resolvable to real
+        # catalogued items that are not installed. `rep.note`, not `bad`: it
+        # is somebody else's frontmatter, and boost will not install it for
+        # them (see `core/prereq`), so counting it would leave doctor
+        # permanently red on something no boost command clears on its own.
+        #
+        # One line, truncated, like `orphans` above — not one per item. The
+        # census found 1,323 `skills:` values across 18 taps, so a note per
+        # declaring item buries the rest of the report and repeats a single
+        # `name` down the whole `--json` `checks` array. The hint stays
+        # whole: it is a command, and a truncated command does not run.
+        missing = sorted({m.spec for row in prereq_rows for m in row.unmet})
+        rep.note("unmet-prerequisite",
+                 "%d installed item%s declare%s %d prerequisite%s not "
+                 "installed (%s%s) — `%s`"
+                 % (len(prereq_rows), _s(len(prereq_rows)),
+                    "" if len(prereq_rows) > 1 else "s",
+                    len(missing), _s(len(missing)),
+                    ", ".join(missing[:5]),
+                    ", …" if len(missing) > 5 else "",
+                    prereq.install_hint(prereq_rows)), wrap=True)
+
     for dup in store.duplicate_discovery():
         # An agent that reads the canonical store natively, holding its own
         # entry for a skill that store already carries. Boost did not put it

{boost_skill_cli-1.2.147 → boost_skill_cli-1.2.148}/boost_cli/core/catalog.py

@@ -469,6 +469,30 @@ def all_entries() -> list[dict]:
     return out
 
 
+def cached_entries() -> list[dict]:
+    """:func:`all_entries`, but never writing — whatever the caches hold.
+
+    :func:`load_tap` *rescans* a missing or stale cache and writes it, which is
+    the right default for a command whose answer depends on the catalogue. It
+    is the wrong default for a read-only check bolted onto another command:
+    ``boost doctor`` reports a missing cache as an issue and ``boost heal``
+    rebuilds it, so a doctor that quietly rebuilt it first turned heal's
+    "rebuilt catalog cache" into "nothing to heal" — doctor curing the thing it
+    had just diagnosed.
+
+    A tap with no cache contributes nothing rather than being scanned. Callers
+    of this get a possibly-incomplete corpus by construction, so it suits a
+    check that only ever *adds* an advisory line and must stay silent when it
+    cannot see enough to be sure.
+    """
+    out: list[dict] = []
+    for tap in registry.list_taps():
+        cached = _cached_tap(tap)
+        if cached is not None:
+            out.extend(cached[0])
+    return out
+
+
 def kind_counts() -> dict[str, int]:
     """Per-kind entry counts across every configured tap.
 
@@ -518,12 +542,19 @@ def tap_matches(tap_name: str, qualifier: str) -> bool:
     return bool(tap_name) and qualifier in (tap_name, tap_name.split("/")[-1])
 
 
-def find(name: str, tap: str | None = None) -> list[dict]:
-    """Exact-name lookup. Supports 'owner/repo:skill' qualified form."""
+def find(name: str, tap: str | None = None,
+         entries: list[dict] | None = None) -> list[dict]:
+    """Exact-name lookup. Supports 'owner/repo:skill' qualified form.
+
+    ``entries`` searches a corpus the caller already has instead of reading
+    every tap again: a caller resolving many names in a row (one per installed
+    item) would otherwise pay a full :func:`all_entries` per name.
+    """
     qualifier, bare = split_name(name)
     if qualifier is not None:
         tap, name = qualifier, bare
-    matches = [e for e in all_entries() if e["name"] == name]
+    pool = all_entries() if entries is None else entries
+    matches = [e for e in pool if e["name"] == name]
     if tap:
         # Same tiering as registry.get: a qualified owner/repo beats a bare
         # repo tail, so `angular/skills:x` never picks up `microsoft/skills:x`.
@@ -688,6 +719,35 @@ def _fuzzy_suggestions(query: str, entries: list[dict], limit: int = 3) -> list[
     return difflib.get_close_matches(query, names, n=limit)
 
 
+def distinct_candidates(matches: list[dict]) -> list[dict]:
+    """The candidates :func:`resolve_one` would still have to choose between.
+
+    The same two collapses ``resolve_one`` makes, without raising or picking:
+    inside one tap, rows that render identically are a vendored copy
+    (:func:`_identity`); across taps, rows that agree on a non-empty content
+    digest are a mirror (:func:`_same_thing`). What is left is genuine
+    ambiguity, and more than one of it means an unqualified ``boost install
+    <name>`` exits 1.
+
+    A caller that only wants to know whether a name is *installable by name*
+    needs exactly that count. Asking ``resolve_one`` instead would mean
+    catching an exception per name, and counting ``find()`` rows instead
+    over-reports every mirrored skill in the catalogue.
+    """
+    if len(matches) <= 1:
+        return matches.copy()
+    # `.get`, like `_identity`: this is an advisory read behind `install`
+    # and `doctor`, and a synthesised entry missing `tap` must not raise
+    # KeyError out of a hint.
+    taps = list(dict.fromkeys(e.get("tap") for e in matches))
+    if len(taps) == 1:
+        if len({_identity(e) for e in matches}) == 1:
+            return [_canonical(matches)]
+        return matches.copy()
+    best = _same_thing(matches)
+    return [best] if best is not None else matches.copy()
+
+
 def resolve_one(name: str, path: str | None = None) -> dict:
     """Find exactly one entry or raise with a helpful hint.
 

boost_skill_cli-1.2.148/boost_cli/core/deps.py

@@ -0,0 +1,343 @@
+# Copyright the boost contributors.
+# SPDX-License-Identifier: Apache-2.0
+"""Requirement & conflict *facts* for ``boost deps``/``boost info`` — what is
+declared, and whether it is currently satisfied.
+
+Distinct from :mod:`boost_cli.core.resolve`, which turns ``requires:`` into an
+install *order*. This module never decides what to install; it answers "given
+what is installed right now, is this skill's declared graph satisfied?" — the
+question ``boost deps`` renders and scores an exit code on. Pure and I/O-free,
+like :mod:`boost_cli.core.mcpdecl`: callers read frontmatter and pass the
+parsed value in, so every branch here is unit- and mutation-testable with no
+lock file or filesystem access.
+
+The bug this closes: ``boost deps <name>`` used to test only *that skill's own*
+``requires:`` against the installed set, then separately render one level of
+*its dependencies'* own unmet requirements underneath — so a transitively unmet
+requirement printed a "✗ not installed" line the exit code never counted.
+:func:`has_unmet` is the one place that walks the same nesting the renderer
+does, so the two can never disagree again.
+"""
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+
+
+def as_list(value) -> list[str]:
+    """Normalize a frontmatter value to a list of non-empty names.
+
+    Accepts a YAML list, a comma-separated string, or a blank/``False``
+    value ("declares nothing") — the shared contract ``requires:`` and
+    ``conflicts:`` both use.
+    """
+    if value in (None, "", False):
+        return []
+    if isinstance(value, list):
+        return [str(x).strip() for x in value if str(x).strip()]
+    return [s.strip() for s in str(value).split(",") if s.strip()]
+
+
+def requirement_names(meta: dict | None) -> list[str]:
+    """The plain skill/rule/workflow names a ``requires:`` frontmatter value
+    lists.
+
+    Deliberately blind to the MCP-server shape a ``requires:`` block can also
+    carry (``requires: {mcp: [...]}`` in an author's source) — boost's
+    stdlib-only frontmatter parser has no nested-mapping support, so a value
+    written that way never survives parsing as a mapping at all: it is
+    hoisted, leaving the *parsed* ``requires`` empty and the MCP names on the
+    top-level ``mcp`` key instead (see :mod:`boost_cli.core.mcpdecl`'s module
+    docstring). That is precisely why a plain ``requires:`` reader must not
+    also expect a mapping here — there is never one to find — and why an MCP
+    requirement is a separate fact, read from ``mcp`` via
+    :mod:`boost_cli.core.mcpdecl`, not from this function.
+
+    Values that cannot be an item name are dropped by
+    :func:`classify_token`. That is a fix rather than tidying: of the 101
+    ``requires:`` values in the tapped corpus, 37 are prose ("GitHub CLI (gh)
+    installed and authenticated") and several more are package coordinates
+    (``dspy>=0.34.0``, ``python3``) — and every one was rendered by ``boost
+    deps`` as a skill that is "✗ not installed" and warned about by ``boost
+    install`` as "in no tap". Both were naming a missing skill that was never
+    a skill.
+
+    Tokens come back **as written** (:func:`item_tokens`, not
+    :func:`item_names`) because this feeds a resolver: a qualified
+    ``acme/skills:brainstorming`` has to stay qualified all the way to
+    ``catalog.find``.
+    """
+    return item_tokens(as_list((meta or {}).get("requires")))
+
+
+def conflict_names(meta: dict | None) -> list[str]:
+    """The names a ``conflicts:`` frontmatter value lists."""
+    return as_list((meta or {}).get("conflicts"))
+
+
+def requirement_row(name: str, have: set, sub_names: Sequence[str] = ()) -> dict:
+    """One ``{name, installed, requires}`` record.
+
+    The shape both ``boost deps <name>`` (top level and nested, one level
+    deep) and ``boost deps`` (all-installed) now emit for a requirement, so a
+    ``--json`` consumer reads the same fields regardless of nesting depth —
+    the nested form used to be a bare string with no ``installed`` flag,
+    which is what let a genuinely unmet transitive requirement render
+    invisibly to any JSON consumer. ``requires`` is always present (``[]``
+    when ``sub_names`` is empty) rather than omitted, matching the envelope
+    shape this command already committed to.
+    """
+    return {"name": name, "installed": name in have,
+            "requires": [requirement_row(n, have) for n in sub_names]}
+
+
+def conflict_row(name: str, have: set) -> dict:
+    """One ``{name, installed}`` conflict record."""
+    return {"name": name, "installed": name in have}
+
+
+def has_unmet(rows) -> bool:
+    """True if any requirement row, at any nesting depth, is unmet.
+
+    Walks ``row["requires"]`` the same way the renderer does, so a skill whose
+    own direct requirement is installed but whose requirement's requirement
+    is not still reports a problem — the exit-code bug this module exists to
+    close.
+    """
+    for row in rows:
+        if not row["installed"] or has_unmet(row.get("requires") or []):
+            return True
+    return False
+
+
+def active_conflicts(rows) -> bool:
+    """True if any conflict row names something actually installed."""
+    return any(row["installed"] for row in rows)
+
+
+def unmet_names(rows) -> list[str]:
+    """Every unmet name across requirement rows, flattened and de-duplicated,
+    sorted for deterministic output — the ``boost install <name>`` hint reads
+    straight off this list.
+    """
+    names: list[str] = []
+    seen: set = set()
+    for row in rows:
+        if not row["installed"] and row["name"] not in seen:
+            seen.add(row["name"])
+            names.append(row["name"])
+        for sub in row.get("requires") or []:
+            if not sub["installed"] and sub["name"] not in seen:
+                seen.add(sub["name"])
+                names.append(sub["name"])
+    return sorted(names)
+
+
+# ── prerequisite declarations ────────────────────────────────────────────
+#
+# `requires:` is the spelling boost has always read, and a census of the 461
+# tapped registries on a real machine (62,310 entries) says it is the
+# *narrowest* real one: 101 declared values across 6 taps. The two that carry
+# almost all of the signal were invisible — `skills:` (1,323 values, 18 taps)
+# and `dependencies:` (1,065 values, 17 taps). So the key set is widened here
+# rather than in a caller, and the two keys that merely *look* like
+# declarations are excluded by name:
+#
+#   `required:`       130 entries, and not a dependency list at all — it is an
+#                     argument-schema field, valued `true`/`false` or naming
+#                     parameters (`["task_type", "requirements"]`, `["type:
+#                     file"]`). Reading it would invent 130 prerequisites.
+#   `tools_required:` names Claude *tool permissions* (`Bash`, `Read`,
+#                     `mcp__github__*`), which are not installable items.
+#   `requires_tools:` names PATH binaries (`kubectl`, `terraform`).
+#   `requires-extras:` names Python extras (`dspy[optuna]`, `faiss-cpu`).
+#
+# `requirements:` and `dependency:` are listed for the same reason even though
+# every occurrence measured empty: a key that is skipped on purpose should say
+# so, so the next census does not have to re-derive it.
+PREREQUISITE_KEYS = ("requires", "dependencies", "depends-on", "depends_on",
+                     "prerequisites", "uses", "skills", "needs")
+
+NON_PREREQUISITE_KEYS = ("required", "tools_required", "requires_tools",
+                         "requires-extras", "requirements", "dependency")
+
+# A declared value is not automatically a name. Over the same corpus the 2,658
+# values under those keys split four ways, and only the first is addressable:
+# 1,944 resolve to a catalogued item, 193 are package specs (`torch>=2.0.0`,
+# `dspy[mcp]`, `actions/upload-artifact@v7.0.1`), 62 are prose sentences
+# ("GitHub CLI (gh) installed and authenticated") and 42 are file paths
+# (`01-base-agentic.rules.md`). Classification is therefore per *value*, never
+# per key: `dependencies:` is packages in `Galaxy-Dawn/claude-scholar` and
+# sibling skills in `athola/claude-night-market`.
+ITEM = "item"
+PACKAGE = "package"
+PROSE = "prose"
+FILE = "file"
+
+_FILE_SUFFIXES = (".md", ".mdc", ".py", ".sh", ".json", ".yml", ".yaml", ".txt")
+# A version constraint, an extras bracket or an `@ref` — every shape that
+# makes a token a package coordinate rather than an item name.
+_PACKAGE = re.compile(r"(>=|<=|==|~=|!=|@|\[)|(?<=[A-Za-z0-9])\s*[<>]\s*\d")
+# Namespaced forms are real and common: `imbue:proof-of-work`,
+# `superpowers:writing-skills`, `marketing-skill/skills/aeo`. 380 of the 1,944
+# resolvable values arrive this way, and in every measured case the item lives
+# in the *declaring* tap — which is also what keeps a GitHub-Actions `uses:`
+# such as `actions/checkout` from resolving against an unrelated registry.
+_NAMESPACE = re.compile(r"[:/]")
+_MAX_NAME_WORDS = 4
+
+
+def item_names(tokens: Sequence[str]) -> list[str]:
+    """The bare item names among ``tokens``, in order, keeping duplicates.
+
+    A namespaced token is reduced to its tail, which is what the *report*
+    path wants: :func:`declared_prerequisites` pairs that tail with
+    ``same_tap_only`` and resolves it inside the declaring tap. See
+    :func:`item_tokens` for the caller that must not do that.
+    """
+    names = []
+    for token in tokens:
+        kind, name = classify_token(token)
+        if kind == ITEM:
+            names.append(name)
+    return names
+
+
+def item_tokens(tokens: Sequence[str]) -> list[str]:
+    """The item-naming tokens among ``tokens``, **exactly as written**.
+
+    The same filter as :func:`item_names` without the namespace split, for
+    the one caller that feeds a resolver rather than a message.
+    ``owner/repo:x`` is boost's own qualified form and
+    ``pkg._expand_dependencies`` hands it straight to ``catalog.find``:
+    reducing it to ``x`` there would turn an unambiguous spec into a bare
+    name two taps can carry, which boost refuses rather than guesses.
+    Dropping the qualifier is only safe once something else supplies the tap.
+    """
+    return [t for t in tokens if classify_token(t)[0] == ITEM]
+
+
+@dataclass(frozen=True)
+class Prerequisite:
+    """One declared value that names an installable item.
+
+    ``key`` is the frontmatter key it came from (so a message can say which
+    spelling it read), ``token`` the value as written, ``name`` the bare name
+    to look up, and ``same_tap_only`` marks a namespaced token, which may only
+    resolve inside the tap that declared it.
+    """
+
+    key: str
+    token: str
+    name: str
+    same_tap_only: bool
+
+
+def classify_token(token: str) -> tuple[str, str]:
+    """Classify one declared value as ``(class, bare_name)``.
+
+    ``bare_name`` is meaningful only for :data:`ITEM`; the other classes
+    return the token unchanged so a caller can report what it skipped. Order
+    matters: `dspy[mcp]` is a package before it is a short name, and
+    `01-base-agentic.rules.md` is a file before it is either.
+
+    A URL is checked before anything else because it defeats every later
+    rule at once: `https://docs.example.com/hooks` has no file suffix, no
+    package marker and one word, so the namespace split would hand back
+    `hooks` — a plausible skill name in almost any registry.
+    """
+    tok = token.strip()
+    if not tok:
+        return PROSE, tok
+    if "://" in tok:
+        return PROSE, tok
+    if tok.lower().endswith(_FILE_SUFFIXES):
+        return FILE, tok
+    if _PACKAGE.search(tok):
+        return PACKAGE, tok
+    if len(tok.split()) > _MAX_NAME_WORDS or tok.endswith(".") or "(" in tok:
+        return PROSE, tok
+    if _NAMESPACE.search(tok):
+        tail = _NAMESPACE.split(tok)[-1].strip()
+        return (ITEM, tail) if tail else (PROSE, tok)
+    return ITEM, tok
+
+
+def declared_prerequisites(meta: dict | None,
+                           own_name: str | None = None) -> list[Prerequisite]:
+    """Every value under :data:`PREREQUISITE_KEYS` that names an item.
+
+    Package specs, prose and file paths are dropped, as is a self-reference —
+    31 entries in the corpus list their own name, and "install x before x" is
+    never a useful line. De-duplicated on the resolved name, first key wins,
+    so a skill declaring the same sibling under both `requires:` and `skills:`
+    is one prerequisite rather than two.
+    """
+    found: list[Prerequisite] = []
+    seen: set[str] = set()
+    for key in PREREQUISITE_KEYS:
+        for token in as_list((meta or {}).get(key)):
+            kind, name = classify_token(token)
+            if kind != ITEM or name == own_name or name in seen:
+                continue
+            seen.add(name)
+            found.append(Prerequisite(key, token, name,
+                                      bool(_NAMESPACE.search(token))))
+    return found
+
+
+@dataclass(frozen=True)
+class Unmet:
+    """A prerequisite that resolves to a real catalogued item nobody installed.
+
+    ``spec`` is what to hand `boost install`: qualified as ``tap:name`` when
+    the name exists in more than one tap, because boost refuses an unqualified
+    name in that case — 422 of the resolvable values are ambiguous that way,
+    so an unqualified hint would be a command that does not run.
+    """
+
+    name: str
+    tap: str
+    spec: str
+    key: str
+
+
+def unmet_prerequisites(prereqs: Sequence[Prerequisite], *, tap: str,
+                        installed, taps_for: Callable[[str], Sequence[str]],
+                        ) -> list[Unmet]:
+    """Which declared prerequisites name a catalogued item that is not installed.
+
+    ``taps_for(name)`` returns **one tap per candidate boost would still have
+    to choose between** — so a name a single registry ships twice under
+    different content appears twice, because that is what
+    ``catalog.resolve_one`` refuses. Resolution is **same tap first** —
+    measured against the 422 ambiguous values, the declaring tap also carries
+    the name in 326 of them (77%) — then a unique other tap.
+
+    Anything else is dropped *silently*, and that is the load-bearing
+    decision: 413 of the declared values are bare tokens matching nothing in
+    any tap (`chromadb`, `torch`, `litgpt`), so a line reading "required skill
+    'chromadb' is in no tap" would be wrong far more often than saying
+    nothing. Silence is the floor this has to beat — and it is why a row only
+    survives when the ``spec`` it carries is a command that runs. Two
+    differing copies inside the declaring tap make ``boost install <name>``
+    exit 1 with "matches 2 different skills", so that row is dropped rather
+    than turned into advice the user cannot follow.
+    """
+    out_rows: list[Unmet] = []
+    for pre in prereqs:
+        if pre.name in installed:
+            continue
+        candidates = list(taps_for(pre.name) or ())
+        own = [c for c in candidates if c == tap]
+        if len(own) == 1:
+            source = tap
+        elif own or pre.same_tap_only or len(candidates) != 1:
+            continue
+        else:
+            source = candidates[0]
+        spec = ("%s:%s" % (source, pre.name) if len(set(candidates)) > 1
+                else pre.name)
+        out_rows.append(Unmet(pre.name, source, spec, pre.key))
+    return out_rows