@imolko/ultra-agent 0.1.0-beta

package/docs/adr/foundational/A-003-tdd.md

@@ -0,0 +1,97 @@
+# A-003: Desarrollo basado en pruebas (TDD)
+
+**Estado**: Aceptado
+
+**Fecha**: 2025-02-25
+**originally**: imolko
+
+**tags**: testing
+
+## Contexto
+
+Las pruebas automatizadas fijan el comportamiento esperado de todo el código del proyecto, en especial de las reglas de negocio complejas: validaciones de value-objects, transiciones de estado de agregados, políticas de negocio, sagas y cálculos de inventario.
+
+La forma de escribirlas necesita una decisión canónica que fije el ciclo, las capas, la nomenclatura y la cobertura de cada artefacto.
+
+Mientras esa forma queda implícita, cada artefacto prueba a su manera: los errores de dominio se detectan tarde, las regresiones se acumulan al modificar reglas de validación o lógica de agregados y los expertos del dominio pierden visibilidad de qué comportamientos están cubiertos.
+
+## Decisión
+
+Adoptar **Test-Driven Development (TDD)** con el ciclo **red-green-refactor** como metodología obligatoria para todo el código del proyecto.
+
+### Stack de testing
+
+El stack concreto de testing (runner, matchers, tipos de error) es específico de cada ecosistema y lo define su tier de lenguaje. Este ADR fija los principios.
+
+### Principios
+
+1. **Red-Green-Refactor**: escribir un test que falle → implementar el código mínimo → refactorizar
+2. **Slices verticales**: un test → una implementación. No escribir todos los tests primero y luego toda la implementación
+3. **API pública**: los tests verifican comportamiento a través de la API pública del artefacto, no de sus internos
+4. **Tests en el idioma del repo**: los nombres y descripciones de los tests van en el idioma del repo (`issue_language`, [A-052](./A-052-distribucion-metodologia-paquete-versionado.md)), el idioma de los colaboradores y expertos del dominio
+5. **Aserciones semánticas**: usar aserciones que expresen el resultado del dominio (válido / inválido / error) en lugar de asserts genéricos
+6. **Tracer bullet**: el primer test siempre verifica la creación válida del artefacto
+
+### Pirámide de tests en tres capas
+
+Organizamos los tests en tres capas con propósitos diferenciados. Cada capa responde una pregunta distinta sobre el sistema:
+
+| Capa | Propósito | Características |
+|------|-----------|-----------------|
+| **Contract** | Validar interfaces, esquemas y contratos — no comportamiento | Sin dependencias externas, validan estructura de datos y tipos |
+| **Unit** | Lógica de dominio aislada con dependencias mockeadas | Rápidos (milisegundos), deterministas, sin I/O |
+| **Integration** | Features punta a punta con infraestructura real o containerizada | Verifican que los adaptadores cumplen los contratos definidos por los puertos |
+
+**Regla de proporción**: la mayoría de los tests deben ser unitarios, seguidos por contract, y la menor cantidad deben ser integration. Los tests de integración son más lentos y frágiles; los unitarios y de contrato dan feedback en segundos.
+
+**Hogar de cada capa**: los tests unitarios y de contrato de una feature viven en la feature. El test de integración — el flujo completo caso de uso → adaptador → driver contra un driver real — vive en `shared-infra/<tech>/`, junto al driver que verifica ([A-026](./A-026-infraestructura-compartida.md)); la feature puede exportar una suite de contrato reutilizable que cada driver de `shared-infra/<tech>/` ejecuta contra su propia implementación.
+
+### Convenciones de nomenclatura
+
+El nombre del archivo de test debe comunicar su capa sin requerir leer su contenido. Usamos un sufijo estandarizado que identifica el tipo de test:
+
+- **Contract**: sufijo que denote validación de contrato (ej. `.contract.test.*`, `_contract_test.*`)
+- **Unit**: sufijo estándar de test unitario (ej. `.unit.test.*`, `_test.*` cuando el default es unitario)
+- **Integration**: sufijo que denote integración (ej. `.integration.test.*`, `_integration_test.*`)
+
+La convención concreta del sufijo la define el tier de lenguaje de cada ecosistema. Lo importante es que el nombre del archivo distinga la capa.
+
+### Separación de runners por entorno de ejecución
+
+Cuando un proyecto tiene múltiples entornos de ejecución (ej. browser y servidor), puede ser necesario separar los tests en runners distintos. Cada runner está optimizado para el entorno donde se ejecuta el código:
+
+- **Browser/UI**: runner con DOM simulado para componentes y lógica de presentación
+- **Servidor/CLI**: runner con acceso real a sistema de archivos, variables de entorno y APIs del sistema operativo
+
+La separación permite que cada entorno use las herramientas nativas que necesita (ej. acceso al sistema de archivos en servidor, DOM simulado en browser) sin comprometer la velocidad ni la fidelidad de los tests. El CI ejecuta ambos runners secuencialmente.
+
+**Criterios para separar runners:**
+1. Si el código bajo prueba requiere APIs específicas de un entorno (DOM, filesystem, network sockets), usar el runner de ese entorno
+2. Si el código es puramente lógico y no toca I/O, puede ejecutarse en cualquier runner — preferir el más rápido
+3. Un comando único debe ejecutar todos los runners para feedback completo en CI
+
+### Cobertura requerida
+
+- **Value-objects**: creación válida, tipo inválido, mínimo/máximo, formato, instancia
+- **Entidades**: creación válida con ID, validaciones de propiedades
+- **Agregados**: creación válida, restauración desde snapshot/memento, transiciones de estado
+- **Servicios de dominio**: casos de éxito, casos de error, edge cases
+- **Features (casos de uso)**: flujo exitoso, errores de dominio, errores de infraestructura
+
+### Guía detallada
+
+Ver el skill de TDD en el paquete `@imolko/ultra-agent` (la fuente canónica del conjunto, [A-052](./A-052-distribucion-metodologia-paquete-versionado.md)) para patrones de test, ejemplos y referencias.
+
+## Consecuencias
+
+### Positivas
+
+- **Confianza en refactors**: los tests garantizan que los cambios no rompen comportamiento existente
+- **Documentación viva**: los tests describen las reglas de negocio, legibles por expertos del dominio
+- **Detección temprana**: errores de dominio se detectan en segundos, no en días
+- **Diseño guiado por tests**: TDD fuerza pensar en la API desde la perspectiva del consumidor
+
+### Negativas
+
+- **Tiempo inicial**: escribir tests antes del código requiere más tiempo al inicio (se recupera en mantenimiento)
+- **Disciplina**: requiere que todo el equipo siga la metodología consistentemente

package/docs/adr/foundational/A-005-either-return-custom-methods.md

@@ -0,0 +1,80 @@
+# A-005: Métodos del lado del negocio retornan `Result` (Either)
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-05-22
+**originally**: imolko
+
+**tags**: dominio
+
+## Contexto
+
+Los procesos y operaciones se componen como un pipeline de pasos encadenados ([A-044](./A-044-composicion-funcional-procesos-operaciones.md)). Para que el pipeline no se interrumpa, cada paso produce un valor para el siguiente; un paso que lanza una excepción rompe la composición y obliga al caller a cablear el control de errores a mano.
+
+La construcción de un artefacto de dominio ya retorna un `Result`/`Either` que encapsula la posibilidad de error. Los métodos que se agregan manualmente (como `add()`, `subtract()`, `isExpired()`) necesitan la misma convención de retorno. Apartarse de ella toma dos formas incorrectas:
+
+1. **Lanzar excepciones**: el método valida y lanza `throw`; el caller debe envolver cada llamada en try/catch y el pipeline se rompe.
+2. **Desenvolver el `Result`**: el método extrae el valor y descarta el error, forzando al caller a manejar el error fuera del tipo.
+
+Cualquiera de las dos impide componer el método dentro del pipeline.
+
+## Decisión
+
+Todo método del lado del negocio — el dominio y los casos de uso, con sus puertos ([A-029](./A-029-verbos-intencion-metodos-lado-negocio.md)) — debe:
+
+1. **Retornar `Result`/`Either`** — el método que produce un valor retorna el error como valor en el canal de error; nunca el valor a secas.
+2. **No desenvolver el `Result` dentro del método** — se retorna íntegro.
+3. **No lanzar excepciones** — ningún método del lado del negocio lanza; el error viaja en el canal de error del `Result`.
+
+Este ADR fija *qué* retornan los métodos; *por qué* (componer sin interrupciones) lo fija [A-044](./A-044-composicion-funcional-procesos-operaciones.md). El tipo concreto de `Result` y sus operadores los provee el tier de lenguaje de cada ecosistema.
+
+### Regla
+
+```text
+// ✅ CORRECTO: retorna Result, el caller compone
+restar(otro): Result<Errores, Cantidad> {
+  return Cantidad.crear({ valor: nuevo })
+}
+
+// ❌ INCORRECTO: desenvuelve el Result (descarta el error)
+restar(otro): Cantidad {
+  return Cantidad.crear({ valor: nuevo }).valor
+}
+
+// ❌ INCORRECTO: lanza excepción
+restar(otro): Cantidad {
+  si nuevo <= 0: lanzar Error()
+}
+```
+
+### Componer, no desmembrar
+
+La decisión fija *qué* retorna el método; *cómo* lo consume el caller importa igual, porque de eso depende que la composición se mantenga ([A-044](./A-044-composicion-funcional-procesos-operaciones.md)):
+
+1. **Componer con los operadores del tier** — el caller encadena el `Result` con los operadores que provee el ecosistema; no ramifica sobre los predicados de estado (que son booleanos y no estrechan el tipo).
+2. **Sin extracción forzada** — el valor se obtiene dentro del operador, donde el tipo ya está resuelto; no con aserciones de no-nulo.
+3. **Ensanchar el canal de error por anotación de tipo, no por casts** — cuando un paso produce un error más estrecho que el del proceso, se anota el tipo más amplio en la variable que lo recibe.
+
+### Tipos de retorno según la operación
+
+| Operación | Tipo de retorno | Justificación |
+|-----------|----------------|---------------|
+| Construcción interna dentro de otro método | `Result<Errores, T>` | La construcción puede fallar; propagar el `Result` |
+| Transformación sin fallo (p. ej. `equals()`, un getter de primitivo) | valor directo (`boolean`, primitivo, …) | No hay posibilidad de error |
+| Validación / consulta con fallo | `Result<Errores, T>` | El fallo es parte del dominio; encapsular en `Result` |
+| Operación aritmética cuyo resultado debe cumplir invariantes | `Result<Errores, T>` | El resultado se construye con un constructor que ya retorna `Result` |
+
+## Consecuencias
+
+### Positivas
+
+- **Componibilidad total**: cualquier método se integra en el pipeline sin adaptadores.
+- **Sin excepciones**: los errores de dominio son valores, no saltos de pila — facilita testing y razonamiento.
+- **Consistencia con el constructor**: mismo patrón que la construcción del artefacto.
+- **Errores declarados**: el tipo `Result` documenta todos los fallos posibles.
+- **Testabilidad**: los tests usan aserciones semánticas (válido/inválido); el detalle concreto lo define el tier de lenguaje (integrado en el ciclo TDD, [A-003](./A-003-tdd.md)).
+
+### Negativas
+
+- **Verbosidad en callers simples**: si el caller solo necesita el valor, debe manejar el `Result` explícitamente. En la práctica es poco frecuente porque la arquitectura favorece pipelines.
+- **Dependencia del tipo `Result`**: cada método debe importar el tipo y los errores declarados del artefacto.

package/docs/adr/foundational/A-006-feature-completion-criteria.md

@@ -0,0 +1,47 @@
+# A-006: Criterios de completitud de artefactos de dominio y features (definition of done)
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-05-27
+**originally**: imolko
+
+**tags**: testing
+
+## Contexto
+
+Un artefacto de dominio o feature se completa cerrando tres frentes a la vez: la lógica (código y reglas de negocio), la prueba (tests que fijan el comportamiento esperado) y la documentación (el formato canónico de [A-032](./A-032-domain-artifact-documentation-format.md)). Cuando una herramienta de scaffolding lo genera, añade además material de construcción — placeholders e instrucciones de implementación — que guía la implementación pero no es parte del artefacto terminado.
+
+La completitud necesita una decisión canónica que fije cuándo un artefacto se declara terminado: qué criterios aplican y cómo se verifican.
+
+Mientras esa decisión queda implícita, la completitud se confunde con una señal aislada — **tests verdes** se lee como "terminado" — y quedan sin cerrar la documentación y sin retirar el material de construcción. El artefacto funciona, pero no está documentado para el equipo y arrastra material de construcción ajeno.
+
+## Decisión
+
+Un artefacto de dominio o feature se considera **completo** únicamente cuando cumple **todos los criterios de completitud aplicables**, cada uno verificable de forma explícita. No importa quién lo produjo — herramienta de scaffolding, agente o persona. La completitud es un estado **binario y verificable criterio por criterio**, no una señal aislada. El orden de implementación es libre; ningún criterio aplicable puede omitirse.
+
+Los criterios concretos los fijan sus ADRs propietarios; este ADR los referencia, no los re-decide:
+
+| Frente | Criterio | Lo fija |
+|--------|----------|---------|
+| Lógica | El código compila y los tests pasan | [A-003](./A-003-tdd.md); lo verificable por máquina, [A-045](./A-045-guardrails-aplicables-no-directrices.md) |
+| Flujo | El caso de uso se expresa como composición de pasos | [A-044](./A-044-composicion-funcional-procesos-operaciones.md) |
+| Documentación | Formato y frontmatter canónicos, sin placeholders | [A-032](./A-032-domain-artifact-documentation-format.md) |
+| Scaffolding | El material de construcción no sobrevive al artefacto terminado | el tier de lenguaje define el archivo concreto y su eliminación |
+
+Cada criterio se verifica de forma explícita: por máquina (compila, tests verdes, scaffolding ausente) o por revisión (flujo, documentación).
+
+## Consecuencias
+
+### Positivas
+
+- **"Terminado" no ambiguo**: cualquier productor — herramienta, agente o persona — dispone de una lista de criterios aplicables para declarar un artefacto completo.
+- **Documentación siempre cerrada**: al ser parte de la completitud, el artefacto terminado describe su dominio para el equipo ([A-032](./A-032-domain-artifact-documentation-format.md)).
+- **Sin material de construcción residual**: el scaffolding no sobrevive al artefacto terminado.
+- **Verificación explícita**: cada criterio se comprueba por máquina o por revisión ([A-045](./A-045-guardrails-aplicables-no-directrices.md)), no por la memoria del productor.
+- **Cierre del ciclo**: la completitud cierra la brecha entre "el código funciona" y "el artefacto está terminado para el equipo".
+
+### Negativas
+
+- **Trabajo manual**: completar la documentación es redacción humana, no generación automática ([A-032](./A-032-domain-artifact-documentation-format.md)).
+- **Disciplina**: el equipo debe verificar todos los criterios aplicables antes de declarar el artefacto completo.
+- **El productor aún puede detenerse antes**: si el issue no menciona la completitud, el agente puede detenerse en tests verdes; se mitiga referenciando el skill por nombre en el issue ([A-038](./A-038-issues-referencian-skills-nombre.md)).

package/docs/adr/foundational/A-007-data-contract-fail-fast.md

@@ -0,0 +1,109 @@
+# A-007: Contrato de datos: fallo en origen, sin fallbacks silenciosos
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-12
+
+**originally**: cortex-035
+
+**Enriquecido desde**: Cortex ADR 035 — Data Contract Fail-Fast Policy
+
+**tags**: testing
+
+## Contexto
+
+Un caso de uso consume dependencias de datos: valores que necesita para producir un
+resultado correcto. Una dependencia requerida se satisface en origen, o el caso de uso no
+se ejecuta.
+
+El tratamiento de una dependencia insatisfecha necesita una decisión canónica: qué se hace
+cuando el dato requerido no está disponible.
+
+Mientras esa decisión queda implícita, cada capa agrega su propio aterrizaje suave — valores
+por defecto, advertencias y continuación — y el efecto acumulativo es que un caso de uso
+reporta ÉXITO con resultados incorrectos o sin sentido. Ninguna capa confía en la capa
+superior; una pérdida de datos produce solo una advertencia en el log.
+
+## Decisión
+
+Una dependencia de datos requerida no satisfecha **falla en origen**: sin fallbacks
+silenciosos ni opcionales por defecto. Un caso de uso que reporta ÉXITO garantiza que todos
+sus contratos de datos fueron honrados; no existe el éxito parcial con datos faltantes.
+
+### 1. Fail-fast: sin fallbacks silenciosos
+
+Cuando una dependencia de datos requerida no puede satisfacerse, el sistema falla
+inmediatamente. No se admite:
+
+- Capturar el error y continuar
+- Advertir y continuar
+- Retornar colecciones vacías en caso de error
+- Reemplazar el dato ausente por un valor por defecto
+
+Los errores se propagan por el canal de error del ecosistema. No se crean canales nuevos.
+
+### 2. Modelos de concepto, no bolsas de datos
+
+Un modelo de dominio representa un concepto de negocio del lenguaje ubicuo
+([A-031](./A-031-ubiquitous-language.md)); un modelo genérico con campos mayormente
+opcionales es un DTO de transporte, no un modelo de dominio.
+
+### 3. No-opcional-por-defecto
+
+Los campos son requeridos a menos que la realidad del negocio justifique un campo opcional,
+con la razón documentada en el modelo. Un campo que "usualmente está presente pero a veces
+falta" es requerido: la ausencia se maneja explícitamente en el llamador, no se oculta con
+un valor por defecto.
+
+### 4. Invariantes en el momento de construcción
+
+Las invariantes de negocio se aplican al construir el modelo, no en métodos de validación
+separados ni en verificaciones posteriores:
+
+- Campos requeridos sin valor por defecto
+- Colecciones no vacías como restricción de construcción
+- Números positivos donde el negocio lo exige
+- Validaciones entre campos
+
+La construcción falla inmediatamente si una invariante no se cumple. Un modelo no puede
+existir en un estado inválido: no hay ventana de "construir primero, validar después". La
+verificación de estas invariantes sigue el ciclo TDD ([A-003](./A-003-tdd.md)).
+
+### 5. El consumidor confía en el contrato, verificado por máquina
+
+La declaración de dependencias de un consumidor — p. ej. la plantilla de un motor de
+renderizado — es su contrato de datos. El consumidor no protege con condicionales un dato
+declarado como requerido: el condicional sobre un dato requerido oculta una violación de
+contrato y se trata como defecto en revisión. El condicional solo es aceptable para conceptos
+genuinamente opcionales con su razón documentada.
+
+Cuando el consumidor es declarativo — declara sus dependencias y las referencia en su cuerpo,
+p. ej. una plantilla — la verificación es bidireccional y por máquina, como guardrail
+([A-045](./A-045-guardrails-aplicables-no-directrices.md)): cada dependencia declarada está
+presente en el contexto, y cada variable referenciada tiene una dependencia declarada. La
+materialización concreta de la verificación es del tier de lenguaje.
+
+## Consecuencias
+
+### Positivas
+
+- **Resultados confiables**: ÉXITO significa que se usaron los datos correctos.
+- **Detección temprana**: las violaciones de contrato se detectan en el punto más temprano
+  posible (la construcción del modelo).
+- **Sin aterrizajes suaves en cascada**: una falla en el origen, no valores vacíos
+  propagándose por N capas.
+- **Contrato auto-documentado**: la declaración de dependencias del consumidor es el contrato
+  de datos.
+- **Testing acotado**: los modelos con restricciones de "no vacío" fallan de forma predecible;
+  no hay necesidad de probar casos de datos vacíos en cada capa ([A-003](./A-003-tdd.md)).
+
+### Negativas
+
+- **Todo campo requerido debe tener datos**: no hay "empezar vacío y ver qué pasa".
+- **Los datos deben estar disponibles antes de que el caso de uso se ejecute**: siempre fue
+  cierto, ahora está aplicado.
+- **Migración**: los modelos existentes con valores por defecto deben auditarse y
+  actualizarse.
+- **El autor del consumidor mantiene la declaración en sincronía**: las dependencias
+  declaradas deben coincidir con las referencias en el cuerpo (aplicado por la verificación
+  bidireccional).

package/docs/adr/foundational/A-008-bounded-context-decomposition.md

@@ -0,0 +1,130 @@
+# A-008: Descomposición en Bounded Contexts
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-12
+
+**originally**: sentinel-0001
+
+**Enriquecido desde**: Sentinel ADR 0001 — Descomposición en Bounded Contexts del dominio
+
+**tags**: arquitectura, dominio
+
+## Contexto
+
+Un dominio DDD con múltiples artefactos (agregados, entidades, value objects, servicios,
+eventos, casos de uso) requiere una organización que permita navegar y comprender el sistema.
+La asignación de cada artefacto a un Bounded Context es necesaria para generar documentación
+estructurada y facilitar el descubrimiento.
+
+Sin embargo, no todos los artefactos tienen el mismo peso semántico. Algunos son
+value objects genéricos (validaciones de formato, tipos primitivos enriquecidos) que
+carecen de lógica de dominio específica. Otros forman agrupaciones naturales alrededor
+de un agregado raíz. Tratar todos los artefactos como iguales y asignarlos a un único
+contexto plano oscurece la estructura real del dominio.
+
+Se necesita un criterio sistemático para identificar agrupaciones naturales (Bounded
+Contexts) y asignar cada artefacto al contexto que le corresponde.
+
+## Decisión
+
+### 1. Identificar agrupaciones naturales
+
+Un Bounded Context se identifica respondiendo a la pregunta: **"¿qué grupo de artefactos
+gira alrededor de un mismo agregado raíz o concepto central?"**
+
+Cada Bounded Context debe tener:
+
+- Un **agregado raíz** o concepto central que le da identidad
+- Artefactos que **dependen principalmente** de otros artefactos dentro del mismo contexto
+
+Los contexts de un mismo sistema comparten el lenguaje ubicuo del sistema (ver
+[A-031](./A-031-ubiquitous-language.md)); lo que los separa es la cohesión alrededor de
+un agregado raíz.
+
+Síntomas de que dos artefactos pertenecen a contexts distintos:
+- Referencian conceptos de negocio fundamentalmente diferentes
+- Cambian por razones diferentes (diferentes stakeholders, diferentes ritmos de cambio)
+
+### 2. Artefactos genéricos de bajo valor semántico → contexto compartido
+
+Los artefactos que implementan validaciones puras (regex, min/max, enum, formato) son
+utilidad sin lógica de dominio: se agrupan en un contexto compartido (p. ej.
+`shared-kernel`) que refleja su naturaleza de utilidad compartida. `scope::core`
+([A-009](./A-009-use-case-taxonomy.md)) designa la criticidad de un caso de uso, un eje
+independiente del Bounded Context.
+
+Características de los artefactos del contexto compartido:
+- Validan solo formato
+- Son reusables entre los demás contexts
+- Son análogos a tipos primitivos enriquecidos (UUID, números naturales, schemas)
+
+El contexto compartido funciona como un **Shared Kernel**: artefactos compartidos entre
+contexts que no pertenecen exclusivamente a ninguno de ellos.
+
+### 3. Artefactos compartidos: documentar la dependencia
+
+Cuando un artefacto del contexto compartido es consumido por artefactos en otros contexts,
+los artefactos consumidores documentan la dependencia en su documentación — el frontmatter
+y la sección `Relaciones` siguen
+[A-032](./A-032-domain-artifact-documentation-format.md). El artefacto compartido no
+referencia a sus consumidores.
+
+### 4. Proceso de asignación
+
+Para asignar artefactos a Bounded Contexts:
+
+1. **Identificar los agregados raíz**: ¿cuáles son las entidades principales del dominio
+   que actúan como raíz de agregados?
+2. **Agrupar dependencias**: para cada agregado raíz, listar todos los artefactos que
+   dependen de él o que este referencia directamente.
+3. **Identificar artefactos huérfanos**: artefactos que no dependen de ningún agregado
+   raíz y que son usados por múltiples contexts → candidatos al contexto compartido.
+4. **Verificar cohesión**: cada contexto debe tener alta cohesión interna (los artefactos
+   dentro del contexto se referencian entre sí con frecuencia) y bajo acoplamiento externo
+   (las dependencias entre contexts son mínimas y documentadas).
+5. **Nombrar el contexto**: usar un nombre que refleje el concepto central, no la
+   implementación.
+
+Criterios adicionales:
+- Los casos de uso se asignan al mismo contexto que el agregado que modifican o consultan
+- Los eventos de dominio se asignan al contexto del agregado cuyos datos describen (quién
+  los emite y publica lo define [A-010](./A-010-propiedad-emision-eventos-dominio.md))
+- Si un artefacto depende de dos agregados raíz, revisar si el diseño de bounded contexts
+  es correcto o si se necesita una interfaz/contrato entre contexts
+
+### 5. Separación de responsabilidades
+
+Cada Bounded Context tiene un propósito documentado que responde a la pregunta: "¿qué
+parte del dominio modela este contexto?"
+
+Ejemplo genérico de propósitos:
+
+| Contexto | Propósito |
+|---|---|
+| `shared-kernel` | Validaciones genéricas reusables entre contexts (utilidad compartida) |
+| `contexto-a` | Gestión del ciclo de vida de la entidad central A y sus dependencias directas |
+| `contexto-b` | Gestión de la entidad B, sus recursos asociados e integraciones externas |
+
+## Consecuencias
+
+**Positivas:**
+
+- Separación clara de responsabilidades dentro del dominio
+- La documentación generada se organiza en secciones navegables por contexto
+- Facilita el descubrimiento: un desarrollador nuevo puede identificar rápidamente en qué
+  contexto se encuentra lo que busca
+- Proporciona criterios objetivos para decidir dónde reside cada artefacto
+
+**Negativas:**
+
+- El contexto compartido carece de agregado raíz e identidad de negocio: es una agrupación
+  de utilidad, y tratarla como un Bounded Context pleno confunde
+- Añade contextos que pueden parecer artificiales si el dominio es pequeño
+
+**Neutrales:**
+
+- Los Bounded Contexts son solo una separación lógica y conceptual: no tienen efecto sobre
+  la estructura de archivos del repositorio ni sobre las dependencias del código.
+- La herramienta de generación de documentación puede usar los Bounded Contexts como criterio
+  de agrupación sin que el sistema de build los conozca

package/docs/adr/foundational/A-009-use-case-taxonomy.md

@@ -0,0 +1,99 @@
+# A-009: Taxonomía de criticidad de casos de uso
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-07
+
+**originally**: sentinel-0004
+
+**tags**: arquitectura, dominio
+
+## Contexto
+
+Los casos de uso de un dominio tienen diferentes niveles de criticidad y propósitos. Sin una taxonomía explícita, la clasificación es inconsistente entre desarrolladores y no hay criterios objetivos para decidir qué casos de uso son esenciales y cuáles son auxiliares. Se necesita una taxonomía de criticidad que asigne a cada caso de uso un nivel y permita filtrarlo y priorizarlo según el interés del stakeholder.
+
+## Decisión
+
+### 1. Taxonomía de criticidad: `scope::`
+
+Cada caso de uso se clasifica en exactamente uno de tres niveles de criticidad — `scope::core`, `scope::support` o `scope::configuration` — expresados como un tag con prefijo `scope::` en el frontmatter del feature (esquema en [A-032](./A-032-domain-artifact-documentation-format.md)).
+
+### 2. Definiciones explícitas
+
+#### `scope::core`
+
+Casos de uso que implementan el propósito fundamental del dominio. Si un caso de uso `core` falla o no existe, el dominio **no puede cumplir su función principal**.
+
+Características:
+- Representan el flujo de valor primario del dominio
+- Su ausencia es un bloqueo para la puesta en producción
+- Son los primeros en implementarse y los últimos en desactivarse
+- Típicamente representan la mayoría de los casos de uso (~50-70%)
+
+Ejemplos genéricos:
+- Registrar una entidad central del dominio
+- Procesar un evento entrante del exterior
+- Validar una operación contra reglas de negocio
+- Ejecutar una transacción que mueve valor entre agregados
+
+#### `scope::support`
+
+Casos de uso que mejoran la experiencia, habilitan optimizaciones o proporcionan información adicional. El dominio **puede operar** sin ellos, aunque con funcionalidad reducida o menor eficiencia.
+
+Características:
+- No son necesarios para el flujo de valor primario
+- Su ausencia degrada la experiencia pero no bloquea la operación
+- Pueden implementarse en iteraciones posteriores al MVP
+
+Ejemplos genéricos:
+- Filtrar entidades por criterios secundarios
+- Validar permisos granulares (más allá de la autorización básica)
+- Generar reportes o vistas resumidas
+- Notificar a usuarios sobre eventos no críticos
+
+#### `scope::configuration`
+
+Casos de uso que configuran el sistema para que los casos `core` y `support` puedan operar. Se ejecutan típicamente durante el onboarding, setup inicial o mantenimiento administrativo.
+
+Características:
+- No se ejecutan durante la operación normal del dominio
+- Su frecuencia de ejecución es baja (una vez por tenant, una vez por release, etc.)
+- Frecuentemente requieren privilegios elevados o contexto de administrador
+- Su ausencia no bloquea la operación de un sistema ya configurado
+
+Ejemplos genéricos:
+- Registrar un nuevo tenant o cliente en el sistema
+- Configurar reglas de autorización o políticas
+- Definir esquemas de datos o estructuras que otros casos de uso consumen
+- Establecer parámetros de integración con sistemas externos
+
+### 3. Criterios de clasificación
+
+Para clasificar un caso de uso, responder las siguientes preguntas en orden:
+
+1. **¿Se ejecuta durante la operación normal del dominio?**
+   - NO → `scope::configuration`
+   - SÍ → continuar a la pregunta 2
+
+2. **¿Puede el dominio cumplir su propósito principal sin este caso de uso?**
+   - NO → `scope::core`
+   - SÍ (con degradación) → `scope::support`
+
+En caso de ambigüedad, se asigna el nivel más alto (configuration < support < core).
+
+## Consecuencias
+
+### Positivas
+
+- **Clasificación explícita y documentada**: cualquier desarrollador puede clasificar nuevos casos de uso consistentemente usando los criterios definidos
+- **Priorización objetiva**: la taxonomía permite decidir qué implementar primero (core antes que support, support antes que configuration)
+- **Generación de vistas**: herramientas de reporting pueden filtrar por scope para generar vistas enfocadas ("mostrar solo casos de uso core", "mostrar solo casos de uso de configuración")
+- **Aliado con el lenguaje ubicuo**: los niveles de criticidad reflejan cómo el domain expert piensa sobre las operaciones del sistema
+
+### Negativas
+
+- **Subjetividad en los bordes**: la clasificación `scope::*` puede ser ambigua en casos límite; requiere revisión del domain expert y aplicación de la regla de desempate (asignar el nivel más alto)
+
+### Neutrales
+
+- El prefijo `scope::` se eligió para evitar colisiones con otros tags que puedan agregarse en el futuro

package/docs/adr/foundational/A-010-propiedad-emision-eventos-dominio.md

@@ -0,0 +1,95 @@
+# A-010: Propiedad de la emisión de eventos de dominio
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-12
+
+**originally**: cortex-037
+
+**Enriquecido desde**: Cortex ADR 037 — Driver-owned event emission
+
+**tags**: arquitectura, eventos
+
+## Contexto
+
+Un caso de uso que cambia el estado del dominio hace dos cosas: persiste el cambio y
+publica los eventos de dominio que lo registran. La pregunta es quién posee cada paso, y
+dos patrones fallan por extremos opuestos:
+
+- **El caso de uso construye el evento**: llama al puerto de repositorio, recibe un evento
+  como valor de retorno — o lo reconstruye a partir del input — y lo publica. El caso de uso
+  termina construyendo hechos sobre una mutación que el agregado ejecutó, sin conocer el
+  estado resultante ni las invariantes.
+- **El driver emite el evento**: el driver de repositorio emite eventos como efecto
+  secundario de la persistencia. Esto acopla el hecho de dominio a la tecnología de
+  persistencia y hace que el puerto asuma emisión de eventos.
+
+La propiedad correcta es la de DDD: el **agregado** emite el evento porque posee la
+transición de estado; el **caso de uso** lo publica porque posee la orquestación; el
+**driver** lo entrega porque posee el mecanismo.
+
+## Decisión
+
+### 1. El agregado emite el hecho
+
+Cuando un método del agregado transiciona estado (p. ej. `crear_entidad`), el agregado
+levanta el evento de dominio correspondiente con la data del estado resultante. El evento
+es un artefacto del dominio: su identificador de agregado y su data nacen del agregado, no
+del input del caso de uso ni del valor de retorno del repositorio.
+
+### 2. El caso de uso publica, no construye
+
+El caso de uso orquesta: carga el agregado, invoca su método (con verbos de intención según
+[A-029](./A-029-verbos-intencion-metodos-lado-negocio.md)), lo persiste a través del puerto de
+repositorio y publica los eventos que el agregado levantó a través del puerto publicador de
+eventos. El caso de uso no reconstruye eventos a partir del input ni de valores de retorno. En persistencia event-sourced, el caso de uso no publica por separado: el append al EventStore es la publicación (ver §5).
+
+### 3. El driver entrega, no posee el hecho
+
+- El puerto de repositorio persiste estado y retorna agregados o identificadores — nunca
+  eventos. (En persistencia event-sourced, persiste apendando los eventos del agregado; ver §5.)
+- El puerto publicador de eventos declara la publicación; el driver que lo implementa posee
+  el mecanismo de entrega (un bus en memoria para tests, un transporte real en producción).
+  El formato del evento es siempre CloudEvents
+  ([A-015](./A-015-cloudevents-estandar-eventos.md)), independiente del transporte.
+- La atomicidad entre persistir y publicar es una responsabilidad de entrega: se resuelve en
+  el driver del bus, no moviendo el hecho al driver de repositorio. (En persistencia event-sourced, se resuelve dentro del store; ver §5.)
+
+### 4. La publicación es fail-fast
+
+La publicación de eventos es parte de la operación del caso de uso: no hay publicación
+parcial — o la mutación persiste y sus eventos se publican, o la operación falla — conforme a
+[A-007](./A-007-data-contract-fail-fast.md).
+
+### 5. Persistencia event-sourced
+
+Cuando la persistencia es event-sourced — el stream de eventos es la fuente de verdad y el estado se reconstruye por replay — los puntos 2 a 4 se materializan así, sin cambiar la propiedad del hecho (el agregado emite, el driver entrega):
+
+- **El puerto de repositorio apende los eventos.** El append al EventStore es la **publicación durable**: no hay un paso separado de publicación en el caso de uso; el puerto de repositorio persiste el hecho como eventos, no como estado derivado.
+- **La entrega a suscriptores es un outbox o tail del stream**, poseído por el driver del store: proyecciones, integraciones y notificaciones consumen del stream, no de un segundo canal coordinado.
+- **La atomicidad entre persistir y publicar se resuelve dentro del store**: el append es el hecho atómico; la publicación fail-fast (§4) se cumple porque persistir y publicar son la misma escritura.
+- **El stream se firma y verifica.** Los eventos se firman y el EventStore los verifica al apender y al cargar; el snapshot cache (optimización del store) se firma y verifica al cargar, y se reconstruye desde el stream si su firma no valida.
+
+## Consecuencias
+
+### Positivas
+
+- **El hecho vive en el dominio**: el evento nace del agregado con la data del estado
+  resultante; el caso de uso y el driver no reconstruyen hechos ajenos.
+- **Puertos sin filtraciones**: el repositorio retorna agregados, no eventos; el puerto
+  publicador solo declara publicación.
+- **Entrega intercambiable**: cambiar la tecnología de entrega (un bus en memoria, NATS,
+  RabbitMQ o Kafka) toca solo el driver del bus.
+- **Atomicidad localizada**: el driver del bus resuelve la atomicidad entre persistir y
+  publicar; la persistencia de estado no se acopla a la emisión.
+- **Tests simples**: se verifica que el agregado levantó el evento y que el caso de uso lo
+  publicó, no la construcción de eventos desde el input.
+
+### Negativas
+
+- **El agregado debe levantar eventos**: los agregados existentes que solo transicionan
+  estado deben empezar a registrar sus eventos.
+- **Migración**: cada feature con eventos debe ajustarse para publicar los eventos del
+  agregado, aunque pueden migrarse independientemente.
+- **Disciplina de entrega**: resolver la atomicidad entre persistir y publicar es trabajo
+  del driver; sin ello, una caída entre ambos pasos pierde eventos.