boost-skill-cli 1.0.281__tar.gz → 1.0.283__tar.gz

{boost_skill_cli-1.0.281 → boost_skill_cli-1.0.283}/.gitignore

@@ -230,6 +230,11 @@ mutants/
 
 # sandboxed boost home for the Tier 1 eval corpus (`make eval` taps here)
 .eval-home/
+
+# `make evals` output. The generated corpus and index live in the system temp
+# dir (see evals/run_evals.py), so only the per-run scores land here; the
+# committed evals/baseline.json is what regressions are measured against.
+evals/results.json
 tests/visual/node_modules/
 tests/visual/out/
 tests/visual/package-lock.json

{boost_skill_cli-1.0.281 → boost_skill_cli-1.0.283}/.vale/styles/config/vocabularies/boost/accept.txt

@@ -34,6 +34,7 @@ mutmut
 mypy
 npm
 onboards
+overclaiming
 Pinecone
 pytest
 rebased

{boost_skill_cli-1.0.281 → boost_skill_cli-1.0.283}/Makefile

@@ -10,7 +10,7 @@ PYTEST    := $(VENV)/bin/pytest
 # pinned taps out of the developer's real ~/.boost.
 EVAL_HOME := $(CURDIR)/.eval-home
 
-.PHONY: venv test unit functional smoke coverage patch-coverage mutation lint check demo carousel clean-test eval eval-ai eval-rec eval-stats eval-explain audit dist-check bdd bench bench-cli fuzz post-deploy
+.PHONY: venv test unit functional smoke coverage patch-coverage mutation lint check demo carousel clean-test eval eval-ai eval-rec eval-stats eval-explain evals evals-baseline evals-golden evals-online audit dist-check bdd bench bench-cli fuzz post-deploy
 
 # Every tool comes from a hash-pinned requirements/*.txt — the same files CI
 # installs (see scripts/lock_toolchain.py). pip enforces the hashes, so a dev
@@ -52,7 +52,7 @@ mutation:
 	$(PY) scripts/mutation_gate.py --run --min 80
 
 lint:
-	$(VENV)/bin/ruff check boost_cli tests
+	$(VENV)/bin/ruff check boost_cli tests evals
 	$(VENV)/bin/mypy
 	$(VENV)/bin/pyright
 	$(VENV)/bin/lint-imports
@@ -72,6 +72,7 @@ lint:
 	$(PY) scripts/perf_gate.py
 	$(PY) scripts/check_anchors.py
 	$(PY) scripts/check_required_checks.py
+	$(PY) evals/make_golden.py --check
 
 # Supply-chain CVE gate: fail on a known OSV/PyPI advisory in the project's
 # dependency closure. Mirrors the pip-audit CI workflow; run before releasing.
@@ -125,6 +126,30 @@ eval-explain:
 	PYTHON=$(PY) BOOST_HOME=$(EVAL_HOME) bash scripts/ensure_eval_corpus.sh
 	BOOST_HOME=$(EVAL_HOME) $(PY) scripts/eval_explain.py --fail-under 0.80
 
+# Retrieval-quality gate over the HERMETIC golden set: recall@5/@10, MRR, and
+# nDCG@5/@10 with graded (3/2/1) relevance, plus a paired-bootstrap regression
+# test against the committed evals/baseline.json. Part of `check` and required
+# in CI. Unlike `eval` above it needs no network and no API key: it generates
+# its own corpus and taps it into a disposable BOOST_HOME under the system temp
+# dir, so a metric moving can only mean the ranker moved.
+evals:
+	$(PY) scripts/eval_gate.py --run
+
+# Re-pin evals/baseline.json to the current scores. Deliberate: it is how you
+# accept a ranking change, so it must be a separate commit that says why.
+evals-baseline:
+	$(PY) evals/run_evals.py --save-baseline
+
+# Regenerate evals/golden_set.json from evals/make_golden.py after editing the
+# query table (`--check` runs in `lint` and fails on drift).
+evals-golden:
+	$(PY) evals/make_golden.py
+
+# The same five metrics over the pinned REAL-registry corpus `eval` uses.
+# Needs the network; reported, never gated — mirrors `tests/smoke.sh --online`.
+evals-online:
+	$(PY) evals/run_evals.py --online --faithfulness
+
 # Opt-in Gherkin/BDD suite (tests/bdd) — additive to tests/functional, not a
 # replacement. Needs the [bdd] extra (`pip install -e '.[bdd]'`); not part of
 # `make check`.
@@ -183,7 +208,7 @@ demo:
 carousel:
 	for t in docs/carousel/tapes/*.tape; do vhs "$$t"; done
 
-check: lint eval test smoke mutation
+check: lint eval evals test smoke mutation
 	@echo "== all gates passed =="
 
 clean-test:

{boost_skill_cli-1.0.281 → boost_skill_cli-1.0.283}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.281
+Version: 1.0.283
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE
@@ -997,16 +997,56 @@ reports, and the free services that monitor the project.
 
 ## Test suite
 
-Three layers, all enforced (`make check` runs the full set; CI runs the same thing):
+Four layers, all enforced (`make check` runs the full set; CI runs the same thing):
 
 | Layer | What it does | Gate |
 |---|---|---|
 | `make test` | pytest across `tests/unit/` (every core module) and `tests/functional/` (drives all 78 commands in-process against sandboxed homes) | **≥80% line coverage** of `boost_cli` (`fail_under` in pyproject.toml) |
 | `make smoke` | `tests/smoke.sh` — 170 checks run through the actual `./boost` shim (`--online` also hits real registries) | all pass |
 | `make mutation` | [mutmut] mutates `boost_cli/core` (~9,900 mutants) and reruns the unit suite against each one | **≥80% killed** (`scripts/mutation_gate.py`) |
+| `make evals` | scores the search ranker on a graded golden set — recall@5/@10, MRR, nDCG@5/@10 | **metric floors + no statistically significant regression** (`scripts/eval_gate.py`) |
 
 Dev setup: `make venv` (pulls in pytest, coverage, mutmut — the shipped
 runtime itself stays dependency-free). Every test run uses a throwaway
 `$HOME`, so your actual agent configs are never at risk.
 
 [mutmut]: https://mutmut.readthedocs.io/
+
+## Evaluation harness
+
+Search quality is the one thing the suite above can't assert: every test can
+pass while the ranker quietly gets worse. `make evals` measures it. The harness
+is pure stdlib and fully offline — it generates its own corpus of skills, rules,
+and workflows and taps it into a disposable `BOOST_HOME`, so a metric that moves
+can only mean the *ranker* moved. See [`evals/README.md`](evals/README.md).
+
+**Golden set** — [`evals/golden_set.json`](evals/golden_set.json): 36 realistic
+queries with **graded** relevance (3 perfect · 2 useful · 1 marginal) over the
+generated corpus. Generated and validated by `evals/make_golden.py`, which
+refuses a judgment naming a skill the corpus doesn't contain; `--check` fails CI
+on drift, so the file can never disagree with its source.
+
+**Five metrics**, all computed by `evals/metrics.py`:
+
+- **recall@5** / **recall@10** — of everything relevant, what fraction reached the top *k*.
+- **MRR** — 1/rank of the first relevant hit, averaged; sensitive only to the top of the list, which is where people look.
+- **nDCG@5** / **nDCG@10** — graded gain (`2^rel − 1`) with the standard `log2(rank + 1)` discount; the only metric that distinguishes the right results in the wrong order from the right order.
+
+**Significance gating.** A metric dropping isn't automatically a regression —
+with 36 queries, one unlucky result moves the mean. So `scripts/eval_gate.py`
+fails a metric only when it falls more than 0.02 below the committed baseline
+**and** a seeded 10,000-resample paired bootstrap over the per-query deltas puts
+that drop at `p < 0.05`. Alongside that, each metric has an absolute floor set
+~0.05 below its first measured value, which catches the erosion that a
+compare-to-last-commit check never sees. Accepting a real ranking change is a
+deliberate `make evals-baseline` commit.
+
+**Faithfulness.** `boost explain` and `boost distill` generate prose from a
+`SKILL.md`, and their failure mode is overclaiming. The harness scores that with
+the Ragas method — split the answer into atomic statements, verify each against
+the source, score supported/total — and reports it alongside what the runtime
+grounding guardrail in `boost explain` would do with the same reply. With no
+`claude` CLI and no `ANTHROPIC_API_KEY` it **skips rather than fails**, and
+reports a status instead of a number so "couldn't measure" is never mistaken for
+"scored zero". It's therefore outside `make check`; run it with
+`make evals-online`.

{boost_skill_cli-1.0.281 → boost_skill_cli-1.0.283}/README.md

@@ -281,16 +281,56 @@ reports, and the free services that monitor the project.
 
 ## Test suite
 
-Three layers, all enforced (`make check` runs the full set; CI runs the same thing):
+Four layers, all enforced (`make check` runs the full set; CI runs the same thing):
 
 | Layer | What it does | Gate |
 |---|---|---|
 | `make test` | pytest across `tests/unit/` (every core module) and `tests/functional/` (drives all 78 commands in-process against sandboxed homes) | **≥80% line coverage** of `boost_cli` (`fail_under` in pyproject.toml) |
 | `make smoke` | `tests/smoke.sh` — 170 checks run through the actual `./boost` shim (`--online` also hits real registries) | all pass |
 | `make mutation` | [mutmut] mutates `boost_cli/core` (~9,900 mutants) and reruns the unit suite against each one | **≥80% killed** (`scripts/mutation_gate.py`) |
+| `make evals` | scores the search ranker on a graded golden set — recall@5/@10, MRR, nDCG@5/@10 | **metric floors + no statistically significant regression** (`scripts/eval_gate.py`) |
 
 Dev setup: `make venv` (pulls in pytest, coverage, mutmut — the shipped
 runtime itself stays dependency-free). Every test run uses a throwaway
 `$HOME`, so your actual agent configs are never at risk.
 
 [mutmut]: https://mutmut.readthedocs.io/
+
+## Evaluation harness
+
+Search quality is the one thing the suite above can't assert: every test can
+pass while the ranker quietly gets worse. `make evals` measures it. The harness
+is pure stdlib and fully offline — it generates its own corpus of skills, rules,
+and workflows and taps it into a disposable `BOOST_HOME`, so a metric that moves
+can only mean the *ranker* moved. See [`evals/README.md`](evals/README.md).
+
+**Golden set** — [`evals/golden_set.json`](evals/golden_set.json): 36 realistic
+queries with **graded** relevance (3 perfect · 2 useful · 1 marginal) over the
+generated corpus. Generated and validated by `evals/make_golden.py`, which
+refuses a judgment naming a skill the corpus doesn't contain; `--check` fails CI
+on drift, so the file can never disagree with its source.
+
+**Five metrics**, all computed by `evals/metrics.py`:
+
+- **recall@5** / **recall@10** — of everything relevant, what fraction reached the top *k*.
+- **MRR** — 1/rank of the first relevant hit, averaged; sensitive only to the top of the list, which is where people look.
+- **nDCG@5** / **nDCG@10** — graded gain (`2^rel − 1`) with the standard `log2(rank + 1)` discount; the only metric that distinguishes the right results in the wrong order from the right order.
+
+**Significance gating.** A metric dropping isn't automatically a regression —
+with 36 queries, one unlucky result moves the mean. So `scripts/eval_gate.py`
+fails a metric only when it falls more than 0.02 below the committed baseline
+**and** a seeded 10,000-resample paired bootstrap over the per-query deltas puts
+that drop at `p < 0.05`. Alongside that, each metric has an absolute floor set
+~0.05 below its first measured value, which catches the erosion that a
+compare-to-last-commit check never sees. Accepting a real ranking change is a
+deliberate `make evals-baseline` commit.
+
+**Faithfulness.** `boost explain` and `boost distill` generate prose from a
+`SKILL.md`, and their failure mode is overclaiming. The harness scores that with
+the Ragas method — split the answer into atomic statements, verify each against
+the source, score supported/total — and reports it alongside what the runtime
+grounding guardrail in `boost explain` would do with the same reply. With no
+`claude` CLI and no `ANTHROPIC_API_KEY` it **skips rather than fails**, and
+reports a status instead of a number so "couldn't measure" is never mistaken for
+"scored zero". It's therefore outside `make check`; run it with
+`make evals-online`.

{boost_skill_cli-1.0.281 → boost_skill_cli-1.0.283}/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.281'
-__version_tuple__ = version_tuple = (1, 0, 281)
+__version__ = version = '1.0.283'
+__version_tuple__ = version_tuple = (1, 0, 283)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.281 → boost_skill_cli-1.0.283}/boost_cli/commands/configuration.py

@@ -917,11 +917,14 @@ def _tool_discover_github(args: dict):
 
 REGISTRY.register(
     "boost_search",
-    "FIRST STOP before writing a skill, subagent, slash-command, rule, or any "
-    "reusable block of agent instructions from scratch: search thousands of "
-    "curated, installable AI-agent skills across the configured registries. "
-    "Returns ranked matches you can install in one call — don't reinvent one "
-    "that already exists.",
+    "Find an existing, installable skill instead of improvising one. Reach for "
+    "this at two moments: (1) when starting non-trivial work — check whether a "
+    "vetted skill already covers the task before planning it yourself; (2) as "
+    "the FIRST STOP before writing a skill, subagent, slash-command, rule, or "
+    "any reusable block of agent instructions from scratch. Searches thousands "
+    "of curated AI-agent skills across the configured registries and returns "
+    "ranked matches you can install in one call — don't reinvent one that "
+    "already exists.",
     {"type": "object",
      "properties": {"query": {"type": "string",
                               "description": "what the skill should do (a task, "
@@ -930,8 +933,10 @@ REGISTRY.register(
     _tool_search)
 REGISTRY.register(
     "boost_list",
-    "List the skills already installed by boost — check here first to avoid "
-    "reinstalling or duplicating something you already have.",
+    "List the skills already installed and usable right now. Check at the "
+    "START of a task to leverage a capability you already have — an installed "
+    "skill is a vetted procedure you can follow immediately, at no cost — and "
+    "again before installing, to avoid duplicating something you have.",
     {"type": "object", "properties": {}},
     _tool_list)
 REGISTRY.register(

{boost_skill_cli-1.0.281 → boost_skill_cli-1.0.283}/boost_cli/core/mcp.py

@@ -83,19 +83,46 @@ PROTOCOL_VERSION = "2024-11-05"
 # Server-level guidance returned in the `initialize` result. MCP hosts load this
 # into the model's context, so it is boost's one chance to tell an agent WHEN it
 # is relevant — the difference between a search tool that sits unused and one an
-# agent reaches for before reinventing a skill. Framed by the agent's trigger
-# ("about to author reusable instructions"), not boost's nouns.
+# agent reaches for. Framed by the agent's triggers, not boost's nouns.
+#
+# It declares TWO triggers, and the first exists because the second alone was
+# not enough. Framed only as "before you author a skill", agents reached for
+# boost exclusively when they were already about to write one — which is the
+# rarer moment. The common one is starting ordinary work that an installed or
+# installable skill already covers, and nothing was telling them to look. The
+# closing proportion note is load-bearing in the other direction: an unbounded
+# "always check first" turns every trivial turn into a tool call, and an agent
+# that learns to ignore the guidance ignores all of it.
 INSTRUCTIONS = (
     "boost is a package manager for AI-agent skills: reusable, version-tracked "
     "capabilities (skills, rules, slash-commands, subagents) from curated "
-    "registries. BEFORE you author a new skill, subagent, slash-command, rule, "
-    "or any reusable block of agent instructions — or when the user describes a "
-    "repeatable workflow (\"set up code review\", \"add a commit convention\") — "
-    "call boost_search FIRST to check whether a vetted one already exists. "
-    "Installing beats hand-writing: an installed skill is version-pinned, wired "
-    "into every agent on this machine, policy-governed, and shareable with the "
-    "team. Typical flow: boost_search -> boost_info -> boost_install. Only build "
-    "from scratch when a search turns up nothing relevant."
+    "registries.\n"
+    "\n"
+    "Two moments make boost relevant. The first is the one usually missed:\n"
+    "\n"
+    "1. STARTING A TASK. Before doing non-trivial work — building a feature, "
+    "setting up tooling or CI, reviewing code, debugging a class of problem, "
+    "writing docs — stop and check whether a skill already covers it. Call "
+    "boost_list for what is installed and usable right now, and boost_search "
+    "for what could be. A matching skill is a procedure someone already got "
+    "right and vetted; following it beats reconstructing the same steps from "
+    "memory.\n"
+    "\n"
+    "2. AUTHORING. Before you write a new skill, subagent, slash-command, "
+    "rule, or any reusable block of agent instructions — or when the user "
+    "describes a repeatable workflow (\"set up code review\", \"add a commit "
+    "convention\") — call boost_search FIRST to check whether a vetted one "
+    "already exists. Installing beats hand-writing: an installed skill is "
+    "version-pinned, wired into every agent on this machine, policy-governed, "
+    "and shareable with the team.\n"
+    "\n"
+    "Typical flow: boost_search -> boost_info -> boost_install. Only build "
+    "from scratch when a search turns up nothing relevant.\n"
+    "\n"
+    "Proportion: skip the check for trivial or one-off turns — answering a "
+    "question, a small edit, running a command you were just handed. Checking "
+    "once when a task starts is the habit; checking before every tool call is "
+    "noise."
 )
 
 

{boost_skill_cli-1.0.281 → boost_skill_cli-1.0.283}/boost_skill_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.281
+Version: 1.0.283
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE
@@ -997,16 +997,56 @@ reports, and the free services that monitor the project.
 
 ## Test suite
 
-Three layers, all enforced (`make check` runs the full set; CI runs the same thing):
+Four layers, all enforced (`make check` runs the full set; CI runs the same thing):
 
 | Layer | What it does | Gate |
 |---|---|---|
 | `make test` | pytest across `tests/unit/` (every core module) and `tests/functional/` (drives all 78 commands in-process against sandboxed homes) | **≥80% line coverage** of `boost_cli` (`fail_under` in pyproject.toml) |
 | `make smoke` | `tests/smoke.sh` — 170 checks run through the actual `./boost` shim (`--online` also hits real registries) | all pass |
 | `make mutation` | [mutmut] mutates `boost_cli/core` (~9,900 mutants) and reruns the unit suite against each one | **≥80% killed** (`scripts/mutation_gate.py`) |
+| `make evals` | scores the search ranker on a graded golden set — recall@5/@10, MRR, nDCG@5/@10 | **metric floors + no statistically significant regression** (`scripts/eval_gate.py`) |
 
 Dev setup: `make venv` (pulls in pytest, coverage, mutmut — the shipped
 runtime itself stays dependency-free). Every test run uses a throwaway
 `$HOME`, so your actual agent configs are never at risk.
 
 [mutmut]: https://mutmut.readthedocs.io/
+
+## Evaluation harness
+
+Search quality is the one thing the suite above can't assert: every test can
+pass while the ranker quietly gets worse. `make evals` measures it. The harness
+is pure stdlib and fully offline — it generates its own corpus of skills, rules,
+and workflows and taps it into a disposable `BOOST_HOME`, so a metric that moves
+can only mean the *ranker* moved. See [`evals/README.md`](evals/README.md).
+
+**Golden set** — [`evals/golden_set.json`](evals/golden_set.json): 36 realistic
+queries with **graded** relevance (3 perfect · 2 useful · 1 marginal) over the
+generated corpus. Generated and validated by `evals/make_golden.py`, which
+refuses a judgment naming a skill the corpus doesn't contain; `--check` fails CI
+on drift, so the file can never disagree with its source.
+
+**Five metrics**, all computed by `evals/metrics.py`:
+
+- **recall@5** / **recall@10** — of everything relevant, what fraction reached the top *k*.
+- **MRR** — 1/rank of the first relevant hit, averaged; sensitive only to the top of the list, which is where people look.
+- **nDCG@5** / **nDCG@10** — graded gain (`2^rel − 1`) with the standard `log2(rank + 1)` discount; the only metric that distinguishes the right results in the wrong order from the right order.
+
+**Significance gating.** A metric dropping isn't automatically a regression —
+with 36 queries, one unlucky result moves the mean. So `scripts/eval_gate.py`
+fails a metric only when it falls more than 0.02 below the committed baseline
+**and** a seeded 10,000-resample paired bootstrap over the per-query deltas puts
+that drop at `p < 0.05`. Alongside that, each metric has an absolute floor set
+~0.05 below its first measured value, which catches the erosion that a
+compare-to-last-commit check never sees. Accepting a real ranking change is a
+deliberate `make evals-baseline` commit.
+
+**Faithfulness.** `boost explain` and `boost distill` generate prose from a
+`SKILL.md`, and their failure mode is overclaiming. The harness scores that with
+the Ragas method — split the answer into atomic statements, verify each against
+the source, score supported/total — and reports it alongside what the runtime
+grounding guardrail in `boost explain` would do with the same reply. With no
+`claude` CLI and no `ANTHROPIC_API_KEY` it **skips rather than fails**, and
+reports a status instead of a number so "couldn't measure" is never mistaken for
+"scored zero". It's therefore outside `make check`; run it with
+`make evals-online`.

{boost_skill_cli-1.0.281 → boost_skill_cli-1.0.283}/boost_skill_cli.egg-info/SOURCES.txt

@@ -232,6 +232,7 @@ 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-aware-skills.md
+docs/roadmap/items/mcp-check-skills-before-starting-a-task.md
 docs/roadmap/items/mcp-hub-diagram-node-text-overflow.md
 docs/roadmap/items/mcp-launch-objc-fork-safety.md
 docs/roadmap/items/mcp-register-names-server-before-env.md
@@ -327,6 +328,15 @@ docs/roadmap/items/workflow-linting-actionlint.md
 docs/roadmap/items/workflow-sast-zizmor.md
 docs/roadmap/items/workspace-scope-install.md
 docs/roadmap/items/zizmor-pin-is-a-yanked-release.md
+evals/README.md
+evals/__init__.py
+evals/baseline.json
+evals/faithfulness.py
+evals/golden_set.json
+evals/make_corpus.py
+evals/make_golden.py
+evals/metrics.py
+evals/run_evals.py
 examples/README.md
 examples/adapt-demo.sh
 examples/boost-run-prototype.sh
@@ -350,6 +360,7 @@ scripts/check_licenses.py
 scripts/check_required_checks.py
 scripts/ensure_eval_corpus.sh
 scripts/eval_explain.py
+scripts/eval_gate.py
 scripts/eval_recommend.py
 scripts/eval_retrieval.py
 scripts/eval_stats_summary.py
@@ -455,6 +466,9 @@ tests/unit/test_docsite_chrome.py
 tests/unit/test_ed25519.py
 tests/unit/test_embed.py
 tests/unit/test_errors_and_cli_table.py
+tests/unit/test_eval_faithfulness.py
+tests/unit/test_eval_gate.py
+tests/unit/test_eval_metrics.py
 tests/unit/test_eval_stats_summary.py
 tests/unit/test_faithfulness.py
 tests/unit/test_frontmatter.py

boost_skill_cli-1.0.283/docs/roadmap/items/mcp-check-skills-before-starting-a-task.md

@@ -0,0 +1,30 @@
+---
+id: mcp-check-skills-before-starting-a-task
+board: code
+section: dx
+status: inflight
+category: Interop · Adoption
+complexity: S
+impact: High
+wow: 3
+note: agent reflex
+order: 64
+owner: mcp-task-entrance
+pr: 318
+title: MCP — check for a skill when a task starts, not only when authoring one
+---
+<a href="#mcp-search-before-reinventing">The previous pass</a> gave the MCP server
+<code>initialize</code> <code>instructions</code> and intent-framed tool descriptions, but
+framed both around a single trigger: <em>before you author a new skill</em>. That is the
+rarer moment. Observed behaviour matched the framing exactly — agents called
+<code>boost_search</code> only when they were already about to write a skill, and never to ask
+whether an installed one covered the work in front of them. The common case, starting
+ordinary work that a vetted skill already handles, had nothing pointing at it.
+Broaden to <strong>two</strong> declared triggers: <em>starting a task</em> (call
+<code>boost_list</code> for what is usable right now, <code>boost_search</code> for what could
+be) and the existing <em>authoring</em> one. <code>boost_list</code> is re-framed from "avoid a
+duplicate install" to "leverage a capability you already have" — it is the free half of the
+check. A closing proportion note bounds it, because an unbounded <em>always check first</em>
+turns every trivial turn into a tool call and an agent that learns to ignore the guidance
+ignores all of it. Both triggers and the bound are pinned by tests, so dropping either
+regresses.

{boost_skill_cli-1.0.281 → boost_skill_cli-1.0.283}/docs/roadmap.html

@@ -110,7 +110,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>4</b><span>Planned</span></div>
-      <div class="stat"><b>173</b><span>Loop finds</span></div>
+      <div class="stat"><b>174</b><span>Loop finds</span></div>
       <!-- /ROADMAP:stats -->
     </div>
   </section>
@@ -3151,6 +3151,32 @@ three states: a <b>failing</b> actionlint now fails <code>make</code> (exit 2) i
           <span class="m">fixed — a failing actionlint now fails make, in all three targets</span>
         </div>
       </article>
+
+      <article class="cap rcard" id="mcp-check-skills-before-starting-a-task">
+        <div class="head"><span class="pill inflight">In flight</span><span class="cat">Interop · Adoption</span></div>
+        <h3>MCP — check for a skill when a task starts, not only when authoring one</h3>
+        <p><a href="#mcp-search-before-reinventing">The previous pass</a> gave the MCP server
+<code>initialize</code> <code>instructions</code> and intent-framed tool descriptions, but
+framed both around a single trigger: <em>before you author a new skill</em>. That is the
+rarer moment. Observed behaviour matched the framing exactly — agents called
+<code>boost_search</code> only when they were already about to write a skill, and never to ask
+whether an installed one covered the work in front of them. The common case, starting
+ordinary work that a vetted skill already handles, had nothing pointing at it.
+Broaden to <strong>two</strong> declared triggers: <em>starting a task</em> (call
+<code>boost_list</code> for what is usable right now, <code>boost_search</code> for what could
+be) and the existing <em>authoring</em> one. <code>boost_list</code> is re-framed from "avoid a
+duplicate install" to "leverage a capability you already have" — it is the free half of the
+check. A closing proportion note bounds it, because an unbounded <em>always check first</em>
+turns every trivial turn into a tool call and an agent that learns to ignore the guidance
+ignores all of it. Both triggers and the bound are pinned by tests, so dropping either
+regresses.</p>
+        <div class="meta">
+          <span class="m">Complexity <b>S</b></span>
+          <span class="m hi">Impact <b>High</b></span>
+          <span class="m">Wow <b class="wow">★★★</b></span>
+          <span class="m">agent reflex</span>
+        </div>
+      </article>
       <!-- /ROADMAP:cards -->
 
     </div>