@imolko/ultra-agent 0.1.0-beta

package/docs/adr/typescript/T-017-characterization-tests-golden-files.md

@@ -0,0 +1,39 @@
+# T-017: Golden files para characterization tests
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-09-06
+
+**originally**: imolko
+
+## Contexto
+
+Los tests de caracterización capturan el comportamiento actual de código legacy antes de refactorizarlo y producen una salida esperada que debe conservarse en el repositorio. El *cuándo* y *por qué* de esa práctica es una decisión fundacional (ver [A-011](../foundational/A-011-characterization-first-refactoring.md)); el *cómo* guardar la salida esperada en el ecosistema TypeScript necesita una decisión propia.
+
+Las anotaciones JSDoc de [T-002](./T-002-test-documentation-jsdoc.md) documentan *qué* verifica cada test para la documentación generada; *dónde* se guarda la salida esperada de un characterization test es un eje distinto, y por eso se decide por separado.
+
+## Decisión
+
+En TypeScript, la salida esperada de los characterization tests se guarda en **golden files**: archivos de referencia en disco, legibles por humanos, almacenados en `__fixtures__/expected/`.
+
+### Reglas
+
+| Regla | Descripción |
+|-------|-------------|
+| Golden files en disco | La salida esperada vive en `__fixtures__/expected/`, junto al proyecto fixture. El golden file contiene la salida en texto plano; `git diff` muestra exactamente qué cambió. |
+| Comparación normalizada | Cada test lee la salida generada, normaliza el contenido no determinista (rutas, timestamps) y la compara contra el golden file. Si hay diferencias, el test falla: el refactoring cambió el comportamiento. |
+| Regeneración por flag | Los golden files se regeneran con un flag de entorno; el comando concreto vive en los scripts de `package.json`. |
+| Snapshots para funciones puras | Para funciones puras con salidas pequeñas se prefieren los snapshots inline de Jest; los golden files se reservan para salidas complejas (documentación, reportes, archivos). |
+
+## Consecuencias
+
+### Positivas
+
+- **Red de seguridad legible**: los golden files se inspeccionan en cualquier editor y `git diff` muestra exactamente qué cambió.
+- **Regeneración reproducible**: un único flag de entorno regenera todos los golden files, sin scripts adicionales.
+- **Un mecanismo por tipo de salida**: golden files para salidas complejas, snapshots inline para funciones puras.
+
+### Negativas
+
+- **Normalización a mantener**: los patrones no deterministas (rutas, timestamps) deben normalizarse antes de comparar, y la función de normalización crece con cada patrón nuevo.
+- **Golden files grandes**: los archivos generados pueden ser grandes y deben versionarse en el repositorio.

package/docs/adr/typescript/T-018-procedencia-campos-frontmatter.md

@@ -0,0 +1,55 @@
+# T-018: Procedencia de los campos del frontmatter del README
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-09-07
+
+**originally**: imolko
+
+## Contexto
+
+El frontmatter del `README.md` de cada artefacto de dominio y feature sigue el esquema canónico de [A-032](../foundational/A-032-domain-artifact-documentation-format.md). En el ecosistema TypeScript, cada campo tiene una fuente de autoría concreta y un consumidor: ultra-reporter ([T-011](./T-011-ultra-reporter-herramienta-canonica-documentacion.md)) lee `description`, `title`, `boundedContext` y `tags` del frontmatter del `README.md`, y determina el `type` por el archivo marcador del artefacto. Los decoradores `@Register*` alimentan el registro de ultra-ddd (`DomainDirectory`), no el pipeline de documentación.
+
+[T-003](./T-003-readme-formatting-domain-artifacts.md) fija la mecánica de reconciliar el scaffold de `ultra-generator` ([T-019](./T-019-ultra-generator-herramienta-canonica-generacion.md)) con el formato de A-032. La procedencia de cada campo del frontmatter — de qué fuente sale y quién lo consume — es un eje distinto, y es el que cubre este ADR.
+
+## Decisión
+
+Cada campo del frontmatter del `README.md` se deriva de una fuente específica del ecosistema TypeScript.
+
+**Artefactos de dominio:**
+
+| Campo | Fuente |
+|-------|--------|
+| `description` | Decorador del artefacto (`@Register*`) — expandido con detalle del dominio |
+| `domain` | `ultra-reporter.config.json` → `domain.name` (nombre del proyecto) |
+| `boundedContext` | El bounded context donde reside el artefacto ([A-008](../foundational/A-008-bounded-context-decomposition.md)); ultra-reporter lo usa para la columna Context (agrupación y fallback: [T-011](./T-011-ultra-reporter-herramienta-canonica-documentacion.md)) |
+| `type` | El archivo marcador del artefacto: `aggregate.ts` → `aggregate`, `entity.ts` → `entity`, `value-object.ts` → `value-object`, `event.ts` → `domain-event`, `service.ts` → `service`; los enums se detectan por `enum.ts` → `enum` |
+| `tags` | `completed` para artefactos implementados |
+
+**Features (casos de uso):**
+
+| Campo | Fuente |
+|-------|--------|
+| `feature` | Nombre del directorio del feature en kebab-case |
+| `type` | `command` o `query` ([A-002](../foundational/A-002-cqrs-semantico.md)) |
+| `title` | Redactado por el equipo: el título legible del caso de uso |
+| `description` | Redactado por el equipo: la descripción corta del caso de uso |
+| `tags` | `completed` o `pending`, más un `scope::*` (taxonomía de [A-009](../foundational/A-009-use-case-taxonomy.md)) |
+
+### Enmienda (2026-09-28): la identidad del caso de uso no viaja en el artefacto
+
+La evaluación posterior contra las fuentes primarias confirmó que el registro de ultra-ddd (`DomainDirectory`) no tiene consumidores: la documentación descubre features escaneando carpetas ([T-011](./T-011-ultra-reporter-herramienta-canonica-documentacion.md)) y el catálogo ejecutable vive en el manifiesto de la app ([T-023](./T-023-registry-cli-declara-dependencias-reales.md)). La procedencia de los campos del frontmatter no cambia; se precisa así:
+
+- La identidad del caso de uso sigue siendo el **nombre del directorio** en kebab-case (`feature`). No se introduce un `NAME` en el artefacto ni un decorador `@RegisterUseCase`: no tendrían consumidor.
+- El `name` del manifiesto ([T-023](./T-023-registry-cli-declara-dependencias-reales.md)) es una clave de composición, no una fuente del frontmatter.
+
+## Consecuencias
+
+### Positivas
+
+- **Una fuente por campo**: cada campo del frontmatter tiene una procedencia inequívoca, alineada con el esquema de A-032.
+- **Fuente y consumidor separados**: ultra-reporter lee el frontmatter; los decoradores alimentan el registro de ultra-ddd; cada uno con su rol documentado.
+
+### Negativas
+
+- **Campos escritos a mano**: la coherencia entre decorador y frontmatter depende de que el agente los complete correctamente; no hay validación automática que los cruce.

package/docs/adr/typescript/T-019-ultra-generator-herramienta-canonica-generacion.md

@@ -0,0 +1,35 @@
+# T-019: ultra-generator como herramienta canónica de generación de artefactos
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-09-07
+
+**originally**: imolko
+
+## Contexto
+
+El dominio y los casos de uso siguen convenciones estrictas de ultra-ddd: cada artefacto de dominio (los tipos que enumera [A-032](../foundational/A-032-domain-artifact-documentation-format.md)) y cada feature (command o query, [A-002](../foundational/A-002-cqrs-semantico.md)) tiene una anatomía fija de archivos por tipo. Escribir ese scaffold a mano es repetitivo y propenso a divergencias.
+
+`ultra-generator` (paquete `@imolko/ultra-generator` y skill `/skill:ultra-generator`) ya produce ese scaffold compilable y testeable, y trabaja en tándem con ultra-reporter ([T-011](./T-011-ultra-reporter-herramienta-canonica-documentacion.md)), que documenta lo generado. El stack del dominio ([T-010](./T-010-stack-tooling-typescript-dominio.md)) excluye explícitamente al generador como pieza separada. Falta decidir que es la herramienta canónica de scaffolding.
+
+## Decisión
+
+Adoptar **ultra-generator** como la herramienta canónica de generación de artefactos del dominio y de features. Todo scaffold nuevo sale de ultra-generator; no se mantiene un generador alternativo ni se escriben artefactos a mano cuando existe un comando que los genera.
+
+Los subcomandos del generador y qué produce cada uno los define `@imolko/ultra-generator`; este ADR no los transcribe. La invocación y la versión en uso viven en el `package.json` (script `ultra-generator`), la fuente canónica; este ADR no lista versiones. La invocación desde issues sigue [A-038](../foundational/A-038-issues-referencian-skills-nombre.md): el issue nombra el skill, no se invoca el generador implícitamente.
+
+El scaffold es un **punto de partida, no el artefacto final**: después de generar, el agente lo reconcilia con el formato canónico (ver [T-003](./T-003-readme-formatting-domain-artifacts.md)) y completa el frontmatter del `README.md` (ver [T-018](./T-018-procedencia-campos-frontmatter.md)).
+
+## Consecuencias
+
+### Positivas
+
+- **Un solo generador**: todo artefacto y feature nace del mismo scaffold, sin variantes escritas a mano.
+- **Anatomía consistente**: el layout de archivos es uniforme y compatible con ultra-ddd y ultra-reporter.
+- **Descubribilidad**: un agente o miembro nuevo sabe que todo scaffold sale de ultra-generator y que se invoca desde el script `ultra-generator` del `package.json`.
+
+### Negativas
+
+- **Scaffold no canónico**: el `README.md` del scaffold trae secciones en inglés y `Relaciones` en bullet points; requiere el paso de reconciliación de T-003.
+- **Regeneración destructiva**: re-ejecutar ultra-generator puede regenerar `.instructions.md` y sobrescribir ajustes manuales (ver [T-003](./T-003-readme-formatting-domain-artifacts.md) y [T-009](./T-009-mdx-brace-escaping.md)).
+- **Dependencia del ecosistema `@imolko`**: migrar fuera de ultra-generator implica reescribir el flujo de scaffolding.

package/docs/adr/typescript/T-020-ultra-settings-herramienta-canonica-exportacion-despliegue.md

@@ -0,0 +1,36 @@
+# T-020: ultra-settings como herramienta canónica de exportación de artefactos de despliegue
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-09-08
+
+**originally**: imolko
+
+## Contexto
+
+El contrato de settings como única fuente de configuración ([A-013](../foundational/A-013-contrato-settings-unica-fuente-configuracion.md)) declara qué settings existen y cómo se validan, y la generación de artefactos de despliegue desde ese contrato ([A-014](../foundational/A-014-generacion-artefactos-despliegue-desde-contrato-settings.md)) decide que esos artefactos se derivan del contrato en lugar de mantenerse a mano. El patrón es agnóstico a la tecnología de validación ([A-013 §5](../foundational/A-013-contrato-settings-unica-fuente-configuracion.md)); [A-014](../foundational/A-014-generacion-artefactos-despliegue-desde-contrato-settings.md) fija *qué* se exporta y *desde dónde*, pero no *con qué herramienta*.
+
+En TypeScript el contrato ya se materializa como schema Zod ([T-016](./T-016-contrato-settings-zod.md)). Falta la pieza complementaria: el mecanismo que lee ese schema y produce los artefactos de despliegue. Sin una herramienta canónica, cada aplicación escribiría su propio script de exportación y reaparecería el drift entre contrato y artefactos que [A-014](../foundational/A-014-generacion-artefactos-despliegue-desde-contrato-settings.md) evita. `@imolko/ultra-settings` cubre ese hueco: lee el schema Zod del contrato y renderiza los artefactos de despliegue.
+
+La exportación es una responsabilidad distinta de la del stack del dominio ([T-010](./T-010-stack-tooling-typescript-dominio.md)), que cubre el tooling para *escribir* código de dominio; por eso se decide en un ADR propio.
+
+## Decisión
+
+Adoptar **ultra-settings** (`@imolko/ultra-settings`) como la herramienta canónica de exportación de artefactos de despliegue desde el contrato de settings. Toda exportación sale de ultra-settings leyendo el schema Zod del contrato; no se mantienen scripts de exportación ad-hoc por aplicación.
+
+La entrada de ultra-settings es el schema Zod del contrato ([T-016](./T-016-contrato-settings-zod.md)); la clasificación de cada campo, la taxonomía de [A-013 §2](../foundational/A-013-contrato-settings-unica-fuente-configuracion.md), es lo que decide el destino de cada artefacto según [A-014](../foundational/A-014-generacion-artefactos-despliegue-desde-contrato-settings.md). La taxonomía y la lista de artefactos las definen esos dos ADRs; ultra-settings solo las ejecuta en TypeScript.
+
+Los comandos y la versión se declaran en `package.json` (dependencia y scripts), que es la fuente canónica; este ADR no duplica comandos ni versiones.
+
+## Consecuencias
+
+### Positivas
+
+- **Un solo exportador**: todas las aplicaciones derivan sus artefactos del mismo mecanismo, sin scripts por aplicación.
+- **Cero drift entre contrato y artefactos**: un cambio en el schema se propaga re-ejecutando la exportación, materializando en TypeScript la promesa de [A-014](../foundational/A-014-generacion-artefactos-despliegue-desde-contrato-settings.md).
+- **Descubribilidad**: un agente o miembro nuevo sabe con qué herramienta se exporta la configuración.
+
+### Negativas
+
+- **Acoplamiento al ecosistema `@imolko`**: migrar fuera de ultra-settings implica reescribir el flujo de exportación.
+- **Atado al schema Zod**: la exportación solo aplica donde el contrato es un schema Zod ([T-016](./T-016-contrato-settings-zod.md)); el patrón es agnóstico ([A-013 §5](../foundational/A-013-contrato-settings-unica-fuente-configuracion.md)), la herramienta no.

package/docs/adr/typescript/T-021-pipe-flujo-datos-operadores-semantica-contexto-inmutable.md

@@ -0,0 +1,105 @@
+# T-021: El pipe del caso de uso fluye datos: operadores por semántica y contexto inmutable
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-09-16
+**originally**: imolko
+
+## Contexto
+
+El pipe del caso de uso ([T-008](./T-008-expressive-use-case-pipe.md)) encadena pasos que comparten un contexto: la salida de un paso alimenta al siguiente ([A-044](../foundational/A-044-composicion-funcional-procesos-operaciones.md)). Los operadores que unen pasos tienen semánticas de flujo distintas, no evidentes por su nombre:
+
+- `chain` reemplaza el valor del pipe con el resultado del paso.
+- `sequence`/`executeSequentially` ejecuta pasos por sus efectos y devuelve el valor original.
+
+Elegir el operador por cuántas funciones caben — y no por esa semántica — produce tres olores:
+
+1. **Lista de un elemento**: `TE.executeSequentially([paso])` o `TV.checkRequirements([paso])` cuando el paso produce el siguiente valor; `chain` es el operador que coincide.
+2. **Contexto mutado**: el paso asigna al contexto recibido (`ctx.claimId = ...`) y retorna `void`, forzando el pass-through de `sequence` para arrastrar la mutación. El flujo de datos queda escondido detrás de un efecto.
+3. **Operador anidado**: el mapper de un `chain`/`map` invoca otro operador (`chain` que llama a `map`, o viceversa). Esconde un paso del proceso: extráelo a una función nombrada y encadénalo a primer nivel.
+
+Sin regla canónica, el olor reaparece: en `abrir-reclamo` se manifestó dos veces en la misma feature (`combineValidationResults` y `executeSequentially([openClaim])`).
+
+## Decisión
+
+El pipe es **flujo de datos**: cada paso retorna el valor que el siguiente consume. El contexto que fluye no se asigna; se retorna.
+
+| Regla | Descripción |
+|-------|-------------|
+| **Operador por semántica** | `chain` cuando el paso produce el siguiente valor (`TV.chain`/`TE.chain`). `sequence`/`executeSequentially` solo cuando hay más de un paso con efectos que deben conservar el acumulador de entrada. |
+| **Lista de uno es señal** | Una función sola envuelta en `[...]` indica que `chain` es el operador correcto. |
+| **Sin operadores anidados** | El mapper de un `chain`/`map` no invoca otro operador; cada paso es una función nombrada encadenada a primer nivel. |
+| **El paso retorna el siguiente valor** | Un paso devuelve el contexto enriquecido (`ok({ ...ctx, claimId })`); no asigna a su argumento. |
+| **El contexto tipifica la fase** | El tipo del contexto refleja la fase que lo produce (validación vs ejecución), de modo que la frontera `TE.startExecutions()` ([T-008](./T-008-expressive-use-case-pipe.md)) coincide con una frontera de tipos. |
+
+La fase la decide el **tipo del puerto** ([A-025](../foundational/A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md)); la forma de fluir el valor la deciden los **tipos del contexto**. El compilador impide ejecutar una lectura como mutación y leer un campo que la fase anterior no produjo.
+
+❌ Incorrecto — el paso muta y la lista de uno fuerza el pass-through:
+
+```typescript
+// use-case.ts — el paso asigna al contexto y retorna void
+private openClaim = (ctx: PipelineContext): TaskExecution<Errors, void> => {
+  return async () => {
+    // … construir y persistir …
+    ctx.claimId = claimIdValue;
+    return ok(undefined);
+  };
+};
+
+// el pipe conserva el contexto mutado con un sequence de un solo elemento
+TE.executeSequentially([this.openClaim]),
+```
+
+✅ Correcto — el paso retorna el contexto enriquecido y el pipe usa `chain`:
+
+```typescript
+// use-case.ts — el paso retorna el siguiente valor, sin mutar el recibido
+private openClaim = (ctx: ValidationContext): TaskExecution<Errors, ExecutionContext> => {
+  return async () => {
+    // … construir y persistir …
+    return ok({ ...ctx, claimId: claimIdValue });
+  };
+};
+
+// el pipe encadena: la salida del paso es la entrada del siguiente
+TE.chain(this.openClaim),
+```
+
+Cuando el paso es una **verificación** que delega en un puerto que retorna `void` ([A-025](../foundational/A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md) "puerto de verificación"), el caso de uso conserva el contexto con `TV.map(() => ctx, verification)`: re-emite el valor previo, sin mutarlo. No es el olor de "contexto mutado" — el contexto no se asigna.
+
+### Contexto por fase
+
+El contexto que fluye se declara por fase, y la frontera entre fases es también una frontera de tipos:
+
+```typescript
+/** Contexto de la fase de validación. */
+interface ValidationContext {
+  input: InputDto;
+  resolvedReferenceId: string;
+  stockMovement: StockMovement;
+}
+
+/** Contexto de la fase de ejecución: agrega lo que esa fase produce. */
+interface ExecutionContext extends ValidationContext {
+  claimId: string;
+}
+```
+
+Así `toOutput` recibe un `ExecutionContext` con `claimId` obligatorio y no necesita non-null assertion: el compilador garantiza que el campo existe cuando el paso lo lee.
+
+La fase a la que pertenece un paso de construcción de objetos (ejecución, no validación) y la unicidad de la frontera `TE.startExecutions()` las fija [T-022](./T-022-construction-is-execution-single-boundary.md).
+
+## Consecuencias
+
+### Positivas
+
+- **Flujo explícito**: leyendo el pipe se ve qué valor produce cada paso, sin rastrear mutaciones.
+- **El compilador vigila**: el contexto por fase elimina las non-null assertions y hace de `TE.startExecutions()` una frontera de tipos.
+- **Sin operadores engañosos**: no hay listas de un elemento ni pass-through implícito.
+- **Pasos testables**: cada paso retorna su resultado, sin efectos sobre el argumento.
+
+### Negativas
+
+- **Un tipo de contexto por fase**: dos interfaces donde antes bastaba una con campo opcional.
+- **Semántica a aprender**: `chain` vs `sequence` no es evidente por el nombre; exige leer el contrato del operador.
+- **Migración**: las features existentes que mutan el contexto o usan `sequence` de un elemento deben refactorizarse, como el paso post-generación de [T-008](./T-008-expressive-use-case-pipe.md).

package/docs/adr/typescript/T-022-construction-is-execution-single-boundary.md

@@ -0,0 +1,112 @@
+# T-022: Construction is Execution; single Validation→Execution boundary
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-09-16
+
+**originally**: imolko
+
+## Contexto
+
+El pipe del caso de uso ([T-008](./T-008-expressive-use-case-pipe.md)) separa validación y ejecución con una única frontera: `TE.startExecutions()`. La fase la decide el tipo del puerto ([A-025](../foundational/A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md)); la forma de fluir el valor la deciden los tipos del contexto ([T-021](./T-021-pipe-flujo-datos-operadores-semantica-contexto-inmutable.md)).
+
+Los constructores del dominio (`ClaimId.of`, `Claim.create`) retornan `Validation`, porque construir valida y puede fallar. Eso invita a tipar también el paso del caso de uso que construye el agregado como `Validation` e invocarlo *dentro* de la fase de ejecución, levantándolo con una conversión `Validation → Execution` escondida (`E.fromValidation`) después de `TE.startExecutions()`. En `abrir-reclamo` se manifestó así: `buildClaim` retornaba `Validation` pero vivía dentro de `openClaim`, que lo levantaba a `Execution` — una segunda frontera de fase que contradice [T-008](./T-008-expressive-use-case-pipe.md).
+
+La causa es una ambigüedad de vocabulario entre dos librerías del stack:
+
+- **ultra-result** define `Execution` como "cualquier función que hace un cambio en la aplicación. **Esto incluye creación de objetos, transformación de objetos**", y `Validation` como "una validación… **no realiza transformación en ninguna variable o estado**".
+- **ultra-ddd** tipa la *construcción* del dominio (`*.of`, `*.create`) como `Validation`, porque la construcción valida.
+
+Sin una regla canónica, el olor reaparece: la creación de objetos queda tipada como `Validation` y arrastrada a una fase que no le corresponde, o escondida dentro de un paso mayor.
+
+## Decisión
+
+La **construcción de objetos es `Execution`**, no `Validation`. El paso del caso de uso que crea el agregado o value object es un paso de la fase de ejecución, aunque internamente componga los `Validation` que retornan los constructores del dominio.
+
+| Regla | Descripción |
+|-------|-------------|
+| **La construcción es Execution** | El paso que crea un agregado/VO (p. ej. `buildClaim` con `Claim.open`) retorna `Execution`/`TaskExecution`, no `Validation`. Compone los `Validation` del dominio con los operadores de `V` y los levanta una vez con `E.fromValidation`, detrás de su propia interfaz `Execution`. |
+| **Una sola frontera de fase** | `TE.startExecutions()` es la única conversión `Validation → Execution` del pipe. La conversión interna de un paso de construcción no es una segunda frontera del pipe: queda oculta tras la interfaz `Execution` de ese paso. |
+| **La construcción fallible es un paso visible** | Si crear el objeto puede fallar, es su propio paso nombrado en el pipe (`TE.chain(this.buildClaim)`): su canal de error queda a la vista. No se entierra dentro de otro paso. |
+
+❌ Incorrecto — la construcción tipada `Validation` se invoca después de la frontera:
+
+```typescript
+// use-case.ts — buildClaim retorna Validation pero vive en la fase de ejecución
+private openClaim = (ctx) => TE.fromAsync(async () => {
+  const built = this.buildClaim(ctx);              // Validation<Errors, BuiltClaim>
+  if (!built.isOk()) return built as unknown as Execution<…>;
+  // … segunda conversión Validation → Execution escondida en openClaim
+});
+```
+
+✅ Correcto — la construcción es un paso `Execution` visible tras la frontera:
+
+```typescript
+const process = seedTV(input).pipe(
+  TV.chain(this.resolveReference),
+  TV.chain(this.loadReferencedMovement),
+  TV.chain(this.verifyNoOpenClaimExists),
+  TE.startExecutions(),
+  TE.chain(this.buildClaim),                                       // Execution: puede fallar, visible
+  TE.executeSequentially([this.recordClaim, this.publishClaimEvents]),
+  TE.map(this.toOutput),
+);
+```
+
+### El pipe de construcción
+
+El paso `buildClaim` compone a primer nivel ([T-021](./T-021-pipe-flujo-datos-operadores-semantica-contexto-inmutable.md)): genera los identificadores con pasos nombrados y construye en el último. Dentro del paso que construye, la `Validation` del dominio se levanta una única vez:
+
+```typescript
+private buildClaim = (ctx: ValidationContext): TaskExecution<Errors, ExecutionContext> =>
+  seedTE(ctx).pipe(
+    TE.chain(this.withClaimId),
+    TE.chain(this.withUuid),
+    TE.chain(this.buildClaimFromIds),
+  );
+
+private buildClaimFromIds = (ctx: ClaimBuildContext): TaskExecution<Errors, ExecutionContext> => {
+  const built: Validation<Errors, ExecutionContext> = V.map(
+    (claim: Claim): ExecutionContext => ({ ...ctx, claim }),
+    Claim.open({
+      id: ctx.uuid,
+      claimId: ctx.claimId,
+      movement: ctx.stockMovement,
+      reason: ctx.input.reason,
+      description: ctx.input.description,
+      createdBy: ctx.input.createdBy,
+    }),
+  );
+  return TE.fromExecution(E.fromValidation(built));
+};
+```
+
+La generación de identificadores vive en el puerto `IdGeneratorPort`, que entrega los value objects (`ClaimId`, `Uuid`) ya construidos ([A-050](../foundational/A-050-el-caso-de-uso-pide-al-dominio-no-lee-su-representacion.md)); `Claim.open` es la fábrica del dominio que ensambla el agregado desde el movimiento ([T-015](./T-015-method-placement-definition.md)).
+
+### No re-validar value objects que el input ya porta
+
+El `InputDto` del caso de uso ya entrega value objects construidos y válidos (p. ej. `reason: ClaimReason`, `createdBy: UserId`). El paso de construcción no los reconstruye con `Xxx.of({ value: input.reason.getPrimitive() })`: usa el value object del input tal cual. Reconstruirlos es trabajo muerto (ya vienen válidos; nunca falla).
+
+### Pitfall de librería: `V.allProperties`
+
+`V.allProperties` tipa su canal de error como la **lista** (`Errors[]`) en lugar del elemento (`Errors`), lo que impide ensanchar la unión sin cast. Para reunir construcciones heterogéneas, componer con `V.chain`/`V.map` y ensanchar el error por anotación (`const r: Validation<Errors, T> = Xxx.of(...)`), no con `V.allProperties`.
+
+### Pitfall de librería: `V.fromValue(undefined)` devuelve el operador curriado
+
+`V.fromValue(undefined)` retorna la función curriada en lugar de `Valid(undefined)`: el helper interno `curry1` de ultra-result usa `undefined` como centinela de "argumento ausente". Para una hoja `undefined`, usar el factory `valid(undefined)` (o `V.fromValue` con un valor distinto de `undefined`). El mismo centinela aplica a cualquier operador curriado al que se le pase `undefined` como argumento.
+
+## Consecuencias
+
+### Positivas
+
+- **Frontera única y visible**: el pipe declara exactamente dónde acaba la validación y empieza la ejecución, sin conversiones escondidas.
+- **Fallos de construcción a la vista**: `TE.chain(this.buildClaim)` deja el canal de error de la creación en el proceso, no enterrado en un helper.
+- **Vocabulario alineado con ultra-result**: "creación = Execution" resuelve la ambigüedad con ultra-ddd y da un criterio para colocar cada paso.
+- **Sin aserciones**: el tipo del pipe se infiere de las firmas de paso; `execute()` retorna `process` sin `as`.
+
+### Negativas
+
+- **Una conversión interna por paso de construcción**: cada paso que construye debe levantar `Validation → Execution` con `E.fromValidation` (una línea, detrás de su interfaz).
+- **Vocabulario a aprender**: distinguir `Validation` (lectura/verificación) de `Execution` (creación/mutación) exige leer las definiciones de ultra-result, no el nombre del constructor.
+- **Migración**: los pasos que hoy construyen dentro de un paso mayor deben promoverse a pasos nombrados del pipe.

package/docs/adr/typescript/T-023-registry-cli-declara-dependencias-reales.md

@@ -0,0 +1,84 @@
+# T-023: El registry del CLI declara las dependencias reales del caso de uso
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-09-19
+
+**originally**: imolko
+
+## Contexto
+
+`apps/cli` registra sus ~41 casos de uso en un registry plano (`USE_CASE_REGISTRY`), un archivo por feature. Cada entrada es un descriptor tipado `UseCaseEntry<TSchema, TDeps>` con tres piezas: `schema` valida el input externo, `deps(drivers): TDeps` construye las dependencias desde los drivers compartidos y `execute(input, deps)` traduce el input validado y ejecuta.
+
+La forma inicial de `TDeps` era opaca:
+
+```typescript
+interface AbrirReclamoDeps { useCase: AbrirReclamoUseCase; }
+```
+
+El seam (`Deps`) no decía qué necesita el caso de uso: había que abrir el `use-case.ts` de la feature para verlo. Y sin embargo el caso de uso **ya** declara sus puertos (`UseCaseDeps` en `use-case.ts`); el registry los ensamblaba y los escondía detrás de `{ useCase }`, duplicando información que ya existía en el constructor.
+
+[A-027](../foundational/A-027-patron-wiring-entry-point.md) fija la separación wiring/lógica, pero para un único entry-point que recibe "el controlador ya cableado"; no cubre un registry de N casos de uso compuestos a mano, sin contenedor de inyección.
+
+## Decisión
+
+El seam de cada entrada del registry declara las **dependencias reales del caso de uso** — sus puertos — y el ensamblado se mueve a la función de ejecución.
+
+### Ámbito
+
+Aplica a las apps que **componen casos de uso manualmente** (registry o wiring explícito, hoy `apps/cli`). **No aplica** a apps con contenedor de inyección de dependencias (p. ej. NestJS): ahí el constructor del caso de uso ya *es* la declaración de dependencias y no existe un seam manual que documentar; registrar los adaptadores como providers e inyectarlos es suficiente ([A-027](../foundational/A-027-patron-wiring-entry-point.md)).
+
+### Reglas
+
+| Regla | Descripción |
+|-------|-------------|
+| **`Deps` expone los puertos** | `type XxxDeps = ConstructorParameters<typeof XxxUseCase>[0]` — el seam es exactamente el `UseCaseDeps` del caso de uso (`stockMovementRepositoryPort`, `claimRepositoryPort`, `eventBusPort`, `idGeneratorPort`), no `{ useCase }`. |
+| **`deps` construye solo puertos/adaptadores** | La raíz de composición instancia los adaptadores que implementan esos puertos ([A-025](../foundational/A-025-anatomia-mecanica-feature-puertos-adaptadores-drivers.md)); no ensambla el caso de uso. |
+| **`execute` ensambla y ejecuta** | `execute(input, deps)` hace `new XxxUseCase(deps)`, construye el controlador y ejecuta. |
+| **Contrato público intacto** | `UseCaseEntry`, `USE_CASE_REGISTRY`, `listUseCases()` y las dos convenciones de retorno no cambian: `undefined` (legacy, escribe en el presenter) o el JSON ya serializado (canónico, con `executionToJson`). |
+
+### Forma
+
+```typescript
+type AbrirReclamoDeps = ConstructorParameters<typeof AbrirReclamoUseCase>[0];
+
+function buildDeps(drivers: DriverMap): AbrirReclamoDeps {
+  return {
+    stockMovementRepositoryPort: new AbrirReclamoStockMovementRepositoryAdapter(
+      new InMemoryStockMovementRepositoryDriver(drivers.stockMovementStore),
+    ),
+    claimRepositoryPort: new AbrirReclamoClaimRepositoryAdapter(
+      new InMemoryClaimRepositoryDriver(drivers.claimStore),
+    ),
+    eventBusPort: new AbrirReclamoEventBusAdapter(drivers.eventBus),
+    idGeneratorPort: new AbrirReclamoIdGeneratorAdapter(new CryptoIdGeneratorDriver()),
+  };
+}
+
+async function run(input: AbrirReclamoInput, deps: AbrirReclamoDeps) {
+  const useCase = new AbrirReclamoUseCase(deps);
+  const controller = new AbrirReclamoController(useCase);
+  return executionToJson(await controller.execute(input)());
+}
+```
+
+`ConstructorParameters` deriva el seam del constructor del caso de uso: si `UseCaseDeps` cambia, el compilador fuerza a `buildDeps` a proveer los puertos nuevos o actualizados, sin un `interface` duplicado que mantener a mano.
+
+### Desviación de A-027
+
+[A-027](../foundational/A-027-patron-wiring-entry-point.md) prescribe que la función de lógica recibe "el controlador ya cableado". Aquí `execute` recibe los **puertos** y ensambla caso de uso + controlador. Es una variante deliberada: el seam cruza los puertos — no el controlador — para que documente las dependencias reales del caso de uso, a costa de mover un paso de ensamblado a la función de lógica.
+
+## Consecuencias
+
+### Positivas
+
+- **Seam autodocumentado**: leer el archivo del registry muestra de un vistazo los puertos que consume el caso de uso.
+- **Sin duplicación**: el seam se deriva del constructor; no se redeclara `UseCaseDeps` ni se mantiene un `interface` espejo.
+- **Paridad forzada por el compilador**: añadir o cambiar un puerto en el caso de uso rompe `buildDeps` en compilación, no en runtime.
+- **Contrato público estable**: `cli-commands.ts` sigue resolviendo `entry.deps(driverMap)` y llamando `entry.execute(parsedInput, deps)`; el cambio es solo el shape del `Deps` por archivo.
+
+### Negativas
+
+- **Ensamblado en la lógica**: `execute` instancia el caso de uso concreto, un paso más allá de la "lógica pura con controlador cableado" de A-027.
+- **Depende de un constructor de un solo objeto**: `ConstructorParameters<...[0]>` asume que el caso de uso recibe exactamente un objeto de dependencias; un constructor posicional rompe el idiom.
+- **No es una regla de DI**: la decisión no se traslada a apps con contenedor; solo documenta el caso de composición manual.

package/docs/adr/typescript/T-024-paquete-ultra-agent-manifiesto-pi-peers-cli.md

@@ -0,0 +1,39 @@
+# T-024: El paquete `@imolko/ultra-agent` — manifiesto pi, peers y CLI
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-10-02
+
+**originally**: imolko
+
+## Contexto
+
+[A-052](../foundational/A-052-distribucion-metodologia-paquete-versionado.md) fija el modelo de distribución (paquete npm de suscripción con CLI). Falta su materialización TypeScript/npm: cómo se declaran los skills y las extensiones para que pi los descubra, qué dependencias de runtime arrastra el paquete y cómo se publica con el pipeline de GitLab.
+
+Las librerías TypeScript del ecosistema ya tienen convenciones de empaquetado y publicación ([T-014](./T-014-publicacion-distribucion-librerias-npm-semver.md), [T-010](./T-010-stack-tooling-typescript-dominio.md)), pero ninguna cubre un paquete cuyo payload principal es markdown (skills + ADRs) más extensiones de pi.
+
+## Decisión
+
+Materializar `@imolko/ultra-agent` como una **librería de un solo paquete**, sin workspaces ([T-012](./T-012-npm-workspaces-estructura-monorepo-clean-architecture.md) aplica a monorepos de sistema, no a una librería):
+
+1. **Estructura.** `skills/` (skills canónicos), `docs/adr/` (payload A/T/P), `pi/extensions/` (extensiones de pi), `eslint/` (el preset flat-config que materializa las reglas ejecutables del tier A, expuesto como `@imolko/ultra-agent/eslint`), `src/` + `bin/` (CLI, incluido el subcomando `ship` con sus prompts de fase `implement`/`review`/`fix` empaquetados como payload). Un único `package.json`, MIT, `publishConfig.access: public`, `engines.node >=20`, `tsconfig` extendiendo `@imolko/ultra-tsconfig/library/tsconfig.json`.
+2. **Manifiesto `pi`.** El `package.json` declara `pi.skills: ["./skills"]` y `pi.extensions: ["./pi/extensions"]`, de modo que `pi install npm:@imolko/ultra-agent` descubre skills y extensiones por el descubrimiento inteligente de pi (cada extensión por su `index.ts`, sin cargar sus `*.test.ts`).
+3. **Dependencias.** `eslint` como `dependency` —peer de runtime del adaptador de `qa-guardrail`, que cierra el punto abierto de [A-049](../foundational/A-049-materializacion-bucle-guardrails-extension-nativa-pi.md)—, junto con los plugins que el preset declara (`@typescript-eslint/eslint-plugin`, `@typescript-eslint/parser`, `eslint-plugin-boundaries`, `eslint-plugin-import-x`, `eslint-import-resolver-typescript`), y `@earendil-works/pi-coding-agent` como `peerDependency: "*"` (lo proporciona pi; no se empaqueta). Las extensiones se publican como fuente `.ts`, que pi transpila; no requieren build propio.
+4. **CLI.** Un `bin` (`ultra-agent`) con `install`, `update`, `status`, `ship` e `init-lint`, según [A-052](../foundational/A-052-distribucion-metodologia-paquete-versionado.md) y [A-039](../foundational/A-039-pipeline-ship-issues-hijos-spec.md). El subcomando `ship` dispara el pipeline de A-039 y lee los prompts de fase (`implement`/`review`/`fix`) del payload del paquete — no de `.pi/agents/` del consumidor. El subcomando `init-lint` escribe en el espacio de extensión del consumidor un `eslint.config.mjs` mínimo que importa el preset y, si falta, el `.pi/qa-guardrail.json` de solo selección; es idempotente, nunca sobrescribe y `update` nunca lo reconcilia.
+5. **Publicación.** El pipeline de GitLab ([A-016](../foundational/A-016-cicd-gitlab-pipeline-raiz-pipelines-modulares.md)) publica con el flujo de release de las librerías: `develop` → `-beta`, `main` → estable. La versión SemVer se deriva de los tipos de Conventional Commits ([A-033](../foundational/A-033-estandar-mensajes-commit.md) §7), sustituyendo las keywords ad hoc `UPGRADE_MAJOR_VERSION`/`UPGRADE_MINOR_VERSION` heredadas de los flujos previos a la migración de A-033.
+
+## Consecuencias
+
+### Positivas
+
+- **Un solo punto de instalación**: `pi install` cubre skills y extensiones; el CLI cubre el espejo de ADRs, los punteros y el pipeline `ship`.
+- **Sin build para el payload**: skills y ADRs se publican tal cual; solo el CLI se compila.
+- **Peer explícito**: `qa-guardrail` pasa a ser distribuible al declarar `eslint` (cierra la consecuencia negativa de A-049).
+- **Versionado coherente con el resto de librerías**: SemVer por tipos de commit, no por keywords ad hoc.
+
+### Negativas
+
+- **Dependencia de runtime de pi**: `eslint` y los plugins del preset como dependencia obligan a instalarlos aunque el consumidor solo quiera skills; se asume el coste por la extensión y el preset.
+- **`pi` como superficie de manifiesto**: la declaración `pi.skills`/`pi.extensions` es específica de pi; otros harnesses ignoran el manifiesto y reciben los skills por el CLI.
+- **Dependencia de runtime de `ship`**: el subcomando `ship` exige `glab` (tracker) y `pi` (sub-agentes) disponibles en el PATH del consumidor; no se empaquetan.
+- **Migración del flujo de release pendiente**: adoptar la derivación por tipos implica no copiar los scripts de release con keywords de las librerías previas.

package/docs/adr/typescript/T-025-publicacion-npm-trusted-publishing-procedencia.md

@@ -0,0 +1,59 @@
+# T-025: Publicación npm con Trusted Publishing, procedencia y fallback por staging
+
+**Estado**: Aceptado
+
+**Fecha**: 2026-10-03
+
+**originally**: imolko
+
+## Contexto
+
+[T-014](./T-014-publicacion-distribucion-librerias-npm-semver.md) fija **qué** se publica —librerías TypeScript en el registry público de npm, bajo el scope `@imolko`, con SemVer y canal `-beta`— y delega el **cómo** al flujo de release de los scripts. Faltaba decidir **cómo se autentica** esa publicación y **qué garantías de cadena de suministro** ofrece. El repositorio lo arrastraba sin decisión: el pipeline declaraba tokens OIDC de GitLab pero los escribía como si fueran tokens de npm, y el push de etiquetas no tenía credencial.
+
+Tres fuerzas restringen la decisión:
+
+- **Trusted Publishing (OIDC) de npm** elimina los tokens de larga vida y genera atestaciones de procedencia de forma automática, pero solo acepta runners alojados en la nube (runners compartidos de GitLab.com). Los runners autoalojados quedan fuera de soporte, y un runner autoalojado lo delata el claim `runner_environment` de su token OIDC.
+- **Cuota de minutos de GitLab.com.** Los namespaces Free tienen una cuota mensual de minutos de cómputo; cuando se agota, los runners alojados dejan de ejecutar jobs y solo quedan los runners propios. Bloquear una publicación hasta que reinicie la cuota es inaceptable: [A-041](../foundational/A-041-estrategia-de-ramas.md) fija la publicación tras la fusión y [A-016](../foundational/A-016-cicd-gitlab-pipeline-raiz-pipelines-modulares.md) gobierna el pipeline.
+- **Deprecación de npm.** Los *granular access tokens* que omiten 2FA pierden la publicación directa (objetivo enero 2027), pero conservan la capacidad de **stage** (`npm stage publish`), que un mantenedor aprueba con 2FA.
+
+## Decisión
+
+### 1. Dos caminos de publicación, un solo job
+
+- **Runner alojado de GitLab → Trusted Publishing (OIDC).** El job declara `id_tokens` para npm y para sigstore; `npm publish` publica directo y npm genera la atestación de procedencia.
+- **Runner propio (cuota agotada) → staging.** El `.npmrc` lleva un *granular access token* **stage-only**; el release script publica con `npm stage publish` y un mantenedor aprueba la versión con 2FA.
+
+El fallback es automático: npm intenta el intercambio OIDC primero y, cuando no está disponible, publica con la credencial configurada.
+
+### 2. Enrutado por `runner_environment`
+
+El job de publicación no se fija a un runner alojado: debe poder correr en los runners propios cuando la cuota se agota. El release script elige el camino leyendo el claim `runner_environment` del token OIDC —el mismo hecho que npm usa para aceptar o rechazar OIDC—: `gitlab-hosted` publica directo; cualquier otro valor hace staging.
+
+### 3. Procedencia como mejor esfuerzo
+
+La procedencia es automática en el camino OIDC y **ausente** en el fallback por staging; no es un requisito bloqueante. En consecuencia, el paquete **no** activa «Require two-factor authentication and disallow tokens»: esa configuración eliminaría el fallback.
+
+### 4. Arranque
+
+npm no puede publicar la **primera** versión por OIDC y npmjs.com no permite adjuntar un *trusted publisher* a un paquete que todavía no existe. La primera versión se publica **una vez, a mano, con 2FA interactivo**; después se adjunta el *trusted publisher* y CI toma el control.
+
+### 5. Etiquetado por reconciliación
+
+El etiquetado de release no ocurre durante la publicación. Un paso de **reconciliación** —cada versión publicada en el registry que no tenga etiqueta git se etiqueta en el commit que la produjo, que el registry expone como `gitHead`— corre **antes** de cada derivación de versión y es el único mecanismo que crea etiquetas de release, para ambos caminos. El push de etiquetas usa una variable enmascarada (`GITLAB_TOKEN`), como el resto de librerías. Así, una versión en staging solo se etiqueta cuando queda aprobada y viva.
+
+## Consecuencias
+
+### Positivas
+
+- **Sin credenciales npm de larga vida en el camino normal**: OIDC autentica y npm genera la procedencia.
+- **La publicación no se bloquea por la cuota**: cuando no hay runners alojados, el fallback hace staging desde los runners propios y un mantenedor aprueba.
+- **El fallback sobrevive la deprecación de npm**: el staging sigue disponible cuando los tokens que omiten 2FA pierdan la publicación directa.
+- **Token de mínimo privilegio**: el único token que permanece es stage-only; aunque se filtre, no puede saltarse la revisión.
+- **Invariante etiqueta↔publicado**: la reconciliación crea etiquetas solo para versiones publicadas, en su commit real; la derivación de versión nunca etiqueta versiones que no existen.
+
+### Negativas
+
+- **Aprobación humana en el fallback**: cada release por staging exige un 2FA de un mantenedor, y esa versión no lleva procedencia.
+- **Dos comportamientos a probar**: camino OIDC y camino staging.
+- **Acoplamiento al claim `runner_environment`**: el enrutado depende de un detalle del token OIDC de GitLab.
+- **Dependencias externas**: el camino normal depende de la configuración de *trusted publisher* en npmjs.com y de versiones mínimas de npm/Node; el fallback depende de un token stage-only con expiración y de la variable enmascarada `GITLAB_TOKEN`.

package/docs/adr/typescript/index.md

@@ -0,0 +1,30 @@
+# ADRs de TypeScript (T-XXX)
+
+Decisiones de arquitectura específicas del ecosistema TypeScript/Zod/Node.js. Definen cómo implementar conceptos fundacionales en TypeScript.
+
+| # | Título | Estado |
+|---|--------|--------|
+| T-001 | [Validación de artefactos DDD con primitivas Zod y errores built-in](./T-001-ddd-artifact-validation-zod-primitives.md) | Aceptado |
+| T-002 | [Documentación de tests con JSDoc para ultra-reporter](./T-002-test-documentation-jsdoc.md) | Aceptado |
+| T-003 | [Reconciliación del scaffold de ultra-generator con el formato canónico](./T-003-readme-formatting-domain-artifacts.md) | Aceptado |
+| T-005 | [Contratos de input reflejan la interfaz externa; el caso de uso resuelve la opcionalidad](./T-005-input-optionality-use-case-not-entity.md) | Aceptado |
+| T-006 | [Enums pequeños y estables se inlinean con Zod regex](./T-006-small-enums-inlined-zod-regex.md) | Aceptado |
+| T-007 | [Todo controlador de feature expone un esquema Zod para su InputDto](./T-007-controller-input-zod-schema.md) | Aceptado |
+| T-008 | [El pipe del caso de uso expresa el proceso con funciones nombradas](./T-008-expressive-use-case-pipe.md) | Aceptado |
+| T-009 | [Escape de llaves en contenido generado para MDX/Docusaurus](./T-009-mdx-brace-escaping.md) | Aceptado |
+| T-010 | [Stack de tooling TypeScript del dominio (ultra-ddd, ultra-v8n, ultra-result, ultra-tsconfig)](./T-010-stack-tooling-typescript-dominio.md) | Aceptado |
+| T-011 | [ultra-reporter como herramienta canónica de documentación](./T-011-ultra-reporter-herramienta-canonica-documentacion.md) | Aceptado |
+| T-012 | [npm workspaces como estructura del monorepo Clean Architecture](./T-012-npm-workspaces-estructura-monorepo-clean-architecture.md) | Aceptado |
+| T-013 | [Definición de eventos versionados con ultra-ddd](./T-013-definicion-eventos-versionados-ultra-ddd.md) | Aceptado |
+| T-014 | [Publicación y distribución de librerías TypeScript con npm y semver](./T-014-publicacion-distribucion-librerias-npm-semver.md) | Aceptado |
+| T-015 | [`Definition` como único hogar de los métodos de dominio](./T-015-method-placement-definition.md) | Aceptado |
+| T-016 | [Implementación del contrato de settings con schema Zod](./T-016-contrato-settings-zod.md) | Aceptado |
+| T-017 | [Golden files para characterization tests](./T-017-characterization-tests-golden-files.md) | Aceptado |
+| T-018 | [Procedencia de los campos del frontmatter del README](./T-018-procedencia-campos-frontmatter.md) | Aceptado |
+| T-019 | [ultra-generator como herramienta canónica de generación de artefactos](./T-019-ultra-generator-herramienta-canonica-generacion.md) | Aceptado |
+| T-020 | [ultra-settings como herramienta canónica de exportación de artefactos de despliegue](./T-020-ultra-settings-herramienta-canonica-exportacion-despliegue.md) | Aceptado |
+| T-021 | [El pipe del caso de uso fluye datos: operadores por semántica y contexto inmutable](./T-021-pipe-flujo-datos-operadores-semantica-contexto-inmutable.md) | Aceptado |
+| T-022 | [Construction is Execution; single Validation→Execution boundary](./T-022-construction-is-execution-single-boundary.md) | Aceptado |
+| T-023 | [El registry del CLI declara las dependencias reales del caso de uso](./T-023-registry-cli-declara-dependencias-reales.md) | Aceptado |
+| T-024 | [El paquete `@imolko/ultra-agent` — manifiesto pi, peers y CLI](./T-024-paquete-ultra-agent-manifiesto-pi-peers-cli.md) | Aceptado |
+| T-025 | [Publicación npm con Trusted Publishing, procedencia y fallback por staging](./T-025-publicacion-npm-trusted-publishing-procedencia.md) | Aceptado |