bmad-method-quarkus 1.0.3 → 1.0.4

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

@@ -1,165 +0,0 @@
----
-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).
----
-
-# Kafka Messaging Standard (Quarkus + SmallRye Reactive Messaging)
-
-Events are the public contract between services (bounded contexts in DDD projects, but the standard applies to any Quarkus backend). Everything below is the default standard; a project directive (CLAUDE.md, ADR, explicit instruction) may override it — otherwise deviations require a change request.
-
-Extension: `quarkus-messaging-kafka` (SmallRye Reactive Messaging). Native-compatible out of the box; payload classes need `@RegisterForReflection`.
-
-## Topic naming
-
-```
-<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.
-- Version bumps ONLY on breaking schema changes; additive fields do not bump.
-- One entity type per topic. Partitioning key = entity id (guarantees per-entity ordering).
-
-## Event envelope: CloudEvents 1.0 (binary mode)
-
-Producers emit CloudEvents in **binary mode** (attributes as Kafka headers `ce_*`, payload = plain JSON body). SmallRye supports this natively:
-
-```properties
-mp.messaging.outgoing.user-registered.connector=smallrye-kafka
-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/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
-```
-
-Required attributes: `id` (UUID, = outbox event id), `source`, `type`, `time`, `subject` (entity id). Mandatory custom header: `traceparent` (W3C — propagated automatically when OTel is enabled, see observability skill).
-
-Payload schema:
-- JSON, documented as JSON Schema stored in a `contracts/` repo folder per topic version.
-- Payload = event facts, not full entity dumps. Include `entityId`, `occurredAt`, changed fields.
-
-## Producing: transactional outbox (mandatory for domain events)
-
-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).
-
-Standard outbox table (one per service):
-
-```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"
-  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
-);
-```
-
-**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
-{
-  "eventId": "evt-883920-a1",
-  "eventType": "ProductOrderStateChangeEvent",
-  "traceContext": {
-    "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
-    "span_id": "00f067aa0ba902b7"
-  },
-  "event": { "productOrder": { "id": "6a43...", "state": "Acknowledged" } }
-}
-```
-
-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:
-
-```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());
-        return partyId;
-    } catch (SQLException e) {
-        throw SqlStateTranslator.translate("PTY-500-001", e);
-    }
-}
-```
-
-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.
-
-Fire-and-forget technical messages (metrics, notifications with no consistency requirement) MAY use a direct `Emitter`:
-
-```java
-@Inject @Channel("audit-out") Emitter<AuditEventPayload> audit;
-```
-
-### Naming
-
-Canonical rules in the quarkus-hexagonal-core skill; messaging specifics:
-
-| Artifact | Convention | Example |
-|---|---|---|
-| 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` |
-| SmallRye channel | `<entity>-<event>-in` / `-out`, kebab-case | `user-registered-in` |
-| CloudEvents `type` | `<javaPackageStyle>.<entity>.<event>.v<major>` | `com.alva.iam.user.registered.v1` |
-
-`<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
-
-```java
-@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) {
-        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.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.iam.user.registered.v1.dlq
-```
-
-Rules:
-- **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.
-- Consumers validate against the payload's JSON Schema version; unknown additive fields are ignored (tolerant reader).
-
-## Ordering & delivery semantics
-
-- Per-entity ordering via partition key = aggregate id. No global ordering assumptions.
-- Exactly-once is NOT assumed; design consumers idempotent instead of enabling Kafka transactions by default.
-
-## 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.

package/src/bmm-skills/agents/bmad-quarkus-dev/skills/quarkus-observability-otel/SKILL.md

@@ -1,196 +0,0 @@
----
-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-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 → 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=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
-
-# W3C Trace Context + Baggage are the DEFAULT propagators — do not override with B3 unless mandated
-# quarkus.otel.propagators=tracecontext,baggage
-
-# Sampling: head-based ratio in prod, always_on elsewhere
-%prod.quarkus.otel.traces.sampler=parentbased_traceidratio
-%prod.quarkus.otel.traces.sampler.arg=0.10
-
-# Don't trace health/metrics noise
-quarkus.otel.traces.suppress-non-application-uris=true
-```
-
-Export to an **OTel Collector** (agent/sidecar/gateway), never directly to the vendor backend — keeps services vendor-neutral.
-
-## Logs: trace_id and span_id in every line
-
-Quarkus OTel injects `traceId`, `spanId`, `sampled` into the MDC automatically.
-
-Console (dev, human-readable):
-
-```properties
-%dev.quarkus.log.console.format=%d{HH:mm:ss} %-5p traceId=%X{traceId} spanId=%X{spanId} [%c{2.}] %s%e%n
-```
-
-Prod: JSON logs (parseable, ship to the log pipeline):
-
-```properties
-%prod.quarkus.log.console.json=true
-%prod.quarkus.log.console.json.additional-field."service.name".value=${quarkus.application.name}
-```
-
-`quarkus-logging-json` includes MDC (traceId/spanId) as fields — logs↔traces correlation in Grafana/Tempo/Loki works with zero code. Rule: NEVER log a business operation without going through JBoss Logging/`Log` — `System.out` breaks correlation.
-
-Also return the trace id to API callers for support tickets: a tiny response filter adds header `X-Trace-Id: ${Span.current().getSpanContext().getTraceId()}` on every response (especially errors — pairs with the unified exception handler).
-
-## Automatic instrumentation (free)
-
-With the extension present, these produce/propagate spans with no code:
-- HTTP server (Quarkus REST) and REST Client
-- gRPC server & client (metadata `traceparent`)
-- Kafka via SmallRye Reactive Messaging (header `traceparent`)
-- Agroal/JDBC: add `quarkus-opentelemetry-jdbc` wrapper (`quarkus.datasource.jdbc.telemetry=true`) for SQL spans
-
-## Mandatory: trace context extraction via the OTel SDK only
-
-It is **strictly prohibited** to build or parse trace strings by hand (no manual `00-...-...-01` concatenation, no UUID-based fake trace ids). The ONLY sanctioned way to obtain the active trace is the SDK injected by `quarkus-opentelemetry`:
-
-```java
-String traceId = Span.current().getSpanContext().getTraceId();
-String spanId  = Span.current().getSpanContext().getSpanId();
-```
-
-If `Span.current()` is invalid (no active trace — e.g., a batch job without instrumentation), fix the instrumentation of the entry point; do not fabricate ids.
-
-## Audit standard: `context` jsonb column in `audit_event`
-
-Every service with a local `audit_event` table persists the active trace in a `context` column of type `jsonb`:
-
-```sql
-ALTER TABLE audit_event ADD COLUMN IF NOT EXISTS context jsonb;
-CREATE INDEX IF NOT EXISTS idx_audit_event_trace_id
-ON audit_event ((context->>'trace_id'));
-```
-
-Stored value (snake_case keys, exactly these):
-
-```json
-{ "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736", "span_id": "00f067aa0ba902b7" }
-```
-
-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
-// common/audit — capability noun, no technology in the name, no interface
-@ApplicationScoped
-public class AuditRecorder {
-
-    private static final String INSERT_AUDIT = """
-        INSERT INTO audit_event (action, entity, entity_id, context)
-             VALUES (?, ?, ?, ?::jsonb)
-        """;
-
-    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();
-        String context = new JsonObject()
-            .put("trace_id", traceId)
-            .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();
-        }
-    }
-}
-```
-
-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.
-
-## Trace context through the outbox (async gap)
-
-The automatic Kafka instrumentation covers direct emits. The outbox breaks the chain — the standard requires the trace in TWO places (see quarkus-kafka-messaging skill):
-
-1. **Kafka header** `traceparent` (W3C format `00-<trace_id>-<span_id>-01`) for technical propagation — captured at outbox insert, forwarded by the relay (Debezium SMT or poller). Consumer side: SmallRye extracts it automatically → consumer spans join the original trace.
-2. **Inside the outbox `payload` jsonb**, a `traceContext` block for audit/immutability:
-
-```json
-"traceContext": { "trace_id": "...", "span_id": "..." }
-```
-
-Both values come from `Span.current()` at insert time — never from manual strings.
-
-## Custom spans and attributes
-
-Annotate the entry point of each slice — `Handler.process()` — not every method:
-
-```java
-// the slice's Handler — one span per business operation
-@Transactional
-@WithSpan("usecase.registerUser")
-public RegisterUserResponseDto process(RegisterUserRequestDto request) {
-    Span.current().setAttribute("user.email.domain", domainOf(request.getEmail()));
-    validate(request);
-    return getResult(execution(request));
-}
-```
-
-- 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.
-
-### Naming for telemetry artifacts
-
-Canonical class-naming rules live in the quarkus-hexagonal-core skill; these are the observability-specific ones:
-
-| Artifact | Convention | Example |
-|---|---|---|
-| Audit bean | `AuditRecorder` — one class in `common/audit`, no port | `AuditRecorder` |
-| Trace-id response filter | `<Purpose>Filter` | `TraceIdResponseFilter` |
-| 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 | `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.
-
-## Metrics (Micrometer)
-
-- Rely on built-in HTTP/JVM-substrate/Kafka metrics first.
-- 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
-
-`quarkus-smallrye-health`: `/q/health/live`, `/q/health/ready`. Readiness includes DB and Kafka checks (provided by extensions). These endpoints are excluded from tracing (see suppress config).
-
-## Checklist per service
-
-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) 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. 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-dev/skills/quarkus-openapi-tmforum/SKILL.md

@@ -1,145 +0,0 @@
----
-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 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)
-
-North-bound/external REST APIs follow TM Forum Open API conventions (TMF630 REST Design Guidelines). Internal service-to-service calls use gRPC (see quarkus-grpc-services skill) — do not build internal REST clients. Applies to any Quarkus backend project (TMF specs matter most in telco-facing APIs; the TMF630 conventions are good REST defaults everywhere); project directives override where they conflict.
-
-Extension: `quarkus-smallrye-openapi`.
-
-## Design-first with TMF specs
-
-1. If a TM Forum spec covers the capability (e.g., TMF632 Party, TMF672 User Roles & Permissions, TMF720 Digital Identity, TMF691 Federated ID, TMF696), START from the official TMF OpenAPI file: commit it to the monorepo `contracts/` folder (e.g. `contracts/tmf678-customer-bill.yaml` — the same folder the app's `service.yaml` references under `apis.provided[].contract`), trim to the operations actually implemented, and implement resources to match it. Do not invent alternative shapes for concepts TMF already models.
-2. Only for non-TMF internal concepts, design your own — still following TMF630 conventions below.
-3. The OpenAPI document is the contract: generate/verify in CI that the served `/q/openapi` matches the committed spec (store snapshot, diff on build).
-
-## Swagger UI: dev/test only (hard rule)
-
-```properties
-# default is already dev-only; NEVER set always-include=true in a prod profile
-quarkus.swagger-ui.always-include=false
-%test.quarkus.swagger-ui.always-include=true
-quarkus.smallrye-openapi.info-title=${quarkus.application.name}
-quarkus.smallrye-openapi.info-version=${quarkus.application.version}
-```
-
-The raw OpenAPI document at `/q/openapi` may stay enabled in prod behind the gateway if the platform team requires it; Swagger UI itself never ships in the native prod binary.
-
-## TMF630 conventions to enforce on every resource
-
-### 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 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 |
-|---|---|---|
-| List | `GET /resource` | 200 + array |
-| Retrieve | `GET /resource/{id}` | 200 |
-| Create | `POST /resource` | **201 + Location header + created body** |
-| Partial update | `PATCH /resource/{id}` (JSON Merge Patch, `application/merge-patch+json`) | 200 + updated body |
-| Delete | `DELETE /resource/{id}` | 204 |
-
-No PUT unless the TMF spec defines it. No RPC-ish URLs (`/user/activate`) — state changes go through PATCH of a state field or a TMF Task resource (`POST /resource/{id}/taskName` only when the spec defines the task pattern).
-
-### Query patterns (list operations)
-- **Attribute selection**: `?fields=id,name,status` — always support; huge payloads otherwise.
-- **Pagination**: `?offset=0&limit=20`; respond with headers `X-Total-Count`, `X-Result-Count`. Enforce a max limit.
-- **Filtering**: simple equality `?status=active&role=admin`; document supported filters per resource.
-
-### Resource body conventions
-- Every resource has `id` and `href`.
-- Polymorphism/extensibility fields where TMF-defined: `@type`, `@baseType`, `@schemaLocation`.
-- Dates ISO-8601 UTC (`OffsetDateTime` serialized as `2026-08-17T15:04:05Z`).
-- Errors: TMF Error schema from the unified handler (see quarkus-error-handling-i18n skill) — document it as the response for 4xx/5xx on every operation.
-
-## Annotating resources (SmallRye OpenAPI)
-
-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
-
-Canonical rules in the quarkus-hexagonal-core skill; REST/TMF specifics:
-
-| Artifact | Convention | Example |
-|---|---|---|
-| 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) | |
-| `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("/iam/tmf-api/digitalIdentityManagement/v4/digitalIdentity")
-@Tag(name = "DigitalIdentity")
-public class DigitalIdentityResource {
-
-    @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) {
-        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(@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 — *form* only; business rules live in `Handler.validate()`.
-
-## PATCH implementation (JSON Merge Patch)
-
-Consume `application/merge-patch+json`. Apply merge onto the current DTO representation, validate the result, map to an update command. Reject attempts to modify read-only fields (`id`, `href`, audit fields) with 400/409 per spec.
-
-## Checklist for a new endpoint
-
-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`).