pytest-selective 0.3.0__tar.gz → 0.4.0__tar.gz

{pytest_selective-0.3.0 → pytest_selective-0.4.0}/.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
     outputs:
       lanes: ${{ steps.plan.outputs.lanes }}
       mode: ${{ steps.files.outputs.mode }}
-      files: ${{ steps.paths.outputs.files }}
+      files: ${{ steps.files.outputs.test_roots_json }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -27,8 +27,6 @@ jobs:
         uses: ./actions/plan-lanes
         with:
           config: .github/test-lanes.json
-          base: ${{ github.event.pull_request.base.sha || github.event.before }}
-          full: ${{ github.run_attempt > 1 || contains(fromJSON('["workflow_dispatch","workflow_call","schedule","release"]'), github.event_name) || contains(github.event.pull_request.labels.*.name, 'test:full') }}
       - name: Share the repository graph and execution inputs with file selection
         env:
           PYTHONPATH: src
@@ -39,21 +37,7 @@ jobs:
         uses: ./
         with:
           config: ${{ runner.temp }}/test-impact.json
-          base: ${{ github.event.pull_request.base.sha || github.event.before }}
           full-roots: tests
-          full: ${{ github.run_attempt > 1 || contains(fromJSON('["workflow_dispatch","workflow_call","schedule","release"]'), github.event_name) || contains(github.event.pull_request.labels.*.name, 'test:full') }}
-      - id: paths
-        name: Forward exact selected paths without shell splitting
-        env:
-          MODE: ${{ steps.files.outputs.mode }}
-        run: |
-          python - <<'PY'
-          import json, os
-          from pathlib import Path
-          files = json.loads(Path('test-impact-report.json').read_text())['selected'] if os.environ['MODE'] == 'scoped' else []
-          with open(os.environ['GITHUB_OUTPUT'], 'a') as output:
-              output.write('files=' + json.dumps(files) + '\n')
-          PY
   quality:
     runs-on: ubuntu-latest
     steps:

{pytest_selective-0.3.0 → pytest_selective-0.4.0}/.github/workflows/public-actions.yml

@@ -19,8 +19,6 @@ jobs:
         uses: ./actions/plan-lanes
         with:
           config: .github/test-lanes.json
-          base: ${{ github.event.pull_request.base.sha || github.event.before }}
-          full: ${{ github.run_attempt > 1 || contains(fromJSON('["workflow_dispatch","workflow_call","schedule","release"]'), github.event_name) || contains(github.event.pull_request.labels.*.name, 'test:full') }}
           artifact-name: public-action-selection
   public-actions:
     needs: select-tests

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

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

{pytest_selective-0.3.0 → pytest_selective-0.4.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.4.0](https://github.com/gigaverse-app/pytest-selective/compare/v0.3.0...v0.4.0) (2026-10-24)
+
+
+### Features
+
+* **actions:** simplify selection adoption with shared defaults ([#63](https://github.com/gigaverse-app/pytest-selective/issues/63)) ([85e082d](https://github.com/gigaverse-app/pytest-selective/commit/85e082dfdbcf2f8c02ac3de38613c818cb749807))
+
 ## [0.3.0](https://github.com/gigaverse-app/pytest-selective/compare/v0.2.0...v0.3.0) (2026-10-23)
 
 

{pytest_selective-0.3.0 → pytest_selective-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pytest-selective
-Version: 0.3.0
+Version: 0.4.0
 Summary: Explainable Python test impact analysis: select affected pytest files from Git changes
 Project-URL: Homepage, https://github.com/gigaverse-app/pytest-selective
 Project-URL: Documentation, https://pytest-selective.readthedocs.io/en/latest/
@@ -71,6 +71,9 @@ and slack. [See the source runs and method](https://github.com/gigaverse-app/ci-
 
 ## Choose how to use it
 
+Follow the [adoption tutorial and checklist](docs/tutorials/adoption-checklist.md)
+for local execution, CI routing, dependency audits, timing feedback and measured rollout.
+
 | You want to… | Use | What it saves |
 | --- | --- | --- |
 | Test local edits with your existing pytest command | `uv add --dev pytest-selective`, then `uv run pytest --selective` | Unaffected test execution; staged, unstaged and untracked changes are included |
@@ -231,7 +234,7 @@ skip pytest, because invoking pytest without paths runs the whole suite.
 | A transitive dependency | Import chains and package initialization |
 | A deleted or renamed module | Dependencies in both the base and head trees |
 | Fixtures or startup code | Ancestor conftests and configured global modules |
-| Templates, schemas, or data files | Reader-owned declarations and YAML sidecars |
+| Templates, schemas, or data files | [Reader-owned declarations and YAML sidecars](docs/tutorials/sidecar-dependencies.md) |
 | A surprisingly large selection | Dependency paths, startup-floor and blast-radius explanations |
 | A large CI suite | Cached parsing, graph reuse, and duration-based shard planning |
 | Undeclared runtime reads | An opt-in pytest recorder and audit command |

{pytest_selective-0.3.0 → pytest_selective-0.4.0}/README.md

@@ -40,6 +40,9 @@ and slack. [See the source runs and method](https://github.com/gigaverse-app/ci-
 
 ## Choose how to use it
 
+Follow the [adoption tutorial and checklist](docs/tutorials/adoption-checklist.md)
+for local execution, CI routing, dependency audits, timing feedback and measured rollout.
+
 | You want to… | Use | What it saves |
 | --- | --- | --- |
 | Test local edits with your existing pytest command | `uv add --dev pytest-selective`, then `uv run pytest --selective` | Unaffected test execution; staged, unstaged and untracked changes are included |
@@ -200,7 +203,7 @@ skip pytest, because invoking pytest without paths runs the whole suite.
 | A transitive dependency | Import chains and package initialization |
 | A deleted or renamed module | Dependencies in both the base and head trees |
 | Fixtures or startup code | Ancestor conftests and configured global modules |
-| Templates, schemas, or data files | Reader-owned declarations and YAML sidecars |
+| Templates, schemas, or data files | [Reader-owned declarations and YAML sidecars](docs/tutorials/sidecar-dependencies.md) |
 | A surprisingly large selection | Dependency paths, startup-floor and blast-radius explanations |
 | A large CI suite | Cached parsing, graph reuse, and duration-based shard planning |
 | Undeclared runtime reads | An opt-in pytest recorder and audit command |

{pytest_selective-0.3.0 → pytest_selective-0.4.0}/action.yml

@@ -10,7 +10,7 @@ inputs:
     required: true
   base:
     description: Complete change-set base (a validated ancestor, PR base, or push before SHA).
-    required: true
+    default: ${{ github.event.pull_request.base.sha || github.event.before }}
   head:
     description: Exact checked-out commit.
     default: HEAD
@@ -18,8 +18,9 @@ inputs:
     description: Space-separated complete test roots used if planning cannot prove a narrower scope.
     required: true
   full:
-    description: Force the complete suite for schedules, explicit labels, or coverage checkpoints.
-    default: 'false'
+    description: auto selects on PRs/pushes and runs full on reruns, manual/scheduled/release events or test:full. Override
+      with true or false.
+    default: auto
   extra-files:
     description: Optional newline file containing prior failure canaries or additional changed paths.
     default: ''
@@ -68,6 +69,9 @@ outputs:
   test_roots:
     description: Exact selected files, or complete roots on fallback.
     value: ${{ steps.action.outputs.test_roots }}
+  test_roots_json:
+    description: JSON array of selected files or fallback roots; preserves spaces in paths. Empty array for none.
+    value: ${{ steps.action.outputs.test_roots_json }}
   shard_count:
     description: Number of shards.
     value: ${{ steps.action.outputs.shard_count }}

{pytest_selective-0.3.0 → pytest_selective-0.4.0}/actions/plan-lanes/action.yml

@@ -6,10 +6,10 @@ inputs:
     required: true
   base:
     description: Base commit containing the complete change set.
-    required: true
+    default: ${{ github.event.pull_request.base.sha || github.event.before }}
   full:
-    description: Run every lane for an explicit full-test checkpoint; ordinary PRs and pushes use selection.
-    default: 'false'
+    description: 'auto selects on PRs/pushes and runs full on reruns, manual/scheduled/release events or test:full. Override with true or false.'
+    default: auto
   artifact-name:
     description: >
       Upload the lane plan under this name, where CI-esta's report renders it as
@@ -41,7 +41,7 @@ runs:
       run: |
         export PYTHONPATH="$SELECTIVE_ACTION/../../src${PYTHONPATH:+:$PYTHONPATH}"
         args=(--config "$SELECTIVE_CONFIG" --base "$SELECTIVE_BASE" --github-output "$GITHUB_OUTPUT")
-        if [ "$SELECTIVE_FULL" = true ]; then args+=(--full); fi
+        args+=(--full "$SELECTIVE_FULL")
         uv run --no-project --python 3.14 --with pydantic==2.13.4 --with pyyaml==6.0.3 \
           python -m pytest_selective.ci "${args[@]}" | tee test-lanes.json
         {

{pytest_selective-0.3.0 → pytest_selective-0.4.0}/actions/test-impact/action.yml

@@ -9,7 +9,7 @@ inputs:
     required: true
   base:
     description: Complete change-set base (a validated ancestor, PR base, or push before SHA).
-    required: true
+    default: ${{ github.event.pull_request.base.sha || github.event.before }}
   head:
     description: Exact checked-out commit.
     default: HEAD
@@ -17,8 +17,8 @@ inputs:
     description: Space-separated complete test roots used if planning cannot prove a narrower scope.
     required: true
   full:
-    description: Force the complete suite for schedules, explicit labels, or coverage checkpoints.
-    default: 'false'
+    description: 'auto selects on PRs/pushes and runs full on reruns, manual/scheduled/release events or test:full. Override with true or false.'
+    default: auto
   extra-files:
     description: Optional newline file containing prior failure canaries or additional changed paths.
     default: ''
@@ -70,6 +70,9 @@ outputs:
   test_roots:
     value: ${{ steps.select.outputs.test_roots }}
     description: Exact selected files, or complete roots on fallback.
+  test_roots_json:
+    value: ${{ steps.select.outputs.test_roots_json }}
+    description: JSON array of selected files or fallback roots; preserves spaces in paths. Empty array for none.
   shard_count:
     value: ${{ steps.select.outputs.shard_count }}
     description: Number of shards.
@@ -139,7 +142,7 @@ runs:
               --explanation-output test-impact-explanation.json)
         # A reused workspace must not upload a previous plan's explanation.
         rm -f test-impact-explanation.json
-        if [ "$IMPACT_FULL" = true ]; then args+=(--full); fi
+        args+=(--full "$IMPACT_FULL")
         if [ -n "$IMPACT_EXTRA" ]; then args+=(--extra-files "$IMPACT_EXTRA"); fi
         if [ -n "${IMPACT_GRAPH_BASE:-}" ]; then args+=(--graph-base "$IMPACT_GRAPH_BASE"); fi
         # Optional: an unfetchable alternate only forgoes a smaller selection.
@@ -170,6 +173,7 @@ runs:
             echo "base=$IMPACT_BASE"
             echo "mode=full"
             echo "test_roots=$IMPACT_ROOTS"
+            echo "test_roots_json=$(python3 -c 'import json,os,shlex; print(json.dumps(shlex.split(os.environ["IMPACT_ROOTS"])))')"
             echo "shard_count=$IMPACT_SHARDS"
             echo "groups=$(python3 -c 'import json,os; print(json.dumps(list(range(1,int(os.environ["IMPACT_SHARDS"])+1))))')"
             echo "reason=Test impact proof unavailable; complete suite fallback"

{pytest_selective-0.3.0 → pytest_selective-0.4.0}/docs/README.md

@@ -4,6 +4,7 @@
 | --- | --- |
 | Have a coding agent optimize your test/CI workflow | [Agent prompt, skill and AGENTS.md instructions](agents.md) |
 | See a real regression caught by a smaller selection | [Runnable tutorial](tutorial.md) |
+| Declare fixture, schema, scanner, or subprocess inputs | [Sidecar tutorial](tutorials/sidecar-dependencies.md) |
 | Configure an existing Python project | [Configuration and dependency declarations](configuration.md) |
 | Use `pytest --selective` or run local edits before collection | [Native plugin and local runner](local-development.md) |
 | Run the selected files safely in CI | [GitHub Actions and runner integration](ci.md) |

{pytest_selective-0.3.0 → pytest_selective-0.4.0}/docs/ci.md

@@ -8,8 +8,8 @@ the base forward after a failed run.
 
 This job uses the repository's composite action and runs the plan on the checked-out
 head. Use the moving `v1` release tag and adapt dependency installation to
-your project. The example assumes a uv project
-and test paths without spaces (the action's `test_roots` output is space-separated).
+your project. The example assumes a uv project and passes the planned paths as
+JSON, so spaces in filenames survive execution.
 
 ```yaml
 name: Affected tests
@@ -28,26 +28,44 @@ jobs:
         uses: gigaverse-app/pytest-selective@v1
         with:
           config: .github/test-impact.json
-          base: ${{ github.event.pull_request.base.sha }}
           full-roots: tests
       - if: steps.impact.outputs.mode != 'none'
         run: uv sync --locked
       - if: steps.impact.outputs.mode != 'none'
         env:
-          TEST_ROOTS: ${{ steps.impact.outputs.test_roots }}
+          TEST_ROOTS: ${{ steps.impact.outputs.test_roots_json }}
         shell: bash
         run: |
-          read -r -a roots <<< "$TEST_ROOTS"
-          if [ "${#roots[@]}" -eq 0 ]; then
-            echo "Expected test roots for a nonempty plan" >&2
-            exit 1
-          fi
-          uv run --locked pytest "${roots[@]}"
+          uv run --locked python - <<'PY'
+          import json, os, subprocess, sys
+          roots = json.loads(os.environ['TEST_ROOTS'])
+          if not roots:
+              raise SystemExit('Expected test roots for a nonempty plan')
+          raise SystemExit(subprocess.call([sys.executable, '-m', 'pytest', '-p', 'no:selective', *roots]))
+          PY
 ```
 
 The action creates its own Python 3.14 planner environment. Your uv project
 controls the test interpreter. `full-roots` must contain the complete roots, not
-the previous selection. With `full: 'true'`, the action requests a complete run.
+the previous selection. `base` defaults to the PR base or the push's previous
+commit. Override it only when you have validated a different comparison base.
+
+Both file and lane actions default to `full: auto`:
+
+| Trigger | Default |
+| --- | --- |
+| First ordinary PR or push attempt | Select affected work |
+| Rerun, manual, schedule or release | Full checkpoint |
+| PR carrying `test:full` | Full checkpoint |
+| Unknown event or unreadable required event metadata | Full checkpoint |
+
+Use `full: 'true'` to always run everything, or `full: 'false'` to request
+selection even for a manual experiment. Operational uncertainty still falls back
+to full execution. Existing explicit expressions keep their behavior; remove a
+copied standard expression to adopt the shared policy. Updating an action does
+not add missing jobs, schedules, permissions or test dependency declarations.
+GitHub reusable workflows retain the caller's event, so pass `full: 'true'` when
+the reusable invocation itself must be a checkpoint.
 
 | Planner outcome | Action behavior |
 | --- | --- |
@@ -193,8 +211,8 @@ when the README is embedded in the built package.
 The action returns a `lanes` JSON object. Expose it as a planning-job output,
 then gate each expensive job with `always() && !cancelled()` and either a true
 lane value **or a failed planning job**. This preserves tests if planning fails.
-Run the action with `full: true` for manual/release checkpoints, schedules, and
-full-test overrides. Ordinary PRs and main pushes use dependency selection.
+The default event policy handles manual/release checkpoints, schedules and
+`test:full`. Ordinary PRs and main pushes use dependency selection.
 Selected jobs retain all of their existing tests and evidence checks.
 
 

{pytest_selective-0.3.0 → pytest_selective-0.4.0}/docs/configuration.md

@@ -54,6 +54,9 @@ runs the complete configured roots.
 
 ## Declare inputs that imports cannot describe
 
+Start with the [sidecar tutorial](tutorials/sidecar-dependencies.md) for a runnable
+fixture example, directory manifests, dependency comments, and dynamic Python inputs.
+
 For a test that reads a tracked JSON fixture, add a reader-owned comment:
 
 ```python

{pytest_selective-0.3.0 → pytest_selective-0.4.0}/docs/selection-health.md

@@ -30,7 +30,8 @@ uv run pytest-selective audit --config .github/test-impact.json --records impact
 The recorder observes real file reads in the tests you execute. The audit can
 expose a JSON fixture, template or schema that the graph did not declare. Add an
 edge at the reader using a dependency comment or YAML sidecar, then recheck the
-route. [Declaration syntax](configuration.md#declare-inputs-that-imports-cannot-describe).
+route. [Work through the sidecar tutorial](tutorials/sidecar-dependencies.md), or consult
+[declaration syntax](configuration.md#declare-inputs-that-imports-cannot-describe).
 The audit covers observed paths; keep representative full runs for paths it has
 not seen, and explicitly model dynamic imports and external inputs.
 

{pytest_selective-0.3.0 → pytest_selective-0.4.0}/docs/tutorial.md

@@ -1,5 +1,8 @@
 # Start using pytest-selective
 
+Use the [adoption checklist](tutorials/adoption-checklist.md) to work through
+configuration, CI integration, selection health and measurement after this quickstart.
+
 ## Try your existing project
 
 Start in a Git repository whose full pytest suite passes. You need Python 3.11+,

pytest_selective-0.4.0/docs/tutorials/adoption-checklist.md

@@ -0,0 +1,244 @@
+---
+title: Get the most benefit from pytest-selective
+description: A staged adoption tutorial and checklist for local pytest, pre-collection planning, CI lanes, dependency audits, hygiene, timing feedback and measured rollout.
+---
+
+# Get the most benefit from pytest-selective
+
+Choose the level that avoids your actual cost. The native plugin avoids
+unaffected test execution. The pre-collection runner also avoids importing and
+collecting unrelated files. Whole-lane CI planning can avoid starting runners,
+services and application installation altogether.
+
+Use this checklist in your adoption PR. Mark each stage **verified**, **deferred**
+or **not applicable**, with a reason. Pair it with the
+[CI-esta adoption checklist](https://github.com/gigaverse-app/ci-esta/blob/6a694957568c81929a2b3021064ad9674516fb7b/docs/tutorials/adoption-checklist.md)
+for reporting, setup, sharding, history, evidence reuse and security integration.
+Selection remains opt-in; installing the package alone does not narrow pytest.
+
+## 1. Run the disposable example
+
+Use Python 3.11+ and Git 2.24+. Plan with an interpreter at least as new as your
+source syntax; the planner need not install your application dependencies.
+
+```bash
+git clone https://github.com/gigaverse-app/pytest-selective.git
+cd pytest-selective
+uv sync --locked
+uv run python scripts/tutorial.py --output tutorial-report.json
+```
+
+- [ ] The transitive regression selects its reader and catches the introduced failure.
+- [ ] An unrelated README selects no tests and does not launch pytest accidentally.
+- [ ] A shared conftest change retains the full configured inventory.
+- [ ] The tutorial exits successfully despite its intentionally failing pytest controls.
+
+**Done when:** you understand the difference between `scoped`, `none` and `full`
+plans. This demonstrates behavior, not a wall-time speedup. The script uses a
+temporary Git repository; it does not alter your project or staging area.
+
+## 2. Choose local collection or pre-collection execution
+
+In your application repository, install the selector in the test environment:
+
+```bash
+uv add --dev pytest-selective
+uv run pytest --selective
+uv run pytest --no-selective
+```
+
+Commit the dependency and lockfile change through your normal workflow before
+trying a narrow source edit. Uncommitted environment changes intentionally
+select everything and would hide the benefit you are trying to verify.
+
+The plugin collects normally and then deselects. Its default includes staged,
+unstaged and nonignored untracked edits relative to HEAD. An explicit
+`--selective-base origin/main` also includes changes since that exact ref.
+Keep normal test paths, marker filters, fixtures and assertion plugins.
+
+If collection or startup is expensive, create `.github/test-impact.json`:
+
+```json
+{
+  "module_roots": ["src", "."],
+  "test_roots": ["tests"]
+}
+```
+
+Review and record [collection-policy fingerprints](../configuration.md#review-and-record-collection-policy)
+before relying on selection in a repository with pytest configuration. Then use:
+
+```bash
+uv run pytest-selective run --config .github/test-impact.json -- -q
+uv run pytest-selective run --config .github/test-impact.json --full -- -q
+```
+
+- [ ] Inventory every intended test root and any custom filename/collection policy.
+- [ ] Check both local edits and committed base/head changes.
+- [ ] Use the native plugin for custom collection/node-oriented workflows unless
+  you have verified that pre-collection file planning models them correctly.
+- [ ] Keep explicit full execution for whole-suite coverage and conformance requirements.
+- [ ] Do not enable selection globally while validating adoption.
+
+**Done when:** an actual small source edit runs the intended tests, while a full
+control still passes. **Rollback:** `--no-selective` for the plugin or `run --full`
+for the runner. Remove a global selective setting if your project previously added one.
+
+## 3. Declare dependencies that Python imports cannot reveal
+
+Follow the [reader-owned sidecar tutorial](sidecar-dependencies.md). For example,
+place this beside the test that reads the fixture, as `test_prices.py.gv-dependency.yaml`:
+
+```yaml
+dependencies:
+  - inputs: ["//tests/data/prices.json"]
+    kind: content
+    reason: The test reads expected prices from this JSON fixture.
+```
+
+- [ ] Declare templates, fixtures, schema files, AST/text scans and subprocess helpers.
+- [ ] Use `content` for bytes read as data, and `import` when the reader executes
+  Python and needs that module's transitive dependencies.
+- [ ] Keep declarations beside readers; use central rules for actual shared policy.
+- [ ] Review locks, environment configuration, external checkout pins and plugin startup.
+- [ ] Retain default global inputs until a narrower environment contract is verified.
+- [ ] Review nested/custom pytest configuration before refreshing fingerprints.
+- [ ] Repair unmatched paths, invalid sidecars and duplicate keys; do not suppress them.
+
+Inspect the plan before executing it:
+
+```bash
+uv run pytest-selective affected --config .github/test-impact.json \
+  --base origin/main --working-tree --output selection.json \
+  --explanation-output explanation.json
+uv run pytest-selective explain --config .github/test-impact.json \
+  --test tests/test_prices.py --source src/shop/prices.py
+```
+
+Adapt the test/source paths. **Done when:** real edits to each declared input
+select its readers, and an unrelated file does not broaden the plan. Deleted
+inputs and both sides of a rename belong in your controls.
+
+## 4. Move CI selection ahead of expensive setup
+
+Use the [complete CI recipe](../ci.md), or the
+[whole-lane tutorial](skip-unrelated-ci.md) when a suite must run intact.
+
+| Interface | Choose it when | Override / contract |
+| --- | --- | --- |
+| `gigaverse-app/pytest-selective@v1` | Plan ordinary pytest files before collection | Root convenience entry point; same implementation as `actions/test-impact` |
+| `actions/test-impact@v1` | Use the direct action, including runners without root self-reference support | Shared `full: auto` checkpoints; consume `mode` and `test_roots_json` without reparsing reports |
+| `actions/plan-lanes@v1` | Skip complete unaffected jobs while preserving coverage/conformance | Shared `full: auto` checkpoints; `lanes` is a boolean JSON map |
+| `actions/pytest-expansion@v1` | Reject unexplained global conftest expansion before application setup | Configure roots/prefixes to your project; this does not itself run tests |
+
+Specialized action paths above are relative to `gigaverse-app/pytest-selective/`.
+See every input and output in the [action reference](../actions.md). Python
+package versions, the moving Actions major and installed skills update separately.
+
+- [ ] Collect a complete change set with enough Git history before selecting.
+- [ ] Model lane execution inputs, including called actions/reusable workflows.
+- [ ] Avoid broad `.github/**` globals when only execution workflows affect tests.
+- [ ] Consume one successful plan consistently across matrix workers; do not run
+  a second hidden selector against an already selected exact-file manifest.
+- [ ] Keep services, coverage and evidence validators intact inside admitted lanes.
+- [ ] Do not invoke bare pytest on a `none` plan; it runs the whole suite.
+- [ ] Missing history/operational uncertainty runs the full configured roots.
+  Invalid declarations remain visible failures to repair.
+- [ ] Make the planner required and validate skips through an aggregate gate.
+- [ ] Keep ordinary PRs and main pushes selective, with explicit full/manual and
+  scheduled checkpoints. Verify label-trigger behavior instead of assuming it.
+
+**Done when:** the acceptance matrix below passes using actual commits and the
+real workflow. A local plan alone does not establish which hosted jobs execute.
+
+| Control | Expected result |
+| --- | --- |
+| Unreferenced README or PR-template change | Zero tests, including routing, tutorial and installed-package smoke lanes unless they declare that document as an input; metadata/docs checks may still run |
+| Source or transitive helper | All affected reader tests or complete lanes run |
+| Fixture, sidecar, subprocess entry point | Declared readers run |
+| Shared conftest, lock, collection policy or execution workflow | Required broad/full work runs or the policy fails visibly for review |
+| Deleted input / renamed module | Dependents from both Git trees remain covered |
+| Missing history | Full execution, with the fallback explained |
+| Failed planner / invalid configuration | Cannot yield a green skipped required gate |
+| Explicit full override | Complete configured suite and existing validators run |
+
+## 5. Keep the graph narrow and check its blind spots
+
+Run a representative full workload with the optional file-read recorder, then
+audit the resulting records:
+
+```bash
+uv run pytest --no-selective -p pytest_selective.impact_audit_plugin --impact-audit-dir impact-audit
+uv run pytest-selective audit --config .github/test-impact.json --records impact-audit
+```
+
+- [ ] Declare missing observed inputs at their reader and repeat the affected route.
+- [ ] Keep full checkpoints for paths the recorder has not observed.
+- [ ] Use `explain`, `dependencies` and `conftest-impact` to investigate unexpectedly broad selections.
+- [ ] Move helpers/fixtures to the narrowest consuming scope before accepting a new startup floor.
+- [ ] Review and set `floor_budget`; verify a deliberately excessive floor fails visibly.
+- [ ] Add the [expansion and test-file isolation guards](../pytest-hygiene.md)
+  where needed; do not hide new global dependencies behind unexplained exceptions.
+- [ ] Consider `warm` only after measuring graph construction; cache misses must
+  rebuild safely and must never become proof that tests passed.
+
+Use the [selection-health guide](../selection-health.md) for complete commands.
+Audits observe executed paths; they cannot prove that every possible runtime
+dependency has been declared. Keep intentional external-state checks separate.
+
+## 6. Balance selected work without changing eligibility
+
+Use [CI-esta timing retention](https://github.com/gigaverse-app/ci-esta/blob/main/docs/learned-test-timings.md)
+when partial whole-file runs would otherwise erase useful costs. CI-esta owns
+the lifecycle; pytest-selective owns inventory and partitioning.
+
+- [ ] Use separate timing histories per environment and fixed marker lane.
+- [ ] Validate complete files and all expected reports before learning.
+- [ ] Restore once, then freeze the plan or duration input for every worker.
+- [ ] Verify that every selected file is assigned exactly once and unknown files remain included.
+- [ ] Compare existing xdist with proposed shard/pool layouts including startup and service costs.
+- [ ] Keep timing retention, job evidence reuse and test eligibility as separate opt-ins.
+
+Setting `--shard-seconds`, `--max-shards` or a duration manifest changes scheduling
+estimates, not the dependency contract. A case-filtered local run may be valid for
+the plugin while still being unsuitable as a complete-file timing observation.
+
+## 7. Know which commands and scripts to use
+
+| Surface | Purpose / boundary |
+| --- | --- |
+| `pytest --selective`, `--no-selective`; `pytest-selective run` | Local execution, including uncommitted changes; choose collection behavior explicitly. |
+| `affected`, `explain`, `dependencies`, `conftest-impact` | Plan and inspect dependency routes; preserve structured explanations for review. |
+| `fingerprints`, `floor-budget`, `audit`, `warm` | Collection-policy review, breadth budgets, observed-read checks and cache preparation. A fingerprint refresh is a review step, not an automatic fix for every fallback. |
+| `typecheck-scope` | Scope type checking with its own checker/global-input contract; retain a full fallback. Inspect `pytest-selective typecheck-scope --help` and the [scope implementation](../../src/pytest_selective/typecheck_scope.py). |
+| `python -m pytest_selective.ci` | Whole-lane planning outside the GitHub action; the [CI recipe](../ci.md) documents its JSON and full override. There is no `pytest-selective lanes` command. |
+| `pytest-selective-expansion` | Standalone expansion guard; use the [hygiene recipe](../pytest-hygiene.md). |
+| [scripts/tutorial.py](../../scripts/tutorial.py) | Executable Git/selection/pytest example used in stage 1. |
+| [scripts/benchmark_graph.py](../../scripts/benchmark_graph.py) | Compare cold, warm and incremental graph construction on fixed revisions. Its in-memory fingerprint refresh is for measurement, not adoption approval. |
+| [scripts/benchmark_parsing.py](../../scripts/benchmark_parsing.py), [benchmark_rust.py](../../scripts/benchmark_rust.py) | Maintainer parser experiments; they do not enable a production alternate parser or establish hosted savings. |
+| [scripts/compare_impacted.py](../../scripts/compare_impacted.py) | Optional comparison experiment; needs a separately installed pytest-impacted revision. Not a runtime dependency. |
+| [scripts/measure_ci_runs.py](../../scripts/measure_ci_runs.py) | Compare recorded GitHub runs with explicit identities; inspect `--help` and the [measurement limits](../evidence.md). |
+| [scripts/ci_file_config.py](../../scripts/ci_file_config.py), [run_ci_tests.py](../../scripts/run_ci_tests.py) | This toolkit's CI adapters; consumers normally use the public action/runner, not copied wrappers. |
+| [scripts/public_actions.py](../../scripts/public_actions.py), [check_docs.py](../../scripts/check_docs.py), [check_metadata.py](../../scripts/check_metadata.py), [smoke_distribution.py](../../scripts/smoke_distribution.py), [render_brand.py](../../scripts/render_brand.py); `documentation/*.py` | Toolkit generation, documentation and release validation. These are maintainer tools, not extra adopter jobs. |
+
+The Python graph/configuration models, inventory, sharding and hygiene helpers
+are available for integrations, but reuse the public runner/actions for ordinary
+adoption. Do not copy selection logic or create a second dependency declaration
+format in an application helper.
+
+## 8. Measure and hand over an adoption that stays useful
+
+- [ ] Compare successful full and selected runs on the same source head and tested
+  checkout, with unchanged environment and required checks.
+- [ ] Record planning, collection, installation, services, artifacts and reporting
+  alongside pytest execution. Fewer files does not by itself mean lower latency.
+- [ ] Retain run/attempt IDs, elapsed seconds and summed runner-seconds; repeat
+  before claiming an average. Keep cancelled experiments visible separately.
+- [ ] Record configuration assumptions, full-run override, rollback and ownership.
+- [ ] Route the adoption regression tests through their declared real inputs.
+- [ ] Link these results from the PR and update your installed
+  [agent skill](../../skills/pytest-selective/SKILL.md) separately from package/action pins.
+
+Use [CI-esta's measurement recipe](https://github.com/gigaverse-app/ci-esta/blob/main/docs/measured-impact.md)
+to report the result. Installing a newer selector does not automatically configure
+lane routing, runtime audits, hygiene policies, timing retention or evidence reuse.