boost-skill-cli 1.0.142__tar.gz → 1.0.144__tar.gz

{boost_skill_cli-1.0.142 → boost_skill_cli-1.0.144}/PKG-INFO

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

{boost_skill_cli-1.0.142 → boost_skill_cli-1.0.144}/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.142'
-__version_tuple__ = version_tuple = (1, 0, 142)
+__version__ = version = '1.0.144'
+__version_tuple__ = version_tuple = (1, 0, 144)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.142 → boost_skill_cli-1.0.144}/boost_skill_cli.egg-info/PKG-INFO

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

{boost_skill_cli-1.0.142 → boost_skill_cli-1.0.144}/boost_skill_cli.egg-info/SOURCES.txt

@@ -138,6 +138,7 @@ docs/roadmap/items/framework-adapter-multi-agent.md
 docs/roadmap/items/framework-adapters-boost-adapt.md
 docs/roadmap/items/frontmatter-scalar-over-coercion.md
 docs/roadmap/items/github-pages-deploy-is-broken-every-push.md
+docs/roadmap/items/golden-set-statistical-power.md
 docs/roadmap/items/hash-pinned-reproducible-toolchain-uv-lock.md
 docs/roadmap/items/html-validation-html-validate.md
 docs/roadmap/items/integrity-verification-boost-verify.md
@@ -173,6 +174,7 @@ docs/roadmap/items/property-based-tests-hypothesis-on-the-parsers.md
 docs/roadmap/items/prose-and-terminology-linting-vale.md
 docs/roadmap/items/prune-ignored-dirs-during-scan-dir-walk.md
 docs/roadmap/items/quality-dashboard-sonarcloud-free-for-oss.md
+docs/roadmap/items/ranx-significance-monitor.md
 docs/roadmap/items/reconcile-the-theme-drift.md
 docs/roadmap/items/refresh-the-marketing-surface.md
 docs/roadmap/items/retrieval-quality-eval-harness.md
@@ -180,6 +182,7 @@ docs/roadmap/items/reuse-helpers-kill-minor-dead-work.md
 docs/roadmap/items/robust-tag-argument-parsing.md
 docs/roadmap/items/rule-install-native-materialization.md
 docs/roadmap/items/runner-egress-monitoring-stepsecurity-harden-run.md
+docs/roadmap/items/runtime-explain-faithfulness-guardrail.md
 docs/roadmap/items/sbom-aware-scanning-osv-scanner.md
 docs/roadmap/items/sbom-on-every-release-cyclonedx-syft.md
 docs/roadmap/items/scan-and-sync-rules-and-workflows.md
@@ -212,6 +215,7 @@ docs/roadmap/items/workflow-sast-zizmor.md
 docs/roadmap/items/workspace-scope-install.md
 examples/README.md
 examples/adapt-demo.sh
+examples/boost-run-prototype.sh
 scripts/build_registries.py
 scripts/build_roadmap.py
 scripts/ensure_eval_corpus.sh

{boost_skill_cli-1.0.142 → boost_skill_cli-1.0.144}/docs/roadmap/items/boost-run-live-agents.md

@@ -13,4 +13,4 @@ owner:
 pr: 
 title: <code>boost run</code> — search → adapt → a live agent doing the task, in one command
 ---
-The allure ceiling on <code>boost adapt</code> (#146, #163): it stops at <b>source you assemble</b>, and the adapted agent has a brain (prompt) but no <b>hands</b> (tools). Close both. <code>boost run &lt;skill&gt; [target]</code> = adapt → wire a default toolset (file read, ripgrep/shell, web) → execute on boost's model and stream the result. Opt-in like the conformance path (installs the framework + needs a key, so the zero-dep default holds). Two prerequisites ship with it: (1) <b>tool-wiring</b> — emit/attach the tools a skill needs (or declares) so the agent can act, not roleplay; (2) reuse the <a href="../adapters.html">adapt</a> renderer for the agent def. Pairs with <code>[[framework-adapter-multi-agent]]</code> so a skill like <code>rust-review</code> runs as a real crew. This is the screenshot: "one command → an expert agent audits your repo, on Claude, that you never wrote."
+The allure ceiling on <code>boost adapt</code> (#146, #163): it stops at <b>source you assemble</b>, and the adapted agent has a brain (prompt) but no <b>hands</b> (tools). Close both. <code>boost run &lt;skill&gt; [target]</code> = adapt → wire a default toolset (file read, ripgrep/shell, web) → execute on boost's model and stream the result. Opt-in like the conformance path (installs the framework + needs a key, so the zero-dep default holds). Two prerequisites ship with it: (1) <b>tool-wiring</b> — emit/attach the tools a skill needs (or declares) so the agent can act, not roleplay; (2) reuse the <a href="../adapters.html">adapt</a> renderer for the agent def. Pairs with <code>[[framework-adapter-multi-agent]]</code> so a skill like <code>rust-review</code> runs as a real crew. This is the screenshot: "one command → an expert agent audits your repo, on Claude, that you never wrote." <b>Working preview:</b> <code>examples/boost-run-prototype.sh</code> already does this by hand (adapt → wire a read_file tool → <code>Runner.run</code> on a file with planted bugs).

boost_skill_cli-1.0.144/docs/roadmap/items/golden-set-statistical-power.md

@@ -0,0 +1,25 @@
+---
+id: golden-set-statistical-power
+board: code
+section: health
+status: planned
+category: Quality · Retrieval eval
+complexity: M
+impact: High
+wow: 4
+note: 43 → deeper, per-kind
+order: 4
+owner:
+pr:
+title: Grow & diversify the golden set for statistical power
+---
+The golden set (<b>43</b> queries / 8 stacks / 7 skills) is small enough that
+engine comparisons don't yet reach significance — the paired t-test lands at
+<code>p≈0.11–0.26</code> on the pinned corpus, so BM25's numeric lead over the
+heuristic can't be called statistically real. Expand and diversify it: many more
+labelled queries with balanced per-kind coverage (skill / rule / workflow),
+harder near-miss distractors, and judgments for the still-unevaluated surfaces
+(<code>search --smart</code>, <code>detect_stack</code>). Tighter confidence
+intervals mean comparisons that actually reach significance and a gate that
+catches subtler regressions. The single highest-leverage extension of the eval
+harness.

boost_skill_cli-1.0.144/docs/roadmap/items/ranx-significance-monitor.md

@@ -0,0 +1,24 @@
+---
+id: ranx-significance-monitor
+board: code
+section: health
+status: planned
+category: Quality · Retrieval eval
+complexity: S
+impact: Med
+wow: 3
+note: p-value, not point delta
+order: 5
+owner:
+pr:
+title: Significance-tracked engine comparison (ranx monitor)
+---
+Tier 1b (the <code>ranx</code> paired t-test, <code>--stats</code>) only runs on
+demand today. Wire it into a scheduled CI monitor — like the
+<code>eval-explain</code> workflow — that tracks whether BM25's lead over the
+heuristic, and any new engine's lead over BM25, is <em>statistically
+significant</em> rather than merely numerically higher, and flags when a change
+erases a previously-significant win. Stays out of the required stdlib gate (ranx
+is an opt-in <code>[eval]</code> dependency); it's a non-blocking monitor, so a
+noisy p-value can never block a merge. Turns "recall went up 0.02" into "the
+improvement is real (or isn't)."

boost_skill_cli-1.0.144/docs/roadmap/items/runtime-explain-faithfulness-guardrail.md

@@ -0,0 +1,25 @@
+---
+id: runtime-explain-faithfulness-guardrail
+board: code
+section: trust
+status: planned
+category: Trust · Hallucination guard
+complexity: M
+impact: Med
+wow: 4
+note: faithfulness → extractive fallback
+order: 4
+owner:
+pr:
+title: Runtime hallucination guardrail for <code>boost explain</code>
+---
+Today the ragas <b>faithfulness</b> check (Tier 2c, <code>scripts/eval_explain.py</code>)
+is <em>eval-time only</em> — an offline monitor that flags when generated
+explanations drift from their <code>SKILL.md</code>, but never intercepts a live
+response. Promote it to a <b>runtime guardrail</b>: score the generated summary
+against the source and, when it falls below a faithfulness threshold, fall back
+to the deterministic extractive summary <code>cmd_explain</code> already ships
+for the no-AI case (description + outline + key rules) — or append a
+low-confidence caveat. Turns "a human notices the drift next week" into "the
+tool refuses to show an ungrounded explanation," closing the gap between
+detecting hallucinations and preventing them.

{boost_skill_cli-1.0.142 → boost_skill_cli-1.0.144}/docs/roadmap.html

@@ -118,7 +118,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>104</b><span>Loop finds</span></div>
+      <div class="stat"><b>107</b><span>Loop finds</span></div>
       <!-- /ROADMAP:stats -->
     </div>
   </section>
@@ -942,6 +942,27 @@ explanations and safety, not better ranking.</p>
         </div>
       </article>
 
+      <article class="cap rcard">
+        <div class="head"><span class="pill planned">Planned</span><span class="cat">Quality · Retrieval eval</span></div>
+        <h3>Grow &amp; diversify the golden set for statistical power</h3>
+        <p>The golden set (<b>43</b> queries / 8 stacks / 7 skills) is small enough that
+engine comparisons don't yet reach significance — the paired t-test lands at
+<code>p≈0.11–0.26</code> on the pinned corpus, so BM25's numeric lead over the
+heuristic can't be called statistically real. Expand and diversify it: many more
+labelled queries with balanced per-kind coverage (skill / rule / workflow),
+harder near-miss distractors, and judgments for the still-unevaluated surfaces
+(<code>search --smart</code>, <code>detect_stack</code>). Tighter confidence
+intervals mean comparisons that actually reach significance and a gate that
+catches subtler regressions. The single highest-leverage extension of the eval
+harness.</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">43 → deeper, per-kind</span>
+        </div>
+      </article>
+
       <article class="cap rcard">
         <div class="head"><span class="pill planned">Planned</span><span class="cat">Security · Secrets</span></div>
         <h3>Secret scanning — <code>gitleaks</code> + push protection</h3>
@@ -974,6 +995,26 @@ explanations and safety, not better ranking.</p>
         </div>
       </article>
 
+      <article class="cap rcard">
+        <div class="head"><span class="pill planned">Planned</span><span class="cat">Quality · Retrieval eval</span></div>
+        <h3>Significance-tracked engine comparison (ranx monitor)</h3>
+        <p>Tier 1b (the <code>ranx</code> paired t-test, <code>--stats</code>) only runs on
+demand today. Wire it into a scheduled CI monitor — like the
+<code>eval-explain</code> workflow — that tracks whether BM25's lead over the
+heuristic, and any new engine's lead over BM25, is <em>statistically
+significant</em> rather than merely numerically higher, and flags when a change
+erases a previously-significant win. Stays out of the required stdlib gate (ranx
+is an opt-in <code>[eval]</code> dependency); it's a non-blocking monitor, so a
+noisy p-value can never block a merge. Turns "recall went up 0.02" into "the
+improvement is real (or isn't)."</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">p-value, not point delta</span>
+        </div>
+      </article>
+
       <article class="cap rcard">
         <div class="head"><span class="pill planned">Planned</span><span class="cat">Quality · Platform</span></div>
         <h3>Quality dashboard — SonarCloud (free for OSS)</h3>
@@ -1420,7 +1461,7 @@ explanations and safety, not better ranking.</p>
       <article class="cap rcard">
         <div class="head"><span class="pill planned">Planned</span><span class="cat">Interop</span></div>
         <h3><code>boost run</code> — search → adapt → a live agent doing the task, in one command</h3>
-        <p>The allure ceiling on <code>boost adapt</code> (#146, #163): it stops at <b>source you assemble</b>, and the adapted agent has a brain (prompt) but no <b>hands</b> (tools). Close both. <code>boost run &lt;skill&gt; [target]</code> = adapt → wire a default toolset (file read, ripgrep/shell, web) → execute on boost's model and stream the result. Opt-in like the conformance path (installs the framework + needs a key, so the zero-dep default holds). Two prerequisites ship with it: (1) <b>tool-wiring</b> — emit/attach the tools a skill needs (or declares) so the agent can act, not roleplay; (2) reuse the <a href="../adapters.html">adapt</a> renderer for the agent def. Pairs with <code>[[framework-adapter-multi-agent]]</code> so a skill like <code>rust-review</code> runs as a real crew. This is the screenshot: "one command → an expert agent audits your repo, on Claude, that you never wrote."</p>
+        <p>The allure ceiling on <code>boost adapt</code> (#146, #163): it stops at <b>source you assemble</b>, and the adapted agent has a brain (prompt) but no <b>hands</b> (tools). Close both. <code>boost run &lt;skill&gt; [target]</code> = adapt → wire a default toolset (file read, ripgrep/shell, web) → execute on boost's model and stream the result. Opt-in like the conformance path (installs the framework + needs a key, so the zero-dep default holds). Two prerequisites ship with it: (1) <b>tool-wiring</b> — emit/attach the tools a skill needs (or declares) so the agent can act, not roleplay; (2) reuse the <a href="../adapters.html">adapt</a> renderer for the agent def. Pairs with <code>[[framework-adapter-multi-agent]]</code> so a skill like <code>rust-review</code> runs as a real crew. This is the screenshot: "one command → an expert agent audits your repo, on Claude, that you never wrote." <b>Working preview:</b> <code>examples/boost-run-prototype.sh</code> already does this by hand (adapt → wire a read_file tool → <code>Runner.run</code> on a file with planted bugs).</p>
         <div class="meta">
           <span class="m">Complexity <b>L</b></span>
           <span class="m hi">Impact <b>High</b></span>
@@ -1919,6 +1960,27 @@ re-break it.</p>
         </div>
       </article>
 
+      <article class="cap rcard">
+        <div class="head"><span class="pill planned">Planned</span><span class="cat">Trust · Hallucination guard</span></div>
+        <h3>Runtime hallucination guardrail for <code>boost explain</code></h3>
+        <p>Today the ragas <b>faithfulness</b> check (Tier 2c, <code>scripts/eval_explain.py</code>)
+is <em>eval-time only</em> — an offline monitor that flags when generated
+explanations drift from their <code>SKILL.md</code>, but never intercepts a live
+response. Promote it to a <b>runtime guardrail</b>: score the generated summary
+against the source and, when it falls below a faithfulness threshold, fall back
+to the deterministic extractive summary <code>cmd_explain</code> already ships
+for the no-AI case (description + outline + key rules) — or append a
+low-confidence caveat. Turns "a human notices the drift next week" into "the
+tool refuses to show an ungrounded explanation," closing the gap between
+detecting hallucinations and preventing them.</p>
+        <div class="meta">
+          <span class="m">Complexity <b>M</b></span>
+          <span class="m">Impact <b>Med</b></span>
+          <span class="m">Wow <b class="wow">★★★★</b></span>
+          <span class="m">faithfulness → extractive fallback</span>
+        </div>
+      </article>
+
       <article class="cap rcard">
         <div class="head"><span class="pill shipped">Shipped</span><span class="cat">Security · Registry</span></div>
         <h3>Typosquat &amp; name-confusion detection</h3>

{boost_skill_cli-1.0.142 → boost_skill_cli-1.0.144}/examples/README.md

@@ -35,3 +35,23 @@ wheel yet; boost itself supports 3.9–3.14). Clean up with
 > The same import path is exercised in CI by
 > [`.github/workflows/adapter-conformance.yml`](../.github/workflows/adapter-conformance.yml),
 > which installs each real framework and asserts the emitted file instantiates.
+
+## `boost-run-prototype.sh` — a preview of `boost run`
+
+A hand-built preview of the planned [`boost run`](../docs/roadmap.html) feature
+(`boost adapt` gives an agent a *brain*, but no *hands*). It shows the
+"one command → a live agent doing the task" wow, built on today's `boost adapt`:
+
+```bash
+ANTHROPIC_API_KEY=sk-ant-... bash examples/boost-run-prototype.sh
+```
+
+1. Authors a `code-reviewer` skill and `boost adapt`s it to the Agents SDK,
+   wired to boost's model (Claude) — **the brain**.
+2. Attaches a `read_file` `@function_tool` — **the hands** the skill needs to act.
+3. `Runner.run`s it against a file with two planted bugs (a `KeyError` and a SQL
+   injection) and prints the agent's actual review.
+
+Everything up to the run is offline; only the final `Runner.run` needs
+`ANTHROPIC_API_KEY`. This is the thinnest slice of what a shipped `boost run`
+would fold into a single command — see the `boost-run-live-agents` roadmap item.

boost_skill_cli-1.0.144/examples/boost-run-prototype.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# boost-run-prototype.sh — the thinnest slice of a future `boost run`.
+#
+# Shows the "one command → a live agent doing the task" wow that turns
+# `boost adapt` from a code generator into an outcome:
+#
+#     search/author a skill  →  boost adapt (the brain)
+#                            →  + a file-read tool (the hands)
+#                            →  Runner.run on boost's model (Claude)
+#                            →  a real review of a real file
+#
+# boost adapt gives the agent DEFINITION; this script adds a tool and executes
+# it — exactly what a shipped `boost run` would fold into one command.
+#
+# Needs ANTHROPIC_API_KEY for the actual run (everything before it is offline).
+# Sandboxed on HOME; clean up with:  rm -rf "${DEMO_DIR:-/tmp/boost-run-demo}"
+#
+# Usage:  ANTHROPIC_API_KEY=sk-ant-... bash boost-run-prototype.sh
+set -euo pipefail
+
+DEMO="${DEMO_DIR:-/tmp/boost-run-demo}"
+SKILL="code-reviewer"
+PYBIN=""
+for v in 3.13 3.12 3.11; do PYBIN="$(command -v "python$v" || true)"; [ -n "$PYBIN" ] && break; done
+[ -n "$PYBIN" ] || { echo "Need python3.11-3.13 (LiteLLM/tiktoken); brew install python@3.13"; exit 1; }
+
+c()  { printf '\n\033[1;36m== %s ==\033[0m\n' "$*"; }
+dim(){ printf '\033[2m%s\033[0m\n' "$*"; }
+ok() { printf '\033[1;32m%s\033[0m\n' "$*"; }
+
+c "1/4  sandbox + install (boost + openai-agents[litellm])"
+rm -rf "$DEMO"; mkdir -p "$DEMO"; export HOME="$DEMO/home"; mkdir -p "$HOME"
+"$PYBIN" -m venv "$DEMO/.venv"
+BOOST="$DEMO/.venv/bin/boost"; PY="$DEMO/.venv/bin/python"
+dim "installing … (~2-3 min first run)"
+"$DEMO/.venv/bin/pip" -q install -U boost-skill-cli "openai-agents[litellm]"
+
+c "2/4  a skill = the agent's brain (author locally; or 'boost search' any catalog skill)"
+mkdir -p "$DEMO/src/$SKILL"
+cat > "$DEMO/src/$SKILL/SKILL.md" <<'MD'
+---
+name: code-reviewer
+description: Reviews a file for correctness, security, and error handling
+---
+You are a precise code reviewer. Use the read_file tool to read the file you are
+asked to review, then list concrete issues as a short bulleted list — each with
+the line and a one-line fix. Focus on real bugs (crashes, unhandled errors,
+injection, missing checks). Be terse.
+MD
+"$BOOST" import "$DEMO/src/$SKILL" >/dev/null
+"$BOOST" adapt "$SKILL" --to agents-sdk -o "$DEMO/agent_def.py"    # wired to boost's model
+ok "adapted '$SKILL' → agent_def.py (on boost's model, Claude)"
+
+# a target file with an obvious bug for the agent to actually find
+cat > "$DEMO/target.py" <<'PY'
+def get_user(users, uid):
+    # BUG: no membership check — KeyError on unknown uid
+    return users[uid]
+
+def run_query(db, name):
+    # BUG: SQL built by string concat — injection
+    return db.execute("SELECT * FROM users WHERE name = '" + name + "'")
+PY
+dim "target file with two planted bugs: $DEMO/target.py"
+
+c "3/4  give the brain HANDS (a read_file tool) — what a shipped 'boost run' would wire"
+cat > "$DEMO/run.py" <<'PY'
+import pathlib, sys
+import agent_def
+from agents import Agent, Runner, function_tool
+
+base = next(v for v in vars(agent_def).values() if isinstance(v, Agent))  # the adapted agent
+
+@function_tool
+def read_file(path: str) -> str:
+    """Read a text file and return its contents."""
+    return pathlib.Path(path).read_text()[:8000]
+
+# boost gave the brain (instructions + model); we add the hands (tools)
+reviewer = Agent(name=base.name, instructions=base.instructions,
+                 model=base.model, tools=[read_file])
+print(f"  wired agent: {reviewer.name}  model={reviewer.model.model}  tools={[t.name for t in reviewer.tools]}")
+
+target = sys.argv[1] if len(sys.argv) > 1 else "target.py"
+result = Runner.run_sync(reviewer, f"Review the file at {target}.")
+print("\n----- review -----\n" + result.final_output)
+PY
+
+c "4/4  RUN it — a live agent reviewing the file, on Claude"
+cd "$DEMO"
+if [ -n "${ANTHROPIC_API_KEY:-}" ]; then
+  "$PY" run.py target.py
+  ok "^ an agent you searched/authored, wired with a tool, found the bugs — on boost's model"
+else
+  # still prove the wiring works with no key
+  "$PY" - <<'PY'
+import agent_def
+from agents import Agent, function_tool
+import pathlib
+base = next(v for v in vars(agent_def).values() if isinstance(v, Agent))
+@function_tool
+def read_file(path: str) -> str: return pathlib.Path(path).read_text()
+reviewer = Agent(name=base.name, instructions=base.instructions, model=base.model, tools=[read_file])
+print(f"  wired agent: {reviewer.name}  model={reviewer.model.model}  tools={[t.name for t in reviewer.tools]}")
+print("  \033[1;32m✓ agent + tool constructed (no key). Set ANTHROPIC_API_KEY to see it review.\033[0m")
+PY
+  dim "  run for real:  ANTHROPIC_API_KEY=sk-ant-... bash $0"
+fi
+
+c "done"
+dim "artifacts in $DEMO :  agent_def.py (from boost adapt)  run.py (the +tools+run wrapper)  target.py"
+dim "clean up:  rm -rf $DEMO"