[autoresearch] baseline: system prompt quality tests (5/5 passing)

.agents/rules/project-structure-python-backend.md

@@ -0,0 +1,144 @@
+---
+trigger: model_decision
+description: When working on a Python backend project, setting up Python project structure, or organizing Python services and APIs
+---
+
+## Python Backend Layout
+
+Use this structure for Python backend applications. The vertical slice principle applies — features are packages, not technical layers.
+
+```
+apps/
+  backend/                          # Backend application source code
+    pyproject.toml                  # Project metadata, dependencies, tool configs
+    src/
+      yourapp/                      # Importable package (src-layout, preferred)
+        main.py                     # Entry point: creates app, wires dependencies, starts server
+        platform/                   # Foundational technical concerns (the "Framework")
+          database.py               # DB engine and session factory
+          server.py                 # ASGI app setup (FastAPI/Starlette router, middleware)
+          logger.py                 # structlog / logging configuration
+          config.py                 # Settings (pydantic-settings BaseSettings)
+        features/                   # Business Features (Vertical Slices)
+          task/                     # Task management
+            __init__.py
+
+            # --- Public API ---
+            service.py              # TaskService class (public API of this feature)
+
+            # --- Delivery (HTTP) ---
+            router.py               # FastAPI APIRouter with HTTP endpoints
+            schemas.py              # Pydantic request/response models (API boundary only)
+            test_router.py          # Component tests (TestClient + mock service)
+
+            # --- Domain (Business Logic) ---
+            logic.py                # Pure domain functions (no I/O)
+            models.py               # Domain dataclasses (Task, Priority, etc.)
+            errors.py               # Feature-specific exceptions
+            test_logic.py           # Unit tests (pure functions — no mocks needed)
+
+            # --- Storage (Data Access) ---
+            storage.py              # TaskStorage Protocol (interface)
+            storage_pg.py           # PostgreSQL implementation (asyncpg / SQLAlchemy)
+            storage_mock.py         # InMemoryTaskStorage (test implementation)
+            test_storage_pg.py      # Integration tests (real DB via testcontainers)
+
+          order/                    # Order management
+            service.py
+            router.py
+            schemas.py
+            logic.py
+            models.py
+            storage.py
+            storage_pg.py
+            storage_mock.py
+            ...
+    tests/                          # Optional: top-level E2E tests (cross-feature boundaries)
+      e2e/
+        test_create_task_api.e2e.py
+```
+
+**Key Python conventions:**
+
+- **`src/` layout** is strongly preferred — prevents accidental imports of the development tree and matches packaging best practices (PEP 517 / `pypa/build`)
+- **`pyproject.toml`** is the single configuration file for `ruff`, `mypy`, `pytest`, `bandit`, and packaging metadata — do not create `setup.cfg`, `.flake8`, or `mypy.ini` files
+- **Feature packages** use `__init__.py` — keep it empty or use it solely to re-export the feature's public API
+- **`platform/`** holds technical infrastructure that features depend on (database sessions, configuration, logging); features never import each other's `platform/` code directly
+- **Tests co-locate** with the code they test (`test_*.py` in the same directory) except for E2E tests which go in `tests/e2e/`
+- **`storage_mock.py`** is a production-quality in-memory implementation, not a `unittest.Mock` — it is the recommended test double for unit and integration tests
+
+### Dependency Wiring (main.py)
+
+```python
+# src/yourapp/main.py
+from yourapp.platform.database import create_engine
+from yourapp.platform.server import create_app
+from yourapp.features.task.storage_pg import PostgresTaskStorage
+from yourapp.features.task.service import TaskService
+from yourapp.features.task.router import build_router as build_task_router
+
+def create_application() -> FastAPI:
+    engine = create_engine()
+    task_storage = PostgresTaskStorage(engine=engine)
+    task_service = TaskService(storage=task_storage)
+
+    app = create_app()
+    app.include_router(build_task_router(service=task_service))
+    return app
+
+app = create_application()
+```
+
+### Configuration (platform/config.py)
+
+```python
+# src/yourapp/platform/config.py
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    database_url: str
+    secret_key: str
+    debug: bool = False
+
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
+
+def get_settings() -> Settings:
+    return Settings()
+```
+
+### pyproject.toml Baseline
+
+```toml
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "yourapp"
+requires-python = ">=3.11"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/yourapp"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "S", "B", "ANN"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+
+[tool.pytest.ini_options]
+testpaths = ["src"]
+asyncio_mode = "auto"
+
+[tool.bandit]
+skips = ["B101"]   # assert statements allowed in test files
+```
+
+### Related Principles
+- Project Structure @project-structure.md (core philosophy)
+- Python Idioms and Patterns @python-idioms-and-patterns.md (coding idioms, error handling, naming)