boost-skill-cli 1.0.214__tar.gz → 1.0.216__tar.gz

{boost_skill_cli-1.0.214 → boost_skill_cli-1.0.216}/CLAUDE.md

@@ -4,6 +4,36 @@ boost is a "Homebrew for AI coding skills": a Python CLI (`boost_cli`) that find
 installs, and governs the skill/rule/workflow files that AI coding agents run on.
 Package name on PyPI is `boost-skill-cli`; the command is `boost`.
 
+## Common commands
+
+```bash
+make venv                                      # .venv from the hash-pinned requirements/*.txt
+.venv/bin/pytest tests/unit/test_catalog.py -q                    # one test file
+.venv/bin/pytest tests/unit/test_catalog.py::test_scan_dir -q     # one test
+.venv/bin/pytest tests/functional -q -k install                   # functional tests matching "install"
+make lint                                      # the whole static tier — see the recipe, it is 18 commands
+make test                                      # unit + functional with 80% coverage gate
+make check                                     # the full required gate — see table below
+
+# run boost itself against a disposable HOME (never your real ~/.boost):
+export HOME=/tmp/boost-sandbox && mkdir -p $HOME
+python3 tests/make_fixture.py /tmp/fixture-tap
+./boost tap /tmp/fixture-tap
+./boost install brainstorming
+./boost doctor
+```
+
+`make venv` installs from `requirements/*.txt`, which are hash-pinned and are the
+same files CI installs (`scripts/lock_toolchain.py --check` gates them against
+drift) — so a dev venv and a runner resolve to identical bytes. Don't `pip
+install` a lint or test tool by hand; add it to the right requirements file and
+regenerate the lock, or `make lint` passes for you and fails in CI.
+
+The functional/unit `sandbox` fixture (`tests/conftest.py`) also sets
+`BOOST_NO_AI=1` and `BOOST_ASSUME_YES=1` so tests are deterministic and never
+block on a confirm prompt or a real AI call — override explicitly in a test
+that means to exercise the AI or confirmation path.
+
 ## The one gate that matters
 
 Before calling any change done, run the full gate:
@@ -124,9 +154,57 @@ Both boards are data-driven: `docs/roadmap.html` from `board: code` items and
 into the per-track sections; the filter JS and counters are computed). Same rule
 for both — edit items, run `build_roadmap.py`, never touch the HTML by hand.
 
+## Architecture
+
+**CLI dispatch.** `boost_cli/cli.py` holds `COMMANDS`, the single
+source-of-truth list of `(name, group, module, summary)` for all 78 commands.
+Each command is implemented as `def cmd_<name_with_underscores>(argv) -> int`
+inside `boost_cli/commands/<module>.py`, and `_dispatch` imports that module
+lazily on invocation — so `boost --help` stays instant and command modules are
+decoupled from each other. To add a command: add a row to `COMMANDS`, add the
+`cmd_*` function to the named module, and it's live. `docs/commands.html` is
+**generated** from `COMMANDS` by `scripts/build_command_reference.py`, so a new
+row means regenerating it (`make generate`) or the `--check` gate fails.
+
+**commands/ vs core/.** `boost_cli/commands/` is thin CLI glue — argument
+parsing, output formatting, calling into `core/`. `boost_cli/core/` is the
+actual engine (catalog scanning, install/link logic, the lock file, registries,
+search) and is what the mutation gate targets — put behavior there, not in
+the command layer, so it's covered by both the unit suite and mutation
+testing.
+
+**Storage layout**, all resolved at call time from `$HOME` (or `$BOOST_HOME`)
+in `boost_cli/core/paths.py`, which is what makes `HOME=<tempdir>` sandboxing
+work in tests and the dev loop:
+
+```text
+~/.boost/repos/     shallow git clones of tapped registries
+~/.boost/cache/     JSON catalogs built from SKILL.md/rule/workflow frontmatter
+~/.boost/logs/      rotating diagnostic log + crash reports
+~/.boost/state/     pins, tags, policy, profiles, pulse feed, snapshots
+~/.boost/config.json
+~/.agents/skills/                canonical store — single source of truth for installed skills
+~/.agents/skills/.skill-lock.json   v3 lock file
+~/.claude/skills/  ~/.windsurf/skills/  ~/.cursor/skills/   symlinked out from the canonical store
+```
+
+`core/catalog.scan_dir` walks a tap's clone and classifies each file into one
+of the three item kinds (see Non-obvious rules above); `core/store.py` owns
+install, uninstall and sync — copying into the canonical store, symlinking into
+each agent's skills dir, and updating the lock file.
+
+**Search has two engines**, both in `core/`: `rag.py` is the always-on,
+zero-dependency BM25 engine (full-content index, auto-builds on first
+search — this is what the required `eval` gate floors at recall@k ≥ 0.85).
+`dense.py` is optional dense/vector retrieval behind the `[rag]` extra plus
+an embeddings key (`VOYAGE_API_KEY`/`OPENAI_API_KEY`); it's used when both
+are present and falls back to BM25 otherwise. `core/ai.py` wraps the
+opt-in LLM-assisted paths (`search --smart`, `explain`, `distill`, `infer`,
+`absorb`, `evolve`, `simulate`, …), shelling out to the `claude` CLI or
+`ANTHROPIC_API_KEY` when available and degrading to heuristics when not.
+
 ## Layout
 
-- `boost_cli/commands/` — CLI command groups   · `boost_cli/core/` — engine (the mutation-gated code)
 - `boost_cli/data/` — shipped catalog data (generated)   · `scripts/` — build/gate tooling
 - `tests/unit`, `tests/functional`, `tests/smoke.sh` — the three test tiers
-- `docs/` — `overview.html` (visual guide), `DEBUGGING.md`; `roadmap.html` is generated from `docs/roadmap/items/*.md` (see above)
+- `docs/` — `index.html` (visual guide), `commands.html` (every flag, generated), `DEBUGGING.md`; `roadmap.html` is generated from `docs/roadmap/items/*.md` (see above)

{boost_skill_cli-1.0.214/boost_skill_cli.egg-info → boost_skill_cli-1.0.216}/PKG-INFO

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

{boost_skill_cli-1.0.214 → boost_skill_cli-1.0.216}/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.214'
-__version_tuple__ = version_tuple = (1, 0, 214)
+__version__ = version = '1.0.216'
+__version_tuple__ = version_tuple = (1, 0, 216)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.214 → boost_skill_cli-1.0.216/boost_skill_cli.egg-info}/PKG-INFO

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

{boost_skill_cli-1.0.214 → boost_skill_cli-1.0.216}/boost_skill_cli.egg-info/SOURCES.txt

@@ -210,6 +210,7 @@ docs/roadmap/items/localize-the-stored-bm25-snippet.md
 docs/roadmap/items/lockfile-enforcement-and-commit-pinning.md
 docs/roadmap/items/log-timestamps-mislabeled-utc.md
 docs/roadmap/items/lowest-version-resolution-uv-resolution-lowest-d.md
+docs/roadmap/items/main-has-no-branch-protection.md
 docs/roadmap/items/make-the-roadmaps-discoverable.md
 docs/roadmap/items/markdown-consistency-markdownlint-cli2.md
 docs/roadmap/items/mcp-aware-skills.md
@@ -259,6 +260,7 @@ 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
+docs/roadmap/items/scorecard-findings-triage.md
 docs/roadmap/items/second-type-checker-pyright.md
 docs/roadmap/items/secret-and-pii-scanning-of-installed-skills.md
 docs/roadmap/items/secret-scanning-gitleaks-push-protection.md

boost_skill_cli-1.0.216/docs/roadmap/items/main-has-no-branch-protection.md

@@ -0,0 +1,32 @@
+---
+id: main-has-no-branch-protection
+board: code
+section: pipeline
+status: planned
+category: Release safety
+complexity: S
+impact: High
+wow: 3
+note: nothing enforces the red-merge rule
+order: 14
+owner:
+pr:
+title: <code>main</code> has no branch protection, so the release rules are honour-system
+---
+<code>GET /branches/main/protection</code> returns <b>"Branch not protected"</b>. Scorecard
+flags it (<code>BranchProtectionID</code>, score 0), but the sharper way to see it is this:
+CLAUDE.md says <i>"never merge onto a red release"</i> and <i>"every merge to main cuts a
+PyPI release"</i> — and <b>nothing enforces either</b>. A merge with a red gate succeeds
+silently, and the release workflow then ships that commit to PyPI. The rule exists only in
+the head of whoever is merging.
+This is a <b>decision, not a bug</b>, which is why it is filed rather than fixed. Requiring
+status checks would have stopped the exact situation that occurred on
+2026-07-25, when three PRs sat red on a <code>lock_toolchain --check</code> failure that
+belonged to none of them. But protection cuts both ways here: the repo's whole working model
+is parallel <code>loop/*</code> branches opening and merging their own PRs, so
+<b>"require pull request reviews"</b> would deadlock every loop (there is no second
+reviewer), and that same absence is what keeps <code>CodeReviewID</code> pinned at 0/30.
+The shape that fits: require <b>status checks</b> to pass (at minimum <code>ci / lint</code>
+and <code>ci / tests</code>) and require branches to be up to date, but do <b>not</b>
+require reviews. That enforces the release rule that actually matters while leaving
+self-merge intact. Decide before adding more concurrent loops, not after.

boost_skill_cli-1.0.216/docs/roadmap/items/scorecard-findings-triage.md

@@ -0,0 +1,38 @@
+---
+id: scorecard-findings-triage
+board: code
+section: pipeline
+status: planned
+category: Supply chain
+complexity: M
+impact: Med
+wow: 2
+note: 15 open · 3 fixed, 4 intentional, 5 not code-fixable
+order: 13
+owner:
+pr:
+title: OpenSSF Scorecard's 15 findings, triaged into three piles
+---
+Scorecard files into the same code-scanning inbox as CodeQL, so its findings read like
+code defects and get ignored alongside the false positives. They are not defects — they
+are <b>posture metrics</b>, and they must not be dismissed as "false positive" the way the
+<code>serve.py</code> traversal alerts legitimately were, because that misrepresents the
+repo's security posture. Triaged 2026-07-25:
+<b>Fixed</b> — <code>TokenPermissions</code> #26/#27/#28: <code>ci</code>,
+<code>codeql</code> and <code>adapter-conformance</code> had no top-level
+<code>permissions:</code> block at all, scoring 0. Added <code>contents: read</code> as the
+least-privilege default.
+<b>Intentional, leave</b> — <code>TokenPermissions</code> #39/#37/#25/#24:
+<code>publish.yml</code> needs <code>contents: write</code> to create the release and tag,
+<code>osv-scanner</code> needs <code>security-events: write</code> to upload SARIF, and
+<code>ci.yml</code>'s <code>tests</code> job needs <code>contents: write</code> for the
+coverage-badge push. "Fixing" these breaks the release pipeline. They should be
+<b>dismissed as used-in-tests/acceptable-risk with a reason</b>, not left open to rot the list.
+<b>Not code-fixable</b> — <code>MaintainedID</code> is repository age; <code>CodeReviewID</code>
+counts approved changesets and is structurally 0 while loops self-merge;
+<code>CIIBestPracticesID</code> is an opt-in badge programme; the four
+<code>PinnedDependencies</code> hits are <code>npx</code> and <code>pip</code> invocations
+inside steps, not actions, so SHA-pinning does not apply to them as written.
+<code>BranchProtectionID</code> is tracked separately in
+<a href="#main-has-no-branch-protection">its own card</a> — it is a workflow decision, not a
+config oversight.

{boost_skill_cli-1.0.214 → boost_skill_cli-1.0.216}/docs/roadmap.html

@@ -109,7 +109,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>143</b><span>Loop finds</span></div>
+      <div class="stat"><b>145</b><span>Loop finds</span></div>
       <!-- /ROADMAP:stats -->
     </div>
   </section>
@@ -1725,6 +1725,68 @@ path is never used — that fixes the behaviour without satisfying Dependabot's
           <span class="m">dismissed as tolerable risk, 2026-07-25</span>
         </div>
       </article>
+
+      <article class="cap rcard" id="scorecard-findings-triage">
+        <div class="head"><span class="pill planned">Planned</span><span class="cat">Supply chain</span></div>
+        <h3>OpenSSF Scorecard's 15 findings, triaged into three piles</h3>
+        <p>Scorecard files into the same code-scanning inbox as CodeQL, so its findings read like
+code defects and get ignored alongside the false positives. They are not defects — they
+are <b>posture metrics</b>, and they must not be dismissed as "false positive" the way the
+<code>serve.py</code> traversal alerts legitimately were, because that misrepresents the
+repo's security posture. Triaged 2026-07-25:
+<b>Fixed</b> — <code>TokenPermissions</code> #26/#27/#28: <code>ci</code>,
+<code>codeql</code> and <code>adapter-conformance</code> had no top-level
+<code>permissions:</code> block at all, scoring 0. Added <code>contents: read</code> as the
+least-privilege default.
+<b>Intentional, leave</b> — <code>TokenPermissions</code> #39/#37/#25/#24:
+<code>publish.yml</code> needs <code>contents: write</code> to create the release and tag,
+<code>osv-scanner</code> needs <code>security-events: write</code> to upload SARIF, and
+<code>ci.yml</code>'s <code>tests</code> job needs <code>contents: write</code> for the
+coverage-badge push. "Fixing" these breaks the release pipeline. They should be
+<b>dismissed as used-in-tests/acceptable-risk with a reason</b>, not left open to rot the list.
+<b>Not code-fixable</b> — <code>MaintainedID</code> is repository age; <code>CodeReviewID</code>
+counts approved changesets and is structurally 0 while loops self-merge;
+<code>CIIBestPracticesID</code> is an opt-in badge programme; the four
+<code>PinnedDependencies</code> hits are <code>npx</code> and <code>pip</code> invocations
+inside steps, not actions, so SHA-pinning does not apply to them as written.
+<code>BranchProtectionID</code> is tracked separately in
+<a href="#main-has-no-branch-protection">its own card</a> — it is a workflow decision, not a
+config oversight.</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">15 open · 3 fixed, 4 intentional, 5 not code-fixable</span>
+        </div>
+      </article>
+
+      <article class="cap rcard" id="main-has-no-branch-protection">
+        <div class="head"><span class="pill planned">Planned</span><span class="cat">Release safety</span></div>
+        <h3><code>main</code> has no branch protection, so the release rules are honour-system</h3>
+        <p><code>GET /branches/main/protection</code> returns <b>"Branch not protected"</b>. Scorecard
+flags it (<code>BranchProtectionID</code>, score 0), but the sharper way to see it is this:
+CLAUDE.md says <i>"never merge onto a red release"</i> and <i>"every merge to main cuts a
+PyPI release"</i> — and <b>nothing enforces either</b>. A merge with a red gate succeeds
+silently, and the release workflow then ships that commit to PyPI. The rule exists only in
+the head of whoever is merging.
+This is a <b>decision, not a bug</b>, which is why it is filed rather than fixed. Requiring
+status checks would have stopped the exact situation that occurred on
+2026-07-25, when three PRs sat red on a <code>lock_toolchain --check</code> failure that
+belonged to none of them. But protection cuts both ways here: the repo's whole working model
+is parallel <code>loop/*</code> branches opening and merging their own PRs, so
+<b>"require pull request reviews"</b> would deadlock every loop (there is no second
+reviewer), and that same absence is what keeps <code>CodeReviewID</code> pinned at 0/30.
+The shape that fits: require <b>status checks</b> to pass (at minimum <code>ci / lint</code>
+and <code>ci / tests</code>) and require branches to be up to date, but do <b>not</b>
+require reviews. That enforces the release rule that actually matters while leaving
+self-merge intact. Decide before adding more concurrent loops, not after.</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">nothing enforces the red-merge rule</span>
+        </div>
+      </article>
       <!-- /ROADMAP:cards -->
 
     </div>