@imolko/ultra-agent 0.1.0-beta

package/docs/adr/foundational/A-018-practicas-build-imagenes-docker.md

@@ -0,0 +1,85 @@
+# A-018: Prácticas de build de imágenes Docker
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-13
+
+**originally**: cortex-dockerimage-for-apps
+
+**Enriquecido desde**: Cortex doc "dockerimage-for-apps" — buenas prácticas para construir imágenes Docker
+
+**tags**: despliegue
+
+## Contexto
+
+Las aplicaciones servidor de Imolko se despliegan en Kubernetes mediante Helm ([A-012](./A-012-helm-mecanismo-primario-despliegue.md)) con una imagen construida y publicada por el pipeline de CI/CD ([A-016](./A-016-cicd-gitlab-pipeline-raiz-pipelines-modulares.md)). La velocidad de construcción y el tamaño de la imagen tienen un costo directo: builds lentos demoran el feedback del pipeline y las imágenes sobredimensionadas consumen recursos en el registro y en cada clúster que las descarga.
+
+Sin convenciones explícitas, cada app construye su imagen a su manera:
+
+- Imágenes base con el tag `latest`, que hacen el build no reproducible.
+- Instalación de dependencias repetida en cada paso del pipeline.
+- Imágenes finales que incluyen compiladores y herramientas que producción no necesita.
+- Contenedores que corren como `root`.
+- Dockerfiles crípticos, sin documentar, difíciles de mantener.
+
+## Decisión
+
+Adoptar un conjunto canónico de prácticas de build para **toda imagen de contenedor** de Imolko. Las prácticas aplican por igual a proyectos Python y Node, y no dependen de un lenguaje concreto.
+
+### 1. Construcción multistage
+
+Toda imagen se construye con un Dockerfile **multistage**: las etapas intermedias instalan herramientas y compilan, y la etapa final copia únicamente los artefactos resultantes. La última etapa declarada es la que se despliega; las anteriores son descartables y no viajan en la imagen final.
+
+Esto separa las herramientas de build de las dependencias de runtime: el compilador vive en una etapa intermedia y el resultado (por ejemplo, un bundle o un paquete instalado) se copia a una imagen final mínima.
+
+### 2. Imagen base oficial y versionada (pineada)
+
+La imagen base se elige entre las imágenes **oficiales y verificadas**, y se fija a una **versión específica** (tag concreto). No se usa `latest` ni tags móviles: el build debe producir el mismo resultado en cada ejecución. Una imagen base cargada con cosas innecesarias se descarta en favor de una sencilla y específica.
+
+### 3. Imagen base custom publicada por el pipeline
+
+Cuando una imagen necesita herramientas que se instalan en cada build (por ejemplo, un entorno de tooling para desarrollo o CI), se construye una **imagen base custom** y se publica en el registro. Esa imagen se mantiene y publica en el registro, no se reinstala ad-hoc en cada Dockerfile. Cada instrucción de un Dockerfile se ejecuta en cada pipeline y consume recursos: lo que se repite entre apps se consolida en una imagen base publicada.
+
+### 4. Instrucciones estables primero, por caché de layers
+
+Cada instrucción de un Dockerfile produce un layer; el build aprovecha la caché de layers y evita reconstruir lo que no cambió. Para maximizarla, las instrucciones que cambian poco van **primero** y las que cambian a menudo, **al final**: primero la imagen base y las dependencias de terceros, después el código de la aplicación.
+
+En proyectos con gestor de dependencias y lockfile, la instalación de dependencias se hace en dos pasos: primero se instalan solo las dependencias de producción usando el lockfile (aprovechando la caché cuando no cambiaron) y después se copia el código y se instala la aplicación. Un solo paso anula la caché ante el mínimo cambio de código.
+
+### 5. Minimizar layers y limpiar en el mismo RUN
+
+Se combinan instrucciones relacionadas en un solo `RUN` y se limpian cachés y archivos temporales en la misma instrucción. El objetivo es menos layers y una imagen final más chica.
+
+### 6. `.dockerignore` para no copiar archivos innecesarios
+
+Cada contexto de build declara un `.dockerignore` que excluye lo que no aporta a la imagen final: directorios de control de versiones, archivos de entorno y secretos, dependencias instaladas localmente y artefactos de build. El patrón concreto depende del ecosistema, pero la regla es: **el contexto de build contiene solo lo que la imagen necesita**.
+
+### 7. Solo dependencias de producción
+
+La imagen final instala únicamente lo que producción usa. Compiladores, librerías de desarrollo y herramientas de test no entran en la imagen final: si se necesitan para construir, viven en una etapa multistage (ver punto 1).
+
+Una imagen publicada se verifica en el registro: si pesa de más, se revisa antes de darla por buena, porque ese exceso se paga en cada entorno que la descarga.
+
+### 8. Usuario no-root
+
+Ningún contenedor corre como `root` en producción. El Dockerfile crea un usuario limitado y lo declara con la directiva correspondiente; la app se ejecuta con ese usuario.
+
+### 9. Nombres significativos y Dockerfile documentado
+
+Cuando un contexto tiene varios Dockerfiles, cada uno lleva un nombre que describe su uso (por ejemplo, `Dockerfile.app`, `Dockerfile.tooling`). Cada Dockerfile se documenta con comentarios que explican **por qué** se hizo cada paso, no solo qué hace: las decisiones de diseño incrustadas en el build deben poder leerse tiempo después.
+
+## Consecuencias
+
+### Positivas
+
+- **Builds más rápidos y baratos**: la caché de layers y el orden de las instrucciones reducen el trabajo repetido.
+- **Imágenes más chicas**: multistage, limpieza y solo dependencias de producción reducen el tamaño final.
+- **Reproducibilidad**: versiones pineadas y sin `latest` hacen el build determinista.
+- **Seguridad**: el usuario no-root y la exclusión de secretos vía `.dockerignore` reducen la superficie de riesgo.
+- **Mantenibilidad**: nombres significativos y Dockerfiles documentados facilitan el mantenimiento.
+
+### Negativas
+
+- **Disciplina de mantenimiento**: elegir y pinear versiones, mantener `.dockerignore` y la imagen base custom requiere atención continua.
+- **Curva de aprendizaje**: multistage y el orden por caché exigen entender cómo funcionan los layers de Docker.
+- **Imagen base custom como dependencia**: publicarla por el pipeline introduce un artefacto intermedio que hay que versionar y actualizar.

package/docs/adr/foundational/A-019-convenciones-autoria-helm-charts.md

@@ -0,0 +1,97 @@
+# A-019: Convenciones de autoría de Helm charts
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-13
+
+**originally**: cortex-helm-chart
+
+**Enriquecido desde**: Cortex doc "helm-chart" — convenciones de autoría de Helm charts
+
+**tags**: despliegue
+
+## Contexto
+
+[A-012](./A-012-helm-mecanismo-primario-despliegue.md) fija Helm como mecanismo primario de despliegue y define la forma externa del chart: un chart por app, valores por entorno e imagen preconstruida. Pero no define cómo se **escribe** un chart de calidad. Sin convenciones internas, cada chart:
+
+- Usa labels y nombres de recursos distintos, dificultando observabilidad y agrupación.
+- Omite probes de readiness, de modo que un pod recibe tráfico antes de estar listo.
+- No valida los requisitos previos del clúster, y los fallos aparecen en runtime con mensajes opacos.
+- No documenta su uso, sus valores ni sus pasos post-instalación.
+- Empaqueta archivos innecesarios o sensibles por falta de `.helmignore`.
+
+Estas prácticas existen de forma implícita; falta fijarlas como convención común de autoría.
+
+## Decisión
+
+Adoptar convenciones canónicas para la **autoría** de Helm charts. Este ADR no vuelve a decidir el mecanismo de despliegue (eso es [A-012](./A-012-helm-mecanismo-primario-despliegue.md)): fija cómo se escribe el chart que ese mecanismo manda crear.
+
+### 1. Topología completa del chart
+
+Cada chart describe la topología completa de la app: Deployment, Service, Ingress, ConfigMap y referencias a Secret (nunca los valores sensibles). La forma externa la fija [A-012 §1](./A-012-helm-mecanismo-primario-despliegue.md).
+
+### 2. Templates comunes de labels y nombre
+
+El chart define templates reutilizables para:
+
+- **Labels comunes** (`common.labels` o similar): los labels estándar de Kubernetes (`app.kubernetes.io/name`, `component`, `part-of`, `managed-by`) que todos los recursos del chart incluyen.
+- **Nombre base** (`chart.name` o similar): genera el nombre base de los recursos aplicando reglas de truncado y limpieza, para respetar los límites de longitud de nombres de Kubernetes.
+
+Los recursos no escriben labels ni nombres a mano: usan los templates.
+
+### 3. `values.schema.json` que valida los valores
+
+El chart incluye un `values.schema.json` que valida los valores antes de instalar. Ese esquema se genera desde el contrato de settings ([A-014 §3](./A-014-generacion-artefactos-despliegue-desde-contrato-settings.md)); los valores que no provienen del contrato son la excepción acotada que [A-014 §4](./A-014-generacion-artefactos-despliegue-desde-contrato-settings.md) admite.
+
+### 4. Validación de requisitos del clúster con hooks
+
+El chart declara explícitamente los requisitos del clúster que la app necesita para funcionar (pods de infraestructura, secretos y config maps preexistentes). Un Job con anotación de hook se ejecuta en `pre-install` y `pre-upgrade` para validar que esos requisitos existen, con política de limpieza del hook definida. La lista de requisitos se expresa como datos del chart, sin nombrar secretos ni credenciales concretas: son referencias a recursos que el entorno debe proveer.
+
+### 5. `readinessProbe` en todo contenedor
+
+Todo contenedor de un Deployment declara un `readinessProbe` que refleja el estado "listo para servir" (un endpoint de salud). Sin probe, el pod recibe tráfico mientras aún se inicializa. El probe además hace útil la espera `--wait` del pipeline ([A-016](./A-016-cicd-gitlab-pipeline-raiz-pipelines-modulares.md)).
+
+### 6. Tests de despliegue como hooks de Helm
+
+El chart incluye Jobs de test anotados con `helm.sh/hook: test`, que verifican el despliegue (por ejemplo, que la app responde en su URL interna) después de instalar o actualizar. Llevan política de limpieza para que los pods de test no queden colgados.
+
+### 7. Documentación del chart
+
+Cada chart incluye:
+
+- **`NOTES.txt`**: instrucciones post-instalación que se muestran al terminar el despliegue (cómo acceder a la app, comandos útiles), con templates para información dinámica.
+- **`README.md`**: propósito del chart, requisitos previos, cómo instalarlo y la descripción de cada parámetro de `values`.
+
+### 8. Higiene del paquete con `.helmignore`
+
+El chart declara un `.helmignore` que excluye del paquete final archivos y directorios que no pertenecen al chart: control de versiones, archivos de entorno y secretos, temporales y de respaldo. El paquete resultante es liviano y no arrastra datos sensibles.
+
+### 9. Exposición HTTP y DNS
+
+Las apps accesibles externamente exponen su URL mediante un recurso **Ingress** (reglas de host/path y TLS configurables por `values`). Los registros DNS de esos hosts no se gestionan a mano: se sincronizan automáticamente con **external-dns** a partir de los Ingress.
+
+### 10. Mensajes de terminación claros en Jobs
+
+Los Jobs de chequeo y testing escriben un mensaje de terminación específico (usando el path de termination-log del contenedor) para que el fallo sea legible en la descripción del pod. Un fallo de un hook de pre-upgrade no se queda en un mensaje genérico de timeout: el job declara la causa real.
+
+### 11. Templates condicionales para recursos opcionales
+
+Los recursos que solo se despliegan bajo una condición (por ejemplo, un servicio auxiliar activado por un flag de `values`) se envuelven en condicionales del template. El recurso se renderiza solo cuando su condición se cumple.
+
+## Consecuencias
+
+### Positivas
+
+- **Charts homogéneos**: labels, nombres, probes, hooks y documentación siguen el mismo patrón en todas las apps.
+- **Fallos tempranos y legibles**: la validación de requisitos y los mensajes de terminación acotan los fallos a su causa real.
+- **Validación de valores**: el `values.schema.json` generado rechaza configuraciones inválidas antes de instalar.
+- **Despliegues saludables**: el `readinessProbe` evita que el tráfico llegue a pods no listos.
+- **Paquetes livianos y sin secretos**: `.helmignore` mantiene el chart limpio.
+- **URLs y DNS consistentes**: Ingress + external-dns automatizan la exposición.
+
+### Negativas
+
+- **Boilerplate de chart**: cada chart lleva templates, probes, hooks y documentación; una app nueva debe copiar y adaptar el patrón.
+- **Dependencia del contrato de settings**: el `values.schema.json` se genera desde el contrato y su vigencia depende del paso de exportación ([A-014](./A-014-generacion-artefactos-despliegue-desde-contrato-settings.md)).
+- **Curva de aprendizaje**: dominar templates, hooks y el ciclo de vida de Helm no es trivial.
+- **Infraestructura previa**: la validación de requisitos y external-dns asumen que el clúster ya provee esos componentes.

package/docs/adr/foundational/A-020-entorno-desarrollo-estandarizado-devcontainer.md

@@ -0,0 +1,58 @@
+# A-020: Entorno de desarrollo estandarizado con DevContainer
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-13
+
+**originally**: cortex-ide-vscode
+
+**Enriquecido desde**: Cortex doc "ide-vscode" — entorno de desarrollo con DevContainer
+
+**tags**: tooling
+
+## Contexto
+
+El entorno de desarrollo local determina la primera experiencia de un miembro nuevo y la reproducibilidad del trabajo diario. Sin un entorno estandarizado:
+
+- "En mi máquina funciona": dependencias, versiones de herramientas y configuraciones de IDE difieren entre equipos.
+- El onboarding exige instalar y configurar herramientas a mano, una por una.
+- Las herramientas de orquestación y despliegue se instalan con versiones distintas o se omiten.
+- El árbol de un monorepo grande abruma: no queda claro dónde están las apps, el dominio y las features.
+
+## Decisión
+
+Estandarizar el entorno de desarrollo con un **DevContainer** canónico en cada repositorio, una **imagen base con tooling** y un **workspace DDD**.
+
+### 1. DevContainer en la raíz del repositorio
+
+Cada repositorio define un `.devcontainer` en su raíz que describe el entorno de desarrollo: imagen base, extensiones recomendadas del IDE, configuraciones y scripts de post-creación. Un desarrollador abre el repositorio en el DevContainer y obtiene un entorno idéntico al del resto, sin instalar nada a mano.
+
+### 2. Imagen base con tooling preinstalado
+
+El DevContainer referencia una **imagen base preconfigurada** que ya trae las herramientas comunes de desarrollo y despliegue (orquestación, CLI de clúster, gestores de paquetes). La instalación de esas herramientas no se repite en cada arranque del contenedor.
+
+La imagen base del DevContainer es una imagen de contenedor más: se construye siguiendo las prácticas de [A-018](./A-018-practicas-build-imagenes-docker.md) y se publica por el pipeline ([A-016](./A-016-cicd-gitlab-pipeline-raiz-pipelines-modulares.md)). A-018 define **cómo** se construye una imagen; este ADR define **qué** imagen usa el entorno de desarrollo. La imagen se versiona y se actualiza periódicamente para incorporar herramientas nuevas o versiones estables.
+
+### 3. Workspace DDD
+
+Cada repositorio define un archivo de workspace (`.code-workspace`) que mapea las carpetas principales en secciones lógicas: aplicaciones (`apps/`), dominio (`domain/`) y features (`features/`). El workspace refleja la estructura de Clean Architecture ([A-001](./A-001-clean-architecture-4-capas.md)): quien abre el repositorio navega por capas, no por un árbol plano de archivos.
+
+### 4. Configuración por entorno fuera del workspace
+
+Los valores concretos de configuración por entorno no viven en el workspace ni en el DevContainer: se rigen por el contrato de settings ([A-013](./A-013-contrato-settings-unica-fuente-configuracion.md)) y sus artefactos derivados ([A-014](./A-014-generacion-artefactos-despliegue-desde-contrato-settings.md)). El entorno de desarrollo estandariza las herramientas y la vista del código, no la configuración de negocio.
+
+## Consecuencias
+
+### Positivas
+
+- **Entorno idéntico**: se elimina el "en mi máquina funciona" y las diferencias de versiones entre desarrolladores.
+- **Onboarding rápido**: un miembro nuevo abre el DevContainer y trabaja, sin instalar herramientas a mano.
+- **Herramientas consistentes**: la imagen base fija las versiones de orquestación y despliegue.
+- **Navegación por capas**: el workspace DDD hace visible la estructura de Clean Architecture.
+
+### Negativas
+
+- **Mantenimiento de la imagen base**: hay que versionarla y actualizarla cuando cambian las herramientas.
+- **Dependencia del DevContainer**: quien trabaje fuera del contenedor puede encontrar diferencias de entorno.
+- **Curva de aprendizaje**: configurar y mantener un DevContainer y su imagen base requiere familiaridad con Docker.
+- **Costo de reconstrucción**: cambiar la imagen base obliga a reconstruir el entorno.

package/docs/adr/foundational/A-022-formato-reporte-tests-ctrf.md

@@ -0,0 +1,55 @@
+# A-022: Formato de reporte de tests (CTRF)
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-13
+
+**originally**: cortex-testing
+
+**Enriquecido desde**: Cortex doc "testing" — sección sobre exportación de resultados de tests en CTRF
+
+**tags**: testing, tooling
+
+## Contexto
+
+Los tests de un proyecto (unitarios, de integración y end-to-end) se ejecutan con runners distintos y producen reportes en formatos propios de cada herramienta. Sin un formato común:
+
+- El pipeline de CI/CD no puede consumir los resultados de forma uniforme para decidir si una etapa pasa o falla.
+- No hay una fuente única y legible por máquina del estado de los tests para paneles, métricas de calidad y documentación generada.
+- Cada runner exige un parser ad hoc, y sumar un lenguaje o un framework nuevo obliga a escribir integración nueva.
+
+CTRF (Common Test Report Format) resuelve esto: es un estándar abierto, agnóstico al lenguaje y a la herramienta, que describe la ejecución de tests en un esquema JSON estable.
+
+## Decisión
+
+Adoptar **CTRF** como el formato canónico de reporte de tests. Todo runner que ejecute tests en un proyecto de Imolko exporta sus resultados en CTRF; el pipeline de CI/CD y las herramientas que consumen reportes leen CTRF, no los formatos propietarios de cada runner.
+
+### 1. Exportación desde todos los runners
+
+Cada runner se configura con su exportador CTRF correspondiente, sea un plugin oficial, un reporter de la comunidad o un adaptador propio. La lista de runners y sus mecanismos de exportación vive en cada proyecto (su configuración de tests), no se duplica en este ADR.
+
+### 2. Reporte accesible para el pipeline
+
+El reporte CTRF se produce como artefacto del job de test y queda disponible para el pipeline de CI/CD ([A-016](./A-016-cicd-gitlab-pipeline-raiz-pipelines-modulares.md)). El pipeline consume el reporte para:
+
+- Decidir el resultado del job: un reporte con tests fallidos o errores de ejecución implica job fallido.
+- Publicar el reporte como artefacto descargable.
+- Alimentar la documentación generada y los paneles de calidad con el estado real de los tests.
+
+### 3. Relación con la metodología de tests
+
+CTRF no define qué testear ni cómo nombrarlo: la metodología la fija [A-003](./A-003-tdd.md) (TDD, pirámide de tests, nomenclatura por capa). CTRF define únicamente el formato de salida. Un test bien diseñado sigue A-003; su reporte sale en CTRF.
+
+## Consecuencias
+
+### Positivas
+
+- **Interoperabilidad**: un solo consumidor (pipeline, panel, documentación) lee todos los reportes, sin importar el runner.
+- **Menos integraciones ad hoc**: sumar un runner nuevo solo requiere su exportador CTRF, no un parser nuevo.
+- **Observabilidad uniforme**: el estado de los tests es comparable entre proyectos y lenguajes.
+
+### Negativas
+
+- **Dependencia del exportador**: cada runner debe tener (o permitir implementar) un exportador CTRF; si no existe, hay que adaptarlo.
+- **Configuración adicional**: cada proyecto debe configurar el exportador y publicar el artefacto en el pipeline.
+- **Esquema en evolución**: hay que mantenerse al día con las versiones del esquema CTRF para no quedar desalineados con los consumidores.

package/docs/adr/foundational/A-023-composicion-bloques-prompt-agentes.md

@@ -0,0 +1,65 @@
+# A-023: Estándar de composición de bloques de prompt para agentes
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-13
+
+**originally**: cortex-prompt-composition-guide
+
+**Enriquecido desde**: Cortex doc "prompt-composition-guide" — estructura estándar de bloques de prompt para agentes
+
+**tags**: agentes, tooling
+
+## Contexto
+
+Los agentes que colaboran en los proyectos de Imolko (revisores de artefactos, generadores, orquestadores de casos de uso) se comportan según prompts. Sin un estándar de composición:
+
+- Cada agente arma sus instrucciones a su manera, con bloques que mezclan responsabilidades.
+- Las instrucciones procedimentales ("paso 1, paso 2, ...") se degradan en ejecuciones largas o con entradas grandes.
+- La ambigüedad produce salidas inconsistentes y difíciles de validar por máquina.
+- Los bloques de contexto se vuelcan sin prioridad, y el agente extrae lo irrelevante o alucina.
+
+## Decisión
+
+Adoptar una **estructura estándar de bloques de prompt** para todo agente de Imolko. Los prompts se componen de bloques con una responsabilidad única, reglas declarativas y un contrato de salida estricto.
+
+### Principios
+
+1. **Separación de responsabilidades**: cada bloque cumple un único propósito (personalidad, tarea, restricciones, datos) y no se mezclan.
+2. **Declarativo sobre procedimental**: se expresan reglas, restricciones y definiciones, no secuencias de pasos ni pseudo-algoritmos.
+3. **Diseño guiado por restricciones**: se limitan los grados de libertad y se hacen explícitas las expectativas para minimizar la ambigüedad.
+4. **Contexto de solo lectura**: el contexto no se modifica ni se reinterpreta; se usa selectivamente.
+5. **Continuidad sobre creatividad**: en pipelines de varias etapas, la salida previa es fuente de verdad y la nueva salida extiende, no redefine.
+
+### Bloques estándar
+
+1. **Personalidad**: quién es el agente; ancla tono y perspectiva y acota el tipo de razonamiento. Declara qué posee y qué no hace.
+2. **Capacidades**: en qué es bueno el agente; limita el dominio de expertise y evita la deriva hacia áreas ajenas.
+3. **Tarea**: qué debe producir en esta ejecución; fija la intención de salida y acota el alcance, sin verbos ambiguos.
+4. **Definición de especialidad** (crítico): qué representa esta sección, qué no debe hacer y cómo se relaciona con las anteriores; evita solapamientos.
+5. **Reglas de decisión** (metodología): cómo se toman decisiones, con restricciones declarativas, no pasos.
+6. **Restricciones de ejecución**: bloque unificado de restricciones de comportamiento, alineación y redacción.
+7. **Prioridad de contexto** (recomendado): cómo se usa el contexto, con un orden estándar para guiar la extracción relevante.
+8. **Bloques de contexto**: datos estructurados provistos al agente (marca, audiencia, producto).
+9. **Trabajo en curso** (estado): salidas previas del pipeline.
+10. **Reglas de continuidad**: cómo interactuar con el trabajo previo; no reafirmar contenido previo.
+11. **Contrato**: cumplimiento de la salida; adherencia estricta al esquema, sin texto extra y siempre una estructura válida.
+
+### Relación con la arquitectura
+
+Este estándar define la composición interna del prompt. La integración arquitectónica del agente — un puerto de dominio como cualquier otra dependencia — sigue la anatomía de [A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md). Los bloques declarados aquí se renderizan desde plantillas. El texto de prompt vive en plantillas, nunca en código.
+
+## Consecuencias
+
+### Positivas
+
+- **Consistencia entre agentes**: todos comparten la misma arquitectura de bloques.
+- **Determinismo y confiabilidad**: restricciones declarativas y contrato estricto reducen salidas inválidas.
+- **Arquitectura escalable**: la estructura escala a múltiples agentes y especialidades sin degenerar en prompts artesanales.
+- **Mantenibilidad**: cada bloque tiene una responsabilidad única y puede revisarse aislado.
+
+### Negativas
+
+- **Disciplina de autoría**: componer un prompt exige respetar la separación de responsabilidades y no caer en instrucciones procedimentales.
+- **Más estructura**: un prompt bien formado es más largo y deliberado que una instrucción libre.
+- **Curva de aprendizaje**: el equipo debe internalizar los principios para aplicarlos de forma consistente.

package/docs/adr/foundational/A-024-features-slices-verticales-portables.md

@@ -0,0 +1,41 @@
+# A-024: Features como slices verticales portables
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-13
+
+**originally**: A-001
+
+**Enriquecido desde**: Cortex ADR 004 — Clean Architecture feature structure with ports & drivers
+
+**tags**: arquitectura
+
+## Contexto
+
+Un workspace de Imolko crece con muchos casos de uso y múltiples destinos de despliegue (servidor HTTP, worker, simulador, nodo local). Para que una feature sea reutilizable entre esos destinos, debe implementar un caso de uso y ser independiente de la tecnología y de la app que la despliega. Esta decisión define dónde viven las features y cómo se componen en las apps.
+
+## Decisión
+
+Las features viven bajo un directorio `features/` a nivel de workspace, **nunca** dentro de apps individuales. Cada feature es una unidad autocontenida de lógica de negocio que puede desarrollarse, probarse y evolucionar independientemente de cualquier destino de despliegue.
+
+Las apps componen features en su capa de wiring importando e instanciando las features que necesitan. Esta es la ventaja arquitectónica principal: las features son **portables entre apps y modos de despliegue** — una feature desarrollada para una app puede reusarse en otra sin modificación.
+
+Las features no se acoplan entre sí: una feature nunca importa ningún elemento de otra feature; el acoplamiento ocurre solo en el wiring.
+
+El empaquetado por feature es opcional: una feature puede ser un paquete propio o convivir con otras en un paquete compartido. El cierre tecnológico es una propiedad **del paquete**, no del archivo: una feature es tech-free solo si su paquete lo es. Como el `package.json` es compartido, una dependencia tecnológica de cualquier miembro del paquete entra en el closure de todo el que lo importa; por eso una feature tech-free **no puede compartir paquete** con features que dependen de tecnología, y se le da paquete propio cuando su portabilidad o evolución independiente lo exige. El núcleo de una feature (caso de uso, adaptadores y driver ports) no importa tecnologías ([A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md)); el cierre tecnológico lo gobierna el empaquetado por tecnología ([A-026](./A-026-infraestructura-compartida.md)).
+
+La anatomía interna de una feature (puertos de dominio, adaptadores, driver ports) y su mecánica (cadena Puerto→Adaptador→Driver port, ISP) están en [A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md). La composición en wiring se detalla en [A-027](./A-027-patron-wiring-entry-point.md).
+
+## Consecuencias
+
+### Positivas
+
+- **Portabilidad de features**: una feature desarrollada para una app se reusa en otra sin modificación — su paquete no declara dependencias tecnológicas.
+- **Desarrollo paralelo**: múltiples features pueden desarrollarse simultáneamente sin conflictos.
+- **Despliegues independientes**: cada app selecciona y empaqueta solo las features que necesita y el driver de la tecnología que usa.
+- **Onboarding**: un desarrollador que aprende una feature entiende inmediatamente todas las demás.
+
+### Negativas
+
+- **Disciplina de composición**: mantener el acoplamiento entre features solo en el wiring requiere revisión constante.
+- **Sin librería compartida de ports**: la reutilización real se consigue componiendo features, no compartiendo su interior.

package/docs/adr/foundational/A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md

@@ -0,0 +1,104 @@
+# A-025: Anatomía y mecánica de una feature: puertos, adaptadores y drivers
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-13
+
+**originally**: A-001
+
+**Enriquecido desde**: Cortex ADR 004 — Clean Architecture feature structure with ports & drivers
+
+**tags**: arquitectura
+
+## Contexto
+
+Cada feature de caso de uso necesita una estructura interna consistente y una cadena clara que conecte su lógica de negocio con la infraestructura sin acoplarla. Sin un estándar de anatomía y de mecánica, cada feature improvisa su disposición de archivos y sus límites de responsabilidad, lo que degrada la navegación y la intercambiabilidad de implementaciones.
+
+El dominio y la tecnología hablan vocabularios distintos: el caso de uso opera con agregados y value objects; la infraestructura, con tablas, filas, mensajes y protocolos. La traducción entre ambos debe ser explícita, tipada y localizada, para que cambiar de tecnología no toque el caso de uso y para que ningún agregado de dominio ni tipo tecnológico (`any`, `unknown`) cruce la costura sin control.
+
+La versión anterior de esta decisión alojaba `drivers/<tech>/` y el transporte dentro de la feature. Eso forzaba a la feature a importar tecnología (mongoose, decoradores de framework) y rompía el objetivo de [A-024](./A-024-features-slices-verticales-portables.md): un paquete de feature que no declara dependencias tecnológicas. Esta decisión corrige la anatomía: la feature conserva solo las piezas tech-free; la implementación tecnológica y el transporte viven fuera.
+
+## Decisión
+
+### Anatomía canónica
+
+```
+features/<caso-de-uso>/
+├── use-case/
+│   ├── use-case.ts               # lógica de negocio — retorna el modelo de salida (DTO o stream)
+│   ├── input.dto.ts              # contrato de entrada del caso de uso
+│   ├── output.dto.ts             # modelo de salida en términos del dominio (VOs, tech-free)
+│   ├── <dependencia>.port.ts     # puertos de dominio: repository, query, event-bus…
+│   └── errors/
+├── adapters/
+│   ├── controller/
+│   │   ├── adapter.ts            # valida/traduce el input, invoca el caso de uso y traduce la salida de dominio
+│   │   └── input.dto.ts          # esquema de validación del input externo
+│   ├── <dependencia>/
+│   │   ├── adapter.ts            # implementa el puerto de dominio; traduce dominio ↔ raw data
+│   │   └── driver.port.ts        # la costura: contrato raw-data que shared-infra implementa
+│   └── …
+└── index.ts                      # API pública (exporta puertos, adaptadores, caso de uso, DTOs y errores)
+```
+
+- **`use-case/`** — la lógica de negocio, su modelo de salida y los puertos de dominio que consume. Los puertos de dominio (`*.port.ts`) viven junto al caso de uso.
+- **`adapters/`** — una carpeta por puerto de dominio, con `adapter.ts` y `driver.port.ts`. `controller/` valida y traduce el input, invoca el caso de uso y traduce la salida de dominio a su forma plana.
+- **`index.ts`** — la API pública que las apps importan; exporta puertos de dominio, driver ports, adaptadores, caso de uso, DTOs y errores. No exporta drivers: estos viven en `shared-infra/` ([A-026](./A-026-infraestructura-compartida.md)).
+- **La feature no tiene `drivers/`, ni `presenter/`, ni `service.port.ts`**: el driver tecnológico vive en `shared-infra/<tech>/` ([A-026](./A-026-infraestructura-compartida.md)); el presentador es propiedad de la app, no de la feature — el caso de uso retorna su modelo de salida y la app lo presenta ([A-027](./A-027-patron-wiring-entry-point.md)); el service port se disuelve porque driver y tecnología cohabitan en el mismo paquete.
+
+### Dos puertos, un adaptador
+
+| Rol | Archivo | Vocabulario |
+|-----|---------|-------------|
+| **Puerto de dominio** | `use-case/*.port.ts` (`XxxPort`) | dominio — tipos y lenguaje del negocio |
+| **Driver port** | `adapters/*/driver.port.ts` (`XxxDriverPort`) | raw data — mementos/snapshots, CloudEvents (cuando la costura es event-shaped) y DTOs planos; sin errores de dominio (`null` señala ausencia); sin tipos tecnológicos; nunca `any`/`unknown` |
+| **Adaptador** | `adapters/*/adapter.ts` (`XxxAdapter`) | la traducción — implementa el puerto de dominio, delega en el driver port, restaura agregados y mapea errores |
+| **Driver** | `shared-infra/<tech>/` (`Driver`) | la implementación tecnológica — implementa el driver port completo ([A-026](./A-026-infraestructura-compartida.md)) |
+
+- El **puerto de dominio** declara lo que el caso de uso necesita.
+- El **driver port** declara lo que un driver debe satisfacer. Es la costura tipada: usa **raw data** — mementos y DTOs planos — y nunca tipos tecnológicos (mongoose, decoradores de framework) ni `any`/`unknown`. La ausencia de datos se expresa con `null`; los errores de dominio se deciden en el adaptador, no en el driver.
+- El **adaptador** implementa el puerto de dominio y delega en el driver port; es el único lugar donde ocurre la traducción tipada dominio ↔ raw data, donde `null` se convierte en error de dominio y un memento en agregado restaurado.
+- El **driver** implementa el driver port en `shared-infra/<tech>/`: la consulta, el mapeo modelo↔memento, el manejo de errores tecnológicos y las transacciones viven enteros allí, junto a la tecnología ([A-026](./A-026-infraestructura-compartida.md)).
+- El **controlador** es el espejo de entrada del presentador: valida el input externo, lo traduce al `InputDto` del caso de uso e invoca el caso de uso ya ensamblado. No ensambla adaptadores ni caso de uso: la app es la única raíz de composición y le inyecta el caso de uso construido ([A-027](./A-027-patron-wiring-entry-point.md)).
+
+### La costura y el flujo
+
+La cadena completa es: `caso de uso → puerto de dominio → adaptador → driver port`. El driver port es la costura: el caso de uso y los adaptadores no importan nada más allá de ella ([A-001](./A-001-clean-architecture-4-capas.md)). El driver que la implementa vive en `shared-infra/<tech>/`; la app lo instancia y lo inyecta en el wiring ([A-027](./A-027-patron-wiring-entry-point.md)).
+
+El caso de uso **retorna** su modelo de salida (`output.dto.ts`): un `OutputDto` en respuestas one-shot (en términos del dominio — value objects, no primitivos; [A-050](./A-050-el-caso-de-uso-pide-al-dominio-no-lee-su-representacion.md)), o un **stream nativo** (`AsyncIterable<OutputDto>`, sin RxJS ni otra dependencia tecnológica) cuando emite más de un valor. No hay presentador en la feature: el presentador es un objeto de frontera **propiedad de la app**, el espejo del controlador — el controlador recibe el input desde afuera y lo entrega al caso de uso; el presentador recibe la salida del caso de uso (una vez, o iterando el stream) y la entrega al exterior, mapeándola al formato de la interface con `representations/<protocol>/` cuando la wire es schema'd (`@ObjectType` de GraphQL, protobuf, OpenAPI/Avro) y con transformaciones cosméticas propias de la app en caso contrario ([A-026](./A-026-infraestructura-compartida.md), [A-027](./A-027-patron-wiring-entry-point.md)). La dependencia apunta hacia adentro: la feature retorna un `OutputDto` en términos del dominio (value objects; o su stream) y no nombra ni el transporte, ni la representación, ni el presentador. Cuando la app no levanta un presentador dedicado (respuestas one-shot), el **controlador** traduce la salida de dominio a su forma plana; el presentador sigue siendo la pieza correcta cuando hay stream o una wire schema'd.
+
+### Reglas
+
+- **Un caso de uso por feature.**
+- **ISP en los puertos de dominio**: agrupan métodos por coherencia de negocio, no por CRUD; un protocolo estrecho por dependencia del caso de uso.
+- **Naming por rol: la carpeta del adaptador espeja el puerto de dominio que implementa.** `adapters/<dependencia>/` se nombra igual que `use-case/<dependencia>.port.ts`; `<dependencia>` se nombra por el **rol** que la dependencia juega para el caso de uso — acceso a un agregado (`claim-repository`, `stock-movement-repository`), publicación de eventos (`event-bus`), generación de identificadores (`id-generator`) — y no por el agregado que expone. La carpeta y el puerto cambian juntos: el nombre del puerto es la autoridad y la carpeta lo espeja. Un `stock-movement/` (concepto) hermanado con `claim-repository/` (rol) es el olor que esta regla elimina.
+- **El puerto de dominio no expone discriminadores del vocabulario raw del driver.** Cuando el caso de uso necesita resolver un objeto por un concepto de negocio ("el movimiento de esta factura"), el puerto declara un método con verbo de intención (`findByFactura(facturaId)`, [A-029](./A-029-verbos-intencion-metodos-lado-negocio.md)); el literal que traduce ese concepto al vocabulario del driver (`'FACTURA'`) vive en el adaptador. Un método CRUD-genérico que obliga al caso de uso a elegir el literal (`findByDocumentRef(type, reference)` con `'FACTURA'`) es el olor que esta regla elimina.
+- **El puerto de dominio nunca retorna `null`**: la ausencia la traduce el adaptador. En una consulta, a error de dominio (`ReferenceNotFoundError`); en una verificación, al veredicto `valid`/`invalid`. El `null` es vocabulario del driver port (raw data), no del caso de uso.
+- **La restauración en el adaptador compone y encamina los errores por el canal**: cuando el adaptador restaura un agregado desde su memento, compone `Memento.of` y `Aggregate.restore` con los operadores del tier (`seedV(...).pipe(V.chain(...))`) y ensancha los errores a la unión `Errors` de la feature **por anotación de tipo**, no con casts ([A-005](./A-005-either-return-custom-methods.md)). Nunca lanza ni desenvuelve con `getValue()`: los fallos de reconstrucción del memento y de `restore` viajan por el canal de error del `TaskValidation`/`Validation` y llegan a la app ([A-007](./A-007-data-contract-fail-fast.md)). La costura async se expresa con `TV.fromAsync` y un helper privado de firma `(param) => TaskValidation`. La unión `Errors` de la feature incluye los errores de cada agregado que restaura (`ClaimErrors`, `StockMovementErrors`), `MementoTamperedError` y los errores v8n de forma de la costura (`InvalidTypeError`, `TooSmallError`, `TooBigError`).
+- **Puerto de verificación**: cuando el caso de uso necesita comprobar un invariante (no obtener el objeto), el puerto declara un método con verbo de intención (`verify*`, [A-029](./A-029-verbos-intencion-metodos-lado-negocio.md)) que retorna `TaskValidation<Errors, void>` — `valid` si pasa, `invalid` con el error de dominio si no. El adaptador implementa el check (interpreta `null` e invoca predicados del dominio); el caso de uso delega y conserva el contexto.
+- **Los puertos de dominio usan conceptos de dominio; el driver port usa raw data.** DTOs custom solo cuando el dominio carece del concepto. Nunca `any` ni `unknown`. Cuando la costura es event-shaped, el raw data de escritura son eventos en formato estándar (p. ej. CloudEvents) y el de lectura el snapshot del agregado; el evento de dominio sin confirmar — que porta tipos de dominio — no cruza la costura tal cual: el adaptador produce la envolvente.
+- **El tipo de retorno de un método del puerto de dominio refleja su naturaleza**: lecturas y verificaciones declaran `TaskValidation`/`Validation`; mutaciones declaran `TaskExecution`/`Execution`. El tipo fija la fase en el pipe del caso de uso y el compilador la hace cumplir.
+- **El caso de uso retorna su modelo de salida** — un `OutputDto` o un `AsyncIterable<OutputDto>` nativo; no hay presentador ni `service.port.ts` en la feature (el presentador es propiedad de la app, [A-027](./A-027-patron-wiring-entry-point.md)).
+- **La feature es tech-free**: solo importa el stack de tipado y las utilidades genéricas que ya usa el dominio (result types, validación) y builtins de plataforma (`crypto`); nunca tecnología de framework, transporte o persistencia (nestjs, mongoose, pg, graphql, rxjs…).
+- **Las features nunca comparten puertos, adaptadores ni driver ports** — el acoplamiento ocurre solo en el wiring ([A-024](./A-024-features-slices-verticales-portables.md), [A-027](./A-027-patron-wiring-entry-point.md)).
+- **Las features nunca importan `shared-infra/` ni `representations/`** ([A-026](./A-026-infraestructura-compartida.md)); el driver se inyecta a través del driver port.
+- **Un driver port, una implementación por tecnología** en `shared-infra/<tech>/`. La tecnología nombra la implementación: `in-memory` y `local-disk` son tecnologías de aplazamiento, igual que `postgres` o `mongo`; permiten construir el caso de uso y la app sin elegir tecnología real y comparten estado dentro de su paquete ([A-026](./A-026-infraestructura-compartida.md)).
+- **El transporte vive en la app** ([A-027](./A-027-patron-wiring-entry-point.md)): el resolver HTTP/GraphQL o el comando CLI valida el input, inyecta los drivers, ejecuta el controlador y mapea el modelo de salida a la wire.
+
+## Consecuencias
+
+### Positivas
+
+- **Feature sin dependencias tecnológicas**: el paquete de la feature no declara tecnologías, lo que cumple [A-024](./A-024-features-slices-verticales-portables.md).
+- **Costura tipada y explícita**: el adaptador concentra la traducción dominio ↔ raw data, y el driver port tipado impide que `any`/`unknown` o tipos tecnológicos se filtren hacia la feature.
+- **Intercambiabilidad**: cambiar de tecnología toca solo `shared-infra/<tech>/`; el puerto de dominio, el adaptador, el driver port y el caso de uso no cambian.
+- **Aplazamiento de la tecnología**: `in-memory` y `local-disk` permiten construir y ejecutar el caso de uso y la app entera antes de elegir tecnología real.
+- **Menos archivos**: la feature ya no arrastra `drivers/`, `presenter/` ni `service.port.ts`.
+- **Consistencia entre features**: la anatomía canónica hace predecible la navegación.
+
+### Negativas
+
+- **Dos paquetes por feature**: la feature (puertos + adaptadores + caso de uso) y su driver en `shared-infra/<tech>/`; una feature nueva toca ambos.
+- **Raw data en la costura**: tipar el driver port exige modelar el memento/snapshot; para consultas complejas (filtros, paginación, transacciones) el puerto se expresa en términos de dominio y raw data, y la implementación entera vive en `shared-infra/<tech>/`.
+- **Disciplina de traducción**: mantener el driver port sin tipos tecnológicos ni errores de dominio requiere revisión constante.
+- **La regla de una verificación se replica en el doble de test**: el check vive en el adaptador; el doble de prueba del puerto repite esa lógica. Es el precio de un caso de uso que delega en lugar de decidir.

package/docs/adr/foundational/A-026-infraestructura-compartida.md

@@ -0,0 +1,44 @@
+# A-026: Infraestructura compartida (shared-infra)
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-13
+
+**originally**: A-001
+
+**Enriquecido desde**: Cortex ADR 004 — Clean Architecture feature structure with ports & drivers
+
+**tags**: arquitectura
+
+## Contexto
+
+Varias features y apps necesitan definiciones y lógica que ninguna de ellas posee exclusivamente: definiciones tecnológicas compartidas (esquemas de persistencia, formas de wire) y operaciones tecnológicas reutilizables. Sin una categorización de esta infraestructura compartida, el código común se mezcla con el de las features o se duplica, erosionando la dirección de dependencias.
+
+Si además esta infraestructura se empaqueta como un único paquete, importar cualquier parte arrastra las dependencias de todas las tecnologías: una app que solo usa MongoDB cargaría también las dependencias de Postgres. La granularidad del paquete y la dirección de la dependencia resuelven juntas ese problema.
+
+## Decisión
+
+El código tecnológico compartido se empaqueta por tecnología — un paquete por tech (`shared-infra/mongo/`, `shared-infra/postgres/`, `shared-infra/in-memory/`, …) — para que cada app importe solo las tecnologías que usa. Dos clases de paquete, con direcciones opuestas:
+
+**`shared-infra/<tech>/`** — los drivers que implementan los driver ports que las features declaran ([A-025](./A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md)), junto con las operaciones tecnológicas que necesitan (pools de conexiones, query builders, file I/O) y sus esquemas de persistencia y modelos tecnológicos (mongo `@Schema` y sus modelos, entidades postgres, layouts de EventStore/snapshots). El driver implementa el driver port completo — consulta, mapeo modelo↔memento, errores y transacciones — y vive aquí, nunca en la feature. Preferentemente agnósticos del dominio: acoplan conceptos de dominio solo cuando la operación lo exige (tipos de eventos, lógica de replay). Importan los driver ports y el dominio; las features nunca las importan. El esquema de persistencia es privado del driver: vive junto a él porque cambian juntos, y no se comparte fuera de este paquete. `in-memory` y `local-disk` son tecnologías de aplazamiento más: permiten construir el caso de uso y la app sin elegir tecnología real, y comparten estado dentro del paquete — varios drivers de features distintas inyectan el mismo store.
+
+**`representations/<protocol>/`** — las formas de wire (tipos `@ObjectType`/`@InputType`, mensajes protobuf, esquemas OpenAPI/Avro) que representan conceptos del dominio para el transporte. Las importa la app para mapear el modelo de salida a la wire; nunca las features, ni sus driver ports, ni los drivers de `shared-infra/`. Importan solo el dominio. Son **domain-aware y app-agnostic**: solo formas schema'd de protocolo, reutilizables por varias apps; los modelos de persistencia, los helpers de conversión (modelo↔memento) y cualquier comportamiento viven en `shared-infra/<tech>/`, nunca aquí.
+
+Son canónicas por protocolo: toda forma de wire que representa un concepto del dominio vive aquí, tenga uno o varios consumidores — una representación del dominio nunca se define ad-hoc en una app. Las formas de wire que son el contrato de una operación puntual (input, result o filter de un entrypoint) no representan un concepto del dominio: viven con su entrypoint, no aquí.
+
+La dirección de dependencias apunta hacia adentro: `representations/<protocol>/` importa solo el dominio; `shared-infra/<tech>/` importa el dominio y los driver ports que las features declaran (sus esquemas de persistencia viven dentro del mismo paquete); las features nunca importan `shared-infra/` ni `representations/` ([A-001](./A-001-clean-architecture-4-capas.md)).
+
+## Consecuencias
+
+### Positivas
+
+- **Duplicación reducida**: cada forma de wire vive una sola vez por protocolo, y cada operación y esquema de persistencia una sola vez por tecnología.
+- **Cierre tecnológico ligero**: la app importa solo los paquetes de la tecnología que usa (`shared-infra/<tech>/`) y las formas de wire de los protocolos que expone (`representations/<protocol>/`); las dependencias de las demás tecnologías no entran en su closure.
+- **Separación clara**: cada paquete tiene un vocabulario y una dirección de importación definidos — `shared-infra/<tech>/` (drivers y esquemas de persistencia) y `representations/<protocol>/` (formas de wire).
+- **Dominio protegido**: ports y dominio nunca importan `shared-infra/` ni `representations/`.
+
+### Negativas
+
+- **Acoplamiento a features**: cada paquete `shared-infra/<tech>/` importa los driver ports de las features que implementa; no es una librería reutilizable entre sistemas ([A-017](./A-017-taxonomia-repositorios-librerias-sistemas.md)).
+- **Tres hogares por tipo de forma**: el equipo distingue forma de persistencia (privada del driver, en `shared-infra/<tech>/`) de representación del dominio (canónica por protocolo, en `representations/<protocol>/`) y de payload de operación (input/result/filter, propiedad del entrypoint que lo expone); confundirlas — una representación del dominio definida ad-hoc en una app, un payload de operación promovido a `representations/`, o un esquema de persistencia en `representations/` — reintroduce la duplicación o acopla `representations/` a una app.
+- **Acoplamiento innecesario al dominio**: un driver que acopla conceptos de dominio sin que la operación lo exija erosiona la reutilización y acerca la infraestructura al dominio.