bmad-method-quarkus 1.0.3 → 1.0.5

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

@@ -1,6 +1,6 @@
 ---
 name: quarkus-kafka-messaging
-description: Standard for asynchronous event-driven messaging with Apache Kafka in Quarkus native services — CloudEvents envelope, topic naming, transactional outbox, idempotent consumers, DLQ, and W3C trace context propagation. Use this skill whenever the user mentions Kafka, events, messaging, publish/subscribe, producers, consumers, outbox, domain events between services, SmallRye Reactive Messaging, or asynchronous integration between bounded contexts — even if they just say "emit an event" or "listen to a topic". Includes payload, consumer, relay-job and channel naming conventions for the vertical-slice layout (the Consumer lives in the slice folder and delegates to the slice Handler; the outbox row is written by the slice's own Sql inside the Handler transaction).
+description: Standard for asynchronous event-driven messaging with Apache Kafka in Quarkus native services — CloudEvents envelope, topic naming, transactional outbox, idempotent consumers, DLQ, and W3C trace context propagation. Use this skill whenever the user mentions Kafka, events, messaging, publish/subscribe, producers, consumers, outbox, domain events between services, SmallRye Reactive Messaging, or asynchronous integration between bounded contexts — even if they just say "emit an event" or "listen to a topic". Includes payload, consumer, relay-job and channel naming conventions for the vertical-slice layout (the Consumer lives in the slice folder and delegates to the slice Handler; the outbox row is written by the shared OutboxEventRecorder in common/messaging, on the Connection the Handler already owns) and the property-driven relay mode (`app.messaging.outbox.relay-mode` = debezium | poller | direct) that decides whether Debezium, a scheduled poller or a direct Emitter publishes the row.
 ---
 
 # Kafka Messaging Standard (Quarkus + SmallRye Reactive Messaging)
@@ -45,23 +45,26 @@ Payload schema:
 Never publish to Kafka in the same breath as a DB write — dual-write problem. Standard:
 
 1. The slice `Handler` (in the SAME JDBC transaction as the state change) inserts into the outbox table.
-2. A relay publishes to Kafka (Debezium outbox connector preferred; scheduled poller as fallback for environments without Kafka Connect).
+2. A relay publishes to Kafka. **Which relay is a runtime property, not a code change** — Debezium outbox connector, in-process scheduled poller, or direct post-commit `Emitter`. See *Relay mode* below.
 
-Standard outbox table (one per service):
+Standard outbox table (one per service), created by a versioned migration in `db/migration` — never at runtime, and independently of whether the Flyway flag lets the app apply it (see quarkus-sql-jdbc-agroal skill §10):
 
 ```sql
 CREATE TABLE outbox_event (
   id            UUID PRIMARY KEY,
   aggregate_type VARCHAR(64)  NOT NULL,   -- "user"
   aggregate_id   VARCHAR(64)  NOT NULL,   -- partition key
-  event_type     VARCHAR(128) NOT NULL,   -- "com.alva.iam.user.registered.v1"
+  event_type     VARCHAR(128) NOT NULL,   -- "com.alva.iam.user.registered.v1" (CloudEvents type)
+  topic          VARCHAR(255) NOT NULL,   -- "alva.iam.user.registered.v1" — resolved once, at insert
   payload        JSONB        NOT NULL,
   traceparent    VARCHAR(64)  NOT NULL,   -- captured at insert time (W3C Trace Context)
   created_at     TIMESTAMPTZ  NOT NULL DEFAULT now(),
-  published_at   TIMESTAMPTZ  NULL        -- poller mode only
+  published_at   TIMESTAMPTZ  NULL        -- poller/direct modes only (see Relay mode)
 );
 ```
 
+Schema-qualify it like any other table (`identity.outbox`, `customer.outbox_event`) — the unqualified name above is shorthand for readability, not a licence to rely on `search_path` (quarkus-sql-jdbc-agroal skill §2). Whatever the name, `OutboxSql` is the only class that spells it.
+
 **Payload traceability (mandatory):** besides the `traceparent` column (used by the relay to set the Kafka header), the `payload` jsonb itself must embed a `traceContext` block for audit and immutability:
 
 ```json
@@ -78,14 +81,18 @@ CREATE TABLE outbox_event (
 
 Both `traceparent` and `traceContext` are captured at insert time from `Span.current().getSpanContext()` — manual construction of trace strings is prohibited (see quarkus-observability-otel skill).
 
-Under the vertical-slice standard there is no `EventPublisher` port and no publisher adapter: the slice's `Handler` writes the outbox row through **its own `Sql` class**, inside `execution()`, on the same `Connection` and therefore in the same transaction as the state change:
+Under the vertical-slice standard there is no `EventPublisher` port and no publisher adapter: the slice's `Handler` writes the outbox row through **`OutboxEventRecorder` in `common/messaging`**, inside `execution()`, on the same `Connection` and therefore in the same transaction as the state change. (`OutboxDispatcher` below is not that port — it publishes nothing in the default mode and never appears in the event's write path.)
+
+**The outbox is a cross-cutting table, so it gets exactly one writer per service — never a per-slice copy.** The dual-write guarantee comes from the shared `Connection`, not from the class living in the slice folder: `OutboxEventRecorder.record(conn, …)` takes the `Connection` the `Handler` already owns, so the row lands in the same JTA transaction as the state change. Re-declaring `insertOutboxEvent` on a `<Slice>Sql` buys nothing and costs ~25 identical lines per slice; the copies drift (a null-guard here, a changed column list there) and the divergence is invisible until one slice writes a row the relay cannot route. `OutboxEventRecorder` mirrors `AuditRecorder` in `common/audit` exactly — same `Connection`-first shape, same reason.
 
 ```java
 private UUID execution(CreatePartyIndividualRequestDto request) {
     try (Connection conn = dataSource.getConnection()) {
         UUID partyId = sql.insertParty(conn, ...);
-        sql.insertOutboxEvent(conn, partyId, "party",
-            "com.alva.customer.party.created.v1", payloadJson(partyId, request), traceparent());
+        UUID eventId = outbox.record(conn, "party", partyId.toString(),
+            "com.alva.customer.party.created.v1", "alva.customer.party.created.v1",
+            eventMap(partyId, request));            // recorder captures the span, builds the envelope
+        dispatcher.dispatchAfterCommit(eventId);   // no-op unless relay-mode=direct (see Relay mode)
         return partyId;
     } catch (SQLException e) {
         throw SqlStateTranslator.translate("PTY-500-001", e);
@@ -93,14 +100,178 @@ private UUID execution(CreatePartyIndividualRequestDto request) {
 }
 ```
 
-That is the whole dual-write guarantee — one connection, one transaction, no port indirection. `OutboxRelayJob` lives in `common/messaging` (or is replaced by the Debezium connector) and is the only component that talks to Kafka on the produce side.
+`execution()` still returns the slice's internal result (`partyId`) for `getResult()`, `@Transactional` still sits on `process()` alone, and the method order of the hexagonal-core skill is unchanged. `OutboxEventRecorder` and `OutboxDispatcher` are injected in the Handler's `common/` bean slot, next to `dataSource` and `sql`.
+
+The slice supplies only what is genuinely slice-specific — the aggregate type/id, the CloudEvents `type`, the topic, and the `event` body. Everything repetitive is the recorder's job:
+
+```java
+// common/messaging/OutboxEventRecorder.java — one per service; the only writer of the outbox table
+@ApplicationScoped
+public class OutboxEventRecorder {
+
+    private final OutboxSql outboxSql;          // common/messaging, Connection-first
+    private final ObjectMapper objectMapper;
+
+    @Inject
+    public OutboxEventRecorder(OutboxSql outboxSql, ObjectMapper objectMapper) { ... }
+
+    /** Captures `traceparent` + the payload's `traceContext` block from `Span.current()` itself,
+     *  wraps `event` in the standard envelope, and inserts on the caller's `Connection`. */
+    public UUID record(Connection conn, String aggregateType, String aggregateId,
+                       String eventType, String topic, Map<String, Object> event)
+            throws SQLException { ... }
+}
+```
+
+A `Handler` that hand-builds the envelope, or hand-reads `Span.current()` to make a `traceparent`, has copied the recorder's body — that is the same defect as a per-slice `insertOutboxEvent`, one layer up.
+
+That is the whole dual-write guarantee — one connection, one transaction, no port indirection. Nothing in the slice knows how the row reaches Kafka: `common/messaging` owns the single publish path (`OutboxDispatcher` + `OutboxRelayJob`) and it is the only code that talks to Kafka on the produce side.
 
-Fire-and-forget technical messages (metrics, notifications with no consistency requirement) MAY use a direct `Emitter`:
+Fire-and-forget technical messages (metrics, notifications with no consistency requirement) MAY use a direct `Emitter` — but it lives in a **`common/` capability bean**, never in a slice. `@Channel`/`Emitter` are `org.eclipse.microprofile.reactive.messaging` types, and the `handlerKnowsNoTransport` ArchUnit rule forbids them in a `Handler`:
 
 ```java
+// common/audit/AuditRecorder.java — the Handler injects AuditRecorder, not the Emitter
 @Inject @Channel("audit-out") Emitter<AuditEventPayload> audit;
 ```
 
+### Relay mode (property-driven, mandatory)
+
+The outbox row is **always** written in the transaction — that never depends on a flag. What a flag selects is *who publishes it*, so the same `Handler` code runs unchanged in every environment:
+
+```properties
+# debezium | poller | direct
+app.messaging.outbox.relay-mode=debezium
+```
+
+| Mode | Publisher | Use in |
+|---|---|---|
+| `debezium` | Debezium Outbox Event Router (Kafka Connect), out of process | prod / staging — the default |
+| `poller` | `OutboxRelayJob` `@Scheduled` inside the service | environments with Kafka but no Kafka Connect |
+| `direct` | `OutboxDispatcher` emits **after commit**, in process | local dev, integration tests, single-node deployments |
+
+`direct` is NOT a licence to dual-write: the row is committed first, the emit is deferred to a post-commit synchronization, and a lost emit is recovered by re-running in `poller` mode (`published_at IS NULL` is still the source of truth). An emit that never reaches Kafka must never fail `process()` — the caller already has a committed result, so the dispatcher logs the failure and leaves `published_at` null for the next relay to pick up; it does not rethrow and it does not build an error response (see quarkus-error-handling-i18n skill). All three modes wrap the emit in the `outbox.publish` span (see quarkus-observability-otel skill).
+
+```java
+@ConfigMapping(prefix = "app.messaging.outbox")
+public interface OutboxConfig {
+    @WithDefault("debezium") RelayMode relayMode();
+    enum RelayMode { DEBEZIUM, POLLER, DIRECT }
+}
+```
+
+**Single dispatch point.** `common/messaging` owns one `OutboxDispatcher`; it is the only code on the produce side that touches the `Emitter`, and it is a no-op unless the mode says otherwise:
+
+```java
+@ApplicationScoped
+public class OutboxDispatcher {
+
+    @Inject OutboxConfig config;
+    @Inject OutboxSql sql;                       // common/messaging own Sql, same Connection-first contract
+    @Inject DataSource dataSource;               // its own connection — the Handler's is closed by now
+    @Inject TransactionSynchronizationRegistry txRegistry;
+    @Inject @Channel("outbox-out") Emitter<JsonNode> emitter;
+
+    /** Called from execution(); the emit itself is deferred until the JTA transaction commits.
+        No-op unless relay-mode=direct. */
+    public void dispatchAfterCommit(UUID eventId) {
+        if (config.relayMode() != RelayMode.DIRECT) return;   // Debezium or the job will pick it up
+        txRegistry.registerInterposedSynchronization(new Synchronization() {
+            @Override public void beforeCompletion() { }
+            @Override public void afterCompletion(int status) {
+                if (status == Status.STATUS_COMMITTED) {       // rolled back → row never existed, nothing to emit
+                    sql.findUnpublished(eventId).ifPresent(OutboxDispatcher.this::publish);
+                }
+            }
+        });
+    }
+
+    void publish(OutboxRow row) {
+        emitter.send(Message.of(row.payload())
+            .addMetadata(OutgoingKafkaRecordMetadata.builder()
+                .withTopic(row.topic())                        // one channel, topic per event type
+                .withKey(row.aggregateId())
+                .withHeaders(new RecordHeaders()
+                    .add("traceparent", row.traceparent().getBytes(UTF_8)))
+                .build())
+            .addMetadata(OutgoingCloudEventMetadata.builder()
+                .withId(row.id().toString())
+                .withType(row.eventType())
+                .withSource(URI.create(SOURCE))
+                .withSubject(row.aggregateId())
+                .build())
+            .withAck(() -> markPublished(row.id())));          // published_at = now()
+    }
+}
+```
+
+The Handler never touches an `Emitter`, a topic or a Kafka header — it hands over an id and the dispatcher decides whether anything happens at all. `dispatchAfterCommit()` is safe to call from inside `execution()` precisely because it only *registers* a synchronization: nothing reaches Kafka until the container commits `process()`. Never call `publish()` from a slice.
+
+**Scheduler flag.** `OutboxRelayJob` is disabled by config expression, not by commenting code — Quarkus treats `off`/`disabled` as "do not schedule this method":
+
+```java
+@ApplicationScoped
+public class OutboxRelayJob {
+
+    @Inject OutboxDispatcher dispatcher;
+    @Inject OutboxSql sql;
+
+    @Scheduled(every = "${app.messaging.outbox.poller.every:off}",
+               concurrentExecution = ConcurrentExecution.SKIP)
+    void relay() {
+        sql.lockUnpublishedBatch(batchSize)   // SELECT ... FOR UPDATE SKIP LOCKED, ORDER BY created_at
+           .forEach(dispatcher::publish);     // ack callback sets published_at
+    }
+}
+```
+
+```properties
+# prod: Debezium owns the relay, the job never schedules
+app.messaging.outbox.relay-mode=debezium
+app.messaging.outbox.poller.every=off
+
+# %dev / %test: no Kafka Connect available
+%dev.app.messaging.outbox.relay-mode=direct
+%dev.app.messaging.outbox.poller.every=off
+
+# fallback environment: in-process poller
+%onprem.app.messaging.outbox.relay-mode=poller
+%onprem.app.messaging.outbox.poller.every=5s
+app.messaging.outbox.poller.batch-size=200
+
+# one outgoing channel for every event type; the topic comes from the outbox row.
+# Left configured and simply never used when relay-mode=debezium.
+mp.messaging.outgoing.outbox-out.connector=smallrye-kafka
+mp.messaging.outgoing.outbox-out.topic=alva.unrouted    # placeholder, always overridden per message
+mp.messaging.outgoing.outbox-out.cloud-events=true
+mp.messaging.outgoing.outbox-out.cloud-events-source=//alva/customer
+mp.messaging.outgoing.outbox-out.key.serializer=org.apache.kafka.common.serialization.StringSerializer
+mp.messaging.outgoing.outbox-out.value.serializer=io.quarkus.kafka.client.serialization.ObjectMapperSerializer
+```
+
+Per-event outgoing channels (`user-registered-out`, one channel per topic, as in the CloudEvents section above) remain valid for fire-and-forget technical messages. Domain events go through the single `outbox-out` channel — one channel, topic per message — so adding an event never means adding messaging config.
+
+Rules:
+- The three modes are **mutually exclusive by configuration** — `relay-mode=debezium` with a scheduled poller means two publishers and duplicate events. Validate at startup (`@Startup` observer: fail fast if `relayMode != POLLER` and `poller.every` is not `off`).
+- `ORDER BY created_at` + `SKIP LOCKED` in `poller`; multiple replicas are safe, per-entity ordering is preserved because the partition key is the aggregate id.
+- `published_at` is only maintained in `poller`/`direct`; in `debezium` mode the router deletes (or ignores) the row and the column stays null — do not build alerts on it without checking the mode.
+- `common/messaging` is **not** `common/client`: Mutiny stays quarantined there (hexagonal-core `reactiveIsQuarantined`). Use the MicroProfile `Emitter`, never `MutinyEmitter`.
+- `OutboxSql` is the one `Sql` class that lives in `common/` rather than a slice, and the one whose callers are not only `Handler`s — `OutboxEventRecorder` writes through it, and the dispatcher and the relay job own the `Connection` in the `Handler`'s place on the read/publish side. That exception is written into the `onlyHandlersTouchSql` ArchUnit rule (`resideInAPackage("..common.messaging..")`), not left for the build to discover.
+- Consumers are unaffected: the same CloudEvent lands on the same topic in all three modes. That is the contract the flag must not break — a contract test asserts headers/topic are identical between `direct` and Debezium output.
+
+**Debezium mode** maps outbox columns to the envelope in the connector, not in Java:
+
+```json
+"transforms": "outbox",
+"transforms.outbox.type": "io.debezium.transforms.outbox.EventRouter",
+"transforms.outbox.table.field.event.id": "id",
+"transforms.outbox.table.field.event.key": "aggregate_id",
+"transforms.outbox.table.field.event.type": "event_type",
+"transforms.outbox.table.field.event.payload": "payload",
+"transforms.outbox.table.fields.additional.placement": "traceparent:header",
+"transforms.outbox.route.by.field": "topic",
+"transforms.outbox.route.topic.replacement": "${routedByValue}"
+```
+
 ### Naming
 
 Canonical rules in the quarkus-hexagonal-core skill; messaging specifics:
@@ -109,8 +280,12 @@ Canonical rules in the quarkus-hexagonal-core skill; messaging specifics:
 |---|---|---|
 | Wire payload DTO | `<Event>Payload`, in the producing/consuming slice's `dto/` | `UserRegisteredPayload` |
 | Consumer | `<Event>Consumer`, in the slice folder | `UserRegisteredConsumer` |
-| Outbox write | a method on the slice's own `Sql` | `insertOutboxEvent(conn, ...)` |
+| Outbox write | `OutboxEventRecorder` in `common/messaging`, called by the slice `Handler` — **never** a per-slice `insertOutboxEvent` | `outbox.record(conn, ...)` |
+| Outbox table access | one `OutboxSql` in `common/messaging`, `Connection`-first | `insertOutboxEvent`, `findUnpublished`, `markPublished` |
 | Outbox relay job | `<Task>Job`, in `common/messaging` | `OutboxRelayJob` |
+| Outbox dispatcher | one per service, in `common/messaging` | `OutboxDispatcher` |
+| Relay-mode config | `@ConfigMapping` in `common/messaging` | `OutboxConfig.RelayMode` |
+| Generic outbox channel | single outgoing channel, dynamic topic | `outbox-out` |
 | SmallRye channel | `<entity>-<event>-in` / `-out`, kebab-case | `user-registered-in` |
 | CloudEvents `type` | `<javaPackageStyle>.<entity>.<event>.v<major>` | `com.alva.iam.user.registered.v1` |
 
@@ -158,8 +333,9 @@ Rules:
 ## Checklist for a new event
 
 1. Define `<Event>Payload` in the slice's `dto/` + its JSON Schema in `contracts/`; name the topic and channel per convention.
-2. Producer: `insertOutboxEvent` method on the slice's `Sql`, called from `Handler.execution()` on the shared `Connection`; relay config for `OutboxRelayJob`/Debezium.
-3. `@RegisterForReflection` on the payload; `traceparent` + `traceContext` captured from `Span.current()` at insert time.
-4. Consumer: `<Event>Consumer` in the slice folder delegating to the `Handler`, idempotency inside the transaction, DLQ topic + owner + alert, `@Blocking`.
-5. Contract test: serialize/deserialize round-trip against the JSON Schema.
-6. New error codes registered in `ErrorCatalog` and present in all locale bundles.
+2. Producer: `OutboxEventRecorder.record(conn, ...)` from `common/messaging`, called from `Handler.execution()` on the shared `Connection`, storing the resolved `topic`; the returned id goes to `OutboxDispatcher.dispatchAfterCommit()`. Do not add an `insertOutboxEvent` to the slice's `Sql` — the recorder is the only writer.
+3. Relay: set `app.messaging.outbox.relay-mode` per environment and keep `poller.every=off` in every mode but `poller`; register the Debezium routing config where the mode is `debezium`.
+4. `@RegisterForReflection` on the payload; `traceparent` + `traceContext` captured from `Span.current()` at insert time.
+5. Consumer: `<Event>Consumer` in the slice folder delegating to the `Handler`, idempotency inside the transaction, DLQ topic + owner + alert, `@Blocking`.
+6. Contract test: serialize/deserialize round-trip against the JSON Schema, plus identical topic/headers between `direct` and Debezium output.
+7. New error codes registered in `ErrorCatalog` and present in all locale bundles.

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

@@ -123,7 +123,7 @@ public class DigitalIdentityResource {
 
 Rules:
 - Return `RestResponse<T>` synchronously — typed, so the generated schema is right. Never `Uni`/`Multi`: the `Handler` is blocking JDBC.
-- `@Blocking` (`io.smallrye.common.annotation.Blocking`) on JDBC-backed methods. With a plain return type Quarkus REST already dispatches to a worker thread, so it is redundant today — keep it as an explicit threading contract that survives a later signature change. `@RunOnVirtualThread` is the high-concurrency alternative (see sql skill §7).
+- `@Blocking` (`io.smallrye.common.annotation.Blocking`) on JDBC-backed methods. With a plain return type Quarkus REST already dispatches to a worker thread, so it is redundant today — keep it as an explicit threading contract that survives a later signature change. `@RunOnVirtualThread` is the high-concurrency alternative (see sql skill §8).
 - Extract `tenantId`, `partyId`, `partyRolList`, `language` from headers where the contract requires them and set them on the request DTO before calling `process()`.
 - No `try/catch` around `process()`. Errors travel as `BusinessException` to `GlobalExceptionHandler`, which resolves the localized TMF Error body (see quarkus-error-handling-i18n skill).
 - `operationId` on every operation (client generation depends on it); match TMF naming (`listX`, `retrieveX`, `createX`, `patchX`, `deleteX`).

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

@@ -1,6 +1,6 @@
 ---
 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. 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.
+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)
@@ -9,7 +9,7 @@ Applies to any Quarkus backend project; project directives (CLAUDE.md, ADRs, exp
 
 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).
+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 §8).
 
 ## 1. Datasource configuration (Agroal)
 
@@ -78,7 +78,7 @@ Absolute rules:
 - 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.
-- Methods declare `throws SQLException` and never catch it — the `Handler` translates it (§8). No `commit`, `rollback` or `setAutoCommit` here, ever.
+- Methods declare `throws SQLException` and never catch it — the `Handler` translates it (§9). 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):
@@ -90,7 +90,7 @@ Naming (canonical rules in the quarkus-hexagonal-core skill):
 | 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` |
+| Technical exception | `PersistenceException` + specific subtypes (§9) | `TransientPersistenceException` |
 
 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`.
 
@@ -116,7 +116,7 @@ public class CreatePartyIndividualHandler {
             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());
+            outbox.record(conn, "party", partyId.toString(), EVENT_TYPE, TOPIC, eventMap(partyId, request));
             return partyId;
         } catch (SQLException e) {
             throw SqlStateTranslator.translate("PTY-500-001", e);      // unchecked -> container rolls back
@@ -129,7 +129,7 @@ public class CreatePartyIndividualHandler {
 
 - `@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.
+- 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 §9 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
@@ -166,7 +166,7 @@ public UUID insertParty(Connection conn, String tenantId, String partyType,
 - **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.
+- Upserts: `ON CONFLICT ... DO UPDATE` explicitly; never SELECT-then-INSERT races. A unique-violation (`23505`) surfacing as a `SQLException` is translated by the `Handler` (§9), not swallowed here.
 
 ## 5. Batches, pagination, jsonb
 
@@ -205,9 +205,22 @@ ps.setObject(5, pgo);
 
 Read side: `rs.getString("context")` then parse. Index jsonb lookups you actually query (`(context->>'trace_id')`).
 
-## 6. A tiny helper is allowed; a framework is not
+## 6. Cross-cutting tables get a cross-cutting `Sql`
 
-To kill boilerplate, ONE small internal helper class (~50 lines) per service or shared lib is the sanctioned maximum:
+One `Sql` class per slice is the rule for the slice's **own** tables. A table that every slice writes the same way — `outbox`, `audit_event`, `processed_event` — gets **one** `Sql` class in `common/`, and a `Connection`-first capability bean in front of it:
+
+| Table | Owner in `common/` | Called by |
+|---|---|---|
+| outbox | `OutboxSql` + `OutboxEventRecorder` (`common/messaging`) | slice `Handler`s, `OutboxDispatcher`, `OutboxRelayJob` |
+| audit_event | `AuditRecorder` (`common/audit`) | slice `Handler`s |
+
+The transactional guarantee is unaffected: these methods take the `Connection` the `Handler` already opened in `execution()`, so the row commits with the state change (§3). **Never copy `insertOutboxEvent` (or any other cross-cutting insert) onto a `<Slice>Sql`.** The columns are fixed by the migration and the envelope is fixed by the messaging standard, so every copy is identical by construction — and identical-by-construction code that is nonetheless written N times drifts: one slice grows a null-guard for a `NOT NULL` column, another falls behind a column addition, and nothing fails until the relay cannot route a row. The `duplicate twice, extract on the third` rule (hexagonal-core skill) is about code that might *turn out* to differ per slice; this cannot.
+
+This does not license a `common/` grab-bag: it applies to tables `common/` genuinely owns, not to a query two slices happen to share today.
+
+## 7. A tiny helper is allowed; a framework is not
+
+To kill boilerplate, ONE small internal helper class (~50 lines) per service or shared lib is the sanctioned maximum. (The cross-cutting owners of §6 are not helpers and do not count against this budget — they own a table, they do not generalize SQL.)
 
 ```java
 public final class Jdbc {   // common/util — the one sanctioned exception to the banned-suffix rule
@@ -225,7 +238,7 @@ Note the signatures take `Connection`, not `DataSource` — the helper must not
 - 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.
 
-## 7. Blocking model: worker threads or virtual threads (and when reactive)
+## 8. Blocking model: worker threads or virtual threads (and when reactive)
 
 JDBC blocks. Never run it on the event loop:
 
@@ -234,7 +247,7 @@ JDBC blocks. Never run it on the event loop:
 - **Virtual threads**: `@RunOnVirtualThread` on JDBC-heavy endpoints is the modern default for high-concurrency blocking work (Java 25 baseline; synchronized-block pinning is fixed since JDK 24) — cheap threads, same simple code. Caveat: keep pool `max-size` as the real ceiling; virtual threads make it easy to pile up on `acquisition-timeout`.
 - **Reactive SQL client** (`quarkus-reactive-pg-client`, Vert.x pool — NOT Agroal): only for measured hot paths (extreme fan-in, streaming thousands of rows). It's a different programming model and a second pool to size; adopting it in a service requires an ADR. Do not mix both models in the same repository class.
 
-## 8. SQLException translation
+## 9. SQLException translation
 
 `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:
 
@@ -256,11 +269,44 @@ Every resulting code is registered in `ErrorCatalog` and present in all locale b
 
 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
+## 10. Schema migrations (Flyway — opt-in, disabled by default)
+
+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.
+
+## 11. 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 (`quarkus.flyway.migrate-at-start=true`) — tests validate DDL and queries together.
+- 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 §10), 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 `Sql` method
@@ -273,3 +319,4 @@ Set `statement_timeout` (session or per-datasource via `quarkus.datasource.jdbc.
 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.
+8. The table belongs to this slice. If it is cross-cutting (`outbox`, `audit_event`, `processed_event`), the method belongs in `common/` (§6) — not here.

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.