test: relocate root tests into suite tree

.github/workflows/ci.yml

@@ -206,7 +206,7 @@ jobs:
       - name: Enforce transcription benchmark contract gate
         run: >
           uv run --frozen --python 3.12 --extra dev pytest -q
-          tests/test_transcription_profiling.py
+          tests/suites/unit/internal/transcription/test_transcription_profiling.py
 
   build:
     runs-on: ubuntu-latest

.github/workflows/linux-selfhosted-gpu-validation.yml

@@ -146,9 +146,9 @@ jobs:
       - name: Run CUDA-focused policy/runtime tests
         run: >
           uv run --python ${{ inputs.python_version }} --extra dev pytest -q
-          tests/test_torch_inference.py
-          tests/test_feature_runtime_policy.py
-          tests/test_transcription_runtime_policy.py
+          tests/suites/unit/utils/test_torch_inference.py
+          tests/suites/unit/repr/test_feature_runtime_policy.py
+          tests/suites/unit/transcription/test_transcription_runtime_policy.py
           tests/suites/integration/test_transcript_extractor.py
 
       - name: Medium profile train and predict (CUDA lane)
@@ -254,11 +254,11 @@ jobs:
       - name: Run XPU-focused policy/runtime tests
         run: >
           uv run --python ${{ inputs.python_version }} --extra dev pytest -q
-          tests/test_torch_inference.py
-          tests/test_feature_runtime_policy.py
-          tests/test_transcription_runtime_policy.py
-          tests/test_emotion2vec_backend.py
-          tests/test_accurate_research_inference.py
+          tests/suites/unit/utils/test_torch_inference.py
+          tests/suites/unit/repr/test_feature_runtime_policy.py
+          tests/suites/unit/transcription/test_transcription_runtime_policy.py
+          tests/suites/unit/repr/test_emotion2vec_backend.py
+          tests/suites/integration/runtime/test_accurate_research_inference.py
 
       - name: Medium profile train and predict (XPU lane)
         env:

.github/workflows/macos15-mps-validation.yml

@@ -97,13 +97,13 @@ jobs:
       - name: Run MPS-focused runtime policy tests
         run: >
           uv run --python ${{ inputs.python_version }} --extra dev pytest -q
-          tests/test_torch_inference.py
-          tests/test_feature_runtime_policy.py
-          tests/test_transcription_runtime_policy.py
-          tests/test_stable_whisper_mps_compat.py
-          tests/test_transcription_mps_admission.py
-          tests/test_transcription_runtime_failures.py
-          tests/test_transcription_backends.py
+          tests/suites/unit/utils/test_torch_inference.py
+          tests/suites/unit/repr/test_feature_runtime_policy.py
+          tests/suites/unit/transcription/test_transcription_runtime_policy.py
+          tests/suites/unit/transcription/test_stable_whisper_mps_compat.py
+          tests/suites/unit/transcription/test_transcription_mps_admission.py
+          tests/suites/unit/transcription/test_transcription_runtime_failures.py
+          tests/suites/unit/transcription/test_transcription_backends.py
 
       - name: Medium profile train and predict (MPS lane)
         env:

README.md

@@ -99,7 +99,11 @@ If your change touches `ser/api.py`, `ser/_internal/api/*`, or `ser/__main__.py`
 
 ```bash
 make import-lint
-uv run pytest -q tests/test_import_lint_policy.py tests/test_api_import_boundary.py tests/test_api.py tests/test_cli.py
+uv run pytest -q \
+  tests/suites/integration/architecture/test_import_lint_policy.py \
+  tests/suites/integration/architecture/test_api_import_boundary.py \
+  tests/suites/integration/api/test_api.py \
+  tests/suites/integration/cli/test_cli.py
 ```
 
 ## Acknowledgments

docs/codebase-architecture.md

@@ -271,7 +271,7 @@ Strengths:
 
 - narrow public API in [`ser/api.py`](../ser/api.py)
 - stable public config facade in [`ser/config.py`](../ser/config.py)
-- boundary tests in [`tests/test_api_import_boundary.py`](../tests/test_api_import_boundary.py)
+- boundary tests in [`tests/suites/integration/architecture/test_api_import_boundary.py`](../tests/suites/integration/architecture/test_api_import_boundary.py)
 - documented hotspot inventory in [`docs/refactor-hotspot-checks.md`](refactor-hotspot-checks.md)
 - CI lanes enforcing lint, typing, tests, contracts, and build in [`.github/workflows/ci.yml`](../.github/workflows/ci.yml)
 

docs/subsystem-dependency-map.md

@@ -230,7 +230,7 @@ smaller abstract service boundaries.
 
 Public modules allowed to import `_internal` directly by design are defined in
 [`boundary_policy.toml`](../boundary_policy.toml). That file is authoritative:
-[`tests/test_api_import_boundary.py`](../tests/test_api_import_boundary.py)
+[`tests/suites/integration/architecture/test_api_import_boundary.py`](../tests/suites/integration/architecture/test_api_import_boundary.py)
 loads it directly, and `make import-lint` enforces the same contract.
 
 Each `[[public_internal_import]]` entry in `boundary_policy.toml` carries both

pyproject.toml

@@ -151,7 +151,7 @@ ignore = ["E501"]
 "ser/_internal/cli/data.py" = ["TID251"]
 "ser/_internal/cli/diagnostics.py" = ["TID251"]
 "ser/_internal/cli/runtime.py" = ["TID251"]
-"tests/test_api.py" = ["TID251"]
+"tests/suites/integration/api/test_api.py" = ["TID251"]
 
 [tool.ruff.format]
 quote-style = "double"

scripts/run_import_lint.sh

@@ -9,5 +9,5 @@ readonly IMPORT_LINT_PATHS=(
 
 uv run --frozen --extra dev ruff check --select TID251 "${IMPORT_LINT_PATHS[@]}"
 uv run --frozen --extra dev pytest -q \
-  tests/test_api_import_boundary.py \
-  tests/test_import_lint_policy.py
+  tests/suites/integration/architecture/test_api_import_boundary.py \
+  tests/suites/integration/architecture/test_import_lint_policy.py

tests/conftest.py

@@ -1,4 +1,4 @@
-"""Shared pytest fixtures for repository-aware test infrastructure."""
+"""Shared pytest fixtures and suite semantics for repository-aware test infrastructure."""
 
 from __future__ import annotations
 
@@ -8,6 +8,55 @@
 
 pytest_plugins = ("tests.fixtures.settings",)
 
+_UNIT_SUITE_PREFIX = ("tests", "suites", "unit")
+_INTEGRATION_SUITE_PREFIX = ("tests", "suites", "integration")
+_ARCHITECTURE_SUITE_PREFIX = ("tests", "suites", "integration", "architecture")
+_SMOKE_SUITE_PREFIX = ("tests", "suites", "smoke")
+_RESET_AMBIENT_SETTINGS_FIXTURE = "reset_ambient_settings"
+
+
+def _matches_suite_prefix(path: Path, prefix: tuple[str, ...]) -> bool:
+    """Returns whether a collected path belongs to the given suite prefix."""
+    parts = path.parts
+    return parts[: len(prefix)] == prefix
+
+
+def _has_usefixture(item: pytest.Item, fixture_name: str) -> bool:
+    """Returns whether a collected item already requests one fixture by name."""
+    return any(fixture_name in marker.args for marker in item.iter_markers(name="usefixtures"))
+
+
+def pytest_collection_modifyitems(
+    config: pytest.Config,
+    items: list[pytest.Item],
+) -> None:
+    """Applies suite markers from the tests/suites directory layout."""
+    root_path = Path(str(config.rootpath)).resolve()
+    for item in items:
+        relative_path = item.path.resolve().relative_to(root_path)
+        if _matches_suite_prefix(relative_path, _ARCHITECTURE_SUITE_PREFIX):
+            if "integration" not in item.keywords:
+                item.add_marker(pytest.mark.integration)
+            if "topology_contract" not in item.keywords:
+                item.add_marker(pytest.mark.topology_contract)
+            if not _has_usefixture(item, _RESET_AMBIENT_SETTINGS_FIXTURE):
+                item.add_marker(pytest.mark.usefixtures(_RESET_AMBIENT_SETTINGS_FIXTURE))
+            continue
+        if _matches_suite_prefix(relative_path, _INTEGRATION_SUITE_PREFIX):
+            if "integration" not in item.keywords:
+                item.add_marker(pytest.mark.integration)
+            if not _has_usefixture(item, _RESET_AMBIENT_SETTINGS_FIXTURE):
+                item.add_marker(pytest.mark.usefixtures(_RESET_AMBIENT_SETTINGS_FIXTURE))
+            continue
+        if _matches_suite_prefix(relative_path, _SMOKE_SUITE_PREFIX):
+            if "smoke" not in item.keywords:
+                item.add_marker(pytest.mark.smoke)
+            if not _has_usefixture(item, _RESET_AMBIENT_SETTINGS_FIXTURE):
+                item.add_marker(pytest.mark.usefixtures(_RESET_AMBIENT_SETTINGS_FIXTURE))
+            continue
+        if _matches_suite_prefix(relative_path, _UNIT_SUITE_PREFIX) and "unit" not in item.keywords:
+            item.add_marker(pytest.mark.unit)
+
 
 @pytest.fixture(scope="session")
 def repo_root(pytestconfig: pytest.Config) -> Path:

tests/test_import_lint_policy.py → tests/suites/integration/architecture/test_import_lint_policy.py

@@ -46,7 +46,7 @@ def test_import_lint_policy_limits_tid251_exceptions_to_boundary_files(repo_root
         "ser/_internal/cli/data.py",
         "ser/_internal/cli/diagnostics.py",
         "ser/_internal/cli/runtime.py",
-        "tests/test_api.py",
+        "tests/suites/integration/api/test_api.py",
     }
     for file_path, ignored_rules in per_file_ignores.items():
         if "TID251" in ignored_rules:
@@ -60,5 +60,5 @@ def test_import_lint_lane_runs_boundary_contract_tests(repo_root: Path) -> None:
     script = (repo_root / "scripts" / "run_import_lint.sh").read_text(encoding="utf-8")
 
     assert "ruff check --select TID251" in script
-    assert "tests/test_api_import_boundary.py" in script
-    assert "tests/test_import_lint_policy.py" in script
+    assert "tests/suites/integration/architecture/test_api_import_boundary.py" in script
+    assert "tests/suites/integration/architecture/test_import_lint_policy.py" in script