coding-os 0.3.2__py3-none-any.whl

core/skills/hexagonal-architecture/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: hexagonal-architecture
+description: Design and refactor systems using Ports & Adapters (Hexagonal Architecture). Use when starting a new service, untangling framework-coupled business logic, supporting multiple delivery mechanisms (HTTP + queue + CLI), swapping infrastructure (Postgres → Mongo, REST → gRPC) without touching domain code, or planning long-lived enterprise systems where framework churn is a real risk. Covers Go+Fiber, Python+FastAPI, and React Native client adaptations.
+tier: cross-cutting
+domain: [architecture]
+last_reviewed: "2026-05-11"
+
+---
+
+# Hexagonal Architecture — Ports & Adapters
+
+A practical playbook for building business-logic-first systems where the domain is shielded from frameworks, transports, and persistence. Pattern by Alistair Cockburn (2005); proven across two decades of Java, .NET, Go, Python, and TypeScript codebases.
+
+## When to Use This Skill
+
+Invoke this skill **before** writing the first business-logic file in a new service, **or** when you find yourself:
+
+- Writing tests that mock five frameworks just to assert one business rule
+- Wanting to add a CLI / cron / queue-consumer entry point but every code path threads through HTTP request/response objects
+- Replacing PostgreSQL with another store and discovering business code imports `sqlalchemy` directly
+- Asking "where does the *real* logic live?" and finding the answer is "scattered across controllers"
+- Planning a long-lived system where the current framework will be obsolete in 5 years
+
+**Skip** for: throwaway scripts, one-off scrapers, CRUD-only admin tools where the framework IS the application.
+
+## The Three Layers
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  ADAPTERS (infrastructure + delivery)                       │
+│   ┌─────────────┐    ┌─────────────┐    ┌──────────────┐   │
+│   │ HTTP route  │    │ CLI command │    │ Queue worker │   │  ← inbound
+│   └──────┬──────┘    └──────┬──────┘    └──────┬───────┘   │
+│          │                  │                   │           │
+│          ▼                  ▼                   ▼           │
+│  ╔══════════════════════════════════════════════════════╗   │
+│  ║  APPLICATION (use cases — orchestrate domain)        ║   │
+│  ║                                                      ║   │
+│  ║  ╔══════════════════════════════════════════════╗    ║   │
+│  ║  ║  DOMAIN (entities, value objects, rules)     ║    ║   │
+│  ║  ║                                              ║    ║   │
+│  ║  ║  Pure. No framework imports. No I/O.         ║    ║   │
+│  ║  ╚══════════════════════════════════════════════╝    ║   │
+│  ║                                                      ║   │
+│  ║  Outbound port interfaces live here.                 ║   │
+│  ╚════════════════════════════════════════════════╤═════╝   │
+│          ▲                  ▲                     ▲          │
+│          │                  │                     │          │  ← outbound
+│   ┌──────┴──────┐    ┌──────┴──────┐    ┌────────┴───────┐  │
+│   │ Postgres    │    │ Redis cache │    │ Stripe SDK     │  │
+│   │ repository  │    │ adapter     │    │ adapter        │  │
+│   └─────────────┘    └─────────────┘    └────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 1. Domain (innermost, framework-free)
+
+The "what is true about the business" layer. Entities (have identity over time), value objects (immutable, identity-by-value), and domain services (operations that don't naturally belong to one entity).
+
+**Rules:**
+
+- ZERO framework imports. No `gorm`, `sqlalchemy`, `fiber`, `fastapi`, `react`. Standard library only.
+- No I/O. No `time.Now()` / `datetime.now()` directly — inject a `Clock` port.
+- No randomness. Inject a `UUIDGen` / `RandomSource` port if needed.
+- Domain types raise domain-level exceptions (`InsufficientBalance`, not `HTTPException(400)`).
+
+### 2. Application (use cases)
+
+Orchestrates the domain. One use case = one user-meaningful operation (`PlaceOrder`, `RegisterUser`, `RecommendNextLesson`).
+
+**Each use case:**
+
+- Has a single public method (typically named `execute`, `handle`, or `__call__`)
+- Receives a typed input (Command / Query DTO) — never an HTTP request object
+- Returns a typed output — never an HTTP response object
+- Depends only on **outbound port interfaces** (repositories, gateways, clock) — never concrete implementations
+- Wraps domain operations in a transaction when needed (via a `UnitOfWork` outbound port)
+
+### 3. Adapters (outermost, framework-coupled)
+
+Two flavors:
+
+- **Inbound (driving)** — turn external triggers into use case invocations. HTTP route → parse body → build Command → call `usecase.execute(command)` → format response.
+- **Outbound (driven)** — implement outbound port interfaces using infrastructure. PostgresUserRepository, StripeBillingGateway, RedisRateLimiter, SystemClock.
+
+The **composition root** is the only place where concrete adapters are wired to use cases — typically `main.go` / `main.py` / `app.tsx`.
+
+## Ports — the Contracts
+
+A port is an interface. Two kinds:
+
+| Kind | Where it lives | Purpose | Examples |
+|---|---|---|---|
+| **Inbound port** | Application layer | What the app *can do* | `PlaceOrder`, `GetUserProfile` (use case interfaces) |
+| **Outbound port** | Application layer (or domain if truly domain-level) | What the app *needs* | `UserRepository`, `PaymentGateway`, `Clock`, `UUIDGen`, `EmailSender` |
+
+**Critical**: outbound port interfaces are owned by the **application layer**, not by the adapter that implements them. This is dependency inversion — the consumer defines the contract, the implementer adapts.
+
+```
+✗ WRONG: postgres/repository.go defines UserRepo, app/usecase.go imports it
+✓ RIGHT: app/ports/user_repository.go defines UserRepository,
+         postgres/user_repository.go implements it
+```
+
+## Per-Stack Layouts
+
+This project spans Go+Fiber (business core), Python+FastAPI (AI adapter service), and React Native (mobile client). The hexagonal pattern translates differently to each idiom — see the dedicated references:
+
+- **Go+Fiber backend** — see [references/go-fiber-layout.md](references/go-fiber-layout.md) — folder layout, interface conventions, wire-style composition root, `internal/` boundary enforcement.
+- **Python+FastAPI service** — see [references/python-fastapi-layout.md](references/python-fastapi-layout.md) — protocol-based ports, dependency injection via `Depends`, async use cases, Pydantic at boundaries only.
+- **React Native client** — see [references/react-native-layout.md](references/react-native-layout.md) — domain in TypeScript, screens-as-adapters, hooks as composition root, why this still pays off on mobile.
+- **Anti-patterns** — see [references/anti-patterns.md](references/anti-patterns.md) — anemic domain, leaky framework types in ports, port-as-DTO confusion, premature port extraction.
+
+## Decision Points
+
+When applying this skill, walk through these in order:
+
+### 1. Is this a new service or a refactor?
+
+- **New service**: scaffold the three folders before writing the first line of business logic. Use [assets/folder-scaffold.md](assets/folder-scaffold.md).
+- **Refactor**: identify the existing god-class / fat controller. Extract domain types first, then use cases, then port interfaces. Adapters come last.
+
+### 2. What are the inbound surfaces?
+
+List every way the use case is triggered: HTTP route, CLI command, scheduled job, queue consumer, gRPC method, GraphQL resolver. Each becomes an inbound adapter. The use case itself does not change.
+
+### 3. What does the use case need?
+
+List every external dependency: data store, external API, email/SMS, message bus, secret store, clock, randomness. Each becomes an outbound port.
+
+### 4. Where do DTOs live?
+
+- **Command/Query DTOs** at use case boundary — application layer.
+- **HTTP request/response DTOs** — inbound adapter (REST controller).
+- **Database row structs** — outbound adapter (repository).
+- **Domain entities** — domain layer.
+
+DTOs cross **only one** layer boundary. The HTTP request struct is parsed in the controller into a Command DTO that the use case understands. The use case returns a result DTO that the controller maps to an HTTP response. **Never let an `HttpRequest` reach the use case.**
+
+### 5. Where does the transaction live?
+
+Outbound port `UnitOfWork` (or `Transactor`). Use case receives it and calls `uow.run(lambda: ...)`. The Postgres adapter implements it with `BEGIN/COMMIT`. The in-memory test adapter implements it with a no-op. **Never sprinkle `BEGIN/COMMIT` in repositories.**
+
+## Testing Strategy
+
+Hexagonal pays its biggest dividend in tests:
+
+- **Domain tests** — pure unit tests, no mocks. `OrderTotal_when_two_items_returns_sum`.
+- **Use case tests** — wire fake (in-memory) outbound adapters, drive the use case, assert outputs and adapter side-effects. Fast, deterministic, covers business rules.
+- **Adapter tests** — integration tests against real infrastructure (real Postgres in a Docker container, real Stripe sandbox). Slow but few.
+- **End-to-end tests** — full HTTP-to-DB. Smoke level only; the use case tests already cover branches.
+
+Inverted from the usual pyramid: lots of fast use-case tests, very few e2e tests.
+
+```
+        /\
+       /  \   e2e (5%)
+      /────\
+     / adapt\  adapter integration (15%)
+    /────────\
+   /          \  use case + domain (80%)
+  /────────────\
+```
+
+## Common Pitfalls (full list in references/anti-patterns.md)
+
+1. **Anemic domain** — entities are bags of public fields with no behavior. The "domain" is just data classes; rules live in services. Symptom: every "domain" file is a struct/dataclass with zero methods.
+2. **Framework types in ports** — outbound port returns `*sql.Rows` or `dict[str, Any]`. The adapter is supposed to hide the framework, not leak it.
+3. **God use case** — one `OrderService` with 20 public methods. Each method should be its own use case class.
+4. **Premature port extraction** — every concrete class wrapped in an interface "just in case". Only extract a port when you have a real reason: testability, two implementations, or anticipated swap.
+5. **Reverse dependency** — domain imports from application or adapters. The dependency rule says inner layers know nothing of outer. If you need infrastructure at domain level, you're missing a port.
+
+## Composition Root
+
+Every entrypoint (main, server bootstrap, lambda handler) wires the graph **once**:
+
+```
+main()
+ ├─ load config
+ ├─ build outbound adapters (PostgresUserRepo, StripeGateway, SystemClock)
+ ├─ build use cases (PlaceOrder(repo, gateway, clock))
+ ├─ build inbound adapters (HTTPRouter(placeOrderUseCase))
+ └─ start server
+```
+
+For Go: hand-wired or use `google/wire`. For Python: hand-wired or `dependency-injector`. For TypeScript: hand-wired (avoid InversifyJS unless team is large).
+
+## Source Material
+
+The patterns in this skill draw from:
+
+- Alistair Cockburn — original Hexagonal Architecture article (2005)
+- "Cosmic Python" (Percival & Gregory) — for Python idioms
+- Kat Zien — "How Do You Structure Your Go Apps?" (GopherCon talk)
+- Robert C. Martin — "Clean Architecture" (the layered cousin)
+- Vaughn Vernon — "Implementing Domain-Driven Design" (chapter on hexagonal)
+- "Get Your Hands Dirty on Clean Architecture" (Tom Hombergs) — concrete Java patterns
+
+Per-stack adaptation references in this skill point to the current 2026 community guidance for Go modules layout, FastAPI dependency injection, and React Native source organization.

core/skills/hexagonal-architecture/assets/folder-scaffold.md

@@ -0,0 +1,233 @@
+# Folder Scaffold — Copy-Pastable Skeletons
+
+Three minimal scaffolds you can drop into a fresh repo and start writing business logic immediately. Each leaves the framework choices opinionated to match this project's stack.
+
+## Go + Fiber Skeleton
+
+```bash
+mkdir -p backend/{cmd/api,internal/{domain,app/{ports,usecase},adapter/{http,postgres,system,fakes}},pkg/apperr}
+
+# Touch placeholder files so go vet runs cleanly
+cat > backend/go.mod << 'EOF'
+module backend
+
+go 1.23
+EOF
+
+cat > backend/cmd/api/main.go << 'EOF'
+package main
+
+func main() {
+    // TODO: wire outbound adapters, build use cases, mount Fiber app, listen.
+}
+EOF
+
+cat > backend/internal/domain/.keep << 'EOF'
+# Domain layer — pure Go, no framework imports.
+# Each bounded context gets a subfolder.
+EOF
+
+cat > backend/internal/app/ports/.keep << 'EOF'
+# Outbound port interfaces. Owned by the application layer.
+# Adapters under internal/adapter/ implement these.
+EOF
+
+cat > backend/internal/app/usecase/.keep << 'EOF'
+# One file per use case. Each has a single Execute method
+# that takes a typed Input and returns a typed Output.
+EOF
+
+cat > backend/internal/adapter/.keep << 'EOF'
+# Outer ring. http/ for inbound (Fiber), postgres/ stripe/ etc. for outbound.
+EOF
+
+cat > backend/.golangci.yml << 'EOF'
+linters:
+  enable:
+    - depguard
+
+linters-settings:
+  depguard:
+    rules:
+      domain-pure:
+        files: ["**/internal/domain/**"]
+        deny:
+          - pkg: "github.com/gofiber/**"
+            desc: "domain must not import http frameworks"
+          - pkg: "github.com/jackc/pgx/**"
+            desc: "domain must not import database drivers"
+EOF
+```
+
+## Python + FastAPI Skeleton
+
+```bash
+mkdir -p ai-adapter/src/ai_adapter/{domain,application/{ports,usecase},infrastructure/{postgres,llm,system},delivery/{http/routers,cli},fakes}
+mkdir -p ai-adapter/tests/integration
+
+cd ai-adapter
+
+cat > pyproject.toml << 'EOF'
+[project]
+name = "ai-adapter"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+  "fastapi>=0.115",
+  "uvicorn[standard]>=0.30",
+  "asyncpg>=0.30",
+  "pydantic>=2.10",
+  "anthropic>=0.40",  # or openai, swap based on provider
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "import-linter>=2"]
+EOF
+
+cat > .importlinter << 'EOF'
+[importlinter]
+root_packages = [ai_adapter]
+
+[importlinter:contract:1]
+name = "Domain has no infrastructure imports"
+type = forbidden
+source_modules = [ai_adapter.domain]
+forbidden_modules = [
+    ai_adapter.application,
+    ai_adapter.infrastructure,
+    ai_adapter.delivery,
+    fastapi,
+    asyncpg,
+    anthropic,
+]
+
+[importlinter:contract:2]
+name = "Application has no infrastructure or delivery imports"
+type = forbidden
+source_modules = [ai_adapter.application]
+forbidden_modules = [
+    ai_adapter.infrastructure,
+    ai_adapter.delivery,
+    fastapi,
+    asyncpg,
+]
+EOF
+
+# Empty __init__.py everywhere so imports work
+find src -type d -exec touch {}/__init__.py \;
+
+cat > src/ai_adapter/delivery/http/server.py << 'EOF'
+"""FastAPI app factory. Wires use cases via lifespan."""
+from contextlib import asynccontextmanager
+from collections.abc import AsyncIterator
+
+from fastapi import FastAPI
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    # TODO: build outbound adapters, instantiate use cases, attach to app.state
+    yield
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(lifespan=lifespan)
+    # TODO: include_router(...)
+    return app
+EOF
+```
+
+Run `lint-imports` to catch reverse dependencies in CI.
+
+## React Native Skeleton
+
+```bash
+mkdir -p mobile/src/{domain/{primitives,lesson,user},application/{ports,usecase},infrastructure/{http,storage,analytics,system},delivery/{navigation,providers,screens,components},fakes}
+
+cd mobile
+
+cat > tsconfig.json << 'EOF'
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "jsx": "react-native",
+    "baseUrl": "./src",
+    "paths": {
+      "@domain/*":         ["domain/*"],
+      "@application/*":    ["application/*"],
+      "@infrastructure/*": ["infrastructure/*"],
+      "@delivery/*":       ["delivery/*"],
+      "@fakes/*":          ["fakes/*"]
+    }
+  }
+}
+EOF
+
+cat > .eslintrc.cjs << 'EOF'
+// Boundary enforcement — prevent reverse dependencies.
+module.exports = {
+  plugins: ['boundaries'],
+  settings: {
+    'boundaries/elements': [
+      { type: 'domain',         pattern: 'src/domain/*' },
+      { type: 'application',    pattern: 'src/application/*' },
+      { type: 'infrastructure', pattern: 'src/infrastructure/*' },
+      { type: 'delivery',       pattern: 'src/delivery/*' },
+      { type: 'fakes',          pattern: 'src/fakes/*' },
+    ],
+  },
+  rules: {
+    'boundaries/element-types': ['error', {
+      default: 'disallow',
+      rules: [
+        { from: 'domain',         allow: ['domain'] },
+        { from: 'application',    allow: ['domain', 'application'] },
+        { from: 'infrastructure', allow: ['domain', 'application', 'infrastructure'] },
+        { from: 'delivery',       allow: ['domain', 'application', 'delivery'] },
+        { from: 'fakes',          allow: ['domain', 'application', 'fakes'] },
+      ],
+    }],
+  },
+};
+EOF
+
+cat > src/delivery/providers/DependencyProvider.tsx << 'EOF'
+import { createContext, useContext, type PropsWithChildren } from 'react';
+
+export interface UseCases {
+  // TODO: list each use case as a typed property
+}
+
+const Ctx = createContext<UseCases | null>(null);
+
+export function DependencyProvider({
+  value, children,
+}: PropsWithChildren<{ value: UseCases }>) {
+  return <Ctx.Provider value={value}>{children}</Ctx.Provider>;
+}
+
+export function useUseCase<K extends keyof UseCases>(key: K): UseCases[K] {
+  const ctx = useContext(Ctx);
+  if (!ctx) throw new Error('useUseCase must be used inside <DependencyProvider>');
+  return ctx[key];
+}
+EOF
+```
+
+Install `eslint-plugin-boundaries` for the boundary rule above.
+
+## After Scaffolding — First Steps
+
+1. **Pick one use case** that genuinely matters (e.g., `RegisterUser`).
+2. Write the **domain entity first** (with its invariants) and its tests.
+3. Write the **use case** with fake outbound ports + tests.
+4. Write the **real adapters** last (Postgres, HTTP route, etc).
+5. Wire into composition root.
+6. Smoke test end-to-end.
+
+This sequence catches design mistakes at the cheapest moment — domain unit tests fail in milliseconds, integration tests take seconds, e2e takes minutes.

core/skills/hexagonal-architecture/references/anti-patterns.md

@@ -0,0 +1,129 @@
+# Hexagonal Anti-Patterns — Field Guide
+
+Twelve concrete failure modes seen across real codebases. For each: how to spot it, why it bites, the fix.
+
+## 1. Anemic Domain Model
+
+**Symptom**: `domain/` is a folder of dataclasses / structs / interfaces with public fields and zero methods. All the rules live in `OrderService.calculateTotal(...)` in the application layer.
+
+**Why it bites**: the "domain" layer is now just DTOs. Business rules are scattered across services. Two teams write two different `calculateTotal` because there's no obvious place for it.
+
+**Fix**: move behavior onto the entity. `order.addLineItem(item)` enforces the invariant; `OrderService` calls it. The entity is the single guardian of its invariants.
+
+```
+✗ if (order.status === 'paid') throw new Error('cannot edit');
+   order.lineItems.push(item);
+
+✓ order.addLineItem(item);  // raises CannotEditPaidOrder internally
+```
+
+## 2. Framework Types in Ports
+
+**Symptom**: `UserRepository.save(req: HttpRequest)` or `PaymentGateway.charge(ctx: fiber.Ctx, ...)`. Outbound port returns `*sql.Rows` or `dict[str, Any]` to the use case.
+
+**Why it bites**: the adapter is supposed to hide the framework. If the port leaks framework types, swapping the framework requires rewriting every use case.
+
+**Fix**: ports speak in domain types and primitives only. Translation happens **at the adapter boundary**, not in the use case.
+
+## 3. Port-as-DTO Confusion
+
+**Symptom**: `ports/` directory contains both interface files AND DTO files. People start importing the DTO from the port file into screens "for convenience".
+
+**Why it bites**: DTOs are now coupled to ports — changing one requires changing both. Screens import application-layer types they shouldn't see.
+
+**Fix**: Ports = interfaces. DTOs = command/query data classes that travel through the port. Put DTOs next to the use case, not in `ports/`.
+
+## 4. God Use Case
+
+**Symptom**: `OrderService` with 20 public methods: `place`, `cancel`, `refund`, `addNote`, `splitShipment`, `markFraud`, ...
+
+**Why it bites**: changing one rule risks 19 others. Tests are huge and slow. The "use case" is really a service — it has no single user-meaningful operation.
+
+**Fix**: one class per use case. `PlaceOrder`, `CancelOrder`, `RefundOrder`. They can share helpers, but their public surface is one method.
+
+## 5. Premature Port Extraction
+
+**Symptom**: every concrete class wrapped in an interface "for testability". Two-line `EmailFormatter` class with a four-line `IEmailFormatter` interface.
+
+**Why it bites**: pointless indirection. The interface and impl change together. Reading the code requires jumping files.
+
+**Fix**: extract a port when:
+- you need a fake/in-memory implementation for tests, OR
+- you have (or genuinely anticipate) two implementations, OR
+- you're crossing a process/network boundary.
+
+A pure-function helper does not need an interface.
+
+## 6. Reverse Dependency
+
+**Symptom**: a file in `domain/` imports from `application/` or `adapter/`. Or `application/` imports from `adapter/`.
+
+**Why it bites**: the dependency rule (inner layers know nothing of outer) is broken. The domain now depends on infrastructure. Tests for domain start needing a database.
+
+**Fix**: if domain needs something from outside, you're missing a port. Add it to `application/ports/`, inject it where the domain operation runs.
+
+Compiler enforcement: Go's `internal/` privacy + a `depguard` lint rule. Python's `import-linter`. TypeScript's `eslint-plugin-boundaries`.
+
+## 7. Use Case Returns Framework Response
+
+**Symptom**: `placeOrder.execute(...)` returns a `Response` / `JSONResponse` / `*fiber.Ctx` write.
+
+**Why it bites**: the use case can no longer be called from a CLI, queue worker, or test without instantiating an HTTP framework.
+
+**Fix**: use case returns a typed Output dataclass. The HTTP adapter maps Output → JSON response. The CLI adapter maps Output → text. The queue worker maps Output → ack/nack.
+
+## 8. Sprinkling Transactions
+
+**Symptom**: every repository starts/commits its own transaction. Multi-repo operations either don't get atomicity or get it via spaghetti `db.transaction { ... }` blocks in the controller.
+
+**Why it bites**: you cannot reason about atomicity from one place. Adding a new step to a use case can silently break atomicity.
+
+**Fix**: outbound port `UnitOfWork` (or `Transactor`). The use case wraps its multi-step block in `uow.run(() => {...})`. Postgres adapter implements `Run` with `BEGIN/COMMIT`. In-memory test adapter implements with a no-op or a list of pending mutations.
+
+## 9. Adapter Owns the Port Interface
+
+**Symptom**: `postgres/user_repository.go` defines `UserRepository` interface AND its impl. The application layer imports the interface from the adapter package.
+
+**Why it bites**: dependency inversion is broken. The application now depends on the adapter package. Swapping Postgres for MongoDB requires changing the import path in every use case.
+
+**Fix**: ports are owned by **the layer that uses them** (application). Adapters import the port and implement it. This is the "Dependency Inversion Principle" in action.
+
+## 10. ORM Models = Domain Entities
+
+**Symptom**: SQLAlchemy / GORM / Prisma model class is also the "domain entity" — same class, used everywhere.
+
+**Why it bites**: domain entities now carry framework metadata, lazy loading, magic field access. Tests need a database to instantiate one. Refactoring the schema means refactoring the domain.
+
+**Fix**: pay the mapping tax. ORM model lives in the adapter (`postgres/models.py` or `internal/adapter/postgres/models.go`). Repository converts row → domain entity on read, domain entity → row on write. Yes, it's more code. Yes, it's worth it.
+
+## 11. Singleton Use Cases at Module Scope
+
+**Symptom**: `export const placeOrder = new PlaceOrder(repo, gateway, clock);` at top of a module. Or `_instance = SendMessage(...)` at module load.
+
+**Why it bites**: tests cannot swap dependencies. Composition is implicit and scattered. Order-of-import bugs appear at startup.
+
+**Fix**: build everything once in the composition root (`main`, `App.tsx`, `lifespan`). Inject down. No module-scope `new`s.
+
+## 12. "It's Just CRUD, We Don't Need a Use Case"
+
+**Symptom**: HTTP handler calls repository directly. `GET /users/123` returns whatever the repository returns.
+
+**Why it bites**: works fine until "users with subscription" needs an N+1 fix, or "soft-deleted users hidden from regular queries" creeps in. Now the handler has business logic; you can't tell where the rules live.
+
+**Fix**: even for read-only operations, define a Query use case. `GetUserProfile(userId)` is a use case. It happens to call one repository method today. Tomorrow it composes three. Tests stay stable.
+
+This is the **Query** side of CQRS, lite — separate from Command use cases that mutate.
+
+---
+
+## Diagnostic Questions
+
+When reviewing a hexagonal codebase, ask these:
+
+1. Can I run **all use case tests** without Docker, network, or a real database? *(If no → fakes are missing.)*
+2. Can I `grep -r 'fiber\|gorm\|fastapi\|axios' internal/domain/` and get **zero hits**? *(If no → reverse dependency leaked in.)*
+3. Pick a use case at random. Can I describe what it does in one sentence? *(If no → it's a god service, split it.)*
+4. Pick an outbound port at random. Could I implement it in-memory in <50 lines? *(If no → port is too fat or leaks framework types.)*
+5. If I deleted all of `cmd/api/` (Go) or `App.tsx` (RN) or `delivery/http/` (Python), would the rest of the code still compile? *(If yes ✓ — composition is properly isolated. If no → application leaks delivery details.)*
+
+If you can answer "yes" to all five, the architecture is honest. If not, the failing answer points at the work to do.