bmad-method-quarkus 1.0.2 → 1.0.4

package/src/bmm-skills/agents/bmad-quarkus-build/skills/quarkus-hexagonal-core/SKILL.md

@@ -1,21 +1,38 @@
 ---
 name: quarkus-hexagonal-core
-description: Foundation for building Java + Quarkus backend services compiled to native binaries (GraalVM/Mandrel) with strict hexagonal architecture (ports & adapters). Applies to ANY Java/Quarkus backend project — DDD bounded contexts, standalone services, internal tools alike. Use this skill whenever creating, scaffolding, reviewing, or modifying ANY Quarkus backend service, module, REST/gRPC/Kafka adapter, repository, use case, or domain entity — even if the user only says "create a service", "add an endpoint", "new microservice", or "backend project". Also the canonical source for CLASS NAMING CONVENTIONS across all layers (entities, use cases, ports, adapters, DTOs, mappers, exceptions, tests), the domain-monorepo layout (apps/, libs/, contracts/, deploy/, db/, docs/), deployable app naming ({module}-{service}-ms, tenant-agnostic), and the mandatory per-app service.yaml + README.md documentation standard — consult it whenever naming/renaming any Java class, scaffolding an app folder, or writing service docs. Enforces Java 25, JDBC-only persistence via Agroal (NO Panache, NO Hibernate/ORM), ArchUnit boundary + naming tests, and native-image compatibility. Project-specific directives (CLAUDE.md, ADRs, explicit instructions) override this standard where they conflict.
+description: Foundation for building Java + Quarkus backend services compiled to native binaries (GraalVM/Mandrel) with VERTICAL SLICE architecture over a hexagonal core (ports & adapters collapsed into one folder per feature). Applies to ANY Java/Quarkus backend project — DDD bounded contexts, standalone services, internal tools alike. Use this skill whenever creating, scaffolding, reviewing, or modifying ANY Quarkus backend service, slice, feature, REST/gRPC/Kafka adapter, Sql data class, Handler, or DTO — even if the user only says "create a service", "add an endpoint", "new microservice", or "backend project". Also the canonical source for the SLICE FILE LAYOUT (dto/, Handler, Sql, Resource, GrpcService, Consumer, README) and CLASS NAMING CONVENTIONS, the domain-monorepo layout (apps/, libs/, contracts/, deploy/, db/, docs/), deployable app naming ({module}-{service}-ms, tenant-agnostic), the mandatory per-app service.yaml + README.md standard, and the Handler contract (@Transactional only on process(), never setAutoCommit/commit/rollback, one Connection per business operation). Enforces Java 25, JDBC-only persistence via Agroal (NO Panache, NO Hibernate/ORM), ArchUnit slice-isolation + naming tests, and native-image compatibility. Project-specific directives (CLAUDE.md, ADRs, explicit instructions) override this standard where they conflict.
 ---
 
-# Quarkus Hexagonal Core (Native-First)
+# Quarkus Vertical Slice + Hexagonal Core (Native-First)
 
-Foundation skill for all backend services. Other skills in this set (error-handling-i18n, kafka-messaging, openapi-tmforum, grpc-services, observability-otel) build on the structure defined here — apply this one first when scaffolding.
+Foundation skill for all backend services. The other skills in this set (sql-jdbc-agroal, error-handling-i18n, openapi-tmforum, grpc-services, kafka-messaging, observability-otel) build on the structure defined here and use the vocabulary defined here — apply this one first when scaffolding.
 
-**Scope & precedence:** these standards apply to any Java/Quarkus backend project, whether or not it is organized as DDD bounded contexts — where examples mention a BC code (`bc05`), read it as "short module/domain prefix". They are the default, not law: a project directive that says otherwise (CLAUDE.md, an ADR, an explicit user instruction) wins over this skill. When you deviate because of such a directive, follow the directive and mention which rule was overridden.
+**Scope & precedence:** these standards apply to any Java/Quarkus backend project, whether or not it is organized as DDD bounded contexts. **Module naming:** every module/bounded context is identified in code by a short, lowercase, semantic name (`iam`, `tenant`, `wallet`, `customer`) — never by an inventory/governance code like `bc01`/`bc02`. If the organization keeps a numbered BC inventory, the `bcNN` ↔ name mapping lives in governance docs (domain README identity table, service catalog); packages, topics, config keys, URLs, metrics and proto packages only ever carry the semantic name. They are the default, not law: a project directive that says otherwise (CLAUDE.md, an ADR, an explicit user instruction) wins over this skill. When you deviate because of such a directive, follow the directive and mention which rule was overridden.
+
+## The central idea: one feature = one folder
+
+Classic layered hexagonal architecture spreads a single feature across eight or more files (inbound port, use case, command, result, outbound port, JDBC adapter, DTO, mapper) in four packages. This standard keeps the **hexagon's dependency rule** but collapses it into a **vertical slice**: everything one business capability needs lives in one folder, and the hexagon is expressed by *class role*, not by package depth.
+
+| Hexagon role | Slice file | Rule |
+|---|---|---|
+| Driving (inbound) adapters | `<Slice>Resource` (REST), `<ProtoService>GrpcService`, `<Event>Consumer` (Kafka) | transport in/out only — no business logic, no SQL, no `Connection` |
+| Application core | `<Slice>Handler` | 100% of the business logic + the transaction boundary. Knows no transport type |
+| Driven (outbound) adapter | `<Slice>Sql` | plain JDBC only. No transaction control, no business rules |
+| Driven (outbound) integrations | capability-named beans in `common/client` | own all Mutiny/`await`; expose plain types to Handlers |
+| Data contracts | `dto/*Dto`, `dto/*Payload` | shape + form validation only |
+
+Dependency rule (unchanged from hexagonal): **transport → Handler → Sql / integration bean**. Never the reverse, never transport → Sql, never Handler → transport type (`RestResponse`, proto message, Kafka `Message`, `Uni`).
+
+The trade the slice makes explicit: **fewer classes, stricter roles.** There are no `*UseCase` interfaces, no `*Command`/`*Result` wrappers, no `*Mapper` classes and no `*Repository` ports. A port with exactly one implementation is a file that only costs compilation time — the `Handler`/`Sql` split already gives you the seam, and `@Mock <Slice>Sql` gives you the test double. Introduce an interface only when a **second** real implementation exists (see "When to add an interface back").
 
 ## Baseline constraints (unless a project directive overrides)
 
 1. **Java 25 LTS** (`maven.compiler.release=25`). Records, sealed interfaces, pattern matching, virtual threads where blocking I/O is unavoidable.
 2. **Native binary is the delivery artifact.** Every dependency and pattern must be GraalVM/Mandrel-compatible. Build with the Mandrel container image so builds don't depend on a local GraalVM.
-3. **No ORM.** Persistence is plain JDBC through the Agroal datasource. No Panache, no Hibernate, no JPA annotations in any layer.
-4. **Domain layer has zero framework imports.** No `jakarta.*`, no `io.quarkus.*`, no Jackson annotations in `domain`. Enforced by ArchUnit.
-5. **Swagger UI only in dev/test** (see quarkus-openapi-tmforum skill).
+3. **No ORM.** Persistence is plain JDBC through the Agroal pool. No Panache, no Hibernate, no JPA annotations anywhere.
+4. **Blocking stack, two reactive exceptions.** `Uni`, `Multi`, `PgPool`, `SqlConnection` are banned in `Handler`, `Sql`, `Resource` and `Consumer`. Mutiny is confined to (a) `*GrpcService` server adapters, where the generated interface demands it, and (b) integration beans in `common/client`, which `await()` internally and hand back plain types.
+5. **Slices are independent.** A slice never imports another slice's `Handler`, `Sql` or `dto`. Shared code goes to `common/` or `libs/` (see "Shared code").
+6. **Swagger UI only in dev/test** (see quarkus-openapi-tmforum skill).
 
 ## Monorepo layout (per domain/module)
 
@@ -33,7 +50,7 @@ One monorepo per domain (bounded context in DDD projects) holds its deployable a
 ├── libs/                            # modules shared within the domain
 ├── contracts/                       # versioned API contracts (TMF/OpenAPI, JSON Schemas, protos)
 ├── deploy/                          # k8s manifests, pipelines, observability-as-code
-├── db/                              # database migrations
+├── db/                              # database migrations (versioned always; applied at boot only where the Flyway flag is on)
 ├── docs/                            # architecture, ADRs, runbooks
 └── README.md                        # domain onboarding doc (see "Domain README")
 ```
@@ -46,136 +63,368 @@ One monorepo per domain (bounded context in DDD projects) holds its deployable a
 
 Suffixes: `-ms` (backend microservice — every Quarkus service here), `-mf` (microfrontend remote), `-module` (host/shell). Example: `wallet-backend-core-ms`. **Client and tenant never appear in app or code names** — they are runtime configuration (namespaces, labels, Helm values) applied at deploy time; the code is identical for every client and tenant.
 
-## Package layout (per service/module)
+## Slice layout (the canonical structure)
+
+An app is a flat list of slices under the base package, plus one `common/`. There are no `domain/`, `application/`, `infrastructure/` packages.
 
 ```
-com.<company>.<module>          # <module> = BC code in DDD projects, service name otherwise
-├── domain/                  # PURE Java. Entities, value objects, domain events, domain services
-│   ├── model/               #   Records for VOs, sealed interfaces for events
-│   ├── event/
-│   └── exception/           #   Domain exceptions with stable error codes
-├── application/             # Use cases + ports. May use CDI annotations only (@ApplicationScoped)
-│   ├── port/
-│   │   ├── in/              #   Inbound ports (use case interfaces)
-│   │   └── out/             #   Outbound ports (repository, publisher, external service interfaces)
-│   └── usecase/             #   One class per use case, implements inbound port
-└── infrastructure/          # Adapters. All framework code lives here
-    ├── rest/                #   JAX-RS resources + DTOs + mappers (inbound adapter)
-    ├── grpc/                #   gRPC services (inbound) and clients (outbound)
-    ├── persistence/         #   JDBC repositories implementing out ports
-    ├── messaging/           #   Kafka producers/consumers, outbox
-    └── config/              #   @ConfigMapping interfaces, CDI producers
+src/main/java/com/<company>/<module>/
+├── common/                                       # cross-slice code ONLY (see "Shared code")
+│   ├── exception/BusinessException.java           #   single code-carrying business exception
+│   ├── exception/PersistenceException.java        #   technical exception family
+│   ├── error/GlobalExceptionHandler.java          #   the one REST ExceptionMapper
+│   ├── error/GrpcExceptionInterceptor.java
+│   ├── error/ErrorCatalog.java                    #   code -> HTTP status + reason
+│   ├── error/ErrorDto.java                        #   TMF630 Error wire shape
+│   ├── error/SqlStateTranslator.java              #   SQLState -> error code
+│   ├── i18n/MessageResolver.java                  #   Accept-Language -> localized message
+│   ├── client/CredentialsValidator.java           #   outbound gRPC/REST integrations
+│   ├── messaging/OutboxRelayJob.java           # + OutboxDispatcher, OutboxConfig, OutboxSql
+│   ├── audit/AuditRecorder.java
+│   └── util/StringUtils.java
+└── create_party_individual/                      ← THE SLICE (snake_case folder)
+    ├── dto/
+    │   ├── CreatePartyIndividualRequestDto.java
+    │   ├── CreatePartyIndividualResponseDto.java
+    │   └── ContactMediumDto.java
+    ├── CreatePartyIndividualResource.java        # REST endpoint       → invokes the Handler
+    │                                              #   (or PartyIndividualResource shared by sibling slices — see below)
+    ├── PartyGrpcService.java                     # gRPC endpoint       → invokes the Handler  (conditional)
+    ├── PartyCreatedConsumer.java                 # Kafka consumer      → invokes the Handler  (conditional)
+    ├── CreatePartyIndividualHandler.java         # business logic + transaction boundary
+    ├── CreatePartyIndividualSql.java             # SQL constants + JDBC access methods
+    └── README.md                                 # slice documentation
+
+src/main/proto/customer/v1/
+└── party.proto                                   # published to contracts/ (see grpc skill)
+
+src/main/resources/messages/
+├── errors.properties                             # default locale (en), keyed by error code
+├── errors_es.properties
+└── errors_pt.properties
+
+src/test/java/com/<company>/<module>/create_party_individual/
+└── CreatePartyIndividualHandlerTest.java         # mirrors the slice
 ```
 
-Rules of dependency: `infrastructure → application → domain`. Never the reverse. DTOs never leak into application/domain; map at the adapter boundary.
+Minimum viable slice = **4 files**: a DTO pair in `dto/`, `Handler`, `Sql`, one transport class. gRPC and Kafka classes are generated only when the slice plan marks `needs_grpc` / `needs_kafka`. A slice that only reads still has a `Handler` — it is the single entry point, even when `validate()` is a no-op.
 
-## Class naming conventions (canonical)
+### Slice naming variables
 
-These names are the standard for ALL services and all sibling skills. A class name must reveal its layer and role without opening the file. Identifiers, packages, SQL objects and comments are **English only** — Spanish appears only in i18n message bundles and user-facing text (see quarkus-error-handling-i18n skill).
+Every generator and every review uses these three names consistently:
 
-### Domain layer (`domain`)
-
-| Artifact | Convention | Example |
+| Variable | Meaning | Example |
 |---|---|---|
-| Entity / aggregate root | singular noun, no suffix | `User`, `Subscription` |
-| Value object | singular noun record, no suffix | `Email`, `Money`, `Msisdn` |
-| Typed identifier | `<Entity>Id` record | `UserId`, `SubscriptionId` |
-| State enum | `<Entity>Status` | `UserStatus` |
-| Domain event | past-tense verb phrase, **no** suffix | `UserRegistered`, `SubscriptionActivated` |
-| Domain service / policy | `<Concept>Policy`, `<Concept>Calculator` | `PasswordPolicy`, `PricingCalculator` |
-| Domain exception | `<Thing><Problem>Exception` | `UserNotFoundException`, `DuplicateEmailException` |
-| Exception base | `DomainException` | |
+| `SLICE_FOLDER` | folder name, `snake_case`, verb-first | `create_party_individual` |
+| `SLICE_PACKAGE` | `<PACKAGE_BASE>.<SLICE_FOLDER>` | `com.alva.customer.create_party_individual` |
+| `SERVICE_CLASS_PREFIX` | `PascalCase` of the slice; prefix of `Handler`, `Sql`, `Resource`, DTOs | `CreatePartyIndividual` |
 
-`*Service` is **never** used in the domain layer — a domain service is a policy, a calculator or a factory, and saying so beats a generic suffix.
+Slice names are **verb + resource** (`create_party_individual`, `find_party_by_id`, `update_party_status`) — they name a capability, not an entity. A slice that would need a name like `party_management` is really several slices.
 
-### Application layer (`application`)
+## Class naming conventions (canonical)
+
+Identifiers, packages, SQL objects and comments are **English only** — localized text lives exclusively in message bundles (see quarkus-error-handling-i18n skill).
 
 | Artifact | Convention | Example |
 |---|---|---|
-| Inbound port (`port/in`) | `<Verb><Entity>UseCase` — always an interface | `RegisterUserUseCase`, `GetUserUseCase` |
-| Use case implementation (`usecase`) | `<Verb><Entity>Service` | `RegisterUserService` |
-| Command (write input) | `<Verb><Entity>Command` | `RegisterUserCommand` |
-| Query (read input) | `<Verb><Entity>Query` | `FindUsersQuery` |
-| Use case output | `<Verb><Entity>Result` | `RegisterUserResult` |
-| Outbound port — persistence | `<Entity>Repository` | `UserRepository` |
-| Outbound port — other capability | capability noun, **no technology** | `EventPublisher`, `CredentialsValidator`, `AuditRecorder` |
+| Business logic core | `${SERVICE_CLASS_PREFIX}Handler` | `CreatePartyIndividualHandler` |
+| Data access | `${SERVICE_CLASS_PREFIX}Sql` | `CreatePartyIndividualSql` |
+| REST adapter | `<Resource>Resource` — the TMF resource name, per openapi skill | `PartyIndividualResource` |
+| gRPC adapter | `<ProtoService>GrpcService` — mirrors the proto service | `PartyGrpcService` |
+| Kafka consumer | `<Event>Consumer` | `PartyCreatedConsumer` |
+| Scheduled entry point | `<Task>Job` | `OutboxRelayJob` |
+| Request DTO | `${SERVICE_CLASS_PREFIX}RequestDto` | `CreatePartyIndividualRequestDto` |
+| Response DTO | `${SERVICE_CLASS_PREFIX}ResponseDto` | `CreatePartyIndividualResponseDto` |
+| TMF create/update DTO | `<Resource>CreateDto` / `<Resource>UpdateDto` when implementing a TMF `X_Create`/`X_Update` | `PartyIndividualCreateDto` |
+| Filter/criteria DTO | `Filter<Resource>Dto` | `FilterPartyDto` |
+| Nested/shared-shape DTO | `<Resource>Dto` | `PartyDto`, `ContactMediumDto` |
+| Kafka payload DTO | `<Event>Payload` | `PartyCreatedPayload` |
+| Outbound integration bean | capability noun, **no technology** | `CredentialsValidator`, `AuditRecorder` |
+| Config mapping | `<Area>Config` (`@ConfigMapping` interface) | `OutboxConfig` |
+| Business exception | `BusinessException` (single, code-carrying, in `common/exception`) | — |
+| Technical exceptions | `PersistenceException`, `TransientPersistenceException`, `PersistenceTimeoutException` | — |
+| Concurrency-conflict exception | `StaleVersionException` (standalone, code-carrying, in `common/exception` — → 409 / `ABORTED` via its own mappers) | — |
+| Global handlers | `GlobalExceptionHandler`, `GrpcExceptionInterceptor` | — |
+| Test class | `<Class>Test` (unit), `<Class>IT` (`@QuarkusIntegrationTest`), `ArchitectureTest` | `CreatePartyIndividualHandlerTest` |
 
-One use case per class, one public method named after the verb (`register`, `getById`). The `*Service` suffix is **reserved** for use-case implementations in `application/usecase` (plus proto-generated gRPC stubs); it never appears on repositories, mappers or helper classes.
+`Handler` and `Sql` carry **no** transport or technology prefix — the slice folder already says which feature they belong to, and there is exactly one of each per slice. The three inbound adapters keep their **transport-idiomatic** names (`Resource`, `GrpcService`, `Consumer`) because those names are contracts with JAX-RS, protobuf and the topic catalog respectively, not ours to rename.
 
-### Infrastructure layer (`infrastructure`)
+### Two slices, one TMF resource path
 
-**Inbound (driving) adapters — suffixed by transport:**
+Several slices may expose operations under the same TMF base path (`create_party_individual` → `POST`, `find_party_by_id` → `GET /{id}`). Two options, pick one per app and stay consistent:
 
-| Adapter | Convention | Example |
-|---|---|---|
-| REST resource | `<Resource>Resource` | `UserResource`, `DigitalIdentityResource` |
-| gRPC endpoint | `<ProtoService>GrpcService` | `UserGrpcService` |
-| Kafka consumer | `<Event>Consumer` | `UserRegisteredConsumer` |
-| Scheduled job | `<Task>Job` | `OutboxRelayJob` |
+- **One `Resource` class per TMF resource** (default, safest): the class lives in the slice folder of its *primary* capability and injects the `Handler` of each slice it fronts. Keeps JAX-RS path resolution unambiguous and produces one clean OpenAPI tag.
+- **One `Resource` class per slice** sharing a base `@Path`: legal in Quarkus REST as long as no two classes declare the same method + sub-path combination, but the spec does not guarantee it across implementations. If you choose this, the `/q/openapi` snapshot test (openapi skill) is what protects you — it fails loudly on a collision.
 
-**Outbound (driven) adapters — prefixed by technology, keeping the port name:**
+### Banned and reserved names
+
+- Suffixes `*Impl`, `*Util`, `*Utils`, `*Helper`, `*Manager`, `*Repository`, `*UseCase`, `*Mapper`, `*Dao`. If a class needs `Util`, it needs a real responsibility name; the sanctioned exceptions are `common/util/StringUtils` and the `Jdbc` namespace helper from the sql skill.
+- `*Service` **except** `*GrpcService` and proto-generated stubs. A class named `PartyService` is business logic that belongs in a `Handler`.
+- `*DTO` / `*VO` / `*Bean` / `*POJO` in all-caps or as decoration — the standard is `*Dto`.
+- Names that shadow JDK or Jakarta types: never declare `Response`, `Entity`, `Optional`, `Record`, or `ConcurrentModificationException` (use `StaleVersionException`). An accidental import silently changes behaviour.
+- Exceptions named after HTTP statuses (`NotFoundException`, `BadRequestException`) — status comes from `ErrorCatalog`, not from the class name.
+- Nested `record` / `static class` redeclaring a DTO that already exists in `dto/` — always import the real class.
+- Abbreviations that are not org-wide vocabulary (`UsrRepo`, `SubsSvc`). Semantic module names (`iam`, `tenant`) are fine in packages and config, not in class names; inventory codes (`bc05`) appear nowhere in code.
+
+### Other identifiers (for reference)
 
-| Adapter | Convention | Example |
+| Kind | Convention | Example |
 |---|---|---|
-| JDBC repository | `Jdbc<Port>` | `JdbcUserRepository` |
-| Outbox / Kafka publisher | `Outbox<Port>`, `Kafka<Port>` | `OutboxEventPublisher` |
-| gRPC client adapter | `Grpc<Port>` | `GrpcCredentialsValidator` |
-| REST client adapter | `Rest<Port>` | `RestPaymentGateway` |
+| Deployable app | `{module}-{service}-{type}` kebab-case, tenant-agnostic (`-ms` backend) | `wallet-backend-core-ms` |
+| Slice package | lowercase `snake_case`, verb-first | `com.alva.customer.create_party_individual` |
+| SQL constant | `UPPER_SNAKE_CASE` matching the method | `INSERT_PARTY`, `SELECT_PARTY_BY_ID` |
+| SQL table / column | `snake_case`, singular table, schema-qualified | `customer.party`, `created_at` |
+| Proto | `PascalCase` messages/services, `snake_case` fields, package `vN` | `GetPartyRequest`, `party_id` |
+| Kafka topic / channel | see quarkus-kafka-messaging skill | `alva.customer.party.created.v1` |
+| Error code (= bundle key) | `<MOD>-<HTTP>-<seq>` (`<MOD>` = uppercase code derived from the semantic module name or its main entity, never `bcNN`) | `PTY-400-001` |
+| Span name | `usecase.<sliceCamelCase>` | `usecase.createPartyIndividual` |
 
-The port says *what*, the prefix says *with what* — so a second implementation (`InMemoryUserRepository` in tests) reads naturally.
+## The Handler — logic and transaction contract
 
-**Supporting classes:**
+`${SERVICE_CLASS_PREFIX}Handler` centralizes **100%** of the slice's business logic. This section is the contract every Handler must satisfy; generators and reviewers check it line by line.
 
-| Artifact | Convention | Example |
-|---|---|---|
-| REST DTO | `<Resource>Dto`, `<Resource>CreateDto`, `<Resource>UpdateDto` | `DigitalIdentityCreateDto` |
-| Kafka payload DTO | `<Event>Payload` | `UserRegisteredPayload` |
-| Mapper | `<Entity><Transport>Mapper` | `UserRestMapper`, `UserGrpcMapper`, `UserEventMapper` |
-| Row mapper | `<Entity>RowMapper` | `UserRowMapper` |
-| Config mapping | `<Area>Config` (`@ConfigMapping` interface) | `OutboxConfig` |
-| Global handlers | `GlobalExceptionHandler`, `GrpcExceptionInterceptor` | |
-| Technical exceptions | `PersistenceException`, `TransientPersistenceException`, `PersistenceTimeoutException`, `StaleVersionException` | |
+### Mandatory method order
 
-The DTO ↔ domain distinction matters: `UserDto` lives in `infrastructure/rest/dto` and is what the wire sees; `User` is the domain entity. They are never the same class, even when the fields match today.
+```
+1.  package
+2.  imports
+3.  @ApplicationScoped
+4.  @Inject DataSource dataSource;
+5.  @Inject ${SERVICE_CLASS_PREFIX}Sql sql;
+6.  (optional) @Inject <integration beans from common/client, OutboxDispatcher from common/messaging>
+7.  private void   validate(RequestDto request)
+8.  private <T>    execution(RequestDto request)      // T = internal result (UUID, DTO, List<Dto>…)
+9.  private ResponseDto getResult(<T> internalResult)
+10. @Transactional public ResponseDto process(RequestDto request)
+```
 
-### Banned and reserved names
+Field `@Inject` is the standard **inside a slice** — it keeps the four-file slice readable and matches the generator templates. (Constructor injection remains the rule for `common/` and `libs/` beans, which are unit-tested outside CDI.)
 
-- Suffixes `*Impl`, `*Util`, `*Utils`, `*Helper`, `*Manager`, `*Handler` (the single `GlobalExceptionHandler` is the only sanctioned `*Handler`). If a class needs `Util`, it needs a real responsibility name.
-- `*DTO` / `*VO` / `*Bean` / `*POJO` in all-caps or as decoration — the standard is `*Dto`.
-- Names that shadow JDK or Jakarta types: never `ConcurrentModificationException` (use `StaleVersionException`), `Entity`, `Optional`, `Record`. An accidental `java.util` import silently changes behaviour.
-- Abbreviations that are not org-wide vocabulary (`UsrRepo`, `SubsSvc`). Module/BC codes (`bc05`) are fine in packages and config, not in class names.
+### `validate()` — input validation
 
-### Other identifiers (for reference)
+Bean Validation on the DTO (`@NotBlank`, `@Size`, `@Pattern`) covers *form*. `validate()` covers *business rules*: mandatory-if, cross-field consistency, allowed state transitions, tenant coherence. It throws `BusinessException` and never returns a boolean or an error list.
 
-| Kind | Convention | Example |
-|---|---|---|
-| Deployable app | `{module}-{service}-{type}` kebab-case, tenant-agnostic (`-ms` backend) | `wallet-backend-core-ms` |
-| Package | lowercase, singular, no underscores | `com.alva.bc05.application.usecase` |
-| Constant | `UPPER_SNAKE_CASE` | `FIND_BY_ID` |
-| SQL table / column | `snake_case`, singular table | `app_user`, `created_at` |
-| Test class | `<Class>Test` (unit/`@QuarkusTest`), `<Class>IT` (`@QuarkusIntegrationTest`), `ArchitectureTest` | `JdbcUserRepositoryTest` |
-| Proto | `PascalCase` messages/services, `snake_case` fields | `GetUserRequest`, `user_id` |
-| Kafka topic / channel | see quarkus-kafka-messaging skill | `alva.bc05.user.registered.v1` |
-| Error code | `<MOD>-<HTTP>-<seq>` (`<MOD>` = short module/domain code) | `USR-404-001` |
+```java
+private void validate(CreatePartyIndividualRequestDto request) {
+    if (StringUtils.isBlank(request.getGivenName())) {
+        throw new BusinessException("PTY-400-001", "givenName");
+    }
+}
+```
+
+**The Handler never formats or translates a message.** It throws a stable error code plus the interpolation arguments; `GlobalExceptionHandler` + `MessageResolver` resolve the localized text from `Accept-Language` at the edge (see quarkus-error-handling-i18n skill). A Handler that injects a `ResourceBundle` and passes a rendered string is wrong — it silently pins every response to one language.
+
+### `execution()` — orchestration inside the container transaction
+
+- Opens **one** `Connection` from the injected `DataSource` in try-with-resources and passes it to every `Sql` call in the operation. This is the performance contract: one connection per business operation, whether or not a transaction is active. Under JTA, Agroal would return the same enlisted connection anyway; on a read path with no `@Transactional`, per-method `getConnection()` would acquire *N* separate pool leases for *N* queries — passing `conn` makes both paths cost exactly one.
+- Calls `${SERVICE_CLASS_PREFIX}Sql` methods in business order (insert `party` first to get `partyId`, reuse it for dependent inserts). Before writing a call, re-read the real `Sql` method signature and pass exactly those parameters, in that order and type.
+- Catches every checked `SQLException` and rethrows it as `BusinessException` via `SqlStateTranslator` — an unchecked exception is what triggers the container rollback, and a propagated checked exception would not.
+- Date fields arrive from the DTO as `String`. To use them as `LocalDate`/`ZonedDateTime`, declare a **new local variable** and convert explicitly (`LocalDate.parse(...)`) — never reassign the DTO field.
+- Domain events are published by inserting an outbox row through this slice's own `Sql`, in this same transaction — never by emitting to Kafka directly (see quarkus-kafka-messaging skill). Who relays that row (Debezium, `OutboxRelayJob`, or a post-commit emit) is a runtime property, `app.messaging.outbox.relay-mode`, and changes nothing here.
+- External services are called through capability-named beans injected from `common/client` — never a raw `@GrpcClient` stub, which would drag Mutiny into the Handler.
+
+```java
+private UUID execution(CreatePartyIndividualRequestDto request) {
+    try (Connection conn = dataSource.getConnection()) {
+        UUID partyId = sql.insertParty(conn, request.getTenantId(), "Individual",
+            "Active", request.getCreatedBy());
+        sql.insertIndividual(conn, partyId, request.getGivenName(), request.getFamilyName());
+        if (request.getContactMedia() != null) {
+            for (ContactMediumDto medium : request.getContactMedia()) {
+                sql.insertContactMedium(conn, partyId, medium.getMediumType(), medium.getContactValue());
+            }
+        }
+        UUID eventId = sql.insertOutboxEvent(conn, partyId, "party",
+            "com.alva.customer.party.created.v1", "alva.customer.party.created.v1",
+            payloadJson(partyId, request), traceparent());   // traceparent captured from Span.current() (see kafka/observability skills)
+        dispatcher.dispatchAfterCommit(eventId);             // no-op unless relay-mode=direct (see kafka skill)
+        return partyId;
+    } catch (SQLException e) {
+        throw SqlStateTranslator.translate("PTY-500-001", e);
+    }
+}
+```
+
+### `getResult()` — response mapping
+
+Builds the response DTO from what `execution()` returned. It touches neither `Sql` nor the `Connection` — pure mapping. This is where the (deleted) `*Mapper` class went.
+
+```java
+private CreatePartyIndividualResponseDto getResult(UUID partyId) {
+    return CreatePartyIndividualResponseDto.builder()
+        .partyId(partyId.toString())
+        .build();
+}
+```
+
+### `process()` — the single entry point
+
+```java
+@Transactional
+@WithSpan("usecase.createPartyIndividual")
+public CreatePartyIndividualResponseDto process(CreatePartyIndividualRequestDto request) {
+    validate(request);
+    UUID partyId = execution(request);
+    return getResult(partyId);
+}
+```
+
+Every transport adapter calls exactly this method. It is the only public method of the Handler, the only place `@Transactional` (`jakarta.transaction.Transactional`) appears, and the natural custom-span boundary (see quarkus-observability-otel skill).
+
+### Transaction rules — no exceptions
+
+The container (Quarkus + Narayana JTA) owns the transaction: it **commits** when `process()` returns normally and **rolls back** on any propagated `RuntimeException`, `BusinessException` included.
+
+- **`conn.setAutoCommit(...)`, `conn.commit()`, `conn.rollback()` are forbidden anywhere in a slice.** There is no valid scenario for them here — not "for safety", not "to make sure it saved", not as generic JDBC good practice. The line right after `try (Connection conn = dataSource.getConnection())` is never `conn.setAutoCommit(false)`.
+- Closing the `Connection` (try-with-resources) returns it to the pool; it does **not** end the JTA transaction.
+- `@Transactional` never goes on `validate()`, `execution()`, `getResult()` or any private method: CDI interceptors do not fire on self-invocation, so the transaction would silently never open.
+- **Read-only slices skip `@Transactional` entirely** — a single `SELECT`, or several reads that tolerate a non-repeatable view, cost less without a JTA transaction. Use `@Transactional` the moment there is a write, or when several reads must see one consistent snapshot.
+- Need a different propagation for one step? Extract it into a separate `@ApplicationScoped` bean in `common/` with its own `@Transactional(REQUIRES_NEW)` public method and inject it — never annotate a private method. `QuarkusTransaction.requiringNew()` is the programmatic alternative for batch loops (see sql skill).
+
+**Pre-delivery checklist for every Handler:**
+
+- [ ] `setAutoCommit` does not appear in the file.
+- [ ] `.commit()` does not appear in the file.
+- [ ] `.rollback()` does not appear in the file.
+- [ ] `@Transactional` appears at most once, on `process()` — and is absent on a read-only slice.
+- [ ] Exactly one `dataSource.getConnection()`, passed to every `Sql` call.
+- [ ] Every `Sql` call matches the real signature (name, order, arity, types).
+- [ ] `BusinessException` is thrown with a code + args, never with a pre-rendered message.
+- [ ] No `Uni`/`Multi`/`PgPool`, no `@GrpcClient` stub, no transport type, no DTO redeclared as a nested class.
+
+### When to add an interface back
+
+Reintroduce a port interface (and only then) when one of these is true, and say so in the slice README:
+
+- A **second real implementation** exists in production code (two data sources, a stub for a partner API, a feature-flagged alternative).
+- The implementation lives in another deployable and is injected across a module boundary.
+- The consumer is `common/`/`libs/` code that must not depend on a slice.
+
+"Mocking is easier" is not a reason — Mockito mocks the concrete `Sql` class fine.
+
+## The Sql class — data adapter
+
+Full standard (pool config, batches, jsonb, pagination, keyset paging, SQLState translation) lives in the **quarkus-sql-jdbc-agroal** skill. Slice-specific shape:
+
+- `@ApplicationScoped`, `@Inject DataSource dataSource;`, then `private static final String` query constants, then one public method per query.
+- Constants are text blocks or comma-first concatenations, schema-qualified, with positional `?` placeholders only. **Check the real schema name before writing a query** — if the schema or table is a reserved word (`order`, `user`, `group`), quote it: `"order".party`.
+- If the PK has a database default (`id uuid DEFAULT customer.uuidv7() NOT NULL`), the `id` column is excluded from the INSERT column list and never passed as a parameter. Prefer `INSERT ... RETURNING id` over `getGeneratedKeys()`.
+- **Every method's first parameter is `Connection conn`** — supplied by the Handler, never obtained inside the method. That signature is the contract the Handler must honour exactly.
+- Methods `throws SQLException` — they never swallow it and never translate it. Translation to `BusinessException` happens in the Handler via `SqlStateTranslator`.
+- **No transaction control here.** No `commit`, no `rollback`, no `setAutoCommit`.
+- Row mapping is hand-written into DTOs (`PartyDto.builder()...`) — no reflection-based mappers, which also keeps native images small.
+
+## DTOs
+
+- Live in `${SLICE_PACKAGE}.dto`, one file per DTO **including nested ones** — never a `static class` or local `record`.
+- Lombok: `@Data`, `@NoArgsConstructor`, `@AllArgsConstructor` on every serializable DTO; `@Builder` on responses and on anything the Handler builds in parts.
+- **Date fields are always `String`** in a DTO (request and response), ISO-8601. Conversion happens exclusively in the Handler.
+- Form validation only (`jakarta.validation.constraints.*`); business rules belong in `validate()`.
+- OpenAPI documentation with `@Schema` on every contract-relevant field. When implementing a TMF spec, wire names are not negotiable — the Java class gets the `Dto` suffix, the serialized schema keeps the TMF name (`@Schema(name = "PartyIndividual")`). See quarkus-openapi-tmforum skill.
+- `@RegisterForReflection` on anything Jackson touches that Quarkus does not process at build time — Kafka payloads especially.
+- No business logic inside a DTO.
+
+## Transport adapters
+
+All three are thin: extract metadata, invoke `handler.process(...)`, format the response. Any `if` that encodes a business rule is in the wrong file. None of them catches and formats errors — they let `BusinessException` propagate to the global handler/interceptor.
+
+**REST** — full standard in **quarkus-openapi-tmforum** and **quarkus-error-handling-i18n**:
+
+- `<Resource>Resource` class with `@Path` + `@Tag`, injecting the slice `Handler`(s).
+- Returns `RestResponse<T>` synchronously. Never `Uni`/`Multi`.
+- `@Blocking` on JDBC-backed methods. With a plain (non-reactive) return type Quarkus REST already dispatches to a worker thread, so the annotation is redundant *today* — keep it as an explicit threading contract that survives a later signature change. `@RunOnVirtualThread` is the alternative for high-concurrency blocking endpoints (see sql skill §7).
+- Extracts `tenantId`, `partyId`, `partyRolList`, `language` from headers when the contract requires them, and sets them on the request DTO before calling `process()`.
+- Full OpenAPI annotations per method: `@Operation` with `operationId`, one `@APIResponse` per relevant status, `@Parameter` for headers and path/query params, `Location` header on create.
+
+**gRPC** — full standard in **quarkus-grpc-services**:
+
+- Proto in `src/main/proto/<module>/v<major>/`, published to `contracts/`, package `<org>.<module>.v1`, `snake_case` fields.
+- `@GrpcService` class named after the proto service, injecting the slice `Handler`.
+- One of the two sanctioned Mutiny sites: `Uni.createFrom().item(() -> {...}).runSubscriptionOn(Infrastructure.getDefaultWorkerPool())`, with proto ↔ DTO conversion inside the lambda.
+
+**Kafka** — full standard in **quarkus-kafka-messaging**:
+
+- `<Event>Consumer` class, `@ApplicationScoped`, injecting the slice `Handler`.
+- `@Incoming` methods are `@Blocking` (JDBC below). Idempotency check + `process()` + DLQ strategy per the kafka skill.
+- Producing domain events is **not** done here — the Handler inserts an outbox row in its transaction and the relay selected by `app.messaging.outbox.relay-mode` (Debezium / `OutboxRelayJob` / `OutboxDispatcher`) publishes it.
+
+## Errors and i18n
+
+Governed by **quarkus-error-handling-i18n**; the slice-relevant rules:
+
+- One exception type for business failures: `BusinessException(String code, Object... args)` in `common/exception`, carrying a stable `<MOD>-<HTTP>-<seq>` code and the interpolation arguments. No subclass-per-error hierarchy.
+- Technical failures keep the `PersistenceException` family; `SqlStateTranslator` maps SQLState → error code (`23505` → conflict, `40001` → transient, `57014` → timeout).
+- Optimistic-lock conflicts throw `StaleVersionException` — standalone, unchecked, code-carrying (not a `PersistenceException` subtype, not SQLState-derived): the `Handler` throws it when a versioned `UPDATE` returns 0 rows; dedicated mappers return 409 (REST) / `ABORTED` (gRPC).
+- `ErrorCatalog` maps code → HTTP status + reason. `MessageResolver` resolves the localized message from `Accept-Language` against `messages/errors[_<lang>].properties`, **keyed by the error code itself**, default locale `en`.
+- **Message resolution happens at the edge, never in the Handler.** `GlobalExceptionHandler` (REST) and `GrpcExceptionInterceptor` (gRPC) are the only places a message string is produced.
+- Native: `quarkus.locales=en,es,pt` and `quarkus.native.resources.includes=messages/*.properties`.
+
+Adding an error is four steps: pick the next code, register it in `ErrorCatalog`, add the key to **every** locale bundle, throw it from `validate()`/`execution()`.
+
+## Observability
+
+Governed by **quarkus-observability-otel**; the slice-relevant rules:
+
+- `@WithSpan("usecase.<sliceCamelCase>")` on `process()` — one span per business operation, matching the skill's `usecase.<verb><Entity>` convention since the slice name *is* the verb+entity.
+- Logger per class via `Log`/`Logger.getLogger(X.class)`; the Handler's class name already carries the slice. Never `System.out`.
+- Trace ids come only from `Span.current().getSpanContext()` — never hand-built strings. Outbox rows carry `traceparent` + a `traceContext` block in the payload.
+- Audit writes go through the `AuditRecorder` bean in `common/audit`, which captures the span itself.
+- No PII or secrets in spans, attributes or logs.
+
+## Shared code
+
+`common/` holds only what **two or more slices** genuinely share, or what is structurally cross-cutting: the exception/error/i18n machinery, integration beans, `OutboxRelayJob`/`OutboxDispatcher`, `AuditRecorder`, `@ConfigMapping` interfaces, `StringUtils`.
+
+Promotion rule: **duplicate twice, extract on the third.** Two slices with similar-looking code is the expected cost of slice independence — premature extraction rebuilds the shared-layer coupling this structure exists to avoid. What must never be shared: a `Handler`, an `Sql`, or a slice's `dto` package. If slice B needs slice A's data, it queries it through its own `Sql` method or consumes A's event — it does not import A.
+
+Code shared across **apps** in the domain goes to `libs/` and uses constructor injection.
 
 ## Scaffolding checklist
 
 When creating a new service:
 
 1. App folder `apps/<module>-<service>-ms/` per the monorepo layout above.
-2. `pom.xml` with BOM `io.quarkus.platform:quarkus-bom` (min version 3.38.2), extensions: `quarkus-rest`, `quarkus-rest-jackson`, `quarkus-agroal`, `quarkus-jdbc-postgresql`, `quarkus-arc`, `quarkus-smallrye-health`, `quarkus-flyway` (schema migrations), plus skills-specific extensions as needed.
-3. `application.properties` baseline (below).
-4. ArchUnit test (below) — add it in the same commit as the first class, not later.
-5. Native profile using Mandrel container build.
-6. `Dockerfile` at the app root, based on `quay.io/quarkus/quarkus-micro-image` (or distroless) running the native binary.
-7. `service.yaml` + per-app `README.md` (below) — in the same PR as the first endpoint, not later; CI blocks merges without them.
+2. `pom.xml` with BOM `io.quarkus.platform:quarkus-bom` (latest 3.x LTS), extensions: `quarkus-rest`, `quarkus-rest-jackson`, `quarkus-agroal`, `quarkus-jdbc-postgresql`, `quarkus-arc`, `quarkus-narayana-jta`, `quarkus-hibernate-validator`, `quarkus-smallrye-health`, `quarkus-smallrye-openapi`, `quarkus-opentelemetry`, `quarkus-flyway` (kept even where migrations are disabled — see sql skill §9), plus Lombok and skill-specific extensions as needed.
+3. `common/` package: `BusinessException`, `ErrorCatalog`, `ErrorDto`, `GlobalExceptionHandler`, `MessageResolver`, `SqlStateTranslator`, `StringUtils`.
+4. `application.properties` baseline (below).
+5. ArchUnit test (below) — in the same commit as the first slice, not later.
+6. Native profile using the Mandrel container build.
+7. `Dockerfile` at the app root — **always a native-image Dockerfile** (see "Dockerfile (native image — mandatory)" below). A JVM image (`quarkus-app/` + JRE base) is never the delivery artifact.
+8. `service.yaml` + per-app `README.md` (below) — in the same PR as the first endpoint; CI blocks merges without them.
+
+When creating a new slice, in this order (each step reads the previous file's real signatures):
+
+1. `dto/` — request, response, nested DTOs.
+2. `<Slice>Sql.java` — query constants + one method per query, `Connection` first.
+3. `<Slice>Handler.java` — `validate` → `execution` → `getResult` → `process`.
+4. Transport class(es): `Resource` always; `GrpcService`/`Consumer` only if the plan requires them (+ the `.proto` / channel config).
+5. New error codes registered in `ErrorCatalog` and added to **every** locale bundle.
+6. `<Slice>HandlerTest.java`.
+7. Slice `README.md`.
 
 ### application.properties baseline
 
 ```properties
 quarkus.datasource.db-kind=postgresql
 quarkus.datasource.jdbc.max-size=16
-quarkus.flyway.migrate-at-start=true
+
+# Schema migrations are OPT-IN and off by default — the app does not own the schema
+# in a DBA/pipeline-managed environment (see quarkus-sql-jdbc-agroal skill §9)
+quarkus.flyway.enabled=false
+quarkus.flyway.migrate-at-start=false
+%dev.quarkus.flyway.enabled=true
+%dev.quarkus.flyway.migrate-at-start=true
+%test.quarkus.flyway.enabled=true
+%test.quarkus.flyway.migrate-at-start=true
+
+# Outbox relay: who publishes the outbox row (see quarkus-kafka-messaging skill)
+app.messaging.outbox.relay-mode=debezium
+app.messaging.outbox.poller.every=off
+
+# i18n (see error-handling skill) — locales must be declared for native
+quarkus.locales=en,es
+quarkus.default-locale=en
+quarkus.native.resources.includes=messages/*.properties
 
 # Native build via Mandrel container (no local GraalVM needed)
 quarkus.native.container-build=true
@@ -199,6 +448,25 @@ quarkus.http.port=8080
 
 Build: `./mvnw package -Dnative` → binary in `target/*-runner`.
 
+### Dockerfile (native image — mandatory)
+
+The `Dockerfile` at the app root always packages the **native binary** — never a JVM/`fast-jar` image. The binary is produced by the Mandrel container build (`./mvnw package -Dnative` with `quarkus.native.container-build=true`, so no local GraalVM is needed), and the image just runs it:
+
+```dockerfile
+FROM quay.io/quarkus/quarkus-micro-image:2.0
+WORKDIR /work/
+COPY --chown=1001:root target/*-runner /work/application
+EXPOSE 8080
+USER 1001
+ENTRYPOINT ["./application", "-Dquarkus.http.host=0.0.0.0"]
+```
+
+Rules:
+- Base image: `quay.io/quarkus/quarkus-micro-image` (or a distroless equivalent per platform standard) — no JDK/JRE layer in the final image.
+- Non-root user (`USER 1001`), binary copied as `application`, port matching `quarkus.http.port`.
+- If the pipeline cannot run the Maven native build before `docker build`, use a multi-stage Dockerfile whose build stage runs the Mandrel builder image — the final stage is still the micro image with only the binary.
+- A `Dockerfile.jvm` may exist for local debugging only; it is never what CI publishes.
+
 ## Per-app documentation (mandatory, blocking)
 
 Every deployable under `apps/<app>/` carries two files, versioned with the code and updated in the **same PR** that changes the service's behavior:
@@ -210,23 +478,37 @@ Required `README.md` sections:
 
 1. **Identity** — app name, module (`part-of`), type (`ms`), owning team, repository, criticality, part of core yes/no
 2. **Purpose & responsibility** — description + out of scope
-3. **Tenancy model** — `shared` | `per-tenant` | `pool`; tenant identification (validated JWT claim, never a free header); data isolation; per-tenant parameters
-4. **APIs exposed** — table: api/version, protocol, route/topic, contract file, auth, visibility
-5. **Dependencies** — table: name, type, criticality (`hard`|`soft`), timeout/retry, behavior if down
-6. **Data & persistence** — engine, database/schema, tenant isolation, migrations (`db/`), cache, events
-7. **Configuration** — table: variable, description, type, required, default, varies-by (`environment`|`client`|`tenant`)
-8. **Secrets** — table: logical name, what it is, source (vault), who provides it, rotation period — **never the value**
-9. **Runtime & resources** — runtime/version, ports, requests/limits, replicas/HPA
-10. **Health checks** — liveness; readiness = **hard dependencies only**; startup probe
-11. **Deployment dependencies** — classified: startup / readiness-critical / hard runtime / soft runtime
-12. **Observability** — configurable log levels (`TRACE`–`FATAL`), the ConfigMap variable holding `logging_level`, its default, JSON log format
-13. **GitOps deployment** — location in the config repo, delivery strategy, feature flags
-14. **Rollback & recovery** — procedure, reversible migrations (N/N-1 compatible), RTO/RPO
-15. **Post-deploy validation** — smoke tests, contract tests, tenant-isolation tests
-16. **Troubleshooting** — symptom → cause → diagnosis
+3. **Slice inventory** — table: slice folder, capability, exposed channels (REST/gRPC/Kafka), link to the slice README
+4. **Tenancy model** — `shared` | `per-tenant` | `pool`; tenant identification (validated JWT claim, never a free header); data isolation; per-tenant parameters
+5. **APIs exposed** — table: api/version, protocol, route/topic, contract file, auth, visibility
+6. **Dependencies** — table: name, type, criticality (`hard`|`soft`), timeout/retry, behavior if down
+7. **Data & persistence** — engine, database/schema, tenant isolation, migrations (`db/`), cache, events
+8. **Configuration** — table: variable, description, type, required, default, varies-by (`environment`|`client`|`tenant`)
+9. **Secrets** — table: logical name, what it is, source (vault), who provides it, rotation period — **never the value**
+10. **Runtime & resources** — runtime/version, ports, requests/limits, replicas/HPA
+11. **Health checks** — liveness; readiness = **hard dependencies only**; startup probe
+12. **Deployment dependencies** — classified: startup / readiness-critical / hard runtime / soft runtime
+13. **Observability** — configurable log levels (`TRACE`–`FATAL`), the ConfigMap variable holding `logging_level`, its default, JSON log format
+14. **GitOps deployment** — location in the config repo, delivery strategy, feature flags
+15. **Rollback & recovery** — procedure, reversible migrations (N/N-1 compatible), RTO/RPO
+16. **Post-deploy validation** — smoke tests, contract tests, tenant-isolation tests
+17. **Troubleshooting** — symptom → cause → diagnosis
 
 Rule of completeness: if a variable, secret or dependency is not documented here, it does not exist — CI validates the `service.yaml` schema and the mandatory `README.md` sections as a blocking gate.
 
+### Slice README (inside the slice folder)
+
+Every slice carries its own `README.md`, generated from the real code — no invented routes, fields or tables. Sections:
+
+1. **Title** — `SERVICE_CLASS_PREFIX`
+2. **Description** — business purpose and context of the capability
+3. **Exposed routes** — table: channel (REST/gRPC/Kafka), route or operation, method/topic
+4. **Input contract** — table: field, type, required, description
+5. **Output contract** — table: field, type, description
+6. **Database dependencies** — table: table, use
+7. **Business errors** — table: error code, HTTP status, when it is raised
+8. **Usage example** — compact, valid `curl` + JSON response
+
 ### Domain README (repo root)
 
 The monorepo root `README.md` is the onboarding doc for the domain, and the owning team keeps it current:
@@ -237,156 +519,163 @@ The monorepo root `README.md` is the onboarding doc for the domain, and the owni
 
 It never documents live environment or client configuration — the deployed state per environment/client is managed in the GitOps config repo.
 
-## Persistence pattern (JDBC + Agroal)
-
-Full standard (pool config, transactions, batches, jsonb, pagination, SQLException translation) lives in the **quarkus-sql-jdbc-agroal** skill — consult it for any repository work. Summary of the shape:
-
-Outbound port in `application/port/out`:
-
-```java
-public interface UserRepository {
-    Optional<User> findById(UserId id);
-    void save(User user);
-}
-```
-
-Adapter in `infrastructure/persistence`:
-
-```java
-@ApplicationScoped
-public class JdbcUserRepository implements UserRepository {
-
-    private final AgroalDataSource ds;
-
-    public JdbcUserRepository(AgroalDataSource ds) { this.ds = ds; }
-
-    @Override
-    public Optional<User> findById(UserId id) {
-        var sql = "SELECT id, email, status, created_at FROM app_user WHERE id = ?";
-        try (var con = ds.getConnection(); var ps = con.prepareStatement(sql)) {
-            ps.setObject(1, id.value());
-            try (var rs = ps.executeQuery()) {
-                return rs.next() ? Optional.of(mapRow(rs)) : Optional.empty();
-            }
-        } catch (SQLException e) {
-            throw new PersistenceException("user.find_by_id", e);
-        }
-    }
-    // save(): use explicit transaction control or @Transactional on the use case
-}
-```
-
-Conventions:
-- Constructor injection only (no field `@Inject`) — testable and native-friendly.
-- SQL as constants or text blocks; never string concatenation with user input.
-- Transactions: annotate the **use case** with `@Transactional` (from `quarkus-narayana-jta`) so the unit of work matches the business operation, not the repository call.
-- Row mapping by hand or a small private `mapRow(ResultSet)` — no reflection-based mappers.
-
-## Domain conventions
-
-- Value objects = records with validation in a compact constructor.
-- Entity identity = typed IDs (`record UserId(UUID value)`), never bare UUID/String in signatures.
-- Domain events = sealed interface + records, named in past tense (`UserRegistered`).
-- Domain exceptions carry a **stable error code** (used by the error-handling-i18n skill): `throw new UserNotFoundException(id)` where the exception exposes `code() -> "USR-404-001"`.
-- Naming per the canonical table above — entities and events carry no suffix, ids are `<Entity>Id`, exceptions are `<Thing><Problem>Exception`.
-
 ## ArchUnit enforcement (mandatory)
 
-`src/test/java/.../ArchitectureTest.java`:
+Conventions that are not enforced decay within two sprints. `src/test/java/.../ArchitectureTest.java` — scope the analysis to your own packages so proto- and Quarkus-generated classes don't trip the rules. Static imports used below: `ArchRuleDefinition.classes/noClasses/methods`, `SlicesRuleDefinition.slices`, `JavaClass.Predicates.resideInAPackage`, `DescribedPredicate.alwaysTrue`.
 
 ```java
-@AnalyzeClasses(packages = "com.company.bc")
+@AnalyzeClasses(packages = "com.alva.customer", importOptions = ImportOption.DoNotIncludeTests.class)
 class ArchitectureTest {
 
+    // --- Slice isolation: a slice never imports another slice -------------------
     @ArchTest
-    static final ArchRule hexagonal = layeredArchitecture().consideringAllDependencies()
-        .layer("Domain").definedBy("..domain..")
-        .layer("Application").definedBy("..application..")
-        .layer("Infrastructure").definedBy("..infrastructure..")
-        .whereLayer("Domain").mayOnlyBeAccessedByLayers("Application", "Infrastructure")
-        .whereLayer("Application").mayOnlyBeAccessedByLayers("Infrastructure")
-        .whereLayer("Infrastructure").mayNotBeAccessedByAnyLayer();
+    static final ArchRule slicesAreIndependent = slices()
+        .matching("com.alva.customer.(*)..")
+        .namingSlices("slice $1")
+        .should().notDependOnEachOther()
+        .ignoreDependency(resideInAPackage("..common.."), alwaysTrue())
+        .ignoreDependency(alwaysTrue(), resideInAPackage("..common.."));
+
+    // --- Hexagon dependency rule inside the slice ------------------------------
+    @ArchTest
+    static final ArchRule onlyHandlersTouchSql = classes()
+        .that().haveSimpleNameEndingWith("Sql")
+        .should().onlyBeAccessed().byClassesThat(
+            have(simpleNameEndingWith("Handler"))
+            // OutboxSql is cross-cutting: its callers are the dispatcher and the relay job,
+            // which play the Handler role (they own the Connection) outside any slice.
+            .or(resideInAPackage("..common.messaging..")));
 
     @ArchTest
-    static final ArchRule domainIsPure = noClasses().that().resideInAPackage("..domain..")
+    static final ArchRule transportHasNoJdbc = noClasses()
+        .that().haveSimpleNameEndingWith("Resource")
+        .or().haveSimpleNameEndingWith("GrpcService")
+        .or().haveSimpleNameEndingWith("Consumer")
+        .should().dependOnClassesThat().resideInAnyPackage("java.sql..", "javax.sql..");
+
+    // A Handler injecting OutboxDispatcher still satisfies this rule: the dispatcher is a
+    // common/messaging bean, so no messaging API ever reaches the slice.
+    @ArchTest
+    static final ArchRule handlerKnowsNoTransport = noClasses()
+        .that().haveSimpleNameEndingWith("Handler")
+        .and().resideOutsideOfPackage("..common..")
         .should().dependOnClassesThat().resideInAnyPackage(
-            "jakarta..", "io.quarkus..", "org.eclipse.microprofile..",
-            "com.fasterxml.jackson..", "io.smallrye..", "java.sql..");
+            "jakarta.ws.rs..", "org.eclipse.microprofile.reactive.messaging..",
+            "io.grpc..", "io.quarkus.grpc..");
 
+    // --- Stack rules ------------------------------------------------------------
     @ArchTest
     static final ArchRule noOrm = noClasses().should().dependOnClassesThat()
         .resideInAnyPackage("jakarta.persistence..", "org.hibernate..", "io.quarkus.hibernate..");
+
+    // Mutiny is allowed ONLY in gRPC server adapters and common/client integration beans
+    @ArchTest
+    static final ArchRule reactiveIsQuarantined = noClasses()
+        .that().haveSimpleNameNotEndingWith("GrpcService")
+        .and().resideOutsideOfPackage("..common.client..")
+        .should().dependOnClassesThat().resideInAnyPackage(
+            "io.smallrye.mutiny..", "io.vertx.mutiny..");
+
+    // --- Transaction contract ---------------------------------------------------
+    @ArchTest
+    static final ArchRule transactionalOnlyOnProcess = methods()
+        .that().areAnnotatedWith(Transactional.class)
+        .and().areDeclaredInClassesThat().resideOutsideOfPackage("..common..")
+        .should().beDeclaredInClassesThat().haveSimpleNameEndingWith("Handler")
+        .andShould().haveName("process")
+        .andShould().bePublic();
+
+    @ArchTest
+    static final ArchRule handlersExposeOnlyProcess = methods()
+        .that().arePublic()
+        .and().areDeclaredInClassesThat().haveSimpleNameEndingWith("Handler")
+        .and().areDeclaredInClassesThat().resideOutsideOfPackage("..common..")
+        .should().haveName("process");
 }
 ```
 
 ### Naming rules (same test class)
 
-Conventions that are not enforced decay within two sprints. Add these alongside the layer rules — `resideInAPackage` is statically imported from `JavaClass.Predicates`:
-
 ```java
 @ArchTest
-static final ArchRule inboundPorts = classes().that().resideInAPackage("..application.port.in..")
-    .should().beInterfaces()
-    .andShould().haveSimpleNameEndingWith("UseCase");
-
-@ArchTest
-static final ArchRule outboundPorts = classes().that().resideInAPackage("..application.port.out..")
-    .should().beInterfaces();
-
-@ArchTest
-static final ArchRule useCaseImpls = classes().that().resideInAPackage("..application.usecase..")
-    .should().haveSimpleNameEndingWith("Service")
-    .andShould().implement(resideInAPackage("..application.port.in.."));
+static final ArchRule restResources = classes().that().areAnnotatedWith(Path.class)
+    .should().haveSimpleNameEndingWith("Resource");
 
 @ArchTest
-static final ArchRule serviceSuffixIsReserved = classes().that().haveSimpleNameEndingWith("Service")
-    .should().resideInAnyPackage("..application.usecase..", "..infrastructure.grpc..");
+static final ArchRule grpcServices = classes().that().areAnnotatedWith(GrpcService.class)
+    .should().haveSimpleNameEndingWith("GrpcService");
 
 @ArchTest
-static final ArchRule restResources = classes().that().areAnnotatedWith(Path.class)
-    .should().haveSimpleNameEndingWith("Resource")
-    .andShould().resideInAPackage("..infrastructure.rest..");
+static final ArchRule dtosStayInDtoPackage = classes()
+    .that().haveSimpleNameEndingWith("Dto").or().haveSimpleNameEndingWith("Payload")
+    .should().resideInAnyPackage("..dto..", "..common.error..");
 
 @ArchTest
-static final ArchRule jdbcAdapters = classes().that().resideInAPackage("..infrastructure.persistence..")
-    .and().implement(resideInAPackage("..application.port.out.."))
-    .should().haveSimpleNameStartingWith("Jdbc");
+static final ArchRule dtosHaveNoLogic = noClasses().that().resideInAPackage("..dto..")
+    .should().dependOnClassesThat().resideInAnyPackage("java.sql..", "javax.sql..");
 
 @ArchTest
-static final ArchRule dtosStayInAdapters = classes().that().haveSimpleNameEndingWith("Dto")
-    .should().resideInAPackage("..infrastructure..");
+static final ArchRule serviceSuffixIsReserved = classes()
+    .that().haveSimpleNameEndingWith("Service")
+    .should().haveSimpleNameEndingWith("GrpcService");
 
 @ArchTest
-static final ArchRule domainExceptions = classes().that().areAssignableTo(DomainException.class)
-    .should().haveSimpleNameEndingWith("Exception")
-    .andShould().resideInAPackage("..domain.exception..");
+static final ArchRule businessExceptionIsTheOnlyOne = classes()
+    .that().haveSimpleNameEndingWith("Exception")
+    .should().resideInAPackage("..common.exception..");
 
 @ArchTest
 static final ArchRule bannedSuffixes = noClasses().should().haveSimpleNameEndingWith("Impl")
-    .orShould().haveSimpleNameEndingWith("Util")
-    .orShould().haveSimpleNameEndingWith("Utils")
+    .orShould().haveSimpleNameEndingWith("Util")       // note: "Utils" is deliberately absent — common/util/StringUtils
     .orShould().haveSimpleNameEndingWith("Helper")
     .orShould().haveSimpleNameEndingWith("Manager")
+    .orShould().haveSimpleNameEndingWith("Mapper")
+    .orShould().haveSimpleNameEndingWith("UseCase")
+    .orShould().haveSimpleNameEndingWith("Repository")
+    .orShould().haveSimpleNameEndingWith("Dao")
     .orShould().haveSimpleNameEndingWith("DTO");
 ```
 
-Scope the analysis to your own packages (`@AnalyzeClasses(packages = "com.alva.bc05")`) so proto- and Quarkus-generated classes don't trip the suffix rules.
+`common/util/StringUtils` and the `Jdbc` namespace helper (sql skill §6) are the sanctioned exceptions to `bannedSuffixes` — exclude them by fully-qualified name rather than weakening the rule.
+
+Rules the compiler cannot express (enforce in code review and in the generator checklists):
+
+- `setAutoCommit` / `.commit()` / `.rollback()` appear nowhere in a slice. A CI `grep` is the cheapest possible gate:
+  `! grep -rnE '\.(setAutoCommit|commit|rollback)\(' src/main/java`
+- No hand-built trace strings: `! grep -rnE '"00-"\s*\+' src/main/java` (observability skill).
+- Every `ErrorCatalog` code exists in every locale bundle — write that test once, iterating codes × locales (error-handling skill).
 
 ## Native-image survival rules
 
-- Any class serialized by Jackson (DTOs, Kafka payloads) that is NOT touched by Quarkus build-time processing: annotate `@RegisterForReflection`.
-- Resources (SQL files, i18n bundles, certs): declare in `quarkus.native.resources.includes` if read at runtime via classpath.
+- Any class serialized by Jackson (DTOs, Kafka payloads, `ErrorDto`) that is NOT touched by Quarkus build-time processing: annotate `@RegisterForReflection`.
+- Resources read at runtime via the classpath: declare in `quarkus.native.resources.includes` — `messages/*.properties` is required by the standard bundle layout. `quarkus.locales` must list every supported locale or the locale data is not embedded.
 - Avoid libraries relying on dynamic proxies/bytecode generation at runtime. Prefer Quarkus extensions over raw libraries — extensions do build-time registration for you.
+- Hand-written row mapping (no reflection mappers) is already native-friendly; keep it that way.
 - Verify with a native integration test: `@QuarkusIntegrationTest` runs the same tests against the built binary. CI must run `./mvnw verify -Dnative` at least on release branches.
 
 ## Testing strategy
 
-| Layer | Test type | Tools |
+| Target | Test type | Tools |
 |---|---|---|
-| domain | plain JUnit 5 unit tests, no Quarkus | JUnit, AssertJ |
-| application | unit tests with mocked ports | Mockito |
-| infrastructure/persistence | `@QuarkusTest` + Dev Services (Testcontainers Postgres) | REST Assured n/a |
-| REST/gRPC adapters | `@QuarkusTest` + REST Assured / gRPC client | |
+| `<Slice>Handler` (business rules) | plain JUnit 5 + Mockito, **no Quarkus context** | JUnit, Mockito, AssertJ |
+| `<Slice>Sql` | `@QuarkusTest` + Dev Services (Testcontainers Postgres) | real SQL against real Postgres, never H2 |
+| `<Resource>Resource` | `@QuarkusTest` + REST Assured | contract, status codes, localized error body |
+| `*GrpcService` / `*Consumer` | `@QuarkusTest` + generated client / in-memory connector | |
 | native binary | `@QuarkusIntegrationTest` | |
 
-Keep coverage meaningful: mutation testing (PIT) on domain + application layers is the quality gate, not raw line coverage.
+`<Slice>HandlerTest` is mandatory and mirrors the slice. Rules:
+
+- Mockito only — `@Mock <Slice>Sql sql;`, `@Mock DataSource dataSource;`, `@Mock Connection connection;`, `@InjectMocks <Slice>Handler handler;`, with `when(dataSource.getConnection()).thenReturn(connection)` in `@BeforeEach`. Never a real database, never `@QuarkusTest` for pure business rules, never both `@InjectMocks` (Mockito) and `@InjectMock` (Quarkus) in one file.
+- Test names: `should<Result>When<Condition>` — `shouldReturnPartyIdWhenRequestIsValid`, `shouldThrowBusinessExceptionWhenGivenNameIsBlank`.
+- Minimum scenarios per public business path:
+
+| # | Scenario | How to trigger it | What to assert |
+|---|---|---|---|
+| 1 | Happy path | all `sql` mocks return valid values | the mapped response; the expected `sql` calls in order |
+| 2 | Validation failure | a mandatory field blank/null | `BusinessException` thrown **and `verifyNoInteractions(sql)`** |
+| 3 | Database failure | a `sql` method throws `SQLException` | `BusinessException` propagates out of `process()` (this is what makes the container roll back) |
+| 4 | Error code correctness | inspect the thrown exception | `e.code()` is the expected `<MOD>-<HTTP>-<seq>`; the message is **not** rendered here — localization is asserted in the `Resource` test |
+
+Because the container owns the transaction, a Handler unit test **never asserts `verify(connection).commit()` or `verify(connection).rollback()`** — those calls do not exist in the code. The rollback assertion is "a `RuntimeException` escapes `process()`"; verifying the actual rollback belongs to a `@QuarkusTest` that calls `process()` inside a real transaction and then reads the table back.
+
+Keep coverage meaningful: mutation testing (PIT) on the `Handler` classes is the quality gate, not raw line coverage.