@imolko/ultra-agent 0.1.0-beta

package/docs/adr/typescript/T-008-expressive-use-case-pipe.md

@@ -0,0 +1,207 @@
+# T-008: El pipe del caso de uso expresa el proceso con funciones nombradas
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-05-27
+**originally**: imolko
+
+## Contexto
+
+Un caso de uso funcional se escribe como pipeline de composición funcional: en el ecosistema ultra-ddd ([T-010](./T-010-stack-tooling-typescript-dominio.md)), `seedTV(input).pipe(...)` encadena los pasos del proceso. La lógica de validación y ejecución puede escribirse directamente como lambdas inline dentro del pipe:
+
+```typescript
+// ❌ LAMBDAS INLINE: difícil de leer
+const process = seedTV(input).pipe(
+  TV.checkRequirements([
+    TV.fromAsync(async (inp: InputDto): Promise<Validation<...>> => {
+      // 15-20 líneas de validación de warehouse...
+    }),
+    TV.fromAsync(async (inp: InputDto): Promise<Validation<...>> => {
+      // 30-40 líneas de validación de variantes...
+    }),
+    (inp: InputDto): TaskValidation<...> => {
+      // validación de cantidades...
+    },
+    (inp: InputDto): TaskValidation<...> => {
+      // validación de documentos...
+    },
+  ]),
+  TV.chain((results) => {
+    // combinación de resultados...
+  }),
+  TE.executeSequentially([
+    (ctx: PipelineContext): TaskExecution<...> => {
+      return () => this.executeCoreAsync(ctx);
+    },
+  ]),
+  TE.when({ isOk: handleSuccess, isFail: handleFailure }),
+  TE.map(returnVoid),
+);
+```
+
+Este estilo tiene dos problemas:
+
+1. **El significado del proceso queda enterrado**: para entender qué hace el pipe, hay que leer el cuerpo de cada función inline. Las lambdas no comunican intención.
+2. **El pipe ocupa 60-80 líneas**: la mezcla de lógica de negocio con la estructura del pipeline hace que el `execute()` sea difícil de navegar y revisar.
+
+El objetivo de `seedTV(input).pipe(...)` es declarar el proceso de negocio de forma legible, siguiendo el estilo de composición funcional de [A-044](../foundational/A-044-composicion-funcional-procesos-operaciones.md). Las lambdas inline derrotan ese propósito.
+
+## Decisión
+
+Cada paso del pipe debe extraerse a una **función nombrada con un nombre semántico** que describa qué hace ese paso en el proceso de negocio. La función se declara como `const` dentro de `execute()`, antes del pipe.
+
+### Reglas
+
+| Regla | Descripción |
+|-------|-------------|
+| **Una función por paso del proceso** | Cada validador, transformación, y ejecución va en su propia función nombrada |
+| **Nombre semántico** | El nombre describe **qué hace el paso en el proceso de negocio**, no cómo lo hace. Ej: `verifyWarehouseExists`, no `checkWarehouseId` |
+| **Idioma inglés** | Los nombres de funciones van en inglés, consistente con el resto del código del ecosistema |
+| **JSDoc descriptivo** | Cada función nombrada lleva un JSDoc de una línea explicando su rol en el proceso (extiende el JSDoc de [T-002](./T-002-test-documentation-jsdoc.md) a las funciones del pipe, en formato simplificado sin tags) |
+| **El pipe es solo estructura** | El pipe contiene únicamente referencias a las funciones nombradas — sin lambdas, sin cuerpos de función |
+| **Declarar antes del pipe** | Las funciones se declaran como `const` al inicio del `execute()`, antes del `const process = seedTV(...).pipe(...)` |
+| **Validación vs ejecución** | Los pasos que solo leen y deciden son `TaskValidation` (`TV.*`); los que cambian estado son `TaskExecution` (`TE.*`). `TE.startExecutions()` es la única frontera entre ambas fases. |
+| **El puerto fija la fase** | Un método de puerto de dominio que lee o verifica se declara `TaskValidation`/`Validation`; uno que muta, `TaskExecution`/`Execution` ([A-025](../foundational/A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md)). El compilador impide ejecutar una lectura como mutación. |
+
+### Ejemplo canónico
+
+```typescript
+public execute(input: InputDto): TaskExecution<Errors, void> {
+  /** Lo que sucede cuando el proceso completa exitosamente */
+  const handleSuccess = () => {
+    this.setResult(ok(undefined));
+  };
+  /** Lo que sucede cuando el proceso falla en cualquier etapa */
+  const handleFailure = (errors: Errors[]) => {
+    this.setResult(fail(errors));
+  };
+  /** Convierte el resultado del pipe a void para cumplir el contrato */
+  const returnVoid = (): void => undefined;
+
+  /** Verifica que el warehouse existe en el sistema */
+  const verifyWarehouseExists = TV.fromAsync(async (input: InputDto) => {
+    // lógica de validación...
+  });
+
+  /** Verifica que todas las variantes de producto y sus productos padre existen */
+  const verifyProductVariantsExist = TV.fromAsync(async (input: InputDto) => {
+    // lógica de validación...
+  });
+
+  /** Verifica que todas las cantidades sean mayores a cero */
+  const verifyQuantitiesPositive = (input: InputDto): TaskValidation<...> => {
+    // lógica de validación...
+  };
+
+  /** Verifica que los documentos adjuntos tengan datos válidos */
+  const verifyDocumentsValid = (input: InputDto): TaskValidation<...> => {
+    // lógica de validación...
+  };
+
+  /** Combina los resultados individuales de validación en un solo contexto */
+  const combineValidationResults = (results: any[]) => {
+    // lógica de combinación...
+  };
+
+  /** Ejecuta el core: resuelve lotes, construye StockMovement, persiste */
+  const executeRegistration = (ctx: PipelineContext): TaskExecution<...> => {
+    return () => this.executeCoreAsync(ctx);
+  };
+
+  // ── El pipe declara el proceso, no lo implementa ──
+  const process = seedTV(input).pipe(
+    TV.checkRequirements([
+      verifyWarehouseExists,
+      verifyProductVariantsExist,
+      verifyQuantitiesPositive,
+      verifyDocumentsValid,
+    ]),
+    TV.chain(combineValidationResults),
+    TE.startExecutions(),
+    TE.executeSequentially([executeRegistration]),
+    TE.when({ isOk: handleSuccess, isFail: handleFailure }),
+    TE.map(returnVoid),
+  );
+
+  return process as TaskExecution<Errors, void>;
+}
+```
+
+### Validación antes que ejecución: la frontera del pipe
+
+`seedTV(input).pipe(...)` tiene dos fases separadas por una única frontera:
+
+- **Validación** (`TV.*`) — lee y decide; no toca estado. Ejemplos: `verifyWarehouseExists`, `verifyQuantitiesPositive`, `verifyNoOpenClaimExists`. Retornan `TaskValidation` con `valid(ctx)`/`invalid([...])`.
+- **Frontera** — `TE.startExecutions()` convierte la `TaskValidation` en `TaskExecution`. No hay otra transición entre fases.
+- **Ejecución** (`TE.*`) — cambia estado: persiste, publica eventos, muta el contexto. Retornan `TaskExecution` con `ok(...)`/`fail([...])`.
+
+La fase no la decide quien escribe el caso de uso: la decide el **tipo del puerto** ([A-025](../foundational/A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md)). Una verificación de solo lectura tipada como `TaskExecution` arrastra la lectura a la fase de ejecución; tipada como `TaskValidation`, el compilador impide colocarla en `TE.executeSequentially` y solo permite componerla en la fase de validación.
+
+❌ Incorrecto — la lectura se declara como ejecución:
+
+```typescript
+// claim-repository.port.ts
+verifyNoOpenClaim(referenceId: string): TaskExecution<Errors, void>;
+
+// use-case.ts — la verificación queda en la fase de ejecución
+TE.executeSequentially([this.verifyNoOpenClaimExists]),
+```
+
+✅ Correcto — el puerto declara la lectura como validación:
+
+```typescript
+// claim-repository.port.ts
+verifyNoOpenClaim(referenceId: string): TaskValidation<Errors, void>;
+
+// use-case.ts — la verificación compone en la fase de validación
+TV.chain(this.verifyNoOpenClaimExists),
+```
+
+Convención de refuerzo: los nombres `verify*` corresponden a `TaskValidation` (fase `TV`) y `execute*` a `TaskExecution` (fase `TE`).
+
+La semántica de flujo del valor a través del pipe — `chain` produce, `sequence` acumula, y el contexto se retorna en lugar de mutarse — la fija [T-021](./T-021-pipe-flujo-datos-operadores-semantica-contexto-inmutable.md).
+
+Qué cuenta como validación (lectura/verificación) frente a ejecución (creación/mutación) — en particular, que la construcción de objetos es ejecución y que `TE.startExecutions()` es la única frontera — lo fija [T-022](./T-022-construction-is-execution-single-boundary.md).
+
+### Lo que se lee en el pipe
+
+El pipe ahora comunica el proceso de negocio de un vistazo:
+
+1. **Verificar** que el warehouse existe
+2. **Verificar** que las variantes de producto existen  
+3. **Verificar** que las cantidades son válidas
+4. **Verificar** que los documentos son válidos
+5. **Combinar** los resultados de validación
+6. **Ejecutar** el registro
+7. **Manejar** éxito o fallo
+
+Un experto del dominio puede leer solo el pipe y entender el flujo completo sin ver una sola línea de implementación. Las funciones nombradas también hacen explícito dónde ocurre la resolución de opcionalidad que fija [T-005](./T-005-input-optionality-use-case-not-entity.md).
+
+### Criterios para extraer una función
+
+Una lambda dentro del pipe debe extraerse a función nombrada si:
+
+- Tiene **más de 3 líneas** de lógica
+- Representa un **paso del proceso de negocio** con identidad propia (ej: "validar warehouse" vs "parsear un campo")
+- Su lógica podría **reutilizarse** o **testearse de forma aislada**
+
+No es necesario extraer:
+
+- Funciones puramente técnicas como `returnVoid` o `handleSuccess` (ya tienen nombre)
+- Lambdas de una línea que son adaptadores de tipo triviales
+
+## Consecuencias
+
+### Positivas
+
+- **Legibilidad**: cualquier persona (desarrollador, experto del dominio, agente de código) puede leer el pipe y entender el proceso en segundos
+- **Navegabilidad**: el pipe tiene ~15 líneas de estructura. La implementación de cada paso está en su función correspondiente, que se puede colapsar en el editor
+- **Modificabilidad**: agregar un paso nuevo (ej: una validación adicional) es tan simple como declarar una función nueva y agregar su referencia al array correspondiente — el pipe no se desordena
+- **Testabilidad**: las funciones de validación pueden extraerse a métodos privados de la clase si se necesita testeo aislado
+- **Documentación viva**: el pipe es documentación ejecutable. Hace innecesarios los comentarios `// Fase 1: Validaciones` porque las funciones mismas documentan el paso
+
+### Negativas
+
+- **Paso manual post-generación**: después de ejecutar `add-feature`, el desarrollador o agente debe refactorizar las lambdas inline a funciones nombradas. Se mitiga con el `.instructions.md` post-generación, que ultra-generator deja como instrucción para el agente o desarrollador ([T-003](./T-003-readme-formatting-domain-artifacts.md)), y con un futuro cambio en ultra-generator
+- **Mayor número de líneas en `execute()`**: las declaraciones de funciones antes del pipe agregan líneas. En la práctica es beneficioso porque cada función encapsula su complejidad — el método `execute()` se vuelve más largo pero más navegable
+- **Nombres en inglés**: el dominio y los README están en español, pero las funciones del pipe van en inglés para consistencia con el resto del código del ecosistema. Esto crea una mezcla de idiomas en el mismo archivo (JSDoc en español, nombres de función en inglés)

package/docs/adr/typescript/T-009-mdx-brace-escaping.md

@@ -0,0 +1,80 @@
+# T-009: Escape de llaves en contenido generado para MDX/Docusaurus
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-06-03
+**originally**: imolko
+
+## Contexto
+
+`ultra-reporter build` (herramienta canónica de documentación: [T-011](./T-011-ultra-reporter-herramienta-canonica-documentacion.md)) genera archivos `.md` a partir del JSDoc de los tests (cuya documentación fija [T-002](./T-002-test-documentation-jsdoc.md)), del JSDoc de propiedades y de los `README.md` de artefactos. Esos archivos se procesan con Docusaurus y soporte MDX, que interpreta `{...}` como expresiones JSX ([MDX: Interpolation](https://mdxjs.com/docs/what-is-mdx/#interpolation)).
+
+El JSDoc y los `README.md` pueden contener llaves o ángulos literales — tipos como `{ value: string }` o `Array<{name, value}>` — que, al quedar en texto plano (fuera de code fences) del markdown generado, MDX interpreta como expresiones JSX o tags, y hacen fallar el build con errores de `acorn` o `unexpected character` ([micromark-extension-mdx-expression](https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#could-not-parse-expression-with-acorn)).
+
+## Decisión
+
+### Regla
+
+Toda llave literal (`{` o `}`) o ángulo (`<` o `>`) que aparezca en contenido que `ultra-reporter` incluye en el markdown generado **debe evitarse** usando HTML entities o texto descriptivo.
+
+- `{` → `&#123;`
+- `}` → `&#125;`
+- `<` → `&#60;` (cuando aparece junto a texto que podría interpretarse como tag JSX)
+- `>` → `&#62;`
+
+### Dónde aplica
+
+La regla cubre todo contenido que `ultra-reporter` incluye en el markdown generado. Ejemplos concretos:
+
+| Fuente | Ejemplo de problema | Corrección |
+|--------|---------------------|------------|
+| `@scenario` en JSDoc de tests | `retorna { value: string }` | `retorna &#123; value: string &#125;` |
+| `@description` en JSDoc de propiedades | `el valor debe ser { ... }` | `el valor debe ser &#123; ... &#125;` |
+| `README.md` — tablas, párrafos | `Array<{name, value}>` | `Array&#60;&#123;name, value&#125;&#62;` o texto descriptivo: `object (name, value)` |
+| `README.md` — texto fuera de code fences | `el payload es { id: string }` | `el payload es &#123; id: string &#125;` |
+
+> ⚠️ No se acepta el escape con backslash (`\{`). Aunque funciona en texto simple, falla en tablas
+> y en contextos donde MDX interpreta patrones como JSX. Usar siempre HTML entities.
+
+### Dónde NO aplica (seguro sin escapar)
+
+| Contexto | Razón |
+|----------|-------|
+| Dentro de ` ```mermaid ` blocks | MDX no procesa el contenido de code fences |
+| Dentro de ` ```typescript ` / ` ``` ` blocks | Misma razón |
+| Código TypeScript fuera de JSDoc | No llega al markdown generado |
+| `@property {Type}` en JSDoc de props.ts | ultra-reporter no incluye anotaciones `@property` en el markdown generado |
+
+### Verificación local
+
+Antes de pushear, ejecutar el build de documentación localmente para detectar errores MDX:
+
+```bash
+npm run docs:build
+```
+
+Si el build falla con errores de `acorn` o `unexpected-character`, revisar los archivos generados en `.ultra-reporter/docusaurus/docs/` para localizar el texto problemático.
+
+### Alternativas consideradas
+
+| Opción | Evaluación |
+|--------|------------|
+| Desactivar MDX en Docusaurus | ultra-reporter usa MDX por defecto. Cambiar la configuración requeriría modificar el scaffold y perdería funcionalidad (componentes React en docs). |
+| Post-procesar los .md generados | Agregar un paso de escape en el pipeline añade complejidad. Es mejor prevenir en la fuente. |
+| Usar HTML entities (`&#123;`) | **Opción elegida.** Es la forma más robusta: funciona en cualquier contexto MDX (texto, tablas, atributos HTML). La contraparte es menor legibilidad en el source. |
+| Evitar caracteres especiales | **Opción preferida cuando es posible.** En lugar de `Array<{name, value}>` escribir `object (name, value)`. Más limpio y legible que las entities. |
+| Escapar con backslash (`\{`) | **No funciona en todos los contextos.** MDX interpreta `\{` correctamente en texto simple, pero falla dentro de tablas o cerca de patrones que MDX interpreta como JSX (`Array<...>`). El backslash mismo puede ser rechazado como "unexpected character". |
+
+## Consecuencias
+
+### Positivas
+
+- **Build de documentación estable**: los errores MDX se detectan y corrigen en la fuente
+- **Regla simple**: `{` y `}` → `&#123;` y `&#125;` en JSDoc y README.md fuera de code fences
+- **Verificable localmente**: `npm run docs:build` atrapa el error antes del CI
+
+### Negativas
+
+- **Sin lint automático**: no hay un linter que detecte llaves sin escapar en JSDoc o README.md. La verificación es manual o mediante build local
+- **Carga cognitiva**: los colaboradores deben recordar esta regla al escribir JSDoc y README.md
+- **Regeneración**: si `ultra-generator` (herramienta canónica: [T-019](./T-019-ultra-generator-herramienta-canonica-generacion.md)) regenera un README.md, las correcciones de escape se pierden y deben re-aplicarse (la reconciliación del scaffold la fija [T-003](./T-003-readme-formatting-domain-artifacts.md))

package/docs/adr/typescript/T-010-stack-tooling-typescript-dominio.md

@@ -0,0 +1,53 @@
+# T-010: Stack de tooling TypeScript del dominio (ultra-ddd, ultra-v8n, ultra-result, ultra-tsconfig)
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-12
+
+**originally**: imolko
+
+## Contexto
+
+Un dominio escrito en TypeScript que sigue convenciones DDD repite las mismas responsabilidades en cada artefacto: value-objects, entidades, agregados, validación semántica con errores tipados y manejo de resultados sin excepciones. Sin un stack declarado:
+
+- Cada workspace podría elegir librerías o versiones distintas para resolver el mismo problema.
+- Un agente o un miembro nuevo no sabe qué librería usar para modelar un agregado, validar un value-object o retornar un error.
+- La configuración estricta del compilador se duplicaría en cada `tsconfig.json` con riesgo de divergencia.
+
+Las librerías del ecosistema `@imolko` ya cubren esas responsabilidades y están optimizadas para trabajar juntas. Falta explicitar que forman el stack canónico del dominio.
+
+## Decisión
+
+Adoptar un stack fijo de tooling TypeScript del ecosistema `@imolko` para el dominio, compuesto por **ultra-ddd**, **ultra-v8n**, **ultra-result** y **ultra-tsconfig**. Cada librería cubre una responsabilidad del desarrollo DDD y no se sustituye por una alternativa ad-hoc:
+
+- **ultra-ddd** provee los artefactos DDD (value-objects, entidades, agregados, eventos de dominio y errores base) que consumen el dominio y los casos de uso.
+- **ultra-v8n** aporta la validación semántica con errores tipados (las invariantes se aplican en la construcción, ver [A-007](../foundational/A-007-data-contract-fail-fast.md)); sus errores built-in son los que usan las primitivas Zod (ver [T-001](./T-001-ddd-artifact-validation-zod-primitives.md)).
+- **ultra-result** provee el patrón Result para manejar errores sin excepciones (ver [A-005](../foundational/A-005-either-return-custom-methods.md)), tanto en operaciones síncronas como asíncronas.
+- **ultra-tsconfig** provee la base de configuración estricta de TypeScript que extienden los `tsconfig.json` del repositorio.
+
+La lista concreta de dependencias y sus versiones no se duplica en este ADR: la fuente canónica son los `package.json` del repositorio (raíz y workspaces), que declaran las dependencias `@imolko/*`. Este ADR fija *qué* librerías forman el stack y *por qué*; el `package.json` fija *cuál versión* está en uso.
+
+### Import de Zod y tree-shaking
+
+Si el build usa `tsc --build` sin bundler, en runtime Node.js carga el módulo completo y la forma de importar Zod no cambia el tamaño del código compilado; por eso, en ese escenario, el código usa `import { z } from 'zod'` (o `import { z } from '@imolko/ultra-v8n'` en la capa de dominio).
+
+Si el código pasa a bundlearse con esbuild, Webpack o Next.js, la forma sí importa: `import { z } from 'zod'` no es tree-shakable en esos bundlers, mientras que `import * as z from 'zod'` sí lo es (ver [zod#4569](https://github.com/colinhacks/zod/pull/4569)). En ese escenario, la convención debe pasar a `import * as z`.
+
+### Alcance del stack
+
+El stack describe el tooling del **dominio** y de los casos de uso que operan sobre él. El generador de artefactos (ultra-generator, ver [T-019](./T-019-ultra-generator-herramienta-canonica-generacion.md)), el reportero de documentación (ultra-reporter, ver [T-011](./T-011-ultra-reporter-herramienta-canonica-documentacion.md)) y el exportador de artefactos de despliegue (ultra-settings, ver [T-020](./T-020-ultra-settings-herramienta-canonica-exportacion-despliegue.md)) son piezas separadas del ecosistema, con responsabilidades propias (scaffolding, documentación y exportación de configuración), y no se consideran parte del stack del dominio aunque convivan en el mismo monorepo.
+
+## Consecuencias
+
+### Positivas
+
+- **Consistencia entre workspaces**: dominio, features y apps usan las mismas librerías con los mismos patrones.
+- **Configuración estricta compartida**: extender `ultra-tsconfig` evita duplicar la política de compilación en cada workspace.
+- **Descubribilidad**: un agente o un miembro nuevo sabe qué librería corresponde a cada responsabilidad DDD.
+- **Una sola fuente de versiones**: el `package.json` responde "¿qué versión está en uso?" sin que el ADR quede desactualizado al actualizar dependencias.
+
+### Negativas
+
+- **Acoplamiento al ecosistema `@imolko`**: migrar fuera de las librerías del stack implica tocar los artefactos del dominio, no solo un `package.json`.
+- **Límite del ADR**: este documento no lista versiones; quien lea debe consultar `package.json` para conocer el estado exacto de las dependencias.
+- **Stack cerrado**: introducir una librería nueva para una responsabilidad ya cubierta es una decisión que debe revisarse contra este ADR.

package/docs/adr/typescript/T-011-ultra-reporter-herramienta-canonica-documentacion.md

@@ -0,0 +1,52 @@
+# T-011: ultra-reporter como herramienta canónica de documentación
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-12
+
+**originally**: imolko
+
+## Contexto
+
+Un repositorio TypeScript del ecosistema Imolko produce documentación de dos familias de artefactos: los artefactos del dominio (value-objects, entidades, agregados, eventos de dominio y servicios) y los casos de uso (commands y queries). Esa documentación sirve a dos audiencias distintas:
+
+- Expertos del dominio, que validan reglas de negocio y escenarios sin leer código.
+- Desarrolladores y agentes, que necesitan descubrir qué existe cada artefacto y cómo se comporta.
+
+Sin una herramienta canónica, cada artefacto documenta con su propio formato, los tests no se traducen en casos legibles y no hay un sitio navegable que reúna todo. ultra-reporter ya resuelve ese problema: escanea el código fuente, compone la documentación de cada artefacto desde su `README.md` y sus tests, y publica un sitio Docusaurus.
+
+## Decisión
+
+Adoptar **ultra-reporter** como la herramienta canónica de documentación del repositorio. Toda la documentación generada de dominio y de casos de uso sale de ultra-reporter; no se mantiene un generador alternativo ni páginas escritas a mano que dupliquen lo que la herramienta ya produce.
+
+La configuración canónica vive en `ultra-reporter.config.json` (raíz del repositorio): define el nombre del sistema, las rutas de origen del dominio y de los casos de uso, y el destino de la documentación. Los comandos del flujo diario viven en los scripts de `package.json`; no se duplican aquí.
+
+### Convenciones que alimentan a ultra-reporter
+
+ultra-reporter no impone el contenido: documenta lo que el equipo ya declara siguiendo tres convenciones. Estas son las entradas del pipeline:
+
+- [T-002](./T-002-test-documentation-jsdoc.md): las anotaciones JSDoc `@name` y `@scenario` de cada test, junto con el resultado de los tests en formato CTRF ([A-022](../foundational/A-022-formato-reporte-tests-ctrf.md)), son las que ultra-reporter convierte en casos documentados.
+- [A-032](../foundational/A-032-domain-artifact-documentation-format.md): el formato canónico del `README.md` (sin título H1, secciones en español, diagrama Mermaid en Relaciones) es el cuerpo que ultra-reporter concatena. [T-003](./T-003-readme-formatting-domain-artifacts.md) fija la reconciliación del scaffold de `ultra-generator` con ese formato, y [T-018](./T-018-procedencia-campos-frontmatter.md) la procedencia de los campos del frontmatter.
+- La declaración del Bounded Context: ultra-reporter lee el campo `boundedContext` del frontmatter del `README.md` de cada artefacto para agruparlo en la columna "Context"; si falta, usa `domain.name` de `ultra-reporter.config.json` (procedencia de los campos: [T-018](./T-018-procedencia-campos-frontmatter.md)). El campo `domain` de los decoradores `@Register*` es el namespace del registro de ultra-ddd, no el criterio de agrupado. La descomposición en Bounded Contexts es una decisión fundacional (ver [A-008](../foundational/A-008-bounded-context-decomposition.md)); los nombres concretos de cada contexto los define el sistema, no esta convención.
+
+### Enmienda (2026-09-28): el registro de ultra-ddd no es una entrada del pipeline
+
+La evaluación posterior contra las fuentes primarias verificó el mecanismo y precisa —sin cambiar— esta decisión:
+
+- ultra-reporter descubre los dos catálogos **escaneando carpetas**: el dominio con `track-artifacts.js` (`getArtifacts`) y los casos de uso con `loadUseCaseFolders`. Compone cada página desde el `README.md` y los tests; no lee `DomainDirectory` ni los metadatos de `@Register*`. La `description` del decorador es **origen de autoría** del campo homónimo del frontmatter ([T-018](./T-018-procedencia-campos-frontmatter.md)), no una entrada del pipeline.
+- **No se añade un `@RegisterUseCase` ni un registro de casos de uso al pipeline.** El catálogo documentado sale del escaneo de carpetas; el catálogo ejecutable vive en el manifiesto de la app ([T-023](./T-023-registry-cli-declara-dependencias-reales.md)); el registro de ultra-ddd no tiene consumidor en documentación.
+
+## Consecuencias
+
+### Positivas
+
+- **Un solo sitio navegable**: dominio y casos de uso conviven en el mismo sitio Docusaurus, con tablas, filtros y páginas por artefacto.
+- **Documentación viva**: cada test bien anotado se convierte en un caso documentado; no hay dos fuentes de verdad que divergen.
+- **Descubribilidad para agentes y personas nuevas**: la documentación se genera desde el código, así que refleja lo que realmente existe.
+- **Configuración explícita**: `ultra-reporter.config.json` y los scripts de `package.json` son las fuentes canónicas del flujo, sin pasos memorizados.
+
+### Negativas
+
+- **Dependencia de las convenciones**: si un test no sigue T-002 o un README no sigue T-003, la página generada queda incompleta; ultra-reporter no lo valida por sí solo.
+- **Generado no versionado**: el sitio generado vive fuera de git; lo que se versiona es la configuración y las fuentes, no el sitio.
+- **Curva de aprendizaje**: el equipo debe conocer el modelo de descubrimiento de ultra-ddd y el formato de frontmatter para que el resultado sea correcto.

package/docs/adr/typescript/T-012-npm-workspaces-estructura-monorepo-clean-architecture.md

@@ -0,0 +1,54 @@
+# T-012: npm workspaces como estructura del monorepo Clean Architecture
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-12
+
+**originally**: imolko
+
+## Contexto
+
+Un repositorio TypeScript del ecosistema Imolko sigue Clean Architecture con 4 capas (ver [A-001](../foundational/A-001-clean-architecture-4-capas.md)): dominio, features, shared-infra y apps. Esas capas conviven en un único repositorio y necesitan:
+
+- Límites de compilación y de dependencias explícitos entre capas.
+- Tests y build independientes por capa sin reconstruir todo el monorepo.
+- Resolución local de las dependencias internas (`@<proyecto>/*`) durante el desarrollo, sin publicarlas a un registry antes de usarlas.
+
+Sin una herramienta de workspaces, el monorepo tendría que resolver dependencias entre carpetas con rutas relativas frágiles o publicar paquetes internos como paso previo a consumirlos.
+
+## Decisión
+
+Usar **npm workspaces** como mecanismo de estructuración del monorepo. Cada capa de [A-001](../foundational/A-001-clean-architecture-4-capas.md) que constituye una unidad consumible o desplegable es un workspace: un paquete npm con su propio `package.json`, `tsconfig.json` y tests.
+
+### Correspondencia capa → workspace
+
+- **Capa 1 — dominio** corresponde al workspace `domain/`: lo consumen features y apps.
+- **Capa 2 — casos de uso** corresponde al workspace `features/` — o a un workspace por feature cuando su cierre tecnológico lo exige ([A-024](../foundational/A-024-features-slices-verticales-portables.md)): lo consumen las apps.
+- **Capa 4 — apps** corresponde a `apps/<app>/`: una unidad desplegable por workspace.
+
+`shared-infra/` (Capa 3 — la infraestructura compartida de [A-026](../foundational/A-026-infraestructura-compartida.md)) es un directorio de agrupación lógica: cada tecnología (`shared-infra/mongo/`, `shared-infra/postgres/`, …) es su propio workspace, con su `package.json` declarando solo las dependencias de esa tecnología.
+
+`representations/<protocol>/` (las representaciones de dominio de [A-026](../foundational/A-026-infraestructura-compartida.md)) es igualmente un workspace por protocolo, junto a `shared-infra/`; toda forma de wire que representa un concepto del dominio vive ahí, tenga uno o varios consumidores — los payloads de operación (input/result/filter) viven con su entrypoint.
+
+La lista exacta de workspaces vive en el campo `workspaces` del `package.json` raíz, que es la fuente canónica. Este ADR no la duplica: la lista anterior es la *regla de correspondencia* entre capas y workspaces, no una copia de la lista.
+
+### Reglas
+
+- Cada workspace declara sus dependencias internas (`@<proyecto>/*`) en su propio `package.json`; npm resuelve las referencias locales mediante el hoisting del monorepo.
+- Un workspace no importa de otro saltándose la dirección de dependencias de [A-001](../foundational/A-001-clean-architecture-4-capas.md) (las dependencias siempre apuntan hacia adentro).
+- El build y los tests se ejecutan por workspace (por ejemplo, `npm run build -w @<proyecto>/domain`) sin arrastrar el monorepo completo.
+
+## Consecuencias
+
+### Positivas
+
+- **Límites de compilación alineados con la arquitectura**: cada capa compila y se testea de forma independiente.
+- **Sin herramientas extra**: npm workspaces es nativo de npm, sin Nx, Turborepo ni Lerna.
+- **Resolución local**: las dependencias internas se consumen directamente desde el monorepo sin publicaciones intermedias.
+- **Descubribilidad**: el campo `workspaces` del `package.json` raíz responde "¿qué capas son paquetes?" sin mantener una copia manual.
+
+### Negativas
+
+- **Hoisting de npm**: la resolución de dependencias puede ocultar importaciones indebidas entre workspaces; la disciplina de la dirección de dependencias sigue siendo responsabilidad del equipo.
+- **Configuración repetida**: cada workspace mantiene su propio `package.json` y `tsconfig.json`, con la duplicación de setup que eso implica (mitigada por `ultra-tsconfig`, [T-010](./T-010-stack-tooling-typescript-dominio.md)).
+- **`shared-infra/` por tecnología**: cada paquete `shared-infra/<tech>/` compila y se testea como workspace propio; no hay un workspace único que agrupe toda la capa.

package/docs/adr/typescript/T-013-definicion-eventos-versionados-ultra-ddd.md

@@ -0,0 +1,45 @@
+# T-013: Definición de eventos versionados con ultra-ddd
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-12
+
+**originally**: imolko
+
+## Contexto
+
+[A-015](../foundational/A-015-cloudevents-estandar-eventos.md) fija CloudEvents como envolvente de todo evento y la disciplina de versionado de la data: semver, historial append-only y compatibilidad hacia atrás dentro de una misma versión mayor. Esa decisión es agnóstica al lenguaje: dice *qué* reglas debe cumplir la data, no *cómo* se implementa.
+
+En TypeScript hace falta el mecanismo concreto que declare, para cada evento de dominio, el esquema versionado de su data y lo valide al producir y leer ocurrencias. ultra-ddd, la librería del stack ([T-010](./T-010-stack-tooling-typescript-dominio.md)), provee ese mecanismo: `ShapeEvolution`.
+
+## Decisión
+
+Definir la data de cada evento de dominio con **ultra-ddd y su `ShapeEvolution`**: cada evento declara una historia versionada de esquemas (Zod) que versiona el campo `data` de la ocurrencia, en línea con las reglas de [A-015](../foundational/A-015-cloudevents-estandar-eventos.md).
+
+### Forma del evento
+
+Cada evento declara, junto a su definición, una historia versionada de esquemas para su `data`: el esquema inicial, los esquemas de cada versión posterior y el esquema vigente que tipa la data al producir y leer ocurrencias. La lista concreta de eventos del repositorio vive en el dominio; este ADR no la duplica.
+
+### Reglas de versionado
+
+La historia de esquemas sigue las reglas de versionado de [A-015](../foundational/A-015-cloudevents-estandar-eventos.md). ultra-ddd las hace cumplir al declarar la historia: cada versión posterior declara su esquema y su migración desde la anterior, y la herramienta rechaza una historia que las viole.
+
+### Correspondencia con CloudEvents
+
+La historia de esquemas se integra con la envolvente CloudEvents de [A-015](../foundational/A-015-cloudevents-estandar-eventos.md):
+
+- La ocurrencia lleva la versión en el campo de versión dentro de la data que A-015 permite, junto con la `data` validada contra el esquema de esa versión.
+- Al producir, la data se valida contra el esquema vigente; al leer, la ocurrencia se reconstruye desde un CloudEvent serializado.
+- Los esquemas versionados quedan expuestos como `dataschema` (la URI versionada que A-015 declara) para publicarlos en un registry de eventos.
+
+## Consecuencias
+
+### Positivas
+
+- **Una sola fuente del esquema**: el esquema versionado es a la vez esquema de validación, tipo TypeScript y documentación.
+- **Validación automática**: la historia de versiones queda validada por la herramienta al declararla, sin revisión manual de semver.
+- **Alineado con A-015**: la implementación TypeScript materializa las reglas agnósticas del estándar sin redefinirlas.
+
+### Negativas
+
+- **Acoplamiento a ultra-ddd**: el mecanismo de versionado es parte del stack de tooling; migrar a otra librería implicaría reescribir las historias de esquemas.

package/docs/adr/typescript/T-014-publicacion-distribucion-librerias-npm-semver.md

@@ -0,0 +1,53 @@
+# T-014: Publicación y distribución de librerías TypeScript con npm y semver
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-12
+
+**originally**: imolko
+
+## Contexto
+
+Imolko produce librerías TypeScript reutilizables (ver [A-017](../foundational/A-017-taxonomia-repositorios-librerias-sistemas.md)) que otros repositorios consumen como dependencias. Para que una librería sea consumible hacen falta tres cosas:
+
+- Un mecanismo de publicación que la haga instalable mediante `npm install`.
+- Un esquema de versionado que comunique compatibilidad entre versiones.
+- Un flujo reproducible que calcule la versión, publique el paquete y etiquete el commit correspondiente.
+
+Sin una política escrita, cada repositorio decide cómo publicar y versionar, lo que produce paquetes sin canal beta, versiones ad-hoc y publicaciones irreproducibles.
+
+## Decisión
+
+Publicar y distribuir las librerías TypeScript con **npm** como mecanismo de publicación y **semver** (`major.minor.patch`) como esquema de versionado.
+
+### npm como mecanismo de publicación
+
+- Los paquetes se publican en el registry público de npm bajo el scope `@imolko`, mediante `npm publish` con acceso público.
+- El scope se configura durante el flujo de release, no en el código de la librería. La autenticación de la publicación (Trusted Publishing con fallback por staging) y su procedencia se deciden en [T-025](./T-025-publicacion-npm-trusted-publishing-procedencia.md).
+
+### semver como esquema de versionado
+
+Los **paquetes** (librerías publicables) se versionan con **SemVer** —no con CalVer, reservado a las imágenes desplegables— y el canal de pre-lanzamiento usa el sufijo `-beta` (ver [A-016](../foundational/A-016-cicd-gitlab-pipeline-raiz-pipelines-modulares.md)); el incremento de versión se deriva de la convención de commits de [A-033](../foundational/A-033-estandar-mensajes-commit.md).
+
+### Flujo de release como fuente canónica
+
+El flujo completo de versionado y publicación está implementado en los scripts de release del repositorio (`domain/scripts/release*.sh`), que son la fuente canónica; este ADR no duplica sus pasos ni la lista de scripts.
+
+### Librerías, sistemas y configuración
+
+La taxonomía de [A-017](../foundational/A-017-taxonomia-repositorios-librerias-sistemas.md) decide qué se publica: las **librerías** se publican y versionan de forma independiente; los **sistemas** y la **configuración** no se publican como paquetes consumibles.
+
+## Consecuencias
+
+### Positivas
+
+- **Instalación estándar**: cualquier consumidor usa `npm install` sin pasos especiales.
+- **Compatibilidad comunicada**: semver expresa el impacto de cada versión en el número de versión.
+- **Canal beta explícito**: el sufijo `-beta` permite pre-lanzamientos sin contaminar la línea estable.
+- **Reproducibilidad**: el flujo vive en scripts versionados, no en la memoria del equipo.
+
+### Negativas
+
+- **Sin automatización de changelog en este ADR**: el changelog no se deriva automáticamente de los commits; depende del flujo que acompañe a cada release.
+- **Punto único de publicación**: la publicación centralizada en npm requiere credenciales gestionadas en el pipeline; un fallo de autenticación bloquea el release.
+- **Versiones de librerías vs. sistema**: los sistemas comparten versión con su monorepo; las librerías publicadas deben mantener su propio ciclo semver, lo que exige disciplina para no desincronizarlas.

package/docs/adr/typescript/T-015-method-placement-definition.md

@@ -0,0 +1,35 @@
+# T-015: `Definition` como único hogar de los métodos de dominio
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-08-29
+
+**originally**: imolko
+
+## Contexto
+
+Los artefactos de dominio que genera ultra-generator ([T-019](./T-019-ultra-generator-herramienta-canonica-generacion.md)) dividen cada value-object, entidad y agregado en dos clases: la clase `Definition` de ultra-ddd ([T-010](./T-010-stack-tooling-typescript-dominio.md)), que contiene la implementación, y la clase fachada pública, que registra el artefacto y expone su API estática. La fachada delega en `Definition` y no posee el estado del artefacto.
+
+Cuando un método de dominio se coloca en la fachada pública, esta deja de ser un registro declarativo, intenta acceder a estado que no posee y duplica una responsabilidad que ya vive en `Definition`. El lugar de los métodos de dominio necesita una regla explícita, distinta de *qué* deben retornar esos métodos ([A-005](../foundational/A-005-either-return-custom-methods.md)).
+
+## Decisión
+
+Todo método de dominio — lógica de negocio, validaciones adicionales, operaciones aritméticas, transformaciones — se implementa exclusivamente en la clase `Definition`. La clase fachada pública contiene únicamente el registro del artefacto y su API estática; **ningún método de instancia**.
+
+Las fábricas estáticas — `create`, `restore`, `of`, `open` — son parte de la **API estática** de la fachada y pueden vivir allí: el mixin de ultra-ddd las provee (`create`, `restore`) o la fachada las declara (`open`). La prohibición alcanza a los métodos de **instancia**: ninguno puede vivir en la fachada.
+
+Este ADR fija *dónde* viven los métodos de dominio; *qué* deben retornar lo fija [A-005](../foundational/A-005-either-return-custom-methods.md).
+
+## Consecuencias
+
+### Positivas
+
+- **Separación clara**: `Definition` = implementación; la fachada = registro + API estática.
+- **Consistencia**: todos los artefactos siguen el mismo patrón, facilitando navegación y mantenimiento.
+- **Acceso al estado**: los métodos viven en la clase que posee las propiedades, con acceso directo y tipado.
+- **Testabilidad**: los tests ejercen los métodos a través de la API pública sin acoplarse a la separación interna de clases.
+
+### Negativas
+
+- **Dependencia circular**: `Definition` y su fachada se importan mutuamente cuando un método referencia la clase pública como tipo de retorno. Es un patrón que requiere conocimiento.
+- **Doble clase**: los desarrolladores nuevos pueden no entender por qué el artefacto está dividido en dos clases.

package/docs/adr/typescript/T-016-contrato-settings-zod.md

@@ -0,0 +1,34 @@
+# T-016: Implementación del contrato de settings con schema Zod
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-09-06
+
+**originally**: imolko
+
+## Contexto
+
+El contrato de settings como única fuente de configuración es una decisión fundacional (ver [A-013](../foundational/A-013-contrato-settings-unica-fuente-configuracion.md)), y la generación de artefactos de despliegue desde ese contrato también lo es (ver [A-014](../foundational/A-014-generacion-artefactos-despliegue-desde-contrato-settings.md)). Ambas son agnósticas a la tecnología de validación ([A-013 §5](../foundational/A-013-contrato-settings-unica-fuente-configuracion.md)); este ADR fija su implementación concreta en el ecosistema TypeScript.
+
+La validación de artefactos DDD con Zod es un eje distinto, tratado en [T-001](./T-001-ddd-artifact-validation-zod-primitives.md); el contrato de settings valida la configuración de la aplicación, no los artefactos de dominio, y por eso se decide por separado.
+
+## Decisión
+
+En TypeScript, el contrato de settings se implementa con un **schema Zod** que actúa como **fuente única de verdad** para todos los settings.
+
+- Cada campo declara sus metadatos de clasificación (tipo, origen, si contiene secretos) — la taxonomía vive en [A-013 §2](../foundational/A-013-contrato-settings-unica-fuente-configuracion.md).
+- La configuración se carga en tiempo de ejecución validando contra el schema Zod, conforme al fail-fast de [A-013 §3](../foundational/A-013-contrato-settings-unica-fuente-configuracion.md).
+
+La exportación de artefactos de despliegue desde el schema es responsabilidad de [A-014](../foundational/A-014-generacion-artefactos-despliegue-desde-contrato-settings.md), no de este ADR: aquí solo se fija que el schema Zod es lo que habilita la clasificación y la validación fail-fast.
+
+## Consecuencias
+
+### Positivas
+
+- **Una sola fuente de verdad en código**: el schema Zod centraliza qué settings existen y cómo se validan, cumpliendo [A-013](../foundational/A-013-contrato-settings-unica-fuente-configuracion.md).
+- **Fail-fast materializado**: el schema Zod hace ejecutable en TypeScript el fail-fast de [A-013 §3](../foundational/A-013-contrato-settings-unica-fuente-configuracion.md).
+
+### Negativas
+
+- **Acoplamiento a Zod**: el patrón es agnóstico ([A-013 §5](../foundational/A-013-contrato-settings-unica-fuente-configuracion.md)), pero la implementación TypeScript queda atada a Zod.
+- **Metadatos declarados a mano**: la clasificación de cada campo (tipo/origen/secreto) se escribe manualmente en el schema; un error ahí deriva artefactos incorrectos en [A-014](../foundational/A-014-generacion-artefactos-despliegue-desde-contrato-settings.md).