groundwork-method 0.0.1 → 0.11.0

package/src/engineer-skills/groundwork-python-engineer/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: groundwork-python-engineer
+description: >
+  Implement and review Python service changes using self-contained engineering
+  references and the current repository as the source of truth. Use for Python
+  backend handlers, services, providers, domain models, ML pipelines, FastAPI
+  routes, async patterns, dependency injection, tests, resilience, or service
+  architecture. This skill is the execution router for Python backend work: it
+  loads reference docs selectively, preserves core/edge boundaries and the
+  inward dependency rule, coordinates with adjacent skills, and verifies
+  changes against contracts and tests. Use
+  this skill whenever the user works in a Python service directory or asks about
+  Python backend / ML engineering, even if they do not explicitly ask for a
+  "python engineer."
+---
+
+# Python Engineer
+
+Python backend execution router for service repositories. Durable engineering guidance lives in `references/`; this skill decides what to load, how to route the task, what repository facts to verify, and which safety gates apply.
+
+## Operating Contract
+
+1. Load reference docs from `references/` for architectural and implementation guidance. Treat the current repository's code, specs, and generated contracts as the source of truth for naming, structure, and behavior.
+2. Orient with the repo map and Serena before reading widely (see Required First Checks) — find the hubs, then navigate by symbol. Inspect the current repository before naming packages, commands, import paths, schemas, or generated files.
+3. Load the smallest reference set that explains the task. Add more context only when the task crosses a boundary.
+4. Preserve the service's dependency direction and public contracts. Code implements OpenAPI, database migrations, event schemas, and documented architecture — it does not invent them.
+5. Treat observability as part of the contract, not an afterthought: a critical path emits an unbroken trace, and a missing span is a defect. Route durable engineering policy to the canonical docs (`docs/principles/stack/python/`, and the cross-cutting canon under `docs/principles/quality/` and `docs/principles/foundations/`) rather than restating it in code comments or this skill.
+6. Coordinate with adjacent skills when another skill owns the primary decision surface.
+
+---
+
+## Code intelligence (repo map + Serena)
+
+GroundWork gives you a deterministic **repo map** (`npx groundwork-method repo-map` — tree-sitter import edges + PageRank centrality, cached to `.groundwork/cache/repo-map.json`) and the **Serena** MCP server (LSP-backed symbol navigation and editing), registered at init. Orient before reading widely: refresh the map, read its `centrality` ranking to find the hubs, then use Serena to navigate them (`get_symbols_overview` / `find_symbol` / `find_referencing_symbols`) and make reference-aware edits (`replace_symbol_body` / `rename`). Full workflow and the graceful-degradation contract live in `.groundwork/skills/code-intelligence.md`; fall back to ordinary reads and edits when they are unavailable.
+
+---
+
+## Required First Checks
+
+Before non-trivial Python implementation or review work:
+
+| Check | Why |
+|---|---|
+| **Orient with the repo map + Serena** — refresh `npx groundwork-method repo-map`, read its `centrality` ranking to find the hubs, then navigate them with Serena (`get_symbols_overview` / `find_symbol` / `find_referencing_symbols`) | A blind file crawl misses the structure the map already computed; symbol navigation and reference-aware edits beat grep-and-read. Fall back to ordinary reads only when these are unavailable |
+| Service package layout and nearby examples for the touched layer | Prevents inventing structure that already has a convention |
+| `pyproject.toml` for Python version and dependencies | Avoids version-specific advice that contradicts the project |
+| OpenAPI spec (if HTTP behavior changes) | HTTP contracts are generated — code must match the spec |
+| Pydantic models for domain and request/response types | Boundary validation is the code; must not be duplicated |
+| Event specs (AsyncAPI, Protobuf) for async behavior | Event types drive code generation downstream |
+
+---
+
+## Context Routing
+
+Load only the rows relevant to the current task. Reference files are in the skill's `references/` directory.
+
+| Task shape | Reference to load |
+|---|---|
+| Any non-trivial service change | `architecture.md`, `implementation-patterns.md` |
+| Async, event loop, TaskGroup, lifespan, background tasks | `async-patterns.md` |
+| Layer placement, new boundary, dependency direction | `architecture.md` |
+| FastAPI endpoint, route handler, inbound defenses | `architecture.md`, `api-standards.md` |
+| Idempotency, pagination, CORS, load shedding | `api-standards.md` |
+| Database schemas, migrations, test isolation, DB sessions | `database.md` |
+| ML pipeline, inference, embedding, RAG, streaming | `ml-pipelines.md` |
+| ML systems architecture, model serving, evals, prompts | `ml-systems-ai-engineering.md` |
+| AI engineering, context design, agent architecture | `ml-systems-ai-engineering.md` |
+| MCP server, tool/resource design, agent interfaces | `documentation-mcp.md` |
+| Resilience — timeouts, retries, circuit breakers, health probes | `resilience.md` |
+| Graceful shutdown, degradation, lifespan management | `resilience.md`, `async-patterns.md` |
+| Observability — tracing, structured logging, metrics | `observability.md` |
+| Security, auth, secrets, input validation, supply chain, SSRF | `security.md` |
+| Tests, quality gates, coverage strategy, fixture design | `testing.md` |
+| Code documentation, docstrings, Pydantic Field docs | `documentation-mcp.md` |
+| Error handling, exception hierarchy, domain errors | `implementation-patterns.md` |
+| Dependency injection, Protocol ports, wiring | `implementation-patterns.md`, `architecture.md`, `database.md` |
+| Capability port + provider (LLM etc.), generated adapter shape, bare-port bet, `add-capability` | `capability-ports.md`, `architecture.md` |
+
+---
+
+## Skill Handoffs
+
+Use the smallest collaborating set. Keep the Python engineer as lead when the work is mainly Python implementation inside a service directory.
+
+| Condition | Hand off to |
+|---|---|
+| Endpoint shape, OpenAPI, error envelope, pagination, idempotency | API architect / API design skill |
+| Schema, migrations, indexes, query plans, vector search | Database / Postgres design skill |
+| Streaming, Pub/Sub, WebSockets, event schemas, fan-out | Real-time / event architecture skill |
+| Test strategy, CI quality gates, contract tests, flake reduction | Test architecture skill |
+| Deployment, Cloud Run, Docker, CI/CD, observability infra | Platform engineering skill |
+| Go backend coordination, inter-service contracts | Go engineer skill |
+
+If the collaborating skill does not exist in the project, handle the concern inline but flag it as outside this skill's primary scope.
+
+---
+
+## Execution Checklist
+
+1. **Identify the touched contract surface** — domain behavior, HTTP contract, event contract, ML pipeline, or tests.
+2. **Load minimal routed references** and inspect nearby code before designing.
+3. **State important inferences** when guidance comes from general Python knowledge rather than project-specific docs or code.
+4. **Implement within existing conventions** — do not create new layer boundaries without evidence from docs or existing code.
+5. **Run targeted tests/checks** when feasible. If not feasible, explain the blocker and name the exact command to run later.
+6. **Summarize** references consulted, files changed, verification performed, and residual risks.
+
+---
+
+## Safety Gates
+
+### Naming and Boundaries
+- Do not invent package paths, command names, contract files, or service boundaries. Verify them in the repository first.
+- Do not create new layer boundaries without evidence from docs or existing code.
+
+### Layer Discipline
+- Do not put business decisions in entrypoints, adapters, or middleware when the architecture expects them in service code.
+- Do not leak adapter-specific types across the core/edge boundary. If an SDK response type appears in a core port, the architecture is broken.
+- FastAPI `Depends`, `Request`, `Session` objects never enter the Service or Domain layers.
+- Always use `pydantic-settings` to validate configuration at startup.
+
+### Inbound Defenses & API Standards
+- Do not use offset/limit pagination for collections; enforce cursor-based pagination.
+- Do not allow mutating endpoints (POST/PATCH) without an `Idempotency-Key` implementation to prevent duplicate side-effects.
+- Do not omit inbound concurrency limits (load shedding); shed load rather than queuing indefinitely.
+- Never use wildcard CORS (`allow_origins=["*"]`).
+
+### Error Handling
+- Do not log and re-raise the same error at multiple layers. Wrap errors with domain exceptions at the adapter boundary and handle at the entrypoint.
+- Map SDK errors to domain exception types before retrying.
+
+### Async Discipline
+- Do not block the event loop. Use `asyncio.to_thread` for synchronous operations.
+- Do not use bare `asyncio.create_task`. Use `asyncio.TaskGroup`.
+- Do not initialise async resources at module level. Use FastAPI `lifespan`.
+
+### Contract & Data Integrity
+- Do not change HTTP behavior without checking the OpenAPI source.
+- Do not change Pydantic models that are part of the public API without checking downstream consumers.
+- Do not add or modify event types without updating the corresponding event spec.
+- Do not use manual UP/DOWN migrations; enforce declarative schema management (e.g., `schema.sql` + diffing engine).
+
+### ML Pipeline Integrity
+- Do not trust model outputs without boundary validation (shape, length, content).
+- Do not hardcode confidence thresholds — use configuration.
+- Do not embed one item at a time — batch API calls.
+- Prompts are code. They live in version control and are covered by evals.
+
+### Generation
+- Do not run code generation manually outside documented generation flows.
+
+---
+
+## Quick Reference
+
+### Domain Error Pattern
+
+| Exception | HTTP | Use |
+|---|---|---|
+| `NotFoundError` | 404 | Resource lookup miss |
+| `UnauthorizedError` | 401 | Missing/invalid auth |
+| `ForbiddenError` | 403 | Valid auth, insufficient permission |
+| `ConflictError` | 409 | Duplicate resource |
+| `ValidationError` | 422 | Field-level validation |
+| `TransientInferenceError` | 503 | Retriable provider failure |
+| `PermanentInferenceError` | 400/500 | Non-retriable provider failure |
+
+### Test Strategy
+
+| Tier | What | Infrastructure |
+|---|---|---|
+| Service test (default) | HTTP → Service → Adapter | Testcontainers + `dependency_overrides` |
+| Unit test (reserved) | Complex domain logic | None |
+| System test (minimal) | Bootstrap + golden path | Full live stack |
+
+### Dependency Injection
+
+```python
+# Port — in src/<package>/core/ports.py
+class Processor(Protocol):
+    async def process(self, uri: str) -> Result: ...
+
+# Adapter — in src/<package>/adapters/
+class ConcreteProcessor:
+    async def process(self, uri: str) -> Result: ...
+
+# Wiring — in entrypoints/ or dependencies.py, typed as the port
+def get_service() -> ProcessingService:
+    return ProcessingService(processor=ConcreteProcessor())
+```
+
+---
+
+## Output Expectations
+
+- Name the references or source files that informed non-obvious decisions.
+- Separate verified repository facts from recommendations based on general Python knowledge.
+- Provide concrete verification commands and results.
+- For code reviews: findings first, ordered by severity, with file references and missing-test risks.
+- For implementation work: changed files, behavior, tests, and follow-up risks.

package/src/engineer-skills/groundwork-python-engineer/references/api-standards.md

@@ -0,0 +1,88 @@
+# API Standards & Inbound Defenses
+
+Every Python service must expose a hardened, predictable API surface. Implement these Day-2 operational requirements at the FastAPI entrypoint layer.
+
+## 1. Idempotency
+
+Mutating endpoints (`POST`, `PATCH`) must be idempotent to allow safe client retries; `PUT` is idempotent by HTTP semantics and needs no key.
+
+- Require an `Idempotency-Key` header on mutating requests.
+- Intercept the key in middleware or a FastAPI dependency before business logic executes.
+- Store the intent and the final response in a fast, persistent store (e.g., Redis).
+- If a request arrives with a known key and is `IN_PROGRESS`, return `409 Conflict`.
+- If a request arrives with a known key and is `COMPLETED`, return the cached response immediately.
+
+```python
+from fastapi import Header, Depends
+
+async def verify_idempotency(
+    idempotency_key: str = Header(..., min_length=16)
+):
+    # Check Redis/DB. If completed, raise a custom exception that 
+    # an exception handler catches to return the cached response.
+    pass
+
+@router.post("/items")
+async def create_item(
+    body: ItemCreate,
+    _: None = Depends(verify_idempotency)
+) -> ItemResponse:
+    # Business logic executes only once per key
+    pass
+```
+
+## 2. Cursor-Based Pagination
+
+Never use offset/limit pagination for collections. Offset pagination scales poorly (O(N) database scans) and skips/duplicates items if the underlying dataset changes during iteration.
+
+- Always return a `cursor` (usually a base64-encoded string representing the last seen ID and sort column).
+- Include `has_next` boolean.
+- Use generic Pydantic wrappers for paginated responses.
+
+```python
+from typing import Generic, TypeVar
+from pydantic import BaseModel
+
+T = TypeVar("T")
+
+class PaginatedList(BaseModel, Generic[T]):
+    items: list[T]
+    next_cursor: str | None
+    has_next: bool
+
+@router.get("/items")
+async def list_items(cursor: str | None = None, limit: int = 50) -> PaginatedList[ItemResponse]:
+    # Pass cursor down to the repository port
+    pass
+```
+
+## 3. Load Shedding & Concurrency Limits
+
+Do not allow an API to queue requests indefinitely until memory is exhausted or timeouts cascade.
+
+- Implement an inbound concurrency limit (e.g., using a FastAPI middleware that acquires an `asyncio.Semaphore`).
+- When the semaphore is exhausted, immediately shed load by returning `503 Service Unavailable`.
+- This ensures the service remains responsive for health checks and active requests, rather than becoming a black hole.
+
+## 4. CORS Configuration
+
+Configure `CORSMiddleware` explicitly. Never use `allow_origins=["*"]` in production.
+
+```python
+from fastapi.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.CORS_ALLOWED_ORIGINS,  # Loaded from env
+    allow_credentials=True,
+    allow_methods=["GET", "POST", "PATCH", "DELETE"],
+    allow_headers=["Authorization", "Content-Type", "Idempotency-Key"],
+)
+```
+
+## Anti-Patterns
+
+- **Offset pagination.** `?limit=50&offset=1000` requires the database to scan and discard 1,000 rows.
+- **Ignoring idempotency keys.** Clients will retry on timeouts, causing duplicate side effects (e.g., double charges, duplicate records).
+- **Queuing without bounds.** A service processing 10 req/sec should reject the 100th concurrent request rather than queuing it for 10 seconds.
+- **Wildcard CORS.** Leaks cross-origin data. Always restrict to known frontends.

package/src/engineer-skills/groundwork-python-engineer/references/architecture.md

@@ -0,0 +1,57 @@
+# A Pure Core, Swappable Edges (Python)
+
+## Dependency Rule
+
+Dependencies flow inward. The core never imports from the edge. `import-linter` (a `[tool.importlinter]` contract in `pyproject.toml`) makes this a real gate: it forbids `<package>.core` (and `<package>.core.*`) from importing `<package>.adapters`, `<package>.entrypoints`, `fastapi`, or `sqlalchemy`, and a `<package>.core` → `<package>.adapters` import fails `lint-imports`.
+
+## Where code lives
+
+`src/` holds the importable package `src/<package>/` (src-layout); `<package>` is the service name in snake_case. The pieces (paths relative to `src/<package>/`):
+
+| Zone | Location | Depends on | Contains |
+|---|---|---|---|
+| **Domain** | `src/<package>/core/domain` | Nothing (stdlib + Pydantic only) | Pydantic/dataclass entities, value objects, exceptions, constants |
+| **Ports** | `src/<package>/core/ports.py` (+ per-capability modules like `src/<package>/core/llm.py`) | Domain only | `typing.Protocol` (default) or `abc.ABC` definitions describing the capabilities the core consumes |
+| **Services** | `src/<package>/core/service` | Domain + Ports | Use-case orchestration, workflow coordination |
+| **Adapters** | `src/<package>/adapters/` | Domain + Ports | Concrete implementations (Postgres, external APIs, message brokers) |
+| **Entrypoints** | `src/<package>/entrypoints/` | Domain + Services | FastAPI routes, CLI, Pub/Sub consumers, MCP servers |
+
+## Structural Invariants
+
+- The Domain imports no framework, no SDK, no database driver, no HTTP library. Pydantic and stdlib only.
+- Ports define _what_ (e.g., `store`, `transcribe`), never _how_. Signatures use Domain entities exclusively.
+- Ports use domain names: `publish(msg: Message)`, not `send_to_sqs(msg: Message)`.
+- Services depend on ports (Protocols), not concrete adapters. Return concrete Domain objects.
+- Adapters map external SDK responses into Domain entities. Catch library-specific errors and raise Domain exceptions.
+- Entrypoints validate inputs, map request schemas to Domain objects, and delegate all business decisions to Services.
+- All concrete adapter-to-service wiring happens at the outermost edge (entrypoint startup or a dedicated `dependencies.py` / `container.py`).
+
+## Dependency Injection
+
+- **Constructor injection** via `__init__` for all dependencies.
+- **Explicit lifecycles**: initialise database clients in FastAPI's `lifespan` context manager, not at module level.
+- **No DI frameworks**: wiring is manual, explicit, and visible at the composition root.
+
+## Integrity Testing
+
+### Bootstrap Verification
+A test in `tests/system/test_bootstrap.py` initialises the full dependency tree. Catches missing env vars and wiring failures before production.
+
+### Golden Path System Tests
+Run a live instance against real infrastructure via Testcontainers. Zero mocks. Verify the critical success paths end-to-end.
+
+## Engineering Standards
+
+1. **Pydantic everywhere.** Use Pydantic for all data boundaries (request/response and domain).
+2. **Structured logging.** Use `structlog` or equivalent — never bare `print`.
+3. **Acyclic dependencies.** Import cycles are an immediate signal of leaked layer responsibilities.
+4. **Strict boundaries.** FastAPI `Depends`, `Request`, `Session` objects never enter the Service or Domain layers.
+5. **Clean containers.** Always call `container.stop()` or equivalent in pytest fixtures.
+
+## Anti-Patterns
+
+- **Framework-coupled domain.** If the core imports FastAPI or SQLAlchemy, it is broken.
+- **Leaky ports.** A port with SDK types in its signature is an adapter in disguise.
+- **Anaemic domain models.** Data structs with no behaviour and a thick service.
+- **Over-layering.** Five layers of DTO translation. Adapters are thin.
+- **Layer-skipping.** Entrypoints talking directly to adapters.

package/src/engineer-skills/groundwork-python-engineer/references/async-patterns.md

@@ -0,0 +1,103 @@
+# Async Patterns
+
+## The One Rule: Never Block the Event Loop
+
+Any synchronous call longer than ~1ms inside an `async def` stalls every other coroutine. Symptoms: random, unrelated timeouts across the service.
+
+Blocking calls — file I/O, model loading, `time.sleep`, synchronous SDK methods — must run in a thread:
+
+```python
+import asyncio
+
+result = await asyncio.to_thread(blocking_function, arg1, arg2)
+```
+
+## Structured Concurrency with TaskGroup
+
+`asyncio.TaskGroup` is the only primitive that guarantees all tasks complete — or are cancelled — before control returns to the caller:
+
+```python
+async def process_item(item_id: str) -> ProcessedResult:
+    async with asyncio.TaskGroup() as tg:
+        primary_task = tg.create_task(primary_process(item_id))
+        secondary_task = tg.create_task(secondary_process(item_id))
+
+    return ProcessedResult(
+        primary=primary_task.result(),
+        secondary=secondary_task.result(),
+    )
+```
+
+If either task raises, `TaskGroup` cancels the sibling and re-raises. No orphaned tasks, no leaked resources.
+
+**Never use bare `asyncio.create_task`.** The event loop holds only a weak reference — if the caller exits, the task is garbage collected mid-execution:
+
+```python
+# Wrong — task may be silently dropped
+asyncio.create_task(publish_event(event))
+
+# Correct — task lifetime bound to TaskGroup scope
+async with asyncio.TaskGroup() as tg:
+    tg.create_task(publish_event(event))
+```
+
+## Route Handlers
+
+All route handlers are `async def`. Synchronous `def` handlers are threaded by FastAPI's executor — this makes the async/sync boundary invisible and causes subtle performance issues.
+
+## Background Tasks
+
+Use FastAPI's `BackgroundTasks` for post-response work:
+
+```python
+from fastapi import BackgroundTasks
+
+@router.post("/process")
+async def process_endpoint(
+    request: ProcessRequest,
+    background_tasks: BackgroundTasks,
+) -> ProcessResponse:
+    result = await service.process(request.input_url)
+    background_tasks.add_task(publish_completed_event, result.id)
+    return ProcessResponse.from_domain(result)
+```
+
+## Application Lifespan
+
+Initialise shared resources in the FastAPI `lifespan` context manager:
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    db_pool = await create_db_pool()
+    app.state.db = db_pool
+    yield
+    await db_pool.close()
+
+app = FastAPI(lifespan=lifespan)
+```
+
+**Never initialise clients at module level.** Module-level runs at import time, before env vars load, and cannot be awaited.
+
+## Toolchain
+
+`uv` manages all Python tooling:
+
+```bash
+uv run pytest          # Run tests
+uv add httpx           # Add a dependency
+uv sync                # Sync from lockfile
+```
+
+The lockfile (`uv.lock`) is committed. Every developer and CI run resolves identical trees.
+
+## Anti-Patterns
+
+- **Blocking the event loop.** Use `asyncio.to_thread` for blocking operations.
+- **Bare `asyncio.create_task`.** Creates untracked tasks that can be silently dropped.
+- **Synchronous `def` route handlers.** Write `async def` so the boundary is explicit.
+- **Module-level async initialisation.** `asyncio.run()` at import time conflicts with FastAPI's loop.
+- **`asyncio.sleep` as retry delay.** Use `tenacity` with async backoff.

package/src/engineer-skills/groundwork-python-engineer/references/capability-ports.md

@@ -0,0 +1,44 @@
+# Capability Ports & Providers
+
+GroundWork scaffolds external capabilities (LLM inference, and the same pattern for any future capability) as **a port the core owns plus a selectable provider that satisfies it**. When you read or hand-write one of these, match the generated shape exactly — the generator and your code are the same contract.
+
+## The model
+
+- A **capability** is a port: a `Protocol` the core owns, in `src/<package>/core/` (e.g. `src/<package>/core/llm.py`).
+- A **provider** is the vendor that satisfies the capability; its implementation is the adapter, in `src/<package>/adapters/` (e.g. `src/<package>/adapters/llm.py`). Choosing a provider selects the adapter wired in at the edge; the port and its callers never change.
+- Each provider declares a **footprint** — exactly one of `env`, `compose-service`, `runner`, `none` — which is the only thing that varies the operational cost. Infrastructure is a consequence of the provider, not a default.
+
+| Footprint | Means | Materializes as |
+|---|---|---|
+| `env` | config only (a hosted API) | env vars in `.env.example`, no infra |
+| `compose-service` | a container (a self-hosted server) | a service in `docker-compose.yml` |
+| `runner` | a host process | an entry in `.dev/dev.config.json` runners |
+| `none` | the bare port — a bet | port + stub + conformance test, nothing else |
+
+## Generated shape (LLM reference family)
+
+```
+src/<package>/core/llm.py            # the port — a runtime_checkable Protocol, core-owned
+src/<package>/adapters/llm.py        # the adapter — one provider's implementation
+tests/contracts/test_llm.py   # the contract test
+```
+
+- **Port** — a `@runtime_checkable` `Protocol`, no SDK type in its signature. It lives in its own module (`src/<package>/core/llm.py`), separate from the shared `src/<package>/core/ports.py`, so `add-capability` can generate it independently.
+  ```python
+  @runtime_checkable
+  class TextGenerator(Protocol):
+      async def generate_text(self, prompt: str, max_tokens: int = 100) -> str: ...
+  ```
+- **Adapter** — `LLMClient` in `src/<package>/adapters/llm.py`, implements the protocol structurally (no `class LLMClient(TextGenerator)` inheritance needed). Reads config from `settings`, wraps calls in `tenacity` retry + a circuit breaker, raises the domain's `TransientInferenceError` / `PermanentInferenceError`. A hosted provider adds its SDK to `pyproject.toml`; a self-hosted one uses the OpenAI-compatible client.
+- **Wiring** — provide `LLMClient()` from your composition root (e.g. `dependencies.py get_text_generator`) typed as the `TextGenerator` port from `core.llm`. Never let a service depend on the concrete adapter.
+
+## The `none` bare port (a bet)
+
+`--provider none` ships the port, a stub adapter that raises `NotImplementedError`, and a **strict-xfail** contract test. The test is kept `@pytest.mark.xfail(strict=True)` so a fresh scaffold stays green *and* flips red the moment the adapter starts working — that is the open-bet marker: the contract is fixed, the implementation is owed. Implement the adapter behind the existing port to cash it, then drop the xfail. The conformance check is `issubclass(LLMClient, TextGenerator)` — no construction, no network.
+
+## Rules when you touch one of these
+
+- Add a capability to an existing service with `nx g add-capability --service <svc> --capability llm --provider <p>` — it runs the same injector the scaffold does, idempotently.
+- Swapping providers swaps only the adapter file, its dependency, and the footprint. If a change forces the port or a caller to change, the port was leaky — fix the port, not the callers.
+- Surfaces and frontends do **not** embed an adapter; they call this service's port over its API (keys stay server-side, one owner per capability).
+- A hand-written adapter must pass the same `issubclass(...)` conformance test the generator emits.

package/src/engineer-skills/groundwork-python-engineer/references/database.md

@@ -0,0 +1,88 @@
+# Database & Schema Management
+
+## 1. Declarative Schema
+
+Manual `UP`/`DOWN` migrations (e.g., standard Alembic versions) cause merge conflicts in distributed teams and make the "target state" of the database impossible to read without executing scripts.
+
+We use **declarative schema management**.
+- The source of truth is a single `schema.sql` file (or equivalent Prisma/SQLAlchemy models).
+- We use a diffing engine (e.g., `atlas` or `alembic revision --autogenerate`) to compute the migration dynamically.
+- Migrations are applied automatically during deployment, or generated purely as a verification step in CI.
+
+## 2. Session Management & Dependency Injection
+
+The database session lifecycle is managed at the entrypoint layer (FastAPI), not within the Domain or Service layers.
+
+### The FastAPI Dependency
+
+Use a FastAPI dependency to yield a session and ensure it is closed after the request completes.
+
+```python
+from typing import AsyncGenerator
+from sqlalchemy.ext.asyncio import AsyncSession
+from <package>.adapters.database import async_session_maker
+
+async def get_db_session() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session_maker() as session:
+        yield session
+```
+
+### Injecting into Adapters
+
+Inject the `AsyncSession` into the concrete adapter. **Never pass the session into the Service or Domain layers.**
+
+```python
+from fastapi import Depends
+from <package>.core.ports import OrderRepository
+from <package>.adapters.repository import PostgresOrderRepository
+
+def get_order_repository(
+    session: AsyncSession = Depends(get_db_session)
+) -> OrderRepository:
+    # PostgresOrderRepository implements the OrderRepository port
+    return PostgresOrderRepository(session=session)
+
+def get_order_service(
+    repository: OrderRepository = Depends(get_order_repository)
+) -> OrderService:
+    return OrderService(repository=repository)
+```
+
+The dependency is typed as the **port** (the `OrderRepository` Protocol from `<package>.core.ports`), not the concrete `PostgresOrderRepository` — the seam stays on the port.
+
+## 3. Transaction Boundaries
+
+By default, the `get_db_session` dependency provides an open transaction if the SQLAlchemy engine is configured correctly. However, explicit transaction boundaries (commit/rollback) belong in the Provider or the Service, depending on the isolation requirement.
+
+If the Service coordinates multiple repository calls that must be transactional, use a generic "Unit of Work" (UoW) pattern rather than leaking `session.commit()` into the Service.
+
+## 4. The shape of the persistence port
+
+By default the SQLAlchemy `AsyncSession` already is a unit of work and a collection-like store — a thin CRUD service can use it directly rather than defining its own port. Introduce a persistence port (a domain-named repository Protocol in `src/<package>/core/ports.py`) only when a rich domain aggregate must stay storage-ignorant. When you do:
+
+- **One port per aggregate root, named in the domain's language** (`OrderRepository.get`, `.save`) — never a generic `Repository[T]` / `Generic[T]` CRUD base. Its "generic" is unproven from a single implementation, and a uniform CRUD surface leaks the store's shape into the core (the very leak it was meant to prevent).
+- **Define the port as a narrow `Protocol` or ABC in the core**, exposing only the methods the service calls. A good size check: if an in-memory fake of the port is awkward to write, the port is too broad.
+- When query variety grows, reach for a query object / specification — not more methods on the port or a leaked SQLAlchemy `Select`.
+- Integration-test the adapter against a real Postgres (Testcontainers); never mock the port or the database.
+
+## 5. Test Isolation
+
+Never mock the database. Use Testcontainers for a real Postgres instance.
+Between tests, isolate state by truncating tables rather than recreating the schema, as truncation is significantly faster.
+
+```python
+import pytest
+from sqlalchemy import text
+
+@pytest.fixture(autouse=True)
+async def clear_database(db_session: AsyncSession):
+    """Truncates all tables between tests."""
+    await db_session.execute(text("TRUNCATE TABLE orders, users CASCADE;"))
+    await db_session.commit()
+```
+
+## Anti-Patterns
+
+- **Leaking sessions.** Passing `AsyncSession` directly into the Domain or Service layer breaks the Dependency Inversion Principle.
+- **Manual migration scripts.** Writing manual `ALTER TABLE` statements causes drift. Use a declarative engine.
+- **Mocking the database.** Use Testcontainers. Mocks hide SQL syntax errors and constraint violations.