bmad-method-quarkus 1.0.4 → 1.0.5

package/package.json

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

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

@@ -84,7 +84,23 @@ Fully embody this persona so the user gets the best experience. Do not break cha
 
 Treat every entry in `{agent.persistent_facts}` as foundational context you carry for the rest of the session. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
 
-### Step 5: Load Config
+### 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.
+
+1. `{project-root}/.claude/skills/quarkus-hexagonal-core/SKILL.md` — **read this one first**; the other six 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`
+
+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.
+
+Loading them here is deliberate: description-based auto-triggering fires on what the *user asks*, not on the code being edited, so "add a field to this DTO" or "make this compile" would otherwise reach the file with none of the standards in context.
+
+### Step 6: Load Config
 
 Load available config from `{project-root}/_bmad/config.yaml` and `{project-root}/_bmad/config.user.yaml` if present. If neither exists, mention that `bqa-setup` can configure the project. Resolve and apply throughout the session (defaults in parens):
 
@@ -92,19 +108,19 @@ Load available config from `{project-root}/_bmad/config.yaml` and `{project-root
 - `{communication_language}` (system default) — use for all communications
 - `{document_output_language}` (system default) — use for generated document content
 
-### Step 6: Greet the User
+### Step 7: Greet the User
 
 Greet `{user_name}` warmly by name as Marcus, speaking in `{communication_language}`. Lead the greeting with `{agent.icon}` so the user can see at a glance which agent is speaking. Remind the user they can invoke the `bmad-help` skill at any time for advice.
 
 Continue to prefix your messages with `{agent.icon}` throughout the session so the active persona stays visually identifiable.
 
-### Step 7: Execute Append Steps
+### Step 8: Execute Append Steps
 
 Execute each entry in `{agent.activation_steps_append}` in order.
 
 Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
-### Step 8: Dispatch or Present the Menu
+### Step 9: Dispatch or Present the Menu
 
 If the user's initial message already names an intent that clearly maps to a menu item (e.g. "Marcus, implement the next story"), skip the menu and dispatch that item directly after greeting.
 

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

@@ -1,6 +1,6 @@
 ---
 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}-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 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.
 ---
 
 # Quarkus Vertical Slice + Hexagonal Core (Native-First)
@@ -36,32 +36,40 @@ The trade the slice makes explicit: **fewer classes, stricter roles.** There are
 
 ## Monorepo layout (per domain/module)
 
-One monorepo per domain (bounded context in DDD projects) holds its deployable apps plus internal libs. It never contains live environment/client configuration — the deployed state lives in the GitOps config repo.
+One monorepo per domain (bounded context in DDD projects) holds **every deployable that belongs to that domain — backends and frontends alike** — plus the libs and contracts they share. It never contains live environment/client configuration — the deployed state lives in the GitOps config repo.
 
 ```
-/  (domain monorepo, e.g. wallet)
-├── apps/                            # deployable applications, one folder each
-│   └── wallet-backend-core-ms/
-│       ├── src/
-│       ├── pom.xml
-│       ├── Dockerfile               # this app's image build (native)
-│       ├── service.yaml             # structured metadata — JSON-Schema validated in CI
-│       └── README.md                # per-app operational doc (see "Per-app documentation")
-├── libs/                            # modules shared within the domain
+/  (domain monorepo, e.g. iam)
+├── apps/                            # deployable applications, one folder each — backends AND frontends
+│   ├── iam-management-ms/           # Quarkus backend (native) — structured per "Slice layout" below
+│   │   ├── src/
+│   │   ├── pom.xml
+│   │   ├── Dockerfile               # this app's image build (native)
+│   │   ├── 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-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
+│   ├── java/                        # shared Java modules (constructor injection — see "Shared code")
+│   └── web/                         # shared TS/UI packages
 ├── contracts/                       # versioned API contracts (TMF/OpenAPI, JSON Schemas, protos)
+│                                    #   — the seam the -ms and -mf apps meet at; neither imports the other
 ├── deploy/                          # k8s manifests, pipelines, observability-as-code
 ├── db/                              # database migrations (versioned always; applied at boot only where the Flyway flag is on)
 ├── docs/                            # architecture, ADRs, runbooks
 └── 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`.
+
 ### Deployable app naming (tenant-agnostic)
 
 ```
-{module}-{service}-{type-suffix}
+{module}-{service or submodule}-{type-suffix}
 ```
 
-Suffixes: `-ms` (backend microservice — every Quarkus service here), `-mf` (microfrontend remote), `-module` (host/shell). Example: `wallet-backend-core-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 — 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.
 
 ## Slice layout (the canonical structure)
 
@@ -79,6 +87,7 @@ src/main/java/com/<company>/<module>/
 │   ├── error/SqlStateTranslator.java              #   SQLState -> error code
 │   ├── i18n/MessageResolver.java                  #   Accept-Language -> localized message
 │   ├── client/CredentialsValidator.java           #   outbound gRPC/REST integrations
+│   ├── messaging/OutboxEventRecorder.java      # the ONLY writer of the outbox table
 │   ├── messaging/OutboxRelayJob.java           # + OutboxDispatcher, OutboxConfig, OutboxSql
 │   ├── audit/AuditRecorder.java
 │   └── util/StringUtils.java
@@ -170,7 +179,7 @@ Several slices may expose operations under the same TMF base path (`create_party
 
 | Kind | Convention | Example |
 |---|---|---|
-| Deployable app | `{module}-{service}-{type}` kebab-case, tenant-agnostic (`-ms` backend) | `wallet-backend-core-ms` |
+| Deployable app | `{module}-{service or submodule}-{type}` kebab-case, tenant-agnostic (`-ms` backend) | `iam-management-ms` |
 | 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` |
@@ -191,7 +200,8 @@ Several slices may expose operations under the same TMF base path (`create_party
 3.  @ApplicationScoped
 4.  @Inject DataSource dataSource;
 5.  @Inject ${SERVICE_CLASS_PREFIX}Sql sql;
-6.  (optional) @Inject <integration beans from common/client, OutboxDispatcher from common/messaging>
+6.  (optional) @Inject <integration beans from common/client; OutboxEventRecorder +
+                    OutboxDispatcher from common/messaging; AuditRecorder from common/audit>
 7.  private void   validate(RequestDto request)
 8.  private <T>    execution(RequestDto request)      // T = internal result (UUID, DTO, List<Dto>…)
 9.  private ResponseDto getResult(<T> internalResult)
@@ -220,7 +230,8 @@ private void validate(CreatePartyIndividualRequestDto request) {
 - 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.
 - 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 this slice's own `Sql`, 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.
+- 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.
 - External services are called through capability-named beans injected from `common/client` — never a raw `@GrpcClient` stub, which would drag Mutiny into the Handler.
 
 ```java
@@ -234,9 +245,9 @@ private UUID execution(CreatePartyIndividualRequestDto request) {
                 sql.insertContactMedium(conn, partyId, medium.getMediumType(), medium.getContactValue());
             }
         }
-        UUID eventId = sql.insertOutboxEvent(conn, partyId, "party",
+        UUID eventId = outbox.record(conn, "party", partyId.toString(),
             "com.alva.customer.party.created.v1", "alva.customer.party.created.v1",
-            payloadJson(partyId, request), traceparent());   // traceparent captured from Span.current() (see kafka/observability skills)
+            eventMap(partyId, request));                     // recorder captures the span and builds the envelope (see kafka/observability skills)
         dispatcher.dispatchAfterCommit(eventId);             // no-op unless relay-mode=direct (see kafka skill)
         return partyId;
     } catch (SQLException e) {
@@ -332,7 +343,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 §7).
+- `@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()`.
 - Full OpenAPI annotations per method: `@Operation` with `operationId`, one `@APIResponse` per relevant status, `@Parameter` for headers and path/query params, `Location` header on create.
 
@@ -373,9 +384,11 @@ Governed by **quarkus-observability-otel**; the slice-relevant rules:
 
 ## Shared code
 
-`common/` holds only what **two or more slices** genuinely share, or what is structurally cross-cutting: the exception/error/i18n machinery, integration beans, `OutboxRelayJob`/`OutboxDispatcher`, `AuditRecorder`, `@ConfigMapping` interfaces, `StringUtils`.
+`common/` holds only what **two or more slices** genuinely share, or what is structurally cross-cutting: the exception/error/i18n machinery, integration beans, `OutboxEventRecorder`/`OutboxSql`/`OutboxRelayJob`/`OutboxDispatcher`, `AuditRecorder`, `@ConfigMapping` interfaces, `StringUtils`.
+
+Cross-cutting **tables** are exempt from the promotion rule and shared from day one — the outbox and audit tables have one writer each (`OutboxEventRecorder`, `AuditRecorder`), never a copy per slice. The test is whether the code is *identical by construction*: a slice cannot have its own opinion about the outbox schema, so waiting for a third occurrence just buys 3× the drift. Everything else follows the rule below.
 
-Promotion rule: **duplicate twice, extract on the third.** Two slices with similar-looking code is the expected cost of slice independence — premature extraction rebuilds the shared-layer coupling this structure exists to avoid. What must never be shared: a `Handler`, an `Sql`, or a slice's `dto` package. If slice B needs slice A's data, it queries it through its own `Sql` method or consumes A's event — it does not import A.
+Promotion rule: **duplicate twice, extract on the third.** Two slices with similar-looking code is the expected cost of slice independence — premature extraction rebuilds the shared-layer coupling this structure exists to avoid. What must never be shared: a `Handler`, a **slice's** `Sql`, or a slice's `dto` package (the cross-cutting `Sql` classes `common/` owns are the exception above, not a violation). If slice B needs slice A's data, it queries it through its own `Sql` method or consumes A's event — it does not import A.
 
 Code shared across **apps** in the domain goes to `libs/` and uses constructor injection.
 
@@ -383,8 +396,8 @@ Code shared across **apps** in the domain goes to `libs/` and uses constructor i
 
 When creating a new service:
 
-1. App folder `apps/<module>-<service>-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 §9), plus Lombok and skill-specific extensions as needed.
+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.
 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.
@@ -409,7 +422,7 @@ quarkus.datasource.db-kind=postgresql
 quarkus.datasource.jdbc.max-size=16
 
 # Schema migrations are OPT-IN and off by default — the app does not own the schema
-# in a DBA/pipeline-managed environment (see quarkus-sql-jdbc-agroal skill §9)
+# in a DBA/pipeline-managed environment (see quarkus-sql-jdbc-agroal skill §10)
 quarkus.flyway.enabled=false
 quarkus.flyway.migrate-at-start=false
 %dev.quarkus.flyway.enabled=true
@@ -542,10 +555,18 @@ class ArchitectureTest {
         .that().haveSimpleNameEndingWith("Sql")
         .should().onlyBeAccessed().byClassesThat(
             have(simpleNameEndingWith("Handler"))
-            // OutboxSql is cross-cutting: its callers are the dispatcher and the relay job,
-            // which play the Handler role (they own the Connection) outside any slice.
+            // OutboxSql is cross-cutting: besides slice Handlers (via OutboxEventRecorder),
+            // its callers are the recorder, the dispatcher and the relay job, which play the
+            // Handler role (they own the Connection) outside any slice.
             .or(resideInAPackage("..common.messaging..")));
 
+    // Cross-cutting tables have exactly one writer. Without this rule the per-slice copy
+    // grows back on the next generated slice and drifts silently.
+    @ArchTest
+    static final ArchRule crossCuttingWritesAreCentralised = methods()
+        .that().haveNameMatching("insertOutboxEvent|insertAuditEvent")
+        .should().beDeclaredInClassesThat().resideInAnyPackage("..common.messaging..", "..common.audit..");
+
     @ArchTest
     static final ArchRule transportHasNoJdbc = noClasses()
         .that().haveSimpleNameEndingWith("Resource")
@@ -636,7 +657,7 @@ static final ArchRule bannedSuffixes = noClasses().should().haveSimpleNameEnding
     .orShould().haveSimpleNameEndingWith("DTO");
 ```
 
-`common/util/StringUtils` and the `Jdbc` namespace helper (sql skill §6) are the sanctioned exceptions to `bannedSuffixes` — exclude them by fully-qualified name rather than weakening the rule.
+`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.
 
 Rules the compiler cannot express (enforce in code review and in the generator checklists):
 

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

@@ -1,6 +1,6 @@
 ---
 name: quarkus-kafka-messaging
-description: Standard for asynchronous event-driven messaging with Apache Kafka in Quarkus native services — CloudEvents envelope, topic naming, transactional outbox, idempotent consumers, DLQ, and W3C trace context propagation. Use this skill whenever the user mentions Kafka, events, messaging, publish/subscribe, producers, consumers, outbox, domain events between services, SmallRye Reactive Messaging, or asynchronous integration between bounded contexts — even if they just say "emit an event" or "listen to a topic". Includes payload, consumer, relay-job and channel naming conventions for the vertical-slice layout (the Consumer lives in the slice folder and delegates to the slice Handler; the outbox row is written by the slice's own Sql inside the Handler transaction) 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.
+description: Standard for asynchronous event-driven messaging with Apache Kafka in Quarkus native services — CloudEvents envelope, topic naming, transactional outbox, idempotent consumers, DLQ, and W3C trace context propagation. Use this skill whenever the user mentions Kafka, events, messaging, publish/subscribe, producers, consumers, outbox, domain events between services, SmallRye Reactive Messaging, or asynchronous integration between bounded contexts — even if they just say "emit an event" or "listen to a topic". Includes payload, consumer, relay-job and channel naming conventions for the vertical-slice layout (the Consumer lives in the slice folder and delegates to the slice Handler; the outbox row is written by the shared OutboxEventRecorder in common/messaging, on the Connection the Handler already owns) and the property-driven relay mode (`app.messaging.outbox.relay-mode` = debezium | poller | direct) that decides whether Debezium, a scheduled poller or a direct Emitter publishes the row.
 ---
 
 # Kafka Messaging Standard (Quarkus + SmallRye Reactive Messaging)
@@ -47,7 +47,7 @@ Never publish to Kafka in the same breath as a DB write — dual-write problem.
 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), 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):
+Standard outbox table (one per service), created by a versioned migration in `db/migration` — never at runtime, and independently of whether the Flyway flag lets the app apply it (see quarkus-sql-jdbc-agroal skill §10):
 
 ```sql
 CREATE TABLE outbox_event (
@@ -63,6 +63,8 @@ CREATE TABLE outbox_event (
 );
 ```
 
+Schema-qualify it like any other table (`identity.outbox`, `customer.outbox_event`) — the unqualified name above is shorthand for readability, not a licence to rely on `search_path` (quarkus-sql-jdbc-agroal skill §2). Whatever the name, `OutboxSql` is the only class that spells it.
+
 **Payload traceability (mandatory):** besides the `traceparent` column (used by the relay to set the Kafka header), the `payload` jsonb itself must embed a `traceContext` block for audit and immutability:
 
 ```json
@@ -79,15 +81,17 @@ CREATE TABLE outbox_event (
 
 Both `traceparent` and `traceContext` are captured at insert time from `Span.current().getSpanContext()` — manual construction of trace strings is prohibited (see quarkus-observability-otel skill).
 
-Under the vertical-slice standard there is no `EventPublisher` port and no publisher adapter: the slice's `Handler` writes the outbox row through **its own `Sql` class**, inside `execution()`, on the same `Connection` and therefore in the same transaction as the state change. (`OutboxDispatcher` below is not that port — it publishes nothing in the default mode and never appears in the event's write path.)
+Under the vertical-slice standard there is no `EventPublisher` port and no publisher adapter: the slice's `Handler` writes the outbox row through **`OutboxEventRecorder` in `common/messaging`**, inside `execution()`, on the same `Connection` and therefore in the same transaction as the state change. (`OutboxDispatcher` below is not that port — it publishes nothing in the default mode and never appears in the event's write path.)
+
+**The outbox is a cross-cutting table, so it gets exactly one writer per service — never a per-slice copy.** The dual-write guarantee comes from the shared `Connection`, not from the class living in the slice folder: `OutboxEventRecorder.record(conn, …)` takes the `Connection` the `Handler` already owns, so the row lands in the same JTA transaction as the state change. Re-declaring `insertOutboxEvent` on a `<Slice>Sql` buys nothing and costs ~25 identical lines per slice; the copies drift (a null-guard here, a changed column list there) and the divergence is invisible until one slice writes a row the relay cannot route. `OutboxEventRecorder` mirrors `AuditRecorder` in `common/audit` exactly — same `Connection`-first shape, same reason.
 
 ```java
 private UUID execution(CreatePartyIndividualRequestDto request) {
     try (Connection conn = dataSource.getConnection()) {
         UUID partyId = sql.insertParty(conn, ...);
-        UUID eventId = sql.insertOutboxEvent(conn, partyId, "party",
+        UUID eventId = outbox.record(conn, "party", partyId.toString(),
             "com.alva.customer.party.created.v1", "alva.customer.party.created.v1",
-            payloadJson(partyId, request), traceparent());
+            eventMap(partyId, request));            // recorder captures the span, builds the envelope
         dispatcher.dispatchAfterCommit(eventId);   // no-op unless relay-mode=direct (see Relay mode)
         return partyId;
     } catch (SQLException e) {
@@ -96,7 +100,30 @@ private UUID execution(CreatePartyIndividualRequestDto request) {
 }
 ```
 
-`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`.
+`execution()` still returns the slice's internal result (`partyId`) for `getResult()`, `@Transactional` still sits on `process()` alone, and the method order of the hexagonal-core skill is unchanged. `OutboxEventRecorder` and `OutboxDispatcher` are injected in the Handler's `common/` bean slot, next to `dataSource` and `sql`.
+
+The slice supplies only what is genuinely slice-specific — the aggregate type/id, the CloudEvents `type`, the topic, and the `event` body. Everything repetitive is the recorder's job:
+
+```java
+// common/messaging/OutboxEventRecorder.java — one per service; the only writer of the outbox table
+@ApplicationScoped
+public class OutboxEventRecorder {
+
+    private final OutboxSql outboxSql;          // common/messaging, Connection-first
+    private final ObjectMapper objectMapper;
+
+    @Inject
+    public OutboxEventRecorder(OutboxSql outboxSql, ObjectMapper objectMapper) { ... }
+
+    /** Captures `traceparent` + the payload's `traceContext` block from `Span.current()` itself,
+     *  wraps `event` in the standard envelope, and inserts on the caller's `Connection`. */
+    public UUID record(Connection conn, String aggregateType, String aggregateId,
+                       String eventType, String topic, Map<String, Object> event)
+            throws SQLException { ... }
+}
+```
+
+A `Handler` that hand-builds the envelope, or hand-reads `Span.current()` to make a `traceparent`, has copied the recorder's body — that is the same defect as a per-slice `insertOutboxEvent`, one layer up.
 
 That is the whole dual-write guarantee — one connection, one transaction, no port indirection. Nothing in the slice knows how the row reaches Kafka: `common/messaging` owns the single publish path (`OutboxDispatcher` + `OutboxRelayJob`) and it is the only code that talks to Kafka on the produce side.
 
@@ -228,7 +255,7 @@ Rules:
 - `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.
+- `OutboxSql` is the one `Sql` class that lives in `common/` rather than a slice, and the one whose callers are not only `Handler`s — `OutboxEventRecorder` writes through it, and the dispatcher and the relay job own the `Connection` in the `Handler`'s place on the read/publish side. That exception is written into the `onlyHandlersTouchSql` ArchUnit rule (`resideInAPackage("..common.messaging..")`), not left for the build to discover.
 - Consumers are unaffected: the same CloudEvent lands on the same topic in all three modes. That is the contract the flag must not break — a contract test asserts headers/topic are identical between `direct` and Debezium output.
 
 **Debezium mode** maps outbox columns to the envelope in the connector, not in Java:
@@ -253,7 +280,8 @@ Canonical rules in the quarkus-hexagonal-core skill; messaging specifics:
 |---|---|---|
 | Wire payload DTO | `<Event>Payload`, in the producing/consuming slice's `dto/` | `UserRegisteredPayload` |
 | Consumer | `<Event>Consumer`, in the slice folder | `UserRegisteredConsumer` |
-| Outbox write | a method on the slice's own `Sql` | `insertOutboxEvent(conn, ...)` |
+| Outbox write | `OutboxEventRecorder` in `common/messaging`, called by the slice `Handler` — **never** a per-slice `insertOutboxEvent` | `outbox.record(conn, ...)` |
+| Outbox table access | one `OutboxSql` in `common/messaging`, `Connection`-first | `insertOutboxEvent`, `findUnpublished`, `markPublished` |
 | Outbox relay job | `<Task>Job`, in `common/messaging` | `OutboxRelayJob` |
 | Outbox dispatcher | one per service, in `common/messaging` | `OutboxDispatcher` |
 | Relay-mode config | `@ConfigMapping` in `common/messaging` | `OutboxConfig.RelayMode` |
@@ -305,7 +333,7 @@ Rules:
 ## Checklist for a new event
 
 1. Define `<Event>Payload` in the slice's `dto/` + its JSON Schema in `contracts/`; name the topic and channel per convention.
-2. Producer: `insertOutboxEvent` method on the slice's `Sql`, called from `Handler.execution()` on the shared `Connection`, storing the resolved `topic`; `process()` passes the returned id to `OutboxDispatcher.dispatchAfterCommit()`.
+2. Producer: `OutboxEventRecorder.record(conn, ...)` from `common/messaging`, called from `Handler.execution()` on the shared `Connection`, storing the resolved `topic`; the returned id goes to `OutboxDispatcher.dispatchAfterCommit()`. Do not add an `insertOutboxEvent` to the slice's `Sql` — the recorder is the only writer.
 3. Relay: set `app.messaging.outbox.relay-mode` per environment and keep `poller.every=off` in every mode but `poller`; register the Debezium routing config where the mode is `debezium`.
 4. `@RegisterForReflection` on the payload; `traceparent` + `traceContext` captured from `Span.current()` at insert time.
 5. Consumer: `<Event>Consumer` in the slice folder delegating to the `Handler`, idempotency inside the transaction, DLQ topic + owner + alert, `@Blocking`.

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

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

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

@@ -9,7 +9,7 @@ Applies to any Quarkus backend project; project directives (CLAUDE.md, ADRs, exp
 
 Persistence is explicit SQL through the Agroal pool. No Panache, no Hibernate, no reflection-based row mappers. Data access lives in the slice's `<Slice>Sql` class — the driven adapter of the vertical slice (see quarkus-hexagonal-core skill). There are no `*Repository` ports and no `Jdbc*` adapters: one `Sql` class per slice, called only by that slice's `Handler`.
 
-One clarification to keep teams from chasing ghosts: **Agroal is a JDBC (blocking) pool** — there is no "reactive Agroal". The reactive path in Quarkus is the Vert.x SQL client (`quarkus-reactive-pg-client`) with its own pool. Default choice here is **Agroal + JDBC** (simpler, dominant skill base, works perfectly in native); reactive client only for measured hot paths with extreme concurrency (see §7).
+One clarification to keep teams from chasing ghosts: **Agroal is a JDBC (blocking) pool** — there is no "reactive Agroal". The reactive path in Quarkus is the Vert.x SQL client (`quarkus-reactive-pg-client`) with its own pool. Default choice here is **Agroal + JDBC** (simpler, dominant skill base, works perfectly in native); reactive client only for measured hot paths with extreme concurrency (see §8).
 
 ## 1. Datasource configuration (Agroal)
 
@@ -78,7 +78,7 @@ Absolute rules:
 - SQL as `private static final String` text blocks (comma-first concatenation is equally acceptable), schema-qualified. Never concatenate user input — `PreparedStatement` placeholders ALWAYS (SQL injection + plan cache).
 - Quote reserved-word schemas and tables: `"order".party`. Verify the real schema name before writing the query.
 - Dynamic WHERE clauses: build from a whitelist of column/operator constants, values still as placeholders.
-- Methods declare `throws SQLException` and never catch it — the `Handler` translates it (§8). No `commit`, `rollback` or `setAutoCommit` here, ever.
+- Methods declare `throws SQLException` and never catch it — the `Handler` translates it (§9). No `commit`, `rollback` or `setAutoCommit` here, ever.
 - One private `mapRow(ResultSet) -> Dto` per `Sql` class. Rows map to the slice's own DTOs; there is no separate domain entity and no `*RowMapper` class. No reflection mappers: they break native and hide cost.
 
 Naming (canonical rules in the quarkus-hexagonal-core skill):
@@ -90,7 +90,7 @@ Naming (canonical rules in the quarkus-hexagonal-core skill):
 | SQL constant | `UPPER_SNAKE_CASE` matching the method, `private static final String` | `SELECT_PARTY_BY_ID`, `INSERT_PARTY` |
 | Table / column | `snake_case`, singular table name, schema-qualified | `customer.party`, `created_at` |
 | Row target | the slice's `*Dto` | `PartyDto` |
-| Technical exception | `PersistenceException` + specific subtypes (§8) | `TransientPersistenceException` |
+| Technical exception | `PersistenceException` + specific subtypes (§9) | `TransientPersistenceException` |
 
 Never name this class `*Repository`, `*Dao`, `*Manager` or `*Service` — those suffixes are banned by the core skill's ArchUnit rules. An `Sql` class that grows an `if` encoding a business rule has swallowed logic that belongs in the `Handler`.
 
@@ -116,7 +116,7 @@ public class CreatePartyIndividualHandler {
             UUID partyId = sql.insertParty(conn, request.getTenantId(), "Individual",
                 "Active", request.getCreatedBy());
             sql.insertIndividual(conn, partyId, request.getGivenName(), request.getFamilyName());
-            sql.insertOutboxEvent(conn, partyId, "party", EVENT_TYPE, TOPIC, payloadJson(partyId, request), traceparent());
+            outbox.record(conn, "party", partyId.toString(), EVENT_TYPE, TOPIC, eventMap(partyId, request));
             return partyId;
         } catch (SQLException e) {
             throw SqlStateTranslator.translate("PTY-500-001", e);      // unchecked -> container rolls back
@@ -129,7 +129,7 @@ public class CreatePartyIndividualHandler {
 
 - `@Transactional` goes on `process()` only — never on a private method (CDI interceptors don't fire on self-invocation, so the transaction would silently never open), never on the `Sql` class.
 - **Read-only slices skip `@Transactional` entirely.** A single `SELECT`, or several reads that tolerate a non-repeatable view, are cheaper without a JTA transaction — still one `Connection`, opened and closed in `execution()`. Add the annotation the moment there is a write, or when several reads must see one snapshot.
-- Runtime exceptions roll back by default; `BusinessException` extends `RuntimeException`, so throwing it rolls back — correct by construction. A checked `SQLException` would **not** roll back, which is why §8 translation is mandatory.
+- Runtime exceptions roll back by default; `BusinessException` extends `RuntimeException`, so throwing it rolls back — correct by construction. A checked `SQLException` would **not** roll back, which is why §9 translation is mandatory.
 - Programmatic control when annotations don't fit (loops with per-item commit, batch jobs) — from a `common/` bean or a `*Job`, never from inside a slice `Handler`:
 
 ```java
@@ -166,7 +166,7 @@ public UUID insertParty(Connection conn, String tenantId, String partyType,
 - **Generated ids**: when the PK has a database default (`id uuid DEFAULT customer.uuidv7() NOT NULL`), exclude `id` from the column list and never bind it. Read it back with `RETURNING id` + `executeQuery()` — preferred over `getGeneratedKeys()`.
 - Check `executeUpdate()` counts — 0 rows on an expected UPDATE is a bug or a concurrency signal, not a success. The `Handler` decides what that means; `Sql` just returns the count.
 - Optimistic locking: `version` column, `UPDATE ... WHERE id = ? AND version = ?`; 0 rows → the `Handler` throws `StaleVersionException` (code-carrying, in `common/exception`) with the slice's conflict code → 409 via its dedicated mapper (see quarkus-error-handling-i18n skill). It is not SQLState-derived — no `SQLException` occurs, so `SqlStateTranslator` never sees it; the `Handler` checks the update count. Do NOT name it `ConcurrentModificationException` — it shadows `java.util.ConcurrentModificationException` and an accidental import turns the 409 mapping into a 500.
-- Upserts: `ON CONFLICT ... DO UPDATE` explicitly; never SELECT-then-INSERT races. A unique-violation (`23505`) surfacing as a `SQLException` is translated by the `Handler` (§8), not swallowed here.
+- Upserts: `ON CONFLICT ... DO UPDATE` explicitly; never SELECT-then-INSERT races. A unique-violation (`23505`) surfacing as a `SQLException` is translated by the `Handler` (§9), not swallowed here.
 
 ## 5. Batches, pagination, jsonb
 
@@ -205,9 +205,22 @@ ps.setObject(5, pgo);
 
 Read side: `rs.getString("context")` then parse. Index jsonb lookups you actually query (`(context->>'trace_id')`).
 
-## 6. A tiny helper is allowed; a framework is not
+## 6. Cross-cutting tables get a cross-cutting `Sql`
 
-To kill boilerplate, ONE small internal helper class (~50 lines) per service or shared lib is the sanctioned maximum:
+One `Sql` class per slice is the rule for the slice's **own** tables. A table that every slice writes the same way — `outbox`, `audit_event`, `processed_event` — gets **one** `Sql` class in `common/`, and a `Connection`-first capability bean in front of it:
+
+| Table | Owner in `common/` | Called by |
+|---|---|---|
+| outbox | `OutboxSql` + `OutboxEventRecorder` (`common/messaging`) | slice `Handler`s, `OutboxDispatcher`, `OutboxRelayJob` |
+| audit_event | `AuditRecorder` (`common/audit`) | slice `Handler`s |
+
+The transactional guarantee is unaffected: these methods take the `Connection` the `Handler` already opened in `execution()`, so the row commits with the state change (§3). **Never copy `insertOutboxEvent` (or any other cross-cutting insert) onto a `<Slice>Sql`.** The columns are fixed by the migration and the envelope is fixed by the messaging standard, so every copy is identical by construction — and identical-by-construction code that is nonetheless written N times drifts: one slice grows a null-guard for a `NOT NULL` column, another falls behind a column addition, and nothing fails until the relay cannot route a row. The `duplicate twice, extract on the third` rule (hexagonal-core skill) is about code that might *turn out* to differ per slice; this cannot.
+
+This does not license a `common/` grab-bag: it applies to tables `common/` genuinely owns, not to a query two slices happen to share today.
+
+## 7. A tiny helper is allowed; a framework is not
+
+To kill boilerplate, ONE small internal helper class (~50 lines) per service or shared lib is the sanctioned maximum. (The cross-cutting owners of §6 are not helpers and do not count against this budget — they own a table, they do not generalize SQL.)
 
 ```java
 public final class Jdbc {   // common/util — the one sanctioned exception to the banned-suffix rule
@@ -225,7 +238,7 @@ Note the signatures take `Connection`, not `DataSource` — the helper must not
 - The class is named `Jdbc` — a namespace, not `JdbcUtils`/`JdbcHelper`. The banned-suffix ArchUnit rule (see quarkus-hexagonal-core skill) exists precisely to stop this class from becoming a junk drawer.
 - jOOQ (code-gen, type-safe SQL) MAY be evaluated as an alternative via formal ADR; MyBatis/Hibernate remain excluded.
 
-## 7. Blocking model: worker threads or virtual threads (and when reactive)
+## 8. Blocking model: worker threads or virtual threads (and when reactive)
 
 JDBC blocks. Never run it on the event loop:
 
@@ -234,7 +247,7 @@ JDBC blocks. Never run it on the event loop:
 - **Virtual threads**: `@RunOnVirtualThread` on JDBC-heavy endpoints is the modern default for high-concurrency blocking work (Java 25 baseline; synchronized-block pinning is fixed since JDK 24) — cheap threads, same simple code. Caveat: keep pool `max-size` as the real ceiling; virtual threads make it easy to pile up on `acquisition-timeout`.
 - **Reactive SQL client** (`quarkus-reactive-pg-client`, Vert.x pool — NOT Agroal): only for measured hot paths (extreme fan-in, streaming thousands of rows). It's a different programming model and a second pool to size; adopting it in a service requires an ADR. Do not mix both models in the same repository class.
 
-## 8. SQLException translation
+## 9. SQLException translation
 
 `Sql` methods propagate `SQLException`; the `Handler` catches it once, in `execution()`, and translates it through `SqlStateTranslator` (`common/error`) so nothing checked ever escapes `process()` — a checked exception would not trigger the container rollback:
 
@@ -256,7 +269,7 @@ Every resulting code is registered in `ErrorCatalog` and present in all locale b
 
 Set `statement_timeout` (session or per-datasource via `quarkus.datasource.jdbc.additional-jdbc-properties.options=-c statement_timeout=5000`) so runaway queries fail fast instead of holding pool connections.
 
-## 9. Schema migrations (Flyway — opt-in, disabled by default)
+## 10. Schema migrations (Flyway — opt-in, disabled by default)
 
 The schema is versioned in git as SQL under `db/` in every environment. **Who applies it is a flag**, because a service is rarely allowed to alter its own schema in production — that is a DBA or pipeline responsibility, and a native binary starting up in a replica set is the worst possible place to run DDL.
 
@@ -289,11 +302,11 @@ Rules:
 - The extension stays in `pom.xml` even when disabled — one binary for every environment, and a runtime flag can't resurrect a dependency that isn't there. Drop `quarkus-flyway` entirely only if no environment migrates at boot; then `db/` is applied exclusively by the pipeline.
 - Cross-cutting tables (`outbox_event`, `processed_event`, `audit_event` — see kafka/observability skills) are ordinary migrations in the same `db/migration` folder, not runtime-created.
 
-## 10. Testing
+## 11. Testing
 
 - `<Slice>Sql` tests: `@QuarkusTest` + Dev Services (Testcontainers Postgres starts automatically — no config). Real SQL against real Postgres; never H2 (dialect lies). Obtain a `Connection` in the test and pass it in, exactly as the `Handler` does.
 - `<Slice>Handler` tests are pure Mockito with a mocked `Sql` — no database (see quarkus-hexagonal-core skill).
-- Flyway migrations run at test start — `%test` is one of the two profiles where the flag is on (`quarkus.flyway.enabled=true` + `migrate-at-start=true`, see §9), so tests validate DDL and queries together against the same SQL production will receive.
+- Flyway migrations run at test start — `%test` is one of the two profiles where the flag is on (`quarkus.flyway.enabled=true` + `migrate-at-start=true`, see §10), so tests validate DDL and queries together against the same SQL production will receive.
 - Native verification: `@QuarkusIntegrationTest` re-runs the same tests against the binary.
 
 ## Checklist for a new `Sql` method
@@ -306,3 +319,4 @@ Rules:
 5. `executeUpdate()` count returned or checked; `SQLException` propagated for the `Handler` to translate, never swallowed.
 6. Generated ids via `RETURNING`; jsonb via `PGobject`; batch + chunking for bulk; keyset pagination if deep.
 7. Rows mapped by hand into the slice's `*Dto`; Dev Services test written.
+8. The table belongs to this slice. If it is cross-cutting (`outbox`, `audit_event`, `processed_event`), the method belongs in `common/` (§6) — not here.