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.
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.
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.
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.
Root cause found: a bogus mutants/None gitlink (a stray
mutmut artifact) was committed with no .gitmodules entry,
so Pages' submodule checkout aborts with
fatal: No url found for submodule path 'mutants/None'.
Fix: stop tracking mutants/.
Over a hundred mutants/**, __pycache__/*.pyc
and .coverage files are tracked despite being in
.gitignore — they churn every diff and forced careful
path-scoped git adds. Remove from the index.
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.
read() returns an empty skeleton on any JSON error and write() is a bare write_text at core/lockfile.py:55. An interrupted or concurrent write truncates the lock — the next set_skill() then permanently drops every prior install record while store dirs linger as orphans. Write to a temp file + os.replace(), and tell "empty" apart from "corrupt".
The "is this skill outdated" decision — semver_gt → commit compare → sha256_dir vs lock — is reimplemented nearly verbatim in cmd_update, cmd_outdated and _drift_status (pkg.py:277 · taps.py:225 · quality.py:120). Three copies of core business logic that will drift apart. Make it one core function the commands render.
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.
configuration.py~290 lines implement a full HTTP catalog server and a JSON-RPC 2.0 MCP server — with search/install/doctor dispatch that duplicates the CLI — inside a "configuration" command module (commands/configuration.py:741–1028). Move to core/mcp.py / core/serve.py, leaving thin wrappers. It's the biggest driver of the file's 1,099 lines and nearly untestable in place.
_copy_skill does rmtree(dest) then copytree() (core/store.py:108–131); an interrupt between the two leaves a missing or half-copied skill, and the lock is written afterward — so a mid-copy failure leaves store and lock disagreeing. Copy to a temp dir and atomically swap into place.
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.
Stack detection exists three times — discovery.detect_stack, intelligence._local_stack, quality._STACK_MARKERS (discovery.py:74 · intelligence.py:359 · quality.py:55) — and two already import detect_stack yet still carry a parallel marker table "as a fallback". Consolidate into one core prober.
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 (14 cmds / 1,051 lines) mixes audit regexes, conflict NLP, decay scoring, fingerprinting and a health dashboard; intelligence.py and configuration.py are similarly overloaded. Split along cohesive seams to shrink blast radius and sharpen mutation-gate targeting.
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 stores piece[:200] — the head of the best chunk — and retrieve surfaces it verbatim (rag.py:154–172,337–341), yet the docstrings promise the "best-matching passage". Center the snippet on the matched terms to improve display and the rerank context sent to the LLM.
_scalar turns no/on/off/null into bool/None (core/frontmatter.py:32–53), so a tag or name literally equal to one of those parses to the wrong type and leaks into search/ranking meta. Restrict boolean coercion to true/false.
cmd_migrate re-implements agent validation instead of calling _check_agents; _user() is copy-pasted between configuration and team; cmd_simulate parses the same frontmatter twice (pkg.py:38,577 · configuration.py:39 · team.py:30). Small, satisfying cleanups.
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.
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.
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.
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.
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.
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.
Neither roadmap.html nor design-roadmap.html is
linked from docs/index.html or the README — the living
roadmaps are unreachable unless you already know the URL. Add nav entries
on the Visual Guide and a "Roadmap" link in the README so the two 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 a number that can't
silently regress as the Aurora theme evolves.
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.
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.
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.
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.
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.
boost update overwrites installed skills in place. Show a
content diff of what an upstream change alters — and require confirmation
for anything that touches executable-looking instructions — so a poisoned
update is visible instead of silent. The "review the diff" gate,
applied to skills.
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.
Promote the recorded sha256 from a note to a rule: refuse to
load a skill whose content has drifted from the lockfile, and let users
pin a skill to an exact commit. The enforcement layer that makes the
verify digest binding rather than advisory.
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.