scitex-dev 0.60.0__tar.gz → 0.60.2__tar.gz

scitex_dev-0.60.2/.github/ci/exec-in-sif.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# Outer apptainer-exec wrapper for scitex-dev's self-hosted CI.
+#
+# Runs ON THE RUNNER (outside the SIF). Resolves apptainer + the SIF image, then
+# `apptainer exec`s the SIF and hands off to an INNER script (run inside the
+# container). Keeps every workflow job's YAML down to one line —
+# `bash .github/ci/exec-in-sif.sh <inner-script> [args...]` — and concentrates
+# all the SIF plumbing (apptainer resolution, ~-expansion, scratch, binds) in
+# one version-controlled place.
+#
+# HOST-AGNOSTIC. This script is NOT Spartan-only: it auto-adapts to whichever
+# self-hosted runner picks the job up, keyed off what actually exists on the box.
+#
+#   * Spartan HPC — the GPFS project dir /data/gpfs/projects/punim0264 EXISTS:
+#     apptainer comes from the ~/.env-3.11 shim named by SCITEX_CI_APPTAINER,
+#     apptainer scratch lives on the GPFS project, and punim0264 is bound into
+#     the container ($HOME/.scitex there is a symlink into it, so without the
+#     bind the symlink dangles inside the SIF).
+#
+#   * Local compute nodes (scitex-compute-01..04) — NO /data/gpfs at all:
+#     apptainer is the distro package on PATH (/usr/bin/apptainer), scratch is
+#     host-local under $HOME/.cache/scitex-ci, and the GPFS bind is OMITTED
+#     (apptainer refuses a bind whose source does not exist, and `mkdir -p` on a
+#     GPFS scratch path would hard-fail here under `set -e`).
+#
+# Each of those three decisions (interpreter, scratch, bind) is made
+# INDEPENDENTLY from a probe of this host, so a runner that matches neither
+# profile exactly still gets a coherent command line.
+#
+# Env (set by the workflow from repo Actions Variables):
+#   SCITEX_CI_APPTAINER   OPTIONAL path to an apptainer shim
+#                         (e.g. ~/.env-3.11/bin/apptainer). Honoured when it
+#                         points at an executable; otherwise apptainer is taken
+#                         from PATH.
+#   SCITEX_CI_SIF         REQUIRED path to the CI SIF image
+#                         (e.g. ~/.scitex/dev/containers/ci-cpu.sif)
+#
+# Usage:
+#   bash .github/ci/exec-in-sif.sh run-in-sif.sh 3.12
+#
+# Fail-loud (operator directive): if NEITHER the shim nor PATH yields an
+# apptainer, or the SIF is missing, that is a HARD error naming what was tried
+# — never a silent fallback to a bare-runner install.
+set -euo pipefail
+
+INNER="${1:?inner script name required (relative to .github/ci/)}"
+shift || true
+
+# Spartan's job shell is --noprofile --norc (no Lmod), so its apptainer shim dir
+# must be put on PATH explicitly; the shim execs the real Apptainer binary.
+# Harmless where that directory is absent — a non-existent PATH entry is simply
+# never matched — which is the case on the local compute nodes.
+export PATH="$HOME/.env-3.11/bin:$PATH"
+
+# ~-expand the Actions-Variable paths: a quoted "~/…" is NOT tilde-expanded by
+# the shell, so substitute a leading ~ with $HOME ourselves.
+APPTAINER_VAR="${SCITEX_CI_APPTAINER:-}"
+APPTAINER_VAR="${APPTAINER_VAR/#\~/$HOME}"
+SIF="${SCITEX_CI_SIF:?SCITEX_CI_SIF not set (repo Actions Variable)}"
+SIF="${SIF/#\~/$HOME}"
+SIF_SHA256="${SCITEX_CI_SIF_SHA256:?SCITEX_CI_SIF_SHA256 not set (repo Actions Variable)}"
+
+# Apptainer resolution, in order:
+#   1. SCITEX_CI_APPTAINER when it names an executable  (Spartan's shim)
+#   2. `apptainer` on PATH                              (local compute nodes)
+# Only when NEITHER resolves is this an error — and the message names BOTH
+# attempts, because "which one did you even try" is the whole diagnosis.
+if [ -n "$APPTAINER_VAR" ] && [ -x "$APPTAINER_VAR" ]; then
+    APPTAINER="$APPTAINER_VAR"
+    APPTAINER_FROM="SCITEX_CI_APPTAINER"
+elif APPTAINER="$(command -v apptainer 2>/dev/null)"; then
+    APPTAINER_FROM="PATH"
+else
+    echo "::error::no apptainer on this runner. Tried (1) SCITEX_CI_APPTAINER=${SCITEX_CI_APPTAINER:-<unset>} (expanded to '${APPTAINER_VAR:-<empty>}') — not an executable; (2) 'apptainer' on PATH ($PATH) — not found. Install apptainer on this runner, or point SCITEX_CI_APPTAINER at a working shim. Running the job outside the SIF on a bare-runner install is NOT an acceptable fallback."
+    exit 1
+fi
+
+[ -f "$SIF" ] || {
+    echo "::error::CI SIF missing at $SIF — rebuild it: scitex-container apptainer build ci-cpu"
+    exit 1
+}
+
+ACTUAL_SIF_SHA256="$(sha256sum "$SIF" | awk '{print $1}')"
+if [ "$ACTUAL_SIF_SHA256" != "$SIF_SHA256" ]; then
+    echo "::error::CI SIF digest mismatch at $SIF: expected $SIF_SHA256, got $ACTUAL_SIF_SHA256. Synchronize the versioned image before accepting jobs; running an unverified image is forbidden."
+    exit 1
+fi
+
+# Apptainer scratch. On Spartan the GPFS project scratch (shared FS) keeps HOME
+# clean; everywhere else that path does not exist, and `mkdir -p` under it would
+# be a hard failure, so fall back to host-local scratch under $HOME.
+GPFS_PROJECT="/data/gpfs/projects/punim0264"
+if [ -d "$GPFS_PROJECT" ]; then
+    export APPTAINER_TMPDIR="$GPFS_PROJECT/ywatanabe/ci/apptainer-tmp"
+else
+    export APPTAINER_TMPDIR="$HOME/.cache/scitex-ci/apptainer-tmp"
+fi
+mkdir -p "$APPTAINER_TMPDIR"
+
+# Build the argv as an ARRAY so the GPFS bind can be dropped cleanly rather than
+# passed as an empty string. --pwd "$PWD" keeps the checkout as cwd.
+APPTAINER_ARGV=(exec --pwd "$PWD")
+if [ -d "$GPFS_PROJECT" ]; then
+    APPTAINER_ARGV+=(--bind "$GPFS_PROJECT")
+    GPFS_STATE="present (scratch on GPFS, punim0264 bound)"
+else
+    GPFS_STATE="absent (scratch under \$HOME, no GPFS bind)"
+fi
+
+# Echo the resolved plan: when a run fails on an unfamiliar node, the FIRST
+# question is which of the two profiles it took.
+echo "exec-in-sif: apptainer=$APPTAINER (via $APPTAINER_FROM)"
+echo "exec-in-sif: sif=$SIF"
+echo "exec-in-sif: sif_sha256=$ACTUAL_SIF_SHA256 (verified)"
+echo "exec-in-sif: $GPFS_PROJECT $GPFS_STATE"
+echo "exec-in-sif: APPTAINER_TMPDIR=$APPTAINER_TMPDIR"
+echo "exec-in-sif: + $APPTAINER ${APPTAINER_ARGV[*]} $SIF bash .github/ci/$INNER $*"
+
+exec "$APPTAINER" "${APPTAINER_ARGV[@]}" "$SIF" bash ".github/ci/$INNER" "$@"

scitex_dev-0.60.2/.github/ci/run-in-sif.sh

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+# Runs INSIDE the reused scitex-ci SIF (apptainer exec). $1 = python version.
+#
+# WHY a layered install (not the bare PYTHONPATH=src trick scitex-dev uses):
+# the shared ci-cpu.sif bakes scitex-dev[all,dev] DEPS, NOT scitex-dev's —
+# matplotlib / graphviz / seaborn / django / Pillow / networkx / playwright /
+# pytesseract / scitex-app / scitex-ui are absent from the SIF. So we install
+# THIS checkout + its [all,dev] extras (WITH dependency resolution) into a
+# writable --target dir and prepend that on PYTHONPATH. The SIF still supplies
+# the heavy shared base (pip/uv, the python interpreters, scitex-dev's deps),
+# so only scitex-dev's own thin dep set is fetched per run.
+#
+# --target (not a plain `-e .`): the SIF's /opt/venv-* are root-owned + RO and
+# the HPC compute-node HOME is RO inside the container, so a normal site install
+# fails Permission denied. A writable target on node-local /tmp sidesteps both.
+#
+# Fail-loud: a missing interpreter or a failed install is a hard error.
+set -euo pipefail
+
+V="${1:?python version arg required (3.11/3.12/3.13)}"
+VENV="/opt/venv-$V"
+test -x "$VENV/bin/python" || {
+    echo "::error::baked python missing in $VENV — rebuild the SIF: scitex-container apptainer build ci-cpu"
+    exit 1
+}
+
+mapfile -t PG_INITDB_CANDIDATES < <(compgen -G '/usr/lib/postgresql/*/bin/initdb' | sort -V)
+[ "${#PG_INITDB_CANDIDATES[@]}" -gt 0 ] || {
+    echo "::error::CI image lacks PostgreSQL server binaries under /usr/lib/postgresql/*/bin. Rebuild and synchronize ci-cpu.sif; host binaries are not an allowed fallback."
+    exit 1
+}
+PGBIN="$(dirname "${PG_INITDB_CANDIDATES[-1]}")"
+for required in initdb pg_ctl postgres; do
+    [ -x "$PGBIN/$required" ] || {
+        echo "::error::CI image PostgreSQL capability is incomplete: $PGBIN/$required is not executable. Rebuild and synchronize ci-cpu.sif."
+        exit 1
+    }
+done
+PSQL="$(command -v psql 2>/dev/null || true)"
+[ -x "$PSQL" ] || {
+    echo "::error::CI image PostgreSQL capability is incomplete: psql is not executable. Rebuild and synchronize ci-cpu.sif."
+    exit 1
+}
+
+export LC_ALL=C.UTF-8 LANG=C.UTF-8
+
+# Real writable scratch. The runner profile exports TMPDIR=~/.cache/tmp, a host
+# path that does NOT resolve inside the container; tests (tmp_path) and the
+# install target both need a working, writable tmp. Node-local /tmp is writable
+# + ephemeral and per-version-isolated so concurrent matrix legs don't collide.
+export TMPDIR="/tmp/ci-scitex_dev-${GITHUB_RUN_ID:-0}-${GITHUB_RUN_ATTEMPT:-0}-$V"
+# `${TMPDIR:?}` AND NOT `$TMPDIR`.
+#
+# The line above cannot produce an empty value TODAY — the `/tmp/…` prefix is a
+# literal. The guard pins that. scitex-agent-container's wrappers started from
+# this exact shape and later moved the name into a helper function in another
+# file, at which point "always non-empty" stopped being visible from the
+# deletion site; nothing there would have noticed.
+#
+# And `rm -rf ""` IS NOT A SAFE NO-OP. Measured, GNU coreutils 9.4: `-f` treats
+# the empty operand as a nonexistent file, so it exits 0 SILENTLY — `set -euo
+# pipefail` catches nothing, and the script CONTINUES with TMPDIR="". Every
+# later use is then a path off the filesystem root: `"$TMPDIR/site"` is `/site`.
+# The empty value is dangerous precisely because it is quiet.
+rm -rf "${TMPDIR:?ci scratch path is empty — refusing to rm -rf it}"
+mkdir -p "$TMPDIR/site" "$TMPDIR/uv-cache"
+
+# The HPC compute-node $HOME is READ-ONLY inside the container, so uv/pip cannot
+# create their default caches under ~/.cache — point them at the writable
+# scratch instead (else `uv pip install` dies: "failed to create directory
+# ~/.cache/uv: File exists / read-only").
+export UV_CACHE_DIR="$TMPDIR/uv-cache"
+export XDG_CACHE_HOME="$TMPDIR"
+export PIP_CACHE_DIR="$TMPDIR/pip-cache"
+
+# Headless matplotlib — no DISPLAY on the compute node; force the Agg backend so
+# pyplot imports + figure rendering in the test suite never try to open a GUI.
+export MPLBACKEND=Agg
+
+# Dedicated, stable matplotlib config/cache dir for this matrix leg. Without
+# pinning it, MPLCONFIGDIR defaults to $XDG_CACHE_HOME/matplotlib which is COLD
+# every CI run; the xdist workers (one per core, see below) then each cold-start
+# matplotlib and RACE to build fontList.json in that shared dir.
+# A partial/contended cache makes some renders fall back to a different font, so
+# scitex-dev's reproducibility tests (validate_recipe renders the SAME recipe
+# twice and compares) see render1 != render2 → spurious MSE-over-threshold
+# failures (e.g. TestValidateRecipe, max channel diff 255). One stable dir +
+# a single warm-up below (build the cache ONCE, pre-fork) removes the race.
+export MPLCONFIGDIR="$TMPDIR/mpl"
+mkdir -p "$MPLCONFIGDIR"
+
+# A VIRTUAL_ENV leaked from the runner profile (~/.env-3.11) is a broken symlink
+# in here; unset it so no tool (uv, pip) tries to follow it.
+unset VIRTUAL_ENV || true
+
+# venv bin on PATH (this matrix leg's python3 + pip); PYTHONPATH points at the
+# writable target so imports + coverage use the freshly-installed checkout.
+export PATH="$VENV/bin:$PATH"
+
+echo "py=$("$VENV/bin/python" -V) target=$TMPDIR/site"
+
+# The full declared test environment is mandatory. A reduced-extra fallback can
+# make the same commit pass or fail depending on resolver timing, so it is not
+# a valid CI environment.
+uv pip install --python "$VENV/bin/python" --target="$TMPDIR/site" -e ".[all,dev]"
+
+export PYTHONPATH="$TMPDIR/site:$PWD/src${PYTHONPATH:+:$PYTHONPATH}"
+
+PGDIR="$TMPDIR/postgres"
+mkdir -p "$PGDIR"
+cleanup_postgres() {
+    "$PGBIN/pg_ctl" -D "$PGDIR/data" -m immediate stop >/dev/null 2>&1 || true
+}
+trap cleanup_postgres EXIT
+"$PGBIN/initdb" -D "$PGDIR/data" -A trust --encoding=UTF8 -U postgres >"$PGDIR/initdb.log" 2>&1 || {
+    echo "::error::PostgreSQL initdb failed in the verified CI image"
+    tail -40 "$PGDIR/initdb.log"
+    exit 1
+}
+"$PGBIN/pg_ctl" -D "$PGDIR/data" -o "-k $PGDIR -h ''" -w -t 60 start >"$PGDIR/start.log" 2>&1 || {
+    echo "::error::throwaway PostgreSQL cluster failed to start"
+    tail -40 "$PGDIR/start.log"
+    exit 1
+}
+PGHOST_ENC="$(printf '%s' "$PGDIR" | sed 's|/|%2F|g')"
+export SCITEX_STORE_DSN="postgresql://postgres@${PGHOST_ENC}/postgres"
+"$PSQL" -h "$PGDIR" -U postgres -d postgres -Atqc 'select 1' | grep -qx 1 || {
+    echo "::error::throwaway PostgreSQL cluster failed its readiness query"
+    exit 1
+}
+echo "postgres=$($PGBIN/postgres --version) socket=$PGDIR readiness=verified"
+
+# Parallelise with pytest-xdist (baked in [dev]/[all,dev] as pytest-xdist>=3).
+# scitex-dev's suite is ~2460 tests; single-process it overran the job's old
+# 30-min cap (2300 passed in ~28 min, cancelled at 96%). Each xdist worker is
+# a SEPARATE PROCESS, so matplotlib's global rcParams / pyplot state and the
+# scitex-dev style-stack are naturally isolated per worker — the safe way to
+# parallelise a matplotlib-heavy suite.
+#
+# Worker count: use ALL cores. Each matrix leg now runs on its own dedicated
+# self-hosted node (one runner per node: scitex-dev-01/02/03), so there is no
+# co-tenant to yield half the box to — the old nproc//2 cap left 2x the cores
+# idle. nice/ionice (below) handles the "yield to higher-priority work if the
+# node is ever shared" concern instead of statically reserving half the CPUs.
+# Floor 4. pyproject addopts carries `-v`; override to `-q` here — 2460 verbose
+# lines x workers bloats the CI log and adds measurable overhead.
+NPROC="$(nproc 2>/dev/null || echo 4)"
+WORKERS=$NPROC
+[ "$WORKERS" -lt 4 ] && WORKERS=4
+echo "xdist workers=$WORKERS (nproc=$NPROC)"
+
+# Warm the matplotlib font cache ONCE, single-process, before xdist forks the
+# workers. This builds $MPLCONFIGDIR/fontlist-*.json a single time so every
+# worker reads a complete, consistent cache instead of racing to build it
+# concurrently (the source of the render1!=render2 reproducibility flakes).
+# Fail-loud: if matplotlib can't even build its font cache, CI must surface it.
+# matplotlib may not be a dependency of this package; only warm the
+# font cache when it's importable (no-op otherwise — never fail the run
+# on an optional warm-up).
+if python -c "import matplotlib" 2>/dev/null; then
+  python -c "import matplotlib; matplotlib.use('Agg'); from matplotlib import font_manager; font_manager.fontManager; import matplotlib.pyplot as plt; f=plt.figure(); f.canvas.draw(); print('mpl font cache warmed at', matplotlib.get_cachedir())"
+else
+  echo "matplotlib not importable — skipping font-cache warm-up (not a dep)"
+fi
+
+# Distribution: `--dist load` (per-TEST round-robin), NOT `--dist loadscope`.
+# loadscope pins an entire MODULE's tests to ONE worker — and scitex-dev's heavy
+# suites are big SINGLE modules (e.g. tests/integration/test_all_plotters_*.py
+# parametrize one test over all 47 plotters, ~28 s each). loadscope therefore
+# ran all ~50+ cases of such a module SERIALLY on one worker (~25 min) while the
+# rest idled. There are NO module/session/class-scoped fixtures in those heavy
+# modules and the root conftest's autouse `_close_figures` resets pyplot state
+# after EVERY test, so loadscope's "same worker per module" buys nothing here —
+# it only serialized. `load` spreads the parametrized cases across ALL workers.
+#
+# nice -n 19 ionice -c 3: run at the lowest CPU + idle I/O priority so that if
+# this node is ever shared with interactive/dev work, CI grabs otherwise-idle
+# cores but YIELDS the CPU and disk to any higher-priority process — "all
+# available CPUs, with priority handling". The shell remains alive so its EXIT
+# trap always stops the private PostgreSQL cluster.
+nice -n 19 ionice -c 3 \
+    python -m pytest tests/ -n "$WORKERS" --dist load -q \
+    --cov=src/scitex_dev --cov-report=xml --cov-report=term \
+    -p no:cacheprovider

scitex_dev-0.60.2/.github/workflows/import-smoke-on-ubuntu-py3-12.yml

@@ -0,0 +1,40 @@
+name: import-smoke
+
+# Catches "wheel installs but `import scitex_dev` blows up at runtime"
+# — separate from the full pytest suite so a broken entry-point fails
+# fast without paying for the matrix. Companion to `tests` — confirms
+# the bare package (no extras) is `pip install -e .`-able and
+# `import scitex_dev` succeeds. Catches `[project] dependencies`
+# drift that the test matrix masks because it installs `[all,dev]`.
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+  schedule:
+    - cron: "0 17 * * *"  # nightly 17:00 UTC (~02:00 JST), off-peak
+  workflow_dispatch:
+
+jobs:
+  install-check:
+    name: import-smoke-on-ubuntu-py3-12
+    runs-on: ${{ fromJSON(vars.CI_RUNS_ON || '["self-hosted","Linux","X64","scitex-ci"]') }}
+    steps:
+      # fetch-depth: 0 is REQUIRED — the same defect as the pytest-matrix
+      # workflow: a shallow clone hides the tags setuptools-scm derives the
+      # version from, the install resolves to `0.1.dev1+g<sha>`, and that string
+      # cannot satisfy scitex-cards' `scitex-dev>=0.59.0` requirement.
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install (no extras)
+        run: |
+          python -m venv .venv
+          .venv/bin/pip install --upgrade pip
+          .venv/bin/pip install -e .
+      - name: Import smoke
+        run: .venv/bin/python -c "import scitex_dev; print(scitex_dev.__version__)"

scitex_dev-0.60.2/.github/workflows/pytest-matrix-on-ubuntu-py3-11-3-12-3-13.yml

@@ -0,0 +1,56 @@
+name: tests
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+  schedule:
+    - cron: "0 17 * * *"  # nightly 17:00 UTC (~02:00 JST), off-peak
+  workflow_dispatch:
+
+jobs:
+  test:
+    # Job name is a REQUIRED status check (branch protection):
+    # pytest-matrix-on-ubuntu-py3.11 / 3.12 / 3.13 — keep verbatim.
+    name: pytest-matrix-on-ubuntu-py${{ matrix.python-version }}
+    runs-on: ${{ fromJSON(vars.CI_RUNS_ON || '["self-hosted","Linux","X64","scitex-ci"]') }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    env:
+      SCITEX_CI_APPTAINER: ${{ vars.SCITEX_CI_APPTAINER }}
+      SCITEX_CI_SIF: ${{ vars.SCITEX_CI_SIF }}
+      SCITEX_CI_SIF_SHA256: ${{ vars.SCITEX_CI_SIF_SHA256 }}
+    steps:
+      # fetch-depth: 0 is REQUIRED here, not an optimisation. setuptools-scm
+      # derives the version from git tags; a shallow clone hides them, so the
+      # local editable install resolves to `0.1.dev1+g<sha>`. Published
+      # scitex-cards unconditionally requires `scitex-dev>=0.59.0`, which makes
+      # that string unsatisfiable — every matrix leg then fails BEFORE a test
+      # is collected, which reads as a test failure and is not one.
+      # The quality-audit workflow already checks out with fetch-depth: 0 and
+      # passes for exactly this reason; it is the control for this change.
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Run tests
+        # The wrapper verifies the immutable image digest before execution.
+        # The inner runner then verifies its Python/PostgreSQL capabilities and
+        # owns one socket-only throwaway cluster for this matrix leg.
+        run: bash .github/ci/exec-in-sif.sh run-in-sif.sh ${{ matrix.python-version }}
+      - name: Upload coverage to Codecov
+        if: always() && matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v5
+        env:
+          # Per-job isolated HOME so parallel matrix jobs don't race on the
+          # codecov uploader's state under $HOME, and so the uploader's
+          # internal `git` calls don't trip "dubious ownership" on the
+          # shared checkout. Paired with disable_safe_directory below.
+          HOME: ${{ runner.temp }}/codecov-home-${{ matrix.python-version }}
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage.xml
+          fail_ci_if_error: false
+          disable_safe_directory: true

scitex_dev-0.60.2/.scitex/dev/config.yaml

@@ -0,0 +1,71 @@
+# Per-repo overrides for scitex-dev auditors.
+# See _skills/general/01_ecosystem_06_local-state-directories.md and
+# _skills/general/02_package_06_project-structure-tests.md for the full
+# config schema and rule index.
+
+audit:
+  # PS-220 is an ecosystem-wide error-tier rule. There is no staged
+  # `enforce-logging` switch: deterministic data/content transports are
+  # recognized structurally, and human-facing output must use scitex-logging.
+
+  # Whitelisted top-level directories/files that PS-103 would otherwise
+  # flag as "junk at repo root". Empty for now; add an entry only when the
+  # artefact genuinely belongs in this repo's root (otherwise relocate to
+  # ./.dev/ or ./GITIGNORED/).
+  root-whitelist:
+    dirs: []
+    files: []
+
+  # PS-231 — scitex-dev's OWN four re-implemented workflows.
+  #
+  # Read that twice: the repository DEFINING the no-duplicate-workflows rule is
+  # exempt from it at four sites. The exemptions are here rather than hidden
+  # because the reason is a real sequencing constraint, and because a rule whose
+  # author quietly excuses themselves is worth less than no rule.
+  #
+  # THE CONSTRAINT: under `workflow_call` GitHub renders a check as
+  # `<caller-job-id> / <reusable job name>`, so converting these to org callers
+  # RENAMES the status checks. Measured 2026-08-15 on this repo:
+  #
+  #     develop requires  pytest-matrix-on-ubuntu-py3.11 / .12 / .13, audit
+  #     main    requires  pytest-matrix-on-ubuntu-py3.11 / .12 / .13
+  #
+  # Converting without updating branch protection leaves every PR waiting on
+  # contexts nothing will ever report — the same never-arrives shape as the
+  # queued-runner outage, one layer up. So it is ONE coordinated change, not a
+  # line in this PR.
+  #
+  # These are NOT a grandfather list and must not become one. Each names one
+  # file, states this reason, and is retired by the card below — the operator
+  # rejected new-vs-old ratchets for exactly this rule family
+  # (「昔だろうが今だろうが問題点は問題点」).
+  #
+  # REMOVAL CONDITION — retired by scitex-todo card
+  #   dev-migrate-own-workflows-to-org-callers-and-rename-required-checks-20260815
+  # Deleting these four entries is a STEP of that card.
+  exemptions:
+    PS-231:
+      - path: .github/workflows/pytest-matrix-on-ubuntu-py3-11-3-12-3-13.yml
+        line: 0
+        reason: >-
+          Converting to the org caller renames the required contexts
+          pytest-matrix-on-ubuntu-py3.11/.12/.13 on BOTH develop and main;
+          protection must be updated in the same change. Card
+          dev-migrate-own-workflows-to-org-callers-and-rename-required-checks-20260815.
+      - path: .github/workflows/import-smoke-on-ubuntu-py3-12.yml
+        line: 0
+        reason: >-
+          Migrated together with pytest-matrix so the repo lands on the single
+          canonical caller shape in one reviewable change rather than a
+          half-converted workflow set. Same card.
+      - path: .github/workflows/rtd-sphinx-build-on-ubuntu-latest.yml
+        line: 0
+        reason: >-
+          Same migration. Its check renders as `rtd-sphinx-build / docs-sphinx`
+          after conversion, replacing the current `sphinx`. Same card.
+      - path: .github/workflows/auto-merge-to-develop.yaml
+        line: 0
+        reason: >-
+          Same migration. Auto-merge is the mechanism that lands the migration
+          PR itself, so it is converted LAST, after the others are verified
+          green. Same card.