Every finding from the autonomous quality loop lands here — what shipped, what's mid-flight, and what's queued — scored by complexity, impact, and a little bit of wow.
Shipped in #65 (this card lingered as "next" after the fact).
core/lockfile.py now writes through util.atomic_write_text
(temp file + os.replace()) and read() tells "empty"
apart from "corrupt": an unparseable lock is preserved as <lock>.corrupt
and surfaced loudly rather than silently overwritten, so an interrupted or
concurrent write can no longer drop every prior install record.
Fixed by #60: the bogus mutants/None gitlink (a stray mutmut
artifact with no .gitmodules entry) that made Pages' submodule
checkout abort with fatal: No url found for submodule path 'mutants/None'
is gone. Verified: the Pages "build and deployment" now completes successfully and
the site serves — the boards live at
jonnyeclectic.github.io/boost/docs/roadmap.html (200), since Pages
publishes from the repo root.
core/store.pyCut mutmut survivors 54 → 29 and uncovered a latent
timestamp-preservation bug the old tests masked (second-precision
now_iso() collisions hid installed_at/tags
preservation mutants).
core/gitutil.py35 → 1 survivor via argv-assertion tests that record the exact
git command line — sidestepping the macOS case-insensitive filesystem
that let HEAD/head, .git/.GIT and
git/GIT mutants survive against a real repo.
Shipped in #60. The generated mutants/**,
__pycache__/*.pyc and .coverage files were removed from
the index (verified: git ls-files now tracks zero of them), so they
no longer churn every diff or force path-scoped git adds.
browse crashes when you pick a rule or workflowcmd_browse lists every catalog entry — skills, rules
and workflows — then called store.install(picked)
unconditionally, so selecting a rule or workflow raised
… is a workflow, which boost indexes but cannot install yet and the
TUI exited with a fatal Error: after the user had already navigated
and chosen (reported from a real boost browse session on
AGENT-playbook-to-automated-agent-workflow). Fixed in #118:
the install call now catches BoostError and renders the message +
hint as a friendly non-fatal notice (exit 0), so a non-skill pick — or an
already-installed / pinned skill — no longer crashes the browser. Covered by a
regression test that picks a workflow and asserts no fatal exit.
The "is this skill outdated" decision — semver_gt → commit compare → sha256_dir vs lock — was reimplemented nearly verbatim in cmd_update, cmd_outdated and _drift_status — three copies of core business logic that would drift apart. It now lives in one place: core/staleness.py exposes two pure (I/O-free) decisions — upstream_reason() (the version→commit→content ladder rendered by cmd_update/cmd_outdated) and drift_state() (the store/local-edits/upstream ladder rendered by _drift_status). The commands became thin renderers; behavior is byte-for-byte preserved and the new module is fully unit-tested (every branch pinned, all mutants killed).
core/frontmatter.py34 → 11 survivors with exact-equality tests, replacing
substring in checks a mutated string literal still
satisfied (e.g. dump()'s XX%s:XX still
contains tags:).
core/dense.pyThe dense-vector RAG backend's whole test module is
skipif-gated on the [rag] sqlite-vec C
extension, so on the default zero-dependency install
every degradation and ranking path went untested
(17.6% → 89% coverage). New tests force
_load() → None and drive the SQL helpers and
retrieve()'s cosine reducer through in-memory/fake
connections — killing mutants on every machine, extension or not.
core/logs.pyThe black-box diagnostic logger swallows every filesystem/handler
failure so a broken log can never break the CLI — but those
except arms (the parts that matter most during a
crash) were the least exercised. New tests force each failure —
handler close() raising, a read-only log dir, an
unresolvable version, a wedged logger, unlink denied —
taking the module to 100% coverage.
configuration.py~200 lines implementing a full HTTP catalog server and a JSON-RPC 2.0 MCP
server lived inside the "configuration" command module — nearly untestable in
place. The JSON-RPC protocol now lives in core/mcp.py as a pure
handle_request(req, *, version, registry) plus a
serve_stdio() loop with injectable stdin/stdout; the HTTP server
moved to a new core/serve.py with a pure route()
function, serve_page()/skill_text(), and
serve_http(). cmd_serve and cmd_mcp --stdio
became thin wrappers. Behavior is preserved exactly (the full-server and
stdio-protocol functional tests pass unchanged) and the extracted core is pinned
by new unit tests covering every branch.
The loop now runs commit → PR → green CI → squash-merge → release in a
dedicated ~/boost-loop git worktree (own venv for mutmut),
and modern git 2.55 replaced a 2017 build that
fatally choked on the global zdiff3 config.
self-update version detection (dead branch)boost self-update greped __init__.py for a
__version__ = "…" literal that setuptools-scm never
writes, so the regex never matched and it always reported
"already up to date" — even after a pull brought a newer tag.
The success path was unreachable. It now derives the pulled
version straight from git (describe --tags, mirroring
_detect_version()) and treats a moved HEAD
as the "an update landed" signal, so the version-bump path finally
fires. Regression tests cover both the up-to-date and update-landed
branches.
-- guard on git commandsclone_shallow passed the clone URL as a positional with no
-- separator, so a value beginning with -
could be read as a git flag, and git's remote-helper transports
(ext::sh -c …, file::, fd::)
can execute arbitrary commands straight from a URL. Now it refuses
those transports outright and passes -- before the URL
so option parsing can't be hijacked — argument-injection
defense-in-depth beside registry.parse_spec. Kept scoped
to the one primitive that takes a user-influenced URL (the refs in
pull/reset are constants, and --
there would wrongly mean a pathspec). Six tests, mutation-verified.
A native abort (e.g. a macOS Obj-C fork-safety SIGABRT) kills the
process outright, so it never reaches boost's Python crash recorder —
leaving no boost-side trace to confirm or clear boost when an OS crash
report appears. log_invocation now records
pid, ppid and the interpreter path on every
run, so any OS crash report can be cross-referenced by PID: if the
crashing PID never appears in ~/.boost/logs/boost.log,
boost is definitively ruled out.
Shipped in #126. The byte-identical _user() getpass helper —
copy-pasted three times across core/journal.py,
commands/configuration.py and commands/team.py — is now a
single public core/util.user() the three call sites delegate to
(covered incl. the getpass-raises fallback). cmd_simulate also parsed
the same frontmatter twice (_, body = … then
meta, _ = …); collapsed to one
meta, body = frontmatter.parse(text).
cmd_migrate's two-agent validation is intentionally left as-is —
its first-fail wording differs from _check_agents' collect-all
message, so routing it through the helper would change user-facing errors.
docs/index.html inlines its own amber/orange palette
instead of the canonical Aurora cyan→violet→pink system in
style/boost.css. Move it onto the shared stylesheet so
one token edit recolours the guide, roadmap, and demo together.
core/Work down the remaining survivor counts, biggest first: catalog (27), util (26), ai (21), registry (20), lockfile (13), policy (12), config (9), output (8), agents (6), paths (4).
commands/ under mutation testingThe ~5,000-line CLI command layer has zero mutation
coverage today — mutmut is scoped to core/ only. Extend
the gate (or a second gate) to the command groups.
Drive docs/index.html in a real browser across breakpoints
to confirm the glass cards, aurora, and terminal windows render
cleanly — and to catch anything the theme reconciliation shifts.
Re-record docs/demo.gif from demo.tape against
the current CLI, tighten the README hero, and give the landing page a
flashier first impression that matches the Aurora theme.
config.load() in-processEvery config.get() re-reads config.json and runs a recursive deepcopy of DEFAULTS (core/config.py:80–102). It's called all over hot paths — ai.enabled, per-skill enabled_agents in sync loops, log-level and policy checks — so one command triggers dozens of full reads + deep-copies. Cache the load, invalidate on save.
Already shipped: core/store.py's _copy_skill stages the
full copy in a temp dir on the same filesystem, then swaps it in with
two atomic os.replace renames and rolls back to the original
on any failure — the old rmtree-then-copytree window is gone. Covered by
test_copytree_failure_preserves_existing and the flaky
os.replace test in tests/unit/test_store.py.
journal._maybe_rotate is a racy read-modify-write that concurrent appends can truncate mid-line; rag._save and config.save repeat the non-atomic pattern (journal.py:63 · rag.py:252 · config.py:93). Factor a single atomic_write into core and route all four through it.
_tilde() — two copies have a boundary bugEight command modules each define _tilde; the quality and intelligence versions use startswith(home) with no separator check (quality.py:78), so /Users/bob-backup wrongly contracts to ~-backup. Collapse to one helper in core/paths.
rag.retrieve() calls all_entries(), which reads & json.loads every tap cache on every search to build the live map (rag.py:323 · catalog.py:166–181) — the BM25 index is mtime-cached, the entry set is not. Memoize the entry set on cache mtime the same way.
catalog.search computes json.dumps(meta).lower() for every entry on every query just to substring-match (catalog.py:222). Precompute a lowercased search blob at index time, or match structured fields directly.
scan_dir walkTwo full rglob passes descend into .git/node_modules and only filter afterward, and the skill-dir membership test is O(files × skill_dirs) (catalog.py:106,119–123). Switch to an os.walk that prunes ignored dirs in place; index skill dirs in a set.
Shipped in #140. The canonical detect_stack prober — a
~75-line pure function that lived in the command module
commands/discovery.py yet was imported across the command layer by
both intelligence and quality — now lives in one place:
a new pure core module core/stackprobe.py (with its private
_SKIP_DIRS/_EXT_LANGS/_read_text helpers,
used nowhere else). Every consumer imports the single core prober;
discovery re-exports it for compatibility, and the now-dead helpers
+ unused os import were removed from it. Covered by 16 new
mutation-gated unit tests. The consumer-local enrichment fallbacks
(_local_stack, _STACK_MARKERS) are intentionally kept —
they add coarse filesystem signal the language-only prober doesn't.
Three separate regexes scan SKILL.md bodies for "Always / Never / Must / Do not" lines across cmd_explain, simulate and conflict (info.py:363 · intelligence.py:254 · quality.py:822) — same concept, three implementations. Extract one shared core extractor.
quality.py (15 cmds / 1,264 lines) mixes audit regexes, conflict NLP, decay scoring, fingerprinting, a health dashboard and tap-provenance; intelligence.py and configuration.py are similarly overloaded. Split along cohesive seams to shrink blast radius. First seam (this PR): lift the installed-skill safety & integrity commands — audit, verify, attest, quarantine — into commands/safety.py, with the two shared helpers in commands/_common.py; quality.py drops from 1,264 to ~955 lines. Tap-side trust and the health/diagnostics set stay put.
tag argument parsingBecause -tag looks like an option, cmd_tag calls parse_known_args then re-walks raw argv to reorder tokens (info.py:575–584) — fragile enough that the comment calls it "defensive". Replace with a positional-only sub-parser or an explicit --add/--remove design.
_make_docs stored piece[:200] — the head of the best
chunk — and retrieve surfaced it verbatim, yet the docstrings
promised the "best-matching passage": when the matched terms sat past the
chunk's first 200 chars, the shown snippet (and the rerank context fed to the
LLM) missed them entirely. Now the index stores a larger head of the matched
chunk (SNIP_STORE) and retrieve windows a
SNIP_WIDTH-char passage centered on the first query term,
with ellipsis markers on trimmed edges (_passage). Ranking is
untouched — the eval harness confirms recall@10 holds at
0.919 — and the index grows a bounded ~34% (an
INDEX_VERSION bump forces the one-time reindex); storing whole
chunks instead cost ~70%.
Already shipped: core/frontmatter._scalar coerces only the YAML 1.2
core keywords (true/false/null/~);
the 1.1 aliases yes/no/on/off/none stay strings, so a skill
named none or tagged on keeps the right type.
Guarded by test_scalar_leaves_yaml11_aliases_as_strings.
Today store.install refuses every non-skill kind
("rules and workflows show up in boost search/boost taps
for now"), so rules are indexed for discovery but land nowhere —
there is no boost install path for a rule. Add one that
writes each rule into the form the target agent actually reads, since
there is no single cross-agent "rules folder": Cursor/Windsurf/Cline
consume a rules directory (.cursorrules /
.windsurfrules / .clinerules / .mdc),
but Claude Code has no rules folder — its standing
rules are CLAUDE.md. So installing a rule for Claude means
merging it into CLAUDE.md (a managed, idempotent block),
while for the others it means dropping the file into their rules dir.
Needs a store/lock model for rules (uninstall must cleanly remove the
merged block), mirroring how skills symlink into enabled_agents().
After rules landed (#141), store.install still refused
kind == "workflow", so slash commands and subagents were
indexed for discovery but installed nowhere — browse could
surface a workflow but not install it. Add the install path. Unlike
rules (no cross-agent rules folder, so Claude needs a
CLAUDE.md merge), workflows are a clean file drop: a
command markdown lands in the agent's commands/ dir and a
subagent in its agents/ dir, with the slot derived from the
source path (commands//workflows/ →
commands, agents//subagents/ →
agents). Mirrors the rule store/lock model so uninstall
removes exactly what install wrote.
boost install --local into the projectboost was user-global by construction: one store at
~/.agents/skills, symlinked into every home-level agent
dir. Right for the skills you use everywhere, wrong for the
ones a team agrees on. Shipped the npm
--save half: boost install <skill> --local
(= --scope project) writes into the repo's own
.claude/skills/, .cursor/skills/, … and
records a committable per-repo lock at
.boost/skill-lock.json. Real directories, never
symlinks — a link into the author's ~/.agents/skills
arrives dangling on a teammate's machine, which is the exact problem
committing skills is meant to solve. Two separate locks, because
~40 call sites resolve a locked skill to
~/.agents/skills/<name>, which a project skill does
not have. Scope resolution walks up for the nearest project root, so
installing from src/deep/nested lands in the repo instead
of scattering a .claude/ three levels down;
list --local, uninstall --local and
sync all understand both scopes, and sync
re-materializes what a fresh clone is missing while never deleting a
directory boost did not write.
boost list shows installed rules and workflowsRule (#141) and workflow (#150) install landed, but
boost list still read only the lock file's
skills section — so a rule or workflow installed from
browse showed up nowhere, and worse, the empty-state
("no skills installed") fired whenever no skill was
present even if rules/workflows were, hiding them entirely. Extend
list to render an installed rules and
installed workflows table (agents drawn from each item's
recorded materializations, workflows also showing their slot), gate
the empty state on all three kinds being empty, and move
--json to a {skills, rules, workflows} shape.
--tag stays skill-only.
Workspace scope shipped in #212
— install --local, list --local,
uninstall --local, info and
sync all understand the per-repo lock. The other ~70
commands still read the user lock alone, and an adversarial review
of that PR named the consequences: boost update and
outdated can't see a vendored skill (the workaround is
install --local --force), and the governance
commands — audit, verify,
drift, doctor, health,
fingerprint, attest — report a clean bill
of health while N third-party skills sit in the repo being loaded by
every agent on the team. That last one is the real prize: vendored
skills are exactly the ones a security review should be looking at,
because they arrive by PR and run on everyone's machine. Shipped the governance slice — the real prize — via a shared
integrity.project_skills() / project_status() pair: verify and
doctor now check project-scoped skills' committed digests the same
way they do user-scope ones, so a drifted vendored skill is flagged
instead of silently trusted.
boost update refreshes installed rules and workflowsAfter rule (#141) and workflow (#150) install landed,
boost update still upgraded only skills — a rule or
workflow stayed frozen at its install-time content even after its tap
moved. Extend the update pass: for each installed rule/workflow from a
refreshed tap, re-materialize (force reinstall) when the source
version bumped or its file content sha changed, mirroring the skill
upgrade loop. Rules/workflows carry no pin/quarantine flags and their
source is a single file, so there is no risky-diff gate — re-applying
a file drop or a CLAUDE.md managed block is cheap and the
refresh is reported per item.
sync rules/workflows like skillsTwo skill-only gaps remained after rule (#141) / workflow
(#150) install: the install-time injection + secret scan
read res.dest/SKILL.md, which doesn't exist for a
rule/workflow (a single file / merged block), so their executable
Markdown went unscanned; and boost sync only reconciled
skills, so a deleted rule/workflow materialization couldn't be
repaired. Fix both: carry the raw source on the install result
(scan_text) so injectscan/secretscan see exactly what was
installed, and extend sync_plan/sync_apply
with a missing_materializations pass that re-materializes
a rule/workflow from its tap when a drop file or CLAUDE.md block is
gone — mirroring the missing-store-dir repair for skills.
boost install --scope user|project for rules/workflowsRule and workflow install always materialized into user-global agent config
(~/.claude/CLAUDE.md, ~/.cursor/rules, …), so a
rule meant for one repo leaked into every session. Add
--scope project: materialize into the current repo instead —
<repo>/.cursor/rules/, <repo>/.claude/commands|agents/,
and, since Claude reads per-repo memory from the root and has no rules
folder, <repo>/CLAUDE.local.md (the personal, git-ignored
file). The chosen scope + base dir are recorded in the lock so
update/sync re-materialize back into the same
repo rather than wherever they happen to run. Default stays
--scope user (unchanged behavior). Uninstall already reverses
by recorded path, so it works for either scope.
bandit via ruff S rulesTurn on the flake8-bandit (S) rule family already
bundled in ruff — one line in pyproject.toml, zero new
tools. It catches the Python SAST smells the linter is blind to today:
subprocess(shell=True), assert as a runtime
check, tempfile.mktemp, unsafe yaml.load,
hardcoded secrets and weak hashing. Semgrep Community rules are the
heavier alternative when a finding needs real dataflow.
pip-auditPyPA's pip-audit fails CI when a resolved dependency
matches a known advisory in the OSV / PyPI Advisory database.
Dependabot opens update PRs but never blocks a merge on a live
CVE; a scheduled + PR pip-audit job closes that
gap and covers the dev/test toolchain that ships nothing but can still
run malicious code.
Boost's unit tests prove the retrieval math is arithmetically correct,
but nothing graded whether search returns the right skill for a real
question. This adds a golden-set harness — tests/eval/golden.jsonl,
43 query → relevant skill(s) judgments across
skills, rules and workflows — scored with rank-aware IR metrics
(recall@k, hit@1, MRR,
nDCG@k). Deterministic and offline over the tapped catalog, so it
runs as a local pre-release gate (make eval,
--fail-under 0.85) alongside make check, with
a pinned baseline (tests/eval/baseline.json) that flags
regressions. The
first run earned its keep immediately, exposing a duplicate-name double-count
(recall 2.7) fixed by deduping the ranked list. A three-way engine compare
proved BM25 full-content (0.919 recall) decisively beats the frontmatter
heuristic (0.756), justifying the RAG stack. An opt-in, key-gated
make eval-ai arm reuses the same labels to measure the LLM
rerank lift — no judge needed — and confirmed rerank promotes the right skill to
#1 in 16% more cases (hit@1 0.605 → 0.767) at unchanged recall. A
Tier 2b arm (eval_recommend.py, make eval-rec)
grades the boost recommend AI pick stage over golden project
stacks with a hard grounding gate: it found the AI picks statistically tied with
the heuristic on precision but perfectly grounded (0 hallucinated /
off-shortlist picks) — the honest verdict that this stage earns its place through
explanations and safety, not better ranking.
The Scorecard GitHub Action audits ~18 supply-chain signals weekly — branch protection, token permissions, SHA-pinned actions, dangerous workflows, signed releases — and publishes results to the Security tab plus a README badge. Turns "are we set up safely?" into a tracked, trend-able number for a repo that owns a Trusted-Publisher release path.
The golden set (43 queries / 8 stacks / 7 skills) is small enough that
engine comparisons don't yet reach significance — the paired t-test lands at
p≈0.11–0.26 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
(search --smart, detect_stack). 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.
gitleaks + push protectionScan the full history and every PR diff for leaked tokens, keys and
PyPI credentials with the free gitleaks action, paired
with GitHub push-protection (free on public repos) so a secret is
blocked before it lands. Cheap insurance for a project whose
release automation trades on trusted identity.
xenon · vultureGate CI on a maintainability grade with xenon (built on
radon) and flag unreachable branches, unused arguments and
orphan helpers with vulture. First target: the
~5,000-line commands/ layer that has no complexity signal
today. Surfaces the structural smells mutation testing can't see.
Tier 1b (the ranx paired t-test, --stats) only runs on
demand today. Wire it into a scheduled CI monitor — like the
eval-explain workflow — that tracks whether BM25's lead over the
heuristic, and any new engine's lead over BM25, is statistically
significant 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 [eval] 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)."
SonarCloud is free for public repos and layers bugs, code smells, security hotspots, duplication and a coverage overlay into one dashboard, decorating each PR with a pass/fail quality gate. The single highest-signal freemium add — one external surface that unifies everything else in this section.
hypothesis on the parsersGenerate adversarial inputs against core/frontmatter and
core/catalog.scan_dir to surface crashes and round-trip
failures the example-based unit tests never think to try — a
dump→parse must round-trip; a scan must never
raise on arbitrary bytes. Complements the gate: mutmut proves the tests
are strict, Hypothesis proves the inputs are wide.
atheris / OSS-FuzzGoogle's atheris fuzzes the frontmatter and registry
parsers under coverage guidance to mine deep crash inputs; OSS-Fuzz
runs it continuously for free once boost qualifies as an open-source
project. The stretch goal — the highest ceiling for finding the bug
nobody thought to write a test for.
ProxyHandlercore/ai.py and core/embed.py call
urllib.request.urlopen with the default opener, which on
macOS runs getproxies_macosx_sysconf() →
_scproxy → SystemConfiguration/CoreFoundation — an
Obj-C path that is not fork-safe and aborts on the
child side of a fork(). Harmless in today's single-process
CLI, but fragile if boost ever runs post-fork (a future multiprocessing
worker, or an embedding host). Build the opener with an explicit
ProxyHandler honoring HTTP(S)_PROXY/NO_PROXY
so network calls never touch the Obj-C proxy machinery — deterministic
and fork-safe.
Zcore/logs.py builds the logging.Formatter with
datefmt="%Y-%m-%dT%H:%M:%SZ" but never sets
converter = time.gmtime, so %(asctime)s uses
local time while stamping a literal Z (UTC)
suffix. Every line in ~/.boost/logs/boost.log is therefore
off by the machine's UTC offset — which nearly caused a 5-hour
mis-correlation when matching the log against an OS crash report. Set
the formatter's converter to time.gmtime (or
drop the Z) so the trail is honestly UTC, making the
pid/ppid crash-correlation breadcrumbs trustworthy.
boost doctor checks installed rules and workflowsAfter rule (#141) and workflow (#150) install landed,
boost doctor's health loop still only walked the lock
file's skills — so a rule or workflow whose materialized
file a user deleted (or whose CLAUDE.md managed block was
hand-removed) went undetected. Extend the doctor loop to verify every
recorded rule/workflow materialization is still on disk: a file drop
must exist, and a Claude rule's CLAUDE.md must still carry
its managed block. A missing materialization is flagged with a
boost reinstall hint and flips the verdict, matching how
skill-drift is surfaced.
zizmorboost's four workflows embed github-script JavaScript and
shell and drive a Trusted-Publisher release — a rich attack surface.
zizmor statically flags template injection, unpinned
actions, over-broad GITHUB_TOKEN permissions and dangerous
triggers. The one tool that audits the automation that ships every
other fix.
actionlintCatches GitHub Actions YAML bugs before they fail a live release:
malformed ${{ }} expressions, deprecated syntax, and
shellcheck run over every run: block. Cheap insurance for a
repo whose release is fully automated — a broken workflow is a broken
publish.
actions/attest-build-provenance emits a cryptographically
signed, verifiable record of which workflow built which wheel from
which commit, layered on top of the existing PyPI Trusted
Publishing. Consumers can gh attestation verify the
artifact they install — provenance without a paid signing service.
Generate a CycloneDX SBOM with the free anchore/sbom-action
and attach it to each GitHub Release, so downstreams can inventory and
scan exactly what boost is built from. Modest today (boost is close to
stdlib-only) but it grows in value as the optional [rag]
extras pull in real dependencies.
osv-scannerGoogle's osv-scanner cross-checks a lockfile or the SBOM
above against the OSV database, with broader ecosystem coverage than a
single-language audit. The SBOM-driven complement to pip-audit:
one scans the resolved env, the other scans the published manifest.
pyrightRun Microsoft's pyright alongside mypy. Its independent
inference catches None-flow and narrowing bugs the current
mypy config lets slide, and it's the same engine most editors use — so
CI enforces what contributors already see. Two type checkers rarely
agree on nothing.
B·SIM·C4·PERF·RUFBeyond the S security family (round 1), enable
flake8-bugbear (B), simplify (SIM),
comprehensions (C4), perflint (PERF) and
Ruff-native (RUF) rules — bug, readability and performance
smells caught at zero new-tool cost since ruff already runs in the lint
gate.
diff-coverEnforce coverage on the changed lines of each PR — no external
service needed, it reads the same coverage.xml the suite
already emits. Pairs with the 80% project gate so new code can't quietly
ride in under-tested behind an already-high overall number.
Canonical style/boost.css ships tokens + primitives but
no nav, logo, or footer, so every page (the guide and
both roadmaps) redefines that chrome inline — and the Design Roadmap
currently renders its nav unstyled because of the gap.
Add .site-nav/.logo/footer
primitives to the one sheet so the chrome is defined once and can't drift.
pre-commit + pre-commit.ciA .pre-commit-config.yaml runs ruff, mypy, codespell and the
whitespace fixers before code ever reaches CI, and the free-for-OSS
pre-commit.ci auto-fixes and auto-updates hooks right on the
PR. The foundation the rest of this section plugs into — one config,
many checks, faster feedback.
import-linterEnforce the architecture boost already assumes: core/ must
never import commands/, and the CLI depends inward only.
import-linter turns that contract into a CI check, catching
the cross-layer imports that slowly erode a clean engine — a structural
smell no line-level linter can see.
codespellCheap, high-signal for a project this documentation-heavy: scan the
README, docs/*.html, docstrings and every user-facing CLI
string for misspellings. A typo in boost --help is a bug
users see on their first run.
interrogateGate CI below a docstring-coverage threshold so the engine stays
self-documenting as it grows. core/ is already well
commented; interrogate keeps it that way and flags the
new public function that shipped without a word of explanation.
pytest-benchmarkBenchmark the hot paths — a catalog scan over a large skills tree, a registry load — and fail the build when a change regresses them past a threshold. Catches the performance bugs a correctness suite waves through: the O(n²) that only bites at scale.
refurb + pyupgraderefurb's unique FURB checks flag dated idioms
the ruff families miss, and pyupgrade rewrites to the
cleanest form the >=3.9 floor allows. Keeps the codebase
reading like modern Python instead of accreting legacy patterns.
Upgrade the homegrown coverage badge to Codecov's PR diff-coverage
comments, file sunburst and trend graph — free for public repos. The
hosted counterpart to the self-contained diff-cover gate:
one enforces patch coverage in CI, the other visualizes the trend over
time.
The lint job installed its tools unpinned
(pip install ruff mypy …), so every run pulled the latest
release. When ruff 0.16.0 shipped it began flagging rule
families this repo deliberately does not select
(UP/BLE/PLW — ~1100 findings of
exactly the pyupgrade-style churn the roadmap already declined),
turning the gate red on every open PR and on main with no
code change. A gate whose meaning can shift out from under you on an
upstream release is not a gate. Froze the eight lint tools to their
known-good versions in one requirements/lint-tools.txt
that both CI and the Makefile install from, so upgrades become a
deliberate, reviewable bump. (The broader runtime/build reproducibility
story is the uv.lock item; this is the lint-gate slice
that was actively on fire.)
Free for public repos, Harden-Runner watches (and can block) unexpected
network egress from CI runners — the runtime signal that catches a
compromised action exfiltrating a token. The dynamic complement to
zizmor's static workflow analysis, guarding the release
path from both sides.
boost adapt — render a skill as another framework's agent sourceboost only installs skills as files for editor agents (Claude Code, Cursor, Windsurf); CrewAI / OpenAI-Agents-SDK apps can't consume them — an agent there is a value built in source. boost adapt <skill> --to crewai|agents-sdk renders one SKILL.md into each framework's native Agent(...) as a deterministic, zero-dependency string transform (core/adapters.py). Strings emit via json.dumps so any body (quotes, """, unicode) stays valid Python; 97.6% mutation kill. Docs: adapters.html.
boost adapt --to langgraph — third framework rendererExtend boost adapt (shipped in #146) with a LangGraph target. Unlike CrewAI / Agents-SDK, a LangGraph agent isn't one Agent(...) constructor — the skill body is the system prompt of a node bound into a StateGraph. Add a render_langgraph to core/adapters.py emitting a node factory (prebuilt create_react_agent, or a prompt-carrying node) + its FORMATS row, with byte-exact golden + compile() tests. Then add a langgraph leg to .github/workflows/adapter-conformance.yml (pip install langgraph, import the emitted file). Follows the pattern in adapters.html: one render_* fn + registry row + golden test + one matrix line.
boost adapt — multi-agent skills → crews/graphs, not one AgentToday boost adapt (#146, #163) projects a skill into a single framework Agent carrying its instructions/role/model — but a skill can declare tools and a whole subagent graph (e.g. rust-review = worker + dedup-judge + fp-judge). Adapt the richer structure: emit a CrewAI Crew (agents + tasks) or a LangGraph StateGraph when a skill's frontmatter/plugin dir declares subagents, and surface declared tools as stubs. Scope: detect subagent/tool declarations in SKILL.md/plugins/*/agents/*.md; add a crew/graph renderer path in core/adapters.py (single-Agent stays the default for flat skills); golden + compile() tests + a conformance leg. Turns "one skill → one agent" into "one skill → a runnable multi-agent workflow." See adapters.html.
boost run — search → adapt → a live agent doing the task, in one commandThe allure ceiling on boost adapt (#146, #163): it stops at source you assemble, and the adapted agent has a brain (prompt) but no hands (tools). Close both. boost run <skill> [target] = 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) tool-wiring — emit/attach the tools a skill needs (or declares) so the agent can act, not roleplay; (2) reuse the adapt renderer for the agent def. Pairs with [[framework-adapter-multi-agent]] so a skill like rust-review runs as a real crew. This is the screenshot: "one command → an expert agent audits your repo, on Claude, that you never wrote." Working preview: examples/boost-run-prototype.sh already does this by hand (adapt → wire a read_file tool → Runner.run on a file with planted bugs).
The boost MCP server returned no initialize instructions and described its tools by boost's nouns ("Search AI coding skills across the configured tap registries"), so an agent mid-task never mapped "I'll write a code-review workflow" onto "search boost first" — and reinvented the wheel. Add server-level instructions (the field MCP hosts load into the agent's context) framed by the agent's trigger — before you author a reusable skill / rule / subagent, call boost_search FIRST — and rewrite the six tool descriptions to lead with that trigger and a "don't reinvent one that already exists" frame. Follow-up: a self-bootstrapping boost-first meta-skill that boost mcp register / onboard offers to install.
The living roadmaps were unreachable unless you knew the URL:
design-roadmap.html was linked nowhere and the README had no
roadmap link at all. The Visual Guide nav now carries both boards (a
Design ↗ entry beside the existing Roadmap ↗),
and the README opens with a Roadmap section linking the code and design
boards plus the Visual Guide — so the two data-driven boards are one click away
and the work stays visible.
treosh/lighthouse-ci-action scores index.html
and roadmap.html on performance, accessibility,
best-practices and SEO on every deploy, and fails the build against
budgets. Turns the marketing surface's quality into four numbers that can't
silently regress as the Aurora theme evolves — four floors (a11y and
SEO 0.95, best-practices 0.90, the noisier performance 0.85) asserted
on the median of three runs, calibrated below the real scores with
margin the same way perf_gate sets its thresholds. And,
as every checker on this repo has, it found real defects on the
storefront: muted text at 3.9:1 contrast (below WCAG AA),
an h2 → h4 heading skip, and colour-only footer links —
all fixed, so both pages now score 100 on accessibility.
pa11y-ci / axe-coreRun WCAG checks over the rendered pages: colour contrast, focus order,
alt text and ARIA. The Aurora palette leans on muted
--text-2/--text-3 tokens against dark glass — exactly where
contrast ratios slip below AA. Catches the a11y regressions a purely
visual review misses.
html-validateThe guide and roadmap are hand-authored HTML whose tags are balanced by
eye today. A CI html-validate pass catches unclosed
elements, duplicate ids and invalid nesting before they
ship a subtly broken layout — the automated version of the manual
tag-count sanity check.
lycheeFast, free link checker over the README and docs/*.html:
verifies external URLs (GitHub, PyPI), asset paths
(../style/boost.css) and in-page anchors
(#next, #health) still resolve. A dead link in
the landing page is the first broken promise a visitor sees. Red on
its first run: eight were already broken — four ../adapters.html
at the wrong depth, two dangling anchors, one link to an item file as
though it were a page, and a README pointing at
docs/overview.html, renamed to index.html
and never updated.
valevale enforces a consistent voice across the README and docs
with a small boost vocabulary — canonical spelling of skill,
tap, registry; no Boost/boost
drift; flagged weasel words. Keeps a docs-heavy project reading like one
author wrote it.
markdownlint-cli2Lint every Markdown surface — README, CLAUDE.md,
DEBUGGING.md, rag-architecture.md — for
heading order, list style and fenced-code hygiene. Cheap, deterministic,
and it keeps the contributor-facing docs as tidy as the code the gates
already enforce.
stylelint + eslintThe shared style/boost.css and boost.js theme
the guide, roadmap and demo together, so a bug there recolours or breaks
everything at once. stylelint guards the CSS tokens and
eslint the reveal/interaction JS — the one place a small
mistake has system-wide blast radius.
After each Pages deploy, headless-load the guide and roadmap and assert the essentials: HTTP 200, every asset resolves, and the console is free of errors. Distinct from the planned visual-regression pass — this is a cheap always-on health gate that would have caught the current broken Pages deploy automatically.
boost has no browsable command reference — help lives only in
--help output and scattered README prose, so there's no
versioned, searchable home for what each command does. Build a proper
docs site in the shape of
learning-python.readthedocs.io:
a left-nav tree of commands, per-command pages (synopsis, flags,
examples, exit codes), and full-text search. Generate the command
pages from the CLI's own definitions so the docs can't drift from the
code, and publish alongside the existing Pages site under the Aurora theme.
docs/*.html page from the main pageMaking the roadmaps discoverable
put both boards in the Visual Guide nav, but the same gap remains for
the rest of docs/*.html: mcp-hub.html is
reachable only if you already know the URL — nothing on
index.html links to it. Add a nav entry for every shipped
doc page (today just the MCP Hub, beside Roadmap ↗ /
Design ↗) so no page is an orphan, and treat "a new
docs/*.html means a new nav link" as the standing rule —
ideally checked in CI so a future page can't ship unlinked.
mcp-hub.html)On the Fig 2 RAG-pipeline diagram, the read_body → chunk node
overflows its rounded box: the third caption line
(1000 chars · 150 overlap · ≤40…) runs past the node's
right border and is clipped where the pink embed arrow begins.
Give the node room so all three lines sit inside the bubble — widen its
min-width, wrap or shrink the caption, or trim the label text — and
re-check the other nodes at the same breakpoint so none clip.
The test matrix runs macOS and Ubuntu only, so
windows-latest path separators, case-sensitivity and
console-encoding bugs ship uncaught to any Windows user. Adding one
matrix leg closes the biggest untested surface for a tool that promises
to work "everywhere your agent does".
pipxEvery gate runs against an editable pip install -e ., which
hides missing package-data, a broken entry point or an undeclared
dependency. A job that pip installs the built wheel into a
fresh venv (and pipx installs it) then runs
boost --version proves the artifact a user actually gets
works.
uv --resolution lowest-directCI always installs the newest compatible dependencies, so the
lower bounds declared in pyproject.toml are never actually
exercised. Resolving and testing against the minimum versions catches
the "works here, breaks on the floor we advertise" class of bug.
An allow-failure matrix leg on Python pre-releases and the free-threaded (no-GIL) build gives early warning of breakage before users on new interpreters hit it. Cheap insurance for a project that already targets 3.9 → 3.14 and can't afford a surprise on release day.
-X importtimeFor a CLI, cold-start latency is the UX — every command pays it.
A gate on python -X importtime boost catches the accidental
top-level import of a heavy module (the optional [rag] stack
is the obvious trap) and keeps common commands feeling instant.
twine check + friendsBefore every publish, twine check confirms the long
description renders on PyPI, check-wheel-contents catches
stray or missing files, and pyroma scores the metadata
completeness. Stops a broken PyPI page or an empty wheel from reaching
users — the release path currently trusts the build blindly.
uv.lockPin the dev and CI toolchain with a hash-locked uv.lock (or
a hashed constraints file) so a yanked or compromised transitive
dependency can't silently change a build. The reproducibility layer that
complements Dependabot and pip-audit — same inputs, same
bytes, every run.
noxA noxfile.py makes the full lint / test / smoke / mutation
gate reproducible across 3.9 → 3.14 in isolated environments,
locally and in CI alike — so "green on my machine" and "green in CI"
finally mean the same thing, and a contributor can run the exact gate
before pushing.
boost mcp launch against macOS Obj-C fork abortsOn macOS, a host that spawns boost mcp --stdio via fork()
can abort on the child side pre-exec when Obj-C is touched
post-fork (CFPreferences / _scproxy proxy lookup) — the
classic "crashed on child side of fork pre-exec"
SIGABRT. Not boost's own code (it aborts before boost
runs), but boost can make its integration robust: when registering the
MCP server (boost mcp register / the emitted client
config), set OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES (and
no_proxy=*) in the launch environment so the host's fork
into boost can't trip the Obj-C fork-safety abort. Document it for
hosts that launch boost directly.
The launch-env fix (#119) only
protects hosts that register boost through boost, which
injects no_proxy=*. A host that fork()s into
boost mcp --stdio from a stale or hand-written config —
or any stray default-opener call inside the process — is still one
getproxies() away from the macOS _scproxy
Obj-C SIGABRT. Close the gap from inside: at the top of
main(), seed no_proxy for the current
process (only when no *_proxy env is already set, so a
real proxy is never clobbered) so the stdlib default
getproxies() short-circuits on
getproxies_environment() and never consults
SystemConfiguration. Belt-and-suspenders atop the
nethttp opener (#115).
boost mcp register shelled out to
claude mcp add --scope user -e OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES -e
no_proxy=* boost -- … — the -e flags before the
server name. But claude's -e is variadic, so it
swallowed boost as a third env var and aborted with
Invalid environment variable format: boost, making the one-command
install path fail outright on macOS. Reordered to
claude mcp add boost --scope user -e … -- … (the
add <name> [options] -- <command> form), so the name is
consumed as the positional before -e can grab it. A regression
test pins name < first -e so a future reorder can't silently
re-break it.
The highest-signal gap: boost installs Markdown an agent then executes,
and nothing inspects that content. Scan skills for injection patterns —
"ignore previous instructions", data-exfiltration prompts,
embedded curl … | sh — with free rule engines
(semgrep custom rules, garak/llm-guard
patterns) at tap and install time.
boost verifyThe lockfile already records a sha256 per install via
util.sha256_dir, but nothing ever re-checks it. A
verify command (and a doctor gate) that
re-hashes installed skills and flags drift turns that stored digest into
actual tamper-detection — cheap, and built on machinery that already
exists.
A tap records its commit today but offers no cryptographic
proof the content came from its claimed publisher, so a hijacked mirror
can serve altered skills undetected. Verify a signature (Sigstore
keyless or minisign) before trusting a tap — free, and the
standard the wider ecosystem is converging on.
boost explainToday the ragas faithfulness check (Tier 2c, scripts/eval_explain.py)
is eval-time only — an offline monitor that flags when generated
explanations drift from their SKILL.md, but never intercepts a live
response. Promote it to a runtime guardrail: score the generated summary
against the source and, when it falls below a faithfulness threshold, fall back
to the deterministic extractive summary cmd_explain 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.
The classic package-manager attack: a skill named one edit-distance from
a popular one, or a familiar name that quietly resolves to an unexpected
owner/repo. Flag near-duplicate names and owner mismatches
at search and install time so a user can't fat-finger their way into a
malicious skill.
Shipped in #132. boost update no longer overwrites an
installed skill in place unseen. A new pure core module
core/updatediff.py diffs the installed tree against the incoming
source (diff_tree) and flags when the change adds
executable-looking instructions — shell commands, pipe-to-shell,
shebangs (touches_executable). When it does,
cmd_update prints the unified diff and requires confirmation before
applying, so a poisoned update is visible instead of silent; routine
version bumps and prose edits still apply quietly. Fully unit-tested and
mutation-covered, plus functional coverage of the confirm / decline / no-gate
paths.
Workspace scope (#212)
guarded the delete side — uninstall --local re-derives every
recorded path and refuses one that resolves outside the repo — but not
the write side. A project install builds its destination from
agent-dir names committed in the repo
(.claude/skills and its per-agent siblings), and a hostile
clone can ship one of those as a symlink pointing outside the
tree — at ~/.ssh, say. Cloning that repo and
running boost install <skill> --local then writes on the
far side: confirmed by reproduction, a skill directory landed in a
sibling of the repo instead of inside it. The squatter check does not
stop it (a brand-new leaf name like authorized_keys
collides with nothing, and --force waives it anyway).
scopes.ensure_in_base is the write-side mirror of the
delete guard: it re-derives containment through symlinks for every
target up front, so one escaping directory aborts the whole install
before anything is written. Covers all three project-scope kinds —
skill, rule and workflow.
Point the round-2 secret scanners (gitleaks/trufflehog)
at third-party skill content, not just boost's own repo — catching
a skill that ships embedded credentials or, worse, one whose prompt
coaxes the agent into harvesting the user's. Same free tools, a different
and higher-stakes target.
Promoted the recorded sha256 from a note to a rule. The check
moved into core/integrity.py (where the mutation gate
covers it), and every command that serves a skill's content routes
through one resolver that now refuses a tree whose bytes have drifted
from the lock — a tamper tripwire at the point of use, since boost
can't police what the agent loads but can refuse to hand you
a skill that no longer matches what you reviewed. Opt-in
(config security.enforce_digest, default off) so it never
surprises an existing setup; verify reports drift either
way. Commit pinning rides alongside: boost pin <skill>
--commit freezes the exact source commit, and
verify flags it if the recorded commit ever moves off the
pin.
Extend the existing policy.py so a skill declares the
capabilities it expects — network, shell, file scope — and the user's
policy allows or denies them. Turns install-time governance into
least-privilege for the instructions an agent is about to run, the
natural next step for a tool that already blocks installs by policy.