bmad-method-quarkus 1.0.2 → 1.0.4

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 event, payload, consumer, publisher and channel naming conventions.
+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) 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)
@@ -12,9 +12,9 @@ Extension: `quarkus-messaging-kafka` (SmallRye Reactive Messaging). Native-compa
 ## Topic naming
 
 ```
-<org>.<module>.<entity>.<event-type>.v<major>     # <module> = BC code or service name
-alva.bc05.user.registered.v1
-alva.bc01.subscription.status-changed.v2
+<org>.<module>.<entity>.<event-type>.v<major>     # <module> = semantic module name (see quarkus-hexagonal-core skill)
+alva.iam.user.registered.v1
+alva.tenant.subscription.status-changed.v2
 ```
 
 - Kebab-case segments, past-tense event types.
@@ -27,10 +27,10 @@ Producers emit CloudEvents in **binary mode** (attributes as Kafka headers `ce_*
 
 ```properties
 mp.messaging.outgoing.user-registered.connector=smallrye-kafka
-mp.messaging.outgoing.user-registered.topic=alva.bc05.user.registered.v1
+mp.messaging.outgoing.user-registered.topic=alva.iam.user.registered.v1
 mp.messaging.outgoing.user-registered.cloud-events=true
-mp.messaging.outgoing.user-registered.cloud-events-source=//alva/bc05
-mp.messaging.outgoing.user-registered.cloud-events-type=com.alva.bc05.user.registered.v1
+mp.messaging.outgoing.user-registered.cloud-events-source=//alva/iam
+mp.messaging.outgoing.user-registered.cloud-events-type=com.alva.iam.user.registered.v1
 mp.messaging.outgoing.user-registered.value.serializer=io.quarkus.kafka.client.serialization.ObjectMapperSerializer
 ```
 
@@ -42,23 +42,24 @@ Payload schema:
 
 ## Producing: transactional outbox (mandatory for domain events)
 
-Never publish directly from a use case in the same breath as a DB write — dual-write problem. Standard:
+Never publish to Kafka in the same breath as a DB write — dual-write problem. Standard:
 
-1. Use case (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).
+1. The slice `Handler` (in the SAME JDBC transaction as the state change) inserts into the outbox table.
+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 §9):
 
 ```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.bc05.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)
 );
 ```
 
@@ -78,31 +79,189 @@ 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).
 
-The domain/application layer only knows an outbound port `EventPublisher.publish(DomainEvent e)`; the outbox insert is its JDBC adapter, `OutboxEventPublisher` in `infrastructure/messaging`.
+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. (`OutboxDispatcher` below is not that port — it publishes nothing in the default mode and never appears in the event's write path.)
 
-Fire-and-forget technical messages (metrics, notifications with no consistency requirement) MAY use a direct `Emitter`:
+```java
+private UUID execution(CreatePartyIndividualRequestDto request) {
+    try (Connection conn = dataSource.getConnection()) {
+        UUID partyId = sql.insertParty(conn, ...);
+        UUID eventId = sql.insertOutboxEvent(conn, partyId, "party",
+            "com.alva.customer.party.created.v1", "alva.customer.party.created.v1",
+            payloadJson(partyId, request), traceparent());
+        dispatcher.dispatchAfterCommit(eventId);   // no-op unless relay-mode=direct (see Relay mode)
+        return partyId;
+    } catch (SQLException e) {
+        throw SqlStateTranslator.translate("PTY-500-001", e);
+    }
+}
+```
+
+`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. `OutboxDispatcher` is injected in the Handler's `common/` bean slot, next to `dataSource` and `sql`.
+
+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` — 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 whose callers are not a `Handler` — the dispatcher and the job own the `Connection` in its place. That exception is written into the `onlyHandlersTouchSql` ArchUnit rule, 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:
 
 | Artifact | Convention | Example |
 |---|---|---|
-| Domain event | past tense, no suffix, in `domain/event` | `UserRegistered` |
-| Wire payload DTO | `<Event>Payload`, in `infrastructure/messaging/dto` | `UserRegisteredPayload` |
-| Outbound port | `EventPublisher` (capability, no technology) | |
-| Publisher adapter | `Outbox<Port>` / `Kafka<Port>` | `OutboxEventPublisher` |
-| Consumer | `<Event>Consumer` | `UserRegisteredConsumer` |
-| Outbox relay job | `<Task>Job` | `OutboxRelayJob` |
-| Event ↔ payload mapper | `<Entity>EventMapper` | `UserEventMapper` |
+| 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 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.bc05.user.registered.v1` |
+| CloudEvents `type` | `<javaPackageStyle>.<entity>.<event>.v<major>` | `com.alva.iam.user.registered.v1` |
 
-Keep the domain event (`UserRegistered`) and the wire payload (`UserRegisteredPayload`) as separate classes even when their fields match: the domain event is free to change with the model, while the payload is a published contract versioned by topic. Never annotate the domain event with Jackson or `@RegisterForReflection` — that annotation belongs on the payload.
+`<Event>Payload` is the **only** event class: there is no separate in-memory domain event, because the slice has no domain layer to protect it from. The payload is a published contract versioned by topic — treat a field rename as a breaking change and bump the topic version, never "because the model moved". It carries `@RegisterForReflection` for native. There is no `*EventMapper`: the payload is built in the `Handler`, the same place `getResult()` builds the response.
 
 ## Consuming
 
@@ -110,25 +269,29 @@ Keep the domain event (`UserRegistered`) and the wire payload (`UserRegisteredPa
 @ApplicationScoped
 public class UserRegisteredConsumer {
 
+    @Inject RegisterUserFromEventHandler handler;   // the slice's business logic
+
     @Incoming("user-registered-in")
     @Blocking            // JDBC inside → run on worker thread (or virtual thread)
-    public void on(UserRegisteredPayload payload) {   // wire DTO, not the domain event
-        // 1. idempotency check  2. delegate to use case  3. done
+    public void on(UserRegisteredPayload payload) {
+        handler.process(toRequest(payload));        // idempotency + side effects, one transaction
     }
 }
 ```
 
+The consumer is as thin as a `Resource`: deserialize, convert to the slice's request DTO, call `process()`. **The idempotency check belongs inside `Handler.execution()`**, not here — it must share the transaction with the side effects, and only the Handler owns the `Connection`. For explicit ack/nack, take `Message<UserRegisteredPayload>` and return `message.ack()` / `message.nack(e)`; do not catch `BusinessException` to build your own error response.
+
 ```properties
 mp.messaging.incoming.user-registered-in.connector=smallrye-kafka
-mp.messaging.incoming.user-registered-in.topic=alva.bc05.user.registered.v1
+mp.messaging.incoming.user-registered-in.topic=alva.iam.user.registered.v1
 mp.messaging.incoming.user-registered-in.group.id=${quarkus.application.name}
 mp.messaging.incoming.user-registered-in.auto.offset.reset=earliest
 mp.messaging.incoming.user-registered-in.failure-strategy=delayed-retry-then-dead-letter-queue
-mp.messaging.incoming.user-registered-in.dead-letter-queue.topic=alva.bc05.user.registered.v1.dlq
+mp.messaging.incoming.user-registered-in.dead-letter-queue.topic=alva.iam.user.registered.v1.dlq
 ```
 
 Rules:
-- **Idempotency is mandatory**: `processed_event(consumer_group, event_id)` table checked/inserted in the same transaction as the side effects. Kafka is at-least-once; duplicates WILL happen.
+- **Idempotency is mandatory**: `processed_event(consumer_group, event_id)` checked/inserted through the slice's `Sql` on the same `Connection`, in the same transaction as the side effects. Kafka is at-least-once; duplicates WILL happen.
 - Consumer group = service name; stable across deployments.
 - Failure strategy: bounded retries with delay, then DLQ topic `<topic>.dlq`. DLQ messages keep original headers plus `dead-letter-reason`. A DLQ must have an owner and an alert — never a silent graveyard.
 - Poison-pill safety: deserialization failures also route to DLQ (`...deserialization-failure-handler` or failure strategy), never block the partition.
@@ -141,8 +304,10 @@ Rules:
 
 ## Checklist for a new event
 
-1. Define `<Event>Payload` record + JSON Schema in `contracts/`, name the topic and channel per convention.
-2. Producer: outbox insert in use-case transaction; relay config.
-3. `@RegisterForReflection` on the payload record (never on the domain event).
-4. Consumer(s): idempotency table entry, DLQ topic + alert, `@Blocking` if JDBC.
-5. Contract test: serialize/deserialize round-trip against the JSON Schema.
+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`, storing the resolved `topic`; `process()` passes the returned id to `OutboxDispatcher.dispatchAfterCommit()`.
+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-observability-otel/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: quarkus-observability-otel
-description: Observability standard for Quarkus native services using OpenTelemetry — distributed tracing with W3C Trace Context (traceparent), trace_id/span_id in every log line (JSON logs + MDC), OTLP export, metrics with Micrometer, custom spans, and trace propagation across REST, gRPC, and Kafka. Use this skill whenever the user mentions OpenTelemetry, OTel, tracing, trace_id, span_id, traceparent, distributed tracing, logging standard, log correlation, metrics, Grafana/Tempo/Jaeger/Prometheus, or debugging requests across services. Includes span, metric, logger and audit-adapter naming conventions.
+description: Observability standard for Quarkus native services using OpenTelemetry — distributed tracing with W3C Trace Context (traceparent), trace_id/span_id in every log line (JSON logs + MDC), OTLP export, metrics with Micrometer, custom spans, and trace propagation across REST, gRPC, and Kafka. Use this skill whenever the user mentions OpenTelemetry, OTel, tracing, trace_id, span_id, traceparent, distributed tracing, logging standard, log correlation, metrics, Grafana/Tempo/Jaeger/Prometheus, or debugging requests across services. Includes span, metric, logger and audit-bean naming conventions for the vertical-slice layout (one span per Handler.process()).
 ---
 
 # OpenTelemetry Observability Standard (Quarkus)
 
-Every request must be traceable end-to-end: REST → use case → JDBC → outbox → Kafka → consumer → gRPC. `trace_id`/`span_id` appear in every log line and propagate across every transport via W3C Trace Context. Applies to any Quarkus backend project; project directives (CLAUDE.md, ADRs, explicit instructions) override these defaults.
+Every request must be traceable end-to-end: REST → Handler → JDBC → outbox → Kafka → consumer → gRPC. `trace_id`/`span_id` appear in every log line and propagate across every transport via W3C Trace Context. Applies to any Quarkus backend project; project directives (CLAUDE.md, ADRs, explicit instructions) override these defaults.
 
 Extensions: `quarkus-opentelemetry` (+ `quarkus-micrometer-registry-prometheus` or Micrometer→OTLP for metrics, `quarkus-logging-json` for structured logs). All native-compatible.
 
 ## Baseline configuration
 
 ```properties
-quarkus.application.name=bc05-users            # becomes service.name
+quarkus.application.name=iam-users             # becomes service.name
 quarkus.otel.exporter.otlp.endpoint=http://otel-collector:4317
 quarkus.otel.resource.attributes=deployment.environment=${ENV:dev},service.namespace=alva
 
@@ -85,35 +85,43 @@ Stored value (snake_case keys, exactly these):
 { "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736", "span_id": "00f067aa0ba902b7" }
 ```
 
-Reference implementation. The application layer depends on an outbound port `AuditRecorder` (`application/port/out`); capturing the active span is an infrastructure concern, so it happens in the adapter:
+Reference implementation. Auditing is cross-cutting, so it is a single capability-named bean in `common/audit` — no port, no adapter pair. It captures the active span itself and takes the caller's `Connection` so the audit row joins the caller's transaction:
 
 ```java
-// application/port/out — capability noun, no technology in the name
-public interface AuditRecorder {
-    void record(String action, String entity, String entityId);
-}
-
-// infrastructure/persistence — Jdbc<Port>
+// common/audit — capability noun, no technology in the name, no interface
 @ApplicationScoped
-public class JdbcAuditRecorder implements AuditRecorder {
+public class AuditRecorder {
 
-    private final AuditEventRepository repository;
+    private static final String INSERT_AUDIT = """
+        INSERT INTO audit_event (action, entity, entity_id, context)
+             VALUES (?, ?, ?, ?::jsonb)
+        """;
 
-    public JdbcAuditRecorder(AuditEventRepository repository) { this.repository = repository; }
-
-    @Override
-    public void record(String action, String entity, String entityId) {
+    public void record(Connection conn, String action, String entity, String entityId) throws SQLException {
         String traceId = Span.current().getSpanContext().getTraceId();
         String spanId  = Span.current().getSpanContext().getSpanId();
-        JsonObject context = new JsonObject()
+        String context = new JsonObject()
             .put("trace_id", traceId)
-            .put("span_id", spanId);
-        repository.save(action, entity, entityId, context.encode());
+            .put("span_id", spanId)
+            .encode();
+        try (PreparedStatement ps = conn.prepareStatement(INSERT_AUDIT)) {
+            ps.setString(1, action);
+            ps.setString(2, entity);
+            ps.setString(3, entityId);
+            ps.setString(4, context);
+            ps.executeUpdate();
+        }
     }
 }
 ```
 
-Identifiers are English (`record`, `action`, `entity`), even when the business vocabulary and the UI are Spanish — Spanish belongs in the i18n bundles, not in class and method names. `*Service` is not used here: this is an outbound adapter, not a use case.
+The slice `Handler` calls it from `execution()` on the same `Connection` it already holds, so an audit row can never survive a rolled-back operation:
+
+```java
+audit.record(conn, "CREATE", "party", partyId.toString());
+```
+
+Identifiers are English (`record`, `action`, `entity`), even when the business vocabulary and the UI are Spanish — Spanish belongs in the message bundles, not in class and method names. `*Service` is not used here: under the slice standard that suffix is reserved for `*GrpcService`.
 
 Any code path that writes `audit_event` without populating `context` is non-compliant — flag it in review.
 
@@ -132,15 +140,23 @@ Both values come from `Span.current()` at insert time — never from manual stri
 
 ## Custom spans and attributes
 
-Annotate use cases that matter for diagnosis (not every method):
+Annotate the entry point of each slice — `Handler.process()` — not every method:
 
 ```java
-// application/usecase — RegisterUserService implements RegisterUserUseCase
+// the slice's Handler — one span per business operation
+@Transactional
 @WithSpan("usecase.registerUser")
-public UserId register(@SpanAttribute("user.email.domain") String emailDomain, RegisterUserCommand cmd) { ... }
+public RegisterUserResponseDto process(RegisterUserRequestDto request) {
+    Span.current().setAttribute("user.email.domain", domainOf(request.getEmail()));
+    validate(request);
+    return getResult(execution(request));
+}
 ```
 
-- Span names: `usecase.<verb><Entity>` (lowerCamelCase, matching the use-case method), `outbox.publish`, `job.<name>`.
+- Span names: `usecase.<sliceCamelCase>` (lowerCamelCase). Because a slice is named verb+entity (`register_user`), this is identical to the older `usecase.<verb><Entity>` convention — existing dashboards keep working.
+- **`process()` is the span boundary.** One span per business operation; do not annotate `validate()`/`execution()`/`getResult()` (they are private, so the interceptor would not fire anyway). JDBC spans come free from `quarkus.datasource.jdbc.telemetry=true`.
+- Other span names: `outbox.publish`, `job.<name>`.
+- Attributes are set inside `process()` via `Span.current().setAttribute(...)` — never by adding `@SpanAttribute` parameters, which would change the `process(RequestDto)` single-argument signature that every transport adapter and the Handler contract depend on (see quarkus-hexagonal-core skill).
 - Attributes: business-relevant, LOW-cardinality, NEVER PII (no emails, MSISDNs, tokens — use derived/hashed values).
 - Manual spans (`Tracer.spanBuilder`) only for background work not covered by annotations; always `try/finally` end the span and restore scope.
 
@@ -150,12 +166,12 @@ Canonical class-naming rules live in the quarkus-hexagonal-core skill; these are
 
 | Artifact | Convention | Example |
 |---|---|---|
-| Audit port / adapter | `AuditRecorder` / `Jdbc<Port>` | `AuditRecorder`, `JdbcAuditRecorder` |
+| Audit bean | `AuditRecorder` — one class in `common/audit`, no port | `AuditRecorder` |
 | Trace-id response filter | `<Purpose>Filter` | `TraceIdResponseFilter` |
-| Span name | `usecase.<verb><Entity>`, `outbox.publish`, `job.<name>` | `usecase.registerUser` |
+| Span name | `usecase.<sliceCamelCase>` on `Handler.process()`, `outbox.publish`, `job.<name>` | `usecase.registerUser` |
 | Span attribute | dotted lowercase, OTel semconv where one exists | `user.email.domain` |
-| Metric | `<module>_<entity>_<action>_total` / `_seconds`, snake_case | `bc05_user_registrations_total` |
-| Logger | one per class via `Log`/`Logger.getLogger(Xxx.class)` — never a shared `LogUtil` | |
+| Metric | `<module>_<entity>_<action>_total` / `_seconds`, snake_case | `iam_user_registrations_total` |
+| Logger | one per class via `Log`/`Logger.getLogger(Xxx.class)` — never a shared `LogUtil`; the Handler's class name already carries the slice | |
 | MDC / jsonb trace keys | `snake_case`, exactly `trace_id` / `span_id` | |
 
 Span, metric and log-field names are a contract with the dashboards — renaming one silently breaks alerts. Treat a rename like an API change.
@@ -163,7 +179,7 @@ Span, metric and log-field names are a contract with the dashboards — renaming
 ## Metrics (Micrometer)
 
 - Rely on built-in HTTP/JVM-substrate/Kafka metrics first.
-- Custom business metrics: counters/timers via `MeterRegistry`, names `bc05_user_registrations_total` style, low-cardinality tags only.
+- Custom business metrics: counters/timers via `MeterRegistry`, names `iam_user_registrations_total` style, low-cardinality tags only.
 - Expose `/q/metrics` for Prometheus scrape or bridge Micrometer→OTLP if the platform standardizes on the collector for metrics too.
 
 ## Health
@@ -174,7 +190,7 @@ Span, metric and log-field names are a contract with the dashboards — renaming
 
 1. `quarkus-opentelemetry` + JSON logging configured as above; OTLP → collector.
 2. Log format includes traceId/spanId (both profiles); `X-Trace-Id` response filter registered.
-3. JDBC telemetry enabled; `audit_event.context` jsonb populated with `trace_id`/`span_id` (+ index); outbox rows carry `traceparent` (header) AND `traceContext` in payload; the relay forwards the header.
+3. JDBC telemetry enabled; `audit_event.context` jsonb populated with `trace_id`/`span_id` (+ index) on the Handler's own `Connection`; outbox rows carry `traceparent` (header) AND `traceContext` in payload; the relay forwards the header.
    3b. No manual trace-string construction anywhere — grep-check in review; only `Span.current()` via the OTel SDK.
-4. Key use cases annotated `@WithSpan`; attributes reviewed for PII/cardinality.
+4. Every slice `Handler.process()` annotated `@WithSpan("usecase.<sliceCamelCase>")`; attributes reviewed for PII/cardinality.
 5. Verify end-to-end in dev: one request produces a single trace spanning REST → DB → Kafka → consumer (Dev UI or Jaeger/Tempo).

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

@@ -1,6 +1,6 @@
 ---
 name: quarkus-openapi-tmforum
-description: API design and documentation standard for Quarkus REST services — OpenAPI 3.1 via SmallRye, Swagger UI restricted to dev/test, and full alignment with TM Forum Open API specifications (TMF630 design guidelines, TMF resource patterns, Error schema, pagination, filtering, JSON Merge Patch). Use this skill whenever the user mentions Swagger, OpenAPI, API documentation, REST API design, TMF/TM Forum APIs, endpoints/resources naming, pagination, PATCH semantics, or creates/reviews ANY REST resource class. Includes resource, DTO, mapper and operationId naming conventions.
+description: API design and documentation standard for Quarkus REST services — OpenAPI 3.1 via SmallRye, Swagger UI restricted to dev/test, and full alignment with TM Forum Open API specifications (TMF630 design guidelines, TMF resource patterns, Error schema, pagination, filtering, JSON Merge Patch). Use this skill whenever the user mentions Swagger, OpenAPI, API documentation, REST API design, TMF/TM Forum APIs, endpoints/resources naming, pagination, PATCH semantics, or creates/reviews ANY REST resource class. Includes resource, DTO and operationId naming conventions for the vertical-slice layout (the Resource class lives in the slice folder and delegates to the slice Handler; there are no REST mappers).
 ---
 
 # OpenAPI + TM Forum API Standard (Quarkus)
@@ -31,7 +31,7 @@ The raw OpenAPI document at `/q/openapi` may stay enabled in prod behind the gat
 
 ### URLs & versioning
 - Plural kebab-free camelCase resource names as in TMF specs: `/user`, `/partyAccount` — follow the TMF spec exactly when implementing one; plural nouns for custom resources.
-- Base path: `/{context}/{apiName}/v{major}` e.g. `/tmf-api/digitalIdentityManagement/v4`. Major version in path only.
+- Base path starts with the module's semantic name (`iam`, `tenant` — see quarkus-hexagonal-core skill, never a `bcNN` code): `/{module}/{context}/{apiName}/v{major}` e.g. `/iam/tmf-api/digitalIdentityManagement/v4`. Major version in path only.
 
 ### Standard operations
 | Operation | Verb | Response |
@@ -57,7 +57,9 @@ No PUT unless the TMF spec defines it. No RPC-ish URLs (`/user/activate`) — st
 
 ## Annotating resources (SmallRye OpenAPI)
 
-DTOs live in `infrastructure/rest/dto` — never annotate domain classes.
+DTOs live in the slice's own `dto/` package (`<slice_folder>/dto/*Dto.java`) — see quarkus-hexagonal-core skill. There is no separate domain class to protect: the DTO **is** the wire contract, so annotate it freely, and keep business logic out of it.
+
+The `Resource` class lives in the slice folder alongside the `Handler` it fronts, and does exactly three things: extract headers/params, call `handler.process(...)`, shape the response. It never catches `BusinessException` (the global handler owns that) and never touches JDBC.
 
 ### Naming
 
@@ -65,55 +67,69 @@ Canonical rules in the quarkus-hexagonal-core skill; REST/TMF specifics:
 
 | Artifact | Convention | Example |
 |---|---|---|
-| Resource class | `<Resource>Resource` — matches the TMF resource name | `DigitalIdentityResource` |
-| Response DTO | `<Resource>Dto` | `DigitalIdentityDto` |
+| Resource class | `<Resource>Resource` — matches the TMF resource name, lives in the slice folder | `DigitalIdentityResource` |
+| Response DTO | `<Resource>Dto`, or `${SERVICE_CLASS_PREFIX}ResponseDto` for a slice-specific shape | `DigitalIdentityDto` |
 | Create / update DTO | `<Resource>CreateDto` / `<Resource>UpdateDto` (TMF `X_Create` / `X_Update`) | `DigitalIdentityCreateDto` |
+| Request DTO (non-TMF) | `${SERVICE_CLASS_PREFIX}RequestDto` | `CreatePartyIndividualRequestDto` |
 | Error DTO | `ErrorDto` (see quarkus-error-handling-i18n skill) | |
-| DTO ↔ domain mapper | `<Resource>RestMapper` | `DigitalIdentityRestMapper` |
 | `operationId` | `list/retrieve/create/patch/delete` + `<Resource>` | `listDigitalIdentity` |
 | Path segment | camelCase, exactly as the TMF spec spells it | `/partyAccount` |
 | JSON field | camelCase; TMF meta-fields keep their `@` | `@type`, `@baseType` |
 
+There is **no `*RestMapper` class** — the DTO↔internal conversion is the `Handler`'s `getResult()` (see quarkus-hexagonal-core skill), and `*Mapper` is a banned suffix. When a TMF spec prescribes `X_Create`/`X_Update`, those names win over the generic `RequestDto`; use the generic form only for non-TMF operations.
+
+**One Resource per TMF resource, or one per slice?** When several slices serve the same TMF path, the default is one `Resource` class per TMF resource that injects each slice's `Handler` — JAX-RS path resolution stays unambiguous and the OpenAPI tag stays clean. One class per slice sharing a base `@Path` also works in Quarkus REST provided no two classes declare the same method+sub-path; the `/q/openapi` snapshot test below is what catches a collision.
+
 When implementing a TMF spec the wire names are **not negotiable** — DTO field names must match the spec even where our own convention would differ. The Java class name adds the `Dto` suffix; the serialized schema name stays the TMF one (`@Schema(name = "DigitalIdentity")`).
 
 ```java
-@Path("/tmf-api/digitalIdentityManagement/v4/digitalIdentity")
+@Path("/iam/tmf-api/digitalIdentityManagement/v4/digitalIdentity")
 @Tag(name = "DigitalIdentity")
 public class DigitalIdentityResource {
 
-    private final CreateDigitalIdentityUseCase createIdentity;   // inbound port
-    private final DigitalIdentityRestMapper mapper;
-
-    public DigitalIdentityResource(CreateDigitalIdentityUseCase createIdentity,
-                                   DigitalIdentityRestMapper mapper) {
-        this.createIdentity = createIdentity;
-        this.mapper = mapper;
-    }
+    @Inject CreateDigitalIdentityHandler createHandler;   // the slice's business logic
+    @Inject FindDigitalIdentityHandler findHandler;
 
     @GET
+    @Blocking
     @Operation(operationId = "listDigitalIdentity", summary = "List or find DigitalIdentity objects")
     @APIResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = DigitalIdentityDto[].class)))
     @APIResponse(responseCode = "400", ref = "#/components/responses/BadRequest")
     public RestResponse<List<DigitalIdentityDto>> list(
+            @HeaderParam("tenantId") String tenantId,
             @QueryParam("fields") String fields,
             @QueryParam("offset") @DefaultValue("0") int offset,
-            @QueryParam("limit") @DefaultValue("20") int limit) { ... }
+            @QueryParam("limit") @DefaultValue("20") int limit) {
+        var query = FilterDigitalIdentityDto.builder()
+            .tenantId(tenantId).fields(fields).offset(offset).limit(limit).build();
+        return RestResponse.ok(findHandler.process(query).getItems());
+    }
 
     @POST
+    @Blocking
     @Operation(operationId = "createDigitalIdentity")
     @APIResponse(responseCode = "201", headers = @Header(name = "Location"))
-    public RestResponse<DigitalIdentityDto> create(@Valid DigitalIdentityCreateDto dto, @Context UriInfo uri) {
-        var created = createIdentity.create(mapper.toCommand(dto));
-        return RestResponse.created(uri.getAbsolutePathBuilder().path(created.id()).build());
+    public RestResponse<DigitalIdentityDto> create(@HeaderParam("tenantId") String tenantId,
+                                                   @Valid DigitalIdentityCreateDto dto,
+                                                   @Context UriInfo uri) {
+        dto.setTenantId(tenantId);
+        var created = createHandler.process(dto);              // BusinessException propagates to the global handler
+        return RestResponse.ResponseBuilder
+            .created(uri.getAbsolutePathBuilder().path(created.getId()).build())
+            .entity(created).build();
     }
 }
 ```
 
 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).
+- 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`).
 - Reusable components: define common responses (400/401/404/409/500 with TMF Error schema) once via an `@OpenAPIDefinition`/filter class, `ref` them everywhere.
 - `*CreateDto` (no id/href) vs full DTO — TMF pattern (`X_Create`, `X_Update`).
-- Bean Validation on DTOs (`@NotNull`, `@Size`) so constraints appear in the schema.
+- Bean Validation on DTOs (`@NotNull`, `@Size`) so constraints appear in the schema — *form* only; business rules live in `Handler.validate()`.
 
 ## PATCH implementation (JSON Merge Patch)
 
@@ -121,8 +137,9 @@ Consume `application/merge-patch+json`. Apply merge onto the current DTO represe
 
 ## Checklist for a new endpoint
 
-1. TMF spec exists? Copy & trim official OpenAPI, implement to match.
-2. `<Resource>Resource` class with full annotations + operationIds; `<Resource>Dto` / `<Resource>CreateDto` with validation + `@RegisterForReflection`.
-3. Error responses referenced to the shared TMF Error components.
-4. fields/offset/limit on list operations; Location header on create.
-5. Snapshot test: `/q/openapi` diff against committed contract.
+1. TMF spec exists? Copy & trim official OpenAPI into `contracts/`, implement to match.
+2. `<Resource>Resource` class in the slice folder with full annotations + operationIds, `@Blocking`, injecting the slice `Handler`; DTOs in `<slice>/dto` with validation + `@RegisterForReflection`.
+3. Error responses referenced to the shared TMF Error components — and no `try/catch` in the resource.
+4. fields/offset/limit on list operations; `Location` header on create; 201 on create, 204 on delete.
+5. Snapshot test: `/q/openapi` diff against the committed contract (also catches a `@Path` collision between slices).
+6. `@QuarkusTest` + REST Assured covering one success and one localized error body (`Accept-Language: es`).