Carry the shared tooling fixes: tag filter, encodings, python3 shim, workflow permissions

Byte-identical with the sibling repos: gen-llms-txt.py strips sloppy comment closes
(`--!>`) and unterminated openers instead of only well-formed `<!-- -->` (CodeQL
bad-tag-filter; --check proves the generated output is byte-identical); every text-mode
open()/read_text()/write_text() names encoding="utf-8" so the remediation commands the
guards print survive a Windows console; doc-lint.sh resolves python3 to python where only
the latter exists; doc-lint.yml declares contents: read. CHANGELOG rolls [Unreleased]
into [3.0.0].

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: mbelhadi

.github/workflows/doc-lint.yml

@@ -71,6 +71,12 @@ on:
       # can invalidate hundreds of citations. Without this the guard never fires on it.
       - 'src/**'
 
+
+# Least privilege. Nothing in this workflow writes to the repository, so nothing
+# in it needs a token that can.
+permissions:
+  contents: read
+
 concurrency:
   group: doc-lint-${{ github.ref }}
   cancel-in-progress: true

CHANGELOG.md

@@ -7,6 +7,11 @@ All notable changes to the qbm-http module are documented here. The format is ba
 
 ## [Unreleased]
 
+Nothing yet. Entries land here as they are merged, and move under a version heading when that
+version is tagged.
+
+## [3.0.0] - 2026-08-20
+
 Tracks changes not yet part of a tagged release. Since 2026-08-11 that is **both** branches:
 `main` was fast-forwarded to `develop` for the release, so the module version is **3.0.0** on either,
 in lockstep with the qb framework; see the qb CHANGELOG for what makes that release major.
@@ -229,5 +234,6 @@ Aligns qbm-http with the qb 2.0 framework and hardens the HTTP/2, HTTP/3, WebSoc
   pending-request queue.
 - Reject control characters in quoted header-attribute values.
 
-[Unreleased]: https://github.com/isndev/qbm-http/compare/v2.6.0...HEAD
+[Unreleased]: https://github.com/isndev/qbm-http/compare/v3.0.0...HEAD
+[3.0.0]: https://github.com/isndev/qbm-http/compare/v2.6.0...v3.0.0
 [2.6.0]: https://github.com/isndev/qbm-http/releases/tag/v2.6.0

scripts/__pycache__/cite-check.cpython-314.pyc

@@ -92,13 +92,13 @@
 def project_prefix(root):
     """This project's prefix in repo-root-form paths, or None if it is none of the four."""
     try:
-        with open(os.path.join(root, "cmake", "qbConfig.cmake"), errors="ignore") as fh:
+        with open(os.path.join(root, "cmake", "qbConfig.cmake"), errors="ignore", encoding="utf-8") as fh:
             if re.search(r'^\s*set\(QB_FRAMEWORK_NAME\s+"qb"\)', fh.read(), re.M):
                 return "qb/"
     except OSError:
         pass
     try:
-        with open(os.path.join(root, "CMakeLists.txt"), errors="ignore") as fh:
+        with open(os.path.join(root, "CMakeLists.txt"), errors="ignore", encoding="utf-8") as fh:
             m = re.search(r"^\s*project\(\s*qbm-([A-Za-z0-9_]+)\b", fh.read(), re.M)
     except OSError:
         m = None

scripts/__pycache__/gen-llms-txt.cpython-314.pyc

@@ -15,6 +15,11 @@
 # Usage:  ./scripts/doc-lint.sh   (from the qbm-http root)
 #
 set -uo pipefail
+# `python3` is not a given on Windows hosts (the launcher is `py`, the binary `python`);
+# resolve it once so a direct invocation of this script works everywhere verify.sh's shim
+# is not wrapping it. A no-op wherever python3 exists.
+command -v python3 >/dev/null 2>&1 || python3() { python "$@"; }
+
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
 cd "${ROOT}" || exit 2

scripts/__pycache__/llm-guard.cpython-314.pyc

@@ -94,13 +94,13 @@
 def project_prefix(root):
     """This project's prefix in repo-root-form paths, or None if it is none of the four."""
     try:
-        with open(os.path.join(root, "cmake", "qbConfig.cmake"), errors="ignore") as fh:
+        with open(os.path.join(root, "cmake", "qbConfig.cmake"), errors="ignore", encoding="utf-8") as fh:
             if re.search(r'^\s*set\(QB_FRAMEWORK_NAME\s+"qb"\)', fh.read(), re.M):
                 return "qb/"
     except OSError:
         pass
     try:
-        with open(os.path.join(root, "CMakeLists.txt"), errors="ignore") as fh:
+        with open(os.path.join(root, "CMakeLists.txt"), errors="ignore", encoding="utf-8") as fh:
             m = re.search(r"^\s*project\(\s*qbm-([A-Za-z0-9_]+)\b", fh.read(), re.M)
     except OSError:
         m = None
@@ -199,7 +199,13 @@ def note_of(rel: str) -> str:
             if para:
                 break
             continue
-        para.append(re.sub(r"<!--.*?-->", "", s).strip())
+        # Strip HTML comments defensively, not just the well-formed shape. `<!--.*?-->` alone
+        # leaves two things behind that CodeQL's bad-tag-filter rightly flags: the sloppy
+        # close `--!>` that browsers accept, and an opener with no close on the line, which
+        # would pass the whole comment body through into the published lead verbatim.
+        cleaned = re.sub(r"<!--.*?(?:-->|--!>)", "", s)
+        cleaned = re.sub(r"<!--.*$", "", cleaned)
+        para.append(cleaned.strip())
     # Join the WHOLE paragraph before looking for a sentence end.  Reading only the first
     # physical line truncated every hard-wrapped lead ("... libraries of the"), which is how
     # a generated index ends up quoting half-sentences at an agent.

scripts/cite-check.py

@@ -187,13 +187,13 @@ def relpath(path: str) -> str:
 def project_prefix(root):
     """This project's prefix in repo-root-form paths, or None if it is none of the four."""
     try:
-        with open(os.path.join(root, "cmake", "qbConfig.cmake"), errors="ignore") as fh:
+        with open(os.path.join(root, "cmake", "qbConfig.cmake"), errors="ignore", encoding="utf-8") as fh:
             if re.search(r'^\s*set\(QB_FRAMEWORK_NAME\s+"qb"\)', fh.read(), re.M):
                 return "qb/"
     except OSError:
         pass
     try:
-        with open(os.path.join(root, "CMakeLists.txt"), errors="ignore") as fh:
+        with open(os.path.join(root, "CMakeLists.txt"), errors="ignore", encoding="utf-8") as fh:
             m = re.search(r"^\s*project\(\s*qbm-([A-Za-z0-9_]+)\b", fh.read(), re.M)
     except OSError:
         m = None
@@ -343,7 +343,7 @@ def expected_version():
         p, rx = os.path.join(ROOT, "CMakeLists.txt"), \
             r'^\s*project\(' + re.escape(PROJECT) + r'\s+VERSION\s+([0-9][0-9.]*)\)'
     try:
-        with open(p, errors="ignore") as fh:
+        with open(p, errors="ignore", encoding="utf-8") as fh:
             m = re.search(rx, fh.read(), re.M)
     except OSError:
         m = None
@@ -415,7 +415,7 @@ def __init__(self):
                 if not idents_ok or fn in SKIP_IDENT_FILES:
                     continue
                 try:
-                    with open(p, errors="ignore") as fh:
+                    with open(p, errors="ignore", encoding="utf-8") as fh:
                         self.idents.update(re.findall(r"[A-Za-z_][A-Za-z0-9_]*", fh.read()))
                 except OSError:
                     pass
@@ -463,7 +463,7 @@ def resolve_dir(self, spec: str):
     def lines(self, path):
         if path not in self._lines:
             try:
-                with open(path, errors="ignore") as fh:
+                with open(path, errors="ignore", encoding="utf-8") as fh:
                     self._lines[path] = fh.read().split("\n")
             except OSError:
                 self._lines[path] = None
@@ -484,7 +484,7 @@ def iter_docs():
 def check_doc(path, idx, tol, max_occ, want_ver, ver_src,
               findings, stats, suppressions, digests):
     rel = relpath(path)
-    with open(path) as fh:
+    with open(path, encoding="utf-8") as fh:
         lines = fh.read().split("\n")
 
     # ---- 5. Verified-against marker, BY VALUE --------------------------------
@@ -814,7 +814,7 @@ def main() -> int:
 
     accepted = {}
     if not a.no_baseline and os.path.isfile(a.baseline):
-        with open(a.baseline) as fh:
+        with open(a.baseline, encoding="utf-8") as fh:
             for raw in fh:
                 raw = raw.rstrip("\n")
                 if not raw.strip() or raw.lstrip().startswith("#"):
@@ -851,7 +851,7 @@ def main() -> int:
                   f"(expected >= {min_dig}); the parser has stopped matching the corpus and "
                   f"recording now would erase the baseline")
             return 1
-        with open(a.digest_baseline, "w") as fh:
+        with open(a.digest_baseline, "w", encoding="utf-8") as fh:
             fh.write(
                 "# llm-cite-digest.baseline -- what every line-cited range in llm/ SAID when\n"
                 "# it was last verified.  Regenerate with:\n"
@@ -876,7 +876,7 @@ def main() -> int:
     # -- rule 2b: the cited lines must still say what they said -------------------
     recorded = {}
     if os.path.isfile(a.digest_baseline):
-        with open(a.digest_baseline) as fh:
+        with open(a.digest_baseline, encoding="utf-8") as fh:
             for raw in fh:
                 if not raw.strip() or raw.lstrip().startswith("#"):
                     continue