bmad-method-quarkus 1.0.2 → 1.0.3

package/src/bmm-skills/agents/bmad-quarkus-build/skills/quarkus-sql-jdbc-agroal/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: quarkus-sql-jdbc-agroal
-description: Standard for executing SQL queries, updates, batches, and transactions in Quarkus WITHOUT Panache or any ORM — using the Agroal connection pool with plain JDBC (default) or the reactive Vert.x SQL client (justified cases only). Use this skill whenever the user writes or reviews ANY repository, DAO, SQL statement, SELECT/INSERT/UPDATE/DELETE, batch operation, transaction, pagination query, jsonb access, connection pool configuration, or mentions Agroal, JDBC, PreparedStatement, datasource, or "query the database" — all persistence code must follow these patterns, including repository/adapter/row-mapper naming.
+description: Standard for executing SQL queries, updates, batches, and transactions in Quarkus WITHOUT Panache or any ORM — using the Agroal connection pool with plain JDBC (default) or the reactive Vert.x SQL client (justified cases only). Use this skill whenever the user writes or reviews ANY repository, DAO, SQL statement, SELECT/INSERT/UPDATE/DELETE, batch operation, transaction, pagination query, jsonb access, connection pool configuration, or mentions Agroal, JDBC, PreparedStatement, datasource, or "query the database" — all persistence code must follow these patterns. Data access lives in the slice `<Slice>Sql` class with `Connection` as the first parameter of every method (see quarkus-hexagonal-core skill); there are no repositories, DAOs or row-mapper classes.
 ---
 
 # SQL Execution Standard: Agroal + Plain JDBC (No ORM)
 
 Applies to any Quarkus backend project; project directives (CLAUDE.md, ADRs, explicit instructions) override these defaults where they conflict.
 
-Persistence is explicit SQL through the Agroal pool. No Panache, no Hibernate, no reflection-based row mappers. Repositories are adapters in `infrastructure/persistence` implementing outbound ports (see quarkus-hexagonal-core skill).
+Persistence is explicit SQL through the Agroal pool. No Panache, no Hibernate, no reflection-based row mappers. Data access lives in the slice's `<Slice>Sql` class — the driven adapter of the vertical slice (see quarkus-hexagonal-core skill). There are no `*Repository` ports and no `Jdbc*` adapters: one `Sql` class per slice, called only by that slice's `Handler`.
 
 One clarification to keep teams from chasing ghosts: **Agroal is a JDBC (blocking) pool** — there is no "reactive Agroal". The reactive path in Quarkus is the Vert.x SQL client (`quarkus-reactive-pg-client`) with its own pool. Default choice here is **Agroal + JDBC** (simpler, dominant skill base, works perfectly in native); reactive client only for measured hot paths with extreme concurrency (see §7).
 
@@ -42,131 +42,149 @@ Rules:
 
 ## 2. Injection and the golden resource pattern
 
-Inject the pool, never raw drivers, never `DriverManager`:
+Inject the pool, never raw drivers, never `DriverManager`. The `Sql` class holds the `DataSource` but **does not open connections** — the `Handler` opens exactly one per business operation and passes it in (see §3):
 
 ```java
 @ApplicationScoped
-public class JdbcUserRepository implements UserRepository {
+public class CreatePartyIndividualSql {
 
-    private final AgroalDataSource ds;
-    public JdbcUserRepository(AgroalDataSource ds) { this.ds = ds; }
+    @Inject
+    DataSource dataSource;      // injected for symmetry/health checks; connections come from the Handler
 }
 ```
 
-Every statement uses **try-with-resources on Connection, PreparedStatement AND ResultSet** — this is what returns connections to the pool. A missed close under load exhausts the pool and takes the native pod down:
+**Every method's first parameter is `Connection conn`.** That signature is the contract the `Handler` must honour exactly — same name, order, arity and types. Statements use **try-with-resources on PreparedStatement AND ResultSet** (the `Connection` is owned and closed by the caller). A missed close under load exhausts the pool and takes the native pod down:
 
 ```java
-private static final String FIND_BY_ID = """
-    SELECT id, email, status, created_at
-    FROM app_user
-    WHERE id = ?
+private static final String SELECT_PARTY_BY_ID = """
+    SELECT id, tenant_id, party_type, status, created_at
+      FROM customer.party
+     WHERE id = ?
+       AND tenant_id = ?
     """;
 
-@Override
-public Optional<User> findById(UserId id) {
-    try (var con = ds.getConnection();
-         var ps  = con.prepareStatement(FIND_BY_ID)) {
-        ps.setObject(1, id.value());
-        try (var rs = ps.executeQuery()) {
-            return rs.next() ? Optional.of(mapRow(rs)) : Optional.empty();
+public PartyDto findPartyById(Connection conn, UUID id, String tenantId) throws SQLException {
+    try (PreparedStatement ps = conn.prepareStatement(SELECT_PARTY_BY_ID)) {
+        ps.setObject(1, id);
+        ps.setString(2, tenantId);
+        try (ResultSet rs = ps.executeQuery()) {
+            return rs.next() ? mapRow(rs) : null;
         }
-    } catch (SQLException e) {
-        throw translate("user.find_by_id", e);
     }
 }
 ```
 
 Absolute rules:
-- SQL as `private static final String` text blocks. Never concatenate user input — `PreparedStatement` placeholders ALWAYS (SQL injection + plan cache).
+- SQL as `private static final String` text blocks (comma-first concatenation is equally acceptable), schema-qualified. Never concatenate user input — `PreparedStatement` placeholders ALWAYS (SQL injection + plan cache).
+- Quote reserved-word schemas and tables: `"order".party`. Verify the real schema name before writing the query.
 - Dynamic WHERE clauses: build from a whitelist of column/operator constants, values still as placeholders.
-- One private `mapRow(ResultSet) -> Entity` per repository (or a `RowMapper<T>` functional interface shared via a tiny helper — see §6). No reflection mappers: they break native and hide cost.
+- Methods declare `throws SQLException` and never catch it — the `Handler` translates it (§8). No `commit`, `rollback` or `setAutoCommit` here, ever.
+- One private `mapRow(ResultSet) -> Dto` per `Sql` class. Rows map to the slice's own DTOs; there is no separate domain entity and no `*RowMapper` class. No reflection mappers: they break native and hide cost.
 
 Naming (canonical rules in the quarkus-hexagonal-core skill):
 
 | Artifact | Convention | Example |
 |---|---|---|
-| Outbound port | `<Entity>Repository`, in `application/port/out` | `UserRepository` |
-| JDBC adapter | `Jdbc<Port>`, in `infrastructure/persistence` | `JdbcUserRepository` |
-| Shared row mapper | `<Entity>RowMapper` (private `mapRow` when not shared) | `UserRowMapper` |
-| SQL constant | `UPPER_SNAKE_CASE` verb-first `private static final String` | `FIND_BY_ID`, `INSERT_USER` |
-| Table / column | `snake_case`, singular table name | `app_user`, `created_at` |
+| Data access class | `${SERVICE_CLASS_PREFIX}Sql`, in the slice folder | `CreatePartyIndividualSql` |
+| Method | imperative verb, matching the query | `insertParty`, `findPartyById`, `listPartiesByTenant` |
+| SQL constant | `UPPER_SNAKE_CASE` matching the method, `private static final String` | `SELECT_PARTY_BY_ID`, `INSERT_PARTY` |
+| Table / column | `snake_case`, singular table name, schema-qualified | `customer.party`, `created_at` |
+| Row target | the slice's `*Dto` | `PartyDto` |
 | Technical exception | `PersistenceException` + specific subtypes (§8) | `TransientPersistenceException` |
 
-Never name a repository `*Dao`, `*Manager` or `*Service` — `*Service` is reserved for use-case implementations, and a repository that grows business logic is a use case in disguise.
+Never name this class `*Repository`, `*Dao`, `*Manager` or `*Service` — those suffixes are banned by the core skill's ArchUnit rules. An `Sql` class that grows an `if` encoding a business rule has swallowed logic that belongs in the `Handler`.
 
-## 3. Transactions: on the use case, not the repository
+## 3. Transactions and connections: one of each, on `Handler.process()`
 
-The unit of work is the business operation. Annotate the **application-layer use case**:
+The unit of work is the business operation, which in a slice is `process()`. The `Handler` opens **one** `Connection` in `execution()` and passes it to every `Sql` call:
 
 ```java
 @ApplicationScoped
-public class RegisterUserService implements RegisterUserUseCase {   // impl = *Service, port = *UseCase
-
-    @Transactional
-    public UserId register(RegisterUserCommand cmd) {
-        var user = User.register(cmd);       // domain
-        userRepository.save(user);           // same tx
-        eventPublisher.publish(new UserRegistered(user.id())); // same tx (outbox insert)
-        return user.id();
+public class CreatePartyIndividualHandler {
+
+    @Inject DataSource dataSource;
+    @Inject CreatePartyIndividualSql sql;
+
+    @Transactional                                    // the ONLY @Transactional in the slice
+    public CreatePartyIndividualResponseDto process(CreatePartyIndividualRequestDto request) {
+        validate(request);
+        return getResult(execution(request));
+    }
+
+    private UUID execution(CreatePartyIndividualRequestDto request) {
+        try (Connection conn = dataSource.getConnection()) {          // exactly one, for the whole operation
+            UUID partyId = sql.insertParty(conn, request.getTenantId(), "Individual",
+                "Active", request.getCreatedBy());
+            sql.insertIndividual(conn, partyId, request.getGivenName(), request.getFamilyName());
+            sql.insertOutboxEvent(conn, partyId, "party", EVENT_TYPE, payloadJson(partyId, request), traceparent());
+            return partyId;
+        } catch (SQLException e) {
+            throw SqlStateTranslator.translate("PTY-500-001", e);      // unchecked -> container rolls back
+        }
     }
 }
 ```
 
-With `@Transactional` active, Agroal enlists the connection in the JTA transaction automatically — repositories keep using `ds.getConnection()` and all writes inside the use case share one transaction, committed/rolled back together. This is exactly what the outbox pattern requires (see quarkus-kafka-messaging skill).
+**Why the explicit `Connection` parameter (performance):** inside an active JTA transaction Agroal returns the *same* enlisted connection for every `getConnection()` call, so both styles cost one physical connection. The difference shows on **read paths that carry no `@Transactional`** — there, a per-method `ds.getConnection()` takes *N* pool leases for *N* queries, each with its own acquisition and return. Passing `conn` makes every path, transactional or not, cost exactly one lease. It also keeps session state (`statement_timeout`, prepared-statement cache, temp tables) coherent across the operation.
 
-- Runtime exceptions roll back by default; domain exceptions extend `RuntimeException`, so throwing them rolls back — correct by construction.
-- Programmatic control when annotations don't fit (loops with per-item commit, batch jobs):
+- `@Transactional` goes on `process()` only — never on a private method (CDI interceptors don't fire on self-invocation, so the transaction would silently never open), never on the `Sql` class.
+- **Read-only slices skip `@Transactional` entirely.** A single `SELECT`, or several reads that tolerate a non-repeatable view, are cheaper without a JTA transaction — still one `Connection`, opened and closed in `execution()`. Add the annotation the moment there is a write, or when several reads must see one snapshot.
+- Runtime exceptions roll back by default; `BusinessException` extends `RuntimeException`, so throwing it rolls back — correct by construction. A checked `SQLException` would **not** roll back, which is why §8 translation is mandatory.
+- Programmatic control when annotations don't fit (loops with per-item commit, batch jobs) — from a `common/` bean or a `*Job`, never from inside a slice `Handler`:
 
 ```java
-QuarkusTransaction.requiringNew().timeout(30).run(() -> { ...repos... });
+QuarkusTransaction.requiringNew().timeout(30).run(() -> { ...sql calls... });
 ```
 
-- Never call `con.commit()`/`setAutoCommit()` manually inside JTA-managed code paths.
-- Read-only single queries need no `@Transactional` (auto-commit read is fine); multi-read consistency or any write → transaction.
+- Never call `con.commit()`/`rollback()`/`setAutoCommit()` anywhere. The core skill ships a CI `grep` gate for exactly these three tokens.
 
 ## 4. Updates, inserts, upserts, generated keys
 
 ```java
-private static final String INSERT = """
-    INSERT INTO app_user (id, email, status, created_at)
-    VALUES (?, ?, ?, ?)
-    ON CONFLICT (email) DO NOTHING
+private static final String INSERT_PARTY = """
+    INSERT INTO customer.party (tenant_id, party_type, status, created_by, updated_by)
+         VALUES (?, ?, ?, ?, ?)
+      RETURNING id
     """;
 
-@Override
-public void save(User u) {
-    try (var con = ds.getConnection(); var ps = con.prepareStatement(INSERT)) {
-        ps.setObject(1, u.id().value());
-        ps.setString(2, u.email().value());
-        ps.setString(3, u.status().name());
-        ps.setObject(4, u.createdAt());
-        if (ps.executeUpdate() == 0) throw new DuplicateEmailException(u.email());
-    } catch (SQLException e) {
-        throw translate("user.save", e);
+public UUID insertParty(Connection conn, String tenantId, String partyType,
+                        String status, String createdBy) throws SQLException {
+    try (PreparedStatement ps = conn.prepareStatement(INSERT_PARTY)) {
+        ps.setString(1, tenantId);
+        ps.setString(2, partyType);
+        ps.setString(3, status);
+        ps.setString(4, createdBy);
+        ps.setString(5, createdBy);
+        try (ResultSet rs = ps.executeQuery()) {
+            rs.next();
+            return rs.getObject("id", UUID.class);
+        }
     }
 }
 ```
 
-- Check `executeUpdate()` counts — 0 rows on an expected UPDATE is a bug or a concurrency signal, not a success.
-- Prefer DB-generated values via `RETURNING` (Postgres) over `getGeneratedKeys()` when you need them: `INSERT ... RETURNING id` + `executeQuery()`.
-- Optimistic locking: `version` column, `UPDATE ... WHERE id = ? AND version = ?`; 0 rows → `StaleVersionException` (domain) → 409 via the unified handler. Do NOT name it `ConcurrentModificationException` — it shadows `java.util.ConcurrentModificationException` and an accidental import turns the 409 mapping into a 500.
-- Upserts: `ON CONFLICT ... DO UPDATE` explicitly; never SELECT-then-INSERT races.
+- **Generated ids**: when the PK has a database default (`id uuid DEFAULT customer.uuidv7() NOT NULL`), exclude `id` from the column list and never bind it. Read it back with `RETURNING id` + `executeQuery()` — preferred over `getGeneratedKeys()`.
+- Check `executeUpdate()` counts — 0 rows on an expected UPDATE is a bug or a concurrency signal, not a success. The `Handler` decides what that means; `Sql` just returns the count.
+- Optimistic locking: `version` column, `UPDATE ... WHERE id = ? AND version = ?`; 0 rows → the `Handler` throws `StaleVersionException` (code-carrying, in `common/exception`) with the slice's conflict code → 409 via its dedicated mapper (see quarkus-error-handling-i18n skill). It is not SQLState-derived — no `SQLException` occurs, so `SqlStateTranslator` never sees it; the `Handler` checks the update count. Do NOT name it `ConcurrentModificationException` — it shadows `java.util.ConcurrentModificationException` and an accidental import turns the 409 mapping into a 500.
+- Upserts: `ON CONFLICT ... DO UPDATE` explicitly; never SELECT-then-INSERT races. A unique-violation (`23505`) surfacing as a `SQLException` is translated by the `Handler` (§8), not swallowed here.
 
 ## 5. Batches, pagination, jsonb
 
 **Batch** (bulk inserts/updates — outbox relays, imports):
 
 ```java
-try (var con = ds.getConnection(); var ps = con.prepareStatement(INSERT)) {
-    for (var item : items) {
-        bind(ps, item);
-        ps.addBatch();
+public int[] insertPartiesBatch(Connection conn, List<PartyDto> items) throws SQLException {
+    try (PreparedStatement ps = conn.prepareStatement(INSERT_PARTY)) {
+        for (PartyDto item : items) {
+            bind(ps, item);
+            ps.addBatch();
+        }
+        return ps.executeBatch();   // add ?reWriteBatchedInserts=true to the JDBC URL (Postgres)
     }
-    ps.executeBatch();          // add ?reWriteBatchedInserts=true to the JDBC URL (Postgres)
 }
 ```
 
-Chunk batches (500–1000) inside long jobs; combine with `QuarkusTransaction` per chunk.
+Chunk batches (500–1000) inside long jobs; combine with `QuarkusTransaction` per chunk, driven from a `*Job` in `common/`, not from a slice `Handler`.
 
 **Pagination**: keyset over OFFSET for anything user-facing/deep:
 
@@ -192,15 +210,17 @@ Read side: `rs.getString("context")` then parse. Index jsonb lookups you actuall
 To kill boilerplate, ONE small internal helper class (~50 lines) per service or shared lib is the sanctioned maximum:
 
 ```java
-public final class Jdbc {
+public final class Jdbc {   // common/util — the one sanctioned exception to the banned-suffix rule
     @FunctionalInterface public interface RowMapper<T> { T map(ResultSet rs) throws SQLException; }
 
-    public static <T> Optional<T> queryOne(DataSource ds, String sql, RowMapper<T> m, Object... params) { ... }
-    public static <T> List<T> queryList(DataSource ds, String sql, RowMapper<T> m, Object... params) { ... }
-    public static int update(DataSource ds, String sql, Object... params) { ... }
+    public static <T> Optional<T> queryOne(Connection conn, String sql, RowMapper<T> m, Object... params) throws SQLException { ... }
+    public static <T> List<T> queryList(Connection conn, String sql, RowMapper<T> m, Object... params) throws SQLException { ... }
+    public static int update(Connection conn, String sql, Object... params) throws SQLException { ... }
 }
 ```
 
+Note the signatures take `Connection`, not `DataSource` — the helper must not open connections either, or it defeats the one-lease-per-operation rule of §3.
+
 - Pure delegation to the try-with-resources pattern above; no reflection, no annotations, no SQL generation. If someone proposes adding criteria builders or entity mapping to it, that's an ORM growing back — reject.
 - The class is named `Jdbc` — a namespace, not `JdbcUtils`/`JdbcHelper`. The banned-suffix ArchUnit rule (see quarkus-hexagonal-core skill) exists precisely to stop this class from becoming a junk drawer.
 - jOOQ (code-gen, type-safe SQL) MAY be evaluated as an alternative via formal ADR; MyBatis/Hibernate remain excluded.
@@ -216,30 +236,40 @@ JDBC blocks. Never run it on the event loop:
 
 ## 8. SQLException translation
 
-One translator in `infrastructure/persistence`, mapping SQLState to domain/persistence exceptions so callers never see `SQLException`:
+`Sql` methods propagate `SQLException`; the `Handler` catches it once, in `execution()`, and translates it through `SqlStateTranslator` (`common/error`) so nothing checked ever escapes `process()` — a checked exception would not trigger the container rollback:
+
+```java
+} catch (SQLException e) {
+    throw SqlStateTranslator.translate("PTY-500-001", e);   // default code if the state is not mapped
+}
+```
 
-| SQLState | Meaning | Throw |
+| SQLState | Meaning | Resulting exception (all unchecked) |
 |---|---|---|
-| `23505` | unique violation | domain conflict exception (→ 409) |
-| `23503` | FK violation | domain integrity exception |
+| `23505` | unique violation | `BusinessException` with the slice's conflict code (→ 409) |
+| `23503` | FK violation | `BusinessException` with the slice's integrity code (→ 409/422) |
 | `40001` / `40P01` | serialization failure / deadlock | retryable `TransientPersistenceException` |
 | `57014` | statement timeout/cancel | `PersistenceTimeoutException` |
 | other | infrastructure failure | `PersistenceException(code, e)` (→ 500) |
 
+Every resulting code is registered in `ErrorCatalog` and present in all locale bundles (see quarkus-error-handling-i18n skill). The client sees a localized message; the `SQLException` stays in the logs.
+
 Set `statement_timeout` (session or per-datasource via `quarkus.datasource.jdbc.additional-jdbc-properties.options=-c statement_timeout=5000`) so runaway queries fail fast instead of holding pool connections.
 
 ## 9. Testing
 
-- Repository tests: `@QuarkusTest` + Dev Services (Testcontainers Postgres starts automatically — no config). Real SQL against real Postgres; never H2 (dialect lies).
+- `<Slice>Sql` tests: `@QuarkusTest` + Dev Services (Testcontainers Postgres starts automatically — no config). Real SQL against real Postgres; never H2 (dialect lies). Obtain a `Connection` in the test and pass it in, exactly as the `Handler` does.
+- `<Slice>Handler` tests are pure Mockito with a mocked `Sql` — no database (see quarkus-hexagonal-core skill).
 - Flyway migrations run at test start (`quarkus.flyway.migrate-at-start=true`) — tests validate DDL and queries together.
 - Native verification: `@QuarkusIntegrationTest` re-runs the same tests against the binary.
 
-## Checklist for a new repository method
+## Checklist for a new `Sql` method
 
-0. Names follow the canonical table above (`Jdbc<Port>` adapter, `<Entity>Repository` port, `UPPER_SNAKE` SQL constants).
-1. SQL text block constant, placeholders only; whitelist for any dynamic fragment.
-2. try-with-resources on connection/statement/resultset (or the `Jdbc` helper).
-3. Transaction boundary on the use case, not here.
-4. `executeUpdate()` count checked; SQLState translated, never leaked.
-5. jsonb via `PGobject`; batch + chunking for bulk; keyset pagination if deep.
-6. `@Blocking`/virtual thread if called from a reactive context; Dev Services test written.
+0. Names follow the canonical table above (`<Slice>Sql` class, imperative method name, `UPPER_SNAKE` SQL constant).
+1. First parameter is `Connection conn`; the method declares `throws SQLException` and opens no connection of its own.
+2. SQL text block constant, schema-qualified, reserved words quoted, placeholders only; whitelist for any dynamic fragment.
+3. try-with-resources on statement/resultset (the caller owns the connection).
+4. No `commit`/`rollback`/`setAutoCommit`; the transaction boundary is `Handler.process()`.
+5. `executeUpdate()` count returned or checked; `SQLException` propagated for the `Handler` to translate, never swallowed.
+6. Generated ids via `RETURNING`; jsonb via `PGobject`; batch + chunking for bulk; keyset pagination if deep.
+7. Rows mapped by hand into the slice's `*Dto`; Dev Services test written.

package/src/bmm-skills/agents/bmad-quarkus-dev/skills/quarkus-error-handling-i18n/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: quarkus-error-handling-i18n
-description: Unified (single) global exception handler and internationalized (i18n) API responses for Quarkus backend services, aligned to TM Forum error schema (TMF630). Use this skill whenever the user mentions exception handling, error responses, ExceptionMapper, error codes, Problem Details, localization, i18n, translations, Accept-Language, message bundles, or when creating/reviewing ANY REST endpoint that can fail — errors and locale handling must always go through this standard, never ad-hoc try/catch in resources. Also defines exception class naming and the English-identifiers/localized-messages rule.
+description: Unified (single) global exception handler and internationalized (i18n) API responses for Quarkus backend services, aligned to TM Forum error schema (TMF630). Use this skill whenever the user mentions exception handling, error responses, ExceptionMapper, error codes, Problem Details, localization, i18n, translations, Accept-Language, message bundles, or when creating/reviewing ANY REST endpoint that can fail — errors and locale handling must always go through this standard, never ad-hoc try/catch in resources. Also defines the single BusinessException type (code + args, never a pre-rendered message), the ErrorCatalog/MessageResolver machinery in common/, and the English-identifiers/localized-messages rule.
 ---
 
 # Unified Exception Handler + i18n Responses (Quarkus, TMF-aligned)
@@ -24,33 +24,42 @@ All error responses use `application/json` with the TMF Error structure (interop
 }
 ```
 
-- `code`: stable, machine-readable, defined in the **domain exception**, format `<MOD>-<HTTP>-<seq>` where `<MOD>` is a short module/domain code (the BC code in DDD projects). Never reworded, never localized.
+- `code`: stable, machine-readable, carried by the thrown `BusinessException`, format `<MOD>-<HTTP>-<seq>` where `<MOD>` is a short uppercase code derived from the semantic module name or its main entity (`IAM`, `USR`, `PTY` — never a `bcNN` inventory code; see quarkus-hexagonal-core skill). It is also the **bundle key**. Never reworded, never localized.
 - `message`: human-readable, **localized** via bundles.
 - `referenceError`: link to error catalog docs.
 - Add `traceId` propagation via response header `X-Trace-Id` (see observability skill), not in the body.
 
-## Exception hierarchy (domain layer, framework-free)
+## One business exception (`common/exception`)
+
+The vertical-slice standard uses a **single** business exception carrying a stable code plus interpolation arguments — not a subclass per error. The subclass hierarchy bought nothing that the code does not already express, and cost one file per error:
 
 ```java
-// domain/exception
-public abstract class DomainException extends RuntimeException {
+// common/exception
+public class BusinessException extends RuntimeException {
     private final String code;          // "USR-404-001"
-    private final Object[] messageArgs; // interpolated into localized message
-    protected DomainException(String code, Object... args) {
-        super(code);
+    private final Object[] messageArgs; // interpolated into the localized message
+    public BusinessException(String code, Object... args) {
+        super(code);                    // super message = the code; the human text is resolved at the edge
         this.code = code;
         this.messageArgs = args;
     }
+    public BusinessException(String code, Throwable cause, Object... args) { ... }
     public String code() { return code; }
     public Object[] messageArgs() { return messageArgs; }
 }
+```
 
-public final class UserNotFoundException extends DomainException {
-    public UserNotFoundException(UserId id) { super("USR-404-001", id.value()); }
-}
+Thrown from the slice `Handler` and nowhere else:
+
+```java
+throw new BusinessException("USR-404-001", userId);
 ```
 
-HTTP status is NOT known by the domain. The mapping code→status lives in the handler via a registry (an enum or properties-driven map in infrastructure).
+**The thrower never formats or translates the message.** A `Handler` that injects a `ResourceBundle` and passes a rendered string silently pins every response to one language, defeating `Accept-Language`. Resolution happens once, at the edge, in `GlobalExceptionHandler` / `GrpcExceptionInterceptor`.
+
+HTTP status is not known by the `Handler` either. The mapping code→status lives in `ErrorCatalog` (`common/error`).
+
+One sibling, not a subclass: `StaleVersionException` (optimistic-lock conflict) is the only other code-carrying exception. It is NOT a `BusinessException` subtype and NOT part of the `PersistenceException` family — a version conflict is a client-actionable 409, not an infrastructure failure hidden behind a 500. It is thrown by the `Handler` when a versioned `UPDATE` returns 0 rows (never by `SqlStateTranslator` — there is no `SQLException` involved) and mapped by its own dedicated mapper below.
 
 ### Naming
 
@@ -58,21 +67,24 @@ Canonical rules in the quarkus-hexagonal-core skill; the error/i18n specifics:
 
 | Artifact | Convention | Example |
 |---|---|---|
-| Domain exception | `<Thing><Problem>Exception`, in `domain/exception` | `UserNotFoundException`, `DuplicateEmailException` |
-| Base class | `DomainException` | |
-| Technical exceptions | `PersistenceException`, `TransientPersistenceException`, `StaleVersionException` | |
-| Single REST handler | `GlobalExceptionHandler` (the only sanctioned `*Handler`) | |
-| gRPC counterpart | `GrpcExceptionInterceptor` | |
+| Business exception | `BusinessException` — one class, in `common/exception` | thrown with `("USR-404-001", id)` |
+| Technical exceptions | `PersistenceException`, `TransientPersistenceException`, `PersistenceTimeoutException`, in `common/exception` | |
+| Concurrency-conflict exception | `StaleVersionException` — standalone, code-carrying (`code + args`, like `BusinessException`), in `common/exception` | thrown with `("PTY-409-001", id)` |
+| SQLState translator | `SqlStateTranslator`, in `common/error` | |
+| Single REST handler | `GlobalExceptionHandler`, in `common/error` | |
+| gRPC counterpart | `GrpcExceptionInterceptor`, in `common/error` | |
 | i18n components | `MessageResolver`, `ErrorCatalog` | |
-| Error DTO | `ErrorDto` | |
+| Error DTO | `ErrorDto` (TMF630 Error shape) | |
 | Bundle files | `messages/errors[_<lang>].properties` | `errors_en.properties` |
 | Bundle key | the error code itself, never a prose key | `USR-404-001` |
 
-Never name an exception after the HTTP status (`NotFoundException`, `BadRequestException`) — the domain does not know about HTTP, and the status is resolved by `ErrorCatalog`. Never shadow a JDK type (`ConcurrentModificationException` → `StaleVersionException`).
+`GlobalExceptionHandler` is no longer "the only sanctioned `*Handler`" — under the slice standard `*Handler` is the business-logic class of every slice (`CreatePartyIndividualHandler`). What stays true is that there is exactly **one** global exception handler per transport, both in `common/error`, and that no `Resource`, `GrpcService` or `Consumer` builds an error response itself.
 
-**Language rule:** class, method and field names are English; the *messages* are localized per bundle, with **English as the default locale** and other languages (es, pt, ...) added per project need. `UserNotFoundException` with a Spanish translation `El usuario {0} no existe.` in `errors_es.properties` is correct — `UsuarioNoEncontradoException` is not.
+Never name an exception after the HTTP status (`NotFoundException`, `BadRequestException`) — the status is resolved by `ErrorCatalog`. Never shadow a JDK type (`ConcurrentModificationException` → `StaleVersionException`).
 
-## The single global handler (infrastructure/rest)
+**Language rule:** class, method and field names are English; the *messages* are localized per bundle, with **English as the default locale** and other languages (es, pt, ...) added per project need. A slice named `create_party_individual` throwing `PTY-400-001`, translated as `El campo ''{0}'' es obligatorio.` in `errors_es.properties`, is correct — a class or key named `crear_persona.campo_obligatorio` is not.
+
+## The single global handler (`common/error`)
 
 Exactly ONE class. Use `@ServerExceptionMapper` (Quarkus REST) — build-time wired, native-friendly:
 
@@ -89,13 +101,27 @@ public class GlobalExceptionHandler {
     }
 
     @ServerExceptionMapper
-    public RestResponse<ErrorDto> map(DomainException e, HttpHeaders headers) {
+    public RestResponse<ErrorDto> map(BusinessException e, HttpHeaders headers) {
         var status = catalog.statusOf(e.code());               // e.g. 404
         var msg = messages.resolve(e.code(), headers, e.messageArgs());
         return RestResponse.status(status,
             ErrorDto.of(e.code(), status, msg));
     }
 
+    @ServerExceptionMapper
+    public RestResponse<ErrorDto> map(StaleVersionException e, HttpHeaders headers) {
+        // optimistic-lock conflict: 409 per catalog, client-visible and localized like a business error
+        var status = catalog.statusOf(e.code());               // 409
+        var msg = messages.resolve(e.code(), headers, e.messageArgs());
+        return RestResponse.status(status, ErrorDto.of(e.code(), status, msg));
+    }
+
+    @ServerExceptionMapper
+    public RestResponse<ErrorDto> map(PersistenceException e, HttpHeaders headers) {
+        // technical failures: 500/503 per catalog, stack trace to logs only
+        ...
+    }
+
     @ServerExceptionMapper
     public RestResponse<ErrorDto> map(ConstraintViolationException e, HttpHeaders headers) {
         // 400, code "GEN-400-001", join violations into localized detail
@@ -114,7 +140,7 @@ public class GlobalExceptionHandler {
 Rules:
 - Catch-all `Exception` mapper is mandatory: internal details/stack traces NEVER reach the client. Log with full context (trace_id lands in the log automatically via MDC).
 - Validation errors (Bean Validation) map to 400 with one generic code + per-field details array.
-- Resources and use cases must NOT catch-and-format errors themselves — throw domain exceptions and let the handler translate.
+- `Resource`, `GrpcService`, `Consumer` and `Handler` classes must NOT catch-and-format errors themselves — throw `BusinessException` with a code and let the handler translate. A `try { ... } catch (BusinessException e) { return Response.status(400)... }` inside a `Resource` is the anti-pattern this skill exists to prevent: it bypasses the catalog, the locale and the trace header.
 - `ErrorDto` is `@RegisterForReflection` (native).
 
 ## i18n resolution from Accept-Language
@@ -135,17 +161,23 @@ quarkus.default-locale=en
 ```properties
 # errors.properties (en, default)
 USR-404-001=User {0} does not exist.
+PTY-400-001=The ''{0}'' field is required.
 GEN-400-001=The request contains invalid data.
 GEN-500-001=Internal error. Contact support with the trace identifier.
 ```
 
+Bundles are **per application, keyed by error code** — not per slice, not keyed by prose. A slice contributes rows to the same files, which is what keeps "every code exists in every locale" a single testable invariant. (`''` escapes a literal apostrophe for `MessageFormat`.)
+
 ```properties
 # errors_es.properties
 USR-404-001=El usuario {0} no existe.
+PTY-400-001=El campo ''{0}'' es obligatorio.
 GEN-400-001=La solicitud contiene datos inválidos.
 GEN-500-001=Error interno. Contacte a soporte con el identificador de traza.
 ```
 
+Quality bar per language — Spanish: formal or infinitive, precise, no vague `Error de validación`. English: direct declarative, no vague `something went wrong`. Same key order in every file so diffs stay readable.
+
 For native: `quarkus.native.resources.includes=messages/*.properties`.
 
 ### Resolver
@@ -175,7 +207,9 @@ Success-path localizable strings (notification texts, report labels) use the sam
 
 ## Checklist when adding a new error
 
-1. Create domain exception extending `DomainException`, named `<Thing><Problem>Exception`, with new code `<MOD>-<HTTP>-<seq>`.
-2. Register code → status/reason in `ErrorCatalog`.
-3. Add the message key to ALL locale bundles (build fails a test if a code is missing in any bundle — write that test once: iterate catalog codes × locales).
-4. Document in the error catalog page referenced by `referenceError`.
+1. Pick the next code `<MOD>-<HTTP>-<seq>` — no new exception class.
+2. Throw `new BusinessException(code, args...)` from the slice `Handler` (`validate()` or `execution()`), with the interpolation args and no rendered text.
+3. Register code → status/reason in `ErrorCatalog`.
+4. Add the message key to ALL locale bundles (a test fails the build if a code is missing in any bundle — write it once: iterate catalog codes × locales).
+5. Document in the error catalog page referenced by `referenceError`, and add the row to the slice `README.md` "Business errors" table.
+6. Assert the code (not the message) in the `HandlerTest`; assert the localized body in the `Resource` `@QuarkusTest`.