boost-skill-cli 1.0.304__tar.gz → 1.0.306__tar.gz

{boost_skill_cli-1.0.304/boost_skill_cli.egg-info → boost_skill_cli-1.0.306}/PKG-INFO

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

{boost_skill_cli-1.0.304 → boost_skill_cli-1.0.306}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.304'
-__version_tuple__ = version_tuple = (1, 0, 304)
+__version__ = version = '1.0.306'
+__version_tuple__ = version_tuple = (1, 0, 306)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.304 → boost_skill_cli-1.0.306/boost_skill_cli.egg-info}/PKG-INFO

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

{boost_skill_cli-1.0.304 → boost_skill_cli-1.0.306}/boost_skill_cli.egg-info/SOURCES.txt

@@ -225,6 +225,7 @@ docs/roadmap/items/integrity-verification-boost-verify.md
 docs/roadmap/items/internal-architecture-diagrams.md
 docs/roadmap/items/invocation-pid-logging-for-crash-correlation.md
 docs/roadmap/items/journal-rotation-race-and-handle-leak.md
+docs/roadmap/items/keyless-item.md
 docs/roadmap/items/layering-guard-import-linter.md
 docs/roadmap/items/license-compliance-scanning.md
 docs/roadmap/items/lighthouse-ci-on-the-pages-site.md
@@ -546,6 +547,7 @@ tests/unit/test_typosquat.py
 tests/unit/test_updatediff.py
 tests/unit/test_util.py
 tests/unit/test_version.py
+tests/unit/test_workflow_concurrency.py
 tests/unit/test_workflow_timeouts.py
 tests/unit/test_workflows.py
 tests/visual/a11y_check.mjs

boost_skill_cli-1.0.306/docs/roadmap/items/ci-time-is-now-runner-queueing.md

@@ -0,0 +1,71 @@
+---
+id: ci-time-is-now-runner-queueing
+board: code
+section: pipeline
+status: shipped
+category: CI speed
+complexity: M
+impact: High
+wow: 4
+note: 104 job-min queued vs 236 executing — 31% of CI is waiting for a runner
+order: 62
+owner: loop/ci-concurrency
+pr: 350
+title: A third of CI job time is spent waiting for a runner, not running
+---
+With the mutation gate no longer dominating, the largest remaining term in CI wall clock is
+<b>queueing</b>. Measured over six consecutive successful <code>ci</code> runs: <b>104
+job-minutes queued</b> against <b>236 job-minutes executing</b> &mdash; <b>31%</b> of all job
+time spent waiting for a runner.
+
+<b>The obvious metric lies.</b> A run's <code>run_started_at</code> minus
+<code>created_at</code> is <b>0.0 for every run</b>, which reads as "no queueing anywhere".
+Queueing happens per <em>job</em>, not per run, so it is only visible as
+<code>job.started_at - job.created_at</code>. Anything measuring this at run level will
+conclude, wrongly, that there is nothing to fix.
+
+The per-run spread shows what drives it &mdash; median job queue by run:
+<code>c36c53a7</code> 0.1&nbsp;min, <code>c15ed9da</code> 0.1, <code>903b704f</code> 0.2,
+<code>638bffeb</code> 0.7, <code>ad71ba99</code> <b>2.5</b>, <code>9e190537</code> <b>2.9</b>.
+That is a 29&times; swing driven not by the change under test but by how many sibling
+<code>loop/*</code> branches and Dependabot PRs happen to be live at the same moment. It is why
+one merge took <b>41 minutes</b> 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 <code>concurrency</code> group that cancels
+superseded PR runs; capping the shard matrix with <code>max-parallel</code>; or making the shard
+count adaptive. Worth measuring before choosing &mdash; this item is the measurement, not the
+fix.
+
+<b>Shipped: the least intrusive one, and it turned out to be a plain omission rather than a
+trade-off.</b> Seven workflows here already declare a <code>concurrency</code> group.
+<code>ci.yml</code> &mdash; the largest by a wide margin, ~36 checks including six mutation
+shards &mdash; 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 <b>condition</b>:
+<code>cancel-in-progress: true</code> would also cancel a push to main, which
+<code>publish.yml</code> gates the release on via <code>workflow_run</code> &mdash; a merge that
+silently never ships &mdash; and a <code>merge_group</code> 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 <b>key</b>: non-PR events group on <code>github.sha</code>, not <code>github.ref</code>.
+<code>cancel-in-progress: false</code> does not mean "never cancel" &mdash; it means a newer run
+<i>waits</i>, and GitHub cancels the older <em>pending</em> 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 <code>ci</code> never completes, and since <code>publish.yml</code> fires on
+<code>workflow_run</code> of <code>ci</code>, 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 <code>merge_group</code> and fails if any cancels unconditionally
+&mdash; so the deadlock cannot arrive later through a different file.
+
+What this does <em>not</em> do is reduce the footprint of a single run, which is the other half of
+the measurement. <code>max-parallel</code> on the shard matrix and an adaptive shard count are
+still open, and both trade latency for footprint rather than removing waste &mdash; worth
+re-measuring queue time after this lands before spending that trade.

boost_skill_cli-1.0.306/docs/roadmap/items/keyless-item.md

@@ -0,0 +1,84 @@
+---
+id: keyless-semantic-search-for-everyone
+board: code
+section: internals
+status: next
+category: Retrieval · Architecture
+complexity: L
+impact: High
+wow: 5
+note: the vector store was never the problem — only turning text into vectors needs a key
+order: 0
+owner:
+pr:
+title: Semantic search is gated behind an API key it does not need
+---
+boost's flagship retrieval is invisible to almost everyone who installs it. <code>boost search "my
+app is slow"</code> on the five default taps returns <code>dnanexus-integration</code>,
+<code>tamarind</code>, <code>cirq</code>, <code>molfeat</code> &mdash; 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.
+
+<b>The vector database was never the problem.</b> Vectors already live on the user's own machine in
+sqlite-vec (<code>~/.boost/cache/rag_vectors.sqlite</code>), refreshed per tap against the commit it
+was built from. Nothing is hosted and nothing needs to be. The <em>only</em> API-bound step is
+turning text into vectors: <code>embed.provider()</code> returns <code>"voyage"</code> with
+<code>VOYAGE_API_KEY</code> set, <code>"openai"</code> with <code>OPENAI_API_KEY</code>, and
+otherwise <code>None</code> &mdash; 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.
+
+<b>1 &mdash; A local ONNX provider, as the third link in a chain built for it.</b> Extend
+<code>embed.provider()</code> to Voyage &rarr; OpenAI &rarr; <b>local</b> &rarr; BM25, using ONNX
+Runtime on CPU with a small model (<code>bge-small-en-v1.5</code>, 384-dim, ~30&nbsp;MB once). The
+sqlite-vec store, the per-tap commit cache and KNN search are all untouched &mdash; only the
+text&rarr;vector call changes. This removes the key, the signup and the card for <em>every</em>
+user, and Voyage stays a free quality upgrade for anyone who adds one.
+
+<b>2 &mdash; Prebuild per-registry shards in CI.</b> 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
+&mdash; the cache key the code already uses &mdash; so <code>boost tap</code> fetches the catalogue
+<em>and</em> its shard. This is how Homebrew, npm and crates.io index a moving world.
+
+<b>3 &mdash; Local delta top-up.</b> 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.
+
+<b>4 &mdash; Fuse the two engines with reciprocal rank fusion.</b> Confirmed against the shipped
+code: <code>rag.retrieve_any()</code> picks <em>one</em> engine &mdash; 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": <code>score = 1/(60+rank_bm25) + 1/(60+rank_dense)</code>. Fusing on
+<b>ranks, not scores</b>, is the point &mdash; 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
+(<code>EAS</code>, <code>pptx</code>, skill names) where BM25 is strongest and embeddings weakest,
+while sloppy queries are where BM25 returns quantum computing. <code>retrieve_any</code> 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.
+
+<b>5 &mdash; A hosted demo</b> on free tiers, so the experience is reachable without installing
+anything. <b>6 &mdash; Publish the eval</b>: 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 &mdash; and if pure dense wins on this corpus, that is the result worth publishing.
+
+<b>Scope note.</b> This is an epic, not a single change. Step 1 is the one that removes the wall and
+is worth landing alone; steps 2&ndash;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 &mdash; the value of keeping it whole here is that the
+steps only make sense against each other.
+
+Constraints this must respect: the shipped runtime is stdlib-only and
+<code>[project].dependencies</code> is empty, so a local model belongs behind an extra like
+<code>[rag]</code>, with the keyless path degrading to BM25 exactly as it does now. The required
+<code>eval</code> 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]].

{boost_skill_cli-1.0.304 → boost_skill_cli-1.0.306}/docs/roadmap.html

@@ -111,7 +111,7 @@
       <div class="stat"><b>16</b><span>Shipped</span></div>
       <div class="stat"><b>1</b><span>Next up</span></div>
       <div class="stat"><b>4</b><span>Planned</span></div>
-      <div class="stat"><b>181</b><span>Loop finds</span></div>
+      <div class="stat"><b>182</b><span>Loop finds</span></div>
       <!-- /ROADMAP:stats -->
     </div>
   </section>
@@ -598,6 +598,86 @@ message, so routing it through the helper would change user-facing errors.</p>
     <div class="rgrid">
 
       <!-- ROADMAP:cards section=internals -->
+      <article class="cap rcard" id="keyless-semantic-search-for-everyone">
+        <div class="head"><span class="pill next">Next</span><span class="cat">Retrieval · Architecture</span></div>
+        <h3>Semantic search is gated behind an API key it does not need</h3>
+        <p>boost's flagship retrieval is invisible to almost everyone who installs it. <code>boost search "my
+app is slow"</code> on the five default taps returns <code>dnanexus-integration</code>,
+<code>tamarind</code>, <code>cirq</code>, <code>molfeat</code> &mdash; 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.
+
+<b>The vector database was never the problem.</b> Vectors already live on the user's own machine in
+sqlite-vec (<code>~/.boost/cache/rag_vectors.sqlite</code>), refreshed per tap against the commit it
+was built from. Nothing is hosted and nothing needs to be. The <em>only</em> API-bound step is
+turning text into vectors: <code>embed.provider()</code> returns <code>"voyage"</code> with
+<code>VOYAGE_API_KEY</code> set, <code>"openai"</code> with <code>OPENAI_API_KEY</code>, and
+otherwise <code>None</code> &mdash; 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.
+
+<b>1 &mdash; A local ONNX provider, as the third link in a chain built for it.</b> Extend
+<code>embed.provider()</code> to Voyage &rarr; OpenAI &rarr; <b>local</b> &rarr; BM25, using ONNX
+Runtime on CPU with a small model (<code>bge-small-en-v1.5</code>, 384-dim, ~30&nbsp;MB once). The
+sqlite-vec store, the per-tap commit cache and KNN search are all untouched &mdash; only the
+text&rarr;vector call changes. This removes the key, the signup and the card for <em>every</em>
+user, and Voyage stays a free quality upgrade for anyone who adds one.
+
+<b>2 &mdash; Prebuild per-registry shards in CI.</b> 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
+&mdash; the cache key the code already uses &mdash; so <code>boost tap</code> fetches the catalogue
+<em>and</em> its shard. This is how Homebrew, npm and crates.io index a moving world.
+
+<b>3 &mdash; Local delta top-up.</b> 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.
+
+<b>4 &mdash; Fuse the two engines with reciprocal rank fusion.</b> Confirmed against the shipped
+code: <code>rag.retrieve_any()</code> picks <em>one</em> engine &mdash; 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": <code>score = 1/(60+rank_bm25) + 1/(60+rank_dense)</code>. Fusing on
+<b>ranks, not scores</b>, is the point &mdash; 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
+(<code>EAS</code>, <code>pptx</code>, skill names) where BM25 is strongest and embeddings weakest,
+while sloppy queries are where BM25 returns quantum computing. <code>retrieve_any</code> 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.
+
+<b>5 &mdash; A hosted demo</b> on free tiers, so the experience is reachable without installing
+anything. <b>6 &mdash; Publish the eval</b>: 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 &mdash; and if pure dense wins on this corpus, that is the result worth publishing.
+
+<b>Scope note.</b> This is an epic, not a single change. Step 1 is the one that removes the wall and
+is worth landing alone; steps 2&ndash;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 &mdash; the value of keeping it whole here is that the
+steps only make sense against each other.
+
+Constraints this must respect: the shipped runtime is stdlib-only and
+<code>[project].dependencies</code> is empty, so a local model belongs behind an extra like
+<code>[rag]</code>, with the keyless path degrading to BM25 exactly as it does now. The required
+<code>eval</code> 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]].</p>
+        <div class="meta">
+          <span class="m">Complexity <b>L</b></span>
+          <span class="m hi">Impact <b>High</b></span>
+          <span class="m">Wow <b class="wow">★★★★★</b></span>
+          <span class="m">the vector store was never the problem — only turning text into vectors needs a key</span>
+        </div>
+      </article>
+
       <article class="cap rcard" id="memoize-config-load-in-process">
         <div class="head"><span class="pill shipped">Shipped</span><span class="cat">Performance</span></div>
         <h3>Memoize <code>config.load()</code> in-process</h3>
@@ -2623,7 +2703,7 @@ missing file is now imputed at the measured mean rate, which keeps every weight
       </article>
 
       <article class="cap rcard" id="ci-time-is-now-runner-queueing">
-        <div class="head"><span class="pill planned">Planned</span><span class="cat">CI speed</span></div>
+        <div class="head"><span class="pill shipped">Shipped</span><span class="cat">CI speed</span></div>
         <h3>A third of CI job time is spent waiting for a runner, not running</h3>
         <p>With the mutation gate no longer dominating, the largest remaining term in CI wall clock is
 <b>queueing</b>. Measured over six consecutive successful <code>ci</code> runs: <b>104
@@ -2649,7 +2729,38 @@ dozen branches are in flight, because every concurrent PR now multiplies its foo
 roughly in increasing order of intrusiveness: a <code>concurrency</code> group that cancels
 superseded PR runs; capping the shard matrix with <code>max-parallel</code>; or making the shard
 count adaptive. Worth measuring before choosing &mdash; this item is the measurement, not the
-fix.</p>
+fix.
+
+<b>Shipped: the least intrusive one, and it turned out to be a plain omission rather than a
+trade-off.</b> Seven workflows here already declare a <code>concurrency</code> group.
+<code>ci.yml</code> &mdash; the largest by a wide margin, ~36 checks including six mutation
+shards &mdash; 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 <b>condition</b>:
+<code>cancel-in-progress: true</code> would also cancel a push to main, which
+<code>publish.yml</code> gates the release on via <code>workflow_run</code> &mdash; a merge that
+silently never ships &mdash; and a <code>merge_group</code> 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 <b>key</b>: non-PR events group on <code>github.sha</code>, not <code>github.ref</code>.
+<code>cancel-in-progress: false</code> does not mean "never cancel" &mdash; it means a newer run
+<i>waits</i>, and GitHub cancels the older <em>pending</em> 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 <code>ci</code> never completes, and since <code>publish.yml</code> fires on
+<code>workflow_run</code> of <code>ci</code>, 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 <code>merge_group</code> and fails if any cancels unconditionally
+&mdash; so the deadlock cannot arrive later through a different file.
+
+What this does <em>not</em> do is reduce the footprint of a single run, which is the other half of
+the measurement. <code>max-parallel</code> on the shard matrix and an adaptive shard count are
+still open, and both trade latency for footprint rather than removing waste &mdash; worth
+re-measuring queue time after this lands before spending that trade.</p>
         <div class="meta">
           <span class="m">Complexity <b>M</b></span>
           <span class="m hi">Impact <b>High</b></span>

boost_skill_cli-1.0.306/tests/unit/test_workflow_concurrency.py

@@ -0,0 +1,112 @@
+"""Unit tests: superseded PR runs are cancelled, releases never are.
+
+Measured over six consecutive successful ``ci`` runs, **31%** of all job time
+was spent queueing rather than executing (104 job-minutes against 236). The
+median per-job queue swung 29x between runs — 0.1 min when the repo was quiet,
+2.9 min when a dozen ``loop/*`` branches and Dependabot PRs were live — so the
+cost is driven by concurrent footprint, not by the change under test. Sharding
+the mutation gate traded one runner slot for six and made that worse on purpose.
+
+``ci.yml`` is the largest workflow in the repo by a wide margin, and it was the
+only one with no ``concurrency`` group at all: every push to a pull request left
+the previous run's ~36 checks (six of them mutation shards) running to
+completion against nothing.
+
+The dangerous half of the fix is the half these tests pin. Cancelling a
+**pull_request** run that a newer push superseded costs nothing. Cancelling a
+**push to main** would abandon the run ``publish.yml`` gates the release on, and
+cancelling a **merge_group** run would leave a required check permanently
+unreported and deadlock the queue — the exact failure mode ci.yml's own comments
+describe. So cancellation must be conditional on the event, and that condition
+is what a future edit is most likely to get wrong.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+
+WORKFLOWS = Path(__file__).resolve().parents[2] / ".github" / "workflows"
+CI = WORKFLOWS / "ci.yml"
+
+pytestmark = pytest.mark.skipif(
+    not CI.exists(),
+    reason=".github/workflows not reachable (e.g. mutation sandbox)")
+
+
+def concurrency_block(path: Path) -> str:
+    """The top-level ``concurrency:`` mapping of a workflow, or ''.
+
+    Top-level only: a job-level block is indented and must not be mistaken for
+    the workflow's own policy.
+    """
+    text = path.read_text(encoding="utf-8")
+    m = re.search(r"^concurrency:\s*$\n((?:^[ \t]+\S.*\n|^\s*#.*\n)*)", text, re.M)
+    return m.group(1) if m else ""
+
+
+class TestCiCancelsSupersededRuns:
+    def test_ci_declares_a_concurrency_group(self):
+        assert concurrency_block(CI), \
+            "ci.yml is the biggest workflow here; without a concurrency group " \
+            "every superseded push keeps ~36 checks running against nothing"
+
+    def test_the_group_is_per_pull_request(self):
+        # Keyed on the PR number so two PRs never cancel each other.
+        assert "github.event.pull_request.number" in concurrency_block(CI)
+
+    def test_non_pr_events_group_on_the_commit_not_the_ref(self):
+        # THE SUBTLE ONE. `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 `github.ref` puts
+        # every main push in one group, so three quick merges would leave a
+        # middle commit whose ci never completes; publish.yml fires on
+        # `workflow_run` of ci, so that commit would never release. A sha is
+        # unique per commit, so main and the merge queue never share a group.
+        block = concurrency_block(CI)
+        assert "github.sha" in block, block
+        assert "github.ref" not in block, \
+            "grouping non-PR runs on the ref can strand a main commit unreleased"
+
+    def test_cancellation_is_conditional_not_unconditional(self):
+        # `cancel-in-progress: true` would cancel main and merge_group runs too.
+        block = concurrency_block(CI)
+        m = re.search(r"cancel-in-progress:\s*(.+)", block)
+        assert m, "no cancel-in-progress in %r" % block
+        value = m.group(1).strip()
+        assert value not in ("true", "'true'", '"true"'), \
+            "unconditional cancel would abandon the run publish.yml gates on"
+        assert "pull_request" in value, value
+
+    def test_only_pull_request_events_are_cancelled(self):
+        # The whole safety property in one assertion: the guard names
+        # pull_request, so push-to-main and merge_group evaluate false.
+        value = re.search(r"cancel-in-progress:\s*(.+)",
+                          concurrency_block(CI)).group(1)
+        assert "github.event_name == 'pull_request'" in value, value
+
+
+class TestReleasePathIsNeverCancelled:
+    def test_publish_does_not_cancel_in_progress(self):
+        # Every merge to main cuts a PyPI release; cancelling a release run
+        # mid-upload is how you get a tagged version that never shipped.
+        block = concurrency_block(WORKFLOWS / "publish.yml")
+        assert "cancel-in-progress: false" in block, block
+
+    def test_no_workflow_cancels_a_merge_group_run(self):
+        # A required context whose run is cancelled never reports, and the
+        # merge queue waits on it forever. Any workflow that both triggers on
+        # merge_group and cancels unconditionally is that deadlock waiting to
+        # happen.
+        offenders = []
+        for path in sorted(WORKFLOWS.glob("*.yml")):
+            text = path.read_text(encoding="utf-8")
+            if not re.search(r"^\s*merge_group:", text, re.M):
+                continue
+            block = concurrency_block(path)
+            if re.search(r"cancel-in-progress:\s*true\s*$", block, re.M):
+                offenders.append(path.name)
+        assert not offenders, \
+            "these cancel merge_group runs and would deadlock the queue: %s" \
+            % ", ".join(offenders)

boost_skill_cli-1.0.304/docs/roadmap/items/ci-time-is-now-runner-queueing.md

@@ -1,40 +0,0 @@
----
-id: ci-time-is-now-runner-queueing
-board: code
-section: pipeline
-status: planned
-category: CI speed
-complexity: M
-impact: High
-wow: 4
-note: 104 job-min queued vs 236 executing — 31% of CI is waiting for a runner
-order: 62
-owner:
-pr:
-title: A third of CI job time is spent waiting for a runner, not running
----
-With the mutation gate no longer dominating, the largest remaining term in CI wall clock is
-<b>queueing</b>. Measured over six consecutive successful <code>ci</code> runs: <b>104
-job-minutes queued</b> against <b>236 job-minutes executing</b> &mdash; <b>31%</b> of all job
-time spent waiting for a runner.
-
-<b>The obvious metric lies.</b> A run's <code>run_started_at</code> minus
-<code>created_at</code> is <b>0.0 for every run</b>, which reads as "no queueing anywhere".
-Queueing happens per <em>job</em>, not per run, so it is only visible as
-<code>job.started_at - job.created_at</code>. Anything measuring this at run level will
-conclude, wrongly, that there is nothing to fix.
-
-The per-run spread shows what drives it &mdash; median job queue by run:
-<code>c36c53a7</code> 0.1&nbsp;min, <code>c15ed9da</code> 0.1, <code>903b704f</code> 0.2,
-<code>638bffeb</code> 0.7, <code>ad71ba99</code> <b>2.5</b>, <code>9e190537</code> <b>2.9</b>.
-That is a 29&times; swing driven not by the change under test but by how many sibling
-<code>loop/*</code> branches and Dependabot PRs happen to be live at the same moment. It is why
-one merge took <b>41 minutes</b> 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 <code>concurrency</code> group that cancels
-superseded PR runs; capping the shard matrix with <code>max-parallel</code>; or making the shard
-count adaptive. Worth measuring before choosing &mdash; this item is the measurement, not the
-fix.