ci: mutation-test the package lines a PR changes (warn-only)

.github/workflows/ci.yml

@@ -386,6 +386,39 @@ jobs:
           use_pypi: true
           version: '11.3.1'
 
+  # Mutates only the package lines a PR changes and runs the tests covering each (scripts/mutate_changed.py).
+  # Warn-only: survivors go to the step summary and as annotations; runtime and survivor counts are in the PR that added it.
+  mutation-diff:
+    name: Mutation of changed lines
+    if: github.event_name == 'pull_request'
+    needs: static
+    runs-on: ${{ github.repository_owner != 'intel' && 'ubuntu-latest' || vars.LINUX_RUNNER_OFF != 'true' && 'dokimi-ec2' || 'intel-ubuntu-latest' }}
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
+        with:
+          python-version: '3.13'
+          cache: pip
+          cache-dependency-path: dokimi/requirements.lock.txt
+      - name: Install deps
+        run: pip install --no-deps --require-hashes -r requirements.lock.txt
+      # No new mutant after 900 s, each at most 120 s: the step ends well inside its 22 minutes.
+      - name: Mutate changed lines
+        timeout-minutes: 22
+        env:
+          BASE_REF: ${{ github.event.pull_request.base.ref }}
+        run: |
+          python scripts/mutate_changed.py --base "origin/$BASE_REF" --max-mutants 40 --budget 900 \
+            --mutant-timeout 120 --json mutation-diff.json --markdown mutation-diff.md
+      - name: Mutation summary
+        if: ${{ !cancelled() }}
+        run: |
+          if [ -f mutation-diff.md ]; then cat mutation-diff.md; else echo "No report: see the Mutate changed lines log."; fi >> "$GITHUB_STEP_SUMMARY"
+
   # Pins the request a docker-claude arm sends (#354); the golden and what it covers are in
   # tests/fixtures/fidelity/README.md. A diff here means the npm build or the arm changed.
   fidelity:

.gitignore

@@ -9,6 +9,8 @@ coverage.json
 # Written by the CI steps (and `make ci-local`)
 /dokimi/diff-cover.json
 /dokimi/diff-cover.md
+/dokimi/mutation-diff.json
+/dokimi/mutation-diff.md
 /dokimi/compat.txt
 /dokimi/outcomes-result.json
 /dokimi/journeys-result.json

AGENTS.md

@@ -144,6 +144,12 @@ finds little:
 
 - For each test of changed behaviour, break the code it covers (flip a
   condition, drop a branch), confirm the test fails, then revert the break.
+  CI's `Mutation of changed lines` job (`dokimi/scripts/mutate_changed.py`)
+  does this for the package lines a PR changes, up to 40 mutants, and lists
+  each surviving mutant in its step summary. It warns, it does not fail: kill
+  a survivor with an assertion, or say in the description why it is
+  equivalent. Run it locally with
+  `python scripts/mutate_changed.py --base origin/main` from `dokimi/`.
 - For a bug fix, find every other site with the same bug class. Fix the ones
   within this PR's scope; list the rest in the description or an issue.
 - Where it applies, run the changed command on a bad input: missing file,

dokimi/pyproject.toml

@@ -136,6 +136,8 @@ extend_exclude = [
   "scripts/conda_forge_specs.py",
   # Run by fuzz.yml, which installs atheris from requirements-fuzz.lock.txt.
   "fuzz",
+  # Run by ci.yml's mutation-diff job; coverage comes with pytest-cov from requirements.lock.txt.
+  "scripts/mutate_changed.py",
 ]
 # Tools in the dev extra (pytest and plugins, ruff, mypy, scriv), never imported by
 # the package. A dev dep imported from the package is DEP004.