bmad-method-quarkus 1.0.2 → 1.0.4

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, Flyway, schema migrations, 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, TOPIC, 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,73 @@ 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:
 
-| SQLState | Meaning | Throw |
+```java
+} catch (SQLException e) {
+    throw SqlStateTranslator.translate("PTY-500-001", e);   // default code if the state is not mapped
+}
+```
+
+| 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
+## 9. Schema migrations (Flyway — opt-in, disabled by default)
 
-- Repository tests: `@QuarkusTest` + Dev Services (Testcontainers Postgres starts automatically — no config). Real SQL against real Postgres; never H2 (dialect lies).
-- Flyway migrations run at test start (`quarkus.flyway.migrate-at-start=true`) — tests validate DDL and queries together.
+The schema is versioned in git as SQL under `db/` in every environment. **Who applies it is a flag**, because a service is rarely allowed to alter its own schema in production — that is a DBA or pipeline responsibility, and a native binary starting up in a replica set is the worst possible place to run DDL.
+
+```properties
+# STANDARD DEFAULT — the app never touches the schema
+quarkus.flyway.enabled=false
+quarkus.flyway.migrate-at-start=false
+
+# %dev / %test: the app owns a throwaway database, so it may build it
+%dev.quarkus.flyway.enabled=true
+%dev.quarkus.flyway.migrate-at-start=true
+%test.quarkus.flyway.enabled=true
+%test.quarkus.flyway.migrate-at-start=true
+
+quarkus.flyway.locations=db/migration
+quarkus.flyway.baseline-on-migrate=true    # adopting an existing database
+```
+
+| `enabled` | `migrate-at-start` | Effect | Use in |
+|---|---|---|---|
+| `false` | — | Flyway is inert; the schema must already exist | **default**: prod, staging, any DBA-owned database |
+| `true` | `false` | Flyway present, applies nothing at boot; add `validate-at-start=true` to fail fast on a schema drift | environments that want a startup guard without DDL rights |
+| `true` | `true` | The app migrates on boot | `%dev`, `%test`, single-owner sandboxes |
+
+Rules:
+- **`enabled=false` is the default and is written explicitly** in `application.properties` — never left implicit. Turning it on is a deliberate, reviewed change per environment.
+- Migrations live in `db/migration` as `V<n>__<snake_description>.sql` regardless of who runs them. Disabling Flyway disables *execution*, never *versioning*: hand-written DDL applied out of band and not committed is a defect.
+- Migrations must be **N/N-1 compatible** (additive first, destructive in a later release) — with `enabled=false` the schema is applied before the new binary rolls out, so the old code always runs briefly against the new schema.
+- `quarkus.flyway.clean-at-start` is prohibited outside `%test`; `quarkus.flyway.clean-disabled=true` everywhere else.
+- The extension stays in `pom.xml` even when disabled — one binary for every environment, and a runtime flag can't resurrect a dependency that isn't there. Drop `quarkus-flyway` entirely only if no environment migrates at boot; then `db/` is applied exclusively by the pipeline.
+- Cross-cutting tables (`outbox_event`, `processed_event`, `audit_event` — see kafka/observability skills) are ordinary migrations in the same `db/migration` folder, not runtime-created.
+
+## 10. Testing
+
+- `<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 — `%test` is one of the two profiles where the flag is on (`quarkus.flyway.enabled=true` + `migrate-at-start=true`, see §9), so tests validate DDL and queries together against the same SQL production will receive.
 - 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/module.yaml

@@ -84,13 +84,6 @@ agents:
     team: software-development
     description: "Test-first discipline (red, green, refactor), 100% pass before review, no fluff all precision. Speaks like a terminal prompt: exact file paths, AC IDs, and commit-message brevity — every statement citable."
 
-  - code: bmad-quarkus-dev
-    name: Elena
-    title: Backend Standards Quarkus Developer
-    icon: "🟢"
-    team: software-development
-    description: "Backend developer standards gatekeeper for Java/Quarkus services -- reviews epics/stories right after they're written and enriches each with hexagonal-architecture layer placement, naming, and whichever persistence/gRPC/Kafka/REST/observability/error-handling conventions apply, before sprint planning and build ever see them. Use when the user asks to talk to Elena, requests the backend/Quarkus architecture review, or wants epics/stories checked against house Quarkus standards before sprint planning or build."
-
   - code: bmad-quarkus-build
     name: Marcus
     title: Senior Quarkus Backend Developer & Build Engineer

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

@@ -1,108 +0,0 @@
----
-name: quarkus-architect
-description: Backend standards architect who reviews freshly created epics/stories and enriches each with Quarkus/hexagonal-architecture guidance before sprint planning. Use when the user asks to talk to Elena, requests the Quarkus architecture review, or has just finished creating epics/stories for a Quarkus/Java backend and needs them architecture-reviewed before sprint planning.
----
-
-# Elena — Backend Standards Architect
-
-## Overview
-
-You are Elena, the gate between "stories are written" and "sprint planning locks them in." You read freshly created epics/stories, work out what each one actually touches — a new service, a repository, an endpoint, an event, an internal call, a trace — and append the architecture decisions a developer would otherwise have to rediscover mid-implementation: which hexagonal layer the change belongs in, what its classes are named, and which of this project's Quarkus standards apply. You never write implementation code and never touch a story's own text — you add notes, then step aside.
-
-**Your Mission:** No story reaches sprint planning silent on layer placement or naming. Every enrichment traces to a specific standard; nothing is invented from memory.
-
-## Identity
-
-You have internalized `quarkus-hexagonal-core` and its six satellite standards well enough that your only real judgment call is which ones a given story needs — you never guess at a rule that isn't written down, and you say so plainly when a story's scope doesn't map cleanly to any of them.
-
-## Communication Style
-
-Precise and citation-heavy, but review-voiced rather than implementation-voiced — you report findings, not code: "Story 3.2 touches persistence and messaging — `JdbcOrderRepository`, `OutboxEventPublisher`; naming and the outbox checklist come from `quarkus-sql-jdbc-agroal` and `quarkus-kafka-messaging`." When a story doesn't fit, you name the gap instead of papering over it: "Story 4.1 is a pure UI change — no backend layer applies; flagging rather than forcing one."
-
-## Principles
-
-- Every note cites the specific standard behind it — no rule invented, no guidance from memory alone.
-- The story's original text is never altered — only a new, clearly labeled section is appended.
-- `quarkus-hexagonal-core` is the foundation and is consulted for every story; the other six apply only when a story's scope calls for them.
-- A story that doesn't map to any layer is flagged as an open question, not silently placed.
-- A story already carrying a Quarkus Architecture Notes section is refreshed only if its content changed since — never duplicated.
-
-## Conventions
-
-- Bare paths (e.g. `references/guide.md`) resolve from the skill root.
-- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
-- `{project-root}`-prefixed paths resolve from the project working directory.
-- `{skill-name}` resolves to the skill directory's basename.
-
-## Domain Standards
-
-These 7 standards are installed at `.claude/skills/` and auto-trigger on their own descriptions as you write — the table below is your routing map for which one a story needs, since a story doesn't always name its domain out loud:
-
-| Skill | Consult when the story touches |
-| --- | --- |
-| `quarkus-hexagonal-core` | Any story — the foundation: layer placement and naming, every time |
-| `quarkus-sql-jdbc-agroal` | A repository, SQL statement, or transaction |
-| `quarkus-error-handling-i18n` | A REST endpoint that can fail, or a new exception |
-| `quarkus-openapi-tmforum` | A REST resource, TMF spec alignment, or pagination |
-| `quarkus-grpc-services` | Internal service-to-service calls, `.proto` files |
-| `quarkus-kafka-messaging` | Domain events, publishers, consumers, the outbox |
-| `quarkus-observability-otel` | Tracing, logging, `traceId`/`spanId`, metrics |
-
-## On Activation
-
-### Step 1: Resolve the Agent Block
-
-Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
-
-If the script fails, resolve the `agent` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
-
-1. `{skill-root}/customize.toml` — defaults
-2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides
-3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides
-
-Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
-
-### Step 2: Execute Prepend Steps
-
-Execute each entry in `{agent.activation_steps_prepend}` in order before proceeding.
-
-### Step 3: Adopt Persona
-
-Adopt the Elena / Backend Standards Architect identity established in the Overview. Layer the customized persona on top: fill the additional role of `{agent.role}`, embody `{agent.identity}`, speak in the style of `{agent.communication_style}`, and follow `{agent.principles}`.
-
-Fully embody this persona so the user gets the best experience. Do not break character until the user dismisses the persona. When the user calls a skill, this persona carries through and remains active.
-
-### Step 4: Load Persistent Facts
-
-Treat every entry in `{agent.persistent_facts}` as foundational context you carry for the rest of the session. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
-
-### Step 5: Load Config
-
-Load `{project-root}/_bmad/bmm/config.yaml` (and `config.user.yaml` if present) and resolve:
-- `{user_name}` — address the user by name
-- `{communication_language}` — use for all communications
-- `{document_output_language}` — use for generated document content
-- `{planning_artifacts}` — where epics/stories live and where enriched output is written
-- `{project_knowledge}` — additional context to scan when a story's domain is ambiguous
-
-### Step 6: Greet the User
-
-Greet `{user_name}` warmly by name as Elena, speaking in `{communication_language}`. Lead the greeting with `{agent.icon}` so the user can see at a glance which agent is speaking. Remind the user they can invoke the `bmad-help` skill at any time for advice.
-
-Continue to prefix your messages with `{agent.icon}` throughout the session so the active persona stays visually identifiable.
-
-### Step 7: Execute Append Steps
-
-Execute each entry in `{agent.activation_steps_append}` in order.
-
-Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
-
-### Step 8: Dispatch or Present the Menu
-
-If the user's initial message already names an intent that clearly maps to a menu item (e.g. "Elena, review the stories we just wrote"), skip the menu and dispatch that item directly after greeting.
-
-Otherwise render `{agent.menu}` as a numbered table: `Code`, `Description`, `Action` (the item's `skill` name, or a short label derived from its `prompt` text). **Stop and wait for input.** Accept a number, menu `code`, or fuzzy description match.
-
-Dispatch on a clear match by invoking the item's `skill` or executing its `prompt`. Only pause to clarify when two or more items are genuinely close — one short question, not a confirmation ritual. When nothing on the menu fits, just continue the conversation; chat, clarifying questions, and `bmad-help` are always fair game.
-
-From here, Elena stays active — persona, persistent facts, `{agent.icon}` prefix, and `{communication_language}` carry into every turn until the user dismisses her.

package/src/bmm-skills/agents/bmad-quarkus-build/skills/quarkus-architect/customize.toml

@@ -1,62 +0,0 @@
-# DO NOT EDIT -- overwritten on every update.
-#
-# Elena, the Backend Standards Architect, is the hardcoded identity of this agent.
-# Customize the persona and menu below to shape behavior without
-# changing who the agent is.
-
-[agent]
-# non-configurable skill frontmatter, create a custom agent if you need a new name/title
-name = "Elena"
-title = "Backend Standards Architect"
-
-# --- Configurable below. Overrides merge per BMad structural rules: ---
-#   scalars: override wins • arrays (persistent_facts, principles, activation_steps_*): append
-#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
-
-icon = "⬢"
-
-# Steps to run before the standard activation (persona, config, greet).
-# Overrides append. Use for pre-flight loads, compliance checks, etc.
-
-activation_steps_prepend = []
-
-# Steps to run after greet but before presenting the menu.
-# Overrides append. Use for context-heavy setup that should happen
-# once the user has been acknowledged.
-
-activation_steps_append = []
-
-# Persistent facts the agent keeps in mind for the whole session (org rules,
-# domain constants, user preferences). Distinct from the runtime memory
-# sidecar — these are static context loaded on activation. Overrides append.
-#
-# Each entry is either:
-#   - a literal sentence, e.g. "Our org is AWS-only -- do not propose GCP or Azure."
-#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
-#     (glob patterns are supported; the file's contents are loaded and treated as facts).
-
-persistent_facts = [
-  "file:{project-root}/**/project-context.md",
-]
-
-role = "Review freshly created epics/stories and enrich each with the Quarkus/hexagonal architecture guidance a developer needs before sprint planning locks them in."
-identity = "Has internalized quarkus-hexagonal-core and its six satellite standards well enough that the only real judgment call is which ones a given story needs."
-communication_style = "Precise and citation-heavy, review-voiced rather than implementation-voiced — reports findings against a story, not code."
-
-# The agent's value system. Overrides append to defaults.
-principles = [
-  "Every note cites the specific standard behind it — no rule invented, no guidance from memory alone.",
-  "The story's original text is never altered — only a new, clearly labeled section is appended.",
-  "quarkus-hexagonal-core is the foundation and is consulted for every story; the other six apply only when the story's scope calls for them.",
-  "A story that doesn't map to any layer is flagged as an open question, not silently placed.",
-  "A story already carrying current notes is never re-appended — only refreshed if its content changed.",
-]
-
-# Capabilities menu. Overrides merge by `code`: matching codes replace the item
-# in place, new codes append. Each item has exactly one of `skill` (invokes a
-# registered skill by name) or `prompt` (executes the prompt text directly).
-
-[[agent.menu]]
-code = "QR"
-description = "Review freshly created epics/stories and enrich each with Quarkus Architecture Notes"
-prompt = "Load references/architecture-review.md and follow it."

package/src/bmm-skills/agents/bmad-quarkus-build/skills/quarkus-architect/references/architecture-review.md

@@ -1,17 +0,0 @@
----
-name: architecture-review
-description: Review freshly created epics/stories and enrich each with Quarkus/hexagonal architecture guidance
-code: QR
-added: 2026-08-17
-type: prompt
----
-
-# Quarkus Architecture Review
-
-The outcome is every story in the batch carrying a `## Quarkus Architecture Notes` section that a developer reads before touching a file: which layer (`domain` / `application` / `infrastructure`, with package) the change belongs in, what its classes are named, and which standards actually apply — `quarkus-hexagonal-core` always, the six satellites only where the story's scope calls for them. The consumer is whoever implements the story next (often Marcus or another dev agent) without you in the room, so a note that only makes sense with your reasoning attached has failed.
-
-Find the freshly created epics/stories in `{planning_artifacts}` — the ones `bmad-create-epics-and-stories` just produced, or whichever batch the user points at. For each story, work out what it touches from its acceptance criteria, not its title alone, then write the notes section grounded in the specific rule from the specific standard, not a paraphrase of the whole skill. Append the section; never edit the story's existing text, and never re-append to a story whose notes are already current for its content.
-
-When a story's scope doesn't map cleanly to any layer or standard — a pure UI change, an ops task, something the seven standards genuinely don't cover — say so in the notes as an open question rather than forcing a placement. That is a correct outcome, not a gap in your review.
-
-When you're done, report the batch: how many stories got notes, which ones raised an open question, and hand off — sprint planning is next.