groundwork-method 0.0.1 → 0.10.0

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

@@ -0,0 +1,42 @@
+# Service Structure: A Pure Core, Swappable Edges
+
+## Dependency Rule
+
+Dependencies flow inward. The core depends on nothing concrete; the edge implementations depend on the core through the interfaces it owns.
+
+## Where code lives
+
+| Zone | Location | Depends on | Contains |
+|---|---|---|---|
+| **Domain** | `internal/core/domain` | Nothing | Entities, value objects, validation, sentinel errors |
+| **Core service** | `internal/core/service` | Domain | Application orchestration **and** the interfaces it consumes (`Repository`, `MessageQueue`, `TextGenerator`) — declared at the point of use, in domain language |
+| **Edge implementations** | technology-named packages — `internal/postgres`, `internal/kafka`, `internal/pubsub`, `internal/httpclient`, `internal/websocket`, `internal/llm` | Domain + `internal/core/service` | Concrete implementations of the core's interfaces (Postgres, Kafka, Pub/Sub, HTTP clients, the LLM client) |
+| **Entrypoints (driving edge)** | `internal/entrypoints` | Domain + Services | HTTP routes, middleware, WebSocket handlers |
+| **Composition root** | `cmd/` | Everything | Wires concrete implementations into services at startup |
+
+The interface and the code that calls it live in the **same** package — Go's "accept interfaces, return structs," applied to the whole service. There is no abstract `adapters` package and no layer named for the pattern; the core is `internal/core/service`, and each implementation sits in a package named for the technology it wraps (`internal/postgres`, `internal/kafka`, …).
+
+## Structural Invariants
+
+- The domain and core service import no framework, no driver, no HTTP library, no SQL client.
+- Interfaces are owned by the core package that consumes them, declared in domain language and named for the role (`Repository`, not `PostgresThing`).
+- Edge implementations are interchangeable — swapping Postgres for another store requires zero core changes. They import `internal/core/service` and assert conformance with `var _ service.Repository = (*Repository)(nil)` (edge → core, the correct inward direction).
+- The application service orchestrates; it does not contain business rules. Rules live on entities.
+- Three conceptual zones: domain; the core service (interfaces + orchestration); edge implementations. More layers are ritual, not rigour.
+
+## Dependency Enforcement
+
+`depguard` is a **shipped gate** in `.golangci.yml.template`: it denies `internal/core/...` importing any edge package (`internal/postgres`, `internal/kafka`, `internal/pubsub`, `internal/httpclient`, `internal/websocket`, `internal/llm`) or any framework/driver, allowing it only stdlib + `internal/core/...`. The edge and the composition root in `cmd/` may import anything. A core-imports-edge violation fails `golangci-lint run`, so the inward-flow rule is a guarantee, not a hope.
+
+## Anti-Patterns
+
+- **Framework-coupled core.** If the core imports `gin.Context` or any HTTP type, it is no longer the core.
+- **Anaemic domain models.** Data structs with no behaviour and a thick service that knows all the rules.
+- **Leaky interfaces.** An interface with `*sql.DB` in its signature is a Postgres type wearing a costume.
+- **Layer-skipping.** Handlers that talk directly to a store because "it is just a simple endpoint."
+- **Per-implementation domain types.** Different entity definitions across packages. Map explicitly at the edge.
+- **Over-layering.** Five layers of DTO translation between HTTP and the core. Edge code is thin.
+
+## Test Seams
+
+A pure core is trivially testable without infrastructure — every outbound dependency is an interface that can be stubbed. Test the edge implementation against the real thing it wraps; test the service against stubs of the interfaces it consumes.

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

@@ -0,0 +1,50 @@
+# Capability Ports & Providers
+
+GroundWork scaffolds external capabilities (LLM inference, and the same pattern for any future capability) as **an interface in the core 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 an interface declared by the core that consumes it, in `internal/core/service` (package `service`) — domain-named (e.g. `TextGenerator`), no SDK type in its signature.
+- A **provider** is the vendor that satisfies the capability; its implementation is the adapter, in a technology-named edge package (e.g. `internal/llm`). Choosing a provider selects the implementation wired in at the edge; the interface 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`, 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 interface — a bet | interface + stub + conformance test, nothing else |
+
+## Generated shape (LLM reference family)
+
+```
+internal/core/service/llm.go      # the interface — declared where it is consumed, domain-owned
+internal/llm/llm.go               # the adapter — one provider's implementation
+internal/llm/llm_test.go          # the contract test
+```
+
+- **Interface** — a plain interface in `package service`, no SDK or HTTP type in its signature. An interface with `*sql.DB` or an `*http.Client` in it is an implementation wearing a costume.
+  ```go
+  // internal/core/service/llm.go
+  package service
+
+  type TextGenerator interface {
+      GenerateText(ctx context.Context, prompt string, maxTokens int) (string, error)
+  }
+  ```
+- **Adapter** — `package llm`, implemented with `net/http` and stdlib, no vendor SDK (so `go.mod` is untouched and the adapter compiles standalone). Reads its config from `os.Getenv`, retries transient 5xx/429/connection failures, maps non-retryable status to a permanent error. It imports `internal/core/service` and asserts conformance at compile time (edge → core, the inward direction):
+  ```go
+  var _ service.TextGenerator = (*Client)(nil)
+  ```
+- **Wiring** — construct `llm.NewClient()` in `cmd/api/main.go` and pass it, typed as the `service.TextGenerator` interface, into your service. Run `go mod tidy` if a provider added a dependency. Never let a service depend on the concrete `*llm.Client`.
+
+## The `none` bare interface (a bet)
+
+`--provider none` ships the interface, a stub adapter that returns a not-implemented error, and a contract test that `Skip`s while the stub errors and flips to a live assertion once `GenerateText` works. Go has no xfail, so the skip *is* the open-bet marker: a green suite with a visible skip means "the contract is fixed, the implementation is owed." Implement the adapter behind the existing interface to cash it — do not touch the interface or the test's conformance line.
+
+## 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 and the footprint. If a change forces the interface or a caller to change, the interface was leaky — fix the interface, not the callers.
+- Surfaces and frontends do **not** embed an adapter; they call this service's interface over its API (keys stay server-side, one owner per capability).
+- A hand-written adapter must pass the same `var _ service.X = (*T)(nil)` conformance assertion and the contract test the generator emits.

package/src/engineer-skills/groundwork-go-engineer/references/code-craft-security.md

@@ -0,0 +1,34 @@
+# Code Craft & Security
+
+## Code Craft Principles
+
+1. **Simpler is better than clever.** Plain data structures over clever abstractions, plain control flow over meta-programming.
+2. **No speculative abstraction.** Three concrete use cases before generalising.
+3. **Deletion is a virtue.** Dead code cannot break, confuse, or leak.
+4. **Names are the interface.** Spend time on names. Rename aggressively.
+5. **Comments explain the "why."** Non-obvious constraints, invariants, ADR references.
+6. **Error handling is design, not decoration.** Decide which errors a function returns, how callers respond, where recoverable/fatal boundary is.
+7. **Trust the boundary; distrust the internal.** Validate at system boundaries. Do not re-validate between internal callers.
+8. **Dead code is a bug.** Commented-out code, `_unused` variables, orphan functions — delete them.
+
+## Security Principles
+
+1. **Zero trust between services.** Every call carries an identity, every identity is authorised per operation.
+2. **Threat model the change.** Five-minute threat conversation for new endpoints, data fields, integrations.
+3. **Secrets are managed, rotated, and audited.** No secrets in source. Fetched at runtime from a secret manager.
+4. **Input is hostile; validate at the boundary.** Request bodies, webhook payloads, message queue events.
+5. **Supply chain is part of the attack surface.** Pin versions, review new dependencies, SBOM generation.
+6. **Least privilege by default.** Minimum permissions, extended only on evidence.
+7. **Auth is boring technology.** Standard auth provider, standard session handling. No custom auth.
+8. **Detect and respond, not just prevent.** Log security events, alert on suspicious patterns, run tabletops.
+
+## Anti-Patterns
+
+### Code Craft
+- Defensive programming without a threat model. "Might need it later" scaffolding.
+- Fashion-driven refactors. Multi-paragraph docstrings. Backwards-compatibility shims for internal APIs.
+
+### Security
+- Internal network = trusted. Secrets in environment variables checked into Git.
+- "It is an internal tool, we can skip auth." Dependencies pulled in on intuition.
+- Exotic auth. "The WAF will catch it."

package/src/engineer-skills/groundwork-go-engineer/references/concurrency.md

@@ -0,0 +1,108 @@
+# Concurrency
+
+## Core Rules
+
+Every goroutine has an owner. `errgroup.WithContext` is the default supervision primitive. Context is passed everywhere. No goroutine runs past the lifetime of the work it was started for.
+
+### Never Use Bare `go func()`
+
+A bare `go func()` that fires and forgets is a goroutine with no owner and no cancellation path. Every `go` statement launches a goroutine that is either:
+
+1. Tracked by an `errgroup.Group` or `sync.WaitGroup` that the caller waits on, or
+2. A long-lived background worker started at program entry and shut down via a dedicated `context.Context` and `sync.WaitGroup` on the composition root.
+
+### `errgroup.WithContext` Is the Default
+
+For fan-out work — fetching multiple resources concurrently, processing items in parallel:
+
+```go
+g, ctx := errgroup.WithContext(ctx)
+
+g.Go(func() error {
+    return fetchResource(ctx, id)
+})
+g.Go(func() error {
+    return fetchMetadata(ctx, id)
+})
+
+if err := g.Wait(); err != nil {
+    return fmt.Errorf("fetching resources: %w", err)
+}
+```
+
+When the first goroutine returns an error, the derived `ctx` is cancelled, signalling the others to stop.
+
+### Context Propagation Is Non-Negotiable
+
+Every function that launches goroutines accepts a `context.Context` and passes it down. Every goroutine checks `ctx.Done()` on any blocking operation:
+
+```go
+select {
+case result := <-ch:
+    process(result)
+case <-ctx.Done():
+    return ctx.Err()
+}
+```
+
+### Limit Concurrency with Semaphores
+
+Unconstrained fan-out exhausts file descriptors and saturates downstream services:
+
+```go
+const maxConcurrency = 10
+sem := make(chan struct{}, maxConcurrency)
+
+g, ctx := errgroup.WithContext(ctx)
+for _, item := range items {
+    sem <- struct{}{}
+    g.Go(func() error {
+        defer func() { <-sem }()
+        return process(ctx, item)
+    })
+}
+if err := g.Wait(); err != nil {
+    return fmt.Errorf("processing items: %w", err)
+}
+```
+
+### Shared State: Channels First, Mutexes Second
+
+Pass ownership via channels rather than sharing pointers through mutexes. Use `sync.Mutex` when a channel would be awkward — e.g., protecting a map read from many goroutines.
+
+Never access shared state without synchronisation. The Go race detector (`-race`) is a required CI gate.
+
+## Graceful Shutdown
+
+Background workers started at program entry respect the root context. The composition root in `cmd/` creates a context cancelled by `SIGTERM`/`SIGINT`:
+
+```go
+func (w *Worker) Run(ctx context.Context) error {
+    for {
+        select {
+        case <-ctx.Done():
+            return nil
+        case job := <-w.queue:
+            if err := w.process(ctx, job); err != nil {
+                // log, metric, continue — or propagate if fatal
+            }
+        }
+    }
+}
+```
+
+The composition root waits on all workers before the process exits. A service that kills itself with `os.Exit` rather than waiting for goroutines to drain drops in-flight requests and corrupts state.
+
+## Anti-Patterns
+
+- **Fire-and-forget goroutines.** If you don't track it, you don't own it.
+- **Sharing context derivations across goroutines.** Each goroutine derives its own from the parent.
+- **Goroutines in `init()` or package-level `var`.** Goroutines belong in functions with explicit lifecycle management.
+- **Infinite retry loops without backoff and cancellation.** A retry loop that ignores `ctx.Done()` spins forever after shutdown.
+- **Mutexes without deferred unlock.** Always `defer mu.Unlock()` immediately after acquiring the lock.
+
+## References
+
+- [sync/errgroup package](https://pkg.go.dev/golang.org/x/sync/errgroup)
+- *The Go Memory Model* (golang.org/ref/mem)
+- *Concurrency in Go*, Katherine Cox-Buday

package/src/engineer-skills/groundwork-go-engineer/references/go-services.md

@@ -0,0 +1,77 @@
+# Go Service Standards
+
+Go code is boring on purpose. It leans into the standard library, uses interfaces only where they earn their keep, treats errors as values with context, and structures every service as a pure core wrapped by swappable edges — the inward-dependency rule written the Go way.
+
+## Principles
+
+### 1. Standard Library First
+
+`net/http`, `context`, `database/sql` — the standard library is the default. Reach for third-party packages only when the standard library demonstrably cannot do the job. Frameworks that "wrap" the standard library to make it "easier" usually make it harder to reason about.
+
+### 2. A Pure Core, Swappable Edges
+
+Every service is a thin HTTP handler at the edge that extracts and validates inputs, an application service that orchestrates, domain types that hold rules, and interfaces (e.g. `Repository`) declared in the core package that consumes them, with technology-named implementations at the edge. Packages are nested under `internal/` — `internal/core/domain` and `internal/core/service` (the latter holds both the orchestration **and** the interfaces it calls), technology-named edge packages (`internal/postgres`, `internal/kafka`, `internal/pubsub`, `internal/httpclient`, `internal/websocket`, `internal/llm`), and `internal/entrypoints/api` (HTTP edge) — with composition roots in `cmd/`. Exported interfaces declared at the point of use, unexported or concrete edge types returned. `depguard` (in `.golangci.yml.template`) fails the build if `internal/core/...` imports an edge package.
+
+### 3. Errors Are Values with Context
+
+Wrap errors with `fmt.Errorf("doing X: %w", err)` when adding context. Inspect with `errors.Is` and `errors.As` at the boundary. Never `panic` in service code; `panic` is reserved for truly unrecoverable conditions and is recovered only at the HTTP boundary.
+
+Sentinel errors are defined where the caller must branch on them. Structured error types are defined where the caller needs detail.
+
+### 4. Context Is Threaded Everywhere
+
+Every function that does I/O takes a `context.Context` as its first parameter. Cancellation and deadlines are respected. A goroutine that outlives its parent context without explicit opt-in is a bug. `context.Background()` appears only at program entry points and in tests.
+
+### 5. Concurrency Is Simple or Explicit
+
+`go` statements that fire-and-forget are banned. Every goroutine is tracked by a `sync.WaitGroup`, an `errgroup.Group`, or a channel that signals completion. Shared state is accessed through channels by default, through mutexes when a channel would be awkward, and never through silence.
+
+### 6. Interfaces Are Defined by Consumers
+
+Define interfaces in the package that consumes them — "accept interfaces, return structs." A package that defines an interface for its own use is leaking internals. Small interfaces (one to three methods) compose well; wide interfaces are a smell.
+
+### 7. Dependency Injection Is Manual and Explicit
+
+No runtime DI frameworks. Dependencies are passed into constructors. Composition happens in a `cmd/` entry point — the "composition root" pattern. Every dependency is visible at build time; cycles are impossible by construction.
+
+### 8. Configuration Validation at Startup
+
+Validate all environment variables immediately at startup using declarative struct tags (e.g., using `kelseyhightower/envconfig`). Do not scatter `os.Getenv` throughout the codebase. If configuration is missing or invalid, the service must crash immediately before accepting traffic.
+
+```go
+type Config struct {
+    DatabaseURL string `envconfig:"DATABASE_URL" required:"true"`
+    Port        int    `envconfig:"PORT" default:"8080"`
+    Environment string `envconfig:"ENVIRONMENT" default:"production"`
+}
+
+func main() {
+    var cfg Config
+    if err := envconfig.Process("myapp", &cfg); err != nil {
+        log.Fatalf("failed to load configuration: %v", err)
+    }
+    // ...
+}
+```
+
+### 9. Tests Use the Real Thing Where Possible
+
+Service tests spin up a real Postgres container via Testcontainers and exercise the handler through HTTP. Mock only the expensive external edges (model clients, third-party APIs).
+
+## Anti-Patterns
+
+- **Framework-flavoured Go.** Heavy router libraries, ORMs that rewrite queries.
+- **`interface{}` or `any` as a type.** Except at reflection boundaries. Name the type.
+- **Package-level mutable state.** Config, loggers, metrics registries in package variables. Inject them.
+- **Goroutines without supervision.** If you launch it, you own its lifetime.
+- **`init()` functions that do work.** `init` is for registering, not for running.
+- **Pointer-to-struct when a value would do.** Pointers imply "this may be nil or may be mutated." If neither is true, pass the value.
+
+## Canonical References
+
+- *The Go Programming Language*, Donovan & Kernighan
+- *100 Go Mistakes and How to Avoid Them*, Teiva Harsanyi
+- *Dave Cheney's blog* (dave.cheney.net)
+- *Effective Go* (go.dev/doc/effective_go)
+- *Uber Go Style Guide* (github.com/uber-go/guide)
+- *The Go Memory Model* (golang.org/ref/mem)

package/src/engineer-skills/groundwork-go-engineer/references/http-handlers.md

@@ -0,0 +1,172 @@
+# HTTP Handlers
+
+## Handler Framework
+
+Handlers use typed function registration (e.g., Huma v2, Chi, or standard library). The Go types are the spec — no separate YAML to drift from production. Request types are validated before the handler runs. Error responses are serialised to RFC 9457 `application/problem+json`.
+
+## Handler Structure
+
+### Registration
+
+Register every handler via a typed registration function. Pass an operation for metadata and a typed function for implementation:
+
+```go
+func RegisterEntity(api huma.API, svc service.EntityService) {
+    huma.Register(api, huma.Operation{
+        OperationID:   "createEntity",
+        Method:        http.MethodPost,
+        Path:          "/entities",
+        Summary:       "Create an Entity",
+        Tags:          []string{"Entities"},
+        DefaultStatus: http.StatusCreated,
+        Security:      []map[string][]string{{"bearerAuth": {}}},
+    }, func(ctx context.Context, req *CreateEntityRequest) (*CreateEntityResponse, error) {
+        // ...
+    })
+}
+```
+
+Each `RegisterXxx` function takes the API and the service interfaces it needs. Called once from the composition root in `internal/entrypoints/api/router.go`.
+
+### Handler Signature
+
+```go
+func(ctx context.Context, req *InputType) (*OutputType, error)
+```
+
+- `ctx` carries request context, auth principal, and cancellation signal.
+- `req` is fully validated before the function is called.
+- Return `(nil, huma.NewError(...))` to abort with a specific HTTP status.
+- Return `(nil, err)` for unexpected errors — framework converts to a 500.
+
+### Request Types
+
+Request structs compose path, query, header, and body fields with struct tags:
+
+```go
+type CreateEntityRequest struct {
+    IdempotencyKey string `header:"Idempotency-Key" required:"false" format:"uuid"`
+    Body           createEntityBody
+}
+
+type createEntityBody struct {
+    Name  string  `json:"name" min:"1" max:"100" example:"example"`
+    Email string  `json:"email" format:"email"`
+    RefID *string `json:"ref_id,omitempty"`
+}
+```
+
+Use a nested body type (unexported) to separate the JSON body from path/query/header fields.
+
+### Response Types
+
+```go
+type CreateEntityResponse struct {
+    Body EntityItem
+}
+
+type EntityItem struct {
+    ID        string `json:"id" format:"uuid" readOnly:"true"`
+    Name      string `json:"name"`
+    CreatedAt string `json:"created_at" format:"date-time" readOnly:"true"`
+}
+```
+
+Use `readOnly:"true"` on fields never accepted on input. Keep response types separate from request body types.
+
+## Authentication
+
+Extract the principal at the top of the handler:
+
+```go
+func(ctx context.Context, req *GetEntityRequest) (*GetEntityResponse, error) {
+    principal, err := auth.PrincipalFromContext(ctx)
+    if err != nil {
+        return nil, huma.NewError(http.StatusUnauthorized, "unauthorized")
+    }
+    // use principal.ID(), principal.IsSystem(), etc.
+}
+```
+
+Pass the principal into service calls — never access auth state from globals.
+
+## Error Handling
+
+Use framework helpers for expected domain errors; return unwrapped errors for unexpected failures:
+
+```go
+// Domain validation error
+if err := entity.Validate(); err != nil {
+    return nil, huma.NewError(http.StatusUnprocessableEntity, err.Error())
+}
+
+// Auth failure
+return nil, huma.NewError(http.StatusForbidden, "insufficient permissions")
+
+// Unexpected error — framework returns 500
+saved, err := svc.Save(ctx, principal, entity)
+if err != nil {
+    return nil, err  // log at the service layer
+}
+```
+
+Do not log errors in the handler and also return them. Log at the layer with enough context; wrap elsewhere.
+
+## Inbound Defenses
+
+### CORS Configuration
+
+Configure CORS explicitly at the router level. Never use wildcard `"*"` origins in production.
+
+```go
+import "github.com/go-chi/cors"
+
+router.Use(cors.Handler(cors.Options{
+    AllowedOrigins:   []string{"https://app.example.com"}, // Loaded from config
+    AllowedMethods:   []string{"GET", "POST", "PATCH", "DELETE", "OPTIONS"},
+    AllowedHeaders:   []string{"Accept", "Authorization", "Content-Type", "Idempotency-Key"},
+    AllowCredentials: true,
+}))
+```
+
+### Idempotency Middleware
+
+Mutating endpoints (`POST`, `PATCH`) must be idempotent. Extract the `Idempotency-Key` header and verify its state before allowing the handler to execute.
+
+```go
+func IdempotencyMiddleware(store IdempotencyStore) func(http.Handler) http.Handler {
+    return func(next http.Handler) http.Handler {
+        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+            key := r.Header.Get("Idempotency-Key")
+            if key == "" && (r.Method == "POST" || r.Method == "PATCH") {
+                http.Error(w, "Idempotency-Key required", http.StatusBadRequest)
+                return
+            }
+            
+            // Check store and return cached response if COMPLETED,
+            // or 409 Conflict if IN_PROGRESS.
+            // Otherwise, proceed.
+            next.ServeHTTP(w, r)
+        })
+    }
+}
+```
+
+## Handler Placement
+
+- One `RegisterXxx` function per domain resource in `internal/entrypoints/api/routes/<resource>.go`
+- Request/response types in the same file as the handler
+- Domain conversion helpers (`toXxx`) at the bottom of the file, unexported
+- Inline closures for simple handlers; named methods on a struct for handlers that share helpers
+- When a handler needs more than two service calls or substantial conditional logic, move logic to the application service layer
+
+## Operation Metadata
+
+Every operation needs:
+
+- `OperationID` — unique, camelCase, used as the generated client method name
+- `Method` + `Path` — HTTP verb and URI template; use `{id}` placeholders
+- `Summary` — one sentence, title-cased, no period
+- `Tags` — group the endpoint in the OpenAPI UI
+- `Security` — authentication scheme for the endpoint
+- `DefaultStatus` — only for non-200 success codes (201 for creation, 204 for deletions)

package/src/engineer-skills/groundwork-go-engineer/references/implementation-patterns.md

@@ -0,0 +1,156 @@
+# Implementation Patterns
+
+Concrete Go patterns for trace-first logging, a pure core with swappable edges, error handling, and dependency injection.
+
+## 1. Trace-First Development
+
+Every inbound request starts a trace. Every outbound request cascades it.
+
+### Initializing a Span
+
+```go
+import "go.opentelemetry.io/otel/trace"
+
+func (s *OrderService) Process(ctx context.Context, orderID string) error {
+	ctx, span := s.tracer.Start(ctx, "OrderService.Process")
+	defer span.End()
+
+	span.SetAttributes(attribute.String("order.id", orderID))
+	// ... logic
+}
+```
+
+### Passing Context
+
+Context is King. Do not store context in structs. Pass it as the first parameter to every domain, service, and edge-implementation function. Dropping the context severs the distributed trace.
+
+## 2. Error Handling
+
+Use Go's `errors.Is` with sentinel errors to prevent database or HTTP leakage into domain logic.
+
+### Defining Sentinels
+
+Define business rule errors in `internal/core/domain/errors.go`:
+
+```go
+package domain
+
+import "errors"
+
+var ErrNotFound    = errors.New("not found")
+var ErrUnauthorized = errors.New("unauthorized access")
+```
+
+### Wrapping & Mapping Errors at the Edge
+
+An edge implementation catching an infrastructure error wraps it into a Domain error before returning:
+
+```go
+// internal/postgres
+func (r *Repository) Get(ctx context.Context, id string) (*domain.Entity, error) {
+	var entity domain.Entity
+	err := r.db.QueryRowContext(ctx, "SELECT ...").Scan(...)
+
+	if err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			return nil, fmt.Errorf("lookup failed: %w", domain.ErrNotFound)
+		}
+		// %v, not %w: unexpected driver errors stay opaque at the storage
+		// boundary so callers cannot couple to infrastructure internals.
+		return nil, fmt.Errorf("unexpected db error: %v", err)
+	}
+	return &entity, nil
+}
+```
+
+## 3. Dependency Injection
+
+### The Interface (Declared by the Core)
+
+The interface belongs in `internal/core/service` (package `service`), declared at the point of use and speaking Domain language:
+
+```go
+package service
+
+import "myservice/internal/core/domain"
+
+type EntityStore interface {
+	Get(ctx context.Context, id string) (*domain.Entity, error)
+}
+```
+
+### The Wiring (Composition Root)
+
+Constructor injection assembles pieces at startup without globals:
+
+```go
+// 1. Initialize the concrete edge implementation
+store := postgres.NewRepository(sqlDB)
+
+// 2. Inject into the Service (which only knows the service.EntityStore interface)
+entityService := service.NewEntityService(store)
+
+// 3. Inject the Service into the inbound HTTP route
+entrypoints.RegisterEntityRoutes(router, entityService)
+```
+
+## 4. Accept Interfaces, Return Structs
+
+This idiom is how the inward-dependency rule is written in Go. The core service declares the interface; it accepts that interface; the edge implementation returns a concrete struct that satisfies it.
+
+```go
+// 1. The interface lives in the core, with the code that calls it
+package service
+
+type Store interface {
+	Get(ctx context.Context, id string) (*domain.Entity, error)
+}
+
+// 2. The Service accepts the interface
+func NewService(store Store) *Service {
+	return &Service{store: store}
+}
+
+// 3. The edge implementation returns the concrete struct
+package postgres
+
+type Repository struct { /* ... */ }
+
+func NewRepository(db *sql.DB) *Repository {
+	return &Repository{db: db}
+}
+```
+
+## 5. Goroutines and Context Loss
+
+When spawning background tasks, use `context.WithoutCancel` (Go 1.21+) or extract/inject the trace so the background span remains a child of the request trace — even if the HTTP client disconnects early.
+
+```go
+func (s *Service) ProcessAsync(ctx context.Context) {
+	bgCtx := context.WithoutCancel(ctx)
+
+	go func() {
+		_, span := s.tracer.Start(bgCtx, "ProcessAsync.Background")
+		defer span.End()
+		// Execute asynchronous domain work...
+	}()
+}
+```
+
+## 6. Immutability in the Domain
+
+When creating methods on Domain entities that calculate or evaluate state rather than modifying it, enforce immutability by exclusively using value receivers:
+
+```go
+package domain
+
+type Order struct {
+	DurationSeconds int
+	Status          string
+}
+
+// CalculateCost uses a value receiver — cannot mutate the Order.
+func (o Order) CalculateCost(rate float64) float64 {
+	return float64(o.DurationSeconds) * rate
+}
+```