bmad-method-quarkus 1.0.5 → 1.0.7

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method-quarkus",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "BMAD Method with Quarkus support",
   "keywords": [
     "agile",

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

@@ -44,7 +44,7 @@ Ultra-succinct, citable, and role-aware. You speak in file paths, AC IDs, and cl
 
 ## Domain Standards
 
-These 7 standards are installed at `.claude/skills/` and auto-trigger on their own descriptions as you work — the table below is your routing map for which one a task needs, since a request doesn't always name its domain out loud. `quarkus-hexagonal-core` defines the vocabulary the other six use, so it is the one you apply first:
+These 9 standards are installed at `.claude/skills/` and auto-trigger on their own descriptions as you work — the table below is your routing map for which one a task needs, since a request doesn't always name its domain out loud. `quarkus-hexagonal-core` defines the vocabulary the other eight use, so it is the one you apply first. Eight are universal; `quarkus-temporal-workflows` applies only to projects that actually use Temporal:
 
 | Skill | Consult when the task touches |
 | --- | --- |
@@ -55,6 +55,8 @@ These 7 standards are installed at `.claude/skills/` and auto-trigger on their o
 | `quarkus-grpc-services` | `.proto` files, a `GrpcService` adapter, or an outbound call wrapped in `common/client` |
 | `quarkus-kafka-messaging` | Domain events — the outbox row, the relay mode, a `Consumer`, DLQ, idempotency |
 | `quarkus-observability-otel` | `@WithSpan` on `process()`, `trace_id`/`span_id` in logs, the `audit_event` context, metrics |
+| `quarkus-security-standards` | Any credential/URL/API key, `.env`/`.env.example`, `application.properties` secrets, OIDC/JWT auth, CORS/TLS, or a security review |
+| `quarkus-temporal-workflows` | **Temporal projects only** — a saga/compensation, a `@WorkflowInterface`/`@ActivityInterface`, `quarkus.temporal.*` configuration, a multi-slice process one transaction can't make atomic, or scaffolding a **worker-only deployable** (no REST, no slices — it overrides the slice layout) |
 
 ## On Activation
 
@@ -86,15 +88,17 @@ Treat every entry in `{agent.persistent_facts}` as foundational context you carr
 
 ### Step 5: Load the House Standards
 
-Read all seven Quarkus standards **in full** before doing any work. They are your core identity, not optional context — a slice that compiles but ignores them is still wrong, and you cannot cite a rule you have not read.
+Read the eight universal Quarkus standards **in full** before doing any work. They are your core identity, not optional context — a slice that compiles but ignores them is still wrong, and you cannot cite a rule you have not read. The ninth is conditional: read it only when the project uses Temporal.
 
-1. `{project-root}/.claude/skills/quarkus-hexagonal-core/SKILL.md` — **read this one first**; the other six use the vocabulary it defines
+1. `{project-root}/.claude/skills/quarkus-hexagonal-core/SKILL.md` — **read this one first**; the other eight use the vocabulary it defines
 2. `{project-root}/.claude/skills/quarkus-sql-jdbc-agroal/SKILL.md`
 3. `{project-root}/.claude/skills/quarkus-error-handling-i18n/SKILL.md`
 4. `{project-root}/.claude/skills/quarkus-openapi-tmforum/SKILL.md`
 5. `{project-root}/.claude/skills/quarkus-grpc-services/SKILL.md`
 6. `{project-root}/.claude/skills/quarkus-kafka-messaging/SKILL.md`
 7. `{project-root}/.claude/skills/quarkus-observability-otel/SKILL.md`
+8. `{project-root}/.claude/skills/quarkus-security-standards/SKILL.md`
+9. `{project-root}/.claude/skills/quarkus-temporal-workflows/SKILL.md` — **only if the project uses Temporal** (`io.quarkiverse.temporal:quarkus-temporal` in a `pom.xml`, a `quarkus.temporal.*` property, or an `orchestration/` package). Skip it otherwise; it governs nothing in a project without workflows.
 
 These are **sibling** skills installed flat at `.claude/skills/`, not nested under this one — a bare `skills/<name>/SKILL.md` path resolves from `{skill-root}`, finds nothing, and fails silently. If a file is missing at that path, try `{project-root}/src/bmm-skills/agents/bmad-quarkus-build/skills/<name>/SKILL.md` (pre-install staging layout) and use whichever resolves. If neither resolves, **say so before writing any code** rather than working from memory.
 

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

@@ -75,7 +75,7 @@ Canonical rules in the quarkus-hexagonal-core skill; the error/i18n specifics:
 | gRPC counterpart | `GrpcExceptionInterceptor`, in `common/error` | |
 | i18n components | `MessageResolver`, `ErrorCatalog` | |
 | Error DTO | `ErrorDto` (TMF630 Error shape) | |
-| Bundle files | `messages/errors[_<lang>].properties` | `errors_en.properties` |
+| Bundle files | `messages/errors[_<lang>].properties` — the default (en) bundle is `errors.properties`, with no suffix | `errors.properties`, `errors_es.properties` |
 | Bundle key | the error code itself, never a prose key | `USR-404-001` |
 
 `GlobalExceptionHandler` is no longer "the only sanctioned `*Handler`" — under the slice standard `*Handler` is the business-logic class of every slice (`CreatePartyIndividualHandler`). What stays true is that there is exactly **one** global exception handler per transport, both in `common/error`, and that no `Resource`, `GrpcService` or `Consumer` builds an error response itself.
@@ -189,7 +189,11 @@ public class MessageResolver {
         var locale = headers.getAcceptableLanguages().stream()
             .findFirst().filter(l -> !"*".equals(l.getLanguage()))
             .orElse(Locale.ENGLISH);   // default locale = en
-        var bundle = ResourceBundle.getBundle("messages.errors", locale);
+        // getNoFallbackControl is REQUIRED: the default Control falls back to the JVM's
+        // default locale before the base bundle, so `Accept-Language: fr` on a pod with
+        // LANG=es returns Spanish instead of the English default.
+        var bundle = ResourceBundle.getBundle("messages.errors", locale,
+            ResourceBundle.Control.getNoFallbackControl(ResourceBundle.Control.FORMAT_PROPERTIES));
         var pattern = bundle.containsKey(code) ? bundle.getString(code)
                                                : bundle.getString("GEN-500-001");
         return MessageFormat.format(pattern, args);

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

@@ -140,6 +140,7 @@ Rules:
 - Retries only for idempotent RPCs and only `UNAVAILABLE`/`DEADLINE_EXCEEDED`, with budget — prefer platform/mesh retry policy over hand-rolled loops.
 - TLS/mTLS per platform standard (`quarkus.grpc.clients.*.ssl.*` / mesh-provided).
 - Translate `StatusRuntimeException` into a `BusinessException` carrying the caller's own error code, inside the integration bean — gRPC types (and `Uni`) never reach a `Handler`. Read the upstream code from the `error-code` trailer and map it through the caller's `ErrorCatalog`.
+- **Exception: a bean called from a Temporal activity rethrows the raw `StatusRuntimeException`.** Flattening it to `BusinessException` destroys the `Status.Code`, and that code is the only thing telling Temporal whether the failure is retryable — collapsed, an `UNAVAILABLE` blip becomes indistinguishable from an `INVALID_ARGUMENT` and would permanently fail the saga. The activity classifies it instead (see quarkus-temporal-workflows skill §9). Keep such a bean's activity-facing method separate from any `Handler`-facing one rather than changing behaviour based on the caller.
 
 ## Health & reflection
 

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

@@ -1,14 +1,16 @@
 ---
 name: quarkus-hexagonal-core
-description: Foundation for building Java + Quarkus backend services compiled to native binaries (GraalVM/Mandrel) with VERTICAL SLICE architecture over a hexagonal core (ports & adapters collapsed into one folder per feature). Applies to ANY Java/Quarkus backend project — DDD bounded contexts, standalone services, internal tools alike. Use this skill whenever creating, scaffolding, reviewing, or modifying ANY Quarkus backend service, slice, feature, REST/gRPC/Kafka adapter, Sql data class, Handler, or DTO — even if the user only says "create a service", "add an endpoint", "new microservice", or "backend project". Also the canonical source for the SLICE FILE LAYOUT (dto/, Handler, Sql, Resource, GrpcService, Consumer, README) and CLASS NAMING CONVENTIONS, the domain-monorepo layout (apps/, libs/, contracts/, deploy/, db/, docs/), deployable app naming ({module}-{service or submodule}-ms, tenant-agnostic), the mandatory per-app service.yaml + README.md standard, and the Handler contract (@Transactional only on process(), never setAutoCommit/commit/rollback, one Connection per business operation). Enforces Java 25, JDBC-only persistence via Agroal (NO Panache, NO Hibernate/ORM), ArchUnit slice-isolation + naming tests, and native-image compatibility. Project-specific directives (CLAUDE.md, ADRs, explicit instructions) override this standard where they conflict.
+description: Foundation for Java + Quarkus backend services compiled to native binaries (GraalVM/Mandrel) with VERTICAL SLICE architecture over a hexagonal core. Use when creating, scaffolding, reviewing or modifying ANY Quarkus backend service, slice, feature, REST/gRPC/Kafka adapter, Sql data class, Handler or DTO — even if the user only says "create a service", "add an endpoint" or "new microservice". Canonical source for the SLICE FILE LAYOUT, CLASS NAMING CONVENTIONS, the domain-monorepo layout, deployable naming (`-ms` with an API, `-worker` without one), the mandatory per-app service.yaml + README standard including API gateway base paths, and the Handler contract (@Transactional only on process(), one Connection per business operation). Enforces Java 25, JDBC-only persistence via Agroal (NO Panache/ORM), ArchUnit slice-isolation + naming tests, and native-image compatibility. Project directives (CLAUDE.md, ADRs) override this where they conflict.
 ---
 
 # Quarkus Vertical Slice + Hexagonal Core (Native-First)
 
-Foundation skill for all backend services. The other skills in this set (sql-jdbc-agroal, error-handling-i18n, openapi-tmforum, grpc-services, kafka-messaging, observability-otel) build on the structure defined here and use the vocabulary defined here — apply this one first when scaffolding.
+Foundation skill for all backend services. The other eight skills in this set (`quarkus-sql-jdbc-agroal`, `quarkus-error-handling-i18n`, `quarkus-openapi-tmforum`, `quarkus-grpc-services`, `quarkus-kafka-messaging`, `quarkus-observability-otel`, `quarkus-security-standards`, and `quarkus-temporal-workflows` on Temporal projects) build on the structure defined here and use the vocabulary defined here — apply this one first when scaffolding.
 
 **Scope & precedence:** these standards apply to any Java/Quarkus backend project, whether or not it is organized as DDD bounded contexts. **Module naming:** every module/bounded context is identified in code by a short, lowercase, semantic name (`iam`, `tenant`, `wallet`, `customer`) — never by an inventory/governance code like `bc01`/`bc02`. If the organization keeps a numbered BC inventory, the `bcNN` ↔ name mapping lives in governance docs (domain README identity table, service catalog); packages, topics, config keys, URLs, metrics and proto packages only ever carry the semantic name. They are the default, not law: a project directive that says otherwise (CLAUDE.md, an ADR, an explicit user instruction) wins over this skill. When you deviate because of such a directive, follow the directive and mention which rule was overridden.
 
+**One structural exception:** a **Temporal worker-only deployable** (`{module}-{capability}-worker`) — an app that hosts workflows and activities and exposes no API — has no vertical slices, no `Resource`, no `<Slice>Handler`/`<Slice>Sql` pair and usually no datasource. The naming rules, monorepo layout, native build, Dockerfile and the `service.yaml` + README standard below still apply to it in full; the slice layout, the REST adapter rules and the slice-oriented ArchUnit rules do not. See the quarkus-temporal-workflows skill §3 before scaffolding one — do not give it slices because this skill's checklist says so.
+
 ## The central idea: one feature = one folder
 
 Classic layered hexagonal architecture spreads a single feature across eight or more files (inbound port, use case, command, result, outbound port, JDBC adapter, DTO, mapper) in four packages. This standard keeps the **hexagon's dependency rule** but collapses it into a **vertical slice**: everything one business capability needs lives in one folder, and the hexagon is expressed by *class role*, not by package depth.
@@ -48,6 +50,7 @@ One monorepo per domain (bounded context in DDD projects) holds **every deployab
 │   │   ├── service.yaml             # structured metadata — JSON-Schema validated in CI
 │   │   └── README.md                # per-app operational doc (see "Per-app documentation")
 │   ├── iam-identity-ms/             # a second backend in the same domain, same internal structure
+│   ├── iam-onboarding-worker/       # Temporal worker — no API, no slices (see temporal skill)
 │   ├── iam-admin-mf/                # microfrontend remote — own build, same service.yaml + README rule
 │   └── iam-shell-module/            # host/shell that composes the remotes
 ├── libs/                            # code shared *within* this domain — never across domains
@@ -61,7 +64,7 @@ One monorepo per domain (bounded context in DDD projects) holds **every deployab
 └── README.md                        # domain onboarding doc (see "Domain README")
 ```
 
-**Scope of this skill inside the monorepo:** everything from "Slice layout" onward governs `-ms` apps only. `-mf` and `-module` apps are first-class residents of the same repo — they share `contracts/`, `libs/web/`, `deploy/` and `docs/`, and they carry the same mandatory `service.yaml` + `README.md` — but their internal structure is not this standard's business. A frontend never reaches a backend except through a published contract in `contracts/`; there is no shared runtime code between an `-ms` and an `-mf`.
+**Scope of this skill inside the monorepo:** everything from "Slice layout" onward governs `-ms` apps only. A `-worker` app is a backend and follows this skill's naming, native build and documentation rules, but it has no slices — its internal structure belongs to the quarkus-temporal-workflows skill. `-mf` and `-module` apps are first-class residents of the same repo — they share `contracts/`, `libs/web/`, `deploy/` and `docs/`, and they carry the same mandatory `service.yaml` + `README.md` — but their internal structure is not this standard's business. A frontend never reaches a backend except through a published contract in `contracts/`; there is no shared runtime code between an `-ms` and an `-mf`.
 
 ### Deployable app naming (tenant-agnostic)
 
@@ -69,7 +72,9 @@ One monorepo per domain (bounded context in DDD projects) holds **every deployab
 {module}-{service or submodule}-{type-suffix}
 ```
 
-Suffixes: `-ms` (backend microservice — every Quarkus service here), `-mf` (microfrontend remote), `-module` (host/shell). Example: `iam-management-ms`. **Client and tenant never appear in app or code names** — they are runtime configuration (namespaces, labels, Helm values) applied at deploy time; the code is identical for every client and tenant.
+Suffixes: `-ms` (backend microservice serving an API), `-worker` (backend deployable that serves **no** API — currently Temporal workflow workers; see the quarkus-temporal-workflows skill), `-mf` (microfrontend remote), `-module` (host/shell). Examples: `iam-management-ms`, `customer-onboarding-worker`.
+
+`-ms` vs `-worker` is a deploy-time contract, not a label: an `-ms` gets an ingress, HTTP probes and RPS-based scaling; a `-worker` gets none of those and scales on queue backlog. An app that serves an API *and* hosts a worker is an `-ms`. **Client and tenant never appear in app or code names** — they are runtime configuration (namespaces, labels, Helm values) applied at deploy time; the code is identical for every client and tenant.
 
 ## Slice layout (the canonical structure)
 
@@ -179,7 +184,7 @@ Several slices may expose operations under the same TMF base path (`create_party
 
 | Kind | Convention | Example |
 |---|---|---|
-| Deployable app | `{module}-{service or submodule}-{type}` kebab-case, tenant-agnostic (`-ms` backend) | `iam-management-ms` |
+| Deployable app | `{module}-{service or submodule}-{type}` kebab-case, tenant-agnostic (`-ms` backend with an API, `-worker` backend without one) | `iam-management-ms`, `customer-onboarding-worker` |
 | Slice package | lowercase `snake_case`, verb-first | `com.alva.customer.create_party_individual` |
 | SQL constant | `UPPER_SNAKE_CASE` matching the method | `INSERT_PARTY`, `SELECT_PARTY_BY_ID` |
 | SQL table / column | `snake_case`, singular table, schema-qualified | `customer.party`, `created_at` |
@@ -228,7 +233,7 @@ private void validate(CreatePartyIndividualRequestDto request) {
 
 - Opens **one** `Connection` from the injected `DataSource` in try-with-resources and passes it to every `Sql` call in the operation. This is the performance contract: one connection per business operation, whether or not a transaction is active. Under JTA, Agroal would return the same enlisted connection anyway; on a read path with no `@Transactional`, per-method `getConnection()` would acquire *N* separate pool leases for *N* queries — passing `conn` makes both paths cost exactly one.
 - Calls `${SERVICE_CLASS_PREFIX}Sql` methods in business order (insert `party` first to get `partyId`, reuse it for dependent inserts). Before writing a call, re-read the real `Sql` method signature and pass exactly those parameters, in that order and type.
-- Catches every checked `SQLException` and rethrows it as `BusinessException` via `SqlStateTranslator` — an unchecked exception is what triggers the container rollback, and a propagated checked exception would not.
+- Catches every checked `SQLException` and rethrows it **unchecked** via `SqlStateTranslator` — as a `BusinessException` for the states that mean a business conflict (`23505`, `23503`) and as the `PersistenceException` family for everything else (see the mapping table in quarkus-sql-jdbc-agroal skill §9). An unchecked exception is what triggers the container rollback; a propagated checked one would not.
 - Date fields arrive from the DTO as `String`. To use them as `LocalDate`/`ZonedDateTime`, declare a **new local variable** and convert explicitly (`LocalDate.parse(...)`) — never reassign the DTO field.
 - Domain events are published by inserting an outbox row through `OutboxEventRecorder` from `common/messaging`, on this method's `Connection` and therefore in this same transaction — never by emitting to Kafka directly (see quarkus-kafka-messaging skill). Who relays that row (Debezium, `OutboxRelayJob`, or a post-commit emit) is a runtime property, `app.messaging.outbox.relay-mode`, and changes nothing here.
 - **The outbox is cross-cutting, not slice-local: never declare `insertOutboxEvent` on a `<Slice>Sql`.** It is the same table, the same columns and the same envelope in every slice, so the "duplicate twice, extract on the third" rule below does not apply — there is nothing slice-specific to discover. The shared `Connection` is what keeps the write transactional; the class's location is irrelevant to that guarantee. Same for `AuditRecorder` and any other table `common/` owns.
@@ -321,7 +326,7 @@ Full standard (pool config, batches, jsonb, pagination, keyset paging, SQLState
 - Constants are text blocks or comma-first concatenations, schema-qualified, with positional `?` placeholders only. **Check the real schema name before writing a query** — if the schema or table is a reserved word (`order`, `user`, `group`), quote it: `"order".party`.
 - If the PK has a database default (`id uuid DEFAULT customer.uuidv7() NOT NULL`), the `id` column is excluded from the INSERT column list and never passed as a parameter. Prefer `INSERT ... RETURNING id` over `getGeneratedKeys()`.
 - **Every method's first parameter is `Connection conn`** — supplied by the Handler, never obtained inside the method. That signature is the contract the Handler must honour exactly.
-- Methods `throws SQLException` — they never swallow it and never translate it. Translation to `BusinessException` happens in the Handler via `SqlStateTranslator`.
+- Methods `throws SQLException` — they never swallow it and never translate it. Translation happens in the Handler via `SqlStateTranslator`, into `BusinessException` or the `PersistenceException` family depending on the SQLState.
 - **No transaction control here.** No `commit`, no `rollback`, no `setAutoCommit`.
 - Row mapping is hand-written into DTOs (`PartyDto.builder()...`) — no reflection-based mappers, which also keeps native images small.
 
@@ -344,7 +349,7 @@ All three are thin: extract metadata, invoke `handler.process(...)`, format the
 - `<Resource>Resource` class with `@Path` + `@Tag`, injecting the slice `Handler`(s).
 - Returns `RestResponse<T>` synchronously. Never `Uni`/`Multi`.
 - `@Blocking` on JDBC-backed methods. With a plain (non-reactive) return type Quarkus REST already dispatches to a worker thread, so the annotation is redundant *today* — keep it as an explicit threading contract that survives a later signature change. `@RunOnVirtualThread` is the alternative for high-concurrency blocking endpoints (see sql skill §8).
-- Extracts `tenantId`, `partyId`, `partyRolList`, `language` from headers when the contract requires them, and sets them on the request DTO before calling `process()`.
+- Reads `tenantId` — and any other value that drives authorization, such as `partyId` or `partyRolList` — from the **validated token** (`@Inject JsonWebToken jwt` → `jwt.getClaim(...)`, or `@Claim` — not `SecurityIdentity`, which carries roles and mechanism attributes rather than claims), never from a request header the caller controls (see the Tenancy model rule under "Per-app documentation" and quarkus-security-standards skill §4). `language` and other non-security metadata may come from headers. It sets them on the request DTO before calling `process()`.
 - Full OpenAPI annotations per method: `@Operation` with `operationId`, one `@APIResponse` per relevant status, `@Parameter` for headers and path/query params, `Location` header on create.
 
 **gRPC** — full standard in **quarkus-grpc-services**:
@@ -394,10 +399,15 @@ Code shared across **apps** in the domain goes to `libs/` and uses constructor i
 
 ## Scaffolding checklist
 
-When creating a new service:
+When creating a new service. A **Temporal worker-only deployable** (quarkus-temporal-workflows skill §3) follows the same steps with a reduced scope — it has no slices and no `Resource`:
 
-1. App folder `apps/<module>-<service-or-submodule>-ms/` per the monorepo layout above.
-2. `pom.xml` with BOM `io.quarkus.platform:quarkus-bom` (latest 3.x LTS), extensions: `quarkus-rest`, `quarkus-rest-jackson`, `quarkus-agroal`, `quarkus-jdbc-postgresql`, `quarkus-arc`, `quarkus-narayana-jta`, `quarkus-hibernate-validator`, `quarkus-smallrye-health`, `quarkus-smallrye-openapi`, `quarkus-opentelemetry`, `quarkus-flyway` (kept even where migrations are disabled — see sql skill §10), plus Lombok and skill-specific extensions as needed.
+- **Step 2 — add** `io.quarkiverse.temporal:quarkus-temporal` and `quarkus-grpc`; **keep** `quarkus-arc`, `quarkus-smallrye-health` and the three observability extensions; **drop** `quarkus-rest*`, `quarkus-smallrye-openapi`, `quarkus-hibernate-validator` and `quarkus-oidc`, and — unless it owns a table of its own — `quarkus-agroal`, `quarkus-jdbc-*`, `quarkus-narayana-jta` and `quarkus-flyway`.
+- **Step 3 —** keep only the error/exception classes it actually throws.
+- **Step 4 —** drop the datasource and Flyway blocks from the baseline below whenever step 2 dropped those extensions. **Leaving `quarkus.datasource.db-kind=postgresql` in place without a JDBC driver fails the Quarkus build** with "Unable to find a JDBC driver corresponding to the database kind". Add the `quarkus.temporal.*` block that skill's §2 defines instead.
+- **Step 5 —** skip the slice-oriented rules and ship the ArchUnit subset that skill lists.
+
+1. App folder `apps/<module>-<service-or-submodule>-ms/` per the monorepo layout above — `-worker` instead of `-ms` for a Temporal worker deployable.
+2. `pom.xml` with BOM `io.quarkus.platform:quarkus-bom` (latest 3.x LTS), extensions: `quarkus-rest`, `quarkus-rest-jackson`, `quarkus-agroal`, `quarkus-jdbc-postgresql`, `quarkus-arc`, `quarkus-narayana-jta`, `quarkus-hibernate-validator`, `quarkus-smallrye-health`, `quarkus-smallrye-openapi`, `quarkus-opentelemetry`, `quarkus-micrometer-registry-prometheus` (mandatory metrics — brings `quarkus-micrometer` transitively) and `quarkus-logging-json` (mandatory structured logs) — the three observability extensions are all required, see that skill — `quarkus-oidc` wherever the app exposes an authenticated API (security skill §4), `quarkus-flyway` (kept even where migrations are disabled — see sql skill §10), plus Lombok and skill-specific extensions as needed.
 3. `common/` package: `BusinessException`, `ErrorCatalog`, `ErrorDto`, `GlobalExceptionHandler`, `MessageResolver`, `SqlStateTranslator`, `StringUtils`.
 4. `application.properties` baseline (below).
 5. ArchUnit test (below) — in the same commit as the first slice, not later.
@@ -434,8 +444,12 @@ quarkus.flyway.migrate-at-start=false
 app.messaging.outbox.relay-mode=debezium
 app.messaging.outbox.poller.every=off
 
+# Metrics — Micrometer is mandatory in every service (see quarkus-observability-otel skill)
+quarkus.micrometer.export.prometheus.enabled=true
+quarkus.datasource.metrics.enabled=true
+
 # i18n (see error-handling skill) — locales must be declared for native
-quarkus.locales=en,es
+quarkus.locales=en,es,pt
 quarkus.default-locale=en
 quarkus.native.resources.includes=messages/*.properties
 
@@ -484,13 +498,13 @@ Rules:
 
 Every deployable under `apps/<app>/` carries two files, versioned with the code and updated in the **same PR** that changes the service's behavior:
 
-- **`service.yaml`** — structured metadata validated against a JSON Schema in CI: identity (domain, system, component type, lifecycle), ownership (team, SRE, support group), criticality, tenancy (model, data isolation), runtime (type, version, ports), provided APIs with their contract files in `contracts/`, dependencies with `hard`/`soft` requirement, and the observability contract (log format, levels, required fields, data-protection rules). It feeds the service catalog and the dependency map.
+- **`service.yaml`** — structured metadata validated against a JSON Schema in CI: identity (domain, system, component type, lifecycle), **the API gateway base path(s) under `metadata.gateway`** (see "Gateway routing" below), ownership (team, SRE, support group), criticality, tenancy (model, data isolation), runtime (type, version, ports), provided APIs with their contract files in `contracts/`, dependencies with `hard`/`soft` requirement, and the observability contract (log format, levels, required fields, data-protection rules). It feeds the service catalog, the dependency map and the gateway route configuration.
 - **`README.md`** (per app) — operational doc written so a system administrator who has never seen the code can configure, deploy and recover the service. No `TBD` / "see code" (a justified `N/A` is allowed). No manual changelog section — Git keeps the history.
 
 Required `README.md` sections:
 
 1. **Identity** — app name, module (`part-of`), type (`ms`), owning team, repository, criticality, part of core yes/no
-2. **Purpose & responsibility** — description + out of scope
+2. **Purpose, responsibility & gateway routes** — description + out of scope, **plus the API gateway base path(s) this service is published under** (see "Gateway routing" below). A `-worker` app declares `N/A — publishes no API`.
 3. **Slice inventory** — table: slice folder, capability, exposed channels (REST/gRPC/Kafka), link to the slice README
 4. **Tenancy model** — `shared` | `per-tenant` | `pool`; tenant identification (validated JWT claim, never a free header); data isolation; per-tenant parameters
 5. **APIs exposed** — table: api/version, protocol, route/topic, contract file, auth, visibility
@@ -509,6 +523,39 @@ Required `README.md` sections:
 
 Rule of completeness: if a variable, secret or dependency is not documented here, it does not exist — CI validates the `service.yaml` schema and the mandatory `README.md` sections as a blocking gate.
 
+### Gateway routing (README §2 + `service.yaml` `metadata.gateway`)
+
+Infra configures the API gateway from these two files, so the route a service will be published under is declared **before** it is deployed, in the same PR as the endpoint.
+
+**The base path is the module's semantic name**, the same name packages, topics, config keys and metrics already use: `/iam`, `/customer`, `/wallet` — **never the inventory code** (`/bc01` is wrong; the `bcNN` ↔ name mapping lives in governance docs, not in a URL). Every north-bound REST API of every `-ms` in the module therefore hangs off one shared prefix, and the API's own path continues from there per the quarkus-openapi-tmforum skill: `/{module}/{context}/{apiName}/v{major}`, e.g. `/iam/tmf-api/digitalIdentityManagement/v4`.
+
+README §2 carries the human-readable table:
+
+| Base path | Protocol | Visibility | Purpose |
+|---|---|---|---|
+| `/iam` | REST | public | north-bound TMF identity APIs |
+
+`service.yaml` carries the same facts as structured metadata:
+
+```yaml
+metadata:
+  name: iam-management-ms
+  module: iam
+  gateway:
+    base-paths:
+      - path: /iam
+        protocol: REST
+        visibility: public          # public | partner | internal
+        purpose: north-bound TMF identity APIs
+```
+
+Rules:
+- **`service.yaml` is authoritative; the README renders the same facts for humans.** They must agree — two copies of one fact drift, and here the drift is a misrouted service. CI cross-checks them.
+- **Only north-bound REST appears here.** Internal gRPC never crosses the gateway (internal calls are gRPC, external is REST — see "Baseline constraints"), so a `*GrpcService` contributes no gateway route.
+- **A `-worker` app declares none** — `metadata.gateway.base-paths: []` and `N/A` in the README. It publishes no API by definition (see the quarkus-temporal-workflows skill).
+- List **every** prefix when a service is published under more than one — a legacy alias kept during a migration, or a second public API — each with its own purpose, so nobody has to guess which is being retired.
+- The declared path must match the ingress/gateway configuration in the GitOps repo. A README that disagrees with what is deployed is a defect, not a stale doc: it is the input infra works from.
+
 ### Slice README (inside the slice folder)
 
 Every slice carries its own `README.md`, generated from the real code — no invented routes, fields or tables. Sections:
@@ -547,7 +594,10 @@ class ArchitectureTest {
         .namingSlices("slice $1")
         .should().notDependOnEachOther()
         .ignoreDependency(resideInAPackage("..common.."), alwaysTrue())
-        .ignoreDependency(alwaysTrue(), resideInAPackage("..common.."));
+        .ignoreDependency(alwaysTrue(), resideInAPackage("..common.."))
+        // Temporal only: orchestration/ may reach into slices, never the reverse (deliberately
+        // asymmetric — see quarkus-temporal-workflows skill §3). Omit on non-Temporal projects.
+        .ignoreDependency(resideInAPackage("..orchestration.."), alwaysTrue());
 
     // --- Hexagon dependency rule inside the slice ------------------------------
     @ArchTest
@@ -646,7 +696,9 @@ static final ArchRule businessExceptionIsTheOnlyOne = classes()
     .should().resideInAPackage("..common.exception..");
 
 @ArchTest
-static final ArchRule bannedSuffixes = noClasses().should().haveSimpleNameEndingWith("Impl")
+static final ArchRule bannedSuffixes = noClasses()
+    .that().resideOutsideOfPackage("..orchestration..")   // Temporal workflow/activity Impl pair — see below
+    .should().haveSimpleNameEndingWith("Impl")
     .orShould().haveSimpleNameEndingWith("Util")       // note: "Utils" is deliberately absent — common/util/StringUtils
     .orShould().haveSimpleNameEndingWith("Helper")
     .orShould().haveSimpleNameEndingWith("Manager")
@@ -657,7 +709,7 @@ static final ArchRule bannedSuffixes = noClasses().should().haveSimpleNameEnding
     .orShould().haveSimpleNameEndingWith("DTO");
 ```
 
-`common/util/StringUtils` and the `Jdbc` namespace helper (sql skill §7) are the sanctioned exceptions to `bannedSuffixes` — exclude them by fully-qualified name rather than weakening the rule.
+`common/util/StringUtils`, the `Jdbc` namespace helper (sql skill §7) and, on Temporal projects, the `*WorkflowImpl`/`*ActivitiesImpl` pair inside `..orchestration..` (whose interface+implementation split the SDK requires — see quarkus-temporal-workflows skill §3) are the sanctioned exceptions to `bannedSuffixes`. Exclude them by package or fully-qualified name, as above, rather than weakening the rule.
 
 Rules the compiler cannot express (enforce in code review and in the generator checklists):
 
@@ -686,7 +738,7 @@ Rules the compiler cannot express (enforce in code review and in the generator c
 
 `<Slice>HandlerTest` is mandatory and mirrors the slice. Rules:
 
-- Mockito only — `@Mock <Slice>Sql sql;`, `@Mock DataSource dataSource;`, `@Mock Connection connection;`, `@InjectMocks <Slice>Handler handler;`, with `when(dataSource.getConnection()).thenReturn(connection)` in `@BeforeEach`. Never a real database, never `@QuarkusTest` for pure business rules, never both `@InjectMocks` (Mockito) and `@InjectMock` (Quarkus) in one file.
+- Mockito only — `@Mock <Slice>Sql sql;`, `@Mock DataSource dataSource;`, `@Mock Connection connection;`, `@InjectMocks <Slice>Handler handler;`. Stub `when(dataSource.getConnection()).thenReturn(connection)` **inside the tests that reach `execution()`**, not in `@BeforeEach`: the mandatory validation-failure test (scenario 2 below) never opens a connection, so a shared stub fails it with Mockito's `UnnecessaryStubbingException` under the default strict stubs. Use `lenient()` only if you genuinely prefer the shared setup. Never a real database, never `@QuarkusTest` for pure business rules, never both `@InjectMocks` (Mockito) and `@InjectMock` (Quarkus) in one file.
 - Test names: `should<Result>When<Condition>` — `shouldReturnPartyIdWhenRequestIsValid`, `shouldThrowBusinessExceptionWhenGivenNameIsBlank`.
 - Minimum scenarios per public business path:
 

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

@@ -130,7 +130,9 @@ That is the whole dual-write guarantee — one connection, one transaction, no p
 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
+// common/audit/AuditEventPublisher.java — the Handler injects this bean, not the Emitter.
+// Distinct from AuditRecorder (common/audit), which writes the local audit_event table
+// on the Handler's Connection — see quarkus-observability-otel skill.
 @Inject @Channel("audit-out") Emitter<AuditEventPayload> audit;
 ```
 
@@ -314,12 +316,12 @@ 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.failure-strategy=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.
+- **Idempotency is mandatory**: `processed_event(consumer_group, event_id)` checked/inserted through the cross-cutting `ProcessedEventSql` in `common/messaging` — never a per-slice copy, it is the same table for every slice (see quarkus-sql-jdbc-agroal skill §6) — on the `Connection` the `Handler` already owns, 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.