CI checks a branch against the kernel branch of the same name, or main; pages regenerated for v0.10 items 1 to 5

.github/workflows/ci.yml

@@ -26,14 +26,49 @@ jobs:
         with:
           path: ctrlrun-docs
 
+      # Which commit of the library to check these pages against. A dispatch names one. A
+      # branch here is checked against the `CTRLRun/ctrlrun` branch of the same name when
+      # there is one, because that is the pair: a change there that alters a docstring or a
+      # `--help` comes with a branch here, regenerated against it, and each is checked against
+      # the other (that repository's `docs` job does the mirror image). Everything else is
+      # checked against `main`, so the pages on `main` match the library's `main` at all times.
+      #
+      # Before this every branch here was checked against the library's `main`, and a page
+      # regenerated for a commit that had not merged yet was red until it did -- by
+      # construction, for the whole of a release cycle. The fallback is `main` and not a skip,
+      # for the reason `_core.py` raises: red for a reason beats green for none.
+      #
+      # The branch name reaches the shell through `env:`, never inline in the script, so a
+      # branch called `$(...)` is a string here and not a command. The match is exact and
+      # fixed-string: `ls-remote` matches a pattern against the tail of a ref, and `.` in a
+      # version would be a regex wildcard.
+      - name: Pick the ctrlrun ref
+        id: ctrlrun
+        env:
+          DISPATCHED: ${{ github.event.client_payload.sha }}
+          BRANCH: ${{ github.head_ref || github.ref_name }}
+        run: |
+          set -eu
+          if [ -n "$DISPATCHED" ]; then
+            echo "ref=$DISPATCHED" >> "$GITHUB_OUTPUT"
+            echo "ctrlrun at $DISPATCHED, the commit the dispatch named"
+          elif git ls-remote --heads https://github.com/CTRLRun/ctrlrun.git "refs/heads/$BRANCH" \
+              | cut -f2 | grep -qxF "refs/heads/$BRANCH"; then
+            echo "ref=$BRANCH" >> "$GITHUB_OUTPUT"
+            echo "ctrlrun at $BRANCH, the branch of the same name"
+          else
+            echo "ref=main" >> "$GITHUB_OUTPUT"
+            echo "ctrlrun at main: it has no branch named $BRANCH"
+          fi
+
       # The library these pages document. The checks read it -- a page that says the CLI
       # prints X is only true if the CLI prints X -- and `tools/docs_audit/_core.py` raises
       # when it is absent rather than skipping, so a checkout that failed to happen is a red
       # run and not a green one that verified nothing.
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           repository: CTRLRun/ctrlrun
-          ref: ${{ github.event.client_payload.sha || 'main' }}
+          ref: ${{ steps.ctrlrun.outputs.ref }}
           path: ctrlrun
 
       - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0

README.md

@@ -64,7 +64,12 @@ Each also takes `--check`, which is what CI runs.
 
 ## How the two repositories stay in step
 
-- CI here checks out `CTRLRun/ctrlrun` and runs every page check against it.
+- CI here checks out `CTRLRun/ctrlrun` and runs every page check against it: the branch of
+  the same name as the one under test when there is one, `main` otherwise. A change there
+  that alters a docstring or a `--help` comes with a branch here of the same name, regenerated
+  against it, and the two merge together, the code first. `main` is checked against `main`.
+- That repository's `docs` job is the mirror image: it checks out the branch here named
+  after the kernel branch under test, or `main`, and runs the same checks.
 - A push to that repository's `main` sends a `library-changed` dispatch, so a change to the
   code re-checks the pages that describe it.
 - A weekly run is the floor, so a dispatch that stops arriving is a red run and not silence.

docs.mdx

@@ -219,8 +219,8 @@ the framework's own interrupt, and a framework with no such primitive does not n
 
 {/* generated from the suite, pyproject and the soak (mdx) — run the generator */}
 - **Version 0.9.0**, on [PyPI](https://pypi.org/project/ctrlrun/), Python 3.11 and later.
-- **5,975 tests**, every version specified before it was written and every requirement mutation-tested.
-- **24 guarantees you can check in your own setup**, with `ctrlrun verify` against your policy, on your store's backend, in a scratch store it creates.
+- **6,033 tests**, every version specified before it was written and every requirement mutation-tested.
+- **27 guarantees you can check in your own setup**, with `ctrlrun verify` against your policy, on your store's backend, in a scratch store it creates.
 - **One host: a file.** SQLite, no server, no ops. **Many hosts: Postgres**, the same guarantees, graded by the same suite.
 - **Soaked for 20m 0s on postgres**: 889,735 actions, 0 unattributed ambiguous outcomes, positive control fired. Nothing here establishes what only accumulates over days. [What it does not establish](https://ctrlrun.dev/docs/production/soak).
 - **Each receipt carries the hash of the one before it**, so an alteration is detected and named.