pytest-selective 0.4.2__tar.gz → 1.1.0__tar.gz

{pytest_selective-0.4.2 → pytest_selective-1.1.0}/.github/test-lanes.json

@@ -7,6 +7,11 @@
     "test_roots": [
       "tests"
     ],
+    "global_inputs": [
+      "pyproject.toml",
+      "uv.lock",
+      ".python-version"
+    ],
     "pytest_policy": {
       "pyproject.toml": "7a78d68735c0e3b091962244620d3a17557951123c645970638f15d3a737d987"
     }
@@ -20,6 +25,27 @@
         "src/**",
         "tests/**"
       ]
+    },
+    "contracts": {
+      "roots": [
+        "contracts"
+      ],
+      "inputs": [
+        "src/**",
+        "contracts/**",
+        "tests/testing/git_repo.py"
+      ]
+    },
+    "package": {
+      "inputs": [
+        "src/**",
+        "pyproject.toml",
+        "uv.lock",
+        "README.md",
+        "LICENSE",
+        "scripts/check_metadata.py",
+        "scripts/smoke_distribution.py"
+      ]
     }
   },
   "global_inputs": [
@@ -33,9 +59,9 @@
     ".github/test-lanes.json",
     ".github/workflows/ci.yml",
     ".github/workflows/release.yml",
-    "actions/**",
+    "actions/*/*",
+    "actions/*.py",
     "action.yml",
-    "examples/**",
     ".github/workflows/public-actions.yml"
   ]
 }

pytest_selective-1.1.0/.github/validation-inputs.json

@@ -0,0 +1,11 @@
+[
+  ".github",
+  "src",
+  "tests",
+  "scripts",
+  "actions",
+  "action.yml",
+  "pyproject.toml",
+  "uv.lock",
+  ".pre-commit-config.yaml"
+]

pytest_selective-1.1.0/.github/workflows/ci.yml

@@ -0,0 +1,245 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [opened, synchronize, reopened]
+  workflow_dispatch:
+  workflow_call:
+  schedule:
+    - cron: '13 3 * * 1'
+permissions:
+  contents: read
+concurrency:
+  # Only newer revisions of the same PR supersede work; keep every main/manual run.
+  group: ci-${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.run_attempt == 1 && github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' && github.run_attempt == 1 }}
+jobs:
+  select-tests:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read # Receipts are completed steps of earlier runs' jobs.
+      checks: read
+      pull-requests: read
+    env:
+      # The jobs whose passing first attempts can prove the tests lane, by exact job name.
+      TEST_LANE_JOBS: >-
+        {"py311-ubuntu":"tests (3.11, ubuntu-latest)","py311-windows":"tests (3.11, windows-latest)",
+        "py311-macos":"tests (3.11, macos-latest)","py314-ubuntu":"tests (3.14, ubuntu-latest)",
+        "py314-windows":"tests (3.14, windows-latest)","py314-macos":"tests (3.14, macos-latest)",
+        "minimum":"pytest-minimum"}
+    outputs:
+      # Planned lanes after reuse: the tests lane is false only when every one of its jobs is proven by a receipt.
+      lanes: ${{ steps.admit.outputs.lanes }}
+      # The plan before reuse, for steps that follow changed runtime inputs rather than test execution.
+      planned: ${{ steps.plan.outputs.lanes }}
+      mode: ${{ steps.files.outputs.mode }}
+      files: ${{ steps.files.outputs.test_roots_json }}
+      receipt: ${{ steps.evidence.outputs.receipt }}
+      reused: ${{ steps.evidence.outputs.reused }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      # GitHub often omits a run's pull_requests link. This marker binds the run to its PR and head, so the push
+      # after a squash merge can use this run's receipts. CI-esta matches the exact name.
+      - name: "PR evidence #${{ github.event.pull_request.number }} head ${{ github.event.pull_request.head.sha }}"
+        if: github.event_name == 'pull_request'
+        run: 'true'
+      - id: plan
+        uses: ./actions/plan-lanes
+        with:
+          config: .github/test-lanes.json
+      - name: Share the repository graph and execution inputs with file selection
+        env:
+          PYTHONPATH: src
+        run: |
+          uv run --no-project --python 3.14 --with pydantic==2.13.4 --with pyyaml==6.0.3 \
+            python scripts/ci_file_config.py "$RUNNER_TEMP/test-impact.json"
+      - id: files
+        uses: ./
+        with:
+          config: ${{ runner.temp }}/test-impact.json
+          full-roots: tests
+      # Everything the tests lane executes or reads, bound into each receipt.
+      - id: inputs
+        run: echo "paths=$(jq -c . .github/validation-inputs.json)" >> "$GITHUB_OUTPUT"
+      # CI-esta reuses a passing first attempt of the same job when its inputs and selected files are identical:
+      # after a squash merge, on a version-only release PR, and on a PR push that changes nothing the tests read.
+      # Release (workflow_call), schedules, manual runs and the test:full label always execute.
+      - id: evidence
+        if: >-
+          ${{ (github.event_name == 'pull_request' || github.event_name == 'push') &&
+              !contains(github.event.pull_request.labels.*.name, 'test:full') }}
+        uses: gigaverse-app/ci-esta/actions/resolve-lane-evidence@v1
+        with:
+          lanes: ${{ env.TEST_LANE_JOBS }}
+          execution-context: ${{ steps.files.outputs.mode }} ${{ steps.files.outputs.test_roots_json }}
+          input-paths: ${{ steps.inputs.outputs.paths }}
+          reuse-after-merge: 'true'
+          reuse-version-only-release: 'true'
+      - id: admit
+        name: Admit the tests lane unless every job is proven
+        env:
+          PLANNED_LANES: ${{ steps.plan.outputs.lanes }}
+          REUSED: ${{ steps.evidence.outputs.reused || '{}' }}
+        run: |
+          admitted=$(jq -c --argjson jobs "$TEST_LANE_JOBS" --argjson reused "$REUSED" 'if [$jobs | keys[] | $reused[.] == true] | all then .tests = false else . end' <<<"$PLANNED_LANES")
+          echo "reused=$REUSED"
+          echo "lanes=$admitted" | tee -a "$GITHUB_OUTPUT"
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: gigaverse-app/ci-esta/actions/setup-cached-uv@v1
+        with:
+          python-version: '3.14'
+      # Semantic judging owns its credentials and fork boundary in the required dry-lint job.
+      - run: uv run --locked pre-commit run --all-files
+        env:
+          SKIP: dry-lint
+      - name: Check aggregate gate against the execution lanes
+        run: >-
+          uv run --no-project --python 3.14
+          --with "ci-esta>=1.1.0,<2.0.0"
+          ci-esta check-workflow --workflow .github/workflows/ci.yml --lanes .github/test-lanes.json
+      - name: Validate GitHub Actions
+        run: docker run --rm -v "$PWD:/repo" -w /repo rhysd/actionlint:1.7.7 -color
+  tests:
+    needs: select-tests
+    if: >-
+      ${{ always() && !cancelled() && (needs.select-tests.result != 'success' ||
+          fromJSON(needs.select-tests.outputs.lanes).tests) }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.11', '3.14']
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: gigaverse-app/ci-esta/actions/setup-cached-uv@v1
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Use native Git for Windows
+        uses: gigaverse-app/ci-esta/actions/native-windows-git@v1
+      - name: Record coverage runtime
+        run: uv run --locked python -m coverage --version
+      - name: Execute the shared affected-file plan
+        run: uv run --locked python scripts/run_ci_tests.py -q -n 4 --durations=20 --junitxml=test-timings.xml
+        env:
+          CI_PLANNER_RESULT: ${{ needs.select-tests.result }}
+          CI_TEST_MODE: ${{ needs.select-tests.outputs.mode }}
+          CI_TEST_FILES: ${{ needs.select-tests.outputs.files }}
+          CI_COVERAGE: 'true'
+          # Keep temporary Git repositories beside the checkout on the work disk.
+          TMP: ${{ runner.temp }}
+          TEMP: ${{ runner.temp }}
+          TMPDIR: ${{ runner.temp }}
+      - uses: gigaverse-app/ci-esta/actions/learn-test-timings@v1
+        if: ${{ hashFiles('test-timings.xml') != '' }}
+        with:
+          junit-pattern: test-timings.xml
+          artifact-name: test-timings-${{ matrix.python }}-${{ matrix.os }}
+      # tests/test_tutorial.py owns the end-to-end tutorial and follows the file plan.
+      - uses: actions/upload-artifact@v7
+        if: ${{ hashFiles('coverage.xml') != '' }}
+        with:
+          name: evidence-${{ matrix.os }}-${{ matrix.python }}
+          path: coverage.xml
+      - name: ${{ needs.select-tests.outputs.receipt || 'No execution receipt' }}
+        if: ${{ needs.select-tests.result == 'success' && needs.select-tests.outputs.receipt != '' }}
+        run: echo 'Recording a completed execution of this job for this tested tree and selection.'
+  pytest-minimum:
+    needs: select-tests
+    if: >-
+      ${{ always() && !cancelled() && (needs.select-tests.result != 'success' ||
+          fromJSON(needs.select-tests.outputs.lanes).tests) }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: gigaverse-app/ci-esta/actions/setup-cached-uv@v1
+        with:
+          python-version: '3.11'
+      - run: uv pip install 'pytest==8.0.0'
+      - name: Execute the same file plan on minimum pytest
+        run: uv run --no-sync python scripts/run_ci_tests.py -q -n 4 --durations=20
+        env:
+          CI_PLANNER_RESULT: ${{ needs.select-tests.result }}
+          CI_TEST_MODE: ${{ needs.select-tests.outputs.mode }}
+          CI_TEST_FILES: ${{ needs.select-tests.outputs.files }}
+      - name: ${{ needs.select-tests.outputs.receipt || 'No execution receipt' }}
+        if: ${{ needs.select-tests.result == 'success' && needs.select-tests.outputs.receipt != '' }}
+        run: echo 'Recording a completed execution of this job for this tested tree and selection.'
+  distributions:
+    needs: select-tests
+    # The package lane includes the embedded README and LICENSE; planner failure must not skip it.
+    if: >-
+      ${{ always() && !cancelled() && (needs.select-tests.result != 'success' ||
+          fromJSON(needs.select-tests.outputs.lanes).package) }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: gigaverse-app/ci-esta/actions/setup-cached-uv@v1
+        with:
+          python-version: '3.14'
+      - run: uv build
+      - run: uv run --locked twine check --strict dist/*
+      - run: uv run --locked python scripts/check_metadata.py
+      - name: Smoke installed distributions when runtime inputs change
+        if: >-
+          ${{ needs.select-tests.result != 'success' ||
+              fromJSON(needs.select-tests.outputs.planned).tests }}
+        run: uv run --locked python scripts/smoke_distribution.py
+      - uses: actions/upload-artifact@v7
+        with:
+          name: distributions
+          path: dist/*
+          if-no-files-found: error
+
+  selection-contract:
+    name: Selection contract (Quint)
+    needs: select-tests
+    permissions:
+      contents: read
+      # The contract report's pull-request comment.
+      pull-requests: write
+    if: >-
+      ${{ always() && !cancelled() && (needs.select-tests.result != 'success' ||
+          fromJSON(needs.select-tests.outputs.lanes).contracts) }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: gigaverse-app/ci-esta/actions/setup-cached-uv@v1
+        with:
+          python-version: '3.14'
+      # pytest-quint-connect installs its locked Quint with npm on first use.
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '24'
+      - name: Check the generated driver against the model
+        run: uv run --locked --group quint pytest-quint-connect codegen --check contracts/selection/quint-connect.json
+      - name: Generate histories from the model and replay them against the planner
+        run: uv run --locked --group quint pytest -c contracts/selection/quint.ini contracts/selection --quint-require-complete -q
+      # Match the README with the same locked renderer that produced these receipts.
+      # A presentation update to the floating report action must not break an immutable release.
+      - name: Check the README against the locked contract renderer
+        run: uv run --locked --group quint pytest-quint-connect report '**/.artifacts/quint-connect/results.json' --readme README.md --check
+      # The current action owns the sticky and artifacts, independently of README formatting.
+      - uses: gigaverse-app/pytest-quint-connect/report@v1
+        if: ${{ always() }}
+        with:
+          readme-mode: 'off'
+
+  validation-gate:
+    name: Validation gate
+    needs: [select-tests, quality, tests, pytest-minimum, distributions, selection-contract]
+    if: ${{ !cancelled() }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: gigaverse-app/ci-esta/actions/validation-gate@v1
+        with:
+          needs: ${{ toJSON(needs) }}
+          lanes: ${{ needs.select-tests.outputs.lanes || '{}' }}
+          lane-jobs: '{"tests":["tests"],"pytest-minimum":["tests"],"distributions":["package"],"selection-contract":["contracts"]}'

{pytest_selective-0.4.2 → pytest_selective-1.1.0}/.github/workflows/public-actions.yml

@@ -4,6 +4,8 @@ on:
   push:
     branches: [main]
   workflow_dispatch:
+  schedule:
+    - cron: '33 3 * * 1'
 permissions:
   contents: read
 jobs:
@@ -67,8 +69,22 @@ jobs:
         run: |
           python - <<'PY'
           import json, os
-          assert json.loads(os.environ['LANES']) == {'tests': True}
+          # A full checkpoint admits every configured lane.
+          configured = json.load(open('.github/test-lanes.json', encoding='utf-8'))['lanes']
+          assert json.loads(os.environ['LANES']) == dict.fromkeys(configured, True)
           PY
       - name: Require successful planning after fallback execution
         if: ${{ !cancelled() && needs.select-tests.result != 'success' }}
         run: exit 1
+  gate:
+    name: Public action gate
+    needs: [select-tests, public-actions]
+    if: ${{ !cancelled() }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      # Dogfood the public gate: the smoke may be skipped only when the successful plan said so.
+      - uses: ./actions/validation-gate
+        with:
+          needs: ${{ toJSON(needs) }}
+          lane-jobs: '{"public-actions":["tests"]}'

{pytest_selective-0.4.2 → pytest_selective-1.1.0}/.github/workflows/release.yml

@@ -21,6 +21,13 @@ jobs:
           uv run --no-project python -c 'import os, pathlib, tomllib; version = tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"]; assert os.environ["RELEASE_REF"] == f"refs/tags/v{version}", "Run publishing from the version-matching v tag"'
   checks:
     needs: validate-tag
+    # A called workflow gets no more than this, and GitHub refuses to start it when a job asks for more: the Quint
+    # report needs pull-requests: write, and select-tests reads earlier runs' jobs and checks for lane receipts.
+    permissions:
+      contents: read
+      actions: read
+      checks: read
+      pull-requests: write
     uses: ./.github/workflows/ci.yml
   publish:
     needs: checks

{pytest_selective-0.4.2 → pytest_selective-1.1.0}/.github/workflows/windows-performance.yml

@@ -1,17 +1,19 @@
 name: Matched Windows performance
 on:
-  pull_request:
-    paths: ['.github/workflows/windows-performance.yml']
   workflow_dispatch:
     inputs:
       baseline:
         description: Immutable baseline commit to compare with the selected ref
         required: true
+      candidate-workers:
+        description: Windows xdist worker count to compare with the existing four workers
+        type: number
+        default: 4
+      ci-esta-ref:
+        description: CI-esta ref containing the candidate native-Git action
+        default: v1
 permissions:
   contents: read
-concurrency:
-  group: windows-performance-${{ github.event.pull_request.number || github.run_id }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 jobs:
   compare:
     runs-on: windows-latest
@@ -23,11 +25,11 @@ jobs:
     steps:
       - uses: actions/checkout@v7
         with:
-          ref: ${{ inputs.baseline || github.event.pull_request.base.sha }}
+          ref: ${{ inputs.baseline }}
           path: baseline
       - uses: actions/checkout@v7
         with:
-          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          ref: ${{ github.sha }}
           path: candidate
       - uses: astral-sh/setup-uv@v10.3.3
         with:
@@ -35,34 +37,47 @@ jobs:
           cache-suffix: matched-windows-${{ matrix.python }}
       - run: uv sync --directory baseline --locked
       - run: uv sync --directory candidate --locked
-      - name: Preserve the baseline Git search path
+      - uses: actions/checkout@v7
+        with:
+          repository: gigaverse-app/ci-esta
+          ref: ${{ inputs.ci-esta-ref }}
+          path: ci-esta-tools
+      - name: Preserve the launcher path for the control
         shell: pwsh
         run: '"BASELINE_GIT_PATH=$env:PATH" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append'
-      - uses: gigaverse-app/ci-esta/actions/native-windows-git@v1
+      - uses: ./ci-esta-tools/actions/native-windows-git
       - name: Run complete suites in both orders on the same worker
         shell: pwsh
+        env:
+          CANDIDATE_WORKERS: ${{ inputs.candidate-workers }}
+          TMP: ${{ runner.temp }}
+          TEMP: ${{ runner.temp }}
+          TMPDIR: ${{ runner.temp }}
         run: |
           $results = Join-Path $env:GITHUB_WORKSPACE 'measurements'
           New-Item -ItemType Directory -Path $results | Out-Null
           $measurements = @()
-          $originalPath = $env:BASELINE_GIT_PATH
           $nativeGitPath = $env:PATH
           foreach ($sample in @('baseline-1', 'candidate-1', 'candidate-2', 'baseline-2')) {
             $arm = $sample.Split('-')[0]
             Push-Location (Join-Path $env:GITHUB_WORKSPACE $arm)
             try {
-              # Start every arm with the same PATH; only the candidate opts in.
-              $env:PATH = if ($arm -eq 'candidate') { $nativeGitPath } else { $originalPath }
+              # Keep the suite, coverage and disk identical; record the actual executable.
+              $env:PATH = if ($arm -eq 'candidate') { $nativeGitPath } else { $env:BASELINE_GIT_PATH }
+              $env:PYTHONPATH = Join-Path (Get-Location) 'src'
+              $git = (Get-Command git -CommandType Application | Select-Object -First 1).Source
+              Write-Host "$sample uses $git"
+              $workers = if ($arm -eq 'candidate') { [int]$env:CANDIDATE_WORKERS } else { 4 }
               $sha = git rev-parse HEAD
               # Keep repeated arms from timing cleanup of an earlier arm's Git fixtures.
               $temp = Join-Path $env:RUNNER_TEMP "matched-pytest-$sample"
               if (Test-Path -LiteralPath $temp) { throw "Temporary path already exists: $temp" }
               $clock = [System.Diagnostics.Stopwatch]::StartNew()
-              uv run --locked pytest -q -n 4 --basetemp="$temp" --durations=20 --cov --cov-report="xml:$results/$sample-coverage.xml" --junitxml="$results/$sample-tests.xml" *> "$results/$sample.log"
+              uv run --locked pytest -q -p no:selective -n $workers --basetemp="$temp" --durations=20 --cov --cov-report="xml:$results/$sample-coverage.xml" --junitxml="$results/$sample-tests.xml" *> "$results/$sample.log"
               $result = $LASTEXITCODE
               $clock.Stop()
               Get-Content "$results/$sample.log" | Select-Object -Last 25
-              $measurements += [pscustomobject]@{ sample=$sample; sha=$sha; seconds=$clock.Elapsed.TotalSeconds; exit_code=$result }
+              $measurements += [pscustomobject]@{ sample=$sample; sha=$sha; git=$git; workers=$workers; seconds=$clock.Elapsed.TotalSeconds; exit_code=$result }
               $measurements | ConvertTo-Json | Set-Content "$results/timings.json"
               if ($result -ne 0) { throw "${sample} failed: $result" }
             } finally { Pop-Location }

{pytest_selective-0.4.2 → pytest_selective-1.1.0}/.gitignore

@@ -18,3 +18,6 @@ tutorial-report.json
 
 # Local judge credentials
 .env
+
+# pytest-quint-connect receipts, traces and logs
+.artifacts/

pytest_selective-1.1.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "1.1.0"
+}

{pytest_selective-0.4.2 → pytest_selective-1.1.0}/AGENTS.md

@@ -11,6 +11,11 @@ on pytest-selective itself.
 - Reproduce selection bugs using real temporary Git repositories and existing
   `tests/testing/git_repo.py` helpers. Cover base and head trees, deleted inputs,
   explicit declarations and the relevant fallback. Do not mock away selection.
+- The planner's import, conftest, declaration and content-read closure, its parse-error
+  stop, its selection against older bases and its graph cache's transparency are also a
+  Quint contract in
+  `contracts/selection`. After changing selection, run it (CONTRIBUTING.md, *The selection
+  contract*); extend the model rather than weakening it when the promise changes.
 - Planning supports committed revisions and explicit working-tree snapshots. Preserve full execution on
   operational uncertainty and diagnostics for invalid declarations. An empty
   selection is not an empty pytest argument list.

{pytest_selective-0.4.2 → pytest_selective-1.1.0}/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [1.1.0](https://github.com/gigaverse-app/pytest-selective/compare/v1.0.0...v1.1.0) (2026-11-09)
+
+
+### Features
+
+* one-prompt agent setup, and fixes from a real adoption trial ([#105](https://github.com/gigaverse-app/pytest-selective/issues/105)) ([27c4578](https://github.com/gigaverse-app/pytest-selective/commit/27c45786f1a6a349409eb2a083510e4e9a9180d3))
+
+
+### Bug fixes
+
+* **lanes:** select only lanes holding graph tests when every graph test is affected ([#102](https://github.com/gigaverse-app/pytest-selective/issues/102)) ([d6f22b8](https://github.com/gigaverse-app/pytest-selective/commit/d6f22b8f93773a4b2e60b2b8ad9d4b26762b2d2f))
+* **selection:** resolve imports from the directories pytest's default import mode adds to sys.path ([#96](https://github.com/gigaverse-app/pytest-selective/issues/96)) ([d825176](https://github.com/gigaverse-app/pytest-selective/commit/d825176eb6d259733ec8132ba98ac327be15eb72))
+
+## [1.0.0](https://github.com/gigaverse-app/pytest-selective/compare/v0.4.3...v1.0.0) (2026-11-08)
+
+
+### Bug fixes
+
+* **ci:** streamline dogfood checks and prepare the 1.0 release ([#97](https://github.com/gigaverse-app/pytest-selective/issues/97)) ([5c79edc](https://github.com/gigaverse-app/pytest-selective/commit/5c79edcc2e234ccd90902ef001d2852cf7ecfdbc))
+* **selection:** follow star imports to the submodules a package lists in __all__ ([#94](https://github.com/gigaverse-app/pytest-selective/issues/94)) ([ea02fbf](https://github.com/gigaverse-app/pytest-selective/commit/ea02fbfe85c2d5b6e8685a4b159215d421f78653))
+
+## [0.4.3](https://github.com/gigaverse-app/pytest-selective/compare/v0.4.2...v0.4.3) (2026-11-08)
+
+
+### Bug fixes
+
+* **lanes:** select lanes through the graph and match ** like gitignore ([#90](https://github.com/gigaverse-app/pytest-selective/issues/90)) ([107b021](https://github.com/gigaverse-app/pytest-selective/commit/107b0212ed741ac72c36a39cc864906eca75d1ab))
+
 ## [0.4.2](https://github.com/gigaverse-app/pytest-selective/compare/v0.4.1...v0.4.2) (2026-11-07)
 
 

{pytest_selective-0.4.2 → pytest_selective-1.1.0}/CONTRIBUTING.md

@@ -32,6 +32,31 @@ Changes to collection policy, runtime auditing, or the composite action need tes
 at that boundary. Update the tutorial when the public command contract changes.
 Keep performance claims tied to reproducible measurements and their limitations.
 
+### The selection contract
+
+[contracts/selection](contracts/selection/README.md) states the planner's core
+promise as a [Quint](https://quint.sh) model and checks it with
+[pytest-quint-connect](https://github.com/gigaverse-app/pytest-quint-connect):
+generated histories of real commits, each selected by `affected()` and compared
+with the model. It runs as its own CI lane, outside the xdist suite, and needs
+Node.js 22+ for Quint:
+
+```bash
+uv run --group quint pytest -c contracts/selection/quint.ini contracts/selection --quint-require-complete
+```
+
+When selection semantics change on purpose, change `selection.qnt` with them and
+regenerate the driver (`pytest-quint-connect codegen contracts/selection/quint-connect.json`).
+Never drop a witness, mutant or observed field to make it pass.
+
+CI reports each run in one pull-request comment and checks the README's contract block
+against it. After a change to the contract's cases, refresh the block from a complete
+local run and commit it:
+
+```bash
+uv run --group quint pytest-quint-connect report '**/.artifacts/quint-connect/results.json' --readme README.md
+```
+
 ### Shared implementation owners
 
 | Contract | Owner |
@@ -72,8 +97,9 @@ limitations. The pull request template provides a short checklist. See
 ## CI lane selection
 
 This repository uses its own `plan-lanes` action. Documentation-only PRs keep
-quality checks (including Markdown links) and distribution build/metadata checks,
-while skipping the six-platform pytest matrix and minimum-pytest lane. Within an
+quality checks (including Markdown links) and the documentation build, while
+skipping every test lane and the distribution build. A README or LICENSE change
+also runs the `package` lane, because both distributions embed them. Within an
 admitted lane, the repository's public file-selection action selects affected
 test files once; the platform matrix and minimum-pytest job execute that same
 plan. CI-esta receives both lane and file explanations, learns JUnit timings,
@@ -171,6 +197,12 @@ history or failed planning must execute the full affected lanes and fail the
 required planning gate. Ordinary PRs and pushes use selection; manual/release/scheduled/full overrides
 remain complete checkpoints.
 
+CI and public-action smoke run full checkpoints every Monday. Ordinary runs keep
+the shared affected-file plan across all six OS/Python combinations and minimum
+pytest. `tests/test_tutorial.py` owns the end-to-end tutorial execution and follows
+that plan; there is no second tutorial invocation in each matrix job. JUnit retains
+its test result and timing, and full plans also upload whole-suite coverage.
+
 ## Duplication
 
 `uv run pre-commit install` installs both the staged dry-lint check and the