The boost roadmap

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.

Cut 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).

35 → 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.

cmd_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).

34 → 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:).

The 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.

The 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.

~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.

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.

clone_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.

Audited the surviving mutants across all ten listed modules — catalog, util, ai, registry, lockfile, policy, config, output, agents, paths — and killed every one that reflected a real behavioral coverage gap: the search desc-bonus accumulation and classify_workflow signature logic; score_skill signal detection and the rel_time bucket boundaries; registry.remove keeping other taps; a 3-level config.unset slicing bug; the untested lockfile.remove_rule/remove_workflow returns and corrupt-history skip; the entirely-untested policy.check_capabilities; and confirm()'s safe default. The residual survivors are equivalent mutants — encoding defaults, macOS case-folding (killed on CI's Linux runner), += vs = on a zero-init score, // vs / under %d, dead defensive defaults carried by DEFAULTS, and test-double-stubbed plumbing kwargs — none of which represents a missing assertion. The required mutation gate stays green with margin.

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.

The front page had drifted from the product: the README claimed 72 commands in one place and 78 in another (78 is correct), and ~2,600 mutants against a real ~9,900. A number a reader can check in ten seconds costs more credibility when wrong than the feature it describes earned. All three corrected — and pinned, so they cannot rot again: a unit test derives the command and group counts from cli.COMMANDS and fails if the README, the landing page, or the two disagree with each other. The README hero now leads with the one-line pitch and a four-command block that shows the whole flow before any prose. And demo.gif — a generated artifact whose regeneration needed brew install vhs on someone's laptop, so in practice it drifted (a merged PR had to fix it for showing ./boost long after that changed) — is now re-recorded by CI whenever the surfaces it demonstrates change, proposed as a PR because a GIF re-encode always differs byte-for-byte and its correctness is visual, not comparable.

boost's flagship retrieval is invisible to almost everyone who installs it. boost search "my app is slow" on the five default taps returns dnanexus-integration, tamarind, cirq, molfeat — bioinformatics and quantum computing, nothing about performance. That is BM25 doing exactly what BM25 does when a human types like a human, and it is what every keyless user experiences. The vector database was never the problem. Vectors already live on the user's own machine in sqlite-vec (~/.boost/cache/rag_vectors.sqlite), refreshed per tap against the commit it was built from. Nothing is hosted and nothing needs to be. The only API-bound step is turning text into vectors: embed.provider() returns "voyage" with VOYAGE_API_KEY set, "openai" with OPENAI_API_KEY, and otherwise None — at which point everything degrades to BM25. So the real dilemma ("every user rebuilds the index, or someone hosts and pays for it") is false in both halves. Six steps, and the first two carry most of the value. 1 — A local ONNX provider, as the third link in a chain built for it. Extend embed.provider() to Voyage → OpenAI → local → BM25, using ONNX Runtime on CPU with a small model (bge-small-en-v1.5, 384-dim, ~30 MB once). The sqlite-vec store, the per-tap commit cache and KNN search are all untouched — only the text→vector call changes. This removes the key, the signup and the card for every user, and Voyage stays a free quality upgrade for anyone who adds one. 2 — Prebuild per-registry shards in CI. Embedding the full catalogue (~28k items, ~150M tokens) on a laptop is an hour-plus, which no one will wait for. A workflow embeds each registry and publishes vectors as GitHub Release artifacts keyed on the registry's git commit — the cache key the code already uses — so boost tap fetches the catalogue and its shard. This is how Homebrew, npm and crates.io index a moving world. 3 — Local delta top-up. When a tap runs ahead of its published shard, or is a team or private registry CI has never seen, embed just those files on the spot. This is the structural answer to an unbounded ecosystem: shards cover the popular registries, the local model makes the long tail self-serve, and cost scales with what each user taps rather than with the size of the whole ecosystem. Without it, every uncatalogued registry is a dead end for a keyless user. 4 — Fuse the two engines with reciprocal rank fusion. Confirmed against the shipped code: rag.retrieve_any() picks one engine — dense when it is ready and returns a non-empty result, BM25 otherwise. There is no hybrid path today. RRF changes that to "run both, fuse by rank": score = 1/(60+rank_bm25) + 1/(60+rank_dense). Fusing on ranks, not scores, is the point — a BM25 score and a cosine similarity are on incomparable scales, and rank fusion sidesteps calibration entirely. The two engines fail in opposite directions and this corpus needs both: registries are full of exact identifiers (EAS, pptx, skill names) where BM25 is strongest and embeddings weakest, while sloppy queries are where BM25 returns quantum computing. retrieve_any is the single seam every retrieval path already passes through, CLI and MCP alike, so it is one function. The tradeoffs are real and should be measured rather than assumed: rank fusion discards confidence, so plain RRF can trail pure dense on purely semantic queries; "why did this rank third?" gains a two-part answer; and both engines must index the same chunks (they already share chunking). Ship the k=60 default, benchmark it, and tune only if the eval says so. 5 — A hosted demo on free tiers, so the experience is reachable without installing anything. 6 — Publish the eval: BM25 vs local dense vs Voyage dense vs hybrid on the existing golden set, with recall@k and MRR. That last one settles step 4 with data instead of argument — and if pure dense wins on this corpus, that is the result worth publishing. Scope note. This is an epic, not a single change. Step 1 is the one that removes the wall and is worth landing alone; steps 2–3 are what make it fast enough to be real; step 4 is ~20 lines in one function and independently shippable; 5 and 6 are separable. Expect this card to decompose into per-step items as each is picked up — the value of keeping it whole here is that the steps only make sense against each other. Step 1 is shipped, with two corrections to the plan above that surfaced only by measuring. fastembed cannot be used here. Its PyPI classifier declares License :: Other/Proprietary License even though the project is Apache-2.0, and scripts/check_licenses.py denies that with no override — UNDECLARED_OK exists for a package declaring nothing (the ragas precedent), not for one declaring the wrong thing. Its tree also drags in py-rust-stemmers, which declares no licence at all, plus Pillow, requests and loguru, none of which boost has a use for. Measured with the repo's own gate: the fastembed closure is 32 packages with 2 findings, ONNX Runtime plus a tokenizer is 20 packages with 0. The lean pair shipped, at the cost of ~150 lines of download/pool/normalise in core/localembed.py. The model is 133 MB, not ~30 MB. That figure describes the quantized rebuild third parties publish; BAAI's own ONNX export is 133,093,490 bytes. boost fetches the authoritative one and sha256-verifies it against a pinned repository revision — a project with signed taps and hash-pinned locks has no business taking model weights from a re-uploader to save a one-time download. Quantization is a genuine follow-up, but it changes the vectors, so it needs its own eval rather than a swap. Two details worth recording for whoever takes step 4. BGE is CLS-pooled, not mean-pooled: mean pooling would still emit 384 plausible-looking floats and quietly worse retrieval, which is the kind of error an eval catches and a unit test does not. And the chain puts local last, so a user with a Voyage key keeps voyage-4 instead of being silently downgraded. Verified end to end against the real weights: 384 dimensions as declared, L2 norm 1.000000, and sim("making my application faster", "application performance tuning") = 0.7691 against sim(…, "quantum computing circuit simulation") = 0.5338 — the exact failure this card opened with, now ordered correctly. Constraints this must respect: the shipped runtime is stdlib-only and [project].dependencies is empty, so a local model belongs behind an extra like [rag], with the keyless path degrading to BM25 exactly as it does now. The required eval gate already floors BM25 recall@k at 0.85 over the golden set, so step 6 has a harness to extend rather than invent. Related: [[dense-search-fallback-and-stale-tap-pruning]] and [[cache-the-catalog-entry-set-across-rag-queries]]. A sibling item proposes a different backend, and landed from another loop while this was in review: [[keyless-dense-tier-local-static-embeddings]] argues for a static model (model2vec/potion class) — a lookup table rather than a transformer, pure stdlib, no numpy, no onnxruntime, ~1 ms per query, reranking BM25's top-200. The two are not the same design and the comparison is worth settling with the eval (step 6) rather than by argument. One of its objections applies directly to what shipped here and was worth measuring rather than waving away: it holds that import numpy alone costs 180–390 ms cold, which would disqualify a transformer from a one-shot CLI path. Measured on this machine, best of three cold processes: import numpy 51 ms, import onnxruntime 62 ms, and a complete cold embed() — process start, ONNX session build over the 133 MB graph, tokenize, infer — 233 ms. So the objection does not reproduce here, though import cost is genuinely machine- and version-dependent and their number may be real on theirs. 233 ms is also very likely faster than the Voyage round trip it sits beside, and it is paid only by users who installed the extra. If step 6 is the tie-break, it needs a method and not just a number. The sibling item already produced one cautionary result worth inheriting rather than repeating: its own headline, +11.0 recall / +15.9 hit@1, did not survive verification. Three failures, none specific to a static model, all reachable from here. Its baseline used a kind oracle the live search path does not have, so the comparison was never against what a user experiences. The blend weight (w_dense=0.7) and the rerank pool depth were both tuned by argmax on the same 82 queries they were then reported on — fitting and reporting on one set. And at n=82 on a binary metric, the smallest net win reaching p<0.05 is 6 queries: its hit@1 (+13 net) clears that bar, while recall (+9) sits at the resolution floor and should not have led. So four constraints on step 6, whichever backend wins. Report McNemar on paired per-query outcomes rather than two independent-looking averages, since the engines are scored on the same queries. Hold the blend weight and pool depth out of the query set they are scored on. Lead with hit@1 — on a golden set this size, recall moves inside its own noise. And measure each engine alone before any fusion, so a hybrid win cannot be quietly credited to the embedder that did not earn it. One structural caveat also transfers: a skill's name is only ~10.5% of a mean-pooled surface vector while 106 description clusters are shared across 270 distinct names, so a lift measured on today's corpus may shrink rather than hold as the index grows toward 50k items — an argument for re-measuring at scale before believing any of this. The static approach still wins on cost and would win outright if the quality gap is small — which is exactly what the eval should decide. Its own card is right that neither should ship a retrieval claim before that eval exists. Step 6, run against those four constraints — and it does not say what this card assumed. Corpus rebuilt from tests/eval/taps.txt (6 taps, 743 entries, 3740 passages embedded locally), k=10, 91 golden queries. Each engine measured alone, no fusion: catalog.search hit@1 0.714, recall 0.918, MRR 0.783; BM25 full-content hit@1 0.780, recall 1.000, MRR 0.860; dense (local bge-small) hit@1 0.780, recall 0.956, MRR 0.853. Leading with hit@1 as instructed: 71 queries each — an exact tie. Recall differs by 4 queries (91 against 87) and MRR by 0.6, both under the ~6-query floor this card sets for p<0.05 at this n. So the honest reading is no significant difference between BM25 and local dense on the golden set — not a win for either. An earlier draft of this note claimed BM25 won; that was the recall number leading, which is exactly the error the four constraints above were written to prevent. The more useful result is that the golden set cannot grade this feature at all. It scores real catalog items by name, which is BM25's strength by construction — CLAUDE.md already records that BM25 recall over this corpus is 1.000. It contains none of the human-phrased queries the keyless work exists for, and on those the two engines separate sharply: "my app is slow" returns phoenix-docker-setup, guidelines, solidjs---error-boundaries from BM25 against analyse-problem, performance-optimization, fastapi-best-practices from dense; "I need to make my website accessible" returns do-and-judge, write-concisely, do-in-steps against accessibility-guidelines first. That is a demonstration, not a measurement — there is no scored query set of that shape yet, which is the point. Three consequences. Step 6's first deliverable is a query set, not a number: golden queries in the human-phrased style, or the eval keeps answering a question nobody asked. Step 4 (RRF) gains support — a tie on keyword queries plus a qualitative dense win on human ones is the "two engines fail in opposite directions" case, and fusing is the response to it. And the current preference order deserves a look: rag.retrieve_any takes dense whenever it is ready and non-empty, so shipping step 1 without step 4 silently moved keyword queries onto the engine that is, at best, tied for them. Method note. The first indexing pass reported 3 taps failed to embed (2716 of 3740 passages). A rerun stored all 3740, and two 30-batch replays never reproduced a failure, so it was transient resource pressure rather than a defect — the retry path (no commit recorded for a failed tap) did its job. The figures above come from a complete index. Step 4 shipped, measured against the same 91 queries. retrieve_any no longer picks an engine; it over-fetches RRF_K=60 from each and fuses by reciprocal rank, 1/(60+rank) summed, keyed on (name, tap) — the key both engines already dedupe on. Adding a hybrid column to the eval: catalog.search hit@1 0.714; BM25 hit@1 0.780, recall 1.000, MRR 0.860, nDCG 0.895; dense hit@1 0.780, recall 0.956, MRR 0.853, nDCG 0.876; hybrid hit@1 0.813, recall 0.978, MRR 0.883, nDCG 0.905. Hybrid leads on hit@1, MRR and nDCG, and gives up 2 queries of recall to BM25. Neither difference is significant by the bar set above: +3 net queries on hit@1 and −2 on recall, both inside the ~6-query floor for p<0.05 at this n. So the case for fusing is not "it scores higher" — it is that fusing is the only option that is at or near best on both query shapes, where preferring either engine is measurably wrong for half of them. This reverses a deliberate earlier decision, and that is worth flagging rather than burying: test_a_non_empty_dense_result_is_still_final existed precisely to stop retrieve_any "always running BM25 too". Its premise was that a dense hit is the better answer, which the tie above retires. The other half of that fix — an empty dense result is a thin index, not a verdict, and must fall through to BM25 — still stands and is still tested. One honest counter-observation. On two hand-picked human-phrased queries, fusion at k=3 lost the best dense hit: "my app is slow" dropped performance-optimization and "I need to make my website accessible" dropped accessibility-guidelines, in both cases because a junk BM25 rank-1 outweighed a good dense rank-2. That is exactly the tradeoff this card predicted — "rank fusion discards confidence" — and it is an anecdote at n=2 against a measured win at n=91, so it did not block shipping. It is the strongest argument for the query set step 6 still needs, and the first thing to re-measure once that exists. Step 6's real deliverable, and it settles the question. The missing piece was never a number — it was a query set of the shape this feature exists for. tests/eval/golden-natural.jsonl is 50 queries written from each target's own description and nothing else, phrased as a user problem, with the target's distinctive name tokens deliberately excluded (a query containing "docker" finds docker-expert by string match and measures nothing). The whole set was written before any engine was run against it and scored once, so it could not be selected to flatter a result already seen. A mechanical check caught five queries that had leaked a name token and they were rewritten. Over the same corpus at k=10, 50 queries: catalog.search recall 0.330 hit@1 0.080; BM25 recall 0.690 hit@1 0.240; dense recall 0.760 hit@1 0.420; hybrid RRF recall 0.820 hit@1 0.420 MRR 0.559 nDCG 0.614. BM25 collapses on this shape — hit@1 falls from 0.780 on the keyword set to 0.240 here, recall from 1.000 to 0.690. And dense beats it by +9 net queries on hit@1 (21 of 50 against 12), which clears the ~6-query significance floor this card set. That is the first significant retrieval difference anyone has measured in this repo, and it is in the opposite direction from the keyword set. So the two sets together say something neither says alone. On keyword queries BM25 and dense tie and hybrid edges ahead; on natural queries BM25 is far behind and hybrid is at-or-above dense on every metric. Hybrid is the only engine that is at or near best on both shapes — which is precisely the argument step 4 was shipped on, now with a significant margin behind it rather than +3 queries inside the noise. One caveat the slice exposes: skill queries score hit@1 0.459 against workflow 0.308. The workflows in this corpus are overwhelmingly <technology>-expert agents, so a problem-phrased query has to bridge from a symptom to a product name with no shared vocabulary at all — the hardest case, and the one where a larger embedding model would most likely show its value. Worth re-running against Voyage before concluding the local model is enough. The set is deliberately not wired into make eval or the required gate: it needs the [rag] extra and a built store, and its purpose is comparing engines rather than flooring one. Run it with --golden tests/eval/golden-natural.jsonl. Step 4 is shipped too. rag.rrf_fuse landed in #360 with RRF_K = 60, fusing on ranks exactly as described above, and retrieve_any reports hybrid RRF when both engines are built. Recording it here because this card still read as though only step 1 were done, and the next loop scanning for work would have rebuilt it. The step's own instruction — “ship the k=60 default, benchmark it, and tune only if the eval says so” — was followed: the benchmark is tests/eval/golden-natural.jsonl, and k=60 is untouched. Steps 2, 3, 5 and 6 remain open. Note that step 6 (publish the eval) is now partly answered by the gate work in #365, which floors four metrics instead of recall alone and keys baselines to their query set, so BM25-vs-dense-vs-hybrid comparisons are at least falsifiable. What step 6 still wants is the published write-up rather than the instrument. Step 6 is shipped — the eval is published in docs/eval.html, and it settles step 4 with data. Every engine, same corpus, both query sets, k=10. Voyage is absent because it needs a key and these runs were keyless, which is the configuration this whole epic exists to serve. On the keyword set (91 queries, graded by name): BM25 0.978 / 0.791 / 0.854 / 0.882, dense 0.956 / 0.780 / 0.853 / 0.876, hybrid 0.978 / 0.780 / 0.864 / 0.891. On the natural-language set (50 queries, name tokens stripped): BM25 0.750 / 0.340 / 0.474 / 0.524, dense 0.760 / 0.420 / 0.541 / 0.580, hybrid 0.820 / 0.440 / 0.578 / 0.623. Fusing beats choosing, which is what step 4 claimed. Hybrid wins or ties on both sets, and on human-phrased queries it beats both of its own components on every metric. The components fail in opposite directions exactly as predicted — BM25 takes hit@1 on name-shaped queries (0.791 vs 0.780), dense takes it on human-phrased ones (0.420 vs 0.340) — so preferring either would hand half the queries to the engine that is worse at them. The k=60 default was shipped unchanged and the eval did not ask for it to be tuned. One estimate in this card was badly wrong. Step 2 says embedding the full catalogue on a laptop is “an hour-plus, which no one will wait for”. Measured: building the keyless store over 743 entries (3,740 chunks, ONNX bge-small-en-v1.5 on CPU) took 4,431 s — 74 minutes, about 1.2 s per chunk. Extrapolated to ~28k items that is on the order of days. This does not weaken the keyless tier: queries embed in milliseconds and the store is built once. It does mean step 2 (prebuilt per-registry shards) is a requirement rather than an optimisation, and step 3 (local delta top-up) has to stay scoped to genuinely small deltas. Still open: steps 2, 3 and 5. Claim released. Steps 1, 4 and 6 have shipped; steps 2, 3 and 5 are unowned and open. Step 2 is the one to take next and it is better justified than when it was written: embedding measured at ~1.2 s/chunk locally, so prebuilt per-registry shards are a requirement rather than an optimisation. Step 2, the shard mechanism, is shipped. boost reindex --export-shard TAP writes one registry's vectors as JSON; --import-shard FILE merges them. Measured end to end on the real store: exporting anthropics/skills gives 262 chunks in 0.63 MB, and importing it into a fresh BOOST_HOME takes 0.12 s against roughly five minutes to embed the same rows locally. That ratio is the whole point of the step. Import refuses rather than degrades. A shard carries the provider, model, dimension and the registry commit it was built from, and all four are checked. Mixing vectors from a different embedding space would not raise — it would quietly return nonsense rankings, which is worse than failing — and accepting a shard from a stale commit would let build() mark that tap “reused” and never re-embed it, pinning the user to old vectors indefinitely. Verified: a shard with a doctored commit is rejected with a message naming both hashes. What this does NOT remove: the query-side model download. A shard eliminates the document embedding cost, but a keyless user still needs the ~133 MB local model to embed their own query. Confirmed by importing into a fresh BOOST_HOME, where retrieval returned zero hits until the model was present — dense.status() reported ready the whole time, because the store genuinely was ready. The card's framing of “the only API-bound step is turning text into vectors” is right, but that step runs on both sides, and only the document half can be shipped ahead of time. Still open in step 2: the CI workflow that publishes shards as release artifacts, and the boost tap integration that fetches one automatically. Both are now plumbing on top of a verified mechanism rather than open questions. Steps 3 and 5 are untouched. Step 3 works, and it did not need new code — it needed proving. Local delta top-up falls out of the shard mechanism plus the commit-keyed reuse build() already had: import_shard records the tap's commit in the same meta.commits map build() consults, so an imported shard is indistinguishable from locally-built vectors as far as reuse is concerned. Measured end to end with a stubbed embedder, on a store holding an imported shard for anthropics/skills plus a freshly tapped Aaronontheweb/dotnet-cursor-rules: 158 chunks embedded — the new tap only — and the shard's 262 untouched. The resulting store is one coherent embedding space: 420 vectors, both taps' commits recorded, single provider/model/dim. That is exactly the shape this step asks for — shards cover the popular registries, the local model makes the long tail self-serve, and cost scales with what a user taps rather than with the ecosystem. Two tests now pin it, because the coupling is the kind that breaks silently: an import that forgot to record the commit would still produce a working store, and the only symptom would be re-embedding the shard's chunks on every later build — minutes of wasted CPU that nothing reports. Steps 1, 2, 3, 4 and 6 are now done; step 5 (a hosted demo) is the remainder, along with the CI workflow that publishes shards as release artifacts, which is noted under step 2. Step 2's publishing half is shipped — .github/workflows/shards.yml. Weekly plus on-demand, it taps each registry, embeds it, exports a shard and uploads it as an artifact. It is deliberately not chained off release, and that is the load-bearing decision. publish.yml already sits at ci → release → sbom, GitHub's documented three-level workflow_run limit; a fourth link would silently never fire. sbom.yml's header records exactly what that looks like in this repo — 253 releases, 0 runs, 0 assets, a control that appeared present and produced nothing. Shards are keyed on a registry's commit anyway, not on a boost release, so coupling them to our version cadence would be wrong even if the chain allowed it. Same reasoning for uploading artifacts rather than release assets: attaching them to a release would re-publish unchanged vectors on every version bump. Scale drove the shape. At the measured ~1.2 s/chunk, the 20-tap corpus is ~3.4 h against the 6 h job limit and the full 466-registry catalogue is far past it. So the workflow fans out one job per registry (fail-fast: false, so one bad registry cannot lose the others' work) rather than embedding everything in a single job. Two things were caught by testing the pieces locally rather than trusting the YAML. The matrix-planning step used printf '%s\n' $repos, which relies on word-splitting that does not survive quoting: it produced a one-entry matrix holding all twenty repos as a single string — one job attempting the entire corpus, straight past the job limit, and it would have looked like a plausible timeout rather than a bug. Splitting in Python fixes it. The shard validation step was also run against a real 262-chunk shard and against a provenance-stripped copy, to confirm it accepts one and rejects the other; a shard missing provider, model, dim or commit cannot be validated on import and would be refused by every consumer, silently, forever. Unproven until it runs: the workflow has never executed. The pieces are tested, the YAML parses and the pinned action SHAs match the repo's existing ones, but the first real run is the first end-to-end exercise. Step 5 is shipped as a keyword demo, and the card should say plainly what that does and does not deliver. docs/demo.html runs BM25 in the browser over a real 743-item, six-registry catalogue — a 1.27 MB index, built by scripts/build_demo_index.py from the same index the CLI uses. Nothing installs, nothing leaves the visitor's machine, and GitHub Pages already served docs/ so no new hosting was needed. The transfer figure was wrong, and the way it was wrong is the useful part. This card and the page both claimed 320 KB gzipped, taken from a local gzip -6 run (319.0 KB; -9 gives 310.2 KB). Fetching the deployed asset with Accept-Encoding: gzip returns 340,866 bytes — 333 KB, because a CDN trades compression ratio for speed. So the published number understated what a visitor actually downloads by 4%, and only measuring the served artefact caught it. Both places now quote the wire figure. Parity is the claim that had to be earned. The page asserts it runs “the same BM25 ranking boost search runs”, which is only worth saying if it is true, so the JS scorer and tokenizer are ports of rag._bm25 and rag.tokenize rather than approximations — same k1=1.2, b=0.75, same idf, same stopwords. Verified by running both implementations over six queries and diffing the results: top-5 identical on 6/6. Ten tests pin the contract that makes that possible. What it deliberately does not demo is the semantic half, and the page says so with numbers rather than hedging. Embedding a query needs the ~133 MB local model; shipping that to a visitor is not a free tier, and a hosted inference endpoint means someone pays per query. The page therefore states the measured gap it cannot show — on natural-language queries BM25 scores hit@1 0.340 against hybrid's 0.440 — and links the eval page for the full comparison. A demo that quietly implied it was showing semantic search would misrepresent the product to exactly the audience the epic is trying to reach. A cheaper path exists and is recorded rather than taken. A model2vec-class model is ~8 MB and would make a genuine in-browser semantic demo plausible — but that rests on the unverified ~29 ms/doc claim in keyless-dense-tier-local-static-embeddings, and it would make the docs site load its first external dependency, a property every page currently holds. Worth revisiting once that card is measured. All six steps of this epic are now done.

Every 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.

Eight 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.

Two 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.

Because -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 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.

Rule (#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.

After 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.

Two 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.

Rule 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.

registry.get(name) matches on full name, safe-name, or trailing path segment and returns the first hit with no ambiguity check — unlike catalog.resolve_one, which explicitly errors on a multi-tap ambiguous match. Three of the five default taps end in /skills, so after boost tap --defaults, boost untap skills or boost update skills silently resolves to whichever tap sorts first and the others become unreachable by short name. Raise on an ambiguous short-name match, mirroring resolve_one. Shipped. registry.get() is now tiered — exact owner/repo, then safe_name, then the bare repo tail — and refuses a short name that matches more than one tap instead of taking the first. Two corrections while fixing it: there is no sort, the winner was whichever came first in config.json; and the fix was half a fix as originally scoped. catalog.find() carried an independent, untiered tap in (e["tap"], tail) membership test, so with both taps configured angular/skills:brainstorming also matched microsoft/skills, and boost bundle apply took matches[0] — silently installing from the wrong tap, verbatim the defect this item exists to fix. Fixing only registry.get would have left the CLI self-contradictory: boost untap skills erroring while a Boostfile silently guessed. Both resolvers are tiered now and bundle apply refuses an ambiguous entry rather than picking one.

sync_plan flags every broken symlink under an enabled agent dir as stale regardless of whether it points into boost's store — the points_into_store check only runs on the live-link branch — and sync_apply unconditionally unlinks everything in stale_links. A user's own unrelated broken symlink sitting in ~/.claude/skills gets deleted by boost sync --apply with no ownership check. Only treat a broken symlink as boost-managed if its raw readlink() target resolves under the store dir. Shipped as store.points_into_store(), applied to broken and live links alike. Two things turned up while fixing it. boost clean carried the identical overreach — it unlinked every broken symlink under an agent dir with no ownership test at all — so it now shares the same helper; fixing only sync would have left boost contradicting itself. And the original check was a substring test (str(store_dir) in str(target)), which also matches siblings like ~/.agents/skills-backup; the comparison is component-wise now, and a relative readlink() target is resolved against the link's own directory before it is judged. Comparing properly is what exposed a Windows bug the sloppy check had been hiding: since 3.8 os.readlink() there returns the reparse point's substitution path, which carries the \\?\ extended-length prefix, so boost's own link reads back as a different drive and stopped matching the store at all. Every Windows leg of the matrix went red on it. The prefix is stripped before comparison, and the behaviour is pinned on every platform via ntpath, which imports fine on POSIX.

_retrieve_any treats any non-None dense result as final, but dense.retrieve() returns [] (not None) whenever every KNN neighbor gets filtered by kind mismatch or staleness — silently short-circuiting the documented "everything degrades to BM25" contract. Compounding it, dense.build()'s incremental path only prunes chunks for taps still present in the current entry set, so a tap removed via boost tap remove leaves ghost vectors in rag_vectors.sqlite forever, crowding the KNN pool on every future query. Distinguish "dense unavailable" from "dense had zero live hits," and prune removed taps on every build, not just changed ones.

_maybe_rotate reads the whole pulse file and atomically replaces it with a truncated snapshot — but two concurrent boost processes (explicitly expected per this repo's parallel-loop model) can both read, then both write their own snapshot, and whichever writes last silently discards any event the other appended in between. rotation_healthy() also opens the file with a bare p.open() and never closes it, relying on GC instead of a with block like every other open in the module. Rotate under a lock (or an append-only rename scheme), and close the handle explicitly. Shipped with util.try_lock(), a portable O_CREAT | O_EXCL advisory lock that needs neither fcntl (absent on Windows) nor msvcrt (absent everywhere else). It yields False rather than waiting: a process that cannot take it just returns, because another one is already trimming and blocking would trade a rare lost update for a common stall. A lock older than five minutes is stolen, so a process killed mid-rotation cannot wedge the feed forever. Inside the lock the file is re-read (the count that got us there was taken outside it) and anything appended since is carried into the new file instead of dropped. log() stays lock-free — O_APPEND writes of one short record do not tear, and making every command contend on a lock to protect an advisory feed would be the wrong trade. Writing the test for a torn append turned up a third defect neither the card nor the code had noticed: a single invalid byte in the feed raised UnicodeDecodeError, which is a ValueError and sails straight past the except OSError guard — so one bad byte crashed every command that logs, permanently. Both reads decode with errors="replace" now.

boost uninstall deletes a skill's store directory and lock entry straight through shutil.rmtree() with zero confirmation — every other destructive command (snapshot restore, cohort delete, profile delete, untap, replay rollback, bmad uninstall) gates on out.confirm() first. Shipped: a single prompt naming every skill about to go, before anything is touched, plus -y/--yes and the existing BOOST_ASSUME_YES bypass. The prompt is gated on sys.stdin.isatty(), not just on the flag. out.confirm() returns its default — False — when stdin is not a terminal, so the obvious if not out.confirm(...) would have turned boost uninstall x in every CI step, Makefile and Dockerfile into a silent no-op exiting 1. Guarding a destructive command must not break the callers that cannot see the guard; a regression test drives the command with a non-TTY stdin and no BOOST_ASSUME_YES to hold that line.

A skill installed with --agent narrowing (e.g. boost install foo --agent claude-code) records that subset in the lock, but boost update/ boost reinstall force-reinstall via store.install(entry, force=True) without passing only_agents — so link_agents relinks into every currently enabled agent and silently overwrites the lock's narrower agent list. Pass only_agents=lk.get("agents") on both force-reinstall paths, matching what the rule/workflow update path already does for scope.

boost lint --tap builds its target list without filtering by kind, so rule/workflow catalog entries (which have no SKILL.md) always report "missing SKILL.md," and repo-root items get scored against the entire tap directory instead of their actual file. Running it against any tap that mixes rules/workflows with skills makes every rule/workflow entry show a bogus error and a garbage score. Skip or special-case non-skill kinds, mirroring the kind-branching already used elsewhere in pkg.py.

store.preserved_agent_scope (PR #288) stopped update and reinstall widening a skill installed with --agent narrowing, but sync_plan() was a second, independent path to the same leak: it walked agents.enabled_agents() for every locked skill and reported a missing_link for any agent the skill was not linked into — the lock's recorded scope was never consulted. sync_apply then dutifully linked them, so a single boost sync undid the narrowing that install --agent asked for and rewrote the lock to match. It was left out of #288 because the fix is a real trade-off, not an oversight: boost sync is also how a newly enabled agent picks up skills installed before it existed, and honouring the lock's agents list would silently break that — agents records what is linked right now, so reading it as a scope would freeze every existing skill out of any agent enabled later. Resolved by separating the two questions. A new only_agents field records what the user asked for, written only by an explicit --agent and carried forward across update/reinstall; agents keeps meaning what is actually linked. sync_plan filters through scoped_agents(), which fails open — an entry with no declaration, which is every entry written before this field existed, still fans out to every enabled agent. So narrowing is honoured and the newly-enabled-agent path is untouched.

PR #289 added a third Dependabot entry, package-ecosystem: pip with directory: /, to give pyproject.toml's optional extras the proactive bump PRs they had never had. The first scheduled run after it merged produced eight PRs, and two pairs of them are duplicates: #301/#302 (twine) and #300/#303 (hypothesis) change byte-identical file sets — one PR from the / entry and one from the pre-existing /requirements entry, for the same bump. Merging either makes the other redundant, and Dependabot closes the twin automatically, so the cost is noise rather than breakage. It will recur every week. Worse, the entry cannot deliver what it was added for. Every constraint under [project.optional-dependencies] is either an open lower bound (sqlite-vec>=0.1.6) or explicitly listed in that entry's own ignore block (the pinned langchain 0.3 stack held back for ragas). Dependabot does not raise a version PR when the declared range already admits the newest release, so the set of pyproject.toml version updates this entry can ever produce is empty — which is why none of the eight touched pyproject.toml. Do not simply revert it. Dependabot security updates ignore the versioning strategy and fire on a vulnerable version inside a permitted range, so the entry does give the extras security coverage they previously lacked — the item it closed was right that [rag]/[bdd]/[perf] had only reactive pip-audit flags. The entry should be narrowed, not removed. Two candidate fixes, both needing verification against a real scheduled run rather than reasoning — Dependabot's file discovery is what got this wrong in the first place. First, scope the / entry so it stops matching requirements/**, leaving /requirements as the single owner of the hash-pinned lock. Second, if proactive extras bumps are genuinely wanted, that needs versioning-strategy: increase so open lower bounds are raised at all; otherwise accept that this entry is security-only and say so in the comment, which is the honest smaller change. Shipped — the second one, and #342 changed why. That change gave /requirements open-pull-requests-limit: 0, which silences the duplicate on one side but leaves the / entry as the only remaining path to a lock-regenerating pull request — precisely the thing that cannot be done correctly on a single platform. The duplicate stopped being the problem and the survivor became one. So the version-update side of the / entry is off too, and the reasoning is now written where the next person will look. It produces nothing wanted: every constraint under [project.optional-dependencies] is an open lower bound or sits in the entry's own ignore list, so its set of possible pyproject.toml version updates is empty — none of the eight PRs in that first run touched it. And it produces one thing actively harmful: four of those eight were byte-identical lock regenerations. Security updates ignore the limit and keep firing, which is the coverage the extras genuinely gained, and lock_toolchain.py --audit now catches a security PR that arrives having dropped a marker-gated pin. Both pip entries are pinned at limit: 0 by tests/unit/test_dependabot_config.py, alongside an assertion that neither entry is deleted — removing them would give up the security coverage that is the whole remaining point. Related: [[dependabot-regeneration-drops-platform-pins]].

boost onboard writes .boost/telemetry.json, a GitHub Actions workflow, and .skill-lock.json via a bare write_text() with no existence check, confirmation, or diff — unlike the sibling "write a generated file" helper elsewhere in the codebase, which always confirms before overwriting. Re-running it on a repo with its own tracked lock file silently clobbers it and still reports "created," even though it overwrote. Check dest.exists() and route through out.confirm() first.

Every Dependabot PR that touches requirements/*.txt is unmergeable, and the failure is not in the bumped package. Dependabot re-resolves the lock on Linux and writes that resolution back, which silently drops entries whose environment marker excludes them on the resolving platform — but the lock is installed with --require-hashes on Windows and macOS too, so the dropped pins become install failures on the platforms that need them. Two of two observed in one scheduled run. The hypothesis bump (#300/#303) deleted colorama==0.4.6 ; sys_platform == 'win32' — pytest's Windows terminal dependency — from all three of test-tools, coverage-tools and mutation-tools, so tests (windows-latest, 3.12) and (windows-latest, 3.14) both died in the install test deps step with the suite never running. The twine bump (#301/#302) deleted colorama and pywin32-ctypes (keyring's Windows backend, and keyring is twine's own dependency) plus pip and setuptools from release-tools.txt, failing the metadata job in Install build + validation tools. The GitHub-Actions bumps in the same run were all fine: they are pure SHA pins in workflow YAML and involve no resolution. scripts/lock_toolchain.py is the source of truth precisely because it resolves for every supported platform and keeps the conditional pins. Dependabot has no equivalent. The same run also rewrote the provenance comments from -r requirements/test-tools.in to -r test-tools.in, i.e. it compiled from a different working directory — the machine-independence that test_header_is_machine_independent already guards. The cheapest honest fix is to stop asking Dependabot to do this: drop the version-update side of the pip entries (or set open-pull-requests-limit: 0, which leaves security updates firing, since those are what the entries are actually worth) and regenerate the locks on a schedule with lock_toolchain.py instead. Whatever is chosen, it needs a guard: a lock that loses a platform-markered pin should fail its own gate rather than fail three Windows jobs two steps later, because the current failure names the install step and never mentions the missing package. Related: [[dependabot-root-pip-entry-duplicates-requirements]]. Progress: lock_toolchain.py now takes -P/--upgrade-package, so a Dependabot bump can be reproduced rather than merged — take the version it proposes, re-resolve that one package universally, and every other pin (markers included) stays as committed. Both open bumps were landed that way: hypothesis 6.161.6 to 6.163.0 and twine 6.2.0 to 7.0.0, four changed lines across five locks, with colorama and pywin32-ctypes intact. Shipped: both remaining halves. The /requirements entry now carries open-pull-requests-limit: 0, which switches off version updates — the ones that regenerate the lock — while security updates ignore the limit and keep firing, so the entry still earns its place. The / entry is untouched; narrowing that one is [[dependabot-root-pip-entry-duplicates-requirements]]. And the guard the card asked for exists: requirements/platform-pins.lock records every marker-gated pin by name and marker but not version, so a routine bump leaves it untouched and only a change in the shape of a resolution moves a line. lock_toolchain.py --audit diffs the locks against it and runs first inside --check, before uv is invoked at all — it reads only committed files, so it also runs in the unit suite and on a runner that could not resolve. A lost pin now fails naming the package, the group and the marker it lost, and prints the -P command that reproduces the bump properly. A lost pin and a new pin are reported differently on purpose: the same textual drift, but one is a broken install on a platform CI never resolves on and the other is routine — collapsing them into one "stale" message is how this stayed invisible the first time.

boost log/boost pulse accept -n/--limit as a bare type=int with no positivity check, and the slicing does out[:n] if n else out — a negative n becomes a Python negative slice, so -n -1 silently returns everything except the most recent event instead of erroring. discovery.py's --limit flags already share a _positive_int validator that rejects values below 1; reuse it here.

#342 set open-pull-requests-limit: 0 on the /requirements Dependabot entry, because Dependabot cannot regenerate a hash-pinned universal lock without dropping the pins whose environment markers exclude them on the resolving platform (see [[dependabot-regeneration-drops-platform-pins]]). That was the right call — every pip bump it raised was unmergeable — but it reverses the reason the entry was added in the first place: a pin with no update path is only half the job, and the dev/CI toolchain now has none. The trade is bounded rather than silent, which is why this is Med and not High. Dependabot security updates ignore the limit and still fire; pip-audit.yml runs weekly against the resolved closure and blocks on a live CVE (Dependabot only ever opened a PR); and osv-scanner.yml covers what a PR introduces. So the exposure is not "a vulnerable pin sits there unnoticed" — it is stale-but-not-vulnerable tooling, drifting further from upstream every week until something forces a bump. The replacement the card already named: regenerate on a schedule with scripts/lock_toolchain.py --upgrade and open the PR from that, so the resolution stays universal and every conditional pin survives. Four points worth getting right rather than guessing. First, it needs uv and the network — the required gate's --check already assumes both on CI, but no scheduled job currently sets them up. Second, --upgrade re-resolves all five groups, so a weekly cadence would land large multi-group diffs; per-group jobs, or a lower cadence, keep a bump reviewable, and the reason -P exists at all is that a bare --upgrade buries one package in unrelated churn. Third, a new workflow is not free in this repo: it must be zizmor-clean with every uses: pinned to a peeled commit SHA, carry narrow permissions, and — if it is ever made a required context — grow a merge_group: trigger, which check_required_checks.py enforces. Fourth, nothing needs to guard the output: lock_toolchain.py --audit and requirements/platform-pins.lock already fail closed on a lost marker-gated pin, so a regeneration job that got it wrong would be caught the same way a Dependabot PR now is. Blocked on a repository setting, and it is the same one that blocks [[demo-cannot-open-its-own-pr]]. The obvious shape for this — a scheduled job that runs lock_toolchain.py --upgrade and opens a pull request — cannot work here. Actions → General → Workflow permissions → "Allow GitHub Actions to create and approve pull requests" is off; the API reports can_approve_pull_request_reviews: false, and demo.yml already fails on every push to main with GitHub Actions is not permitted to create or approve pull requests. Declaring pull-requests: write does not help, as that card established at length. Building this the obvious way would produce a second workflow that is correct in the file and inert in reality. So the two items are coupled: flipping that one toggle unblocks both, which is worth knowing when weighing it — the decision is no longer about a demo GIF alone. That card is right that it is a real decision, since the toggle grants every workflow the ability to open pull requests. Two designs that respect the constraint, if the toggle stays off. Actions can still push a branch, so the job can regenerate the lock, commit to chore/toolchain-lock-YYYY-MM-DD and stop — leaving a one-click "Compare & pull request", with the expensive part (resolving five groups universally with uv) already done. Or it can open an issue containing the diff, which issues: write does permit. The branch is better: it carries the actual bytes rather than a description of them, and lock_toolchain.py --audit then runs against it as a normal PR gate once a human opens it. Either way the freshness gap this item exists to close narrows from "nobody is watching" to "a human clicks a button", which is the honest available improvement while the setting stands. The blocker is gone. This card is gated on the same repository setting as demo-cannot-open-its-own-pr, and the API now reports can_approve_pull_request_reviews: true. Confirmed working rather than merely configured: #353 was opened by github-actions[bot]. So the “honest available improvement while the setting stands” compromise described above — a workflow that only reports drift and waits for a human to click a button — is no longer the ceiling. A scheduled job can now regenerate the lock and open its own PR, which is what this card originally asked for. Deliberately left unimplemented here. It needs a real decision about cadence and about what happens when the regenerated lock fails lock_toolchain.py --check on a runner, and shipping an untested scheduled workflow that opens PRs against main is worse than shipping nothing. The value of this note is that the next person picking it up starts from “build it” rather than from “it cannot be built”. Shipped as .github/workflows/lock-refresh.yml, and the first thing that had to be re-checked was this card's own blocker. It states the work is blocked because Actions → Workflow permissions forbids creating pull requests, citing can_approve_pull_request_reviews: false. That is no longer true: the API now returns true, demo.yml succeeds on every push to main, and it opened #353 and #394 as github-actions[bot]. A blocker recorded once is a claim with an expiry date; this one had quietly lapsed, and the card would have kept the item shelved indefinitely. One PR for all five groups — a deliberate departure from what this card proposed. The card suggested per-group jobs so a bump stays reviewable. Two things measured while building it argue the other way. lock_toolchain.py has no per-group flag (--upgrade always re-resolves all five), so a five-job matrix would run the same resolution five times and commit one file from each. And a PR opened this way arrives with zero check runs — create-pull-request pushes with GITHUB_TOKEN, which never triggers workflows — so every one of them costs a human a manual Update branch before CI reports at all. Five PRs a month is five full CI runs and five manual unblocks to review what is usually a list of version bumps. Reviewability is bought instead with a monthly cadence and a per-group diffstat in the PR body. The other three constraints this card named were met as written. uv and the network are provisioned the same way ci.yml does it (pip install uv, then the script). --audit runs as its own invocation, because the script refuses it alongside --upgrade — auditing a file mid-replacement reads the old bytes — and a failure there means no PR is opened. Every uses: is pinned to the same peeled SHAs the repo already uses, permissions are contents: read at the top with the two writes scoped to the one job, and no merge_group: trigger is needed because this is not a required context (check_required_checks.py passes). Verified before pushing: the workflow parses, and zizmor reports no findings. That clean result was itself checked rather than trusted — re-running the scanner against a copy with ${{ github.event.head_commit.message }} spliced into a run: block produces a high-severity template-injection, so the scanner is genuinely reading this file. That check exists because an earlier workflow in this repo (shards.yml) shipped exactly that hole. Unproven until it runs: the first scheduled execution is the first end-to-end exercise.

_show_crashes has an empty-state branch and a listing branch that reads each crash-*.log, extracts its summary line, and swallows OSError on an unreadable report — only the empty-state message is exercised by any test. A regression in the glob sort, the summary-extraction regex, or the OSError fallback would ship undetected. Add a test that seeds one or more crash logs and asserts on the rendered listing.

serve.py's defenses against a malicious catalog skill_md path (_is_within, _safe_join_within, the ".." in rel.parts check) and its HTTP-handler failure modes are the least-covered lines in core/ — 84.5% file coverage, the lowest of any module — and no test actually feeds a ..-containing path through skill_text() to prove the guard fires. Add adversarial tests for the traversal guards and for _CatalogHandler's error paths.

core/logs.py uses stdlib logging with rotation and crash reports, but its file formatter only ever emits fixed plain-text lines — unlike core/journal.py, which already writes one JSON object per line for the pulse feed. A BOOST_LOG_FORMAT=json option emitting the same fields as structured records would let ~/.boost/logs/boost.log feed straight into jq or a log aggregator instead of needing regex parsing.

core/ai.py's CLI and API call paths both catch their failure modes (timeout, OS error, URL error, bad JSON) and return None — but neither ever calls into the logger, unlike the rest of boost. A user whose expired key or flaky network silently degrades every AI-assisted command to its heuristic fallback has no trail to diagnose why, even with --debug. Add a one-line logger.debug(...) in each except branch.

make eval reports BM25 recall@10 = 1.000 against the pinned corpus in tests/eval/taps.txt. Run the same script against a real 83-tap install and it reports 0.720 — below the gate's own 0.85 floor — with hit@1 0.407, MRR 0.526, nDCG 0.566, and rule the weakest kind at 0.500 recall / 0.286 hit@1. The gate has been advertising a perfect score while real-world recall sits at 0.72, and it is blind in three separate ways: (1) recall-only flooring. --fail-under gates recall@k and nothing else, so a total hit@1 collapse from 0.780 to 0.000 would still pass. (2) regression detection is switched off. Makefile passes --regression-eps 1, which tolerates any absolute drop up to 1.0. (3) a kind oracle. Grading per-row by the golden set's kind field tells the retriever whether the answer is a skill, a rule or a workflow — which boost search never knows unless the user passes --kind. That single filter is worth +0.073 recall and +0.073 hit@1, enough to flatter any change measured against it. The consequence is that no retrieval work in the repo is currently falsifiable, which makes this a hard prerequisite for every other item in this group rather than a cleanup. Note the companion gate is in better shape: make evals (scripts/eval_gate.py) already floors five metrics and runs a paired bootstrap for significance — its limitation is corpus size (57 entries, 1 tap), not metric design, so the work is to grow an instrument that exists rather than to build one. Also needed: queries that only body text can satisfy. The golden set grades items by name, so it scores a surface-only index above the full-content one and would cheerfully greenlight deleting body indexing altogether. Half of the "also needed" already exists. This card asks for queries that only body text can satisfy, on the grounds that a name-graded set would greenlight deleting body indexing. tests/eval/golden-natural.jsonl (shipped in #360) is 50 such queries: each is written from its target's own description and has the target's distinctive name tokens deliberately stripped — a mechanical check rejected five drafts that had leaked one — so a surface-only index cannot answer them. It was written before any engine ran against it and scored once, which is the same fitting-and-reporting discipline this group needs. It corroborates this card's thesis from a second, independent direction. This card shows the gate blind to corpus size: 1.000 on a handful of taps against 0.720 on 83. The natural set shows it blind to query shape on the same corpus — BM25 scores recall 1.000 / hit@1 0.780 on the keyword golden set and 0.690 / 0.240 on natural-language queries over identical data. Two different axes, same conclusion: the number the gate reports is not a number about retrieval. What it does not fix is the corpus-size half, which is this card's own finding and remains open — 50 queries over 6 taps cannot speak to an 83-tap install. The two are complementary rather than overlapping, and combining them (natural-language queries over a realistically sized corpus) is the instrument this group actually wants. Two of the three blindnesses are now closed, and the third was never true of the committed harness. (1) recall-only flooring is fixed: --floor NAME=VALUE is repeatable and gates any metric, and make eval now floors all four — measured BM25 on the pinned corpus is 1.000 / 0.780 / 0.860 / 0.895, with each floor about 0.12 under its measured value so upstream drift cannot flake the build. A misspelled metric name is a hard error rather than a silently skipped floor, since a floor that never fires is worse than no floor. (3) the kind oracle does not exist in scripts/eval_retrieval.py. Checked directly: every ranker — catalog_ranker, bm25_ranker, dense_ranker, hybrid_ranker — is called with the query alone, and there is no kind= argument anywhere in scripts/ or evals/, before or after #360. The golden set's kind field feeds the per-kind reporting slices in _aggregate and nothing else, so the +0.073 figure quoted above cannot have come from this harness. Recording it here rather than silently deleting the claim, because the number was real in whatever script measured it. A defect the card did not predict: the baseline was not keyed to the query set that produced it. Running the natural-language set printed eight confident REGRESSION vs baseline lines — BM25 recall 1.000→0.690, hit@1 0.780→0.240 — which were not regressions but the gap between two different question sets, and --save-baseline on the natural set would have silently overwritten the keyword set's numbers with them. Baselines are now keyed by name@content-digest, so editing a query in place invalidates its baseline rather than quietly re-grading against numbers that no longer describe it. Still open: the corpus-size half and --regression-eps 1, which is a symptom of the corpus tracking upstream HEAD rather than pinned commits. Pinning taps.txt by commit SHA is the change that would make regression-vs-baseline meaningful again; the absolute floors added here are drift-tolerant by construction and do not depend on it. The corpus-size half is shipped, and the tap count in this card was wrong. tests/eval/taps.txt never held 23 repos — it held six. Twenty-three was the file's total line count, seventeen of which are comments, and the number propagated from here into CLAUDE.md. The error understated the card's own case rather than overstating it: the comparison was six taps against a real eighty-three, not twenty-three. Grown to twenty taps (10,145 entries, 79.7% sharing a name), and the effect on the required gate is the finding this card predicted. Same golden set, same queries, only the corpus changed: recall@10 0.978 → 0.863 · hit@1 0.791 → 0.473 · MRR 0.854 → 0.607 · nDCG 0.882 → 0.662 Three of the four floors fail outright once the corpus is realistic. The floors have been re-derived against the twenty-tap numbers at the same ~10% relative headroom, so the gate now floors something a user would recognise. Lowering a threshold normally deserves suspicion, so the reasoning is stated plainly: the old floors were calibrated against a corpus small enough that BM25 scored 1.000, and a floor calibrated on an unrepresentative corpus measures the corpus. The absolute drop is recorded here precisely so it reads as a finding rather than as goalposts being moved. That hit@1 0.473 is the honest headline: at twenty taps, fewer than half of these queries put the right item first. It is not a regression — it is what users already had, now visible. Cost to CI is ~20 s of tapping on a cold run (measured ~1 s/repo) and nothing on a warm local one. Still open: twenty taps is closer to eighty-three than six was, but it is not eighty-three, and --regression-eps 1 still stands down regression detection because the corpus tracks upstream HEAD rather than pinned commits. Pinning by SHA remains the change that would make regression-vs-baseline meaningful.

The sweep job failed on #373 with 20 violating node(s) in docs/mcp-hub.html — [serious] color-contrast on every .topic-tag, reported as 3.57:1 (#656a81 on #0e0f16, 8.3pt, weight normal) against the 4.5:1 threshold. That PR touched docs/eval.html and the roadmap items. It did not touch mcp-hub.html, its CSS, or anything either imports. It is a flake, and that much is established rather than assumed. Four checks: the PR branched from 170d52c, and on that exact commit the same page passes with 25 rules; sweep is green on all of 86163e0, 4e22379, 088f1e2, 678bbc2, 93d82a6, 584997d, e6177a6, 693601f and 170d52c; axe-core is pinned at 4.12.1 through npm ci and a committed lockfile, so it is not dependency drift; and re-running the identical job passed with no code change. The cause is NOT established, which is why this is a card and not a patch. Two plausible mechanisms were checked and both ruled out. Webfont loading: --mono is a pure system stack (ui-monospace, "SF Mono", SFMono-Regular, Menlo, Consolas, monospace), so there is no font to wait for. Reveal animations: mcp-hub.html carries no .reveal rule and no IntersectionObserver. A remaining hypothesis worth testing is that axe walks ancestors to resolve an effective background, and a semi-transparent panel composited over the page gradient resolves differently depending on paint timing — but that is a guess, and it should be reproduced before anything is changed. Do not "fix" this by adding a settle delay and declaring it solved. A document.fonts.ready plus requestAnimationFrame wait is the obvious patch and it may well work, but applied without reproducing the failure it papers over the symptom and makes the next occurrence harder to read — the same trap as a tolerant lookup key that turns a loud error into silent wrong behaviour. Reproduce first: loop a11y_check.mjs over mcp-hub.html some tens of times on a runner and see whether the violation appears, then fix what that shows. Why it is worth doing at all. A required check that reddens on a file the author never opened is worse than a slow one: the natural response is to dismiss it as noise, and the next real color-contrast regression gets dismissed with it. Note also that 3.57:1 is genuinely below AA — if the flake turns out to be axe correctly catching a contrast defect that it usually misses, the fix is the token, not the harness. Reproduction attempt: blocked on macOS, do it on a runner. The pinned harness installs and runs fine locally (npm ci with npm_config_cache redirected — ~/.npm/_cacache is not writable in the agent sandbox), and BOOST_CHROME_BIN accepts /Applications/Google Chrome.app/Contents/MacOS/Google Chrome. But every launch dies with The browser is already running for <fresh profile dir>, on a newly created userDataDir each time, because Chrome on macOS is a single-instance app: launching the bundle binary attaches to the running instance instead of starting an isolated one. Nothing to fix in the harness — it is why the reproduction loop belongs on a Linux runner (or against Chrome for Testing), not on a developer laptop with Chrome open. Cause found — and my earlier “maybe axe is right about the contrast” caveat was wrong. It is a harness defect, and the harness predicted it in a comment. a11y_check.mjs loads each page over file:// and passes --allow-file-access-from-files, with this note: “without this Chrome treats each file as its own opaque origin and the stylesheet never applies, which would make every contrast result meaningless.” That is exactly what happens intermittently. Every failing element resolves its colour from var(--text-3), defined once in style/boost.css and linked relatively (../style/boost.css). The arithmetic settles it. The shipped token is #767c96, which is 4.85:1 on #07080f — passing AA, and it was already raised once from #676d86 (3.9:1) by #243. The colours axe reported — #505467 on roadmap.html, #656a81 on mcp-hub.html — appear nowhere in this repository. They are Chrome's unstyled fallbacks. So both “contrast failures” were the same defect: the stylesheet silently not applying. The fix is therefore not a colour and not a settle delay. Both would be treating a symptom. The real options are to stop depending on a flag that intermittently fails — serve the docs over a throwaway http:// origin for the sweep, or inline the stylesheet into a temporary copy — and, more importantly, to fail loudly when it happens: assert that a known token resolves before running axe at all, so an unstyled page reports “stylesheet did not load” rather than twenty plausible-looking contrast violations against colours that do not exist. That guard matters more than the flake. Without it the sweep produces confident, specific, entirely wrong findings — which is what sent me to check a token that had been correct for months. Reopened, then actually solved. Both of my earlier diagnoses were wrong, and the card records them rather than quietly overwriting. The stylesheet-load theory in #384 predicted that if the flake recurred the sweep would report page is unstyled. It recurred on #386 and reported 10 contrast violations on a fully styled page — so that prediction failed, exactly as the card invited. What broke it open was a third phantom colour. Across three runs axe reported #505467, #656a81 and #363948, none of which exist anywhere in this repository. A fixed browser fallback cannot drift. Measured against the real token #767c96, those three sit at 44%, 72% and 20% of its luminance — the signature of one colour composited at varying opacity, not of three different colours. The cause is .js .reveal: opacity: 0 transitioning to 1 over 600 ms. axe computes contrast from the composited pixel, so running mid-transition grades a half-faded element. The failing nodes are .count spans inside <section class="block reveal">. My earlier “no .reveal rule on this page” check was simply wrong: I grepped the page, and the rule lives in the shared style/boost.css. The fix is one line, and the stylesheet was already prepared for it. boost.css carries a prefers-reduced-motion: reduce block forcing opacity: 1 !important on .reveal; the sweep never asked for that media feature. It now calls emulateMediaFeatures before navigating. That is better than waiting out the animation, because it audits the page as a motion-sensitive user actually receives it — a settle delay would have papered over a timing race while testing a state no user is guaranteed to see. The #385 guard stays: it is orthogonal, it caught a real mis-assumption about commands.html on its first run, and an unstyled page still deserves to fail loudly. Closed. The cause is understood (reveal-animation compositing), the fix shipped in #388, and the #385 stylesheet guard stays as an orthogonal safety net. Verified on #388: all seven pages ran the real axe check — a11y-check: OK — 7 pages clean — including docs/roadmap.html, the page that had failed on the two runs immediately before. Worth keeping the trail: this card went through three wrong diagnoses before the right one — a genuine contrast defect, then a stylesheet-load failure, then the animation. Each was killed by measurement rather than argument, and the one that cracked it was noticing a third phantom colour, because a fixed browser fallback cannot drift.

Turn 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.

PyPA'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.

Scan 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.

Gate 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)."

One external surface over everything the offline gates measure separately: bugs, code smells, security hotspots, duplication and a coverage overlay, decorating each PR with a quality gate. Free for public repos. Settings live in sonar-project.properties — boost_cli as sources with tests declared separately (so the suite's asserts do not score as duplication), the generated version stub and boards excluded, coverage read from the Cobertura report CI already emits rather than re-running the suite. Non-blocking and inert until onboarded: without SONAR_TOKEN the job skips and writes what to do into the run summary, so a skipped run explains itself instead of looking broken. Not added to required checks — boost's own gates stay authoritative because they run offline and a contributor can reproduce them.

Generate 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.

Google's atheris instruments the bytecode and evolves inputs toward uncovered branches in boost's two hand-rolled parsers — the SKILL.md frontmatter reader (a stdlib-only YAML subset, so no upstream project's fuzzing covers it) and the tap-spec parser. It has already paid for itself: the frontmatter harness found that numeric coercion was lossy. version: 1.10 is ten patch releases past 1.1, but float("1.10") is 1.1 — so boost read a skill published at 1.10 as 1.1, compared it as older than 1.9, and never offered the update, with boost outdated reporting "everything up to date" while the tap was nine releases ahead. Note that "it doesn't crash" would have missed it entirely: the invariant has to compare the parsed value against the source text. The seeds through every invariant run in the required suite so a harness cannot rot; the coverage-guided run is a weekly non-blocking job, because a timed search is not reproducible enough to gate a merge. Targets follow the OSS-Fuzz Python contract, ready for continuous runs once boost qualifies.

core/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.

core/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.

[tool.mypy] in pyproject.toml sets only python_version/ files, leaving mypy in its default permissive mode — a function with any untyped parameter has its body skipped entirely. All 76 cmd_* functions across boost_cli/commands/*.py take a bare argv, and a third have no return-type annotation, so the required "zero mypy errors" lint gate isn't actually checking most of the CLI's dispatch logic. Scoping disallow_untyped_defs (or at least check_untyped_defs) to boost_cli.commands will surface a real backlog — exactly what the gate is supposed to catch.

Dependabot #236 bumps ruff 0.15.22 → 0.16.0 and the ruff step fails with 83 errors. None of them are new code — 0.16 widened the default selection, and because pyproject.toml uses extend-select (which adds to the defaults rather than replacing them), every newly-defaulted family switched on at once. The project only ever opted into S, B, SIM, C4, PERF, RUF, UP; what fires now is I001 (33), PLW1510 (19), BLE001 (9), ISC004 (4), plus TRY, PLR, PIE, DTZ, RET, PYI, FLY and — awkwardly — FURB167, a family the config explicitly delegates to refurb via external = ["FURB"]. So this is a policy decision, not a lint fix, and there are two honest answers. Pin the policy: switch extend-select to a full select = [...] so the rule set is stated outright and a future ruff release can never widen it again — the bump then lands with zero code changes. Or adopt some of them: I001 (import sorting) and the 43 auto-fixable errors are cheap and arguably worth having, while PLW1510 (subprocess.run without check=) is 19 real call sites that each need a judgement about whether a non-zero exit should raise. DTZ005/006 (naive datetime.now()) is worth a look on its own merits given the clock-racing test. Recommended: pin select first so the bump is unblocked and the gate stops depending on an upstream default, then adopt families deliberately in follow-ups. Shipped that way in #260: pyproject.toml now states the rule set outright with select = ["E4", "E7", "E9", "F", "S", "B", "SIM", "C4", "PERF", "RUF", "UP", "I"], so a future ruff release can only change how the chosen rules behave, never which rules run. I001 was adopted (34 sites, entirely mechanical); ISC was considered and declined — all 8 hits were deliberate line wrapping. external = ["FURB"] is preserved, so FURB167 stays refurb's call rather than ruff's. requirements/lint-tools.txt carries ruff==0.16.0 and Dependabot #236 was closed as superseded. PLW1510 and DTZ005/006 remain unadopted and are the deliberate follow-ups.

tests/unit/test_toolchain_lock.py (added with the lock-stability fix, #248) asserts every requirement is pinned with ==. Its regex is (?P<name>[A-Za-z0-9][A-Za-z0-9._-]*)(?P<spec>==[^\s;\\]+)? — and the name class has no [ or ]. So against coverage[toml]==7.15.2 the name matches coverage, the spec then fails to match because the next character is [, and spec comes back None. The test reports "coverage is not pinned with == in test-tools" about a line that is pinned exactly. Latent today — nothing in requirements/*.txt currently carries an extra — but uv/pip-tools emit name[extra]==version routinely, so the first legitimate extras-bearing pin will block the gate with a message that points at the wrong thing. Fix by allowing an optional extras group in the name, e.g. [A-Za-z0-9._-]*(?:\[[^\]]+\])?, and add both forms to the test's own cases. Found the honest way: Dependabot #253 (hypothesis) regenerated the lock and tripped this assertion. That PR is genuinely bad for an unrelated reason — it collapses coverage==7.10.7 ; python<'3.10' and coverage==7.15.2 ; python>='3.10' into a single coverage[toml]==7.15.2, and 7.15.2 requires Python ≥3.10, so it silently drops the 3.9 leg this project promises. The gate correctly refused it. But it refused for the wrong reason, and that is the part worth fixing: the same message will one day reject a lock that is perfectly fine. See the pytest card — collapsing a marker-split pin is the recurring shape here, and is worth its own assertion.

After 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.

TestRelTime builds its input with iso_ago(n) = (now() - n).strftime("%Y-%m-%dT%H:%M:%SZ"), which truncates sub-second precision, then asserts on util.rel_time() calling now() a second time. The elapsed delta is therefore n + frac(first_now) + runtime, and rel_time floors it — so whenever frac(first_now) + runtime ≥ 1.0 the bucket is one higher than the test expects. Observed failing on tests (ubuntu-latest, 3.14): assert '31s ago' == '30s ago'. The off-by-one cases are the mild ones. iso_ago(59) and iso_ago(59 * 60) sit directly on a bucket boundary, so the same race flips "59s ago" to "1m ago" and "59m ago" to "1h ago" — a different unit, not a neighbouring number. Every assertion in the class shares the window; it is narrow on a quiet machine and widens with runner load, which is why it reads as random redness rather than a broken test. Fix by giving the test a fixed clock — monkeypatch util.datetime (or inject a now seam into rel_time) so both reads come from one frozen instant, and the boundary cases become exact rather than probabilistic. Freezing is preferable to widening the assertions: the boundaries are precisely the behaviour worth pinning. Shipped. It came true exactly as described: the mutation gate on main went red with assert '1m ago' == '59s ago' — the iso_ago(59) boundary named above — which skipped the release. Fixed by freezing the clock rather than widening the assertions: a frozen_clock fixture pins util.datetime to one instant and iso_ago measures back from that same instant, so both reads can no longer drift apart. The two absolute-date cases were rebased onto the frozen instant too — they read the real clock and would otherwise never have agreed with it.

boost'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.

Catches 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.

Google'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.

Run 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.

Beyond 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.

Enforce 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.

publish.yml triggers on workflow_run: [ci] and gates only on github.event.workflow_run.conclusion == 'success' — it never checks the independently-triggered pip-audit.yml or package-metadata.yml workflows that run on the same push. A merge that fails the live-CVE gate or the twine/metadata check still auto-publishes to PyPI as long as ci itself is green. Shipped as the second option: scripts/release_preflight.py runs as the release job's first step — before release-drafter creates the tag, so a blocked release leaves no published Release behind — and waits for each required workflow to conclude for git rev-parse HEAD, the commit actually checked out and about to be built. Folding them into ci.yml was rejected: pip-audit also runs weekly on a cron, which inside ci.yml would drag the whole 9-cell test matrix along with it. The gate fails closed — red, cancelled, skipped, never started, still running at the deadline and an unreadable API reply are all refusals. Silence is the dangerous case: a gate that never ran leaves nothing red to see, so it must never read as consent.

A hung step — a stalled tap clone, a wedged smoke-test subprocess — runs until GitHub's default job timeout instead of failing fast, costliest across the 3 OS × 3 Python tests matrix. (The card said 8 workflow files; there are 24 now, of which only fuzz.yml and sonarcloud.yml had a timeout.) Shipped: 24 jobs across 22 files, with the numbers taken from measured durations over recent runs rather than guessed — mutation's slowest observed run was 24.8m so it gets 60, the tests matrix peaked at 8.3m so it gets 30, publish's release job gets 45 because the new release preflight can legitimately wait on a sibling gate, and everything else ran under 2m so it gets 15. A timeout that trips on a normal run is worse than no timeout. osv-scanner.yml's scan-pr is the one job left without one: it delegates to a reusable workflow via a job-level uses:, and GitHub rejects timeout-minutes there outright — the bound has to live in the called workflow. A unit test holds the line so a job added next month cannot quietly arrive without one, and it refuses to pass vacuously if its own parser stops finding jobs.

.github/dependabot.yml declares pip for directory: /requirements, so the hash-pinned dev/CI toolchain does get weekly bump PRs. What it does not cover is pyproject.toml at the repo root: Dependabot only scans manifests under the declared directory, so the optional extras — [rag] (sqlite-vec), [eval] (ranx, ragas and the pinned langchain 0.3 stack), [bdd] (behave), [perf] (pytest-benchmark) — never get proactive version-bump PRs, only reactive pip-audit CVE flags. Low impact by design: [project].dependencies is empty, so none of this reaches anyone who installs boost-skill-cli — it is contributor-facing only. The fix is a second pip entry with directory: /. Weigh it against the noise: the [eval] stack is deliberately held at langchain 0.3 because ragas 0.2.x breaks against langchain ≥1.0, so that one will raise PRs that must be closed unmerged until ragas catches up.

Nothing in CI checks SPDX license compatibility of resolved dependencies — pip-audit gates known CVEs, not license terms, and the [eval]/[rag] extras pull in a nontrivial transitive closure (the langchain stack, ragas, sqlite-vec) whose licenses are never verified against boost's own. Add a pip-licenses --fail-on (or reuse lint) step to package-metadata.yml to catch an incompatible transitive dependency before an extra ships it.

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 posture metrics, and they must not be dismissed as "false positive" the way the serve.py traversal alerts legitimately were, because that misrepresents the repo's security posture. Triaged 2026-07-25, re-triaged 2026-07-29 against the 7 still open. Fixed — TokenPermissions #26/#27/#28: ci, codeql and adapter-conformance had no top-level permissions: block at all, scoring 0. Added contents: read as the least-privilege default. Intentional, leave — TokenPermissions #39/#37/#25/#24: publish.yml needs contents: write to create the release and tag, osv-scanner needs security-events: write to upload SARIF, and ci.yml's tests job needs contents: write for the coverage-badge push. "Fixing" these breaks the release pipeline. They should be dismissed as used-in-tests/acceptable-risk with a reason, not left open to rot the list. Correction — PinnedDependencies was NOT "not code-fixable". The first pass filed #40/#41/#48 under "npx and pip invocations inside steps, not actions, so SHA-pinning does not apply". That reads the check as being about action SHAs, and it is not: for npm the remediation is a committed lockfile, and all three hits were npm install steps. tests/visual/package.json pinned its two direct deps exactly — and .gitignore then excluded the lockfile, so 79 transitive packages resolved fresh on every run. theme-lint was worse: npm install stylelint@16 eslint@9 re-resolved the whole linter every run, so the linter CI executed was never the linter anyone reviewed. Both trees are now hash-pinned (181 + 81 packages, integrity on every one) and installed with npm ci; dependabot.yml gains both npm directories, because a pin with no update path is only half the job. What the pin immediately exposed. Committing the lock made osv-scanner able to see the transitive tree for the first time, and it failed the branch at once on CVE-2026-14257 (brace-expansion, CVSS 7.5, unbounded expansion → OOM). Pre-existing, not introduced: the old floating npm install eslint@9 resolved the same package, invisibly. The advisory's range is all versions below 5.0.8, so the 1.x maintenance line has no fix — and the obvious patch, an overrides entry forcing brace-expansion@^5, breaks eslint: v5 exports { expand } where minimatch@3 requires a callable default, so eslint "style/**/*.{js,mjs}" dies with "expand is not a function" while plain eslint style/ still passes — a green-looking linter with a broken glob path. The real fix is upstream: eslint@10 depends on minimatch@^10.2.5, which requires the patched brace-expansion@^5.0.8. Bumped 9.39.5 → 10.8.0; all 262 packages across both locks now return zero OSV advisories. Open by decision, correctly — BranchProtectionID #33 (4/10) and CodeReviewID #34 (0/26 approved changesets) are two readings of one deliberate choice recorded in its own card: require status checks, do not require reviews, because the working model is parallel loop/* branches that self-merge and there is no second reviewer. Every warning Scorecard prints under #33 — stale-review dismissal, required approvers, CODEOWNERS review, last-push approval — follows from that one choice. They stay open because the score is accurate: this repo really does merge without human review. Dismissing them would be the lie. Clears itself — MaintainedID #35 is "repository was created within the last 90 days". Created 2026-07-17, so it resolves on its own around 2026-10-15. Nothing to do but not dismiss it. Needs a human, not a commit — CIIBestPracticesID #36 is the one remaining actionable finding, and it cannot be fixed from a branch: it asks whether the project is registered for an OpenSSF Best Practices badge, which means creating a project entry at bestpractices.dev under a real account and answering its criteria. The prerequisites are already in place (LICENSE, SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, a published CI gate); only the registration is missing.

GET /branches/main/protection returns "Branch not protected". Scorecard flags it (BranchProtectionID, score 0), but the sharper way to see it is this: CLAUDE.md says "never merge onto a red release" and "every merge to main cuts a PyPI release" — and nothing enforces either. 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 decision, not a bug, 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 lock_toolchain --check failure that belonged to none of them. But protection cuts both ways here: the repo's whole working model is parallel loop/* branches opening and merging their own PRs, so "require pull request reviews" would deadlock every loop (there is no second reviewer), and that same absence is what keeps CodeReviewID pinned at 0/30. The shape that fits: require status checks to pass (at minimum lint and the tests matrix) and require branches to be up to date, but do not require reviews. That enforces the release rule that actually matters while leaving self-merge intact. Decide before adding more concurrent loops, not after. Update — the blocker is gone. This prescription was not implementable as written: lint named three different jobs (ci, markdownlint, theme-lint), and GitHub matches required checks by name alone. Those collisions are now renamed, the required list is checked-in at .github/required-checks.txt and gated against drift, and python3 scripts/check_required_checks.py --print-api emits the exact payload — with required_pull_request_reviews: null, so self-merging loops keep working. Still a decision, but now a one-command one. Shipped. The decision was taken as prescribed — status checks yes, reviews no. GET /branches/main/protection now returns strict: true with required_pull_request_reviews absent, so a red gate blocks the merge that would have cut the release, and loops still self-merge. One correction to the prescription above: requiring "at minimum lint and the tests matrix" is right, but the list must contain only checks that run on every PR — the first version also required four path-filtered docs checks, which report on some PRs and not others and would have hung any PR that touched no matching file. See required-checks-can-declare-a-check-that-deadlocks-prs.

The install step ran pip -q install "${{ matrix.pip }}". Quoting is correct for the two legs whose matrix value is a single token (crewai[anthropic], openai-agents[litellm]) — the brackets would otherwise be shell globs. But the LangGraph leg's value is a requirement list, langgraph langchain-anthropic, so the quotes handed pip one bogus requirement and it refused before installing anything: ERROR: Invalid requirement: 'langgraph langchain-anthropic'. The leg landed 2026-07-22 and the workflow was schedule/workflow_dispatch only, so nothing exercised it on its own pull request — the first Monday cron was its first execution ever, five days later, and it has a 0% pass rate. It read as upstream framework drift; it was never that. Reproduced locally, and with the step fixed the whole leg passes end to end against live PyPI: langgraph 1.2.9 + langchain-anthropic 1.5.2 resolve clean, boost adapt --to langgraph renders, and the factory builds a real langgraph.graph.state.CompiledStateGraph. Fix: pass the spec through env: (rather than inlining a ${{ }} expansion into run:, the shape zizmor flags) and let it word-split under set -f, which keeps the [extra] brackets literal — without it, crewai[anthropic] glob-expands against any matching filename. Also added a narrow pull_request trigger on adapters.py and this workflow, so an edit to the thing under test is tested on the PR that makes it. That trigger is path-filtered, so it must stay out of the required-check list: a required context that does not report on a PR leaves it pending forever.

.github/required-checks.txt declared 21 contexts and scripts/check_required_checks.py reported "21 required, 22 PR check names, no ambiguity" and exited 0. Four of those 21 — validate, markdown-lint, theme-lint and vale — are produced by path-filtered workflows. When a pull request touches none of a workflow's paths:, GitHub does not create a pending check run that later resolves; it creates no check run at all. Branch protection then waits forever for a status that is never coming, and the pull request can never merge. Applying that list would have bricked the repository — and --print-api would have emitted the payload to do it. The cause is one regex. The gate decided "runs on pull_request" with re.search(r"^\s{2}pull_request:", header), which is true for any workflow that mentions the trigger, whether or not paths:, paths-ignore: or types: [labeled] narrows it — precisely the distinction that decides whether a required check deadlocks. Demonstrated live rather than argued: the PR that fixed the adapter-conformance install touches no style/** file, and its 30 check runs contain validate, markdown-lint, vale, check and sweep — but no theme-lint. Requiring theme-lint would have hung that PR permanently. Fix: classify the trigger as none/always/filtered and refuse any required name that resolves only to a filtered workflow, with an error that names the culprit file. The four docs checks move to a commented block explaining why they are useful but not requireable. The list is 17 contexts, all verified to report on every PR. Ten new tests cover the rule and all ten fail against the previous script.

The job summary step is marked if: always() so a run still reports when something upstream died. Its last line was [ -n "$SMOKE" ] && echo "- **Smoke suite:** ${SMOKE}", which is the final command of the { ... } >> "$GITHUB_STEP_SUMMARY" group, and that group is the final command of the step. GitHub runs shell: bash as bash --noprofile --norc -eo pipefail, so with $SMOKE empty the AND-list's status of 1 becomes the group's status and then the step's exit code. $SMOKE is empty precisely when smoke.sh never printed its == results: line — an earlier step died first, or smoke never ran. That is the exact scenario always() exists for, so the reporting step failed in the one case it was written to survive. Reproduced directly: exit 1 with no match, exit 0 with one. It never masked a real failure (the job is already red when this happens), but it planted a second misleading red step, and would have silently reddened the job if that step were ever moved into a green context. Replaced with an if block.

The console-health step carries if: always() with the comment "an HTTP failure above must not hide a console failure here — they are different breakages and both belong in one report". But the two steps it depends on — actions/setup-node and the npm install that fetches puppeteer — had no if: at all. A failure in the HTTP smoke skips both, so the console check then runs with no node_modules and produces an environment error rather than a console verdict. The run history separates the two cleanly: an environment error exits 2, a genuine console failure exits 1. Run 30214061945 has HTTP smoke = failure, setup-node = skipped, npm = skipped, console = failure (exit 2), while the four runs where the npm install actually happened all exit 1. So in exactly the case the always() was written for, the second signal was destroyed instead of preserved — and the report said "console check failed" when it meant "the console check never ran". Fixed by putting always() on the setup steps too, so the dependency chain the final step needs survives the failure it is meant to outlive.

.markdownlint-cli2.jsonc globs **/*.md and its ignores list carved out .claude/** and docs/roadmap/items/** but not tests/fuzz/corpus/**. So 12 of the 21 files being prose-linted were deliberately-malformed YAML-frontmatter seeds for the atheris fuzzer — 07-unterminated.md, 09-unbalanced-quote.md, 12-bom.md and friends. Malformed is their entire purpose, and they passed the gate only by luck. That luck was going to run out by design. fuzz.yml exists to mine new malformed inputs and ship them as reproducers (-artifact_prefix=artifacts/, uploaded as fuzz-crash-<target>), and one such crash artifact already exists from a real run. The moment anyone committed it into tests/fuzz/corpus/frontmatter/ — exactly what the workflow is for — an unrelated prose-style gate would have gone red for a reason with nothing to do with prose, on a file whose whole point is to be invalid. Fixed by adding tests/fuzz/corpus/** to ignores. Verified with the pinned markdownlint-cli2@0.18.1: 21 → 9 files linted, 0 errors, and a planted crash reproducer no longer reddens the gate.

Only ci.yml declares merge_group among its triggers. The other workflows producing required contexts — codeql.yml, pip-audit.yml, package-metadata.yml, osv-scanner.yml — run on pull_request only. GitHub's merge queue evaluates the required checks against the temporary merge_group ref, not against the pull request. So the moment a merge queue is turned on, codeql-analyze, pip-audit, metadata and scan-pr / osv-scan would never report on the queued ref and every enqueued PR would sit forever — the same never-reports deadlock as required-checks-can-declare-a-check-that-deadlocks-prs, arriving through a different door. Nothing is broken today; no merge queue is configured. Filed because the trap is invisible until the switch is flipped, and because the pressure to flip it is real: with strict: true and several concurrent loops, every merge forces every other open PR to rebase and re-run its full matrix, which is exactly the problem merge queues solve. Fix before enabling, not after: add merge_group: to each workflow that produces a required context, and extend scripts/check_required_checks.py to fail when a required name comes from a workflow lacking that trigger — the same gate that now catches paths: filters.

Measured across twelve consecutive runs, the mutation job took 20.6–39.2 minutes (median ~27) while the next-longest job in the same run, tests (windows-latest, 3.12), took 8.6. One job was the critical path, and it was charged twice per change: once blocking the pull request, then again on main, because publish.yml fires on workflow_run after CI completes — so the PyPI release waited on it too. PR #278 merged at 20:52 and the release landed at ~21:20, essentially all of it this gate. The cost is ~10,502 mutants over 45 files in boost_cli/core, run 4-way parallel (max_children defaults to os.cpu_count(); ubuntu-latest is 4 vCPU). Generating them takes 5.3 seconds — the entire cost is executing the unit suite ten thousand times. A measured local baseline: 1600s wall, 6.70 mutations/second, 8850/10502 killed (84.3%). Two independent wins, because they apply to different pull requests. Skip what cannot have changed. Sampling the last 40 merged PRs, 38% touch neither boost_cli/ nor tests/ nor the mutation configuration — docs, roadmap cards, other workflows. Their score is identical to the base commit's by construction, and they were each paying 26 minutes to prove it. The relevance rule is deliberately wider than boost_cli/core/: setup.cfg's also_copy ships the whole package into mutants/ and the tests import it, so a change in commands/ can flip a core mutant. It also fails safe — no resolvable base commit means run the full gate. Shard the rest. mutmut run accepts fnmatch patterns over mutant names and each source file owns a disjoint mutants/<path>.meta, so splitting by file yields results that merge without any per-mutant reconciliation. Verified live: mutmut run 'boost_cli.core.nethttp.*' ran 16/16 of that file's mutants and left store.py at 0/1931. Six shards reach 5.44x — and no further, because store.py alone is 18% of all mutants and cannot be split. That ceiling is printed by plan --explain rather than left to be rediscovered. The dead end, recorded so nobody repeats it. Caching mutants/ between runs is the obvious first idea and it does not work in mutmut 3.6 — it actively destroys the data it would need. copy_src_dir skips targets that already exist, so on a warm tree create_mutants_for_file takes its source_mtime < mutant_mtime branch and resets every exit code to None. Demonstrated rather than inferred: a file with 235/235 recorded results came back with 185 wiped and the run re-testing from zero. It would have looked like it was working while saving 5.3 seconds. What adversarial review caught, which local testing did not. The first working version sharded by glob("*.py") — non-recursive — while mutmut walks source_paths with os.walk. A subpackage (core/rag/bm25.py) would therefore be assigned to no shard; and because export-cicd-stats skips a path with no .meta rather than counting it unkilled, those mutants would drop out of total entirely and the required check would report PASS over a subset. Fail-open — precisely inverting the property the file's own docstring claimed. Two further finds: no fnmatch pattern can address __init__.py, because mutmut rewrites .__init__. out of mutant names (boost_cli.core.__init__.* matches nothing, and boost_cli.core.* would swallow the whole package); and git diff --name-only reports only a rename's destination, so moving core/x.py to docs/x.py looked like a docs-only change and skipped the gate. All three are now covered by tests that fail against the pre-fix code, and merge asserts that every mutatable file was actually accounted for — so future layout drift reddens the gate instead of quietly narrowing it. The trap this had to avoid. mutation is a required status check (.github/required-checks.txt). Path-filtering the job — the natural way to implement "skip" — means GitHub creates no check run at all, and branch protection waits for a status that never comes. This repository has already deadlocked that way twice. So the required job always runs (if: always()) and inspects what the upstream jobs actually did; always() on its own would have reported a failed shard as a green required check. Merging likewise fails closed: mutmut counts an unrun mutant as "not checked" inside total, and the gate divides by it, so a partial merge would quietly depress the score instead of erroring. What actually landed, measured on main. The eleven CI runs before this merged took 20.7–39.4 minutes (median ~28.4); the merge commit's own run took 12.1. This pull request touches tests/, so it ran the full six-shard gate — the worst case, not the docs-only path. It also missed its own estimate, in an instructive way. The prediction was ~6 minutes for a code change; the slowest shard took 9.9. Packing by mutant count is near-perfect — the six shards carry 1703–1931 mutants each, within 1.10x of ideal — but measured throughput ran 3.39 to 14.19 mutants/second, a 4.2x spread. Mutant count is simply a poor proxy for time: a store.py mutant re-runs a far larger covering test set than an ed25519.py one, and survivors run their tests to completion where kills exit early. Re-weighting the planner by seconds instead of count would even out the billed minutes but not the wall clock, because shard 0 is store.py by itself and its 9.5 minutes is the floor. Going below it means splitting a single file — feasible, since mutant names are addressable per function (boost_cli.core.store.install_*), which would bring the floor toward the 5.1-minute even split of the 30.8 minutes of total work.

Sharding took the mutation gate from ~28 minutes to ~12 (see mutation-gate-was-the-whole-critical-path), but it cannot go lower without splitting one file. Measured across four consecutive six-shard runs: 638bffeb ran 1.9, 3.9, 5.7, 6.7, 7.2, 11.7 minutes; 02c18bd6 ran 2.7, 5.0, 5.2, 5.5, 5.9, 11.7; fc427839 ran 3.1, 4.8, 5.3, 6.4, 7.3, 9.7; and f42e617b ran 2.9, 4.9, 5.5, 6.6, 7.3, 9.3. mutation-shard (0) was the slowest leg in all four. Total work is 36–37 job-minutes, so a perfectly even split would be 6.1; the actual critical path is 9.3–11.7, or 1.5–1.9× that. The gap is not bad packing — the planner balances mutant count to within 1.10× of ideal. It is that count is a poor proxy for time: measured throughput spans 3.39 to 14.19 mutants/second, because a store.py mutant re-runs a far larger covering test set than an ed25519.py one, and survivors run their tests to completion where kills exit early. Re-weighting the planner by seconds would even out the billed minutes but not the wall clock, because store.py is 1931 mutants (18.4% of the repo) in one file and longest-processing-time packing cannot place a single file across two bins. The floor is that file. The way under it: mutant names are addressable per function, so boost_cli.core.store.install_* can be its own shard. That would bring the critical path toward the 6.1-minute even split. Two things must survive the change — pattern_for() still has to emit patterns that match nothing else, and cmd_merge's completeness assertion has to keep failing closed, since mutmut counts an unrun mutant inside total and a partial merge would silently depress the score rather than error. Shipped. A file heavier than an even share is now split into one unit per top-level function, and those units pack independently. store.py's 31 functions come out as a complete partition — each assigned exactly once, each matched by exactly one pattern — and spread across all six shards, so no shard is more than 27% store.py where one was previously 100%. By mutant count the critical path drops from 1931 to 1786, i.e. from 1.08× of ideal to 1.00×, and the packing lands within 0.4% of a perfect split (1777–1786 against an ideal 1779). Both invariants are asserted rather than argued. Patterns anchor on the __mutmut_ suffix, which is what stops install swallowing install_from_path — a real pair in this file. And the merge now unions each shard's results: every shard writes a .meta listing every key in the file with None against what it did not run, so a mutant is only "unrun" when it is None everywhere. A function no shard was assigned therefore reddens the gate. That was verified adversarially — a synthetic mutant name outside the enumerated partition matches no shard's pattern, stays None, and is reported. Any file whose partition cannot be enumerated exactly (a class with methods, a duplicate name, a syntax error) is left whole rather than guessed at. Splitting alone was not enough, and the first green run proved it. With store.py divided, mutation-shard (0) fell from 9.3–11.7 minutes to 4.7 — it is no longer the slowest leg, which is exactly what the card predicted. But shard 3 became the new bottleneck at 10.3 minutes, leaving the run at 1.6× ideal. The diagnosis above was right and incomplete: counts were balanced to 0.4%, and the time spread across shards was still 2.6×. So the second half is weighting by measured time, which a divisible file finally makes possible. weights now records mutmut's per-mutant durations and the planner prefers them. The count-based split, balanced to 1.08× of ideal by count, was 2.24× of ideal by time — one shard carrying 39.3 minutes of summed test time against a 17.5-minute even share. Measured, that bought less than the arithmetic suggested. Time-weighting moved the critical path from 10.3 to 9.3 minutes (shards 5.2, 5.8, 6.3, 6.8, 6.2, 9.3), 1.41× ideal rather than the 1.04× the summed-time model predicted. Summed test time is not shard wall clock: mutmut runs mutants across parallel workers, so a shard's elapsed time is its summed time divided by an effective worker count, and the model ignored that. Per-shard fixed overhead was ruled out by measurement rather than assumed — checkout, venv and install together are 0.4 minutes, against 4.8–8.9 minutes inside mutmut run itself. The residual had a specific cause, and it is the same proxy error one level down: a split file's time was apportioned across its functions by mutant count. Across store.py's functions the per-mutant cost spans 0.273 s to 3.900 s — 14.3× — and install alone is 36% of the file's time from 12% of its mutants, so the shard that drew it ran 8.9 minutes against a 4.8-minute sibling. weights now records per-function durations too and apportions on those, which balances the plan to 0.06%. That closed most of the gap. The next run came back at 4.9, 5.6, 6.3, 7.2, 7.3, 7.7 minutes — a critical path of 7.7 against a 6.5-minute even share, or 1.19×, from 1.5–1.9× before. Measured end to end, the slowest leg went from 9.3–11.7 minutes to 7.7, and the shard that used to be store.py alone now finishes first. Total work is unchanged at ~39 job-minutes, as it should be — this moved the work around, it did not remove any. The remaining 1.19× is not packing error. The plan is balanced to 0.06% on measured time, so what is left is variance between runners and the fact that a mutant's cost is not perfectly stable run to run. Chasing it further would mean re-measuring every run rather than better arithmetic. Two bugs found by running it rather than reasoning about it. mutmut records durations in seconds, so summing them into a field named millis understated store.py's 2360 seconds of test time as 2.4 — a 1000× mislabel. And requiring a duration for every file before trusting the tier was too brittle to fire: one file of 46 (util.py) came back short on the first run, which would have silently dropped the planner back to counting mutants and looked like the feature simply not working. A missing file is now imputed at the measured mean rate, which keeps every weight in one unit — the property that actually matters.

With the mutation gate no longer dominating, the largest remaining term in CI wall clock is queueing. Measured over six consecutive successful ci runs: 104 job-minutes queued against 236 job-minutes executing — 31% of all job time spent waiting for a runner. The obvious metric lies. A run's run_started_at minus created_at is 0.0 for every run, which reads as "no queueing anywhere". Queueing happens per job, not per run, so it is only visible as job.started_at - job.created_at. Anything measuring this at run level will conclude, wrongly, that there is nothing to fix. The per-run spread shows what drives it — median job queue by run: c36c53a7 0.1 min, c15ed9da 0.1, 903b704f 0.2, 638bffeb 0.7, ad71ba99 2.5, 9e190537 2.9. That is a 29× swing driven not by the change under test but by how many sibling loop/* branches and Dependabot PRs happen to be live at the same moment. It is why one merge took 41 minutes wall clock with a max shard of only 11.4. Sharding the mutation gate made this worse on purpose: it traded one runner slot for six. That is the right trade for latency in isolation, and the wrong one to keep making blindly while a dozen branches are in flight, because every concurrent PR now multiplies its footprint. Options, roughly in increasing order of intrusiveness: a concurrency group that cancels superseded PR runs; capping the shard matrix with max-parallel; or making the shard count adaptive. Worth measuring before choosing — this item is the measurement, not the fix. Shipped: the least intrusive one, and it turned out to be a plain omission rather than a trade-off. Seven workflows here already declare a concurrency group. ci.yml — the largest by a wide margin, ~36 checks including six mutation shards — declared none, so every push to a pull request left the whole previous run executing against a commit nobody was waiting on. This session alone pushed four times to one PR, which is 24 shard jobs of which 18 were already superseded. Two things keep the release path out of it, and the second is easy to miss. The condition: cancel-in-progress: true would also cancel a push to main, which publish.yml gates the release on via workflow_run — a merge that silently never ships — and a merge_group run, where a cancelled run never reports its required contexts and the queue then waits forever on a status that is not coming. Both evaluate false. The key: non-PR events group on github.sha, not github.ref. cancel-in-progress: false does not mean "never cancel" — it means a newer run waits, and GitHub cancels the older pending run when a third arrives. Keying main on its ref would put every main push in one group, so three quick merges would leave a middle commit whose ci never completes, and since publish.yml fires on workflow_run of ci, that commit would never release. A sha is unique per commit, so main and the merge queue never share a group at all. Both properties are pinned by tests rather than by the comment, and a separate assertion sweeps every workflow that triggers on merge_group and fails if any cancels unconditionally — so the deadlock cannot arrive later through a different file. What this does not do is reduce the footprint of a single run, which is the other half of the measurement. max-parallel on the shard matrix and an adaptive shard count are still open, and both trade latency for footprint rather than removing waste — worth re-measuring queue time after this lands before spending that trade.

ci.yml runs the workflow SAST step as pipx run zizmor==1.27.0 .github/workflows. PyPI marks 1.27.0 as yanked, with yanked_reason: GHSA-f42p-wjw5-97qh. It is the only yanked release out of 66, and 1.28.0 is the successor. Exact-pinning the security scanner is correct — an unpinned linter is how ruff-defaults-broke-boost-lint happened. Pinning to a version its maintainer has withdrawn for a security advisory is the failure mode on the other side, and it is quieter: a yank does not stop an exact pin from resolving. pip installs 1.27.0 and emits a warning nobody reads in CI logs, so the required lint gate goes on passing while running a withdrawn build of the tool that audits the workflows driving a Trusted-Publisher release. Two things worth doing together. Bump to 1.28.0 and confirm the four documented dangerous-triggers exemptions in .github/zizmor.yml still suppress cleanly — the line-anchored ignore entries (publish.yml:19, sbom.yml:29, …) are exactly the kind of thing a version bump can invalidate. And sweep the other exact pins for yanks: nothing currently checks for this. pip-audit catches CVEs in the resolved dependency closure, but a yanked pinned tool is neither a CVE in the closure nor a manifest diff, so osv-scanner does not see it either. This was found by accident, while installing zizmor locally to verify an unrelated change. Already shipped when this card was written — the card was filed stale, and that is the more useful finding. Commit a4450f76, "ci(security): zizmor 1.27.0 is yanked — take 1.28.0", landed at 08:07Z; this card was filed at 20:18Z, twelve hours later, against a base that already carried 1.28.0. The yank was observed correctly against a tree extracted earlier in the day and then never re-checked against the branch point. ci.yml now runs pipx run zizmor==1.28.0. Two things worth keeping from it. The predicted risk did not materialise: zizmor 1.28.0 runs clean over all 25 workflows (exit 0, "no findings to report"), and the line-anchored ignores in .github/zizmor.yml — including sbom.yml:29 — all still resolve, so the bump needed no config change. And the gap the card names remains real and unclosed: nothing checks whether an exact pin has been yanked. pip-audit scans the resolved dependency closure and osv-scanner diffs the manifest; a yanked pinned tool is neither, so this was caught by a human noticing a pip warning, twice, by luck.

publish.yml fires on workflow_run when ci completes, gates on that run's conclusion == 'success' (plus event == 'push' and head_repository == this repo), and then checks out ref: main. Those are not the same commit. Observed 2026-07-28: ci for ecfe38bc completed at 20:19:05Z; the release run was created at 20:19:07Z; it tagged and shipped c1727bac as v1.0.271 — while c1727bac's own ci, started 20:18:40Z, was still in_progress. One commit's green verdict authorised a different commit's release. Most of this is already mitigated, and the card should not be read as "untested code ships". A strict "require branches to be up to date" policy means the shipped commit was green as a pull request before it could merge, so its tree was gated. And release_preflight.py is already pointed at the right commit — --sha "$(git rev-parse HEAD)", with an explicit comment that this is "not the trigger sha". It polls each required workflow for that exact sha and fails closed on red, cancelled, skipped, never-ran or still-running-at-deadline. The machinery is correct. Its coverage is the gap. .github/required-checks.txt lists 18 required contexts. publish.yml passes preflight exactly two of them — --require pip-audit.yml and --require package-metadata.yml. The other 16 are never re-checked against the commit being shipped, including all 14 that come from ci.yml and codeql-analyze. The clearest evidence this is an oversight rather than a decision is in-tree: release_preflight.py's own docstring says it waits for every required workflow for the exact commit being released, and the caller hands it two. A required context that can never report on main at all — and must not be made to. osv-scanner.yml declares only pull_request and merge_group, so scan-pr / osv-scan produces nothing for any commit on main. This card originally proposed giving it a push trigger. That was wrong. It is PR-scoped deliberately: it calls the osv-scanner-reusable-pr.yml diff workflow so it reports only what a pull request adds, and its own header records why a full-repo scan is unwanted — it would trip the accepted, documented old-langchain pin in the [eval] extra that ragas requires. The correct conclusion is the opposite one: scan-pr / osv-scan is inherently a pull-request gate and belongs nowhere near release preflight. The fix is not to change the checkout ref. Pinning to github.event.workflow_run.head_sha would build the older commit while release-drafter still tags the default branch's head — artifact and tag would disagree. The lower-risk change is to widen preflight's --require set to the contexts that actually run on main, and optionally fail the job when git rev-parse HEAD differs from the triggering run's head_sha. This is the third defect found in the same few lines — see publish-trigger-was-reachable-from-a-fork (who can fire it) and publish-gate-ignores-pip-audit-and-metadata (which gates are consulted); this one is which commit they were consulted about. Shipped. publish.yml now passes preflight every required context's workflow that actually runs on a push to main — ci.yml, codeql.yml, pip-audit.yml, package-metadata.yml — taking coverage of the shipped sha from 2 of 18 required contexts to 17 of 18. The remaining one is scan-pr / osv-scan, excluded on purpose for the reason above. The checkout ref is untouched: pinning it to the trigger's head_sha would build the older commit while release-drafter still tags the branch head, leaving artifact and tag disagreeing. --timeout-seconds is raised to 3600 because ci must now finish for the shipped sha and ci's wall clock is dominated by runner queueing; failing closed on a slow-but-green ci would be worse than waiting, and a timeout is still fail-closed either way. Verified by running the real script against main before merging: the four shipped gates return exit 0 ("all 4 release gates green"), and adding --require osv-scanner.yml returns exit 1 — "no run recorded for this commit ... a release gate that never reported cannot be assumed green" — which is the concrete proof that the original recommendation would have blocked every release.

demo-gif-workflow-has-never-succeeded (shipped, PR 294) fixed the recorder: charmbracelet/vhs-action's broken ffmpeg installer was replaced with apt plus ttyd/vhs pinned by release-asset id. That worked. The recording step now succeeds on both event paths. The workflow still fails on every push to main — observed 2026-07-28 at 20:56, 20:04 and 09:27, and it is the only failing workflow in the last 60 runs. The failure moved one step later, to open a PR if the recording changed. The run annotation gives it verbatim: GitHub Actions is not permitted to create or approve pull requests. Nothing in demo.yml is wrong, so nothing in demo.yml will fix it. The job already declares contents: write and pull-requests: write, which is exactly what peter-evans/create-pull-request documents as required. The workflow uses no secrets. persist-credentials: false on the checkout is correct and is the repo-wide convention across all 31 checkout steps — the action supplies its own git auth and explicitly unsets any persisted credential. Every one of those is a plausible-looking false lead. The actual blocker is a repository setting: Actions → General  → Workflow permissions  →  "Allow GitHub Actions to create and approve pull requests", which the API reports as can_approve_pull_request_reviews: false. This is the same shape as sbom.yml: a workflow that is correct in the file and inert in reality. Deciding it is a real decision, not a formality. Turning that toggle on grants every workflow in the repo the ability to open pull requests, which is a genuine widening of what a compromised action can do. The alternative is to accept that this step cannot work and change what the push path does — upload the GIF as an artifact on both paths, as the pull-request path already does, and drop the PR-opening step. A second, independent defect in the same file. Its concurrency group is group: demo, not ref-scoped. Every other per-ref workflow scopes it — sonarcloud-${{ github.ref }}, fuzz-${{ github.ref }}, eval-stats-${{ github.ref }}, eval-explain-${{ github.ref }}; only the deliberately-singleton release and post-deploy are global. With cancel-in-progress: true, a pull-request run and a main run therefore cancel each other, which is where demo's cancelled runs come from. Fix is group: demo-${{ github.ref }} regardless of what is decided about the toggle. Worth reconciling while here: the tree disagrees with itself on the history. demo-gif-workflow-has-never-succeeded says "3 runs, 3 failures", while demo.yml and ci-failure-issue.yml both say six of six. It is not only the demo any more. [[scheduled-toolchain-lock-regeneration]] needs the same permission: since #349 switched off Dependabot's version updates for the pinned toolchain, the replacement is a scheduled job that regenerates the lock and proposes it — and that job cannot open a pull request either. So this toggle now gates two items rather than one, and the second is a supply-chain freshness gap rather than a docs asset. That does not make the decision automatic, but it does change what is on each side of it. Unblocked, and already working — the setting was flipped. This card's blocker is can_approve_pull_request_reviews: false. The API now reports it as true, and the effect is visible rather than theoretical: demo.yml's recent runs are green, and PR #353 was opened by github-actions[bot] — the exact action this card says is impossible. Nothing in the tree needed changing. Recording it as shipped rather than deleting it, because the card's analysis was right about where the blocker was: the earlier investigation had chased demo.yml's own permissions: block, and the note that no edit to the workflow could fix a repository-level setting is what stopped that from being a long false lead. Update — the repository setting this card called immovable has been turned on. The API now reports can_approve_pull_request_reviews: true, demo.yml succeeds on every push to main, and it has opened real pull requests as github-actions[bot] (#353, #394). So the coupled item [[scheduled-toolchain-lock-regeneration]] was unblocked too, and shipped on the strength of it. What did not change is the check-run consequence, which is worth keeping on the record because it is invisible: a PR opened this way lands with zero check runs, since create-pull-request pushes with GITHUB_TOKEN and a GITHUB_TOKEN push never triggers workflows. Measured on both bot PRs — ffc07b0 and a9da922 each had 0, and the same commits had 27 after an Update branch. An empty check list is indistinguishable from "CI has not started yet", so a bot PR can look ready to merge while nothing has run.

The repository carries 77 branches, 70 of them loop/*. Classifying each by the state of its pull request: 68 have a merged PR and are safe to delete, 1 has an open PR (loop/dependabot-findings), and 1 has no PR on record. The default branch list is almost entirely finished work. The obvious measurement is wrong here, which is worth recording. Testing "is it merged?" with compare(main...branch).ahead_by == 0 reports 0 of 70 as merged — because this repo squash-merges, and a squash leaves the branch's original commits outside main's history forever. Every merged branch looks permanently ahead. The state has to come from the pull request, not from commit reachability. The cause is a single repository setting: delete_branch_on_merge is false, so nothing removes a head branch when its PR merges. No workflow prunes them either — none of the 25 workflow files triggers on create/delete or touches loop/*, and no scripts/ entry or Makefile target does branch cleanup. The one branch-deletion automation in the tree is demo.yml's delete-branch: true, which is create-pull-request tidying its own bot/demo-gif branch and has nothing to do with loop/*. No documentation asks anyone to clean up either: CONTRIBUTING.md, CLAUDE.md and .claude/commands/roadmap-loop.md all describe branching and squash-merging, and none of the three mentions deleting the branch afterwards. Not a claim that branches are never deleted. The item files name 144 distinct owner: loop/<topic> values against 70 surviving branches, so roughly 98 have gone at some point — by hand, or by topic reuse. The accurate statement is narrower: nothing in the repo causes cleanup, so merged branches accumulate until someone does it manually. Low impact and near-zero risk to fix — flip delete_branch_on_merge to true and the backlog can be pruned by listing merged PR head refs. The reason it is worth doing at all is that CLAUDE.md tells every agent to run git worktree list and inspect branch state before touching a tree, and 68 stale entries make that check noisier for every concurrent loop. Shipped — and the premise had gone stale, which is why it was worth re-checking rather than assuming. This card's core claim is that delete_branch_on_merge is false. It is now true, and the backlog it describes is gone: against the card's 77 branches, 70 of them loop/*, the repository today carries 5 branches, 2 loop/*. Two stragglers predating the setting change were still present and are now deleted: evals-harness (PR #317, merged) and mcp-task-entrance (PR #318, merged). Both were classified the way this card insists on — by pull-request state, not commit reachability — because the squash-merge point above is real: compare(main...branch).ahead_by reports every merged branch as permanently ahead, so reachability would have reported 0 of them deletable. Three branches remain and are deliberately not deleted: bot/demo-gif has an open PR (#353), and badges, loop/keyless-card-dedupe and loop/sbom-in-release-job have no PR on record. A branch with no PR cannot be shown to be merged, and deleting it could destroy unmerged work — so the safe rule is to leave it for a human, which is also why no automated pruner is proposed here. No automation was added. The repository setting does the job going forward; a workflow that deleted branches on a schedule would add a way to lose work in exchange for tidying a list that is now five entries long.

publish.yml checks out ref: main rather than the commit whose ci fired it. release-verifies-the-wrong-commit fixed the verification half of that — preflight now waits on the shipped sha's own gates — but the same decoupling has a second consequence it does not address: two triggers can both resolve to the same tip and release it twice. Observed on 5061e756: two release runs created 27 seconds apart (22:24:32Z and 22:24:59Z), both succeeding, cutting v1.0.277 and v1.0.278 from one commit. It recurs — v1.0.246/v1.0.247 both point at c1d67c1c, and v1.0.248/v1.0.249 both at c750651. Each duplicate burns a PyPI version on a byte-identical build and, until the companion fix in this change, left one of the two GitHub Releases with no SBOM. Preflight does not stop it and was never going to: both runs check out the same green tip, so both legitimately pass every gate. The duplication is upstream of verification. The obvious fix is a trap, which is why this is filed rather than patched. Guarding with "skip if git tag --points-at HEAD already has a v* tag" would stop the duplicate — and would also stop any legitimate retry. release-drafter creates the tag before the build, attestation, wheel smoke-test and PyPI upload run, so a release that failed at the upload step leaves a tag behind with nothing on PyPI. Under that guard, re-running it would skip instead of finishing the job, converting a recoverable failure into a version that can never be published. The concurrency: group: release block does not help either: it serialises the two runs rather than collapsing them, which is exactly what happened here. A correct fix has to distinguish "already released" from "tagged but not published" — check whether the version exists on PyPI, or whether the GitHub Release has its expected assets, rather than whether a tag exists. Alternatives worth weighing: collapse the trigger so only the newest queued run proceeds (cancel-in-progress on a group keyed by nothing, losing the serialisation the release job wants), or skip when git rev-parse HEAD already differs from workflow_run.head_sha — that is self-healing, since the newer commit's own ci will trigger its own release, but it means some merges never get their own version. Already mitigated: sbom.yml now builds and attaches an SBOM for every tag on the commit rather than only the highest, so a duplicate release no longer produces a release with no SBOM. Each tag is built separately so its SBOM carries its own version. Correction: the claim above originally read "because setuptools-scm reads the version from the tag", and that is false — it reads the version from the commit, so separate checkouts of two tags on one commit produce the same version. That was a second, quieter consequence of the duplicate release, fixed separately in sbom-declares-the-wrong-version. Shipped — the PyPI option above, because it is the only one that answers what was actually published rather than what was merely attempted. A new guard job runs scripts/release_guard.py before release and resolves three cases: tagged and the version is on PyPI → skip; tagged and it is not on PyPI → release, because that is the failed-upload retry this card warned a tag-only guard would break; untagged → release. It fails closed — tagged but PyPI unreadable also skips, since a missed release is one workflow_dispatch away while a duplicate burns a version on identical code. A separate job rather than an if: on all eight release steps, so one forgotten condition cannot half-execute a release. ref: main stays: shipping the tip is deliberate, and idempotence was the piece missing from it.

Measured on a real 83-tap install: 11,147 catalog entries carry only 6,997 unique names — 1.593 copies per name, and 56.3% of entries share a name with another entry. rule appears in 47 taps, code-reviewer in 18, prompt-engineer in 15, security-auditor and incident-responder in 13 each. Roughly 18% of bodies are byte-identical, in clusters of up to 8. Because rag.retrieve keys its best map on (name, tap) and then takes ranked[:k], N copies of one item across N registries consume N of the ten slots a user sees. This is the ranking problem that grows with the catalog, and no retrieval engine fixes it: byte-identical bodies produce byte-identical vectors, so a dense reranker cannot separate them and reciprocal-rank fusion actively reinforces the agreement. Adding distractor taps was measured driving base recall@10 down 0.902 → 0.872. Dedup is model-free, needs no download and no new dependency, and its benefit scales up as the corpus grows rather than washing out. Two things to get right. First, cluster on content hash (or canonical name) rather than name alone, and pick a winner with a quality prior — source trust, stars, recency, maintenance — so the surviving copy is the one worth installing; core/typosquat.py already has confusion machinery to build on. Second, (tap, name) is not a unique key: it collides on 1,557 of 11,147 entries (14.0%), worst case ('survivorforge/cursor-rules', 'rule') ×47. Anything keyed on it — a cache, a shipped artifact, a lock row — silently binds data to the wrong entry. Use (tap, skill_md), which is 11,147/11,147 distinct. A scale bound, and one claim checked. This card holds that reciprocal-rank fusion "actively reinforces the agreement" between duplicate copies. That is a claim about rag.rrf_fuse as shipped in #360, so it was worth measuring rather than assuming. Over the pinned 6-tap eval corpus — 743 entries, 693 unique names, so 12.7% of entries share a name against the 56.3% measured on the 83-tap install — and the 50 natural-language queries in tests/eval/golden-natural.jsonl: repeated-name slots consumed in the top-10 were 0 for BM25, 0 for dense and 0 for hybrid. Querying directly at a duplicated item (code-reviewer appears in 3 taps here, judge and guidelines in 2) returned exactly one copy in the top-10 under all three engines. So at this scale fusion is neutral, not amplifying — it consumes no more duplicate slots than either engine alone. That does not contradict this card: absence at 6 taps says nothing about 83, where rule spans 47 registries and 18% of bodies are byte-identical. What it adds is a lower bound and a mechanism note. Duplicates survive fusion because rrf_fuse keys on (name, tap), exactly as rag.retrieve already does, so copies in different taps remain distinct keys under every engine; fusion neither merges nor multiplies them. If the amplification appears at 83 taps it will be because both engines rank the copies adjacently, not because fusion treats them specially — which points the fix at deduplication before ranking rather than at the fusion rule. Worth re-measuring on the 83-tap install with the same script (rrf_fuse is public) to turn this bound into a curve. The key half is shipped; the ranking half is not. This card names two things to get right, and the second — (tap, name) is not a unique key — turned out to be a correctness bug rather than a ranking one, so it was fixed first and separately. Both engines built live = {(name, tap): entry} as a dict comprehension, so the last entry silently won. Reproduced on the pinned 6-tap corpus: 743 entries collapse to 694 pairs, leaving 49 entries (6.6%) unreachable — the card's 14.0% at 83 taps, at small scale. It is not only that a copy is hidden: a query matching a shadowed entry's body was reported under the surviving entry's name, description and path. The clearest pair, same tap and same name, is two genuinely different rules: docs/rules/backend/nodejs/express-mongodb/admin-interface-rule.mdc and docs/rules/backend/nodejs/fullstack-mern-guide/admin-interface-rule.mdc. rag.entry_key is now the single identity function shared by BM25, dense and RRF, keyed on (tap, skill_md) — 743/743 distinct here and 11,147/11,147 on the 83-tap install, exactly as this card predicted. Both index versions are bumped, and dense.build now wipes on a version change: it compared only provider/model/dim, and since _ensure_schema uses CREATE TABLE IF NOT EXISTS an existing store would have crashed on the first insert with “no column named path”. Measured cost: none. Over the pinned corpus BM25 scores 1.000 / 0.780 / 0.860 / 0.895 both before and after, so recovering 49 entries did not disturb ranking. Several fixtures were modelling data a real catalog cannot produce — every entry sharing skill_md="s", two skills at one path — and were corrected. Still open: the ranking half. Clustering on content hash, picking a winner with a quality prior, and the 83-tap re-measurement of the fusion bound are all untouched. Note the two are independent: dedup merges copies that are genuinely the same, whereas this fix stops copies that were never the same from being merged by accident. The curve this card asked for. The note above measured 0 duplicate slots over the pinned 6-tap corpus and said, correctly, that absence at 6 taps says nothing about 83. Re-measured over 77 tapped registries sampled across the shipped list, with the same 50 natural-language queries, counting how many of the ten slots a user sees are second-or-later copies of a name already in that same result list: 6 taps: 1,122 entries, 0.0% sharing a name, 0.00 duplicate slots/query · 12: 14,194 entries, 77.8%, 4.28 · 25: 16,633, 77.9%, 4.12 · 40: 17,470, 74.7%, 3.88 · 60: 29,137, 83.9%, 5.08 · 77: 29,938 entries, 82.7% sharing a name, 4.94 duplicate slots/query. So at realistic corpus size roughly half the ten slots a user sees are repeat copies of a name already in the list, worst observed 9 of 10 (“our full-text queries have got slow as the index grew”). The card's thesis holds, and more sharply than its own 56.3% figure suggested. But the driver is not tap count. Entries jump 1,122 → 14,194 between 6 and 12 taps, so the sample is not uniform: a single awesome-list-style rule registry contributes more entries than the entire 6-tap eval corpus. Duplicate pressure is a step function of which registries are tapped, not a smooth function of how many — it appears the moment one duplicate-heavy registry is added and then stays flat at ~4-5 slots per query from 12 taps to 77. Any dedup benefit should be reported against a stated tap set for that reason, and a user who taps only curated skill registries may never see the problem at all. What this does not settle. The measurement counts repeated names, which is the symptom the card names, not content-identical bodies — two rules that share a name and genuinely differ (the admin-interface-rule pair fixed in #366) are counted here as duplicate slots but must not be merged. That is precisely why the card asks for clustering on content hash rather than on name, and this curve is an upper bound on what dedup could reclaim, not a target. Shipped: content-hash dedup, measured 4.94 → 0.60 duplicate slots per query over the 77-tap corpus (worst case 9 of 10 → 4). The residual 0.60 is correct rather than leftover: those are entries sharing a name whose bodies genuinely differ, which must stay separate. Two measurements settled the design the card left open (“content hash or canonical name”). Of 29,938 entries, 78.3% are byte-identical duplicates — 14,153 distinct bodies, largest cluster 40 copies — while 82.7% share a name. That ~4.4% gap is real distinct content, so name clustering would merge exactly the pairs #366 proved must not be merged. And clustering on content cannot make the opposite mistake here: the number of content clusters spanning more than one name is 0, so collapsing by body never merges two differently-named items. Content hashing is strictly the safer of the two options the card offered, which was not obvious before measuring. The quality prior is curated: inside a cluster every copy is byte-identical, so the one worth surfacing is the one from a tap the user marked trusted. The cluster keeps its best score when that swap happens, so promoting the trusted copy never demotes the result. Mechanically, the body hash is computed in _make_docs where the body is already read — doing it at query time would mean re-reading ~30k files to answer one search — and persisted per document (INDEX_VERSION 4 → 5). Dense hits carry no hash of their own and do not need a second schema: content_hashes() serves one map to every engine from the BM25 index, so the engines can never disagree about which copies are identical. Dedup runs inside retrieve and at the retrieve_any seam, because fusion can reintroduce a copy BM25 already dropped — the copies are distinct (tap, path) keys, so RRF has no reason to treat them as one. Collapsing happens before k is applied, or the duplicates would still consume the slots they were removed from. Cost on the pinned eval corpus: none — 0.978 / 0.791 / 0.854 / 0.882, identical to before, all four floors passing. That corpus has little content duplication, which is exactly why the 83-tap measurement had to exist. Still open: a richer quality prior than curated (the card names stars, recency, maintenance; only curated is available on an entry today), and core/typosquat.py's confusion machinery for near-identical rather than byte-identical bodies. Both are refinements — the byte-identical case is 78.3% of the problem. Claim released. The key fix and content-hash dedup have merged; what is left is a richer quality prior than curated and near-identical (rather than byte-identical) clustering. Unowned and ready for anyone — the byte-identical case was 78.3% of the problem, so the remainder is refinement rather than the bulk. The quality prior is now richer than the curated flag alone. Inside a cluster every copy is byte-identical, so which one survives is not a relevance question — it decides where the user installs from. Two signals exist and they are not the same thing: the entry's own curated flag, which is a decision this machine's owner made with boost tap --curated, and confidence in the shipped registries.json (high / med / low across 466 registries, currently 268 / 153 / 45). rag.source_rank orders on the user's flag first and the shipped confidence second, deliberately: a maintainer opinion baked into the package should never override a choice made on the user's own machine. An uncatalogued registry ranks below every catalogued one rather than above, so an unknown tap never wins by default, and equal trust falls back to ranking order so the result stays deterministic when there is no signal at all. The catalog is read once (lru_cache) because dedup asks per hit and parsing 466 rows inside a search loop would be a real cost for a value that cannot change while the process runs. Retrieval quality is untouched by construction — the gate reads 0.863 / 0.473 / 0.607 / 0.662 before and after, because the prior only chooses between copies that are already identical. Still open: near-identical rather than byte-identical clustering, where core/typosquat.py's confusion machinery would apply. Stars and recency, which the card also names, have no shipped data source today — adding one is its own piece of work rather than a tweak to this. Both halves this card asked for are on main, and the card simply never got flipped. It set two requirements. Cluster on content rather than name, and pick a winner with a quality prior — rag.dedupe_by_content (#370) does exactly that: it keys on the body digest, keeps the cluster's best score, and breaks ties with source_rank so a curated tap outranks a better-placed uncurated copy. Stop keying on (tap, name) — fixed in #366, which moved the key to (tap, skill_md) after the collision hit 14.0% of entries. The measurement moved too, and it moved against the original framing. The card was written from an 83-tap install at 56.3% shared names. Re-measured over 77 registries the figure is 78.3% of 29,938 entries byte-identical, with the natural-language query set averaging 4.94 of 10 slots consumed by a repeat before dedup and 0.60 after. What made content-clustering safe rather than merely appealing is a separate count: of 14,153 distinct bodies, the number of clusters spanning more than one name is zero — so collapsing identical bodies cannot merge two genuinely different skills, which name-clustering would have done. Related follow-on: the same duplicate shape reaches resolve_one, where a tap that vendors its own skills produced an unanswerable disambiguation prompt. Tracked separately in resolve-vendored-duplicate-copies.

rag.py persists the whole index as a single JSON file and json.loads it on every invocation. _CACHE (rag.py:275) is process-local, so a long-lived MCP server amortises the cost but every cold boost search pays it in full. Measured on a synthetic corpus of real repo prose, 10k items → 50k items:
index on disk 52.7 MB → 270 MB;
json.loads per search 2.0–2.9 s → 12.2–13.6 s;
peak RSS 702 MB → 2.49 GB;
BM25 scoring itself 31 ms → 70 ms — cold start dominates by ~200×. On a real 83-tap install the index is already 132 MB at 11.1k entries. Scaling that shape to 50k gives ~594 MB and ~5.7 GB resident. Target RSS, not bytes: Python object overhead was measured at a consistent 9.5–9.6× file size across three independent runs, which is what OOM-kills an 8 GB machine while the disk figure still looks survivable. Two cheap wins come first and are worth landing on their own. (1) Stop chunking. An unchunked index with the item's surface (name + de-hyphenated name + description) counted alongside the body scored recall@10 0.742 / hit@1 0.429 at 41 MB and 0.43 s to load, versus the live chunked index's 0.720 / 0.407 at 132 MB and 8–13 s — better on every metric, 3.2× smaller, 20× faster to load. (2) Get postings out of JSON. FTS5 is compiled into CPython's bundled sqlite (verified: 3.53.4, ENABLE_FTS5), so there is a zero-dependency path — but probe it at runtime, because that is a per-build property, not a guarantee. A compact mmap-able binary postings format is the alternative. Either way snip text (46.7 MB of the 132 MB) belongs out of the hot path. Also note build()'s incremental path is O(entire corpus): reusing unchanged taps runs _kept_docs → _postings_to_doc_tf, which inverts every posting in the index — measured 35 s and 1.72 GB RSS at 11.1k entries to reindex a single changed file. Win (1) is shipped, and the “better on every metric” claim did not survive re-measurement. On the pinned 6-tap corpus unchunking is a trade, not a free win, and which way it falls depends entirely on the shape of the query. On the keyword golden set — which grades items by name — recall@10 fell 1.000 → 0.978 and nDCG 0.895 → 0.882, while hit@1 rose 0.780 → 0.791. On the 50 natural-language queries in golden-natural.jsonl, over identical data, every metric improved and not marginally: recall 0.690 → 0.750, hit@1 0.240 → 0.340, MRR 0.382 → 0.474, nDCG 0.446 → 0.524. That +0.100 hit@1 is 5 of 50 queries, which is at the edge of what 50 queries can resolve — worth stating rather than rounding up. Index cost on the same corpus: 5.3 MB → 2.1 MB and 3,740 documents → 743, one per entry, with load time 0.032 s → 0.015 s. The card's headline figures are from an 83-tap install where the constant factors are far larger; this is the small-scale confirmation of the same shape, not a substitute for it. Chunking's one real contribution was locality — a term only had to beat the length normalisation of its own 1000-char window. BM25's b already does that, and retrieve collapsed chunks back to one hit per entry regardless, so the extra documents were built, stored, re-parsed on every cold search and then discarded. What chunking did provide for free was name matching, since the name sat in whichever chunk contained it; one document per entry has to state the surface explicitly, so rag.surface indexes the name, its de-hyphenated form (tokenize does not split hyphens, so “code reviewer” would otherwise never match code-reviewer) and the description alongside the body. Still open: win (2), getting postings out of JSON — the FTS5 probe and the mmap-able binary format are both untouched, as is moving snip text off the hot path. So is build()'s O(entire-corpus) incremental path, which still inverts every posting to reindex one changed file. Where the bytes are now, measured after win (1). This card sends win (2) after two targets: postings, and snip text (“46.7 MB of the 132 MB”, ~35%). That split was a property of the chunked index, where every 1000-char window carried its own snippet. With one document per entry the balance moves sharply, measured on the pinned 6-tap corpus at 2.05 MB total: postings 1.31 MB (64%), doc metadata 0.46 MB (22%), snips 0.29 MB (14%), over 743 documents and 15,639 distinct terms. So unchunking already collected most of the snippet win, and postings are now the dominant lever by a wide margin. Anyone picking up win (2) should size it against 64%, not chase snip at an assumed 35%. FTS5 probe result. Confirmed present on both interpreters available here — CPython 3.14 (bundled SQLite 3.53.4) and the macOS system Python 3.9 (SQLite 3.54.0). That supports the card's design instruction rather than replacing it: it is still a per-build property, so the runtime probe stays required. A distro CPython compiled without ENABLE_FTS5 is the case the probe exists for. On the incremental path. The O(entire-corpus) reindex noted above is not separable from win (2). _kept_docs calls _postings_to_doc_tf because per-document term frequencies exist only inside the postings on disk, so recovering them for the unchanged taps means scanning every posting whatever the filter. Narrowing the inversion to kept doc ids saves memory but not the scan, and in the common case (one tap of many changed) nearly every document is kept, so it saves little of that either. Denormalising tf back into the documents would fix it directly but roughly duplicates the 64% that postings already occupy. The real fix is the storage format, which is win (2) — worth treating them as one item rather than two. Win (2) is shipped: postings now live in SQLite, and a query reads its terms rather than the whole index. Measured on the pinned corpus — JSON 2.05 MB → 0.76 MB, load 0.015 s → 0.0013 s, cold retrieve 0.0003 s. SQLite as a key-value store, not as FTS5. The card offered FTS5 or a binary format, and FTS5 was the tempting one — it is compiled in, verified on CPython 3.14 (SQLite 3.53.4) and system 3.9 (3.54.0). But FTS5 replaces BM25 with its own ranking: different tokenizer, different parameters, different results. The measured problem is cold-start cost, not scoring quality, so adopting FTS5 would risk what works to fix what does not. Here _bm25 is unchanged byte for byte, and the eval gate proves the change is behaviour-neutral: 0.978 / 0.791 / 0.854 / 0.882, identical before and after. _bm25 also now takes postings as an argument, so the one function whose arithmetic is pinned exactly contains no I/O and is not coupled to where postings are stored. The honest cost: total disk goes up. The store is 3.89 MB against 1.31 MB of JSON postings, because SQLite keeps the term string on every row plus an index over it. Total on-disk is 4.65 MB versus 2.05 MB. This card says “target RSS, not bytes” and that is why the trade is the right way round — the hot path now reads kilobytes instead of materialising megabytes of Python objects — but it is a real cost, not a free win. Interning terms into a term_id table would recover most of it and is the obvious follow-up if the size matters. Both halves are now required. ready() checks for the postings store as well as the documents, so a docs-only index reports not-ready instead of silently scoring every query to zero hits. INDEX_VERSION 5 → 6 forces the one-time rebuild. Still open: snip text off the hot path — now only 14% of the JSON half, so much smaller than this card assumed — and the O(entire-corpus) incremental reindex. The latter is closer than it was: per-document term frequencies are now queryable by document rather than only recoverable by inverting every posting, so scoping the rebuild to the changed taps is a tractable follow-up rather than a format change. Claim released. Both “cheap wins” have merged. What is left is snip off the hot path (only 14% of the JSON half now, so much smaller than this card first assumed) and the O(entire-corpus) incremental reindex — which got cheaper as a side effect, since per-document term frequencies are now queryable by document rather than only recoverable by inverting every posting. Unowned. The incremental-reindex figures above are now stale — re-measured. This card records “35 s and 1.72 GB RSS at 11.1k entries to reindex a single changed file”. On the current code at 10,145 entries, a rebuild that reuses every tap and reindexes nothing costs 5.20 s and 684 MB peak RSS, against 8.15 s for a full forced build. So the two shipped wins cut it roughly 6.7× in time and 2.5× in memory without targeting it: unchunking removed ~5× the documents, and moving postings to SQLite removed the giant JSON parse. The defect itself is unchanged. 5.20 s to reindex zero files is still O(entire corpus) — _kept_docs calls _postings_to_doc_tf, which inverts every posting in the store to recover term frequencies for the taps that did not change. What moved is the priority: this is a 5-second annoyance rather than the 35-second crisis the card describes, so it should be weighed against the other open work rather than assumed urgent. The fix is now a smaller change than it was. Postings live in SQLite keyed by document position, so the blocker is that a rebuild renumbers every document. Keying rows by the entry's stable identity — (tap, skill_md), already the retrieval key since #366 — instead of by position would make an incremental update a DELETE of the changed taps' rows plus an INSERT, with no renumbering and no inversion. That is a schema change rather than a format change, which is what the earlier note meant by it getting cheaper. Both “cheap wins” this card names have shipped. (1) Stop chunking landed in #367 — one document per entry rather than one per chunk. (2) Get postings out of JSON landed in #371, moving them to SQLite so a query reads only the terms it needs instead of json.loads-ing the whole index. That is the fix for the failure this card is actually about: cold-start cost scaling with corpus size rather than with the query. The third suggestion was measured and declined. Moving snip text off the hot path was worth 14% of load time once postings had already left the JSON — real, but not worth the extra artefact and the staleness surface it would add. Recorded as a decision rather than left as an open bullet. The related incremental-reindex concern was separately re-measured in #377: 35 s → 5.2 s, so the O(entire corpus) note at the end of this card no longer describes the code.

Everything needed for conversational search already existed and had never been put together: rag.retrieve_any finds candidates with whatever engine the machine has, ai.ask writes prose, and faithfulness.score checks prose against its source. boost chat is the seam — a question in, an answer that names specific skills and says why, with citations. The design problem is not the chat loop, it is fabrication. boost is a package manager. An assistant that invents a plausible-sounding skill name sends the user hunting for docker-compose-expert, finding nothing, and concluding either that the catalogue is broken or — worse — that something adjacent from an unvetted tap is the thing they meant. Typosquatting is a live hazard in this ecosystem; core/typosquat.py exists for it. So a chatbot that manufactures names is actively dangerous rather than merely unhelpful, and the whole command is built as a retrieval system that happens to speak rather than a model that happens to search. Two defences, in order. Retrieval decides what may be discussed — the model is never asked “what skill does X?”, it is handed a numbered candidate set and asked to answer from it, so nothing outside that set can be recommended because nothing outside it is in the prompt. The reply is then checked before it is shown: every skill-shaped token must name something in the retrieved set (chat.ungrounded_names), and the prose as a whole must clear the same faithfulness threshold boost explain uses. A reply failing either is discarded, not patched — there is no honest way to show prose pointing at a skill that does not exist. Degrading is the default, not the error path. With BOOST_NO_AI=1, no key, or no claude CLI, the answer is the retrieved matches themselves: names, descriptions, taps and the command to install one. That is what every keyless install gets, so it is written to be genuinely useful rather than an apology. The AI path improves the prose and is never load-bearing for correctness. A downgraded answer says so. Silently swapping a rejected reply for the extractive one makes the two indistinguishable, so a rejection is reported — and --json carries grounded: false as a field a caller can branch on rather than a string to parse. Shipped with: core/chat.py (the engine, so the mutation gate covers it), cmd_chat as thin CLI glue per the commands/core split, 21 unit tests weighted toward the rejection paths, 13 functional tests on the CLI contract, and docs/chat.html walking through what happens to a question. Verified against the real 6-tap corpus: the AI path returns source: ai, grounded: true over hybrid RRF retrieval, and an injected reply naming docker-compose-expert is caught and replaced. Deliberately not built. No session persistence — a saved transcript is a second source of truth about a catalogue that changes under it. No tool-calling or install-on-your-behalf: the command answers questions, and boost install stays an explicit act. History is bounded at four turns because a long transcript encourages answering from the conversation rather than from what retrieval returned, which is the same failure the grounding checks exist to catch.

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.

A .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.

Enforce 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.

Cheap, 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.

Gate 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.

Benchmark 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'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.

The self-contained diff-cover gate enforces patch coverage in CI; this is its hosted counterpart — the same coverage.xml the gate already reads, turned into PR diff-coverage comments, a file sunburst and a trend line over time. Wired into the existing patch-coverage job (no second test run) and deliberately non-blocking: codecov.yml marks every status informational, because boost already enforces coverage twice offline and a merge should never hinge on a third party's uptime. Inert until a CODECOV_TOKEN secret exists — the step's if reads the token through env (a secret cannot be referenced directly in an if), so with no secret it skips rather than fails.

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.

Shipped. .github/required-checks.txt is now the source of truth and scripts/check_required_checks.py (in make lint, so in CI) fails when a required name stops matching a job that runs on pull_request. It also caught something the card missed: three check names were ambiguous — lint in ci/markdownlint/theme-lint, audit in lighthouse/pip-audit, analyze in codeql/sonarcloud. GitHub matches required checks by name, so none of those could be required unambiguously, and the colliding jobs are renamed. Original report follows. Branch protection was hand-configured in GitHub Settings and only described in prose in CONTRIBUTING.md — there is no config-as-code (a repo ruleset export, Terraform, or a CI check diffing required names against real job names) to catch drift. It has already drifted: ci.yml's install-smoke job, and the pip-audit/ package-metadata workflows, are never listed as required, so a PR can merge to main with any of them red.

The repo has SECURITY.md, CONTRIBUTING.md, and dependabot.yml, but no .github/ISSUE_TEMPLATE/, no .github/PULL_REQUEST_TEMPLATE.md, and no CODE_OF_CONDUCT.md. For a project that explicitly expects parallel external contributors (per the worktree-coordination rules in CONTRIBUTING.md), a bug-report template built around boost doctor/crash-log output and a PR checklist would cut triage friction more cheaply than most engine work.

The behave suite added under tests/bdd/ (11 features, 47 scenarios) passes cleanly today, but make bdd is invoked nowhere in .github/workflows/ — only lint, test, smoke, and mutation run in ci.yml. Unlike the eval/mutation gates, which degrade cleanly but still execute, this suite only runs if a human remembers to run it locally, so a CLI change that breaks the step glue (output-string matching, mocked shutil.which) can rot silently for any number of merges.

boost install <skill> --scope project (or --here) is a promise about blast radius: the skill lands inside this repo, committable, affecting nobody else's machine. The MCP servers that skill declares do not keep that promise. They are registered at user scope — globally, for every repo you open — whatever scope the skill itself was installed at. The path is short and the gap is a missing argument. _offer_mcp() in commands/pkg.py receives the whole InstallResult, so res.scope is right there, and never reads it. It calls _register_mcp_server(name, spec, host), which takes no scope parameter at all, so mcpdecl.register_argv() falls to its scope="user" default and boost shells out claude mcp add <name> --scope user …. Nothing warns that the scope the user asked for was not the scope they got. The repo-local machinery is already written, and nothing calls it. mcpdecl.merge_into(existing, rows, skill) merges declared servers into an .mcp.json document — the committable, project-scoped file agents already read (mcpdecl.SIDECAR). It returns a new document rather than mutating, never overwrites a server the user configured by hand, and stamps each entry it adds with a MARKER_KEY naming the skill that asked for it, precisely so a later uninstall can remove what boost wrote and nothing else. It is covered by nine assertions in tests/unit/test_mcpdecl.py and has zero callers in boost_cli/. The install path shells out to the host CLI instead. That marker matters because of the second half of the bug: uninstall never unregisters anything. Removing a skill sweeps its files and its symlinks and leaves the MCP server registered, so a skill you installed once to try out keeps launching for every project you open afterwards. Wiring merge_into gives cleanup something exact to reverse, which shelling out to mcp add does not. What the fix has to get right: Scope must flow, not be re-derived. Thread res.scope from _offer_mcp through _register_mcp_server into register_argv(..., scope=…). Both call sites of store.declared_mcp_servers (the user-scope and project-scope install paths in core/store.py) already know their scope; the command layer is where it gets dropped. Project scope should write the file, not shell out. A registration that lives in .mcp.json is reviewable in a diff, committable, and shared with the team — which is the whole point of --scope project. Shelling out to mcp add --scope project would work for a host that supports it, but produces nothing to review and re-opens the per-host grammar problem core/mcphost.py exists to contain. Uninstall has to reverse exactly what was written. Marker-keyed entries only — a server the user added by hand, or one another skill declared, must survive. Note the asymmetry already documented in core/mcphost.py: claude mcp remove finds a user-scope server unaided, while gemini mcp remove defaults to project scope and will report "not found in project settings" while leaving the user-scope entry in place. Removal needs the scope it was registered at, which is another reason to record it rather than guess. The prompt should say where. Today it asks "register N servers with Claude Code now?" and names no scope. It should say which file or scope is about to change, because that is the decision being made. Shipped, all four. Scope now flows: _offer_mcp reads res.scope and threads it through _register_mcp_server into register_argv, so a user-scope install passes its scope explicitly rather than silently inheriting the scope="user" default that caused this. A project-scope install does not shell out at all — it records into the repo's .mcp.json, which is the committable, reviewable registration --scope project promises, and it arrives with a teammate's clone where a host-CLI registration exists only on the machine that ran it. Uninstall reverses exactly those entries. And the prompt names the scope: it now asks to register "for every project on this machine", which is the detail the answer turns on. Wiring was most of it — both halves of the document logic already existed and had no callers. merge_into and strip_owned were written, tested and unused; the new code is the file I/O around them, which lives in core/store.py because core/mcpdecl.py is deliberately I/O-free (the same split core/mcphost.py keeps). The properties worth stating, because each is a way to destroy someone else's work: a server the user configured by hand is never overwritten on install and never removed on uninstall; another skill's server survives both; unrelated keys in the document survive both; an uninstall that owns nothing does not rewrite — and so does not reformat — a file it has no claim on; and a corrupt or absent .mcp.json is never fatal, because by then the skill is already on disk. A skill declaring nothing registrable creates no file at all. Verified by disabling the wiring and confirming the end-to-end tests fail without it, rather than trusting that a passing test proves anything. Related: [[mcp-aware-skills]] (which added the declaration format), [[mcp-install-skips-the-injection-scan]] and [[mcp-register-names-server-before-env]].

boost 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.

Extend 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.

Today 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.

The 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.

Skills already declare relationships in frontmatter (requires: / conflicts:), and boost info / boost deps show them — but boost install X only ever installed exactly what you named, never what X depends on. That is the one headline package-manager behavior boost was missing: installing a skill should pull in the skills it needs, in the right order. Add a pure, mutation-tested resolver in core/resolve.py — post-order DFS over the requires: graph, cycle-safe, deduped, already-installed nodes pruned — and wire it into cmd_install so a named skill installs its transitive requires: closure (dependencies first), with a --no-deps escape hatch. Declared conflicts: against an installed or co-installed skill surface as an advisory warning, and a requires: naming a skill in no tap is flagged, not fatal. Surfaced by mining boost's own catalog: the densest skill cluster is dependency management, which every package manager treats as table stakes.

Mining boost's catalog surfaces a recurring shape: skills that only work paired with a Model Context Protocol server (manage-mcp-servers, mcp-integration, mcp-builder and dozens more). boost already is an MCP server and registers itself, but a skill could not say "I need server Y", so it installed cleanly and then failed in the agent for a reason nothing surfaced. Now a skill declares mcp: github, playwright in frontmatter and/or bundles a standard .mcp.json; on install boost states the requirement and offers to register the servers that came with a runnable spec, the same way boost mcp register wires boost itself. boost info lists them beside capabilities:, and --no-mcp opts out. Deliberately flat, not the nested mcp: block first sketched: boost's frontmatter parser is a stdlib YAML subset that does not fail loudly on a nested mapping — it hoists the inner keys to top level and clobbers their siblings — so the declaration meets the parser where it already works and full specs live in the sidecar that needs no parser at all. The decision layer is core/mcpdecl.py, pure and I/O-free like core/resolve.py.

The data-driven roadmap solved the conflict problem for item files: two loops adding two cards touch two different files and merge cleanly. But docs/roadmap.html is still a single committed artifact generated from all of them, and update-branch merges it textually. So whenever another roadmap-carrying PR merges first, the rebase brings in the new item .md cleanly and leaves the generated HTML behind. The board no longer matches docs/roadmap/items/, and both build_roadmap.py --check (in lint) and tests/unit/test_roadmap_fresh.py fail — on every test leg, for a PR that changed no Python at all. It reads as a catastrophic failure and is really a stale generated file. This is not hypothetical: one PR hit it twice in a single afternoon, each time needing a manual regenerate-and-push, and the cost scales with the number of concurrent loops — the exact workload the item-file split was introduced to support. With strict: true every merge rebases every open PR, so any PR carrying a card is guaranteed to hit it if it sits behind one other roadmap PR. Options, roughly in order of appeal: have CI regenerate and push the board on the PR branch (fixes it silently, needs a bot token and care with the required checks); a custom merge driver for the generated boards that reruns the generator instead of merging text; or stop committing the HTML and build the site at deploy time (biggest change, and it removes the artifact from review). At minimum, make the --check failure message say "regenerate after rebasing" so the cause is obvious from the log. Update 2026-07-29 — the three options were measured, and two of them do not work. First, the repro, because both halves matter and they fail differently. Two branches each adding one item to the same section: the cards hard-conflict (same insertion point), while the counters merge silently to a wrong value — base N, both sides N+1, git keeps N+1, the truth is N+2. So a clean merge still fails --check. That is why one root cause reddens ~6 checks. "Custom merge driver" is dead. GitHub's server-side merge ignores .gitattributes merge strategies — not just custom drivers, the built-in ones too. Measured on this repo with four throwaway branches and POST /repos/…/merges: 409 without the attribute and 409 with docs/roadmap.html merge=union, while the identical merge locally succeeds cleanly and one build_roadmap.py run makes it correct. The attribute would help only whoever resolves the conflict by hand, which is the case that already works. "CI regenerates and pushes on the PR branch" is dead too, at least with GITHUB_TOKEN: a push made with it deliberately does not trigger workflows, so the fix-up commit would land a new head with no check runs at all and the required contexts would never report — the PR blocks forever instead of for one cycle. It needs a PAT or a GitHub App, i.e. a new long-lived secret with write access to every branch. The survivor is the third one — stop committing the generated HTML and build the site at deploy time — and it has a prerequisite that is a repository setting, not a commit: Pages is currently build_type: legacy serving main:/, so it publishes whatever bytes are committed. The artifact cannot leave git until Pages builds it, which means either an Actions-built site or a generated gh-pages branch (the pattern ci.yml already uses for the coverage badge, and one that does not re-trigger ci → publish, so it cuts no extra release). Everything that reads docs/*.html off disk — html-validate, visual, lighthouse, check_anchors, a11y_check, test_docsite_chrome — would need a generate step first, and test_roadmap_fresh loses its purpose. That is the whole cost, and it is bounded; what it is not is a change one loop should make to a live public site on its own initiative.

Makefile:64 guards the workflow linter like this: @command -v actionlint >/dev/null 2>&1 && actionlint || echo "actionlint not on PATH — skipping (CI enforces it)" Because || binds to the whole && chain, the fallback fires in both failure modes — actionlint absent, and actionlint present and reporting findings. Reproduced with a stub that exits 1: actionlint: FAKE ERROR
actionlint not on PATH — skipping (CI enforces it)
make exit=0 So a real workflow-lint failure is swallowed, and the message asserts something false — that the tool is not installed, when it is installed and just failed. make lint and therefore make check can never fail on actionlint. CLAUDE.md calls make check "the one gate that matters" and tells every agent to run it before calling a change done; for this tool it returns green unconditionally, and the developer who reads the output is told the opposite of what happened. The local-versus-CI gap is wider than this one line. CI's required lint job runs three workflow/security tools that make lint has no equivalent for at all: actionlint (present but unfailable), zizmor and gitleaks (absent from the Makefile entirely). No CI job invokes make lint, so the two lists are hand-maintained duplicates with nothing checking they agree — which is how they drifted. Minimal fix is to stop discarding the exit status: @if command -v actionlint >/dev/null 2>&1; then actionlint; else echo "actionlint not on PATH — skipping (CI enforces it)"; fi The stricter option is to install actionlint in make venv and let absence itself fail, so make check cannot report success while skipping a required gate. The same masking idiom appears at Makefile:143 (hyperfine) and Makefile:167 (node); neither is reached by check, so they are cosmetic by comparison, but they are the same bug. Incidental drift found alongside: CLAUDE.md describes the lint recipe as "18 commands" and it is 19. Shipped. All three occurrences of the idiom were rewritten to an if/then/else so the tool's exit status is no longer discarded — Makefile:64 (actionlint, inside lint and therefore inside check), plus bench-cli and post-deploy, which had the same bug without being reachable from the gate. Verified against the patched recipe itself, in all three states: a failing actionlint now fails make (exit 2) instead of printing "not on PATH" and returning 0; a passing one still exits 0; an absent one still exits 0 with the skip message intact. The wider local-versus-CI gap this card also names — zizmor and gitleaks run only in CI and are absent from the Makefile — is untouched and still open.

The previous pass gave the MCP server initialize instructions and intent-framed tool descriptions, but framed both around a single trigger: before you author a new skill. That is the rarer moment. Observed behaviour matched the framing exactly — agents called boost_search only when they were already about to write a skill, and never to ask whether an installed one covered the work in front of them. The common case, starting ordinary work that a vetted skill already handles, had nothing pointing at it. Broaden to two declared triggers: starting a task (call boost_list for what is usable right now, boost_search for what could be) and the existing authoring one. boost_list is re-framed from "avoid a duplicate install" to "leverage a capability you already have" — it is the free half of the check. A closing proportion note bounds it, because an unbounded always check first turns every trivial turn into a tool call and an agent that learns to ignore the guidance ignores all of it. Both triggers and the bound are pinned by tests, so dropping either regresses. Shipped — the claim was stale, not the work. PR #318 merged and its branch is gone, but this item sat at inflight under that branch name, so the board advertised live work as taken. Verified against the code rather than the PR state alone: mcp.INSTRUCTIONS leads with using an installed skill, names boost_list for what is usable right now, and carries the proportion bound this card asks for — “Skip it for a question, a one-line edit, or a command you were just handed.” The trigger is pinned by test_instructions_lead_with_using_a_skill_not_authoring_one. One note for anyone reading both cards: mcp-one-benefit-nameable-task (#355, later) superseded this card's “two declared triggers” framing by demoting authoring to a clause on boost_search, on the grounds that it was the rarer moment crowding out the common one. The task-start trigger this card argued for is what survived.

make-lint-masks-actionlint-failures fixed the layer everyone can see: make lint discarded actionlint's exit status. There is a second layer underneath it, and the first fix does not reach it. actionlint does not lint run: blocks itself. It shells out to shellcheck, and when shellcheck is not on PATH it skips every one of them — no warning, no note, exit 0. Same workflow file, same actionlint binary, only PATH differs: without shellcheck -> (no output) exit=0
with shellcheck -> bad.yml:8:9: shellcheck reported issue in this script: SC2001 … exit=1 So the honest description of the gate before this change was: make lint ran a workflow linter that silently declined to look inside any script, and reported success. That is not hypothetical either — it is exactly how an SC2001 reached CI from a green local gate, in the very change that fixed layer one. CI was not safe, only lucky. Its actionlint step carried the comment "shellcheck is preinstalled on the runner, so run: blocks are checked too" — true today, and an unpinned, unversioned, silently revocable dependency on somebody else's base image. If GitHub ever drops it from ubuntu-latest, CI degrades to the same hollow check with no signal that anything changed. For a repository that hash-pins its entire lint toolchain precisely so an upstream release cannot move a gate underneath it, an implicit dependency on a runner image is the same bug in a different coat. Shipped. shellcheck-py==0.11.0.1 is declared in requirements/lint-tools.in and hash-pinned into the generated lint-tools.txt like every other tool, which puts it on both sides: CI installs it from that lock, and make venv puts it in .venv/bin. make lint now prepends .venv/bin to PATH so actionlint can find it, and fails if it is missing rather than running a check it knows is hollow; CI asserts command -v shellcheck before invoking actionlint. Verified in four states against the real recipe: the tool absent (skip message, exit 0), shellcheck missing from the venv (exit 1 with a message naming the fix), both present and workflows clean (exit 0), and both present with an SC2001 in a run: block (exit 1 — the case that used to pass). The old recipe on that same file exits 0. What is deliberately still skipped. If actionlint itself is absent, make lint prints a message and continues. Closing that would mean pinning actionlint-py, which is sdist-only and fetches the binary from the network at install time, and which tracks a different actionlint version than the URL-pinned one CI uses. Trading a pinned binary for a build-time download is a worse trade than the skip, so the skip stays and is documented rather than quietly tolerated. The wider gap named by the earlier card is also still open: zizmor and gitleaks run only in CI and have no Makefile equivalent.

Gemini CLI used the boost MCP server only when asked by hand, never on its own. Two causes, and neither was fixed by writing more instructions. Placement: Gemini appends a server's initialize instructions to the GEMINI.md memory tier (getMcpInstructions → categorizeMemoryContents), gated on folder trust — so the block reads as background documentation, sits far from the tool-call decision, and is dropped entirely in an untrusted folder. Claude Code puts the same text in the system prompt, which is why the gap only showed on Gemini. The tool descriptions are the only boost text reliably in context at the decision point, so each now repeats the trigger, the cost and the miss protocol instead of deferring upward. Wording: the previous pass declared three triggers bounded by a proportionality note, and the bound beat the triggers every time — judging work "non-trivial" takes judgement, while "this turn looks small" is free, and every turn looks small when it opens. Collapse to one benefit (find a skill for the task in front of you) and one observable trigger (does the task have a name?), which an agent can pattern-match without deciding anything. Authoring drops from co-equal trigger to a clause on boost_search — it is the rarer moment and it was crowding out the common one. Three additions are load-bearing, not padding: the stated cost (read-only, ~1s, installs nothing) kills the unknown-price hesitation; the miss protocol ("finding nothing is a good outcome") stops one empty search teaching an agent to quit checking; and "the task stays yours" is what makes an agent willing to look, since one that expects a hit to seize the work is safer not looking. Finally, drop boost_info from the advertised flow — boost_search already returns each hit's description, the only field that changes an install decision, so the hop bought a round-trip and a decision point and nothing else. It stays registered for looking up a name from elsewhere, and its description now says so. All of it is pinned by tests, including negative assertions so authoring and the info hop cannot creep back. Shipped — the claim was stale, not the work. PR #355 merged and its branch is gone, yet this item still read as owned. Every element is verifiable in mcp.INSTRUCTIONS today: the stated cost (“read-only, take about a second, and install nothing”), the miss protocol (“Finding nothing is a good outcome, not a wasted call”), “The task stays yours”, and boost_info absent from the advertised flow — which test_instructions_route_search_straight_to_install pins with a negative assertion so the hop cannot creep back.

The nameable-task rewrite gave the MCP server a stated cost, on the reasoning that an unknown-price call with an unknown hit rate gets skipped. That reasoning still holds. The number was wrong: "Both are read-only, take about a second, and install nothing." Measured against the real path, boost_list is instant but boost_search runs 11.7–17.0 s (median ~12) against 0.10 s with the rerank off — because rag.search defaults smart=True and the MCP tool called it bare, so every agent search spends an LLM call while the CLI makes a human ask with --smart. Ship the cost, not a smaller one. The fix is not to hide the latency: the rerank is the largest measured quality lever in the retrieval stack. On the 91-query golden set it moves hit@1 from 0.791 to 0.945 — +14 net queries, against the ~6-query floor for p<0.05 at this n. For scale, full-content BM25 beat the old frontmatter search by +0.077, and dense retrieval tied BM25 exactly at 0.000. An agent acts on the top result rather than scanning ten, so it is the caller for whom those seconds are most clearly worth paying. The instructions now separate the two tools (boost_list instant, boost_search a few seconds) and say what the seconds buy, because a wrong cost in the one paragraph whose job is to make the tool worth reaching for discredits everything around it — and an agent that budgeted a second gets a surprise instead of a decision. The default is now written down. smart=True is passed explicitly at the MCP call site with the measurement in a comment. It was previously inherited from rag.search's signature, which meant the most expensive behaviour in the tool was an accident nobody had chosen and nobody could find. Same asymmetry as before, but now it is a decision someone can revisit. What is still unmeasured: the lift is over raw BM25, the pipeline that stopped shipping when RRF fusion landed. Whether it survives over the fused ranking needs the arm that step 6 is already committed to. Shipped in #391 (6dc1600, “state what a search really costs, and choose the default”). The card sat at inflight after the PR merged, which is the failure mode a claimed item has: nothing re-checks a status once the work lands, so the board kept advertising work that was already done.

Found by using boost, not by reading it. Installing debugging-and-error-recovery failed with exists in multiple taps: addyosmani/agent-skills, lingxling/awesome-skills-cn, lingxling/awesome-skills-cn, lingxling/awesome-skills-cn — one tap named three times, under a heading that says “multiple taps”. Following the hint made it worse, and this is the part that matters: qualifying by tap re-raised the identical error, now hinting lingxling/awesome-skills-cn:lingxling/awesome-skills-cn:debugging-and-error-recovery — a string that can never resolve. The escape route from the error was the error. Three defects behind one symptom. The message joined e["tap"] across matches with no dedupe, so a repeated tap read as repeated registries. The hint re-qualified name rather than the bare name, so an already-qualified input got a second prefix. And “qualify it by tap” is not advice at all when every candidate shares a tap. The cause is a registry convention, not a corrupt cache. lingxling/awesome-skills-cn vendors its own skills into plugin bundles, so the same skill exists at antigravity/skills/dbg, .../plugins/pack/skills/dbg and .../plugins/pack-claude/skills/dbg — three paths, one identical search_blob. boost was asking the user to choose between three rows that render identically everywhere it displays them. That prompt is unanswerable by construction. So it now chooses, but only where choosing is safe. When every candidate shares a tap and is indistinguishable on name, description, version and frontmatter, boost resolves to the shallowest path — the original, since vendored copies sit deeper by construction — tie-broken lexicographically so the pick cannot drift with dict order between machines. The earlier duplicate census is what makes this safe rather than merely convenient: of 29,938 entries, 78.3% are byte-identical duplicates and zero content-clusters span more than one name, so collapsing identical rows can never merge two genuinely different skills. Two cases deliberately still refuse. Identical content in different taps stays an error — two registries shipping the same text are still two supply chains, and typosquat.py exists because that distinction is load-bearing. Same tap but genuinely different rows also stays an error, since the user can tell them apart and the choice is theirs; that case now names the conflicting paths, because the path is the only thing that distinguishes them, instead of offering a tap qualifier that cannot help. Nine tests, written before the fix. Five failed against the old resolver and the two “still refuses” guards passed from the start, which is what showed the change was additive rather than a loosening. Verified end to end against the real catalogue: the qualified form now resolves to antigravity-awesome-skills/skills/debugging-and-error-recovery, the top-level copy.

boost install <TAB> should offer skill names. It does not, and what it offers instead is different in each shell. boost is a package manager, so completing an installable name is the single highest-value completion it could ship — and it is the one that is wrong in the most confusing way. Measured against the generated scripts (79 commands, docs/commands.html as the flag inventory): all three shells complete 79 of 79 command names and 0 flags, and for boost install <TAB> bash re-offers the 79 command names, zsh offers local filenames, and fish offers nothing. The command-name half genuinely works — all three emit exactly the 79 names in cli.COMMANDS, verified equal as a set, and zsh and fish carry the one-line summaries. Nothing below is a regression; it is scope that was never built. Each shell fails structurally, not by accident. bash emits complete -W "<79 names>" boost with no -F function, and a -W wordlist is position-independent by definition — bash offers the same list at argument 1 and argument 5, so after boost install it re-offers command names. zsh guards on (( CURRENT == 2 )) and falls through to _files, which is why it proposes the contents of your working directory where a skill name belongs — the most misleading of the three, because it looks like a real answer. fish registers every completion under __fish_use_subcommand, so it has nothing to say past the first word. The flag surface is entirely absent. docs/commands.html documents 82 distinct long flags; the completion scripts contain zero. boost search --<TAB> completes nothing in all three shells. The tests pass and prove the wrong thing, which is why this survived. Four tests in TestCompletions assert the emitted text — that the wordlist equals COMMANDS, that there are 79 zsh entries, that fish emits 79 lines. Every one is about what the generator prints; none is about what a shell would propose. A test suite can be green and thorough about the wrong layer. Suggested shape: one completer in Python, three thin shims. Add a hidden boost __complete <words> that takes the current argv and returns candidates, and reduce each shell script to a delegation (-F for bash, _boost calling it for zsh, a function for fish). That puts the logic in core/ where the mutation gate reaches it and where it can be unit-tested in Python, instead of triplicating context rules across three shell dialects that cannot share a test. It also lets candidates be dynamic: installed skills for uninstall, catalog names for install and info, tap names for untap, profiles for profile. Two constraints worth stating before anyone starts. Completion runs on every keystroke-ish TAB, so the candidate path must not pay catalog-scan cost — it needs the cached catalog, and a budget (target <100 ms) measured rather than assumed. And __complete must never fail loudly: a completer that prints a traceback into the user's prompt is worse than one that returns nothing, so it should exit 0 with empty output on any error. Shipped as core/complete.py plus a hidden boost __complete, with the three shell scripts reduced to shims that call it. Verified by driving real bash and real zsh rather than by asserting on emitted text — which is precisely the gap that let this survive: boost install <TAB> now offers the catalogue, boost uninstall <TAB> offers what is installed, boost untap <TAB> offers configured taps, and boost search --<TAB> offers that command's own flags (previously zero in every shell). A measurement decided the architecture. Completion fires on a keystroke, and catalog.all_entries() costs 423 ms for 71,655 entries — four times over the <100 ms budget this card set, before interpreter start. A flat names cache answers the same question in 1.9 ms, a 220× difference, and a test asserts the completion path never calls all_entries() at all. Without that number the obvious implementation would have shipped a TAB that visibly stalls. Driving a real shell found a bug that no unit test would have. The zsh shim passed ${words[1,$CURRENT]} unquoted, and zsh drops an empty trailing word — so boost install <TAB> arrived as two words and completed command names, reproducing the exact defect this card exists to fix, in the new code. "${(@)...}" preserves it. Bash never showed this because "${COMP_WORDS[@]:0:…}" already preserves empty elements. A test now pins the quoting. The layering got stricter, not looser. completions used to import COMMANDS out of cli.py — the single upward edge the import-linter contract allowlisted. The registry is now passed into core.complete as data, so the allowlist entry is gone and boost_cli has no exceptions to its cli → commands → core rule at all. __complete is deliberately not a row in COMMANDS: that list generates docs/commands.html, --help and the command counts, and plumbing belongs in none of them — so the count stays 79. The old tests were replaced, not extended. Four tests asserted that the bash wordlist equalled COMMANDS and that zsh emitted 79 entries. All four passed for years while the feature was broken, because each asked what the generator printed rather than what a shell would propose. The replacements pin behaviour and the shim contract.

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.

WCAG 2.1 AA over every docs page, in two halves. scripts/a11y_check.py is the always-on gate: pure stdlib, so it runs in the lint job beside the other --check scripts with no Node, Chrome or network. It covers what the markup alone decides — lang, alt, accessible names for links and buttons, duplicate ids, heading order — plus the 1.4.3 contrast ratios computed from the Aurora tokens for the ink/ground pairs the CSS actually puts together (listing the real pairs, not the cross-product, so a pair that never renders can't cry wolf). The axe-core sweep in tests/visual/ is the other half: contrast as rendered over glass and gradient, ARIA validity against the computed tree, landmarks, focusable-but-hidden elements — everything that needs a live DOM and therefore can't be a cheap always-on gate. The audit found one real failure, a skipped heading level on the design board, fixed by promoting the section headings with their class-scoped selectors in lockstep so the rendering is unchanged. Contrast came back clean: the muted tokens the card suspected were already fixed (--text-3 had been raised from a 3.9:1 value), and this gate is what keeps them that way.

The 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.

Fast, 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.

vale 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.

Lint 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.

The 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.

Every other docs gate runs against the working tree — html-validate and the a11y checker parse the files, the visual sweep loads them over file://. All of them can be green while the deployed site is broken, because deployment is where the paths change: Pages serves this repo under /boost/, so a link that resolves on disk can 404 in production. Nothing was watching that. Now, triggered by the Pages deployment finishing (so it checks what was actually published rather than guessing at propagation), scripts/post_deploy_smoke.py asserts every page answers 200 and every local asset and internal link resolves — pure stdlib over HTTP, no browser — and console_check.mjs loads each live page in headless Chrome for the half only a browser sees: uncaught JS, console.error, and runtime request failures. Off-site links are deliberately excluded: a flaky third party must never redden boost's deploy, and links.yml already owns those.

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.

Making 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.

boost had no internal architecture diagram of any kind. docs/rag-architecture.md covers retrieval and docs/DEBUGGING.md covers diagnostics, but nothing described the shape of the thing: 45 modules in boost_cli/core, 78 commands across 12 command modules, four agent targets that are deliberately not symmetric, and a cli → commands → core layering rule that import-linter enforces on every build. A new contributor — or a new agent session — had to reconstruct all of that from ls. Shipped as C4-model diagrams in Mermaid under docs/architecture/, so they render on GitHub and stay reviewable in a diff rather than being a binary nobody updates: context, containers, core components, and a dynamic walk through boost install. Mermaid was already a dependency-free choice here — the repo had none before this, so nothing new ships. Writing them turned up a documentation bug worth more than the diagrams. CLAUDE.md stated "Only skill installs — store.install refuses non-skill kinds; rules/workflows are search/tap-only." That is backwards: store.install dispatches to _install_rule and _install_workflow, every kind honours scope, and it raises only for a kind outside the three. The consequence is not cosmetic — installing a rule materialises it into the agent's context file, so a boost install of a rule appends to ~/.claude/CLAUDE.md and is read every session afterwards. Every agent reading CLAUDE.md to learn this repo was being told the most invasive install kind could not happen. Corrected in the same change, with the landing places for all three kinds spelled out. The diagrams are hand-written rather than generated, which is a deliberate trade: they describe structure — layers, boundaries, which component owns which decision — not anything that moves on a routine edit, so drift should be rare and visible in review. docs/architecture/README.md lists the four claims most worth re-checking against the code when the engine changes, so the staleness question has an answer rather than being left to erode.

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.

Promoting the chrome into style/boost.css gave the docsite .site-nav and footer primitives, but nothing adopted them: three pages still had no nav at all (eval, adapters, mcp-hub), commands.html had neither nav nor footer, and design-roadmap.html had no footer. Alongside that, stale content — the Visual Guide advertised “73 commands” in three places while cli.py's COMMANDS held 78, its embedded array missing adapt, run, trust, hooks and bmad — and unprofessional footers: four pages signed off with “Styled with the shared Aurora design system” over a raw ../style/boost.css link, the roadmap credited “the boost quality loop”, and the MCP Hub listed three internal PR numbers. Shipped: every page now carries the same nav and the same footer — brand line, install line, the page index, GitHub/PyPI/Portfolio and the licence, and nothing else. The command inventory is regenerated from COMMANDS. On phones the link row drops to its own full-width line and scrolls with 40 px tap targets (WCAG 2.5.5) and a faded trailing edge, replacing both roadmap.html's display:none below 560 px — which deleted the nav outright — and the column stack that turned fourteen links into six rows of sticky header. Two latent bugs fell out: roadmap.html's hero was a second bare <header>, so it silently inherited the shared sheet's sticky chrome, and generated cards had no id, so no item could link another. Locked by tests/unit/test_docsite_chrome.py.

README shipped a single demo.gif and the guide described 78 commands entirely in prose — nothing showed what a boost session actually looks like. Shipped: docs/carousel.html, a keyboard- and swipe-navigable carousel of 8 terminal recordings, one flagship command per command group — install, search, explain, tap, distill, doctor, hooks and pulse. Every recording is scripted as a VHS tape checked in beside the GIF it produces, so a stale frame is one make carousel away from being regenerated rather than re-recorded by hand. Each GIF carries descriptive alt text covering what the terminal actually does, so the page is usable without images. The counts on the page are hand-typed no longer: the per-slide “N commands in this group” notes and the headline total are asserted against cli.py's COMMANDS by tests/unit/test_docsite_chrome.py, the same guard that covers the guide — the page arrived claiming 76 commands with two group counts already adrift. Built on the shared chrome from the docsite audit, so it carries the same nav and footer as every other page.

demo.yml re-records docs/demo.gif with charmbracelet/vhs-action and opens a PR when the recording changes. It exists because "a generated artifact whose regeneration is manual is one nobody regenerates". All 3 of its 3 runs since 2026-07-26 failed at the recording step with the annotation Failed to install ffmpeg, so the follow-on "open a PR" step was skipped every time and it has never produced a single PR. The net effect is worse than not having it: demo.gif is exactly as stale as before, but the repo now looks covered. Same class as the LangGraph conformance leg — a leg that has never passed since the day it was added. A secondary annotation on the same runs flags that vhs-action v2.1.0 targets Node 20, now deprecated and force-run on Node 24. Options: install ffmpeg explicitly before the action runs, pin a runner image that carries it, switch to a maintained recorder, or delete the workflow and regenerate the GIF by hand. Whichever is chosen, the workflow should fail loudly rather than sit red indefinitely — a scheduled job nobody reads is how this went unnoticed for its whole lifetime.

A user on the README-recommended pipx install ran pipx install boost-skill-cli --upgrade and stayed on 1.0.203 while PyPI was at 1.0.226 — 23 releases behind. Nothing was broken. pipx's install --upgrade only acts when the installed version does not satisfy the supplied spec, and the spec was the bare name boost-skill-cli, which every version satisfies. It printed boost-skill-cli 1.0.203 already satisfies boost-skill-cli and did nothing. Confirmed at the source (pipx 1.16.2): package_spec_satisfied() returns True for a bare name at any installed version, so the upgrade branch is never reached; a pinned spec returns False. pipx upgrade boost-skill-cli is the correct verb, verified end to end (1.0.203 → 1.0.227). The root cause is documentation, not pipx. Every install surface — README, docs/index.html, the site root — stopped at the install command; the word "upgrade" appeared nowhere in any of them. With no correct command to copy, guessing install --upgrade is the reasonable move. Fixed by adding the upgrade line inside the code block users already copy from (docs/index.html's Copy button takes the whole block, so the right command travels with the paste). The deeper bug — boost self-update hard-failing on pip/pipx installs and telling a PyPI user to clone the repo — is separate and still open at self-update-broken-for-pip-pipx-installs.

Shipped. Dense retrieval needs things to line up — the [rag] extra (sqlite-vec plus a bundled local model, so an embeddings key is now a quality upgrade rather than the entry fee) and a built vector store (boost reindex --dense) — and every one of them failed silently: rag.retrieve_any floors to BM25 and returns, so a user who installed the extra but never set a key, or set a key but never reindexed, has no way to learn that the semantic search they think they enabled had never once run. Three gaps, all closed: (1) README. Prerequisites live in half a sentence (“Needs Python 3.9+ and git”) and the optional stack is buried in Install prose. Give required vs. optional prerequisites a dedicated Configuring semantic search section, and automate the optional install the way requirements/*.txt already does for the toolchain, so it is one command rather than three remembered ones. (2) Surfacing. cmd_search printed which engine ran but never that a better one was available — embed.fallback_note() exists and is only wired into reindex --dense. Now said on search — including the zero-results path, where a keyword engine finding nothing is exactly what a semantic one is for — and silent when vectors already served or output is --json. The remedy table moved out of commands/quality.py into core.dense.fix_hint, so doctor and search cannot give contradictory advice; it had no tests at all, which is how its “set an API key” entry went stale. Engine state also lands in the MCP initialize instructions, appended at connect time, so an agent reading /mcp sees “BM25 keyword matching only” instead of assuming vector search. (3) Stale docs. mcp-hub.html advertised voyage-3 (1024-d) in the pipeline diagram and the Phase 2 details block; core/embed.py has pinned voyage-4 since the complimentary-token change; the sweep also caught the diagram and prose still calling a key mandatory, and the same claim in CLAUDE.md. Three environment-dependent tests were fixed on the way: they asserted answers that were only correct where the [rag] extra was absent, so they were green on CI and red on any machine that had installed it.

The generated board is 407.6 KB, of which 404.7 KB is markup — 189 <article> cards rendered eagerly into one DOM. Measured across this session's merges it went 301.6 KB → 409.9 KB, a 36% rise, monotonically increasing with every card documented. The mechanism is that shipped work never stops costing. Sizing the sections: shipped 17.6 KB / 16 cards, next 1.1 KB / 1, planned 383.0 KB / 172 — but 164 of those 172 carry a shipped pill. They are finished items grouped under their original section, each still rendering its full body, and those bodies grow because closing an item well means recording what was measured and what turned out to be wrong. The board is now mostly an archive that every visitor downloads in full. This is NOT what failed lighthouse on #386, and that is worth stating because the correlation is seductive. #388 passed the same gate at 409.9 KB — very slightly larger than #386's 409.8 KB, which failed. A bigger page scoring better rules out page weight as that failure's cause; it was runner variance, exactly as lighthouse.yml's own comment predicts ("a single sample dips into the 80s under runner load, which the median absorbs"). The performance floor is minScore 0.85 against a normal score of ~99–100, so there is real headroom today. The case for doing it anyway is the trend, not the current number. At roughly +6 KB per merged card the page crosses 500 KB within a few working sessions, and DOM size is precisely what Lighthouse's performance category penalises — so this becomes the cause eventually even though it is not the cause now. Likely levers, cheapest first. Collapse shipped card bodies behind <details> so the text ships but does not render — that alone addresses the 383 KB block and keeps every word searchable in the source. Failing that, render shipped items as one-line entries linking to their item file, or paginate by section. All three live in scripts/build_roadmap.py; none require touching an item file, which matters because the item files are the merge-conflict-free part of this design. Do not raise the Lighthouse floor to fix this. The floor is calibrated and honest; a page that outgrows it should be made smaller, not re-graded. Update — the prediction above came true, and the card's own headline claim is now false. This card argued page weight “is not the cause now” of any lighthouse failure, and that it would become the cause eventually. Eventually arrived on #395: docs/roadmap.html scored 0.74, 0.77, 0.81 against the minScore 0.85 floor — all three runs below the floor, not a single sample dipping under load. The board was 433.7 KB / 192 cards at that point, against the 407.6 KB / 189 recorded when this card was filed. The distinction that matters for whoever picks this up: the earlier #386 failure really was runner variance — #388 passed at a very slightly larger size, which is what ruled weight out then. This one is not the same shape. main passed at 430.0 KB one minute earlier on the same runner class, and #395's best of three runs was below main's worst. So the honest reading is not “+3.7 KB broke it” — a 0.9% size change cannot move a score that far. It is that the page now sits on the cliff, with roughly 0.07 of run-to-run spread straddling the floor, so it fails intermittently and will fail more often as cards accrue. Headroom, not the mean, is what was spent. This also raises the cost of documenting work well, which is the uncomfortable part: closing a card properly means recording what was measured and what turned out wrong, and every such paragraph now pushes a shared gate closer to red. That is an argument for the <details> lever rather than for writing less. Shipped — and the measurement corrected the card's own framing. This item is titled for page weight, and every earlier paragraph reasons about kilobytes. Reading the Lighthouse artefact from the failing run shows bytes were never the mechanism. Of 1.6 s of main-thread work: styleLayout 705 ms, paintCompositeRender 393 ms, parseHTML 83 ms, scriptEvaluation 20 ms. The page was slow because the browser lays out and paints 6,316 elements, not because it downloads 440 KB and not because of JavaScript. The weighted losses name the same thing. Reconstructing the 0.74: TBT 0.58 × 30%, LCP 0.69 × 25%, FCP 0.47 × 10%, SI 0.93 × 10%, CLS 1.00 × 25% → 0.7365. Worth noting dom-size scored 0 at 6,316 elements but is unweighted in the performance category — so the obvious-looking number was not the one costing the score, which is exactly the trap of optimising against a diagnostic instead of the metric. The fix is the cheapest lever this card already proposed, for a better reason than it gave. build_roadmap.py now wraps a shipped card's body in a closed <details> — 188 of 192 cards. A closed <details> subtree still parses and still ships, so every word stays greppable and findable by the browser's own find-in-page, but it is never laid out or painted: 3,764 of 6,781 elements (55.5%) now skip both. Anything a reader might act on — planned, next, inflight — stays expanded. The page got bigger, and that is the point. 440.3 KB → 453.5 KB, because 188 <summary> elements cost ~13 KB. Under the original framing that reads as a regression; under the measurement it is irrelevant, because transfer was never what breached the floor. Had this been fixed by chasing kilobytes, the work would have been aimed at the one number the score does not weigh. Not claimed: a resulting Lighthouse score. It could not be reproduced locally (no Chrome in this sandbox), so the element count is the measured claim and CI's own lighthouse job is the verdict.

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".

Every 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.

CI 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.

For 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.

Before 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.

Every dev/CI tool was resolved at install time, so two runs of the same gate could install different bytes — and only requirements/lint-tools.txt pinned anything at all (added after ruff 0.16.0 reddened the gate with no code change). Now every tool comes from a generated, hash-pinned requirements/*.txt: exact versions plus a sha256 for every artifact in the transitive closure, which pip enforces on install, so a yanked or tampered dependency fails loudly instead of silently changing a build. scripts/lock_toolchain.py regenerates from the .in declarations and --check gates drift in make lint; a new Dependabot pip entry keeps the locks from rotting. One file per consumer, because pip enforces hashes across a whole resolution — and test-tools resolves universally, so one file covers the 3 OS × 3 Python matrix without dragging 3.12/3.14 back to the 3.9 floor's versions. The opt-in [eval] extra stays out on purpose: locking its deliberately-old langchain stack into a scannable file would re-expose the pin osv-scanner.yml is PR-diff-scoped to avoid.

A 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.

On 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 self-update only works when boost runs from a git checkout: paths.repo_root() resolves inside site-packages for a pip/pipx install, gitutil.is_repo() is False, and cmd_self_update raises "boost is not running from a git checkout" with a hint to clone the repo — telling a normal PyPI user to abandon their install method. Detect the install method and shell out to pip install --upgrade boost-skill-cli / pipx upgrade boost-skill-cli, falling back to the git-pull path only for source checkouts. Shipped as core/selfupdate.py: detection reads evidence on disk — .git, then pipx_metadata.json or uv-receipt.toml in sys.prefix, then installed package metadata — and a --dry-run flag prints the exact command without running it. Two details carry the weight: the pip branch invokes sys.executable -m pip, never a bare pip, because the pip first on PATH can belong to another interpreter and would upgrade a different copy while reporting success; and an install nothing has a record of reports that plainly instead of guessing pip. The new version is read from a freshly spawned boost --version, since the running process imported its own version before the upgrade — if that probe says nothing, neither does boost.

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.

boost spoke Claude Code, Cursor and Windsurf; Gemini CLI users got nothing. It is now a fourth target — and the interesting part is what it doesn't need. Gemini implements the Agent Skills standard and discovers ~/.agents/skills — boost's canonical store — natively, so skills need no symlink (links_skills: false); linking anyway put one skill in two of its discovery tiers and cost a "Skill conflict detected" line per skill per session. agents.linking_agents() / native_store_agents() partition the enabled set so link, unlink, sync and health each iterate the right one. Formats diverge where Gemini's do: rules become a GEMINI.md managed block (rules.CONTEXT_FILES, generalized from CLAUDE_MD_AGENTS), and slash commands render to TOML (workflows.render_gemini_command, strings via json.dumps — a valid TOML basic string for any input) while subagents stay verbatim Markdown. New core/mcphost.py holds the per-host mcp add/remove grammar: Claude wants <name> … -- <cmd>, Gemini wants flags-then-name and no --, and its remove defaults to project scope so unregister must pass -s user or silently no-op. boost mcp register gained --host (default: every installed CLI). Verified end to end against a real Gemini CLI 0.46.0: gemini mcp list reports boost Connected, and gemini skills list discovers the store with no conflict warning.

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.

The 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.

prompt-injection-scanning-of-skill-markdown shipped the scanner and secret-and-pii-scanning-of-installed-skills shipped its sibling, but both were wired up in the command layer — pkg._warn_injection and pkg._warn_secrets, called from _report_result. So they ran on exactly one path: boost install. The MCP tool did not call them. _tool_install resolved an entry, called store.install, and reported "installed … quality score: 70/100" — no scan, no warning, whatever the Markdown contained. That is the path that needed it most. On the CLI a human is watching a terminal and chose the skill by name. Over MCP, an agent picked the skill and installed it on its own, and since mcp-check-skills-before-starting-a-task the server's own instructions actively push it to do that at the start of every task. The content it installs becomes instructions that agent then follows. A skill carrying "ignore previous instructions" was delivered silently to the one consumer that cannot notice. Fixed by moving the behaviour, not by adding a second call site. The scan now lives in core/installscan.py — content resolution (SKILL.md for skills, scan_text for rules/workflows), both scanners, worst-first ordering, the detail cap and the exact headline wording. pkg.py renders reports through output.warn; the MCP tool folds the same reports into its reply text and names the file to read, with an explicit instruction to disregard anything in it that redirects the agent from the user's task. Advisory on both paths, as before — it warns, it never blocks. Putting it in core/ is what makes it stick: the CLI wiring was correct and still left a hole, because "remember to call two helpers" is not a property a new front end inherits. core/ is also what the mutation gate targets, so the logic is now covered by a gate the command layer never was.

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.

Today 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.

Shipped. Confirmed by running it: install_from_path enforced no gate, so import, create --install, migrate --from-skills-cli and distill/infer/absorb --install each walked past a blocklist, pin_only, max_skills and denied_capabilities. Worse than filed: the lock write hardcoded "pinned": False, so a re-import did not merely skip the pin check — it silently cleared an existing pin. Fixed in core/store.py with a force flag for the legitimate reinstall path; force covers the pin, never policy. Three corrections to this card: boost rename does not exist (misread of the rename= parameter behind import --name); evolve does not route through this function (it writes the store in place — a separate pin bypass, still open); and allowed_taps would not have refused any of these, since policy.py exempts local explicitly. Adopting install()'s "already installed" refusal was rejected — this is the re-import path, so it would break boost reinstall. The multi-item callers (import --all, reinstall --all, migrate) now warn per item and keep going instead of aborting the run on the first refusal, and _install_generated catches the refusal so a paid LLM generation is written to disk rather than deleted with the tempdir.

catalog._make_entry only slugifies a catalog name when it contains a space, so a tap's rule/workflow frontmatter carrying name: ../../../../.ssh/authorized_keys sails straight through into rule_target/workflow_target, which build the destination as root / "rules" / (name + ext) with zero traversal guard — unlike skill_store_dir()'s [A-Za-z0-9._-]+ regex. A malicious tap can write an arbitrary file outside .cursor/rules/ or .claude/, and it is worse under --scope project since base is the victim's own repo. Apply the same name-validation regex used by skill_store_dir() before any rule/workflow install path is built.

GitHub identifies a code-scanning configuration by <workflow path>:<job id>, which makes the job id load-bearing in a way nothing in the workflow file hints at: renaming it does not move the configuration, it forks it. #259 renamed this job analyze to codeql-analyze on 2026-07-27. The last :analyze analysis landed 20 seconds after that merge and never refreshed, stranding 247 of them on refs/heads/main where GitHub kept counting them as a configuration present on the base branch. Merge protection then reported 1 configuration not found on every pull request — conclusion neutral — and because the branch ruleset carries a code_scanning rule, that neutral blocked 100% of merges while every required status check stayed green. The cutover is exact: the last success was #263, the first neutral #259, and every PR from #264 to #316 was neutral regardless of whether its diff contained Python at all. That symmetry is what makes it so easy to misread — it presents as a rule that rejects docs-only PRs, and the two hypotheses it invites ("CodeQL has nothing to analyse" and "the rule is unsatisfiable") are both wrong. 29 docs-only PRs merged happily under the same rule before the rename. The check body says the real answer outright, and reading it beats inferring from mergeable_state. Fixed by deleting the 247 orphaned analyses, which was verified safe first: every alert still on the stale key was fixed, and all nine dismissed CodeQL alerts already carried their false-positive rationale on the live key. The job id was already guarded as a required status-check context by scripts/check_required_checks.py, and that guard passed during #259 because the context list was updated in the same commit — only the invisible half broke. So the guard added here pins the id from the analysis-key side, with a note that a future rename is not finished until the stale configuration is deleted. Related: [[release-verifies-the-wrong-commit]].

boost already computes every individual trust signal, each in its own command: verify checks lock-file integrity, outdated compares an installed skill against its tap, trust reports tap-level signing provenance, deps shows the requires:/conflicts: graph. What nothing answered is the aggregate question — of the skills I actually run, which ones should I stop trusting? boost audit --skills gathers all of it into one report: every installed skill that is unsigned, signed by an untrusted key, signed but failing verification, sitting on a tap nobody has synced in a month, behind its tap, or conflicting with another installed skill. The decision layer is core/trustaudit.py — pure and I/O-free like core/staleness.py, so every branch is unit-tested and reachable by the mutation gate. Only a malformed signature is HIGH; an unsigned tap is the norm for most of the catalog today and stays LOW, so the command never cries wolf on an ordinary install.

sbom.yml triggers on release: types: [published] and promises "a CycloneDX SBOM for every release, attached to the GitHub Release as an asset". It has 0 runs. Releases here are created by release-drafter inside publish.yml authenticated with GITHUB_TOKEN, and events created with GITHUB_TOKEN do not trigger workflows. publish.yml's own header states that rule verbatim — "we never rely on the release event to trigger a second workflow" — and sbom.yml is exactly that pattern. So the if: github.event_name == 'release' guard on its upload step is dead code, workflow_dispatch is the only reachable path and has never been used, and every one of the last ten releases carries assets: []. Zero SBOMs have been produced since the file landed on 2026-07-22. Same shape as the LangGraph conformance leg: wired up, looks covered, never executed once. By the time it was fixed the count was 253 releases, 0 runs, 0 SBOM assets. Fixed with a third option neither branch of that decision considered: workflow_run. The GITHUB_TOKEN restriction applies to events a token creates; workflow_run is documented as exempt and fires on the upstream run completing regardless of what triggered it — which is already how ci → release works in this repo. Chaining release → sbom makes this the third link, inside GitHub's documented three-level workflow_run limit. So no PAT is needed, and the SBOM logic stays out of publish.yml. That separation turned out to matter more than "keeps the logic in its own file": publish.yml's job holds PyPI Trusted-Publishing OIDC credentials, and generating the SBOM means installing a third-party build plugin (cyclonedx-bom). Inlining it would have put that plugin inside the one job that can publish to PyPI. Kept separate, it holds only contents: write. Two details the trigger change forced. The workflow now resolves its tag from the release commit (git tag --points-at) rather than "newest release" — releases here land minutes apart, so gh release view would race and SBOM the next version; and two tags on one commit is real (v1.0.248 and v1.0.249 both point at c750651), so it takes every tag on the commit and builds each separately — taking only the highest left the other release with no SBOM, which showed up in production as v1.0.277; see one-commit-can-cut-two-releases. And per the original note, a final step re-reads the release and fails unless the asset is actually attached — a silent upload no-op is indistinguishable from success, which is the same class of quiet nothing that produced this bug.

The repo has an active ruleset named main (id 19130332) carrying eight rules: deletion, non_fast_forward, pull_request, required_status_checks (9 contexts), code_quality, code_coverage (minimum 80), code_scanning and required_deployments. Its ref condition is: "include": ["refs/heads/\"main\""] — with literal quote characters, so it matches a branch named "main", not main. GitHub's authoritative endpoint settles it: /rules/branches/main returns 0 rules, while /rules/branches/%22main%22 returns all 8. Everything in that ruleset is unenforced. Only the legacy branch protection is actually gating main, and it requires a different, shorter list. Do not just fix the quotes. The ruleset includes required_deployments: ["github-pages", "pypi"]. Correcting the ref pattern activates that rule, and no pull request deploys to the pypi environment — publish.yml runs post-merge on workflow_run. So the one-character fix converts an inert ruleset into a hard deadlock on every PR, for a reason that has nothing to do with status checks. Its check list is also stale relative to .github/required-checks.txt (missing the three Windows legs, install-smoke, patch-coverage, codeql-analyze) and it pins CodeQL from the code-scanning app rather than the workflow job. The safe move is one edit that does all of it: fix the pattern, drop required_deployments, and reconcile the contexts with the checked-in list — or delete the ruleset outright and keep the legacy protection as the single mechanism. Two overlapping systems is how this stayed invisible. Shipped — repaired in a single write, so it never existed in the deadlocking state: pattern corrected to refs/heads/main, required_deployments removed, and the status-check list replaced with the 17 contexts from .github/required-checks.txt (dropping the code-scanning CodeQL entry in favour of the codeql-analyze workflow job the checked-in list names). Verified after: /rules/branches/main returns 7 rules, and /rules/branches/%22main%22 returns 0. Confirmed against all three open pull requests beforehand that every one of the 17 contexts actually reports — including a PR touching only .github/ — so the tightened list cannot deadlock. One API wrinkle worth recording: GET returns code_coverage.max_coverage_drop: null but PUT rejects it ("data matches no possible input"), so round-tripping a ruleset requires stripping null-valued parameters.

publish.yml fires on workflow_run of ci with branches: [main]. That filter matches the triggering run's head_branch — not the event type, and not the repository. ci.yml also runs on pull_request, so a pull request opened from a branch named main produced a ci run whose head_branch was main and satisfied the filter. The job gate checked only workflow_run.conclusion == 'success', so a green run on that path fired the release job with contents: write and PyPI Trusted-Publishing OIDC — cutting a tag, a GitHub Release and a PyPI upload. There was no second gate: the pypi environment has no protection rules and no deployment branch policy. Never code execution — the checkout pins ref: main, so what ships is always main's code. The exposure was an unreviewed release triggerable from outside the repo. Measured rather than assumed: ci-failure-issue.yml draws from the same workflow_run source with no branches filter and has 679 runs against ci's 254 pushes, proving workflow_run fires for PR-triggered runs too; only the head_branch filter kept publish.yml near the push count. Fixed by requiring the triggering run to be a push whose head_repository is this repo. No regression: all 254 ci runs with head_branch=main are pushes from jonnyeclectic/boost, and the gate still admits push-to-main and workflow_dispatch while rejecting fork PRs, same-repo PRs and red CI.

Repairing the main ruleset dropped its code_scanning rule in favour of codeql-analyze as a required status check (see main-ruleset-ref-pattern-has-literal-quotes). That was the safe call at the time, and it left an open question: can the rule come back? Yes — and the thing that would break it is not what it looks like. Nothing is blocking it. Verified without touching the live ruleset: POST a throwaway ruleset with enforcement: disabled and a ref pattern matching no branch, carrying code_scanning for tool CodeQL → HTTP 201, rule stored intact. Delete it, then diff the live ruleset against a backup taken beforehand → no drift. That disabled-and-non-matching probe is the general way to test a ruleset change without risking anyone's in-flight pull request. The stale analyses are a red herring. 693 analyses still carry the old codeql.yml:analyze category against 122 on the current codeql-analyze, which looks like it should matter and does not: the rule keys on tool name, not category. Deleting them is irreversible, destroys alert history, and fixes nothing. Don't. The actual hazard is the tool list. Three tools file into the same code-scanning inbox. CodeQL has 0 open alerts (9 dismissed, 17 fixed). Scorecard has 7 open, every one severity=error — and they are posture metrics that must not be dismissed, so they will stay open. Enabling the rule with Scorecard in its tool list therefore blocks every merge in the repository, immediately. The GitHub UI offers every tool that has reported analyses, so Scorecard sits right next to CodeQL in the picker. That is almost certainly why this has been assumed to be blocked. Scoped to CodeQL alone it is safe and adds real protection: codeql.yml carries no path filters and runs on push, pull_request and merge_group, so it always reports and cannot produce the never-reports deadlock this repo has hit twice. And it catches something the status check does not — codeql-analyze passes when the job succeeds, including when it succeeds having found error-severity alerts. Done — the rule is back, and scoped exactly as this card prescribed. Read from the live main ruleset (id 19130332): it carries a code_scanning rule whose code_scanning_tools list is CodeQL alone, at security_alerts_threshold: high_or_higher and alerts_threshold: errors. Scorecard is not in the list, which is the single decision this card exists to get right. The safety precondition still holds and was re-checked rather than assumed: CodeQL has 0 open alerts, while Scorecard has 4 open (down from the 7 recorded above), every one still a posture metric that must not be dismissed. Had Scorecard been added to that tool list, those four would block every merge in the repository immediately — the failure mode this card correctly identifies as the reason the work looked blocked. No change was needed. Recording it as shipped so the board stops advertising work that is already in place, and so the tool-list constraint stays written down: anyone re-editing this rule through the GitHub UI will be offered Scorecard right next to CodeQL in the picker.

sbom.yml builds each released tag separately so that every release gets an SBOM describing its own version. It does that by checking the tag out: git checkout --detach "refs/tags/$TAG". The premise is wrong. setuptools-scm derives the version from the commit, not from the ref used to reach it, so when one commit carries two tags every checkout resolves to the same version — whichever one git describe picks, which is not the highest. Measured against the real repository, detached at each tag in turn: checked out v1.0.278 -> setuptools-scm says: 1.0.277
checked out v1.0.277 -> setuptools-scm says: 1.0.277 And confirmed in production rather than in a fixture — the published asset on v1.0.278, downloaded from the release, contains {"name": "boost-skill-cli", "version": "1.0.277"}. The SBOM attached to release v1.0.278 describes v1.0.277. A consumer resolving that release's bill of materials gets a document for a different version, which is precisely the trust property an SBOM exists to provide. The blast radius is bounded by how often one commit cuts two releases, which one-commit-can-cut-two-releases documents happening three times so far (246/247, 248/249, 277/278). Every duplicate pair mislabels one of its two SBOMs. It is not latent in publish.yml, which builds the PyPI dist: that job checks out before the sibling run's tag exists, so it happens to resolve correctly — all 281 PyPI versions are present and correctly numbered. The defect is specific to the job that runs after both tags are in place. Shipped. The build now pins the version to the tag it is building (SETUPTOOLS_SCM_PRETEND_VERSION_FOR_BOOST_SKILL_CLI="${TAG#v}") and then asserts the wheel it produced carries that version, so a package rename — which would silently unhook the scoped variable and restore the bug — fails the job instead of shipping a mislabelled document. Verified both ways against the live repository: without the pin, v1.0.278 resolves to 1.0.277; with it, 1.0.278. The same exercise settled the other thing this workflow had never proven: the multi-tag loop itself. Both run: blocks were extracted verbatim from the YAML and driven against a fixture repository with two tags on one commit, with gh and the build toolchain stubbed. Resolution returns both tags newest-first, the loop iterates both, and it issues a separate upload and a separate post-upload view assertion per tag. That path had never executed in production — every commit since it shipped has carried exactly one tag.