feat(experiments)!: modernize Python experiment workflows

.github/CONTRIBUTING.md

@@ -1,29 +1,31 @@
-# Contributing during maintenance mode
+# Contributing to CDT++
 
 Thank you for helping improve CDT++.
 
-CDT++ v1.0.0-rc3 is the release candidate for the final C++23 release, v1.0.0, after which this repository will be
-archived. The project
-is maintained as a scientific reference implementation and regression oracle for
+CDT++ v1.0.0-rc3 is the current C++23 release candidate. The project remains maintained as a scientific reference
+implementation and regression oracle for
 [causal-triangulations](https://github.com/acgetchell/causal-triangulations), its supported Rust successor. The
-maintenance and archival scope is tracked by
-[issue #90](https://github.com/acgetchell/CDT-plusplus/issues/90).
+v1.0.0 release scope is tracked by [issue #90](https://github.com/acgetchell/CDT-plusplus/issues/90). Archiving the
+GitHub repository or making it read-only is a separate future maintainer decision, not settled policy for immediately
+after v1.0.0.
 
 ## Accepted work
 
-Until archival, contributions should be limited to:
+Contributions should be limited to:
 
 - correctness fixes, especially for causal invariants, bistellar moves, and scientific results;
 - deterministic tests, reproducibility improvements, and cross-implementation validation;
 - documentation, build, CI, portability, dependency, and release-readiness fixes;
 - work already approved in a project issue or release milestone, including
   [Qt restoration #98](https://github.com/acgetchell/CDT-plusplus/issues/98) and
-  [domain invariant work #101](https://github.com/acgetchell/CDT-plusplus/issues/101); and
-- changes required to complete the v1.0.0 release and Zenodo archival handoff.
+  [domain invariant work #101](https://github.com/acgetchell/CDT-plusplus/issues/101) and
+  [Python experiment modernization #143](https://github.com/acgetchell/CDT-plusplus/issues/143); and
+- changes required to complete the v1.0.0 release and Zenodo deposit.
 
-New simulation features, 3+1D/4D development, and unrelated C++ expansion are out of scope. Propose ongoing feature
-development in the Rust successor instead. If a change is not already tracked, open an issue before investing in a
-substantial implementation so its maintenance value and scope can be agreed upon.
+New simulation features, 3+1D/4D development, and unrelated C++ expansion remain out of scope unless a project issue
+explicitly approves them. Potential future 4D research does not authorize implementation by itself. If a change is
+not already tracked, open an issue before investing in a substantial implementation so its maintenance value and
+scope can be agreed upon.
 
 ## Contribution workflow
 
@@ -49,10 +51,10 @@ substantial implementation so its maintenance value and scope can be agreed upon
    ```
 
    `just check` is the fast, non-mutating source and tooling gate, including the repository-owned Semgrep policy and
-   its fixtures. `just ci` adds the supported build and complete 24-entry CTest suite: all 103 doctest unit scenarios
-   and 23 CLI integration tests. `just build-parallel` builds the distinct CGAL/oneTBB configuration and runs the same
-   scientific suite plus the
-   replayable parallel stress launcher, for 25 entries. When changing C++ behavior, also run
+   its fixtures. `just ci` adds the supported build and complete 127-entry CTest suite: 104 doctest unit scenarios and
+   23 CLI integration tests. `just build-parallel` builds the distinct CGAL/oneTBB configuration and runs its
+   127-entry suite: 103 ordinary doctest scenarios, one replayable parallel stress launcher containing five scenarios,
+   and the same 23 CLI integration tests. When changing C++ behavior, also run
    `just clang-tidy` with the pinned LLVM 22 toolchain and review its advisory diagnostics.
    GitHub Actions runs `just ci` in its Ubuntu GCC, Ubuntu Clang, macOS AppleClang, and Windows MSVC jobs. The two
    Ubuntu jobs also run `just build-parallel` to exercise the opt-in CGAL/oneTBB contract. Sanitizer and coverage
@@ -93,14 +95,13 @@ Project source files belong in `src`, public or shared headers in `include`, and
 CMake targets, presets, CTest registrations, Just recipes, and pinned vcpkg manifest rather than introducing parallel
 build paths.
 
-## Release and archival
+## Release and repository lifecycle
 
-Release candidates, the final tag, and the archival handoff follow the
-[`docs/RELEASING.md`](../docs/RELEASING.md) runbook. The final v1.0.0 release will be tagged from `main` and archived
-through [Zenodo]. Release metadata and the archival handoff are tracked by
-[issue #96](https://github.com/acgetchell/CDT-plusplus/issues/96). After archival, the repository will be read-only and
-will no longer accept issues or pull requests. Further development should occur in
-[causal-triangulations](https://github.com/acgetchell/causal-triangulations) or in an independent fork.
+Release candidates, the final tag, and the Zenodo deposit follow the
+[`docs/RELEASING.md`](../docs/RELEASING.md) runbook. The final v1.0.0 release will be tagged from `main`; release
+metadata and the Zenodo handoff are tracked by [issue #96](https://github.com/acgetchell/CDT-plusplus/issues/96).
+Making the GitHub repository read-only would require a separate explicit maintainer decision. Until then, issues and
+pull requests remain governed by the scoped contribution policy above.
 
 Contributors retain credit through the repository history and resulting project citation metadata.
 

.github/ISSUE_TEMPLATE/feature_request.md

@@ -9,8 +9,10 @@ assignees: ''
 
 ## Problem
 
-Describe the problem this request would solve. CDT++ is approaching its final archival release; new development may
-belong in the supported [causal-triangulations](https://github.com/acgetchell/causal-triangulations) successor.
+Describe the problem this request would solve. CDT++ remains a maintained C++ reference implementation, while broad
+new development may belong in the supported
+[causal-triangulations](https://github.com/acgetchell/causal-triangulations) successor. Explain why this repository is
+the right ownership boundary.
 
 ## Proposed solution
 

.github/dependabot.yml

@@ -13,6 +13,11 @@ updates:
     open-pull-requests-limit: 10
     groups:
       github-actions:
+        applies-to: version-updates
+        patterns:
+          - "*"
+      github-actions-security:
+        applies-to: security-updates
         patterns:
           - "*"
 
@@ -28,6 +33,11 @@ updates:
     open-pull-requests-limit: 10
     groups:
       dependencies:
+        applies-to: version-updates
+        patterns:
+          - "*"
+      python-security:
+        applies-to: security-updates
         patterns:
           - "*"
 
@@ -46,5 +56,6 @@ updates:
     open-pull-requests-limit: 10
     groups:
       dependencies:
+        applies-to: version-updates
         patterns:
           - "*"

.github/workflows/ci.yml

@@ -93,9 +93,15 @@ jobs:
             echo "llvm=$(just --evaluate llvm_version)"
             echo "ninja=$(just --evaluate ninja_version)"
             echo "ninja-windows-wheel=$(just --evaluate ninja_windows_wheel_version)"
+            echo "typos=$(just --evaluate typos_version)"
             echo "uv=$(just --evaluate uv_version)"
           } >> "$GITHUB_OUTPUT"
 
+      - name: Set up typos
+        uses: taiki-e/install-action@6a1bd70eaac3c8bdf093356838d7ee09fda951cf  # v2.85.5
+        with:
+          tool: typos@${{ steps.tool-versions.outputs.typos }}
+
       - name: Set up canonical CI environment with pkgx
         if: runner.os != 'Windows'
         uses: pkgxdev/setup@4d4ae97af87ccb39ab8be4e073dea697fef2c6f7  # v5.0.0

.github/workflows/python-experiments.yml

@@ -0,0 +1,84 @@
+---
+name: Python experiments
+
+"on":
+  push:
+    branches:
+      - main
+    paths:
+      - .github/actions/setup-just/action.yml
+      - .github/workflows/python-experiments.yml
+      - .python-version
+      - Justfile
+      - pyproject.toml
+      - scripts/experiment_tests/**
+      - scripts/mnist_experiment.py
+      - scripts/optimize_initialize.py
+      - ty.toml
+      - uv.lock
+  pull_request:
+    branches:
+      - main
+    paths:
+      - .github/actions/setup-just/action.yml
+      - .github/workflows/python-experiments.yml
+      - .python-version
+      - Justfile
+      - pyproject.toml
+      - scripts/experiment_tests/**
+      - scripts/mnist_experiment.py
+      - scripts/optimize_initialize.py
+      - ty.toml
+      - uv.lock
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  offline:
+    name: ${{ matrix.name }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: Ubuntu x86-64
+            os: ubuntu-latest
+          - name: macOS ARM64
+            os: macos-15
+          - name: Windows x86-64
+            os: windows-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Just
+        uses: ./.github/actions/setup-just
+
+      - name: Resolve uv version
+        id: tool-versions
+        shell: bash
+        run: echo "uv=$(just --evaluate uv_version)" >> "$GITHUB_OUTPUT"
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version-file: .python-version
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9  # v9.0.0
+        with:
+          version: ${{ steps.tool-versions.outputs.uv }}
+
+      - name: Resolve wheels, type-check, and run offline experiment tests
+        run: just python-experiment-check

.python-version

@@ -1 +1 @@
-3.12
+3.14

Justfile

@@ -1,15 +1,17 @@
 # Justfile for the CDT++ maintenance workflow.
 # Usage: just <recipe> or just --list
 
-set minimum-version := "1.57.0"
+set minimum-version := "1.58.0"
 set shell := ["bash", "-euo", "pipefail", "-c"]
 
-just_version := "1.57.0"
+just_version := "1.58.0"
 uv_version := "0.12.1"
+python_version := "3.14.6"
 git_cliff_version := "2.13.1"
 actionlint_version := "1.7.12"
 pinact_version := "4.1.1"
 pinact_module := "github.com/suzuki-shunsuke/pinact/v4/cmd/pinact@v" + pinact_version
+typos_version := "1.49.0"
 llvm_version := "22"
 cmake_minimum_version := "4.4.0"
 cmake_version := "4.4.1"
@@ -42,12 +44,12 @@ build-debug:
 
 # Run fast, non-mutating local validation.
 [group('workflows')]
-check: _justfile-check _format-check _yaml-check _action-lint _zizmor _whitespace-check _cmake-check release-check python-check reference-check semgrep semgrep-test
+check: _justfile-check _format-check _yaml-check _action-lint _zizmor _whitespace-check _cmake-check release-check python-check reference-check semgrep semgrep-test spell-check
     @echo "Checks complete."
 
 # Run the comprehensive pre-commit/pre-push validation gate.
 [group('workflows')]
-ci: check _pinact-check reference-generated-check
+ci: check _pinact-check reference-generated-check python-package-check
     @echo "CI validation complete."
 
 # Configure dependencies before CodeQL begins tracing the C++ build.
@@ -161,7 +163,7 @@ clang-tidy:
       "+llvm.org@{{ llvm_version }}" \
       "+cmake.org@{{ cmake_version }}" \
       "+ninja-build.org@{{ ninja_version }}" \
-      +python.org@3.11.15 \
+      "+python.org@{{ python_version }}" \
       +gnu.org/m4@1.4.21 \
       +gnu.org/autoconf@2.73.0 \
       +gnu.org/autoconf-archive@2024.10.16 \
@@ -230,6 +232,11 @@ semgrep-test: _sync-python-dev
             uv run --no-sync semgrep scan --test --strict --config "$config_path" "$fixture"
     done < <(find tests/semgrep -type f ! -name '*.fixed' -print0)
 
+# Check repository text and identifiers for common spelling mistakes.
+[group('workflows')]
+spell-check: _ensure-typos
+    typos
+
 # Build and exercise one supported Linux sanitizer configuration.
 [group('workflows')]
 sanitize kind:
@@ -240,6 +247,7 @@ sanitize kind:
         "+llvm.org@{{ llvm_version }}" \
         "+cmake.org@{{ cmake_version }}" \
         "+ninja-build.org@{{ ninja_version }}" \
+        "+python.org@{{ python_version }}" \
         -- ./scripts/sanitizer.sh "{{ kind }}"
     fi
     exec ./scripts/sanitizer.sh "{{ kind }}"
@@ -249,6 +257,50 @@ sanitize kind:
 python-check: python-format-check python-lint python-typecheck python-support-test python-entrypoint-test
     @echo "Python source checks complete."
 
+# Install, type-check, and exercise the heavyweight PyTorch/Comet surface without networked services or datasets.
+[group('workflows')]
+python-experiment-check: _sync-python-experiments
+    uv run --no-sync ty check scripts/mnist_experiment.py scripts/optimize_initialize.py scripts/experiment_tests/*.py --error all
+    MPLCONFIGDIR="${TMPDIR:-/tmp}/cdt-matplotlib-cache" uv run --no-sync python -c "import comet_ml; import torch; import torchvision; print(comet_ml.__version__, torch.__version__, torchvision.__version__)"
+    MPLCONFIGDIR="${TMPDIR:-/tmp}/cdt-matplotlib-cache" uv run --no-sync python -m unittest scripts.experiment_tests.test_comet_pytorch
+    MPLCONFIGDIR="${TMPDIR:-/tmp}/cdt-matplotlib-cache" uv run --no-sync python -m unittest scripts.experiment_tests.test_mnist_training
+
+# Build both Python artifacts and exercise every installed entry point outside the checkout.
+[group('workflows')]
+python-package-check: _sync-python-dev
+    #!/usr/bin/env bash
+    set -euo pipefail
+    artifact_directory="$(mktemp -d "${TMPDIR:-/tmp}/cdt-python-artifacts.XXXXXX")"
+    consumer_directory="$(mktemp -d "${TMPDIR:-/tmp}/cdt-python-consumer.XXXXXX")"
+    cleanup() {
+      rm -rf "$artifact_directory" "$consumer_directory"
+    }
+    trap cleanup EXIT
+
+    uv build --out-dir "$artifact_directory"
+    wheel="$(find "$artifact_directory" -maxdepth 1 -name '*.whl' -print -quit)"
+    [[ -n "$wheel" ]] || { echo "uv build did not produce a wheel." >&2; exit 1; }
+    uv venv --python {{ python_version }} "$consumer_directory/.venv"
+    uv pip install --python "$consumer_directory/.venv" --no-build "$wheel"
+
+    if [[ -x "$consumer_directory/.venv/bin/python" ]]; then
+      python="$consumer_directory/.venv/bin/python"
+      scripts_directory="$consumer_directory/.venv/bin"
+      executable_suffix=""
+    else
+      python="$consumer_directory/.venv/Scripts/python.exe"
+      scripts_directory="$consumer_directory/.venv/Scripts"
+      executable_suffix=".exe"
+    fi
+    (
+      cd "$consumer_directory"
+      "$python" -c "import scripts"
+      "$scripts_directory/cdt-bootstrap-vcpkg$executable_suffix" --help >/dev/null
+      "$scripts_directory/cdt-optimize-initialize$executable_suffix" --help >/dev/null
+      "$scripts_directory/cdt-mnist-experiment$executable_suffix" --help >/dev/null
+      "$scripts_directory/cdt-tag-release$executable_suffix" --help >/dev/null
+    )
+
 # Apply Ruff lint fixes and formatting to Python source.
 [group('workflows')]
 python-fix: _sync-python-dev
@@ -418,6 +470,21 @@ _ensure-git-cliff:
       exit 1
     fi
 
+[private]
+_ensure-typos:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    command -v typos >/dev/null || {
+      echo "typos-cli {{ typos_version }} is required." >&2
+      echo "Install it with: cargo install typos-cli --version {{ typos_version }} --locked" >&2
+      exit 1
+    }
+    actual_version="$(typos --version | awk '{print $2}')"
+    if [[ "$actual_version" != "{{ typos_version }}" ]]; then
+      echo "typos-cli {{ typos_version }} is required; found $actual_version." >&2
+      exit 1
+    fi
+
 [private]
 _ensure-uv:
     #!/usr/bin/env bash