v0.10.0

.github/actions/setup-bocpy-test/action.yml

@@ -26,6 +26,17 @@ inputs:
       windows-x86 sets this to ``x86``).
     required: false
     default: ""
+  check-latest:
+    description: >
+      Forwarded to ``actions/setup-python``. When ``"true"`` the
+      action resolves the interpreter against the downloadable
+      versions-manifest instead of relying on a local toolcache hit.
+      Required for ``x86`` on the Windows 2025 image, where 32-bit
+      CPython is no longer pre-installed in the toolcache (only the
+      manifest ships ``win32`` builds). Defaults to ``"false"`` so
+      the cached fast path is used everywhere else.
+    required: false
+    default: "false"
   upgrade-pip:
     description: >
       When ``"true"`` (the default) run ``python -m pip install
@@ -51,6 +62,7 @@ runs:
       with:
         python-version: ${{ inputs.python-version }}
         architecture: ${{ inputs.architecture }}
+        check-latest: ${{ inputs.check-latest }}
 
     - name: Upgrade pip
       if: ${{ inputs.upgrade-pip == 'true' }}

.github/agents/editor-lens.agent.md

@@ -25,6 +25,38 @@ target is a codebase where every remaining comment is one a maintainer
 would write today, from scratch, knowing nothing about the PR that
 introduced it.
 
+### The inline-comment single-line rule (repo norm)
+
+**Every inline comment defaults to a single line of at most 120
+characters, or it is deleted.** An inline comment is a `#` block in
+Python or a `//` block in C that sits inside a function body or above a
+statement. This is the repo standard, not a per-PR cleanup: verbose
+multi-line inline comments rot as the code beneath them changes, drift
+out of sync, and bury the few comments that earn their keep. A
+multi-line inline comment is a smell — collapse it to one line or cut
+it.
+
+A multi-line inline comment survives **only** with an explicit
+per-case justification, and only these justifications qualify:
+
+- a non-obvious concurrency invariant the code cannot express (2PL
+  lock ordering, MCS handoff, memory-ordering rationale);
+- the rationale block above a non-trivial version-gate `#if`/`#elif`
+  ladder;
+- an X-macro / `clang-format off` table boundary that is itself
+  structural;
+- a reference anchor that needs a line of context to be followed.
+
+If a surviving multi-line inline comment does not fall into one of
+those buckets, collapse it. When in doubt, collapse.
+
+**Docstrings and doc-blocks are exempt from the single-line rule.**
+Python docstrings, C `///` / `/** */` Doxygen headers, and Sphinx
+`:param:` / `:returns:` stubs in `.pyi` files are *documentation*, not
+inline commentary. They may — and should — carry in-depth, useful
+prose across multiple lines. Trim genuine wordiness, but do not force a
+docstring onto one line; a docstring's job is to document thoroughly.
+
 A second, broader mandate: catch **cryptic references to internal
 review artifacts** wherever they appear in the diff, including
 user-facing files (`README.md`, `sphinx/source/**`, `CHANGELOG.md`,
@@ -144,7 +176,9 @@ finalize.
   express: 2PL lock ordering by cown ID, MCS handoff invariants,
   memory-ordering rationale (`// acquire pairs with the release in
   ...`), why a particular `_Py_atomic_*` was chosen, why a
-  sub-interpreter API ladder is structured the way it is.
+  sub-interpreter API ladder is structured the way it is. These are
+  the canonical justification for a multi-line inline comment — but
+  prefer one tight line even here when the invariant fits.
 - **Version-gate rationale** — the prose above a non-trivial
   `#if PY_VERSION_HEX >= ...` ladder explaining what changed
   upstream. Trim if wordy; do not delete.
@@ -160,6 +194,14 @@ finalize.
 
 ### Rewrite (collapse, don't delete)
 
+- **Any multi-line inline comment without a qualifying justification.**
+  Per the inline-comment single-line rule above, a `#` or `//`
+  comment spanning more than one line is collapsed to a single
+  ≤120-char line unless it is a concurrency invariant, version-gate
+  rationale, X-macro / `clang-format` table boundary, or a reference
+  anchor needing context. Default to collapsing; keep multi-line only
+  when one of those buckets applies. (Docstrings and Doxygen / Sphinx
+  doc-blocks are exempt — see the rule above.)
 - **Wordy explanations of correct behavior.** Three sentences
   paraphrasing what the next ten lines obviously do → one line, a
   reference anchor, or nothing.
@@ -249,8 +291,10 @@ When reviewing, produce findings in these sections:
    archaeology, or paraphrase. List file + line range + the comment
    text. These can be deleted without further review. *Full prose
    edit scope only.*
-3. **Rewrites** — wordy or stale comments that should be collapsed.
-   For each, give the original and the proposed replacement. *Full
+3. **Rewrites** — wordy or stale comments that should be collapsed,
+   including every multi-line inline comment collapsed to a single
+   ≤120-char line under the inline-comment single-line rule. For
+   each, give the original and the proposed replacement. *Full
    prose edit scope only.*
 4. **Keep with edit** — load-bearing comments that need a small fix
    (stale file path, wrong PEP number, dated phrasing). *Full prose
@@ -262,7 +306,9 @@ When reviewing, produce findings in these sections:
    comment and what's ambiguous. Always include any `TODO` / `FIXME`
    without an issue or sketch link.
 6. **Summary** — counts (cuts / rewrites / edits / kept / asked),
-   and an estimated LOC reduction.
+   the number of multi-line inline comments collapsed to one line
+   and the number of multi-line inline comments kept (each with its
+   qualifying justification), and an estimated LOC reduction.
 
 When invoked via `review-loop`, expect to iterate: apply approved
 cuts and rewrites, then re-scan the same target until no new

.github/dependabot.yml

@@ -36,6 +36,24 @@ updates:
         applies-to: version-updates
         patterns:
           - "*"
+    # Deferred docs-stack updates. These releases require Python >=3.11
+    # and therefore cannot enter ``ci/constraints-docs.txt`` while the
+    # project floor in ``pyproject.toml`` is still ``>=3.10``. Keep this
+    # list in sync with the comment above ``requires-python`` in
+    # ``pyproject.toml``; remove the block (and regenerate the
+    # constraints) once the floor is bumped to >=3.11 after Python 3.10
+    # reaches EOL (October 2026).
+    #
+    # ``ignore`` filters out matching packages before the group is
+    # assembled, so non-docs bumps (cyclonedx-python-lib, idna, etc.)
+    # still land in a smaller weekly PR. Security advisories for the
+    # ignored packages bypass this list and open immediately.
+    ignore:
+      - dependency-name: "docutils"
+      - dependency-name: "ruamel-yaml"
+      - dependency-name: "sphinx-tabs"
+      - dependency-name: "sphinx-toolbox"
+      - dependency-name: "standard-imghdr"
     labels:
       - "dependencies"
       - "ci"

.github/skills/commenting-c-and-python/SKILL.md

@@ -60,19 +60,29 @@ typedef struct boc_message {
 
 ### Inline Comments — `//` Style
 
-Use `//` for short explanatory comments inside function bodies. Place them on
-the line **above** the code they describe, at the current indentation level:
+**An inline comment defaults to a single line of at most 120
+characters, or it is deleted.** Verbose multi-line inline comments rot
+as the code beneath them changes and make the code harder to read, not
+easier. Place the comment on the line **above** the code it describes,
+at the current indentation level:
 
 ```c
-  // two possibilities:
-  // 1. queue is empty
-  // 2. queue is inconsistent
-
-  // step 1: swap the new node in as the new head
+  // swap the new node in as the new head
   node->next = head;
 ```
 
-End-of-line `//` comments are reserved for preprocessor version annotations:
+A multi-line `//` inline comment is permitted **only** when it records
+something the code cannot express and that does not fit on one line:
+a non-obvious concurrency invariant (2PL lock ordering, MCS handoff,
+memory-ordering rationale), the rationale above a version-gate
+`#if`/`#elif` ladder, an X-macro / `clang-format off` table boundary,
+or a reference anchor that needs a line of context. When in doubt,
+collapse to one line. (Doxygen `///` / `/** */` doc-blocks are
+documentation, not inline comments, and are exempt from this rule —
+they may carry in-depth prose.)
+
+End-of-line `//` comments are reserved for preprocessor version
+annotations:
 
 ```c
 #if PY_VERSION_HEX >= 0x030E0000 // 3.14
@@ -249,19 +259,26 @@ def send(tag: str, contents: Any):
 
 ### Inline `#` Comments
 
-Use `#` comments for short notes inside function bodies. Place them on the line
-above the code, at the current indentation:
+**An inline comment defaults to a single line of at most 120
+characters, or it is deleted.** Verbose multi-line inline comments rot
+as the surrounding code changes and reduce readability. Place the
+comment on the line above the code, at the current indentation:
 
 ```python
         orphan_cowns = _core.cowns()
         if len(orphan_cowns) != 0:
             logger.debug("acquiring orphan cowns")
-            # at this stage all behaviors have exited, but it may be the case
-            # that some cowns are released but associated with this interpreter.
-            # by acquiring them, we ensure that the XIData objects have been
-            # freed _before_ this interpreter is destroyed.
+            # acquire orphaned cowns so their XIData is freed before teardown
 ```
 
+A multi-line `#` inline comment is permitted **only** when it records
+something the code cannot express and that does not fit on one line:
+a non-obvious concurrency invariant, a behavior-changing transpiler
+rule, the rationale above a version gate, or a reference anchor that
+needs context. When in doubt, collapse to one line. Docstrings are
+*not* inline comments and are exempt — they should carry in-depth,
+useful documentation across as many lines as the reader needs.
+
 Same-line `#` comments are acceptable for very short annotations:
 
 ```python