eva4j 1.0.17 → 1.0.18

package/src/skills/build-system-yaml/SKILL.md

@@ -47,6 +47,9 @@ Antes de generar nada, lee estos archivos del proyecto para obtener contexto:
 | 6.5 | `system/c4-context.mmd` + `system/c4-container.mmd` | Este archivo (sección C4) |
 | 7 | `system/{module}.yaml` (uno por módulo) | `references/domain-yaml-spec.md` |
 | 8 | `system/{module}.md` (uno por módulo) | `references/module-spec.md` |
+| 9a | `AGENTS.md` (project root — rewrite) | Este archivo (Paso 9) |
+| 9b | `system/VALIDATION_FLOWS.md` | Este archivo (Paso 9) |
+| 9c | `system/USER_FLOWS.md` | Este archivo (Paso 9) |
 
 Ejecuta **todos** los pasos en orden antes de devolver el control al usuario.
 
@@ -54,7 +57,14 @@ Ejecuta **todos** los pasos en orden antes de devolver el control al usuario.
 
 ## Paso 1 — Recopilar información
 
-Si el usuario no proveyó todos los datos, **pregunta** antes de generar:
+**Antes de preguntar nada**, verifica si ya existen artefactos del skill `requirements-elicitation`:
+- `system/FUNCTIONAL_REQUIREMENTS.md` — casos de uso, actores, ciclos de vida, integraciones externas
+- `system/PRODUCT_FLOWS.md` — flujos de negocio por actor (happy paths + alternativos)
+- `system/BUSINESS_RULES.md` — reglas de negocio, invariantes, restricciones
+
+Si existen, **léelos primero** y extrae de ellos el contexto de negocio. Reduce o elimina las preguntas que ya están respondidas por estos archivos. Estos documentos son la fuente de verdad funcional — los módulos, casos de uso, estados y reglas que diseñes deben ser consistentes con lo que describen.
+
+Si el usuario no proveyó todos los datos y los archivos anteriores no existen, **pregunta** antes de generar:
 
 0. **Contexto del negocio** — ¿Cuál es el dominio? Actores, procesos clave, reglas importantes.
 1. **¿Usa mensajería asíncrona?** `kafka` | `rabbitmq` | `sns-sqs`
@@ -337,13 +347,36 @@ Lee `references/domain-yaml-spec.md` para la especificación completa de estruct
 
 Para cada módulo en `modules:`, genera `system/{nombre-del-modulo}.yaml` con: aggregates, entities, valueObjects, enums (con transitions si aplica), events, endpoints, listeners, ports y **readModels** — todo inferido del `system.yaml`.
 
+### Endpoints en módulos con múltiples agregados
+
+Si el módulo tiene **2 o más agregados** (ej: `Product` + `Category`), la sección `endpoints:` debe usar `basePath: ""` (string vacío) y paths **absolutos** en cada operación:
+
+```yaml
+# Módulo con 2+ agregados → basePath vacío
+endpoints:
+  basePath: ""
+  versions:
+    - version: v1
+      operations:
+        - useCase: CreateProduct
+          method: POST
+          path: /products
+        - useCase: CreateCategory
+          method: POST
+          path: /categories
+```
+
+Si el módulo tiene **un solo agregado**, usar `basePath: /recurso` con paths relativos (ej: `/`, `/{id}`).
+
+**NUNCA usar `basePath: /`** (con slash) — genera trailing slash en `@RequestMapping`. Usar `basePath: ""` (vacío).
+
 ### Inferencia de readModels desde system.yaml
 
 Cuando `integrations.async[].consumers[]` tiene `readModel:` y el `module` es el módulo actual:
 1. Agrupar todos los eventos del mismo `readModel:` → una entrada `readModels:` con múltiples `syncedBy`
 2. `source.module` = el `producer` de esas integraciones async
 3. `source.aggregate` = derivar del nombre del readModel (ej: `ProductReadModel` → `Product`)
-4. `tableName` = `rm_` + snake_case del source module (ej: `rm_products`)
+4. `tableName` = `rm_` + consumer module + `_` + source module en snake_case (ej: `rm_orders_products`)
 5. `fields` = inferir del payload del evento fuente (incluir siempre `id`)
 6. `syncedBy[].action` = `UPSERT` para Created/Updated, `SOFT_DELETE` para Deactivated, `DELETE` para Deleted
 7. Si había una entrada `integrations.sync[]` al mismo módulo fuente → **no generar `ports:`** para esa llamada (el readModel la reemplaza)
@@ -435,10 +468,197 @@ Para cada módulo, genera `system/{nombre-del-modulo}.md` con: rol del módulo,
 
 ---
 
+## Paso 9 — Artefactos post-diseño
+
+Inmediatamente después de completar el Paso 8, genera tres artefactos finales que contextualizan el sistema recién diseñado.
+
+### Paso 9a — Reescribir AGENTS.md (project-specific)
+
+Reescribe el archivo `AGENTS.md` en la **raíz del proyecto** con contenido específico para el sistema diseñado.
+
+**Proceso:**
+
+1. Lee el `AGENTS.md` actual como template base
+2. Analiza `system/system.yaml` y todos los `system/{module}.yaml` para detectar qué features se usan:
+   - Tipo de broker (Kafka / RabbitMQ / ninguno)
+   - `readModels:` en algún módulo
+   - `ports:` (llamadas HTTP síncronas)
+   - `listeners:` (consumidores de eventos)
+   - `events:` con `triggers:` vs `lifecycle:`
+   - `hasSoftDelete` en alguna entidad
+   - `audit.trackUser` en alguna entidad
+   - Value Objects con `methods:`
+   - Enums con `transitions:` e `initialValue`
+   - Flags de campo: `readOnly`, `hidden`, `defaultValue`, `validations`, `reference`
+3. **Poda** secciones de features no usados según estas reglas:
+
+| Condición | Sección a eliminar |
+|---|---|
+| Sin Temporal | "Temporal Workflows" completa |
+| Sin `readModels:` | Subsecciones readModels de "Características Avanzadas" y checklist |
+| Sin `ports:` | Subsecciones ports |
+| Sin `listeners:` | Subsecciones listeners |
+| Sin `hasSoftDelete` | Sección soft delete y checklist items |
+| Sin `audit.trackUser` | Infraestructura UserContextFilter/UserContextHolder/AuditorAwareImpl (mantener audit básico si `audit.enabled`) |
+| Sin VO `methods:` | "Value Objects con Métodos" |
+| Sin enum `transitions:` | "Enums con Ciclo de Vida" |
+
+4. **Especializa** el contenido restante:
+   - Reemplaza ejemplos genéricos (`User`, `Order`) con entidades/módulos reales del proyecto
+   - Actualiza la sección de comandos `eva` con los nombres de módulos reales
+   - Actualiza el ejemplo de `domain.yaml` con la estructura real del proyecto
+   - Reduce el checklist a solo items relevantes para este proyecto
+5. Agrega un **header de contexto** al inicio:
+
+```markdown
+# AI Agent Guide — {System Name}
+
+## Project Overview
+- **System:** {name} — {brief description from system.yaml}
+- **Modules:** {list of modules with 1-line descriptions}
+- **Messaging:** {broker type or "none"}
+- **Database:** {database type}
+- **Java:** {javaVersion} / **Spring Boot:** {springBootVersion}
+```
+
+6. **Siempre conserva** (son universales): principios DDD, arquitectura hexagonal, reglas de mappers, reglas de DTOs, diagramas de flujo de datos (Command write / Query read), patrones de testing
+7. Escribe **todo en inglés**
+8. **Límite: ≤ 1000 líneas** — poda agresivamente, comprime ejemplos, evita redundancia
+
+---
+
+### Paso 9b — Crear system/VALIDATION_FLOWS.md
+
+Genera `system/VALIDATION_FLOWS.md` con los flujos de validación técnica del sistema. Toda la información se deriva de `system.yaml` y los `{module}.yaml`.
+
+**Estructura obligatoria:**
+
+```markdown
+# Validation Flows — {System Name}
+
+## Prerequisites
+- Services: {infrastructure requerida — DB, broker, etc.}
+- Startup order: {si relevante}
+- Base URLs: {por módulo si difieren}
+
+## 1. Module Validation
+
+### 1.1 {Module Name}
+
+#### CRUD Operations
+| # | Operation | Endpoint | Payload/Params | Expected Result | Validates |
+|---|-----------|----------|----------------|-----------------|------ ----|
+| 1 | Create | POST /x | {key fields} | 201 + entity | {invariant} |
+| 2 | Get by ID | GET /x/{id} | — | 200 + entity | — |
+| 3 | List | GET /x | — | 200 + page | — |
+| 4 | Update | PUT /x/{id} | {fields} | 200 + updated | — |
+| 5 | Delete | DELETE /x/{id} | — | 204 | — |
+
+#### State Transitions (if module has enum transitions)
+| # | Transition | Endpoint | Precondition | Expected | Event Emitted |
+|---|-----------|----------|--------------|----------|---------------|
+| 1 | DRAFT→PUBLISHED | PUT /x/{id}/publish | exists in DRAFT | 200, status=PUBLISHED | XPublishedEvent |
+
+#### Business Rules
+| # | Rule | How to Trigger | Expected Error |
+|---|------|----------------|----------------|
+
+(repeat per module)
+
+## 2. Integration Flows
+
+### 2.1 {Flow Name}: {Event} → {Consumer Module}
+**Trigger:** {action that emits the event}
+**Steps:**
+1. {Create/modify entity in producer module}
+2. {Event emitted}: {EventName} on topic {TOPIC_NAME}
+3. {Consumer module} processes via {useCase}
+4. **Verify:** {expected state change in consumer}
+
+(repeat per async integration)
+
+## 3. Read Model Synchronization (if applicable)
+### 3.1 {ReadModelName}
+| Source Event | Action | Verification |
+|---|---|---|
+| XCreatedEvent | UPSERT | Query rm_table, record exists |
+| XUpdatedEvent | UPSERT | Fields updated |
+| XDeactivatedEvent | SOFT_DELETE | Record marked deleted |
+
+## 4. Sync Port Calls (if applicable)
+### 4.1 {PortName}: {caller} → {target}
+| Method | Expected | Fallback |
+|---|---|---|
+
+## 5. Error & Edge Cases
+| # | Scenario | Steps | Expected Error |
+|---|----------|-------|----------------|
+| 1 | Create with missing required field | POST /x without {field} | 400 + validation message |
+| 2 | Invalid state transition | PUT /x/{id}/action when invalid state | 400/409 + business error |
+| 3 | Get non-existent entity | GET /x/{invalid-id} | 404 |
+```
+
+**Reglas:**
+- Cada flujo debe ser concreto: paths reales, nombres de eventos reales, campos reales del proyecto
+- Incluir payloads JSON sugeridos donde sea útil
+- Omitir secciones enteras si no aplican (ej: sin readModels → omitir sección 3)
+- Todo en inglés
+
+---
+
+### Paso 9c — Crear system/USER_FLOWS.md
+
+Genera `system/USER_FLOWS.md` con los flujos end-to-end desde la perspectiva del usuario.
+
+**Estructura obligatoria:**
+
+```markdown
+# User Flows — {System Name}
+
+## Actors
+| Actor | Description | Modules Interacted |
+|-------|-------------|--------------------|
+| {Actor 1} | {role description} | {module list} |
+
+## Flow 1: {Business Process Name}
+**Actor:** {who}
+**Goal:** {what they want to achieve}
+**Preconditions:** {initial state}
+
+### Happy Path
+| Step | User Action | System Response | Behind the Scenes |
+|------|-------------|-----------------|-------------------|
+| 1 | {does X} | {sees Y} | {endpoint called, event emitted, etc.} |
+| 2 | {does Z} | {sees W} | {consumer processes, state changes} |
+
+### Alternative Paths
+| Condition | At Step | What Happens |
+|-----------|---------|---------- ---|
+| {condition} | {N} | {alternative outcome} |
+
+### Error Paths
+| Error | At Step | User Sees |
+|-------|---------|----------|
+| {error} | {N} | {error message/behavior} |
+
+(repeat per major business flow)
+```
+
+**Reglas:**
+- Derivar actores de quienes consumen los `exposes[]` (misma fuente que `Person()` del C4 Context)
+- Cada flujo es un **escenario de negocio completo** que cruza módulos cuando aplica
+- La columna "Behind the Scenes" conecta la experiencia de usuario con la realidad técnica (eventos, procesamiento async, state changes)
+- Incluir al menos un flujo por cada camino principal de caso de uso del sistema
+- Foco en comportamiento observable por el usuario, no implementación interna
+- Todo en inglés
+
+---
+
 ## Ciclo de refinamiento
 
 Después de entregar v1, si el usuario pide ajustes:
 - Aplica el **cambio mínimo** necesario
 - Revalida el checklist del Paso 4
 - Actualiza `system.md`, `c4-context.mmd`, `c4-container.mmd`, `{module}.yaml` y `{module}.md` afectados
+- Actualiza `AGENTS.md`, `VALIDATION_FLOWS.md` y `USER_FLOWS.md` si fueron afectados por el cambio
 - Entrega solo el diff explicado

package/src/skills/build-system-yaml/references/domain-yaml-spec.md

@@ -25,7 +25,7 @@ Propón campos necesarios no mencionados, Value Objects expresivos, invariantes
 4. ❌ **No `transitions` sin `initialValue`** en el enum
 5. ❌ **No inventar módulos en `reference.module`** — solo los de `system/system.yaml`
 6. ❌ **No duplicar en `endpoints:`** lo de `system.yaml → exposes:`
-7. ❌ **`endpoints:` NUNCA es lista plana** — siempre `{ basePath, versions: [{ version, operations }] }`
+7. ❌ **`endpoints:` NUNCA es lista plana** — siempre `{ basePath, versions: [{ version, operations }] }`. Si el módulo tiene **2+ agregados**, usar `basePath: ""` y paths absolutos por operación
 8. ❌ **No inventar eventos** — deben coincidir con `integrations.async[]` donde `producer` es este módulo
 9. ❌ **No inventar listeners** — deben coincidir con `integrations.async[].consumers[]` donde `module` es este módulo
 10. ❌ **No inventar ports** — deben coincidir con `integrations.sync[]` donde `caller` es este módulo
@@ -76,6 +76,50 @@ endpoints:
           path: /{id}
 ```
 
+### Módulos con múltiples agregados
+
+Cuando un módulo contiene **2 o más agregados** (ej: Product + Category), NO es posible usar un solo `basePath` porque cada agregado tiene su propio recurso REST. En este caso:
+
+- Usar `basePath: ""` (string vacío — **NO** `basePath: /` que genera slash trailing)
+- Declarar paths **absolutos** en cada operación (ej: `/products`, `/categories/{id}`)
+- El controlador generado tendrá `@RequestMapping("/api/v1")` (limpio, sin slash extra)
+
+```yaml
+# ✅ Módulo con múltiples agregados — basePath vacío + paths absolutos
+endpoints:
+  basePath: ""
+  versions:
+    - version: v1
+      operations:
+        # ── Product operations ──
+        - useCase: CreateProduct
+          method: POST
+          path: /products
+        - useCase: GetProduct
+          method: GET
+          path: /products/{id}
+        - useCase: FindAllProducts
+          method: GET
+          path: /products
+        # ── Category operations ──
+        - useCase: CreateCategory
+          method: POST
+          path: /categories
+        - useCase: GetCategory
+          method: GET
+          path: /categories/{id}
+        - useCase: FindProductsByCategory
+          method: GET
+          path: /categories/{id}/products
+```
+
+**Regla de decisión:**
+
+| Agregados en el módulo | basePath | Paths en operations |
+|---|---|---|
+| 1 agregado | `/recurso` (ej: `/orders`) | Relativos: `/`, `/{id}`, `/{id}/confirm` |
+| 2+ agregados | `""` (vacío) | Absolutos: `/products`, `/categories/{id}` |
+
 ---
 
 ## Estructura completa del module.yaml
@@ -350,7 +394,7 @@ readModels:
     source:                              # Trazabilidad al módulo fuente (OBLIGATORIO)
       module: products                   # Módulo fuente (kebab-case)
       aggregate: Product                 # Agregado fuente (PascalCase)
-    tableName: rm_products               # Tabla en BD (OBLIGATORIO, prefijo rm_)
+    tableName: rm_orders_products         # Tabla en BD (OBLIGATORIO, prefijo rm_{consumer}_{source})
     fields:                              # Campos proyectados — subconjunto del fuente
       - name: id
         type: String
@@ -372,7 +416,7 @@ readModels:
 ### Reglas
 
 - **`name:`** — PascalCase, **DEBE** terminar con `ReadModel`
-- **`tableName:`** — **DEBE** empezar con `rm_` (identificación visual en BD)
+- **`tableName:`** — **DEBE** seguir el patrón `rm_{consumerModule}_{sourceModule}` (ej: `rm_orders_products`) para evitar colisiones en monolitos
 - **`fields:`** — **DEBE** incluir un campo `id`
 - **`syncedBy:`** — **DEBE** tener al menos una entrada
 - **`source.module:`** — **NO PUEDE** ser el mismo módulo actual (cross-module exclusivamente)
@@ -565,7 +609,9 @@ Si un valor no es trazable → falta un endpoint o listener en el diseño.
 - [ ] `events[].triggers[]` referencia métodos existentes en `transitions[].method`
 - [ ] `{entityName}Id` en `events[].fields` cuando cruza módulos via Kafka
 - [ ] `endpoints:` con estructura `{ basePath, versions }` — no lista plana
-- [ ] `endpoints[].path` relativos al basePath
+- [ ] Módulo con 1 agregado → `basePath: /recurso` y paths relativos
+- [ ] Módulo con 2+ agregados → `basePath: ""` y paths absolutos por operación
+- [ ] `endpoints[].path` coherentes con el basePath elegido
 - [ ] `listeners[]` para todos los eventos donde este módulo es consumidor
 - [ ] `listeners[].useCase` coincide con `consumers[].useCase`
 - [ ] `listeners[].topic` bare SCREAMING_SNAKE_CASE (sin topicPrefix)

package/src/skills/build-system-yaml/references/module-spec.md

@@ -34,16 +34,23 @@ Especificación técnica narrativa del sistema completo. Una sección `##` por c
 **Postconditions:** [system state after successful execution]
 **Validations and errors:** [exception conditions and error types]
 **Events emitted:** [DomainEvent name and trigger condition, or "none"]
+**Operations:**
+1. [Load entity / validate precondition — throw NotFoundException or 400 if invalid]
+2. [External port call: {PortName}.{method}() — if applicable]
+3. [Invoke domain method: entity.{method}()]
+4. [Persist via repository]
+5. [Emit event — if applicable]
 
 ### Exposed Endpoints
 [One `####` per endpoint in exposes:]
 
 #### {METHOD} {/path}
 **Purpose:** [endpoint description and usage context]
-**Path params / Query params:** [each parameter described]
-**Request body:** [expected fields, types, validation constraints]
-**Response:** [returned fields and their business meaning]
-**Errors:** [HTTP status codes and when they occur]
+**Path params:** [param — Type — Description; omit if none]
+**Query params:** [GET/DELETE only — param: Type, required/optional, default, description; omit if none]
+**Request body:** [POST/PUT/PATCH only — field: Type — constraint; omit for GET/DELETE]
+**Response:** [GET only — field: Type — business meaning; list endpoints include {content:[...], totalElements, page, size}]
+**Errors:** [HTTP status — condition]
 
 ### Emitted Events
 [Only if module is producer in integrations.async]
@@ -81,6 +88,8 @@ Especificación técnica narrativa del sistema completo. Una sección `##` por c
 - **Incluir useCases de consumers** como casos de uso del módulo consumidor.
 - **Referenciar módulos por nombre**.
 - **Máquinas de estado** cuando hay ciclos de vida.
+- **Endpoints detallados**: separar path params de query params. Para GETs indicar los campos clave de la respuesta con sus tipos. Para POST/PUT/PATCH listar los campos del body con tipo y constraint. Nunca "ver request" como descripción de response.
+- **Operations en casos de uso**: el campo `**Operations:**` es obligatorio en cada `#### {UseCaseName}`. Cada ítem describe un paso concreto del handler referenciando nombres reales de repositorios, ports, métodos de dominio y eventos. No usar items genéricos como "execute business logic".
 - Omitir secciones no aplicables.
 
 ---
@@ -215,6 +224,12 @@ sequenceDiagram
 **Invariants verified:** [ID list — e.g., INV-01, INV-03]
 **Validations and errors:** [exception conditions, error type, HTTP status]
 **Events emitted:** [DomainEvent name and condition, or "none"]
+**Operations:**
+1. [Load entity by id via {Repository}.findById() — throw NotFoundException if absent]
+2. [Call {PortName}.{method}() to obtain cross-module data — if applicable]
+3. [Invoke entity.{domainMethod}() — domain enforces invariants]
+4. [Persist via {Repository}.save(entity)]
+5. [DomainEventHandler publishes event after transaction commit — if applicable]
 
 **Flow diagram:**
 ```mermaid
@@ -235,10 +250,42 @@ flowchart TD
 ### {METHOD} {/path}
 **Use case:** `{UseCase}`
 **Purpose:** [description]
-**Path params / Query params:** [each parameter]
-**Request body:** [fields, types, validations]
-**Response:** [fields and business meaning]
-**Errors:** [HTTP status codes and conditions]
+**Path params:** _(omit table if none)_
+
+| Param | Type | Description |
+|-------|------|-------------|
+| {param} | `String` | [description] |
+
+**Query params:** _(GET / DELETE only — omit table if none)_
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| {param} | `String` | No | — | [description] |
+
+**Request body:** _(POST / PUT / PATCH only — omit for GET / DELETE)_
+```json
+{
+  "field": "String",       // required — [constraint]
+  "otherField": "Integer"  // optional — [constraint]
+}
+```
+
+**Response schema:** _(GET single only — omit for mutations)_
+```json
+{
+  "id": "String",
+  "field": "Type"          // [business meaning]
+}
+```
+_(For GET list: `{ "content": [...], "totalElements": "Long", "page": "Integer", "size": "Integer" }`)_
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 404 | [entity] not found |
+| 400 | [validation failure] |
+| 409 | [invariant violated] |
 
 ## Emitted Events
 [Only if module is producer in integrations.async]
@@ -290,6 +337,8 @@ flowchart TD
 - **Diagrama de flujo por caso de uso**: `flowchart TD` dentro de cada `### {UseCase}` con trigger, invariantes, lógica y eventos.
 - **Máquina de estados condicional**: solo si hay entidades con ciclo de vida. Restricciones de transición son invariantes implícitas.
 - **Referenciar invariantes** en cada caso de uso (INV-01, INV-02...).
+- **Endpoints con contratos ricos**: para cada endpoint separar path params, query params, body y response en bloques distintos con tipos y constraints reales del dominio. Para GETs incluir el JSON schema de respuesta; para POST/PUT/PATCH el JSON del body. Listas incluyen wrapper de paginación `{ content, totalElements, page, size }`. Nunca usar placeholders genéricos.
+- **Operations en casos de uso**: el campo `**Operations:**` es **obligatorio** en cada `### {UseCase}`. Lista los pasos del handler con nombres concretos: repositorio, port, método de dominio, evento. Sirve como contrato de implementación evaluable por revisores humanos antes de generar código.
 - **No duplicar** system.md — el `.md` del módulo es la especificación completa.
 - Archivos en `system/{module-name}.md`.