Restructure tests into unit, integration, and e2e tiers

.github/workflows/ci.yml

@@ -41,5 +41,5 @@ jobs:
           DISABLE_KUZU: '1'
           DISABLE_NEPTUNE: '1'
         run: |
-          uv run pytest tests/orchestration/test_bulk_serialization.py tests/search/test_search_utils_filters.py
-          uv run pytest tests/test_graphium_mock.py::test_add_episode_persists_nodes_and_edges
+          uv run pytest tests/unit/orchestration/test_bulk_serialization.py tests/unit/search/test_search_utils_filters.py
+          uv run pytest tests/integration/core/shared/test_ingestion_pipeline.py::test_add_episode_persists_nodes_and_edges

AGENTS.md

@@ -52,6 +52,15 @@ Author tests alongside features under `tests/`, naming files `test_<feature>.py`
 - Use `DISABLE_NEO4J=1` (and similar env vars) when running unit-only workflows.
 - `tests/evals/` contains end-to-end evaluation scripts.
 
+### Clean Code & Test Hygiene
+- Prefer `@pytest.mark.parametrize` over manual loops for clearer, isolated assertions.
+- Seed random fixtures (embeddings, UUID helpers, etc.) so test runs are deterministic.
+- Reuse shared constants (e.g., `GROUP_ID`) instead of hard-coding values inside tests.
+- Register fixtures via `pytest_plugins = [...]` rather than importing them solely for side effects; drop unnecessary `noqa` directives once unused imports disappear.
+- Tag fenced markdown blocks with an explicit language (` ```text `, ` ```ini `) to satisfy linting.
+- When defaulting environment flags (e.g., `DISABLE_NEPTUNE`), document the behaviour and let caller-provided values take precedence.
+- For provider-specific integration fixtures, parameterise with sentinels and skip inside the fixture so CI reports a skip instead of aborting when services are disabled.
+
 ## Commit & Pull Request Guidelines
 Commits use an imperative, present-tense summary (for example, `add async cache invalidation`) optionally suffixed with the PR number as seen in history (`(#927)`). Squash fixups and keep unrelated changes isolated. Pull requests should include: a concise description, linked tracking issue, notes about schema or API impacts, and screenshots or logs when behavior changes. Confirm `make lint` and `make test` pass locally, and update docs or examples when public interfaces shift.