test: assert the schema-payload invariant once and share one candidate wheel across pristine-root tests

scripts/verify.sh

@@ -326,8 +326,13 @@ lane_compatibility() {
         -m compatibility -n "$workers" --dist load --max-worker-restart=0
         --basetemp="$BASETEMP_ROOT/compatibility"
     )
-    # The compatibility matrix installs wheels per case; there is no cheap
-    # subset, so smoke mode proves the lane runs by collecting only.
+    # Smoke mode collects only because there is no cheap subset, NOT because of
+    # the wheel: both distributions are session fixtures
+    # (tests/package_compatibility/conftest.py) and the wheel arm additionally
+    # honors PROJECT_STANDARDS_COMPATIBILITY_WHEEL, exported above, so the build
+    # happens at most once per worker. The cost is the matrix rows themselves —
+    # each runs the full adopt/reconcile lifecycle once per distribution — and no
+    # `-k` selection of them proves the ownership matrix this lane exists for.
     [[ "$SMOKE" == "1" ]] && args+=(--collect-only -q)
     "$VENV_BIN/pytest" "${args[@]}" || return $?
     reap_basetemp "$BASETEMP_ROOT/compatibility"

tests/agent_handoff/test_packaging.py

@@ -179,16 +179,8 @@ def test_automatic_adoption_preserves_executable_hook_mode(tmp_path: Path) -> No
     assert main(["agent-handoff", "validate", "--repo", str(tmp_path)]) == 0
 
 
-def test_wheel_contains_complete_agent_handoff_bundle(tmp_path: Path) -> None:
-    subprocess.run(
-        ["uv", "build", "--wheel", "--out-dir", str(tmp_path)],
-        cwd=_REPO,
-        check=True,
-        capture_output=True,
-        text=True,
-    )
-    (wheel,) = tmp_path.glob("*.whl")
-    names = set(zipfile.ZipFile(wheel).namelist())
+def test_wheel_contains_complete_agent_handoff_bundle(built_wheel: Path) -> None:
+    names = set(zipfile.ZipFile(built_wheel).namelist())
 
     for bundled in payload_tree(_BUNDLE):
         if not bundled.is_file():
@@ -198,16 +190,10 @@ def test_wheel_contains_complete_agent_handoff_bundle(tmp_path: Path) -> None:
         assert any(name.endswith(expected) for name in names), expected
 
 
-def test_installed_wheel_adopts_and_validates_without_source_checkout(tmp_path: Path) -> None:
-    dist = tmp_path / "dist"
-    subprocess.run(
-        ["uv", "build", "--wheel", "--out-dir", str(dist)],
-        cwd=_REPO,
-        check=True,
-        capture_output=True,
-        text=True,
-    )
-    (wheel,) = dist.glob("*.whl")
+def test_installed_wheel_adopts_and_validates_without_source_checkout(
+    tmp_path: Path, built_wheel: Path
+) -> None:
+    wheel = built_wheel
     venv = tmp_path / "venv"
     environment = {**os.environ, "PYTHONPATH": ""}
     subprocess.run(["uv", "venv", "--seed", str(venv)], check=True, capture_output=True)

tests/conftest.py

@@ -20,6 +20,9 @@
 
 from __future__ import annotations
 
+import os
+import subprocess
+from pathlib import Path
 from typing import Protocol, cast
 
 import pytest
@@ -75,3 +78,40 @@ def pytest_unconfigure(config: pytest.Config) -> None:
     del config.stash[_COVERAGE_STASH]
     worker_coverage.stop()
     worker_coverage.save()
+
+
+_PREBUILT_WHEEL = "PROJECT_STANDARDS_COMPATIBILITY_WHEEL"
+
+_REPO_ROOT = Path(__file__).resolve().parent.parent
+
+
+@pytest.fixture(scope="session")
+def built_wheel(tmp_path_factory: pytest.TempPathFactory) -> Path:
+    """Return one wheel built from the pristine repository root, per session.
+
+    Only for tests that judge what the *released* artifact contains. A test that
+    builds a deliberately modified tree — a synthesized minimal project, a bumped
+    version, a rewritten `[tool.uv.build-backend]` — must keep its own build; this
+    fixture would silently substitute the real repository and prove nothing.
+
+    `PROJECT_STANDARDS_COMPATIBILITY_WHEEL` short-circuits the build, matching the
+    override `tests/package_compatibility/conftest.py` already honors. `scripts/verify.sh`
+    exports it (line 144) after building the candidate wheel once, so every xdist worker
+    reuses that single 71 MB artifact instead of rebuilding it. Without the export each
+    worker builds once, which is the floor: session scope cannot cross process boundaries.
+    """
+    configured = os.environ.get(_PREBUILT_WHEEL)
+    if configured is not None:
+        wheel = Path(configured).resolve(strict=True)
+        if not wheel.is_file() or wheel.suffix != ".whl":
+            raise ValueError(f"{_PREBUILT_WHEEL} must name one wheel file")
+        return wheel
+    output = tmp_path_factory.mktemp("built-wheel")
+    subprocess.run(
+        ["uv", "build", "--wheel", "--out-dir", str(output)],
+        cwd=_REPO_ROOT,
+        check=True,
+        capture_output=True,
+    )
+    (wheel,) = output.glob("*.whl")
+    return wheel

tests/package_contract/test_agent_handoff_1_14.py

@@ -26,8 +26,6 @@
 from project_standards.package_contract.family import load_family_manifest
 from project_standards.package_contract.integrity import validate_payload_integrity
 from project_standards.package_contract.payload import load_payload_manifest
-from project_standards.package_contract.repository import build_package_repository
-from tests.package_contract.helpers import assert_schema_payload_references
 from tests.payload_tree import payload_tree
 
 _ROOT = Path(__file__).resolve().parents[2]
@@ -220,8 +218,6 @@ def test_agent_handoff_1_14__schemas__carry_no_predecessor_version_reference() -
     per-cut assertion caught, so this derives the check from the payload manifest
     instead of naming the constants.
     """
-    assert assert_schema_payload_references(build_package_repository(_ROOT)) == []
-
     successor_text = {
         relative: path.read_text(encoding="utf-8")
         for relative, path in _files(_SUCCESSOR).items()

tests/package_contract/test_agent_handoff_1_15.py

@@ -27,8 +27,6 @@
 from project_standards.package_contract.family import load_family_manifest
 from project_standards.package_contract.integrity import validate_payload_integrity
 from project_standards.package_contract.payload import load_payload_manifest
-from project_standards.package_contract.repository import build_package_repository
-from tests.package_contract.helpers import assert_schema_payload_references
 from tests.payload_tree import payload_tree
 
 _ROOT = Path(__file__).resolve().parents[2]
@@ -148,8 +146,6 @@ def test_agent_handoff_1_15__identity__is_complete_and_current() -> None:
 
 def test_agent_handoff_1_15__schemas__carry_no_predecessor_version_reference() -> None:
     """Guard the copied-payload failure mode: schema constants left pointing at 1.14."""
-    assert assert_schema_payload_references(build_package_repository(_ROOT)) == []
-
     successor_text = {
         relative: path.read_text(encoding="utf-8")
         for relative, path in _files(_SUCCESSOR).items()

tests/package_contract/test_agent_handoff_1_16.py

@@ -25,8 +25,6 @@
 from project_standards.package_contract.family import load_family_manifest
 from project_standards.package_contract.integrity import validate_payload_integrity
 from project_standards.package_contract.payload import load_payload_manifest
-from project_standards.package_contract.repository import build_package_repository
-from tests.package_contract.helpers import assert_schema_payload_references
 from tests.payload_tree import payload_tree
 
 _ROOT = Path(__file__).resolve().parents[2]
@@ -119,8 +117,6 @@ def test_agent_handoff_1_16__identity__is_complete_and_current() -> None:
 
 def test_agent_handoff_1_16__schemas__carry_no_predecessor_version_reference() -> None:
     """Guard the copied-payload failure mode: schema constants left pointing at 1.15."""
-    assert assert_schema_payload_references(build_package_repository(_ROOT)) == []
-
     successor_text = {
         relative: path.read_text(encoding="utf-8")
         for relative, path in _files(_SUCCESSOR).items()

tests/package_contract/test_github_workflow_1_4.py

@@ -25,8 +25,6 @@
 from project_standards.package_contract.family import load_family_manifest
 from project_standards.package_contract.integrity import validate_payload_integrity
 from project_standards.package_contract.payload import load_payload_manifest
-from project_standards.package_contract.repository import build_package_repository
-from tests.package_contract.helpers import assert_schema_payload_references
 from tests.payload_tree import payload_tree
 
 _ROOT = Path(__file__).resolve().parents[2]
@@ -143,8 +141,6 @@ def test_github_workflow_1_4__identity__is_complete_and_current() -> None:
 
 def test_github_workflow_1_4__schemas__carry_no_predecessor_version_reference() -> None:
     """Guard the copied-payload failure mode: constants left pointing at 1.3."""
-    assert assert_schema_payload_references(build_package_repository(_ROOT)) == []
-
     stale = {
         relative
         for relative, path in _files(_SUCCESSOR).items()

tests/package_contract/test_github_workflow_1_5.py

@@ -27,9 +27,7 @@
 from project_standards.package_contract.family import load_family_manifest
 from project_standards.package_contract.integrity import validate_payload_integrity
 from project_standards.package_contract.payload import load_payload_manifest
-from project_standards.package_contract.repository import build_package_repository
 from tests.module_loading import load_module_from_path
-from tests.package_contract.helpers import assert_schema_payload_references
 from tests.payload_tree import payload_tree
 
 _ROOT = Path(__file__).resolve().parents[2]
@@ -133,8 +131,6 @@ def test_github_workflow_1_5__identity__is_complete_and_indexed() -> None:
 
 def test_github_workflow_1_5__schemas__carry_no_predecessor_version_reference() -> None:
     """Guard the copied-payload failure mode: constants left pointing at 1.4."""
-    assert assert_schema_payload_references(build_package_repository(_ROOT)) == []
-
     stale = {
         relative
         for relative, path in _files(_SUCCESSOR).items()

tests/package_contract/test_github_workflow_1_6.py

@@ -28,9 +28,7 @@
 from project_standards.package_contract.family import load_family_manifest
 from project_standards.package_contract.integrity import validate_payload_integrity
 from project_standards.package_contract.payload import load_payload_manifest
-from project_standards.package_contract.repository import build_package_repository
 from tests.module_loading import load_module_from_path
-from tests.package_contract.helpers import assert_schema_payload_references
 from tests.payload_tree import payload_tree
 
 _ROOT = Path(__file__).resolve().parents[2]
@@ -131,8 +129,6 @@ def test_github_workflow_1_6__identity__is_complete_and_indexed() -> None:
 
 def test_github_workflow_1_6__schemas__carry_no_predecessor_version_reference() -> None:
     """Guard the copied-payload failure mode: constants left pointing at 1.5."""
-    assert assert_schema_payload_references(build_package_repository(_ROOT)) == []
-
     stale = {
         relative
         for relative, path in _files(_SUCCESSOR).items()

tests/package_contract/test_github_workflow_1_8.py

@@ -45,8 +45,6 @@
     load_option_schema,
     load_payload_manifest,
 )
-from project_standards.package_contract.repository import build_package_repository
-from tests.package_contract.helpers import assert_schema_payload_references
 from tests.payload_tree import payload_tree
 
 _ROOT = Path(__file__).resolve().parents[2]
@@ -479,8 +477,6 @@ def test_github_workflow_1_8__machine_readable_payload__carries_no_stale_1_7_ref
     adopt.md carry this cut's account of what changed, which cannot be written without
     naming 1.7.
     """
-    assert assert_schema_payload_references(build_package_repository(_ROOT)) == []
-
     stale = {
         relative
         for relative, path in _files(_V18).items()

tests/package_contract/test_markdown_frontmatter_1_13.py

@@ -25,8 +25,6 @@
 from project_standards.package_contract.family import load_family_manifest
 from project_standards.package_contract.integrity import validate_payload_integrity
 from project_standards.package_contract.payload import load_payload_manifest
-from project_standards.package_contract.repository import build_package_repository
-from tests.package_contract.helpers import assert_schema_payload_references
 from tests.payload_tree import payload_tree
 
 _ROOT = Path(__file__).resolve().parents[2]
@@ -183,8 +181,6 @@ def test_markdown_frontmatter_1_13__identity__is_complete_and_retained() -> None
 
 def test_markdown_frontmatter_1_13__schemas__carry_no_predecessor_version_reference() -> None:
     """Guard the copied-payload failure mode: schema constants left pointing at 1.12."""
-    assert assert_schema_payload_references(build_package_repository(_ROOT)) == []
-
     successor_text = {
         relative: path.read_text(encoding="utf-8")
         for relative, path in _files(_SUCCESSOR).items()

tests/package_contract/test_markdown_frontmatter_1_14.py

@@ -28,8 +28,6 @@
 from project_standards.package_contract.family import load_family_manifest
 from project_standards.package_contract.integrity import validate_payload_integrity
 from project_standards.package_contract.payload import load_payload_manifest
-from project_standards.package_contract.repository import build_package_repository
-from tests.package_contract.helpers import assert_schema_payload_references
 from tests.payload_tree import payload_tree
 
 _ROOT = Path(__file__).resolve().parents[2]
@@ -340,8 +338,6 @@ def test_markdown_frontmatter_1_14__identity__is_complete_and_advertised() -> No
 
 def test_markdown_frontmatter_1_14__schemas__carry_no_predecessor_version_reference() -> None:
     """Guard the copied-payload failure mode: constants left pointing at 1.13."""
-    assert assert_schema_payload_references(build_package_repository(_ROOT)) == []
-
     successor_text = {
         relative: path.read_text(encoding="utf-8")
         for relative, path in _files(_SUCCESSOR).items()

tests/package_contract/test_markdown_frontmatter_1_15.py

@@ -38,8 +38,6 @@
     load_option_schema,
     load_payload_manifest,
 )
-from project_standards.package_contract.repository import build_package_repository
-from tests.package_contract.helpers import assert_schema_payload_references
 from tests.payload_tree import payload_tree
 
 _ROOT = Path(__file__).resolve().parents[2]
@@ -416,8 +414,6 @@ def test_markdown_frontmatter_1_15__machine_readable_payload__carries_no_1_14_re
     which predecessors owe no migration edge. Markdown is excluded because the
     standard's own history prose names 1.14 deliberately.
     """
-    assert assert_schema_payload_references(build_package_repository(_ROOT)) == []
-
     stale = {
         relative
         for relative, path in _files(_V115).items()

tests/package_contract/test_project_spec_1_10.py

@@ -28,9 +28,7 @@
 from project_standards.package_contract.family import load_family_manifest
 from project_standards.package_contract.integrity import validate_payload_integrity
 from project_standards.package_contract.payload import load_payload_manifest
-from project_standards.package_contract.repository import build_package_repository
 from project_standards.specs.registry import TEMPLATES_DIR, TIER_FILES
-from tests.package_contract.helpers import assert_schema_payload_references
 from tests.payload_tree import payload_tree
 
 _ROOT = Path(__file__).resolve().parents[2]
@@ -203,8 +201,6 @@ def test_project_spec_1_10__projection_and_catalog_activation_are_exact() -> Non
     generated = (_ROOT / "standards/catalog.md").read_text(encoding="utf-8")
     assert "| [`project-spec`](project-spec/README.md) | active | 1.10 | retained |" in generated
 
-    assert assert_schema_payload_references(build_package_repository(_ROOT)) == []
-
 
 def test_project_spec_1_10__catalog_default__is_what_this_repository_dogfoods() -> None:
     """`.standards/` must resolve the family's catalog default, and still offer 1.10.

tests/package_contract/test_project_spec_1_11.py

@@ -39,8 +39,6 @@
     load_option_schema,
     load_payload_manifest,
 )
-from project_standards.package_contract.repository import build_package_repository
-from tests.package_contract.helpers import assert_schema_payload_references
 from tests.payload_tree import payload_tree
 
 _ROOT = Path(__file__).resolve().parents[2]
@@ -367,8 +365,6 @@ def test_project_spec_1_11__machine_readable_payload__carries_no_stale_1_10_refe
     released edge id stable while its `to` endpoint advances, so `legacy-v4-to-1-10`
     naming 1.10 is the intended state and the endpoint below is what must have moved.
     """
-    assert assert_schema_payload_references(build_package_repository(_ROOT)) == []
-
     stale = {
         path.relative_to(_V111).as_posix()
         for path in payload_tree(_V111)

tests/package_contract/test_project_toolbox_1_0.py

@@ -22,8 +22,6 @@
 from project_standards.package_contract.family import load_family_manifest
 from project_standards.package_contract.integrity import validate_payload_integrity
 from project_standards.package_contract.payload import load_payload_manifest
-from project_standards.package_contract.repository import build_package_repository
-from tests.package_contract.helpers import assert_schema_payload_references
 from tests.payload_tree import payload_tree
 
 _ROOT = Path(__file__).resolve().parents[2]
@@ -132,10 +130,6 @@ def test_project_toolbox_1_0__declared_inventory__matches_the_bytes_on_disk() ->
     assert manifest.capabilities.consumes_platform == ["project-standards.reconcile"]
 
 
-def test_project_toolbox_1_0__schemas__carry_no_dangling_payload_reference() -> None:
-    assert assert_schema_payload_references(build_package_repository(_ROOT)) == []
-
-
 def test_project_toolbox_1_0__payload_projection__matches_the_versioned_source() -> None:
     source_files = {relative: path.read_bytes() for relative, path in _files(_VERSION).items()}
     projected_links = {

tests/package_contract/test_project_toolbox_1_1.py

@@ -25,8 +25,6 @@
 from project_standards.package_contract.family import load_family_manifest
 from project_standards.package_contract.integrity import validate_payload_integrity
 from project_standards.package_contract.payload import load_payload_manifest
-from project_standards.package_contract.repository import build_package_repository
-from tests.package_contract.helpers import assert_schema_payload_references
 from tests.payload_tree import payload_tree
 
 _ROOT = Path(__file__).resolve().parents[2]
@@ -179,8 +177,6 @@ def test_project_toolbox_1_1__identity__is_complete_and_current() -> None:
 
 def test_project_toolbox_1_1__schemas__carry_no_predecessor_version_reference() -> None:
     """Guard the copied-payload failure mode: schema constants left pointing at 1.0."""
-    assert assert_schema_payload_references(build_package_repository(_ROOT)) == []
-
     successor_text = {
         relative: path.read_text(encoding="utf-8")
         for relative, path in _files(_SUCCESSOR).items()

tests/package_contract/test_python_tooling_1_15.py

@@ -60,9 +60,7 @@
     load_option_schema,
     load_payload_manifest,
 )
-from project_standards.package_contract.repository import build_package_repository
 from tests.control_plane.planner_helpers import resolution_request
-from tests.package_contract.helpers import assert_schema_payload_references
 from tests.payload_tree import payload_tree
 
 _ROOT = Path(__file__).resolve().parents[2]
@@ -588,8 +586,6 @@ def test_python_tooling_1_15__machine_readable_payload__carries_no_1_14_referenc
     are excluded for the same reason and are pinned by the narrower assertion below,
     which names the one machine-readable version literal the provider emits.
     """
-    assert assert_schema_payload_references(build_package_repository(_ROOT)) == []
-
     stale = {
         path.relative_to(_V115).as_posix()
         for path in payload_tree(_V115)