boost-skill-cli 1.2.48__tar.gz → 1.2.49__tar.gz

{boost_skill_cli-1.2.48 → boost_skill_cli-1.2.49}/CLAUDE.md

@@ -185,7 +185,16 @@ line coverage. Target `boost_cli/core` behavior with assertions, not just import
   `HOME`/`BOOST_HOME`; tests point them at a tempdir. In zsh, one-line chains
   like `export A=$(...) B=$A/x` leave `B` broken — use separate `export`
   statements.
-- **Versioning is setuptools-scm from git tags.** There is no `__version__`
+- **Versioning is setuptools-scm from git tags.** **Only `vX.Y.Z` tags count**, and
+  two settings say so: `git_describe_command`'s `--match v[0-9]*` decides which
+  tag is *found* and `tag_regex` decides how it is *parsed*. Both are load-
+  bearing since the repo gained a deliberate non-version tag — `shards-latest`,
+  the rolling release hosting the vector shards. At defaults, `git describe`
+  returned `shards-latest-1-g82c3e6a`, the build called itself
+  `vshards-latest-…`, and `boost self-update` then reported "already up to
+  date" against a newer PyPI release, because it compares version tuples and
+  that string parses as none. A silent wrong answer in the command whose job is
+  to detect being behind. There is no `__version__`
   constant and `boost_cli/_version.py` is generated + gitignored. Don't hardcode
   or assert exact versions; version tests are shape-only (`^boost \S+$`). The
   publish workflow filename must stay `publish.yml` (PyPI Trusted Publisher
@@ -450,6 +459,18 @@ each agent's skills dir, and updating the lock file.
   costs a download instead of an hour of CPU — and says plainly when one does
   not.
 
+- **The shard matrix is packed, not sliced, and 256 is a hard ceiling.**
+  GitHub runs at most 256 matrix jobs per workflow, so `shards.yml` cannot take
+  one job per registry once the scope is the 463-registry catalogue — the run
+  fails before a job starts. `scripts/shard_plan.py` bin-packs by the measured
+  `est_items` (longest-processing-time-first), which matters because cost is
+  uneven: the largest catalogued registry is 880 items against a median of 30,
+  so slicing puts several giants in one job while others idle, against a
+  6-hour per-job ceiling. Packing is deterministic on purpose — a rerun that
+  repacked differently would re-embed registries whose shards were already
+  published. A matrix entry is a **space-separated list**, split in Python
+  inside the job, never by shell word-splitting.
+
 - **A published shard is only importable while three things match, and every
   mismatch is silent if waved through.** `core/shards.py` fetches
   `manifest.json` from a rolling `shards-latest` **prerelease** on this repo —

{boost_skill_cli-1.2.48/boost_skill_cli.egg-info → boost_skill_cli-1.2.49}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.48
+Version: 1.2.49
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0
@@ -186,6 +186,10 @@ those vectors. Embedding is ~1.2 s/chunk on CPU — hours for a real corpus —
 and importing the same rows takes 0.12 s, so the difference between the two is
 the difference between semantic search being available and being reachable.
 
+Want everything? `boost quickstart --catalog` taps all 463 catalogued
+registries — 2 min 10 s now that clones run in parallel — and fetches vectors
+for every one that has a published shard.
+
 Already tapped? `boost reindex --fetch-shards` does the download half alone,
 and `boost reindex --dense` embeds locally whatever has no published shard.
 

{boost_skill_cli-1.2.48 → boost_skill_cli-1.2.49}/README.md

@@ -144,6 +144,10 @@ those vectors. Embedding is ~1.2 s/chunk on CPU — hours for a real corpus —
 and importing the same rows takes 0.12 s, so the difference between the two is
 the difference between semantic search being available and being reachable.
 
+Want everything? `boost quickstart --catalog` taps all 463 catalogued
+registries — 2 min 10 s now that clones run in parallel — and fetches vectors
+for every one that has a published shard.
+
 Already tapped? `boost reindex --fetch-shards` does the download half alone,
 and `boost reindex --dense` embeds locally whatever has no published shard.
 

{boost_skill_cli-1.2.48 → boost_skill_cli-1.2.49}/boost_cli/__init__.py

@@ -21,8 +21,16 @@ def _detect_version() -> str:
         import subprocess
         from pathlib import Path
         root = Path(__file__).resolve().parent.parent
+        # `--match v[0-9]*`, exactly as pyproject's git_describe_command:
+        # the repo carries a deliberate non-version tag (`shards-latest`, the
+        # rolling release hosting the vector shards), and without the match
+        # this fallback served `shards-latest-3-g…` as the version — which
+        # parses as no version at all, so `self-update` compared nothing and
+        # answered "already up to date" while a newer release existed.
+        # `--always` still yields a bare SHA when no version tag is reachable.
         proc = subprocess.run(
-            ["git", "-C", str(root), "describe", "--tags", "--always", "--dirty"],
+            ["git", "-C", str(root), "describe", "--tags", "--always",
+             "--dirty", "--match", "v[0-9]*"],
             capture_output=True, text=True, timeout=3)
         described = proc.stdout.strip()
         if proc.returncode == 0 and described:

{boost_skill_cli-1.2.48 → boost_skill_cli-1.2.49}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.2.48'
-__version_tuple__ = version_tuple = (1, 2, 48)
+__version__ = version = '1.2.49'
+__version_tuple__ = version_tuple = (1, 2, 49)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.2.48 → boost_skill_cli-1.2.49}/boost_cli/commands/quickstart.py

@@ -32,19 +32,43 @@ from ..core import output as out
 from ..errors import BoostError
 
 
-def _tap_defaults(pins: dict[str, dict], dry_run: bool) -> list[str]:
-    """Tap the default registries, pinned to a shard's commit when one exists.
+def _selection(catalog_scope: bool) -> list[dict]:
+    """The registries quickstart will tap: the seven defaults, or all of them.
+
+    `--catalog` exists because "search everything" is a real ask and the two
+    costs that used to make it unreasonable are gone: tapping 463 registries is
+    2 min 10 s now that clones run in parallel, and their vectors are a
+    download rather than an hour of CPU.
+    """
+    if not catalog_scope:
+        return [d.copy() for d in config.DEFAULT_TAPS]
+    return [{"name": e["name"], "url": e["url"]}
+            for e in config.load_registry_catalog()
+            if not e.get("list_only") and e.get("name") and e.get("url")]
+
+
+def _tap_defaults(selection: list[dict], pins: dict[str, dict],
+                  dry_run: bool) -> list[str]:
+    """Tap the selected registries, pinned to a shard's commit when one exists.
 
     Returns the tap names that are configured afterwards, tapped here or not.
     Pinning is the whole point: tapping HEAD and then fetching a shard is the
     ordering that produces a commit mismatch on every registry that moved since
     the last shard run.
     """
-    names = [str(d["name"]) for d in config.DEFAULT_TAPS]
+    names = [str(d["name"]) for d in selection]
     commits = {name: str(pins[name].get("commit")) for name in names
                if name in pins}
     if dry_run:
         existing = {t.name for t in registry.list_taps()}
+        pending = [n for n in names if n not in existing]
+        # Over 463 registries a line each is a wall of text, so past a handful
+        # the dry run reports the shape instead of the list.
+        if len(pending) > 12:
+            out.info("would tap %d registries (%d pinned to a published "
+                     "shard's commit)"
+                     % (len(pending), sum(1 for n in pending if n in commits)))
+            return names
         for name in names:
             if name in existing:
                 out.info(out.role("%s already tapped" % name, "muted"))
@@ -56,7 +80,7 @@ def _tap_defaults(pins: dict[str, dict], dry_run: bool) -> list[str]:
     # for work that takes ~2 s done together, and the first thing a new user
     # sees should not be a progress bar.
     with spin.Spinner("tapping %d registries" % len(names)):
-        results = registry.add_many([str(d["url"]) for d in config.DEFAULT_TAPS],
+        results = registry.add_many([str(d["url"]) for d in selection],
                                     curated=True, pins=commits)
     for res in results:
         name = res["name"]
@@ -104,10 +128,13 @@ def _report(results: list[dict]) -> None:
 
 
 def cmd_quickstart(argv) -> int:
-    """boost quickstart [--no-vectors] [--dry-run]"""
+    """boost quickstart [--catalog] [--no-vectors] [--dry-run]"""
     p = cliparse.parser(
         prog="boost quickstart",
         description="Tap the starter registries and load prebuilt vectors")
+    p.add_argument("--catalog", action="store_true",
+                   help="tap every catalogued registry, not just the 7 "
+                        "starters, and fetch vectors for all of them")
     p.add_argument("--no-vectors", action="store_true",
                    help="set up taps and keyword search only, skip shards")
     p.add_argument("--dry-run", action="store_true",
@@ -129,7 +156,8 @@ def cmd_quickstart(argv) -> int:
             out.warn("no published shards: %s" % exc.message)
             manifest = None
 
-    names = _tap_defaults(pins, args.dry_run)
+    selection = _selection(args.catalog)
+    names = _tap_defaults(selection, pins, args.dry_run)
     if args.dry_run:
         planned = [n for n in names if n in pins] if manifest else []
         out.info("would build the keyword index, then import %d shard(s)"

{boost_skill_cli-1.2.48 → boost_skill_cli-1.2.49/boost_skill_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.2.48
+Version: 1.2.49
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License-Expression: Apache-2.0
@@ -186,6 +186,10 @@ those vectors. Embedding is ~1.2 s/chunk on CPU — hours for a real corpus —
 and importing the same rows takes 0.12 s, so the difference between the two is
 the difference between semantic search being available and being reachable.
 
+Want everything? `boost quickstart --catalog` taps all 463 catalogued
+registries — 2 min 10 s now that clones run in parallel — and fetches vectors
+for every one that has a published shard.
+
 Already tapped? `boost reindex --fetch-shards` does the download half alone,
 and `boost reindex --dense` embeds locally whatever has no published shard.
 

{boost_skill_cli-1.2.48 → boost_skill_cli-1.2.49}/boost_skill_cli.egg-info/SOURCES.txt

@@ -553,6 +553,7 @@ scripts/publish_shards.py
 scripts/release_guard.py
 scripts/release_preflight.py
 scripts/serve_docs.py
+scripts/shard_plan.py
 style/README.md
 style/boost.css
 style/boost.js
@@ -776,6 +777,7 @@ tests/unit/test_secretscan.py
 tests/unit/test_selfupdate.py
 tests/unit/test_serve.py
 tests/unit/test_serve_docs.py
+tests/unit/test_shard_plan.py
 tests/unit/test_shards.py
 tests/unit/test_shards_matrix.py
 tests/unit/test_smoke_covers_every_command.py
@@ -795,6 +797,7 @@ tests/unit/test_typosquat.py
 tests/unit/test_updatediff.py
 tests/unit/test_util.py
 tests/unit/test_version.py
+tests/unit/test_version_tags.py
 tests/unit/test_vex.py
 tests/unit/test_visual_harness_flags.py
 tests/unit/test_workflow_concurrency.py

{boost_skill_cli-1.2.48 → boost_skill_cli-1.2.49}/docs/commands.html

@@ -180,7 +180,7 @@
     </div>
     <div class="group" data-group="cfg">
       <div class="group-h">Config &amp; setup</div>
-      <a class="cmd-link" href="#cmd-quickstart" data-search="quickstart tap the starter registries and load prebuilt vectors  --no-vectors --dry-run">quickstart</a>
+      <a class="cmd-link" href="#cmd-quickstart" data-search="quickstart tap the starter registries and load prebuilt vectors  --catalog --no-vectors --dry-run">quickstart</a>
       <a class="cmd-link" href="#cmd-config" data-search="config display or modify boost configuration  --json {list,get,set,unset} key value">config</a>
       <a class="cmd-link" href="#cmd-clean" data-search="clean clear stale caches &amp; broken symlinks  --dry-run --deep">clean</a>
       <a class="cmd-link" href="#cmd-compact" data-search="compact shrink tap clones to the files boost indexes  --dry-run --reclone tap">compact</a>
@@ -974,12 +974,13 @@
         </div>
       </section>
       <h2 class="group-h" id="grp-cfg">Config &amp; setup</h2>
-      <section class="cmd" id="cmd-quickstart" data-search="quickstart tap the starter registries and load prebuilt vectors  --no-vectors --dry-run">
+      <section class="cmd" id="cmd-quickstart" data-search="quickstart tap the starter registries and load prebuilt vectors  --catalog --no-vectors --dry-run">
         <h3><span class="cname">quickstart</span><span class="gtag">cfg</span></h3>
         <p class="summary">Tap the starter registries and load prebuilt vectors</p>
-        <pre class="syn">boost quickstart [--no-vectors] [--dry-run]</pre>
+        <pre class="syn">boost quickstart [--catalog] [--no-vectors] [--dry-run]</pre>
         <div class="args-h">Options</div>
         <div class="args">
+          <div class="arg"><code>--catalog</code><span>tap every catalogued registry, not just the 7 starters, and fetch vectors for all of them</span></div>
           <div class="arg"><code>--no-vectors</code><span>set up taps and keyword search only, skip shards</span></div>
           <div class="arg"><code>--dry-run</code><span>print what would happen, change nothing</span></div>
         </div>

{boost_skill_cli-1.2.48 → boost_skill_cli-1.2.49}/docs/semantic-search.md

@@ -61,9 +61,16 @@ two commands consume them:
 
 ```bash
 boost quickstart                 # tap the starter registries + import their vectors
+boost quickstart --catalog       # …or all 463 catalogued registries
 boost reindex --fetch-shards     # already tapped: import whatever is published
 ```
 
+The published set is the whole catalogue, refreshed weekly. CI packs the 463
+registries into ~60 matrix jobs rather than one per registry, because GitHub
+caps a matrix at 256 jobs and embedding cost is uneven enough that slicing
+would leave one job carrying several of the largest registries
+(`scripts/shard_plan.py`).
+
 Three rules keep a downloaded vector honest, and each of them refuses rather
 than degrades — the failures they prevent are silent ones:
 

{boost_skill_cli-1.2.48 → boost_skill_cli-1.2.49}/pyproject.toml

@@ -118,6 +118,21 @@ boost = "boost_cli.cli:main"
 # are the single source of truth — no constant to bump, no drift. Writes the
 # resolved version to boost_cli/_version.py (git-ignored).
 version_file = "boost_cli/_version.py"
+# ONLY vX.Y.Z tags are versions, and both settings are needed to say so: the
+# describe command decides which tag is *found*, `tag_regex` decides how it is
+# *parsed*. Without them, the rolling `shards-latest` tag that hosts the
+# prebuilt vector shards was picked up as this project's version — a CI
+# checkout resolved `vshards-latest-4-g1c1398c`, which then broke
+# `boost self-update`'s "am I behind PyPI?" comparison, because that compares
+# version tuples and this parses as none.
+#
+# The repository now carries a non-version tag on purpose (a GitHub release
+# needs one), so this is not a hypothetical: any future non-version tag is
+# covered too.
+git_describe_command = [
+    "git", "describe", "--dirty", "--tags", "--long", "--match", "v[0-9]*",
+]
+tag_regex = "^v(?P<version>[0-9]+[^+]*)$"
 
 [tool.setuptools.packages.find]
 # Two top-level packages, one wheel: boost_cli (the zero-dependency CLI) and

boost_skill_cli-1.2.49/scripts/shard_plan.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+# Copyright the boost contributors.
+# SPDX-License-Identifier: Apache-2.0
+"""Pack the registry catalogue into a bounded, balanced Actions matrix.
+
+WHY THIS EXISTS. `shards.yml` ran one job per registry, which is fine for the
+20-repo eval corpus and impossible for the 463-registry catalogue: **GitHub
+caps a matrix at 256 jobs per workflow run**, so 463 rows do not start at all.
+Chunking is therefore not an optimisation, it is the difference between the
+workflow running and not.
+
+WHY BIN-PACKING RATHER THAN SLICING. Embedding cost is wildly uneven — the
+catalogue's largest registry is 880 measured items against a median of 30 and a
+minimum of 1 — so a naive `chunk(n)` puts several giants in one job and leaves
+others with nothing. The whole run then takes as long as its unluckiest chunk, against
+a hard 6-hour job ceiling. Longest-processing-time-first (sort by cost
+descending, always add to the currently cheapest bin) is the standard greedy
+answer and is within 4/3 of optimal, which is far inside the margin that
+matters here. The practical effect is that the biggest registry ends up
+effectively alone in its bin, which is exactly what you want: it is the run's
+critical path either way.
+
+COST PROXY. `est_items` from the bundled catalogue, which is *measured* (see
+`scripts/measure_registry.py`) rather than guessed. It is a proxy for chunk
+count, not chunk count itself — deduplication means a registry that mirrors
+itself is cheaper than its size suggests — but it is the only per-registry
+number available before cloning, and it is right about the ordering, which is
+what the packing needs.
+
+    shard_plan.py --scope catalog                 # matrix JSON for GITHUB_OUTPUT
+    shard_plan.py --scope catalog --explain       # what each job would carry
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from boost_cli.core import config
+
+#: GitHub's documented ceiling. Not a tunable — a matrix that exceeds it fails
+#: the whole run before a single job starts.
+MAX_MATRIX_JOBS = 256
+
+#: Default jobs to plan for. Under the ceiling with room to spare, and enough
+#: parallelism that the run is bounded by its largest registry rather than by
+#: how many bins there are.
+DEFAULT_JOBS = 60
+
+
+def catalog_rows(include_lists: bool = False) -> list[dict]:
+    """Every catalogued registry as ``{"name", "cost"}``, biggest first."""
+    rows = []
+    for entry in config.load_registry_catalog():
+        if not include_lists and entry.get("list_only"):
+            # An awesome-list repo indexes other repos; there is nothing of its
+            # own to embed.
+            continue
+        name = str(entry.get("name") or "")
+        if not name:
+            continue
+        rows.append({"name": name, "cost": int(entry.get("est_items") or 0)})
+    rows.sort(key=lambda r: (-r["cost"], r["name"]))
+    return rows
+
+
+def pack(rows: list[dict], jobs: int) -> list[list[str]]:
+    """Longest-processing-time-first packing into at most `jobs` bins.
+
+    Deterministic: rows arrive sorted by (-cost, name), and ties between bins
+    are broken by index, so the same catalogue always plans the same matrix.
+    That matters for reruns — a rerun that repacked differently would re-embed
+    registries whose shards were already published.
+    """
+    if jobs < 1:
+        raise SystemExit("--jobs must be at least 1")
+    bins: list[list[str]] = [[] for _ in range(min(jobs, max(1, len(rows))))]
+    loads = [0] * len(bins)
+    for row in rows:
+        i = loads.index(min(loads))
+        bins[i].append(row["name"])
+        loads[i] += row["cost"]
+    return [b for b in bins if b]
+
+
+def plan(scope: str, jobs: int, include_lists: bool = False) -> list[list[str]]:
+    """The matrix for `scope`, as a list of registry-name lists."""
+    if scope == "eval":
+        # The pinned corpus every other gate measures against: one job per
+        # registry, because there are twenty of them and no packing is needed.
+        import subprocess
+        out = subprocess.run(
+            [sys.executable, str(Path(__file__).with_name("eval_corpus.py")),
+             "--list-repos"], check=True, capture_output=True, text=True).stdout
+        return [[name] for name in out.split()]
+    rows = catalog_rows(include_lists=include_lists)
+    if not rows:
+        raise SystemExit("the bundled registry catalogue is empty")
+    return pack(rows, jobs)
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--scope", choices=("catalog", "eval"), default="catalog",
+                   help="which registries to shard (default: %(default)s)")
+    p.add_argument("--jobs", type=int, default=DEFAULT_JOBS,
+                   help="how many matrix jobs to plan for (default: %(default)s)")
+    p.add_argument("--include-lists", action="store_true",
+                   help="also shard awesome-list/index repos")
+    p.add_argument("--explain", action="store_true",
+                   help="print the packing as a table instead of JSON")
+    args = p.parse_args(argv)
+
+    if args.jobs > MAX_MATRIX_JOBS:
+        raise SystemExit(
+            "--jobs %d exceeds GitHub's %d-job matrix ceiling; the run would "
+            "fail before starting" % (args.jobs, MAX_MATRIX_JOBS))
+    chunks = plan(args.scope, args.jobs, args.include_lists)
+    if len(chunks) > MAX_MATRIX_JOBS:
+        raise SystemExit("planned %d jobs, over the %d-job ceiling"
+                         % (len(chunks), MAX_MATRIX_JOBS))
+    if args.explain:
+        costs = {r["name"]: r["cost"] for r in catalog_rows(args.include_lists)}
+        for i, chunk in enumerate(chunks):
+            load = sum(costs.get(n, 0) for n in chunk)
+            print("job %2d  %5d est. items  %2d registries  %s"
+                  % (i, load, len(chunk),
+                     ", ".join(chunk[:3]) + (" …" if len(chunk) > 3 else "")))
+        loads = [sum(costs.get(n, 0) for n in c) for c in chunks]
+        print("\n%d jobs · %d registries · %d est. items · heaviest %d, "
+              "lightest %d" % (len(chunks), sum(len(c) for c in chunks),
+                               sum(loads), max(loads), min(loads)))
+        return 0
+    # One matrix entry per job: a space-separated list the workflow splits in
+    # Python, never in shell — `shards.yml`'s header records what happened the
+    # last time a list was word-split by the runner.
+    print(json.dumps([" ".join(chunk) for chunk in chunks]))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{boost_skill_cli-1.2.48 → boost_skill_cli-1.2.49}/tests/functional/test_cli_quickstart.py

@@ -56,6 +56,38 @@ class TestQuickstartDryRun:
             assert str(default["name"]) in res.out
 
 
+class TestQuickstartCatalog:
+    """`--catalog` is the "search everything" entry point."""
+
+    def test_it_plans_every_catalogued_registry(self, boost):
+        from boost_cli.core import config
+        catalogued = [e for e in config.load_registry_catalog()
+                      if not e.get("list_only")]
+        res = boost("quickstart", "--catalog", "--dry-run")
+        # Past a handful the dry run reports the shape: 463 lines of "would
+        # tap" is a wall of text, not a preview.
+        assert "would tap %d registries" % len(catalogued) in res.out
+
+    def test_the_default_scope_is_still_the_seven_starters(self, boost):
+        from boost_cli.core import config
+        res = boost("quickstart", "--dry-run")
+        for default in config.DEFAULT_TAPS:
+            assert str(default["name"]) in res.out
+
+    def test_catalog_scope_excludes_index_repos(self, boost):
+        from boost_cli.core import config
+        lists = [e for e in config.load_registry_catalog()
+                 if e.get("list_only")]
+        if not lists:
+            pytest.skip("no list-only repos in the bundled catalogue")
+        res = boost("quickstart", "--catalog", "--dry-run")
+        total = len([e for e in config.load_registry_catalog()
+                     if not e.get("list_only")])
+        # An awesome-list repo indexes other repos and ships nothing of its
+        # own, so tapping it for vectors buys nothing.
+        assert "would tap %d registries" % total in res.out
+
+
 class TestQuickstartWithoutTheExtra:
     """The default install: no `rag` extra, so no vectors and no fetch."""
 

boost_skill_cli-1.2.49/tests/unit/test_shard_plan.py

@@ -0,0 +1,125 @@
+# Copyright the boost contributors.
+# SPDX-License-Identifier: Apache-2.0
+"""Packing the catalogue into a matrix GitHub will actually run.
+
+Two facts drive every test here. **GitHub caps a matrix at 256 jobs**, so the
+463-registry catalogue cannot be one job per registry — the run fails before a
+single job starts. And embedding cost is wildly uneven: the largest catalogued
+registry measures 880 items against a median of 30, so slicing the list
+into equal chunks puts several giants in one job while others idle, and the run
+takes as long as its unluckiest chunk against a hard 6-hour job ceiling.
+
+Longest-processing-time-first fixes the second and the job count fixes the
+first. The packing must also be *deterministic*: a rerun that repacked
+differently would re-embed registries whose shards were already published.
+"""
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(ROOT / "scripts"))
+
+import shard_plan  # noqa: E402
+
+
+def _rows(*costs):
+    return [{"name": "o/r%d" % i, "cost": c} for i, c in enumerate(costs)]
+
+
+class TestPack:
+    def test_every_registry_lands_in_exactly_one_bin(self):
+        rows = _rows(*range(1, 40))
+        packed = shard_plan.pack(rows, jobs=7)
+        flat = [name for chunk in packed for name in chunk]
+        assert sorted(flat) == sorted(r["name"] for r in rows)
+        assert len(flat) == len(set(flat))
+
+    def test_it_never_plans_more_bins_than_asked(self):
+        # The ceiling is the whole reason this function exists.
+        assert len(shard_plan.pack(_rows(*range(500)), jobs=60)) <= 60
+
+    def test_fewer_registries_than_bins_does_not_pad_with_empties(self):
+        # An empty matrix entry would be a job that taps nothing and then fails
+        # its own "produced no shards" assertion.
+        packed = shard_plan.pack(_rows(5, 5, 5), jobs=10)
+        assert packed == [["o/r0"], ["o/r1"], ["o/r2"]]
+
+    def test_the_giant_ends_up_effectively_alone(self):
+        # It is the run's critical path either way; what matters is that it is
+        # not also carrying somebody else's work.
+        rows = _rows(1000, 10, 10, 10, 10)
+        packed = shard_plan.pack(rows, jobs=3)
+        giant = next(c for c in packed if "o/r0" in c)
+        assert giant == ["o/r0"]
+
+    def test_load_is_balanced_far_better_than_slicing(self):
+        rows = _rows(*([100] * 3 + [1] * 30))
+        costs = {r["name"]: r["cost"] for r in rows}
+        loads = [sum(costs[n] for n in c)
+                 for c in shard_plan.pack(rows, jobs=3)]
+        # Sliced by position the three giants land together (300 vs 15); packed
+        # they separate.
+        assert max(loads) - min(loads) <= 20
+
+    def test_packing_is_deterministic(self):
+        rows = _rows(*range(1, 60))
+        assert shard_plan.pack(rows, jobs=8) == shard_plan.pack(rows, jobs=8)
+
+    def test_zero_jobs_is_refused_rather_than_silently_empty(self):
+        with pytest.raises(SystemExit):
+            shard_plan.pack(_rows(1, 2), jobs=0)
+
+
+class TestCatalogRows:
+    def test_it_reads_the_bundled_catalogue_biggest_first(self):
+        rows = shard_plan.catalog_rows()
+        assert rows, "the bundled catalogue should not be empty"
+        assert [r["cost"] for r in rows] == sorted(
+            (r["cost"] for r in rows), reverse=True)
+
+    def test_list_only_repos_are_excluded_by_default(self):
+        # An awesome-list repo indexes other repos; there is nothing of its own
+        # to embed, so a job for it would produce no shard and fail.
+        from boost_cli.core import config
+        lists = {e["name"] for e in config.load_registry_catalog()
+                 if e.get("list_only")}
+        names = {r["name"] for r in shard_plan.catalog_rows()}
+        assert not (names & lists)
+        if lists:
+            assert names < {r["name"] for r
+                            in shard_plan.catalog_rows(include_lists=True)}
+
+
+class TestCli:
+    def _run(self, *args):
+        return subprocess.run([sys.executable,
+                               str(ROOT / "scripts" / "shard_plan.py"), *args],
+                              capture_output=True, text=True)
+
+    def test_it_emits_a_json_list_of_space_separated_chunks(self):
+        out = self._run("--scope", "catalog", "--jobs", "12").stdout
+        matrix = json.loads(out)
+        assert len(matrix) == 12
+        assert all(isinstance(chunk, str) for chunk in matrix)
+        assert all("/" in chunk for chunk in matrix)
+
+    def test_over_the_ceiling_is_a_hard_error_not_a_truncation(self):
+        # Truncating would silently drop registries from the publish.
+        res = self._run("--scope", "catalog", "--jobs", "300")
+        assert res.returncode != 0
+        assert "256" in res.stderr + res.stdout
+
+    def test_explain_reports_the_shape(self):
+        out = self._run("--scope", "catalog", "--jobs", "10", "--explain").stdout
+        assert "heaviest" in out and "lightest" in out
+
+    def test_the_whole_catalogue_fits_the_default_plan(self):
+        # The number the workflow actually runs with.
+        matrix = json.loads(self._run("--scope", "catalog").stdout)
+        assert len(matrix) <= shard_plan.MAX_MATRIX_JOBS
+        packed = sum(len(chunk.split()) for chunk in matrix)
+        assert packed == len(shard_plan.catalog_rows())