From cd2911f3a69a80a6e8db99206fc1eeefcfec2c67 Mon Sep 17 00:00:00 2001
From: lusoris <lusoris@proton.me>
Date: Tue, 10 Nov 2026 14:40:01 +0100
Subject: [PATCH 1/7] ci(badges): draw the README status badges in one design

The README header mixed four badge designs: GitHub's workflow
badge.svg images, the Best Practices and Codacy service badges, a
static Scorecard image without the score, and a flat-square backends
row. GitHub's badge.svg cannot be restyled, so the ten status badges
are now drawn by the repository in the for-the-badge style.

The README Badges workflow runs every 15 minutes. readme_badges.py
reads the newest decisive push run of each badged workflow on master
and the public Scorecard, Best Practices and Codacy APIs; render.mjs
draws the SVGs with the pinned badge-maker; the publish job commits
them to the badges branch, signed by GitHub and never forced. A
failed source keeps its value for six hours, then reads stale, and
the run turns red. Requests go through the new ci_tier.https_json,
which refuses non-https URLs and caps each answer; api_request uses
it too and is now size-capped.

check-readme refuses any README image outside the one design and runs
as a pre-commit and pre-push hook; the Praetor governance badge is the
one exception until Praetor issue 1893 lands. ADR-3519 records the
design and why a schedule replaces workflow_run.

Signed-off-by: lusoris <lusoris@proton.me>
---
 .github/workflows/readme-badges.yml           | 109 +++
 .pre-commit-config.yaml                       |  16 +
 README.md                                     |  40 +-
 changelog.d/changed/readme-badges-uniform.md  |   5 +
 docs/README-STANDARD.md                       |  35 +-
 .../adr/3519-readme-badges-rendered-branch.md |  83 ++
 .../3519-readme-badges-rendered-branch.md     |   1 +
 docs/development/readme-badges.md             | 112 +++
 mkdocs.yml                                    |   1 +
 scripts/ci/AGENTS-gates.md                    |   1 +
 scripts/ci/AGENTS.d/readme-badges.md          |  24 +
 scripts/ci/ci_tier.py                         |  51 +-
 scripts/ci/readme_badges.py                   | 620 +++++++++++++++
 scripts/ci/tests/test_ci_tier.py              |  70 ++
 scripts/ci/tests/test_readme_badges.py        | 752 ++++++++++++++++++
 tools/badges/package-lock.json                |  87 ++
 tools/badges/package.json                     |  14 +
 tools/badges/render.mjs                       |  62 ++
 18 files changed, 2035 insertions(+), 48 deletions(-)
 create mode 100644 .github/workflows/readme-badges.yml
 create mode 100644 changelog.d/changed/readme-badges-uniform.md
 create mode 100644 docs/adr/3519-readme-badges-rendered-branch.md
 create mode 100644 docs/adr/_index_fragments/3519-readme-badges-rendered-branch.md
 create mode 100644 docs/development/readme-badges.md
 create mode 100644 scripts/ci/AGENTS.d/readme-badges.md
 create mode 100644 scripts/ci/readme_badges.py
 create mode 100644 scripts/ci/tests/test_readme_badges.py
 create mode 100644 tools/badges/package-lock.json
 create mode 100644 tools/badges/package.json
 create mode 100644 tools/badges/render.mjs

diff --git a/.github/workflows/readme-badges.yml b/.github/workflows/readme-badges.yml
new file mode 100644
index 0000000000..5447adfb0e
--- /dev/null
+++ b/.github/workflows/readme-badges.yml
@@ -0,0 +1,109 @@
+name: README Badges
+
+# Render the README status badges in one style (docs/development/readme-badges.md).
+# scripts/ci/readme_badges.py reads the latest decisive push run of every badged
+# workflow on master plus the OpenSSF Scorecard, OpenSSF Best Practices and
+# Codacy public APIs; tools/badges/render.mjs draws the SVGs with the pinned
+# shields.io renderer; the publish job commits them to the badges branch the
+# README links. A source that fails keeps its last value for six hours, then
+# reads "stale", and this run turns red so the failure is seen.
+
+on:
+  # Every 15 minutes: a badge lags a master run by at most that. A
+  # workflow_run trigger would be faster, but zizmor rates it a dangerous
+  # trigger, and its branch filter would also match a fork's branch named
+  # master.
+  schedule:
+    - cron: "7,22,37,52 * * * *"
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: readme-badges
+  cancel-in-progress: false
+
+jobs:
+  render:
+    name: Read the sources and render
+    # github.com only: the job reads and the publish job writes through the
+    # GitHub API, which a mirror's token cannot reach (as in supply-chain.yml).
+    if: github.repository == 'VMAFx/vmafx' && github.server_url == 'https://github.com'
+    runs-on: ubuntu-26.04
+    timeout-minutes: 10
+    permissions:
+      actions: read
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          ref: master
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
+        with:
+          python-version: "3.14.10"
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7.1.0
+        with:
+          node-version: "26.12.1"
+      - name: Install the pinned badge renderer
+        working-directory: tools/badges
+        run: npm ci --ignore-scripts --no-audit --no-fund
+      - name: Read the badge sources
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: >-
+          python3 scripts/ci/readme_badges.py spec
+          --spec build/badges-spec.json --state build/badges/state.json
+      - name: Render the SVGs
+        run: node tools/badges/render.mjs build/badges-spec.json build/badges
+      - if: ${{ env.GITEA_ACTIONS != 'true' }}
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7.0.2
+        with:
+          name: readme-badges
+          path: build/badges/
+          retention-days: 1
+          if-no-files-found: error
+      - name: Upload artifact (Gitea)
+        if: ${{ env.GITEA_ACTIONS == 'true' }}
+        uses: actions/upload-artifact@c6a366c94c3e0affe28c06c8df20a878f24da3cf  # v3.2.2
+        with:
+          name: readme-badges
+          path: build/badges/
+          retention-days: 1
+          if-no-files-found: error
+
+  publish:
+    name: Publish to the badges branch
+    needs: render
+    runs-on: ubuntu-26.04
+    timeout-minutes: 5
+    # contents: write is the narrowest token right that can create a commit;
+    # the job writes refs/heads/badges only, and the master ruleset refuses
+    # this token on master.
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          ref: master
+          persist-credentials: false
+      - if: ${{ env.GITEA_ACTIONS != 'true' }}
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333  # v8.0.2
+        with:
+          name: readme-badges
+          path: build/badges
+      - name: Download artifact (Gitea)
+        if: ${{ env.GITEA_ACTIONS == 'true' }}
+        uses: actions/download-artifact@a9bc5e6ef2cb54c177f32aa5726adaa15e7e2d59  # v3.1.0
+        with:
+          name: readme-badges
+          path: build/badges
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
+        with:
+          python-version: "3.14.10"
+      - name: Commit the badges
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: python3 scripts/ci/readme_badges.py publish --dir build/badges
+      - name: Fail the run when a source failed
+        run: python3 scripts/ci/readme_badges.py verdict --state build/badges/state.json
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index f7ee76802f..244af4319d 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -808,6 +808,22 @@ repos:
         files: '^(scripts/ci/(check-workflow-size\.py|tests/test_check_workflow_size\.py)|\.pre-commit-config\.yaml)$'
         pass_filenames: false
 
+      - id: readme-badge-design
+        name: Every README image keeps the one badge design (ADR-3519)
+        entry: python3 -B scripts/ci/readme_badges.py check-readme --readme README.md
+        language: system
+        files: '^(README\.md|scripts/ci/readme_badges\.py)$'
+        pass_filenames: false
+        stages: [pre-commit, pre-push]
+
+      - id: test-readme-badges
+        name: README badge renderer and design check keep positive, negative and boundary cases (ADR-3519)
+        entry: bash -c 'python3 -B scripts/ci/tests/test_readme_badges.py && python3 -B scripts/ci/tests/test_ci_tier.py'
+        language: system
+        files: '^(README\.md|scripts/ci/(readme_badges|ci_tier|tests/test_readme_badges|tests/test_ci_tier)\.py|tools/badges/.*|\.github/workflows/.*\.yml|\.pre-commit-config\.yaml)$'
+        pass_filenames: false
+        stages: [pre-commit, pre-push]
+
       - id: check-hosted-runner-labels
         name: Workflow jobs name an explicit hosted Ubuntu image, an older one only with a dated fallback
         entry: python3 scripts/ci/check_hosted_runner_labels.py
diff --git a/README.md b/README.md
index 662bab473b..4f2bdd28a3 100644
--- a/README.md
+++ b/README.md
@@ -11,17 +11,17 @@
   <!-- 1 release/version -->
   [![Release](https://img.shields.io/static/v1?label=release&message=v1.0.0-rc.3&style=for-the-badge&color=3b82f6&labelColor=111a35)](https://github.com/VMAFx/vmafx/releases) <!-- x-release-please-version -->
   <!-- 2 CI/build -->
-  [![Tests](https://github.com/VMAFx/vmafx/actions/workflows/tests-and-quality-gates.yml/badge.svg?branch=master&event=push)](https://github.com/VMAFx/vmafx/actions/workflows/tests-and-quality-gates.yml)
-  [![Builds](https://github.com/VMAFx/vmafx/actions/workflows/libvmaf-build-matrix.yml/badge.svg?branch=master&event=push)](https://github.com/VMAFx/vmafx/actions/workflows/libvmaf-build-matrix.yml)
-  [![Lint](https://github.com/VMAFx/vmafx/actions/workflows/lint-and-format.yml/badge.svg?branch=master&event=push)](https://github.com/VMAFx/vmafx/actions/workflows/lint-and-format.yml)
-  [![FFmpeg](https://github.com/VMAFx/vmafx/actions/workflows/ffmpeg-integration.yml/badge.svg?branch=master&event=push)](https://github.com/VMAFx/vmafx/actions/workflows/ffmpeg-integration.yml)
-  [![Go](https://github.com/VMAFx/vmafx/actions/workflows/go-ci.yml/badge.svg?branch=master&event=push)](https://github.com/VMAFx/vmafx/actions/workflows/go-ci.yml)
-  [![Rust](https://github.com/VMAFx/vmafx/actions/workflows/rust-ci.yml/badge.svg?branch=master&event=push)](https://github.com/VMAFx/vmafx/actions/workflows/rust-ci.yml)
+  [![Tests](https://raw.githubusercontent.com/VMAFx/vmafx/badges/tests.svg)](https://github.com/VMAFx/vmafx/actions/workflows/tests-and-quality-gates.yml)
+  [![Builds](https://raw.githubusercontent.com/VMAFx/vmafx/badges/builds.svg)](https://github.com/VMAFx/vmafx/actions/workflows/libvmaf-build-matrix.yml)
+  [![Lint](https://raw.githubusercontent.com/VMAFx/vmafx/badges/lint.svg)](https://github.com/VMAFx/vmafx/actions/workflows/lint-and-format.yml)
+  [![FFmpeg](https://raw.githubusercontent.com/VMAFx/vmafx/badges/ffmpeg.svg)](https://github.com/VMAFx/vmafx/actions/workflows/ffmpeg-integration.yml)
+  [![Go](https://raw.githubusercontent.com/VMAFx/vmafx/badges/go.svg)](https://github.com/VMAFx/vmafx/actions/workflows/go-ci.yml)
+  [![Rust](https://raw.githubusercontent.com/VMAFx/vmafx/badges/rust.svg)](https://github.com/VMAFx/vmafx/actions/workflows/rust-ci.yml)
   <!-- 3 security/scorecard -->
-  [![Security](https://github.com/VMAFx/vmafx/actions/workflows/security-scans.yml/badge.svg?branch=master&event=push)](https://github.com/VMAFx/vmafx/actions/workflows/security-scans.yml)
-  [![OpenSSF Scorecard](https://img.shields.io/badge/OpenSSF-Scorecard-06b6d4?style=for-the-badge&labelColor=111a35)](https://scorecard.dev/viewer/?uri=github.com/VMAFx/vmafx)
-  [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14549/badge)](https://www.bestpractices.dev/projects/14549)
-  [![Codacy](https://app.codacy.com/project/badge/Grade/ca74eb98b9b94cfc8d60d965b836b55d)](https://app.codacy.com/gh/VMAFx/vmafx/dashboard)
+  [![Security](https://raw.githubusercontent.com/VMAFx/vmafx/badges/security.svg)](https://github.com/VMAFx/vmafx/actions/workflows/security-scans.yml)
+  [![OpenSSF Scorecard](https://raw.githubusercontent.com/VMAFx/vmafx/badges/scorecard.svg)](https://scorecard.dev/viewer/?uri=github.com/VMAFx/vmafx)
+  [![OpenSSF Best Practices](https://raw.githubusercontent.com/VMAFx/vmafx/badges/best-practices.svg)](https://www.bestpractices.dev/projects/14549)
+  [![Codacy](https://raw.githubusercontent.com/VMAFx/vmafx/badges/codacy.svg)](https://app.codacy.com/gh/VMAFx/vmafx/dashboard)
   [![CodeRabbit](https://img.shields.io/badge/Reviews-CodeRabbit-8b5cf6?style=for-the-badge&logo=coderabbit&logoColor=white&labelColor=111a35)](https://coderabbit.ai)
   <!-- 4 standards -->
   [![HISS-21](https://img.shields.io/badge/Standards-HISS--21-06b6d4?style=for-the-badge&logo=nasa&labelColor=111a35)](AGENTS.md)
@@ -105,16 +105,16 @@ and output options. For compressed inputs such as MP4, use
 
 ## 🧩 Backends at a glance
 
-[![C23](https://img.shields.io/badge/C-23-3b82f6?style=flat-square&labelColor=111a35)](docs/principles.md)
-[![C++23](https://img.shields.io/badge/C%2B%2B-23-3b82f6?style=flat-square&labelColor=111a35)](docs/principles.md)
-[![Go](https://img.shields.io/badge/Go-1.27-06b6d4?style=flat-square&labelColor=111a35)](go.mod)
-[![Rust](https://img.shields.io/badge/Rust-2024-8b5cf6?style=flat-square&labelColor=111a35)](bindings/rust/vmafx-sys/Cargo.toml)
-[![Python](https://img.shields.io/badge/Python-3.14%2B-3b82f6?style=flat-square&labelColor=111a35)](pyproject.toml)
-[![CUDA](https://img.shields.io/badge/CUDA-13.4-06b6d4?style=flat-square&labelColor=111a35)](docs/backends/cuda/overview.md)
-[![ROCm](https://img.shields.io/badge/ROCm-10.1-06b6d4?style=flat-square&labelColor=111a35)](docs/backends/hip/overview.md)
-[![SYCL](https://img.shields.io/badge/SYCL-oneAPI-06b6d4?style=flat-square&labelColor=111a35)](docs/backends/sycl/overview.md)
-[![Metal](https://img.shields.io/badge/Metal-Apple_Silicon-06b6d4?style=flat-square&labelColor=111a35)](docs/backends/metal/index.md)
-[![FFmpeg](https://img.shields.io/badge/FFmpeg-n9.0.2-8b5cf6?style=flat-square&labelColor=111a35)](docs/usage/ffmpeg.md)
+[![C23](https://img.shields.io/badge/C-23-3b82f6?style=for-the-badge&labelColor=111a35)](docs/principles.md)
+[![C++23](https://img.shields.io/badge/C%2B%2B-23-3b82f6?style=for-the-badge&labelColor=111a35)](docs/principles.md)
+[![Go](https://img.shields.io/badge/Go-1.27-06b6d4?style=for-the-badge&labelColor=111a35)](go.mod)
+[![Rust](https://img.shields.io/badge/Rust-2024-8b5cf6?style=for-the-badge&labelColor=111a35)](bindings/rust/vmafx-sys/Cargo.toml)
+[![Python](https://img.shields.io/badge/Python-3.14%2B-3b82f6?style=for-the-badge&labelColor=111a35)](pyproject.toml)
+[![CUDA](https://img.shields.io/badge/CUDA-13.4-06b6d4?style=for-the-badge&labelColor=111a35)](docs/backends/cuda/overview.md)
+[![ROCm](https://img.shields.io/badge/ROCm-10.1-06b6d4?style=for-the-badge&labelColor=111a35)](docs/backends/hip/overview.md)
+[![SYCL](https://img.shields.io/badge/SYCL-oneAPI-06b6d4?style=for-the-badge&labelColor=111a35)](docs/backends/sycl/overview.md)
+[![Metal](https://img.shields.io/badge/Metal-Apple_Silicon-06b6d4?style=for-the-badge&labelColor=111a35)](docs/backends/metal/index.md)
+[![FFmpeg](https://img.shields.io/badge/FFmpeg-n9.0.2-8b5cf6?style=for-the-badge&labelColor=111a35)](docs/usage/ffmpeg.md)
 
 Every GPU-backed feature extractor has at least one device twin, and each twin
 is held to the CPU reference by the cross-backend parity gate. The coverage
diff --git a/changelog.d/changed/readme-badges-uniform.md b/changelog.d/changed/readme-badges-uniform.md
new file mode 100644
index 0000000000..177c50ad57
--- /dev/null
+++ b/changelog.d/changed/readme-badges-uniform.md
@@ -0,0 +1,5 @@
+- **Every README badge now has the same `for-the-badge` design, and the status badges come from this project's own render.**
+  `.github/workflows/readme-badges.yml` draws the seven workflow badges and the OpenSSF Scorecard,
+  OpenSSF Best Practices and Codacy badges every 15 minutes onto the `badges` branch: a workflow badge
+  shows the newest finished master push run, so a run in progress never hides a red one, and the
+  Scorecard badge now shows the score. See `docs/development/readme-badges.md` (ADR-3519).
diff --git a/docs/README-STANDARD.md b/docs/README-STANDARD.md
index 8e2cef2195..59b407710e 100644
--- a/docs/README-STANDARD.md
+++ b/docs/README-STANDARD.md
@@ -39,10 +39,11 @@ the VMAFx banner and documentation site.
 | `text` | `#e2e8f0` | light text on dark fills |
 | `muted` | `#94a3b8` | secondary text in the banner |
 
-The static badge messages use the three accent colours and set
-`labelColor=111a35` so the block reads as one band. Workflow-status badges are
-GitHub's own and keep its green, red or grey colour, because that colour is the
-status.
+Every badge uses `style=for-the-badge` and `labelColor=111a35`, so the page
+shows one badge design. Static badges take their message colour from the three
+accents. Status badges (workflow, Scorecard, Best Practices, Codacy) keep a
+status colour, because that colour is the status: green `#1f883d`, amber
+`#9a6700`, red `#cf222e`, grey `#6e7781` for unknown or stale.
 
 ## Hero banner
 
@@ -58,15 +59,15 @@ status.
 ## Badge block
 
 All badges at the top sit in one block directly under the banner, inside the
-centred header; static badges use `style=for-the-badge`. The groups always
+centred header; every badge uses `style=for-the-badge`. The groups always
 come in this order; a repository leaves out a group it has nothing for, but
 never reorders them:
 
 1. **Release / version**: the current release as a static badge that
    release-please keeps up to date (see "Badge sources").
-2. **CI / build**: one workflow-status badge per main workflow, with
-   `branch=<default>&event=push`. The badge label is the workflow name, so a
-   red badge points at the workflow of the same name.
+2. **CI / build**: one status badge per main workflow, showing its latest
+   decisive push run on the default branch. The badge label is the workflow
+   name, so a red badge points at the workflow of the same name.
 3. **Security / scorecard**: the security workflow, the OpenSSF Scorecard, the
    OpenSSF Best Practices level and the review bots that check every pull
    request (Codacy, CodeRabbit), where the project has them.
@@ -80,9 +81,16 @@ reviewer can check the order without rendering the page.
 
 Version badges for languages, toolchains, backends and integrations (C, Go,
 Rust, Python, CUDA, ROCm and the like) are not part of the top block. Where
-they help, they go in one compact row (`style=flat-square`) inside the section
-they describe; for VMAFx that is "Backends at a glance". No `for-the-badge`
-badge appears below the header.
+they help, they go in one row inside the section they describe, in the same
+`for-the-badge` style as the header; for VMAFx that is "Backends at a glance".
+
+One badge keeps another design: the governance badge inside the
+`praetor:readme-governance` block, which the Praetor tool writes and checks.
+That block is not edited by hand.
+
+`python3 scripts/ci/readme_badges.py check-readme` enforces the one design on
+every commit that touches `README.md`; see
+[README status badges](development/readme-badges.md#checks).
 
 A static badge is built from shields.io's path form,
 `https://img.shields.io/badge/<label>-<message>-<colour>`, where `-` inside a
@@ -101,11 +109,8 @@ that answers well inside that limit:
 
 | Badge | Source |
 | --- | --- |
-| Workflow status | GitHub's own `https://github.com/<owner>/<repo>/actions/workflows/<file>/badge.svg?branch=<default>&event=push`; GitHub serves it directly, not through the proxy. |
+| Workflow status, OpenSSF Scorecard, OpenSSF Best Practices, Codacy | An SVG on the `badges` branch, `https://raw.githubusercontent.com/<owner>/<repo>/badges/<slug>.svg`, linked to the workflow, the Scorecard viewer, the Best Practices project and the Codacy dashboard. The README Badges workflow reads the values and draws the SVGs with the pinned shields.io renderer; see [README status badges](development/readme-badges.md). GitHub's own workflow badge and the badges Best Practices and Codacy serve each have a design of their own, so they are not used. |
 | Release | A static shields.io badge in query form, `https://img.shields.io/static/v1?label=release&message=v<version>&...`, on a line that ends with `<!-- x-release-please-version -->`. `README.md` is a generic extra file in `release-please-config.json`, so each release PR rewrites the version, and `scripts/release/verify-release-version.sh` checks the marker against the tag. |
-| OpenSSF Best Practices | `https://www.bestpractices.dev/projects/<id>/badge`, served by the project itself. |
-| OpenSSF Scorecard | A static link badge to the Scorecard viewer. The score badge (`api.scorecard.dev/.../badge`) redirects to a computed shields.io badge and is too slow for the proxy. |
-| Codacy | The grade badge Codacy serves itself, `https://app.codacy.com/project/badge/Grade/<project token>`, linked to the repository dashboard; the token is `badges.grade` of `GET https://app.codacy.com/api/v3/organizations/gh/<owner>/repositories/<repo>`. |
 | CodeRabbit | A static link badge. shields.io's computed `coderabbit/prs` badge counts only part of the reviews (it showed 13 for VMAFx on 2026-11-01) and is not served from a cache. |
 
 Measure a new badge source before adding it: `curl -o /dev/null -w '%{time_total}'`
diff --git a/docs/adr/3519-readme-badges-rendered-branch.md b/docs/adr/3519-readme-badges-rendered-branch.md
new file mode 100644
index 0000000000..e651b3482d
--- /dev/null
+++ b/docs/adr/3519-readme-badges-rendered-branch.md
@@ -0,0 +1,83 @@
+<!-- markdownlint-disable MD013 MD041 MD060 -->
+# ADR-3519: Render the README status badges in one style onto a `badges` branch
+
+- **Status**: Accepted
+- **Date**: 2026-11-10
+- **Deciders**: Lusoris
+- **Tags**: `ci`, `docs`, `readme`, `supply-chain`
+
+## Context
+
+[ADR-3366](3366-readme-presentation-standard.md) puts one `for-the-badge`
+badge block under the README banner. The header still mixed four designs:
+the seven workflow badges were GitHub's own `badge.svg` images, which come in
+one fixed design; the Best Practices and Codacy badges came from their
+services in their own designs; the OpenSSF Scorecard badge was a static
+shields.io image that showed no score at all; and the backends row used
+`flat-square`. GitHub's `badge.svg` cannot be restyled, and the shields.io
+workflow badge reads that same image
+(`services/github/github-actions-workflow-status.service.js` in the shields
+repository, read 2026-11-10), so neither gives this project a say in which run
+a badge reports.
+
+## Decision
+
+We render the ten status badges ourselves.
+`.github/workflows/readme-badges.yml` runs every 15 minutes and on demand: its
+render job (`actions: read`, `contents: read`) runs
+`scripts/ci/readme_badges.py spec`, which reads the newest decisive push run of
+each badged workflow on the default branch and the public Scorecard, Best
+Practices and Codacy APIs, and `tools/badges/render.mjs` draws the SVGs with
+`badge-maker` 6.0.0, the shields.io renderer, pinned in
+`tools/badges/package-lock.json`. Its publish job (`contents: write`) commits
+the SVGs and `state.json` to the `badges` branch through the GitHub API, and
+the README links `https://raw.githubusercontent.com/VMAFx/vmafx/badges/<slug>.svg`.
+A source that fails keeps its last value for six hours, then reads `stale`,
+and the run turns red. Every other README badge, the backends row included,
+uses `for-the-badge`. The full rules are in
+[docs/development/readme-badges.md](../development/readme-badges.md).
+
+## Alternatives considered
+
+| Option | Pros | Cons | Why not chosen |
+|---|---|---|---|
+| Rendered badges on a `badges` branch, schedule trigger (chosen) | One design; the project decides which run a badge shows; Scorecard shows its score; no third-party request per page view | Up to 15 minutes of lag; a job with `contents: write`; a branch that grows by about one commit an hour | Chosen |
+| Same, triggered by `workflow_run` | Badge within a minute of a master run | zizmor rates `workflow_run` a dangerous trigger; its `branches: [master]` filter matches a fork's branch named `master` too | The 15-minute lag is the smaller cost |
+| shields.io dynamic URLs with `style=for-the-badge` | No workflow or branch; one design | Each page view depends on shields.io; the workflow badge scrapes GitHub's `badge.svg`, so run selection stays GitHub's; Scorecard and Codacy would need per-service shields routes | Keeps a third party on every page view and leaves run selection out of reach |
+| Keep each service's own badge | Nothing to build | Four designs in one block, against ADR-3366; the Scorecard badge shows no score | It is the defect this decision fixes |
+| Badges as GitHub Pages files | Same rendering | Pages deploys the documentation site; a second deploy path for ten files | The branch needs no Pages change |
+
+## Consequences
+
+- **Positive**: one badge design on the README; a run in progress or
+  cancelled never hides a red one; the Scorecard badge shows the score; a
+  failed source turns the run red the same day. `readme_badges.py
+  check-readme`, run as a pre-commit and pre-push hook, refuses any README
+  image outside the one design, so the mix cannot come back unnoticed.
+- **Negative**: the publish job holds `contents: write`, which GitHub cannot
+  limit to one branch. The script writes only `refs/heads/badges` and never
+  forces, and the master ruleset requires a pull request, so the token cannot
+  move `master`. An SVG cannot age by itself: if the workflow stops, the
+  badges keep their last values until someone sees the red or missing run.
+- **Neutral / follow-ups**: a ruleset for the `badges` branch in
+  `.github/repository-security-policy.json` (deletion and non-fast-forward
+  refused); the Praetor governance badge in the `praetor:readme-governance`
+  block keeps GitHub's design until Praetor offers the style (Praetor issue
+  1893), and `check-readme` then drops its one exception. This style is
+  the reference for the ecosystem README badge audit.
+
+## References
+
+- Controller answer `vmafx-readme-badge-style-r1` (2026-11-10, option b,
+  paraphrased): one `for-the-badge` design everywhere, a workflow rendering the
+  dynamic badges with a pinned `badge-maker` onto a `badges` branch with the
+  least rights, a stale marker after six hours; it answers the operator order
+  `vmafx-readme-badges-and-lint-red-20261110` (paraphrased: the README badge
+  row mixes designs).
+- [ADR-3366](3366-readme-presentation-standard.md): the README presentation
+  standard.
+- shields.io GitHub Actions workflow status service:
+  <https://github.com/badges/shields/blob/master/services/github/github-actions-workflow-status.service.js>.
+- `badge-maker` package: <https://www.npmjs.com/package/badge-maker>.
+- GitHub Actions `workflow_run` event:
+  <https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#workflow_run>.
diff --git a/docs/adr/_index_fragments/3519-readme-badges-rendered-branch.md b/docs/adr/_index_fragments/3519-readme-badges-rendered-branch.md
new file mode 100644
index 0000000000..fbff2ce75f
--- /dev/null
+++ b/docs/adr/_index_fragments/3519-readme-badges-rendered-branch.md
@@ -0,0 +1 @@
+| [ADR-3519](3519-readme-badges-rendered-branch.md) | The ten README status badges are rendered with the pinned shields.io renderer by `.github/workflows/readme-badges.yml` every 15 minutes onto the `badges` branch, from the newest decisive master push run of each workflow and the Scorecard, Best Practices and Codacy APIs; a failed source carries six hours then reads `stale`; every README badge uses `for-the-badge` | Accepted | ci, docs, readme, supply-chain |
diff --git a/docs/development/readme-badges.md b/docs/development/readme-badges.md
new file mode 100644
index 0000000000..4bea062370
--- /dev/null
+++ b/docs/development/readme-badges.md
@@ -0,0 +1,112 @@
+# README status badges
+
+The README header shows ten status badges: seven workflows (Tests, Builds,
+Lint, FFmpeg, Go, Rust, Security), the OpenSSF Scorecard score, the OpenSSF
+Best Practices level and the Codacy grade. They are SVG files on the `badges`
+branch, drawn in the same `for-the-badge` style as every other badge on the
+page ([README standard](../README-STANDARD.md#badge-block)). The README links
+each one with
+`https://raw.githubusercontent.com/VMAFx/vmafx/badges/<slug>.svg`.
+
+## Where a badge value comes from
+
+The README Badges workflow (`.github/workflows/readme-badges.yml`) runs every
+15 minutes, at minutes 7, 22, 37 and 52, and on demand:
+
+```bash
+gh workflow run readme-badges.yml -R VMAFx/vmafx
+```
+
+Its first job runs `scripts/ci/readme_badges.py spec`, which asks each source
+for the current value:
+
+| Badge | Source | Message and colour |
+| --- | --- | --- |
+| Tests, Builds, Lint, FFmpeg, Go, Rust, Security | GitHub API: the newest completed push run of the workflow on the default branch whose conclusion is `success`, `failure`, `timed_out` or `startup_failure`. Cancelled, skipped and waiting runs are passed over, so a run in progress never hides a red one. | `passing` green, `failing` red, `unknown` grey when none of the last 30 runs decided. |
+| OpenSSF Scorecard | `https://api.scorecard.dev/projects/github.com/VMAFx/vmafx` | the score with one decimal, `7.0 / 10`; green from 7.0, amber from 4.0, red below. The colour follows the shown value, so 6.96 reads `7.0 / 10` in green. |
+| OpenSSF Best Practices | `https://www.bestpractices.dev/projects.json?url=https://github.com/VMAFx/vmafx` | `in progress` amber, `passing`, `silver` or `gold` green. |
+| Codacy | `https://app.codacy.com/api/v3/analysis/organizations/gh/VMAFx/repositories/vmafx` | the grade letter; A and B green, C amber, D to F red. |
+
+Only the GitHub API call carries the workflow token. The three public
+sources get a plain request with no token.
+
+The workflow writes the list to `build/badges-spec.json`, and
+`tools/badges/render.mjs` draws one SVG per entry with `badge-maker`, the
+renderer shields.io uses, at the version pinned in
+`tools/badges/package-lock.json`. The renderer accepts only the four keys
+`slug`, `label`, `message` and `color`, printable ASCII text up to 40
+characters and a `#rrggbb` colour, so a source cannot put markup into the SVG.
+
+## When a source fails
+
+A source that times out or answers something unexpected keeps its last value
+for six hours. After that its badge reads `stale` in grey. Either way the run
+turns red at its last step (`readme_badges.py verdict`), so the failure shows
+in the Actions tab the same day, not when someone notices an old badge.
+
+The last values live in `state.json` on the `badges` branch, next to the SVGs,
+with the time each one was read.
+
+## How the badges branch is written
+
+The second job runs `scripts/ci/readme_badges.py publish`, which writes the
+ten SVGs and `state.json` as the whole tree of one new commit through the
+GitHub API:
+
+- GitHub signs the commit. A commit that comes back unverified is not
+  published, and the branch stays where it was.
+- The branch only moves forward (`force: false`).
+- When every SVG is unchanged and the last commit is less than an hour old,
+  nothing is committed, so the branch grows by about one commit an hour.
+- A commit made with the workflow token starts no other workflow.
+
+The job's token has `contents: write`, the narrowest right that can make a
+commit. GitHub cannot limit that right to one branch; the script writes only
+`refs/heads/badges`, and the master ruleset requires a pull request, so the
+token cannot move `master`.
+
+## Why a schedule and not `workflow_run`
+
+A `workflow_run` trigger would refresh a badge within a minute of each master
+run. zizmor rates `workflow_run` a dangerous trigger, and its
+`branches: [master]` filter matches the branch name only, so a pull request
+from a fork's branch named `master` would start it too. The schedule costs up
+to 15 minutes of lag and has neither problem.
+
+## Limits
+
+- An SVG cannot age by itself. When the workflow itself stops (disabled, or
+  scheduled runs paused after 60 days without repository activity), the
+  badges keep showing the last values. The red run and the README Badges
+  entry in the Actions tab are the signal.
+- The Praetor governance badge in the `praetor:readme-governance` block is
+  written by Praetor and keeps GitHub's design.
+
+## Checks
+
+```bash
+python3 scripts/ci/readme_badges.py check-readme --readme README.md
+python3 -m pytest scripts/ci/tests/test_readme_badges.py
+```
+
+`check-readme` fails when any image in the README breaks the one design. An
+image passes only when it is one of the rendered SVGs on the `badges` branch,
+a shields.io badge with both `style=for-the-badge` and `labelColor=111a35`, or
+a file inside the repository (the banner). Images inside code fences and code
+spans are ignored. The one exception is the Praetor governance badge inside
+the `praetor:readme-governance` block; it goes once Praetor can draw that
+badge in the same style (Praetor issue 1893). Each fault names the line:
+
+```text
+README.md:117: https://img.shields.io/badge/FFmpeg-n9.0.2-8b5cf6?style=flat-square&labelColor=111a35: a shields.io badge needs style=for-the-badge
+```
+
+The `readme-badge-design` pre-commit hook runs the check whenever `README.md`
+or the script changes, at commit and at push, and the `test-readme-badges`
+hook runs both test files.
+
+The tests cover every value rule above, the six-hour carry, the publish rules,
+the design check and the README itself: the badge order and alt texts in
+`README.md` must match `BADGES` in `scripts/ci/readme_badges.py`, each
+workflow badge's label must be that workflow's `name:`, and the text and
+colour patterns of `render.mjs` must equal the Python ones.
diff --git a/mkdocs.yml b/mkdocs.yml
index ecc466f167..a1944b4f59 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -545,6 +545,7 @@ nav:
       - PR body validator: development/pr-body-validator.md
       - mkdocs strict pre-push hook: development/pre-push-mkdocs-strict.md
       - Documentation site design: development/docs-site-design.md
+      - README status badges: development/readme-badges.md
       - Dev MCP container: development/dev-mcp.md
       - Kubernetes deployment: development/k8s-deployment.md
       - Operator: development/operator.md
diff --git a/scripts/ci/AGENTS-gates.md b/scripts/ci/AGENTS-gates.md
index 910504e03b..88b72afd68 100644
--- a/scripts/ci/AGENTS-gates.md
+++ b/scripts/ci/AGENTS-gates.md
@@ -35,6 +35,7 @@ file of this directory. `Touching` paths: relative to this directory, leading
 | `pr-diff-base.sh`, `classify-dependency-pr.sh`, `release-pr-exempt.sh`, `tests/test_pr_gates_merge_base.py` | [pr-diff-base](AGENTS.d/pr-diff-base.md) | PR gates diff from merge base of BASE_SHA and HEAD_SHA, never from BASE_SHA; no merge base -> fail closed. |
 | `/.pre-commit-config.yaml` | [pre-commit-hygiene](AGENTS.d/pre-commit-hygiene.md) | Third-party code enters through Meson wraps or `ffmpeg-patches/`, never a submodule; verify hook revision bumps. |
 | `precommit_scope.py`, `tests/test_precommit_scope.py`, `/.github/workflows/lint-and-format.yml` | [precommit-scope](AGENTS.d/precommit-scope.md) | PR Pre-Commit = diff only if no hook input changed; input change or unreadable diff -> whole tree. |
+| `readme_badges.py`, `tests/test_readme_badges.py`, `/tools/badges/*`, `/.github/workflows/readme-badges.yml`, `/README.md` | [readme-badges](AGENTS.d/readme-badges.md) | README badge order = `BADGES`; README images pass `check-readme`; publish moves `refs/heads/badges` only, unforced. |
 | `check-aggregator-names.sh`, `tests/test-check-aggregator-names.sh`, `required_aggregator_harness.py`, `test_go_workflow_contract.py`, `tests/test_required_release_legs.py`, `tests/test_aggregator_absent_fails.py` | [required-aggregator](AGENTS.d/required-aggregator.md) | `required` list = `# required-aggregator` markers; one reporter per required name; contract suites share one harness. |
 | `*research-digest-id*`, `tests/test_research_digest_ids.py`, `/docs/research/*.md` | [research-digest-ids](AGENTS.d/research-digest-ids.md) | New digest: unique numeric prefix + H1 `# Research-NNNN`; baseline debt only shrinks; no `--bootstrap-from-ref` in CI. |
 | `/REUSE.toml`, `tests/test_reuse_compliance.py`, `/.github/workflows/reuse.yml` | [reuse-provenance](AGENTS.d/reuse-provenance.md) | `reuse lint` green is not provenance: keep exact overrides for inherited, ported, no-CLA and FFmpeg-patch files. |
diff --git a/scripts/ci/AGENTS.d/readme-badges.md b/scripts/ci/AGENTS.d/readme-badges.md
new file mode 100644
index 0000000000..3966f59fdc
--- /dev/null
+++ b/scripts/ci/AGENTS.d/readme-badges.md
@@ -0,0 +1,24 @@
+---
+paths:
+  - scripts/ci/readme_badges.py
+  - scripts/ci/tests/test_readme_badges.py
+  - tools/badges/*
+  - .github/workflows/readme-badges.yml
+  - README.md
+invariant: README badge order = `BADGES`; README images pass `check-readme`; publish moves `refs/heads/badges` only, unforced.
+area: gates
+---
+<!-- markdownlint-disable MD013 MD060 -->
+# README status badges (ADR-3519)
+
+`scripts/ci/readme_badges.py` reads badge values; `tools/badges/render.mjs` draws SVGs; `.github/workflows/readme-badges.yml` publishes SVGs to `badges` branch. Human guide: `docs/development/readme-badges.md`.
+
+- Order + labels: README header badges, alt texts, order = `BADGES` tuple; workflow badge label = that workflow's `name:`. `test_readme_badges.py` reads `README.md`; new badge changes both.
+- Run choice: workflow badge = newest push run on default branch with conclusion `success`, `failure`, `timed_out` or `startup_failure`; cancelled, skipped, in-progress runs passed over. Never "latest run".
+- Renderer allow-list: keys `slug`, `label`, `message`, `color` only; text `[\x20-\x7e]{1,40}`; colour `#[0-9a-f]{6}`. `TEXT` / `COLOR` in Python and `render.mjs` stay equal (test compares both).
+- Carry: failed source keeps last value `STALE_AFTER` = 6 h from `state.json`, then `stale` grey; `verdict` step exits 1 on any failed source.
+- Publish: one commit via Git data API; GitHub-signed commit required (unverified -> no ref move); `force: false`; ref path only `refs/heads/badges`; no commit when SVGs unchanged and head < `QUIET_WINDOW` = 1 h old.
+- Tokens: `GITHUB_TOKEN` only to `api.github.com`; Scorecard, Best Practices, Codacy reads carry no token.
+- Requests: every call through `ci_tier.https_json` (https only, size cap: public `MAX_RESPONSE_BYTES`, GitHub API `ci_tier.API_MAX_BYTES`); no second request helper. JSON answers read with `field()`, never bare indexing.
+- Design check: `readme_badges.py check-readme` (hook `readme-badge-design`) fails README image unless rendered `badges`-branch SVG, shields.io badge with `style=for-the-badge` + `labelColor=111a35`, or repo-local file. Fences + code spans ignored. Only exception: `praetor-docs.yml/badge.svg` inside `praetor:readme-governance` block (`GOVERNANCE_BADGE`) until Praetor issue 1893 lands; then drop exception.
+- Rights: render job `actions: read` + `contents: read`; publish job `contents: write` only; workflow top level `permissions: {}`. No `workflow_run` trigger (zizmor dangerous trigger; fork branch named `master` matches).
diff --git a/scripts/ci/ci_tier.py b/scripts/ci/ci_tier.py
index 23f3740cb3..a9fd59338b 100644
--- a/scripts/ci/ci_tier.py
+++ b/scripts/ci/ci_tier.py
@@ -57,6 +57,7 @@
 DEFAULT_CONFIG = REPO_ROOT / ".github" / "ci-tier.json"
 EXEMPT_SCRIPT = REPO_ROOT / "scripts" / "ci" / "release-pr-exempt.sh"
 API_TIMEOUT_S = 30
+API_MAX_BYTES = 32 << 20  # a 100-entry API page is well under 1 MiB
 PAGE_SIZE = 100
 MAX_PAGES = 30
 PULL_REQUEST_EVENTS = frozenset({"pull_request", "pull_request_target"})
@@ -163,23 +164,47 @@ def decide(
     return Decision(LIGHT, "pull request from this repository")
 
 
-def api_request(method: str, url: str, token: str) -> object:
-    """One bounded GitHub API call; the only network access of the tier scripts."""
+def api_request(method: str, url: str, token: str, payload: object | None = None) -> object:
+    """One bounded GitHub API call; the only network access of the tier scripts.
+
+    ``payload`` goes out as the JSON request body; without one a POST sends
+    an empty body.
+    """
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+    data = b"" if method == "POST" else None
+    if payload is not None:
+        data = json.dumps(payload).encode("utf-8")
+        headers["Content-Type"] = "application/json"
+    return https_json(method, url, headers, data, API_TIMEOUT_S, API_MAX_BYTES)
+
+
+def https_json(
+    method: str,
+    url: str,
+    headers: Mapping[str, str],
+    data: bytes | None,
+    timeout_s: float,
+    limit: int,
+) -> object:
+    """One https request whose answer is JSON, bounded in time and in size.
+
+    The scheme check and the size cap live here so every caller gets them; an
+    empty answer reads as an empty object.
+    """
     if urllib.parse.urlsplit(url).scheme != "https":
         raise TierError(f"refusing a non-https API URL: {url}")
     request = urllib.request.Request(  # noqa: S310 - the scheme is checked above
-        url,
-        method=method,
-        data=b"" if method == "POST" else None,
-        headers={
-            "Authorization": f"Bearer {token}",
-            "Accept": "application/vnd.github+json",
-            "X-GitHub-Api-Version": "2022-11-28",
-        },
+        url, method=method, data=data, headers=dict(headers)
     )
-    with urllib.request.urlopen(request, timeout=API_TIMEOUT_S) as response:  # noqa: S310
-        body = response.read().decode("utf-8")
-    return json.loads(body) if body else {}
+    with urllib.request.urlopen(request, timeout=timeout_s) as response:  # noqa: S310
+        body = response.read(limit + 1)
+    if len(body) > limit:
+        raise TierError(f"{url}: answer larger than {limit} bytes")
+    return json.loads(body.decode("utf-8")) if body else {}
 
 
 def _paged(fetch: Fetcher, path: str) -> list[object]:
diff --git a/scripts/ci/readme_badges.py b/scripts/ci/readme_badges.py
new file mode 100644
index 0000000000..308d1408e3
--- /dev/null
+++ b/scripts/ci/readme_badges.py
@@ -0,0 +1,620 @@
+#!/usr/bin/env python3
+# Copyright 2026 Lusoris
+# SPDX-License-Identifier: EUPL-1.2
+"""Read, publish and judge the README status badges (docs/development/readme-badges.md).
+
+    readme_badges.py spec --spec SPEC.json --state DIR/state.json
+        Read every badge source and write the render list for
+        tools/badges/render.mjs plus the state file. Exit 0 once both exist.
+    readme_badges.py publish --dir DIR
+        Commit DIR/<slug>.svg and DIR/state.json to the badges branch.
+    readme_badges.py verdict --state DIR/state.json
+        Exit 1 when a source failed this run, so the run turns red.
+    readme_badges.py check-readme [--readme README.md]
+        Exit 1 when a README image is not a rendered badge, a shields.io
+        badge in for-the-badge with the dark label, or a local image.
+        Offline; pre-commit runs it on every README change.
+
+Sources: the latest decisive completed push run of each workflow on the
+default branch (GitHub API with GITHUB_TOKEN), and the OpenSSF Scorecard
+score, OpenSSF Best Practices level and Codacy grade (public APIs, sent no
+token). A source that fails keeps its last value for six hours; after that
+the badge reads "stale". The repository comes from GITHUB_REPOSITORY.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import functools
+import hashlib
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.parse
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from http import HTTPStatus
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
+
+from scripts.ci import ci_tier
+
+API = "https://api.github.com"
+BRANCH = "badges"
+STATE = "state.json"
+STALE_AFTER = timedelta(hours=6)
+QUIET_WINDOW = timedelta(hours=1)
+RUNS_PER_PAGE = 30
+PUBLIC_TIMEOUT_S = 20
+MAX_RESPONSE_BYTES = 1 << 20
+MAX_FILE_BYTES = 64 << 10
+
+GREEN = "#1f883d"
+RED = "#cf222e"
+AMBER = "#9a6700"
+GREY = "#6e7781"
+SCORE_MAX = 10  # OpenSSF Scorecard scores run from 0 to 10
+SCORE_GREEN = 7.0  # shown score from which the badge is green
+SCORE_AMBER = 4.0  # shown score from which it is amber; red below
+TEXT = re.compile(r"[\x20-\x7e]{1,40}")
+COLOR = re.compile(r"#[0-9a-f]{6}")
+
+PASSING = ("passing", GREEN)
+FAILING = ("failing", RED)
+DECISIVE = {
+    "success": PASSING,
+    "failure": FAILING,
+    "timed_out": FAILING,
+    "startup_failure": FAILING,
+}
+BEST_PRACTICES = {
+    "in_progress": ("in progress", AMBER),
+    "passing": PASSING,
+    "silver": ("silver", GREEN),
+    "gold": ("gold", GREEN),
+}
+CODACY = {"A": GREEN, "B": GREEN, "C": AMBER, "D": RED, "E": RED, "F": RED}
+
+Value = tuple[str, str]
+GitHub = Callable[[str], object]
+Public = Callable[[str], object]
+Call = Callable[[str, str, object | None], object]
+
+
+class BadgeError(Exception):
+    """A badge source answered something the renderer cannot show."""
+
+
+@dataclass(frozen=True)
+class Badge:
+    """One README badge: its file name, label and where its value comes from."""
+
+    slug: str
+    label: str
+    kind: str
+    workflow: str = ""
+
+
+BADGES = (
+    Badge("tests", "Tests", "workflow", "tests-and-quality-gates.yml"),
+    Badge("builds", "Builds", "workflow", "libvmaf-build-matrix.yml"),
+    Badge("lint", "Lint", "workflow", "lint-and-format.yml"),
+    Badge("ffmpeg", "FFmpeg", "workflow", "ffmpeg-integration.yml"),
+    Badge("go", "Go", "workflow", "go-ci.yml"),
+    Badge("rust", "Rust", "workflow", "rust-ci.yml"),
+    Badge("security", "Security", "workflow", "security-scans.yml"),
+    Badge("scorecard", "OpenSSF Scorecard", "scorecard"),
+    Badge("best-practices", "OpenSSF Best Practices", "best-practices"),
+    Badge("codacy", "Codacy", "codacy"),
+)
+
+
+def stamp(moment: datetime) -> str:
+    """UTC time as the state file stores it."""
+    return moment.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def workflow_value(runs: object) -> Value:
+    """Value of the newest run that passed or failed; cancelled and skipped runs do not count."""
+    rows = runs.get("workflow_runs") if isinstance(runs, dict) else None
+    if not isinstance(rows, list):
+        raise BadgeError("the runs answer has no workflow_runs list")
+    for row in rows:
+        conclusion = row.get("conclusion") if isinstance(row, dict) else None
+        if conclusion in DECISIVE:
+            return DECISIVE[conclusion]
+    return ("unknown", GREY)
+
+
+def scorecard_value(doc: object) -> Value:
+    """OpenSSF Scorecard score out of 10: green from 7, amber from 4, red below.
+
+    The colour follows the shown one-decimal score, so 6.96 reads "7.0" in green.
+    """
+    score = doc.get("score") if isinstance(doc, dict) else None
+    if isinstance(score, bool) or not isinstance(score, int | float) or not 0 <= score <= SCORE_MAX:
+        raise BadgeError(f"Scorecard score {score!r} is not a number from 0 to 10")
+    shown = round(float(score), 1)
+    color = GREEN if shown >= SCORE_GREEN else AMBER if shown >= SCORE_AMBER else RED
+    return (f"{shown:.1f} / 10", color)
+
+
+def best_practices_value(rows: object, repo_url: str) -> Value:
+    """Badge level of the Best Practices project registered for ``repo_url``."""
+    matches = (
+        [r for r in rows if isinstance(r, dict) and r.get("repo_url") == repo_url]
+        if isinstance(rows, list)
+        else []
+    )
+    if len(matches) != 1:
+        raise BadgeError(f"{len(matches)} Best Practices projects list {repo_url}")
+    level = matches[0].get("badge_level")
+    if level not in BEST_PRACTICES:
+        raise BadgeError(f"Best Practices level {level!r} is not one this badge knows")
+    return BEST_PRACTICES[level]
+
+
+def codacy_value(doc: object) -> Value:
+    """Codacy grade letter: A and B green, C amber, D to F red."""
+    data = doc.get("data") if isinstance(doc, dict) else None
+    letter = data.get("gradeLetter") if isinstance(data, dict) else None
+    if letter not in CODACY:
+        raise BadgeError(f"Codacy grade {letter!r} is not a letter from A to F")
+    return (str(letter), CODACY[letter])
+
+
+def default_branch(github: GitHub, repository: str) -> str:
+    """Name of the repository's default branch, whose push runs the workflow badges show."""
+    doc = github(f"/repos/{repository}")
+    branch = doc.get("default_branch") if isinstance(doc, dict) else None
+    if not isinstance(branch, str) or not branch:
+        raise BadgeError(f"{repository}: the API names no default branch")
+    return branch
+
+
+def read_value(badge: Badge, repository: str, github: GitHub, public: Public) -> Value:
+    """Ask the badge's source for its current value."""
+    if badge.kind == "workflow":
+        branch = default_branch(github, repository)
+        query = urllib.parse.urlencode(
+            {"branch": branch, "event": "push", "status": "completed", "per_page": RUNS_PER_PAGE}
+        )
+        return workflow_value(
+            github(f"/repos/{repository}/actions/workflows/{badge.workflow}/runs?{query}")
+        )
+    owner, name = repository.split("/", 1)
+    if badge.kind == "scorecard":
+        return scorecard_value(
+            public(f"https://api.scorecard.dev/projects/github.com/{repository}")
+        )
+    if badge.kind == "best-practices":
+        repo_url = f"https://github.com/{repository}"
+        query = urllib.parse.urlencode({"url": repo_url})
+        return best_practices_value(
+            public(f"https://www.bestpractices.dev/projects.json?{query}"), repo_url
+        )
+    if badge.kind == "codacy":
+        path = f"organizations/gh/{owner}/repositories/{name}"
+        return codacy_value(public(f"https://app.codacy.com/api/v3/analysis/{path}"))
+    raise BadgeError(f"{badge.slug}: unknown source kind {badge.kind!r}")
+
+
+def usable(entry: object) -> dict[str, str | None] | None:
+    """A previous state entry when its shape is one this script writes, else ``None``."""
+    if not isinstance(entry, dict):
+        return None
+    message, color, fetched = entry.get("message"), entry.get("color"), entry.get("fetched_at")
+    if not (isinstance(message, str) and TEXT.fullmatch(message)):
+        return None
+    if not (isinstance(color, str) and COLOR.fullmatch(color)):
+        return None
+    if fetched is not None and not isinstance(fetched, str):
+        return None
+    return {"message": message, "color": color, "fetched_at": fetched}
+
+
+def carried(previous: Mapping[str, str | None] | None, now: datetime) -> dict[str, str | None]:
+    """Keep the last value up to STALE_AFTER after it was read; then show "stale"."""
+    fetched = previous.get("fetched_at") if previous else None
+    if previous and fetched:
+        try:
+            age = now - datetime.fromisoformat(fetched)
+        except ValueError:
+            age = None
+        if age is not None and timedelta(0) <= age <= STALE_AFTER:
+            return dict(previous)
+    return {"message": "stale", "color": GREY, "fetched_at": fetched}
+
+
+def refresh(
+    badges: tuple[Badge, ...],
+    previous: Mapping[str, object],
+    now: datetime,
+    read: Callable[[Badge], Value],
+) -> tuple[dict[str, dict[str, str | None]], list[str]]:
+    """New state entries for every badge, and one line per source that failed."""
+    entries: dict[str, dict[str, str | None]] = {}
+    failures: list[str] = []
+    for badge in badges:
+        try:
+            message, color = read(badge)
+        except (BadgeError, ci_tier.TierError, OSError, ValueError, KeyError, TypeError) as error:
+            entries[badge.slug] = carried(usable(previous.get(badge.slug)), now)
+            failures.append(f"{badge.slug}: {error}")
+            continue
+        entries[badge.slug] = {"message": message, "color": color, "fetched_at": stamp(now)}
+    return entries, failures
+
+
+def render_list(
+    badges: tuple[Badge, ...], entries: Mapping[str, Mapping[str, str | None]]
+) -> list[dict[str, str]]:
+    """The list tools/badges/render.mjs takes, in README order."""
+    return [
+        {
+            "slug": b.slug,
+            "label": b.label,
+            "message": str(entries[b.slug]["message"]),
+            "color": str(entries[b.slug]["color"]),
+        }
+        for b in badges
+    ]
+
+
+def public_json(url: str) -> object:
+    """GET a public JSON API without credentials; https only, bounded in time and size."""
+    return ci_tier.https_json(
+        "GET", url, {"Accept": "application/json"}, None, PUBLIC_TIMEOUT_S, MAX_RESPONSE_BYTES
+    )
+
+
+def field(doc: object, *keys: str) -> object:
+    """``doc[key][key]...`` of a JSON answer; BadgeError when a level is missing or no object."""
+    value = doc
+    for key in keys:
+        if not isinstance(value, dict) or key not in value:
+            raise BadgeError(f"the answer has no {'.'.join(keys)}")
+        value = value[key]
+    return value
+
+
+def previous_state(github: GitHub, repository: str) -> tuple[dict[str, object], str | None]:
+    """Badge entries of the badges branch's state file; none when the branch is new."""
+    try:
+        doc = github(f"/repos/{repository}/contents/{STATE}?ref={BRANCH}")
+    except urllib.error.HTTPError as error:
+        error.close()  # it holds the answer body; a 404 or a carried failure ends here
+        if error.code == HTTPStatus.NOT_FOUND:
+            return {}, None
+        return {}, f"{STATE}: {error}"
+    except (ci_tier.TierError, OSError, ValueError) as error:
+        return {}, f"{STATE}: {error}"
+    try:
+        text = base64.b64decode(str(field(doc, "content"))).decode("utf-8")
+        badges = json.loads(text).get("badges")
+    except (BadgeError, TypeError, ValueError, AttributeError) as error:
+        return {}, f"{STATE}: unreadable ({error})"
+    return (badges if isinstance(badges, dict) else {}), None
+
+
+def blob_sha(data: bytes) -> str:
+    """Git object id of a blob holding ``data``."""
+    return hashlib.sha1(b"blob %d\x00" % len(data) + data, usedforsecurity=False).hexdigest()
+
+
+def collect(directory: Path, badges: tuple[Badge, ...]) -> dict[str, bytes]:
+    """The files to publish: exactly one SVG per badge plus the state file, nothing else."""
+    wanted = {f"{b.slug}.svg" for b in badges} | {STATE}
+    found = {p.name for p in directory.iterdir()}
+    if found != wanted:
+        raise BadgeError(
+            f"{directory}: missing {sorted(wanted - found)}, unexpected {sorted(found - wanted)}"
+        )
+    files: dict[str, bytes] = {}
+    for name in sorted(wanted):
+        path = directory / name
+        if path.is_symlink() or not path.is_file() or path.stat().st_size > MAX_FILE_BYTES:
+            raise BadgeError(f"{path}: not a regular file of at most {MAX_FILE_BYTES} bytes")
+        data = path.read_bytes()
+        text = data.decode("utf-8")
+        if name == STATE:
+            json.loads(text)
+        elif not text.startswith("<svg "):
+            raise BadgeError(f"{path}: not an SVG document")
+        files[name] = data
+    return files
+
+
+def branch_head(call: Call, repository: str) -> dict[str, str] | None:
+    """Commit id, tree id and commit time of the badges branch; ``None`` when it does not exist."""
+    try:
+        ref = call("GET", f"/repos/{repository}/git/ref/heads/{BRANCH}", None)
+    except urllib.error.HTTPError as error:
+        if error.code == HTTPStatus.NOT_FOUND:
+            error.close()  # it holds the answer body; the caller never sees this one
+            return None
+        raise
+    sha = str(field(ref, "object", "sha"))
+    commit = call("GET", f"/repos/{repository}/git/commits/{sha}", None)
+    return {
+        "sha": sha,
+        "tree": str(field(commit, "tree", "sha")),
+        "date": str(field(commit, "committer", "date")),
+    }
+
+
+def unchanged(
+    call: Call, repository: str, head: Mapping[str, str], files: Mapping[str, bytes], now: datetime
+) -> bool:
+    """True when every SVG matches the branch and its last commit is younger than QUIET_WINDOW."""
+    if now - datetime.fromisoformat(head["date"]) >= QUIET_WINDOW:
+        return False
+    rows = field(call("GET", f"/repos/{repository}/git/trees/{head['tree']}", None), "tree")
+    if not isinstance(rows, list):
+        raise BadgeError("the tree answer has no tree list")
+    current = {str(field(e, "path")): str(field(e, "sha")) for e in rows}
+    if set(current) != set(files):
+        return False
+    return all(current[name] == blob_sha(data) for name, data in files.items() if name != STATE)
+
+
+def publish(call: Call, repository: str, files: Mapping[str, bytes], now: datetime) -> str:
+    """Commit ``files`` as the whole badges tree; GitHub signs the commit, the ref moves only forward."""
+    head = branch_head(call, repository)
+    if head and unchanged(call, repository, head, files, now):
+        return f"unchanged at {head['sha']}"
+    entries = [
+        {"path": name, "mode": "100644", "type": "blob", "content": data.decode("utf-8")}
+        for name, data in sorted(files.items())
+    ]
+    tree = call("POST", f"/repos/{repository}/git/trees", {"tree": entries})
+    message = f"chore(badges): render the README badges at {stamp(now)}"
+    parents = [head["sha"]] if head else []
+    payload = {"message": message, "tree": field(tree, "sha"), "parents": parents}
+    commit = call("POST", f"/repos/{repository}/git/commits", payload)
+    sha = str(field(commit, "sha"))
+    verification = commit.get("verification") if isinstance(commit, dict) else None
+    if not isinstance(verification, dict) or verification.get("verified") is not True:
+        raise BadgeError(f"commit {sha} is not signed by GitHub; the branch stays put")
+    if head:
+        call("PATCH", f"/repos/{repository}/git/refs/heads/{BRANCH}", {"sha": sha, "force": False})
+    else:
+        call("POST", f"/repos/{repository}/git/refs", {"ref": f"refs/heads/{BRANCH}", "sha": sha})
+    return sha
+
+
+# The one README badge design, as an allow-list: a badge rendered onto the
+# badges branch, a shields.io badge in for-the-badge with the dark label, or a
+# local image. Anything else, a reference-style image whose address this check
+# cannot see included, is a fault. The Praetor-managed governance block may
+# also hold its own GitHub workflow badge until Praetor issue 1893 offers the
+# style; then GOVERNANCE_BADGE goes.
+FENCE = re.compile(r"^(?P<mark>`{3,}|~{3,})[^\n]*\n.*?^(?P=mark)[ \t]*$", re.M | re.S)
+CODE_SPAN = re.compile(r"`[^`\n]+`")
+MANAGED_BLOCK = re.compile(
+    r"<!-- praetor:readme-governance:start -->.*?<!-- praetor:readme-governance:end -->", re.S
+)
+IMAGE_START = re.compile(r"!\[")
+INLINE_IMAGE = re.compile(r'!\[[^\]\n]*\]\((?P<url>[^)\s]+)(?:[ \t]+"[^"\n]*")?\)')
+REFERENCE_IMAGE = re.compile(r"!\[(?P<alt>[^\]\n]*)\](?:\[(?P<ref>[^\]\n]*)\])?")
+REFERENCE_DEF = re.compile(r"^ {0,3}\[(?P<ref>[^\]\n]+)\]:[ \t]*<?(?P<url>[^\s>]+)>?", re.M)
+HTML_IMAGE = re.compile(r"<(?:img|source)\b[^>]*>", re.I)
+HTML_SOURCE = re.compile(r'\b(?:src|srcset)[ \t]*=[ \t]*"(?P<url>[^"]*)"', re.I)
+RENDERED = re.compile(
+    r"https://raw\.githubusercontent\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+/"
+    + re.escape(BRANCH)
+    + r"/(?P<slug>[a-z0-9-]+)\.svg"
+)
+LOCAL_IMAGE = re.compile(r"[A-Za-z0-9_][A-Za-z0-9_./-]*")
+GOVERNANCE_BADGE = re.compile(
+    r"https://github\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+/actions/workflows/praetor-docs\.yml/badge\.svg"
+)
+SHIELDS_HOST = "img.shields.io"
+SHIELDS_DESIGN = {"style": "for-the-badge", "labelColor": "111a35"}
+
+
+def blanked(match: re.Match[str]) -> str:
+    """The matched text as spaces, newlines kept, so positions and line numbers stay."""
+    return re.sub(r"[^\n]", " ", match[0])
+
+
+def local_image(url: str) -> bool:
+    """True for a relative path inside the repository: no scheme, no leading slash, no ``..``."""
+    return LOCAL_IMAGE.fullmatch(url) is not None and ".." not in url.split("/")
+
+
+def image_fault(url: str) -> str | None:
+    """Why the image at ``url`` breaks the one badge design; ``None`` when it keeps it."""
+    rendered = RENDERED.fullmatch(url)
+    if rendered:
+        if rendered["slug"] in {badge.slug for badge in BADGES}:
+            return None
+        return f"{url}: no rendered badge is named {rendered['slug']!r}"
+    parts = urllib.parse.urlsplit(url)
+    if parts.scheme == "https" and parts.netloc == SHIELDS_HOST:
+        query = urllib.parse.parse_qs(parts.query, keep_blank_values=True)
+        wrong = [
+            f"{key}={value}" for key, value in SHIELDS_DESIGN.items() if query.get(key) != [value]
+        ]
+        return f"{url}: a shields.io badge needs {' and '.join(wrong)}" if wrong else None
+    if local_image(url):
+        return None
+    return f"{url}: not a rendered badge, a for-the-badge shields.io badge or a local image"
+
+
+def image_url(text: str, start: int, refs: Mapping[str, str]) -> str | None:
+    """Address of the Markdown image at ``start``; ``None`` when it names no known reference."""
+    inline = INLINE_IMAGE.match(text, start)
+    if inline:
+        return inline["url"]
+    reference = REFERENCE_IMAGE.match(text, start)
+    if reference is None:
+        return None
+    key = reference["ref"] or reference["alt"]
+    return refs.get(key.strip().lower())
+
+
+def markdown_faults(
+    text: str, span: tuple[int, int], refs: Mapping[str, str], extra: re.Pattern[str] | None
+) -> list[str]:
+    """One line per Markdown image in ``text[span]`` that breaks the design; ``extra`` also passes."""
+    faults: list[str] = []
+    for found in IMAGE_START.finditer(text, *span):
+        line = text.count("\n", 0, found.start()) + 1
+        url = image_url(text, found.start(), refs)
+        if url is None:
+            faults.append(f"{line}: an image without an inline address this check can read")
+        elif not (extra and extra.fullmatch(url)) and (fault := image_fault(url)):
+            faults.append(f"{line}: {fault}")
+    return faults
+
+
+def html_faults(text: str) -> list[str]:
+    """One line per HTML ``<img>`` or ``<source>`` that shows anything but a local image."""
+    faults: list[str] = []
+    for tag in HTML_IMAGE.finditer(text):
+        line = text.count("\n", 0, tag.start()) + 1
+        urls = [
+            candidate.split()[0]
+            for source in HTML_SOURCE.finditer(tag[0])
+            for candidate in source["url"].split(",")
+            if candidate.strip()
+        ]
+        if not urls:
+            faults.append(f"{line}: an HTML image without a double-quoted src or srcset")
+        faults += [
+            f"{line}: {url}: an HTML image must be a local file"
+            for url in urls
+            if not local_image(url)
+        ]
+    return faults
+
+
+def design_faults(readme: str) -> list[str]:
+    """Every image in ``readme`` that breaks the one badge design, as ``line: reason``."""
+    text = CODE_SPAN.sub(blanked, FENCE.sub(blanked, readme))
+    faults: list[str] = []
+    for block in MANAGED_BLOCK.finditer(text):
+        refs = {
+            d["ref"].strip().lower(): d["url"]
+            for d in REFERENCE_DEF.finditer(text, block.start(), block.end())
+        }
+        faults += markdown_faults(text, block.span(), refs, GOVERNANCE_BADGE)
+    outside = MANAGED_BLOCK.sub(blanked, text)
+    faults += markdown_faults(outside, (0, len(outside)), {}, None)
+    faults += html_faults(text)
+    return sorted(faults, key=lambda fault: int(fault.split(":", 1)[0]))
+
+
+def cmd_check_readme(args: argparse.Namespace) -> int:
+    faults = design_faults(args.readme.read_text(encoding="utf-8"))
+    for fault in faults:
+        print(f"{args.readme}:{fault}", file=sys.stderr)
+    if faults:
+        print(
+            f"{len(faults)} README images break the one badge design (docs/development/readme-badges.md)",
+            file=sys.stderr,
+        )
+        return 1
+    print(f"{args.readme}: every badge has the one design")
+    return 0
+
+
+def write_json(path: Path, doc: object) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(doc, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def cmd_spec(args: argparse.Namespace, env: Mapping[str, str], now: datetime) -> int:
+    repository, token = env["GITHUB_REPOSITORY"], env["GITHUB_TOKEN"]
+
+    @functools.cache
+    def github(path: str) -> object:
+        return ci_tier.api_request("GET", API + path, token)
+
+    previous, problem = previous_state(github, repository)
+    entries, failures = refresh(
+        BADGES, previous, now, lambda b: read_value(b, repository, github, public_json)
+    )
+    failures = ([problem] if problem else []) + failures
+    write_json(args.spec, render_list(BADGES, entries))
+    write_json(
+        args.state,
+        {"version": 1, "generated_at": stamp(now), "failures": failures, "badges": entries},
+    )
+    for line in failures:
+        print(f"::warning title=Badge source failed::{line}")
+    print(
+        f"{len(BADGES) - len(failures)} of {len(BADGES)} badge sources read; state in {args.state}"
+    )
+    return 0
+
+
+def cmd_publish(args: argparse.Namespace, env: Mapping[str, str], now: datetime) -> int:
+    repository, token = env["GITHUB_REPOSITORY"], env["GITHUB_TOKEN"]
+
+    def call(method: str, path: str, payload: object | None) -> object:
+        return ci_tier.api_request(method, API + path, token, payload)
+
+    print(f"{BRANCH}: {publish(call, repository, collect(args.dir, BADGES), now)}")
+    return 0
+
+
+def cmd_verdict(args: argparse.Namespace) -> int:
+    failures = json.loads(args.state.read_text(encoding="utf-8")).get("failures")
+    if not isinstance(failures, list):
+        raise BadgeError(f"{args.state}: no failures list")
+    for line in failures:
+        print(f"::error title=Badge source failed::{line}")
+    if failures:
+        print(
+            f"{len(failures)} badge sources failed; the badges keep their last value up to {STALE_AFTER}"
+        )
+        return 1
+    print("every badge source answered")
+    return 0
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    spec = sub.add_parser("spec", help="read the sources, write the render list and state")
+    spec.add_argument("--spec", type=Path, required=True)
+    spec.add_argument("--state", type=Path, required=True)
+    pub = sub.add_parser("publish", help="commit the rendered badges to the badges branch")
+    pub.add_argument("--dir", type=Path, required=True)
+    verdict = sub.add_parser("verdict", help="fail when a source failed this run")
+    verdict.add_argument("--state", type=Path, required=True)
+    check = sub.add_parser("check-readme", help="fail when a README image breaks the badge design")
+    check.add_argument("--readme", type=Path, default=Path("README.md"))
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None, env: Mapping[str, str] | None = None) -> int:
+    args = parse_args(sys.argv[1:] if argv is None else argv)
+    env = os.environ if env is None else env
+    now = datetime.now(UTC)
+    try:
+        if args.command == "verdict":
+            return cmd_verdict(args)
+        if args.command == "check-readme":
+            return cmd_check_readme(args)
+        missing = [k for k in ("GITHUB_REPOSITORY", "GITHUB_TOKEN") if not env.get(k)]
+        if missing:
+            raise BadgeError(f"set {', '.join(missing)}")
+        handler = cmd_spec if args.command == "spec" else cmd_publish
+        return handler(args, env, now)
+    except (BadgeError, ci_tier.TierError, OSError, ValueError, KeyError, TypeError) as error:
+        print(f"readme_badges.py {args.command}: {error}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/ci/tests/test_ci_tier.py b/scripts/ci/tests/test_ci_tier.py
index b1d838368a..118e8267c9 100644
--- a/scripts/ci/tests/test_ci_tier.py
+++ b/scripts/ci/tests/test_ci_tier.py
@@ -11,8 +11,10 @@
 import sys
 import tempfile
 import unittest
+import urllib.request
 from contextlib import redirect_stderr, redirect_stdout
 from pathlib import Path
+from typing import Any
 from unittest import mock
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[3]))
@@ -156,6 +158,74 @@ def test_a_non_https_url_is_refused(self) -> None:
             with self.subTest(url=url), self.assertRaises(ci_tier.TierError):
                 ci_tier.api_request("GET", url, "t")
 
+    def sent(
+        self, method: str, payload: object | None = None, answer: bytes = b"{}"
+    ) -> tuple[urllib.request.Request, Any]:
+        """The request api_request hands to urlopen, and what it returned."""
+        opened = mock.MagicMock()
+        opened.__enter__.return_value.read.return_value = answer
+        with mock.patch.object(urllib.request, "urlopen", return_value=opened) as urlopen:
+            result = ci_tier.api_request(method, "https://api.github.com/x", "t", payload)
+        return urlopen.call_args.args[0], result
+
+    def test_a_payload_goes_out_as_a_json_body(self) -> None:
+        request, _ = self.sent("PATCH", {"sha": "c1", "force": False})
+        data = request.data
+        if not isinstance(data, bytes):
+            self.fail(f"request body is {type(data).__name__}, not bytes")
+        self.assertEqual(json.loads(data), {"sha": "c1", "force": False})
+        self.assertEqual(request.get_header("Content-type"), "application/json")
+        self.assertEqual(request.get_method(), "PATCH")
+
+    def test_a_post_without_payload_sends_an_empty_body(self) -> None:
+        request, _ = self.sent("POST")
+        self.assertEqual(request.data, b"")
+        self.assertIsNone(request.get_header("Content-type"))
+
+    def test_a_get_sends_no_body(self) -> None:
+        request, _ = self.sent("GET")
+        self.assertIsNone(request.data)
+        self.assertEqual(request.get_header("Authorization"), "Bearer t")
+
+    def test_an_empty_answer_reads_as_an_empty_object(self) -> None:
+        self.assertEqual(self.sent("GET", answer=b"")[1], {})
+
+
+class HttpsJson(unittest.TestCase):
+    def answer(
+        self, body: bytes, limit: int, headers: dict[str, str] | None = None
+    ) -> tuple[Any, Any, Any]:
+        """https_json's result for ``body`` and the request and read size it used."""
+        opened = mock.MagicMock()
+        opened.__enter__.return_value.read.return_value = body
+        with mock.patch.object(urllib.request, "urlopen", return_value=opened) as urlopen:
+            result = ci_tier.https_json("GET", "https://h/x", headers or {}, None, 5, limit)
+        read = opened.__enter__.return_value.read
+        return result, urlopen.call_args, read.call_args
+
+    def test_an_answer_of_exactly_the_limit_is_read(self) -> None:
+        result, opened, read = self.answer(b'{"a":1}', 7)
+        self.assertEqual(result, {"a": 1})
+        self.assertEqual(read.args, (8,))
+        self.assertEqual(opened.kwargs["timeout"], 5)
+
+    def test_an_answer_one_byte_over_the_limit_is_refused(self) -> None:
+        with self.assertRaisesRegex(ci_tier.TierError, "larger than 6 bytes"):
+            self.answer(b'{"a":1}', 6)
+
+    def test_the_caller_headers_go_out_and_nothing_else(self) -> None:
+        _, opened, _ = self.answer(b"{}", 10, {"Accept": "application/json"})
+        request = opened.args[0]
+        self.assertEqual(request.get_header("Accept"), "application/json")
+        self.assertIsNone(request.get_header("Authorization"))
+
+    def test_a_non_https_url_is_refused_before_any_request(self) -> None:
+        with mock.patch.object(urllib.request, "urlopen") as urlopen:
+            for url in ("http://h/x", "file:///etc/passwd"):
+                with self.subTest(url=url), self.assertRaises(ci_tier.TierError):
+                    ci_tier.https_json("GET", url, {}, None, 5, 10)
+        urlopen.assert_not_called()
+
 
 class Config(unittest.TestCase):
     def write(self, text: str) -> Path:
diff --git a/scripts/ci/tests/test_readme_badges.py b/scripts/ci/tests/test_readme_badges.py
new file mode 100644
index 0000000000..6d04b89eb3
--- /dev/null
+++ b/scripts/ci/tests/test_readme_badges.py
@@ -0,0 +1,752 @@
+#!/usr/bin/env python3
+# Copyright 2026 Lusoris
+# SPDX-License-Identifier: EUPL-1.2
+"""Positive, negative and boundary cases for scripts/ci/readme_badges.py."""
+
+from __future__ import annotations
+
+import base64
+import email.message
+import io
+import json
+import re
+import sys
+import tempfile
+import unittest
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from contextlib import redirect_stderr, redirect_stdout
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any, ClassVar
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[3]))
+
+from scripts.ci import ci_tier
+from scripts.ci import readme_badges as rb
+
+ROOT = Path(__file__).resolve().parents[3]
+NOW = datetime(2026, 11, 10, 12, 0, tzinfo=UTC)
+REPO = "VMAFx/vmafx"
+RAW = re.compile(
+    r"\[!\[(?P<alt>[^\]]+)\]\(https://raw\.githubusercontent\.com/VMAFx/vmafx/badges/"
+    r"(?P<slug>[a-z0-9-]+)\.svg\)\]"
+)
+
+
+def runs(*conclusions: object) -> dict[str, object]:
+    return {"workflow_runs": [{"conclusion": c} for c in conclusions]}
+
+
+def http_error(code: int) -> urllib.error.HTTPError:
+    return urllib.error.HTTPError(
+        "https://api.github.com/x", code, "x", email.message.Message(), None
+    )
+
+
+def entry(
+    message: str = "passing", color: str = rb.GREEN, fetched: str | None = None
+) -> dict[str, str | None]:
+    return {"message": message, "color": color, "fetched_at": fetched or rb.stamp(NOW)}
+
+
+class WorkflowValue(unittest.TestCase):
+    def test_success_is_passing(self) -> None:
+        self.assertEqual(rb.workflow_value(runs("success")), rb.PASSING)
+
+    def test_every_failing_conclusion_is_failing(self) -> None:
+        for conclusion in ("failure", "timed_out", "startup_failure"):
+            with self.subTest(conclusion=conclusion):
+                self.assertEqual(rb.workflow_value(runs(conclusion, "success")), rb.FAILING)
+
+    def test_an_unfinished_or_cancelled_run_does_not_mask_a_failure(self) -> None:
+        # Planted case of the red-reader miss: the newest run had no conclusion yet.
+        answer = runs(None, "cancelled", "skipped", "action_required", "failure", "success")
+        self.assertEqual(rb.workflow_value(answer), rb.FAILING)
+
+    def test_no_decisive_run_is_unknown(self) -> None:
+        self.assertEqual(rb.workflow_value(runs()), ("unknown", rb.GREY))
+        self.assertEqual(rb.workflow_value(runs("cancelled", None)), ("unknown", rb.GREY))
+
+    def test_a_row_that_is_not_an_object_is_skipped(self) -> None:
+        answer = {"workflow_runs": ["x", 3, {"conclusion": "success"}]}
+        self.assertEqual(rb.workflow_value(answer), rb.PASSING)
+
+    def test_an_answer_without_a_run_list_is_refused(self) -> None:
+        answers: tuple[object, ...] = ({}, [], None, {"workflow_runs": {}})
+        for answer in answers:
+            with self.subTest(answer=answer), self.assertRaises(rb.BadgeError):
+                rb.workflow_value(answer)
+
+
+class ScorecardValue(unittest.TestCase):
+    def test_colour_boundaries(self) -> None:
+        cases = {
+            10: ("10.0 / 10", rb.GREEN),
+            7.0: ("7.0 / 10", rb.GREEN),
+            6.96: ("7.0 / 10", rb.GREEN),
+            6.9: ("6.9 / 10", rb.AMBER),
+            4: ("4.0 / 10", rb.AMBER),
+            3.9: ("3.9 / 10", rb.RED),
+            0: ("0.0 / 10", rb.RED),
+        }
+        for score, want in cases.items():
+            with self.subTest(score=score):
+                self.assertEqual(rb.scorecard_value({"score": score}), want)
+
+    def test_a_score_outside_zero_to_ten_or_not_a_number_is_refused(self) -> None:
+        for score in (True, False, "8.9", None, -0.1, 10.01, float("nan"), float("inf")):
+            with self.subTest(score=score), self.assertRaises(rb.BadgeError):
+                rb.scorecard_value({"score": score})
+
+    def test_an_answer_that_is_not_an_object_is_refused(self) -> None:
+        with self.assertRaises(rb.BadgeError):
+            rb.scorecard_value([8.9])
+
+
+class BestPracticesValue(unittest.TestCase):
+    URL = "https://github.com/VMAFx/vmafx"
+
+    def rows(self, *levels: str) -> list[dict[str, str]]:
+        return [{"repo_url": self.URL, "badge_level": level} for level in levels]
+
+    def test_every_known_level(self) -> None:
+        for level, want in rb.BEST_PRACTICES.items():
+            with self.subTest(level=level):
+                self.assertEqual(rb.best_practices_value(self.rows(level), self.URL), want)
+
+    def test_exactly_one_project_must_list_the_repository(self) -> None:
+        other = [{"repo_url": "https://github.com/Netflix/vmaf", "badge_level": "passing"}]
+        for rows in ([], other, self.rows("passing", "gold"), {"repo_url": self.URL}, None):
+            with self.subTest(rows=rows), self.assertRaises(rb.BadgeError):
+                rb.best_practices_value(rows, self.URL)
+
+    def test_an_unknown_level_is_refused(self) -> None:
+        for level in ("platinum", None, ""):
+            with self.subTest(level=level), self.assertRaises(rb.BadgeError):
+                rb.best_practices_value([{"repo_url": self.URL, "badge_level": level}], self.URL)
+
+
+class CodacyValue(unittest.TestCase):
+    def test_every_grade_letter(self) -> None:
+        for letter, color in rb.CODACY.items():
+            with self.subTest(letter=letter):
+                want = (letter, color)
+                self.assertEqual(rb.codacy_value({"data": {"gradeLetter": letter}}), want)
+        self.assertEqual(rb.CODACY["B"], rb.GREEN)
+        self.assertEqual(rb.CODACY["C"], rb.AMBER)
+        self.assertEqual(rb.CODACY["D"], rb.RED)
+
+    def test_anything_but_a_letter_from_a_to_f_is_refused(self) -> None:
+        docs: tuple[object, ...] = (
+            {"data": {"gradeLetter": "G"}},
+            {"data": {"gradeLetter": "a"}},
+            {"data": {}},
+            {},
+            [],
+        )
+        for doc in docs:
+            with self.subTest(doc=doc), self.assertRaises(rb.BadgeError):
+                rb.codacy_value(doc)
+
+
+class ReadValue(unittest.TestCase):
+    def github(self, paths: list[str], branch: object = "master") -> rb.GitHub:
+        def fetch(path: str) -> object:
+            paths.append(path)
+            return {"default_branch": branch} if path == f"/repos/{REPO}" else runs("success")
+
+        return fetch
+
+    def test_a_workflow_badge_reads_completed_push_runs_on_the_default_branch(self) -> None:
+        paths: list[str] = []
+        badge = rb.Badge("lint", "Lint", "workflow", "lint-and-format.yml")
+        value = rb.read_value(badge, REPO, self.github(paths), self.fail)
+        self.assertEqual(value, rb.PASSING)
+        query = paths[1].split("?", 1)[1]
+        self.assertIn("/actions/workflows/lint-and-format.yml/runs?", paths[1])
+        self.assertEqual(query, "branch=master&event=push&status=completed&per_page=30")
+
+    def test_a_repository_without_a_default_branch_is_refused(self) -> None:
+        badge = rb.Badge("lint", "Lint", "workflow", "lint-and-format.yml")
+        for branch in ("", None, 3):
+            with self.subTest(branch=branch), self.assertRaises(rb.BadgeError):
+                rb.read_value(badge, REPO, self.github([], branch), lambda url: {})
+
+    def test_public_sources_get_their_own_urls_and_no_github_call(self) -> None:
+        answers = {
+            "https://api.scorecard.dev/projects/github.com/VMAFx/vmafx": {"score": 8.9},
+            "https://www.bestpractices.dev/projects.json?url=https%3A%2F%2Fgithub.com%2FVMAFx%2Fvmafx": [
+                {"repo_url": "https://github.com/VMAFx/vmafx", "badge_level": "passing"}
+            ],
+            "https://app.codacy.com/api/v3/analysis/organizations/gh/VMAFx/repositories/vmafx": {
+                "data": {"gradeLetter": "A"}
+            },
+        }
+        public = answers.__getitem__
+        for badge in rb.BADGES:
+            if badge.kind != "workflow":
+                with self.subTest(badge=badge.slug):
+                    rb.read_value(badge, REPO, self.fail, public)
+
+    def test_an_unknown_kind_is_refused(self) -> None:
+        with self.assertRaises(rb.BadgeError):
+            rb.read_value(rb.Badge("x", "X", "rss"), REPO, lambda p: {}, lambda u: {})
+
+
+class Usable(unittest.TestCase):
+    def test_an_entry_this_script_writes_is_usable(self) -> None:
+        self.assertEqual(rb.usable(entry()), entry())
+        self.assertEqual(
+            rb.usable({"message": "x" * 40, "color": rb.RED}),
+            {"message": "x" * 40, "color": rb.RED, "fetched_at": None},
+        )
+
+    def test_a_malformed_entry_is_not(self) -> None:
+        for bad in (
+            entry(message=""),
+            entry(message="x" * 41),
+            entry(message="café"),
+            entry(color="red"),
+            entry(color="#1F883D"),
+            {**entry(), "fetched_at": 3},
+            "passing",
+            None,
+        ):
+            with self.subTest(bad=bad):
+                self.assertIsNone(rb.usable(bad))
+
+
+class Carried(unittest.TestCase):
+    def test_a_value_is_kept_up_to_exactly_six_hours(self) -> None:
+        fetched = rb.stamp(NOW - rb.STALE_AFTER)
+        self.assertEqual(rb.carried(entry(fetched=fetched), NOW)["message"], "passing")
+
+    def test_one_second_past_six_hours_reads_stale(self) -> None:
+        fetched = rb.stamp(NOW - rb.STALE_AFTER - timedelta(seconds=1))
+        got = rb.carried(entry(fetched=fetched), NOW)
+        self.assertEqual(got, {"message": "stale", "color": rb.GREY, "fetched_at": fetched})
+
+    def test_a_future_or_unreadable_time_reads_stale(self) -> None:
+        for fetched in (rb.stamp(NOW + timedelta(seconds=1)), "yesterday"):
+            with self.subTest(fetched=fetched):
+                self.assertEqual(rb.carried(entry(fetched=fetched), NOW)["message"], "stale")
+
+    def test_no_previous_value_reads_stale(self) -> None:
+        self.assertEqual(rb.carried(None, NOW)["message"], "stale")
+        self.assertEqual(
+            rb.carried({"message": "passing", "fetched_at": None}, NOW)["message"], "stale"
+        )
+
+
+class Refresh(unittest.TestCase):
+    BADGE = (rb.Badge("go", "Go", "workflow", "go-ci.yml"),)
+
+    def test_a_source_that_answers_gets_a_new_time(self) -> None:
+        entries, failures = rb.refresh(self.BADGE, {}, NOW, lambda b: rb.FAILING)
+        self.assertEqual(
+            entries["go"], {"message": "failing", "color": rb.RED, "fetched_at": rb.stamp(NOW)}
+        )
+        self.assertEqual(failures, [])
+
+    def test_a_failing_source_keeps_its_last_value_and_is_reported(self) -> None:
+        previous = {"go": entry(fetched=rb.stamp(NOW - timedelta(hours=1)))}
+        for error in (
+            rb.BadgeError("b"),
+            OSError("o"),
+            ValueError("v"),
+            KeyError("k"),
+            TypeError("t"),
+            ci_tier.TierError("too large"),
+        ):
+            with self.subTest(error=type(error).__name__):
+
+                def read(badge: rb.Badge, error: Exception = error) -> rb.Value:
+                    raise error
+
+                entries, failures = rb.refresh(self.BADGE, previous, NOW, read)
+                self.assertEqual(entries["go"]["message"], "passing")
+                self.assertEqual(len(failures), 1)
+                self.assertTrue(failures[0].startswith("go: "))
+
+    def test_an_unexpected_error_is_not_swallowed(self) -> None:
+        def read(badge: rb.Badge) -> rb.Value:
+            raise RuntimeError("bug")
+
+        with self.assertRaises(RuntimeError):
+            rb.refresh(self.BADGE, {}, NOW, read)
+
+    def test_the_render_list_keeps_readme_order(self) -> None:
+        entries = {b.slug: entry() for b in rb.BADGES}
+        rendered = rb.render_list(rb.BADGES, entries)
+        self.assertEqual([r["slug"] for r in rendered], [b.slug for b in rb.BADGES])
+        self.assertEqual(set(rendered[0]), {"slug", "label", "message", "color"})
+
+
+class PreviousState(unittest.TestCase):
+    def fetch(self, answer: object) -> rb.GitHub:
+        def github(path: str) -> object:
+            self.assertEqual(path, f"/repos/{REPO}/contents/state.json?ref=badges")
+            if isinstance(answer, Exception):
+                raise answer
+            return answer
+
+        return github
+
+    def test_a_new_branch_has_no_state_and_no_problem(self) -> None:
+        self.assertEqual(rb.previous_state(self.fetch(http_error(404)), REPO), ({}, None))
+
+    def test_a_handled_error_is_closed(self) -> None:
+        for code in (404, 500):
+            with self.subTest(code=code):
+                error = http_error(code)
+                rb.previous_state(self.fetch(error), REPO)
+                self.assertTrue(error.fp.closed)
+
+    def test_the_badges_of_the_state_file_are_read(self) -> None:
+        text = json.dumps({"badges": {"go": entry()}}).encode()
+        doc = {"content": base64.b64encode(text).decode()}
+        self.assertEqual(rb.previous_state(self.fetch(doc), REPO), ({"go": entry()}, None))
+
+    def test_an_unreadable_state_is_a_problem_not_a_crash(self) -> None:
+        unreadable = (http_error(500), OSError("down"), ci_tier.TierError("too large"))
+        for answer in (*unreadable, {}, {"content": "!!"}, {"content": ""}, {"content": 7}):
+            with self.subTest(answer=answer):
+                badges, problem = rb.previous_state(self.fetch(answer), REPO)
+                self.assertEqual(badges, {})
+                self.assertIsNotNone(problem)
+
+    def test_a_badges_field_that_is_not_an_object_is_empty(self) -> None:
+        doc = {"content": base64.b64encode(b'{"badges": []}').decode()}
+        self.assertEqual(rb.previous_state(self.fetch(doc), REPO), ({}, None))
+
+
+class Field(unittest.TestCase):
+    def test_a_nested_value_is_returned(self) -> None:
+        self.assertEqual(rb.field({"a": {"b": "c"}}, "a", "b"), "c")
+
+    def test_no_keys_returns_the_document(self) -> None:
+        self.assertEqual(rb.field([1], *()), [1])
+
+    def test_a_missing_or_non_object_level_is_refused(self) -> None:
+        docs: tuple[object, ...] = ({}, {"a": {}}, {"a": "b"}, {"a": None}, [], None)
+        for doc in docs:
+            with self.subTest(doc=doc), self.assertRaisesRegex(rb.BadgeError, "no a.b"):
+                rb.field(doc, "a", "b")
+
+
+class PublicJson(unittest.TestCase):
+    def test_a_public_source_gets_no_token_and_the_badge_bounds(self) -> None:
+        with mock.patch.object(ci_tier, "https_json", return_value={"score": 7}) as sent:
+            self.assertEqual(rb.public_json("https://api.scorecard.dev/x"), {"score": 7})
+        method, url, headers, data, timeout, limit = sent.call_args.args
+        self.assertEqual((method, url, data), ("GET", "https://api.scorecard.dev/x", None))
+        self.assertEqual(headers, {"Accept": "application/json"})
+        self.assertEqual((timeout, limit), (rb.PUBLIC_TIMEOUT_S, rb.MAX_RESPONSE_BYTES))
+
+    def test_a_non_https_source_is_refused_before_any_request(self) -> None:
+        with mock.patch.object(urllib.request, "urlopen") as urlopen:
+            with self.assertRaises(ci_tier.TierError):
+                rb.public_json("http://api.scorecard.dev/x")
+        urlopen.assert_not_called()
+
+
+class Collect(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tmp = tempfile.TemporaryDirectory()
+        self.dir = Path(self.tmp.name)
+        for badge in rb.BADGES:
+            (self.dir / f"{badge.slug}.svg").write_text('<svg xmlns="x"></svg>\n', encoding="utf-8")
+        (self.dir / "state.json").write_text("{}\n", encoding="utf-8")
+
+    def tearDown(self) -> None:
+        self.tmp.cleanup()
+
+    def test_one_svg_per_badge_and_the_state_file(self) -> None:
+        self.assertEqual(len(rb.collect(self.dir, rb.BADGES)), len(rb.BADGES) + 1)
+
+    def test_a_missing_or_unexpected_file_is_refused(self) -> None:
+        (self.dir / "extra.svg").write_text("<svg ></svg>", encoding="utf-8")
+        with self.assertRaisesRegex(rb.BadgeError, "unexpected"):
+            rb.collect(self.dir, rb.BADGES)
+        (self.dir / "extra.svg").unlink()
+        (self.dir / "go.svg").unlink()
+        with self.assertRaisesRegex(rb.BadgeError, "missing"):
+            rb.collect(self.dir, rb.BADGES)
+
+    def test_a_symlink_a_large_file_or_a_non_svg_is_refused(self) -> None:
+        target = self.dir / "go.svg"
+
+        def relink() -> None:
+            target.unlink()
+            target.symlink_to(self.dir / "lint.svg")
+
+        cases: tuple[Callable[[], object], ...] = (
+            relink,
+            lambda: target.write_text("<svg " + "x" * rb.MAX_FILE_BYTES, encoding="utf-8"),
+            lambda: target.write_text("<html></html>", encoding="utf-8"),
+        )
+        for plant in cases:
+            with self.subTest(plant=plant):
+                target.unlink()
+                target.write_text("<svg ></svg>", encoding="utf-8")
+                plant()
+                with self.assertRaises(rb.BadgeError):
+                    rb.collect(self.dir, rb.BADGES)
+
+    def test_a_state_file_that_is_not_json_is_refused(self) -> None:
+        (self.dir / "state.json").write_text("{", encoding="utf-8")
+        with self.assertRaises(ValueError):
+            rb.collect(self.dir, rb.BADGES)
+
+
+class Publish(unittest.TestCase):
+    FILES: ClassVar[dict[str, bytes]] = {"go.svg": b"<svg >go</svg>", "state.json": b"{}"}
+    OLD = rb.stamp(NOW - rb.QUIET_WINDOW)
+
+    def fake(
+        self,
+        head: str | None,
+        date: str = OLD,
+        verified: bool = True,
+        tree_files: dict[str, bytes] | None = None,
+    ) -> tuple[rb.Call, list[tuple[str, str, Any]]]:
+        calls: list[tuple[str, str, Any]] = []
+        tree_files = self.FILES if tree_files is None else tree_files
+
+        def call(method: str, path: str, payload: object) -> object:
+            calls.append((method, path, payload))
+            if path.endswith("/git/ref/heads/badges"):
+                if head is None:
+                    raise http_error(404)
+                return {"object": {"sha": head}}
+            if "/git/commits/" in path:
+                return {"tree": {"sha": "t0"}, "committer": {"date": date}}
+            if "/git/trees/" in path:
+                return {"tree": [{"path": n, "sha": rb.blob_sha(d)} for n, d in tree_files.items()]}
+            if path.endswith("/git/trees"):
+                return {"sha": "t1"}
+            if path.endswith("/git/commits"):
+                return {"sha": "c1", "verification": {"verified": verified}}
+            return {}
+
+        return call, calls
+
+    def test_the_first_publish_creates_the_branch(self) -> None:
+        call, calls = self.fake(None)
+        self.assertEqual(rb.publish(call, REPO, self.FILES, NOW), "c1")
+        self.assertEqual(calls[2][2]["parents"], [])
+        self.assertEqual(
+            calls[-1],
+            ("POST", f"/repos/{REPO}/git/refs", {"ref": "refs/heads/badges", "sha": "c1"}),
+        )
+
+    def test_an_old_head_gets_a_new_commit_moved_forward_only(self) -> None:
+        call, calls = self.fake("c0")
+        rb.publish(call, REPO, self.FILES, NOW)
+        commit = next(c for c in calls if c[1].endswith("/git/commits"))
+        self.assertEqual(commit[2]["parents"], ["c0"])
+        self.assertEqual(
+            calls[-1],
+            ("PATCH", f"/repos/{REPO}/git/refs/heads/badges", {"sha": "c1", "force": False}),
+        )
+
+    def test_an_unsigned_commit_leaves_the_branch_alone(self) -> None:
+        call, calls = self.fake("c0", verified=False)
+        with self.assertRaisesRegex(rb.BadgeError, "not signed"):
+            rb.publish(call, REPO, self.FILES, NOW)
+        self.assertFalse([c for c in calls if "/git/refs" in c[1]])
+
+    def test_a_commit_without_a_true_verification_is_not_signed(self) -> None:
+        for answer in ({"sha": "c1"}, {"sha": "c1", "verification": {"verified": "true"}}):
+            with self.subTest(answer=answer):
+                call, calls = self.fake("c0")
+
+                def answered(
+                    method: str,
+                    path: str,
+                    payload: object,
+                    answer: object = answer,
+                    call: rb.Call = call,
+                ) -> object:
+                    if path.endswith("/git/commits"):
+                        return answer
+                    return call(method, path, payload)
+
+                with self.assertRaisesRegex(rb.BadgeError, "c1 is not signed"):
+                    rb.publish(answered, REPO, self.FILES, NOW)
+                self.assertFalse([c for c in calls if "/git/refs" in c[1]])
+
+    def test_a_tree_answer_without_a_list_is_refused(self) -> None:
+        young = rb.stamp(NOW - timedelta(minutes=5))
+        call, _ = self.fake("c0", date=young)
+
+        def answered(method: str, path: str, payload: object) -> object:
+            return {"tree": {}} if "/git/trees/" in path else call(method, path, payload)
+
+        with self.assertRaisesRegex(rb.BadgeError, "no tree list"):
+            rb.publish(answered, REPO, self.FILES, NOW)
+
+    def test_same_svgs_inside_the_quiet_window_commit_nothing(self) -> None:
+        young = rb.stamp(NOW - rb.QUIET_WINDOW + timedelta(seconds=1))
+        call, calls = self.fake("c0", date=young)
+        self.assertEqual(rb.publish(call, REPO, self.FILES, NOW), "unchanged at c0")
+        self.assertFalse([c for c in calls if c[0] != "GET"])
+
+    def test_a_changed_svg_inside_the_quiet_window_is_committed(self) -> None:
+        young = rb.stamp(NOW - timedelta(minutes=5))
+        call, _ = self.fake(
+            "c0", date=young, tree_files={"go.svg": b"<svg >old</svg>", "state.json": b"{}"}
+        )
+        self.assertEqual(rb.publish(call, REPO, self.FILES, NOW), "c1")
+
+    def test_a_ref_lookup_error_other_than_404_is_raised(self) -> None:
+        def call(method: str, path: str, payload: object) -> object:
+            raise http_error(500)
+
+        with self.assertRaises(urllib.error.HTTPError) as raised:
+            rb.publish(call, REPO, self.FILES, NOW)
+        raised.exception.close()
+
+    def test_a_missing_branch_closes_its_404(self) -> None:
+        error = http_error(404)
+
+        def call(method: str, path: str, payload: object) -> object:
+            raise error
+
+        self.assertIsNone(rb.branch_head(call, REPO))
+        self.assertTrue(error.fp.closed)
+
+    def test_blob_sha_is_the_git_object_id(self) -> None:
+        # `printf 'hi\n' | git hash-object --stdin`
+        self.assertEqual(rb.blob_sha(b"hi\n"), "45b983be36b73c0788dc9cbcb76cbb80fc7bb057")
+
+
+class Verdict(unittest.TestCase):
+    def verdict(self, doc: object) -> tuple[int, str]:
+        with tempfile.TemporaryDirectory() as tmp:
+            state = Path(tmp) / "state.json"
+            state.write_text(json.dumps(doc), encoding="utf-8")
+            out = io.StringIO()
+            with redirect_stdout(out), redirect_stderr(io.StringIO()):
+                rc = rb.main(["verdict", "--state", str(state)], env={})
+        return rc, out.getvalue()
+
+    def test_no_failure_passes(self) -> None:
+        self.assertEqual(self.verdict({"failures": []})[0], 0)
+
+    def test_a_failure_fails_the_run_with_an_annotation(self) -> None:
+        rc, out = self.verdict({"failures": ["codacy: down"]})
+        self.assertEqual(rc, 1)
+        self.assertIn("::error title=Badge source failed::codacy: down", out)
+
+    def test_a_state_without_a_failures_list_is_an_error(self) -> None:
+        self.assertEqual(self.verdict({"failures": "none"})[0], 2)
+
+
+class Main(unittest.TestCase):
+    def test_spec_and_publish_need_the_repository_and_a_token(self) -> None:
+        for argv in (["spec", "--spec", "s", "--state", "t"], ["publish", "--dir", "d"]):
+            err = io.StringIO()
+            with self.subTest(argv=argv[0]), redirect_stderr(err):
+                self.assertEqual(rb.main(argv, env={"GITHUB_REPOSITORY": REPO}), 2)
+            self.assertIn("set GITHUB_TOKEN", err.getvalue())
+
+
+SHIELDS = "https://img.shields.io/badge/C-23-3b82f6?style=for-the-badge&labelColor=111a35"
+GOVERNANCE = "https://github.com/vmafx/vmafx/actions/workflows/praetor-docs.yml/badge.svg"
+BLOCK = (
+    "<!-- praetor:readme-governance:start -->\n"
+    "[![Documentation Governance][docs-badge]][docs-runs]\n"
+    "\n"
+    f"[docs-badge]: {GOVERNANCE}\n"
+    "[docs-runs]: https://github.com/vmafx/vmafx/actions/workflows/praetor-docs.yml\n"
+    "<!-- praetor:readme-governance:end -->\n"
+)
+
+
+def image(url: str) -> str:
+    return f"[![x]({url})](https://example.org)\n"
+
+
+class ImageFault(unittest.TestCase):
+    def test_the_one_design_passes(self) -> None:
+        allowed = [
+            f"https://raw.githubusercontent.com/{REPO}/badges/{b.slug}.svg" for b in rb.BADGES
+        ]
+        allowed += [
+            SHIELDS,
+            "https://img.shields.io/static/v1?label=release&message=v1&style=for-the-badge&color=3b82f6&labelColor=111a35",
+            "docs/assets/vmafx-readme-banner.svg",
+        ]
+        for url in allowed:
+            with self.subTest(url=url):
+                self.assertIsNone(rb.image_fault(url))
+
+    def test_another_design_or_host_is_a_fault(self) -> None:
+        refused = {
+            "https://img.shields.io/badge/C-23-3b82f6?style=flat-square&labelColor=111a35": "style=for-the-badge",
+            "https://img.shields.io/badge/C-23-3b82f6?style=for-the-badge": "labelColor=111a35",
+            "https://img.shields.io/badge/C-23-3b82f6": "style=for-the-badge and labelColor=111a35",
+            f"https://github.com/{REPO}/actions/workflows/lint-and-format.yml/badge.svg": "not a rendered",
+            "https://www.bestpractices.dev/projects/14549/badge": "not a rendered",
+            "http://img.shields.io/badge/C-23-3b82f6?style=for-the-badge&labelColor=111a35": "not a rendered",
+            f"https://raw.githubusercontent.com/{REPO}/badges/coverage.svg": "no rendered badge is named 'coverage'",
+            f"https://raw.githubusercontent.com/{REPO}/master/tests.svg": "not a rendered",
+            "/docs/assets/banner.svg": "not a rendered",
+            "../banner.svg": "not a rendered",
+            "docs/../../banner.svg": "not a rendered",
+            "docs/assets/..": "not a rendered",
+            "//cdn.example.org/badge.svg": "not a rendered",
+        }
+        for url, reason in refused.items():
+            with self.subTest(url=url):
+                self.assertIn(reason, rb.image_fault(url) or "")
+
+    def test_a_repeated_or_empty_design_parameter_is_a_fault(self) -> None:
+        for query in (
+            "style=for-the-badge&style=flat&labelColor=111a35",
+            "style=for-the-badge&labelColor=",
+            "style=FOR-THE-BADGE&labelColor=111a35",
+            "style=for-the-badge&labelcolor=111a35",
+        ):
+            with self.subTest(query=query):
+                self.assertIsNotNone(
+                    rb.image_fault(f"https://img.shields.io/badge/C-23-3b82f6?{query}")
+                )
+
+
+class DesignFaults(unittest.TestCase):
+    def test_the_readme_has_the_one_design(self) -> None:
+        self.assertEqual(rb.design_faults((ROOT / "README.md").read_text(encoding="utf-8")), [])
+
+    def test_an_empty_readme_has_no_fault(self) -> None:
+        self.assertEqual(rb.design_faults(""), [])
+
+    def test_a_fault_names_its_line(self) -> None:
+        readme = "# Title\n\n" + image(SHIELDS.replace("for-the-badge", "flat-square"))
+        self.assertEqual(
+            rb.design_faults(readme),
+            [
+                f"3: {SHIELDS.replace('for-the-badge', 'flat-square')}: a shields.io badge needs style=for-the-badge"
+            ],
+        )
+
+    def test_the_governance_block_may_hold_its_own_badge(self) -> None:
+        self.assertEqual(rb.design_faults("# Title\n\n" + BLOCK), [])
+
+    def test_the_block_exception_covers_only_the_governance_badge(self) -> None:
+        flat = BLOCK.replace(GOVERNANCE, SHIELDS.replace("for-the-badge", "flat-square"))
+        self.assertEqual(len(rb.design_faults(flat)), 1)
+        unresolved = BLOCK.replace("[docs-badge]:", "[other]:")
+        self.assertIn("without an inline address", rb.design_faults(unresolved)[0])
+
+    def test_the_governance_badge_outside_the_block_is_a_fault(self) -> None:
+        for readme in (
+            image(GOVERNANCE),
+            BLOCK.replace("<!-- praetor:readme-governance:end -->\n", ""),
+            BLOCK.replace("<!-- praetor:readme-governance:start -->\n", ""),
+        ):
+            with self.subTest(readme=readme[:40]):
+                self.assertNotEqual(rb.design_faults(readme), [])
+
+    def test_a_reference_style_image_outside_the_block_is_a_fault(self) -> None:
+        for readme in (
+            f"![C][c]\n\n[c]: {SHIELDS}\n",
+            f"![c][]\n\n[c]: {SHIELDS}\n",
+            f"![c]\n\n[c]: {SHIELDS}\n",
+        ):
+            with self.subTest(readme=readme.splitlines()[0]):
+                self.assertEqual(
+                    rb.design_faults(readme),
+                    ["1: an image without an inline address this check can read"],
+                )
+
+    def test_code_is_not_an_image(self) -> None:
+        flat = SHIELDS.replace("for-the-badge", "flat-square")
+        for readme in (
+            f"```markdown\n![x]({flat})\n```\n",
+            f'~~~\n<img src="{flat}">\n~~~\n',
+            f"Write `![x]({flat})` for a badge.\n",
+        ):
+            with self.subTest(readme=readme.splitlines()[0]):
+                self.assertEqual(rb.design_faults(readme), [])
+
+    def test_an_unclosed_fence_hides_nothing(self) -> None:
+        flat = SHIELDS.replace("for-the-badge", "flat-square")
+        self.assertEqual(len(rb.design_faults(f"```\n![x]({flat})\n")), 1)
+
+    def test_an_html_image_must_be_a_local_file(self) -> None:
+        passing = (
+            '<img src="docs/assets/vmafx-readme-banner.svg" alt="VMAFx" height="120" />\n',
+            '<picture><source media="(prefers-color-scheme: dark)" srcset="docs/a.svg 2x, docs/b.svg"></picture>\n',
+        )
+        for readme in passing:
+            with self.subTest(readme=readme):
+                self.assertEqual(rb.design_faults(readme), [])
+        failing = (
+            f'<img src="{SHIELDS}">\n',
+            f'<IMG SRC="{GOVERNANCE}">\n',
+            f'<source srcset="docs/a.svg 1x, {SHIELDS} 2x">\n',
+            '<img alt="no source">\n',
+            f"<img src='{SHIELDS}'>\n",
+        )
+        for readme in failing:
+            with self.subTest(readme=readme):
+                self.assertEqual(len(rb.design_faults(readme)), 1)
+
+    def test_faults_come_in_line_order(self) -> None:
+        readme = f'<img src="{SHIELDS}">\n' + image(GOVERNANCE) + f'<img src="{SHIELDS}">\n'
+        lines = [int(fault.split(":", 1)[0]) for fault in rb.design_faults(readme)]
+        self.assertEqual(lines, [1, 2, 3])
+
+
+class CheckReadme(unittest.TestCase):
+    def check(self, text: str | None) -> tuple[int, str, str]:
+        with tempfile.TemporaryDirectory() as tmp:
+            readme = Path(tmp) / "README.md"
+            if text is not None:
+                readme.write_text(text, encoding="utf-8")
+            out, err = io.StringIO(), io.StringIO()
+            with redirect_stdout(out), redirect_stderr(err):
+                rc = rb.main(["check-readme", "--readme", str(readme)], env={})
+        return rc, out.getvalue(), err.getvalue()
+
+    def test_the_one_design_passes_without_a_token(self) -> None:
+        rc, out, _ = self.check(image(SHIELDS))
+        self.assertEqual(rc, 0)
+        self.assertIn("every badge has the one design", out)
+
+    def test_a_fault_fails_with_file_and_line(self) -> None:
+        rc, _, err = self.check("\n" + image(GOVERNANCE))
+        self.assertEqual(rc, 1)
+        self.assertRegex(err, r"README\.md:2: https://github\.com/")
+        self.assertIn("1 README images break the one badge design", err)
+
+    def test_a_missing_readme_is_an_error(self) -> None:
+        self.assertEqual(self.check(None)[0], 2)
+
+
+class Consistency(unittest.TestCase):
+    def test_render_mjs_allows_the_same_text_and_colours(self) -> None:
+        source = (ROOT / "tools/badges/render.mjs").read_text(encoding="utf-8")
+        self.assertIn(f"const TEXT = /^{rb.TEXT.pattern}$/", source)
+        self.assertIn(f"const COLOR = /^{rb.COLOR.pattern}$/", source)
+
+    def test_every_workflow_badge_names_a_workflow_by_its_name(self) -> None:
+        for badge in (b for b in rb.BADGES if b.kind == "workflow"):
+            path = ROOT / ".github/workflows" / badge.workflow
+            with self.subTest(badge=badge.slug):
+                first = re.search(r"^name: (.+)$", path.read_text(encoding="utf-8"), re.M)
+                self.assertEqual(first.group(1).strip() if first else None, badge.label)
+
+    def test_the_readme_shows_every_badge_once_with_its_label(self) -> None:
+        readme = (ROOT / "README.md").read_text(encoding="utf-8")
+        shown = [(m["slug"], m["alt"]) for m in RAW.finditer(readme)]
+        self.assertEqual(shown, [(b.slug, b.label) for b in rb.BADGES])
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tools/badges/package-lock.json b/tools/badges/package-lock.json
new file mode 100644
index 0000000000..6149e4f010
--- /dev/null
+++ b/tools/badges/package-lock.json
@@ -0,0 +1,87 @@
+{
+  "name": "@vmafx/readme-badges",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@vmafx/readme-badges",
+      "version": "1.0.0",
+      "license": "EUPL-1.2",
+      "dependencies": {
+        "badge-maker": "6.0.0"
+      },
+      "engines": {
+        "node": ">=22.12.0"
+      }
+    },
+    "node_modules/anafanafo": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/anafanafo/-/anafanafo-2.0.0.tgz",
+      "integrity": "sha512-Nlfq7NC4AOkTJerWRIZcOAiMNtIDVIGWGvQ98O7Jl6Kr2Dk0dX5u4MqN778kSRTy5KRqchpLdF2RtLFEz9FVkQ==",
+      "license": "MIT",
+      "dependencies": {
+        "char-width-table-consumer": "^1.0.0"
+      }
+    },
+    "node_modules/badge-maker": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/badge-maker/-/badge-maker-6.0.0.tgz",
+      "integrity": "sha512-+P5EsfmFWAR2cA9M0q20pa4OVOgnOXZkfRYUkQYHanECXCIg10ZnSBzelfBtEjt03b4Vac/yC1h55/wJPLmaOg==",
+      "license": "(MIT OR Apache-2.0)",
+      "dependencies": {
+        "anafanafo": "2.0.0",
+        "css-color-converter": "^2.0.0"
+      },
+      "bin": {
+        "badge": "lib/badge-cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/binary-search": {
+      "version": "1.3.6",
+      "resolved": "https://registry.npmjs.org/binary-search/-/binary-search-1.3.6.tgz",
+      "integrity": "sha512-nbE1WxOTTrUWIfsfZ4aHGYu5DOuNkbxGokjV6Z2kxfJK3uaAb8zNK1muzOeipoLHZjInT4Br88BHpzevc681xA==",
+      "license": "CC0-1.0"
+    },
+    "node_modules/char-width-table-consumer": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/char-width-table-consumer/-/char-width-table-consumer-1.0.0.tgz",
+      "integrity": "sha512-Fz4UD0LBpxPgL9i29CJ5O4KANwaMnX/OhhbxzvNa332h+9+nRKyeuLw4wA51lt/ex67+/AdsoBQJF3kgX2feYQ==",
+      "license": "MIT",
+      "dependencies": {
+        "binary-search": "^1.3.5"
+      }
+    },
+    "node_modules/color-convert": {
+      "version": "0.5.3",
+      "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-0.5.3.tgz",
+      "integrity": "sha512-RwBeO/B/vZR3dfKL1ye/vx8MHZ40ugzpyfeVG5GsiuGnrlMWe2o8wxBbLCpw9CsxV+wHuzYlCiWnybrIA0ling=="
+    },
+    "node_modules/color-name": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz",
+      "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
+      "license": "MIT"
+    },
+    "node_modules/css-color-converter": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/css-color-converter/-/css-color-converter-2.0.0.tgz",
+      "integrity": "sha512-oLIG2soZz3wcC3aAl/7Us5RS8Hvvc6I8G8LniF/qfMmrm7fIKQ8RIDDRZeKyGL2SrWfNqYspuLShbnjBMVWm8g==",
+      "license": "MIT",
+      "dependencies": {
+        "color-convert": "^0.5.2",
+        "color-name": "^1.1.4",
+        "css-unit-converter": "^1.1.2"
+      }
+    },
+    "node_modules/css-unit-converter": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/css-unit-converter/-/css-unit-converter-1.1.2.tgz",
+      "integrity": "sha512-IiJwMC8rdZE0+xiEZHeru6YoONC4rfPMqGm2W85jMIbkFvv5nFTwJVFHam2eFrN6txmoUYFAFXiv8ICVeTO0MA==",
+      "license": "MIT"
+    }
+  }
+}
diff --git a/tools/badges/package.json b/tools/badges/package.json
new file mode 100644
index 0000000000..77ff4a142f
--- /dev/null
+++ b/tools/badges/package.json
@@ -0,0 +1,14 @@
+{
+  "name": "@vmafx/readme-badges",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Renders the README status badges (scripts/ci/readme_badges.py) with the shields.io badge renderer",
+  "license": "EUPL-1.2",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "dependencies": {
+    "badge-maker": "6.0.0"
+  }
+}
diff --git a/tools/badges/render.mjs b/tools/badges/render.mjs
new file mode 100644
index 0000000000..eb2801753d
--- /dev/null
+++ b/tools/badges/render.mjs
@@ -0,0 +1,62 @@
+// Copyright 2026 Lusoris
+// SPDX-License-Identifier: EUPL-1.2
+//
+// Render README status badges as SVG with badge-maker, the shields.io
+// renderer (MIT OR Apache-2.0, https://github.com/badges/shields).
+//
+// Usage: node tools/badges/render.mjs <spec.json> <out-dir>
+//
+// <spec.json> is written by `scripts/ci/readme_badges.py spec`: a list of
+// {"slug", "label", "message", "color"} objects. Each entry becomes
+// <out-dir>/<slug>.svg in the for-the-badge style the README header uses
+// (docs/README-STANDARD.md). The script reads no network and no
+// environment; it fails on any entry outside the allow-listed shape.
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { makeBadge } from 'badge-maker'
+
+const LABEL_COLOR = '#111a35'
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+const COLOR = /^#[0-9a-f]{6}$/
+const TEXT = /^[\x20-\x7e]{1,40}$/
+const MAX_BADGES = 32
+
+function checked(entry, index) {
+  const keys = Object.keys(entry ?? {}).sort().join(',')
+  if (keys !== 'color,label,message,slug') {
+    throw new Error(`entry ${index}: keys ${keys}, want color,label,message,slug`)
+  }
+  const { slug, label, message, color } = entry
+  if (!SLUG.test(slug)) throw new Error(`entry ${index}: bad slug ${JSON.stringify(slug)}`)
+  if (!TEXT.test(label)) throw new Error(`${slug}: bad label ${JSON.stringify(label)}`)
+  if (!TEXT.test(message)) throw new Error(`${slug}: bad message ${JSON.stringify(message)}`)
+  if (!COLOR.test(color)) throw new Error(`${slug}: bad color ${JSON.stringify(color)}`)
+  return entry
+}
+
+function main(argv) {
+  if (argv.length !== 2) {
+    throw new Error('usage: node tools/badges/render.mjs <spec.json> <out-dir>')
+  }
+  const [specPath, outDir] = argv
+  const spec = JSON.parse(readFileSync(specPath, 'utf8'))
+  if (!Array.isArray(spec) || spec.length === 0 || spec.length > MAX_BADGES) {
+    throw new Error(`${specPath}: want a list of 1 to ${MAX_BADGES} badges`)
+  }
+  const seen = new Set()
+  spec.map(checked).forEach(({ slug, label, message, color }) => {
+    if (seen.has(slug)) throw new Error(`${slug}: listed twice`)
+    seen.add(slug)
+    const svg = makeBadge({ label, message, color, labelColor: LABEL_COLOR, style: 'for-the-badge' })
+    writeFileSync(join(outDir, `${slug}.svg`), `${svg}\n`, 'utf8')
+  })
+  process.stdout.write(`rendered ${seen.size} badges into ${outDir}\n`)
+}
+
+try {
+  main(process.argv.slice(2))
+} catch (error) {
+  process.stderr.write(`render.mjs: ${error.message}\n`)
+  process.exitCode = 1
+}

From 3b3a5673f6833c5450e9976466bdff3d37d6dbcb Mon Sep 17 00:00:00 2001
From: lusoris <lusoris@proton.me>
Date: Tue, 10 Nov 2026 19:19:05 +0100
Subject: [PATCH 2/7] fix(ci): fetch over an https-only opener and hash blobs
 with git

Codacy raised three new issues on this branch; each is fixed in the
source, with nothing dismissed or suppressed.

- ci_tier.https_json called urllib.request.urlopen, which also opens
  file:, ftp:, data: and http: addresses (Bandit B310). It now uses
  HTTPS_OPENER, an OpenerDirector built with the https handler only,
  so neither a caller nor a redirect can reach another scheme.
- readme_badges.blob_sha hashed blobs with hand-written SHA-1 code
  (insecure-hash-algorithm-sha1). git computes the object id itself
  now through `git hash-object --stdin`, run with the repository's
  bounded subprocess helper; a failing or garbled answer is a
  BadgeError.
- A test closure took its loop values as mutable default arguments
  (Pylint W0102). A commit_answering() factory builds it now.

New tests cover the opener (https reaches the handler, other schemes
fail, a redirect off https is not followed) and blob_sha (the empty
blob id, a non-zero exit, a garbled id, a missing git). Four mutants
of the new code each fail at least one test.

Signed-off-by: lusoris <lusoris@proton.me>
---
 scripts/ci/ci_tier.py                  | 25 ++++++++++-
 scripts/ci/readme_badges.py            | 27 ++++++++++--
 scripts/ci/tests/test_ci_tier.py       | 60 +++++++++++++++++++++++---
 scripts/ci/tests/test_readme_badges.py | 58 ++++++++++++++++++-------
 4 files changed, 143 insertions(+), 27 deletions(-)

diff --git a/scripts/ci/ci_tier.py b/scripts/ci/ci_tier.py
index a9fd59338b..831865db12 100644
--- a/scripts/ci/ci_tier.py
+++ b/scripts/ci/ci_tier.py
@@ -64,6 +64,29 @@
 _BASH_PATH = shutil.which("bash")
 BASH = str(Path(_BASH_PATH).resolve(strict=True)) if _BASH_PATH is not None else None
 
+
+def _https_opener() -> urllib.request.OpenerDirector:
+    """An opener that speaks https only.
+
+    ``urlopen`` also opens ``file:``, ``ftp:``, ``data:`` and plain ``http:``
+    addresses. This opener has no handler for them, so neither a caller nor a
+    redirect can reach one: the address fails as an unknown URL type.
+    """
+    opener = urllib.request.OpenerDirector()
+    for handler in (
+        urllib.request.ProxyHandler(),
+        urllib.request.UnknownHandler(),
+        urllib.request.HTTPSHandler(),
+        urllib.request.HTTPDefaultErrorHandler(),
+        urllib.request.HTTPRedirectHandler(),
+        urllib.request.HTTPErrorProcessor(),
+    ):
+        opener.add_handler(handler)
+    return opener
+
+
+HTTPS_OPENER = _https_opener()
+
 FULL = "full"
 LIGHT = "light"
 RELEASE_LIGHT = "release-light"
@@ -200,7 +223,7 @@ def https_json(
     request = urllib.request.Request(  # noqa: S310 - the scheme is checked above
         url, method=method, data=data, headers=dict(headers)
     )
-    with urllib.request.urlopen(request, timeout=timeout_s) as response:  # noqa: S310
+    with HTTPS_OPENER.open(request, timeout=timeout_s) as response:
         body = response.read(limit + 1)
     if len(body) > limit:
         raise TierError(f"{url}: answer larger than {limit} bytes")
diff --git a/scripts/ci/readme_badges.py b/scripts/ci/readme_badges.py
index 308d1408e3..195c9ef2d6 100644
--- a/scripts/ci/readme_badges.py
+++ b/scripts/ci/readme_badges.py
@@ -27,7 +27,6 @@
 import argparse
 import base64
 import functools
-import hashlib
 import json
 import os
 import re
@@ -43,11 +42,19 @@
 sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
 
 from scripts.ci import ci_tier
+from scripts.lib.safe_subprocess import (
+    CommandOutputLimitExceeded,
+    CommandTimedOut,
+    CommandValidationError,
+)
+from scripts.lib.safe_subprocess import run as run_command
 
 API = "https://api.github.com"
 BRANCH = "badges"
 STATE = "state.json"
 STALE_AFTER = timedelta(hours=6)
+GIT_TIMEOUT_S = 30
+OBJECT_ID = re.compile(r"[0-9a-f]{40}")
 QUIET_WINDOW = timedelta(hours=1)
 RUNS_PER_PAGE = 30
 PUBLIC_TIMEOUT_S = 20
@@ -303,8 +310,22 @@ def previous_state(github: GitHub, repository: str) -> tuple[dict[str, object],
 
 
 def blob_sha(data: bytes) -> str:
-    """Git object id of a blob holding ``data``."""
-    return hashlib.sha1(b"blob %d\x00" % len(data) + data, usedforsecurity=False).hexdigest()
+    """Git object id of a blob holding ``data``, as git computes it (stdin skips filters)."""
+    try:
+        result = run_command(
+            ["git", "hash-object", "--stdin"],
+            allowed_executables=("git",),
+            input_data=data,
+            capture_output=True,
+            timeout_seconds=GIT_TIMEOUT_S,
+        )
+    except (CommandValidationError, CommandTimedOut, CommandOutputLimitExceeded, OSError) as error:
+        raise BadgeError(f"git hash-object: {error}") from error
+    sha = result.stdout.decode("ascii", "replace").strip()
+    if result.returncode or not OBJECT_ID.fullmatch(sha):
+        detail = result.stderr.decode("utf-8", "replace").strip()
+        raise BadgeError(f"git hash-object exited {result.returncode}: {sha or detail}")
+    return sha
 
 
 def collect(directory: Path, badges: tuple[Badge, ...]) -> dict[str, bytes]:
diff --git a/scripts/ci/tests/test_ci_tier.py b/scripts/ci/tests/test_ci_tier.py
index 118e8267c9..5a08a848e2 100644
--- a/scripts/ci/tests/test_ci_tier.py
+++ b/scripts/ci/tests/test_ci_tier.py
@@ -5,12 +5,14 @@
 
 from __future__ import annotations
 
+import http.client
 import io
 import json
 import os
 import sys
 import tempfile
 import unittest
+import urllib.error
 import urllib.request
 from contextlib import redirect_stderr, redirect_stdout
 from pathlib import Path
@@ -161,12 +163,12 @@ def test_a_non_https_url_is_refused(self) -> None:
     def sent(
         self, method: str, payload: object | None = None, answer: bytes = b"{}"
     ) -> tuple[urllib.request.Request, Any]:
-        """The request api_request hands to urlopen, and what it returned."""
+        """The request api_request hands to the https opener, and what it returned."""
         opened = mock.MagicMock()
         opened.__enter__.return_value.read.return_value = answer
-        with mock.patch.object(urllib.request, "urlopen", return_value=opened) as urlopen:
+        with mock.patch.object(ci_tier.HTTPS_OPENER, "open", return_value=opened) as sent:
             result = ci_tier.api_request(method, "https://api.github.com/x", "t", payload)
-        return urlopen.call_args.args[0], result
+        return sent.call_args.args[0], result
 
     def test_a_payload_goes_out_as_a_json_body(self) -> None:
         request, _ = self.sent("PATCH", {"sha": "c1", "force": False})
@@ -198,10 +200,10 @@ def answer(
         """https_json's result for ``body`` and the request and read size it used."""
         opened = mock.MagicMock()
         opened.__enter__.return_value.read.return_value = body
-        with mock.patch.object(urllib.request, "urlopen", return_value=opened) as urlopen:
+        with mock.patch.object(ci_tier.HTTPS_OPENER, "open", return_value=opened) as sent:
             result = ci_tier.https_json("GET", "https://h/x", headers or {}, None, 5, limit)
         read = opened.__enter__.return_value.read
-        return result, urlopen.call_args, read.call_args
+        return result, sent.call_args, read.call_args
 
     def test_an_answer_of_exactly_the_limit_is_read(self) -> None:
         result, opened, read = self.answer(b'{"a":1}', 7)
@@ -220,11 +222,55 @@ def test_the_caller_headers_go_out_and_nothing_else(self) -> None:
         self.assertIsNone(request.get_header("Authorization"))
 
     def test_a_non_https_url_is_refused_before_any_request(self) -> None:
-        with mock.patch.object(urllib.request, "urlopen") as urlopen:
+        with mock.patch.object(ci_tier.HTTPS_OPENER, "open") as sent:
             for url in ("http://h/x", "file:///etc/passwd"):
                 with self.subTest(url=url), self.assertRaises(ci_tier.TierError):
                     ci_tier.https_json("GET", url, {}, None, 5, 10)
-        urlopen.assert_not_called()
+        sent.assert_not_called()
+
+
+class HttpsOpener(unittest.TestCase):
+    @staticmethod
+    def response(code: int, location: str | None = None) -> mock.Mock:
+        """A stand-in for an https answer with ``code`` and an optional Location."""
+        headers = http.client.HTTPMessage()
+        if location is not None:
+            headers["Location"] = location
+        answer = mock.Mock(code=code, msg="status")
+        answer.info.return_value = headers
+        return answer
+
+    def test_an_https_address_reaches_the_https_handler(self) -> None:
+        answer = self.response(200)
+        with mock.patch.object(
+            urllib.request.HTTPSHandler, "https_open", return_value=answer
+        ) as https_open:
+            self.assertIs(ci_tier.HTTPS_OPENER.open("https://h/x", timeout=1), answer)
+        self.assertEqual(https_open.call_args.args[0].full_url, "https://h/x")
+
+    def test_a_non_https_address_fails_without_being_opened(self) -> None:
+        for url in ("file:///etc/passwd", "data:text/plain,x", "ftp://h/x", "http://h/x"):
+            with (
+                self.subTest(url=url),
+                self.assertRaisesRegex(urllib.error.URLError, "unknown url type"),
+            ):
+                ci_tier.HTTPS_OPENER.open(url, timeout=1)
+
+    def test_a_redirect_off_https_is_not_followed(self) -> None:
+        for target in ("http://h/y", "ftp://h/y", "file:///etc/passwd"):
+            with (
+                self.subTest(target=target),
+                mock.patch.object(
+                    urllib.request.HTTPSHandler,
+                    "https_open",
+                    return_value=self.response(302, target),
+                ) as https_open,
+            ):
+                with self.assertRaises(urllib.error.URLError) as raised:
+                    ci_tier.HTTPS_OPENER.open("https://h/x", timeout=1)
+                if isinstance(raised.exception, urllib.error.HTTPError):
+                    raised.exception.close()
+                self.assertEqual(https_open.call_count, 1)
 
 
 class Config(unittest.TestCase):
diff --git a/scripts/ci/tests/test_readme_badges.py b/scripts/ci/tests/test_readme_badges.py
index 6d04b89eb3..0afe7ed799 100644
--- a/scripts/ci/tests/test_readme_badges.py
+++ b/scripts/ci/tests/test_readme_badges.py
@@ -14,7 +14,6 @@
 import tempfile
 import unittest
 import urllib.error
-import urllib.request
 from collections.abc import Callable
 from contextlib import redirect_stderr, redirect_stdout
 from datetime import UTC, datetime, timedelta
@@ -26,6 +25,7 @@
 
 from scripts.ci import ci_tier
 from scripts.ci import readme_badges as rb
+from scripts.lib.safe_subprocess import CommandValidationError
 
 ROOT = Path(__file__).resolve().parents[3]
 NOW = datetime(2026, 11, 10, 12, 0, tzinfo=UTC)
@@ -40,6 +40,17 @@ def runs(*conclusions: object) -> dict[str, object]:
     return {"workflow_runs": [{"conclusion": c} for c in conclusions]}
 
 
+def commit_answering(answer: object, call: rb.Call) -> rb.Call:
+    """``call``, except that creating a commit answers ``answer``."""
+
+    def answered(method: str, path: str, payload: object) -> object:
+        if path.endswith("/git/commits"):
+            return answer
+        return call(method, path, payload)
+
+    return answered
+
+
 def http_error(code: int) -> urllib.error.HTTPError:
     return urllib.error.HTTPError(
         "https://api.github.com/x", code, "x", email.message.Message(), None
@@ -347,10 +358,10 @@ def test_a_public_source_gets_no_token_and_the_badge_bounds(self) -> None:
         self.assertEqual((timeout, limit), (rb.PUBLIC_TIMEOUT_S, rb.MAX_RESPONSE_BYTES))
 
     def test_a_non_https_source_is_refused_before_any_request(self) -> None:
-        with mock.patch.object(urllib.request, "urlopen") as urlopen:
+        with mock.patch.object(ci_tier.HTTPS_OPENER, "open") as sent:
             with self.assertRaises(ci_tier.TierError):
                 rb.public_json("http://api.scorecard.dev/x")
-        urlopen.assert_not_called()
+        sent.assert_not_called()
 
 
 class Collect(unittest.TestCase):
@@ -463,20 +474,8 @@ def test_a_commit_without_a_true_verification_is_not_signed(self) -> None:
         for answer in ({"sha": "c1"}, {"sha": "c1", "verification": {"verified": "true"}}):
             with self.subTest(answer=answer):
                 call, calls = self.fake("c0")
-
-                def answered(
-                    method: str,
-                    path: str,
-                    payload: object,
-                    answer: object = answer,
-                    call: rb.Call = call,
-                ) -> object:
-                    if path.endswith("/git/commits"):
-                        return answer
-                    return call(method, path, payload)
-
                 with self.assertRaisesRegex(rb.BadgeError, "c1 is not signed"):
-                    rb.publish(answered, REPO, self.FILES, NOW)
+                    rb.publish(commit_answering(answer, call), REPO, self.FILES, NOW)
                 self.assertFalse([c for c in calls if "/git/refs" in c[1]])
 
     def test_a_tree_answer_without_a_list_is_refused(self) -> None:
@@ -523,6 +522,33 @@ def test_blob_sha_is_the_git_object_id(self) -> None:
         # `printf 'hi\n' | git hash-object --stdin`
         self.assertEqual(rb.blob_sha(b"hi\n"), "45b983be36b73c0788dc9cbcb76cbb80fc7bb057")
 
+    def test_the_empty_blob_has_the_well_known_id(self) -> None:
+        # `git hash-object --stdin </dev/null`
+        self.assertEqual(rb.blob_sha(b""), "e69de29bb2d1d6434b8b29ae775ad8c2e48c5391")
+
+    def test_a_failing_or_garbled_git_is_refused(self) -> None:
+        answers = (
+            mock.Mock(returncode=128, stdout=b"", stderr=b"fatal: no"),
+            mock.Mock(
+                returncode=1, stdout=b"45b983be36b73c0788dc9cbcb76cbb80fc7bb057\n", stderr=b""
+            ),
+            mock.Mock(returncode=0, stdout=b"not-an-id\n", stderr=b""),
+            mock.Mock(returncode=0, stdout=b"a" * 64 + b"\n", stderr=b""),
+        )
+        for answer in answers:
+            with (
+                self.subTest(stdout=answer.stdout),
+                mock.patch.object(rb, "run_command", return_value=answer),
+                self.assertRaisesRegex(rb.BadgeError, "git hash-object exited"),
+            ):
+                rb.blob_sha(b"hi\n")
+
+    def test_a_missing_git_is_a_badge_error(self) -> None:
+        missing = CommandValidationError("required executable not found: git")
+        with mock.patch.object(rb, "run_command", side_effect=missing):
+            with self.assertRaisesRegex(rb.BadgeError, "not found: git"):
+                rb.blob_sha(b"hi\n")
+
 
 class Verdict(unittest.TestCase):
     def verdict(self, doc: object) -> tuple[int, str]:

From 0bc84f4beffb1c780b213409f5630ad7fbe6bba4 Mon Sep 17 00:00:00 2001
From: lusoris <lusoris@proton.me>
Date: Tue, 10 Nov 2026 20:04:18 +0100
Subject: [PATCH 3/7] fix(ci): close the badge review findings on run choice,
 time and scope

The pull request 3393 review found gaps in how the badge script picks a
run, carries a value, reads its state and checks the README, and in how
the workflow chooses the code it runs.

Script:

- the newest completed run that was not cancelled or skipped decides a
  workflow badge; timed_out and startup_failure read failing, any other
  conclusion unknown, and an older run never stands in
- a naive or unreadable read time counts as stale instead of raising or
  passing as fresh
- a state.json read that fails with anything but 404 stops the run
- the Scorecard badge is green from an unrounded 8.5, the master gate
- check-readme accepts only this repository's rendered badges, and a
  local image must name a file inside the README directory
- the https opener follows no redirect, so a 3xx is an error

Workflow: the render job runs only on master, and both jobs check out
github.sha, so the publish token never meets a branch copy and a master
push between the jobs cannot change the code.

Docs: the guide, both agent pages, ADR-3519 and a new research digest
record the run rule, the 75-minute early stale bound, the rights limits
and the open App-token follow-up. Eleven planted mutants fail the tests.

Signed-off-by: lusoris <lusoris@proton.me>
---
 .github/AGENTS.d/readme-badges.md             |  28 ++
 .github/AGENTS.md                             |   1 +
 .github/workflows/readme-badges.yml           |  19 +-
 changelog.d/changed/readme-badges-uniform.md  |   2 +-
 .../adr/3519-readme-badges-rendered-branch.md |  24 +-
 .../3519-readme-badges-rendered-branch.md     |   2 +-
 docs/development/readme-badges.md             |  60 +++-
 .../3519-readme-badges-rendered-branch.md     |  61 +++++
 scripts/ci/AGENTS.d/readme-badges.md          |  12 +-
 scripts/ci/ci_tier.py                         |  10 +-
 scripts/ci/readme_badges.py                   | 231 +++++++++++-----
 scripts/ci/tests/test_ci_tier.py              |  42 ++-
 scripts/ci/tests/test_readme_badges.py        | 259 +++++++++++++++---
 13 files changed, 600 insertions(+), 151 deletions(-)
 create mode 100644 .github/AGENTS.d/readme-badges.md
 create mode 100644 docs/research/3519-readme-badges-rendered-branch.md

diff --git a/.github/AGENTS.d/readme-badges.md b/.github/AGENTS.d/readme-badges.md
new file mode 100644
index 0000000000..9b18bf27cd
--- /dev/null
+++ b/.github/AGENTS.d/readme-badges.md
@@ -0,0 +1,28 @@
+---
+paths:
+  - .github/workflows/readme-badges.yml
+invariant: Render job on master only; both checkouts at github.sha; publish job contents: write only; no workflow_run trigger.
+---
+# README badges workflow (ADR-3519)
+
+`.github/workflows/readme-badges.yml` renders + publishes README status
+badges onto `badges` branch. Script rules, design check, carry:
+[scripts/ci/AGENTS.d/readme-badges.md](../../scripts/ci/AGENTS.d/readme-badges.md).
+Human guide: `docs/development/readme-badges.md`.
+
+- Guard: render job `if:` = policy repository + `https://github.com` +
+  `github.ref == 'refs/heads/master'`. Publish job `needs: render`, so
+  skipped render skips publish. Manual run on other branch -> nothing runs;
+  publish token never meets branch copy of workflow. Names come from
+  `.github/repository-security-policy.json`; `test_readme_badges.py` keeps
+  them equal.
+- Checkout: both jobs `ref: ${{ github.sha }}`, `persist-credentials: false`.
+  Never `ref: master`: master push between jobs hands publisher other code
+  than renderer ran.
+- Rights: top level `permissions: {}`; render job `actions: read` +
+  `contents: read`; publish job `contents: write` only. No other write scope.
+- Trigger: `schedule` (minutes 7, 22, 37, 52) + `workflow_dispatch`. No
+  `workflow_run` (zizmor dangerous trigger; fork branch named `master`
+  matches `branches` filter).
+- Ref: publish writes `refs/heads/badges` only, `force: false`;
+  GitHub-signed commit required.
diff --git a/.github/AGENTS.md b/.github/AGENTS.md
index 2caba47c6b..27de45844c 100644
--- a/.github/AGENTS.md
+++ b/.github/AGENTS.md
@@ -39,6 +39,7 @@ broken `.c` file).
 | `workflows/libvmaf-build-matrix.yml`, `/scripts/ci/run_meson_test.py`, `/core/test/test_meson_secret_env_sanitization.py` | [meson-sanitization](AGENTS.d/meson-sanitization.md) | Every workflow step running Meson/Ninja test invokes run_meson_test.py; resolve Python before sudo. |
 | `workflows/lint-and-format.yml`, `/scripts/sync-pelorus-interop.sh` | [pelorus-mirror](AGENTS.d/pelorus-mirror.md) | Pre-Commit job verifies exact declared commit of VMAFx/pelorus before pre-commit; no moving branch or tag. |
 | `/pyproject.toml`, `/renovate.json` | [python-requirement](AGENTS.d/python-requirement.md) | Root pyproject.toml keeps requires-python >=3.14 without patch component; renovate excludes root requires-python. |
+| `workflows/readme-badges.yml` | [readme-badges](AGENTS.d/readme-badges.md) | Render job on master only; both checkouts at github.sha; publish job contents: write only; no workflow_run trigger. |
 | `workflows/release-please.yml`, `workflows/supply-chain.yml`, `/scripts/release/verify-release-version.sh`, `/dev/Containerfile` | [release-fan-out](AGENTS.d/release-fan-out.md) | Single root package draft release; release-publish environment; native release-build stage; tag-bound recovery. |
 | `/renovate.json`, `/scripts/ci/tests/test_renovate_file_patterns.py`, `/docs/development/dependency-bot.md` | [renovate-bot](AGENTS.d/renovate-bot.md) | Mend Renovate config in renovate.json; dependabot.yml disabled; RENOVATE_TOKEN repository secret. |
 | `workflows/required-aggregator.yml`, `/scripts/ci/check-aggregator-names.sh`, `/scripts/ci/plan-ci-impact.py` | [required-aggregator](AGENTS.d/required-aggregator.md) | Aggregator runs on drafts; gates route in-job without paths filters; display names <=30 chars and match aggregator. |
diff --git a/.github/workflows/readme-badges.yml b/.github/workflows/readme-badges.yml
index 5447adfb0e..0ff767b493 100644
--- a/.github/workflows/readme-badges.yml
+++ b/.github/workflows/readme-badges.yml
@@ -28,7 +28,14 @@ jobs:
     name: Read the sources and render
     # github.com only: the job reads and the publish job writes through the
     # GitHub API, which a mirror's token cannot reach (as in supply-chain.yml).
-    if: github.repository == 'VMAFx/vmafx' && github.server_url == 'https://github.com'
+    # Default branch only: a manual run picked on another branch runs nothing,
+    # so the publish token never meets a branch's own copy of this file.
+    # .github/repository-security-policy.json holds both names; a test keeps
+    # these in step with it.
+    if: >-
+      github.repository == 'VMAFx/vmafx'
+      && github.server_url == 'https://github.com'
+      && github.ref == 'refs/heads/master'
     runs-on: ubuntu-26.04
     timeout-minutes: 10
     permissions:
@@ -37,7 +44,10 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
-          ref: master
+          # The commit this run started from, in both jobs: a master push
+          # between them cannot hand the publisher other code than the
+          # renderer ran.
+          ref: ${{ github.sha }}
           persist-credentials: false
       - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
         with:
@@ -85,7 +95,10 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
-          ref: master
+          # The commit this run started from, in both jobs: a master push
+          # between them cannot hand the publisher other code than the
+          # renderer ran.
+          ref: ${{ github.sha }}
           persist-credentials: false
       - if: ${{ env.GITEA_ACTIONS != 'true' }}
         uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333  # v8.0.2
diff --git a/changelog.d/changed/readme-badges-uniform.md b/changelog.d/changed/readme-badges-uniform.md
index 177c50ad57..dd0c81a314 100644
--- a/changelog.d/changed/readme-badges-uniform.md
+++ b/changelog.d/changed/readme-badges-uniform.md
@@ -1,4 +1,4 @@
-- **Every README badge now has the same `for-the-badge` design, and the status badges come from this project's own render.**
+- **Every README badge but the Praetor-managed governance badge now has the same `for-the-badge` design, and the status badges come from this project's own render.**
   `.github/workflows/readme-badges.yml` draws the seven workflow badges and the OpenSSF Scorecard,
   OpenSSF Best Practices and Codacy badges every 15 minutes onto the `badges` branch: a workflow badge
   shows the newest finished master push run, so a run in progress never hides a red one, and the
diff --git a/docs/adr/3519-readme-badges-rendered-branch.md b/docs/adr/3519-readme-badges-rendered-branch.md
index e651b3482d..9ad70bc729 100644
--- a/docs/adr/3519-readme-badges-rendered-branch.md
+++ b/docs/adr/3519-readme-badges-rendered-branch.md
@@ -32,9 +32,11 @@ Practices and Codacy APIs, and `tools/badges/render.mjs` draws the SVGs with
 `tools/badges/package-lock.json`. Its publish job (`contents: write`) commits
 the SVGs and `state.json` to the `badges` branch through the GitHub API, and
 the README links `https://raw.githubusercontent.com/VMAFx/vmafx/badges/<slug>.svg`.
-A source that fails keeps its last value for six hours, then reads `stale`,
-and the run turns red. Every other README badge, the backends row included,
-uses `for-the-badge`. The full rules are in
+Both jobs run only on the default branch and check out the commit the run
+started from. A source that fails keeps its last value for six hours, then
+reads `stale`, and the run turns red. Every other README badge, the backends
+row included, uses `for-the-badge`; the one exception is the Praetor
+governance badge, which Praetor writes. The full rules are in
 [docs/development/readme-badges.md](../development/readme-badges.md).
 
 ## Alternatives considered
@@ -58,16 +60,26 @@ uses `for-the-badge`. The full rules are in
   limit to one branch. The script writes only `refs/heads/badges` and never
   forces, and the master ruleset requires a pull request, so the token cannot
   move `master`. An SVG cannot age by itself: if the workflow stops, the
-  badges keep their last values until someone sees the red or missing run.
+  badges keep their last values until someone sees the missing run. The six
+  hours count from the read time `state.json` records, which an unchanged
+  badge refreshes only once an hour, so `stale` can come up to 75 minutes
+  early; committing on every run would quadruple the branch's growth.
 - **Neutral / follow-ups**: a ruleset for the `badges` branch in
   `.github/repository-security-policy.json` (deletion and non-fast-forward
   refused); the Praetor governance badge in the `praetor:readme-governance`
   block keeps GitHub's design until Praetor offers the style (Praetor issue
-  1893), and `check-readme` then drops its one exception. This style is
-  the reference for the ecosystem README badge audit.
+  1893), and `check-readme` then drops its one exception. Publishing with a
+  GitHub App token instead of the workflow token, so that a `badges` ruleset
+  can refuse every other writer, is open. This style is the reference for the
+  ecosystem README badge audit.
 
 ## References
 
+- Source: `req` (operator order `vmafx-readme-badges-and-lint-red-20261110`,
+  2026-11-10, paraphrased): every README badge in one design, and no red
+  default branch anywhere in the fleet.
+- [Research-3519](../research/3519-readme-badges-rendered-branch.md): the
+  sources, measurements and alternatives behind this decision.
 - Controller answer `vmafx-readme-badge-style-r1` (2026-11-10, option b,
   paraphrased): one `for-the-badge` design everywhere, a workflow rendering the
   dynamic badges with a pinned `badge-maker` onto a `badges` branch with the
diff --git a/docs/adr/_index_fragments/3519-readme-badges-rendered-branch.md b/docs/adr/_index_fragments/3519-readme-badges-rendered-branch.md
index fbff2ce75f..094005da48 100644
--- a/docs/adr/_index_fragments/3519-readme-badges-rendered-branch.md
+++ b/docs/adr/_index_fragments/3519-readme-badges-rendered-branch.md
@@ -1 +1 @@
-| [ADR-3519](3519-readme-badges-rendered-branch.md) | The ten README status badges are rendered with the pinned shields.io renderer by `.github/workflows/readme-badges.yml` every 15 minutes onto the `badges` branch, from the newest decisive master push run of each workflow and the Scorecard, Best Practices and Codacy APIs; a failed source carries six hours then reads `stale`; every README badge uses `for-the-badge` | Accepted | ci, docs, readme, supply-chain |
+| [ADR-3519](3519-readme-badges-rendered-branch.md) | The ten README status badges are rendered with the pinned shields.io renderer by `.github/workflows/readme-badges.yml` every 15 minutes onto the `badges` branch, from the newest decisive master push run of each workflow and the Scorecard, Best Practices and Codacy APIs; a failed source carries six hours then reads `stale`; every README badge but the Praetor-managed governance badge uses `for-the-badge` | Accepted | ci, docs, readme, supply-chain |
diff --git a/docs/development/readme-badges.md b/docs/development/readme-badges.md
index 4bea062370..36482b8e28 100644
--- a/docs/development/readme-badges.md
+++ b/docs/development/readme-badges.md
@@ -22,13 +22,15 @@ for the current value:
 
 | Badge | Source | Message and colour |
 | --- | --- | --- |
-| Tests, Builds, Lint, FFmpeg, Go, Rust, Security | GitHub API: the newest completed push run of the workflow on the default branch whose conclusion is `success`, `failure`, `timed_out` or `startup_failure`. Cancelled, skipped and waiting runs are passed over, so a run in progress never hides a red one. | `passing` green, `failing` red, `unknown` grey when none of the last 30 runs decided. |
-| OpenSSF Scorecard | `https://api.scorecard.dev/projects/github.com/VMAFx/vmafx` | the score with one decimal, `7.0 / 10`; green from 7.0, amber from 4.0, red below. The colour follows the shown value, so 6.96 reads `7.0 / 10` in green. |
+| Tests, Builds, Lint, FFmpeg, Go, Rust, Security | GitHub API: the newest push run of the workflow on the default branch, among the last 30, that has a conclusion and was not cancelled or skipped. Runs in progress, cancelled and skipped are passed over, so a run in progress never hides a red one. | `passing` green for `success`; `failing` red for `failure`, `timed_out` or `startup_failure`; `unknown` grey for any other conclusion (`action_required`, `neutral`, `stale`) and when no run qualifies. An older run's value never stands in. |
+| OpenSSF Scorecard | `https://api.scorecard.dev/projects/github.com/VMAFx/vmafx` | the score with one decimal, `8.5 / 10`; green from an unrounded 8.5, the master requirement in [the principles](../principles.md) ([ADR-1247](../adr/1247-scorecard-exact-head-gates.md)), amber from 4.0, red below. The colour follows the unrounded score, so 8.46 reads `8.5 / 10` in amber. |
 | OpenSSF Best Practices | `https://www.bestpractices.dev/projects.json?url=https://github.com/VMAFx/vmafx` | `in progress` amber, `passing`, `silver` or `gold` green. |
 | Codacy | `https://app.codacy.com/api/v3/analysis/organizations/gh/VMAFx/repositories/vmafx` | the grade letter; A and B green, C amber, D to F red. |
 
 Only the GitHub API call carries the workflow token. The three public
-sources get a plain request with no token.
+sources get a plain request with no token. Every request goes over https
+only, and a redirect is not followed: it fails as an error, so the token
+never travels to another address.
 
 The workflow writes the list to `build/badges-spec.json`, and
 `tools/badges/render.mjs` draws one SVG per entry with `badge-maker`, the
@@ -45,7 +47,20 @@ turns red at its last step (`readme_badges.py verdict`), so the failure shows
 in the Actions tab the same day, not when someone notices an old badge.
 
 The last values live in `state.json` on the `badges` branch, next to the SVGs,
-with the time each one was read.
+with the time each one was read. A time without a UTC offset, or one that
+cannot be read, counts as stale.
+
+The six hours run from the read time `state.json` holds. A run whose SVGs are
+all unchanged commits nothing for an hour (see below), so that time trails the
+last successful read by at most one hour plus one 15-minute schedule step. A
+badge can therefore turn `stale` up to 75 minutes before six hours have passed
+since its last successful read, and at most one schedule step after.
+Committing `state.json` on every run would close that gap at the cost of
+about four commits an hour instead of one.
+
+When `state.json` itself cannot be read (any answer but 404, which means the
+branch is new), the run stops before it renders anything. The badges keep
+their values instead of all turning `stale` at once.
 
 ## How the badges branch is written
 
@@ -65,6 +80,13 @@ commit. GitHub cannot limit that right to one branch; the script writes only
 `refs/heads/badges`, and the master ruleset requires a pull request, so the
 token cannot move `master`.
 
+Both jobs run only on the default branch (`github.ref` is
+`refs/heads/master`): a manual run started on another branch does nothing, so
+the publish token never runs a branch's own copy of the workflow. Both jobs
+check out `github.sha`, the commit the run started from, so a master push
+between the two jobs cannot hand the publisher other code than the renderer
+ran.
+
 ## Why a schedule and not `workflow_run`
 
 A `workflow_run` trigger would refresh a badge within a minute of each master
@@ -76,9 +98,16 @@ to 15 minutes of lag and has neither problem.
 ## Limits
 
 - An SVG cannot age by itself. When the workflow itself stops (disabled, or
-  scheduled runs paused after 60 days without repository activity), the
-  badges keep showing the last values. The red run and the README Badges
-  entry in the Actions tab are the signal.
+  scheduled runs paused after 60 days without repository activity), no run
+  starts, so none turns red, and the badges keep showing the last values,
+  green ones included. The signal is a missing run: the newest README Badges
+  run is older than 15 minutes. Check it, then re-enable the workflow:
+
+  ```bash
+  gh run list -R VMAFx/vmafx --workflow readme-badges.yml --limit 1 --json createdAt,conclusion
+  gh workflow enable readme-badges.yml -R VMAFx/vmafx
+  ```
+
 - The Praetor governance badge in the `praetor:readme-governance` block is
   written by Praetor and keeps GitHub's design.
 
@@ -90,12 +119,17 @@ python3 -m pytest scripts/ci/tests/test_readme_badges.py
 ```
 
 `check-readme` fails when any image in the README breaks the one design. An
-image passes only when it is one of the rendered SVGs on the `badges` branch,
-a shields.io badge with both `style=for-the-badge` and `labelColor=111a35`, or
-a file inside the repository (the banner). Images inside code fences and code
-spans are ignored. The one exception is the Praetor governance badge inside
-the `praetor:readme-governance` block; it goes once Praetor can draw that
-badge in the same style (Praetor issue 1893). Each fault names the line:
+image passes only when it is one of the rendered SVGs on this repository's
+`badges` branch, a shields.io badge with both `style=for-the-badge` and
+`labelColor=111a35`, or a file that exists inside the repository (the
+banner). The repository name comes from
+`.github/repository-security-policy.json`; a badge rendered for any other
+repository or a fork fails. A local path fails when it names no file or
+resolves outside the README's directory, through a symbolic link included.
+Images inside code fences and code spans are ignored. The one exception is
+the Praetor governance badge inside the `praetor:readme-governance` block;
+it goes once Praetor can draw that badge in the same style (Praetor issue
+1893). Each fault names the line:
 
 ```text
 README.md:117: https://img.shields.io/badge/FFmpeg-n9.0.2-8b5cf6?style=flat-square&labelColor=111a35: a shields.io badge needs style=for-the-badge
diff --git a/docs/research/3519-readme-badges-rendered-branch.md b/docs/research/3519-readme-badges-rendered-branch.md
new file mode 100644
index 0000000000..730896fde2
--- /dev/null
+++ b/docs/research/3519-readme-badges-rendered-branch.md
@@ -0,0 +1,61 @@
+<!-- markdownlint-disable MD013 MD060 -->
+# Research-3519: README status badges rendered in one style onto a `badges` branch
+
+- **Status**: Completed
+- **Workstream**: [ADR-3519](../adr/3519-readme-badges-rendered-branch.md), [ADR-3366](../adr/3366-readme-presentation-standard.md)
+- **Last updated**: 2026-11-10
+
+## Question
+
+How can the ten README status badges (seven workflow badges, OpenSSF Scorecard, OpenSSF Best Practices and Codacy) share the one `for-the-badge` design that [ADR-3366](../adr/3366-readme-presentation-standard.md) sets, report the run this project chooses, and be published with the fewest rights a workflow can hold?
+
+## Sources
+
+- `services/github/github-actions-workflow-status.service.js` in the shields repository (read 2026-11-10): the shields.io workflow badge fetches GitHub's own `badge.svg` and reads its text.
+- GitHub REST API "List workflow runs for a workflow" (`GET /repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs`): `branch`, `event`, `status` and `per_page` filters; default page size 30.
+- GitHub Docs, "Creating rulesets for a repository", section "Granting bypass permissions" (read 2026-11-10): the eligible bypass actors are repository admins and owners, the maintain or write role, teams, GitHub Apps and Dependabot.
+- GitHub Docs, "About commit signature verification", section "Signature verification for bots": GitHub signs commits a GitHub App or the workflow token creates through the API when no custom author or committer is set.
+- Commit `e3d3cbcb602af571f93a1cc72e71ed71fad14b38` (an API commit by a GitHub App bot): committer `web-flow`, signature verified.
+- A gh-aw issue opened 2026-10-30 and the Codex Review Gate marketplace page (read 2026-11-10): the workflow token cannot be added as a ruleset bypass actor on its own; integration id 15368 names the whole GitHub Actions App, not one workflow.
+- zizmor audit `dangerous-triggers`: rates `workflow_run` and `pull_request_target` as dangerous triggers.
+- [docs/principles.md](../principles.md) section 6 and [ADR-1247](../adr/1247-scorecard-exact-head-gates.md): unrounded Scorecard ≥ 8.5 required on master.
+- `badge-maker` 6.0.0, the shields.io renderer, pinned in `tools/badges/package-lock.json`.
+- `scripts/ci/readme_badges.py`, `.github/workflows/readme-badges.yml`, `scripts/ci/check_repository_security.py` and `.github/repository-security-policy.json` on the pull request 3393 branch.
+
+## Findings
+
+1. **GitHub's badge has one fixed design, and shields.io reads it.** `badge.svg` cannot be restyled. The shields.io workflow badge takes its text from that same image, so a `for-the-badge` shields URL changes the look but not which run the badge reports. Rendering the SVGs from the API is the only path that gives the project both the design and the run choice.
+
+2. **Run choice.** GitHub's badge shows the latest run, so a cancelled or skipped run hides a failed one. `readme_badges.py` lists completed push runs on the default branch (`per_page` = `RUNS_PER_PAGE` = 30) and takes the newest one with a conclusion other than cancelled or skipped (`PASSED_OVER`). `success` reads passing; `failure`, `timed_out` and `startup_failure` read failing; any other conclusion reads `unknown`. An older run never stands in for a newer decisive one. When all 30 runs are passed over, the badge reads `unknown` rather than paging further back.
+
+3. **Trigger.** A `workflow_run` trigger would refresh a badge within a minute of a master run, but zizmor rates it a dangerous trigger, and its `branches: [master]` filter also matches a fork's branch named `master`. A schedule (`7,22,37,52 * * * *`) with a default-branch guard on the render job and checkouts at `github.sha` has no outside input and lags by at most one 15-minute step.
+
+4. **Rights.** `contents: write` cannot be limited to one branch. The master ruleset requires a pull request and the workflow token holds no bypass, so the token cannot move `master`. The token also cannot be named as a ruleset bypass actor: the eligible actors are roles, teams, GitHub Apps and Dependabot, and the GitHub Actions App (integration 15368) covers every workflow in the repository. A `badges` ruleset that refuses deletion and non-fast-forward pushes therefore still lets any workflow with `contents: write` add forward commits; refusing every other writer needs a dedicated GitHub App as the only bypass actor.
+
+5. **Signed commits.** Commits the workflow token creates through the Git data API with no custom author or committer are signed by GitHub and show as verified (committer `web-flow`). The publish job sets no author or committer, so the `badges` branch carries only verified commits without any signing key in the workflow.
+
+6. **Staleness.** A source that fails keeps its last value for `STALE_AFTER` = 6 hours, then reads `stale` and turns the run red. The publish job skips the commit while every SVG matches the branch and the branch's last commit is younger than `QUIET_WINDOW` = 1 hour, so the read time `state.json` records can lag the true last read by up to 1 hour plus one 15-minute step: `stale` can come up to 75 minutes early, and at most one schedule step late. Committing `state.json` on every run would remove that lag at the cost of about four commits an hour instead of one.
+
+7. **Scorecard threshold.** The badge is green from an unrounded 8.5, the gate [docs/principles.md](../principles.md) and [ADR-1247](../adr/1247-scorecard-exact-head-gates.md) set for master. A score of 8.46 shows `8.5 / 10` in amber, so the rounded text never hides a miss.
+
+8. **Pinned renderer.** `badge-maker` 6.0.0 draws the same SVG shields.io serves, without a request to shields.io per page view. The lock file pins it with its integrity hash.
+
+## Alternatives explored
+
+- **`workflow_run` trigger**: Rejected. Faster badges, but a dangerous trigger with a branch filter that fork branches can match.
+- **shields.io dynamic URLs with `style=for-the-badge`**: Rejected. Every page view depends on shields.io, and the workflow badge keeps GitHub's run choice.
+- **Each service's own badge**: Rejected. Four designs in one block and a Scorecard badge without a score.
+- **GitHub Pages files**: Rejected. Pages deploys the documentation site; a second deploy path for ten files is not worth it.
+- **Commit `state.json` on every run**: Rejected. Removes the 75-minute early `stale`, but quadruples the branch's growth.
+- **Rendered SVGs on a `badges` branch, schedule trigger, workflow token**: Chosen.
+
+## Open questions
+
+- Publishing with a dedicated GitHub App token plus a second managed ruleset on `badges`, so that no other workflow can write the branch. `check_repository_security.py` manages one ruleset today; a second one needs a policy change and an App installation.
+- The Praetor governance badge keeps GitHub's design until Praetor offers the style (Praetor issue 1893).
+
+## Related
+
+- [ADR-3519](../adr/3519-readme-badges-rendered-branch.md) — Render the README status badges in one style onto a `badges` branch
+- [ADR-3366](../adr/3366-readme-presentation-standard.md) — README presentation standard
+- [README badges](../development/readme-badges.md)
diff --git a/scripts/ci/AGENTS.d/readme-badges.md b/scripts/ci/AGENTS.d/readme-badges.md
index 3966f59fdc..499bc0edf4 100644
--- a/scripts/ci/AGENTS.d/readme-badges.md
+++ b/scripts/ci/AGENTS.d/readme-badges.md
@@ -14,11 +14,13 @@ area: gates
 `scripts/ci/readme_badges.py` reads badge values; `tools/badges/render.mjs` draws SVGs; `.github/workflows/readme-badges.yml` publishes SVGs to `badges` branch. Human guide: `docs/development/readme-badges.md`.
 
 - Order + labels: README header badges, alt texts, order = `BADGES` tuple; workflow badge label = that workflow's `name:`. `test_readme_badges.py` reads `README.md`; new badge changes both.
-- Run choice: workflow badge = newest push run on default branch with conclusion `success`, `failure`, `timed_out` or `startup_failure`; cancelled, skipped, in-progress runs passed over. Never "latest run".
+- Run choice: workflow badge = newest push run on default branch with a conclusion, not cancelled or skipped (`PASSED_OVER`). `success` -> passing; `failure`, `timed_out`, `startup_failure` -> failing; other conclusion -> `unknown`, never older run's value. Never "latest run".
+- Scorecard: green from unrounded `SCORE_GREEN` = 8.5 (master requirement, `docs/principles.md`, ADR-1247); shown value rounded to 1 decimal, colour from unrounded score.
 - Renderer allow-list: keys `slug`, `label`, `message`, `color` only; text `[\x20-\x7e]{1,40}`; colour `#[0-9a-f]{6}`. `TEXT` / `COLOR` in Python and `render.mjs` stay equal (test compares both).
-- Carry: failed source keeps last value `STALE_AFTER` = 6 h from `state.json`, then `stale` grey; `verdict` step exits 1 on any failed source.
+- Carry: failed source keeps last value `STALE_AFTER` = 6 h from `state.json` read time, then `stale` grey; naive or unreadable time = stale (`read_time`). Recorded time trails real read <= `QUIET_WINDOW` + 15 min schedule (test pins bound); accepted trade-off vs 4 commits/h. `verdict` step exits 1 on any failed source.
+- State read: `previous_state` 404 = new branch, empty; any other failure -> `BadgeError`, run stops, nothing rendered or published. Never return empty state on failed read.
 - Publish: one commit via Git data API; GitHub-signed commit required (unverified -> no ref move); `force: false`; ref path only `refs/heads/badges`; no commit when SVGs unchanged and head < `QUIET_WINDOW` = 1 h old.
 - Tokens: `GITHUB_TOKEN` only to `api.github.com`; Scorecard, Best Practices, Codacy reads carry no token.
-- Requests: every call through `ci_tier.https_json` (https only, size cap: public `MAX_RESPONSE_BYTES`, GitHub API `ci_tier.API_MAX_BYTES`); no second request helper. JSON answers read with `field()`, never bare indexing.
-- Design check: `readme_badges.py check-readme` (hook `readme-badge-design`) fails README image unless rendered `badges`-branch SVG, shields.io badge with `style=for-the-badge` + `labelColor=111a35`, or repo-local file. Fences + code spans ignored. Only exception: `praetor-docs.yml/badge.svg` inside `praetor:readme-governance` block (`GOVERNANCE_BADGE`) until Praetor issue 1893 lands; then drop exception.
-- Rights: render job `actions: read` + `contents: read`; publish job `contents: write` only; workflow top level `permissions: {}`. No `workflow_run` trigger (zizmor dangerous trigger; fork branch named `master` matches).
+- Requests: every call through `ci_tier.https_json` (https only, size cap: public `MAX_RESPONSE_BYTES`, GitHub API `ci_tier.API_MAX_BYTES`); no second request helper. `HTTPS_OPENER` has no redirect handler: 3xx = `HTTPError`, `Authorization` never resent elsewhere. JSON answers read with `field()`, never bare indexing.
+- Design check: `readme_badges.py check-readme` (hook `readme-badge-design`) fails README image unless rendered `badges`-branch SVG, shields.io badge with `style=for-the-badge` + `labelColor=111a35`, or repo-local file that exists. Rendered + governance badges must name home repository (`home_repository()` from `.github/repository-security-policy.json`, case-insensitive); other repo or fork fails. Local path: `missing_file` resolves symlinks, fails outside README dir or no file. Fences + code spans ignored. Only exception: `praetor-docs.yml/badge.svg` inside `praetor:readme-governance` block (`governance_badge()`) until Praetor issue 1893 lands; then drop exception.
+- Rights: render job `actions: read` + `contents: read`; publish job `contents: write` only; workflow top level `permissions: {}`. No `workflow_run` trigger (zizmor dangerous trigger; fork branch named `master` matches). Workflow guard + checkout rules: `.github/AGENTS.d/readme-badges.md`.
diff --git a/scripts/ci/ci_tier.py b/scripts/ci/ci_tier.py
index 831865db12..b96ad25ed4 100644
--- a/scripts/ci/ci_tier.py
+++ b/scripts/ci/ci_tier.py
@@ -66,11 +66,14 @@
 
 
 def _https_opener() -> urllib.request.OpenerDirector:
-    """An opener that speaks https only.
+    """An opener that speaks https only and follows no redirect.
 
     ``urlopen`` also opens ``file:``, ``ftp:``, ``data:`` and plain ``http:``
-    addresses. This opener has no handler for them, so neither a caller nor a
-    redirect can reach one: the address fails as an unknown URL type.
+    addresses. This opener has no handler for them, so a caller cannot reach
+    one: the address fails as an unknown URL type. It has no redirect handler
+    either, so a 3xx answer is an ``HTTPError``: urllib's redirect handler
+    would resend the ``Authorization`` header to whichever host the
+    ``Location`` names, and every API these scripts call answers 200 directly.
     """
     opener = urllib.request.OpenerDirector()
     for handler in (
@@ -78,7 +81,6 @@ def _https_opener() -> urllib.request.OpenerDirector:
         urllib.request.UnknownHandler(),
         urllib.request.HTTPSHandler(),
         urllib.request.HTTPDefaultErrorHandler(),
-        urllib.request.HTTPRedirectHandler(),
         urllib.request.HTTPErrorProcessor(),
     ):
         opener.add_handler(handler)
diff --git a/scripts/ci/readme_badges.py b/scripts/ci/readme_badges.py
index 195c9ef2d6..143336eae3 100644
--- a/scripts/ci/readme_badges.py
+++ b/scripts/ci/readme_badges.py
@@ -11,9 +11,10 @@
     readme_badges.py verdict --state DIR/state.json
         Exit 1 when a source failed this run, so the run turns red.
     readme_badges.py check-readme [--readme README.md]
-        Exit 1 when a README image is not a rendered badge, a shields.io
-        badge in for-the-badge with the dark label, or a local image.
-        Offline; pre-commit runs it on every README change.
+        Exit 1 when a README image is not a badge rendered onto this
+        repository's badges branch, a shields.io badge in for-the-badge with
+        the dark label, or a file in the repository. Offline; pre-commit runs
+        it on every README change.
 
 Sources: the latest decisive completed push run of each workflow on the
 default branch (GitHub API with GITHUB_TOKEN), and the OpenSSF Scorecard
@@ -42,6 +43,7 @@
 sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
 
 from scripts.ci import ci_tier
+from scripts.dev.check_repository_security import POLICY as SECURITY_POLICY
 from scripts.lib.safe_subprocess import (
     CommandOutputLimitExceeded,
     CommandTimedOut,
@@ -66,8 +68,11 @@
 AMBER = "#9a6700"
 GREY = "#6e7781"
 SCORE_MAX = 10  # OpenSSF Scorecard scores run from 0 to 10
-SCORE_GREEN = 7.0  # shown score from which the badge is green
-SCORE_AMBER = 4.0  # shown score from which it is amber; red below
+# The unrounded score from which the badge is green: the master requirement in
+# docs/principles.md (ADR-1247). The badge colours the public score only; the
+# exact-head check stays the Scorecard workflow's job.
+SCORE_GREEN = 8.5
+SCORE_AMBER = 4.0  # unrounded score from which it is amber; red below
 TEXT = re.compile(r"[\x20-\x7e]{1,40}")
 COLOR = re.compile(r"#[0-9a-f]{6}")
 
@@ -79,6 +84,12 @@
     "timed_out": FAILING,
     "startup_failure": FAILING,
 }
+# Runs that say nothing about the code: no conclusion yet, cancelled or
+# skipped. The badge looks past them. Any other conclusion of the newest run
+# (action_required, neutral, stale) reads "unknown", never an older run's value.
+# A tuple, not a set: membership then compares and never hashes the API value.
+PASSED_OVER = (None, "cancelled", "skipped")
+UNKNOWN = ("unknown", GREY)
 BEST_PRACTICES = {
     "in_progress": ("in progress", AMBER),
     "passing": PASSING,
@@ -127,28 +138,32 @@ def stamp(moment: datetime) -> str:
 
 
 def workflow_value(runs: object) -> Value:
-    """Value of the newest run that passed or failed; cancelled and skipped runs do not count."""
+    """Value of the newest run that has a conclusion and was not cancelled or skipped.
+
+    That run reads "passing" or "failing" when it passed or failed, "unknown"
+    otherwise; so does an answer with no such run.
+    """
     rows = runs.get("workflow_runs") if isinstance(runs, dict) else None
     if not isinstance(rows, list):
         raise BadgeError("the runs answer has no workflow_runs list")
     for row in rows:
         conclusion = row.get("conclusion") if isinstance(row, dict) else None
-        if conclusion in DECISIVE:
-            return DECISIVE[conclusion]
-    return ("unknown", GREY)
+        if conclusion not in PASSED_OVER:
+            return DECISIVE.get(conclusion, UNKNOWN) if isinstance(conclusion, str) else UNKNOWN
+    return UNKNOWN
 
 
 def scorecard_value(doc: object) -> Value:
-    """OpenSSF Scorecard score out of 10: green from 7, amber from 4, red below.
+    """OpenSSF Scorecard score out of 10: green from 8.5, amber from 4, red below.
 
-    The colour follows the shown one-decimal score, so 6.96 reads "7.0" in green.
+    The colour follows the unrounded score, as the master requirement does, so
+    8.46 reads "8.5 / 10" in amber.
     """
     score = doc.get("score") if isinstance(doc, dict) else None
     if isinstance(score, bool) or not isinstance(score, int | float) or not 0 <= score <= SCORE_MAX:
         raise BadgeError(f"Scorecard score {score!r} is not a number from 0 to 10")
-    shown = round(float(score), 1)
-    color = GREEN if shown >= SCORE_GREEN else AMBER if shown >= SCORE_AMBER else RED
-    return (f"{shown:.1f} / 10", color)
+    color = GREEN if score >= SCORE_GREEN else AMBER if score >= SCORE_AMBER else RED
+    return (f"{float(score):.1f} / 10", color)
 
 
 def best_practices_value(rows: object, repo_url: str) -> Value:
@@ -225,16 +240,25 @@ def usable(entry: object) -> dict[str, str | None] | None:
     return {"message": message, "color": color, "fetched_at": fetched}
 
 
+def read_time(text: str) -> datetime | None:
+    """The time ``text`` names in ISO 8601 with a UTC offset; ``None`` when unreadable or naive."""
+    try:
+        value = datetime.fromisoformat(text)
+    except ValueError:
+        return None
+    return value if value.utcoffset() is not None else None
+
+
 def carried(previous: Mapping[str, str | None] | None, now: datetime) -> dict[str, str | None]:
-    """Keep the last value up to STALE_AFTER after it was read; then show "stale"."""
+    """Keep the last value up to STALE_AFTER after it was read; then show "stale".
+
+    A read time that is unreadable, names no UTC offset or lies in the future
+    counts as stale.
+    """
     fetched = previous.get("fetched_at") if previous else None
-    if previous and fetched:
-        try:
-            age = now - datetime.fromisoformat(fetched)
-        except ValueError:
-            age = None
-        if age is not None and timedelta(0) <= age <= STALE_AFTER:
-            return dict(previous)
+    read_at = read_time(fetched) if previous and fetched else None
+    if previous and read_at is not None and timedelta(0) <= now - read_at <= STALE_AFTER:
+        return dict(previous)
     return {"message": "stale", "color": GREY, "fetched_at": fetched}
 
 
@@ -291,16 +315,22 @@ def field(doc: object, *keys: str) -> object:
 
 
 def previous_state(github: GitHub, repository: str) -> tuple[dict[str, object], str | None]:
-    """Badge entries of the badges branch's state file; none when the branch is new."""
+    """Badge entries of the badges branch's state file; none when the branch is new.
+
+    A failed read other than a 404 raises BadgeError: refreshing without the
+    last values would turn every failing source "stale" at once, so the run
+    stops and the branch keeps what it has. A file that was read but cannot be
+    parsed holds no value worth keeping; it reads as empty, with a failure line.
+    """
     try:
         doc = github(f"/repos/{repository}/contents/{STATE}?ref={BRANCH}")
     except urllib.error.HTTPError as error:
-        error.close()  # it holds the answer body; a 404 or a carried failure ends here
+        error.close()  # it holds the answer body; the 404 and the raise below end here
         if error.code == HTTPStatus.NOT_FOUND:
             return {}, None
-        return {}, f"{STATE}: {error}"
+        raise BadgeError(f"{STATE}: {error}; the badges keep their values") from error
     except (ci_tier.TierError, OSError, ValueError) as error:
-        return {}, f"{STATE}: {error}"
+        raise BadgeError(f"{STATE}: {error}; the badges keep their values") from error
     try:
         text = base64.b64decode(str(field(doc, "content"))).decode("utf-8")
         badges = json.loads(text).get("badges")
@@ -372,8 +402,14 @@ def branch_head(call: Call, repository: str) -> dict[str, str] | None:
 def unchanged(
     call: Call, repository: str, head: Mapping[str, str], files: Mapping[str, bytes], now: datetime
 ) -> bool:
-    """True when every SVG matches the branch and its last commit is younger than QUIET_WINDOW."""
-    if now - datetime.fromisoformat(head["date"]) >= QUIET_WINDOW:
+    """True when every SVG matches the branch and its last commit is younger than QUIET_WINDOW.
+
+    The state file is left out on purpose: its read times change every run, so
+    comparing it would commit every run. The branch's read times therefore
+    trail the newest read by less than QUIET_WINDOW plus one schedule interval.
+    """
+    committed = read_time(head["date"])
+    if committed is None or now - committed >= QUIET_WINDOW:
         return False
     rows = field(call("GET", f"/repos/{repository}/git/trees/{head['tree']}", None), "tree")
     if not isinstance(rows, list):
@@ -385,7 +421,10 @@ def unchanged(
 
 
 def publish(call: Call, repository: str, files: Mapping[str, bytes], now: datetime) -> str:
-    """Commit ``files`` as the whole badges tree; GitHub signs the commit, the ref moves only forward."""
+    """Commit ``files`` as the whole badges tree.
+
+    GitHub signs the commit, and the ref moves only forward.
+    """
     head = branch_head(call, repository)
     if head and unchanged(call, repository, head, files, now):
         return f"unchanged at {head['sha']}"
@@ -409,12 +448,12 @@ def publish(call: Call, repository: str, files: Mapping[str, bytes], now: dateti
     return sha
 
 
-# The one README badge design, as an allow-list: a badge rendered onto the
-# badges branch, a shields.io badge in for-the-badge with the dark label, or a
-# local image. Anything else, a reference-style image whose address this check
-# cannot see included, is a fault. The Praetor-managed governance block may
-# also hold its own GitHub workflow badge until Praetor issue 1893 offers the
-# style; then GOVERNANCE_BADGE goes.
+# The one README badge design, as an allow-list: a badge rendered onto this
+# repository's badges branch, a shields.io badge in for-the-badge with the dark
+# label, or a file in the repository. Anything else, a reference-style image
+# whose address this check cannot see included, is a fault. The Praetor-managed
+# governance block may also hold this repository's own GitHub workflow badge
+# until Praetor issue 1893 offers the style; then governance_badge() goes.
 FENCE = re.compile(r"^(?P<mark>`{3,}|~{3,})[^\n]*\n.*?^(?P=mark)[ \t]*$", re.M | re.S)
 CODE_SPAN = re.compile(r"`[^`\n]+`")
 MANAGED_BLOCK = re.compile(
@@ -426,19 +465,50 @@ def publish(call: Call, repository: str, files: Mapping[str, bytes], now: dateti
 REFERENCE_DEF = re.compile(r"^ {0,3}\[(?P<ref>[^\]\n]+)\]:[ \t]*<?(?P<url>[^\s>]+)>?", re.M)
 HTML_IMAGE = re.compile(r"<(?:img|source)\b[^>]*>", re.I)
 HTML_SOURCE = re.compile(r'\b(?:src|srcset)[ \t]*=[ \t]*"(?P<url>[^"]*)"', re.I)
-RENDERED = re.compile(
-    r"https://raw\.githubusercontent\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+/"
-    + re.escape(BRANCH)
-    + r"/(?P<slug>[a-z0-9-]+)\.svg"
-)
+REPOSITORY_PART = re.compile(r"[A-Za-z0-9_.-]+")
 LOCAL_IMAGE = re.compile(r"[A-Za-z0-9_][A-Za-z0-9_./-]*")
-GOVERNANCE_BADGE = re.compile(
-    r"https://github\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+/actions/workflows/praetor-docs\.yml/badge\.svg"
-)
 SHIELDS_HOST = "img.shields.io"
 SHIELDS_DESIGN = {"style": "for-the-badge", "labelColor": "111a35"}
 
 
+@functools.cache
+def home_repository() -> str:
+    """``owner/name`` of this repository, as its security policy file declares it."""
+    try:
+        name = json.loads(SECURITY_POLICY.read_text(encoding="utf-8"))["repository"]
+    except (OSError, ValueError, KeyError, TypeError) as error:
+        raise BadgeError(f"{SECURITY_POLICY}: no repository name ({error})") from error
+    if not isinstance(name, str):
+        raise BadgeError(f"{SECURITY_POLICY}: repository {name!r} is not owner/name")
+    owner, slash, repo = name.partition("/")
+    if not (slash and REPOSITORY_PART.fullmatch(owner) and REPOSITORY_PART.fullmatch(repo)):
+        raise BadgeError(f"{SECURITY_POLICY}: repository {name!r} is not owner/name")
+    return name
+
+
+def repository_pattern() -> str:
+    """This repository's ``owner/name`` as a regex; GitHub matches both case-insensitively."""
+    return f"(?i:{re.escape(home_repository())})"
+
+
+@functools.cache
+def rendered_badge() -> re.Pattern[str]:
+    """A badge rendered onto this repository's badges branch, with its slug."""
+    return re.compile(
+        rf"https://raw\.githubusercontent\.com/{repository_pattern()}/{re.escape(BRANCH)}"
+        r"/(?P<slug>[a-z0-9-]+)\.svg"
+    )
+
+
+@functools.cache
+def governance_badge() -> re.Pattern[str]:
+    """This repository's own Praetor docs workflow badge; only the governance block may show it."""
+    return re.compile(
+        rf"https://github\.com/{repository_pattern()}"
+        r"/actions/workflows/praetor-docs\.yml/badge\.svg"
+    )
+
+
 def blanked(match: re.Match[str]) -> str:
     """The matched text as spaces, newlines kept, so positions and line numbers stay."""
     return re.sub(r"[^\n]", " ", match[0])
@@ -449,9 +519,27 @@ def local_image(url: str) -> bool:
     return LOCAL_IMAGE.fullmatch(url) is not None and ".." not in url.split("/")
 
 
-def image_fault(url: str) -> str | None:
-    """Why the image at ``url`` breaks the one badge design; ``None`` when it keeps it."""
-    rendered = RENDERED.fullmatch(url)
+def missing_file(url: str, root: Path) -> str | None:
+    """Why the local image ``url`` shows nothing from ``root``; ``None`` when it is a file there.
+
+    The path is resolved with its symbolic links, so a link that leaves
+    ``root`` is a fault as well.
+    """
+    base = root.resolve()
+    target = (base / url).resolve()
+    if not target.is_relative_to(base):
+        return f"{url}: resolves outside {base}"
+    if not target.is_file():
+        return f"{url}: no such file next to the README"
+    return None
+
+
+def image_fault(url: str, root: Path) -> str | None:
+    """Why the image at ``url`` breaks the one badge design; ``None`` when it keeps it.
+
+    ``root`` is the directory of the README, which relative paths start from.
+    """
+    rendered = rendered_badge().fullmatch(url)
     if rendered:
         if rendered["slug"] in {badge.slug for badge in BADGES}:
             return None
@@ -464,7 +552,7 @@ def image_fault(url: str) -> str | None:
         ]
         return f"{url}: a shields.io badge needs {' and '.join(wrong)}" if wrong else None
     if local_image(url):
-        return None
+        return missing_file(url, root)
     return f"{url}: not a rendered badge, a for-the-badge shields.io badge or a local image"
 
 
@@ -481,22 +569,29 @@ def image_url(text: str, start: int, refs: Mapping[str, str]) -> str | None:
 
 
 def markdown_faults(
-    text: str, span: tuple[int, int], refs: Mapping[str, str], extra: re.Pattern[str] | None
+    text: str,
+    span: tuple[int, int],
+    refs: Mapping[str, str],
+    extra: re.Pattern[str] | None,
+    root: Path,
 ) -> list[str]:
-    """One line per Markdown image in ``text[span]`` that breaks the design; ``extra`` also passes."""
+    """One line per Markdown image in ``text[span]`` that breaks the design.
+
+    An image whose address ``extra`` matches passes as well.
+    """
     faults: list[str] = []
     for found in IMAGE_START.finditer(text, *span):
         line = text.count("\n", 0, found.start()) + 1
         url = image_url(text, found.start(), refs)
         if url is None:
             faults.append(f"{line}: an image without an inline address this check can read")
-        elif not (extra and extra.fullmatch(url)) and (fault := image_fault(url)):
+        elif not (extra and extra.fullmatch(url)) and (fault := image_fault(url, root)):
             faults.append(f"{line}: {fault}")
     return faults
 
 
-def html_faults(text: str) -> list[str]:
-    """One line per HTML ``<img>`` or ``<source>`` that shows anything but a local image."""
+def html_faults(text: str, root: Path) -> list[str]:
+    """One line per HTML ``<img>`` or ``<source>`` that shows anything but a local file."""
     faults: list[str] = []
     for tag in HTML_IMAGE.finditer(text):
         line = text.count("\n", 0, tag.start()) + 1
@@ -508,16 +603,19 @@ def html_faults(text: str) -> list[str]:
         ]
         if not urls:
             faults.append(f"{line}: an HTML image without a double-quoted src or srcset")
-        faults += [
-            f"{line}: {url}: an HTML image must be a local file"
-            for url in urls
-            if not local_image(url)
-        ]
+        for url in urls:
+            if not local_image(url):
+                faults.append(f"{line}: {url}: an HTML image must be a local file")
+            elif fault := missing_file(url, root):
+                faults.append(f"{line}: {fault}")
     return faults
 
 
-def design_faults(readme: str) -> list[str]:
-    """Every image in ``readme`` that breaks the one badge design, as ``line: reason``."""
+def design_faults(readme: str, root: Path) -> list[str]:
+    """Every image in ``readme`` that breaks the one badge design, as ``line: reason``.
+
+    ``root`` is the directory of the README, which relative paths start from.
+    """
     text = CODE_SPAN.sub(blanked, FENCE.sub(blanked, readme))
     faults: list[str] = []
     for block in MANAGED_BLOCK.finditer(text):
@@ -525,20 +623,22 @@ def design_faults(readme: str) -> list[str]:
             d["ref"].strip().lower(): d["url"]
             for d in REFERENCE_DEF.finditer(text, block.start(), block.end())
         }
-        faults += markdown_faults(text, block.span(), refs, GOVERNANCE_BADGE)
+        faults += markdown_faults(text, block.span(), refs, governance_badge(), root)
     outside = MANAGED_BLOCK.sub(blanked, text)
-    faults += markdown_faults(outside, (0, len(outside)), {}, None)
-    faults += html_faults(text)
+    faults += markdown_faults(outside, (0, len(outside)), {}, None, root)
+    faults += html_faults(text, root)
     return sorted(faults, key=lambda fault: int(fault.split(":", 1)[0]))
 
 
 def cmd_check_readme(args: argparse.Namespace) -> int:
-    faults = design_faults(args.readme.read_text(encoding="utf-8"))
+    readme = args.readme.resolve()
+    faults = design_faults(readme.read_text(encoding="utf-8"), readme.parent)
     for fault in faults:
         print(f"{args.readme}:{fault}", file=sys.stderr)
     if faults:
         print(
-            f"{len(faults)} README images break the one badge design (docs/development/readme-badges.md)",
+            f"{len(faults)} README images break the one badge design"
+            " (docs/development/readme-badges.md)",
             file=sys.stderr,
         )
         return 1
@@ -594,7 +694,8 @@ def cmd_verdict(args: argparse.Namespace) -> int:
         print(f"::error title=Badge source failed::{line}")
     if failures:
         print(
-            f"{len(failures)} badge sources failed; the badges keep their last value up to {STALE_AFTER}"
+            f"{len(failures)} badge sources failed;"
+            f" the badges keep their last value up to {STALE_AFTER}"
         )
         return 1
     print("every badge source answered")
diff --git a/scripts/ci/tests/test_ci_tier.py b/scripts/ci/tests/test_ci_tier.py
index 5a08a848e2..0cd6a0c56f 100644
--- a/scripts/ci/tests/test_ci_tier.py
+++ b/scripts/ci/tests/test_ci_tier.py
@@ -256,21 +256,35 @@ def test_a_non_https_address_fails_without_being_opened(self) -> None:
             ):
                 ci_tier.HTTPS_OPENER.open(url, timeout=1)
 
-    def test_a_redirect_off_https_is_not_followed(self) -> None:
-        for target in ("http://h/y", "ftp://h/y", "file:///etc/passwd"):
-            with (
-                self.subTest(target=target),
-                mock.patch.object(
-                    urllib.request.HTTPSHandler,
-                    "https_open",
-                    return_value=self.response(302, target),
-                ) as https_open,
-            ):
-                with self.assertRaises(urllib.error.URLError) as raised:
-                    ci_tier.HTTPS_OPENER.open("https://h/x", timeout=1)
-                if isinstance(raised.exception, urllib.error.HTTPError):
+    def test_a_redirect_is_not_followed(self) -> None:
+        # An https target too: following it would resend the Authorization header.
+        targets = ("https://other.example/y", "http://h/y", "ftp://h/y", "file:///etc/passwd")
+        for code in (301, 302, 307, 308):
+            for target in targets:
+                with (
+                    self.subTest(code=code, target=target),
+                    mock.patch.object(
+                        urllib.request.HTTPSHandler,
+                        "https_open",
+                        return_value=self.response(code, target),
+                    ) as https_open,
+                ):
+                    with self.assertRaises(urllib.error.HTTPError) as raised:
+                        ci_tier.HTTPS_OPENER.open("https://h/x", timeout=1)
                     raised.exception.close()
-                self.assertEqual(https_open.call_count, 1)
+                    self.assertEqual(raised.exception.code, code)
+                    self.assertEqual(https_open.call_count, 1)
+
+    def test_an_error_answer_is_an_http_error(self) -> None:
+        with (
+            mock.patch.object(
+                urllib.request.HTTPSHandler, "https_open", return_value=self.response(404)
+            ),
+            self.assertRaises(urllib.error.HTTPError) as raised,
+        ):
+            ci_tier.HTTPS_OPENER.open("https://h/x", timeout=1)
+        raised.exception.close()
+        self.assertEqual(raised.exception.code, 404)
 
 
 class Config(unittest.TestCase):
diff --git a/scripts/ci/tests/test_readme_badges.py b/scripts/ci/tests/test_readme_badges.py
index 0afe7ed799..bc553159b4 100644
--- a/scripts/ci/tests/test_readme_badges.py
+++ b/scripts/ci/tests/test_readme_badges.py
@@ -10,6 +10,7 @@
 import io
 import json
 import re
+import secrets
 import sys
 import tempfile
 import unittest
@@ -74,9 +75,26 @@ def test_every_failing_conclusion_is_failing(self) -> None:
 
     def test_an_unfinished_or_cancelled_run_does_not_mask_a_failure(self) -> None:
         # Planted case of the red-reader miss: the newest run had no conclusion yet.
-        answer = runs(None, "cancelled", "skipped", "action_required", "failure", "success")
+        answer = runs(None, "cancelled", "skipped", "failure", "success")
         self.assertEqual(rb.workflow_value(answer), rb.FAILING)
 
+    def test_any_other_newest_conclusion_is_unknown_not_an_older_value(self) -> None:
+        # Planted case from the pull request 3393 review: action_required read
+        # as the older success behind it.
+        conclusions: tuple[object, ...] = (
+            "action_required",
+            "neutral",
+            "stale",
+            "new_kind",
+            7,
+            ["x"],
+            {},
+        )
+        for conclusion in conclusions:
+            with self.subTest(conclusion=conclusion):
+                answer = runs("cancelled", conclusion, "success")
+                self.assertEqual(rb.workflow_value(answer), ("unknown", rb.GREY))
+
     def test_no_decisive_run_is_unknown(self) -> None:
         self.assertEqual(rb.workflow_value(runs()), ("unknown", rb.GREY))
         self.assertEqual(rb.workflow_value(runs("cancelled", None)), ("unknown", rb.GREY))
@@ -94,12 +112,16 @@ def test_an_answer_without_a_run_list_is_refused(self) -> None:
 
 class ScorecardValue(unittest.TestCase):
     def test_colour_boundaries(self) -> None:
+        # Green from the unrounded 8.5 of docs/principles.md (ADR-1247), so a
+        # score shown as "8.5" can still be amber.
         cases = {
             10: ("10.0 / 10", rb.GREEN),
-            7.0: ("7.0 / 10", rb.GREEN),
-            6.96: ("7.0 / 10", rb.GREEN),
-            6.9: ("6.9 / 10", rb.AMBER),
+            8.5: ("8.5 / 10", rb.GREEN),
+            8.46: ("8.5 / 10", rb.AMBER),
+            7.0: ("7.0 / 10", rb.AMBER),
+            6.96: ("7.0 / 10", rb.AMBER),
             4: ("4.0 / 10", rb.AMBER),
+            3.96: ("4.0 / 10", rb.RED),
             3.9: ("3.9 / 10", rb.RED),
             0: ("0.0 / 10", rb.RED),
         }
@@ -116,6 +138,10 @@ def test_an_answer_that_is_not_an_object_is_refused(self) -> None:
         with self.assertRaises(rb.BadgeError):
             rb.scorecard_value([8.9])
 
+    def test_green_starts_at_the_master_requirement(self) -> None:
+        principles = (ROOT / "docs/principles.md").read_text(encoding="utf-8")
+        self.assertIn(f"{rb.SCORE_GREEN}", principles)
+
 
 class BestPracticesValue(unittest.TestCase):
     URL = "https://github.com/VMAFx/vmafx"
@@ -241,10 +267,24 @@ def test_one_second_past_six_hours_reads_stale(self) -> None:
         self.assertEqual(got, {"message": "stale", "color": rb.GREY, "fetched_at": fetched})
 
     def test_a_future_or_unreadable_time_reads_stale(self) -> None:
-        for fetched in (rb.stamp(NOW + timedelta(seconds=1)), "yesterday"):
+        # The naive times are planted cases from the pull request 3393 review:
+        # they raised TypeError and stopped the run.
+        naive = ("2026-11-10T12:00:00", "2026-11-10")
+        for fetched in (rb.stamp(NOW + timedelta(seconds=1)), "yesterday", *naive):
             with self.subTest(fetched=fetched):
                 self.assertEqual(rb.carried(entry(fetched=fetched), NOW)["message"], "stale")
 
+    def test_a_time_with_any_utc_offset_is_read(self) -> None:
+        for fetched in ("2026-11-10T13:00:00+01:00", "2026-11-10T12:00:00+00:00"):
+            with self.subTest(fetched=fetched):
+                self.assertEqual(rb.carried(entry(fetched=fetched), NOW)["message"], "passing")
+
+    def test_read_time_needs_an_offset(self) -> None:
+        self.assertEqual(rb.read_time(rb.stamp(NOW)), NOW)
+        for text in ("2026-11-10T12:00:00", "2026-11-10", "", "noon"):
+            with self.subTest(text=text):
+                self.assertIsNone(rb.read_time(text))
+
     def test_no_previous_value_reads_stale(self) -> None:
         self.assertEqual(rb.carried(None, NOW)["message"], "stale")
         self.assertEqual(
@@ -310,20 +350,32 @@ def test_a_new_branch_has_no_state_and_no_problem(self) -> None:
         self.assertEqual(rb.previous_state(self.fetch(http_error(404)), REPO), ({}, None))
 
     def test_a_handled_error_is_closed(self) -> None:
-        for code in (404, 500):
-            with self.subTest(code=code):
-                error = http_error(code)
-                rb.previous_state(self.fetch(error), REPO)
-                self.assertTrue(error.fp.closed)
+        missing = http_error(404)
+        rb.previous_state(self.fetch(missing), REPO)
+        self.assertTrue(missing.fp.closed)
+        failed = http_error(500)
+        with self.assertRaises(rb.BadgeError):
+            rb.previous_state(self.fetch(failed), REPO)
+        self.assertTrue(failed.fp.closed)
 
     def test_the_badges_of_the_state_file_are_read(self) -> None:
         text = json.dumps({"badges": {"go": entry()}}).encode()
         doc = {"content": base64.b64encode(text).decode()}
         self.assertEqual(rb.previous_state(self.fetch(doc), REPO), ({"go": entry()}, None))
 
+    def test_a_failed_read_stops_the_run(self) -> None:
+        # Planted case from the pull request 3393 review: a failed read returned
+        # no state, so every failing source turned "stale" at once.
+        failed = (http_error(500), OSError("down"), ci_tier.TierError("too large"), ValueError("x"))
+        for answer in failed:
+            with (
+                self.subTest(answer=type(answer).__name__),
+                self.assertRaisesRegex(rb.BadgeError, "the badges keep their values"),
+            ):
+                rb.previous_state(self.fetch(answer), REPO)
+
     def test_an_unreadable_state_is_a_problem_not_a_crash(self) -> None:
-        unreadable = (http_error(500), OSError("down"), ci_tier.TierError("too large"))
-        for answer in (*unreadable, {}, {"content": "!!"}, {"content": ""}, {"content": 7}):
+        for answer in ({}, {"content": "!!"}, {"content": ""}, {"content": 7}):
             with self.subTest(answer=answer):
                 badges, problem = rb.previous_state(self.fetch(answer), REPO)
                 self.assertEqual(badges, {})
@@ -366,15 +418,11 @@ def test_a_non_https_source_is_refused_before_any_request(self) -> None:
 
 class Collect(unittest.TestCase):
     def setUp(self) -> None:
-        self.tmp = tempfile.TemporaryDirectory()
-        self.dir = Path(self.tmp.name)
+        self.dir = Path(self.enterContext(tempfile.TemporaryDirectory()))
         for badge in rb.BADGES:
             (self.dir / f"{badge.slug}.svg").write_text('<svg xmlns="x"></svg>\n', encoding="utf-8")
         (self.dir / "state.json").write_text("{}\n", encoding="utf-8")
 
-    def tearDown(self) -> None:
-        self.tmp.cleanup()
-
     def test_one_svg_per_badge_and_the_state_file(self) -> None:
         self.assertEqual(len(rb.collect(self.dir, rb.BADGES)), len(rb.BADGES) + 1)
 
@@ -494,6 +542,12 @@ def test_same_svgs_inside_the_quiet_window_commit_nothing(self) -> None:
         self.assertEqual(rb.publish(call, REPO, self.FILES, NOW), "unchanged at c0")
         self.assertFalse([c for c in calls if c[0] != "GET"])
 
+    def test_a_naive_or_unreadable_head_date_commits(self) -> None:
+        for date in ("2026-11-10T11:59:00", "2026-11-10", "soon"):
+            with self.subTest(date=date):
+                call, _ = self.fake("c0", date=date)
+                self.assertEqual(rb.publish(call, REPO, self.FILES, NOW), "c1")
+
     def test_a_changed_svg_inside_the_quiet_window_is_committed(self) -> None:
         young = rb.stamp(NOW - timedelta(minutes=5))
         call, _ = self.fake(
@@ -580,6 +634,20 @@ def test_spec_and_publish_need_the_repository_and_a_token(self) -> None:
                 self.assertEqual(rb.main(argv, env={"GITHUB_REPOSITORY": REPO}), 2)
             self.assertIn("set GITHUB_TOKEN", err.getvalue())
 
+    def test_a_failed_state_read_writes_nothing_to_publish(self) -> None:
+        def fail(*_args: object) -> object:
+            raise http_error(503)
+
+        env = {"GITHUB_REPOSITORY": REPO, "GITHUB_TOKEN": secrets.token_urlsafe(8)}
+        with tempfile.TemporaryDirectory() as tmp:
+            spec, state = Path(tmp) / "spec.json", Path(tmp) / "badges/state.json"
+            err = io.StringIO()
+            with mock.patch.object(ci_tier, "api_request", side_effect=fail), redirect_stderr(err):
+                argv = ["spec", "--spec", str(spec), "--state", str(state)]
+                self.assertEqual(rb.main(argv, env=env), 2)
+            self.assertFalse(spec.exists() or state.exists())
+        self.assertIn("the badges keep their values", err.getvalue())
+
 
 SHIELDS = "https://img.shields.io/badge/C-23-3b82f6?style=for-the-badge&labelColor=111a35"
 GOVERNANCE = "https://github.com/vmafx/vmafx/actions/workflows/praetor-docs.yml/badge.svg"
@@ -607,9 +675,10 @@ def test_the_one_design_passes(self) -> None:
             "https://img.shields.io/static/v1?label=release&message=v1&style=for-the-badge&color=3b82f6&labelColor=111a35",
             "docs/assets/vmafx-readme-banner.svg",
         ]
+        allowed.append("https://raw.githubusercontent.com/vmafx/VMAFX/badges/tests.svg")
         for url in allowed:
             with self.subTest(url=url):
-                self.assertIsNone(rb.image_fault(url))
+                self.assertIsNone(rb.image_fault(url, ROOT))
 
     def test_another_design_or_host_is_a_fault(self) -> None:
         refused = {
@@ -621,6 +690,13 @@ def test_another_design_or_host_is_a_fault(self) -> None:
             "http://img.shields.io/badge/C-23-3b82f6?style=for-the-badge&labelColor=111a35": "not a rendered",
             f"https://raw.githubusercontent.com/{REPO}/badges/coverage.svg": "no rendered badge is named 'coverage'",
             f"https://raw.githubusercontent.com/{REPO}/master/tests.svg": "not a rendered",
+            # Planted cases from the pull request 3393 review: other repositories.
+            "https://raw.githubusercontent.com/someone/vmafx/badges/tests.svg": "not a rendered",
+            "https://raw.githubusercontent.com/VMAFx/vmafx-fork/badges/tests.svg": "not a rendered",
+            "https://raw.githubusercontent.com/VMAFx/vmafx/badges/x/tests.svg": "not a rendered",
+            # Planted cases from the pull request 3393 review: missing files.
+            "docs/assets/no-such-banner.svg": "no such file next to the README",
+            "docs/assets": "no such file next to the README",
             "/docs/assets/banner.svg": "not a rendered",
             "../banner.svg": "not a rendered",
             "docs/../../banner.svg": "not a rendered",
@@ -629,7 +705,19 @@ def test_another_design_or_host_is_a_fault(self) -> None:
         }
         for url, reason in refused.items():
             with self.subTest(url=url):
-                self.assertIn(reason, rb.image_fault(url) or "")
+                self.assertIn(reason, rb.image_fault(url, ROOT) or "")
+
+    def test_a_link_out_of_the_readme_directory_is_a_fault(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root, outside = Path(tmp) / "repo", Path(tmp) / "outside.svg"
+            root.mkdir()
+            outside.write_text("<svg/>", encoding="utf-8")
+            (root / "inside.svg").write_text("<svg/>", encoding="utf-8")
+            (root / "link.svg").symlink_to(outside)
+            (root / "local-link.svg").symlink_to(root / "inside.svg")
+            self.assertIn("resolves outside", rb.image_fault("link.svg", root) or "")
+            self.assertIsNone(rb.image_fault("inside.svg", root))
+            self.assertIsNone(rb.image_fault("local-link.svg", root))
 
     def test_a_repeated_or_empty_design_parameter_is_a_fault(self) -> None:
         for query in (
@@ -640,34 +728,88 @@ def test_a_repeated_or_empty_design_parameter_is_a_fault(self) -> None:
         ):
             with self.subTest(query=query):
                 self.assertIsNotNone(
-                    rb.image_fault(f"https://img.shields.io/badge/C-23-3b82f6?{query}")
+                    rb.image_fault(f"https://img.shields.io/badge/C-23-3b82f6?{query}", ROOT)
                 )
 
 
+class HomeRepository(unittest.TestCase):
+    def setUp(self) -> None:
+        self.clear()
+        self.addCleanup(self.clear)
+
+    @staticmethod
+    def clear() -> None:
+        for cached in (rb.home_repository, rb.rendered_badge, rb.governance_badge):
+            cached.cache_clear()
+
+    def test_the_policy_names_this_repository(self) -> None:
+        self.assertEqual(rb.home_repository(), REPO)
+
+    def test_a_missing_or_malformed_policy_is_a_badge_error(self) -> None:
+        for text in (
+            None,
+            "{",
+            "[]",
+            "{}",
+            '{"repository": 7}',
+            '{"repository": "vmafx"}',
+            '{"repository": "a/b/c"}',
+            '{"repository": "a b/c"}',
+            '{"repository": "/c"}',
+        ):
+            with self.subTest(text=text), tempfile.TemporaryDirectory() as tmp:
+                policy = Path(tmp) / "policy.json"
+                if text is not None:
+                    policy.write_text(text, encoding="utf-8")
+                with mock.patch.object(rb, "SECURITY_POLICY", policy):
+                    self.clear()
+                    with self.assertRaises(rb.BadgeError):
+                        rb.home_repository()
+                    self.clear()
+
+    def test_the_rendered_badge_follows_the_policy(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            policy = Path(tmp) / "policy.json"
+            policy.write_text('{"repository": "adopter/fork"}', encoding="utf-8")
+            with mock.patch.object(rb, "SECURITY_POLICY", policy):
+                self.clear()
+                ours = "https://raw.githubusercontent.com/adopter/fork/badges/tests.svg"
+                self.assertIsNone(rb.image_fault(ours, ROOT))
+                theirs = f"https://raw.githubusercontent.com/{REPO}/badges/tests.svg"
+                self.assertIn("not a rendered", rb.image_fault(theirs, ROOT) or "")
+                self.clear()
+
+
 class DesignFaults(unittest.TestCase):
     def test_the_readme_has_the_one_design(self) -> None:
-        self.assertEqual(rb.design_faults((ROOT / "README.md").read_text(encoding="utf-8")), [])
+        self.assertEqual(
+            rb.design_faults((ROOT / "README.md").read_text(encoding="utf-8"), ROOT), []
+        )
 
     def test_an_empty_readme_has_no_fault(self) -> None:
-        self.assertEqual(rb.design_faults(""), [])
+        self.assertEqual(rb.design_faults("", ROOT), [])
 
     def test_a_fault_names_its_line(self) -> None:
         readme = "# Title\n\n" + image(SHIELDS.replace("for-the-badge", "flat-square"))
         self.assertEqual(
-            rb.design_faults(readme),
+            rb.design_faults(readme, ROOT),
             [
                 f"3: {SHIELDS.replace('for-the-badge', 'flat-square')}: a shields.io badge needs style=for-the-badge"
             ],
         )
 
     def test_the_governance_block_may_hold_its_own_badge(self) -> None:
-        self.assertEqual(rb.design_faults("# Title\n\n" + BLOCK), [])
+        self.assertEqual(rb.design_faults("# Title\n\n" + BLOCK, ROOT), [])
 
     def test_the_block_exception_covers_only_the_governance_badge(self) -> None:
         flat = BLOCK.replace(GOVERNANCE, SHIELDS.replace("for-the-badge", "flat-square"))
-        self.assertEqual(len(rb.design_faults(flat)), 1)
+        self.assertEqual(len(rb.design_faults(flat, ROOT)), 1)
         unresolved = BLOCK.replace("[docs-badge]:", "[other]:")
-        self.assertIn("without an inline address", rb.design_faults(unresolved)[0])
+        self.assertIn("without an inline address", rb.design_faults(unresolved, ROOT)[0])
+
+    def test_another_repository_governance_badge_is_a_fault(self) -> None:
+        other = GOVERNANCE.replace("vmafx/vmafx", "someone/vmafx")
+        self.assertEqual(len(rb.design_faults(BLOCK.replace(GOVERNANCE, other), ROOT)), 1)
 
     def test_the_governance_badge_outside_the_block_is_a_fault(self) -> None:
         for readme in (
@@ -676,7 +818,7 @@ def test_the_governance_badge_outside_the_block_is_a_fault(self) -> None:
             BLOCK.replace("<!-- praetor:readme-governance:start -->\n", ""),
         ):
             with self.subTest(readme=readme[:40]):
-                self.assertNotEqual(rb.design_faults(readme), [])
+                self.assertNotEqual(rb.design_faults(readme, ROOT), [])
 
     def test_a_reference_style_image_outside_the_block_is_a_fault(self) -> None:
         for readme in (
@@ -686,7 +828,7 @@ def test_a_reference_style_image_outside_the_block_is_a_fault(self) -> None:
         ):
             with self.subTest(readme=readme.splitlines()[0]):
                 self.assertEqual(
-                    rb.design_faults(readme),
+                    rb.design_faults(readme, ROOT),
                     ["1: an image without an inline address this check can read"],
                 )
 
@@ -698,43 +840,52 @@ def test_code_is_not_an_image(self) -> None:
             f"Write `![x]({flat})` for a badge.\n",
         ):
             with self.subTest(readme=readme.splitlines()[0]):
-                self.assertEqual(rb.design_faults(readme), [])
+                self.assertEqual(rb.design_faults(readme, ROOT), [])
 
     def test_an_unclosed_fence_hides_nothing(self) -> None:
         flat = SHIELDS.replace("for-the-badge", "flat-square")
-        self.assertEqual(len(rb.design_faults(f"```\n![x]({flat})\n")), 1)
+        self.assertEqual(len(rb.design_faults(f"```\n![x]({flat})\n", ROOT)), 1)
 
     def test_an_html_image_must_be_a_local_file(self) -> None:
         passing = (
-            '<img src="docs/assets/vmafx-readme-banner.svg" alt="VMAFx" height="120" />\n',
+            '<img src="docs/a.svg" alt="VMAFx" height="120" />\n',
             '<picture><source media="(prefers-color-scheme: dark)" srcset="docs/a.svg 2x, docs/b.svg"></picture>\n',
         )
-        for readme in passing:
-            with self.subTest(readme=readme):
-                self.assertEqual(rb.design_faults(readme), [])
         failing = (
             f'<img src="{SHIELDS}">\n',
             f'<IMG SRC="{GOVERNANCE}">\n',
             f'<source srcset="docs/a.svg 1x, {SHIELDS} 2x">\n',
             '<img alt="no source">\n',
             f"<img src='{SHIELDS}'>\n",
+            '<img src="docs/c.svg">\n',
+            '<source srcset="docs/a.svg 1x, docs/c.svg 2x">\n',
         )
-        for readme in failing:
-            with self.subTest(readme=readme):
-                self.assertEqual(len(rb.design_faults(readme)), 1)
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "docs").mkdir()
+            for name in ("a.svg", "b.svg"):
+                (root / "docs" / name).write_text("<svg/>", encoding="utf-8")
+            for readme in passing:
+                with self.subTest(readme=readme):
+                    self.assertEqual(rb.design_faults(readme, root), [])
+            for readme in failing:
+                with self.subTest(readme=readme):
+                    self.assertEqual(len(rb.design_faults(readme, root)), 1)
 
     def test_faults_come_in_line_order(self) -> None:
         readme = f'<img src="{SHIELDS}">\n' + image(GOVERNANCE) + f'<img src="{SHIELDS}">\n'
-        lines = [int(fault.split(":", 1)[0]) for fault in rb.design_faults(readme)]
+        lines = [int(fault.split(":", 1)[0]) for fault in rb.design_faults(readme, ROOT)]
         self.assertEqual(lines, [1, 2, 3])
 
 
 class CheckReadme(unittest.TestCase):
-    def check(self, text: str | None) -> tuple[int, str, str]:
+    def check(self, text: str | None, files: tuple[str, ...] = ()) -> tuple[int, str, str]:
         with tempfile.TemporaryDirectory() as tmp:
             readme = Path(tmp) / "README.md"
             if text is not None:
                 readme.write_text(text, encoding="utf-8")
+            for name in files:
+                (Path(tmp) / name).write_text("<svg/>", encoding="utf-8")
             out, err = io.StringIO(), io.StringIO()
             with redirect_stdout(out), redirect_stderr(err):
                 rc = rb.main(["check-readme", "--readme", str(readme)], env={})
@@ -754,6 +905,12 @@ def test_a_fault_fails_with_file_and_line(self) -> None:
     def test_a_missing_readme_is_an_error(self) -> None:
         self.assertEqual(self.check(None)[0], 2)
 
+    def test_a_local_image_is_looked_up_next_to_the_readme(self) -> None:
+        self.assertEqual(self.check(image("banner.svg"), files=("banner.svg",))[0], 0)
+        rc, _, err = self.check(image("banner.svg"))
+        self.assertEqual(rc, 1)
+        self.assertIn("banner.svg: no such file next to the README", err)
+
 
 class Consistency(unittest.TestCase):
     def test_render_mjs_allows_the_same_text_and_colours(self) -> None:
@@ -768,6 +925,30 @@ def test_every_workflow_badge_names_a_workflow_by_its_name(self) -> None:
                 first = re.search(r"^name: (.+)$", path.read_text(encoding="utf-8"), re.M)
                 self.assertEqual(first.group(1).strip() if first else None, badge.label)
 
+    def test_the_workflow_runs_only_on_the_policy_repository_and_branch(self) -> None:
+        policy = json.loads(
+            (ROOT / ".github/repository-security-policy.json").read_text(encoding="utf-8")
+        )
+        workflow = (ROOT / ".github/workflows/readme-badges.yml").read_text(encoding="utf-8")
+        self.assertIn(f"github.repository == '{policy['repository']}'", workflow)
+        self.assertIn(f"github.ref == 'refs/heads/{policy['default_branch']}'", workflow)
+        # Both jobs check out the commit the run started from, so a master push
+        # between them cannot change the code the publisher runs.
+        self.assertEqual(workflow.count("ref: ${{ github.sha }}"), 2)
+        self.assertNotRegex(workflow, r"ref: (?!\$\{\{ github\.sha \}\})")
+
+    def test_a_carried_read_time_trails_by_less_than_the_stale_bound(self) -> None:
+        # The state file is committed with the SVGs only once QUIET_WINDOW has
+        # passed, so its read times trail the newest read by at most that plus
+        # one schedule gap; that lag must stay well inside STALE_AFTER.
+        workflow = (ROOT / ".github/workflows/readme-badges.yml").read_text(encoding="utf-8")
+        cron = re.search(r'cron: "(?P<minutes>[0-9,]+) \* \* \* \*"', workflow)
+        self.assertIsNotNone(cron)
+        minutes = sorted(int(m) for m in cron["minutes"].split(",")) if cron else []
+        gaps = [b - a for a, b in zip(minutes, [*minutes[1:], minutes[0] + 60], strict=True)]
+        lag = rb.QUIET_WINDOW + timedelta(minutes=max(gaps))
+        self.assertLess(lag, rb.STALE_AFTER / 4)
+
     def test_the_readme_shows_every_badge_once_with_its_label(self) -> None:
         readme = (ROOT / "README.md").read_text(encoding="utf-8")
         shown = [(m["slug"], m["alt"]) for m in RAW.finditer(readme)]

From 42f91a41b733d84d4341d2f6ba82ba8f67910059 Mon Sep 17 00:00:00 2001
From: lusoris <lusoris@proton.me>
Date: Tue, 10 Nov 2026 20:27:37 +0100
Subject: [PATCH 4/7] docs(ci): document the badge code and link the badges
 branch follow-up

CodeRabbit's docstring-coverage check on pull request 3393 read 32.05
percent against its 80 percent bar. Every function and class this pull
request adds or changes in the badge script, its tests, the ci_tier
tests and the renderer now carries a docstring or JSDoc block, 203 of
203 counted over the diff against master.

The review left one finding open on purpose: any token with contents:
write can push to the badges branch, because a ruleset cannot name the
workflow token as its only bypass actor. Issue 3394 tracks a dedicated
GitHub App as the publisher with its own badges ruleset. ADR-3519, its
research digest and the badge guide now name that issue and the gap, and
ADR-3519 records the answer to land on the workflow token first. The
ruleset that only refuses deletion and non-fast-forward updates is
dropped as a follow-up of its own, since it would not stop a writer.

Signed-off-by: lusoris <lusoris@proton.me>
---
 .../adr/3519-readme-badges-rendered-branch.md |  22 ++-
 docs/development/readme-badges.md             |   6 +-
 .../3519-readme-badges-rendered-branch.md     |   2 +-
 scripts/ci/readme_badges.py                   |   9 +
 scripts/ci/tests/test_ci_tier.py              |  18 ++
 scripts/ci/tests/test_readme_badges.py        | 163 ++++++++++++++++++
 tools/badges/render.mjs                       |  14 ++
 7 files changed, 224 insertions(+), 10 deletions(-)

diff --git a/docs/adr/3519-readme-badges-rendered-branch.md b/docs/adr/3519-readme-badges-rendered-branch.md
index 9ad70bc729..503d61bc58 100644
--- a/docs/adr/3519-readme-badges-rendered-branch.md
+++ b/docs/adr/3519-readme-badges-rendered-branch.md
@@ -64,14 +64,16 @@ governance badge, which Praetor writes. The full rules are in
   hours count from the read time `state.json` records, which an unchanged
   badge refreshes only once an hour, so `stale` can come up to 75 minutes
   early; committing on every run would quadruple the branch's growth.
-- **Neutral / follow-ups**: a ruleset for the `badges` branch in
-  `.github/repository-security-policy.json` (deletion and non-fast-forward
-  refused); the Praetor governance badge in the `praetor:readme-governance`
-  block keeps GitHub's design until Praetor offers the style (Praetor issue
-  1893), and `check-readme` then drops its one exception. Publishing with a
-  GitHub App token instead of the workflow token, so that a `badges` ruleset
-  can refuse every other writer, is open. This style is the reference for the
-  ecosystem README badge audit.
+- **Neutral / follow-ups**: issue 3394 tracks publishing with a dedicated
+  GitHub App token instead of the workflow token, plus a second ruleset on
+  `refs/heads/badges`, managed by `scripts/dev/check_repository_security.py`,
+  that lets only that App write the branch. A ruleset that only refuses
+  deletion and non-fast-forward updates would still let any writer add
+  commits, so it is not a follow-up on its own. The Praetor governance badge
+  in the `praetor:readme-governance` block keeps GitHub's design until
+  Praetor offers the style (Praetor issue 1893), and `check-readme` then
+  drops its one exception. This style is the reference for the ecosystem
+  README badge audit.
 
 ## References
 
@@ -86,6 +88,10 @@ governance badge, which Praetor writes. The full rules are in
   least rights, a stale marker after six hours; it answers the operator order
   `vmafx-readme-badges-and-lint-red-20261110` (paraphrased: the README badge
   row mixes designs).
+- Operator answer `vmafx-badges-app-token-ruleset` (2026-11-10, option a,
+  paraphrased): land on the workflow token now, and harden the `badges`
+  branch with a GitHub App token and its own ruleset as a follow-up
+  (issue 3394).
 - [ADR-3366](3366-readme-presentation-standard.md): the README presentation
   standard.
 - shields.io GitHub Actions workflow status service:
diff --git a/docs/development/readme-badges.md b/docs/development/readme-badges.md
index 36482b8e28..3f650b2627 100644
--- a/docs/development/readme-badges.md
+++ b/docs/development/readme-badges.md
@@ -78,7 +78,11 @@ GitHub API:
 The job's token has `contents: write`, the narrowest right that can make a
 commit. GitHub cannot limit that right to one branch; the script writes only
 `refs/heads/badges`, and the master ruleset requires a pull request, so the
-token cannot move `master`.
+token cannot move `master`. No ruleset guards `badges` yet, so any other
+token with `contents: write` (another workflow, an installed app, a person
+with write access) can push to it too. Issue 3394 tracks a dedicated GitHub
+App as the only publisher, with a `badges` ruleset that refuses every other
+writer.
 
 Both jobs run only on the default branch (`github.ref` is
 `refs/heads/master`): a manual run started on another branch does nothing, so
diff --git a/docs/research/3519-readme-badges-rendered-branch.md b/docs/research/3519-readme-badges-rendered-branch.md
index 730896fde2..51c04b233a 100644
--- a/docs/research/3519-readme-badges-rendered-branch.md
+++ b/docs/research/3519-readme-badges-rendered-branch.md
@@ -51,7 +51,7 @@ How can the ten README status badges (seven workflow badges, OpenSSF Scorecard,
 
 ## Open questions
 
-- Publishing with a dedicated GitHub App token plus a second managed ruleset on `badges`, so that no other workflow can write the branch. `check_repository_security.py` manages one ruleset today; a second one needs a policy change and an App installation.
+- Publishing with a dedicated GitHub App token plus a second managed ruleset on `badges`, so that no other workflow can write the branch. `check_repository_security.py` manages one ruleset today; a second one needs a policy change and an App installation. Tracked in issue 3394.
 - The Praetor governance badge keeps GitHub's design until Praetor offers the style (Praetor issue 1893).
 
 ## Related
diff --git a/scripts/ci/readme_badges.py b/scripts/ci/readme_badges.py
index 143336eae3..b611dad15a 100644
--- a/scripts/ci/readme_badges.py
+++ b/scripts/ci/readme_badges.py
@@ -631,6 +631,7 @@ def design_faults(readme: str, root: Path) -> list[str]:
 
 
 def cmd_check_readme(args: argparse.Namespace) -> int:
+    """Print every design fault of the README; 1 when there is one."""
     readme = args.readme.resolve()
     faults = design_faults(readme.read_text(encoding="utf-8"), readme.parent)
     for fault in faults:
@@ -647,15 +648,18 @@ def cmd_check_readme(args: argparse.Namespace) -> int:
 
 
 def write_json(path: Path, doc: object) -> None:
+    """Write ``doc`` as sorted, indented JSON, creating the parent directory."""
     path.parent.mkdir(parents=True, exist_ok=True)
     path.write_text(json.dumps(doc, indent=2, sort_keys=True) + "\n", encoding="utf-8")
 
 
 def cmd_spec(args: argparse.Namespace, env: Mapping[str, str], now: datetime) -> int:
+    """Read every source, then write the render list and the new state."""
     repository, token = env["GITHUB_REPOSITORY"], env["GITHUB_TOKEN"]
 
     @functools.cache
     def github(path: str) -> object:
+        """GET ``path`` from the GitHub API with the workflow token, once per run."""
         return ci_tier.api_request("GET", API + path, token)
 
     previous, problem = previous_state(github, repository)
@@ -677,9 +681,11 @@ def github(path: str) -> object:
 
 
 def cmd_publish(args: argparse.Namespace, env: Mapping[str, str], now: datetime) -> int:
+    """Commit the rendered SVGs and the state file to the badges branch."""
     repository, token = env["GITHUB_REPOSITORY"], env["GITHUB_TOKEN"]
 
     def call(method: str, path: str, payload: object | None) -> object:
+        """Send one GitHub API request with the workflow token."""
         return ci_tier.api_request(method, API + path, token, payload)
 
     print(f"{BRANCH}: {publish(call, repository, collect(args.dir, BADGES), now)}")
@@ -687,6 +693,7 @@ def call(method: str, path: str, payload: object | None) -> object:
 
 
 def cmd_verdict(args: argparse.Namespace) -> int:
+    """Turn the run red, with one annotation per line, when a source failed."""
     failures = json.loads(args.state.read_text(encoding="utf-8")).get("failures")
     if not isinstance(failures, list):
         raise BadgeError(f"{args.state}: no failures list")
@@ -703,6 +710,7 @@ def cmd_verdict(args: argparse.Namespace) -> int:
 
 
 def parse_args(argv: list[str]) -> argparse.Namespace:
+    """Parse the four subcommands and their paths."""
     parser = argparse.ArgumentParser(
         description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
     )
@@ -720,6 +728,7 @@ def parse_args(argv: list[str]) -> argparse.Namespace:
 
 
 def main(argv: list[str] | None = None, env: Mapping[str, str] | None = None) -> int:
+    """Run one subcommand; 2 for a missing input or a handled error."""
     args = parse_args(sys.argv[1:] if argv is None else argv)
     env = os.environ if env is None else env
     now = datetime.now(UTC)
diff --git a/scripts/ci/tests/test_ci_tier.py b/scripts/ci/tests/test_ci_tier.py
index 0cd6a0c56f..c81190dd89 100644
--- a/scripts/ci/tests/test_ci_tier.py
+++ b/scripts/ci/tests/test_ci_tier.py
@@ -155,6 +155,8 @@ def test_a_null_payload_means_no_labels(self) -> None:
 
 
 class Api(unittest.TestCase):
+    """``api_request`` sends GitHub API calls over the https-only opener."""
+
     def test_a_non_https_url_is_refused(self) -> None:
         for url in ("http://api.github.com/x", "file:///etc/passwd", "ftp://h/x"):
             with self.subTest(url=url), self.assertRaises(ci_tier.TierError):
@@ -171,6 +173,7 @@ def sent(
         return sent.call_args.args[0], result
 
     def test_a_payload_goes_out_as_a_json_body(self) -> None:
+        """A payload goes out as a JSON body with its content type and method."""
         request, _ = self.sent("PATCH", {"sha": "c1", "force": False})
         data = request.data
         if not isinstance(data, bytes):
@@ -180,20 +183,25 @@ def test_a_payload_goes_out_as_a_json_body(self) -> None:
         self.assertEqual(request.get_method(), "PATCH")
 
     def test_a_post_without_payload_sends_an_empty_body(self) -> None:
+        """A POST without payload sends an empty body and no content type."""
         request, _ = self.sent("POST")
         self.assertEqual(request.data, b"")
         self.assertIsNone(request.get_header("Content-type"))
 
     def test_a_get_sends_no_body(self) -> None:
+        """A GET sends no body and carries the bearer token."""
         request, _ = self.sent("GET")
         self.assertIsNone(request.data)
         self.assertEqual(request.get_header("Authorization"), "Bearer t")
 
     def test_an_empty_answer_reads_as_an_empty_object(self) -> None:
+        """An empty answer reads as an empty object."""
         self.assertEqual(self.sent("GET", answer=b"")[1], {})
 
 
 class HttpsJson(unittest.TestCase):
+    """``https_json`` sends the caller's headers and bounds the answer size."""
+
     def answer(
         self, body: bytes, limit: int, headers: dict[str, str] | None = None
     ) -> tuple[Any, Any, Any]:
@@ -206,22 +214,26 @@ def answer(
         return result, sent.call_args, read.call_args
 
     def test_an_answer_of_exactly_the_limit_is_read(self) -> None:
+        """An answer of exactly the limit is read, with one byte more requested."""
         result, opened, read = self.answer(b'{"a":1}', 7)
         self.assertEqual(result, {"a": 1})
         self.assertEqual(read.args, (8,))
         self.assertEqual(opened.kwargs["timeout"], 5)
 
     def test_an_answer_one_byte_over_the_limit_is_refused(self) -> None:
+        """An answer one byte over the limit is refused."""
         with self.assertRaisesRegex(ci_tier.TierError, "larger than 6 bytes"):
             self.answer(b'{"a":1}', 6)
 
     def test_the_caller_headers_go_out_and_nothing_else(self) -> None:
+        """Only the caller's headers go out; no Authorization is added."""
         _, opened, _ = self.answer(b"{}", 10, {"Accept": "application/json"})
         request = opened.args[0]
         self.assertEqual(request.get_header("Accept"), "application/json")
         self.assertIsNone(request.get_header("Authorization"))
 
     def test_a_non_https_url_is_refused_before_any_request(self) -> None:
+        """A non-https URL is refused before the opener is called."""
         with mock.patch.object(ci_tier.HTTPS_OPENER, "open") as sent:
             for url in ("http://h/x", "file:///etc/passwd"):
                 with self.subTest(url=url), self.assertRaises(ci_tier.TierError):
@@ -230,6 +242,8 @@ def test_a_non_https_url_is_refused_before_any_request(self) -> None:
 
 
 class HttpsOpener(unittest.TestCase):
+    """The shared opener speaks https only and follows no redirect."""
+
     @staticmethod
     def response(code: int, location: str | None = None) -> mock.Mock:
         """A stand-in for an https answer with ``code`` and an optional Location."""
@@ -241,6 +255,7 @@ def response(code: int, location: str | None = None) -> mock.Mock:
         return answer
 
     def test_an_https_address_reaches_the_https_handler(self) -> None:
+        """An https address reaches the https handler unchanged."""
         answer = self.response(200)
         with mock.patch.object(
             urllib.request.HTTPSHandler, "https_open", return_value=answer
@@ -249,6 +264,7 @@ def test_an_https_address_reaches_the_https_handler(self) -> None:
         self.assertEqual(https_open.call_args.args[0].full_url, "https://h/x")
 
     def test_a_non_https_address_fails_without_being_opened(self) -> None:
+        """Every other scheme fails as an unknown url type."""
         for url in ("file:///etc/passwd", "data:text/plain,x", "ftp://h/x", "http://h/x"):
             with (
                 self.subTest(url=url),
@@ -257,6 +273,7 @@ def test_a_non_https_address_fails_without_being_opened(self) -> None:
                 ci_tier.HTTPS_OPENER.open(url, timeout=1)
 
     def test_a_redirect_is_not_followed(self) -> None:
+        """Every 3xx answer is an HTTPError after exactly one request."""
         # An https target too: following it would resend the Authorization header.
         targets = ("https://other.example/y", "http://h/y", "ftp://h/y", "file:///etc/passwd")
         for code in (301, 302, 307, 308):
@@ -276,6 +293,7 @@ def test_a_redirect_is_not_followed(self) -> None:
                     self.assertEqual(https_open.call_count, 1)
 
     def test_an_error_answer_is_an_http_error(self) -> None:
+        """A 404 answer is an HTTPError."""
         with (
             mock.patch.object(
                 urllib.request.HTTPSHandler, "https_open", return_value=self.response(404)
diff --git a/scripts/ci/tests/test_readme_badges.py b/scripts/ci/tests/test_readme_badges.py
index bc553159b4..9d01f26e04 100644
--- a/scripts/ci/tests/test_readme_badges.py
+++ b/scripts/ci/tests/test_readme_badges.py
@@ -38,6 +38,7 @@
 
 
 def runs(*conclusions: object) -> dict[str, object]:
+    """A workflow-runs answer with one run per conclusion, newest first."""
     return {"workflow_runs": [{"conclusion": c} for c in conclusions]}
 
 
@@ -45,6 +46,7 @@ def commit_answering(answer: object, call: rb.Call) -> rb.Call:
     """``call``, except that creating a commit answers ``answer``."""
 
     def answered(method: str, path: str, payload: object) -> object:
+        """Answer ``answer`` to the commit request; pass every other call on."""
         if path.endswith("/git/commits"):
             return answer
         return call(method, path, payload)
@@ -53,6 +55,7 @@ def answered(method: str, path: str, payload: object) -> object:
 
 
 def http_error(code: int) -> urllib.error.HTTPError:
+    """An HTTPError with ``code`` and an empty body, as urllib raises it."""
     return urllib.error.HTTPError(
         "https://api.github.com/x", code, "x", email.message.Message(), None
     )
@@ -61,24 +64,31 @@ def http_error(code: int) -> urllib.error.HTTPError:
 def entry(
     message: str = "passing", color: str = rb.GREEN, fetched: str | None = None
 ) -> dict[str, str | None]:
+    """A state entry as ``refresh`` writes it, read at ``NOW`` unless ``fetched`` is set."""
     return {"message": message, "color": color, "fetched_at": fetched or rb.stamp(NOW)}
 
 
 class WorkflowValue(unittest.TestCase):
+    """A workflow badge reads the newest decisive run."""
+
     def test_success_is_passing(self) -> None:
+        """A successful newest run reads passing."""
         self.assertEqual(rb.workflow_value(runs("success")), rb.PASSING)
 
     def test_every_failing_conclusion_is_failing(self) -> None:
+        """failure, timed_out and startup_failure all read failing."""
         for conclusion in ("failure", "timed_out", "startup_failure"):
             with self.subTest(conclusion=conclusion):
                 self.assertEqual(rb.workflow_value(runs(conclusion, "success")), rb.FAILING)
 
     def test_an_unfinished_or_cancelled_run_does_not_mask_a_failure(self) -> None:
+        """Runs without a conclusion, cancelled and skipped runs are passed over."""
         # Planted case of the red-reader miss: the newest run had no conclusion yet.
         answer = runs(None, "cancelled", "skipped", "failure", "success")
         self.assertEqual(rb.workflow_value(answer), rb.FAILING)
 
     def test_any_other_newest_conclusion_is_unknown_not_an_older_value(self) -> None:
+        """Any other conclusion reads unknown; an older success never stands in."""
         # Planted case from the pull request 3393 review: action_required read
         # as the older success behind it.
         conclusions: tuple[object, ...] = (
@@ -96,14 +106,17 @@ def test_any_other_newest_conclusion_is_unknown_not_an_older_value(self) -> None
                 self.assertEqual(rb.workflow_value(answer), ("unknown", rb.GREY))
 
     def test_no_decisive_run_is_unknown(self) -> None:
+        """No run, or only passed-over runs, reads unknown."""
         self.assertEqual(rb.workflow_value(runs()), ("unknown", rb.GREY))
         self.assertEqual(rb.workflow_value(runs("cancelled", None)), ("unknown", rb.GREY))
 
     def test_a_row_that_is_not_an_object_is_skipped(self) -> None:
+        """A run row that is not an object is passed over."""
         answer = {"workflow_runs": ["x", 3, {"conclusion": "success"}]}
         self.assertEqual(rb.workflow_value(answer), rb.PASSING)
 
     def test_an_answer_without_a_run_list_is_refused(self) -> None:
+        """An answer without a ``workflow_runs`` list is a badge error."""
         answers: tuple[object, ...] = ({}, [], None, {"workflow_runs": {}})
         for answer in answers:
             with self.subTest(answer=answer), self.assertRaises(rb.BadgeError):
@@ -111,7 +124,10 @@ def test_an_answer_without_a_run_list_is_refused(self) -> None:
 
 
 class ScorecardValue(unittest.TestCase):
+    """The Scorecard badge shows the score with one decimal and the master colour."""
+
     def test_colour_boundaries(self) -> None:
+        """The colour follows the unrounded score, green from 8.5, amber from 4.0."""
         # Green from the unrounded 8.5 of docs/principles.md (ADR-1247), so a
         # score shown as "8.5" can still be amber.
         cases = {
@@ -130,44 +146,56 @@ def test_colour_boundaries(self) -> None:
                 self.assertEqual(rb.scorecard_value({"score": score}), want)
 
     def test_a_score_outside_zero_to_ten_or_not_a_number_is_refused(self) -> None:
+        """A score that is not a finite number from 0 to 10 is refused."""
         for score in (True, False, "8.9", None, -0.1, 10.01, float("nan"), float("inf")):
             with self.subTest(score=score), self.assertRaises(rb.BadgeError):
                 rb.scorecard_value({"score": score})
 
     def test_an_answer_that_is_not_an_object_is_refused(self) -> None:
+        """An answer that is not an object is refused."""
         with self.assertRaises(rb.BadgeError):
             rb.scorecard_value([8.9])
 
     def test_green_starts_at_the_master_requirement(self) -> None:
+        """The green threshold is the score docs/principles.md requires."""
         principles = (ROOT / "docs/principles.md").read_text(encoding="utf-8")
         self.assertIn(f"{rb.SCORE_GREEN}", principles)
 
 
 class BestPracticesValue(unittest.TestCase):
+    """The Best Practices badge shows the level of the one listed project."""
+
     URL = "https://github.com/VMAFx/vmafx"
 
     def rows(self, *levels: str) -> list[dict[str, str]]:
+        """One Best Practices row for this repository per level."""
         return [{"repo_url": self.URL, "badge_level": level} for level in levels]
 
     def test_every_known_level(self) -> None:
+        """Every known level maps to its message and colour."""
         for level, want in rb.BEST_PRACTICES.items():
             with self.subTest(level=level):
                 self.assertEqual(rb.best_practices_value(self.rows(level), self.URL), want)
 
     def test_exactly_one_project_must_list_the_repository(self) -> None:
+        """No match, another repository or two matches are refused."""
         other = [{"repo_url": "https://github.com/Netflix/vmaf", "badge_level": "passing"}]
         for rows in ([], other, self.rows("passing", "gold"), {"repo_url": self.URL}, None):
             with self.subTest(rows=rows), self.assertRaises(rb.BadgeError):
                 rb.best_practices_value(rows, self.URL)
 
     def test_an_unknown_level_is_refused(self) -> None:
+        """A level outside the known ones is refused."""
         for level in ("platinum", None, ""):
             with self.subTest(level=level), self.assertRaises(rb.BadgeError):
                 rb.best_practices_value([{"repo_url": self.URL, "badge_level": level}], self.URL)
 
 
 class CodacyValue(unittest.TestCase):
+    """The Codacy badge shows the grade letter."""
+
     def test_every_grade_letter(self) -> None:
+        """Every letter from A to F maps to its colour."""
         for letter, color in rb.CODACY.items():
             with self.subTest(letter=letter):
                 want = (letter, color)
@@ -177,6 +205,7 @@ def test_every_grade_letter(self) -> None:
         self.assertEqual(rb.CODACY["D"], rb.RED)
 
     def test_anything_but_a_letter_from_a_to_f_is_refused(self) -> None:
+        """Anything but an upper-case letter from A to F is refused."""
         docs: tuple[object, ...] = (
             {"data": {"gradeLetter": "G"}},
             {"data": {"gradeLetter": "a"}},
@@ -190,14 +219,20 @@ def test_anything_but_a_letter_from_a_to_f_is_refused(self) -> None:
 
 
 class ReadValue(unittest.TestCase):
+    """``read_value`` asks the right source for each badge kind."""
+
     def github(self, paths: list[str], branch: object = "master") -> rb.GitHub:
+        """A GitHub stub that records each path and answers one successful run."""
+
         def fetch(path: str) -> object:
+            """Record ``path``; answer the repository or the run list."""
             paths.append(path)
             return {"default_branch": branch} if path == f"/repos/{REPO}" else runs("success")
 
         return fetch
 
     def test_a_workflow_badge_reads_completed_push_runs_on_the_default_branch(self) -> None:
+        """The run query names the default branch, push, completed and 30 runs."""
         paths: list[str] = []
         badge = rb.Badge("lint", "Lint", "workflow", "lint-and-format.yml")
         value = rb.read_value(badge, REPO, self.github(paths), self.fail)
@@ -207,12 +242,14 @@ def test_a_workflow_badge_reads_completed_push_runs_on_the_default_branch(self)
         self.assertEqual(query, "branch=master&event=push&status=completed&per_page=30")
 
     def test_a_repository_without_a_default_branch_is_refused(self) -> None:
+        """A missing or non-string default branch is a badge error."""
         badge = rb.Badge("lint", "Lint", "workflow", "lint-and-format.yml")
         for branch in ("", None, 3):
             with self.subTest(branch=branch), self.assertRaises(rb.BadgeError):
                 rb.read_value(badge, REPO, self.github([], branch), lambda url: {})
 
     def test_public_sources_get_their_own_urls_and_no_github_call(self) -> None:
+        """Scorecard, Best Practices and Codacy are read from their own URLs only."""
         answers = {
             "https://api.scorecard.dev/projects/github.com/VMAFx/vmafx": {"score": 8.9},
             "https://www.bestpractices.dev/projects.json?url=https%3A%2F%2Fgithub.com%2FVMAFx%2Fvmafx": [
@@ -229,12 +266,16 @@ def test_public_sources_get_their_own_urls_and_no_github_call(self) -> None:
                     rb.read_value(badge, REPO, self.fail, public)
 
     def test_an_unknown_kind_is_refused(self) -> None:
+        """A badge kind the script does not know is refused."""
         with self.assertRaises(rb.BadgeError):
             rb.read_value(rb.Badge("x", "X", "rss"), REPO, lambda p: {}, lambda u: {})
 
 
 class Usable(unittest.TestCase):
+    """``usable`` accepts only entries this script could have written."""
+
     def test_an_entry_this_script_writes_is_usable(self) -> None:
+        """A written entry passes, and a missing read time becomes None."""
         self.assertEqual(rb.usable(entry()), entry())
         self.assertEqual(
             rb.usable({"message": "x" * 40, "color": rb.RED}),
@@ -242,6 +283,7 @@ def test_an_entry_this_script_writes_is_usable(self) -> None:
         )
 
     def test_a_malformed_entry_is_not(self) -> None:
+        """Bad text, colour, time type or shape gives None."""
         for bad in (
             entry(message=""),
             entry(message="x" * 41),
@@ -257,16 +299,21 @@ def test_a_malformed_entry_is_not(self) -> None:
 
 
 class Carried(unittest.TestCase):
+    """A failed source keeps its last value for six hours, then reads stale."""
+
     def test_a_value_is_kept_up_to_exactly_six_hours(self) -> None:
+        """A value read exactly six hours ago is still shown."""
         fetched = rb.stamp(NOW - rb.STALE_AFTER)
         self.assertEqual(rb.carried(entry(fetched=fetched), NOW)["message"], "passing")
 
     def test_one_second_past_six_hours_reads_stale(self) -> None:
+        """One second past six hours reads stale in grey and keeps the read time."""
         fetched = rb.stamp(NOW - rb.STALE_AFTER - timedelta(seconds=1))
         got = rb.carried(entry(fetched=fetched), NOW)
         self.assertEqual(got, {"message": "stale", "color": rb.GREY, "fetched_at": fetched})
 
     def test_a_future_or_unreadable_time_reads_stale(self) -> None:
+        """A future, unreadable or naive read time reads stale."""
         # The naive times are planted cases from the pull request 3393 review:
         # they raised TypeError and stopped the run.
         naive = ("2026-11-10T12:00:00", "2026-11-10")
@@ -275,17 +322,20 @@ def test_a_future_or_unreadable_time_reads_stale(self) -> None:
                 self.assertEqual(rb.carried(entry(fetched=fetched), NOW)["message"], "stale")
 
     def test_a_time_with_any_utc_offset_is_read(self) -> None:
+        """A read time with any UTC offset counts."""
         for fetched in ("2026-11-10T13:00:00+01:00", "2026-11-10T12:00:00+00:00"):
             with self.subTest(fetched=fetched):
                 self.assertEqual(rb.carried(entry(fetched=fetched), NOW)["message"], "passing")
 
     def test_read_time_needs_an_offset(self) -> None:
+        """``read_time`` returns None for a time without an offset."""
         self.assertEqual(rb.read_time(rb.stamp(NOW)), NOW)
         for text in ("2026-11-10T12:00:00", "2026-11-10", "", "noon"):
             with self.subTest(text=text):
                 self.assertIsNone(rb.read_time(text))
 
     def test_no_previous_value_reads_stale(self) -> None:
+        """No previous entry, or one without a read time, reads stale."""
         self.assertEqual(rb.carried(None, NOW)["message"], "stale")
         self.assertEqual(
             rb.carried({"message": "passing", "fetched_at": None}, NOW)["message"], "stale"
@@ -293,9 +343,12 @@ def test_no_previous_value_reads_stale(self) -> None:
 
 
 class Refresh(unittest.TestCase):
+    """``refresh`` reads every badge and carries the ones whose source failed."""
+
     BADGE = (rb.Badge("go", "Go", "workflow", "go-ci.yml"),)
 
     def test_a_source_that_answers_gets_a_new_time(self) -> None:
+        """An answering source is stored with the current read time."""
         entries, failures = rb.refresh(self.BADGE, {}, NOW, lambda b: rb.FAILING)
         self.assertEqual(
             entries["go"], {"message": "failing", "color": rb.RED, "fetched_at": rb.stamp(NOW)}
@@ -303,6 +356,7 @@ def test_a_source_that_answers_gets_a_new_time(self) -> None:
         self.assertEqual(failures, [])
 
     def test_a_failing_source_keeps_its_last_value_and_is_reported(self) -> None:
+        """Each expected error keeps the last value and adds one failure line."""
         previous = {"go": entry(fetched=rb.stamp(NOW - timedelta(hours=1)))}
         for error in (
             rb.BadgeError("b"),
@@ -315,6 +369,7 @@ def test_a_failing_source_keeps_its_last_value_and_is_reported(self) -> None:
             with self.subTest(error=type(error).__name__):
 
                 def read(badge: rb.Badge, error: Exception = error) -> rb.Value:
+                    """Raise the planted ``error``."""
                     raise error
 
                 entries, failures = rb.refresh(self.BADGE, previous, NOW, read)
@@ -323,13 +378,17 @@ def read(badge: rb.Badge, error: Exception = error) -> rb.Value:
                 self.assertTrue(failures[0].startswith("go: "))
 
     def test_an_unexpected_error_is_not_swallowed(self) -> None:
+        """An error outside the expected kinds propagates."""
+
         def read(badge: rb.Badge) -> rb.Value:
+            """Raise an error the script does not expect."""
             raise RuntimeError("bug")
 
         with self.assertRaises(RuntimeError):
             rb.refresh(self.BADGE, {}, NOW, read)
 
     def test_the_render_list_keeps_readme_order(self) -> None:
+        """The render list follows BADGES and holds only the four render keys."""
         entries = {b.slug: entry() for b in rb.BADGES}
         rendered = rb.render_list(rb.BADGES, entries)
         self.assertEqual([r["slug"] for r in rendered], [b.slug for b in rb.BADGES])
@@ -337,8 +396,13 @@ def test_the_render_list_keeps_readme_order(self) -> None:
 
 
 class PreviousState(unittest.TestCase):
+    """``previous_state`` reads state.json from the badges branch or stops the run."""
+
     def fetch(self, answer: object) -> rb.GitHub:
+        """A GitHub stub that checks the state path and answers or raises ``answer``."""
+
         def github(path: str) -> object:
+            """Check the state path, then raise or return the planted answer."""
             self.assertEqual(path, f"/repos/{REPO}/contents/state.json?ref=badges")
             if isinstance(answer, Exception):
                 raise answer
@@ -347,9 +411,11 @@ def github(path: str) -> object:
         return github
 
     def test_a_new_branch_has_no_state_and_no_problem(self) -> None:
+        """A 404 means a new branch: empty state and no problem."""
         self.assertEqual(rb.previous_state(self.fetch(http_error(404)), REPO), ({}, None))
 
     def test_a_handled_error_is_closed(self) -> None:
+        """Both the 404 and the failing 500 answer are closed."""
         missing = http_error(404)
         rb.previous_state(self.fetch(missing), REPO)
         self.assertTrue(missing.fp.closed)
@@ -359,11 +425,13 @@ def test_a_handled_error_is_closed(self) -> None:
         self.assertTrue(failed.fp.closed)
 
     def test_the_badges_of_the_state_file_are_read(self) -> None:
+        """The badges object of state.json is returned."""
         text = json.dumps({"badges": {"go": entry()}}).encode()
         doc = {"content": base64.b64encode(text).decode()}
         self.assertEqual(rb.previous_state(self.fetch(doc), REPO), ({"go": entry()}, None))
 
     def test_a_failed_read_stops_the_run(self) -> None:
+        """Any read failure but 404 raises, so nothing is published."""
         # Planted case from the pull request 3393 review: a failed read returned
         # no state, so every failing source turned "stale" at once.
         failed = (http_error(500), OSError("down"), ci_tier.TierError("too large"), ValueError("x"))
@@ -375,6 +443,7 @@ def test_a_failed_read_stops_the_run(self) -> None:
                 rb.previous_state(self.fetch(answer), REPO)
 
     def test_an_unreadable_state_is_a_problem_not_a_crash(self) -> None:
+        """Content that cannot be decoded gives empty state and a problem."""
         for answer in ({}, {"content": "!!"}, {"content": ""}, {"content": 7}):
             with self.subTest(answer=answer):
                 badges, problem = rb.previous_state(self.fetch(answer), REPO)
@@ -382,18 +451,24 @@ def test_an_unreadable_state_is_a_problem_not_a_crash(self) -> None:
                 self.assertIsNotNone(problem)
 
     def test_a_badges_field_that_is_not_an_object_is_empty(self) -> None:
+        """A badges field that is not an object reads as empty."""
         doc = {"content": base64.b64encode(b'{"badges": []}').decode()}
         self.assertEqual(rb.previous_state(self.fetch(doc), REPO), ({}, None))
 
 
 class Field(unittest.TestCase):
+    """``field`` walks nested objects or names the missing key."""
+
     def test_a_nested_value_is_returned(self) -> None:
+        """Each key goes one level down."""
         self.assertEqual(rb.field({"a": {"b": "c"}}, "a", "b"), "c")
 
     def test_no_keys_returns_the_document(self) -> None:
+        """Without keys the document itself is returned."""
         self.assertEqual(rb.field([1], *()), [1])
 
     def test_a_missing_or_non_object_level_is_refused(self) -> None:
+        """A missing key or a non-object level names the dotted path."""
         docs: tuple[object, ...] = ({}, {"a": {}}, {"a": "b"}, {"a": None}, [], None)
         for doc in docs:
             with self.subTest(doc=doc), self.assertRaisesRegex(rb.BadgeError, "no a.b"):
@@ -401,7 +476,10 @@ def test_a_missing_or_non_object_level_is_refused(self) -> None:
 
 
 class PublicJson(unittest.TestCase):
+    """Public sources get an https request with no token."""
+
     def test_a_public_source_gets_no_token_and_the_badge_bounds(self) -> None:
+        """Only an Accept header goes out, with the badge timeout and size limit."""
         with mock.patch.object(ci_tier, "https_json", return_value={"score": 7}) as sent:
             self.assertEqual(rb.public_json("https://api.scorecard.dev/x"), {"score": 7})
         method, url, headers, data, timeout, limit = sent.call_args.args
@@ -410,6 +488,7 @@ def test_a_public_source_gets_no_token_and_the_badge_bounds(self) -> None:
         self.assertEqual((timeout, limit), (rb.PUBLIC_TIMEOUT_S, rb.MAX_RESPONSE_BYTES))
 
     def test_a_non_https_source_is_refused_before_any_request(self) -> None:
+        """An http URL is refused before the opener is called."""
         with mock.patch.object(ci_tier.HTTPS_OPENER, "open") as sent:
             with self.assertRaises(ci_tier.TierError):
                 rb.public_json("http://api.scorecard.dev/x")
@@ -417,16 +496,21 @@ def test_a_non_https_source_is_refused_before_any_request(self) -> None:
 
 
 class Collect(unittest.TestCase):
+    """``collect`` takes exactly the rendered SVGs and the state file."""
+
     def setUp(self) -> None:
+        """Write one SVG per badge and an empty state file."""
         self.dir = Path(self.enterContext(tempfile.TemporaryDirectory()))
         for badge in rb.BADGES:
             (self.dir / f"{badge.slug}.svg").write_text('<svg xmlns="x"></svg>\n', encoding="utf-8")
         (self.dir / "state.json").write_text("{}\n", encoding="utf-8")
 
     def test_one_svg_per_badge_and_the_state_file(self) -> None:
+        """The collected tree holds every SVG and state.json."""
         self.assertEqual(len(rb.collect(self.dir, rb.BADGES)), len(rb.BADGES) + 1)
 
     def test_a_missing_or_unexpected_file_is_refused(self) -> None:
+        """An extra file or a missing SVG is refused."""
         (self.dir / "extra.svg").write_text("<svg ></svg>", encoding="utf-8")
         with self.assertRaisesRegex(rb.BadgeError, "unexpected"):
             rb.collect(self.dir, rb.BADGES)
@@ -436,9 +520,11 @@ def test_a_missing_or_unexpected_file_is_refused(self) -> None:
             rb.collect(self.dir, rb.BADGES)
 
     def test_a_symlink_a_large_file_or_a_non_svg_is_refused(self) -> None:
+        """A symbolic link, an oversized file or a non-SVG file is refused."""
         target = self.dir / "go.svg"
 
         def relink() -> None:
+            """Replace go.svg with a link to lint.svg."""
             target.unlink()
             target.symlink_to(self.dir / "lint.svg")
 
@@ -456,12 +542,15 @@ def relink() -> None:
                     rb.collect(self.dir, rb.BADGES)
 
     def test_a_state_file_that_is_not_json_is_refused(self) -> None:
+        """A state.json that is not JSON is refused."""
         (self.dir / "state.json").write_text("{", encoding="utf-8")
         with self.assertRaises(ValueError):
             rb.collect(self.dir, rb.BADGES)
 
 
 class Publish(unittest.TestCase):
+    """``publish`` writes one signed commit and moves the badges branch forward only."""
+
     FILES: ClassVar[dict[str, bytes]] = {"go.svg": b"<svg >go</svg>", "state.json": b"{}"}
     OLD = rb.stamp(NOW - rb.QUIET_WINDOW)
 
@@ -472,10 +561,12 @@ def fake(
         verified: bool = True,
         tree_files: dict[str, bytes] | None = None,
     ) -> tuple[rb.Call, list[tuple[str, str, Any]]]:
+        """A GitHub stub for ``publish`` that records each call; no ``head`` means no branch."""
         calls: list[tuple[str, str, Any]] = []
         tree_files = self.FILES if tree_files is None else tree_files
 
         def call(method: str, path: str, payload: object) -> object:
+            """Record the call and answer it like the Git data API."""
             calls.append((method, path, payload))
             if path.endswith("/git/ref/heads/badges"):
                 if head is None:
@@ -494,6 +585,7 @@ def call(method: str, path: str, payload: object) -> object:
         return call, calls
 
     def test_the_first_publish_creates_the_branch(self) -> None:
+        """Without a branch the commit has no parent and the ref is created."""
         call, calls = self.fake(None)
         self.assertEqual(rb.publish(call, REPO, self.FILES, NOW), "c1")
         self.assertEqual(calls[2][2]["parents"], [])
@@ -503,6 +595,7 @@ def test_the_first_publish_creates_the_branch(self) -> None:
         )
 
     def test_an_old_head_gets_a_new_commit_moved_forward_only(self) -> None:
+        """An old head becomes the parent, and the ref moves with force false."""
         call, calls = self.fake("c0")
         rb.publish(call, REPO, self.FILES, NOW)
         commit = next(c for c in calls if c[1].endswith("/git/commits"))
@@ -513,12 +606,14 @@ def test_an_old_head_gets_a_new_commit_moved_forward_only(self) -> None:
         )
 
     def test_an_unsigned_commit_leaves_the_branch_alone(self) -> None:
+        """An unverified commit raises before any ref call."""
         call, calls = self.fake("c0", verified=False)
         with self.assertRaisesRegex(rb.BadgeError, "not signed"):
             rb.publish(call, REPO, self.FILES, NOW)
         self.assertFalse([c for c in calls if "/git/refs" in c[1]])
 
     def test_a_commit_without_a_true_verification_is_not_signed(self) -> None:
+        """A missing or non-boolean verification counts as unsigned."""
         for answer in ({"sha": "c1"}, {"sha": "c1", "verification": {"verified": "true"}}):
             with self.subTest(answer=answer):
                 call, calls = self.fake("c0")
@@ -527,28 +622,33 @@ def test_a_commit_without_a_true_verification_is_not_signed(self) -> None:
                 self.assertFalse([c for c in calls if "/git/refs" in c[1]])
 
     def test_a_tree_answer_without_a_list_is_refused(self) -> None:
+        """A head tree answer without a list raises."""
         young = rb.stamp(NOW - timedelta(minutes=5))
         call, _ = self.fake("c0", date=young)
 
         def answered(method: str, path: str, payload: object) -> object:
+            """Answer the head tree without a list; pass every other call on."""
             return {"tree": {}} if "/git/trees/" in path else call(method, path, payload)
 
         with self.assertRaisesRegex(rb.BadgeError, "no tree list"):
             rb.publish(answered, REPO, self.FILES, NOW)
 
     def test_same_svgs_inside_the_quiet_window_commit_nothing(self) -> None:
+        """Same SVGs and a head younger than an hour make only GET calls."""
         young = rb.stamp(NOW - rb.QUIET_WINDOW + timedelta(seconds=1))
         call, calls = self.fake("c0", date=young)
         self.assertEqual(rb.publish(call, REPO, self.FILES, NOW), "unchanged at c0")
         self.assertFalse([c for c in calls if c[0] != "GET"])
 
     def test_a_naive_or_unreadable_head_date_commits(self) -> None:
+        """A head date without an offset, or unreadable, counts as old."""
         for date in ("2026-11-10T11:59:00", "2026-11-10", "soon"):
             with self.subTest(date=date):
                 call, _ = self.fake("c0", date=date)
                 self.assertEqual(rb.publish(call, REPO, self.FILES, NOW), "c1")
 
     def test_a_changed_svg_inside_the_quiet_window_is_committed(self) -> None:
+        """A changed SVG is committed even inside the quiet window."""
         young = rb.stamp(NOW - timedelta(minutes=5))
         call, _ = self.fake(
             "c0", date=young, tree_files={"go.svg": b"<svg >old</svg>", "state.json": b"{}"}
@@ -556,7 +656,10 @@ def test_a_changed_svg_inside_the_quiet_window_is_committed(self) -> None:
         self.assertEqual(rb.publish(call, REPO, self.FILES, NOW), "c1")
 
     def test_a_ref_lookup_error_other_than_404_is_raised(self) -> None:
+        """A failing ref lookup other than 404 propagates."""
+
         def call(method: str, path: str, payload: object) -> object:
+            """Fail every call with a 500."""
             raise http_error(500)
 
         with self.assertRaises(urllib.error.HTTPError) as raised:
@@ -564,23 +667,28 @@ def call(method: str, path: str, payload: object) -> object:
         raised.exception.close()
 
     def test_a_missing_branch_closes_its_404(self) -> None:
+        """``branch_head`` returns None for a 404 and closes it."""
         error = http_error(404)
 
         def call(method: str, path: str, payload: object) -> object:
+            """Fail every call with the planted 404."""
             raise error
 
         self.assertIsNone(rb.branch_head(call, REPO))
         self.assertTrue(error.fp.closed)
 
     def test_blob_sha_is_the_git_object_id(self) -> None:
+        """``blob_sha`` matches ``git hash-object`` for a known blob."""
         # `printf 'hi\n' | git hash-object --stdin`
         self.assertEqual(rb.blob_sha(b"hi\n"), "45b983be36b73c0788dc9cbcb76cbb80fc7bb057")
 
     def test_the_empty_blob_has_the_well_known_id(self) -> None:
+        """The empty blob has git's well-known id."""
         # `git hash-object --stdin </dev/null`
         self.assertEqual(rb.blob_sha(b""), "e69de29bb2d1d6434b8b29ae775ad8c2e48c5391")
 
     def test_a_failing_or_garbled_git_is_refused(self) -> None:
+        """A non-zero exit or an output that is not a SHA-1 id is refused."""
         answers = (
             mock.Mock(returncode=128, stdout=b"", stderr=b"fatal: no"),
             mock.Mock(
@@ -598,6 +706,7 @@ def test_a_failing_or_garbled_git_is_refused(self) -> None:
                 rb.blob_sha(b"hi\n")
 
     def test_a_missing_git_is_a_badge_error(self) -> None:
+        """A missing git executable becomes a badge error."""
         missing = CommandValidationError("required executable not found: git")
         with mock.patch.object(rb, "run_command", side_effect=missing):
             with self.assertRaisesRegex(rb.BadgeError, "not found: git"):
@@ -605,7 +714,10 @@ def test_a_missing_git_is_a_badge_error(self) -> None:
 
 
 class Verdict(unittest.TestCase):
+    """``verdict`` turns the run red when a source failed."""
+
     def verdict(self, doc: object) -> tuple[int, str]:
+        """Run ``verdict`` on a state file holding ``doc``; return the code and stdout."""
         with tempfile.TemporaryDirectory() as tmp:
             state = Path(tmp) / "state.json"
             state.write_text(json.dumps(doc), encoding="utf-8")
@@ -615,19 +727,25 @@ def verdict(self, doc: object) -> tuple[int, str]:
         return rc, out.getvalue()
 
     def test_no_failure_passes(self) -> None:
+        """An empty failures list exits 0."""
         self.assertEqual(self.verdict({"failures": []})[0], 0)
 
     def test_a_failure_fails_the_run_with_an_annotation(self) -> None:
+        """A failure exits 1 with a GitHub error annotation."""
         rc, out = self.verdict({"failures": ["codacy: down"]})
         self.assertEqual(rc, 1)
         self.assertIn("::error title=Badge source failed::codacy: down", out)
 
     def test_a_state_without_a_failures_list_is_an_error(self) -> None:
+        """A failures field that is not a list exits 2."""
         self.assertEqual(self.verdict({"failures": "none"})[0], 2)
 
 
 class Main(unittest.TestCase):
+    """The command line refuses to run without its inputs."""
+
     def test_spec_and_publish_need_the_repository_and_a_token(self) -> None:
+        """spec and publish exit 2 without GITHUB_TOKEN."""
         for argv in (["spec", "--spec", "s", "--state", "t"], ["publish", "--dir", "d"]):
             err = io.StringIO()
             with self.subTest(argv=argv[0]), redirect_stderr(err):
@@ -635,7 +753,10 @@ def test_spec_and_publish_need_the_repository_and_a_token(self) -> None:
             self.assertIn("set GITHUB_TOKEN", err.getvalue())
 
     def test_a_failed_state_read_writes_nothing_to_publish(self) -> None:
+        """A failed state read exits 2 before the spec or state file is written."""
+
         def fail(*_args: object) -> object:
+            """Fail every API request with a 503."""
             raise http_error(503)
 
         env = {"GITHUB_REPOSITORY": REPO, "GITHUB_TOKEN": secrets.token_urlsafe(8)}
@@ -662,11 +783,15 @@ def fail(*_args: object) -> object:
 
 
 def image(url: str) -> str:
+    """A linked Markdown image of ``url`` on its own line."""
     return f"[![x]({url})](https://example.org)\n"
 
 
 class ImageFault(unittest.TestCase):
+    """``image_fault`` accepts only the one badge design."""
+
     def test_the_one_design_passes(self) -> None:
+        """Rendered badges, for-the-badge shields and repository files pass."""
         allowed = [
             f"https://raw.githubusercontent.com/{REPO}/badges/{b.slug}.svg" for b in rb.BADGES
         ]
@@ -681,6 +806,7 @@ def test_the_one_design_passes(self) -> None:
                 self.assertIsNone(rb.image_fault(url, ROOT))
 
     def test_another_design_or_host_is_a_fault(self) -> None:
+        """Every other style, host, repository or path names its reason."""
         refused = {
             "https://img.shields.io/badge/C-23-3b82f6?style=flat-square&labelColor=111a35": "style=for-the-badge",
             "https://img.shields.io/badge/C-23-3b82f6?style=for-the-badge": "labelColor=111a35",
@@ -708,6 +834,7 @@ def test_another_design_or_host_is_a_fault(self) -> None:
                 self.assertIn(reason, rb.image_fault(url, ROOT) or "")
 
     def test_a_link_out_of_the_readme_directory_is_a_fault(self) -> None:
+        """A link out of the README directory fails; a link inside passes."""
         with tempfile.TemporaryDirectory() as tmp:
             root, outside = Path(tmp) / "repo", Path(tmp) / "outside.svg"
             root.mkdir()
@@ -720,6 +847,7 @@ def test_a_link_out_of_the_readme_directory_is_a_fault(self) -> None:
             self.assertIsNone(rb.image_fault("local-link.svg", root))
 
     def test_a_repeated_or_empty_design_parameter_is_a_fault(self) -> None:
+        """A repeated, empty or differently cased design parameter fails."""
         for query in (
             "style=for-the-badge&style=flat&labelColor=111a35",
             "style=for-the-badge&labelColor=",
@@ -733,19 +861,25 @@ def test_a_repeated_or_empty_design_parameter_is_a_fault(self) -> None:
 
 
 class HomeRepository(unittest.TestCase):
+    """The repository name comes from the security policy file."""
+
     def setUp(self) -> None:
+        """Start and end every test with empty caches."""
         self.clear()
         self.addCleanup(self.clear)
 
     @staticmethod
     def clear() -> None:
+        """Clear the cached policy reads."""
         for cached in (rb.home_repository, rb.rendered_badge, rb.governance_badge):
             cached.cache_clear()
 
     def test_the_policy_names_this_repository(self) -> None:
+        """The checked-in policy names VMAFx/vmafx."""
         self.assertEqual(rb.home_repository(), REPO)
 
     def test_a_missing_or_malformed_policy_is_a_badge_error(self) -> None:
+        """A missing file, or a repository that is not owner/name, is refused."""
         for text in (
             None,
             "{",
@@ -768,6 +902,7 @@ def test_a_missing_or_malformed_policy_is_a_badge_error(self) -> None:
                     self.clear()
 
     def test_the_rendered_badge_follows_the_policy(self) -> None:
+        """A fork's policy accepts its own badges and refuses this repository's."""
         with tempfile.TemporaryDirectory() as tmp:
             policy = Path(tmp) / "policy.json"
             policy.write_text('{"repository": "adopter/fork"}', encoding="utf-8")
@@ -781,15 +916,20 @@ def test_the_rendered_badge_follows_the_policy(self) -> None:
 
 
 class DesignFaults(unittest.TestCase):
+    """``design_faults`` checks every image in a README."""
+
     def test_the_readme_has_the_one_design(self) -> None:
+        """The checked-in README has no fault."""
         self.assertEqual(
             rb.design_faults((ROOT / "README.md").read_text(encoding="utf-8"), ROOT), []
         )
 
     def test_an_empty_readme_has_no_fault(self) -> None:
+        """An empty README has no fault."""
         self.assertEqual(rb.design_faults("", ROOT), [])
 
     def test_a_fault_names_its_line(self) -> None:
+        """A fault starts with its line number."""
         readme = "# Title\n\n" + image(SHIELDS.replace("for-the-badge", "flat-square"))
         self.assertEqual(
             rb.design_faults(readme, ROOT),
@@ -799,19 +939,23 @@ def test_a_fault_names_its_line(self) -> None:
         )
 
     def test_the_governance_block_may_hold_its_own_badge(self) -> None:
+        """The Praetor governance block may keep GitHub's badge."""
         self.assertEqual(rb.design_faults("# Title\n\n" + BLOCK, ROOT), [])
 
     def test_the_block_exception_covers_only_the_governance_badge(self) -> None:
+        """Another image in the block, or an unresolved reference, is a fault."""
         flat = BLOCK.replace(GOVERNANCE, SHIELDS.replace("for-the-badge", "flat-square"))
         self.assertEqual(len(rb.design_faults(flat, ROOT)), 1)
         unresolved = BLOCK.replace("[docs-badge]:", "[other]:")
         self.assertIn("without an inline address", rb.design_faults(unresolved, ROOT)[0])
 
     def test_another_repository_governance_badge_is_a_fault(self) -> None:
+        """A governance badge of another repository is a fault."""
         other = GOVERNANCE.replace("vmafx/vmafx", "someone/vmafx")
         self.assertEqual(len(rb.design_faults(BLOCK.replace(GOVERNANCE, other), ROOT)), 1)
 
     def test_the_governance_badge_outside_the_block_is_a_fault(self) -> None:
+        """The governance badge outside a complete block is a fault."""
         for readme in (
             image(GOVERNANCE),
             BLOCK.replace("<!-- praetor:readme-governance:end -->\n", ""),
@@ -821,6 +965,7 @@ def test_the_governance_badge_outside_the_block_is_a_fault(self) -> None:
                 self.assertNotEqual(rb.design_faults(readme, ROOT), [])
 
     def test_a_reference_style_image_outside_the_block_is_a_fault(self) -> None:
+        """Every reference-style image form outside the block is a fault."""
         for readme in (
             f"![C][c]\n\n[c]: {SHIELDS}\n",
             f"![c][]\n\n[c]: {SHIELDS}\n",
@@ -833,6 +978,7 @@ def test_a_reference_style_image_outside_the_block_is_a_fault(self) -> None:
                 )
 
     def test_code_is_not_an_image(self) -> None:
+        """Images inside fences or code spans are not checked."""
         flat = SHIELDS.replace("for-the-badge", "flat-square")
         for readme in (
             f"```markdown\n![x]({flat})\n```\n",
@@ -843,10 +989,12 @@ def test_code_is_not_an_image(self) -> None:
                 self.assertEqual(rb.design_faults(readme, ROOT), [])
 
     def test_an_unclosed_fence_hides_nothing(self) -> None:
+        """An unclosed fence does not hide the image after it."""
         flat = SHIELDS.replace("for-the-badge", "flat-square")
         self.assertEqual(len(rb.design_faults(f"```\n![x]({flat})\n", ROOT)), 1)
 
     def test_an_html_image_must_be_a_local_file(self) -> None:
+        """img and source tags pass only for existing local files."""
         passing = (
             '<img src="docs/a.svg" alt="VMAFx" height="120" />\n',
             '<picture><source media="(prefers-color-scheme: dark)" srcset="docs/a.svg 2x, docs/b.svg"></picture>\n',
@@ -873,13 +1021,17 @@ def test_an_html_image_must_be_a_local_file(self) -> None:
                     self.assertEqual(len(rb.design_faults(readme, root)), 1)
 
     def test_faults_come_in_line_order(self) -> None:
+        """Faults are listed by line, whatever their kind."""
         readme = f'<img src="{SHIELDS}">\n' + image(GOVERNANCE) + f'<img src="{SHIELDS}">\n'
         lines = [int(fault.split(":", 1)[0]) for fault in rb.design_faults(readme, ROOT)]
         self.assertEqual(lines, [1, 2, 3])
 
 
 class CheckReadme(unittest.TestCase):
+    """The ``check-readme`` command fails on any image outside the one design."""
+
     def check(self, text: str | None, files: tuple[str, ...] = ()) -> tuple[int, str, str]:
+        """Run ``check-readme`` on a temporary README; return code, stdout and stderr."""
         with tempfile.TemporaryDirectory() as tmp:
             readme = Path(tmp) / "README.md"
             if text is not None:
@@ -892,20 +1044,24 @@ def check(self, text: str | None, files: tuple[str, ...] = ()) -> tuple[int, str
         return rc, out.getvalue(), err.getvalue()
 
     def test_the_one_design_passes_without_a_token(self) -> None:
+        """A passing README exits 0 without any token."""
         rc, out, _ = self.check(image(SHIELDS))
         self.assertEqual(rc, 0)
         self.assertIn("every badge has the one design", out)
 
     def test_a_fault_fails_with_file_and_line(self) -> None:
+        """A fault exits 1 and names README.md and the line."""
         rc, _, err = self.check("\n" + image(GOVERNANCE))
         self.assertEqual(rc, 1)
         self.assertRegex(err, r"README\.md:2: https://github\.com/")
         self.assertIn("1 README images break the one badge design", err)
 
     def test_a_missing_readme_is_an_error(self) -> None:
+        """A missing README exits 2."""
         self.assertEqual(self.check(None)[0], 2)
 
     def test_a_local_image_is_looked_up_next_to_the_readme(self) -> None:
+        """A local image passes only when the file is next to the README."""
         self.assertEqual(self.check(image("banner.svg"), files=("banner.svg",))[0], 0)
         rc, _, err = self.check(image("banner.svg"))
         self.assertEqual(rc, 1)
@@ -913,12 +1069,16 @@ def test_a_local_image_is_looked_up_next_to_the_readme(self) -> None:
 
 
 class Consistency(unittest.TestCase):
+    """The README, the workflow and render.mjs agree with the script."""
+
     def test_render_mjs_allows_the_same_text_and_colours(self) -> None:
+        """render.mjs uses the same text and colour patterns as the script."""
         source = (ROOT / "tools/badges/render.mjs").read_text(encoding="utf-8")
         self.assertIn(f"const TEXT = /^{rb.TEXT.pattern}$/", source)
         self.assertIn(f"const COLOR = /^{rb.COLOR.pattern}$/", source)
 
     def test_every_workflow_badge_names_a_workflow_by_its_name(self) -> None:
+        """Each workflow badge label is that workflow's ``name:``."""
         for badge in (b for b in rb.BADGES if b.kind == "workflow"):
             path = ROOT / ".github/workflows" / badge.workflow
             with self.subTest(badge=badge.slug):
@@ -926,6 +1086,7 @@ def test_every_workflow_badge_names_a_workflow_by_its_name(self) -> None:
                 self.assertEqual(first.group(1).strip() if first else None, badge.label)
 
     def test_the_workflow_runs_only_on_the_policy_repository_and_branch(self) -> None:
+        """The guard names the policy repository and branch; both jobs check out github.sha."""
         policy = json.loads(
             (ROOT / ".github/repository-security-policy.json").read_text(encoding="utf-8")
         )
@@ -938,6 +1099,7 @@ def test_the_workflow_runs_only_on_the_policy_repository_and_branch(self) -> Non
         self.assertNotRegex(workflow, r"ref: (?!\$\{\{ github\.sha \}\})")
 
     def test_a_carried_read_time_trails_by_less_than_the_stale_bound(self) -> None:
+        """The quiet window plus the largest schedule gap stays under a quarter of six hours."""
         # The state file is committed with the SVGs only once QUIET_WINDOW has
         # passed, so its read times trail the newest read by at most that plus
         # one schedule gap; that lag must stay well inside STALE_AFTER.
@@ -950,6 +1112,7 @@ def test_a_carried_read_time_trails_by_less_than_the_stale_bound(self) -> None:
         self.assertLess(lag, rb.STALE_AFTER / 4)
 
     def test_the_readme_shows_every_badge_once_with_its_label(self) -> None:
+        """The README shows each badge of BADGES once, in order, with its label as alt text."""
         readme = (ROOT / "README.md").read_text(encoding="utf-8")
         shown = [(m["slug"], m["alt"]) for m in RAW.finditer(readme)]
         self.assertEqual(shown, [(b.slug, b.label) for b in rb.BADGES])
diff --git a/tools/badges/render.mjs b/tools/badges/render.mjs
index eb2801753d..f0f4b49da0 100644
--- a/tools/badges/render.mjs
+++ b/tools/badges/render.mjs
@@ -22,6 +22,14 @@ const COLOR = /^#[0-9a-f]{6}$/
 const TEXT = /^[\x20-\x7e]{1,40}$/
 const MAX_BADGES = 32
 
+/**
+ * Return a render-list entry when it has exactly the four keys and each
+ * value matches its pattern; throw naming the entry otherwise.
+ *
+ * @param {unknown} entry one object of the render list
+ * @param {number} index its position, for the error text
+ * @returns {{slug: string, label: string, message: string, color: string}}
+ */
 function checked(entry, index) {
   const keys = Object.keys(entry ?? {}).sort().join(',')
   if (keys !== 'color,label,message,slug') {
@@ -35,6 +43,12 @@ function checked(entry, index) {
   return entry
 }
 
+/**
+ * Write one for-the-badge SVG per render-list entry into the output
+ * directory; throw on a malformed list or a slug listed twice.
+ *
+ * @param {string[]} argv the spec path and the output directory
+ */
 function main(argv) {
   if (argv.length !== 2) {
     throw new Error('usage: node tools/badges/render.mjs <spec.json> <out-dir>')

From f796981302e2c81a84b97a65d47b5f73b11b6af7 Mon Sep 17 00:00:00 2001
From: lusoris <lusoris@proton.me>
Date: Tue, 10 Nov 2026 21:09:39 +0100
Subject: [PATCH 5/7] fix(ci): stop a broken answer escaping the badge refresh

CodeRabbit's third review of pull request 3393 found that an answer
cut off mid-body (http.client.IncompleteRead) or a malformed status
line (BadStatusLine) escaped refresh and previous_state, because
http.client.HTTPException is not an OSError. https_json in
scripts/ci/ci_tier.py now turns any HTTPException into a TierError, so
a public source keeps its last value and a broken state answer stops
the run. An error status stays an HTTPError, as api_request expects.
One fix at the shared helper covers both callers.

The same review asked for precise docs. The research digest now links
each external source and limits the signed-commit claim to the publish
job's commits. ADR-3519, the digest, the badge guide and the script
note no longer treat 15 minutes as a maximum badge age: GitHub can
start a scheduled run late or drop it under load. They also say that a
failed source turns its run red at once while the badge keeps its last
value for six hours.

Signed-off-by: lusoris <lusoris@proton.me>
---
 .../adr/3519-readme-badges-rendered-branch.md | 14 ++++----
 docs/development/readme-badges.md             | 20 ++++++-----
 .../3519-readme-badges-rendered-branch.md     | 23 ++++++-------
 scripts/ci/AGENTS.d/readme-badges.md          |  2 +-
 scripts/ci/ci_tier.py                         | 14 ++++++--
 scripts/ci/tests/test_ci_tier.py              | 29 ++++++++++++++++
 scripts/ci/tests/test_readme_badges.py        | 33 +++++++++++++++++++
 7 files changed, 105 insertions(+), 30 deletions(-)

diff --git a/docs/adr/3519-readme-badges-rendered-branch.md b/docs/adr/3519-readme-badges-rendered-branch.md
index 503d61bc58..4ed6e64469 100644
--- a/docs/adr/3519-readme-badges-rendered-branch.md
+++ b/docs/adr/3519-readme-badges-rendered-branch.md
@@ -23,8 +23,8 @@ a badge reports.
 ## Decision
 
 We render the ten status badges ourselves.
-`.github/workflows/readme-badges.yml` runs every 15 minutes and on demand: its
-render job (`actions: read`, `contents: read`) runs
+`.github/workflows/readme-badges.yml` is scheduled every 15 minutes and runs
+on demand: its render job (`actions: read`, `contents: read`) runs
 `scripts/ci/readme_badges.py spec`, which reads the newest decisive push run of
 each badged workflow on the default branch and the public Scorecard, Best
 Practices and Codacy APIs, and `tools/badges/render.mjs` draws the SVGs with
@@ -33,17 +33,17 @@ Practices and Codacy APIs, and `tools/badges/render.mjs` draws the SVGs with
 the SVGs and `state.json` to the `badges` branch through the GitHub API, and
 the README links `https://raw.githubusercontent.com/VMAFx/vmafx/badges/<slug>.svg`.
 Both jobs run only on the default branch and check out the commit the run
-started from. A source that fails keeps its last value for six hours, then
-reads `stale`, and the run turns red. Every other README badge, the backends
-row included, uses `for-the-badge`; the one exception is the Praetor
-governance badge, which Praetor writes. The full rules are in
+started from. A source that fails turns the run red at once; its badge keeps
+the last value for six hours, then reads `stale`. Every other README badge,
+the backends row included, uses `for-the-badge`; the one exception is the
+Praetor governance badge, which Praetor writes. The full rules are in
 [docs/development/readme-badges.md](../development/readme-badges.md).
 
 ## Alternatives considered
 
 | Option | Pros | Cons | Why not chosen |
 |---|---|---|---|
-| Rendered badges on a `badges` branch, schedule trigger (chosen) | One design; the project decides which run a badge shows; Scorecard shows its score; no third-party request per page view | Up to 15 minutes of lag; a job with `contents: write`; a branch that grows by about one commit an hour | Chosen |
+| Rendered badges on a `badges` branch, schedule trigger (chosen) | One design; the project decides which run a badge shows; Scorecard shows its score; no third-party request per page view | About 15 minutes of lag, more when GitHub delays a scheduled run; a job with `contents: write`; a branch that grows by about one commit an hour | Chosen |
 | Same, triggered by `workflow_run` | Badge within a minute of a master run | zizmor rates `workflow_run` a dangerous trigger; its `branches: [master]` filter matches a fork's branch named `master` too | The 15-minute lag is the smaller cost |
 | shields.io dynamic URLs with `style=for-the-badge` | No workflow or branch; one design | Each page view depends on shields.io; the workflow badge scrapes GitHub's `badge.svg`, so run selection stays GitHub's; Scorecard and Codacy would need per-service shields routes | Keeps a third party on every page view and leaves run selection out of reach |
 | Keep each service's own badge | Nothing to build | Four designs in one block, against ADR-3366; the Scorecard badge shows no score | It is the defect this decision fixes |
diff --git a/docs/development/readme-badges.md b/docs/development/readme-badges.md
index 3f650b2627..bdc43b3f0c 100644
--- a/docs/development/readme-badges.md
+++ b/docs/development/readme-badges.md
@@ -10,8 +10,10 @@ each one with
 
 ## Where a badge value comes from
 
-The README Badges workflow (`.github/workflows/readme-badges.yml`) runs every
-15 minutes, at minutes 7, 22, 37 and 52, and on demand:
+The README Badges workflow (`.github/workflows/readme-badges.yml`) is
+scheduled every 15 minutes, at minutes 7, 22, 37 and 52, and runs on demand.
+GitHub can start a scheduled run late, or drop it, when Actions is under load,
+so 15 minutes is the intended step, not a promise:
 
 ```bash
 gh workflow run readme-badges.yml -R VMAFx/vmafx
@@ -51,10 +53,11 @@ with the time each one was read. A time without a UTC offset, or one that
 cannot be read, counts as stale.
 
 The six hours run from the read time `state.json` holds. A run whose SVGs are
-all unchanged commits nothing for an hour (see below), so that time trails the
-last successful read by at most one hour plus one 15-minute schedule step. A
-badge can therefore turn `stale` up to 75 minutes before six hours have passed
-since its last successful read, and at most one schedule step after.
+all unchanged commits nothing for an hour (see below), so with runs on
+schedule that time trails the last successful read by up to one hour plus one
+15-minute schedule step. A badge can therefore turn `stale` up to 75 minutes
+before six hours have passed since its last successful read, and one schedule
+step after, plus any delay GitHub adds to a scheduled run.
 Committing `state.json` on every run would close that gap at the cost of
 about four commits an hour instead of one.
 
@@ -97,7 +100,7 @@ A `workflow_run` trigger would refresh a badge within a minute of each master
 run. zizmor rates `workflow_run` a dangerous trigger, and its
 `branches: [master]` filter matches the branch name only, so a pull request
 from a fork's branch named `master` would start it too. The schedule costs up
-to 15 minutes of lag and has neither problem.
+to 15 minutes of lag, more when GitHub delays a run, and has neither problem.
 
 ## Limits
 
@@ -105,7 +108,8 @@ to 15 minutes of lag and has neither problem.
   scheduled runs paused after 60 days without repository activity), no run
   starts, so none turns red, and the badges keep showing the last values,
   green ones included. The signal is a missing run: the newest README Badges
-  run is older than 15 minutes. Check it, then re-enable the workflow:
+  run is more than an hour old (a single scheduled run can start late or be
+  dropped). Check it, then re-enable the workflow:
 
   ```bash
   gh run list -R VMAFx/vmafx --workflow readme-badges.yml --limit 1 --json createdAt,conclusion
diff --git a/docs/research/3519-readme-badges-rendered-branch.md b/docs/research/3519-readme-badges-rendered-branch.md
index 51c04b233a..2cf1e950d0 100644
--- a/docs/research/3519-readme-badges-rendered-branch.md
+++ b/docs/research/3519-readme-badges-rendered-branch.md
@@ -11,15 +11,16 @@ How can the ten README status badges (seven workflow badges, OpenSSF Scorecard,
 
 ## Sources
 
-- `services/github/github-actions-workflow-status.service.js` in the shields repository (read 2026-11-10): the shields.io workflow badge fetches GitHub's own `badge.svg` and reads its text.
-- GitHub REST API "List workflow runs for a workflow" (`GET /repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs`): `branch`, `event`, `status` and `per_page` filters; default page size 30.
-- GitHub Docs, "Creating rulesets for a repository", section "Granting bypass permissions" (read 2026-11-10): the eligible bypass actors are repository admins and owners, the maintain or write role, teams, GitHub Apps and Dependabot.
-- GitHub Docs, "About commit signature verification", section "Signature verification for bots": GitHub signs commits a GitHub App or the workflow token creates through the API when no custom author or committer is set.
-- Commit `e3d3cbcb602af571f93a1cc72e71ed71fad14b38` (an API commit by a GitHub App bot): committer `web-flow`, signature verified.
-- A gh-aw issue opened 2026-10-30 and the Codex Review Gate marketplace page (read 2026-11-10): the workflow token cannot be added as a ruleset bypass actor on its own; integration id 15368 names the whole GitHub Actions App, not one workflow.
-- zizmor audit `dangerous-triggers`: rates `workflow_run` and `pull_request_target` as dangerous triggers.
+- [`services/github/github-actions-workflow-status.service.js`](https://github.com/badges/shields/blob/master/services/github/github-actions-workflow-status.service.js) in the shields repository (read 2026-11-10): the shields.io workflow badge fetches GitHub's own `badge.svg` and reads its text.
+- GitHub REST API, ["List workflow runs for a workflow"](https://docs.github.com/en/rest/actions/workflow-runs?apiVersion=2022-11-28#list-workflow-runs-for-a-workflow) (`GET /repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs`): `branch`, `event`, `status` and `per_page` filters; default page size 30.
+- Ruleset bypass actors, from ["Creating rulesets for a repository"](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#granting-bypass-permissions-for-your-branch-or-tag-ruleset), section "Granting bypass permissions for your branch or tag ruleset" (GitHub Docs, read 2026-11-10): the eligible bypass actors are repository admins and owners, the maintain or write role, teams, GitHub Apps and Dependabot.
+- Bot commit signing, from ["About commit signature verification"](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification#signature-verification-for-bots), section "Signature verification for bots" (GitHub Docs): GitHub signs commits a GitHub App or the workflow token creates through the API when no custom author or committer is set.
+- Commit [`e3d3cbcb602af571f93a1cc72e71ed71fad14b38`](https://github.com/VMAFx/vmafx/commit/e3d3cbcb602af571f93a1cc72e71ed71fad14b38) in this repository (an API commit by a GitHub App bot): committer `web-flow`, signature verified.
+- [gh-aw issue 73207](https://github.com/github/gh-aw/issues/73207) (opened 2026-10-30) and the [Codex Review Gate marketplace page](https://github.com/marketplace/actions/codex-review-gate) (read 2026-11-10): the workflow token cannot be added as a ruleset bypass actor on its own; integration id 15368 names the whole GitHub Actions App, not one workflow.
+- Scheduled runs, from ["Events that trigger workflows", section `schedule`](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#schedule) (GitHub Docs, read 2026-11-10): a scheduled run can start late when Actions is under load, most often at the start of an hour, and queued jobs can be dropped; scheduled workflows in a public repository are disabled after 60 days without activity.
+- zizmor audit [`dangerous-triggers`](https://docs.zizmor.sh/audits/#dangerous-triggers): rates `workflow_run` and `pull_request_target` as dangerous triggers.
 - [docs/principles.md](../principles.md) section 6 and [ADR-1247](../adr/1247-scorecard-exact-head-gates.md): unrounded Scorecard ≥ 8.5 required on master.
-- `badge-maker` 6.0.0, the shields.io renderer, pinned in `tools/badges/package-lock.json`.
+- [`badge-maker` 6.0.0](https://www.npmjs.com/package/badge-maker/v/6.0.0), the shields.io renderer, pinned in `tools/badges/package-lock.json`.
 - `scripts/ci/readme_badges.py`, `.github/workflows/readme-badges.yml`, `scripts/ci/check_repository_security.py` and `.github/repository-security-policy.json` on the pull request 3393 branch.
 
 ## Findings
@@ -28,13 +29,13 @@ How can the ten README status badges (seven workflow badges, OpenSSF Scorecard,
 
 2. **Run choice.** GitHub's badge shows the latest run, so a cancelled or skipped run hides a failed one. `readme_badges.py` lists completed push runs on the default branch (`per_page` = `RUNS_PER_PAGE` = 30) and takes the newest one with a conclusion other than cancelled or skipped (`PASSED_OVER`). `success` reads passing; `failure`, `timed_out` and `startup_failure` read failing; any other conclusion reads `unknown`. An older run never stands in for a newer decisive one. When all 30 runs are passed over, the badge reads `unknown` rather than paging further back.
 
-3. **Trigger.** A `workflow_run` trigger would refresh a badge within a minute of a master run, but zizmor rates it a dangerous trigger, and its `branches: [master]` filter also matches a fork's branch named `master`. A schedule (`7,22,37,52 * * * *`) with a default-branch guard on the render job and checkouts at `github.sha` has no outside input and lags by at most one 15-minute step.
+3. **Trigger.** A `workflow_run` trigger would refresh a badge within a minute of a master run, but zizmor rates it a dangerous trigger, and its `branches: [master]` filter also matches a fork's branch named `master`. A schedule (`7,22,37,52 * * * *`) with a default-branch guard on the render job and checkouts at `github.sha` has no outside input. Fifteen minutes is the intended step, not a bound on a badge's age: GitHub can start a scheduled run late or drop it when Actions is under load, and the minutes 7, 22, 37 and 52 stay clear of the busy start of the hour.
 
 4. **Rights.** `contents: write` cannot be limited to one branch. The master ruleset requires a pull request and the workflow token holds no bypass, so the token cannot move `master`. The token also cannot be named as a ruleset bypass actor: the eligible actors are roles, teams, GitHub Apps and Dependabot, and the GitHub Actions App (integration 15368) covers every workflow in the repository. A `badges` ruleset that refuses deletion and non-fast-forward pushes therefore still lets any workflow with `contents: write` add forward commits; refusing every other writer needs a dedicated GitHub App as the only bypass actor.
 
-5. **Signed commits.** Commits the workflow token creates through the Git data API with no custom author or committer are signed by GitHub and show as verified (committer `web-flow`). The publish job sets no author or committer, so the `badges` branch carries only verified commits without any signing key in the workflow.
+5. **Signed commits.** Commits the workflow token creates through the Git data API with no custom author or committer are signed by GitHub and show as verified (committer `web-flow`). The publish job sets no author or committer and moves the branch only to a commit GitHub reports as verified, so every commit the publish job adds is verified without any signing key in the workflow. That covers the publish job's commits, not the whole branch: until issue 3394 lands, another writer with `contents: write` can add commits of its own (finding 4).
 
-6. **Staleness.** A source that fails keeps its last value for `STALE_AFTER` = 6 hours, then reads `stale` and turns the run red. The publish job skips the commit while every SVG matches the branch and the branch's last commit is younger than `QUIET_WINDOW` = 1 hour, so the read time `state.json` records can lag the true last read by up to 1 hour plus one 15-minute step: `stale` can come up to 75 minutes early, and at most one schedule step late. Committing `state.json` on every run would remove that lag at the cost of about four commits an hour instead of one.
+6. **Staleness.** A source that fails turns that run red at once: its `verdict` step exits 1. The badge itself keeps the last value for `STALE_AFTER` = 6 hours and then reads `stale`. The publish job skips the commit while every SVG matches the branch and the branch's last commit is younger than `QUIET_WINDOW` = 1 hour, so with runs on schedule the read time `state.json` records can lag the true last read by up to 1 hour plus one 15-minute step: `stale` can come up to 75 minutes early, and one schedule step late plus any delay GitHub adds to a scheduled run. Committing `state.json` on every run would remove that lag at the cost of about four commits an hour instead of one.
 
 7. **Scorecard threshold.** The badge is green from an unrounded 8.5, the gate [docs/principles.md](../principles.md) and [ADR-1247](../adr/1247-scorecard-exact-head-gates.md) set for master. A score of 8.46 shows `8.5 / 10` in amber, so the rounded text never hides a miss.
 
diff --git a/scripts/ci/AGENTS.d/readme-badges.md b/scripts/ci/AGENTS.d/readme-badges.md
index 499bc0edf4..ff501d0133 100644
--- a/scripts/ci/AGENTS.d/readme-badges.md
+++ b/scripts/ci/AGENTS.d/readme-badges.md
@@ -17,7 +17,7 @@ area: gates
 - Run choice: workflow badge = newest push run on default branch with a conclusion, not cancelled or skipped (`PASSED_OVER`). `success` -> passing; `failure`, `timed_out`, `startup_failure` -> failing; other conclusion -> `unknown`, never older run's value. Never "latest run".
 - Scorecard: green from unrounded `SCORE_GREEN` = 8.5 (master requirement, `docs/principles.md`, ADR-1247); shown value rounded to 1 decimal, colour from unrounded score.
 - Renderer allow-list: keys `slug`, `label`, `message`, `color` only; text `[\x20-\x7e]{1,40}`; colour `#[0-9a-f]{6}`. `TEXT` / `COLOR` in Python and `render.mjs` stay equal (test compares both).
-- Carry: failed source keeps last value `STALE_AFTER` = 6 h from `state.json` read time, then `stale` grey; naive or unreadable time = stale (`read_time`). Recorded time trails real read <= `QUIET_WINDOW` + 15 min schedule (test pins bound); accepted trade-off vs 4 commits/h. `verdict` step exits 1 on any failed source.
+- Carry: failed source keeps last value `STALE_AFTER` = 6 h from `state.json` read time, then `stale` grey; naive or unreadable time = stale (`read_time`). Recorded time trails real read <= `QUIET_WINDOW` + one 15 min step when runs start on time (test pins bound); accepted trade-off vs 4 commits/h. GitHub may delay or drop scheduled runs: 15 min = intended step, never stated as max badge age. `verdict` step exits 1 on any failed source.
 - State read: `previous_state` 404 = new branch, empty; any other failure -> `BadgeError`, run stops, nothing rendered or published. Never return empty state on failed read.
 - Publish: one commit via Git data API; GitHub-signed commit required (unverified -> no ref move); `force: false`; ref path only `refs/heads/badges`; no commit when SVGs unchanged and head < `QUIET_WINDOW` = 1 h old.
 - Tokens: `GITHUB_TOKEN` only to `api.github.com`; Scorecard, Best Practices, Codacy reads carry no token.
diff --git a/scripts/ci/ci_tier.py b/scripts/ci/ci_tier.py
index b96ad25ed4..ed51f5aa17 100644
--- a/scripts/ci/ci_tier.py
+++ b/scripts/ci/ci_tier.py
@@ -36,6 +36,7 @@
 from __future__ import annotations
 
 import argparse
+import http.client
 import json
 import os
 import shutil
@@ -218,15 +219,22 @@ def https_json(
     """One https request whose answer is JSON, bounded in time and in size.
 
     The scheme check and the size cap live here so every caller gets them; an
-    empty answer reads as an empty object.
+    empty answer reads as an empty object. A broken answer (cut off, a bad
+    status line, an overlong header) raises ``http.client.HTTPException``,
+    which is no ``OSError``; it becomes a ``TierError`` here so every caller
+    treats it as the failed request it is. An error status stays an
+    ``HTTPError`` for the caller to read its code.
     """
     if urllib.parse.urlsplit(url).scheme != "https":
         raise TierError(f"refusing a non-https API URL: {url}")
     request = urllib.request.Request(  # noqa: S310 - the scheme is checked above
         url, method=method, data=data, headers=dict(headers)
     )
-    with HTTPS_OPENER.open(request, timeout=timeout_s) as response:
-        body = response.read(limit + 1)
+    try:
+        with HTTPS_OPENER.open(request, timeout=timeout_s) as response:
+            body = response.read(limit + 1)
+    except http.client.HTTPException as exc:
+        raise TierError(f"{url}: broken answer ({type(exc).__name__}: {exc})") from exc
     if len(body) > limit:
         raise TierError(f"{url}: answer larger than {limit} bytes")
     return json.loads(body.decode("utf-8")) if body else {}
diff --git a/scripts/ci/tests/test_ci_tier.py b/scripts/ci/tests/test_ci_tier.py
index c81190dd89..6cc5b3ef3c 100644
--- a/scripts/ci/tests/test_ci_tier.py
+++ b/scripts/ci/tests/test_ci_tier.py
@@ -232,6 +232,35 @@ def test_the_caller_headers_go_out_and_nothing_else(self) -> None:
         self.assertEqual(request.get_header("Accept"), "application/json")
         self.assertIsNone(request.get_header("Authorization"))
 
+    def test_a_broken_answer_is_a_tier_error(self) -> None:
+        """A cut-off body or a broken status line on open or read is a TierError."""
+        for where, error in (
+            ("read", http.client.IncompleteRead(b"par")),
+            ("read", http.client.LineTooLong("header line")),
+            ("open", http.client.BadStatusLine("x")),
+            ("open", http.client.RemoteDisconnected("closed")),
+        ):
+            with self.subTest(where=where, error=type(error).__name__):
+                opened = mock.MagicMock()
+                opened.__enter__.return_value.read.side_effect = error
+                kind = {"return_value": opened} if where == "read" else {"side_effect": error}
+                with (
+                    mock.patch.object(ci_tier.HTTPS_OPENER, "open", **kind),
+                    self.assertRaisesRegex(ci_tier.TierError, type(error).__name__),
+                ):
+                    ci_tier.https_json("GET", "https://h/x", {}, None, 5, 10)
+
+    def test_an_error_status_stays_an_http_error(self) -> None:
+        """An error status is not turned into a TierError; callers read its code."""
+        error = urllib.error.HTTPError("https://h/x", 404, "Not Found", None, None)  # type: ignore[arg-type]
+        with (
+            mock.patch.object(ci_tier.HTTPS_OPENER, "open", side_effect=error),
+            self.assertRaises(urllib.error.HTTPError) as raised,
+        ):
+            ci_tier.https_json("GET", "https://h/x", {}, None, 5, 10)
+        self.assertEqual(raised.exception.code, 404)
+        raised.exception.close()
+
     def test_a_non_https_url_is_refused_before_any_request(self) -> None:
         """A non-https URL is refused before the opener is called."""
         with mock.patch.object(ci_tier.HTTPS_OPENER, "open") as sent:
diff --git a/scripts/ci/tests/test_readme_badges.py b/scripts/ci/tests/test_readme_badges.py
index 9d01f26e04..29ec16be3d 100644
--- a/scripts/ci/tests/test_readme_badges.py
+++ b/scripts/ci/tests/test_readme_badges.py
@@ -7,6 +7,7 @@
 
 import base64
 import email.message
+import http.client
 import io
 import json
 import re
@@ -377,6 +378,23 @@ def read(badge: rb.Badge, error: Exception = error) -> rb.Value:
                 self.assertEqual(len(failures), 1)
                 self.assertTrue(failures[0].startswith("go: "))
 
+    def test_a_cut_off_answer_keeps_the_last_value(self) -> None:
+        """A source whose answer breaks off mid-body keeps its last value."""
+        previous = {"go": entry(fetched=rb.stamp(NOW - timedelta(hours=1)))}
+        opened = mock.MagicMock()
+        opened.__enter__.return_value.read.side_effect = http.client.IncompleteRead(b"par")
+
+        def read(badge: rb.Badge) -> rb.Value:
+            """Read a public source the way the real readers do."""
+            rb.public_json("https://h/x")
+            return rb.PASSING
+
+        with mock.patch.object(ci_tier.HTTPS_OPENER, "open", return_value=opened):
+            entries, failures = rb.refresh(self.BADGE, previous, NOW, read)
+        self.assertEqual(entries["go"]["message"], "passing")
+        self.assertEqual(len(failures), 1)
+        self.assertIn("IncompleteRead", failures[0])
+
     def test_an_unexpected_error_is_not_swallowed(self) -> None:
         """An error outside the expected kinds propagates."""
 
@@ -424,6 +442,21 @@ def test_a_handled_error_is_closed(self) -> None:
             rb.previous_state(self.fetch(failed), REPO)
         self.assertTrue(failed.fp.closed)
 
+    def test_a_broken_state_answer_stops_the_run(self) -> None:
+        """A state.json answer with a broken status line stops the run, not a crash."""
+
+        def github(path: str) -> object:
+            """Read the state file through the real API helper."""
+            return ci_tier.api_request("GET", "https://api.github.com" + path, "t")
+
+        with (
+            mock.patch.object(
+                ci_tier.HTTPS_OPENER, "open", side_effect=http.client.BadStatusLine("x")
+            ),
+            self.assertRaisesRegex(rb.BadgeError, "BadStatusLine"),
+        ):
+            rb.previous_state(github, REPO)
+
     def test_the_badges_of_the_state_file_are_read(self) -> None:
         """The badges object of state.json is returned."""
         text = json.dumps({"badges": {"go": entry()}}).encode()

From 470bfaacc85159b6e8124c0982724c00f39db676 Mon Sep 17 00:00:00 2001
From: lusoris <lusoris@proton.me>
Date: Tue, 10 Nov 2026 21:47:58 +0100
Subject: [PATCH 6/7] fix(ci): commit a recovered badge's new read time

CodeRabbit found that a source which recovers with its old value after
a long outage left the old read time on the badges branch. The SVG was
unchanged and the last commit young, so the publish job skipped the
commit, and a failure soon after could show stale well before six hours
had passed since the last good read.

The publish job now skips only while the branch's state.json also holds
each badge's read time less than an hour before this run's
(reads_recorded, read_lag). A missing, unreadable, future or one-sided
read time means a commit. The recorded time therefore trails the last
successful read by less than an hour, so stale comes at most an hour
early instead of 75 minutes. ADR-3519, its research digest, the badge
guide and the script notes now state that bound.

A regression test runs the outage, the unchanged recovery and a later
failure, and eight planted mutants of the new rule each fail the suite.

Signed-off-by: lusoris <lusoris@proton.me>
---
 .../adr/3519-readme-badges-rendered-branch.md |   8 +-
 docs/development/readme-badges.md             |  18 ++-
 .../3519-readme-badges-rendered-branch.md     |   4 +-
 scripts/ci/AGENTS.d/readme-badges.md          |   4 +-
 scripts/ci/readme_badges.py                   |  52 ++++++-
 scripts/ci/tests/test_readme_badges.py        | 127 +++++++++++++++++-
 6 files changed, 187 insertions(+), 26 deletions(-)

diff --git a/docs/adr/3519-readme-badges-rendered-branch.md b/docs/adr/3519-readme-badges-rendered-branch.md
index 4ed6e64469..7503fc006c 100644
--- a/docs/adr/3519-readme-badges-rendered-branch.md
+++ b/docs/adr/3519-readme-badges-rendered-branch.md
@@ -61,9 +61,11 @@ Praetor governance badge, which Praetor writes. The full rules are in
   forces, and the master ruleset requires a pull request, so the token cannot
   move `master`. An SVG cannot age by itself: if the workflow stops, the
   badges keep their last values until someone sees the missing run. The six
-  hours count from the read time `state.json` records, which an unchanged
-  badge refreshes only once an hour, so `stale` can come up to 75 minutes
-  early; committing on every run would quadruple the branch's growth.
+  hours count from the read time `state.json` records. A run with unchanged
+  SVGs commits once a badge's new read time is an hour or more newer than the
+  recorded one, so the recorded time trails the last successful read by less
+  than an hour and `stale` can come up to an hour early; committing on every
+  run would quadruple the branch's growth.
 - **Neutral / follow-ups**: issue 3394 tracks publishing with a dedicated
   GitHub App token instead of the workflow token, plus a second ruleset on
   `refs/heads/badges`, managed by `scripts/dev/check_repository_security.py`,
diff --git a/docs/development/readme-badges.md b/docs/development/readme-badges.md
index bdc43b3f0c..aea0f8b3a1 100644
--- a/docs/development/readme-badges.md
+++ b/docs/development/readme-badges.md
@@ -53,11 +53,12 @@ with the time each one was read. A time without a UTC offset, or one that
 cannot be read, counts as stale.
 
 The six hours run from the read time `state.json` holds. A run whose SVGs are
-all unchanged commits nothing for an hour (see below), so with runs on
-schedule that time trails the last successful read by up to one hour plus one
-15-minute schedule step. A badge can therefore turn `stale` up to 75 minutes
-before six hours have passed since its last successful read, and one schedule
-step after, plus any delay GitHub adds to a scheduled run.
+all unchanged still commits once a badge's new read time is an hour or more
+newer than the one on the branch (see below), so that time trails the last
+successful read by less than an hour, also right after a source recovers with
+its old value. A badge can therefore turn `stale` up to an hour before six
+hours have passed since its last successful read, and one schedule step after,
+plus any delay GitHub adds to a scheduled run.
 Committing `state.json` on every run would close that gap at the cost of
 about four commits an hour instead of one.
 
@@ -74,8 +75,11 @@ GitHub API:
 - GitHub signs the commit. A commit that comes back unverified is not
   published, and the branch stays where it was.
 - The branch only moves forward (`force: false`).
-- When every SVG is unchanged and the last commit is less than an hour old,
-  nothing is committed, so the branch grows by about one commit an hour.
+- When every SVG is unchanged, the last commit is less than an hour old, and
+  `state.json` on the branch holds each badge's read time less than an hour
+  before this run's, nothing is committed, so the branch grows by about one
+  commit an hour. A read time that is missing, unreadable, in the future or on
+  one side only means a commit.
 - A commit made with the workflow token starts no other workflow.
 
 The job's token has `contents: write`, the narrowest right that can make a
diff --git a/docs/research/3519-readme-badges-rendered-branch.md b/docs/research/3519-readme-badges-rendered-branch.md
index 2cf1e950d0..3d0a8246b5 100644
--- a/docs/research/3519-readme-badges-rendered-branch.md
+++ b/docs/research/3519-readme-badges-rendered-branch.md
@@ -35,7 +35,7 @@ How can the ten README status badges (seven workflow badges, OpenSSF Scorecard,
 
 5. **Signed commits.** Commits the workflow token creates through the Git data API with no custom author or committer are signed by GitHub and show as verified (committer `web-flow`). The publish job sets no author or committer and moves the branch only to a commit GitHub reports as verified, so every commit the publish job adds is verified without any signing key in the workflow. That covers the publish job's commits, not the whole branch: until issue 3394 lands, another writer with `contents: write` can add commits of its own (finding 4).
 
-6. **Staleness.** A source that fails turns that run red at once: its `verdict` step exits 1. The badge itself keeps the last value for `STALE_AFTER` = 6 hours and then reads `stale`. The publish job skips the commit while every SVG matches the branch and the branch's last commit is younger than `QUIET_WINDOW` = 1 hour, so with runs on schedule the read time `state.json` records can lag the true last read by up to 1 hour plus one 15-minute step: `stale` can come up to 75 minutes early, and one schedule step late plus any delay GitHub adds to a scheduled run. Committing `state.json` on every run would remove that lag at the cost of about four commits an hour instead of one.
+6. **Staleness.** A source that fails turns that run red at once: its `verdict` step exits 1. The badge itself keeps the last value for `STALE_AFTER` = 6 hours and then reads `stale`. The publish job skips the commit only while every SVG matches the branch, the branch's last commit is younger than `QUIET_WINDOW` = 1 hour, and the branch's `state.json` holds each badge's read time less than an hour before this run's. The read time `state.json` records therefore lags the last successful read by less than an hour, also when a source recovers with its old value: `stale` can come up to an hour early, and one schedule step late plus any delay GitHub adds to a scheduled run. Committing `state.json` on every run would remove that lag at the cost of about four commits an hour instead of one.
 
 7. **Scorecard threshold.** The badge is green from an unrounded 8.5, the gate [docs/principles.md](../principles.md) and [ADR-1247](../adr/1247-scorecard-exact-head-gates.md) set for master. A score of 8.46 shows `8.5 / 10` in amber, so the rounded text never hides a miss.
 
@@ -47,7 +47,7 @@ How can the ten README status badges (seven workflow badges, OpenSSF Scorecard,
 - **shields.io dynamic URLs with `style=for-the-badge`**: Rejected. Every page view depends on shields.io, and the workflow badge keeps GitHub's run choice.
 - **Each service's own badge**: Rejected. Four designs in one block and a Scorecard badge without a score.
 - **GitHub Pages files**: Rejected. Pages deploys the documentation site; a second deploy path for ten files is not worth it.
-- **Commit `state.json` on every run**: Rejected. Removes the 75-minute early `stale`, but quadruples the branch's growth.
+- **Commit `state.json` on every run**: Rejected. Removes the up to one hour early `stale`, but quadruples the branch's growth.
 - **Rendered SVGs on a `badges` branch, schedule trigger, workflow token**: Chosen.
 
 ## Open questions
diff --git a/scripts/ci/AGENTS.d/readme-badges.md b/scripts/ci/AGENTS.d/readme-badges.md
index ff501d0133..1b638602c1 100644
--- a/scripts/ci/AGENTS.d/readme-badges.md
+++ b/scripts/ci/AGENTS.d/readme-badges.md
@@ -17,9 +17,9 @@ area: gates
 - Run choice: workflow badge = newest push run on default branch with a conclusion, not cancelled or skipped (`PASSED_OVER`). `success` -> passing; `failure`, `timed_out`, `startup_failure` -> failing; other conclusion -> `unknown`, never older run's value. Never "latest run".
 - Scorecard: green from unrounded `SCORE_GREEN` = 8.5 (master requirement, `docs/principles.md`, ADR-1247); shown value rounded to 1 decimal, colour from unrounded score.
 - Renderer allow-list: keys `slug`, `label`, `message`, `color` only; text `[\x20-\x7e]{1,40}`; colour `#[0-9a-f]{6}`. `TEXT` / `COLOR` in Python and `render.mjs` stay equal (test compares both).
-- Carry: failed source keeps last value `STALE_AFTER` = 6 h from `state.json` read time, then `stale` grey; naive or unreadable time = stale (`read_time`). Recorded time trails real read <= `QUIET_WINDOW` + one 15 min step when runs start on time (test pins bound); accepted trade-off vs 4 commits/h. GitHub may delay or drop scheduled runs: 15 min = intended step, never stated as max badge age. `verdict` step exits 1 on any failed source.
+- Carry: failed source keeps last value `STALE_AFTER` = 6 h from `state.json` read time, then `stale` grey; naive or unreadable time = stale (`read_time`). Recorded time trails last successful read < `QUIET_WINDOW` (`reads_recorded`), recovery with same value included (regression test pins it); `stale` <= 1 h early, <= 1 step late; accepted trade-off vs 4 commits/h. GitHub may delay or drop scheduled runs: 15 min = intended step, never stated as max badge age. `verdict` step exits 1 on any failed source.
 - State read: `previous_state` 404 = new branch, empty; any other failure -> `BadgeError`, run stops, nothing rendered or published. Never return empty state on failed read.
-- Publish: one commit via Git data API; GitHub-signed commit required (unverified -> no ref move); `force: false`; ref path only `refs/heads/badges`; no commit when SVGs unchanged and head < `QUIET_WINDOW` = 1 h old.
+- Publish: one commit via Git data API; GitHub-signed commit required (unverified -> no ref move); `force: false`; ref path only `refs/heads/badges`; no commit only when SVGs unchanged, head < `QUIET_WINDOW` = 1 h old, and branch `state.json` holds each badge read time 0 to < `QUIET_WINDOW` before this run's (`reads_recorded`); missing, unreadable, future or one-sided time -> commit.
 - Tokens: `GITHUB_TOKEN` only to `api.github.com`; Scorecard, Best Practices, Codacy reads carry no token.
 - Requests: every call through `ci_tier.https_json` (https only, size cap: public `MAX_RESPONSE_BYTES`, GitHub API `ci_tier.API_MAX_BYTES`); no second request helper. `HTTPS_OPENER` has no redirect handler: 3xx = `HTTPError`, `Authorization` never resent elsewhere. JSON answers read with `field()`, never bare indexing.
 - Design check: `readme_badges.py check-readme` (hook `readme-badge-design`) fails README image unless rendered `badges`-branch SVG, shields.io badge with `style=for-the-badge` + `labelColor=111a35`, or repo-local file that exists. Rendered + governance badges must name home repository (`home_repository()` from `.github/repository-security-policy.json`, case-insensitive); other repo or fork fails. Local path: `missing_file` resolves symlinks, fails outside README dir or no file. Fences + code spans ignored. Only exception: `praetor-docs.yml/badge.svg` inside `praetor:readme-governance` block (`governance_badge()`) until Praetor issue 1893 lands; then drop exception.
diff --git a/scripts/ci/readme_badges.py b/scripts/ci/readme_badges.py
index b611dad15a..c646c8d7a5 100644
--- a/scripts/ci/readme_badges.py
+++ b/scripts/ci/readme_badges.py
@@ -399,14 +399,53 @@ def branch_head(call: Call, repository: str) -> dict[str, str] | None:
     }
 
 
+def read_lag(recorded: object, fresh: object) -> timedelta | None:
+    """How far a recorded state entry's read time trails a fresh one's; ``None`` if incomparable.
+
+    Two entries that both lack a read time trail by nothing. An entry this
+    script would not write, or a read time on one side only or unreadable,
+    cannot be compared.
+    """
+    old, new = usable(recorded), usable(fresh)
+    if old is None or new is None:
+        return None
+    old_at, new_at = old["fetched_at"], new["fetched_at"]
+    if old_at is None or new_at is None:
+        return timedelta(0) if old_at == new_at else None
+    then, latest = read_time(old_at), read_time(new_at)
+    return latest - then if then is not None and latest is not None else None
+
+
+def reads_recorded(call: Call, repository: str, files: Mapping[str, bytes]) -> bool:
+    """True when the branch's state file holds every badge's read time well enough.
+
+    Well enough: for the same badges, each recorded read time lies less than
+    QUIET_WINDOW before the one about to be published, and not after it. A
+    source that recovers with its old value thus gets its new read time
+    committed, so a later failure carries that time, not the one from before
+    the outage. An unreadable state on either side means commit.
+    """
+    recorded, problem = previous_state(lambda path: call("GET", path, None), repository)
+    doc = json.loads(files[STATE].decode("utf-8"))
+    fresh = doc.get("badges") if isinstance(doc, dict) else None
+    if problem or not isinstance(fresh, dict) or set(recorded) != set(fresh):
+        return False
+    lags = (read_lag(recorded[slug], entry) for slug, entry in fresh.items())
+    return all(lag is not None and timedelta(0) <= lag < QUIET_WINDOW for lag in lags)
+
+
 def unchanged(
     call: Call, repository: str, head: Mapping[str, str], files: Mapping[str, bytes], now: datetime
 ) -> bool:
-    """True when every SVG matches the branch and its last commit is younger than QUIET_WINDOW.
-
-    The state file is left out on purpose: its read times change every run, so
-    comparing it would commit every run. The branch's read times therefore
-    trail the newest read by less than QUIET_WINDOW plus one schedule interval.
+    """True when a commit would add nothing the branch needs.
+
+    That is: the branch's last commit is younger than QUIET_WINDOW, every SVG
+    matches the branch, and the branch's state file already holds each
+    badge's read time to within QUIET_WINDOW (``reads_recorded``). The state
+    file's bytes are not compared, since its run time changes every run. So a
+    carried value's read time trails the newest successful read by less than
+    QUIET_WINDOW, and the commit-age rule keeps the branch's run time and
+    failure list from aging past it either.
     """
     committed = read_time(head["date"])
     if committed is None or now - committed >= QUIET_WINDOW:
@@ -417,7 +456,8 @@ def unchanged(
     current = {str(field(e, "path")): str(field(e, "sha")) for e in rows}
     if set(current) != set(files):
         return False
-    return all(current[name] == blob_sha(data) for name, data in files.items() if name != STATE)
+    svgs = (current[name] == blob_sha(data) for name, data in files.items() if name != STATE)
+    return all(svgs) and reads_recorded(call, repository, files)
 
 
 def publish(call: Call, repository: str, files: Mapping[str, bytes], now: datetime) -> str:
diff --git a/scripts/ci/tests/test_readme_badges.py b/scripts/ci/tests/test_readme_badges.py
index 29ec16be3d..558e690ac9 100644
--- a/scripts/ci/tests/test_readme_badges.py
+++ b/scripts/ci/tests/test_readme_badges.py
@@ -55,6 +55,12 @@ def answered(method: str, path: str, payload: object) -> object:
     return answered
 
 
+def state_file(fetched_at: str | None, slug: str = "go") -> bytes:
+    """A state file holding one passing badge read at ``fetched_at``."""
+    entry = {"message": "passing", "color": rb.GREEN, "fetched_at": fetched_at}
+    return json.dumps({"version": 1, "badges": {slug: entry}}).encode("utf-8")
+
+
 def http_error(code: int) -> urllib.error.HTTPError:
     """An HTTPError with ``code`` and an empty body, as urllib raises it."""
     return urllib.error.HTTPError(
@@ -584,7 +590,10 @@ def test_a_state_file_that_is_not_json_is_refused(self) -> None:
 class Publish(unittest.TestCase):
     """``publish`` writes one signed commit and moves the badges branch forward only."""
 
-    FILES: ClassVar[dict[str, bytes]] = {"go.svg": b"<svg >go</svg>", "state.json": b"{}"}
+    FILES: ClassVar[dict[str, bytes]] = {
+        "go.svg": b"<svg >go</svg>",
+        "state.json": state_file(rb.stamp(NOW)),
+    }
     OLD = rb.stamp(NOW - rb.QUIET_WINDOW)
 
     def fake(
@@ -593,14 +602,25 @@ def fake(
         date: str = OLD,
         verified: bool = True,
         tree_files: dict[str, bytes] | None = None,
+        state: bytes | None = None,
     ) -> tuple[rb.Call, list[tuple[str, str, Any]]]:
-        """A GitHub stub for ``publish`` that records each call; no ``head`` means no branch."""
+        """A GitHub stub for ``publish`` that records each call; no ``head`` means no branch.
+
+        ``state`` is the branch's state file, by default the one in ``FILES``.
+        """
         calls: list[tuple[str, str, Any]] = []
         tree_files = self.FILES if tree_files is None else tree_files
+        state = self.FILES["state.json"] if state is None else state
 
         def call(method: str, path: str, payload: object) -> object:
-            """Record the call and answer it like the Git data API."""
+            """Record the call; answer the state file read like the contents API."""
             calls.append((method, path, payload))
+            if path == f"/repos/{REPO}/contents/state.json?ref=badges":
+                return {"content": base64.b64encode(state).decode("ascii")}
+            return git(path)
+
+        def git(path: str) -> object:
+            """Answer like the Git data API."""
             if path.endswith("/git/ref/heads/badges"):
                 if head is None:
                     raise http_error(404)
@@ -688,6 +708,101 @@ def test_a_changed_svg_inside_the_quiet_window_is_committed(self) -> None:
         )
         self.assertEqual(rb.publish(call, REPO, self.FILES, NOW), "c1")
 
+    def young_publish(self, state: bytes, files: dict[str, bytes] | None = None) -> str:
+        """``publish`` against a head five minutes old with the same SVG and ``state`` on it."""
+        call, _ = self.fake("c0", date=rb.stamp(NOW - timedelta(minutes=5)), state=state)
+        return rb.publish(call, REPO, self.FILES if files is None else files, NOW)
+
+    def test_read_times_inside_the_quiet_window_commit_nothing(self) -> None:
+        """A recorded read time up to just under an hour before this run's commits nothing."""
+        for lag in (timedelta(0), rb.QUIET_WINDOW - timedelta(seconds=1)):
+            with self.subTest(lag=lag):
+                self.assertEqual(
+                    self.young_publish(state_file(rb.stamp(NOW - lag))), "unchanged at c0"
+                )
+
+    def test_a_recovered_read_time_is_committed_inside_the_quiet_window(self) -> None:
+        """A read time an hour or more newer than the branch's is committed, SVGs unchanged."""
+        for lag in (rb.QUIET_WINDOW, timedelta(hours=5)):
+            with self.subTest(lag=lag):
+                self.assertEqual(self.young_publish(state_file(rb.stamp(NOW - lag))), "c1")
+
+    def test_a_recorded_read_time_that_cannot_be_compared_is_committed(self) -> None:
+        """A future, unreadable, one-sided or missing recorded read time, or bad state, commits."""
+        cases = {
+            "future": state_file(rb.stamp(NOW + timedelta(seconds=1))),
+            "naive": state_file("2026-11-10T12:00:00"),
+            "none on the branch": state_file(None),
+            "other badge": state_file(rb.stamp(NOW), slug="lint"),
+            "extra badge": json.dumps(
+                {"badges": {**json.loads(state_file(rb.stamp(NOW)))["badges"], "lint": {}}}
+            ).encode(),
+            "entry not an object": b'{"badges": {"go": "passing"}}',
+            "no badges": b"{}",
+            "not json": b"{",
+        }
+        for name, state in cases.items():
+            with self.subTest(case=name):
+                self.assertEqual(self.young_publish(state), "c1")
+
+    def test_a_fresh_state_that_cannot_be_compared_is_committed(self) -> None:
+        """A run's own state without a read time, or without a badges object, commits."""
+        for state in (state_file(None), b"[]", b'{"badges": []}', b'{"badges": ["go"]}'):
+            with self.subTest(state=state):
+                files = {**self.FILES, "state.json": state}
+                self.assertEqual(self.young_publish(self.FILES["state.json"], files), "c1")
+
+    def test_an_unreadable_branch_state_is_committed_with_nothing_to_compare(self) -> None:
+        """A branch state.json that cannot be parsed is replaced even when no badge is listed."""
+        files = {**self.FILES, "state.json": b'{"badges": {}}'}
+        self.assertEqual(self.young_publish(b'{"badges": {}}', files), "unchanged at c0")
+        self.assertEqual(self.young_publish(b"{", files), "c1")
+
+    def test_no_read_time_on_both_sides_commits_nothing(self) -> None:
+        """A badge never read, on the branch and in this run, needs no commit."""
+        files = {**self.FILES, "state.json": state_file(None)}
+        self.assertEqual(self.young_publish(state_file(None), files), "unchanged at c0")
+
+    def test_a_missing_branch_state_file_is_committed(self) -> None:
+        """A branch without state.json (404) commits."""
+        call, _ = self.fake("c0", date=rb.stamp(NOW - timedelta(minutes=5)))
+
+        def answered(method: str, path: str, payload: object) -> object:
+            """Answer the state file read with 404; pass every other call on."""
+            if "/contents/" in path:
+                raise http_error(404)
+            return call(method, path, payload)
+
+        self.assertEqual(rb.publish(answered, REPO, self.FILES, NOW), "c1")
+
+    def test_a_failure_after_an_unchanged_recovery_carries_the_recovered_time(self) -> None:
+        """Outage, recovery with the same value, then a new failure: the badge stays current.
+
+        The branch holds the read time from before a five-hour outage and a
+        commit five minutes old. The source answers again with its old value,
+        so the SVG is unchanged; the publish still commits the new read time,
+        and a failure 75 minutes later keeps "passing" instead of "stale".
+        """
+        go = rb.Badge("go", "Go", "workflow", "go-ci.yml")
+        before = rb.stamp(NOW - timedelta(hours=5))
+        recovered, _ = rb.refresh((go,), {}, NOW, lambda b: rb.PASSING)
+        files = {**self.FILES, "state.json": json.dumps({"badges": recovered}).encode()}
+        call, calls = self.fake(
+            "c0", date=rb.stamp(NOW - timedelta(minutes=5)), state=state_file(before)
+        )
+        self.assertEqual(rb.publish(call, REPO, files, NOW), "c1")
+        tree = next(c[2]["tree"] for c in calls if c[1].endswith("/git/trees"))
+        branch = json.loads(next(e["content"] for e in tree if e["path"] == "state.json"))
+        later = NOW + timedelta(minutes=75)
+
+        def fails(badge: rb.Badge) -> rb.Value:
+            """The source fails again."""
+            raise rb.BadgeError(f"{badge.slug}: timed out")
+
+        entries, _ = rb.refresh((go,), branch["badges"], later, fails)
+        self.assertEqual(entries["go"]["message"], "passing")
+        self.assertEqual(entries["go"]["fetched_at"], rb.stamp(NOW))
+
     def test_a_ref_lookup_error_other_than_404_is_raised(self) -> None:
         """A failing ref lookup other than 404 propagates."""
 
@@ -1133,9 +1248,9 @@ def test_the_workflow_runs_only_on_the_policy_repository_and_branch(self) -> Non
 
     def test_a_carried_read_time_trails_by_less_than_the_stale_bound(self) -> None:
         """The quiet window plus the largest schedule gap stays under a quarter of six hours."""
-        # The state file is committed with the SVGs only once QUIET_WINDOW has
-        # passed, so its read times trail the newest read by at most that plus
-        # one schedule gap; that lag must stay well inside STALE_AFTER.
+        # The branch's state file holds each read time to within QUIET_WINDOW
+        # (reads_recorded), so `stale` comes at most that early and one
+        # schedule gap late; together they must stay well inside STALE_AFTER.
         workflow = (ROOT / ".github/workflows/readme-badges.yml").read_text(encoding="utf-8")
         cron = re.search(r'cron: "(?P<minutes>[0-9,]+) \* \* \* \*"', workflow)
         self.assertIsNotNone(cron)

From 409bfd7fec7b0e83d653a1123fcf558a424e8aec Mon Sep 17 00:00:00 2001
From: lusoris <lusoris@proton.me>
Date: Tue, 10 Nov 2026 22:36:11 +0100
Subject: [PATCH 7/7] docs(ci): name the never-read badge case in the publish
 rule

CodeRabbit read the publish rule as saying any missing read time means
a commit. The code does not do that: a badge whose source has never
answered has no read time in either state file, read_lag counts that
as no lag, and the run commits nothing for it, as
test_no_read_time_on_both_sides_commits_nothing pins. The rule
fragment and the badge guide now name that case and list what does
mean a commit: a missing state file or badge entry, a different badge
set, or a read time that is unreadable, in the future or on one side
only.

The rule fragment also drops five words the caveman lint flags, so
praetorctl caveman check passes on it with no findings.

Signed-off-by: lusoris <lusoris@proton.me>
---
 docs/development/readme-badges.md    |  6 ++++--
 scripts/ci/AGENTS.d/readme-badges.md | 10 +++++-----
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/docs/development/readme-badges.md b/docs/development/readme-badges.md
index aea0f8b3a1..cc517afda0 100644
--- a/docs/development/readme-badges.md
+++ b/docs/development/readme-badges.md
@@ -78,8 +78,10 @@ GitHub API:
 - When every SVG is unchanged, the last commit is less than an hour old, and
   `state.json` on the branch holds each badge's read time less than an hour
   before this run's, nothing is committed, so the branch grows by about one
-  commit an hour. A read time that is missing, unreadable, in the future or on
-  one side only means a commit.
+  commit an hour. A badge whose source has never answered has no read time in
+  either file; that counts as recorded, since there is nothing to record. A
+  missing state file or badge entry, a different set of badges, or a read time
+  that is unreadable, in the future or on one side only means a commit.
 - A commit made with the workflow token starts no other workflow.
 
 The job's token has `contents: write`, the narrowest right that can make a
diff --git a/scripts/ci/AGENTS.d/readme-badges.md b/scripts/ci/AGENTS.d/readme-badges.md
index 1b638602c1..22544184e6 100644
--- a/scripts/ci/AGENTS.d/readme-badges.md
+++ b/scripts/ci/AGENTS.d/readme-badges.md
@@ -14,13 +14,13 @@ area: gates
 `scripts/ci/readme_badges.py` reads badge values; `tools/badges/render.mjs` draws SVGs; `.github/workflows/readme-badges.yml` publishes SVGs to `badges` branch. Human guide: `docs/development/readme-badges.md`.
 
 - Order + labels: README header badges, alt texts, order = `BADGES` tuple; workflow badge label = that workflow's `name:`. `test_readme_badges.py` reads `README.md`; new badge changes both.
-- Run choice: workflow badge = newest push run on default branch with a conclusion, not cancelled or skipped (`PASSED_OVER`). `success` -> passing; `failure`, `timed_out`, `startup_failure` -> failing; other conclusion -> `unknown`, never older run's value. Never "latest run".
+- Run choice: workflow badge = newest push run on default branch with conclusion, not cancelled or skipped (`PASSED_OVER`). `success` -> passing; `failure`, `timed_out`, `startup_failure` -> failing; other conclusion -> `unknown`, never older run's value. Never "latest run".
 - Scorecard: green from unrounded `SCORE_GREEN` = 8.5 (master requirement, `docs/principles.md`, ADR-1247); shown value rounded to 1 decimal, colour from unrounded score.
 - Renderer allow-list: keys `slug`, `label`, `message`, `color` only; text `[\x20-\x7e]{1,40}`; colour `#[0-9a-f]{6}`. `TEXT` / `COLOR` in Python and `render.mjs` stay equal (test compares both).
-- Carry: failed source keeps last value `STALE_AFTER` = 6 h from `state.json` read time, then `stale` grey; naive or unreadable time = stale (`read_time`). Recorded time trails last successful read < `QUIET_WINDOW` (`reads_recorded`), recovery with same value included (regression test pins it); `stale` <= 1 h early, <= 1 step late; accepted trade-off vs 4 commits/h. GitHub may delay or drop scheduled runs: 15 min = intended step, never stated as max badge age. `verdict` step exits 1 on any failed source.
+- Carry: failed source keeps last value `STALE_AFTER` = 6 h from `state.json` read time, then `stale` grey; naive or unreadable time = stale (`read_time`). Recorded time trails last successful read < `QUIET_WINDOW` (`reads_recorded`), recovery with same value included (regression test pins case); `stale` <= 1 h early, <= 1 step late; accepted trade-off vs 4 commits/h. GitHub delays or drops scheduled runs at times: 15 min = intended step, never stated as max badge age. `verdict` step exits 1 on any failed source.
 - State read: `previous_state` 404 = new branch, empty; any other failure -> `BadgeError`, run stops, nothing rendered or published. Never return empty state on failed read.
-- Publish: one commit via Git data API; GitHub-signed commit required (unverified -> no ref move); `force: false`; ref path only `refs/heads/badges`; no commit only when SVGs unchanged, head < `QUIET_WINDOW` = 1 h old, and branch `state.json` holds each badge read time 0 to < `QUIET_WINDOW` before this run's (`reads_recorded`); missing, unreadable, future or one-sided time -> commit.
+- Publish: one commit via Git data API; GitHub-signed commit required (unverified -> no ref move); `force: false`; ref path only `refs/heads/badges`; no commit only when SVGs unchanged, head < `QUIET_WINDOW` = 1 h old, and branch `state.json` holds each badge read time 0 to < `QUIET_WINDOW` before this run's (`reads_recorded`). No read time on both sides (source never answered) = nothing to record, counts as recorded (`read_lag` 0; `test_no_read_time_on_both_sides_commits_nothing`). Missing state file or entry, other badge set, unreadable, future or one-sided time -> commit.
 - Tokens: `GITHUB_TOKEN` only to `api.github.com`; Scorecard, Best Practices, Codacy reads carry no token.
-- Requests: every call through `ci_tier.https_json` (https only, size cap: public `MAX_RESPONSE_BYTES`, GitHub API `ci_tier.API_MAX_BYTES`); no second request helper. `HTTPS_OPENER` has no redirect handler: 3xx = `HTTPError`, `Authorization` never resent elsewhere. JSON answers read with `field()`, never bare indexing.
-- Design check: `readme_badges.py check-readme` (hook `readme-badge-design`) fails README image unless rendered `badges`-branch SVG, shields.io badge with `style=for-the-badge` + `labelColor=111a35`, or repo-local file that exists. Rendered + governance badges must name home repository (`home_repository()` from `.github/repository-security-policy.json`, case-insensitive); other repo or fork fails. Local path: `missing_file` resolves symlinks, fails outside README dir or no file. Fences + code spans ignored. Only exception: `praetor-docs.yml/badge.svg` inside `praetor:readme-governance` block (`governance_badge()`) until Praetor issue 1893 lands; then drop exception.
+- Requests: every call through `ci_tier.https_json` (https only, size cap: public `MAX_RESPONSE_BYTES`, GitHub API `ci_tier.API_MAX_BYTES`); no second request helper. `HTTPS_OPENER` = no redirect handler: 3xx = `HTTPError`, `Authorization` never resent elsewhere. JSON answers read with `field()`, never bare indexing.
+- Design check: `readme_badges.py check-readme` (hook `readme-badge-design`) fails README image unless rendered `badges`-branch SVG, shields.io badge with `style=for-the-badge` + `labelColor=111a35`, or repo-local file that exists. Rendered + governance badges -> home repository required (`home_repository()` from `.github/repository-security-policy.json`, case-insensitive); other repo or fork fails. Local path: `missing_file` resolves symlinks, fails outside README dir or no file. Fences + code spans ignored. Only exception: `praetor-docs.yml/badge.svg` inside `praetor:readme-governance` block (`governance_badge()`) until Praetor issue 1893 lands; then drop exception.
 - Rights: render job `actions: read` + `contents: read`; publish job `contents: write` only; workflow top level `permissions: {}`. No `workflow_run` trigger (zizmor dangerous trigger; fork branch named `master` matches). Workflow guard + checkout rules: `.github/AGENTS.d/readme-badges.md`.