@imolko/ultra-agent 0.1.0-beta

package/docs/adr/foundational/A-011-characterization-first-refactoring.md

@@ -0,0 +1,90 @@
+# A-011: Refactoring con characterization tests
+
+**Estado**: Aceptado
+
+**Fecha**: 2025-07-09
+
+**originally**: ultra-reporter-009, ultra-reporter-010
+
+**tags**: testing
+
+## Contexto
+
+Al enfrentar código legacy o duplicado, el enfoque tradicional de "refactorizar y después probar" es riesgoso: sin tests que capturen el comportamiento actual, los cambios pueden introducir regresiones silenciosas. El riesgo se multiplica cuando existe lógica duplicada en múltiples ubicaciones (módulos compartidos, copias en diferentes lenguajes, métodos inline en clases monolíticas).
+
+Antes de modificar la estructura del código, necesitamos una red de seguridad que garantice que el comportamiento observable se preserva.
+
+## Decisión
+
+Adoptar el enfoque **characterization-first**: escribir tests de caracterización antes de cualquier refactoring, siguiendo un orden estricto de tres fases.
+
+### Fase 1: Caracterizar
+
+Escribir tests que capturen el comportamiento actual del sistema, sin modificarlo. Estos tests:
+
+- Ejecutan el código tal como existe hoy, con sus entradas y salidas reales
+- No validan "corrección" — validan "así funciona ahora": el complemento del ciclo TDD, que especifica el comportamiento deseado ([A-003](./A-003-tdd.md))
+- Cubren los caminos principales (happy path) y edge cases visibles
+- Sirven como red de seguridad: si un refactor cambia el comportamiento, los tests lo detectan
+
+### Fase 2: Refactorizar
+
+Con los tests de caracterización en verde, modificar la estructura interna del código en un orden específico:
+
+1. **Unificar código duplicado primero.** Extraer lógica común dispersa en múltiples ubicaciones hacia un módulo compartido. Todas las copias pasan a consumir la fuente unificada. Eliminar las copias redundantes.
+2. **Migrar a la plataforma destino después.** Con la lógica ya consolidada en módulos compartidos, migrar los consumidores a la plataforma destino. Los módulos compartidos son la base estable sobre la que se construye la migración.
+3. **Descomponer monolitos al final.** Con el código unificado y migrado, dividir archivos que exceden los límites de forma ([A-046](./A-046-metricas-de-forma-y-legibilidad-del-codigo.md)) en unidades composables ([A-044](./A-044-composicion-funcional-procesos-operaciones.md)).
+
+**Por qué este orden:**
+
+- Unificar primero crea la base compartida que necesitan la migración y la descomposición
+- Migrar segundo se apoya en módulos ya consolidados, reduciendo la superficie de cambio
+- Descomponer al final opera sobre código ya unificado y migrado, con dependencias claras
+
+Cada paso tiene un punto de partida definido y tests que lo respaldan. Ningún paso requiere tocar más código del necesario.
+
+### Qué código merece tests de caracterización
+
+No todo el código justifica el esfuerzo de caracterizarlo. Aplicar estos criterios:
+
+| Situación | ¿Caracterizar? | Razón |
+|-----------|:---:|-------|
+| **Fuente de verdad** (módulo canónico del que otras copias derivan) | ✅ Sí | Es la referencia contra la que se validan las copias |
+| **Lógica duplicada** en múltiples ubicaciones | ❌ No | Testear solo la fuente de verdad; las copias se validan por comparación |
+| **Código que será eliminado** (copias redundantes) | ❌ No | No invertir esfuerzo en código con fecha de caducidad |
+| **Lógica de negocio compleja** con múltiples caminos | ✅ Sí | El riesgo de regresión justifica la inversión |
+| **Coordinación I/O** (orquestación de llamadas externas) | ⚠️ Condicional | Solo si la orquestación tiene complejidad no trivial |
+| **Configuración y wiring** (inyección de dependencias, setup) | ❌ No | Se valida con tests de integración post-refactor |
+
+**Regla general**: testear solo la fuente de verdad, no las copias. Las copias se cubren indirectamente cuando, tras la unificación, consumen el módulo compartido.
+
+### Orden de operaciones en la práctica
+
+```
+1. Identificar código duplicado y su fuente de verdad
+2. Escribir characterization tests para la fuente de verdad
+3. Extraer fuente de verdad a módulo compartido
+4. Redirigir consumidores al módulo compartido
+5. Eliminar copias redundantes
+6. Migrar consumidores a plataforma destino
+7. Descomponer monolitos en unidades composables
+```
+
+Los tests de caracterización se ejecutan después de cada paso para verificar que el comportamiento se preserva.
+
+## Consecuencias
+
+### Positivas
+
+- **Red de seguridad antes de tocar código**: los tests de caracterización capturan regresiones inmediatamente
+- **Sin esfuerzo duplicado**: testear solo la fuente de verdad evita escribir los mismos tests para cada copia
+- **Orden con fundamento**: cada fase construye la base para la siguiente, minimizando el riesgo
+- **Criterios claros**: saber qué testear y qué no reduce la parálisis por análisis
+- **Deuda técnica controlada**: las copias redundantes tienen fecha de caducidad desde el inicio
+
+### Negativas
+
+- **Inversión inicial**: caracterizar lleva tiempo antes de ver mejoras estructurales
+- **Disciplina de orden**: saltarse una fase (ej. descomponer antes de unificar) crea retrabajo
+- **Tests desechables**: los tests de caracterización pueden volverse redundantes una vez que se escriben tests unitarios post-refactor. Esto es aceptable: cumplieron su propósito como red de seguridad durante la transición
+- **Compatibilidad temporal**: durante la fase de unificación puede ser necesario manejar diferencias de módulo entre el origen y la plataforma destino hasta completar la migración

package/docs/adr/foundational/A-012-helm-mecanismo-primario-despliegue.md

@@ -0,0 +1,67 @@
+# A-012: Helm como mecanismo primario de despliegue para aplicaciones servidor
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-12
+
+**originally**: generator-021
+
+**Enriquecido desde**: Generator ADR 021 — Helm Chart Deployment with Pre-Built Docker Image
+
+**tags**: despliegue
+
+## Contexto
+
+Las aplicaciones servidor de Imolko se ejecutan sobre Kubernetes y requieren un mecanismo de despliegue que sea:
+
+- **Declarativo**: el estado deseado se describe en archivos versionados, no en comandos improvisados.
+- **Repetible**: desplegar dos veces con los mismos parámetros produce el mismo resultado.
+- **Versionado**: cada despliegue queda asociado a una versión de chart y una versión de imagen, de modo que se puede volver atrás.
+- **Validable**: los requisitos previos (secretos, config maps, recursos del clúster) se verifican antes de instalar.
+
+Desplegar con `kubectl apply` de manifiestos sueltos, o con scripts ad-hoc, produce drift entre entornos, sin historial de versiones y sin validación de requisitos. Mantener esa maquinaria por app multiplica el trabajo y hace que cada app despliegue de una forma distinta.
+
+## Decisión
+
+Adoptar **Helm como mecanismo primario de despliegue para toda aplicación servidor**. Helm actúa como gestor de paquetes y de releases sobre Kubernetes: empaqueta los manifiestos en un chart versionado, los parametriza con valores y registra cada instalación como un release con historial y rollback.
+
+### 1. Un chart por aplicación servidor
+
+Cada aplicación servidor incluye su propio chart, co-localizado en el repositorio de la aplicación. No se usan charts compartidos entre aplicaciones: un chart expresa la topología de despliegue de una app concreta (deployment, servicio, config maps, secretos, hooks). Una app nueva copia el patrón de una existente y lo adapta.
+
+### 2. Despliegue declarativo con install/upgrade
+
+Todo despliegue se realiza con `helm install` (primera vez) y `helm upgrade` (cambios posteriores). No se aplican manifiestos sueltos con `kubectl` para recursos que pertenecen a la app. El historial de releases de Helm es la bitácora de despliegue: ante una regresión, `helm rollback` restaura la versión anterior.
+
+### 3. Valores por entorno sobre una base común
+
+Los valores se organizan con una base común y overlays por entorno (desarrollo, pruebas, producción), aplicando la regla de superposición del contrato de settings ([A-013](./A-013-contrato-settings-unica-fuente-configuracion.md)).
+
+### 4. Artefactos de configuración generados, no mantenidos a mano
+
+El chart consume los artefactos de configuración que se generan desde el contrato de settings (ver [A-014](./A-014-generacion-artefactos-despliegue-desde-contrato-settings.md)): plantillas de config map, de secretos y de valores de ejemplo. No se mantienen a mano listas de variables de entorno ni config maps duplicados; la fuente de verdad de qué configuración existe vive en el contrato de settings (ver [A-013](./A-013-contrato-settings-unica-fuente-configuracion.md)).
+
+### 5. Imagen preconstruida por el pipeline
+
+El chart despliega una imagen de contenedor que ya fue compilada y publicada por el pipeline de CI/CD. El clúster no compila, no instala dependencias y no ejecuta builds: solo despliega la imagen. Los fallos de compilación se detectan en el pipeline, no en producción. Compilar en el clúster — por ejemplo, en un Job hook de Helm en `post-install`/`post-upgrade` — reserva pods sobredimensionados para un trabajo que solo ocurre ocasionalmente.
+
+### 6. Versión de chart e imagen rastreables
+
+Cada despliegue referencia explícitamente una versión de chart y una etiqueta de imagen. No se despliega "la última": se despliega una versión concreta, de modo que un rollback es determinista.
+
+## Consecuencias
+
+### Positivas
+
+- **Despliegues repetibles**: el mismo chart y los mismos valores producen el mismo resultado en cualquier entorno.
+- **Historial y rollback**: cada cambio queda registrado como release; volver atrás es un comando, no una reconstrucción manual.
+- **Separación build/deploy**: el pipeline construye, Helm despliega. El clúster no necesita acceso a redes de build ni recursos de compilación.
+- **Configuración sin drift**: al consumir artefactos generados desde el contrato de settings, el chart no se desincroniza del código.
+- **Validación de requisitos**: los hooks de Helm pueden verificar secretos y config maps antes de instalar, fallando con mensajes claros.
+
+### Negativas
+
+- **Curva de aprendizaje**: el equipo debe dominar la sintaxis de plantillas de Helm y el ciclo install/upgrade/rollback.
+- **Mantenimiento de charts**: cada app mantiene su chart; un cambio de topología implica editar plantillas.
+- **Depuración de plantillas opaca**: el resultado renderizado depende de la combinación de plantillas y valores; depurar por qué un manifiesto no salió como se esperaba puede ser no trivial.
+- **Valores custom fuera del contrato**: los valores de Helm que no corresponden a un campo del contrato de settings se mantienen a mano en el values (excepción acotada, ver [A-014](./A-014-generacion-artefactos-despliegue-desde-contrato-settings.md)).

package/docs/adr/foundational/A-013-contrato-settings-unica-fuente-configuracion.md

@@ -0,0 +1,74 @@
+# A-013: Contrato de settings como única fuente de configuración de la aplicación
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-12
+
+**originally**: cortex-001, generator-018
+
+**Enriquecido desde**: Cortex ADR 001 — UltraSettings pattern; Generator ADR 018 — Settings Contract with schemas and auto-export
+
+**tags**: configuracion
+
+## Contexto
+
+Cada aplicación necesita configuración que varía entre entornos (local, desarrollo, producción) y entre despliegues: URLs de servicios, flags de features, parámetros del clúster y secretos. Sin un contrato formal, la configuración se dispersa:
+
+- Variables de entorno leídas ad-hoc en distintos puntos del código.
+- Archivos de configuración duplicados entre entornos.
+- Valores faltantes o mal tipados que producen errores en runtime en lugar de al arrancar.
+- Drift entre la configuración que el código espera y la que el despliegue provee.
+
+Cuando la configuración no tiene una definición única, nadie puede responder con certeza "¿qué settings existen y cuáles son obligatorios?" sin leer todo el código.
+
+## Decisión
+
+Declarar **toda la configuración de una aplicación en un único contrato de settings**, tipado y validado, que es la única fuente de verdad sobre qué configuración existe y cómo se valida.
+
+### 1. Un contrato por aplicación, centralizado
+
+Cada aplicación define exactamente un contrato de settings en un único archivo. Todo el código lee configuración a través de ese contrato; ningún módulo lee variables de entorno o archivos de configuración por su cuenta. Agregar un setting es editar un solo lugar.
+
+### 2. Cada campo declara tipo y origen
+
+Cada setting anota metadatos que clasifican su naturaleza. La taxonomía distingue al menos:
+
+| Tipo | Prefijo | Cambia por entorno | Contiene secretos | Ejemplo abstracto |
+|------|---------|:---:|:---:|-------------------|
+| **Metadato** | `APP_` | No | No | nombre y resumen de la app |
+| **Entorno** | `ENV_` | Sí | No | dominio o modo de ejecución |
+| **Infraestructura** | `INFRA_` | Sí | No | URL de un servicio externo |
+| **Clúster** | `CLUSTER_` | Sí | No | réplicas, imagen, recursos |
+| **Secreto** | `SECRET_` | Sí | Sí | token de API, credencial |
+
+El prefijo hace visible la clasificación en el propio nombre del setting: `APP_`, `ENV_`, `INFRA_`, `CLUSTER_` y `SECRET_`. Un nombre como `SECRET_API_TOKEN` declara su naturaleza sin necesidad de consultar el metadato.
+
+El metadato de cada campo es lo que permite, más adelante, derivar artefactos automáticamente ([A-014](./A-014-generacion-artefactos-despliegue-desde-contrato-settings.md)).
+
+### 3. Validación fail-fast al arrancar
+
+El contrato se valida al cargar la configuración, antes de que la aplicación procese trabajo real. Una configuración inválida (campo faltante, tipo incorrecto, secreto vacío) detiene el arranque con un error claro que identifica el campo y la causa. No se toleran valores parcialmente correctos.
+
+### 4. Definición y valores viven en lugares distintos
+
+El contrato define **qué** settings existen y cómo se validan. Los **valores** concretos por entorno viven fuera del contrato: archivos de entorno para desarrollo local y overlays por entorno para el despliegue. La regla es "común por defecto, explícito por diferencia": los valores idénticos entre entornos se declaran una sola vez; cada overlay sobrescribe únicamente lo que cambia.
+
+Los valores no secretos se versionan en el repositorio junto al contrato: la base común y los overlays por entorno quedan bajo control de versiones, de modo que cada cambio de configuración es rastreable y comparable entre versiones. La única excepción son los secretos: sus valores reales nunca se versionan — no se commitea ningún `.env`, credencial ni `kubeconfig` — y cada entorno los provee en el momento del despliegue, fuera del repositorio. El repositorio solo contiene plantillas `.sample` que muestran la forma de los valores (nombre y tipo) sin su contenido.
+
+### 5. El contrato es agnóstico a la tecnología de validación
+
+El patrón (definición central, metadatos por campo, validación fail-fast) es independiente del lenguaje. Cada ecosistema lo implementa con su librería de validación y su sistema de tipos; el contrato de settings no depende de una librería concreta. Lo que se comparte entre proyectos es el patrón, no la implementación.
+
+## Consecuencias
+
+### Positivas
+
+- **Una sola fuente de verdad**: la pregunta "¿qué configuración existe?" se responde abriendo un archivo.
+- **Fallos tempranos**: la configuración inválida detiene la app al arrancar con un mensaje claro, no en runtime.
+- **Taxonomía útil**: el metadato de tipo/origen habilita generación de artefactos ([A-014](./A-014-generacion-artefactos-despliegue-desde-contrato-settings.md)).
+- **Entornos coherentes**: los overlays sobre una base común evitan duplicar valores idénticos y hacen explícitas las diferencias.
+
+### Negativas
+
+- **El contrato crece**: con el tiempo, el archivo central acumula todos los settings de la app y se vuelve extenso; la taxonomía de tipos es la mitigación para navegarlo.
+- **Riesgo de duplicación tipo/schema**: en ecosistemas con tipos fuertes, la definición puede existir dos veces (schema de validación y tipos del lenguaje); requiere disciplina para mantenerlos sincronizados.

package/docs/adr/foundational/A-014-generacion-artefactos-despliegue-desde-contrato-settings.md

@@ -0,0 +1,75 @@
+# A-014: Generación de artefactos de despliegue desde el contrato de settings
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-12
+
+**originally**: cortex-002
+
+**Enriquecido desde**: Cortex ADR 002 — Settings-to-Helm contract generation
+
+**tags**: despliegue, configuracion
+
+## Contexto
+
+Mantener a mano los artefactos de despliegue (valores de ejemplo, config maps, secretos y su esquema de validación) es propenso a errores. Un setting agregado al código pero olvidado en el chart produce una configuración errónea silenciosa en producción: la app arranca con un valor por defecto o falla en runtime, en lugar de fallar donde corresponde.
+
+El contrato de settings ([A-013](./A-013-contrato-settings-unica-fuente-configuracion.md)) ya define qué configuración existe, con su tipo y su origen. Si ese contrato es la única fuente de verdad, los artefactos de despliegue deberían **derivarse** de él, no mantenerse como una copia paralela.
+
+## Decisión
+
+Generar **todos los artefactos de despliegue desde el contrato de settings**, mediante un comando de exportación que lee el contrato y renderiza plantillas.
+
+### 1. Exportación automática, no edición manual
+
+Un único comando de exportación lee el contrato de settings y genera, por cada aplicación:
+
+- Muestra de entorno para desarrollo local.
+- Plantilla de secretos para el despliegue.
+- Plantilla de config map para el despliegue.
+- Valores de ejemplo para el chart de Helm.
+- Esquema de validación de valores para el chart.
+
+No se editan a mano estos archivos generados. Un cambio de configuración se hace en el contrato y se propaga ejecutando el comando de exportación.
+
+### 2. La clasificación del contrato decide el destino
+
+El metadato de tipo/origen de cada campo ([A-013 §2](./A-013-contrato-settings-unica-fuente-configuracion.md)) determina a qué artefacto pertenece:
+
+- Un campo marcado como **secreto** se renderiza en la plantilla de secretos, nunca en el config map.
+- Un campo marcado como **clúster** se traduce a la forma que el orquestador espera (por ejemplo, un objeto con `kind`, `name` y `key` que referencia un recurso del clúster).
+- Un campo de **infraestructura** o **entorno** no secreto se renderiza en el config map.
+- Los **metadatos** alimentan la muestra de entorno y la documentación.
+
+### 3. Esquema de validación generado
+
+El esquema de valores del chart se genera desde el contrato, con los campos requeridos correctos y las formas de los objetos de clúster. El orquestador puede validar los valores antes de instalar, rechazando configuraciones que el contrato no contempla.
+
+### 4. Excepción acotada: valores fuera del contrato
+
+Los valores del chart que no corresponden a ningún campo del contrato (por ejemplo, recursos de cómputo puros o topología de despliegue) se mantienen a mano en el values. Esta excepción es acotada y deliberada: el contrato describe configuración de la aplicación; el chart también necesita valores que no son configuración de la aplicación.
+
+### 5. El chart consume los artefactos generados
+
+El chart de Helm ([A-012](./A-012-helm-mecanismo-primario-despliegue.md)) consume los artefactos generados en lugar de redefinir variables de entorno o config maps. La cadena completa es:
+
+```
+contrato de settings → comando de exportación → artefactos de despliegue → chart de Helm
+```
+
+Un setting nuevo recorre la cadena completa sin intervención manual en el chart.
+
+## Consecuencias
+
+### Positivas
+
+- **Cero drift entre código y chart**: agregar un setting al contrato y ejecutar la exportación actualiza todos los artefactos derivados.
+- **Secretos a salvo por construcción**: un campo marcado como secreto no puede terminar en un config map porque la clasificación lo excluye del renderizado correspondiente.
+- **Validación previa a la instalación**: el esquema generado permite que el orquestador rechace valores inválidos antes de desplegar.
+- **Bootstrap rápido de apps nuevas**: una app nueva copia el patrón de contrato + plantillas y obtiene su chart generado desde el primer momento.
+
+### Negativas
+
+- **Paso de exportación obligatorio**: olvidar ejecutar la exportación tras cambiar un setting deja los artefactos desactualizados hasta el siguiente despliegue.
+- **Depuración de la generación opaca**: el resultado renderizado depende de la combinación de metadatos del contrato y lógica de plantillas; un artefacto incorrecto puede requerir inspeccionar ambos.
+- **Valores custom fuera del flujo**: lo que no mapea a un campo del contrato sigue manteniéndose a mano en el values, con su propio riesgo de drift.

package/docs/adr/foundational/A-015-cloudevents-estandar-eventos.md

@@ -0,0 +1,85 @@
+# A-015: CloudEvents como estándar de eventos
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-12
+
+**originally**: cloudevents
+
+**Enriquecido desde**: CloudEvents Specification (CNCF) — cloudevents.io
+
+**tags**: eventos
+
+## Contexto
+
+Los eventos son el medio por el que las distintas partes de un sistema se comunican: los de dominio, cuya emisión fija [A-010](./A-010-propiedad-emision-eventos-dominio.md), y los de integración que los adaptadores intercambian con sistemas externos. Sin una decisión canónica, cada productor y cada consumidor reinventa su propia envolvente, los eventos quedan legibles solo para quien los escribió y cada integración nueva exige un contrato ad-hoc:
+
+- Campos con nombres distintos para lo mismo (`occurredAt` vs `fecha` vs `timestamp`).
+- Falta de metadatos de enrutamiento (¿quién emitió esto? ¿de qué tipo es?).
+- Imposibilidad de que la infraestructura (transporte, observabilidad, proyecciones) procese eventos sin conocer la data específica de cada dominio.
+- Evolución de la data sin reglas: los consumidores se rompen silenciosamente cuando un productor cambia un campo.
+
+## Decisión
+
+Adoptar **CloudEvents como estándar para todo evento** que el sistema emite o consume — de dominio y de integración. CloudEvents es una especificación del CNCF que define una envolvente común para describir eventos, independiente del lenguaje y del transporte.
+
+### 1. CloudEvents como envolvente único
+
+Todo evento se representa como un CloudEvent conforme a la especificación CloudEvents (versión `1.0`). La especificación separa los atributos de contexto (metadatos estándar) de la data de negocio: la infraestructura enruta y observa usando el contexto, y solo los consumidores que interpretan un tipo concreto leen la data.
+
+### 2. Atributos de contexto
+
+Cada evento declara los atributos obligatorios de la especificación:
+
+- `id`: identificador único del evento.
+- `source`: fuente que emitió el evento (una URI).
+- `specversion`: versión de la especificación CloudEvents (`1.0`).
+- `type`: tipo semántico del evento (ver punto 3).
+
+Y usa los atributos opcionales cuando aportan información:
+
+- `time`: instante en que ocurrió el evento.
+- `subject`: entidad a la que se refiere el evento (por ejemplo, el identificador de un agregado).
+- `datacontenttype`: formato de la data (por ejemplo, `application/json`).
+- `dataschema`: URI del esquema versionado de la data (ver punto 4).
+
+La data de negocio viaja en el campo `data`, tipada para los consumidores que la interpretan y opaca para el resto.
+
+### 3. `type` identifica la semántica y la familia de compatibilidad
+
+El atributo `type` es un identificador estable y legible de la semántica del evento que codifica la familia de compatibilidad de la data: su versión mayor. Por ejemplo, `com.imolko.journal.v1.contact-created` marca la familia `1.x.x`, así que todos los eventos de ese `type` son compatibles dentro de `1.x.x`. El `type` no incluye la versión completa (`mayor.menor.patch`): la versión concreta se expresa por separado (ver punto 4). Así, el enrutamiento y las proyecciones no se rompen cuando la data evoluciona de forma compatible dentro de una familia, y un cambio incompatible produce un `type` nuevo (ver punto 4).
+
+### 4. Versionado semver, append-only y compatible hacia atrás de la data
+
+La data de cada tipo de evento se versiona con semver (`mayor.menor.patch`) y su historial de versiones es **append-only**:
+
+- **Append-only**: una versión publicada nunca se modifica ni se elimina. Un cambio produce una entrada nueva en el historial, agregada al final; las versiones anteriores permanecen intactas y legibles para siempre.
+- **Compatible hacia atrás**: dentro de una misma versión mayor, los cambios son aditivos — se agregan campos opcionales o se relajan validaciones. Nunca se renombra ni se elimina un campo requerido, ni se cambia su significado. Un consumidor viejo sigue leyendo eventos nuevos sin romperse.
+- **Cambios incompatibles**: un cambio que rompe compatibilidad (eliminar o renombrar un campo requerido, cambiar el significado de un campo) no se publica como una versión nueva de la misma data. Se trata como un contrato nuevo — un `type` nuevo — con su propio ciclo de versionado y, si aplica, migración explícita.
+
+La versión concreta de la data de un evento se declara de forma explícita: en el `dataschema` (URI versionada del esquema) y, cuando el ecosistema lo requiera, en un campo de versión dentro de la propia data. Los consumidores leen esa versión y aplican la regla de compatibilidad para interpretar la data.
+
+### 5. Consumidores tolerantes a atributos desconocidos
+
+Los consumidores ignoran los atributos de contexto y de data que no conocen, en lugar de fallar. CloudEvents permite atributos de extensión; un consumidor que rechaza eventos con atributos nuevos se convierte en un cuello de botella para la evolución del contrato. La tolerancia aplica tanto a atributos de contexto adicionales como a campos nuevos de la data (que son opcionales por la regla del punto 4).
+
+### 6. Ámbito agnóstico al lenguaje
+
+La decisión fija el formato y la disciplina de versionado, no una librería concreta. Cualquier proyecto de Imolko — hoy TypeScript, mañana otro lenguaje — emite y consume CloudEvents y aplica las mismas reglas de versionado. Lo que se comparte entre proyectos es el estándar y el contrato de versionado; la implementación de cada ecosistema es un detalle.
+
+## Consecuencias
+
+### Positivas
+
+- **Interoperabilidad**: la infraestructura común (transporte, observabilidad, enrutamiento) procesa cualquier evento sin conocer su data.
+- **Contratos estables**: la data evoluciona de forma aditiva y los consumidores viejos siguen funcionando con eventos nuevos.
+- **Historial inmutable**: las versiones publicadas nunca cambian, por lo que reproducir o auditar un evento viejo siempre es posible.
+- **Descubrimiento**: el `type` y el `dataschema` permiten localizar la definición y el esquema de un evento sin leer código del productor.
+- **Desacoplamiento del lenguaje**: la decisión aplica igual a TypeScript, Python o cualquier ecosistema futuro.
+
+### Negativas
+
+- **Disciplina de versionado**: agregar un campo requiere pensar en compatibilidad y registrar una versión nueva, en lugar de editar libremente la data.
+- **Curva de aprendizaje**: el equipo debe conocer los atributos de contexto de CloudEvents y las reglas semver aplicadas a eventos.
+- **Romper compatibilidad es costoso**: un cambio incompatible no se arregla con una versión más; exige un `type` nuevo y, si aplica, una migración.
+- **Manejo de atributos desconocidos**: la tolerancia del punto 5 es una responsabilidad de cada consumidor; un consumidor que la omita reintroduce el acoplamiento que el estándar busca evitar.

package/docs/adr/foundational/A-016-cicd-gitlab-pipeline-raiz-pipelines-modulares.md

@@ -0,0 +1,92 @@
+# A-016: CI/CD con GitLab: pipeline raíz y pipelines modulares por app
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-12
+
+**originally**: generator-019
+
+**Enriquecido desde**: Generator ADR 019 — CI/CD Store Generator Pipeline; Cortex docs — GitLab CI/CD parent-child pipelines
+
+**tags**: despliegue, tooling
+
+## Contexto
+
+Todo repositorio de Imolko necesita verificar sus cambios de forma automática — ejecutar tests, compilar, validar requisitos y publicar artefactos — y desplegar las aplicaciones que lo componen. Sin una plataforma y una estructura de pipeline canónicas, cada repositorio reinventa su proceso:
+
+- Pipelines con nombres y stages distintos entre proyectos.
+- Validaciones globales mezcladas con los pasos de despliegue de una app concreta.
+- Todas las apps se re-ejecutan en cada cambio, aunque el cambio no las afecte.
+- Un agente o un miembro nuevo no puede descubrir cómo se valida y despliega un proyecto sin leer pipeline a pipeline.
+
+## Decisión
+
+Adoptar **GitLab CI/CD como plataforma canónica de integración y despliegue continuo** para todos los proyectos de Imolko, con una estructura de **pipeline raíz + pipelines modulares por app**.
+
+### 1. GitLab como plataforma canónica
+
+Todo pipeline de CI/CD se define como un pipeline de GitLab. No se mantiene una segunda plataforma de CI/CD como mecanismo primario. La definición vive en archivos de pipeline versionados junto al código, de modo que la forma de validar y desplegar se descubre leyendo el repositorio.
+
+### 2. Pipeline raíz: validaciones globales y orquestación
+
+Cada repositorio tiene exactamente un **pipeline raíz** en su raíz. Su responsabilidad es el trabajo que concierne al repositorio como un todo, no el despliegue de una app concreta:
+
+- **Reglas de workflow**: cuándo se ejecuta un pipeline y con qué intención (ver punto 4).
+- **Validación de requisitos globales**: variables y condiciones previas que el pipeline necesita.
+- **Trabajo compartido**: tests y builds de las capas comunes (el dominio y los casos de uso, según [A-001](./A-001-clean-architecture-4-capas.md)) y generación de documentación.
+- **Reporte de tests unificado**: los jobs de test exportan sus resultados en formato CTRF (ver [A-022](./A-022-formato-reporte-tests-ctrf.md)); el pipeline y la documentación generada consumen ese reporte en lugar de los formatos propios de cada runner.
+- **Orquestación de apps**: un job trigger por cada aplicación, que dispara el pipeline modular de esa app solo cuando corresponde (ver punto 3).
+
+El pipeline raíz no contiene los pasos de build o despliegue de ninguna aplicación: ese trabajo pertenece al pipeline de la app.
+
+### 3. Pipeline modular por app con disparo por cambios
+
+Cada aplicación desplegable ([A-001](./A-001-clean-architecture-4-capas.md)) posee su **propio pipeline**, definido en el directorio de la app. El pipeline raíz lo dispara mediante **parent-child pipelines**, y el trigger usa reglas de **cambios** (`rules:changes`): el pipeline de una app se ejecuta únicamente cuando cambian los archivos que la afectan. Un cambio que no toca a una app no la recompila ni la redespliega.
+
+El pipeline de la app es dueño del ciclo específico de esa app:
+
+- Verificar los archivos requeridos para desplegar.
+- Construir y publicar la imagen de contenedor.
+- Desplegar con Helm ([A-012](./A-012-helm-mecanismo-primario-despliegue.md)), consumiendo los artefactos generados desde el contrato de settings ([A-014](./A-014-generacion-artefactos-despliegue-desde-contrato-settings.md)).
+- Verificar el despliegue.
+
+### 4. Intención del pipeline declarada en la raíz
+
+El pipeline raíz declara la **intención** de cada ejecución en un único lugar, con dos valores:
+
+- **Integración**: verificar cambios antes de fusionar (tests y builds, sin despliegue).
+- **Entrega** (delivery): desplegar tras fusionar a una rama protegida.
+
+La intención se decide en las reglas de workflow del raíz y se transmite a los pipelines de las apps. Los jobs de test se ejecutan en integración y entrega; los jobs de despliegue solo en entrega. Así, la semántica de "qué hace este pipeline" no se deduce de reglas dispersas.
+
+### 5. Contrato explícito entre raíz y apps mediante inputs
+
+Cada pipeline de app declara los parámetros que necesita (por ejemplo, nombre de la app, directorio, entorno a desplegar, intención) como **inputs** con su tipo y descripción. El pipeline raíz se los pasa al disparar el trigger. Los pipelines de app no leen variables globales sueltas: reciben un contrato explícito que documenta qué necesitan y quién se lo provee.
+
+### 6. Convenciones operativas
+
+Además de la estructura de dos niveles, los pipelines comparten convenciones operativas canónicas:
+
+- **Helpers de CI versionados**: los pipelines usan el módulo de utilidades versionado en el repositorio (`ci-helpers.sh` en la raíz) en lugar de scripts externos no versionados. Ese archivo es la fuente canónica de las funciones disponibles —las familias de logging (`log_*`), las secciones colapsables (`section_start`, `section_end`) y las validaciones de requisitos (`validate_required_*`)—; los pipelines hacen `source` del archivo y consultan su documentación para conocer la lista completa, sin duplicarla en cada pipeline.
+- **Naming `stage:job`**: los nombres de stage y de job siguen una convención explícita y uniforme, de modo que el propósito de un job se deduce de su nombre. La convención concreta vive en la fuente canónica de cada repositorio; este ADR fija la obligación de mantenerla, no duplica la tabla de nombres.
+- **Versionado de imágenes con CalVer**: las imágenes de contenedor se versionan con **CalVer** (p. ej. `YYYY.MM.patch`), no con SemVer. El canal de desarrollo usa el sufijo `-beta` en la rama `develop`. Los **paquetes** (librerías publicables) siguen **SemVer**; CalVer aplica únicamente a imágenes desplegables. Esta distinción evita mezclar el ciclo de un artefacto desplegable con el de un artefacto consumible.
+- **Despliegue Helm con espera y timeout**: el pipeline despliega con `helm upgrade --wait` y un `--timeout` explícito, de modo que Helm espera a que los pods reporten `ready` (coherente con el `readinessProbe` de [A-019](./A-019-convenciones-autoria-helm-charts.md)) antes de dar el despliegue por exitoso, en lugar de regresar de inmediato.
+- **Sin scripts externos no versionados**: todo paso del pipeline ejecuta comandos en línea o scripts versionados en el repositorio. No se depende de scripts alojados fuera del repositorio ni de pasos que un miembro nuevo no pueda inspeccionar.
+
+## Consecuencias
+
+### Positivas
+
+- **Modularidad**: cada app evoluciona su pipeline sin tocar el raíz, y el raíz cambia sin reescribir los pipelines de las apps.
+- **Ejecución selectiva**: solo se ejecutan las apps afectadas por un cambio, lo que reduce tiempo y recursos.
+- **Descubribilidad**: la estructura de dos niveles es predecible; un agente o un miembro nuevo encuentra el pipeline raíz y el de cada app sin ambigüedad.
+- **Intención única**: integración versus entrega se define en un solo sitio, sin reglas contradictorias entre jobs.
+- **Contrato claro**: los inputs de cada app documentan sus requisitos de pipeline.
+
+### Negativas
+
+- **Complejidad de dos niveles**: depurar parent-child pipelines es más difícil que un pipeline único.
+- **Mantenimiento por app**: cada app mantiene su archivo de pipeline; una app nueva debe crear el suyo.
+- **Reglas de cambios frágiles**: si `rules:changes` no lista todos los paths que afectan a una app, el pipeline puede saltarse un cambio necesario.
+- **Boilerplate de inputs**: declarar y pasar inputs agrega verbosidad frente a usar variables globales.
+- **Disciplina**: mantener el raíz libre de pasos específicos de app requiere revisión constante.

package/docs/adr/foundational/A-017-taxonomia-repositorios-librerias-sistemas.md

@@ -0,0 +1,93 @@
+# A-017: Taxonomía de repositorios: sistemas, librerías y configuración
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-12
+
+**originally**: imolko
+
+**tags**: arquitectura
+
+## Contexto
+
+Imolko mantiene varios repositorios de naturaleza distinta. Algunos encapsulan una funcionalidad técnica reutilizable (validación, resultados, generación, documentación); otros modelan un dominio de negocio completo con sus reglas y sus aplicaciones desplegables; otros guardan artefactos de despliegue y configuración. Sin una taxonomía explícita:
+
+- No queda claro qué estándares aplican a cada repositorio.
+- Se corre el riesgo de imponer estructura de negocio a una utilidad, o de tratar un producto como si fuera una pieza reutilizable.
+- Un miembro nuevo o un agente no puede deducir el propósito de un repositorio a partir de una convención escrita.
+
+Las prácticas del equipo se aplican de forma distinta según la naturaleza del repositorio. Fijar la taxonomía permite saber, para cada repositorio, qué reglas aplican.
+
+## Decisión
+
+Clasificar todo repositorio de Imolko en exactamente una de tres categorías: **sistema**, **librería** o **configuración**. La clasificación depende del propósito del repositorio — un dominio de negocio, una funcionalidad técnica reutilizable, o artefactos de despliegue y configuración — no del tamaño, del lenguaje ni de la forma de despliegue.
+
+### 1. Librería
+
+Una **librería** es un repositorio que provee **funcionalidad específica y reutilizable**, sin un dominio de negocio propio. La «funcionalidad» incluye metodología y documentación reutilizables —por ejemplo skills de agentes y un registro ADR de metodología, como `@imolko/ultra-agent`—, no solo código ejecutable.
+
+Características:
+
+- **Sin lenguaje ubicuo**: su vocabulario es técnico, no de negocio.
+- **Sin Clean Architecture**: no se organiza en capas concéntricas de negocio. Es una pieza cohesionada — típicamente uno o unos pocos paquetes — que otros repositorios consumen como dependencia.
+- **Problema acotado**: resuelve un problema bien delimitado, no un proceso de negocio completo.
+
+Ejemplos abstractos: una librería de validación, una librería de resultados, una herramienta de documentación.
+
+### 2. Sistema
+
+Un **sistema** es un repositorio que modela un **dominio de negocio**.
+
+Características:
+
+- **Con lenguaje ubicuo**: los artefactos y los nombres hablan el lenguaje del negocio.
+- **Clean Architecture**: se organiza en capas concéntricas de negocio.
+- **Aplicaciones desplegables**: posee apps que componen casos de uso y se despliegan de forma independiente.
+
+Ejemplos abstractos: un sistema de inventario, un punto de venta, una plataforma de compras.
+
+### 3. Configuración
+
+Un repositorio de **configuración** guarda artefactos de despliegue y configuración (settings, Helm charts, pipelines, entornos). No modela un dominio de negocio ni provee funcionalidad reutilizable.
+
+Características:
+
+- **Sin dominio de negocio**: no tiene capa `domain/` ni lenguaje ubicuo.
+- **Sin lógica reutilizable**: no se consume como dependencia; lo consumen las herramientas de despliegue y el entorno.
+- **Referencia a lo que configura**: un chart o un contrato de settings apunta al sistema (o librería) que despliega o configura.
+
+Ejemplos abstractos: un repositorio de Helm charts, un contrato de settings, pipelines de CI/CD.
+
+### 4. Regla de dependencia entre categorías
+
+Una **librería nunca depende de un sistema**. Los sistemas pueden depender de librerías, nunca al revés. Esta dirección mantiene las piezas reutilizables independientes de cualquier negocio concreto.
+
+La **configuración** no participa del grafo de dependencias de código: referencia los sistemas y librerías que despliega o configura, y ningún repositorio la importa como dependencia.
+
+### 5. La taxonomía decide qué estándares aplican
+
+La clasificación determina las expectativas estructurales:
+
+- Un **sistema** debe exhibir lenguaje ubicuo ([A-031](./A-031-ubiquitous-language.md)) y Clean Architecture ([A-001](./A-001-clean-architecture-4-capas.md)); es candidato a un dominio DDD completo con sus bounded contexts ([A-008](./A-008-bounded-context-decomposition.md)).
+- Una **librería** no debe cargar con capas de negocio; se mantiene como una pieza técnica cohesionada. Imponerle Clean Architecture es sobre-ingeniería.
+- Un repositorio de **configuración** no aplica DDD ni Clean Architecture; sigue los estándares de despliegue y configuración (settings [A-013](./A-013-contrato-settings-unica-fuente-configuracion.md), Helm [A-019](./A-019-convenciones-autoria-helm-charts.md), CI/CD [A-016](./A-016-cicd-gitlab-pipeline-raiz-pipelines-modulares.md)).
+
+### 6. Clasificación por naturaleza dominante
+
+Un repositorio se clasifica por su naturaleza dominante. Si un repositorio adquiere con el tiempo la naturaleza de otra categoría, se reclasifica — y esa reclasificación es una decisión que puede implicar migración estructural.
+
+## Consecuencias
+
+### Positivas
+
+- **Clasificación inmediata**: la taxonomía responde "¿es un sistema, una librería o configuración?" sin ambigüedad.
+- **Estándares correctos por repositorio**: un sistema exige DDD y Clean Architecture; una librería no arrastra esa ceremonia; la configuración sigue los estándares de despliegue, sin DDD ni Clean Architecture.
+- **Dirección de dependencias sana**: las librerías permanecen libres de negocio y reutilizables entre sistemas.
+- **Descubribilidad**: un agente o un miembro nuevo sabe qué buscar y qué reglas aplicar al entrar a un repositorio.
+- **Distribución de librerías natural**: las librerías quedan identificadas como candidatas a publicación y versionado independientes.
+
+### Negativas
+
+- **Solapamiento parcial**: un sistema puede alojar sus charts y settings en su propio repositorio; la categoría la decide la naturaleza dominante, lo que admite cierto criterio.
+- **Reclasificación costosa**: una librería que crece hasta tener dominio debe migrar a la estructura de sistema.
+- **Riesgo de sobre-ingeniería inversa**: aplicar la taxonomía a la inversa (forzar DDD en una librería, o aplanar un sistema) degrada el diseño.